geospec 0.0.0 → 0.1.0-beta.2

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,244 @@
+# geospec
+
+GeoSpec is a CAD geometry testing library with one host-independent authoring API:
+`loadModel` from `geospec/model` and `expectGeo` from `geospec`.
+
+This package is the **matcher-API substrate** (Apache-2.0): the authoring DSL,
+the selector language, the diagnostics and evidence schemas, the matcher
+registry, and host integration. It executes no geometry on its own: every claim
+is evaluated by the compiled
+[`geospec-engine`](https://github.com/taucad/geospec/tree/main/packages/geospec-engine) core that
+the host passes to the runner. Tau's desktop/browser composition and the
+[`geospec` CLI](../geospec-engine/README.md) supply that engine. Authored tests
+do not import or select an engine, and nothing registers one globally.
+
+The following is a `*.geospec.ts` module for the CLI or Tau `test_model`:
+
+```ts
+import { describe, expectGeo, it } from 'geospec';
+import { loadModel } from 'geospec/model';
+
+const code = `
+  import { makeBaseBox } from 'replicad';
+  export default function main() {
+    return makeBaseBox(40, 20, 8);
+  }
+`;
+
+describe('bracket', () => {
+  it('has expected measurements', async () => {
+    const model = await loadModel({
+      code: { 'main.ts': code },
+      file: 'main.ts',
+      format: 'glb',
+    });
+
+    expectGeo(model).toHaveBoundingBox({ size: { x: 40, y: 20, z: 8 }, tolerance: 0.1 });
+    expectGeo(model).toHaveSurfaceArea({ value: 2560, tolerance: 10 });
+    expectGeo(model).toHaveVolume({ value: 6400, tolerance: 10 });
+  });
+});
+```
+
+## Running specs
+
+### Subjects and host lifetime
+
+Await `loadModel`, then make synchronous `expectGeo` assertions. Its
+`GeoSpecSubject` is opaque: do not read mesh fields, forge a subject hash, or
+reuse a subject after its owning loader/run is disposed. The host retains the
+source and parameter identity and owns geometry admission, reuse and release.
+
+Standalone and Vitest hosts supply a managed loader through `createModelLoader`
+and the existing host integration; `geospec/vitest` supplies the framework
+adapter. Vitest's `describe`/`it` come from Vitest, while the helpers imported
+from `geospec` above belong to GeoSpec's VM runner. Ordinary assertions remain
+`expectGeo`; the optional Vitest `expect` extension has its own asynchronous
+settlement contract. See the [host binding documentation](https://github.com/taucad/geospec/tree/main/packages/geospec-engine#readme).
+
+Python uses `load_model`/`expect_geo` from `geospec`, with the wheel's pytest
+plugin scope or a standalone `GeoSpecEngine` context. Tau `test_model` discovers
+TypeScript/JavaScript tests, not Python files.
+
+Read `runStatus`, complete accounting, discovery and source-lineage status when
+interpreting a run. Unsupported, inconclusive, skipped and not-run requirements
+are not passes. Compact `test_model` output can omit details; its retained
+`fullResult` remains the complete result. An empty failures list alone is not
+qualification, and filtered requirements remain outside the demonstrated scope.
+
+### Runner configuration
+
+Install [`@taucad/geospec-engine`](../geospec-engine) for its `geospec` CLI or
+Node worker pool. To embed a serial runner, pass a compiled engine to
+`createNativeGeoSpecRunner` from `geospec/runner/native`; it builds the native
+model loader and releases every admitted subject after each run. These use the
+same compiled composition. Other embeddings must qualify their actual binding,
+input representation and supported domain; shared authoring syntax alone does
+not establish verdict equivalence. The CLI's flags and pool options are
+documented in that package's README.
+
+The filters below are the shared vocabulary of the CLI, the embedded runners
+and the Tau `test_model` tool:
+
+- `files`: GeoSpec files or directory roots to run. Empty input recursively discovers from the project root.
+- `include`: GeoSpec file include globs, defaulting to `["**/*.geospec.{ts,js}"]`
+- `exclude`: GeoSpec file exclude globs
+- `testNamePattern`: JavaScript regular expression matched against full `suite > test` names
+- `testTimeout`: async test timeout in milliseconds
+
+The host uses Tau runtime exports or already-exported GLB/glTF/STEP bytes. Authored tests use `loadModel` for both code and direct geometry inputs; low-level parsing/host APIs are not an alternate authored-test dialect.
+
+Load failures carry structured diagnostics. Assertion reports retain the selected claim, evidence, provenance and diagnostics; inspect those reports rather than expecting mutable evidence fields on the opaque subject.
+
+Keep each test readable with its own `loadModel()` call. Each load captures current source/parameter identity; hosts may reuse admitted computations only under matching identities. Do not assume a filename alone permits cross-file memoization:
+
+```ts
+import { describe, expectGeo, it } from 'geospec';
+import { loadModel } from 'geospec/model';
+
+describe('assembly', () => {
+  it('has no global part interference', async () => {
+    const model = await loadModel({ file: 'main.ts' });
+    expectGeo(model).toHaveNoComponentInterference({ tolerance: 0.1 });
+  });
+
+  it('keeps the ring and planet free of interference', async () => {
+    const model = await loadModel({ file: 'main.ts' });
+    expectGeo(model).toHaveNoComponentInterference({
+      tolerance: 0.05,
+      pairs: [{ left: /ring/i, right: /planet gear/i }],
+    });
+  });
+});
+```
+
+Production assembly suites can combine mesh-integrity, occurrence, spatial
+relationship, and exact BRep assertions without adding domain-specific
+matchers for each mechanical subsystem:
+
+```ts
+expectGeo(model).toHaveMeshIntegrity({
+  finitePositions: true,
+  degenerateTriangles: { count: 0 },
+  duplicateFaces: { count: 0 },
+});
+
+expectGeo(model).toHaveAssemblyOccurrences({
+  uniqueNames: true,
+  occurrences: [
+    { name: 'Housing', count: 1 },
+    { name: /^Fastener \d+$/, count: 8 },
+  ],
+});
+
+expectGeo(model).toHaveSpatialRelationships({
+  relationships: [
+    { id: 'shaft seats in bearing', kind: 'contact', subject: 'Shaft', target: 'Bearing', tolerance: 0.05 },
+    { id: 'pin remains inside yoke', kind: 'containment', subject: 'Pin', target: 'Yoke', tolerance: 0.05 },
+  ],
+});
+```
+
+Choose selectors supported by the admitted source. A qualified mesh `body`
+selector identifies one material root with its cavity boundaries; disconnected
+roots and islands inside cavities remain separate Bodies. Its `of` scope
+matches the exact retained primitive label, including any ordinal suffix.
+Inspect that label and preserve cardinality instead of guessing an occurrence
+path. Mesh input does not invent assembly ancestry or analytic faces; missing
+measure, probe or ordering evidence refuses, even through query negation.
+The STEP Body index currently exposes per-occurrence solid aggregates, so do
+not assume its Body count maps one-to-one to mesh material roots.
+
+Whole-Body contact requires no interior overlap and boundary separation within
+the declared inclusive tolerance. It does not establish a contact area or seal;
+finite-face angular requirements need their actual analytic evidence.
+
+Load STEP through the same authoring API:
+
+```ts
+import { loadModel } from 'geospec/model';
+
+const subject = await loadModel({ file: 'part.step', format: 'step' });
+```
+
+For CAD source, `loadModel({ file: 'main.ts', format: 'step' })` asks the host to export STEP. The configured compiled engine admits the exact returned bytes through its OCCT binding. Export and source provenance do not by themselves certify a geometric requirement.
+
+Measurement matchers currently support mesh evidence and prefer exact BRep evidence when it is present:
+
+```ts
+expectGeo(subject).toHaveSurfaceArea({ value: 12_345, tolerance: 1 });
+expectGeo(subject).toHaveVolume({ value: 120_000, tolerance: 10 });
+expectGeo(subject).toHaveMass({ value: 94.2, density: 0.000_785, tolerance: 0.5 });
+expectGeo(subject).toHaveCenterOfMass({ point: { x: 0, y: 0, z: 10 }, tolerance: 0.05 });
+```
+
+Initial BRep feature matchers are available when a loader provides BRep evidence:
+
+```ts
+import { loadModel } from 'geospec/model';
+
+const subject = await loadModel({ file: 'main.ts', format: 'step' });
+
+expectGeo(subject).toBeValidBrep({ maxTolerance: 0.01, closedShells: true });
+expectGeo(subject).toHavePlanarFace({ normal: { x: 0, y: 0, z: 1 }, offset: 20, tolerance: 0.05 });
+expectGeo(subject).toHaveCylindricalFace({ radius: 15, axis: 'z', tolerance: 0.05 });
+expectGeo(subject).toHaveCircularHole({ diameter: 8, through: true, axis: 'z', center: { x: 25, y: 15 } });
+expectGeo(subject).toHaveChamferFeature({ distance: 2, selection: 'outer top perimeter', tolerance: 0.05 });
+expectGeo(subject).toHaveMinimumWallThickness({ value: { greaterThanOrEqual: 2 }, tolerance: 0.05 });
+expectGeo(subject).toHaveVoidContinuity({
+  path: [{ occurrence: 'Throttle Body 1' }, { occurrence: 'Cylinder Head R' }],
+  material: ['Throttle Body 1', 'Intake Manifold 1', 'Cylinder Head R'],
+  minCrossSection: 900,
+  isolatedFrom: [[120, 0, 40]],
+});
+```
+
+These are requirement examples, not a claim that every admitted model supports
+them. `toHaveVoidContinuity` requires the declared path, material and isolation
+proposition to be proved in a qualified domain. A sampled cross-section cannot
+certify a continuous minimum: the general sampled profile refuses a requested
+`minCrossSection`. Restricted nominal analytic domains have separate premises;
+general mesh lumen, wall and motion qualification remains incomplete.
+
+Likewise, watertight edge incidence does not prove manifold validity, a Boolean
+fuse or material connectivity. Bounds and playback cannot certify contact,
+clearance, containment or sealing. Preserve intended geometry and tolerances;
+report unavailable evidence instead of replacing the requirement with a proxy.
+
+The [canonical API index](agent/geospec-authoring/api-index.md) describes
+ordinary authoring. The separate
+[complete public API index](agent/geospec-authoring/public-api-index.md)
+retains host and framework contracts. A low-level
+`GeometrySubject` input is not interchangeable with the opaque subject returned
+by canonical `loadModel`.
+
+When a geometry assertion needs a parameter variant, pass that variant directly to `loadModel`. Omitting `parameters` exercises the defaults authored by the model:
+
+```ts
+import { describe, expectGeo, it } from 'geospec';
+import { loadModel } from 'geospec/model';
+
+describe('parameter variants', () => {
+  it('uses the model defaults', async () => {
+    const model = await loadModel({ file: 'main.ts' });
+    expectGeo(model).toHaveBoundingBox({ size: { x: 40 }, tolerance: 1 });
+  });
+
+  it('accepts an explicit width', async () => {
+    const width = 80;
+    const model = await loadModel({
+      file: 'main.ts',
+      parameters: { width },
+    });
+
+    expectGeo(model).toHaveBoundingBox({ size: { x: width }, tolerance: 1 });
+  });
+});
+```
+
+## License
+
+**Apache-2.0.** This package is the permissive perimeter: your specs, your
+models and your verdicts do not inherit this package's license. See
+[Licensing](../../docs/licensing/overview.md) for the routing map
+and the internal-use FAQ.

package/agent/doctrine.md

@@ -0,0 +1,47 @@
+Write tests before implementation; assert deterministic, measurable properties.
+
+## Test shape
+
+- Use `*.geospec.ts` or `*.geospec.js`. Import `describe`, `it` and `expectGeo` from `geospec`, and `loadModel` from `geospec/model`.
+- Await `loadModel`, then assert synchronously with `expectGeo(model)`. The host supplies the compiled binding; authoring does not select an engine.
+- Await or return the complete model-load chain from the test callback; detached future loads are not part of a completed test.
+- Omit `parameters` for model-code defaults; use `{ file, parameters }` for variants. Loaded subjects are opaque.
+
+Canonical TypeScript authoring:
+
+```ts
+import { describe, expectGeo, it } from 'geospec';
+import { loadModel } from 'geospec/model';
+
+describe('main geometry', () => {
+  it('has the intended envelope', async () => {
+    const model = await loadModel({ file: 'main.ts', parameters: { width: 120 } });
+    expectGeo(model).toHaveBoundingBox({ size: { x: 120 }, tolerance: 1 });
+  });
+});
+```
+
+Specs are always TypeScript or JavaScript, whatever the model's kernel: `loadModel({ file })` evaluates `main.ts`, `main.tsx`, `main.py`, `main.scad`, `main.kcl` or `main.cs` through Tau's runtime. `test_model` discovers `*.geospec.ts` and `*.geospec.js` only.
+
+Every matcher takes one expectation object:
+
+- Wrong: `expectGeo(model).toHaveVolume(5000, { tolerance: 5 })`. Correct: `expectGeo(model).toHaveVolume({ value: 5000, tolerance: 5 })`.
+- Wrong: `await expectGeo(model)…`. Correct: await `loadModel`, then assert synchronously.
+- Wrong: exact-feature matchers on a mesh kernel (Manifold, JSCAD, OpenSCAD, PicoGK, PicoVoxel). Correct: `toBeValidBrep`, `toHaveTopologyCounts`, the face, hole, pattern, chamfer, fillet and wall-thickness matchers, `toHaveStepUnits`, `toHaveProductStructure` and `toHaveVoidContinuity` need STEP BRep evidence and report unsupported on meshes; assert meshes with bounds, volume, surface area, connected components and `toBeWatertight`.
+
+## Coverage
+
+Bounds and physical properties are insufficient. Cover major components, named features, variants, dimensions/positions, disjoint counts, closure, interference and supported exact features. Explicitly report unsupported requirements; proxies cannot fulfill them.
+
+- `toHaveBoundingBox`: size/position.
+- `toHaveConnectedComponents`: qualified material connectivity; visual touching cannot justify tolerance changes.
+- `toBeWatertight`: closed edge incidence, not manifold validity, fusion or material connectivity. Bounds prove none of these. Missing evidence is unsupported.
+- `toHaveSurfaceArea`, `toHaveVolume`, `toHaveCenterOfMass`, `toHaveMass`: physical measurements.
+- `toHaveNoComponentInterference`: overlap; allow deliberate press fits.
+- `loadModel({ file, format: 'step' })`: use BRep evidence for supported topology and feature assertions. Missing occurrence, interference, clearance, containment, lumen, wall, section or motion evidence is unsupported, not a pass or an envelope substitute.
+
+Test assemblies and independent units; preserve sibling coverage when adding files. Non-top-level geometry needs kernel export/invocation, not test removal.
+
+Fix geometry at its root; never weaken tolerances, delete assertions, or reduce detail to pass.
+
+`public-api-index.md` covers the host and framework API; authoring needs only the Core API below and `api-*` files.