@ontrails/warden 1.0.0-beta.13 → 1.0.0-beta.15

package/dist/rules/ast.js

@@ -4,7 +4,11 @@
  * Uses oxc-parser for native-speed TypeScript parsing. Provides a lightweight
  * walker and helpers for finding trail implementation bodies.
  */
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { DRAFT_ID_PREFIX } from '@ontrails/core';
 import { parseSync } from 'oxc-parser';
+const isAstNode = (value) => Boolean(value && typeof value === 'object' && value.type);
 // ---------------------------------------------------------------------------
 // Parser
 // ---------------------------------------------------------------------------
@@ -62,7 +66,7 @@ const walkScopeInner = (node, visit) => {
 /**
  * Walk an AST node tree without descending into nested function scopes.
  * The root node is always traversed; only inner function boundaries are skipped.
- * Useful for provision-access analysis where inner functions may shadow
+ * Useful for resource-access analysis where inner functions may shadow
  * the trail context parameter name.
  */
 export const walkScope = (node, visit) => {
@@ -113,8 +117,181 @@ export const getStringValue = (node) => {
     const val = node.value;
     return typeof val === 'string' ? val : null;
 };
+/**
+ * Best-effort resolution of `const NAME = 'value'` declarations via regex.
+ *
+ * Returns the string value if a simple `const <name> = '...'` or `"..."` is
+ * found in the source. Returns null for anything more complex. Shared between
+ * warden rules that need to resolve identifier references to signal / trail
+ * IDs at lint time.
+ */
+export const deriveConstString = (name, sourceCode) => {
+    const pattern = new RegExp(`const\\s+${name}\\s*=\\s*(?:'([^']*)'|"([^"]*)")`);
+    const match = pattern.exec(sourceCode);
+    if (!match) {
+        return null;
+    }
+    return match[1] ?? match[2] ?? null;
+};
 /** Extract a string literal value, or null when the node is not a string. */
 export const extractStringLiteral = (node) => node && isStringLiteral(node) ? getStringValue(node) : null;
+/**
+ * Extract the cooked value from a `TemplateLiteral` with no interpolations
+ * (e.g. `` `entity.fallback` ``). Template literals with `${...}` expressions
+ * cannot be resolved at lint time and return null.
+ *
+ * Shared helper used by rules that accept both string literals and simple
+ * backtick-literal IDs (e.g. `valid-describe-refs`).
+ */
+const getSingleQuasi = (node) => {
+    const expressions = node['expressions'] ?? [];
+    if (expressions.length > 0) {
+        return null;
+    }
+    const quasis = node['quasis'] ?? [];
+    return quasis.length === 1 ? (quasis[0] ?? null) : null;
+};
+export const extractPlainTemplateLiteral = (node) => {
+    if (!node || node.type !== 'TemplateLiteral') {
+        return null;
+    }
+    const quasi = getSingleQuasi(node);
+    if (!quasi) {
+        return null;
+    }
+    const cooked = quasi.value
+        ?.cooked;
+    return typeof cooked === 'string' ? cooked : null;
+};
+/**
+ * Extract a string value from either a string literal or a plain template
+ * literal (no `${...}` expressions). Returns null for anything else.
+ */
+export const extractStringOrTemplateLiteral = (node) => extractStringLiteral(node) ?? extractPlainTemplateLiteral(node);
+/**
+ * Names of framework constants whose value is a draft-marker prefix literal.
+ *
+ * String literals that initialize a `const` declaration with one of these
+ * names are treated as the framework's own draft-marker declarations, not as
+ * draft-id usage. This list is intentionally small and explicit — adding a
+ * new framework draft-prefix constant requires updating this set.
+ */
+export const FRAMEWORK_DRAFT_PREFIX_CONSTANT_NAMES = new Set(['DRAFT_ID_PREFIX', 'DRAFT_FILE_PREFIX']);
+/**
+ * Exact string literal value allowed for framework draft-prefix constant
+ * declarations. Tightens the exemption so a future framework file cannot
+ * redeclare `DRAFT_ID_PREFIX = '_draft.something-else'` and accidentally
+ * suppress its own draft-id diagnostic.
+ */
+const FRAMEWORK_DRAFT_PREFIX_LITERAL = DRAFT_ID_PREFIX;
+/**
+ * Absolute paths of the two framework files allowed to declare the
+ * draft-prefix constants. Anchored against the rule module's own URL so the
+ * exemption is scoped to this package's real on-disk location — a consumer
+ * repository that happens to declare `const DRAFT_ID_PREFIX = '_draft.leak'`
+ * anywhere else cannot hide a genuine leak by matching the identifier name.
+ *
+ * The two framework files are:
+ *  - `packages/core/src/draft.ts`   (defines `DRAFT_ID_PREFIX`)
+ *  - `packages/warden/src/draft.ts` (defines `DRAFT_FILE_PREFIX`)
+ */
+const FRAMEWORK_DRAFT_CONSTANT_FILES = new Set([
+    resolve(fileURLToPath(new URL('../../../core/src/draft.ts', import.meta.url))),
+    resolve(fileURLToPath(new URL('../draft.ts', import.meta.url))),
+]);
+/**
+ * Collect the source offsets of string literals that initialize a framework
+ * draft-prefix constant declaration (e.g. `export const DRAFT_ID_PREFIX =
+ * '_draft.'`). Used by draft-awareness rules to skip their own marker
+ * constants.
+ *
+ * Exemption is gated on all three of:
+ *   1. The file's absolute path matches one of the two framework files that
+ *      actually define these constants.
+ *   2. The declaration name is `DRAFT_ID_PREFIX` or `DRAFT_FILE_PREFIX`.
+ *   3. The string literal value is exactly `'_draft.'`.
+ *
+ * A consumer file that reuses one of these identifier names cannot hide a
+ * `_draft.*` leak — the path gate rejects it outright.
+ */
+export const collectFrameworkDraftPrefixConstantOffsets = (ast, filePath) => {
+    const offsets = new Set();
+    if (!FRAMEWORK_DRAFT_CONSTANT_FILES.has(resolve(filePath))) {
+        return offsets;
+    }
+    walk(ast, (node) => {
+        if (node.type !== 'VariableDeclarator') {
+            return;
+        }
+        const { id, init } = node;
+        const name = identifierName(id);
+        if (!name ||
+            !FRAMEWORK_DRAFT_PREFIX_CONSTANT_NAMES.has(name) ||
+            !init ||
+            !isStringLiteral(init)) {
+            return;
+        }
+        if (getStringValue(init) !== FRAMEWORK_DRAFT_PREFIX_LITERAL) {
+            return;
+        }
+        offsets.add(init.start);
+    });
+    return offsets;
+};
+const WARDEN_IGNORE_NEXT_LINE_PRAGMA = '// warden-ignore-next-line';
+/**
+ * Split source code into lines for pragma lookups. Callers should split once
+ * per `check` invocation and thread the result through to
+ * {@link hasIgnoreCommentOnLine} so we avoid re-splitting the full source on
+ * every match in files with many draft-like string literals.
+ */
+export const splitSourceLines = (sourceCode) => sourceCode.split('\n');
+/**
+ * Check whether the line immediately preceding `line` contains a
+ * `// warden-ignore-next-line` pragma (leading/trailing whitespace tolerated).
+ * Pragma scope is strictly one line — an intervening blank line breaks it.
+ *
+ * Takes a pre-split `lines` array so callers can split the source once per
+ * invocation instead of re-splitting for every literal they check.
+ *
+ * @example
+ * ```ts
+ * // warden-ignore-next-line
+ * const x = '_draft.intentional'; // suppressed
+ * ```
+ */
+export const hasIgnoreCommentOnLine = (lines, line) => {
+    if (line <= 1) {
+        return false;
+    }
+    const previous = lines[line - 2];
+    if (previous === undefined) {
+        return false;
+    }
+    return previous.trim() === WARDEN_IGNORE_NEXT_LINE_PRAGMA;
+};
+export const findStringLiterals = (ast, predicate) => {
+    const matches = [];
+    walk(ast, (node) => {
+        if (!isStringLiteral(node)) {
+            return;
+        }
+        const value = getStringValue(node);
+        if (value === null) {
+            return;
+        }
+        if (predicate && !predicate(value, node)) {
+            return;
+        }
+        matches.push({
+            end: node.end,
+            node,
+            start: node.start,
+            value,
+        });
+    });
+    return matches;
+};
 /** Extract the first string argument from a CallExpression. */
 export const extractFirstStringArg = (node) => {
     if (node.type !== 'CallExpression') {
@@ -124,10 +301,10 @@ export const extractFirstStringArg = (node) => {
     const [firstArg] = args ?? [];
     return extractStringLiteral(firstArg);
 };
-const isProvisionCall = (node) => !!node &&
+const isResourceCall = (node) => !!node &&
     node.type === 'CallExpression' &&
     identifierName(node.callee) ===
-        'provision';
+        'resource';
 const extractBindingName = (node) => {
     if (!node) {
         return null;
@@ -140,30 +317,30 @@ const extractBindingName = (node) => {
     }
     return null;
 };
-/** Collect `const foo = provision('id', ...)` bindings from a parsed file. */
-export const collectNamedProvisionIds = (ast) => {
+/** Collect `const foo = resource('id', ...)` bindings from a parsed file. */
+export const collectNamedResourceIds = (ast) => {
     const ids = new Map();
     walk(ast, (node) => {
         if (node.type !== 'VariableDeclarator') {
             return;
         }
         const { id, init } = node;
-        if (!isProvisionCall(init)) {
+        if (!isResourceCall(init)) {
             return;
         }
         const name = extractBindingName(id);
-        const provisionId = init ? extractFirstStringArg(init) : null;
-        if (name && provisionId) {
-            ids.set(name, provisionId);
+        const resourceId = init ? extractFirstStringArg(init) : null;
+        if (name && resourceId) {
+            ids.set(name, resourceId);
         }
     });
     return ids;
 };
-/** Collect all inline `provision('id', ...)` definition IDs from a parsed file. */
-export const collectProvisionDefinitionIds = (ast) => {
+/** Collect all inline `resource('id', ...)` definition IDs from a parsed file. */
+export const collectResourceDefinitionIds = (ast) => {
     const ids = new Set();
     walk(ast, (node) => {
-        if (!isProvisionCall(node)) {
+        if (!isResourceCall(node)) {
             return;
         }
         const id = extractFirstStringArg(node);
@@ -174,12 +351,36 @@ export const collectProvisionDefinitionIds = (ast) => {
     return ids;
 };
 /** Backward-compatible aliases while the migration is in flight. */
-export const collectNamedServiceIds = collectNamedProvisionIds;
+export const collectNamedServiceIds = collectNamedResourceIds;
 /** Backward-compatible aliases while the migration is in flight. */
-export const collectServiceDefinitionIds = collectProvisionDefinitionIds;
+export const collectServiceDefinitionIds = collectResourceDefinitionIds;
 // ---------------------------------------------------------------------------
 // Config property extraction helpers
 // ---------------------------------------------------------------------------
+/**
+ * Extract the identifying name of a `Property` key, supporting both
+ * identifier keys (`{ foo: 1 }`) and string-literal keys
+ * (`{ "foo": 1 }`). Computed keys are intentionally not resolved — a
+ * computed expression could evaluate to anything and we only want to
+ * match keys that are statically equivalent to a plain identifier.
+ */
+const staticPropertyKeyName = (key) => {
+    if (key.type === 'Identifier') {
+        return key.name ?? null;
+    }
+    return isStringLiteral(key) ? getStringValue(key) : null;
+};
+const propertyKeyName = (prop) => {
+    if (prop.type !== 'Property') {
+        return null;
+    }
+    const { computed } = prop;
+    if (computed) {
+        return null;
+    }
+    const key = prop.key;
+    return key ? staticPropertyKeyName(key) : null;
+};
 /** Find a Property node by key name inside an ObjectExpression config. */
 export const findConfigProperty = (config, propertyName) => {
     if (config.type !== 'ObjectExpression') {
@@ -190,7 +391,7 @@ export const findConfigProperty = (config, propertyName) => {
         return null;
     }
     for (const prop of properties) {
-        if (prop.type === 'Property' && prop.key?.name === propertyName) {
+        if (propertyKeyName(prop) === propertyName) {
             return prop;
         }
     }
@@ -202,121 +403,1665 @@ export const findConfigProperty = (config, propertyName) => {
  *
  * Returns the trail ID, kind, and config object node for each definition.
  */
-const TRAIL_CALLEE_NAMES = new Set(['trail', 'signal']);
-const getTrailCalleeName = (node) => {
-    if (node.type !== 'CallExpression') {
-        return null;
+const TRAIL_CALLEE_NAMES = new Set(['signal', 'trail']);
+/**
+ * Source prefix for the Trails framework package whose namespace imports are
+ * recognized as carriers of `trail()` / `signal()` / `contour()` primitives.
+ *
+ * A namespaced callee like `core.trail(...)` is only treated as a framework
+ * call when the receiver identifier resolves to an `import * as core from
+ * '@ontrails/...'` in the same file. An unrelated `analytics.trail(...)`
+ * whose `analytics` comes from a different module (or no import at all)
+ * is ignored.
+ */
+const FRAMEWORK_NAMESPACE_SOURCE_PREFIX = '@ontrails/';
+const isFrameworkNamespaceSource = (value) => typeof value === 'string' &&
+    value.startsWith(FRAMEWORK_NAMESPACE_SOURCE_PREFIX);
+/**
+ * Collect local binding names introduced by `import * as <name> from
+ * '@ontrails/...'` declarations. Used to gate namespaced framework-primitive
+ * calls so an unrelated `analytics.trail(...)` doesn't match.
+ */
+const getImportSourceValue = (node) => {
+    const sourceNode = node.source;
+    return sourceNode
+        ? sourceNode.value
+        : undefined;
+};
+const addNamespaceImportBindings = (node, names) => {
+    const specifiers = node['specifiers'] ?? [];
+    for (const spec of specifiers) {
+        if (spec.type !== 'ImportNamespaceSpecifier') {
+            continue;
+        }
+        const { local } = spec;
+        const localName = identifierName(local);
+        if (localName) {
+            names.add(localName);
+        }
     }
-    const callee = node['callee'];
-    if (!callee || callee.type !== 'Identifier') {
-        return null;
+};
+const TOP_LEVEL_NAMED_DECL_TYPES = new Set([
+    'ClassDeclaration',
+    'FunctionDeclaration',
+    'TSEnumDeclaration',
+    'TSModuleDeclaration',
+]);
+const removeVarDeclarationShadowedNames = (stmt, names) => {
+    const declarations = stmt.declarations ??
+        [];
+    for (const d of declarations) {
+        const { id } = d;
+        const n = identifierName(id);
+        if (n) {
+            names.delete(n);
+        }
     }
-    const { name } = callee;
-    return name && TRAIL_CALLEE_NAMES.has(name) ? name : null;
 };
-/** Extract args from a trail() call, handling both two-arg and single-object forms. */
-const extractTrailArgs = (node) => {
-    const args = node['arguments'];
-    if (!args || args.length === 0) {
-        return null;
+const removeNamedDeclShadowedName = (stmt, names) => {
+    const { id } = stmt;
+    const n = identifierName(id);
+    if (n) {
+        names.delete(n);
     }
-    const [firstArg, secondArg] = args;
-    if (!firstArg) {
-        return null;
+};
+const removeTopLevelShadowedNames = (stmt, names) => {
+    if (stmt.type === 'ExportNamedDeclaration' ||
+        stmt.type === 'ExportDefaultDeclaration') {
+        const { declaration } = stmt;
+        if (declaration) {
+            removeTopLevelShadowedNames(declaration, names);
+        }
+        return;
     }
-    // Two-arg form: trail('id', { ... })
-    if (secondArg && firstArg.type !== 'ObjectExpression') {
-        return { configArg: secondArg, idArg: firstArg };
+    if (stmt.type === 'VariableDeclaration') {
+        removeVarDeclarationShadowedNames(stmt, names);
+        return;
+    }
+    if (TOP_LEVEL_NAMED_DECL_TYPES.has(stmt.type)) {
+        removeNamedDeclShadowedName(stmt, names);
     }
-    // Single-object form: trail({ id: 'x', ... })
-    return firstArg.type === 'ObjectExpression'
-        ? { configArg: firstArg, idArg: null }
-        : null;
 };
-/** Extract the string value from an `id` property inside a config ObjectExpression. */
-const extractIdFromConfig = (config) => {
-    const idProp = findConfigProperty(config, 'id');
-    if (!idProp || !idProp.value) {
-        return null;
+const collectFrameworkNamespaceBindings = (ast) => {
+    const names = new Set();
+    walk(ast, (node) => {
+        if (node.type !== 'ImportDeclaration') {
+            return;
+        }
+        if (!isFrameworkNamespaceSource(getImportSourceValue(node))) {
+            return;
+        }
+        addNamespaceImportBindings(node, names);
+    });
+    if (names.size === 0) {
+        return names;
     }
-    const val = idProp.value.value;
-    return typeof val === 'string' ? val : null;
+    // A same-named top-level declaration (class / enum / namespace / var /
+    // function / lexical binding) shadows the namespace import at module scope.
+    // The scope walker treats Program as the outermost frame and skips it when
+    // testing for inner shadows, so we have to strip these collisions here.
+    if (ast.type === 'Program') {
+        const body = ast.body ?? [];
+        for (const stmt of body) {
+            removeTopLevelShadowedNames(stmt, names);
+        }
+    }
+    return names;
 };
-const extractTrailId = (trailArgs) => {
-    if (trailArgs.idArg) {
-        return trailArgs.idArg.value ?? null;
+const expandAssignmentPattern = (node) => {
+    const { left } = node;
+    return left ? [left] : [];
+};
+const expandRestElement = (node) => {
+    const { argument } = node;
+    return argument ? [argument] : [];
+};
+const expandArrayPattern = (node) => {
+    const elements = node.elements ??
+        [];
+    return elements.filter((e) => e !== null);
+};
+const expandObjectPatternProperty = (prop) => {
+    if (prop.type === 'RestElement') {
+        return prop;
     }
-    return extractIdFromConfig(trailArgs.configArg);
+    const { value } = prop;
+    return value ?? null;
 };
-const extractTrailDefinition = (node) => {
-    const calleeName = getTrailCalleeName(node);
-    if (!calleeName) {
-        return null;
+const expandObjectPattern = (node) => {
+    const properties = node.properties ?? [];
+    return properties
+        .map(expandObjectPatternProperty)
+        .filter((n) => n !== null);
+};
+const PATTERN_EXPANDERS = {
+    ArrayPattern: expandArrayPattern,
+    AssignmentPattern: expandAssignmentPattern,
+    ObjectPattern: expandObjectPattern,
+    RestElement: expandRestElement,
+};
+const processPatternNode = (node, into, stack) => {
+    if (node.type === 'Identifier') {
+        const { name } = node;
+        if (name) {
+            into.add(name);
+        }
+        return;
     }
-    const trailArgs = extractTrailArgs(node);
-    if (!trailArgs) {
-        return null;
+    const expand = PATTERN_EXPANDERS[node.type];
+    if (expand) {
+        stack.push(...expand(node));
     }
-    const trailId = extractTrailId(trailArgs);
-    if (!trailId) {
-        return null;
+};
+const addPatternBindingNames = (pattern, into) => {
+    if (!pattern) {
+        return;
+    }
+    const stack = [pattern];
+    while (stack.length > 0) {
+        const node = stack.pop();
+        if (node) {
+            processPatternNode(node, into, stack);
+        }
     }
-    return {
-        config: trailArgs.configArg,
-        id: trailId,
-        kind: calleeName,
-        start: node.start,
-    };
 };
-export const findTrailDefinitions = (ast) => {
-    const definitions = [];
-    walk(ast, (node) => {
-        const def = extractTrailDefinition(node);
-        if (def) {
-            definitions.push(def);
+const addVarDeclarationBindingNames = (decl, into) => {
+    const declarations = decl.declarations ??
+        [];
+    for (const d of declarations) {
+        addPatternBindingNames(d.id, into);
+    }
+};
+const addFunctionOrClassBindingName = (node, into) => {
+    const { id } = node;
+    const name = identifierName(id);
+    if (name) {
+        into.add(name);
+    }
+};
+const addBlockStatementBindings = (stmt, into) => {
+    if (stmt.type === 'VariableDeclaration') {
+        addVarDeclarationBindingNames(stmt, into);
+        return;
+    }
+    if (stmt.type === 'FunctionDeclaration' ||
+        stmt.type === 'ClassDeclaration' ||
+        stmt.type === 'TSEnumDeclaration' ||
+        stmt.type === 'TSModuleDeclaration') {
+        addFunctionOrClassBindingName(stmt, into);
+    }
+};
+const collectTopLevelStatementBindings = (stmt, into) => {
+    if (stmt.type === 'ExportNamedDeclaration' ||
+        stmt.type === 'ExportDefaultDeclaration') {
+        const { declaration } = stmt;
+        if (declaration) {
+            collectTopLevelStatementBindings(declaration, into);
+        }
+        return;
+    }
+    addBlockStatementBindings(stmt, into);
+};
+const FUNCTION_BOUNDARY_TYPES = new Set([
+    'ArrowFunctionExpression',
+    'FunctionDeclaration',
+    'FunctionExpression',
+    'StaticBlock',
+]);
+const forEachAstChild = (node, visit) => {
+    for (const val of Object.values(node)) {
+        if (Array.isArray(val)) {
+            for (const item of val) {
+                if (item && typeof item === 'object' && item.type) {
+                    visit(item);
+                }
+            }
+        }
+        else if (val && typeof val === 'object' && val.type) {
+            visit(val);
+        }
+    }
+};
+const recordHoistedBinding = (node, into, inNestedBlock) => {
+    if (node.type === 'VariableDeclaration') {
+        const { kind } = node;
+        if (kind === 'var') {
+            addVarDeclarationBindingNames(node, into);
         }
+        return;
+    }
+    // In strict/module code, function/class/enum/module declarations inside a
+    // nested block (`if { function foo() {} }`, `switch` case, etc.) are
+    // block-scoped. Only hoist them to the enclosing function frame when they
+    // sit directly in the function body, not inside a further block.
+    if (inNestedBlock) {
+        return;
+    }
+    if (node.type === 'FunctionDeclaration' ||
+        node.type === 'ClassDeclaration' ||
+        node.type === 'TSEnumDeclaration' ||
+        node.type === 'TSModuleDeclaration') {
+        addFunctionOrClassBindingName(node, into);
+    }
+};
+const NESTED_BLOCK_BOUNDARY_TYPES = new Set([
+    'BlockStatement',
+    'ForStatement',
+    'ForInStatement',
+    'ForOfStatement',
+    'SwitchStatement',
+    'CatchClause',
+]);
+const visitForHoisted = (node, isRoot, into, inNestedBlock) => {
+    if (!isRoot && FUNCTION_BOUNDARY_TYPES.has(node.type)) {
+        return;
+    }
+    recordHoistedBinding(node, into, inNestedBlock);
+    const childInNestedBlock = inNestedBlock || (!isRoot && NESTED_BLOCK_BOUNDARY_TYPES.has(node.type));
+    forEachAstChild(node, (child) => {
+        visitForHoisted(child, false, into, childInNestedBlock);
     });
-    return definitions;
 };
-// ---------------------------------------------------------------------------
-// Blaze body extraction
-// ---------------------------------------------------------------------------
 /**
- * Extract top-level `blaze:` property values from an ObjectExpression's direct properties.
- *
- * Does not recurse into nested objects, so `meta: { blaze: ... }` is ignored.
+ * Collect `var` declarations and `function` declarations hoisted to the
+ * nearest function scope from anywhere inside `root`, without crossing a
+ * nested function or static-block boundary.
  */
-const extractBlazeFromConfig = (config) => {
-    const bodies = [];
-    const properties = config['properties'];
-    if (!properties) {
-        return bodies;
+const collectHoistedVarAndFunctionBindings = (root, into) => {
+    visitForHoisted(root, true, into, false);
+};
+const collectProgramFrame = (node, into) => {
+    const body = node.body ?? [];
+    for (const stmt of body) {
+        collectTopLevelStatementBindings(stmt, into);
     }
-    for (const prop of properties) {
-        if (prop.type === 'Property' && prop.key?.name === 'blaze' && prop.value) {
-            bodies.push(prop.value);
+};
+const collectFunctionFrame = (node, into) => {
+    const params = node.params ?? [];
+    for (const param of params) {
+        addPatternBindingNames(param, into);
+    }
+    // Hoisted vars and function declarations inside the body live in the
+    // function's var-environment. A `var ns = ...;` inside an `if` still
+    // shadows a module-level `ns` for the whole function.
+    const { body } = node;
+    if (body) {
+        collectHoistedVarAndFunctionBindings(body, into);
+    }
+};
+const collectBlockFrame = (node, into) => {
+    const body = node.body ?? [];
+    for (const stmt of body) {
+        addBlockStatementBindings(stmt, into);
+    }
+};
+const collectForStatementFrame = (node, into) => {
+    const { init } = node;
+    if (init && init.type === 'VariableDeclaration') {
+        addVarDeclarationBindingNames(init, into);
+    }
+};
+const collectForInOfFrame = (node, into) => {
+    const { left } = node;
+    if (left && left.type === 'VariableDeclaration') {
+        addVarDeclarationBindingNames(left, into);
+    }
+};
+const collectSwitchStatementFrame = (node, into) => {
+    // `switch` shares one scope across every case. A binding in one case
+    // shadows the namespace across sibling cases (fall-through or otherwise).
+    const cases = node.cases ?? [];
+    for (const c of cases) {
+        const consequent = c.consequent ?? [];
+        for (const stmt of consequent) {
+            addBlockStatementBindings(stmt, into);
         }
     }
-    return bodies;
+};
+const collectCatchClauseFrame = (node, into) => {
+    const { param } = node;
+    addPatternBindingNames(param, into);
+};
+const collectClassExpressionFrame = (node, into) => {
+    // A named `class expr` (`const C = class foo { ... }`) binds its own name
+    // inside its body only. ClassDeclaration names are hoisted into the
+    // enclosing block/program frame instead, so only class *expression* names
+    // need their own frame here.
+    addFunctionOrClassBindingName(node, into);
+};
+const SCOPE_FRAME_COLLECTORS = {
+    ArrowFunctionExpression: collectFunctionFrame,
+    BlockStatement: collectBlockFrame,
+    CatchClause: collectCatchClauseFrame,
+    ClassExpression: collectClassExpressionFrame,
+    ForInStatement: collectForInOfFrame,
+    ForOfStatement: collectForInOfFrame,
+    ForStatement: collectForStatementFrame,
+    // oxc-parser emits `FunctionBody` for `function` expression bodies; without
+    // this entry, a `const ns = ...` at the top of a function-expression body
+    // would not push a scope frame, and a module-level namespace import with
+    // the same name would be incorrectly recognized inside.
+    FunctionBody: collectBlockFrame,
+    FunctionDeclaration: collectFunctionFrame,
+    FunctionExpression: collectFunctionFrame,
+    Program: collectProgramFrame,
+    StaticBlock: collectBlockFrame,
+    SwitchStatement: collectSwitchStatementFrame,
 };
 /**
- * Find `blaze:` property values.
- *
- * When given an ObjectExpression (trail config), returns only its direct `blaze:`
- * properties. When given a full AST, finds trail definitions first and extracts
- * `blaze:` from each config — in both cases ignoring nested `blaze:` properties
- * (e.g. `meta: { blaze: ... }`).
+ * Collect the identifier bindings introduced *directly* by a scope frame
+ * node. Scope frames correspond to JS lexical scopes (function bodies, blocks,
+ * catch clauses, for-statements, switch statements, module/script roots).
  */
-export const findBlazeBodies = (node) => {
-    if (node.type === 'ObjectExpression') {
-        return extractBlazeFromConfig(node);
+export const collectScopeFrameBindings = (node) => {
+    const names = new Set();
+    const collector = SCOPE_FRAME_COLLECTORS[node.type];
+    if (collector) {
+        collector(node, names);
     }
-    // Full AST — find trail definitions and extract blaze from their configs
-    const bodies = [];
-    for (const def of findTrailDefinitions(node)) {
-        bodies.push(...extractBlazeFromConfig(def.config));
+    return names;
+};
+const asAstNode = (node) => {
+    if (!node || typeof node !== 'object') {
+        return null;
     }
-    return bodies;
+    const astNode = node;
+    return astNode.type ? astNode : null;
+};
+/**
+ * Walk an AST subtree while threading lexical scope bindings through each
+ * visit. Callers can seed outer scopes and optionally stop at nested function
+ * boundaries when only the current implementation body should be analyzed.
+ */
+export const walkWithScopes = (node, visit, options = {}) => {
+    const root = asAstNode(node);
+    if (!root) {
+        return;
+    }
+    const stack = [...(options.initialScopes ?? [])];
+    const walkNode = (current, isRoot) => {
+        if (!isRoot &&
+            options.stopAtNestedFunctions &&
+            FUNCTION_BOUNDARY_TYPES.has(current.type)) {
+            return;
+        }
+        const isScope = current.type in SCOPE_FRAME_COLLECTORS;
+        if (isScope) {
+            stack.unshift(collectScopeFrameBindings(current));
+        }
+        try {
+            visit(current, stack);
+            forEachAstChild(current, (child) => {
+                walkNode(child, false);
+            });
+        }
+        finally {
+            if (isScope) {
+                stack.shift();
+            }
+        }
+    };
+    walkNode(root, true);
+};
+const isShadowed = (receiverName, scopeStack) => {
+    // The module-level Program frame is the last entry and contains the
+    // namespace imports themselves. A "shadow" must come from a frame *inside*
+    // that one — i.e. any frame except the outermost.
+    for (let i = 0; i < scopeStack.length - 1; i += 1) {
+        const frame = scopeStack[i];
+        if (frame?.has(receiverName)) {
+            return true;
+        }
+    }
+    return false;
+};
+/**
+ * Return `true` when `node` is a non-computed member access (`a.b` /
+ * `a?.b`) and `false` for anything else, including computed access
+ * (`a[b]`) or non-member nodes. Exported as the canonical predicate so
+ * rule modules do not re-implement the check.
+ *
+ * @remarks
+ * Declared near the top of the file so the scope walker can use it
+ * without hitting `no-use-before-define`. A few sibling helpers in this
+ * module still inline the same shape under different local names for
+ * historical reasons; prefer this export for new call sites.
+ */
+export const isMemberAccessNonComputed = (node) => {
+    if (node.type !== 'MemberExpression' &&
+        node.type !== 'StaticMemberExpression') {
+        return false;
+    }
+    return node.computed !== true;
+};
+const resolveNamespacedMemberNames = (callee) => {
+    if (!isMemberAccessNonComputed(callee)) {
+        return null;
+    }
+    const { object } = callee;
+    const receiver = identifierName(object);
+    if (!receiver) {
+        return null;
+    }
+    const prop = callee.property;
+    const property = prop?.type === 'Identifier'
+        ? (prop.name ?? null)
+        : null;
+    return property ? { property, receiver } : null;
+};
+const getFrameworkCallReceiver = (node, frameworkNamespaces) => {
+    if (node.type !== 'CallExpression') {
+        return null;
+    }
+    const callee = node['callee'];
+    if (!callee) {
+        return null;
+    }
+    const names = resolveNamespacedMemberNames(callee);
+    if (!names || !frameworkNamespaces.has(names.receiver)) {
+        return null;
+    }
+    return names.receiver;
+};
+/**
+ * Walk the AST with a scope stack and collect `CallExpression` start offsets
+ * whose callee is `<receiver>.<property>` where `<receiver>` is proven to
+ * resolve to a framework namespace import (i.e. not shadowed by any
+ * enclosing scope). Used to gate namespaced `core.trail(...)` /
+ * `core.signal(...)` / `core.contour(...)` resolution against local shadows.
+ */
+const collectFrameworkNamespacedCallStarts = (ast, frameworkNamespaces) => {
+    const starts = new Set();
+    if (frameworkNamespaces.size === 0) {
+        return starts;
+    }
+    walkWithScopes(ast, (node, scopes) => {
+        const receiver = getFrameworkCallReceiver(node, frameworkNamespaces);
+        if (!receiver || isShadowed(receiver, scopes)) {
+            return;
+        }
+        starts.add(node.start);
+    });
+    return starts;
+};
+const matchTrailPrimitiveName = (name) => (name && TRAIL_CALLEE_NAMES.has(name) ? name : null);
+const getBareTrailCalleeName = (callee) => {
+    if (callee.type !== 'Identifier') {
+        return null;
+    }
+    return matchTrailPrimitiveName(callee.name);
+};
+/**
+ * Extract the `{ receiverName, propertyName }` of a non-computed member-call
+ * callee, or null for anything else. Computed access (`ns[trail]()`) is
+ * intentionally rejected: the bracketed expression may resolve to any runtime
+ * value, so we cannot prove the call targets a specific member.
+ */
+const isNonComputedMemberAccess = (callee) => {
+    if (callee.type !== 'MemberExpression' &&
+        callee.type !== 'StaticMemberExpression') {
+        return false;
+    }
+    return callee.computed !== true;
+};
+const getNamespacedMemberNames = (callee) => {
+    if (!isNonComputedMemberAccess(callee)) {
+        return null;
+    }
+    const { object } = callee;
+    const receiver = identifierName(object);
+    if (!receiver) {
+        return null;
+    }
+    const prop = callee.property;
+    const property = prop?.type === 'Identifier'
+        ? (prop.name ?? null)
+        : null;
+    return property ? { property, receiver } : null;
+};
+const asNamespaceContext = (input) => {
+    if (!input) {
+        return undefined;
+    }
+    return input instanceof Set
+        ? { namespaces: input }
+        : input;
+};
+const isNamespacedCallAllowed = (callStart, receiver, ctx) => {
+    if (!ctx.namespaces.has(receiver)) {
+        return false;
+    }
+    // When `safeCallStarts` is present, it is the authoritative gate — it was
+    // built by a scope-aware pre-pass and already excludes shadowed receivers.
+    // Without it, fall back to the bare name check (used by unit-test hooks).
+    return ctx.safeCallStarts ? ctx.safeCallStarts.has(callStart) : true;
+};
+/**
+ * Resolve a namespaced `ns.trail(...)` / `ns.signal(...)` callee to its
+ * primitive name. When a {@link FrameworkNamespaceContext} is provided, the
+ * receiver must be a framework namespace binding AND — when a
+ * `safeCallStarts` set is present — the call site must appear in that set,
+ * meaning the receiver is not shadowed by any enclosing scope.
+ *
+ * When `context` is `undefined`, this falls back to permissive matching
+ * (any `ns.trail(...)` shape resolves). Inline resolution paths that do
+ * not have the surrounding AST available (e.g. `crosses: [core.trail(...)]`
+ * or `on: [core.signal(...)]`) rely on this fallback. Scope-aware call
+ * sites always pass a context, so this only affects inline contexts where
+ * a best-effort name match is the intended behavior.
+ */
+const getNamespacedTrailCalleeName = (callExpr, callee, context) => {
+    const names = getNamespacedMemberNames(callee);
+    if (!names) {
+        return null;
+    }
+    const ctx = asNamespaceContext(context);
+    if (ctx && !isNamespacedCallAllowed(callExpr.start, names.receiver, ctx)) {
+        return null;
+    }
+    return matchTrailPrimitiveName(names.property);
+};
+/**
+ * Resolve the callee name of a trail/signal call expression.
+ *
+ * Matches both bare `trail(...)` / `signal(...)` identifiers and namespaced
+ * member-expression callees like `core.trail(...)` or `ns.signal(...)`, where
+ * the namespace must come from an `@ontrails/*` import and, when the scope
+ * pre-pass is wired in, be unshadowed at the call site.
+ */
+const getTrailCalleeName = (node, context) => {
+    if (node.type !== 'CallExpression') {
+        return null;
+    }
+    const callee = node['callee'];
+    if (!callee) {
+        return null;
+    }
+    return (getBareTrailCalleeName(callee) ??
+        getNamespacedTrailCalleeName(node, callee, context));
+};
+/**
+ * Test hook: exposes {@link getTrailCalleeName} for unit tests.
+ *
+ * Kept unexported from the module's public surface (no re-export from
+ * `index.ts`) so internal refactors stay free.
+ */
+export const __getTrailCalleeNameForTest = getTrailCalleeName;
+/**
+ * Test hook: exposes {@link collectFrameworkNamespaceBindings} for unit tests.
+ *
+ * Not re-exported from `index.ts`; the double-underscore prefix marks it as an
+ * internal-only handle so consumer code cannot rely on it.
+ */
+export const __collectFrameworkNamespaceBindingsForTest = collectFrameworkNamespaceBindings;
+/** Extract args from a trail() call, handling both two-arg and single-object forms. */
+const extractTrailArgs = (node) => {
+    const args = node['arguments'];
+    if (!args || args.length === 0) {
+        return null;
+    }
+    const [firstArg, secondArg] = args;
+    if (!firstArg) {
+        return null;
+    }
+    // Two-arg form: trail('id', { ... })
+    if (secondArg && firstArg.type !== 'ObjectExpression') {
+        return { configArg: secondArg, idArg: firstArg };
+    }
+    // Single-object form: trail({ id: 'x', ... })
+    return firstArg.type === 'ObjectExpression'
+        ? { configArg: firstArg, idArg: null }
+        : null;
+};
+/** Extract the string value from an `id` property inside a config ObjectExpression. */
+const extractIdFromConfig = (config) => {
+    const idProp = findConfigProperty(config, 'id');
+    if (!idProp || !idProp.value) {
+        return null;
+    }
+    return extractStringOrTemplateLiteral(idProp.value);
+};
+const extractTrailId = (trailArgs) => {
+    if (trailArgs.idArg) {
+        return extractStringOrTemplateLiteral(trailArgs.idArg);
+    }
+    return extractIdFromConfig(trailArgs.configArg);
+};
+const extractTrailDefinition = (node, context) => {
+    const calleeName = getTrailCalleeName(node, context);
+    if (!calleeName) {
+        return null;
+    }
+    const trailArgs = extractTrailArgs(node);
+    if (!trailArgs) {
+        return null;
+    }
+    const trailId = extractTrailId(trailArgs);
+    if (!trailId) {
+        return null;
+    }
+    return {
+        config: trailArgs.configArg,
+        id: trailId,
+        kind: calleeName,
+        start: node.start,
+    };
+};
+const buildFrameworkNamespaceContext = (ast) => {
+    const namespaces = collectFrameworkNamespaceBindings(ast);
+    return {
+        namespaces,
+        safeCallStarts: collectFrameworkNamespacedCallStarts(ast, namespaces),
+    };
+};
+export const findTrailDefinitions = (ast) => {
+    const definitions = [];
+    const context = buildFrameworkNamespaceContext(ast);
+    walk(ast, (node) => {
+        const def = extractTrailDefinition(node, context);
+        if (def) {
+            definitions.push(def);
+        }
+    });
+    return definitions;
+};
+const CONTOUR_PRIMITIVE_NAME = 'contour';
+const matchContourPrimitiveName = (name) => (name === CONTOUR_PRIMITIVE_NAME ? name : null);
+const getBareContourCalleeName = (callee) => {
+    if (callee.type !== 'Identifier') {
+        return null;
+    }
+    return matchContourPrimitiveName(callee.name);
+};
+/**
+ * Resolve a namespaced `ns.contour(...)` callee to its primitive name. Mirrors
+ * {@link getNamespacedTrailCalleeName}: the receiver identifier must resolve
+ * to an `@ontrails/*` namespace import, and — when a scope-aware
+ * `safeCallStarts` set is provided — the call site must not be shadowed by a
+ * local binding of the same name.
+ */
+const getNamespacedContourCalleeName = (callExpr, callee, context) => {
+    const names = getNamespacedMemberNames(callee);
+    if (!names) {
+        return null;
+    }
+    // Unlike the trail/signal variant, contour has no inline-resolution callers
+    // that legitimately invoke this without a FrameworkNamespaceContext, so the
+    // strict namespace gate stays on. If a future caller needs the permissive
+    // fallback, mirror the trail shape and add a regression test first.
+    const ctx = asNamespaceContext(context);
+    if (!ctx || !isNamespacedCallAllowed(callExpr.start, names.receiver, ctx)) {
+        return null;
+    }
+    return matchContourPrimitiveName(names.property);
+};
+/**
+ * Resolve the callee name of a contour call expression. Matches both bare
+ * `contour(...)` identifiers and namespaced `core.contour(...)` callees where
+ * the namespace comes from an `@ontrails/*` import and is unshadowed.
+ */
+const getContourCalleeName = (node, context) => {
+    if (node.type !== 'CallExpression') {
+        return null;
+    }
+    const callee = node['callee'];
+    if (!callee) {
+        return null;
+    }
+    return (getBareContourCalleeName(callee) ??
+        getNamespacedContourCalleeName(node, callee, context));
+};
+const extractContourDefinition = (node, context) => {
+    if (!getContourCalleeName(node, context)) {
+        return null;
+    }
+    const args = node['arguments'];
+    const [nameArg, shapeArg, optionsArg] = args ?? [];
+    const name = extractStringLiteral(nameArg);
+    if (!name || shapeArg?.type !== 'ObjectExpression') {
+        return null;
+    }
+    return {
+        call: node,
+        name,
+        options: optionsArg?.type === 'ObjectExpression' ? optionsArg : null,
+        shape: shapeArg,
+        start: node.start,
+    };
+};
+const getCallStartFromCandidate = (node) => {
+    if (!node) {
+        return null;
+    }
+    if (node.type === 'CallExpression') {
+        return node.start;
+    }
+    if (node.type !== 'ExpressionStatement') {
+        return null;
+    }
+    const { expression } = node;
+    return expression?.type === 'CallExpression' ? expression.start : null;
+};
+// Statement forms that can directly contain a top-level contour call:
+//   `core.contour(...)` as a bare statement,
+//   `export const ... = core.contour(...)` (handled via VariableDeclarator),
+//   `export default core.contour(...);`.
+const getCandidateCallHosts = (statement) => {
+    if (statement.type !== 'ExportNamedDeclaration' &&
+        statement.type !== 'ExportDefaultDeclaration') {
+        return [statement];
+    }
+    const { declaration } = statement;
+    return [statement, declaration];
+};
+const getTopLevelCallStartsFrom = (statement) => {
+    const hosts = getCandidateCallHosts(statement);
+    const starts = [];
+    for (const host of hosts) {
+        const start = getCallStartFromCandidate(host);
+        if (start !== null) {
+            starts.push(start);
+        }
+    }
+    return starts;
+};
+/**
+ * Collect the `start` offsets of `CallExpression` nodes that appear as
+ * top-level `ExpressionStatement`s in a program body — including inside a
+ * top-level `ExportNamedDeclaration` / `ExportDefaultDeclaration` wrapper.
+ * Used to discriminate top-level statement-form calls from inline nested
+ * calls when `topLevelOnly` is enabled.
+ */
+const collectTopLevelStatementCallStarts = (ast) => {
+    const body = ast.body ?? [];
+    return new Set(body.flatMap(getTopLevelCallStartsFrom));
+};
+/**
+ * Return every `contour('name', ...)` definition reachable from the AST, in
+ * source order, deduplicated by call-expression start offset.
+ *
+ * Includes both top-level bindings (`const user = contour('user', ...)`) and
+ * inline contour calls nested inside other expressions (e.g.
+ * `contour('outer', { inner: contour('inner', ...).id() })`). Inline contours
+ * carry no `bindingName` because they have no local binding — this asymmetry
+ * is why {@link collectNamedContourIds} returns only the top-level subset
+ * while {@link collectContourDefinitionIds} returns the full set.
+ *
+ * Pass `{ topLevelOnly: true }` via `options` to opt out of inline discovery
+ * without disturbing callers that rely on the default behavior.
+ *
+ * @remarks
+ * Supplying a pre-built `context` skips the second full-AST traversal inside
+ * `buildFrameworkNamespaceContext` — useful for callers (such as
+ * {@link collectContourReferenceSites}) that already built one.
+ */
+export const findContourDefinitions = (ast, context, options) => {
+    const definitions = [];
+    const seenStarts = new Set();
+    const resolvedContext = context ?? buildFrameworkNamespaceContext(ast);
+    const topLevelOnly = options?.topLevelOnly === true;
+    const addContourDefinition = (definition) => {
+        if (seenStarts.has(definition.start)) {
+            return;
+        }
+        definitions.push(definition);
+        seenStarts.add(definition.start);
+    };
+    const addNamedContourDefinition = (id, init) => {
+        if (!init) {
+            return;
+        }
+        const definition = extractContourDefinition(init, resolvedContext);
+        if (!definition) {
+            return;
+        }
+        const bindingName = extractBindingName(id);
+        if (bindingName) {
+            addContourDefinition({ ...definition, bindingName });
+            return;
+        }
+        addContourDefinition(definition);
+    };
+    // When `topLevelOnly` is set, collect the start offsets of call expressions
+    // that sit directly in the program body as `ExpressionStatement`s (optionally
+    // wrapped in `export`). These are top-level statement-form contour calls and
+    // should still surface alongside `VariableDeclarator` bindings; only calls
+    // nested inside other expressions are excluded.
+    const topLevelStatementCallStarts = topLevelOnly
+        ? collectTopLevelStatementCallStarts(ast)
+        : null;
+    walk(ast, (node) => {
+        if (node.type === 'VariableDeclarator') {
+            const { id, init } = node;
+            addNamedContourDefinition(id, init);
+            return;
+        }
+        if (topLevelStatementCallStarts &&
+            !topLevelStatementCallStarts.has(node.start)) {
+            return;
+        }
+        const definition = extractContourDefinition(node, resolvedContext);
+        if (definition) {
+            addContourDefinition(definition);
+        }
+    });
+    return definitions.toSorted((left, right) => left.start - right.start);
+};
+/**
+ * Collect the `name` of every contour definition in a parsed file, including
+ * inline contours nested inside other expressions. Returns the same set of
+ * names that {@link findContourDefinitions} discovers under default options.
+ */
+export const collectContourDefinitionIds = (ast) => new Set(findContourDefinitions(ast).map((def) => def.name));
+/**
+ * Collect the `localBinding → contourName` map for `const foo = contour(...)`
+ * declarations. Inline contour calls are intentionally excluded because they
+ * have no local binding — use {@link collectContourDefinitionIds} when the
+ * full set of declared names is required.
+ */
+export const collectNamedContourIds = (ast) => {
+    const ids = new Map();
+    for (const def of findContourDefinitions(ast)) {
+        if (def.bindingName) {
+            ids.set(def.bindingName, def.name);
+        }
+    }
+    return ids;
+};
+const resolveNamedImportedName = (specifier, localName) => {
+    const { imported } = specifier;
+    const importedName = imported
+        ? (identifierName(imported) ?? extractStringLiteral(imported))
+        : null;
+    return importedName ?? localName;
+};
+const extractImportSpecifierAlias = (specifier) => {
+    if (specifier.type !== 'ImportSpecifier' &&
+        specifier.type !== 'ImportDefaultSpecifier') {
+        return null;
+    }
+    const { local } = specifier;
+    const localName = identifierName(local);
+    if (!localName) {
+        return null;
+    }
+    // Default imports bind the default export of the source module to the local
+    // name. We cannot statically recover the exported name without cross-file
+    // analysis, so the local name is the best identifier we have for resolving
+    // against `knownContourIds`. Treat the alias as an identity mapping; the
+    // downstream resolver will fall through to `knownContourIds` on the binding
+    // name and report it as missing when not found.
+    if (specifier.type === 'ImportDefaultSpecifier') {
+        return { importedName: localName, localName };
+    }
+    return {
+        importedName: resolveNamedImportedName(specifier, localName),
+        localName,
+    };
+};
+/**
+ * Collect `import { foo as bar } from '...'` and `import bar from '...'`
+ * specifier mappings keyed by local binding name. The value is the original
+ * exported name for named imports. Default imports map to themselves because
+ * the exported name cannot be recovered statically — callers should fall
+ * through to `knownContourIds` membership on the local binding name.
+ */
+export const collectImportAliasMap = (ast) => {
+    const aliases = new Map();
+    walk(ast, (node) => {
+        if (node.type !== 'ImportDeclaration') {
+            return;
+        }
+        const specifiers = node['specifiers'] ?? [];
+        for (const specifier of specifiers) {
+            const alias = extractImportSpecifierAlias(specifier);
+            if (alias) {
+                aliases.set(alias.localName, alias.importedName);
+            }
+        }
+    });
+    return aliases;
+};
+const addUserNamespaceBindingsFromDeclaration = (node, into) => {
+    if (isFrameworkNamespaceSource(getImportSourceValue(node))) {
+        return;
+    }
+    const specifiers = node['specifiers'] ?? [];
+    for (const specifier of specifiers) {
+        if (specifier.type !== 'ImportNamespaceSpecifier') {
+            continue;
+        }
+        const { local } = specifier;
+        const localName = identifierName(local);
+        if (localName) {
+            into.add(localName);
+        }
+    }
+};
+/**
+ * Collect local binding names introduced by `import * as <name> from '<src>'`
+ * declarations whose source is NOT an `@ontrails/*` framework package. These
+ * are user-defined namespace imports of contour modules (e.g. `import * as
+ * contours from './contours'`), used to resolve `contours.user` member-access
+ * references to contour ids.
+ *
+ * Framework namespace imports (`import * as core from '@ontrails/core'`) are
+ * intentionally excluded — they carry framework primitives like
+ * `core.contour(...)` and are resolved by {@link buildFrameworkNamespaceContext}.
+ * Mixing them here would treat `core.contour` as a reference to a contour
+ * named "contour", producing false positives.
+ */
+export const collectUserNamespaceImportBindings = (ast) => {
+    const bindings = new Set();
+    walk(ast, (node) => {
+        if (node.type !== 'ImportDeclaration') {
+            return;
+        }
+        addUserNamespaceBindingsFromDeclaration(node, bindings);
+    });
+    return bindings;
+};
+/**
+ * Walk the AST with a scope stack and collect `MemberExpression` start offsets
+ * whose receiver is a user-namespace binding that is NOT shadowed by any
+ * enclosing scope. Mirrors `collectFrameworkNamespacedCallStarts` for the
+ * framework-namespace path so `contours.user` inside
+ * `function f(contours) { ... }` is rejected as shadowed.
+ */
+/**
+ * Return the receiver-identifier name of a non-computed member access, or
+ * `null` for any other node shape (computed access, non-member, etc.).
+ */
+const getNonComputedMemberReceiver = (node) => {
+    if (!isMemberAccessNonComputed(node)) {
+        return null;
+    }
+    const { object } = node;
+    return object ? identifierName(object) : null;
+};
+const collectUserNamespacedMemberStarts = (ast, bindings) => {
+    const starts = new Set();
+    if (bindings.size === 0) {
+        return starts;
+    }
+    walkWithScopes(ast, (node, scopes) => {
+        const receiver = getNonComputedMemberReceiver(node);
+        if (!receiver || !bindings.has(receiver) || isShadowed(receiver, scopes)) {
+            return;
+        }
+        starts.add(node.start);
+    });
+    return starts;
+};
+/**
+ * Build a {@link UserNamespaceContext} for `ast`, including the scope-aware
+ * `safeMemberStarts` gate. Prefer this over bare
+ * {@link collectUserNamespaceImportBindings} so member access like
+ * `contours.user` is rejected when `contours` is shadowed by a local binding.
+ */
+export const buildUserNamespaceContext = (ast) => {
+    const bindings = collectUserNamespaceImportBindings(ast);
+    return {
+        bindings,
+        safeMemberStarts: collectUserNamespacedMemberStarts(ast, bindings),
+    };
+};
+/**
+ * Read a property key or member access identifier.
+ *
+ * Returns the identifier name for `Identifier` keys, or the underlying
+ * string literal value for computed access via `['name']` / `"name"`.
+ */
+export const getPropertyName = (node) => {
+    if (typeof node !== 'object' || node === null) {
+        return null;
+    }
+    const { name } = node;
+    if (typeof name === 'string') {
+        return name;
+    }
+    return isAstNode(node) ? extractStringLiteral(node) : null;
+};
+const stripContourSuffix = (name) => {
+    const suffix = 'Contour';
+    return name.endsWith(suffix) ? name.slice(0, -suffix.length) : name;
+};
+const resolveKnownContourName = (name, knownContourIds) => {
+    if (knownContourIds?.has(name)) {
+        return name;
+    }
+    // Support the common `const userContour = contour('user', ...)` naming
+    // pattern when callers refer to the binding name instead of the contour ID.
+    // Exact matches always win; suffix stripping is a fallback only.
+    const stripped = stripContourSuffix(name);
+    if (stripped !== name && knownContourIds?.has(stripped)) {
+        return stripped;
+    }
+    return null;
+};
+/**
+ * Resolve a local binding name to a contour ID, honoring import aliases.
+ *
+ * Strategies, in order:
+ * 1. Local `const foo = contour('name', ...)` binding → the contour name.
+ * 2. `knownContourIds` membership on the binding name itself (or the
+ *    conventional `Contour` suffix strip).
+ * 3. `import { foo as bar }` → use the original exported name `foo`
+ *    (and apply strategy 2 / suffix-stripping against it so aliased imports
+ *    resolve correctly). If the imported name still isn't recognized, the
+ *    imported name is returned so the caller can report it missing.
+ *
+ * Returns `null` only when the name belongs to no known resolution path —
+ * no local binding, no known contour ID, no import, and no suffix match.
+ * Returning `null` means "this identifier is not a contour reference we can
+ * reason about" (e.g. a bare undeclared variable), as opposed to
+ * "a contour reference whose target is missing".
+ */
+export const deriveContourIdentifierName = (bindingName, namedContourIds, knownContourIds, importAliases) => {
+    const localName = namedContourIds.get(bindingName);
+    if (localName) {
+        return localName;
+    }
+    const known = resolveKnownContourName(bindingName, knownContourIds);
+    if (known) {
+        return known;
+    }
+    // If the binding came from an import, use the original exported name as
+    // the resolution target. This lets `import { foo as bar }` resolve to
+    // the exported `foo` rather than the local alias `bar`. If the imported
+    // name still isn't recognized, return it so callers can report it as
+    // missing under its original name.
+    const importedName = importAliases?.get(bindingName);
+    if (importedName) {
+        return (resolveKnownContourName(importedName, knownContourIds) ?? importedName);
+    }
+    return null;
+};
+const getContourReferenceMember = (node) => {
+    if (node.type !== 'MemberExpression' &&
+        node.type !== 'StaticMemberExpression') {
+        return null;
+    }
+    return node;
+};
+const asUserNamespaceContext = (input) => {
+    if (!input) {
+        return undefined;
+    }
+    return input instanceof Set
+        ? { bindings: input }
+        : input;
+};
+/**
+ * Resolve a user-namespace member access like `contours.user` to its contour
+ * id. Returns the property name (e.g. `'user'`) when the receiver identifier
+ * is a known user-defined namespace binding AND — when the caller provides a
+ * {@link UserNamespaceContext} with `safeMemberStarts` — the member access
+ * site is in that set (i.e. the receiver is not shadowed by any enclosing
+ * scope). Otherwise returns `null`.
+ *
+ * The property name is taken as the contour id verbatim — we cannot statically
+ * resolve what `contours.user` binds to without reading the other file, so we
+ * treat the member name as the candidate target and let
+ * {@link deriveContourIdentifierName}'s downstream `knownContourIds` check
+ * report a missing target.
+ */
+export const isUserNamespaceReceiverAllowed = (receiver, memberStart, ctx) => {
+    if (!ctx.bindings.has(receiver)) {
+        return false;
+    }
+    // Scope-aware gate: when the pre-pass produced a set, the member access
+    // must appear in it. Without the set, fall back to the bare name check.
+    return ctx.safeMemberStarts ? ctx.safeMemberStarts.has(memberStart) : true;
+};
+const getContourReferenceTargetFromNamespaceMember = (member, userNamespace) => {
+    const ctx = asUserNamespaceContext(userNamespace);
+    if (!ctx || ctx.bindings.size === 0) {
+        return null;
+    }
+    const receiver = member.object ? identifierName(member.object) : null;
+    if (!receiver ||
+        !isUserNamespaceReceiverAllowed(receiver, member.start, ctx)) {
+        return null;
+    }
+    const { property } = member;
+    if (!property || property.type !== 'Identifier') {
+        return null;
+    }
+    return identifierName(property);
+};
+const getContourReferenceTargetFromObject = (object, namedContourIds, knownContourIds, importAliases, context, userNamespace) => {
+    if (object.type === 'Identifier') {
+        const bindingName = identifierName(object);
+        return bindingName
+            ? deriveContourIdentifierName(bindingName, namedContourIds, knownContourIds, importAliases)
+            : null;
+    }
+    const member = getContourReferenceMember(object);
+    if (member) {
+        const namespaceTarget = getContourReferenceTargetFromNamespaceMember(member, userNamespace);
+        if (namespaceTarget) {
+            return namespaceTarget;
+        }
+    }
+    return extractContourDefinition(object, context)?.name ?? null;
+};
+const CONTOUR_ID_WRAPPER_METHODS = new Set([
+    'brand',
+    'catch',
+    'default',
+    'describe',
+    'meta',
+    'nullable',
+    'nullish',
+    'optional',
+    'readonly',
+]);
+const getContourIdCallMember = (node) => {
+    const callee = node['callee'];
+    const member = callee ? getContourReferenceMember(callee) : null;
+    const propertyName = member ? identifierName(member.property) : null;
+    return member && propertyName ? { member, propertyName } : null;
+};
+const getContourIdCallObject = function getContourIdCallObject(node) {
+    const current = node;
+    if (!current || current.type !== 'CallExpression') {
+        return null;
+    }
+    const member = getContourIdCallMember(current);
+    if (!member) {
+        return null;
+    }
+    if (member.propertyName === 'id') {
+        return member.member.object ?? null;
+    }
+    return CONTOUR_ID_WRAPPER_METHODS.has(member.propertyName)
+        ? getContourIdCallObject(member.member.object)
+        : null;
+};
+const extractContourReferenceTarget = (node, namedContourIds, knownContourIds, importAliases, context, userNamespace) => {
+    const object = getContourIdCallObject(node);
+    return object
+        ? getContourReferenceTargetFromObject(object, namedContourIds, knownContourIds, importAliases, context, userNamespace)
+        : null;
+};
+const getContourShapeProperties = (definition) => definition.shape['properties'] ?? [];
+const buildContourReferenceSite = (definition, property, namedContourIds, knownContourIds, importAliases, context, userNamespace) => {
+    if (property.type !== 'Property') {
+        return null;
+    }
+    const field = getPropertyName(property.key);
+    const target = extractContourReferenceTarget(property.value, namedContourIds, knownContourIds, importAliases, context, userNamespace);
+    if (!field || !target) {
+        return null;
+    }
+    return {
+        field,
+        source: definition.name,
+        start: property.start,
+        target,
+    };
+};
+const findContourReferenceSitesForDefinition = (definition, namedContourIds, knownContourIds, importAliases, context, userNamespace) => getContourShapeProperties(definition).flatMap((property) => {
+    const reference = buildContourReferenceSite(definition, property, namedContourIds, knownContourIds, importAliases, context, userNamespace);
+    return reference ? [reference] : [];
+});
+/** Collect all contour field references declared via `.id()` in a parsed file. */
+export const collectContourReferenceSites = (ast, knownContourIds) => {
+    const namedContourIds = collectNamedContourIds(ast);
+    const importAliases = collectImportAliasMap(ast);
+    const userNamespace = buildUserNamespaceContext(ast);
+    const context = buildFrameworkNamespaceContext(ast);
+    return findContourDefinitions(ast, context).flatMap((definition) => findContourReferenceSitesForDefinition(definition, namedContourIds, knownContourIds, importAliases, context, userNamespace));
+};
+/** Collect contour reference targets keyed by source contour name. */
+export const collectContourReferenceTargetsByName = (ast, knownContourIds) => {
+    const targetsByName = new Map();
+    for (const reference of collectContourReferenceSites(ast, knownContourIds)) {
+        const existing = targetsByName.get(reference.source);
+        if (existing) {
+            existing.add(reference.target);
+            continue;
+        }
+        targetsByName.set(reference.source, new Set([reference.target]));
+    }
+    return new Map([...targetsByName.entries()].map(([name, targets]) => [name, [...targets]]));
+};
+// ---------------------------------------------------------------------------
+// Blaze body extraction
+// ---------------------------------------------------------------------------
+/**
+ * Extract top-level `blaze:` property values from an ObjectExpression's direct properties.
+ *
+ * Does not recurse into nested objects, so `meta: { blaze: ... }` is ignored.
+ */
+const extractBlazeFromConfig = (config) => {
+    const bodies = [];
+    const properties = config['properties'];
+    if (!properties) {
+        return bodies;
+    }
+    for (const prop of properties) {
+        if (prop.type === 'Property' &&
+            prop.key?.name === 'blaze' &&
+            isAstNode(prop.value)) {
+            bodies.push(prop.value);
+        }
+    }
+    return bodies;
+};
+/**
+ * Find `blaze:` property values.
+ *
+ * When given an ObjectExpression (trail config), returns only its direct `blaze:`
+ * properties. When given a full AST, finds trail definitions first and extracts
+ * `blaze:` from each config — in both cases ignoring nested `blaze:` properties
+ * (e.g. `meta: { blaze: ... }`).
+ */
+export const findBlazeBodies = (node) => {
+    if (node.type === 'ObjectExpression') {
+        return extractBlazeFromConfig(node);
+    }
+    // Full AST — find trail definitions and extract blaze from their configs
+    const bodies = [];
+    for (const def of findTrailDefinitions(node)) {
+        bodies.push(...extractBlazeFromConfig(def.config));
+    }
+    return bodies;
+};
+/**
+ * Collect all `signal('id', { ... })` / `signal({ id: 'x', ... })` definition IDs.
+ *
+ * Uses `findTrailDefinitions` under the hood — it already recognizes both
+ * `trail` and `signal` call sites, distinguished by the `kind` field.
+ */
+export const collectSignalDefinitionIds = (ast) => {
+    const ids = new Set();
+    for (const def of findTrailDefinitions(ast)) {
+        if (def.kind === 'signal') {
+            ids.add(def.id);
+        }
+    }
+    return ids;
+};
+/** Collect `const foo = trail('id', ...)` bindings from a parsed file. */
+export const collectNamedTrailIds = (ast) => {
+    const ids = new Map();
+    const context = buildFrameworkNamespaceContext(ast);
+    walk(ast, (node) => {
+        if (node.type !== 'VariableDeclarator') {
+            return;
+        }
+        const { id, init } = node;
+        if (!init) {
+            return;
+        }
+        const def = extractTrailDefinition(init, context);
+        const name = extractBindingName(id);
+        if (def?.kind === 'trail' && name) {
+            ids.set(name, def.id);
+        }
+    });
+    return ids;
+};
+/** Extract the raw `crosses: [...]` array elements from a trail config. */
+export const getCrossElements = (config) => {
+    const crossesProp = findConfigProperty(config, 'crosses');
+    if (!crossesProp) {
+        return [];
+    }
+    const arrayNode = crossesProp.value;
+    if (!arrayNode || arrayNode.type !== 'ArrayExpression') {
+        return [];
+    }
+    const elements = arrayNode['elements'];
+    return elements ?? [];
+};
+/**
+ * Resolve a single `crosses: [...]` element to its target trail ID.
+ *
+ * Handles string literals, identifier references (via `namedTrailIds` map or
+ * `const NAME = '...'` resolution), and inline `trail(...)` call expressions.
+ */
+export const deriveCrossElementId = (element, sourceCode, namedTrailIds) => {
+    if (isStringLiteral(element)) {
+        return getStringValue(element);
+    }
+    if (element.type === 'Identifier') {
+        const name = identifierName(element);
+        return name
+            ? (namedTrailIds.get(name) ?? deriveConstString(name, sourceCode))
+            : null;
+    }
+    const inlineDef = extractTrailDefinition(element);
+    return inlineDef?.kind === 'trail' ? inlineDef.id : null;
+};
+/**
+ * Collect all trail IDs referenced by a single trail definition's
+ * `crosses: [...]` array, deduplicated.
+ */
+export const extractDefinitionCrossTargetIds = (config, sourceCode, namedTrailIds) => [
+    ...new Set(getCrossElements(config).flatMap((element) => {
+        const id = deriveCrossElementId(element, sourceCode, namedTrailIds);
+        return id ? [id] : [];
+    })),
+];
+/** Collect all trail IDs referenced by declared `crosses: [...]` arrays. */
+export const collectCrossTargetTrailIds = (ast, sourceCode) => {
+    const ids = new Set();
+    const namedTrailIds = collectNamedTrailIds(ast);
+    for (const def of findTrailDefinitions(ast)) {
+        if (def.kind !== 'trail') {
+            continue;
+        }
+        for (const id of extractDefinitionCrossTargetIds(def.config, sourceCode, namedTrailIds)) {
+            ids.add(id);
+        }
+    }
+    return ids;
+};
+const extractTrailIntent = (config) => {
+    const intentProp = findConfigProperty(config, 'intent');
+    if (!intentProp || !isStringLiteral(intentProp.value)) {
+        return 'write';
+    }
+    const value = getStringValue(intentProp.value);
+    return value === 'destroy' || value === 'read' ? value : 'write';
+};
+/** Collect the normalized intent for every trail definition in a parsed file. */
+export const collectTrailIntentsById = (ast) => {
+    const intents = new Map();
+    for (const def of findTrailDefinitions(ast)) {
+        if (def.kind === 'trail') {
+            intents.set(def.id, extractTrailIntent(def.config));
+        }
+    }
+    return intents;
+};
+/**
+ * Build a composite key for a store table: `${storeBinding}:${tableName}`,
+ * falling back to the bare `tableName` when the enclosing store has no local
+ * binding. Centralized so rule keying stays stable.
+ *
+ * @remarks
+ * The key is intentionally file-local (no module path prefix). Cross-file
+ * aggregation in `ProjectContext` merges keys from all files, so two files
+ * with `const db = store({ notes: ... })` both produce `db:notes` — this is
+ * the desired behavior because the warden checks for *pattern completeness*
+ * across the project and matching keys signals that the same logical table
+ * is covered. If two genuinely different tables share a binding and name,
+ * that is a code-level naming collision the developer should resolve.
+ */
+export const makeStoreTableKey = (storeBinding, tableName) => (storeBinding ? `${storeBinding}:${tableName}` : tableName);
+const isBooleanLiteral = (node) => Boolean(node &&
+    ((node.type === 'BooleanLiteral' &&
+        node.value === true) ||
+        (node.type === 'Literal' &&
+            node.value === true)));
+/**
+ * Check if a node is a `CallExpression` to the identifier `name`.
+ *
+ * e.g. `isNamedCall(node, 'store')` matches `store({...})` but not
+ * `someObj.store()` or `storeAlt()`.
+ */
+export const isNamedCall = (node, name) => !!node &&
+    node.type === 'CallExpression' &&
+    identifierName(node.callee) === name;
+/**
+ * Narrow a member-expression node (`a.b` or `a['b']`) to its `object` /
+ * `property` pair, returning `null` for anything else.
+ */
+export const getMemberExpression = (node) => {
+    if (!node ||
+        (node.type !== 'MemberExpression' && node.type !== 'StaticMemberExpression')) {
+        return null;
+    }
+    return node;
+};
+/**
+ * Resolve a `<store>.tables.<name>` member expression to its store binding
+ * and table name.
+ *
+ * Returns `null` for anything that isn't a two-level member access ending in
+ * `.tables.<name>`. The store binding is the identifier of the object owning
+ * `.tables` — typically the local binding from `const db = store(...)`.
+ */
+export const extractStoreTableFromMember = (node) => {
+    const member = getMemberExpression(node);
+    const tableName = member ? getPropertyName(member.property) : null;
+    const tablesMember = member ? getMemberExpression(member.object) : null;
+    if (!tableName || !tablesMember) {
+        return null;
+    }
+    if (getPropertyName(tablesMember.property) !== 'tables') {
+        return null;
+    }
+    const storeBinding = identifierName(tablesMember.object) ?? null;
+    return { storeBinding, tableName };
+};
+/**
+ * Back-compat shim for rule code that only needs the table name. Prefer
+ * `extractStoreTableFromMember` so the caller can build a composite key.
+ */
+export const extractStoreTableIdFromMember = (node) => extractStoreTableFromMember(node)?.tableName ?? null;
+/**
+ * Collect `const foo = <store>.tables.<name>` bindings from a parsed file,
+ * keyed by the local binding name. Values are the composite table key
+ * (`${storeBinding}:${tableName}`) so callers can dedupe across stores that
+ * share a table name.
+ */
+export const collectNamedStoreTableIds = (ast) => {
+    const ids = new Map();
+    walk(ast, (node) => {
+        if (node.type !== 'VariableDeclarator') {
+            return;
+        }
+        const { id, init } = node;
+        const name = extractBindingName(id);
+        const table = extractStoreTableFromMember(init);
+        if (name && table) {
+            ids.set(name, makeStoreTableKey(table.storeBinding, table.tableName));
+        }
+    });
+    return ids;
+};
+/**
+ * Resolve an argument node to a composite store-table key
+ * (`${storeBinding}:${tableName}` or bare `tableName` when anonymous).
+ *
+ * Handles the two authoring patterns:
+ *   - direct member access: `db.tables.notes`
+ *   - identifier reference: `const notesTable = db.tables.notes; crud(notesTable, …)`
+ */
+export const deriveStoreTableId = (node, namedStoreTableIds) => {
+    if (!node) {
+        return null;
+    }
+    if (node.type === 'Identifier') {
+        const name = identifierName(node);
+        return name ? (namedStoreTableIds.get(name) ?? null) : null;
+    }
+    const member = extractStoreTableFromMember(node);
+    return member
+        ? makeStoreTableKey(member.storeBinding, member.tableName)
+        : null;
+};
+const extractStoreTableDefinitions = (node, storeBinding) => {
+    if (!isNamedCall(node, 'store')) {
+        return [];
+    }
+    const [tablesArg] = (node
+        .arguments ?? []);
+    if (!tablesArg || tablesArg.type !== 'ObjectExpression') {
+        return [];
+    }
+    const properties = tablesArg['properties'];
+    if (!properties) {
+        return [];
+    }
+    return properties.flatMap((property) => {
+        if (property.type !== 'Property') {
+            return [];
+        }
+        const name = getPropertyName(property.key);
+        const value = property.value;
+        if (!name || value?.type !== 'ObjectExpression') {
+            return [];
+        }
+        const versionedProp = findConfigProperty(value, 'versioned');
+        return [
+            {
+                key: makeStoreTableKey(storeBinding, name),
+                name,
+                start: property.start,
+                storeBinding,
+                versioned: isBooleanLiteral(versionedProp?.value),
+            },
+        ];
+    });
+};
+export const findStoreTableDefinitions = (ast) => {
+    const definitions = [];
+    const seenStoreCalls = new WeakSet();
+    // First pass: bound stores (walk VariableDeclarators so we know the binding).
+    walk(ast, (node) => {
+        if (node.type !== 'VariableDeclarator') {
+            return;
+        }
+        const { id, init } = node;
+        if (!init || !isNamedCall(init, 'store')) {
+            return;
+        }
+        seenStoreCalls.add(init);
+        const storeBinding = extractBindingName(id);
+        definitions.push(...extractStoreTableDefinitions(init, storeBinding));
+    });
+    // Second pass: anonymous `store({...})` calls not bound to a variable
+    // (e.g. an inline default export). Use the bare table name as the key.
+    walk(ast, (node) => {
+        if (!isNamedCall(node, 'store') || seenStoreCalls.has(node)) {
+            return;
+        }
+        definitions.push(...extractStoreTableDefinitions(node, null));
+    });
+    return definitions;
+};
+export const collectVersionedStoreTableIds = (ast) => new Set(findStoreTableDefinitions(ast).flatMap((definition) => definition.versioned ? [definition.key] : []));
+export const collectCrudTableIds = (ast) => {
+    const ids = new Set();
+    const namedStoreTableIds = collectNamedStoreTableIds(ast);
+    walk(ast, (node) => {
+        if (!isNamedCall(node, 'crud')) {
+            return;
+        }
+        const [tableArg] = (node
+            .arguments ?? []);
+        const tableId = deriveStoreTableId(tableArg, namedStoreTableIds);
+        if (tableId) {
+            ids.add(tableId);
+        }
+    });
+    return ids;
+};
+export const collectReconcileTableIds = (ast) => {
+    const ids = new Set();
+    const namedStoreTableIds = collectNamedStoreTableIds(ast);
+    walk(ast, (node) => {
+        if (!isNamedCall(node, 'reconcile')) {
+            return;
+        }
+        const [configArg] = (node.arguments ?? []);
+        if (!configArg || configArg.type !== 'ObjectExpression') {
+            return;
+        }
+        const tableProp = findConfigProperty(configArg, 'table');
+        const tableId = deriveStoreTableId(tableProp?.value, namedStoreTableIds);
+        if (tableId) {
+            ids.add(tableId);
+        }
+    });
+    return ids;
+};
+const STORE_SIGNAL_OPERATIONS = new Set(['created', 'removed', 'updated']);
+const extractStoreSignalIdFromMember = (node, namedStoreTableIds) => {
+    const member = getMemberExpression(node);
+    const operation = member ? getPropertyName(member.property) : null;
+    if (!operation || !STORE_SIGNAL_OPERATIONS.has(operation)) {
+        return null;
+    }
+    const signalsMember = member ? getMemberExpression(member.object) : null;
+    if (!signalsMember || getPropertyName(signalsMember.property) !== 'signals') {
+        return null;
+    }
+    const tableId = deriveStoreTableId(signalsMember.object, namedStoreTableIds);
+    return tableId ? `${tableId}.${operation}` : null;
+};
+const collectNamedStoreSignalIds = (ast, namedStoreTableIds) => {
+    const ids = new Map();
+    walk(ast, (node) => {
+        if (node.type !== 'VariableDeclarator') {
+            return;
+        }
+        const { id, init } = node;
+        const name = extractBindingName(id);
+        const signalId = extractStoreSignalIdFromMember(init, namedStoreTableIds);
+        if (name && signalId) {
+            ids.set(name, signalId);
+        }
+    });
+    return ids;
+};
+const getOnElements = (config) => {
+    const onProp = findConfigProperty(config, 'on');
+    if (!onProp) {
+        return [];
+    }
+    const arrayNode = onProp.value;
+    if (!arrayNode || arrayNode.type !== 'ArrayExpression') {
+        return [];
+    }
+    const elements = arrayNode['elements'];
+    return elements ?? [];
+};
+const resolveNamedOnSignalId = (element, sourceCode, namedStoreSignalIds) => {
+    if (element.type !== 'Identifier') {
+        return null;
+    }
+    const name = identifierName(element);
+    return name
+        ? (namedStoreSignalIds.get(name) ?? deriveConstString(name, sourceCode))
+        : null;
+};
+const resolveInlineOnSignalId = (element) => {
+    const definition = extractTrailDefinition(element);
+    return definition?.kind === 'signal' ? definition.id : null;
+};
+const resolveOnElementSignalId = (element, sourceCode, namedStoreSignalIds, namedStoreTableIds) => {
+    if (isStringLiteral(element)) {
+        return getStringValue(element);
+    }
+    return (extractStoreSignalIdFromMember(element, namedStoreTableIds) ??
+        resolveNamedOnSignalId(element, sourceCode, namedStoreSignalIds) ??
+        resolveInlineOnSignalId(element));
+};
+const addOnTargetSignalIds = (config, ids, sourceCode, namedStoreSignalIds, namedStoreTableIds) => {
+    for (const element of getOnElements(config)) {
+        const signalId = resolveOnElementSignalId(element, sourceCode, namedStoreSignalIds, namedStoreTableIds);
+        if (signalId) {
+            ids.add(signalId);
+        }
+    }
+};
+export const collectOnTargetSignalIds = (ast, sourceCode) => {
+    const ids = new Set();
+    const namedStoreTableIds = collectNamedStoreTableIds(ast);
+    const namedStoreSignalIds = collectNamedStoreSignalIds(ast, namedStoreTableIds);
+    for (const definition of findTrailDefinitions(ast)) {
+        if (definition.kind === 'trail') {
+            addOnTargetSignalIds(definition.config, ids, sourceCode, namedStoreSignalIds, namedStoreTableIds);
+        }
+    }
+    return ids;
 };
 // ---------------------------------------------------------------------------
 // Misc helpers