fix(#809): refman coverage audit for Selection/Construction (Pass 2b) - #923
Merged
Conversation
Adds Scripts/repro/809-refman-selection-construction/refman_census.py, a re-runnable census of every OCCT class under the BRepExtrema_*, BRepClass*, gp_*, and GC_*/GCE2d_* prefixes (126 classes), cross-referenced against Sources/OCCTBridge and docs/ to verdict each ok / deliberate,recorded / under / over. Over-coverage (fixed): six docs/reference/Curve2D.md and Curve2D-Analysis.md entries cited the deprecated GCE2d_Make* class as the OCCT implementation behind arcOfCircle/arcThrough/arcOfEllipse/ arcOfHyperbola/arcOfParabola/segment(Point2D:Point2D:) — GCE2d_* has been a `using` alias for GC_*2d since OCCT 8.0.0 (confirmed via occt-refman, which generates no page for any GCE2d_* class), and direct inspection of the bridge found five of the six methods never call any GC_/GCE2d_ Make helper at all (they construct the Geom2d_* primitive directly), while the sixth (arcThrough) calls GC_MakeArcOfCircle2d. Same class of drift #508 fixed elsewhere in the docs, missed here. Also fixed the one live regression back to the deprecated spelling found during the sweep: OCCTBridge_Modeling.mm's OCCTShapeCreateFaceFromSurfaceUVPolygon still called GCE2d_MakeSegment (a behavior-identical rename to GC_MakeSegment2d, since the deprecated name is literally a type alias for it) — proven so by Issue233FaceFromSurfaceWireTests staying green. Under-coverage (recorded in docs/occtswift-wrapping-gaps.md, none fixed — all are either algorithm-internal implementation helpers reached only through an already-wrapped entry point, exception types, deprecated NCollection/float aliases, dead #include-only references, or capabilities already covered by a wrapped gce_* sibling class): the whole GCE2d_* package, BRepExtrema_ElementFilter/OverlapTool/ProximityDistTool/ ProximityValueTool/TriangleSet/SolutionElem, nine BRepClass_*/BRepClass3d_* internal classifier helpers, GC_Root, GC_MakeLine, GC_MakeArcOfEllipse2d/ ArcOfHyperbola2d/ArcOfParabola2d, GC_MakeRotation(2d)/Mirror2d/Scale2d/ Translation2d, gp_TrsfNLerp, gp_Vec2f/Vec3f, gp_VectorWithNullMagnitude, BRepExtrema_MapOfIntegerPackedMapOfInteger/SeqOfSolution, BRepClass3d_MapOfInter, and BRepExtrema_UnCompatibleShape. 78 ok, 48 deliberate/recorded, 0 under, 0 over — script exits 0. Both detectors (the over-coverage regression check and the under-coverage recorded-reason check) were proven to fail before the fix and pass after, per okf/policies/prove-the-test-fails.md. Ran python3 Scripts/check-docs-existence.py, check-docs-defaults.py, check-bridge-index.py, check-null-handle-guards.py, derive-bridge-header-split.py --verify, count-operations.py (all clean), swift build (clean), and swift test --filter Issue233FaceFromSurfaceWireTests (3/3 passing) to confirm the .mm rename is behavior-identical. Closes #809 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
check-style-manifest.py correctly flagged the GCE2d_MakeSegment -> GC_MakeSegment2d rename this PR made in OCCTBridge_Modeling.mm: that file is grandfathered on Scripts/style-manifest-bridge.txt, so touching even one line mechanically requires bringing the whole ~11,000-line file into clang-format compliance (~24,000 diff lines) in the same PR -- the exact situation #917 already tracks (deferred there from PR #912 for the same reason). Reverted the rename (file is now byte-identical to main). Corrected refman_census.py's GCE2d_MakeSegment note and the matching docs/occtswift-wrapping-gaps.md prose, both of which had claimed the rename was made -- now describe what's actually in the diff (one GCE2d_MakeSegment call remains, tracked on #917). Total verdict counts are unaffected (GCE2d_MakeSegment is curated as 'deliberate, recorded' either way). All 6 static gates clean, swift build clean, diff against main for OCCTBridge_Modeling.mm confirmed empty. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This was referenced Aug 17, 2026
Closed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What & why
Executes #809 (Pass 2b of the refman-audit epic #807): a re-runnable census comparing what
OCCTSwift wraps/documents against what OCCT's pinned refman (
occt-refman@8.0.0-p1) declares, forthe
BRepExtrema_*,BRepClass*,gp_*, andGC_*/GCE2d_*prefixes, in both directions.Artifact:
Scripts/repro/809-refman-selection-construction/refman_census.py. Enumerates all126 classes across the four prefixes (embedded, sourced from the pinned xcframework's headers),
classifies each
wrapped?(constructed on a non-#includeline anywhere inSources/OCCTBridge) /documented?(named anywhere underdocs/, excluding the historicalCHANGELOG.md), and prints alane | occt_class | documented? | wrapped? | verdict | notetable.Verdict:
ok(78),deliberate, recorded(48),under(0),over(0). Exits 1 if an unrecordedunderor an over-coverage regression is detected — proven to do both (fail → fix → pass) perokf/policies/prove-the-test-fails.md, transcript below.Over-coverage found and fixed (6 findings, exactly the
GCE2d_*/GC_*prefix confusion #508already found once and this issue's own text warned to watch for):
docs/reference/Curve2D.mdand
Curve2D-Analysis.mdcited the deprecatedGCE2d_MakeArcOfCircle/MakeArcOfEllipse/MakeArcOfHyperbola/MakeArcOfParabola/MakeSegmentas the OCCT class behindarcOfCircle/arcThrough/arcOfEllipse/arcOfHyperbola/arcOfParabola/segment(from:Point2D,to:Point2D). Verified againstocct-refman@8.0.0-p1(which generates nopage at all for any
GCE2d_*class — every one has been ausing GCE2d_X = GC_X2d/GC_Rootcompatibility alias since OCCT 8.0.0) and against the actual bridge call sites: five of the six
methods construct the
Geom2d_*primitive directly and never call anyGC_/GCE2d_Makehelper; the sixth (
arcThrough) callsGC_MakeArcOfCircle2d. All six doc lines corrected to namethe real backing implementation.
While sweeping every bridge use of the four prefixes for the census, found one live regression
back to the deprecated spelling:
OCCTBridge_Modeling.mm'sOCCTShapeCreateFaceFromSurfaceUVPolygonstill calls
GCE2d_MakeSegment. Not renamed in this PR:check-style-manifest.pycorrectlyflagged it —
OCCTBridge_Modeling.mmis grandfathered onScripts/style-manifest-bridge.txt, sotouching even this one line mechanically requires bringing the whole ~11,000-line file into
clang-formatcompliance (~24,000 diff lines) in the same PR, the exact situation #917 alreadytracks (deferred there from PR #912 for the same reason). Reverted the rename and noted it on #917
instead; it's behavior-identical (the deprecated name is literally a type alias for
GC_MakeSegment2d) so it costs nothing to leave for that file's own compliance sweep.Under-coverage found (24 raw classes, all
deliberate, recordedindocs/occtswift-wrapping-gaps.md— none needed a fix): the entire deprecatedGCE2d_*package(15 classes); nine
BRepClass_*/BRepClass3d_*classes that are internal plumbing of thealready-wrapped
BRepClass_FaceClassifier/BRepClass_FClassifier/BRepClass3d_SolidClassifier(edge/face wrappers, ray intersectors, a bounding-box tree, "passive" strategy variants OCCT
itself doesn't recommend over the wrapped one); six
BRepExtrema_*classes that are internalplumbing of the already-wrapped
BRepExtrema_ShapeProximity/DistShapeShape(a BVH triangle set,an overlap tool, an abstract filter hook, two distance-accumulation helpers, and the per-solution
representation type);
GC_Root(the common base every wrappedGC_Make*subclass alreadyinherits); five dead
#includes (GC_MakeLine,GC_MakeArcOfEllipse2d/ArcOfHyperbola2d/ArcOfParabola2d,gp_TrsfNLerp); five 2D-transform/rotation classes whose capability is alreadywrapped via a
gce_*sibling package outside this lane (GC_MakeRotation/MakeRotation2d/MakeMirror2d/MakeScale2d/MakeTranslation2d); two exception types already absorbed by thebridge's blanket
catch (...)(gp_VectorWithNullMagnitude,BRepExtrema_UnCompatibleShape);and five deprecated
NCollection_*/single-precision aliases (gp_Vec2f/Vec3f,BRepExtrema_MapOfIntegerPackedMapOfInteger/SeqOfSolution,BRepClass3d_MapOfInter). Every onegot a new line in
docs/occtswift-wrapping-gaps.md's existing "Classes Not Wrapped Directly" /"Classes Not Wrapped At All" sections.
Closes #809
CHANGELOG entry
Refman coverage audit, Pass 2b: Selection/Construction (#809)
Scripts/repro/809-refman-selection-construction/refman_census.pyenumerates every OCCT classunder
BRepExtrema_*,BRepClass*,gp_*, andGC_*/GCE2d_*(126 classes) and verdicts eachagainst
Sources/OCCTBridgeanddocs/. Fixed sixdocs/reference/Curve2D.md/Curve2D-Analysis.mdentries that cited the deprecatedGCE2d_Make*class (ausingalias forGC_*2dsince OCCT 8.0.0) as the implementation behindCurve2D.arcOfCircle/arcThrough/arcOfEllipse/arcOfHyperbola/arcOfParabola/segment(from:Point2D,to:Point2D)— five of thesix never call a
GC_/GCE2d_Make helper at all. Also found one liveGCE2d_MakeSegmentcall inOCCTBridge_Modeling.mmstill using the deprecated spelling — left as is and noted on #917 ratherthan forcing that grandfathered file's ~24,000-line compliance sweep into this PR (see #917).
Recorded 24 previously-unrecorded under-wrapped classes in
docs/occtswift-wrapping-gaps.md, allinternal algorithm plumbing, exception types, deprecated aliases, or capability already covered by
a wrapped
gce_*sibling. No public API change.SemVer impact
NONE. Documentation corrections only. No public Swift API or bridge C++ symbol added, removed, or
changed.
Checklist
verification) — N/A: no behavior change of any kind in this PR (docs only; the one bridge
finding is deferred to Bring OCCTBridge_Modeling.h/.mm into clang-format compliance (deferred from PR #912) #917, not fixed here).
--self-testcase was run once with its subject broken, and thefailure is reported here.
refman_census.pyisn't a--self-test-bearing gate, but its twodetectors were each proven to fail before their fix and pass after, per the policy's spirit:
- Over-coverage regression check: reinjected the original
GCE2d_MakeArcOfCirclewording intoCurve2D.md→ script printedREGRESSION: ... GCE2d_MakeArcOfCircle ...and exited 1;restored → exited 0.
- Under-coverage recorded-reason check: stripped the
gp_TrsfNLerpwrapping-gaps.md entry →script listed it under "UNRECORDED under-coverage findings" and exited 1; restored →
exited 0.
docs/CHANGELOG.mdis not in this diff.docs/SEMVER.mdis not in this diff.Notes for the reviewer
check-docs-existence.py,check-docs-defaults.py,check-bridge-index.py,check-null-handle-guards.py,derive-bridge-header-split.py --verify,count-operations.py— all clean.
swift buildclean.renamed the live
GCE2d_MakeSegmentcall inOCCTBridge_Modeling.mmtoGC_MakeSegment2ddirectly, which turned
code-styleCI red —check-style-manifest.pycorrectly caught that thefile is grandfathered on
Scripts/style-manifest-bridge.txtand any touch requires a full~24,000-line compliance sweep in the same PR (measured directly:
clang-format -style=fileagainst the file produces exactly that). Reverted the rename (verified:
grep GCE2d_MakeSegment Sources/OCCTBridge/src/OCCTBridge_Modeling.mmfinds the original#includeand call site again,byte-identical to
main), adjustedrefman_census.py'sGCE2d_MakeSegmentnote and the matchingdocs/occtswift-wrapping-gaps.mdprose so both describe what's actually in the diff, and notedthe finding on Bring OCCTBridge_Modeling.h/.mm into clang-format compliance (deferred from PR #912) #917 (which already tracks this exact file for exactly this reason, deferred there
once already from PR fix(#910): guard ThruSectionsBuilder.generatedFace(from:) on IsDone() #912).
code-styleis green after this edit.Selector.swift,Selection.swift,ConstructionEntity.swift,ConstructionContext.swift,ConstructionLayer.swift,ShapeAxis.swift,ShapeMeasurements.swift) were touched, soScripts/style-manifest-swift.txt(which still listsSelection.swift) doesn't apply here.GCE2d_*/GC_*prefix confusion(the GCE2d 2D-conic bridge family (12 functions) uses a bare "OCT" prefix instead of "OCCT", and the header's own cross-reference index entry for this family points to a symbol that doesn't exist anywhere in the codebase #508 precedent) and that's exactly what the six over-coverage findings turned out to be —
worth flagging since Pass 1a — Geometry primitives duplication audit #380's lesson is that grep-shaped claims here have been wrong before; every
finding above was verified against
occt-refman@8.0.0-p1(via thecontextMCP) and/or a directread of the actual bridge call site before being written up, not inferred from the class name
alone.
gce_*package (a different, related prefix genuinely used byTransformFactory3D/TransformFactory2D) beyond confirming it's what the five "covered bysibling"
GC_*findings are covered by —gce_*is outside this issue's declared 4-prefix lane.