partforge 0.26.1 → 0.28.0

package/src/framework/lint/finding.js

@@ -0,0 +1,20 @@
+// Finding constructors. The shape mirrors the diagnostics contract that verify's
+// checks already satisfy (docs/AUTHORING-PARTS.md "The diagnostics contract"):
+// a self-contained `hint` on every finding, plus an optional stable ERROR-PATTERNS.md
+// `pattern` id. Verify's [x,y,z] `location` is replaced by `path`, an accessor path
+// into the PartDefinition — nothing parses it, it is for navigation only.
+const make = (severity) => (rule, message, hint, path = "", pattern) => ({
+  rule, severity, message, hint, path, ...(pattern ? { pattern } : {}),
+});
+
+// error → the part is PROVABLY broken: it cannot behave as authored, whether or
+// not that surfaces as a thrown exception. A dead control (control-key-not-in-
+// defaults), a view that renders nothing (part-view-unknown), or a verify
+// expectation that's silently dropped so its gate never runs (verify-unknown-
+// subpart) build/measure/verify cleanly today and still earn error — the defect
+// is real even though nothing throws. Because `measure` gates on this tier, a
+// part with one of these silent defects now exits non-zero where it previously
+// didn't; that's the point, not a regression.
+export const err = make("error");
+// warning → suspicious or lossy, but the part behaves as authored.
+export const warn = make("warning");

package/src/framework/lint/index.js

@@ -0,0 +1,114 @@
+// partforge/lint — static PartDefinition validation. Pure: no I/O, no async, and
+// (load-bearing) an import closure that never reaches three / manifold-3d / replicad,
+// so this runs unchanged in Node, a browser sandbox iframe, and Deno. The purity
+// guarantee is enforced by test/lint-purity.test.js — read it before adding an import.
+//
+// A rule is { id, run(ctx) → Finding[] }, one rule object per finding id, so the
+// registry doubles as the documented rule catalog. Rules are cheap and parts are
+// tiny; clarity beats sharing a walk between rules.
+import { resolveDerived } from "../derive.js";
+import { err, warn } from "./finding.js";
+import { SHAPE_RULES } from "./rules-shape.js";
+import { SCHEMA_RULES } from "./rules-schema.js";
+import { runValidatingProbe } from "../geometry/probe.js";
+import { BUILD_RULES } from "./rules-build.js";
+import { VERIFY_RULES, resolveExpect } from "./rules-verify.js";
+
+export const RULES = [...SHAPE_RULES, ...SCHEMA_RULES, ...BUILD_RULES, ...VERIFY_RULES];
+
+// Every rule runs inside a guard. lintPart is called on a user-facing hosted path
+// (partforge-cloud's sandbox), and a linter that takes down the preview it exists to
+// protect is worse than no linter — so a throwing rule becomes a WARNING, never an
+// error, and never blocks a part that would otherwise have built.
+export function runRules(rules, ctx) {
+  const out = [];
+  for (const rule of rules) {
+    try {
+      const found = rule.run(ctx);
+      if (Array.isArray(found)) out.push(...found);
+    } catch (e) {
+      out.push(warn("internal-rule-error",
+        `lint rule "${rule.id}" threw: ${e?.message || String(e)}`,
+        "This is a partforge bug rather than a problem with your part; every other rule still ran. Please report it with the part that triggered it."));
+    }
+  }
+  return out;
+}
+
+// Build the shared context. A throwing derive() must not abort the lint — the
+// throw is captured as `deriveError` (for Group 3's `derive-throws` rule) and `d`
+// falls back to {}, so Groups 1/2/4 remain useful without derived values.
+//
+// Building `p` can itself throw — `part.defaults` may be a getter that throws, or
+// `part.defaults` / `params` may be a Proxy whose `ownKeys` trap throws (the spread
+// below walks own keys) — so that construction gets the same never-escapes
+// treatment as derive(): fall back to `{}` rather than let a hostile/broken input
+// take down lintContext (and, by extension, lintPart — see its own guard below).
+// The failure is also captured as `pError`, mirroring `deriveError`, so lintPart
+// can still surface it as a real finding instead of silently linting against an
+// empty `{}` params object as if nothing were wrong.
+export function lintContext(part, params) {
+  let p;
+  let pError = null;
+  try { p = { ...(part?.defaults ?? {}), ...(params ?? {}) }; }
+  catch (e) { p = {}; pError = e?.message || String(e); }
+  let d = {};
+  let deriveError = null;
+  try { d = resolveDerived(part ?? {}, p) ?? {}; } catch (e) { d = {}; deriveError = e?.message || String(e); }
+  let cached = null;
+  const probe = () => (cached ??= runValidatingProbe(part, p, d));
+  const probeAgain = () => runValidatingProbe(part, p, d);
+  // Group 4's several rules all need `verify.expect` resolved; `expect` may be a
+  // user-supplied function, so — same reasoning as `probe` above — resolve it once
+  // per lint pass and share it, rather than letting each rule invoke it again and
+  // risk a cascading double-report from a function that only throws sometimes.
+  let cachedExpect = null;
+  const resolveExpectOnce = () => (cachedExpect ??= resolveExpect(part?.verify, p, d));
+  return { part, p, d, pError, deriveError, probe, probeAgain, resolveExpectOnce };
+}
+
+/**
+ * Lint a PartDefinition. Never throws.
+ * @param {object} part   the default-exported PartDefinition
+ * @param {{params?: object}} [opts]  params layered over part.defaults for the probe pass
+ * @returns {{ok: boolean, errors: object[], warnings: object[]}}
+ */
+export function lintPart(part, opts) {
+  // `opts` is defaulted here, not via `= {}` on the parameter, because a default
+  // parameter only fires on `undefined` — a caller passing `lintPart(part, null)`
+  // (a plausible downstream-harness call) would otherwise throw destructuring
+  // `{ params }` out of `null` before this function's body ever runs.
+  const { params } = opts ?? {};
+  // lintContext already guards its own internals (see its comment above), but it
+  // is user-authored data all the way down — wrap the call itself too, so a
+  // failure mode neither of us has thought of still degrades to a report instead
+  // of an escaping throw. `lintPart` must never throw; that guarantee is a bigger
+  // deal than any one finding.
+  let ctx;
+  try {
+    ctx = lintContext(part, params);
+  } catch (e) {
+    return {
+      ok: false,
+      errors: [err("lint-context-error",
+        `partforge/lint could not build a lint context: ${e?.message || String(e)}`,
+        "This part is too malformed for lint to analyze safely — make sure `defaults`, `params`, and `verify`/`derive` are plain, side-effect-free data rather than throwing getters or hostile Proxies.",
+        "")],
+      warnings: [],
+    };
+  }
+  const findings = runRules(RULES, ctx);
+  // `p` (params merged from `defaults`) failed to build — every rule still ran
+  // against the `{}` fallback (each guarded individually by runRules), but the
+  // part is provably broken independent of whatever those rules happened to
+  // notice, so report it directly rather than relying on incidental fallout.
+  if (ctx.pError) {
+    findings.push(err("lint-context-error",
+      `partforge/lint could not read \`defaults\`/\`params\`: ${ctx.pError}`,
+      "Make sure `defaults` and any `params` passed to lintPart are plain, side-effect-free data rather than a throwing getter or a hostile Proxy.",
+      ""));
+  }
+  const errors = findings.filter((f) => f.severity === "error");
+  const warnings = findings.filter((f) => f.severity === "warning");
+  return { ok: errors.length === 0, errors, warnings };
+}

package/src/framework/lint/rules-build.js

@@ -0,0 +1,84 @@
+// Group 3 — how the build uses the kernel, discovered by executing build() against
+// the validating probe with no geometry kernel. Every error in this group already
+// throws at runtime; the value is reaching it in microseconds, before a WASM boot.
+import { err, warn } from "./finding.js";
+import { OCCT_ONLY_OPS } from "../geometry/kernel.js";
+import { MAX_PROBE_OPS } from "../geometry/probe.js";
+
+const OCCT_ONLY = new Set(OCCT_ONLY_OPS);
+const unique = (xs) => [...new Set(xs)];
+
+export const BUILD_RULES = [
+  {
+    id: "derive-throws",
+    run: ({ deriveError }) => (deriveError ? [
+      err("derive-throws", `derive(p) threw: ${deriveError}`,
+        "derive(p) must return derived values for any parameter set the defaults allow — fix the error so it does not throw. As written, the app is left spinning with no geometry: resolveParams's catch reports the failure but no build ever runs.",
+        "derive"),
+    ] : []),
+  },
+  {
+    id: "unknown-kernel-op",
+    run: ({ probe }) => unique(probe().issues
+      .filter((i) => i.kind === "unknown-op" && i.scope === "kernel").map((i) => i.op))
+      .map((op) => err("unknown-kernel-op", `\`k.${op}(…)\` is not a kernel operation`,
+        `Remove the call or correct the name — see the kernel op table in docs/AUTHORING-PARTS.md for the full list.`,
+        "parts")),
+  },
+  {
+    id: "unknown-solid-op",
+    run: ({ probe }) => unique(probe().issues
+      .filter((i) => i.kind === "unknown-op" && i.scope === "solid").map((i) => i.op))
+      .map((op) => err("unknown-solid-op", `\`.${op}(…)\` is not a Solid or Shape2D method`,
+        `Remove the call or correct the name — see the Solid and Shape2D method tables in docs/AUTHORING-PARTS.md.`,
+        "parts")),
+  },
+  {
+    id: "invalid-op-options",
+    run: ({ probe }) => unique(probe().issues
+      .filter((i) => i.kind === "invalid-options").map((i) => i.message))
+      .map((message) => err("invalid-op-options", message,
+        "Correct the options object to match the op's documented keys — the message above names the offending key or the missing required one.",
+        "parts")),
+  },
+  {
+    id: "build-throws",
+    run: ({ probe }) => probe().throws.map(({ subpart, message }) =>
+      err("build-throws", `sub-part "${subpart}" threw during a geometry-free build: ${message}`,
+        "Fix the error in build(). This was raised with no kernel attached, so it is a fault in the build's own logic (bad arithmetic, a missing param, a null dereference) rather than a geometry failure.",
+        `parts.${subpart}.build`)),
+  },
+  {
+    id: "manifold-backend-uses-occt-op",
+    run: ({ part, probe }) => {
+      if (part?.meta?.backend !== "manifold") return [];
+      return [...probe().used].filter((op) => OCCT_ONLY.has(op))
+        .map((op) => err("manifold-backend-uses-occt-op",
+          `\`meta.backend\` pins Manifold, but the build calls \`${op}\`, which only OCCT implements`,
+          `Remove \`meta.backend: "manifold"\` and let the probe route this part to OCCT, or replace \`${op}\` with a mesh-friendly construction — as written the build throws KernelCapabilityError.`,
+          "meta.backend"));
+    },
+  },
+  {
+    id: "build-runaway",
+    run: ({ probe }) => (probe().runaway ? [
+      err("build-runaway", `the build exceeded ${MAX_PROBE_OPS} kernel operations`,
+        "A loop in build() is not terminating, or a count parameter is far larger than intended. Bound the loop, or reduce the governing parameter.",
+        "parts"),
+    ] : []),
+  },
+  {
+    id: "nondeterministic-build",
+    run: ({ probe, probeAgain }) => {
+      const a = probe();
+      if (a.runaway || a.throws.length > 0) return []; // an aborted build can't be compared
+      const b = probeAgain();
+      if (b.runaway || b.throws.length > 0) return [];
+      if (JSON.stringify(a.calls) === JSON.stringify(b.calls)) return [];
+      return [warn("nondeterministic-build",
+        "two builds with identical parameters produced different kernel calls",
+        "build() must be a pure function of (k, p, d). Remove Math.random(), Date/clock reads, and module-level mutable state — the preview kernel memoizes geometry by content hash, so an impure build silently returns stale geometry.",
+        "parts", "impure-build-stale-preview")];
+    },
+  },
+];

package/src/framework/lint/rules-schema.js

@@ -0,0 +1,209 @@
+// Group 2 — the parameter schema that src/framework/controls.js turns into the panel.
+// Two failure modes drive this group: a shape controls.js reads without guarding
+// (features[].sliders at controls.js:313, an unguarded .filter), and keys that don't
+// resolve against `defaults`, which produce a control that silently does nothing.
+import { err, warn } from "./finding.js";
+import { suggest } from "../geometry/op-options.js";
+
+// Fields controls.js reads on a slider/number descriptor.
+const CONTROL_FIELDS = ["key", "label", "unit", "min", "max", "step", "control", "hidden", "description"];
+const FEATURE_FIELDS = ["key", "label", "on", "sliders", "hidden", "description"];
+const TOGGLE_FIELDS = ["key", "label", "on", "hidden", "description"];
+
+const sections = (part) => (Array.isArray(part?.parameters) ? part.parameters : []);
+const arr = (x) => (Array.isArray(x) ? x : []);
+const isPlainObject = (x) => x !== null && typeof x === "object" && !Array.isArray(x);
+
+// Every (descriptor, path, allowed-fields) triple that owns a parameter key, across
+// all four section kinds. A feature's own `sliders` are collected too, since each
+// slider is a full control descriptor in its own right.
+function collectDescriptors(part) {
+  const out = [];
+  sections(part).forEach((sec, si) => {
+    arr(sec?.advanced).forEach((d, i) => {
+      if (d) out.push({ d, path: `parameters[${si}].advanced[${i}]`, fields: CONTROL_FIELDS });
+    });
+    arr(sec?.features).forEach((f, i) => {
+      if (!f) return;
+      out.push({ d: f, path: `parameters[${si}].features[${i}]`, fields: FEATURE_FIELDS });
+      arr(f.sliders).forEach((s, j) => {
+        // Tag with the owning feature's key so slider-range-excludes-default can
+        // recognise the demo.js flange_d pattern below: a slider sharing its key
+        // with the feature is not an independent parameter, it's the feature's own
+        // magnitude, and `defaults[key] === 0` there means "off", not "out of range".
+        if (s) out.push({ d: s, path: `parameters[${si}].features[${i}].sliders[${j}]`, fields: CONTROL_FIELDS, featureKey: f.key });
+      });
+    });
+    arr(sec?.toggles).forEach((t, i) => {
+      if (t) out.push({ d: t, path: `parameters[${si}].toggles[${i}]`, fields: TOGGLE_FIELDS });
+    });
+  });
+  return out;
+}
+
+const defaultKeys = (part) => new Set(Object.keys(part?.defaults ?? {}));
+
+// Mirrors src/framework/controls.js's own visibility predicates (visibleFeatures /
+// sectionRenders, controls.js:32,36-41) — NOT imported, because controls.js pulls in
+// `marked`/`dompurify` (via markdown.js) for its description popovers, which would
+// break partforge/lint's zero-bare-dependency purity guarantee (test/lint-purity.test.js).
+// `features-requires-sliders` must not flag a `feat.sliders.filter(...)` the panel
+// will never reach: controls.js only iterates `visibleFeatures(sec)` (skipping any
+// feature marked `hidden: true`), and only builds a section at all when
+// `sectionRenders(sec)` is true.
+const visibleFeatures = (sec) => arr(sec?.features).filter((f) => f && !f.hidden);
+function sectionRenders(sec) {
+  if (sec?.hidden) return false;
+  if (sec?.features) return visibleFeatures(sec).length > 0;
+  const hasPresets = sec?.presets && Object.keys(sec.presets).length > 0;
+  return !!hasPresets || arr(sec?.advanced).some((d) => d && !d.hidden) || arr(sec?.toggles).some((t) => t && !t.hidden);
+}
+
+export const SCHEMA_RULES = [
+  {
+    id: "features-requires-sliders",
+    run: ({ part }) => {
+      const out = [];
+      sections(part).forEach((sec, si) => {
+        // A feature the panel will never reach can't crash it: skip the whole
+        // section when it never renders at all (sectionRenders), and skip any
+        // individual feature the panel skips via `hidden: true` (visibleFeatures'
+        // own filter condition, restated inline rather than built into a Set).
+        if (!sectionRenders(sec)) return;
+        arr(sec?.features).forEach((f, i) => {
+          if (f && !f.hidden && !Array.isArray(f.sliders)) {
+            out.push(err("features-requires-sliders",
+              `section "${sec.id ?? si}" feature ${i} has no \`sliders\` array`,
+              "A `features` entry must carry a `sliders` array — the control panel reads it unguarded, so a missing one throws \"Cannot read properties of undefined (reading 'filter')\". A bare on/off control belongs in `toggles` instead.",
+              `parameters[${si}].features[${i}]`,
+              "features-missing-sliders"));
+          }
+        });
+      });
+      return out;
+    },
+  },
+  {
+    id: "control-key-not-in-defaults",
+    run: ({ part }) => {
+      // Only skip when `defaults` isn't a plain object at all (missing-defaults
+      // already reports that) — an explicit `defaults: {}` must still be checked,
+      // otherwise every control key in the part is silently unreachable and dead.
+      if (!isPlainObject(part?.defaults)) return [];
+      const known = defaultKeys(part);
+      return collectDescriptors(part)
+        .filter(({ d }) => typeof d.key === "string" && !known.has(d.key))
+        .map(({ d, path }) => err("control-key-not-in-defaults",
+          `control key "${d.key}" is not in \`defaults\``,
+          `Add "${d.key}" to \`defaults\`${suggest(d.key, [...known]) ? `, or correct it to "${suggest(d.key, [...known])}"` : ""} — a control whose key is absent from defaults is silently dead and never reaches the build.`,
+          `${path}.key`));
+    },
+  },
+  {
+    id: "preset-key-not-in-defaults",
+    run: ({ part }) => {
+      // Same guard as control-key-not-in-defaults: only bail when `defaults` is
+      // entirely absent (or not an object), not merely empty.
+      if (!isPlainObject(part?.defaults)) return [];
+      const known = defaultKeys(part);
+      const out = [];
+      sections(part).forEach((sec, si) => {
+        const presets = sec?.presets;
+        if (!presets || typeof presets !== "object") return;
+        for (const [name, bundle] of Object.entries(presets)) {
+          if (!bundle || typeof bundle !== "object") continue;
+          for (const key of Object.keys(bundle)) {
+            if (known.has(key)) continue;
+            const hint = suggest(key, [...known]);
+            out.push(err("preset-key-not-in-defaults",
+              `preset "${name}" sets "${key}", which is not in \`defaults\``,
+              `Add "${key}" to \`defaults\`${hint ? `, or correct it to "${hint}"` : ""} — a preset field absent from defaults is dropped, so selecting the preset silently does nothing for it.`,
+              `parameters[${si}].presets[${JSON.stringify(name)}].${key}`));
+          }
+        }
+      });
+      return out;
+    },
+  },
+  {
+    id: "slider-range-excludes-default",
+    run: ({ part }) => {
+      const defaults = part?.defaults ?? {};
+      return collectDescriptors(part)
+        // A slider that shares its key with the feature that owns it (demo.js's
+        // flange_d) is exempt ONLY when the default is actually the feature's
+        // off-sentinel: controls.js sets `params[feat.key] = 0` on uncheck (and
+        // reads `params[feat.key] > 0` to decide checked state), so `0` there means
+        // "off", not "out of range". Matching keys alone isn't enough — a mistyped
+        // non-zero "on" default (e.g. 999 against an 8..50 slider) is exactly the
+        // authoring mistake this rule exists to catch, and must still warn.
+        .filter(({ d, featureKey }) => !(featureKey !== undefined && featureKey === d.key && defaults[d.key] === 0))
+        .filter(({ d }) => typeof d.key === "string"
+          && typeof defaults[d.key] === "number"
+          && (typeof d.min === "number" || typeof d.max === "number")
+          && ((typeof d.min === "number" && defaults[d.key] < d.min)
+            || (typeof d.max === "number" && defaults[d.key] > d.max)))
+        .map(({ d, path }) => warn("slider-range-excludes-default",
+          `\`defaults.${d.key}\` is ${defaults[d.key]}, outside this control's range ${d.min ?? "-∞"}..${d.max ?? "∞"}`,
+          `Widen the control's min/max or move \`defaults.${d.key}\` inside the range — as it stands the panel clamps the value on first render, so the geometry the user sees is not the geometry the defaults describe.`,
+          path));
+    },
+  },
+  {
+    id: "unknown-control-field",
+    run: ({ part }) => {
+      const out = [];
+      for (const { d, path, fields } of collectDescriptors(part)) {
+        for (const key of Object.keys(d)) {
+          if (fields.includes(key)) continue;
+          const hint = suggest(key, fields);
+          out.push(warn("unknown-control-field",
+            `unrecognised control field "${key}"`,
+            `The control panel ignores "${key}"${hint ? ` — did you mean "${hint}"?` : ` (recognised: ${fields.join(", ")}).`}`,
+            `${path}.${key}`));
+        }
+      }
+      return out;
+    },
+  },
+  {
+    id: "duplicate-control-key",
+    run: ({ part }) => {
+      const seen = new Map();
+      const out = [];
+      for (const { d, path } of collectDescriptors(part)) {
+        if (typeof d.key !== "string") continue;
+        // A feature and its own slider legitimately share a key (see demo.js's
+        // flange_d), so only flag a repeat that crosses to a different owner path.
+        const root = path.replace(/\.sliders\[\d+\]$/, "");
+        if (seen.has(d.key) && seen.get(d.key) !== root) {
+          out.push(warn("duplicate-control-key",
+            `parameter key "${d.key}" is owned by more than one control`,
+            `Two controls writing "${d.key}" fight over the same value — rename one, or remove the duplicate.`,
+            path));
+        } else if (!seen.has(d.key)) {
+          seen.set(d.key, root);
+        }
+      }
+      return out;
+    },
+  },
+  {
+    id: "default-not-exposed",
+    run: ({ part }) => {
+      if (sections(part).length === 0) return []; // no panel declared at all — nothing to expose
+      const exposed = new Set(collectDescriptors(part).map(({ d }) => d.key).filter(Boolean));
+      for (const sec of sections(part)) {
+        for (const bundle of Object.values(sec?.presets ?? {})) {
+          for (const key of Object.keys(bundle ?? {})) exposed.add(key);
+        }
+      }
+      return Object.keys(part?.defaults ?? {})
+        .filter((key) => !exposed.has(key))
+        .map((key) => warn("default-not-exposed",
+          `\`defaults.${key}\` is not referenced by any control`,
+          `Either add a control for "${key}" or leave it as an intentional internal constant — a hidden control (\`hidden: true\`) counts as exposing it, and is the documented way to keep a build-only value out of the panel.`,
+          `defaults.${key}`));
+    },
+  },
+];

package/src/framework/lint/rules-shape.js

@@ -0,0 +1,86 @@
+// Group 1 — definition shape and view wiring. This group is the shared replacement
+// for partforge-cloud's hand-rolled sandbox validate(), which checks meta.title,
+// defaults and build but not `views`, and had already drifted from the eval runner's
+// separate views check. One source of truth ends that split.
+import { err, warn } from "./finding.js";
+
+const isPlainObject = (x) => x !== null && typeof x === "object" && !Array.isArray(x);
+const partEntries = (part) => (isPlainObject(part?.parts) ? Object.entries(part.parts) : []);
+
+export const SHAPE_RULES = [
+  {
+    id: "missing-meta-title",
+    run: ({ part }) => (typeof part?.meta?.title === "string" && part.meta.title.length > 0 ? [] : [
+      err("missing-meta-title", "the part has no `meta.title`",
+        "Add a `meta` object with a `title` string — it names the part in the viewer and in export filenames.",
+        "meta.title"),
+    ]),
+  },
+  {
+    id: "missing-defaults",
+    run: ({ part }) => (isPlainObject(part?.defaults) ? [] : [
+      err("missing-defaults", "the part has no `defaults` object",
+        "Add a `defaults` object giving every parameter its starting value; the control panel and every build read from it.",
+        "defaults"),
+    ]),
+  },
+  {
+    id: "no-buildable-parts",
+    run: ({ part }) => {
+      const entries = partEntries(part);
+      if (entries.length === 0) {
+        return [err("no-buildable-parts", "the part declares no sub-parts in `parts`",
+          "Add at least one entry to `parts`, each with a `build(k, p, d)` function returning a solid.",
+          "parts")];
+      }
+      return entries
+        .filter(([, sp]) => typeof sp?.build !== "function")
+        .map(([name]) => err("no-buildable-parts", `sub-part "${name}" has no \`build\` function`,
+          "Every entry in `parts` needs a `build(k, p, d)` function that returns a solid.",
+          `parts.${name}.build`));
+    },
+  },
+  {
+    id: "missing-views",
+    run: ({ part }) => (isPlainObject(part?.views) && Object.keys(part.views).length > 0 ? [] : [
+      err("missing-views", "the part has no `views` map",
+        "Add a top-level `views` object — e.g. `views: { main: { label: \"Main\" } }` — and list each view name in the owning sub-part's `views` array.",
+        "views"),
+    ]),
+  },
+  {
+    id: "part-view-unknown",
+    run: ({ part }) => {
+      const known = isPlainObject(part?.views) ? new Set(Object.keys(part.views)) : new Set();
+      if (known.size === 0) return []; // missing-views already reported it; don't pile on
+      const out = [];
+      for (const [name, sp] of partEntries(part)) {
+        if (!Array.isArray(sp?.views)) continue;
+        sp.views.forEach((v, i) => {
+          if (!known.has(v)) {
+            out.push(err("part-view-unknown",
+              `sub-part "${name}" lists view "${v}", which is not in the \`views\` map`,
+              `Add "${v}" to the top-level \`views\` map, or correct the name to one of: ${[...known].join(", ")}.`,
+              `parts.${name}.views[${i}]`));
+          }
+        });
+      }
+      return out;
+    },
+  },
+  {
+    id: "view-unused",
+    run: ({ part }) => {
+      if (!isPlainObject(part?.views)) return [];
+      const used = new Set();
+      for (const [, sp] of partEntries(part)) {
+        if (Array.isArray(sp?.views)) for (const v of sp.views) used.add(v);
+      }
+      return Object.keys(part.views)
+        .filter((v) => !used.has(v))
+        .map((v) => warn("view-unused", `view "${v}" is not listed by any sub-part`,
+          `Either add "${v}" to a sub-part's \`views\` array or remove it from the \`views\` map — as it stands the view renders empty.`,
+          `views.${v}`));
+    },
+  },
+];