partforge 0.75.0 → 0.77.0

package/bin/cli.js

@@ -6,8 +6,8 @@
 import { parseArgs } from "node:util";
 import { spawnSync } from "node:child_process";
 import { pathToFileURL } from "node:url";
-import { resolve, dirname } from "node:path";
-import { writeFileSync, mkdirSync } from "node:fs";
+import { resolve, dirname, basename } from "node:path";
+import { writeFileSync, mkdirSync, readFileSync } from "node:fs";
 import { detectBackend } from "../src/framework/backend-select.js";
 import { fontsFor } from "../src/framework/fonts.js";
 import { viewAnimations, evaluate, cueAt } from "../src/framework/animation.js";
@@ -77,6 +77,21 @@ async function loadPart(partPath, usage) {
   return part;
 }
 
+// The source rules (group 9) read the part's TEXT, which `loadPart` never sees —
+// it imports the module, and evaluation is exactly what erases the defects those
+// rules exist for (`13 / 3` is just a number by then). The entry module's own file
+// is all we hand over: following relative imports is a deliberate non-goal, and a
+// missing/unreadable file simply leaves `sources` off, which turns the group into
+// a no-op rather than failing the command.
+const readSources = (partPath) => {
+  try {
+    const path = basename(partPath);
+    return { files: { [path]: readFileSync(resolve(process.cwd(), partPath), "utf8") }, entrypoint: path };
+  } catch {
+    return undefined;
+  }
+};
+
 // Pass the part's declared fonts through, mirroring the worker path (jobs.js) —
 // otherwise a part using a named font builds in the browser but dies headlessly
 // with `text2d: unknown font …`. A function-form `fonts` is resolved against
@@ -102,7 +117,8 @@ const commands = {
     try {
       const part = await loadPart(partPath, usage);
       const params = flags.params ? JSON.parse(flags.params) : undefined;
-      const report = lintPart(part, { params });
+      const sources = readSources(partPath);
+      const report = lintPart(part, { params, sources });
       if (!flags.json) printLint(report);
       if (flags.out) {
         mkdirSync(dirname(resolve(flags.out)), { recursive: true });
@@ -131,7 +147,7 @@ const commands = {
       // milliseconds with a precise message rather than after a WASM boot and a
       // downstream error that doesn't name the cause. Warnings never gate measure.
       if (!flags["no-lint"]) {
-        const lint = lintPart(part);
+        const lint = lintPart(part, { sources: readSources(partPath) });
         if (!lint.ok) {
           if (flags.json) console.log(JSON.stringify({ ok: false, lint }, null, 2));
           else printLint(lint);
@@ -385,7 +401,11 @@ function printLint(r) {
   console.log("lint:");
   for (const f of all) {
     const icon = f.severity === "error" ? "✗" : f.severity === "warning" ? "⚠" : "·";
-    console.log(`  ${icon} ${f.rule}${f.path ? `  ${f.path}` : ""}`);
+    // A source-rule finding carries file+line — the only location a reader can
+    // open. Print it alongside the accessor path (which is `""` for a finding
+    // about a token anywhere in the file) rather than instead of it.
+    const at = f.file ? `  ${f.file}:${f.line ?? "?"}` : "";
+    console.log(`  ${icon} ${f.rule}${f.path ? `  ${f.path}` : ""}${at}`);
     console.log(`      ${f.message}`);
     console.log(`      hint: ${f.hint}${f.pattern ? ` (ERROR-PATTERNS.md#${f.pattern})` : ""}`);
   }

package/docs/AUTHORING-PARTS.md

@@ -609,7 +609,12 @@ parameters: [
 ```
 
 Every control `key` must exist in `defaults`, or the control is silently dead —
-`control-key-not-in-defaults` is an error for exactly that reason.
+`control-key-not-in-defaults` is an error for exactly that reason. Its value there must
+be a **number, string or boolean** — a control writes one scalar, so a control bound to
+an array, an object, `null` or `NaN` is dead in the same silent way
+(`control-default-not-primitive`), and a host that saves panel settings back into
+`defaults` cannot write that value either. A non-primitive `defaults` entry that no
+control is bound to is fine: `defaults` also seeds `p` for `build()`.
 
 **Ids.** A section, a group and a preset may carry an `id`; the renderer keys its
 element, state and disclosure maps on ids, so they must be unique across the whole
@@ -1873,6 +1878,16 @@ import { lintPart } from "partforge/lint";
 const { ok, errors, warnings } = lintPart(part, { params });
 ```
 
+`lintPart(part, { sources })` optionally takes the part's own source files
+(`{ files: { path: text }, entrypoint }` — `entrypoint` names the file holding the
+`PartDefinition`, defaulting to the first key) and unlocks a ninth rule group that
+reads the source itself, catching the defects evaluation erases. The CLI passes the
+module's own file automatically, so `partforge lint`/`measure` always run it; a
+programmatic caller that omits `sources` (or hands over a malformed one) just gets
+no findings from that group. Source findings carry `file` and `line` on top of the
+standard shape, and `SOURCE_RULE_IDS` names them — a host that gates rendering on
+lint errors uses it to keep them reported but non-blocking.
+
 `partforge/lint` has **zero runtime dependencies** and never imports a geometry
 kernel or the DOM viewer, so it runs unchanged in Node, a Web Worker, a sandboxed
 iframe, and Deno. A worker also answers `{ type: "lint", params }` with
@@ -1896,7 +1911,8 @@ about the definition as a whole use `""`.
 behave as authored — whether or not that shows up as a thrown exception. Some error
 findings do correspond to a runtime throw (`build-throws`, `verify-expect-throws`),
 but others catch **silent** wrongness: `missing-meta-title`, `part-view-unknown`,
-`control-key-not-in-defaults`, `preset-key-not-in-defaults`, and
+`control-key-not-in-defaults`, `control-default-not-primitive`,
+`preset-key-not-in-defaults`, and
 `verify-unknown-subpart` all fire on parts that build, measure, and verify cleanly —
 a dead control that's silently unreachable, a view that renders nothing, or a
 `verify` expectation that's silently dropped so its gate never runs. That's still an
@@ -1913,7 +1929,8 @@ previously didn't; that's the fix working as intended, not a regression.
 `default-view-ambiguous` (warnings).
 
 **Parameter schema** — `features-requires-sliders`, `features-requires-on`,
-`control-key-not-in-defaults`, `preset-key-not-in-defaults`, `mixed-section-shape`,
+`control-key-not-in-defaults`, `control-default-not-primitive`,
+`preset-key-not-in-defaults`, `mixed-section-shape`,
 `duplicate-preset-name`, `duplicate-node-id`, `select-options-missing`,
 `select-default-not-in-options`, `log-scale-needs-positive-min`,
 `when-key-not-in-defaults`, `when-unknown-operator`, `unknown-control-type` (errors);
@@ -2049,6 +2066,32 @@ control that the control's own `allow` list would refuse — at build time it's
 swapped for `defaults[key]`, i.e. itself, so the part boots with no usable
 font; use a source `allow` accepts, or widen `allow`) (warning).
 
+**Source rules** — the ninth group, which runs only when the caller hands over
+`sources` (above) — `control-default-not-literal` (a control's `defaults` entry is
+written as something other than a plain literal: an expression like `13 / 3`, an
+array or object, a template literal, a `0x10`/`1_000` spelling. Hosts persist a
+panel edit by rewriting that value's span in the source, so a spelling the
+rewriter cannot read means the user's edit is silently lost on reload — write a
+plain decimal/string/boolean literal, or move the computation into `derive()`)
+(error); `impure-source-token` (the source contains `Math.random`, `Date.now`,
+`performance.now`, or an argless `new Date()` — replace it with a parameter or a
+`derive()` output) (warning). Only a default a **visible** control is actually
+**bound** to is checked: an unbound non-primitive default (a lookup table, an
+array of hole positions) is never rewritten by a panel save and stays legal and
+unflagged, and so is the default of a statically hidden control (`hidden: true`
+on the control, or on an enclosing group or section) — it renders no widget, so
+there is no panel edit to lose, and `hidden: true` is the documented idiom for an
+internal constant. A `when`-conditioned control is *not* hidden — it can appear,
+so its default is checked.
+`impure-source-token` is warning-tier because the behavioral
+`nondeterministic-build` probe stays the error authority on impurity — the source
+scan is the wider net that also catches an impure value stable within one probe
+pass. It scans `.js`/`.mjs` files only (prose in a `README.md` is not a build),
+and code only within them (comments and string/template *interiors* are blanked
+first), so an impurity token inside a `${…}` interpolation is not seen. It emits
+one finding per (file, token) pair, carrying the occurrence count and the first
+occurrence's line, rather than one per occurrence.
+
 A rule that itself throws yields an `internal-rule-error` **warning** and the run
 continues: `lintPart` never throws and never blocks a part because of a linter bug.
 

package/docs/ERROR-PATTERNS.md

@@ -601,6 +601,18 @@ between the Manifold preview and the OCCT STEP export.
 
   The same channel carries every other degrade in a build: an `extrude` rim bevel reduced or skipped (`extrude bevel <b> …`), a `roundedBox` rim radius clamped to `round.side`, and the `Shape2D` corner-op clamps in the two entries above. A build result's `warnings` is the complete list of what the part asked for and did not get.
 
+## control-default-not-literal
+
+- **Symptom:** A control works live — the slider moves, the geometry updates — but the user's panel edits are gone when the part is reopened. Nothing throws anywhere.
+- **Cause:** The control's `defaults` entry is written as something other than a plain literal — an expression (`13 / 3`), an array or object, a template literal, a hex/`1_000` spelling. Hosts persist a panel edit by rewriting that value's span in the source, so a value the rewriter cannot read is skipped and the edit is silently lost. The evaluated-object lint cannot see this (`13 / 3` evaluates to an ordinary number); only the source says.
+- **Fix:** Write the computed value as a plain decimal/string/boolean literal, or move the computation into `derive()`. `lintPart(part, { sources })` and the CLI report this as the error `control-default-not-literal` with file and line. Only a **visible** control's default is checked — a statically hidden one (`hidden: true` on the control, group or section) renders no widget, so there is no panel edit to lose, and an expression there is legitimate. See [AUTHORING-PARTS.md](AUTHORING-PARTS.md) § "Linting" (Rule catalog → Source rules).
+
+## impure-source-token
+
+- **Symptom:** The preview shows stale geometry after a parameter edit, or a part behaves differently across rebuilds with identical params — often intermittent.
+- **Cause:** The source contains `Math.random`, `Date.now`, `performance.now`, or an argless `new Date()`. A build must be a pure function of `(k, p, d)`; the memoizing kernel hashes inputs, so an impure value silently serves stale geometry (see impure-build-stale-preview, above). The behavioral lint probe catches impurity only when it changes the recorded call sequence between two probe runs; a value stable within one pass escapes it, which is why the source scan warns on the token itself.
+- **Fix:** Replace the impure value with a parameter or a `derive()` output. `new Date(0)` and other argument-carrying forms are deterministic and not flagged; only `.js`/`.mjs` files are scanned, so the same words in a `README.md` are prose. One finding is emitted per (file, token) pair, carrying the occurrence count and the first occurrence's line. See [AUTHORING-PARTS.md](AUTHORING-PARTS.md) § "Caching & determinism".
+
 # Hardware library
 
 Reserved for `hardware-*` patterns (issue #30). No entries yet.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.75.0",
+  "version": "0.77.0",
   "description": "Turn a declarative part definition into a parametric-CAD web app (three.js + Manifold/Replicad). Requires a Vite-based consumer.",
   "type": "module",
   "license": "MIT",

package/src/framework/lint/index.js

@@ -17,8 +17,32 @@ import { ANIMATION_RULES } from "./rules-animations.js";
 import { PLACE_RULES } from "./rules-place.js";
 import { IMPORT_RULES } from "./rules-imports.js";
 import { FONT_RULES } from "./rules-fonts.js";
+import { SOURCE_RULES } from "./rules-source.js";
 
-export const RULES = [...SHAPE_RULES, ...SCHEMA_RULES, ...BUILD_RULES, ...VERIFY_RULES, ...ANIMATION_RULES, ...PLACE_RULES, ...IMPORT_RULES, ...FONT_RULES];
+export const RULES = [...SHAPE_RULES, ...SCHEMA_RULES, ...BUILD_RULES, ...VERIFY_RULES, ...ANIMATION_RULES, ...PLACE_RULES, ...IMPORT_RULES, ...FONT_RULES, ...SOURCE_RULES];
+
+// A usable sources input, or null. Deliberately forgiving: lintPart's callers
+// include hosted paths handing over user/LLM-authored trees, so a malformed
+// shape means "no source rules", never a throw. Non-string file values are
+// dropped per entry rather than voiding the whole map.
+function normalizeSources(sources) {
+  if (!sources || typeof sources !== "object") return null;
+  const rawFiles = sources.files;
+  if (!rawFiles || typeof rawFiles !== "object") return null;
+  // Null-prototype so a file literally keyed `__proto__` is KEPT as an own
+  // property: `{}["__proto__"] = text` would set the prototype instead, quietly
+  // dropping that file from the scan while still counting toward `any`.
+  const files = Object.create(null);
+  let any = false;
+  for (const [path, text] of Object.entries(rawFiles)) {
+    if (typeof text !== "string") continue;
+    files[path] = text;
+    any = true;
+  }
+  if (!any) return null;
+  const entrypoint = typeof sources.entrypoint === "string" ? sources.entrypoint : Object.keys(files)[0];
+  return { files, entrypoint };
+}
 
 // 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
@@ -74,7 +98,9 @@ export function lintContext(part, params) {
 /**
  * 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
+ * @param {{params?: object, sources?: {files?: Record<string, string>, entrypoint?: string}}} [opts]
+ *   `params` are layered over part.defaults for the probe pass; `sources` is the part's own
+ *   source text, which unlocks the source rules (Group 9) — omit it and lint behaves as before.
  * @returns {{ok: boolean, errors: object[], warnings: object[], notes: object[]}}
  */
 export function lintPart(part, opts) {
@@ -82,7 +108,7 @@ export function lintPart(part, opts) {
   // 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 ?? {};
+  const { params, sources } = 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
@@ -102,6 +128,14 @@ export function lintPart(part, opts) {
       notes: [],
     };
   }
+  // Deliberately its OWN guard, outside the lintContext try above: a malformed
+  // `sources` input means "no source rules", never a broken part. `sources` is
+  // caller-supplied data (a throwing `files`/`entrypoint` getter, a Proxy whose
+  // `ownKeys` trap throws), and folding it into the block above would turn that
+  // into a `lint-context-error` — an id that is NOT in SOURCE_RULE_IDS, so a
+  // host filtering source findings out to keep them non-blocking would instead
+  // refuse to render a part that builds fine.
+  try { ctx.sources = normalizeSources(sources); } catch { ctx.sources = null; }
   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

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

@@ -21,28 +21,34 @@ const isPlainObject = (x) => x !== null && typeof x === "object" && !Array.isArr
 // 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.
+// Each record also carries `inHidden`: whether a STATICALLY hidden container
+// (a section, group or feature written `hidden: true`) encloses the descriptor.
+// It is read only by controlBoundKeys({ excludeHidden }); every other rule
+// ignores it, so their populations are unchanged. `when` is deliberately not
+// hiddenness — a `when`-conditioned node can still appear.
 function collectDescriptors(part) {
   const out = [];
   sections(part).forEach((sec, si) => {
+    const secHidden = sec?.hidden === true;
     // The authored shape: children in `controls`, recursively. Field lists are
     // the authored ones (authorFieldsFor) — the legacy lists stay untouched so
     // `when` on a legacy descriptor still warns. A section routes to one shape
     // or the other (desugar's winner-takes-all), so `return` before the legacy
     // loops below rather than falling through to them.
-    function walkAuthored(list, base) {
+    function walkAuthored(list, base, inHidden) {
       arr(list).forEach((entry, i) => {
         if (!entry) return;
         const path = `${base}[${i}]`;
         if (entry.type === "group") {
-          out.push({ d: entry, path, fields: GROUP_FIELDS, container: true, authored: true });
-          walkAuthored(entry.controls, `${path}.controls`);
+          out.push({ d: entry, path, fields: GROUP_FIELDS, container: true, authored: true, inHidden });
+          walkAuthored(entry.controls, `${path}.controls`, inHidden || entry.hidden === true);
         } else if (entry.type === "preset") {
-          out.push({ d: entry, path, fields: PRESET_FIELDS, container: true, authored: true });
+          out.push({ d: entry, path, fields: PRESET_FIELDS, container: true, authored: true, inHidden });
         } else {
           // A typo'd type (e.g. "grup") fails both branches above and lands
           // here — authorFieldsFor falls back to AUTHOR_COMMON, and
           // unknown-control-type (below) is what actually diagnoses it.
-          out.push({ d: entry, path, fields: authorFieldsFor(entry.type ?? "slider"), authored: true });
+          out.push({ d: entry, path, fields: authorFieldsFor(entry.type ?? "slider"), authored: true, inHidden });
         }
       });
     }
@@ -52,27 +58,27 @@ function collectDescriptors(part) {
       // that case (a deliberate scope choice), and pushing every section
       // unconditionally would produce findings with nothing to say. `when`-only
       // rules just need it present when relevant.
-      if (sec?.when !== undefined) out.push({ d: sec, path: `parameters[${si}]`, fields: SECTION_FIELDS, container: true });
-      walkAuthored(sec.controls, `parameters[${si}].controls`);
+      if (sec?.when !== undefined) out.push({ d: sec, path: `parameters[${si}]`, fields: SECTION_FIELDS, container: true, inHidden: secHidden });
+      walkAuthored(sec.controls, `parameters[${si}].controls`, secHidden);
       return;
     }
 
     arr(sec?.advanced).forEach((d, i) => {
-      if (d) out.push({ d, path: `parameters[${si}].advanced[${i}]`, fields: fieldsFor("slider") });
+      if (d) out.push({ d, path: `parameters[${si}].advanced[${i}]`, fields: fieldsFor("slider"), inHidden: secHidden });
     });
     arr(sec?.features).forEach((f, i) => {
       if (!f) return;
-      out.push({ d: f, path: `parameters[${si}].features[${i}]`, fields: FEATURE_FIELDS });
+      out.push({ d: f, path: `parameters[${si}].features[${i}]`, fields: FEATURE_FIELDS, inHidden: secHidden });
       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: fieldsFor("slider"), featureKey: f.key });
+        if (s) out.push({ d: s, path: `parameters[${si}].features[${i}].sliders[${j}]`, fields: fieldsFor("slider"), featureKey: f.key, inHidden: secHidden || f.hidden === true });
       });
     });
     arr(sec?.toggles).forEach((t, i) => {
-      if (t) out.push({ d: t, path: `parameters[${si}].toggles[${i}]`, fields: fieldsFor("checkbox") });
+      if (t) out.push({ d: t, path: `parameters[${si}].toggles[${i}]`, fields: fieldsFor("checkbox"), inHidden: secHidden });
     });
   });
   return out;
@@ -104,6 +110,44 @@ function collectPresetBundles(part) {
 
 const defaultKeys = (part) => new Set(Object.keys(part?.defaults ?? {}));
 
+// The keys a real control is bound to — the population whose defaults must be
+// panel-writable. Shared with rules-source.js's control-default-not-literal,
+// which needs the SAME key set control-default-not-primitive uses (unbound
+// non-primitive defaults are legal: they seed `p` for build()).
+//
+// `excludeHidden` drops descriptors a STATICALLY hidden container encloses, and
+// those written `hidden: true` themselves. Only the source rule wants it: a
+// hidden control renders no widget, so no panel edit of it can ever be lost,
+// and `hidden: true` is the documented idiom for an internal constant — exactly
+// where an author legitimately writes an expression. `control-default-not-primitive`
+// leaves it off, because a hidden control's key still seeds `p` and so still
+// has to be a scalar.
+export function controlBoundKeys(part, { excludeHidden = false } = {}) {
+  return new Set(
+    collectDescriptors(part)
+      .filter(({ container }) => !container)
+      .filter(({ d, inHidden }) => !excludeHidden || !(inHidden === true || d.hidden === true))
+      .map(({ d }) => d.key)
+      .filter((k) => typeof k === "string"),
+  );
+}
+
+// What a control can actually edit: one finite scalar. Non-finite numbers are out
+// with the rest — a slider cannot show NaN, and neither NaN nor Infinity survives
+// a round trip through JSON or a source rewrite.
+const isEditableValue = (v) =>
+  typeof v === "string" || typeof v === "boolean" || (typeof v === "number" && Number.isFinite(v));
+
+// Name a value for a finding's message: the reader needs to know WHICH default is
+// wrong and what it is, and `typeof []` ("object") tells them neither.
+const describeValue = (v) => {
+  if (Array.isArray(v)) return "an array";
+  if (v === null) return "a null";
+  if (typeof v === "number") return `a ${Number.isNaN(v) ? "NaN" : String(v)}`;
+  if (v === undefined) return "an undefined";
+  return `a ${typeof v}`;
+};
+
 // Walk one WhenCondition, calling onKey(key) for every param key it reads and
 // onOp(op) for every operator name it uses. allOf/anyOf/not recurse; a bare
 // `{ key: value }` entry counts as reading `key` with no operator to check.
@@ -191,6 +235,32 @@ export const SCHEMA_RULES = [
           `${path}.key`));
     },
   },
+  {
+    // A control edits ONE value, and the widgets read and write it as a scalar:
+    // a slider over an array renders NaN, a checkbox over an object writes
+    // `true` over it. It is dead in the same silent way control-key-not-in-defaults
+    // is — the part builds, the panel renders, the control does nothing usable —
+    // which is why this is an error rather than a warning.
+    //
+    // Only a key a CONTROL is bound to. `defaults` also seeds `p` for build(), so
+    // parking a table or a point list there for the build to read is legitimate
+    // authoring and none of lint's business.
+    id: "control-default-not-primitive",
+    run: ({ part }) => {
+      // Same guard as control-key-not-in-defaults: bail only when `defaults`
+      // isn't a plain object at all (missing-defaults already reports that).
+      if (!isPlainObject(part?.defaults)) return [];
+      const defaults = part.defaults;
+      return collectDescriptors(part)
+        .filter(({ container }) => !container)
+        .filter(({ d }) => typeof d.key === "string" && Object.hasOwn(defaults, d.key))
+        .filter(({ d }) => !isEditableValue(defaults[d.key]))
+        .map(({ d, path }) => err("control-default-not-primitive",
+          `control "${d.key}" is bound to ${describeValue(defaults[d.key])} default`,
+          `Give "${d.key}" a number, string or boolean default — a control writes one scalar, so it cannot edit this, and a host that saves panel settings back into \`defaults\` cannot write it either.`,
+          `${path}.key`));
+    },
+  },
   {
     id: "preset-key-not-in-defaults",
     run: ({ part }) => {

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

@@ -0,0 +1,108 @@
+// Group 9 — source-text rules. These run only when the caller hands lintPart
+// the part's SOURCE alongside the evaluated definition, because they exist
+// precisely for the defects evaluation erases: `13 / 3` evaluates to a plain
+// number, so the evaluated-object rules cannot see it, yet a host that
+// persists panel settings by rewriting the defaults literal cannot write that
+// value back — the control moves, the build is green, and the user's edit is
+// silently gone on reload. Findings here carry `file` and `line` on top of
+// the standard shape.
+import { err, warn } from "./finding.js";
+import { controlBoundKeys } from "./rules-schema.js";
+import { pickDefaultsFile, stripNonCode, lineOf } from "./source-scan.js";
+
+const MAX_SOURCE_CHARS = 48;
+// The quoted source is LLM- or user-authored text on its way into a JSON
+// diagnostics channel, so control characters come out along with the whitespace
+// collapse — a raw C0 byte in a finding message is an escaping hazard for every
+// consumer downstream, and it renders as nothing useful anyway.
+const describeSource = (raw) => {
+  const flat = String(raw ?? "").replace(/\s+/g, " ").replace(/[\u0000-\u001f\u007f]/g, "").trim();
+  return flat.length > MAX_SOURCE_CHARS ? `${flat.slice(0, MAX_SOURCE_CHARS - 1)}…` : flat;
+};
+
+// Impurity tokens a source scan can see that the behavioral probe (which runs
+// build() twice and diffs the recorded calls) can miss when the impure value
+// is stable within one probe pass. `new Date()` matches only the ARGLESS
+// form: `new Date(0)` is deterministic and legal.
+//
+// Scope limit (documented in AUTHORING-PARTS.md → Rule catalog → Source rules):
+// stripNonCode blanks whole template interiors, so a token inside a `${…}`
+// interpolation is not seen by this rule.
+const IMPURE_TOKENS = [
+  { re: /\bMath\s*\.\s*random\b/g, token: "Math.random" },
+  { re: /\bDate\s*\.\s*now\b/g, token: "Date.now" },
+  { re: /\bperformance\s*\.\s*now\b/g, token: "performance.now" },
+  { re: /\bnew\s+Date\s*\(\s*\)/g, token: "new Date()" },
+];
+
+export const SOURCE_RULES = [
+  {
+    id: "control-default-not-literal",
+    run: ({ part, sources }) => {
+      if (!sources) return [];
+      const picked = pickDefaultsFile(sources.files, sources.entrypoint);
+      if (!picked) return [];
+      // `excludeHidden` because a STATICALLY hidden control renders no widget,
+      // so a panel save can never lose an edit to it — and `hidden: true` is
+      // the documented idiom for an internal constant, exactly the place an
+      // author legitimately writes an expression. A `when`-conditioned control
+      // stays in: it can appear, so its default must be writable.
+      const bound = controlBoundKeys(part, { excludeHidden: true });
+      return picked.entries
+        .filter((e) => e.key !== null && bound.has(e.key) && !e.readable)
+        .map((e) => ({
+          ...err("control-default-not-literal",
+            `control "${e.key}" has a default written as \`${describeSource(e.raw)}\`, which a panel-settings save cannot write back`,
+            `Write the computed value as a plain decimal number, quoted string or boolean literal (e.g. \`4.333\` instead of \`13 / 3\`), or move the computation into \`derive()\`. Hosts persist panel edits by rewriting this value in the source, so a spelling the rewriter cannot read silently loses the user's changes when the part is reopened.`,
+            `defaults.${e.key}`,
+            "control-default-not-literal"),
+          file: picked.path,
+          line: lineOf(picked.source, e.index),
+        }));
+    },
+  },
+  {
+    id: "impure-source-token",
+    run: ({ sources }) => {
+      if (!sources?.files) return [];
+      const out = [];
+      for (const [path, source] of Object.entries(sources.files)) {
+        if (typeof source !== "string") continue;
+        // Code files only. A part tree can carry prose and data (a README, a
+        // profile JSON), and `Date.now()` written in a sentence is not an
+        // impure build — the scanner's comment/string blanking has no purchase
+        // on a file that is not JS at all.
+        if (!/\.m?js$/.test(path)) continue;
+        const code = stripNonCode(source);
+        for (const { re, token } of IMPURE_TOKENS) {
+          // ONE finding per (file, token), carrying the occurrence count and
+          // the first occurrence's line. Per-occurrence findings are unbounded:
+          // a part looping `Math.random()` a few thousand times produced ~1.4 MB
+          // of identical findings on a channel an LLM reads. The count is the
+          // information; the rest was repetition.
+          re.lastIndex = 0;
+          let count = 0;
+          let firstIndex = 0;
+          for (let m; (m = re.exec(code)); ) {
+            if (count === 0) firstIndex = m.index;
+            count++;
+          }
+          if (count === 0) continue;
+          out.push({
+            ...warn("impure-source-token",
+              `\`${token}\`${count > 1 ? ` ×${count}` : ""} in ${path} — an impure build silently returns stale geometry`,
+              "A build must be a pure function of (k, p, d): the preview kernel memoizes geometry by content hash, so a value that changes between calls silently serves stale geometry instead of rebuilding. Replace the impure value with a parameter or a derive() output.",
+              "",
+              "impure-source-token"),
+            file: path,
+            line: lineOf(code, firstIndex),
+          });
+        }
+      }
+      // Deterministic order for stable reports: by file, then line.
+      return out.sort((a, b) => (a.file === b.file ? a.line - b.line : a.file < b.file ? -1 : 1));
+    },
+  },
+];
+
+export const SOURCE_RULE_IDS = new Set(SOURCE_RULES.map((r) => r.id));

package/src/framework/lint/source-scan.js

@@ -0,0 +1,333 @@
+// Source-text scanning for partforge/lint's SOURCE_RULES. The scanner is a
+// verbatim port of the READ half of partforge-cloud's
+// src/parts/partDefaults.js — the module that persists panel settings by
+// rewriting the defaults literal. THE READABILITY PREDICATE MUST MATCH THAT
+// REWRITER EXACTLY: a value this scanner passes but the rewriter refuses is a
+// silent regression of the incident the control-default-not-literal rule
+// exists to prevent (a `13 / 3` default that builds green and loses the
+// user's panel edits). partforge-cloud carries a parity test against a shared
+// fixture corpus; change the predicate only in both places together.
+//
+// Zero dependencies, no AST: this file must stay inside lint's pure import
+// closure (test/lint-purity.test.js) so lintPart keeps running in Node, the
+// browser sandbox iframe, and Deno.
+//
+// KNOWN BLIND SPOT — regex literals are not tokenized: a `/[/*]/` or `/x\/y/`
+// reads as a comment opener and can blank the rest of the file, and a regex
+// containing a quote can likewise derail string skipping.
+// It is parity-correct (the cloud rewriter has the same gap) and fails toward
+// FALSE NEGATIVES — a derailed scan finds no defaults literal and no tokens,
+// so a rule says nothing rather than something wrong.
+
+// Span of the object literal after the first `defaults:` key (indices into
+// `source`, end exclusive, covering `{...}`). String- and comment-aware so a
+// "defaults: {" inside a string or comment can't fool the scan.
+export function findDefaultsLiteral(source) {
+  if (typeof source !== "string") return null;
+  let i = 0;
+  while (i < source.length) {
+    const c = source[i];
+    if (c === '"' || c === "'" || c === "`") {
+      const quote = c;
+      i++;
+      while (i < source.length && source[i] !== quote) i += source[i] === "\\" ? 2 : 1;
+      i++;
+      continue;
+    }
+    if (c === "/" && source[i + 1] === "/") { while (i < source.length && source[i] !== "\n") i++; continue; }
+    if (c === "/" && source[i + 1] === "*") { const j = source.indexOf("*/", i + 2); if (j === -1) return null; i = j + 2; continue; }
+    const m = /^defaults\s*:\s*\{/.exec(source.slice(i));
+    if (m && (i === 0 || /[\s{,]/.test(source[i - 1]))) {
+      const start = i + m[0].length - 1; // the "{"
+      let depth = 0;
+      let k = start;
+      while (k < source.length) {
+        const ch = source[k];
+        if (ch === '"' || ch === "'" || ch === "`") {
+          const quote = ch;
+          k++;
+          while (k < source.length && source[k] !== quote) k += source[k] === "\\" ? 2 : 1;
+          k++;
+          continue;
+        }
+        if (ch === "/" && source[k + 1] === "/") { while (k < source.length && source[k] !== "\n") k++; continue; }
+        if (ch === "/" && source[k + 1] === "*") { const j = source.indexOf("*/", k + 2); if (j === -1) return null; k = j + 2; continue; }
+        if (ch === "{") depth++;
+        else if (ch === "}") { depth--; if (depth === 0) return { start, end: k + 1 }; }
+        k++;
+      }
+      return null;
+    }
+    i++;
+  }
+  return null;
+}
+
+// --- entry scanning -------------------------------------------------------
+//
+// Every helper here takes an explicit `end` bound and reports an index back,
+// so a run it cannot terminate (an unclosed string, a runaway comment) stops
+// at the bound instead of walking off the literal.
+
+// Whitespace and comments from `i`.
+function skipTrivia(text, i, end) {
+  for (;;) {
+    while (i < end && /\s/.test(text[i])) i++;
+    if (text[i] === "/" && text[i + 1] === "/") { while (i < end && text[i] !== "\n") i++; continue; }
+    if (text[i] === "/" && text[i + 1] === "*") {
+      const j = text.indexOf("*/", i + 2);
+      if (j === -1 || j >= end) return end;
+      i = j + 2;
+      continue;
+    }
+    return i;
+  }
+}
+
+// Index just past a '…' / "…" run starting at its own quote.
+function skipQuoted(text, i, end) {
+  const quote = text[i];
+  i++;
+  while (i < end && text[i] !== quote) i += text[i] === "\\" ? 2 : 1;
+  return Math.min(i + 1, end);
+}
+
+// Index just past a `…` run, stepping over ${…} interpolations so a comma or
+// brace inside one cannot end the value early.
+function skipTemplate(text, i, end) {
+  i++;
+  while (i < end) {
+    const c = text[i];
+    if (c === "\\") { i += 2; continue; }
+    if (c === "`") return i + 1;
+    if (c === "$" && text[i + 1] === "{") { i = skipInterpolation(text, i + 2, end); continue; }
+    i++;
+  }
+  return end;
+}
+
+function skipInterpolation(text, i, end) {
+  let depth = 1;
+  while (i < end) {
+    const c = text[i];
+    if (c === '"' || c === "'") { i = skipQuoted(text, i, end); continue; }
+    if (c === "`") { i = skipTemplate(text, i, end); continue; }
+    if (c === "{") depth++;
+    else if (c === "}" && --depth === 0) return i + 1;
+    i++;
+  }
+  return end;
+}
+
+// The end of one value: the next top-level `,` or the literal's own `}`.
+// Bracket-, string- and comment-aware, so an expression, an array or a nested
+// object is spanned WHOLE even though it will not be read.
+function scanValueEnd(text, i, end) {
+  let depth = 0;
+  while (i < end) {
+    const c = text[i];
+    if (c === '"' || c === "'") { i = skipQuoted(text, i, end); continue; }
+    if (c === "`") { i = skipTemplate(text, i, end); continue; }
+    if (c === "/" && (text[i + 1] === "/" || text[i + 1] === "*")) { i = skipTrivia(text, i, end); continue; }
+    if (c === "(" || c === "[" || c === "{") { depth++; i++; continue; }
+    if (c === ")" || c === "]" || c === "}") { if (depth === 0) return i; depth--; i++; continue; }
+    if (c === "," && depth === 0) return i;
+    i++;
+  }
+  return end;
+}
+
+// JS's own single-character escapes. An escape outside this set is the
+// character itself (`\a` is "a"), which is JS's rule rather than a guess;
+// the sequences that are NOT decodable that way — legacy octal, a malformed
+// \x/\u — return null and leave the key un-editable.
+const SIMPLE_ESCAPES = { n: "\n", t: "\t", r: "\r", b: "\b", f: "\f", v: "\v", 0: "\0" };
+
+// A quoted literal (quotes included) → its string value, or null when it is
+// not exactly one complete string.
+function decodeStringLiteral(raw) {
+  const quote = raw[0];
+  if ((quote !== '"' && quote !== "'") || raw.length < 2 || raw[raw.length - 1] !== quote) return null;
+  let out = "";
+  for (let i = 1; i < raw.length - 1; i++) {
+    const c = raw[i];
+    if (c === quote) return null;                // closed early: this is not one string
+    if (c === "\n" || c === "\r") return null;    // an unescaped newline is a syntax error
+    if (c !== "\\") { out += c; continue; }
+    const e = raw[++i];
+    if (e === undefined) return null;
+    if (e === "\n" || e === "\u2028" || e === "\u2029") continue;          // line continuation
+    if (e === "\r") { if (raw[i + 1] === "\n") i++; continue; }
+    if (e === "x") {
+      const h = raw.slice(i + 1, i + 3);
+      if (!/^[0-9a-fA-F]{2}$/.test(h)) return null;
+      out += String.fromCharCode(Number.parseInt(h, 16));
+      i += 2;
+      continue;
+    }
+    if (e === "u") {
+      if (raw[i + 1] === "{") {
+        const close = raw.indexOf("}", i + 2);
+        const h = close === -1 ? "" : raw.slice(i + 2, close);
+        if (!/^[0-9a-fA-F]{1,6}$/.test(h) || Number.parseInt(h, 16) > 0x10ffff) return null;
+        out += String.fromCodePoint(Number.parseInt(h, 16));
+        i = close;
+        continue;
+      }
+      const h = raw.slice(i + 1, i + 5);
+      if (!/^[0-9a-fA-F]{4}$/.test(h)) return null;
+      out += String.fromCharCode(Number.parseInt(h, 16));
+      i += 4;
+      continue;
+    }
+    if (/[1-9]/.test(e) || (e === "0" && /\d/.test(raw[i + 1] ?? ""))) return null; // legacy octal
+    out += Object.hasOwn(SIMPLE_ESCAPES, e) ? SIMPLE_ESCAPES[e] : e;
+  }
+  return out;
+}
+
+// Numeric literals JS accepts and this module can round-trip. Deliberately not
+// hex, separators or bigint: those stay un-editable rather than being rewritten
+// into a different spelling of themselves.
+const NUMBER_RE = /^-?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?$/;
+
+// One value's source text → { value }, or null when it is not a primitive
+// literal this module can read AND write back.
+function readValue(raw) {
+  if (raw === "true") return { value: true };
+  if (raw === "false") return { value: false };
+  if (NUMBER_RE.test(raw)) {
+    const n = Number(raw);
+    return Number.isFinite(n) ? { value: n } : null;
+  }
+  const q = raw[0];
+  if (q === '"' || q === "'") {
+    const s = decodeStringLiteral(raw);
+    return s === null ? null : { value: s };
+  }
+  return null;
+}
+
+// A key at `i`: identifier or quoted string. → { key, next } or null.
+function readKey(text, i, end) {
+  const q = text[i];
+  if (q === '"' || q === "'") {
+    const next = skipQuoted(text, i, end);
+    const key = decodeStringLiteral(text.slice(i, next));
+    return key === null ? null : { key, next };
+  }
+  const m = /^[A-Za-z_$][\w$]*/.exec(text.slice(i, end));
+  return m ? { key: m[0], next: i + m[0].length } : null;
+}
+
+// Split `{ … }` into entries in source order. `readable` says whether the
+// value was interpreted; `raw` is its exact source text either way, and
+// valueStart/valueEnd are its span (indices into `text`), which is what a
+// rewrite splices. An entry that is not a `key: value` pair at all — a spread,
+// a computed key, a method — is spanned and kept as an unreadable, unnamed
+// entry so the rest of the literal still reads.
+//
+// Null ONLY when `text` is not a braced object; an object whose every entry is
+// unreadable is a valid scan of zero readable keys.
+function scanEntries(text) {
+  const open = skipTrivia(text, 0, text.length);
+  if (text[open] !== "{") return null;
+  let close = text.length;
+  while (close > open && /\s/.test(text[close - 1])) close--;
+  if (text[close - 1] !== "}") return null;
+  const end = close - 1; // the closing brace
+  const entries = [];
+  let i = open + 1;
+  for (;;) {
+    i = skipTrivia(text, i, end);
+    if (i >= end) return entries;
+    const start = i;
+    const k = readKey(text, i, end);
+    let entry = null;
+    if (k) {
+      const afterKey = skipTrivia(text, k.next, end);
+      if (text[afterKey] === ":") {
+        const valueStart = skipTrivia(text, afterKey + 1, end);
+        let valueEnd = scanValueEnd(text, valueStart, end);
+        while (valueEnd > valueStart && /\s/.test(text[valueEnd - 1])) valueEnd--;
+        const raw = text.slice(valueStart, valueEnd);
+        const read = readValue(raw);
+        entry = { key: k.key, valueStart, valueEnd, raw, readable: !!read, value: read?.value };
+        i = valueEnd;
+      }
+    }
+    if (!entry) {
+      const stop = scanValueEnd(text, start, end);
+      entry = { key: null, valueStart: start, valueEnd: stop, raw: text.slice(start, stop), readable: false };
+      i = stop;
+    }
+    entries.push(entry);
+    i = skipTrivia(text, i, end);
+    if (text[i] !== ",") return entries; // no separator: nothing further can be read
+    i++;
+  }
+}
+
+// The literal's entries with ABSOLUTE value offsets into `source`, so a rule
+// can report file + line. Null when there is no defaults literal (or it is
+// unscannable) — a rule treats that as "nothing to say", never an error.
+export function defaultsEntriesIn(source) {
+  if (typeof source !== "string") return null;
+  const span = findDefaultsLiteral(source);
+  if (!span) return null;
+  const entries = scanEntries(source.slice(span.start, span.end));
+  if (!entries) return null;
+  return entries.map((e) => ({
+    key: e.key, raw: e.raw, readable: e.readable, index: span.start + e.valueStart,
+  }));
+}
+
+// Which file the settings session would write — same preference order as the
+// cloud rewriter's findDefaultsFile/readDefaultsEntries: entrypoint first, then
+// any file whose literal has a readable entry. The third tier — falling back
+// to the first literal found anywhere, even wholly unreadable — is a
+// DELIBERATE divergence from cloud's findDefaultsFile, which returns null
+// there: a lint rule still needs to name the right file for a part whose only
+// defaults literal has no readable entry at all.
+export function pickDefaultsFile(files, entrypoint) {
+  if (!files || typeof files !== "object") return null;
+  const paths = [entrypoint, ...Object.keys(files).filter((p) => p !== entrypoint)]
+    .filter((p) => typeof p === "string" && typeof files[p] === "string");
+  let firstFound = null;
+  for (const path of paths) {
+    const entries = defaultsEntriesIn(files[path]);
+    if (!entries) continue;
+    const found = { path, source: files[path], entries };
+    if (entries.some((e) => e.readable)) return found;
+    firstFound ??= found;
+  }
+  return firstFound;
+}
+
+// `source` with every string, template and comment interior blanked to
+// spaces — same length, newlines preserved — so a token scan over the result
+// can never match inside a string or comment and lineOf stays accurate.
+export function stripNonCode(source) {
+  if (typeof source !== "string") return "";
+  const out = source.split("");
+  const blank = (from, to) => {
+    for (let i = from; i < to && i < out.length; i++) if (out[i] !== "\n") out[i] = " ";
+  };
+  let i = 0;
+  while (i < source.length) {
+    const c = source[i];
+    if (c === '"' || c === "'") { const end = skipQuoted(source, i, source.length); blank(i + 1, end - 1); i = end; continue; }
+    if (c === "`") { const end = skipTemplate(source, i, source.length); blank(i + 1, end - 1); i = end; continue; }
+    if (c === "/" && source[i + 1] === "/") { let j = i + 2; while (j < source.length && source[j] !== "\n") j++; blank(i, j); i = j; continue; }
+    if (c === "/" && source[i + 1] === "*") { const j = source.indexOf("*/", i + 2); const end = j === -1 ? source.length : j + 2; blank(i, end); i = end; continue; }
+    i++;
+  }
+  return out.join("");
+}
+
+export function lineOf(text, index) {
+  if (typeof text !== "string") return 1;
+  let n = 1;
+  for (let i = 0; i < index && i < text.length; i++) if (text[i] === "\n") n++;
+  return n;
+}

package/src/lint.js

@@ -1,3 +1,8 @@
 // Public entry for `partforge/lint`. Deliberately separate from `partforge/testing`,
 // whose entry pulls in the WASM kernels and cannot load in a browser sandbox.
 export { lintPart, RULES } from "./framework/lint/index.js";
+// The ids of the rules that read SOURCE rather than the evaluated part. Hosts
+// that gate rendering on lint errors (partforge-cloud's sandbox loader) use
+// this to keep source findings REPORTED but non-blocking: a persistence
+// defect must not stop a legacy part from rendering.
+export { SOURCE_RULE_IDS } from "./framework/lint/rules-source.js";

package/types/lint.d.ts

@@ -29,6 +29,16 @@ export interface Finding {
    * `""` for findings about the definition as a whole. For navigation only.
    */
   path: string;
+  /**
+   * Present on source-rule findings: the tree path of the file the finding was
+   * read from, as keyed in `sources.files`.
+   */
+  file?: string;
+  /**
+   * Present on source-rule findings: the 1-indexed line of the offending source
+   * within `file`.
+   */
+  line?: number;
   /** A stable ERROR-PATTERNS.md entry id, when one applies. */
   pattern?: string;
 }
@@ -42,15 +52,32 @@ export interface LintReport {
   notes: Finding[];
 }
 
+/**
+ * The part's own source text, keyed by tree path — `entrypoint` names the file
+ * holding the `PartDefinition` (the first key when omitted). Handing this over
+ * unlocks the source rules, which read the text the evaluated definition has
+ * already erased.
+ */
+export interface LintSources {
+  files: Record<string, string>;
+  entrypoint?: string;
+}
+
 /**
  * Lint a PartDefinition. NEVER throws — a rule that throws yields an
  * `internal-rule-error` warning and the run continues.
  *
  * @param part - the default-exported PartDefinition (deliberately `unknown`:
  *   lint's whole job is to be handed something that may not be one).
- * @param opts - `params` are layered over `part.defaults` for the probe pass.
+ * @param opts - `params` are layered over `part.defaults` for the probe pass;
+ *   `sources` is the part's own source text. Omitting `sources` (or handing
+ *   over a malformed one) makes the source rules a silent no-op — they are
+ *   never a reason for lint to fail.
  */
-export function lintPart(part: unknown, opts?: { params?: ResolvedParams } | null): LintReport;
+export function lintPart(
+  part: unknown,
+  opts?: { params?: ResolvedParams; sources?: LintSources } | null,
+): LintReport;
 
 /** The shared context a rule reads. */
 export interface LintContext {
@@ -69,6 +96,13 @@ export interface LintContext {
   probeAgain(): unknown;
   /** `verify.expect` resolved once per lint pass. */
   resolveExpectOnce(): unknown;
+  /**
+   * The normalized `opts.sources`, or `null` when none was handed over (or none
+   * survived normalization). The source rules return no findings when it is
+   * `null`. Optional: `lintContext` builds the context without it, and the
+   * field is assigned separately by `lintPart`.
+   */
+  sources?: LintSources | null;
 }
 
 export interface LintRule {
@@ -82,4 +116,12 @@ export interface LintRule {
  */
 export const RULES: LintRule[];
 
+/**
+ * The ids of the rules that read SOURCE rather than the evaluated part. A host
+ * that gates rendering on lint errors uses this to keep source findings
+ * REPORTED but non-blocking: a persistence defect is not a reason to refuse to
+ * render a part that builds.
+ */
+export const SOURCE_RULE_IDS: ReadonlySet<string>;
+
 export type { PartDefinition };