Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

9.1 KB
Raw Blame

Contributing to Aetheris

Thank you for improving Aetheris. Keep changes focused, explain the engineering intent, and preserve the rule that supported semantics are emitted truthfully while unsupported semantics fail with actionable diagnostics.

Release scope

The 2.0.0 release pass covers release hygiene, documentation, tests and narrowly scoped correctness fixes. Develop new capabilities on an explicitly agreed branch and keep experimental API status visible.

Build and test

Install the .NET SDK selected by global.json.

Source builds that include Drawing Notes also require Node 24 and npm. MSBuild restores the pinned PDF.js dependency from Aetheris.Drawing/Web/package-lock.json with install scripts and optional native packages disabled. Only selected browser runtime assets and licenses are embedded; downloaded distributions stay ignored. Published Aetheris tools do not require Node or npm. See Aetheris.Drawing/Web/README.md.

Firmament pins Copeland's published managed VTS/WGSL compiler family to 0.1.0. A fresh checkout restores it from NuGet.org without a Copeland checkout or local feed. The CI action .github/actions/prepare-managed-wgsl verifies this public restore. Use the canonical solution:

dotnet restore Aetheris.slnx
dotnet build Aetheris.slnx -c Release -m:1
dotnet test Aetheris.slnx -c Release --no-build -m:1 -- RunConfiguration.MaxCpuCount=1

Two test lanes

The command above is the full corpus lane and is what has to be green before you commit. It imports the whole NIST and OCCT corpus, so it is the lane that actually protects the interchange behaviour.

For the edit-run-edit inner loop there is a fast lane that skips the corpus-driven tests:

dotnet test Aetheris.Kernel.Core.Tests -c Release --no-build --filter "Category!=SlowCorpus"

Use the fast lane while iterating; never use it as the gate. Its test count and runtime vary with the source and available corpus witnesses.

A test belongs in [Trait("Category", "SlowCorpus")] when its cost is dominated by importing a large corpus file rather than by the behaviour it is checking. Keep at least one cheap test per behaviour outside the trait, so the fast lane still fails when something is broken rather than merely running fewer tests. Aetheris.Kernel.Firmament.Tests has the trait too, but its time is spread evenly across real geometry work rather than concentrated in corpus I/O, so the split buys much less there.

The NIST audit keeps strict canonical STEP byte snapshots. Three recovered-pcurve specimens have qualified Linux hashes in testdata/step242/manifests/nist.v0.canonical-linux.json: native math changes tiny UV values and exact geometry sharing changes entity numbering. The companion overrides only their expected hash on Linux; status, diagnostics, file size and topology counts still use the common snapshot. When refreshing these specimens, qualify both Windows and Linux exports and refresh the companion explicitly. All other specimens retain the common byte hash on both platforms.

Importing corpus files in tests

Do not call File.ReadAllText + Step242Importer.ImportBody directly in a test. Use the shared memoized fixture:

var body = Step242Corpus.Body("testdata/step242/nist/CTC/nist_ctc_02_asme1_ap242-e2.stp");
var import = Step242Corpus.Import(relativePath);   // when the diagnostics matter
var text = Step242Corpus.Text(relativePath);       // when the file text itself matters

The corpus has 48 distinct files and the test project reads from it at roughly two hundred call sites. Importing every file exactly once costs about ten seconds; doing it per call site cost about ninety-eight. Parsing is under a second of that, so caching the parsed document would buy almost nothing - the body is what is expensive to build, so the body is what is cached. A BrepBody is read-only once constructed, which is what makes sharing it safe.

Two cases must still import for themselves and should take only Step242Corpus.Text: tests that install a Step242Importer.CaptureLoopRole*Diagnostics scope, because it collects while the import runs, and tests under Step242Importer.PreserveRationalSurfaces(), because it changes what the import produces.

Cadmata and the VS Code extension use TSPack and their checked-in lock files: The release workflow pins TSPack source 01051b791cf83757a1c419ef7bc276d9de787a9d (npm peers, scoped tools, local dependencies and explicit runtime providers). Build the local Telos producer before syncing Cadmata; its exported dist files are ignored. ./scripts/Build-CadmataFrontend.ps1 runs the complete frontend producer and qualification below. CI runs it before the long .NET lane and again when staging. Use separate generated dependency directories for each package; remove obsolete client-to-workspace node_modules junctions before regenerating with sync --force.

Push-Location Aetheris.Web.Runtime/telos
npm ci --ignore-scripts
npm run build
Pop-Location

Push-Location aetheris.client
tspack sync --root ..
tspack check --root ..
tspack run typecheck --root ..
tspack run test --root ..
tspack run build --root ..
tspack run lint --root ..
Pop-Location

Push-Location tools/vscode-firmament
tspack sync
tspack check
tspack run typecheck
tspack run test
tspack run build
Pop-Location

Use Aetheris.CLI as the ground-truth inspection surface while developing:

dotnet run --project Aetheris.CLI -c Release -- --help
dotnet run --project Aetheris.CLI -c Release -- analyze path/to/part.step --json

The shell entry points under scripts/ remain useful for targeted Linux/framework automation. The release qualification commands above are the authoritative Windows path for 2.0.0.

Contribution expectations

  • Keep pull requests small enough to review and test as one engineering claim.
  • Add tests for behavior changes and run the affected real CLI, package, or UI path.
  • Use ToleranceContext and ToleranceMath; do not introduce ad hoc geometry epsilon constants.
  • State whether display work changes STEP semantics, BRep topology, Firmament/AIR/CIR lowering, DisplayIR authority, or frontend presentation only.
  • Update public documentation whenever a user-visible command, boundary, diagnostic, or example changes.
  • Put current user-facing behavior only under docs/public. Architecture, experiments, and development evidence belong under docs/development and must not silently become the public contract.

Repository content map

Location Durable purpose
docs/public/ Authoritative current user documentation.
docs/development/ Historical engineering, architecture, milestones, experiments, and evidence.
docs/release/ Release qualification, staging, claims, and contracts.
docs/legal/ Legal-review candidates and counsel questions.
fixtures/ All Firmament-family test source and corpus metadata, including .firmament, .firmfixture, and .firmasm.
testdata/ Non-Firmament external/reference inputs and deliberate golden exports.
samples/ External consumer integration examples.
demos/ Runnable narrative demonstrations of Aetheris capabilities.
test-support/ Auxiliary projects and assets used by tests.
artifacts/local/ Generated local output; ignored by Git.

Before adding content, use an existing location above. Do not create another top-level documentation, fixture, example, or generated-output bucket without an explicit architectural reason. Generated output is governed by the generated-artifact policy: tools default to artifacts/local/, and only bounded, reviewed evidence or goldens may be promoted into source control. Run ./scripts/Test-RepositoryLayout.ps1 before submitting structural changes.

Rights and provenance

Submit only code, documentation, models, and assets that you have the right to contribute. Record third-party source, author, license, and redistribution constraints in the pull request and, when bundled, in THIRD_PARTY_NOTICES.md. Tool-assisted or AI-assisted work is acceptable, but the contributor remains responsible for the right to submit it and for reviewing its correctness and provenance.

Contributor license agreement status

Aetheris intends to use a contributor-friendly CLA: contributors keep copyright, while granting the project owner enough non-exclusive rights to distribute contributions under AGPL-3.0 and alternative licenses. In return, the intended bargain commits Aetheris to continuing AGPL availability rather than using the CLA to make the community version proprietary-only.

The current CLA-CANDIDATE.md is draft preparation for human attorney review. It is not a final legal agreement and this repository does not yet define click-through, pull-request, or signature acceptance. Until counsel and the project owner publish approved terms and acceptance mechanics, maintainers should not represent a contribution as having accepted that draft.

Legal reviewers should also see the CLA counsel checklist.