partforge 0.76.0 → 0.78.0

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,28 @@ 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.

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;
+}