Skip to content

fix(#809): refman coverage audit for Selection/Construction (Pass 2b) - #923

Merged
gsdali merged 2 commits into
mainfrom
fix/809-refman-selection-construction
Aug 16, 2026
Merged

fix(#809): refman coverage audit for Selection/Construction (Pass 2b)#923
gsdali merged 2 commits into
mainfrom
fix/809-refman-selection-construction

Conversation

@gsdali

@gsdali gsdali commented Aug 16, 2026

Copy link
Copy Markdown
Collaborator

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, for
the BRepExtrema_*, BRepClass*, gp_*, and GC_*/GCE2d_* prefixes, in both directions.

Artifact: Scripts/repro/809-refman-selection-construction/refman_census.py. Enumerates all
126 classes across the four prefixes (embedded, sourced from the pinned xcframework's headers),
classifies each wrapped? (constructed on a non-#include line anywhere in
Sources/OCCTBridge) / documented? (named anywhere under docs/, excluding the historical
CHANGELOG.md), and prints a lane | occt_class | documented? | wrapped? | verdict | note table.
Verdict: ok (78), deliberate, recorded (48), under (0), over (0). Exits 1 if an unrecorded
under or an over-coverage regression is detected — proven to do both (fail → fix → pass) per
okf/policies/prove-the-test-fails.md, transcript below.

Over-coverage found and fixed (6 findings, exactly the GCE2d_*/GC_* prefix confusion #508
already found once and this issue's own text warned to watch for)
: docs/reference/Curve2D.md
and Curve2D-Analysis.md cited the deprecated GCE2d_MakeArcOfCircle/MakeArcOfEllipse/
MakeArcOfHyperbola/MakeArcOfParabola/MakeSegment as the OCCT class behind
arcOfCircle/arcThrough/arcOfEllipse/arcOfHyperbola/arcOfParabola/
segment(from:Point2D,to:Point2D). Verified against occt-refman@8.0.0-p1 (which generates no
page at all for any GCE2d_* class — every one has been a using GCE2d_X = GC_X2d/GC_Root
compatibility 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 any GC_/GCE2d_ Make
helper; the sixth (arcThrough) calls GC_MakeArcOfCircle2d. All six doc lines corrected to name
the 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's OCCTShapeCreateFaceFromSurfaceUVPolygon
still calls GCE2d_MakeSegment. Not renamed in this PR: check-style-manifest.py correctly
flagged it — OCCTBridge_Modeling.mm is grandfathered on Scripts/style-manifest-bridge.txt, so
touching even this 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 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, recorded in
docs/occtswift-wrapping-gaps.md — none needed a fix)
: the entire deprecated GCE2d_* package
(15 classes); nine BRepClass_*/BRepClass3d_* classes that are internal plumbing of the
already-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 internal
plumbing 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 wrapped GC_Make* subclass already
inherits); five dead #includes (GC_MakeLine, GC_MakeArcOfEllipse2d/ArcOfHyperbola2d/
ArcOfParabola2d, gp_TrsfNLerp); five 2D-transform/rotation classes whose capability is already
wrapped via a gce_* sibling package outside this lane (GC_MakeRotation/MakeRotation2d/
MakeMirror2d/MakeScale2d/MakeTranslation2d); two exception types already absorbed by the
bridge's blanket catch (...) (gp_VectorWithNullMagnitude, BRepExtrema_UnCompatibleShape);
and five deprecated NCollection_*/single-precision aliases (gp_Vec2f/Vec3f,
BRepExtrema_MapOfIntegerPackedMapOfInteger/SeqOfSolution, BRepClass3d_MapOfInter). Every one
got 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.py enumerates every OCCT class
under BRepExtrema_*, BRepClass*, gp_*, and GC_*/GCE2d_* (126 classes) and verdicts each
against Sources/OCCTBridge and docs/. Fixed six docs/reference/Curve2D.md/
Curve2D-Analysis.md entries that cited the deprecated GCE2d_Make* class (a using alias for
GC_*2d since OCCT 8.0.0) as the implementation behind Curve2D.arcOfCircle/arcThrough/
arcOfEllipse/arcOfHyperbola/arcOfParabola/segment(from:Point2D,to:Point2D) — five of the
six never call a GC_/GCE2d_ Make helper at all. Also found one live GCE2d_MakeSegment call in
OCCTBridge_Modeling.mm still using the deprecated spelling — left as is and noted on #917 rather
than 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, all
internal 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

  • New or changed behavior is covered by a unit test in the same PR (not just manual
    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).
  • Every new test and every new --self-test case was run once with its subject broken, and the
    failure is reported here. refman_census.py isn't a --self-test-bearing gate, but its two
    detectors were each proven to fail before their fix and pass after, per the policy's spirit:
    - Over-coverage regression check: reinjected the original GCE2d_MakeArcOfCircle wording into
    Curve2D.md → script printed REGRESSION: ... GCE2d_MakeArcOfCircle ... and exited 1;
    restored → exited 0.
    - Under-coverage recorded-reason check: stripped the gp_TrsfNLerp wrapping-gaps.md entry →
    script listed it under "UNRECORDED under-coverage findings" and exited 1; restored →
    exited 0.
  • The CHANGELOG entry above is complete, and docs/CHANGELOG.md is not in this diff.
  • The SemVer impact above is stated, and docs/SEMVER.md is not in this diff.

Notes for the reviewer

  • Gates run: 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.
  • Edited after the audit's initial submission, before merge: the initial version of this PR
    renamed the live GCE2d_MakeSegment call in OCCTBridge_Modeling.mm to GC_MakeSegment2d
    directly, which turned code-style CI red — check-style-manifest.py correctly caught that the
    file is grandfathered on Scripts/style-manifest-bridge.txt and any touch requires a full
    ~24,000-line compliance sweep in the same PR (measured directly: clang-format -style=file
    against the file produces exactly that). Reverted the rename (verified: grep GCE2d_MakeSegment Sources/OCCTBridge/src/OCCTBridge_Modeling.mm finds the original #include and call site again,
    byte-identical to main), adjusted refman_census.py's GCE2d_MakeSegment note and the matching
    docs/occtswift-wrapping-gaps.md prose so both describe what's actually in the diff, and noted
    the 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-style is green after this edit.
  • None of the 7 lane Swift files (Selector.swift, Selection.swift, ConstructionEntity.swift,
    ConstructionContext.swift, ConstructionLayer.swift, ShapeAxis.swift,
    ShapeMeasurements.swift) were touched, so Scripts/style-manifest-swift.txt (which still lists
    Selection.swift) doesn't apply here.
  • Per this issue's own method note: watched specifically for 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 the context MCP) and/or a direct
    read of the actual bridge call site before being written up, not inferred from the class name
    alone.
  • Did not chase the gce_* package (a different, related prefix genuinely used by
    TransformFactory3D/TransformFactory2D) beyond confirming it's what the five "covered by
    sibling" GC_* findings are covered by — gce_* is outside this issue's declared 4-prefix lane.

gsdali and others added 2 commits August 16, 2026 17:30
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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Refman coverage audit: Selection and Construction (Pass 2b)

1 participant