@backbencher/brain 0.0.0-stage → 0.1.0

package/dist/real-scss-analyzer-TGRJQ7TH.js

@@ -0,0 +1,1515 @@
+import {
+  FILE_CLAIM_MAX_BYTES,
+  dirOf,
+  fileClaimForTarget,
+  foldProjectPath
+} from "./chunk-EWMWK7WN.js";
+import {
+  RealCssAnalyzer,
+  cssFileScopeOf
+} from "./chunk-IFZNR5UJ.js";
+import {
+  ASTEngine
+} from "./chunk-V44PGPA6.js";
+import "./chunk-BQ3OVQ3P.js";
+import "./chunk-SK6YVHFZ.js";
+import "./chunk-2BSKD7O3.js";
+import "./chunk-KAET47ZL.js";
+import "./chunk-KCDECRJY.js";
+import "./chunk-MLKGABMK.js";
+
+// src/ast/real-scss-analyzer.ts
+import * as path from "path";
+import { existsSync } from "fs";
+function stripAllQuotes(text) {
+  let out = "";
+  for (let i = 0; i < text.length; i++) {
+    const c = text[i];
+    if (c === '"' || c === "'") {
+      const close = text.indexOf(c, i + 1);
+      if (close < 0) break;
+      out += text.slice(i + 1, close);
+      i = close;
+    } else {
+      out += c;
+    }
+  }
+  return out.trim();
+}
+var JS_WHITESPACE = /* @__PURE__ */ new Set([
+  " ",
+  "	",
+  "\n",
+  "\v",
+  "\f",
+  "\r",
+  "\xA0",
+  "\u1680",
+  "\u2000",
+  "\u2001",
+  "\u2002",
+  "\u2003",
+  "\u2004",
+  "\u2005",
+  "\u2006",
+  "\u2007",
+  "\u2008",
+  "\u2009",
+  "\u200A",
+  "\u2028",
+  "\u2029",
+  "\u202F",
+  "\u205F",
+  "\u3000",
+  "\uFEFF"
+]);
+function isWordCharCode(code) {
+  return code >= 97 && code <= 122 || // a-z
+  code >= 65 && code <= 90 || // A-Z
+  code >= 48 && code <= 57 || // 0-9
+  code === 95;
+}
+function collapseWhitespace(text) {
+  let out = "";
+  let pendingSpace = false;
+  for (const ch of text) {
+    if (JS_WHITESPACE.has(ch)) {
+      if (out.length > 0) pendingSpace = true;
+      continue;
+    }
+    if (pendingSpace) {
+      out += " ";
+      pendingSpace = false;
+    }
+    out += ch;
+  }
+  return out;
+}
+function isReadablePlaceholder(name) {
+  if (name.length < 2) return false;
+  if (name.charCodeAt(0) !== 37) return false;
+  const last = name.charCodeAt(name.length - 1);
+  if (!isWordCharCode(last)) return false;
+  for (let i = 1; i < name.length - 1; i++) {
+    const code = name.charCodeAt(i);
+    if (code === 45 || isWordCharCode(code)) continue;
+    return false;
+  }
+  return true;
+}
+function containsStatementDelimiter(name) {
+  for (let i = 0; i < name.length; i++) {
+    const code = name.charCodeAt(i);
+    if (code === 59 || code === 123 || code === 125) return true;
+  }
+  return false;
+}
+function mixinName(name) {
+  return `@mixin ${name}`;
+}
+function functionName(name) {
+  return `@function ${name}`;
+}
+var RECOVERY_CHILD_CAP = 1e4;
+var SCOPE_NODES = /* @__PURE__ */ new Set([
+  "rule_set",
+  "mixin_statement",
+  "function_statement",
+  "if_statement",
+  "each_statement",
+  "for_statement",
+  "while_statement"
+]);
+function hasScopeAncestor(node) {
+  for (let p = node.parent; p; p = p.parent) if (SCOPE_NODES.has(p.type)) return true;
+  return false;
+}
+function isPrivateSassName(published) {
+  const bare = published.startsWith("$") ? published.slice(1) : published.startsWith("@mixin ") ? published.slice("@mixin ".length) : published.startsWith("@function ") ? published.slice("@function ".length) : published;
+  return bare.startsWith("-") || bare.startsWith("_");
+}
+function hasSchemeHead(specifier) {
+  const colon = specifier.indexOf(":");
+  if (colon <= 0) return false;
+  const isAlpha = (c) => c >= 65 && c <= 90 || c >= 97 && c <= 122;
+  const isDigit = (c) => c >= 48 && c <= 57;
+  if (!isAlpha(specifier.charCodeAt(0))) return false;
+  for (let i = 1; i < colon; i++) {
+    const c = specifier.charCodeAt(i);
+    if (!isAlpha(c) && !isDigit(c) && c !== 43 && c !== 46 && c !== 45) return false;
+  }
+  return true;
+}
+function hasNodeModulesSegment(specifier) {
+  return specifier.startsWith("node_modules/") || specifier.includes("/node_modules/");
+}
+function isScopedPackageSpecifier(specifier) {
+  if (!specifier.startsWith("@")) return false;
+  const slash = specifier.indexOf("/", 1);
+  if (slash < 2) return false;
+  const isAlpha = (c) => c >= 65 && c <= 90 || c >= 97 && c <= 122;
+  const isDigit = (c) => c >= 48 && c <= 57;
+  for (let i = 1; i < slash; i++) {
+    const c = specifier.charCodeAt(i);
+    if (!isAlpha(c) && !isDigit(c) && c !== 46 && c !== 95 && c !== 45) return false;
+  }
+  return true;
+}
+function hasCssFileExtension(specifier) {
+  const lower = specifier.toLowerCase();
+  let at = lower.indexOf(".css");
+  while (at >= 0) {
+    const next = lower.charAt(at + 4);
+    if (next === "" || next === "?" || next === "#") return true;
+    at = lower.indexOf(".css", at + 4);
+  }
+  return false;
+}
+function includeStatementIsComplete(statementText) {
+  const trimmed = statementText.trimEnd();
+  if (trimmed.endsWith(";")) return true;
+  if (!trimmed.endsWith("}")) return false;
+  return trimmed.indexOf("{") >= 0;
+}
+function normalizeModuleSpelling(spelling) {
+  const segments = spelling.split("\\").join("/").split("/");
+  let leaf = segments.length > 0 ? segments[segments.length - 1] ?? spelling : spelling;
+  const lower = leaf.toLowerCase();
+  for (const ext of [".scss", ".sass", ".css"]) {
+    if (lower.endsWith(ext)) {
+      leaf = leaf.slice(0, leaf.length - ext.length);
+      break;
+    }
+  }
+  if (leaf.startsWith("_")) leaf = leaf.slice(1);
+  return leaf;
+}
+function isExternalImportSpecifier(written) {
+  if (hasSchemeHead(written) || written.startsWith("//")) return true;
+  if (hasNodeModulesSegment(written)) return true;
+  if (written.startsWith("~")) return true;
+  if (isScopedPackageSpecifier(written)) return true;
+  return false;
+}
+function sourcePathClaimIsUnrefutable(projectRoot, written) {
+  const candidates = [];
+  const push = (v) => {
+    const t = v.trim();
+    if (t.length > 0 && !candidates.includes(t)) candidates.push(t);
+  };
+  push(written);
+  push(written.startsWith("./") ? written.slice(2) : written);
+  push(written.startsWith("../") ? written.slice(3) : written);
+  const segs = written.split("/").filter((x) => x.length > 0 && x !== "." && x !== "..");
+  if (segs.length > 0) {
+    push(segs.join("/"));
+    push(segs[segs.length - 1]);
+  }
+  for (const candidate of candidates) {
+    try {
+      if (existsSync(path.resolve(projectRoot, candidate))) return false;
+    } catch {
+      return false;
+    }
+  }
+  return true;
+}
+var RealScssAnalyzer = class {
+  analyze(rootNode, content, filePath, context) {
+    const base = new RealCssAnalyzer().analyze(rootNode, content, filePath);
+    const ctx = {
+      symbols: base.symbols ?? [],
+      relationships: base.relationships ?? [],
+      imports: base.imports ?? [],
+      exports: base.exports ?? [],
+      mixinNames: {},
+      functionNames: {},
+      variableNames: {},
+      namespaces: {},
+      sassPartImports: /* @__PURE__ */ new Set(),
+      published: {},
+      publishedOwner: {},
+      moduleName: this.moduleNameOf(filePath),
+      topLevelVarLines: {},
+      sawDiagnostic: false,
+      sawContent: false,
+      sawAtRoot: false,
+      projectIndex: context?.projectIndex
+    };
+    const baseModule = ctx.symbols.find(
+      (s) => s.kind === ASTEngine.SymbolKind.Module && s.name === ctx.moduleName
+    );
+    if (baseModule) {
+      baseModule.metadata = {
+        ...baseModule.metadata ?? {},
+        isScssModule: true,
+        scssModuleName: ctx.moduleName,
+        scssModulePath: filePath
+      };
+    } else {
+      ctx.symbols.unshift({
+        name: ctx.moduleName,
+        kind: ASTEngine.SymbolKind.Module,
+        range: this.nodeToRange(rootNode),
+        scope: "",
+        visibility: "public",
+        complexity: 1,
+        metadata: { cssSpecific: true, isScssModule: true, scssModuleName: ctx.moduleName, scssModulePath: filePath }
+      });
+    }
+    for (const s of ctx.symbols) ctx.published[s.name] = true;
+    this.collectDeclarations(rootNode, ctx);
+    this.walk(rootNode, ctx);
+    if (ctx.recoveryCap && ctx.relationships.length > 0) {
+      ctx.relationships[0].metadata = { ...ctx.relationships[0].metadata ?? {}, scssRecoveryCap: ctx.recoveryCap };
+    }
+    this.emitModuleExports(ctx);
+    const claimRoot = typeof context?.projectRoot === "string" && context.projectRoot.length > 0 ? context.projectRoot : null;
+    if (claimRoot !== null) {
+      const fileRel = path.relative(path.resolve(claimRoot), filePath).split(path.sep).join("/");
+      const baseDir = dirOf(fileRel);
+      for (const r of ctx.relationships) {
+        if (r.type !== ASTEngine.RelationshipType.Imports) continue;
+        const md = r.metadata;
+        if (!md || typeof md.importProjectFile === "string") continue;
+        const written = String(r.target ?? "").trim();
+        if (written.length === 0) continue;
+        const cut = written.lastIndexOf("/");
+        const dirPart = cut < 0 ? "" : written.slice(0, cut + 1);
+        const leaf = cut < 0 ? written : written.slice(cut + 1);
+        const spellings = /* @__PURE__ */ new Set([`${written}.scss`, `${written}/_index.scss`, `${written}/index.scss`]);
+        if (leaf.length > 0 && !leaf.startsWith("_")) {
+          spellings.add(`${dirPart}_${leaf}.scss`);
+          spellings.add(`${dirPart}_${leaf}/_index.scss`);
+        }
+        const extra = [];
+        for (const sp of spellings) {
+          for (const cand of [foldProjectPath(baseDir, sp), foldProjectPath("", sp)]) {
+            if (cand !== null && !extra.includes(cand)) extra.push(cand);
+          }
+        }
+        const claim = fileClaimForTarget({
+          projectRoot: claimRoot,
+          filePath,
+          written,
+          admittedExtensions: ["scss"],
+          // THE POPULATION'S SIZE CAP, passed because this lane HAS over-cap files (4 for graphql,
+          // 2 for scss on the gate's own population line). A claim about one of them would be
+          // REFUTED, and nothing in the row would say why.
+          maxFileSizeBytes: FILE_CLAIM_MAX_BYTES,
+          extraCandidates: extra
+        });
+        if (claim !== null) {
+          md.importProjectFile = claim;
+          continue;
+        }
+        if (isExternalImportSpecifier(written) && sourcePathClaimIsUnrefutable(claimRoot, written)) {
+          md.sourcePathClaim = [written];
+        }
+      }
+    }
+    this.relabelSassPartImports(ctx);
+    this.publishScssFileScopedIdentities(ctx, filePath);
+    return {
+      ...base,
+      symbols: ctx.symbols,
+      relationships: ctx.relationships,
+      imports: ctx.imports,
+      exports: ctx.exports,
+      metadata: {
+        ...base.metadata ?? {},
+        scssDialect: true,
+        scssMixins: Object.keys(ctx.mixinNames).length,
+        scssFunctions: Object.keys(ctx.functionNames).length,
+        scssVariables: Object.keys(ctx.variableNames).length,
+        scssModuleName: ctx.moduleName,
+        scssFrameworks: ["SCSS/SASS"],
+        ...ctx.sawDiagnostic ? { scssHasDiagnostics: true } : {},
+        ...ctx.sawContent ? { scssForwardsContent: true } : {},
+        ...ctx.sawAtRoot ? { scssEscapesScope: true } : {}
+      }
+    };
+  }
+  /** The stylesheet's own module name: its basename, extension included. */
+  moduleNameOf(filePath) {
+    const normalized = filePath.split("\\").join("/");
+    const base = normalized.slice(normalized.lastIndexOf("/") + 1);
+    return base.length > 0 ? base : "module.scss";
+  }
+  /**
+   * Give the symbols THIS analyzer added — and only those — a project-unique `qualifiedName`,
+   * then respell the edges that name one of them from the file that declares it.
+   *
+   * WHY ONLY THE ONES THIS ANALYZER ADDED. The delegate already ran
+   * `publishFileScopedIdentities` over its own output, so every symbol it published already
+   * carries a `qualifiedName` and every edge it could respell already has. A target that is
+   * STILL bare after the delegate declined it (no local declaration, or several and no line to
+   * choose between them) is a decision the delegate made deliberately, and re-deciding it here
+   * would be a second implementation of a rule this lane is supposed to inherit. So the pass
+   * touches a symbol only when `qualifiedName` is ABSENT, which is exactly the set added here:
+   * `$variables`, `@mixin`/`@function` symbols, the module's namespaces, the control-flow
+   * `interface` symbols, the imported-member symbols, and the module row itself.
+   *
+   * WHY REFERENCES/EXPORTS/CALLS/USES/OVERRIDES. `Exports` and `Calls` are the two the delegate
+   * has no analogue for (CSS has neither a module surface nor a call), and they are the two
+   * carrying this lane's measured collisions; `References` and `Uses` are here because the SCSS
+   * reads (`$var`, `@include`) are pushed AFTER the delegate's pass and so were never seen by
+   * it. `Imports` is deliberately ABSENT for the delegate's own stated reason: an `imports`
+   * edge names ANOTHER file's module, and this file's module symbol happens to share its
+   * spelling with that file's basename — respelling it would point the import at the importing
+   * file itself.
+   */
+  publishScssFileScopedIdentities(ctx, filePath) {
+    const scope = cssFileScopeOf(filePath);
+    if (scope === "") return;
+    const byName = /* @__PURE__ */ new Map();
+    for (const sym of ctx.symbols) {
+      const name = String(sym.name ?? "");
+      if (name.length === 0) continue;
+      if (sym.qualifiedName !== void 0 && sym.qualifiedName !== "") continue;
+      sym.qualifiedName = `${scope}::${name}`;
+      if (!byName.has(name)) byName.set(name, String(sym.qualifiedName));
+    }
+    if (byName.size === 0) return;
+    const REWRITABLE = /* @__PURE__ */ new Set([
+      ASTEngine.RelationshipType.References,
+      ASTEngine.RelationshipType.Exports,
+      ASTEngine.RelationshipType.Calls,
+      ASTEngine.RelationshipType.Uses,
+      ASTEngine.RelationshipType.Overrides,
+      // `mixes_in` targets a `@mixin <name>` symbol THIS FILE may declare, so the same file-scoped
+      // respell applies — and it must: a target published bare for a mixin the file declares is the
+      // collision shape this pass exists to remove. `part_of` is deliberately ABSENT for the reason
+      // `Imports` is: its target names ANOTHER file's module, and respelling it to this file's
+      // scope would point the inclusion at the including file itself.
+      ASTEngine.RelationshipType.MixesIn
+    ]);
+    for (const rel of ctx.relationships) {
+      if (!REWRITABLE.has(String(rel.type ?? ""))) continue;
+      const target = String(rel.target ?? "");
+      if (target.length === 0 || target.includes("::")) continue;
+      const qname = byName.get(target);
+      if (qname !== void 0) rel.target = qname;
+    }
+  }
+  // ── helpers ────────────────────────────────────────────────────────────────
+  lineOf(node) {
+    return node ? node.startPosition.row + 1 : void 0;
+  }
+  isErrorNode(node) {
+    return node.type === "ERROR" || node.isMissing === true;
+  }
+  findChild(node, predicate) {
+    for (let i = 0; i < node.namedChildCount; i++) {
+      const c = node.namedChild(i);
+      if (c && predicate(c)) return c;
+    }
+    return null;
+  }
+  findDescendant(node, predicate) {
+    const queue = [node];
+    while (queue.length > 0) {
+      const n = queue.shift();
+      if (predicate(n)) return n;
+      for (let i = 0; i < n.namedChildCount; i++) {
+        const c = n.namedChild(i);
+        if (c) queue.push(c);
+      }
+    }
+    return null;
+  }
+  /**
+   * The byte offset where an `@extend` statement's own selector stops.
+   *
+   * That is the first `;` at or after the statement starts, because `;` terminates the
+   * declaration the `@extend` belongs to and everything past it is the next declaration. A
+   * statement with no `;` is bounded by its own end.
+   *
+   * Returned as an OFFSET rather than used as a string test on the target, so a legitimate
+   * `@extend` whose target happens to contain `;`-adjacent punctuation is judged by position
+   * in the source and not by a shape.
+   */
+  extendTargetBound(node) {
+    const semi = String(node.text ?? "").indexOf(";");
+    return semi < 0 ? node.endIndex : node.startIndex + semi;
+  }
+  /**
+   * Every strict descendant matching `predicate`, in tree order.
+   *
+   * Needed where `findDescendant`'s breadth-first FIRST match is the wrong node: on a
+   * broken `@extend` the first match is a `class_selector` spanning the rest of the region
+   * and the real referent is a `placeholder` nested inside it (see `extendedSelectorName`).
+   * Depth-first, so the innermost usable node is preferred over a shallower one.
+   */
+  descendants(node, predicate) {
+    const out = [];
+    const stack = [node];
+    while (stack.length > 0) {
+      const n = stack.pop();
+      for (let i = n.namedChildCount - 1; i >= 0; i--) {
+        const c = n.namedChild(i);
+        if (!c) continue;
+        if (predicate(c)) out.push(c);
+        stack.push(c);
+      }
+    }
+    return out;
+  }
+  nodeToRange(node) {
+    return {
+      startLine: node.startPosition.row + 1,
+      startColumn: node.startPosition.column,
+      endLine: node.endPosition.row + 1,
+      endColumn: node.endPosition.column,
+      startIndex: node.startIndex,
+      endIndex: node.endIndex
+    };
+  }
+  childForField(node, field) {
+    return node.childForFieldName(field);
+  }
+  /**
+   * The innermost PUBLISHED symbol whose range contains `node` — i.e. the rule,
+   * mixin or function this statement sits inside.
+   *
+   * WHY A RANGE LOOKUP AND NOT A TRACKED VARIABLE. The first version threaded an
+   * `owner` argument through the walk, the way the CSS analyzer threads
+   * `currentSelector`, and it produced three fabrications in one file:
+   *
+   *     uses  button -> @mixin button     (source was the mixin NAME)
+   *     uses  .btn -> .btn                 (source was its own target)
+   *     references  color: $brand; -> $brand   (source was raw declaration text)
+   *
+   * All three have a source that is not an entity. The reason is that a tracked
+   * variable only advances for the node types the walker recognises, and a `rule_set`
+   * carrying an `@include` is not one of them — so inside any ordinary rule the owner
+   * was empty and each edge fell back to something adjacent.
+   *
+   * Looking the owner up by RANGE fixes all three at once and, more importantly, makes
+   * the edge name the SAME symbol the CSS lane published for that rule. Recomputing a
+   * selector name here would be a second implementation of the CSS lane's naming —
+   * including its `&`-chain resolution — and two implementations of a naming rule is
+   * how a graph ends up with `.card` on one side of an edge and `div .card` on the
+   * other. Innermost wins, so a declaration inside a rule inside a mixin is owned by the
+   * rule, and a statement directly in a mixin body is owned by the mixin.
+   */
+  ownerForNode(node, ctx) {
+    const start = node.startIndex;
+    const idx = this.ownerIndexOf(ctx);
+    const pick = {
+      entry: null,
+      span: Number.POSITIVE_INFINITY,
+      orig: Number.POSITIVE_INFINITY
+    };
+    const consider = (e) => {
+      if (start < e.start || start >= e.end) return;
+      const span = e.end - e.start;
+      if (span < pick.span || span === pick.span && e.orig < pick.orig) {
+        pick.span = span;
+        pick.entry = e;
+        pick.orig = e.orig;
+      }
+    };
+    let lo = 0;
+    let hi = idx.sorted.length - 1;
+    let j = -1;
+    while (lo <= hi) {
+      const mid = lo + hi >> 1;
+      if (idx.sorted[mid].start <= start) {
+        j = mid;
+        lo = mid + 1;
+      } else hi = mid - 1;
+    }
+    for (let i = j; i >= 0; i--) {
+      if (idx.maxEnd[i] <= start) break;
+      consider(idx.sorted[i]);
+    }
+    for (const e of idx.tail) consider(e);
+    return pick.entry ? pick.entry.sym.name : "";
+  }
+  /**
+   * Build (or grow) the interval index `ownerForNode` reads. Rebuilds happen when the un-indexed
+   * tail grows past 32 entries, and whenever the identity guard sees the array reordered — so the
+   * index can only ever be a faster spelling of the scan it replaced.
+   */
+  ownerIndexOf(ctx) {
+    const symbols = ctx.symbols;
+    let idx = ctx.ownerIndex;
+    if (!idx || idx.len > 0 && (idx.len > symbols.length || symbols[idx.len - 1] !== idx.lastSeen)) {
+      idx = ctx.ownerIndex = { len: 0, lastSeen: void 0, sorted: [], maxEnd: [], tail: [] };
+    }
+    if (symbols.length === idx.len) return idx;
+    for (let i = idx.len; i < symbols.length; i++) {
+      const sym = symbols[i];
+      if (sym.metadata?.isScssModule) continue;
+      const r = sym.range;
+      if (!r || typeof r.startIndex !== "number" || typeof r.endIndex !== "number") continue;
+      idx.tail.push({ sym, orig: i, start: r.startIndex, end: r.endIndex });
+    }
+    idx.len = symbols.length;
+    idx.lastSeen = symbols[symbols.length - 1];
+    if (idx.tail.length > 32) {
+      idx.sorted = idx.sorted.concat(idx.tail).sort((a, b) => a.start - b.start || a.orig - b.orig);
+      idx.tail = [];
+      idx.maxEnd = new Array(idx.sorted.length);
+      let m = Number.NEGATIVE_INFINITY;
+      for (let i = 0; i < idx.sorted.length; i++) {
+        if (idx.sorted[i].end > m) m = idx.sorted[i].end;
+        idx.maxEnd[i] = m;
+      }
+    }
+    return idx;
+  }
+  /** The old linear scan, kept so the equivalence harness can compare against it (never used in the
+   *  analysis path). Any difference between this and `ownerForNode` is a regression. */
+  ownerForNodeLinear(node, ctx) {
+    const start = node.startIndex;
+    let best = null;
+    let bestSpan = Number.POSITIVE_INFINITY;
+    for (const sym of ctx.symbols) {
+      if (sym.metadata?.isScssModule) continue;
+      const r = sym.range;
+      if (!r || typeof r.startIndex !== "number" || typeof r.endIndex !== "number") continue;
+      if (start < r.startIndex || start >= r.endIndex) continue;
+      const span = r.endIndex - r.startIndex;
+      if (span < bestSpan) {
+        bestSpan = span;
+        best = sym;
+      }
+    }
+    return best ? best.name : "";
+  }
+  /**
+   * A declaration is published ONCE per name. `$brand: #f00` in three places is one
+   * variable that is assigned three times, and the CSS lane's identity ruling —
+   * `(kind, resolved name)`, scope retained as provenance — applies unchanged: a
+   * symbol that exists twice with one name is the identity collision this project has
+   * been removing all along, and `.scss` is full of re-assignments.
+   */
+  publishOnce(ctx, symbol, owner = "") {
+    const key = `${symbol.kind} ${symbol.name}`;
+    if (!ctx.published[key]) {
+      ctx.published[key] = true;
+      ctx.publishedOwner[key] = owner;
+      ctx.symbols.push(symbol);
+      return true;
+    }
+    if (ctx.publishedOwner[key] === owner) return false;
+    let n = 2;
+    while (ctx.published[`${key}#${n}`]) n++;
+    const disambiguated = { ...symbol, name: `${symbol.name}#${n}` };
+    ctx.published[`${key}#${n}`] = true;
+    ctx.publishedOwner[`${key}#${n}`] = owner;
+    ctx.symbols.push(disambiguated);
+    return true;
+  }
+  // ── the module's public surface: `exports` ─────────────────────────────────
+  /**
+   * A Sass module exports its top-level variables, mixins and functions, and nothing
+   * else — that is precisely what `@use 'this-file'` binds. An assignment inside a rule,
+   * a mixin, a function or a control-flow block is LOCAL and is not part of the surface.
+   *
+   * Measured over 4,394 admitted corpus files: 3,315 top-level `$` assignments naming
+   * 2,501 distinct variables, 30 of them private by the `-`/`_` rule, plus 308 mixin and
+   * 77 function declarations — so this emits roughly one edge per distinct public member
+   * of every stylesheet, which is the module-system pair with `imports`.
+   *
+   * BOTH ends resolve by construction: the source is this file's own module symbol and
+   * the target is a symbol this file publishes. That is the whole reason to model a
+   * module's surface as EDGES rather than as a convention: `@use 'a', 'b'` binds
+   * members from two files and nothing else in the graph can say which file offered a
+   * name.
+   */
+  emitModuleExports(ctx) {
+    const published = /* @__PURE__ */ new Set();
+    for (const sym of ctx.symbols) {
+      if (sym.metadata?.isScssModule) continue;
+      if (sym.metadata?.scssImportedFrom) continue;
+      if (sym.kind !== ASTEngine.SymbolKind.Variable && sym.kind !== ASTEngine.SymbolKind.Function) continue;
+      const isCallable = sym.kind === ASTEngine.SymbolKind.Function;
+      if (isCallable ? !sym.metadata?.scssCallable : !sym.metadata?.isScssVariable) continue;
+      if (sym.scope) continue;
+      const name = sym.name;
+      if (published.has(name)) continue;
+      if (isPrivateSassName(name)) {
+        published.add(name);
+        continue;
+      }
+      published.add(name);
+      ctx.relationships.push({
+        source: ctx.moduleName,
+        target: name,
+        type: ASTEngine.RelationshipType.Exports,
+        line_number: sym.range?.startLine ?? 1,
+        confidence: 1,
+        metadata: {
+          evidenceClass: "structural",
+          cssSpecific: true,
+          isScssModuleMember: true,
+          scssModule: ctx.moduleName
+        }
+      });
+      ctx.exports.push({
+        name,
+        kind: sym.kind,
+        range: sym.range,
+        visibility: "public",
+        metadata: { via: "sass-module-top-level", scssModule: ctx.moduleName }
+      });
+    }
+  }
+  // ── `overrides`: the one reassignment Sass itself calls an override ─────────
+  /**
+   * `$x: … !global` where `$x` was already assigned at this file's top level.
+   *
+   * This is the narrowest honest `overrides` in the language and every part of it is
+   * measured, because the wide readings are wrong:
+   *
+   *   * A SECOND `@mixin x` / `@function x`: 0 occurrences across 4,394 admitted files.
+   *     The branch exists and cannot fire on this corpus, which is a fact about the
+   *     corpus and not a claim that the construct does not exist.
+   *   * A plain same-scope reassignment: 203 occurrences, of which 171 READ the variable
+   *     they assign (`$_args: append($_args, …)` in bootstrap's `_functions.scss` is the
+   *     shape) — an accumulator mutating one binding, which is not the replacement of a
+   *     declaration and would be a fabricated edge. The other 32 are a `$x: 1; … $x: 2`
+   *     pair, which the lane's own identity ruling already collapses into ONE symbol, so
+   *     an edge between the two assignments would be a self-edge.
+   *   * `!global`: 7 occurrences, and it is the only one of the three that means what
+   *     `overrides` means. `!global` is the flag that reaches PAST the enclosing scope
+   *     and reassigns the binding outside it, so the prior declaration is replaced and
+   *     the two are different things. bootstrap's `_box-shadow.test.scss` is the model:
+   *     `$enable-shadows: false !global;` … `$enable-shadows: true !global;` … and a
+   *     final restore, three overrides of one module-level variable.
+   *
+   * The prior assignment must be a TOP-LEVEL one. `!global` beside a name that only
+   * exists inside another mixin CREATES a global rather than replacing one, and the 14
+   * `!global` assignments in element-plus that fail this test are exactly that.
+   *
+   * The edge runs from the scope that performs the assignment to the variable it
+   * replaces, with `overridesLine` carrying the replaced declaration's line, so a
+   * consumer does not have to infer it. `source` falls back to the module symbol for an
+   * assignment at the file's top level, which is the only case with no enclosing scope.
+   */
+  emitGlobalOverride(node, name, ctx) {
+    if (!this.hasVisibilityFlag(node, "global")) return;
+    const line = this.lineOf(node) ?? 0;
+    const prior = ctx.topLevelVarLines[name];
+    if (prior === void 0 || prior >= line) return;
+    const owner = this.ownerForNode(node, ctx) || ctx.moduleName;
+    if (!owner) return;
+    ctx.relationships.push({
+      source: owner,
+      target: name,
+      type: ASTEngine.RelationshipType.Overrides,
+      line_number: line,
+      confidence: 1,
+      metadata: {
+        evidenceClass: "structural",
+        cssSpecific: true,
+        isScssGlobalOverride: true,
+        overridesLine: prior,
+        scssFlagGlobal: true
+      }
+    });
+  }
+  // ── pass 1: declarations, so a use may precede its declaration ─────────────
+  collectDeclarations(root, ctx) {
+    const stack = [root];
+    while (stack.length > 0) {
+      const n = stack.pop();
+      if (this.isErrorNode(n)) continue;
+      if (n.type === "mixin_statement") {
+        const name = this.childForField(n, "name") ?? this.findChild(n, (c) => c.type === "identifier");
+        if (name) ctx.mixinNames[stripAllQuotes(name.text)] = mixinName(stripAllQuotes(name.text));
+      } else if (n.type === "function_statement") {
+        const name = this.childForField(n, "name") ?? this.findChild(n, (c) => c.type === "identifier");
+        if (name) ctx.functionNames[stripAllQuotes(name.text)] = functionName(stripAllQuotes(name.text));
+      } else if (n.type === "property_name" && n.text.startsWith("$") && n.parent?.type === "declaration") {
+        ctx.variableNames[n.text] = n.text;
+      } else if (n.type === "use_statement") {
+        const module = this.findChild(n, (c) => c.type === "string_value");
+        const ns = this.findChild(n, (c) => c.type === "plain_value" || c.type === "identifier");
+        if (module && ns) ctx.namespaces[stripAllQuotes(ns.text)] = stripAllQuotes(module.text);
+      }
+      if (n.type === "declaration" && !hasScopeAncestor(n)) {
+        const prop = this.findChild(n, (c) => c.type === "property_name");
+        const name = prop ? prop.text : "";
+        if (name.startsWith("$")) {
+          const line = n.startPosition.row + 1;
+          const seen = ctx.topLevelVarLines[name];
+          if (seen === void 0 || line < seen) ctx.topLevelVarLines[name] = line;
+        }
+      }
+      for (let i = 0; i < n.namedChildCount; i++) {
+        const c = n.namedChild(i);
+        if (c) stack.push(c);
+      }
+    }
+  }
+  // ── pass 2: the SCSS statements ────────────────────────────────────────────
+  /**
+   * @param recovered TRUE when this node sits inside a region the grammar could not read.
+   *   Threaded rather than recomputed because the read/call scan keeps its OWN notion of
+   *   recovery — it descends into errors on its own — and the two must agree. A claim the
+   *   outer walk reached by descending into a broken region and then handed to the inner
+   *   scan is recovered even though the inner scan arrived by a clean path, so the two are
+   *   OR'd, and that is what makes `scssRecoveredFromError` trustworthy rather than
+   *   merely present.
+   */
+  walk(node, ctx, recovered = false, limit = Number.POSITIVE_INFINITY) {
+    if (limit === Number.POSITIVE_INFINITY && node.namedChildCount > RECOVERY_CHILD_CAP) {
+      const tally = ctx.recoveryCap ??= { cap: RECOVERY_CHILD_CAP, errorNodes: 0, errorChildren: 0, visited: 0, skipped: 0 };
+      tally.errorNodes++;
+      tally.errorChildren += node.namedChildCount;
+      tally.visited += RECOVERY_CHILD_CAP;
+      tally.skipped += node.namedChildCount - RECOVERY_CHILD_CAP;
+      limit = RECOVERY_CHILD_CAP;
+    }
+    for (let i = 0; i < node.namedChildCount && i < limit; i++) {
+      const child = node.namedChild(i);
+      if (!child) continue;
+      if (this.isErrorNode(child)) {
+        this.processRecoveredExtend(child, ctx);
+        this.walk(child, ctx, true);
+        continue;
+      }
+      if (child.type === "at_rule") {
+        const kw = this.findChild(child, (c) => c.type === "at_keyword");
+        const keyword = kw ? kw.text.trim().toLowerCase() : "";
+        if (keyword === "@content") ctx.sawContent = true;
+        if (keyword === "@at-root") ctx.sawAtRoot = true;
+      }
+      switch (child.type) {
+        case "use_statement":
+        case "forward_statement":
+          this.processModuleStatement(child, ctx);
+          break;
+        case "mixin_statement":
+        case "function_statement":
+          this.processCallable(child, ctx);
+          break;
+        case "extend_statement":
+          this.processExtend(child, ctx);
+          break;
+        // The CSS delegate already published this statement's `imports` row. This case only
+        // RECORDS the specifiers whose shape is the Sass FILE-INCLUSION form, for the relabel
+        // that runs after the delegate's file-claim pass (see `relabelSassPartImports`).
+        case "import_statement":
+          this.processSassPartImport(child, ctx);
+          break;
+        case "at_root_statement":
+        case "debug_statement":
+        case "warn_statement":
+        case "error_statement":
+          if (child.type === "at_root_statement") ctx.sawAtRoot = true;
+          else ctx.sawDiagnostic = true;
+          break;
+        case "declaration":
+          this.processScssDeclaration(child, ctx);
+          this.emitVariableReadEdges(child, ctx, recovered);
+          break;
+        // A `$var` is also read in an `@include`'s ARGUMENT list and in a control
+        // flow's condition or iterable, and those are reads like any other:
+        // `@include button($brand, 8px)` reads `$brand`. The first version only
+        // looked inside `declaration`, so an argument read produced no edge and the
+        // variable looked write-only in the graph.
+        case "if_statement":
+        case "each_statement":
+        case "for_statement":
+        case "while_statement":
+          this.processControlFlow(child, ctx, this.ownerForNode(child, ctx));
+          this.emitVariableReadEdges(child, ctx, recovered);
+          break;
+        case "include_statement":
+          this.processInclude(child, ctx);
+          this.emitVariableReadEdges(child, ctx, recovered);
+          break;
+        // `@return` and an `@use … with (…)` configuration are the two remaining
+        // places a `$var` can be READ outside a declaration's value, and both were
+        // silent. The `return_statement` case was removed when the self-edge was
+        // fixed — the edge went, the read scan went with it because the two shared a
+        // case — and nothing replaced it.
+        //
+        // Measured: `element-plus/packages/theme-chalk/src/color/index.scss` reads
+        // `$red`, `$green` and `$blue` in a `@return rgb2hex(rgb($red, $green, $blue))`
+        // at L19, and the differential reported them MISSING. A function's own body
+        // variables were unreadable in the graph: the function published them, and
+        // nothing recorded that it consumed them.
+        case "return_statement":
+        case "use_statement":
+        case "forward_statement":
+          this.emitVariableReadEdges(child, ctx, recovered);
+          break;
+        default:
+          break;
+      }
+      this.walk(child, ctx, recovered);
+    }
+  }
+  ownerNameOf(node) {
+    const name = this.childForField(node, "name") ?? this.findChild(node, (c) => c.type === "identifier");
+    if (!name) return "";
+    const raw = stripAllQuotes(name.text);
+    return node.type === "function_statement" ? functionName(raw) : mixinName(raw);
+  }
+  // ── `@use` / `@forward` ─────────────────────────────────────────────────────
+  /**
+   * An `imports` edge, which is the ontology's type for exactly this — the same one
+   * the CSS lane uses for `@import` and for Sass `@use`/`@forward`.
+   *
+   * The `as` namespace is recorded on the ImportInfo because it is the part a
+   * consumer cannot recover from the module path: `@use 'sass:map' as map` and
+   * `@use 'sass:map' as m` are the same import and different graphs.
+   */
+  processModuleStatement(node, ctx) {
+    const moduleNode = this.findChild(node, (c) => c.type === "string_value");
+    if (!moduleNode) return;
+    const module = stripAllQuotes(moduleNode.text);
+    const nsNode = this.findChild(node, (c) => c.type === "plain_value" || c.type === "identifier");
+    const namespace = nsNode ? stripAllQuotes(nsNode.text) : void 0;
+    if (namespace) {
+      ctx.symbols.push({
+        name: namespace,
+        kind: ASTEngine.SymbolKind.Namespace,
+        range: this.nodeToRange(node),
+        scope: "",
+        visibility: "public",
+        complexity: 1,
+        metadata: { isAtRule: true, isScssModuleNamespace: true, scssModule: module, atKeyword: `@${node.type.replace("_statement", "")}` }
+      });
+    }
+    ctx.imports.push({
+      module,
+      isNamespaceImport: true,
+      alias: namespace,
+      path: module,
+      range: this.nodeToRange(node),
+      metadata: {
+        scssModuleType: node.type,
+        ...namespace ? { scssNamespace: namespace } : {}
+      }
+    });
+    if (ctx.projectIndex && namespace) {
+      this.resolveModuleImports(ctx, namespace, module, this.nodeToRange(node).startLine);
+    }
+  }
+  /**
+   * Resolve an imported module's public members from the project index and create
+   * exports edges from this file's module to those members.
+   * This allows `@use 'other' as ns` to make `ns.$var`, `ns.mixin()`, `ns.function()` resolvable.
+   */
+  resolveModuleImports(ctx, namespace, modulePath, importLine) {
+    if (!ctx.projectIndex) return;
+    const index = ctx.projectIndex;
+    if (modulePath.startsWith("sass:")) return;
+    const norm = (spelling) => normalizeModuleSpelling(spelling);
+    const want = norm(modulePath);
+    let targetTypeName;
+    if (want !== "") {
+      for (const typeName of index.typeMembers.keys()) {
+        if (norm(typeName) === want) {
+          targetTypeName = typeName;
+          break;
+        }
+      }
+    }
+    if (!targetTypeName) return;
+    const declared = index.typeMembers.get(targetTypeName);
+    const closedMembers = index.__closedMembers?.get(targetTypeName) ?? declared;
+    if (!closedMembers || closedMembers.size === 0) return;
+    let scopePrefix = "";
+    for (const sym of ctx.symbols) {
+      const q = String(sym.qualifiedName ?? "");
+      const sep2 = q.indexOf("::");
+      if (sep2 > 0) {
+        scopePrefix = q.slice(0, sep2);
+        break;
+      }
+    }
+    if (scopePrefix === "") {
+      const moduleSym = ctx.symbols.find((sym) => sym.metadata?.isScssModule === true);
+      const modulePath2 = String(moduleSym?.metadata?.scssModulePath ?? "");
+      if (modulePath2 !== "") scopePrefix = cssFileScopeOf(modulePath2);
+    }
+    for (const memberName of closedMembers) {
+      const qualifiedName = `${namespace}.${memberName}`;
+      const scopedName = scopePrefix === "" ? qualifiedName : `${scopePrefix}::${qualifiedName}`;
+      ctx.relationships.push({
+        source: ctx.moduleName,
+        target: scopedName,
+        type: ASTEngine.RelationshipType.Exports,
+        // THE EDGE'S OWN LINE, not a fabricated 0: the import statement's line is what the edge
+        // describes, and `0` is the sentinel this programme has refused everywhere else.
+        line_number: importLine ?? 0,
+        confidence: 1,
+        metadata: {
+          evidenceClass: "structural",
+          cssSpecific: true,
+          isScssModuleMember: true,
+          scssModule: ctx.moduleName,
+          scssNamespace: namespace,
+          scssImportedFrom: modulePath
+        }
+      });
+      ctx.symbols.push({
+        name: qualifiedName,
+        // the discriminator rides the PREFIX, never the name — the delegate's own rule
+        qualifiedName: scopedName,
+        kind: ASTEngine.SymbolKind.Variable,
+        // conservative; actual kind varies
+        range: { startLine: 1, startColumn: 0, endLine: 1, endColumn: 0, startIndex: 0, endIndex: 0 },
+        scope: "",
+        visibility: "public",
+        complexity: 1,
+        metadata: {
+          isScssVariable: true,
+          scssVariableName: qualifiedName,
+          scssNamespace: namespace,
+          scssImportedFrom: modulePath
+        }
+      });
+    }
+  }
+  // ── `@mixin` / `@function` ──────────────────────────────────────────────────
+  processCallable(node, ctx) {
+    const raw = node.type === "function_statement" ? this.childForField(node, "name") : this.childForField(node, "name");
+    const nameNode = raw ?? this.findChild(node, (c) => c.type === "identifier");
+    if (!nameNode) return;
+    const bare = stripAllQuotes(nameNode.text);
+    const published = node.type === "function_statement" ? functionName(bare) : mixinName(bare);
+    const parameters = this.readParameters(node);
+    this.publishOnce(ctx, {
+      name: published,
+      kind: ASTEngine.SymbolKind.Function,
+      range: this.nodeToRange(node),
+      scope: "",
+      visibility: "public",
+      // one step for the declaration, one per parameter, one for the body
+      complexity: 1 + parameters.length + (this.findChild(node, (c) => c.type === "block") ? 1 : 0),
+      ...parameters.length > 0 ? { parameters } : {},
+      metadata: {
+        isAtRule: true,
+        atKeyword: node.type === "function_statement" ? "@function" : "@mixin",
+        scssCallable: true,
+        ...node.type === "function_statement" ? { isScssFunction: true } : { isScssMixin: true },
+        parameterCount: parameters.length,
+        // whether the body returns a value — see the `@return` note above for why
+        // this is a flag and not an edge
+        ...this.findDescendant(node, (n) => n.type === "return_statement") ? { scssReturns: true } : {}
+      }
+    });
+  }
+  /**
+   * A mixin's or function's parameters, read from the `parameter` nodes.
+   *
+   * `defaultValue` is taken from the `default` FIELD rather than by slicing text, so
+   * a parameter whose default is itself an expression keeps the expression rather than
+   * a truncation of it.
+   */
+  // typed NON-optional on purpose: `UniversalSymbol["parameters"]` is
+  // `Parameter[] | undefined`, so returning it made every `.length` below a
+  // possible-undefined error and the fix would have been three `!` assertions. The
+  // empty case is a real empty list, not an absent one.
+  readParameters(node) {
+    const paramsNode = this.findChild(node, (c) => c.type === "parameters");
+    if (!paramsNode) return [];
+    const out = [];
+    for (let i = 0; i < paramsNode.namedChildCount; i++) {
+      const p = paramsNode.namedChild(i);
+      if (!p || p.type !== "parameter") continue;
+      const varNode = this.findChild(p, (c) => c.type === "variable");
+      if (!varNode) continue;
+      const dflt = this.childForField(p, "default");
+      out.push({
+        name: stripAllQuotes(varNode.text),
+        ...dflt ? { defaultValue: stripAllQuotes(dflt.text) } : {}
+      });
+    }
+    return out;
+  }
+  // ── `@include` ──────────────────────────────────────────────────────────────
+  /**
+   * `@include` — A MIXIN COMPOSITION, PUBLISHED AS `mixes_in`.
+   *
+   * THE CONSTRUCT IS THE VOCABULARY'S MIXIN APPLICATION: a rule (or the module, for a top-level
+   * include) composes a named mixin's body into itself. It is NOT `extends` (there is no
+   * inheritance clause), NOT `implements` (no conformance is declared) and NOT `calls` (the
+   * ontology's own measured population for this type is a composition row — ruby relabelled its
+   * include/extend/prepend from `calls` to `mixes_in` for exactly this reason, and php's trait-use
+   * rows are the second precedent). `@extend` is this lane's `extends`; conflict rules keep the
+   * two apart.
+   *
+   * THE TARGET IS THE WRITTEN MIXIN NAME IN THE LANE'S PUBLISHED SPELLING, `@mixin <name>`, for
+   * EVERY clean include — not only the ones this file declares. The old version published a `calls`
+   * row only when the callee resolved IN THE FILE, which measured 48 of 132 clean includes on a
+   * 247-file screen: an include of a mixin that `@use`/`@import` brought in produced NOTHING, and
+   * the relation was invisible for 64% of the construct's sites. A target that names another
+   * file's mixin is UNRESOLVED rather than absent — the arbiter resolves it through the project
+   * index the way it resolves an `imports` specifier, and the same-file case is respelled to
+   * `<scope>::@mixin <name>` by `publishScssFileScopedIdentities`.
+   *
+   * THE NAMESPACED FORM IS A MEASURED WALL, NOT AN EDGE WE CAN NAME. The served build splits
+   * `@include ns.mixin` at the dot — the `include_statement` closes with a MISSING `;` and the
+   * dotted name lands in an ERROR/selector sibling — so the MIXIN name is not a node this walk can
+   * read, and publishing `@mixin <namespace>` would be a FABRICATED target. This case returns and
+   * the site is COUNTED by `script/m14/scss-extended-census.ts` (`includeUnparsable`), with R2 (a
+   * grammar patch to accept a dotted callable path) named as the available remedy and NOT taken
+   * this round.
+   */
+  processInclude(node, ctx) {
+    const includeText = String(node.text ?? "");
+    const complete = includeStatementIsComplete(includeText);
+    if (!complete) return;
+    const nameNode = this.findChild(node, (c) => c.type === "identifier" || c.type === "plain_value");
+    if (!nameNode) return;
+    const bare = stripAllQuotes(nameNode.text).trim();
+    if (bare.length === 0 || bare.includes(".")) return;
+    const owner = this.ownerForNode(node, ctx) || ctx.moduleName;
+    if (!owner) return;
+    if (!ctx.mixinNames[bare] && ctx.functionNames[bare]) {
+      ctx.relationships.push({
+        source: owner,
+        target: ctx.functionNames[bare],
+        type: ASTEngine.RelationshipType.Calls,
+        line_number: this.lineOf(nameNode),
+        metadata: { evidenceClass: "usage_contextual", cssSpecific: true, isScssInclude: true }
+      });
+      return;
+    }
+    const sameFileMixin = ctx.mixinNames[bare] !== void 0;
+    ctx.relationships.push({
+      source: owner,
+      target: mixinName(bare),
+      type: ASTEngine.RelationshipType.MixesIn,
+      line_number: this.lineOf(nameNode),
+      // `structural`: the relation is a syntactic declaration-header construct (the keyword plus
+      // the written name), not a name-resolution guess. The tier follows the CONSTRUCT, the same
+      // rule php recorded when its trait-use rows moved off `usage_contextual`.
+      metadata: {
+        evidenceClass: "structural",
+        cssSpecific: true,
+        isScssInclude: true,
+        mixinComposition: true,
+        ...sameFileMixin ? {} : { mixinDeclaredInFile: false }
+      }
+    });
+  }
+  /**
+   * RECORD the specifiers whose `@import` shape is the Sass FILE-INCLUSION form.
+   *
+   * THE SHAPE IS THE WHOLE DISCRIMINATOR, and it is a tree fact rather than a string guess:
+   *   `@import "x";`          → import_statement with EXACTLY ONE named child, a `string_value`
+   *   `@import url("x.css")`  → the child is a `call_expression`             (stylesheet load)
+   *   `@import "x" screen`    → a second named child (the media query)        (stylesheet load)
+   *   `@import "x.css";`      → one string_value whose TEXT is a CSS file     (stylesheet load)
+   * so the Sass form is: one string_value child AND a specifier that is not a `.css` file, not a
+   * protocol/`//` URL, not `sass:` (built-in module) and not `data:`. The relabel itself runs after
+   * the delegate's file-claim pass; this method only collects the set.
+   */
+  processSassPartImport(node, ctx) {
+    const named = [];
+    for (let i = 0; i < node.namedChildCount; i++) {
+      const c = node.namedChild(i);
+      if (c) named.push(c);
+    }
+    if (named.length !== 1 || named[0].type !== "string_value") return;
+    const spec = stripAllQuotes(named[0].text).trim();
+    if (spec.length === 0) return;
+    if (hasCssFileExtension(spec)) return;
+    const lower = spec.toLowerCase();
+    if (lower.startsWith("//") || lower.startsWith("http://") || lower.startsWith("https://")) return;
+    if (lower.startsWith("sass:") || lower.startsWith("data:")) return;
+    ctx.sassPartImports.add(spec);
+  }
+  /**
+   * MOVE the Sass-form `imports` rows to `part_of`. A LABEL MOVE, NOT A GAIN OR A LOSS: the row's
+   * source, target, line and the delegate's `metadata.importProjectFile` claim are unchanged; only
+   * the type moves, plus the mandatory `partRole` and the structural evidence class. The fixture
+   * suite pins the move in both directions and the census counts the sites, so a reader can check
+   * that nothing vanished.
+   */
+  relabelSassPartImports(ctx) {
+    if (ctx.sassPartImports.size === 0) return;
+    for (const r of ctx.relationships) {
+      if (r.type !== ASTEngine.RelationshipType.Imports) continue;
+      const target = String(r.target ?? "");
+      if (!ctx.sassPartImports.has(target)) continue;
+      r.type = ASTEngine.RelationshipType.PartOf;
+      r.metadata = {
+        ...r.metadata ?? {},
+        // MANDATORY ON EVERY part_of ROW (the vocabulary contract): this file is the LIBRARY —
+        // it carries the directive and names the part it includes.
+        partRole: "library",
+        isSassPartImport: true,
+        evidenceClass: "structural"
+      };
+    }
+  }
+  // ── `@return`: a FACT ABOUT A FUNCTION, NOT AN EDGE ─────────────────────────
+  //
+  // There is deliberately no `@return` handling here. The first version emitted
+  // `contains` from the function to ITSELF, which is a self-edge: it makes a
+  // relationship count look like evidence while connecting nothing, and `contains`
+  // between a thing and itself is not a claim any consumer can use.
+  //
+  // A `@return` names no entity. It says the function produces a value, which is a
+  // property of the function, so it is recorded as one — see `scssReturns` on the
+  // function symbol in `processCallable`, which is where it belongs.
+  // ── `@extend` ───────────────────────────────────────────────────────────────
+  processExtend(node, ctx) {
+    this.emitExtend(node, node, node, ctx, false);
+  }
+  /**
+   * The `@extend` INSIDE A RULE BODY, which is 63 of the 99 `@extend` statements in the
+   * corpus and every one of them was invisible.
+   *
+   * This is a grammar fact and it is worth stating exactly, because it is not a defect
+   * in the analyzer's walk. The `extend_statement` RULE is written for a top-level
+   * `@extend`; nested inside a `block` the same text parses as
+   *
+   *     block > ERROR > "@extend", placeholder, ";", ERROR("or", ":", …)
+   *
+   * — so the statement's own node type never appears, the keyword survives only as an
+   * ANONYMOUS token, and the walk (which visits named children) never sees either.
+   * Measured: 125 `@extend` tokens across 4,394 admitted files and only 36
+   * `extend_statement` nodes, so 89 of them — 71% — are in the recovered shape and 63 of
+   * the 99 real `@extend`s (`.card { @extend %badge; }`, which is where a BEM codebase
+   * puts nearly all of them) were producing no edge at all.
+   *
+   * The recognition is by the KEYWORD, not by shape: the first non-whitespace child is
+   * the anonymous token `@extend`. Checking for "an ERROR with a selector in it" would
+   * fire on every broken declaration, and checking node types would check for the type
+   * that is absent.
+   *
+   * The edge is marked `scssRecoveredFromError` because it is read out of a region the
+   * grammar gave up on, and the rest of this lane marks recovered claims the same way
+   * (see `emitVariableReadEdges`). Both ends still resolve: the owner is a rule this
+   * file publishes and the target is a selector this file publishes.
+   */
+  processRecoveredExtend(node, ctx) {
+    if (!this.isErrorNode(node)) return;
+    let keywordSeen = false;
+    for (let i = 0; i < node.childCount; i++) {
+      const c = node.child(i);
+      if (!c) continue;
+      if (c.type === "@extend") {
+        keywordSeen = true;
+        break;
+      }
+      if (!c.isNamed || c.type === "comment") continue;
+      return;
+    }
+    if (!keywordSeen) return;
+    let ruleAncestor = null;
+    for (let p = node.parent; p; p = p.parent) {
+      if (p.type === "rule_set") {
+        ruleAncestor = p;
+        break;
+      }
+    }
+    const ownerNode = ruleAncestor ?? node;
+    const lineNode = node;
+    this.emitExtend(node, ownerNode, lineNode, ctx, true);
+  }
+  emitExtend(targetNode, ownerNode, lineNode, ctx, recovered) {
+    const found = this.extendedSelectorName(targetNode);
+    if (!found) return;
+    const target = found.name;
+    const owner = this.ownerForNode(ownerNode, ctx);
+    if (!owner) return;
+    ctx.relationships.push({
+      source: owner,
+      target,
+      type: ASTEngine.RelationshipType.Extends,
+      line_number: this.lineOf(lineNode),
+      metadata: {
+        evidenceClass: "structural",
+        cssSpecific: true,
+        isScssExtend: true,
+        ...recovered ? { scssRecoveredFromError: true, scssExtendShape: "recovered" } : {},
+        // The TARGET was read out of a node the grammar built across a damaged region, not
+        // off the selector the statement names. That is a different claim from the statement
+        // having been recovered, and the lane already marks the statement, so it marks this
+        // too rather than letting a consumer read a repaired edge as a clean one. It is not
+        // a confidence reduction: the referent is a `placeholder` node the parser produced,
+        // which is a parse fact either way, and the contract asks for a confidence consistent
+        // with how the edge was DERIVED, not with how much text was damaged around it.
+        //
+        // It also makes the pre-fix defect reproducible from the RESULT, which is what lets
+        // `scss/extend-target-carries-statement-delimiter` be a faithful mutant. Without the
+        // mark, a mutant keyed on "target carries a delimiter" can never fire — the fixed
+        // analyzer emits none — and a mutant that cannot fire is a green that means nothing.
+        ...found.recoveredTarget ? { scssExtendTargetRecoveredFromBrokenNode: true } : {}
+      }
+    });
+  }
+  /**
+   * The selector an `@extend` names, in the spelling the lane publishes selectors.
+   *
+   * Built by SLICING the node's own text rather than by assembling it from node types,
+   * for the reason the CSS lane gives for at-rule preludes: a type list has to be
+   * maintained against the grammar by hand and goes stale the moment the grammar moves.
+   * `.btn` comes out as `.btn`, which is the class symbol the same file publishes.
+   */
+  extendedSelectorName(node) {
+    const candidates = this.descendants(
+      node,
+      (n) => n.type === "class_selector" || n.type === "id_selector" || n.type === "plain_value" || n.type === "placeholder"
+    );
+    if (candidates.length === 0) return void 0;
+    const sel = candidates[candidates.length - 1];
+    const bound = sel.endIndex;
+    const name = collapseWhitespace(sel.text);
+    let recoveredTarget = false;
+    if (containsStatementDelimiter(name)) {
+      const inner = this.descendants(
+        sel,
+        (n) => n.startIndex < bound && n.type === "placeholder" && isReadablePlaceholder(collapseWhitespace(n.text))
+      );
+      if (inner.length > 0) return { name: collapseWhitespace(inner[0].text), recoveredTarget: true };
+      return void 0;
+    }
+    if (name.startsWith("%") && !isReadablePlaceholder(name)) return void 0;
+    const hasPlaceholder = candidates.some((c) => c.type === "placeholder");
+    const hasClassSelector = candidates.some((c) => c.type === "class_selector" || c.type === "id_selector" || c.type === "plain_value");
+    if (!hasPlaceholder && hasClassSelector && (sel.type === "class_selector" || sel.type === "id_selector" || sel.type === "plain_value")) {
+      const extendKeywordEnd = node.text?.indexOf("@extend") + 7;
+      if (extendKeywordEnd > 0 && sel.startIndex > node.startIndex + extendKeywordEnd + 2) {
+        return void 0;
+      }
+    }
+    if (sel.type === "plain_value" || sel.type === "variable") {
+      for (let p = sel.parent; p && p !== node; p = p.parent) {
+        if (p.type === "interpolation") {
+          return void 0;
+        }
+      }
+    }
+    if (candidates.length > 1) {
+      let shallowest = candidates[0];
+      let minDepth = 0;
+      for (const c of candidates) {
+        let depth = 0;
+        for (let p = c.parent; p && p !== node; p = p.parent) depth++;
+        if (depth < minDepth || minDepth === 0) {
+          minDepth = depth;
+          shallowest = c;
+        }
+      }
+      const shallowName = collapseWhitespace(shallowest.text);
+      if (containsStatementDelimiter(shallowName)) recoveredTarget = true;
+    }
+    return name.length > 0 ? { name, recoveredTarget } : void 0;
+  }
+  // ── `@if` / `@each` / `@for` / `@while` ──────────────────────────────────────
+  /**
+   * A control-flow construct is an `interface` — the same shape the CSS lane gives
+   * `@supports`, and for the same reason: it is a CONDITIONAL SCOPE that publishes
+   * symbols and attributes rules to them, not a declaration of a callable.
+   *
+   * The scope is named from the construct's own text, collapsed to one line so a
+   * multi-line `@each` still yields a stable symbol name (M60 R10 — a target must be
+   * spelled the way the lane spells its own symbols, deterministically).
+   */
+  processControlFlow(node, ctx, owner) {
+    const keyword = node.type.replace("_statement", "");
+    const raw = collapseWhitespace(node.text.split("{")[0] ?? node.text);
+    const atKeyword = `@${keyword}`;
+    const prelude = raw.startsWith(atKeyword) ? raw.slice(atKeyword.length).trim() : raw;
+    const name = `${atKeyword} ${prelude}`;
+    if (name.length <= `@${keyword} `.length) return;
+    this.publishOnce(
+      ctx,
+      {
+        name,
+        kind: ASTEngine.SymbolKind.Interface,
+        range: this.nodeToRange(node),
+        scope: "",
+        visibility: "public",
+        // one step for the condition, one for each loop/branch variable, one for the body
+        complexity: 1 + this.countDescendantTypes(node, /* @__PURE__ */ new Set(["variable", "block"])),
+        metadata: {
+          isAtRule: true,
+          atKeyword: `@${keyword}`,
+          isScssControlFlow: true,
+          // the loop variables are recorded by name: `@each $k, $v in $map` is the one
+          // place a stylesheet says what it is iterating, and dropping it loses the only
+          // statement of intent the construct makes
+          ...node.type === "each_statement" ? {
+            scssEachKey: this.fieldText(node, "key"),
+            scssEachValue: this.fieldText(node, "value")
+          } : {},
+          ...node.type === "for_statement" ? { scssForFrom: this.fieldText(node, "from"), scssForThrough: this.fieldText(node, "through") } : {},
+          ...node.type === "if_statement" ? { scssCondition: this.fieldText(node, "condition") } : {},
+          ...owner ? { scssOwner: owner } : {}
+        }
+      },
+      // owner AND line: see the note on `publishOnce`
+      `${owner}@${this.lineOf(node) ?? 0}`
+    );
+  }
+  fieldText(node, field) {
+    const c = this.childForField(node, field);
+    return c ? stripAllQuotes(c.text) : void 0;
+  }
+  countDescendantTypes(node, types) {
+    let n = 0;
+    const stack = [node];
+    while (stack.length > 0) {
+      const cur = stack.pop();
+      if (types.has(cur.type)) n++;
+      for (let i = 0; i < cur.namedChildCount; i++) {
+        const c = cur.namedChild(i);
+        if (c) stack.push(c);
+      }
+    }
+    return n;
+  }
+  // ── declarations: `$var: value` and `$var` reads ─────────────────────────────
+  /**
+   * A `$var: value` declaration publishes a `variable` symbol, deduplicated by name.
+   *
+   * The CSS lane's identity ruling applies unchanged, and `.scss` is where it matters
+   * most: a Sass variable is assigned in several places by design — a `!default` at the
+   * top and an override inside a theme — and publishing one symbol per assignment is
+   * the identity collision this project has spent the wave removing.
+   *
+   * The FIRST occurrence's range wins, so the symbol points at where the variable is
+   * introduced rather than at its last override.
+   */
+  processScssDeclaration(node, ctx) {
+    const prop = this.findChild(node, (c) => c.type === "property_name");
+    if (!prop) return;
+    const name = prop.text;
+    if (!name.startsWith("$")) return;
+    if (!ctx.variableNames[name]) ctx.variableNames[name] = name;
+    this.emitGlobalOverride(node, name, ctx);
+    const owner = this.ownerForNode(node, ctx);
+    this.publishOnce(ctx, {
+      name,
+      kind: ASTEngine.SymbolKind.Variable,
+      range: this.nodeToRange(node),
+      scope: owner,
+      visibility: "public",
+      complexity: 1 + this.countDescendantTypes(node, /* @__PURE__ */ new Set(["binary_expression", "call_expression", "map", "list"])),
+      metadata: {
+        isScssVariable: true,
+        scssVariableName: name,
+        ...owner ? { scssOwner: owner } : {},
+        // `!default` and `!global` are the two flags that change what an assignment
+        // MEANS — a default is overridable, a global assignment leaks out of its
+        // scope — so they are recorded rather than parsed away.
+        ...this.hasVisibilityFlag(node, "default") ? { scssFlagDefault: true } : {},
+        ...this.hasVisibilityFlag(node, "global") ? { scssFlagGlobal: true } : {}
+      }
+    });
+  }
+  /**
+   * Whether a declaration carries `!default` or `!global`.
+   *
+   * The walk uses `childCount`/`child()`, NOT `namedChildCount`/`namedChild()`,
+   * because the flag is TWO ANONYMOUS NODES — the tree is
+   * `declaration > integer_value, "!", "default", ";"` with `!` and `default` both
+   * unnamed. The first version walked named children only, so it could never see
+   * them, the flag was silently always false, and 210 `!default` assignments in the
+   * corpus were recorded as carrying no flag at all.
+   *
+   * Found by `variables-flags-and-identity`, which is the whole argument for writing
+   * a fixture's expectations from the CONTRACT: the analyzer agreed with itself the
+   * entire time, because nothing ever asked.
+   */
+  hasVisibilityFlag(node, flag) {
+    const stack = [node];
+    while (stack.length > 0) {
+      const n = stack.pop();
+      if (!n.isNamed && n.type === flag) return true;
+      for (let i = 0; i < n.childCount; i++) {
+        const c = n.child(i);
+        if (c) stack.push(c);
+      }
+    }
+    return false;
+  }
+  /**
+   * A `$var` READ becomes a `references` edge — the same class the CSS lane uses for
+   * `var(--x)`, and the same discipline: only variables THIS FILE declares get an
+   * edge, because a `$var` may arrive as a mixin parameter and inventing an endpoint
+   * for it is the phantom this lane removed once.
+   *
+   * The read is found by DESCENDANT walk from each declaration, so a read inside a
+   * nested value, a `calc()`, or an interpolated selector is found too.
+   */
+  emitVariableReadEdges(node, ctx, outerRecovered = false) {
+    const NESTED_STATEMENT = /* @__PURE__ */ new Set([
+      "declaration",
+      "block",
+      "rule_set",
+      "mixin_statement",
+      "function_statement",
+      "if_statement",
+      "each_statement",
+      "for_statement",
+      "while_statement",
+      "include_statement",
+      "use_statement",
+      "forward_statement",
+      "return_statement",
+      "extend_statement"
+    ]);
+    const stack = [{ node, recovered: outerRecovered }];
+    while (stack.length > 0) {
+      const { node: n, recovered } = stack.pop();
+      if (this.isErrorNode(n)) {
+        for (let i = 0; i < n.namedChildCount; i++) {
+          const c = n.namedChild(i);
+          if (c && !NESTED_STATEMENT.has(c.type)) stack.push({ node: c, recovered: true });
+        }
+        continue;
+      }
+      if (n.type === "variable" && ctx.variableNames[n.text]) {
+        const owner = this.ownerForNode(n, ctx);
+        if (!owner) continue;
+        ctx.relationships.push({
+          source: owner,
+          target: n.text,
+          type: ASTEngine.RelationshipType.References,
+          line_number: this.lineOf(n),
+          metadata: {
+            evidenceClass: "usage_contextual",
+            cssSpecific: true,
+            isScssVarRef: true,
+            ...recovered ? { scssRecoveredFromError: true } : {}
+          }
+        });
+      }
+      if (n.type === "call_expression") {
+        const fn = this.findChild(n, (c) => c.type === "function_name");
+        const declared = fn ? ctx.functionNames[stripAllQuotes(fn.text)] : void 0;
+        if (fn && declared) {
+          const owner = this.ownerForNode(n, ctx);
+          if (owner) {
+            ctx.relationships.push({
+              source: owner,
+              target: declared,
+              type: ASTEngine.RelationshipType.Calls,
+              line_number: this.lineOf(n),
+              metadata: {
+                evidenceClass: "usage_contextual",
+                cssSpecific: true,
+                isScssFunctionCall: true,
+                ...recovered ? { scssRecoveredFromError: true } : {}
+              }
+            });
+          }
+        }
+      }
+      for (let i = 0; i < n.namedChildCount; i++) {
+        const c = n.namedChild(i);
+        if (c && !NESTED_STATEMENT.has(c.type)) stack.push({ node: c, recovered });
+      }
+    }
+  }
+};
+export {
+  RealScssAnalyzer
+};