vigiles 2.1.1 → 2.2.0

package/dist/skill-runtime.js

@@ -0,0 +1,289 @@
+"use strict";
+/**
+ * vigiles — Skill runtime: the deterministic gate ladder.
+ *
+ * Parses the `vigiles:gate` / `vigiles:result` markers a compiled SKILL.md
+ * carries (emitted by compileSkill) and *executes* them: run each step's gate
+ * in document order, short-circuit on the first failure (Railway error track),
+ * then run the terminal result gate. This is the deterministic spine of the
+ * skill driver — the part that turns the markers from documentation into
+ * enforcement.
+ *
+ * Scope (v0): this runs the GATES only. It does not drive the LLM through the
+ * prose steps one at a time — that needs a live harness and is a later phase.
+ * `retry:N` is parsed and surfaced but executed once here: re-running a
+ * deterministic gate without a model in the loop to fix the step yields the
+ * same result. Retry is meaningful only once the model re-does the step
+ * between attempts.
+ *
+ * Safety: this executes the gate commands the skill author declared (e.g.
+ * `npm test`, `validate.py`) via an explicit, user-invoked command
+ * (`vigiles run-skill`). It is not a silent hook and runs nothing the spec
+ * didn't declare as a gate.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseSkillGates = parseSkillGates;
+exports.detectProjectCommand = detectProjectCommand;
+exports.runGate = runGate;
+exports.gateLabel = gateLabel;
+exports.runSkillGates = runSkillGates;
+exports.setActiveSkill = setActiveSkill;
+exports.clearActiveSkill = clearActiveSkill;
+exports.readActiveSkill = readActiveSkill;
+exports.evaluateStopHook = evaluateStopHook;
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const STEP_RE = /^###\s+Step\s+(\d+)/;
+const GATE_CMD_RE = /<!--\s*vigiles:gate\s+"([^"]*)"(?:\s+retry:(\d+))?\s*-->/;
+const GATE_FILE_RE = /<!--\s*vigiles:gate\s+file:(\S+)\s*-->/;
+const GATE_ROLE_RE = /<!--\s*vigiles:gate\s+role:(\w+)(?:\s+retry:(\d+))?\s*-->/;
+const RESULT_CMD_RE = /<!--\s*vigiles:result\s+"([^"]*)"\s*-->/;
+const RESULT_FILE_RE = /<!--\s*vigiles:result\s+file:(\S+)\s*-->/;
+const RESULT_ROLE_RE = /<!--\s*vigiles:result\s+role:(\w+)\s*-->/;
+/** Parse a single line into a gate, or null if it carries none. */
+function parseGateLine(line) {
+    const cmd = GATE_CMD_RE.exec(line);
+    if (cmd) {
+        return { kind: "cmd", command: cmd[1], retry: cmd[2] ? Number(cmd[2]) : 1 };
+    }
+    const role = GATE_ROLE_RE.exec(line);
+    if (role) {
+        return {
+            kind: "role",
+            role: role[1],
+            retry: role[2] ? Number(role[2]) : 1,
+        };
+    }
+    const fileM = GATE_FILE_RE.exec(line);
+    if (fileM)
+        return { kind: "file", path: fileM[1], retry: 1 };
+    return null;
+}
+/** Parse the terminal result gate from a line, or null. */
+function parseResultLine(line) {
+    const cmd = RESULT_CMD_RE.exec(line);
+    if (cmd)
+        return { kind: "cmd", command: cmd[1], retry: 1 };
+    const role = RESULT_ROLE_RE.exec(line);
+    if (role)
+        return { kind: "role", role: role[1], retry: 1 };
+    const fileM = RESULT_FILE_RE.exec(line);
+    if (fileM)
+        return { kind: "file", path: fileM[1], retry: 1 };
+    return null;
+}
+/** Extract the step gates and result gate from a compiled SKILL.md. */
+function parseSkillGates(markdown) {
+    const steps = [];
+    let result;
+    let currentStep = 0;
+    for (const line of markdown.split("\n")) {
+        const stepMatch = STEP_RE.exec(line);
+        if (stepMatch) {
+            currentStep = Number(stepMatch[1]);
+            continue;
+        }
+        const resultGate = parseResultLine(line);
+        if (resultGate) {
+            result = resultGate;
+            continue;
+        }
+        const gate = parseGateLine(line);
+        if (gate)
+            steps.push({ step: currentStep, gate });
+    }
+    return { steps, result };
+}
+/** Execute a shell command in `cwd`; exit 0 = pass, capturing output. */
+function execCommand(command, cwd) {
+    try {
+        const out = (0, node_child_process_1.execSync)(command, {
+            cwd,
+            encoding: "utf-8",
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        return { ok: true, output: out.trim() };
+    }
+    catch (e) {
+        const err = e;
+        const output = [err.stdout, err.stderr].filter(Boolean).join("\n").trim();
+        return { ok: false, output };
+    }
+}
+const NPM_FOR_ROLE = {
+    test: "npm test",
+    build: "npm run build",
+    lint: "npm run lint",
+};
+/** Detect the npm command for a role from package.json scripts, or null. */
+function detectNpmCommand(role, cwd) {
+    const pkg = (0, node_path_1.resolve)(cwd, "package.json");
+    if (!(0, node_fs_1.existsSync)(pkg))
+        return null;
+    try {
+        const scripts = JSON.parse((0, node_fs_1.readFileSync)(pkg, "utf-8")).scripts ?? {};
+        return scripts[role] ? (NPM_FOR_ROLE[role] ?? null) : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Non-npm ecosystems: marker files + the command for each role. */
+const ECOSYSTEMS = [
+    {
+        markers: ["pyproject.toml", "setup.cfg"],
+        commands: { test: "pytest", lint: "ruff check ." },
+    },
+    {
+        markers: ["Cargo.toml"],
+        commands: {
+            test: "cargo test",
+            build: "cargo build",
+            lint: "cargo clippy",
+        },
+    },
+    {
+        markers: ["go.mod"],
+        commands: { test: "go test ./...", build: "go build ./..." },
+    },
+];
+/**
+ * Resolve a project role (test/build/lint) to the host project's real command,
+ * detected from its ecosystem. Returns null when no command can be found —
+ * which the caller surfaces as a failed gate rather than a silent pass.
+ */
+function detectProjectCommand(role, cwd) {
+    const npm = detectNpmCommand(role, cwd);
+    if (npm)
+        return npm;
+    for (const eco of ECOSYSTEMS) {
+        const present = eco.markers.some((m) => (0, node_fs_1.existsSync)((0, node_path_1.resolve)(cwd, m)));
+        const command = eco.commands[role];
+        if (present && command)
+            return command;
+    }
+    return null;
+}
+/**
+ * Run one gate against `cwd`: a command (exit 0 = pass), a file existence, or
+ * a project role resolved to the host project's command.
+ */
+function runGate(gate, cwd) {
+    if (gate.kind === "file") {
+        const there = (0, node_fs_1.existsSync)((0, node_path_1.resolve)(cwd, gate.path));
+        return { ok: there, output: there ? "" : `${gate.path} not found` };
+    }
+    if (gate.kind === "role") {
+        const command = detectProjectCommand(gate.role, cwd);
+        if (!command) {
+            return {
+                ok: false,
+                output: `No ${gate.role} command detected for this project`,
+            };
+        }
+        return execCommand(command, cwd);
+    }
+    return execCommand(gate.command, cwd);
+}
+/** Human-readable label for a gate (for reports and hook messages). */
+function gateLabel(gate) {
+    if (gate.kind === "cmd")
+        return `\`${gate.command}\``;
+    if (gate.kind === "role")
+        return `the project's ${gate.role} command`;
+    return `${gate.path} exists`;
+}
+/**
+ * Run the gate ladder: step gates in order (short-circuiting on the first
+ * failure), then the result gate. Mirrors a Sequence behavior tree —
+ * ordered AND with short-circuit on FAILURE.
+ */
+function runSkillGates(gates, cwd) {
+    const results = [];
+    for (const { step, gate } of gates.steps) {
+        const r = runGate(gate, cwd);
+        results.push({ at: step, gate, ok: r.ok, output: r.output });
+        if (!r.ok)
+            return { results, blockedAt: step, ok: false };
+    }
+    if (gates.result) {
+        const r = runGate(gates.result, cwd);
+        results.push({
+            at: "result",
+            gate: gates.result,
+            ok: r.ok,
+            output: r.output,
+        });
+        if (!r.ok)
+            return { results, blockedAt: "result", ok: false };
+    }
+    return { results, blockedAt: null, ok: true };
+}
+// ---------------------------------------------------------------------------
+// Stop-hook enforcement
+// ---------------------------------------------------------------------------
+//
+// A skill is "active" while the agent is executing it. The Stop hook then runs
+// the active skill's result gate and blocks completion until it passes — so the
+// agent cannot declare a skill done until its result is deterministically
+// proven. Which skill is active is tracked in `.vigiles/active-skill.json`
+// (Claude Code hooks don't surface the active skill, so we record it). Wiring
+// `skill-start` to fire automatically is the integration step; the decision
+// logic below is harness-agnostic and fully testable.
+const ACTIVE_PATH = ".vigiles/active-skill.json";
+/** Record the skill the agent is currently executing. */
+function setActiveSkill(cwd, skillPath) {
+    const p = (0, node_path_1.resolve)(cwd, ACTIVE_PATH);
+    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(p), { recursive: true });
+    (0, node_fs_1.writeFileSync)(p, JSON.stringify({ skill: skillPath }) + "\n");
+}
+/** Clear the active-skill marker (the skill finished). */
+function clearActiveSkill(cwd) {
+    const p = (0, node_path_1.resolve)(cwd, ACTIVE_PATH);
+    if ((0, node_fs_1.existsSync)(p))
+        (0, node_fs_1.rmSync)(p);
+}
+/** The path of the active skill, or null when none is in progress. */
+function readActiveSkill(cwd) {
+    const p = (0, node_path_1.resolve)(cwd, ACTIVE_PATH);
+    if (!(0, node_fs_1.existsSync)(p))
+        return null;
+    try {
+        const parsed = JSON.parse((0, node_fs_1.readFileSync)(p, "utf-8"));
+        return typeof parsed.skill === "string" ? parsed.skill : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Stop-hook decision. If a skill is active and declares a result gate, run it:
+ * allow the stop only when the gate passes; otherwise block and tell the model
+ * what to fix. With no active skill (or no result gate), always allow.
+ */
+function evaluateStopHook(cwd) {
+    const skillPath = readActiveSkill(cwd);
+    if (!skillPath)
+        return { allow: true, message: "" };
+    const full = (0, node_path_1.resolve)(cwd, skillPath);
+    if (!(0, node_fs_1.existsSync)(full))
+        return { allow: true, message: "" };
+    const gates = parseSkillGates((0, node_fs_1.readFileSync)(full, "utf-8"));
+    if (!gates.result)
+        return { allow: true, message: "" };
+    const outcome = runGate(gates.result, cwd);
+    const desc = gateLabel(gates.result);
+    if (outcome.ok) {
+        return {
+            allow: true,
+            message: `✓ ${skillPath}: result gate ${desc} passed.`,
+        };
+    }
+    const tail = outcome.output ? `\n${outcome.output}` : "";
+    return {
+        allow: false,
+        message: `Skill "${skillPath}" is not done: result gate ${desc} failed. Fix it, then finish.${tail}`,
+    };
+}
+//# sourceMappingURL=skill-runtime.js.map

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

@@ -135,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.
@@ -146,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)
@@ -214,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

@@ -15,9 +15,13 @@ 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;
 // ---------------------------------------------------------------------------
@@ -81,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)
@@ -116,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