partforge 0.7.0 → 0.9.0

package/src/parts/faceted-vase.js

@@ -0,0 +1,75 @@
+// Example PartDefinition — the motivating showcase for k.loft(). Silhouette rings are
+// stacked up a smooth base→waist→rim curve; each ring is a regular n-gon rotated by a
+// running twist plus an alternating half-facet offset, so the facets zig-zag into a
+// woven look. A second, wall-inset loft is cut from the body to hollow it (Manifold
+// backend, so it stays fast — no OCCT). See docs/AUTHORING-PARTS.md for the conventions.
+import { regularPolygon } from "partforge/geometry";
+
+const RINGS = 28; // silhouette resolution (ring count up the height)
+
+// Body radius at height fraction t (0..1): a quadratic Bézier through base/waist/rim.
+const silhouette = (t, p) => { const a = 1 - t; return a * a * p.baseR + 2 * a * t * p.waistR + t * t * p.rimR; };
+
+// Ring list for a wall at radial `inner` inset (offset along the face normal so the
+// perpendicular wall stays == p.wall on every facet). inner=false → outer surface.
+const vaseRings = (p, inner) => {
+  const inset = inner ? p.wall / Math.cos(Math.PI / p.facets) : 0;
+  const out = [];
+  for (let i = 0; i <= RINGS; i++) {
+    const t = i / RINGS;
+    const radius = Math.max(silhouette(t, p) - inset, 0.5);
+    const rotate = p.twist * t + (i % 2) * (180 / p.facets); // running twist + alternating half-facet
+    out.push({ sides: p.facets, radius, z: p.height * t, rotate });
+  }
+  return out;
+};
+
+export default {
+  meta: { title: "Faceted Vase", units: "mm", background: 0x15181d },
+  parameters: [
+    {
+      id: "body",
+      title: "Body",
+      description: "A faceted, twisting vase built from stacked cross-sections (`k.loft`). " +
+        "Pick a preset, or open **Advanced** for exact dimensions. **Facets** and **Twist** are the styling; **Wall** decides whether it prints cleanly.",
+      presets: {
+        "Tulip vase": { height: 150, baseR: 35, waistR: 26, rimR: 40, facets: 5, twist: 40, wall: 2 },
+        "Barrel pot": { height: 90, baseR: 40, waistR: 44, rimR: 38, facets: 8, twist: 0, wall: 2.4 },
+        "Twist column": { height: 180, baseR: 30, waistR: 30, rimR: 30, facets: 6, twist: 120, wall: 2 },
+      },
+      advanced: [
+        { key: "height", label: "Height", unit: "mm", min: 40, max: 220, step: 1, description: "Overall height along the axis." },
+        { key: "baseR", label: "Base radius", unit: "mm", min: 15, max: 70, step: 1, description: "Across-corners radius at the foot." },
+        { key: "waistR", label: "Waist radius", unit: "mm", min: 12, max: 80, step: 1, description: "Radius at mid-height — set below base+rim to pinch a waist, above to bulge a belly." },
+        { key: "rimR", label: "Rim radius", unit: "mm", min: 12, max: 80, step: 1, description: "Across-corners radius at the mouth." },
+        { key: "facets", label: "Facets", min: 3, max: 12, step: 1, description: "Sides of each cross-section. Low counts read crystalline; high counts approach smooth." },
+        { key: "twist", label: "Twist", unit: "°", min: 0, max: 180, step: 5, description: "Total rotation of the facets from foot to rim, for a spiral." },
+        { key: "wall", label: "Wall thickness", unit: "mm", min: 1, max: 5, step: 0.1, description: "Perpendicular wall thickness. The fdm-pla profile wants **≥ 1.2 mm**." },
+        { key: "floor", label: "Floor thickness", unit: "mm", min: 1, max: 8, step: 0.5, hidden: true, description: "Internal: solid base thickness; hidden but drives the geometry." },
+      ],
+    },
+  ],
+  defaults: { height: 150, baseR: 35, waistR: 26, rimR: 40, facets: 5, twist: 40, wall: 2, floor: 3 },
+  parts: {
+    vase: {
+      label: "Vase", views: ["vase"], export: { name: "vase" },
+      build: (k, p) => {
+        const body = k.loft(vaseRings(p, false)).label("Faceted wall");
+        // Hollow it: an inset loft clipped to z ≥ floor (so the base stays solid), cut from the body.
+        const cavity = k.loft(vaseRings(p, true))
+          .intersect(k.box([-1e4, -1e4, p.floor], [1e4, 1e4, p.height + 10])).label("Cavity");
+        return body.cut(cavity);
+      },
+    },
+  },
+  views: { vase: { label: "Vase" } },
+  // Self-verification: opt into the FDM-PLA profile (bed-fit gate + min-wall warning) and
+  // pin the intent — an open vessel (no through-holes), fits the bed, no interpenetration.
+  verify: {
+    process: "fdm-pla",
+    expect: {
+      vase: { holes: 0, bbox: "<=[220,220,230]" },
+      _view: { overlaps: 0 },
+    },
+  },
+};

package/src/testing/error-patterns.js

@@ -0,0 +1,78 @@
+// Shared parser + matcher for docs/ERROR-PATTERNS.md — the symptom-indexed
+// error→pattern library (issue #28). The parser here is the single source of
+// truth: the format lint (test/error-patterns.test.js) and the CLI crash-path
+// matcher (issue #27) both import it. Contract: partforge code that throws must
+// throw strings appearing verbatim, in a backtick literal AT THE START of some
+// entry's Symptom line — only a leading literal participates in matching, so
+// backticks used for prose mid-sentence never mis-attribute an unrelated crash.
+import { readFileSync } from "node:fs";
+
+// Single-pass, fence-aware parse: a heading inside a ``` / ~~~ fence is quoted
+// content, not structure. Each `## <id>` entry records the `# <section>` it sits
+// under; its body runs to the next h1/h2 heading. (Moved verbatim from the lint
+// test, then enriched with symptom/cause/fix extraction.)
+export function parsePatterns(md) {
+  const entries = [];
+  let section = null;
+  let entry = null;
+  let inFence = false;
+  for (const line of md.split("\n")) {
+    if (/^\s*(```|~~~)/.test(line)) {
+      inFence = !inFence;
+      if (entry) entry.body += line + "\n";
+      continue;
+    }
+    if (!inFence) {
+      const h1 = line.match(/^# (.+)$/);
+      const h2 = line.match(/^## (.+)$/);
+      if (h1) { section = h1[1]; entry = null; continue; }
+      if (h2) { entry = { id: h2[1], section, body: "" }; entries.push(entry); continue; }
+    }
+    if (entry) entry.body += line + "\n";
+  }
+  const field = (body, label) => {
+    const i = body.indexOf(`- **${label}:**`);
+    return i < 0 ? null : body.slice(i).split("\n")[0].replace(`- **${label}:**`, "").trim();
+  };
+  return entries.map((e) => {
+    const symptom = field(e.body, "Symptom");
+    // Leading-literal convention: only a backtick literal at the very START of the
+    // Symptom text is a match literal (kept as a ≤1-element array for compatibility
+    // — tests and the matcher read symptomStrings). Mid-line backticks are prose.
+    const leading = symptom?.match(/^`([^`]+)`/);
+    return {
+      ...e,
+      symptom,
+      cause: field(e.body, "Cause"),
+      fix: field(e.body, "Fix"),
+      symptomStrings: leading ? [leading[1]] : [],
+    };
+  });
+}
+
+// Cached read of the live doc, resolved relative to this module so it works from
+// a consuming app's node_modules too. Any read/parse error → null (callers treat
+// that as "no patterns available", never an error).
+let cached;
+export function loadPatterns() {
+  if (cached !== undefined) return cached;
+  try {
+    cached = parsePatterns(readFileSync(new URL("../../docs/ERROR-PATTERNS.md", import.meta.url), "utf8"));
+  } catch {
+    cached = null;
+  }
+  return cached;
+}
+
+// Leading symptom literals ≥ 6 chars, longest match wins. Never throws.
+export function matchPattern(message, patterns = loadPatterns()) {
+  if (!patterns || typeof message !== "string") return null;
+  let best = null;
+  let bestLen = 5;
+  for (const p of patterns) {
+    for (const s of p.symptomStrings) {
+      if (s.length > bestLen && message.includes(s)) { best = p; bestLen = s.length; }
+    }
+  }
+  return best ? { id: best.id, fix: best.fix } : null;
+}

package/src/testing/measure.js

@@ -20,6 +20,7 @@ export function measure(kernel, part, view = Object.keys(part.views)[0], params
   const subparts = built.map(({ name, solid, mesh }) => {
     const b = bounds(mesh.positions);
     subBounds.push(b);
+    const mw = opts.minWall ? minWall(mesh) : null;
     return {
       name,
       bbox: size(b),
@@ -28,7 +29,8 @@ export function measure(kernel, part, view = Object.keys(part.views)[0], params
       triangleCount: mesh.triangles,
       watertight: typeof solid.isEmpty === "function" ? !solid.isEmpty() : null,
       holes: typeof solid.genus === "function" ? solid.genus() : null,
-      minWall: opts.minWall ? (minWall(mesh)?.value ?? null) : null,
+      minWall: mw?.value ?? null,
+      minWallAt: mw?.location ?? null,
     };
   });
 

package/src/testing/verify.js

@@ -4,36 +4,70 @@ import { resolveProfile } from "./dfm-profiles.js";
 import { expandCases } from "./cases.js";
 import { subPartReadKeys, relevanceHash, RELEVANT_ALL } from "../framework/param-deps.js";
 
-// Metric registry: name → how to pull the value out of facts, and whether a failure
-// is a hard gate or a warning. `manifoldOnly` facts are null on OCCT parts.
-const SUBPART_METRICS = {
-  holes: { kind: "gate", manifoldOnly: true, extract: (s) => s.holes },
-  watertight: { kind: "gate", manifoldOnly: true, extract: (s) => s.watertight },
-  volume: { kind: "gate", extract: (s) => s.volume },
-  surfaceArea: { kind: "gate", extract: (s) => s.surfaceArea },
-  triangleCount: { kind: "gate", extract: (s) => s.triangleCount },
-  bbox: { kind: "gate", extract: (s) => s.bbox },
-  minWall: { kind: "warn", extract: (s) => s.minWall },
+// Metric registry: name → how to pull the value out of facts, whether a failure
+// is a hard gate or a warning, and the diagnostics attached to a non-pass check:
+// `hint` (required — the report contract promises one on every fail/warn),
+// `pattern` (optional stable ERROR-PATTERNS.md#<id>), `locate` (optional
+// [x,y,z] source). `manifoldOnly` facts are null on OCCT parts.
+export const SUBPART_METRICS = {
+  holes: { kind: "gate", manifoldOnly: true, extract: (s) => s.holes,
+    hint: "genus is wrong — an unintended tunnel exists or an intended bore is blocked; make cut tools pierce fully (overcut past the faces)" },
+  watertight: { kind: "gate", manifoldOnly: true, extract: (s) => s.watertight,
+    hint: "a boolean produced an open shell — check for coplanar faces or a cut that exactly grazes a surface",
+    pattern: "boolean-not-watertight" },
+  volume: { kind: "gate", extract: (s) => s.volume,
+    hint: "solid volume is out of range — a feature is missing, doubled, or a governing parameter is mis-scaled" },
+  surfaceArea: { kind: "gate", extract: (s) => s.surfaceArea,
+    hint: "surface area is out of range — detail features (facets, ribs, textures) are missing or doubled" },
+  triangleCount: { kind: "gate", extract: (s) => s.triangleCount,
+    hint: "triangle count is out of range — tessellation quality or feature count changed unexpectedly" },
+  bbox: { kind: "gate", extract: (s) => s.bbox,
+    hint: "bounding box is out of range — check the governing dimensions and the part's orientation" },
+  minWall: { kind: "warn", extract: (s) => s.minWall,
+    hint: "thinnest wall is at the reported location — increase the governing wall/thickness parameter or reduce the intersecting feature's depth",
+    pattern: "minwall-sliver-triangles",
+    locate: (s) => s.minWallAt },
 };
-const VIEW_METRICS = {
-  bbox: { kind: "gate", extract: (r) => r.aggregate.bbox },
-  volume: { kind: "gate", extract: (r) => r.aggregate.volume },
-  overlaps: { kind: "gate", extract: (r) => r.overlaps.length },
+export const VIEW_METRICS = {
+  bbox: { kind: "gate", extract: (r) => r.aggregate.bbox,
+    hint: "the assembled view exceeds its size limit — shrink the assembly or pick a process with a larger bed" },
+  volume: { kind: "gate", extract: (r) => r.aggregate.volume,
+    hint: "total assembly volume is out of range — a sub-part is missing, doubled, or mis-scaled" },
+  overlaps: { kind: "gate", extract: (r) => r.overlaps.length,
+    hint: "sub-parts interpenetrate near the reported location — adjust placement or add clearance in derive()",
+    locate: (r) => r.overlaps[0]?.location ?? null },
 };
 
-function check(scope, subpart, metric, expr, registry, factsObj) {
+// An expectation is a bare expression (string/number/boolean) or { expr, hint }.
+const normalizeExpectation = (spec) =>
+  spec !== null && typeof spec === "object" && !Array.isArray(spec) && "expr" in spec
+    ? { expr: spec.expr, hint: spec.hint }
+    : { expr: spec, hint: undefined };
+
+function check(scope, subpart, metric, spec, registry, factsObj) {
   const reg = registry[metric];
   if (!reg) throw new Error(`unknown ${scope} metric "${metric}"${subpart ? ` on sub-part "${subpart}"` : ""}`);
+  const { expr, hint: partHint } = normalizeExpectation(spec);
   const actual = reg.extract(factsObj);
   const base = { scope, subpart, metric, kind: reg.kind, expr: String(expr) };
   if (actual === null || actual === undefined) {
     if (reg.manifoldOnly) return { ...base, actual, status: "skip", pass: null, message: "n/a (OCCT backend)" };
-    if (metric === "minWall") return { ...base, actual, status: "warn", pass: null, message: "min wall unavailable" };
+    if (metric === "minWall") {
+      return { ...base, actual, status: "warn", pass: null, message: "min wall unavailable",
+        hint: partHint ?? "no min-wall reading for this mesh — treat thin features as unverified" };
+    }
     return { ...base, actual, status: "skip", pass: null, message: "unavailable" };
   }
   const { pass, message } = evaluateAssertion(parseAssertion(expr), actual);
   const status = pass ? "pass" : reg.kind === "warn" ? "warn" : "fail";
-  return { ...base, actual, status, pass, message };
+  const out = { ...base, actual, status, pass, message };
+  if (!pass) {
+    out.hint = partHint ?? reg.hint;
+    if (reg.pattern) out.pattern = reg.pattern;
+    const loc = reg.locate?.(factsObj);
+    if (loc) out.location = loc;
+  }
+  return out;
 }
 
 // Pure policy: profile rules + per-part expect → checks for one case's facts.