brepjs-verify 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.4.0](https://github.com/andymai/brepjs/compare/brepjs-verify-v0.3.0...brepjs-verify-v0.4.0) (2026-06-04)
+
+
+### Features
+
+* **brepjs-verify:** eval-driven skill, hint, and reference improvements ([#1219](https://github.com/andymai/brepjs/issues/1219)) ([1a9b80f](https://github.com/andymai/brepjs/commit/1a9b80f3d3dbb44d7a8ae2f601ff305b70534efe))
+
 ## [0.3.0](https://github.com/andymai/brepjs/compare/brepjs-verify-v0.2.1...brepjs-verify-v0.3.0) (2026-06-04)
 
 

package/README.md

@@ -21,6 +21,15 @@ The CLI the skill invokes. Install it in **your** project, where `brepjs` + the
 npm i -D brepjs-verify brepjs occt-wasm
 ```
 
+## API reference
+
+The package bundles brepjs's full API reference for offline/agent use — the complete export surface with signatures and examples:
+
+- `reference/llms-full.txt` — every export, full signatures (the deep reference)
+- `reference/llms.txt` — the same content as a quicker index
+
+Point your agent at `node_modules/brepjs-verify/reference/llms-full.txt` for anything the skill's curated references don't cover.
+
 ## The `.brep.ts` contract
 
 A model is a module whose default export is a zero-arg function returning a shape (or a `Result<shape>`):

package/dist/brepjs-verify.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_diff = require("./diff-mxAOOl_m.cjs");
+const require_diff = require("./diff-BNmCp_8I.cjs");
 exports.DEFAULT_TOLERANCE_PCT = require_diff.DEFAULT_TOLERANCE_PCT;
 exports.TYPECHECK_CODE = require_diff.TYPECHECK_CODE;
 exports.emptyReport = require_diff.emptyReport;

package/dist/brepjs-verify.js

@@ -1,2 +1,2 @@
-import { a as typecheckPart, c as isExpectedDims, d as emptyReport, i as TYPECHECK_CODE, l as pctDelta, m as serializeReport, n as runMeasure, o as DEFAULT_TOLERANCE_PCT, r as runPart, s as evaluateExpected, t as runDiff, u as runChecks } from "./diff-Covv1XuJ.js";
+import { a as typecheckPart, c as isExpectedDims, d as emptyReport, i as TYPECHECK_CODE, l as pctDelta, m as serializeReport, n as runMeasure, o as DEFAULT_TOLERANCE_PCT, r as runPart, s as evaluateExpected, t as runDiff, u as runChecks } from "./diff-D5U3Ie2F.js";
 export { DEFAULT_TOLERANCE_PCT, TYPECHECK_CODE, emptyReport, evaluateExpected, isExpectedDims, pctDelta, runChecks, runDiff, runMeasure, runPart, serializeReport, typecheckPart };

package/dist/cli/main.cjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_diff = require("../diff-mxAOOl_m.cjs");
+const require_diff = require("../diff-BNmCp_8I.cjs");
 let node_url = require("node:url");
 let node_fs = require("node:fs");
 let node_path = require("node:path");

package/dist/cli/main.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { f as pushError, h as loadBrep, m as serializeReport, n as runMeasure, p as reportOk, r as runPart, t as runDiff } from "../diff-Covv1XuJ.js";
+import { f as pushError, h as loadBrep, m as serializeReport, n as runMeasure, p as reportOk, r as runPart, t as runDiff } from "../diff-D5U3Ie2F.js";
 import { fileURLToPath } from "node:url";
 import { existsSync, mkdirSync, realpathSync, watch, writeFileSync } from "node:fs";
 import { basename, dirname, join, resolve } from "node:path";

package/dist/{diff-mxAOOl_m.cjs → diff-BNmCp_8I.cjs}

@@ -164,6 +164,14 @@ var HINT_TABLE = {
 		fix: "The boolean subtraction failed — often a tool that does not actually intersect the base, or tolerance issues.",
 		nextStep: "Confirm the tool overlaps the base, optionally heal the inputs, then re-cut."
 	},
+	FILLET_FAILED: {
+		fix: "The fillet could not be built — usually the radius is too large for an edge it touched (it cannot exceed the adjacent face/wall), or you filleted EVERY edge (the no-edge-list form) including ones too thin to round.",
+		nextStep: "Select only the edges you mean to round — e.g. edgeFinder().inDirection(\"Z\").findAll(solid) — and/or reduce the radius below the thinnest adjacent wall, then re-verify."
+	},
+	CHAMFER_FAILED: {
+		fix: "The chamfer could not be built — usually the distance is too large for an edge it touched, or you chamfered EVERY edge (the no-edge-list form) including ones too thin.",
+		nextStep: "Select only the target edges with an edge finder and/or reduce the distance below the shortest adjacent edge, then re-verify."
+	},
 	BOOLEAN_HAS_ERRORS: {
 		fix: "The boolean ran but the kernel reported errors (often coincident faces or near-tangent contact).",
 		nextStep: "Perturb one operand slightly so contact is a clean overlap, or heal the inputs, then retry."
@@ -199,6 +207,10 @@ var HINT_TABLE = {
 	TYPECHECK: {
 		fix: "Fix the TypeScript type error before running the part — the API call or value does not match brepjs’s types.",
 		nextStep: "Correct the flagged type (e.g. argument/return type or import), then re-verify."
+	},
+	EXPECTED_UNKNOWN_KEY: {
+		fix: "Your `expected` block has keys the CLI does not assert (so the intended check never ran). Bounds must be `{ xMin, xMax, yMin, yMax, zMin, zMax }` — not `{ min, max }` or `{ x, y, z }`.",
+		nextStep: "Rewrite `expected` using only volume, area, tolerancePct, and bounds.{xMin..zMax}, then re-verify."
 	}
 };
 /** Synthetic code attached to validity-check failures (validSolid returns a plain string error). */
@@ -302,8 +314,38 @@ function pctDelta(actual, expected) {
 	return Math.abs(actual - expected) / Math.abs(expected) * 100;
 }
 function withinTolerance(actual, expected, tolerancePct) {
+	if (Math.abs(actual - expected) <= 1e-6) return true;
 	return pctDelta(actual, expected) <= tolerancePct;
 }
+var TOP_LEVEL_KEYS = new Set([
+	"volume",
+	"area",
+	"bounds",
+	"tolerancePct"
+]);
+var BOUND_KEYS = new Set([
+	"xMin",
+	"xMax",
+	"yMin",
+	"yMax",
+	"zMin",
+	"zMax"
+]);
+/**
+* Keys in an `expected` block that the CLI does not understand and would silently ignore — a
+* `{ min: [...], max: [...] }` or `{ x: [...] }` bounds shape, or a misspelled top-level field.
+* Surfaced as an error (not dropped) so a wrong `expected` shape fails loud instead of passing
+* vacuously with the intended assertion never run.
+*/
+function unknownExpectedKeys(expected) {
+	const bad = [];
+	for (const k of Object.keys(expected)) if (!TOP_LEVEL_KEYS.has(k)) bad.push(k);
+	const bounds = expected.bounds;
+	if (bounds && typeof bounds === "object") {
+		for (const k of Object.keys(bounds)) if (!BOUND_KEYS.has(k)) bad.push(`bounds.${k}`);
+	}
+	return bad;
+}
 function isExpectedDims(v) {
 	if (typeof v !== "object" || v === null) return false;
 	const r = v;
@@ -427,6 +469,25 @@ var COMPILER_OPTIONS = {
 	skipLibCheck: true,
 	allowImportingTsExtensions: true
 };
+/**
+* Locate the `@types/node` declarations so a part may import Node built-ins (`node:fs` to load a
+* font, `node:fs/promises` to read a STEP file, etc.) without `--check` failing on the import.
+* Returns the `@types` directory to use as a `typeRoots` entry. Probes the tool's own install
+* first (where `@types/node` ships as a dependency), then the part's directory.
+*/
+function nodeTypesRoot(partPath, toolDir) {
+	const froms = [
+		{}.url,
+		toolDir ? (0, node_url.pathToFileURL)((0, node_path.resolve)(toolDir, "package.json")).href : void 0,
+		(0, node_url.pathToFileURL)(partPath).href
+	];
+	for (const from of froms) {
+		if (!from) continue;
+		try {
+			return (0, node_path.dirname)((0, node_path.dirname)((0, node_module.createRequire)(from).resolve("@types/node/package.json")));
+		} catch {}
+	}
+}
 function diagnosticToErrorInfo(d) {
 	const text = typescript.default.flattenDiagnosticMessageText(d.messageText, "\n");
 	let where = "";
@@ -451,6 +512,11 @@ function typecheckPart(partPath, toolDir) {
 	const dts = resolveBrepjsTypes(partPath, toolDir);
 	const options = { ...COMPILER_OPTIONS };
 	if (dts) options.paths = { brepjs: [dts] };
+	const typesRoot = nodeTypesRoot(partPath, toolDir);
+	if (typesRoot) {
+		options.typeRoots = [typesRoot];
+		options.types = ["node"];
+	}
 	const program = typescript.default.createProgram([partPath], options);
 	const errors = [
 		...program.getSemanticDiagnostics(),
@@ -487,7 +553,13 @@ function toErrorInfo(prefix, e) {
 		code: e.code,
 		suggestion: e.suggestion
 	};
-	if (e instanceof Error) return { message: `${prefix}: ${e.message}` };
+	if (e instanceof Error) {
+		const code = e.message.match(/\[[A-Z][A-Z0-9_]*\]\s+([A-Z][A-Z0-9_]+):/)?.[1];
+		return code ? {
+			message: `${prefix}: ${e.message}`,
+			code
+		} : { message: `${prefix}: ${e.message}` };
+	}
 	return { message: `${prefix}: ${String(e)}` };
 }
 function finalize(result) {
@@ -567,6 +639,11 @@ async function runPart(modulePath, opts = {}) {
 	if (isExpectedDims(mod.expected)) {
 		const expected = mod.expected;
 		result.assertions = evaluateExpected(expected, result.measurements);
+		const unknown = unknownExpectedKeys(expected);
+		if (unknown.length > 0) pushError(result, {
+			message: `expected has unrecognized keys (ignored): ${unknown.join(", ")}. Valid keys: volume, area, tolerancePct, bounds.{xMin,xMax,yMin,yMax,zMin,zMax}.`,
+			code: "EXPECTED_UNKNOWN_KEY"
+		});
 	}
 	let glb;
 	let step;

package/dist/{diff-Covv1XuJ.js → diff-D5U3Ie2F.js}

@@ -162,6 +162,14 @@ var HINT_TABLE = {
 		fix: "The boolean subtraction failed — often a tool that does not actually intersect the base, or tolerance issues.",
 		nextStep: "Confirm the tool overlaps the base, optionally heal the inputs, then re-cut."
 	},
+	FILLET_FAILED: {
+		fix: "The fillet could not be built — usually the radius is too large for an edge it touched (it cannot exceed the adjacent face/wall), or you filleted EVERY edge (the no-edge-list form) including ones too thin to round.",
+		nextStep: "Select only the edges you mean to round — e.g. edgeFinder().inDirection(\"Z\").findAll(solid) — and/or reduce the radius below the thinnest adjacent wall, then re-verify."
+	},
+	CHAMFER_FAILED: {
+		fix: "The chamfer could not be built — usually the distance is too large for an edge it touched, or you chamfered EVERY edge (the no-edge-list form) including ones too thin.",
+		nextStep: "Select only the target edges with an edge finder and/or reduce the distance below the shortest adjacent edge, then re-verify."
+	},
 	BOOLEAN_HAS_ERRORS: {
 		fix: "The boolean ran but the kernel reported errors (often coincident faces or near-tangent contact).",
 		nextStep: "Perturb one operand slightly so contact is a clean overlap, or heal the inputs, then retry."
@@ -197,6 +205,10 @@ var HINT_TABLE = {
 	TYPECHECK: {
 		fix: "Fix the TypeScript type error before running the part — the API call or value does not match brepjs’s types.",
 		nextStep: "Correct the flagged type (e.g. argument/return type or import), then re-verify."
+	},
+	EXPECTED_UNKNOWN_KEY: {
+		fix: "Your `expected` block has keys the CLI does not assert (so the intended check never ran). Bounds must be `{ xMin, xMax, yMin, yMax, zMin, zMax }` — not `{ min, max }` or `{ x, y, z }`.",
+		nextStep: "Rewrite `expected` using only volume, area, tolerancePct, and bounds.{xMin..zMax}, then re-verify."
 	}
 };
 /** Synthetic code attached to validity-check failures (validSolid returns a plain string error). */
@@ -300,8 +312,38 @@ function pctDelta(actual, expected) {
 	return Math.abs(actual - expected) / Math.abs(expected) * 100;
 }
 function withinTolerance(actual, expected, tolerancePct) {
+	if (Math.abs(actual - expected) <= 1e-6) return true;
 	return pctDelta(actual, expected) <= tolerancePct;
 }
+var TOP_LEVEL_KEYS = new Set([
+	"volume",
+	"area",
+	"bounds",
+	"tolerancePct"
+]);
+var BOUND_KEYS = new Set([
+	"xMin",
+	"xMax",
+	"yMin",
+	"yMax",
+	"zMin",
+	"zMax"
+]);
+/**
+* Keys in an `expected` block that the CLI does not understand and would silently ignore — a
+* `{ min: [...], max: [...] }` or `{ x: [...] }` bounds shape, or a misspelled top-level field.
+* Surfaced as an error (not dropped) so a wrong `expected` shape fails loud instead of passing
+* vacuously with the intended assertion never run.
+*/
+function unknownExpectedKeys(expected) {
+	const bad = [];
+	for (const k of Object.keys(expected)) if (!TOP_LEVEL_KEYS.has(k)) bad.push(k);
+	const bounds = expected.bounds;
+	if (bounds && typeof bounds === "object") {
+		for (const k of Object.keys(bounds)) if (!BOUND_KEYS.has(k)) bad.push(`bounds.${k}`);
+	}
+	return bad;
+}
 function isExpectedDims(v) {
 	if (typeof v !== "object" || v === null) return false;
 	const r = v;
@@ -425,6 +467,25 @@ var COMPILER_OPTIONS = {
 	skipLibCheck: true,
 	allowImportingTsExtensions: true
 };
+/**
+* Locate the `@types/node` declarations so a part may import Node built-ins (`node:fs` to load a
+* font, `node:fs/promises` to read a STEP file, etc.) without `--check` failing on the import.
+* Returns the `@types` directory to use as a `typeRoots` entry. Probes the tool's own install
+* first (where `@types/node` ships as a dependency), then the part's directory.
+*/
+function nodeTypesRoot(partPath, toolDir) {
+	const froms = [
+		import.meta.url,
+		toolDir ? pathToFileURL(resolve(toolDir, "package.json")).href : void 0,
+		pathToFileURL(partPath).href
+	];
+	for (const from of froms) {
+		if (!from) continue;
+		try {
+			return dirname(dirname(createRequire(from).resolve("@types/node/package.json")));
+		} catch {}
+	}
+}
 function diagnosticToErrorInfo(d) {
 	const text = ts.flattenDiagnosticMessageText(d.messageText, "\n");
 	let where = "";
@@ -449,6 +510,11 @@ function typecheckPart(partPath, toolDir) {
 	const dts = resolveBrepjsTypes(partPath, toolDir);
 	const options = { ...COMPILER_OPTIONS };
 	if (dts) options.paths = { brepjs: [dts] };
+	const typesRoot = nodeTypesRoot(partPath, toolDir);
+	if (typesRoot) {
+		options.typeRoots = [typesRoot];
+		options.types = ["node"];
+	}
 	const program = ts.createProgram([partPath], options);
 	const errors = [
 		...program.getSemanticDiagnostics(),
@@ -485,7 +551,13 @@ function toErrorInfo(prefix, e) {
 		code: e.code,
 		suggestion: e.suggestion
 	};
-	if (e instanceof Error) return { message: `${prefix}: ${e.message}` };
+	if (e instanceof Error) {
+		const code = e.message.match(/\[[A-Z][A-Z0-9_]*\]\s+([A-Z][A-Z0-9_]+):/)?.[1];
+		return code ? {
+			message: `${prefix}: ${e.message}`,
+			code
+		} : { message: `${prefix}: ${e.message}` };
+	}
 	return { message: `${prefix}: ${String(e)}` };
 }
 function finalize(result) {
@@ -565,6 +637,11 @@ async function runPart(modulePath, opts = {}) {
 	if (isExpectedDims(mod.expected)) {
 		const expected = mod.expected;
 		result.assertions = evaluateExpected(expected, result.measurements);
+		const unknown = unknownExpectedKeys(expected);
+		if (unknown.length > 0) pushError(result, {
+			message: `expected has unrecognized keys (ignored): ${unknown.join(", ")}. Valid keys: volume, area, tolerancePct, bounds.{xMin,xMax,yMin,yMax,zMin,zMax}.`,
+			code: "EXPECTED_UNKNOWN_KEY"
+		});
 	}
 	let glb;
 	let step;

package/dist/verify/expected.d.ts

@@ -16,8 +16,23 @@ export interface ExpectedDims {
     tolerancePct?: number;
 }
 export declare const DEFAULT_TOLERANCE_PCT = 0.5;
+/**
+ * Absolute slack (mm / mm² / mm³) below which a deviation always passes, independent of
+ * percent tolerance. Kernel coordinates carry sub-nanometer float noise (e.g. a loft base
+ * lands at z = -1e-7, not 0), so a percent comparison against an expected `0` — where any
+ * nonzero deviation is infinite percent — would make a zero-valued bound or measurement
+ * impossible to assert. 1e-6 is far above that noise and far below any real feature size.
+ */
+export declare const ABS_EPSILON = 0.000001;
 /** Percent deviation of `actual` from `expected`; 0 expected matches only 0 actual. */
 export declare function pctDelta(actual: number, expected: number): number;
+/**
+ * Keys in an `expected` block that the CLI does not understand and would silently ignore — a
+ * `{ min: [...], max: [...] }` or `{ x: [...] }` bounds shape, or a misspelled top-level field.
+ * Surfaced as an error (not dropped) so a wrong `expected` shape fails loud instead of passing
+ * vacuously with the intended assertion never run.
+ */
+export declare function unknownExpectedKeys(expected: object): string[];
 export declare function isExpectedDims(v: unknown): v is ExpectedDims;
 /**
  * Compare measured dimensions against a part's `expected` export. Each declared field becomes one

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brepjs-verify",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Agent skill + verify/preview tooling for authoring parametric brepjs CAD code",
   "license": "Apache-2.0",
   "type": "module",
@@ -34,12 +34,13 @@
   "files": [
     "dist",
     "viewer/dist",
+    "reference",
     "CHANGELOG.md",
     "LICENSE",
     "README.md"
   ],
   "scripts": {
-    "build": "vite build && vite build --config viewer/vite.config.ts",
+    "build": "node scripts/copyReference.mjs && vite build && vite build --config viewer/vite.config.ts",
     "typecheck": "tsc --noEmit && tsc -p viewer/tsconfig.json --noEmit && tsc -p bench/tsconfig.json",
     "lint": "eslint src tests viewer bench",
     "test": "vitest run",
@@ -50,6 +51,7 @@
     "prepack": "npm run build"
   },
   "dependencies": {
+    "@types/node": "^25.9.1",
     "brepjs": "^18.0.0",
     "commander": "^13.0.0",
     "occt-wasm": "^3.0.0",