@epilot/zenith-react 0.1.0-next.0

package/scripts/migration-diagnostics-core.mjs

@@ -0,0 +1,991 @@
+/**
+ * Pure, fs-free migration-diagnostics rule core (WP6B-2 extraction). Every rule in this file
+ * is a straight-line function of its
+ * arguments: no `node:fs`/`node:path`/`node:module`/`node:process`/`node:child_process`/network
+ * access, no dynamic `import()`, no `eval`/`new Function`, no ambient DOM/global mutation, no
+ * module-load side effects. TypeScript is INJECTED by the caller (a `ts` parameter) — this module
+ * never imports, requires, or resolves `typescript` itself. `identity` (package name/version/
+ * generatedInputHash and the `core`/`palette` token-family `Set`s) is likewise always supplied by
+ * the caller; this module never reads a `dist/tokens/*` file or a `package.json` to derive it.
+ *
+ * `migration-diagnostics.mjs` (the sibling fs-bound orchestration module — file/directory walking,
+ * symlink boundary checks, hashing, `resolvePackageIdentity`, `resolveConsumerTypeScript`) is the
+ * CLI's entrypoint and delegates every file it reads to this module's `analyzeSource`. A future
+ * remote MCP tool would call `analyzeSource` directly with a caller-submitted string and a
+ * build-time-embedded identity — no path ever reaches this file. This module is not itself a
+ * "complete scan" API: it analyzes exactly the one string it is given, and callers remain
+ * responsible for their own completeness/incompleteness accounting (e.g. the CLI's
+ * `analysisIncomplete`/`toolingWarning` contract when TypeScript could not be resolved at all).
+ *
+ * Three rules, deliberately bounded to what survived every other gate on the four pilot
+ * migrations (see the outer module's original header for the incident history):
+ *
+ *   legacy-volt-class            — a v1-only `volt-*` utility class left in a className string.
+ *   hand-written-volt-css-var    — a raw `var(--volt-*)` (v1) or a hand-typed, hash-inlined
+ *                                  `var(--zenith-<hash>-*)` (v2) custom property, instead of
+ *                                  importing the token.
+ *   unestablished-palette-install — a decorative (non-core) token family is used, but no
+ *                                  correctly-scoped install call was found for it.
+ *
+ * `unestablished-palette-install` uses TypeScript's parser (syntax only — no type checker, no
+ * cross-module resolution) to do real lexical binding resolution: a name only counts as "the
+ * installer" or "a decorative token" if it resolves, through actual scope/shadowing, to an import
+ * from this package's own public specifiers, is not a type-only import, and is not shadowed by a
+ * closer local declaration. Certification is evaluated per DECORATIVE USAGE (not merely its
+ * enclosing scope), scoped to that usage's own consuming function plus at most one hop into a
+ * locally-declared helper the consuming scope calls directly, unconditionally, and BEFORE the
+ * usage in document order — never "this name is exported/called somewhere in the file".
+ *
+ * Supported analysis boundary: single-source, syntax-aware static analysis. It can prove a call
+ * exists, is unconditional relative to its own enclosing function, is reachable (not dead code
+ * after an unconditional return/throw), and precedes a given usage in straight-line document
+ * order. It cannot prove a *conditional* or *deferred* (callback/event) call's path always runs
+ * before the usage renders, and it cannot trace an install performed in a genuinely different
+ * source (e.g. a shared bootstrap/provider component) or through a relative (non-public-specifier)
+ * import — both get an explicit warning/uncertain finding, never a silent pass or a hard "error"
+ * (this rule never asserts a definite defect — see `RULES` below).
+ */
+
+// ---------------------------------------------------------------------------
+// Rule catalogue (also the "rule-support matrix" source of truth)
+// ---------------------------------------------------------------------------
+
+export const RULES = [
+  {
+    code: "legacy-volt-class",
+    title: "Legacy v1 volt-* class usage",
+    defaultSeverity: "error",
+    requiresTypeScript: false,
+    description:
+      "A v1-only Tailwind utility class (volt-*) is referenced in a className string. v2 ships no such class, and the singleton stylesheet is what is quietly still supplying it.",
+  },
+  {
+    code: "hand-written-volt-css-var",
+    title: "Hand-written legacy or hashed Volt CSS custom property",
+    defaultSeverity: "error",
+    requiresTypeScript: false,
+    description:
+      'A raw var(--volt-*) (v1, unpublished by v2) or a hand-typed var(--zenith-<hash>-*) (v2, with the generated salt/hash inlined) custom property is referenced directly instead of importing the token — see AGENTS.md: "never hardcode a namespace or salt hash."',
+  },
+  {
+    code: "unestablished-palette-install",
+    title: "Decorative token used without an established palette install",
+    defaultSeverity: "warning (always — see below)",
+    requiresTypeScript: true,
+    description:
+      'A decorative (non-core) token family is used, with varying confidence that a correctly-scoped install call covers it (high confidence for no local evidence at all, down to low for an unresolved dynamic path). This rule NEVER reports severity "error": local absence of an install call does not prove a bootstrap/provider install does not exist elsewhere — this is single-source analysis with no cross-file tracing, so it cannot assert a definite defect, only flag what needs verification. Core families (accent/gray/error/warning/success/info) are excluded — they load by default. Requires an injected TypeScript module (see requiresTypeScript).',
+  },
+]
+
+/** ts/tsx/js/jsx — the extensions `unestablished-palette-install` can parse. Exported so the
+ * fs-bound outer module can reuse the exact same rule (e.g. for its own `hasScriptFiles` check)
+ * without redefining it. */
+export const SCRIPT_EXT_RE = /\.(tsx?|jsx?)$/
+
+// ---------------------------------------------------------------------------
+// Diagnostic shape
+// ---------------------------------------------------------------------------
+
+/** Exported (not just internal) so the fs-bound outer module can build a finding for its own
+ * fs-level failures (e.g. "could not read this file") in the exact same shape, without a second,
+ * possibly-drifting definition of what a finding looks like. */
+export function makeFinding(
+  identity,
+  {
+    code,
+    severity,
+    confidence,
+    file,
+    line,
+    column,
+    evidence,
+    explanation,
+    suggestion,
+  }
+) {
+  return {
+    code,
+    severity,
+    confidence,
+    file,
+    line,
+    column,
+    package: {
+      name: identity.packageName,
+      version: identity.packageVersion,
+      generatedInputHash: identity.generatedInputHash,
+    },
+    evidence,
+    explanation,
+    suggestion,
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Rule 1 + 2: textual, comment-stripped scan (no TypeScript needed)
+// ---------------------------------------------------------------------------
+
+/** `volt-` inside a quoted string, skipping the package name itself. */
+const CLASS_RE =
+  /(['"`])((?:(?!\1)[^\\]|\\.)*?\bvolt-[a-z][a-z0-9-]*(?:(?!\1)[^\\]|\\.)*?)\1/g
+const VAR_RE_V1 = /var\(\s*--volt-[a-z0-9-]+/g
+/** A hand-typed v2 hashed custom property — same salt-shaped pattern the family reader uses. */
+const VAR_RE_V2_HASH = /var\(\s*--zenith-[a-z0-9]+-[a-z]+-[a-z0-9-]*/g
+
+const stripComments = (s) =>
+  s
+    .replace(/\/\*[\s\S]*?\*\//g, (m) => m.replace(/[^\n]/g, " "))
+    .replace(
+      /(^|[^:'"`\\])\/\/[^\n]*/g,
+      (m, p) => p + " ".repeat(m.length - p.length)
+    )
+
+/** Module specifiers are paths, not class lists — `./volt-token-bridge` is a filename. */
+const isModulePath = (src, idx) =>
+  /\b(?:import|require|from)\s*\(?\s*$/.test(
+    src.slice(Math.max(0, idx - 40), idx)
+  )
+
+function textualFindings(identity, fileLabel, raw) {
+  const findings = []
+  const stripped = stripComments(raw)
+  const lineOf = (idx) => stripped.slice(0, idx).split("\n").length
+  const colOf = (idx) => idx - stripped.lastIndexOf("\n", idx - 1)
+
+  for (const m of stripped.matchAll(CLASS_RE)) {
+    if (isModulePath(stripped, m.index)) continue
+    const cls = m[2].match(/\bvolt-[a-z][a-z0-9-]*/g) ?? []
+    const orphans = cls.filter((c) => !c.startsWith("volt-ui"))
+    if (orphans.length) {
+      findings.push(
+        makeFinding(identity, {
+          code: "legacy-volt-class",
+          severity: "error",
+          confidence: "high",
+          file: fileLabel,
+          line: lineOf(m.index),
+          column: colOf(m.index),
+          evidence: orphans.join(" "),
+          explanation:
+            "This v1-only utility class has no v2 equivalent and disappears once the v1 singleton stops loading its stylesheet. Note: this rule matches any quoted string shaped like a volt-* class, not only className attribute values — an unrelated string literal with the same shape can also match (see the WP6A report's documented limitation).",
+          suggestion:
+            "Replace with the equivalent Griffel component prop, or a makeZenithStyles() rule using a canonical token.",
+        })
+      )
+    }
+  }
+
+  for (const m of stripped.matchAll(VAR_RE_V1)) {
+    findings.push(
+      makeFinding(identity, {
+        code: "hand-written-volt-css-var",
+        severity: "error",
+        confidence: "high",
+        file: fileLabel,
+        line: lineOf(m.index),
+        column: colOf(m.index),
+        evidence: `${m[0]})`,
+        explanation:
+          "v2 publishes no such custom property; this resolves today only because the v1 singleton's stylesheet is still loaded at the portal root.",
+        suggestion:
+          "Import the equivalent token from the package's /tokens subpath instead of the raw CSS custom property.",
+      })
+    )
+  }
+
+  for (const m of stripped.matchAll(VAR_RE_V2_HASH)) {
+    findings.push(
+      makeFinding(identity, {
+        code: "hand-written-volt-css-var",
+        severity: "error",
+        confidence: "high",
+        file: fileLabel,
+        line: lineOf(m.index),
+        column: colOf(m.index),
+        evidence: `${m[0]})`,
+        explanation:
+          "The generated salt/hash is not a stable contract — it changes across Griffel engine or token-generation version bumps.",
+        suggestion:
+          "Import the token by name from the package's /tokens subpath and let makeZenithStyles() resolve the current hash; never hardcode a namespace or salt hash.",
+      })
+    )
+  }
+
+  return findings
+}
+
+// ---------------------------------------------------------------------------
+// Rule 3: syntax-aware (TypeScript AST) palette-install analysis
+// ---------------------------------------------------------------------------
+
+function scriptKindFor(ts, fileLabel) {
+  if (fileLabel.endsWith(".tsx")) return ts.ScriptKind.TSX
+  if (fileLabel.endsWith(".jsx")) return ts.ScriptKind.JSX
+  if (fileLabel.endsWith(".ts")) return ts.ScriptKind.TS
+  return ts.ScriptKind.JS
+}
+
+const isPaletteBindingName = (identity, name) => {
+  const fam = name.match(
+    /^([a-z]+)(?:A?\d+|Contrast|Surface|Indicator|Track)$/
+  )?.[1]
+  return Boolean(fam && identity.palette.has(fam))
+}
+
+/** The decorative family a token identifier belongs to (e.g. "blue11" -> "blue"), for suggestion
+ * text — never the specific token accessor itself, which is not the argument ensurePaletteTokensFor
+ * documents. */
+const familyOf = (identity, tokenName) => {
+  const fam = tokenName.match(
+    /^([a-z]+)(?:A?\d+|Contrast|Surface|Indicator|Track)$/
+  )?.[1]
+  return fam && identity.palette.has(fam) ? fam : tokenName
+}
+
+/** Real lexical scope/shadow resolution and same-scope call collection, bound to one `ts` module. */
+function createScopeHelpers(ts) {
+  /** Recursively checks a binding NAME (a plain identifier, or an object/array destructuring
+   * pattern — parameters, `const`/`let`/`var`, catch, and for-loop bindings can all destructure)
+   * for whether it declares `name` anywhere within it — `{ ensurePaletteTokens }`,
+   * `{ ensurePaletteTokens: x }` (bound as `x`, not shadowing), `[a, { b }]`, etc. */
+  function bindingNameDeclares(bindingName, name) {
+    if (ts.isIdentifier(bindingName)) return bindingName.text === name
+    if (
+      ts.isObjectBindingPattern(bindingName) ||
+      ts.isArrayBindingPattern(bindingName)
+    ) {
+      return bindingName.elements.some((el) => {
+        if (ts.isOmittedExpression(el)) return false
+        return bindingNameDeclares(el.name, name)
+      })
+    }
+    return false
+  }
+
+  function declarationDeclares(stmt, name) {
+    if (ts.isVariableStatement(stmt)) {
+      return stmt.declarationList.declarations.some((d) =>
+        bindingNameDeclares(d.name, name)
+      )
+    }
+    if (ts.isFunctionDeclaration(stmt)) return stmt.name?.text === name
+    if (ts.isClassDeclaration(stmt)) return stmt.name?.text === name
+    return false
+  }
+
+  /** True if `name`, referenced at `identifierNode`, is bound by something OTHER than a top-level
+   * (SourceFile-scope) import before the walk reaches the SourceFile — a parameter (including a
+   * destructured one), a local const/let/var (including destructured), a nested function/class
+   * declaration, a catch binding, or a for-loop variable. */
+  function isShadowedBeforeSourceFile(identifierNode, name) {
+    let cur = identifierNode.parent
+    while (cur && !ts.isSourceFile(cur)) {
+      if (
+        ts.isFunctionDeclaration(cur) ||
+        ts.isFunctionExpression(cur) ||
+        ts.isArrowFunction(cur) ||
+        ts.isMethodDeclaration(cur)
+      ) {
+        if (cur.parameters.some((p) => bindingNameDeclares(p.name, name)))
+          return true
+        if (
+          (ts.isFunctionDeclaration(cur) || ts.isFunctionExpression(cur)) &&
+          cur.name?.text === name
+        )
+          return true
+      }
+      if (
+        ts.isBlock(cur) &&
+        cur.statements.some((s) => declarationDeclares(s, name))
+      )
+        return true
+      if (
+        ts.isCatchClause(cur) &&
+        cur.variableDeclaration &&
+        bindingNameDeclares(cur.variableDeclaration.name, name)
+      ) {
+        return true
+      }
+      if (
+        (ts.isForStatement(cur) ||
+          ts.isForInStatement(cur) ||
+          ts.isForOfStatement(cur)) &&
+        cur.initializer &&
+        ts.isVariableDeclarationList(cur.initializer) &&
+        cur.initializer.declarations.some((d) =>
+          bindingNameDeclares(d.name, name)
+        )
+      ) {
+        return true
+      }
+      cur = cur.parent
+    }
+    return false
+  }
+
+  /** True if `node` sits under any branch that can fail to execute, up to (not past) `boundary`. */
+  function isWithinConditional(node, boundary) {
+    let cur = node.parent
+    while (cur && cur !== boundary) {
+      if (
+        ts.isIfStatement(cur) ||
+        ts.isConditionalExpression(cur) ||
+        ts.isSwitchStatement(cur) ||
+        ts.isCaseClause(cur) ||
+        ts.isForStatement(cur) ||
+        ts.isForInStatement(cur) ||
+        ts.isForOfStatement(cur) ||
+        ts.isWhileStatement(cur) ||
+        ts.isDoStatement(cur) ||
+        ts.isCatchClause(cur) ||
+        (ts.isBinaryExpression(cur) &&
+          [
+            ts.SyntaxKind.AmpersandAmpersandToken,
+            ts.SyntaxKind.BarBarToken,
+            ts.SyntaxKind.QuestionQuestionToken,
+          ].includes(cur.operatorToken.kind))
+      ) {
+        return true
+      }
+      cur = cur.parent
+    }
+    return false
+  }
+
+  /** The nearest enclosing function-like node, or the SourceFile itself for a module-scope node. */
+  function enclosingFunctionOrFile(node, sf) {
+    let cur = node.parent
+    while (cur) {
+      if (
+        ts.isFunctionDeclaration(cur) ||
+        ts.isFunctionExpression(cur) ||
+        ts.isArrowFunction(cur) ||
+        ts.isMethodDeclaration(cur)
+      ) {
+        return cur
+      }
+      cur = cur.parent
+    }
+    return sf
+  }
+
+  function functionName(fn, sf) {
+    if (fn === sf) return null
+    if (ts.isFunctionDeclaration(fn) && fn.name) return fn.name.text
+    if (
+      fn.parent &&
+      ts.isVariableDeclaration(fn.parent) &&
+      ts.isIdentifier(fn.parent.name)
+    )
+      return fn.parent.name.text
+    if (ts.isMethodDeclaration(fn) && ts.isIdentifier(fn.name))
+      return fn.name.text
+    return null
+  }
+
+  /** Nodes matching `matcher` that are direct descendants of `scope`'s own body — NOT nested
+   * inside a further function-like declared within `scope` (so a callback/handler's contents are
+   * excluded; see collectNested for the complement). */
+  function collectDirect(scope, matcher) {
+    const results = []
+    const body = ts.isSourceFile(scope) ? scope : scope.body
+    if (!body) return results
+    const visit = (node) => {
+      if (matcher(node)) results.push(node)
+      if (
+        node !== body &&
+        (ts.isFunctionDeclaration(node) ||
+          ts.isFunctionExpression(node) ||
+          ts.isArrowFunction(node) ||
+          ts.isMethodDeclaration(node))
+      ) {
+        return // stop: do not descend into a NESTED function's own body from here
+      }
+      ts.forEachChild(node, visit)
+    }
+    ts.forEachChild(body, visit)
+    return results
+  }
+
+  /** The complement of collectDirect: matches nested inside a function-like descendant of
+   * `scope` — a callback/event-handler/deferred position relative to `scope`. */
+  function collectNested(scope, matcher) {
+    const results = []
+    const body = ts.isSourceFile(scope) ? scope : scope.body
+    if (!body) return results
+    const visitInside = (node) => {
+      if (matcher(node)) results.push(node)
+      ts.forEachChild(node, visitInside)
+    }
+    const visitTop = (node) => {
+      if (
+        ts.isFunctionDeclaration(node) ||
+        ts.isFunctionExpression(node) ||
+        ts.isArrowFunction(node) ||
+        ts.isMethodDeclaration(node)
+      ) {
+        ts.forEachChild(node, visitInside)
+        return
+      }
+      ts.forEachChild(node, visitTop)
+    }
+    ts.forEachChild(body, visitTop)
+    return results
+  }
+
+  return {
+    isShadowedBeforeSourceFile,
+    isWithinConditional,
+    enclosingFunctionOrFile,
+    functionName,
+    collectDirect,
+    collectNested,
+  }
+}
+
+/** Collects trusted import bindings (installer, namespace, individual token names) — value-only:
+ * a `import type {...}` clause or a `import { type X }` specifier is never trusted as a runtime
+ * binding, since it cannot be called/read at runtime (and using it as if it could is itself a
+ * compiler error the consumer's own tsc will catch, not something to certify as evidence). */
+function collectBindings(sf, ts, identity) {
+  const validSpecifiers = new Set([
+    identity.packageName,
+    `${identity.packageName}/tokens`,
+  ])
+  // local (possibly aliased) name -> the ORIGINAL imported symbol ("ensurePaletteTokens" or
+  // "ensurePaletteTokensFor"). installDecorativeStatus must key off this canonical name, never the
+  // local spelling — `import { ensurePaletteTokens as install }` is a genuine, correct install.
+  const installerNames = new Map()
+  const namespaceNames = new Set()
+  const tokenBindings = new Map()
+
+  for (const stmt of sf.statements) {
+    if (
+      !ts.isImportDeclaration(stmt) ||
+      !ts.isStringLiteral(stmt.moduleSpecifier)
+    )
+      continue
+    if (!validSpecifiers.has(stmt.moduleSpecifier.text)) continue
+    const clause = stmt.importClause
+    if (!clause || clause.isTypeOnly || !clause.namedBindings) continue
+    if (ts.isNamespaceImport(clause.namedBindings)) {
+      namespaceNames.add(clause.namedBindings.name.text)
+    } else if (ts.isNamedImports(clause.namedBindings)) {
+      for (const el of clause.namedBindings.elements) {
+        if (el.isTypeOnly) continue
+        const imported = (el.propertyName ?? el.name).text
+        const local = el.name.text
+        if (
+          imported === "ensurePaletteTokens" ||
+          imported === "ensurePaletteTokensFor"
+        ) {
+          installerNames.set(local, imported)
+        } else if (imported === "tokens") {
+          // `export * as tokens from "./tokens"` at the package root — a named import of this
+          // object is functionally a namespace import (`import { tokens } from packageName`, or
+          // `import { tokens as t } from packageName`).
+          namespaceNames.add(local)
+        } else if (isPaletteBindingName(identity, imported)) {
+          tokenBindings.set(local, imported)
+        }
+      }
+    }
+  }
+
+  return { installerNames, namespaceNames, tokenBindings }
+}
+
+/** Whether `call` installs the decorative palette sheet: "confirmed" (the bare no-arg
+ * `ensurePaletteTokens()` form, or an `ensurePaletteTokensFor(<literal>)` argument that is not a
+ * known core family — matching the REAL runtime contract in `tokens/install.ts`:
+ * `if (CORE_FAMILIES.has(family)) return false; return ensurePaletteTokens(doc)` — an
+ * unrecognized/unknown literal still reaches installation; only a KNOWN CORE family is rejected),
+ * "uncertain" (a non-literal/dynamic argument to `-For` — cannot be resolved statically), or
+ * "not-decorative": either a known core family literal argument (a real, provable runtime no-op
+ * per the contract above), OR a call to `ensurePaletteTokensFor` with NO argument at all — `family`
+ * is a required, non-optional parameter, so a genuinely zero-argument call is not a valid typed
+ * call in the first place (it would fail `tsc` with "Expected 1-2 arguments, but got 0"), not a
+ * proven runtime no-op the way the core-family case is. Classified "not-decorative" defensively
+ * (there is no valid evidence of an install here), never claimed as a confirmed no-op. ANY
+ * "confirmed" call installs the WHOLE decorative sheet, not just one family — this does not
+ * require matching the specific family a usage reads. Resolves the callee through `bindings` to
+ * its ORIGINAL imported symbol, never the local (possibly aliased) spelling. */
+function installDecorativeStatus(call, ts, identity, bindings) {
+  const callee = call.expression
+  let canonicalName = null
+  if (ts.isIdentifier(callee)) {
+    canonicalName = bindings.installerNames.get(callee.text) ?? null
+  } else if (ts.isPropertyAccessExpression(callee)) {
+    // Property access names cannot be import-aliased — `tokens.ensurePaletteTokensFor` always
+    // uses the real member name.
+    canonicalName = callee.name.text
+  }
+  if (canonicalName === "ensurePaletteTokens") return "confirmed"
+  if (canonicalName === "ensurePaletteTokensFor") {
+    const arg = call.arguments[0]
+    if (!arg) return "not-decorative"
+    if (ts.isStringLiteralLike(arg)) {
+      return identity.core.has(arg.text) ? "not-decorative" : "confirmed"
+    }
+    return "uncertain"
+  }
+  return "not-decorative"
+}
+
+function isTrustedInstallerCall(call, ts, scope, bindings) {
+  const callee = call.expression
+  if (ts.isIdentifier(callee)) {
+    return (
+      bindings.installerNames.has(callee.text) &&
+      !scope.isShadowedBeforeSourceFile(callee, callee.text)
+    )
+  }
+  if (
+    ts.isPropertyAccessExpression(callee) &&
+    ts.isIdentifier(callee.expression)
+  ) {
+    const objName = callee.expression.text
+    return (
+      bindings.namespaceNames.has(objName) &&
+      !scope.isShadowedBeforeSourceFile(callee.expression, objName) &&
+      (callee.name.text === "ensurePaletteTokens" ||
+        callee.name.text === "ensurePaletteTokensFor")
+    )
+  }
+  return false
+}
+
+/** Every decorative-token usage in the source: a direct trusted token identifier, `namespace.blue11`,
+ * or `namespace["blue11"]` (a literal computed member). A computed member with a non-literal key
+ * (`namespace[dynamicExpr]`) cannot be resolved to a family — recorded as `dynamic: true` so it
+ * gets an explicit uncertain finding rather than silently disappearing. */
+function collectDecorativeUsages(sf, ts, scope, bindings, identity) {
+  const usages = []
+  const visit = (node) => {
+    if (
+      ts.isIdentifier(node) &&
+      !ts.isImportSpecifier(node.parent) &&
+      bindings.tokenBindings.has(node.text)
+    ) {
+      if (!scope.isShadowedBeforeSourceFile(node, node.text)) {
+        usages.push({
+          node,
+          family: bindings.tokenBindings.get(node.text),
+          dynamic: false,
+        })
+      }
+    } else if (
+      ts.isPropertyAccessExpression(node) &&
+      ts.isIdentifier(node.expression) &&
+      bindings.namespaceNames.has(node.expression.text) &&
+      !scope.isShadowedBeforeSourceFile(
+        node.expression,
+        node.expression.text
+      ) &&
+      isPaletteBindingName(identity, node.name.text)
+    ) {
+      usages.push({ node, family: node.name.text, dynamic: false })
+    } else if (
+      ts.isElementAccessExpression(node) &&
+      ts.isIdentifier(node.expression) &&
+      bindings.namespaceNames.has(node.expression.text) &&
+      !scope.isShadowedBeforeSourceFile(node.expression, node.expression.text)
+    ) {
+      const arg = node.argumentExpression
+      if (arg && ts.isStringLiteralLike(arg)) {
+        if (isPaletteBindingName(identity, arg.text)) {
+          usages.push({ node, family: arg.text, dynamic: false })
+        }
+      } else if (arg) {
+        usages.push({ node, family: null, dynamic: true })
+      }
+    }
+    ts.forEachChild(node, visit)
+  }
+  visit(sf)
+  return usages
+}
+
+/**
+ * True if `node` is positioned after an unconditional `return`/`throw` STATEMENT in the same
+ * block, anywhere between `node` and `boundaryFn` — i.e. it is dead code that can never execute
+ * (bounded, single-block-level reachability; not a full CFG — a `return`/`throw` nested inside its
+ * own further conditional does not count, since it does not unconditionally exit ITS enclosing
+ * block).
+ */
+function isDeadCode(node, boundaryFn, ts) {
+  let child = node
+  let cur = node.parent
+  while (cur && cur !== boundaryFn) {
+    if (ts.isBlock(cur) || ts.isSourceFile(cur)) {
+      const idx = cur.statements.indexOf(child)
+      if (idx > 0) {
+        for (let i = 0; i < idx; i++) {
+          if (
+            ts.isReturnStatement(cur.statements[i]) ||
+            ts.isThrowStatement(cur.statements[i])
+          ) {
+            return true
+          }
+        }
+      }
+    }
+    child = cur
+    cur = cur.parent
+  }
+  return false
+}
+
+/** The direct child of `block.statements` that (transitively) contains `node`, or null if `node`
+ * is not actually within `block`. */
+function directStatementContaining(block, node, _ts) {
+  let cur = node
+  while (cur && cur.parent) {
+    if (cur.parent === block) return cur
+    cur = cur.parent
+  }
+  return null
+}
+
+/**
+ * Bounded, order-sensitive coverage check (straight-line document order — no loop/goto modelling):
+ * true if `call` is guaranteed to run before `usageNode` can be evaluated, within the same
+ * consuming scope `F`. This is what makes classification USAGE-sensitive rather than scope-wide —
+ * `isWithinConditional`/`isDeadCode` alone say a call is "unconditional in F", but that does not
+ * mean it precedes every usage in F: a guard clause can return an EARLIER usage before the call
+ * ever runs.
+ *
+ * Walks the block-ancestor chain of both `call` and `usageNode` up to `F`, finds their lowest
+ * shared block (outermost-first), and at the first level where they sit in DIFFERENT direct
+ * statements of that block, compares statement index — the call covers the usage only if its
+ * statement comes first. If they share the exact same direct statement at every checked level
+ * (e.g. both nested in the same `if` body), the deeper shared block is checked next. No shared
+ * block, or no resolvable statement, is conservatively "not covered".
+ */
+function callCoversUsage(call, usageNode, F, ts) {
+  const blockChain = (node) => {
+    const blocks = []
+    let cur = node.parent
+    while (cur && cur !== F) {
+      if (ts.isBlock(cur) || ts.isSourceFile(cur)) blocks.push(cur)
+      cur = cur.parent
+    }
+    const fBody = ts.isSourceFile(F) ? F : F.body
+    if (fBody) blocks.push(fBody)
+    return blocks.reverse() // outermost first
+  }
+  const callBlocks = blockChain(call)
+  const usageBlocks = new Set(blockChain(usageNode))
+  const shared = callBlocks.filter((b) => usageBlocks.has(b))
+  if (shared.length === 0) return false
+
+  for (const block of shared) {
+    const callStmt = directStatementContaining(block, call, ts)
+    const usageStmt = directStatementContaining(block, usageNode, ts)
+    if (!callStmt || !usageStmt) return false
+    if (callStmt === usageStmt) continue // same statement at this level -- check the next, deeper shared block
+    const callIdx = block.statements.indexOf(callStmt)
+    const usageIdx = block.statements.indexOf(usageStmt)
+    if (callIdx === -1 || usageIdx === -1) return false
+    return callIdx < usageIdx
+  }
+  return false
+}
+
+/**
+ * Classifies one decorative USAGE (not merely its enclosing scope — see `callCoversUsage`):
+ * "confirmed" if a reachable, unconditional, correctly-scoped install call precedes it; "uncertain"
+ * with a `reason` if the best (or only) evidence is conditional, dead/unreachable, deferred into a
+ * callback, dynamic, positioned after the usage, or reached through an ambiguously-named or
+ * conditionally-called helper; "absent" if no relevant candidate exists at all. The caller maps
+ * ALL non-"confirmed" tiers to severity "warning" — this function's tiers only drive relative
+ * confidence and the reported reason, never an "error".
+ */
+function classifyScope(F, sf, ts, scope, bindings, identity, usageNode) {
+  const isInstaller = (n) =>
+    ts.isCallExpression(n) && isTrustedInstallerCall(n, ts, scope, bindings)
+  const relevant = (call) =>
+    installDecorativeStatus(call, ts, identity, bindings) !== "not-decorative"
+  const reachable = (call) => !isDeadCode(call, F, ts)
+  const precedesUsage = (call) => callCoversUsage(call, usageNode, F, ts)
+
+  const direct = scope
+    .collectDirect(F, isInstaller)
+    .filter(relevant)
+    .filter(reachable)
+  for (const call of direct) {
+    if (
+      installDecorativeStatus(call, ts, identity, bindings) === "confirmed" &&
+      !scope.isWithinConditional(call, F) &&
+      precedesUsage(call)
+    ) {
+      return { tier: "confirmed" }
+    }
+  }
+
+  // One hop into a locally-declared helper the consuming scope calls directly (not nested in a
+  // further callback) — conditionally called helpers, ambiguously-named helpers (more than one
+  // local declaration shares the name — cannot safely resolve which one runs), helpers whose only
+  // internal install call is itself conditional/dynamic/unreachable, or a helper call that does not
+  // itself PRECEDE this usage (same guard-ordering rule as a direct call), do not certify.
+  const helperDecls = collectLocalFunctionDeclarations(sf, ts)
+  const helperCalls = scope
+    .collectDirect(
+      F,
+      (n) =>
+        ts.isCallExpression(n) &&
+        ts.isIdentifier(n.expression) &&
+        helperDecls.has(n.expression.text)
+    )
+    .filter(
+      (call) =>
+        !scope.isShadowedBeforeSourceFile(call.expression, call.expression.text)
+    )
+    .filter(reachable)
+
+  let helperUncertain = false
+  for (const helperCall of helperCalls) {
+    const helperFn = helperDecls.get(helperCall.expression.text)
+    if (helperFn === "ambiguous") {
+      helperUncertain = true
+      continue
+    }
+    const helperConditional = scope.isWithinConditional(helperCall, F)
+    const helperOrdered = precedesUsage(helperCall)
+    const innerDirect = scope
+      .collectDirect(helperFn, isInstaller)
+      .filter(relevant)
+      .filter((c) => !isDeadCode(c, helperFn, ts))
+    if (innerDirect.length > 0) helperUncertain = true
+    for (const inner of innerDirect) {
+      const innerConfirmed =
+        installDecorativeStatus(inner, ts, identity, bindings) === "confirmed"
+      const innerConditional = scope.isWithinConditional(inner, helperFn)
+      if (
+        innerConfirmed &&
+        !innerConditional &&
+        !helperConditional &&
+        helperOrdered
+      ) {
+        return { tier: "confirmed" }
+      }
+    }
+  }
+
+  if (direct.length > 0) {
+    const dynamicOnly = direct.every(
+      (c) => installDecorativeStatus(c, ts, identity, bindings) === "uncertain"
+    )
+    const anyOrdered = direct.some((c) => precedesUsage(c))
+    return {
+      tier: "uncertain",
+      reason: dynamicOnly
+        ? "the install call's family argument is not a literal, so it cannot be statically confirmed as decorative."
+        : !anyOrdered
+          ? "a reachable, unconditional ensurePaletteTokens()/-For() call exists in this scope, but only AFTER this usage — an earlier return/branch can reach this usage before the install runs."
+          : "a reachable ensurePaletteTokens()/-For() call exists in this scope, but only inside a conditional/guarded path.",
+    }
+  }
+
+  const nested = scope.collectNested(F, isInstaller).filter(relevant)
+  if (nested.length > 0) {
+    return {
+      tier: "uncertain",
+      reason:
+        "an ensurePaletteTokens()/-For() call exists, but only inside a nested callback/event handler — it does not run synchronously as part of this scope's own render path.",
+    }
+  }
+
+  if (helperUncertain) {
+    return {
+      tier: "uncertain",
+      reason:
+        "an ensurePaletteTokens()/-For() call exists in a locally-declared helper this scope calls, but either the helper's name is ambiguous (more than one local declaration), the call to the helper is conditional or positioned after this usage, or the call inside it is conditional/unreachable.",
+    }
+  }
+
+  return { tier: "absent" }
+}
+
+/** Top-level (and nested) named function/arrow declarations, for one-hop helper-call tracing.
+ * Keyed by declared name. A second declaration sharing a name marks it `"ambiguous"` instead of
+ * silently keeping the first one found — classifyScope treats an ambiguous helper call as
+ * uncertain, never resolving into (and potentially mis-certifying from) the wrong declaration. */
+function collectLocalFunctionDeclarations(sf, ts) {
+  const decls = new Map()
+  const record = (name, fn) => {
+    if (decls.has(name)) decls.set(name, "ambiguous")
+    else decls.set(name, fn)
+  }
+  const visit = (node) => {
+    if (ts.isFunctionDeclaration(node) && node.name) {
+      record(node.name.text, node)
+    } else if (
+      ts.isVariableDeclaration(node) &&
+      ts.isIdentifier(node.name) &&
+      node.initializer
+    ) {
+      if (
+        ts.isArrowFunction(node.initializer) ||
+        ts.isFunctionExpression(node.initializer)
+      ) {
+        record(node.name.text, node.initializer)
+      }
+    }
+    ts.forEachChild(node, visit)
+  }
+  visit(sf)
+  return decls
+}
+
+function describeScope(F, sf, scope, _ts) {
+  const name = scope.functionName(F, sf)
+  return name ? `\`${name}\`` : "module scope"
+}
+
+function analyzePaletteInstallation(ts, identity, fileLabel, raw) {
+  const scope = createScopeHelpers(ts)
+  const sf = ts.createSourceFile(
+    fileLabel,
+    raw,
+    ts.ScriptTarget.Latest,
+    true,
+    scriptKindFor(ts, fileLabel)
+  )
+  const bindings = collectBindings(sf, ts, identity)
+  const usages = collectDecorativeUsages(sf, ts, scope, bindings, identity)
+  if (usages.length === 0) return []
+
+  const findings = []
+  const reportedScopes = new Set()
+
+  for (const usage of usages) {
+    if (usage.dynamic) {
+      const key = `dynamic:${usage.node.getStart(sf)}`
+      if (reportedScopes.has(key)) continue
+      reportedScopes.add(key)
+      const pos = sf.getLineAndCharacterOfPosition(usage.node.getStart(sf))
+      findings.push(
+        makeFinding(identity, {
+          code: "unestablished-palette-install",
+          severity: "warning",
+          confidence: "low",
+          file: fileLabel,
+          line: pos.line + 1,
+          column: pos.character + 1,
+          evidence:
+            "A computed member access on the tokens namespace uses a non-literal key, so the referenced family cannot be statically determined.",
+          explanation:
+            "Static analysis cannot resolve which decorative family this reads, so palette-install coverage for this usage cannot be verified.",
+          suggestion:
+            'Prefer a literal token member (e.g. tokens.blue11 or tokens["blue11"]) so this is verifiable, or confirm manually that every family this path may resolve to has its palette sheet installed.',
+        })
+      )
+      continue
+    }
+
+    // Classified PER USAGE, not per scope: a scope can contain an unconditional install call that
+    // still does not cover an EARLIER usage reachable via a guard clause that returns first (see
+    // callCoversUsage) — deduping by scope alone would let that earlier usage silently inherit a
+    // later usage's "confirmed" verdict.
+    const F = scope.enclosingFunctionOrFile(usage.node, sf)
+    const usageKey = String(usage.node.getStart(sf))
+    if (reportedScopes.has(usageKey)) continue
+    reportedScopes.add(usageKey)
+
+    const status = classifyScope(
+      F,
+      sf,
+      ts,
+      scope,
+      bindings,
+      identity,
+      usage.node
+    )
+    if (status.tier === "confirmed") continue
+
+    const pos = sf.getLineAndCharacterOfPosition(usage.node.getStart(sf))
+    const scopeDesc = describeScope(F, sf, scope, ts)
+    const family = familyOf(identity, usage.family)
+
+    // Never "error" here: this is single-source analysis with no cross-file tracing, so it can
+    // never prove a decorative usage is actually broken — a shared bootstrap/provider install
+    // elsewhere is always a possibility this source alone cannot rule out. Severity stays
+    // "warning" for every tier; only confidence varies.
+    const verifyAction =
+      `Not confirmable from this source alone — local absence does not prove a bootstrap/provider install does not exist elsewhere. ` +
+      `Inspect this integration's existing installation contract for "${family}" before assuming a defect. ` +
+      `Once available, establish the install through the pending WP2B React adapter (not yet shipped) rather than adding an ad hoc render-time call here.`
+
+    if (status.tier === "uncertain") {
+      findings.push(
+        makeFinding(identity, {
+          code: "unestablished-palette-install",
+          severity: "warning",
+          confidence: "medium",
+          file: fileLabel,
+          line: pos.line + 1,
+          column: pos.character + 1,
+          evidence: `Decorative token "${usage.family}" is used in ${scopeDesc}: ${status.reason}`,
+          explanation:
+            "Static analysis cannot prove this path always runs, unconditionally and synchronously, before the decorative token renders. If it does not actually cover this usage, the palette sheet may never load and the value renders as an invalid custom property with no colour.",
+          suggestion: verifyAction,
+        })
+      )
+    } else {
+      findings.push(
+        makeFinding(identity, {
+          code: "unestablished-palette-install",
+          severity: "warning",
+          confidence: "high",
+          file: fileLabel,
+          line: pos.line + 1,
+          column: pos.character + 1,
+          evidence: `Decorative token "${usage.family}" is used in ${scopeDesc}, with no reachable, unconditional, correctly-scoped ensurePaletteTokens()/-For() call found for it in this source.`,
+          explanation: `"${family}" sits outside the core sheet (accent/gray/error/warning/success/info) that loads by default. Without an install covering it, this renders an invalid custom property and no colour — but this source alone cannot confirm whether a shared bootstrap/provider elsewhere already covers it.`,
+          suggestion: verifyAction,
+        })
+      )
+    }
+  }
+
+  return findings
+}
+
+// ---------------------------------------------------------------------------
+// Public entrypoint
+// ---------------------------------------------------------------------------
+
+/**
+ * Analyzes one already-in-memory source string — no fs, no path resolution, nothing derived from
+ * `sourceText` is ever used as a filesystem path or executed. Runs `legacy-volt-class` and
+ * `hand-written-volt-css-var` unconditionally (pure text, no TypeScript needed). Runs
+ * `unestablished-palette-install` only if BOTH `ts` is supplied (injected by the caller — this
+ * module never resolves it) AND `fileNameHint` looks like a script file (`.ts`/`.tsx`/`.js`/`.jsx`)
+ * — a `.css`/`.scss` hint (or any non-script hint) only ever produces the two textual rules'
+ * findings, same as the CLI's file-based behavior for a stylesheet. `fileNameHint` is a LABEL for
+ * output only (the `file` field on findings, and which parse mode to use) — never treated as a
+ * path to read.
+ *
+ * Returns the same finding array shape `migration-diagnostics.mjs` (via its `analyzeFile`) has
+ * always returned, in the same order (textual findings first, then palette findings). Calling this
+ * twice with the same inputs returns equivalent findings and does not mutate `identity` (its
+ * `core`/`palette` `Set`s are only ever read, never written).
+ */
+export function analyzeSource(
+  sourceText,
+  { identity, ts, fileNameHint = "source.tsx" } = {}
+) {
+  if (!identity) {
+    throw new Error(
+      "analyzeSource requires a resolved `identity` — { packageName, packageVersion, generatedInputHash, core: Set<string>, palette: Set<string> }."
+    )
+  }
+  const findings = textualFindings(identity, fileNameHint, sourceText)
+  if (ts && SCRIPT_EXT_RE.test(fileNameHint)) {
+    findings.push(
+      ...analyzePaletteInstallation(ts, identity, fileNameHint, sourceText)
+    )
+  }
+  return findings
+}