vigiles 2.0.0 → 2.2.0

package/dist/skill-test.d.ts

@@ -0,0 +1,47 @@
+/**
+ * vigiles — Skill testing: deterministic tests for a skill's action sequence.
+ *
+ * A thin wrapper over the generator driver (`driveSkill`) for use inside an
+ * ordinary `node:test` / Vitest `test()` — no custom runner, no DSL. You script
+ * the *model* (the non-deterministic part) and assert the deterministic spine:
+ * which gates ran, in what order, which branch was taken, whether the result
+ * gate blocked. The model's prose quality is never asserted — that's the
+ * probabilistic boundary; everything else is deterministic and checkable.
+ */
+import { type SkillProgram, type GeneratorSkill } from "./skill-driver.js";
+export type ModelFn = (prose: string) => string;
+/**
+ * Script the mocked model. Pass:
+ *  - an array — answers consumed in order across all acts; or
+ *  - a map keyed by a case-insensitive substring of the act's prose, where each
+ *    value is a single answer, or an array consumed in order *per key* (so a
+ *    loop's prompt can return different answers on successive iterations).
+ * Unmatched prose yields "".
+ */
+export declare function scriptModel(spec: readonly string[] | Readonly<Record<string, string | readonly string[]>>): ModelFn;
+export interface SkillRunResult {
+    /** Every gate passed and the skill reached its end. */
+    readonly ok: boolean;
+    /** Trace index of the gate that blocked, or null when all passed. */
+    readonly blockedAt: number | null;
+    /** Prose steps the model executed, with the scripted answer fed back in. */
+    readonly acts: readonly {
+        prose: string;
+        answer: string;
+    }[];
+    /** Gates that ran, in order, with their label and outcome. */
+    readonly gates: readonly {
+        label: string;
+        terminal: boolean;
+        ok: boolean;
+    }[];
+}
+/**
+ * Drive a skill to completion (or first failed gate) with a scripted model and
+ * return a friendly summary to assert on with plain `assert`.
+ */
+export declare function runSkill(skill: SkillProgram | GeneratorSkill, opts?: {
+    cwd?: string;
+    model?: ModelFn;
+}): SkillRunResult;
+//# sourceMappingURL=skill-test.d.ts.map

package/dist/skill-test.js

@@ -0,0 +1,77 @@
+"use strict";
+/**
+ * vigiles — Skill testing: deterministic tests for a skill's action sequence.
+ *
+ * A thin wrapper over the generator driver (`driveSkill`) for use inside an
+ * ordinary `node:test` / Vitest `test()` — no custom runner, no DSL. You script
+ * the *model* (the non-deterministic part) and assert the deterministic spine:
+ * which gates ran, in what order, which branch was taken, whether the result
+ * gate blocked. The model's prose quality is never asserted — that's the
+ * probabilistic boundary; everything else is deterministic and checkable.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.scriptModel = scriptModel;
+exports.runSkill = runSkill;
+const skill_driver_js_1 = require("./skill-driver.js");
+function gateLabel(g) {
+    if (g._ref === "cmd")
+        return g.command;
+    if (g._ref === "role")
+        return `project:${g.role}`;
+    return g.path;
+}
+/**
+ * Script the mocked model. Pass:
+ *  - an array — answers consumed in order across all acts; or
+ *  - a map keyed by a case-insensitive substring of the act's prose, where each
+ *    value is a single answer, or an array consumed in order *per key* (so a
+ *    loop's prompt can return different answers on successive iterations).
+ * Unmatched prose yields "".
+ */
+function scriptModel(spec) {
+    if (Array.isArray(spec)) {
+        const answers = spec;
+        let i = 0;
+        return () => answers[Math.min(i++, answers.length - 1)] ?? "";
+    }
+    const map = spec;
+    const idx = {};
+    return (prose) => {
+        const p = prose.toLowerCase();
+        for (const k of Object.keys(map)) {
+            if (!p.includes(k.toLowerCase()))
+                continue;
+            const v = map[k];
+            if (typeof v === "string")
+                return v;
+            const i = idx[k] ?? 0;
+            idx[k] = i + 1;
+            return v[Math.min(i, v.length - 1)] ?? "";
+        }
+        return "";
+    };
+}
+/**
+ * Drive a skill to completion (or first failed gate) with a scripted model and
+ * return a friendly summary to assert on with plain `assert`.
+ */
+function runSkill(skill, opts = {}) {
+    const program = typeof skill === "function" ? skill : skill.program;
+    const report = (0, skill_driver_js_1.driveSkill)(program, opts.cwd ?? process.cwd(), opts.model ?? (() => ""));
+    const acts = [];
+    const gates = [];
+    for (const t of report.trace) {
+        if (t.effect.kind === "act") {
+            acts.push({ prose: t.effect.prose, answer: t.answer ?? "" });
+        }
+        else {
+            gates.push({
+                label: gateLabel(t.effect.gate),
+                terminal: t.effect.kind === "result",
+                ok: t.outcome?.ok ?? false,
+            });
+        }
+    }
+    return { ok: report.ok, blockedAt: report.blockedAt, acts, gates };
+}
+//# sourceMappingURL=skill-test.js.map

package/dist/spec.d.ts

@@ -8,8 +8,8 @@
  *   enforce() — delegated to an external linter (ESLint, Ruff, Clippy, etc.)
  *   guidance() — prose only, no mechanical enforcement
  */
-/** Linters vigiles can cross-reference. */
-type BuiltinLinter = "eslint" | "stylelint" | "ruff" | "clippy" | "pylint" | "rubocop";
+/** Linters and policy catalogs vigiles can cross-reference. */
+type BuiltinLinter = "eslint" | "stylelint" | "ruff" | "clippy" | "pylint" | "rubocop" | "cedar";
 /** Scoped ESLint plugin prefix (e.g., @typescript-eslint). */
 type ScopedPlugin = `@${string}/${string}`;
 /** A linter/rule reference: "eslint/no-console", "ruff/T201", "@typescript-eslint/no-explicit-any". */
@@ -52,12 +52,12 @@ export type StrictFile = [keyof KnownProjectFiles] extends [never] ? string : Kn
 export type StrictCmd = [keyof KnownNpmScripts] extends [never] ? string : `npm run ${KnownNpmScripts[keyof KnownNpmScripts] & string}` | `npm ${KnownNpmScripts[keyof KnownNpmScripts] & string}` | (string & {});
 export type ClaudeTool = "Read" | "Write" | "Edit" | "Bash" | "Grep" | "Glob" | "Agent" | "TodoWrite" | "WebSearch" | "WebFetch" | "NotebookEdit";
 export type HookEvent = "PreToolUse" | "PostToolUse" | "PreSession" | "PostSession" | "Notification";
-/** A rule delegated to an external tool (linter, ast-grep, dependency-cruiser, etc.). */
+/** A rule delegated to an external tool (linter, ast-grep, dependency-cruiser, etc.) or to a vigiles-internal check. */
 export interface EnforceRule {
     readonly _kind: "enforce";
-    readonly linterRule: LinterRule;
+    readonly linterRule: LinterRule | VigilesRef;
     readonly why: string;
-    /** Skip linter verification for this rule. Default: true (verify). */
+    /** Skip verification for this rule. Default: true (verify). */
     readonly verify: boolean;
 }
 /** A guidance-only rule (prose, no enforcement). */
@@ -65,18 +65,28 @@ export interface GuidanceRule {
     readonly _kind: "guidance";
     readonly text: string;
 }
-export type Rule = EnforceRule | GuidanceRule;
+/** A reactive rule: runs a command when watched files change. */
+export interface GuardRule {
+    readonly _kind: "guard";
+    readonly watch: string | readonly string[];
+    readonly run: string;
+    readonly description: string;
+}
+export type Rule = EnforceRule | GuidanceRule | GuardRule;
 /**
- * Declare a rule enforced by an external tool.
+ * Declare a rule enforced by an external tool or vigiles itself.
  *
  * When generated types are present, the `linterRule` argument is narrowed
- * to only accept rules that exist in your linter configs.
+ * to only accept rules that exist in your linter configs. Vigiles-internal
+ * checks use the `vigiles/<assertion-id>` namespace and are dispatched to
+ * built-in mechanical validators (e.g. `vigiles/orphan-docs`).
  *
  *   enforce("eslint/no-console", "Use structured logger.")
  *   enforce("@typescript-eslint/no-floating-promises", "Always await.")
  *   enforce("ruff/T201", "Use logging module.")
+ *   enforce("vigiles/orphan-docs", "No docs without spec references.")
  */
-export declare function enforce(linterRule: NoInfer<StrictLinterRule>, why: string, options?: {
+export declare function enforce(ref: NoInfer<StrictLinterRule> | VigilesRef, why: string, options?: {
     verify?: boolean;
 }): EnforceRule;
 /**
@@ -85,6 +95,16 @@ export declare function enforce(linterRule: NoInfer<StrictLinterRule>, why: stri
  *   guidance("Google unfamiliar APIs before implementing.")
  */
 export declare function guidance(text: string): GuidanceRule;
+/**
+ * Declare a reactive guard: runs a command when watched files change.
+ *
+ *   guard({ watch: "*.spec.ts", run: "npx vigiles compile" }, "Recompile on spec change")
+ *   guard({ watch: ["eslint.config.*", "package.json"], run: "npx vigiles generate-types" }, "Regen types")
+ */
+export declare function guard(options: {
+    watch: string | readonly string[];
+    run: string;
+}, description: string): GuardRule;
 /**
  * Branded string types — these prove a reference has gone through
  * vigiles's verification. The compiler only accepts branded refs,
@@ -115,7 +135,13 @@ export interface SkillRef {
     readonly _ref: "skill";
     readonly path: VerifiedRef;
 }
-export type Ref = FileRef | CmdRef | SkillRef;
+/** A typed symbol reference — the named file must define the named symbol. */
+export interface SymbolRef {
+    readonly _ref: "symbol";
+    readonly file: VerifiedPath;
+    readonly symbol: string;
+}
+export type Ref = FileRef | CmdRef | SkillRef | SymbolRef;
 /**
  * Reference a file path — verified to exist at compile time.
  * When generated types are present, narrowed to known project files.
@@ -126,6 +152,13 @@ export declare function file(path: NoInfer<StrictFile>): FileRef;
  * When generated types are present, narrowed to known npm scripts.
  */
 export declare function cmd(command: NoInfer<StrictCmd>): CmdRef;
+/**
+ * Reference a symbol defined in a file — verified at compile time that the
+ * named file exists AND defines the named symbol (via ast-grep, cross-language).
+ * Compiles to the file-qualified inline form `` `file#symbol` `` so the markdown
+ * `audit` / `refs-hook` re-verify the same reference.
+ */
+export declare function symbol(file: NoInfer<StrictFile>, name: string): SymbolRef;
 /**
  * Reference another skill or instruction file — verified to exist.
  * Compiles to a markdown link: [skill name](path)
@@ -194,18 +227,91 @@ type ClaudeSpecInput = ClaudeSpecBase & ClaudeSpecSections;
  *   export default claude({ commands: {...}, rules: {...} });
  */
 export declare function claude(spec: ClaudeSpecInput): ClaudeSpec;
+/**
+ * A deterministic gate on a skill step or its final result. A gate is one of:
+ * a command (exit 0), a file (must exist), or a *project role* that resolves to
+ * the host project's real command at run time. cmd/file gates are verified
+ * against the repo at author time; role gates are portable — a skill that runs
+ * in other repos should prefer `project("test")` over a hard-coded `npm test`.
+ */
+export type Gate = CmdRef | FileRef | RoleGate;
+/** Project command roles, resolved per host project at run time. */
+export type ProjectRole = "test" | "build" | "lint";
+/** A portable gate that resolves to the host project's command for a role. */
+export interface RoleGate {
+    readonly _ref: "role";
+    readonly role: ProjectRole;
+}
+/**
+ * A portable gate that resolves to the host project's command for a role
+ * (e.g. `project("test")` → `npm test` / `pytest` / `cargo test`). Use this
+ * in skills meant to run across projects, instead of hard-coding a command.
+ */
+export declare function project(role: ProjectRole): RoleGate;
+/**
+ * A declared skill input. Compiles to the `argument-hint` frontmatter and a
+ * `## Arguments` section; referenced as `$1`/`$2`/`$ARGUMENTS` in the body.
+ */
+export interface SkillInput {
+    /** Argument name, e.g. "pattern". */
+    readonly name: string;
+    /** Human-readable hint shown in argument-hint and the Arguments section. */
+    readonly hint: string;
+    /** Required by default; set false to render as optional (`[<name>]`). */
+    readonly required?: boolean;
+}
+/** One step of a gated skill pipeline. */
+export interface SkillStep {
+    /** What the model should do — prose, optionally with typed refs. */
+    readonly do: string | InstructionFragment[];
+    /** Deterministic check that must pass before advancing to the next step. */
+    readonly gate?: Gate;
+    /** Max attempts to satisfy the gate before the step fails (default 1). */
+    readonly retry?: number;
+}
+/** Declare a skill input (compiles to argument-hint + an Arguments entry). */
+export declare function input(name: string, hint: string, opts?: {
+    required?: boolean;
+}): SkillInput;
+/** Declare a gated pipeline step. */
+export declare function step(instr: string | InstructionFragment[], opts?: {
+    gate?: Gate;
+    retry?: number;
+}): SkillStep;
 export interface SkillSpec {
     readonly _specType: "skill";
     /** Skill name (used in frontmatter). */
     readonly name: string;
     /** Short description (used in frontmatter). */
     readonly description: string;
-    /** Hint for the argument (used in frontmatter). */
+    /**
+     * Hint for the argument (frontmatter). Ignored when `inputs` is set —
+     * `inputs` derive the argument-hint instead.
+     */
     readonly argumentHint?: string;
+    /** Typed inputs — compile to argument-hint + a `## Arguments` section. */
+    readonly inputs?: readonly SkillInput[];
     /** Whether to disable model invocation (frontmatter flag). */
     readonly disableModelInvocation?: boolean;
-    /** Instruction body — string or tagged template with typed refs. */
-    readonly body: string | InstructionFragment[];
+    /**
+     * Gated pipeline steps. When set, the skill compiles to a `## Steps`
+     * checklist with a deterministic gate per step. Use this OR `body`.
+     */
+    readonly steps?: readonly SkillStep[];
+    /**
+     * Terminal postcondition — the skill is "done" only when this gate passes.
+     * Compiles to a `## Result` section + a `vigiles:result` marker.
+     */
+    readonly result?: Gate;
+    /** Freeform instruction body (linear/unstructured skills). Use this OR `steps`. */
+    readonly body?: string | InstructionFragment[];
+    /**
+     * Max lines for an inline fenced code block before compilation errors,
+     * forcing the script into a file referenced via `file()` (default 20).
+     * Keeps big scripts out of the skill body (token budget + progressive
+     * disclosure). Set 0 to disable.
+     */
+    readonly maxInlineCodeLines?: number;
 }
 /**
  * Define a SKILL.md specification.

package/dist/spec.js

@@ -12,31 +12,39 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.enforce = enforce;
 exports.guidance = guidance;
+exports.guard = guard;
 exports.file = file;
 exports.cmd = cmd;
+exports.symbol = symbol;
 exports.ref = ref;
 exports.instructions = instructions;
 exports.claude = claude;
+exports.project = project;
+exports.input = input;
+exports.step = step;
 exports.skill = skill;
 exports.defineConfig = defineConfig;
 // ---------------------------------------------------------------------------
 // Builder functions
 // ---------------------------------------------------------------------------
 /**
- * Declare a rule enforced by an external tool.
+ * Declare a rule enforced by an external tool or vigiles itself.
  *
  * When generated types are present, the `linterRule` argument is narrowed
- * to only accept rules that exist in your linter configs.
+ * to only accept rules that exist in your linter configs. Vigiles-internal
+ * checks use the `vigiles/<assertion-id>` namespace and are dispatched to
+ * built-in mechanical validators (e.g. `vigiles/orphan-docs`).
  *
  *   enforce("eslint/no-console", "Use structured logger.")
  *   enforce("@typescript-eslint/no-floating-promises", "Always await.")
  *   enforce("ruff/T201", "Use logging module.")
+ *   enforce("vigiles/orphan-docs", "No docs without spec references.")
  */
-function enforce(linterRule, why, options) {
+function enforce(ref, why, options) {
     return {
         _kind: "enforce",
         // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-assertion
-        linterRule: linterRule,
+        linterRule: ref,
         why,
         verify: options?.verify ?? true,
     };
@@ -49,6 +57,20 @@ function enforce(linterRule, why, options) {
 function guidance(text) {
     return { _kind: "guidance", text };
 }
+/**
+ * Declare a reactive guard: runs a command when watched files change.
+ *
+ *   guard({ watch: "*.spec.ts", run: "npx vigiles compile" }, "Recompile on spec change")
+ *   guard({ watch: ["eslint.config.*", "package.json"], run: "npx vigiles generate-types" }, "Regen types")
+ */
+function guard(options, description) {
+    return {
+        _kind: "guard",
+        watch: options.watch,
+        run: options.run,
+        description,
+    };
+}
 /**
  * Reference a file path — verified to exist at compile time.
  * When generated types are present, narrowed to known project files.
@@ -63,6 +85,15 @@ function file(path) {
 function cmd(command) {
     return { _ref: "cmd", command: command };
 }
+/**
+ * Reference a symbol defined in a file — verified at compile time that the
+ * named file exists AND defines the named symbol (via ast-grep, cross-language).
+ * Compiles to the file-qualified inline form `` `file#symbol` `` so the markdown
+ * `audit` / `refs-hook` re-verify the same reference.
+ */
+function symbol(file, name) {
+    return { _ref: "symbol", file: file, symbol: name };
+}
 /**
  * Reference another skill or instruction file — verified to exist.
  * Compiles to a markdown link: [skill name](path)
@@ -98,6 +129,22 @@ function instructions(strings, ...values) {
 function claude(spec) {
     return { _specType: "claude", ...spec };
 }
+/**
+ * A portable gate that resolves to the host project's command for a role
+ * (e.g. `project("test")` → `npm test` / `pytest` / `cargo test`). Use this
+ * in skills meant to run across projects, instead of hard-coding a command.
+ */
+function project(role) {
+    return { _ref: "role", role };
+}
+/** Declare a skill input (compiles to argument-hint + an Arguments entry). */
+function input(name, hint, opts = {}) {
+    return { name, hint, required: opts.required };
+}
+/** Declare a gated pipeline step. */
+function step(instr, opts = {}) {
+    return { do: instr, gate: opts.gate, retry: opts.retry };
+}
 /**
  * Define a SKILL.md specification.
  *

package/dist/symbols.d.ts

@@ -0,0 +1,30 @@
+import { Lang } from "@ast-grep/napi";
+/** A language key accepted by ast-grep's `parse` (core enum or registered id). */
+type LangKey = Lang | string;
+/** The ast-grep language for a file, or null if unsupported (graceful skip). */
+export declare function langForFile(file: string): LangKey | null;
+/** A symbol definition found in a file. */
+export interface SymbolDef {
+    /** The defined identifier, e.g. "parseConfig". */
+    readonly name: string;
+    /** The tree-sitter node kind, e.g. "function_declaration" (raw, per-grammar). */
+    readonly kind: string;
+    /** Enclosing class/module name, or "" at top level. */
+    readonly scope: string;
+    /** 1-based line of the definition. */
+    readonly line: number;
+}
+/** Extract the symbols defined in a single file's source. */
+export declare function definedSymbols(code: string, lang: LangKey): SymbolDef[];
+/** Defined symbols for a file on disk, or [] if unreadable/unsupported. */
+export declare function definedSymbolsInFile(file: string): SymbolDef[];
+/**
+ * Whether `file` defines a top-level (or scoped) symbol named `name`. This is
+ * the whole check for a file-qualified reference (`path#symbol`): we parse the
+ * one named file — no project-wide index, no resolution across files. As a
+ * fallback we also consult a co-located declaration file (`.rbi` / `.d.ts`), so
+ * typed dynamic symbols resolve without running Sorbet / the TS compiler.
+ */
+export declare function fileDefinesSymbol(file: string, name: string): boolean;
+export {};
+//# sourceMappingURL=symbols.d.ts.map

package/dist/symbols.js

@@ -0,0 +1,142 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.langForFile = langForFile;
+exports.definedSymbols = definedSymbols;
+exports.definedSymbolsInFile = definedSymbolsInFile;
+exports.fileDefinesSymbol = fileDefinesSymbol;
+/**
+ * vigiles — cross-language symbol index (ast-grep / tree-sitter).
+ *
+ * The kernel of harness-pinned reference verification. Instruction files
+ * reference project symbols in prose (`parseConfig`, `User`, `create_docx.py`);
+ * authors never write a verifiable `file#symbol` form (corpus: ~0%). So instead
+ * of asking authors to annotate, the *harness* resolves a bare reference against
+ * the live code at write time and pins it. This module is the resolver: extract
+ * the symbols a file defines, and build a project-wide name → locations index.
+ *
+ * Boundary (see research/symbol-verification.md): we answer "does a definition
+ * with this name (in this scope) exist", NOT "does this reference resolve through
+ * imports / Zeitwerk / tsconfig". Resolution is per-language and architectural —
+ * delegated. Ambiguity (a name defined in several files) is reported, not guessed.
+ */
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const napi_1 = require("@ast-grep/napi");
+const lang_python_1 = __importDefault(require("@ast-grep/lang-python"));
+const lang_rust_1 = __importDefault(require("@ast-grep/lang-rust"));
+const lang_ruby_1 = __importDefault(require("@ast-grep/lang-ruby"));
+let registered = false;
+function ensureRegistered() {
+    if (registered)
+        return;
+    // Non-web grammars ship as separate packages registered at runtime.
+    (0, napi_1.registerDynamicLanguage)({ python: lang_python_1.default, rust: lang_rust_1.default, ruby: lang_ruby_1.default });
+    registered = true;
+}
+const EXT_LANG = {
+    ".ts": napi_1.Lang.TypeScript,
+    ".tsx": napi_1.Lang.Tsx,
+    ".mts": napi_1.Lang.TypeScript,
+    ".cts": napi_1.Lang.TypeScript,
+    ".d.ts": napi_1.Lang.TypeScript,
+    ".js": napi_1.Lang.JavaScript,
+    ".jsx": napi_1.Lang.JavaScript,
+    ".mjs": napi_1.Lang.JavaScript,
+    ".cjs": napi_1.Lang.JavaScript,
+    ".css": napi_1.Lang.Css,
+    ".py": "python",
+    ".pyi": "python",
+    ".rs": "rust",
+    ".rb": "ruby",
+    ".rbi": "ruby",
+};
+/** The ast-grep language for a file, or null if unsupported (graceful skip). */
+function langForFile(file) {
+    if (file.endsWith(".d.ts"))
+        return napi_1.Lang.TypeScript;
+    return EXT_LANG[(0, node_path_1.extname)(file).toLowerCase()] ?? null;
+}
+const ID_KINDS = new Set(["identifier", "constant", "type_identifier"]);
+const SCOPE_KINDS = new Set([
+    "class_declaration",
+    "class_definition",
+    "class",
+    "module",
+    "interface_declaration",
+    "enum_declaration",
+]);
+function recordNode(node, scope, out) {
+    const line = node.range().start.line + 1;
+    const nameNode = node.field("name");
+    if (nameNode) {
+        out.push({ name: nameNode.text(), kind: node.kind(), scope, line });
+    }
+    // Assignment-style constants (Python/Ruby `X = ...`): the identifier is the
+    // `left` field, not `name`.
+    const left = node.field("left");
+    if (left && ID_KINDS.has(left.kind())) {
+        out.push({ name: left.text(), kind: node.kind(), scope, line });
+    }
+}
+/** Extract the symbols defined in a single file's source. */
+function definedSymbols(code, lang) {
+    ensureRegistered();
+    const out = [];
+    const walk = (node, scope) => {
+        recordNode(node, scope, out);
+        const nameNode = node.field("name");
+        const nextScope = SCOPE_KINDS.has(node.kind()) && nameNode ? nameNode.text() : scope;
+        for (const child of node.children())
+            walk(child, nextScope);
+    };
+    walk((0, napi_1.parse)(lang, code).root(), "");
+    return out;
+}
+/** Defined symbols for a file on disk, or [] if unreadable/unsupported. */
+function definedSymbolsInFile(file) {
+    const lang = langForFile(file);
+    if (!lang)
+        return [];
+    try {
+        return definedSymbols((0, node_fs_1.readFileSync)(file, "utf-8"), lang);
+    }
+    catch {
+        return [];
+    }
+}
+// A co-located declaration file that may declare symbols the source defines
+// dynamically (Sorbet `.rbi`, TypeScript `.d.ts`) — checked as a fallback so a
+// metaprogrammed `define_method` / ambient declaration still resolves.
+const DECL_SIBLING = {
+    ".ts": ".d.ts",
+    ".tsx": ".d.ts",
+    ".js": ".d.ts",
+    ".jsx": ".d.ts",
+    ".mjs": ".d.ts",
+    ".rb": ".rbi",
+};
+/**
+ * Whether `file` defines a top-level (or scoped) symbol named `name`. This is
+ * the whole check for a file-qualified reference (`path#symbol`): we parse the
+ * one named file — no project-wide index, no resolution across files. As a
+ * fallback we also consult a co-located declaration file (`.rbi` / `.d.ts`), so
+ * typed dynamic symbols resolve without running Sorbet / the TS compiler.
+ */
+function fileDefinesSymbol(file, name) {
+    if (definedSymbolsInFile(file).some((d) => d.name === name))
+        return true;
+    const ext = (0, node_path_1.extname)(file);
+    const decl = DECL_SIBLING[ext];
+    if (decl && !file.endsWith(decl)) {
+        const sibling = file.slice(0, -ext.length) + decl;
+        if ((0, node_fs_1.existsSync)(sibling) &&
+            definedSymbolsInFile(sibling).some((d) => d.name === name)) {
+            return true;
+        }
+    }
+    return false;
+}
+//# sourceMappingURL=symbols.js.map

package/dist/test-utils.d.ts

@@ -0,0 +1,8 @@
+import type { ClaudeSpec } from "./spec.js";
+export declare function makeTmpDir(suffix?: string): string;
+export declare function cleanupTmpDir(dir: string): void;
+export declare function makeSpec(overrides?: Partial<ClaudeSpec>): ClaudeSpec;
+declare function git(cwd: string, cmd: string): string;
+export declare function initGitRepo(dir: string): void;
+export { git };
+//# sourceMappingURL=test-utils.d.ts.map

package/dist/test-utils.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.makeTmpDir = makeTmpDir;
+exports.cleanupTmpDir = cleanupTmpDir;
+exports.makeSpec = makeSpec;
+exports.initGitRepo = initGitRepo;
+exports.git = git;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const node_os_1 = require("node:os");
+const node_child_process_1 = require("node:child_process");
+function makeTmpDir(suffix = "test") {
+    return (0, node_fs_1.mkdtempSync)((0, node_path_1.join)((0, node_os_1.tmpdir)(), `vigiles-${suffix}-`));
+}
+function cleanupTmpDir(dir) {
+    (0, node_fs_1.rmSync)(dir, { recursive: true, force: true });
+}
+function makeSpec(overrides) {
+    return {
+        _specType: "claude",
+        rules: {},
+        ...overrides,
+    };
+}
+function git(cwd, cmd) {
+    return (0, node_child_process_1.execSync)(`git ${cmd}`, {
+        cwd,
+        encoding: "utf-8",
+        stdio: ["pipe", "pipe", "pipe"],
+    }).trim();
+}
+function initGitRepo(dir) {
+    git(dir, "init");
+    git(dir, "config user.email test@test.com");
+    git(dir, "config user.name Test");
+    git(dir, "config commit.gpgsign false");
+    (0, node_fs_1.writeFileSync)((0, node_path_1.join)(dir, "README.md"), "# test");
+    git(dir, "add .");
+    git(dir, 'commit -m "init"');
+}
+//# sourceMappingURL=test-utils.js.map