Skip to main content
InvariantCAD welcomes focused issues, documentation improvements, tests, protocol reviews, and implementation changes. Read the canonical CONTRIBUTING.md before opening a pull request.

Local setup

Node.js 22.13 or newer is required. The lockfile records the tested toolchain. The Mintlify commands pnpm docs:dev, pnpm docs:validate, pnpm docs:links, and pnpm release:check (which runs the validation and link checks) use the pinned Mint CLI, which supports Node.js 20.17 through 24 and exits on Node.js 25 and newer. Run those commands with Node.js 24, as CI and the release workflow do.

Validation levels

Run the smallest relevant loop while developing, then the proportional full gate before handing off a change. release:check is the canonical release acceptance command; coverage and the complete reference benchmark corpus are part of it rather than optional follow-up steps. The canonical support policy, governance model, and Code of Conduct describe the project’s current single-maintainer boundaries and community process.

Pull requests and releases

Protected main merges a pull request only after CI on Node 22.13, 24, and 26, the Chromium smoke test, CodeQL, Socket pull-request alerts, and a Greptile review pass, with every review conversation resolved. Greptile applies the repository rules in .greptile/. Ordinary pull requests add changelog entries under Unreleased and never bump the package version. Releases are prepared as release/vX.Y.Z pull requests. Merging one runs the full release acceptance suite and, after maintainer approval, publishes to npm with provenance, tags the release, creates the GitHub release, and updates the live documentation. See the maintainer release procedure.

Protocol changes

Document, topology, kernel, cache, artifact, and native-facade protocols are versioned separately. A protocol change should include a precise invariant and failure semantics, hostile-input bounds, frozen compatibility tests, cancellation and cleanup tests, serialization impact, documentation, and a migration decision. Never silently widen a frozen document version.

Backend changes

Construction tests are not enough for topology-aware features. Add tests for capability metadata, geometry, topology roles/source, complete versus partial history, failure rollback, resource ceilings, and disposal.

Documentation changes

The Mintlify source lives in /docs. Every navigated page needs non-blank title and description frontmatter values, each written on one line. Keep examples compilable, distinguish tested from planned behavior, and link to one canonical support matrix. Selected complete fences are synchronized from strict TypeScript regions under examples/docs/. The manifest.json lists every canonical TypeScript module, the public workflows it covers, and each synchronized placement. Edit the canonical source rather than content between docs-example markers, then run pnpm docs:generate. pnpm docs:check verifies exact synchronization, manifest-complete TypeScript coverage, and source-mapped public imports without starting native runtimes. pnpm test:docs-examples independently checks that no canonical module is missing from the manifest, imports every listed module, runs its Manifold or OCCT workflow, and requires all named behavioral checks to pass. The manifest is the authoritative list of the executable matrix. It currently covers portable parametric modeling and STL; sketch/extrude plus exact STEP; fixed assemblies with configurations and BOMs; canonical document migration and hashing; content-committed imported bodies with caller-supplied resource resolution, canonical persistence, and an exact STEP round trip; persistent topology capture, resolution, and explanation; and bounded parsing with structured diagnostics. Unmarked fences are intentionally illustrative fragments: keep them accurate and type-aligned, but do not imply that they are independently compiled or executed.

Security reports

Do not open a normal issue for a vulnerability. Follow the security policy.