vigiles 2.0.0 → 2.2.0

package/dist/compile.js

@@ -10,13 +10,18 @@ exports.computeHash = computeHash;
 exports.addHash = addHash;
 exports.verifyHash = verifyHash;
 exports.estimateTokens = estimateTokens;
+exports.validateFileRef = validateFileRef;
+exports.readPackageScripts = readPackageScripts;
+exports.validateCommandRef = validateCommandRef;
+exports.validateSymbolRef = validateSymbolRef;
 exports.compileClaude = compileClaude;
 exports.compileSkill = compileSkill;
 exports.checkFileHash = checkFileHash;
 exports.adoptDiff = adoptDiff;
-const node_crypto_1 = require("node:crypto");
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
+const hash_js_1 = require("./hash.js");
+const symbols_js_1 = require("./symbols.js");
 const linters_js_1 = require("./linters.js");
 // ---------------------------------------------------------------------------
 // Hash utilities
@@ -25,7 +30,7 @@ const HASH_RE = /^<!-- vigiles:sha256:([a-f0-9]+) compiled from (.+) -->\r?\n\r?
 /** @internal Compute SHA-256 hash of content (excluding any existing hash line). */
 function computeHash(content) {
     const body = content.replace(HASH_RE, "");
-    return (0, node_crypto_1.createHash)("sha256").update(body).digest("hex").slice(0, 16);
+    return (0, hash_js_1.sha256short)(body);
 }
 /** @internal Prepend a hash comment to compiled content. */
 function addHash(content, specFile) {
@@ -40,10 +45,7 @@ function verifyHash(content) {
     const expectedHash = match[1];
     const specFile = match[2];
     const body = content.replace(HASH_RE, "");
-    const actualHash = (0, node_crypto_1.createHash)("sha256")
-        .update(body)
-        .digest("hex")
-        .slice(0, 16);
+    const actualHash = (0, hash_js_1.sha256short)(body);
     return { valid: actualHash === expectedHash, specFile };
 }
 // ---------------------------------------------------------------------------
@@ -86,24 +88,57 @@ function readPackageScripts(basePath) {
     }
 }
 function validateCommandRef(command, basePath) {
-    // Check "npm run <script>" or "npm <script>" against package.json
     const npmRunMatch = command.match(/^npm\s+run\s+(\S+)/);
     const npmMatch = command.match(/^npm\s+(test|start|build|pretest)\b/);
     const scriptName = npmRunMatch?.[1] ?? npmMatch?.[1];
-    if (!scriptName)
-        return null;
-    const scripts = readPackageScripts(basePath);
-    if (!scripts)
+    if (scriptName) {
+        const scripts = readPackageScripts(basePath);
+        if (scripts && !scripts[scriptName]) {
+            return {
+                type: "stale-command",
+                message: `Script "${scriptName}" not found in package.json`,
+                path: command,
+            };
+        }
         return null;
-    if (!scripts[scriptName]) {
+    }
+    // Script-runner commands (python/node/bash/ruby/…): verify the referenced
+    // script file exists. Module forms (`python -m pkg`) are skipped — no path.
+    const scriptFile = command.match(/^(?:python3?|node|bash|sh|ruby|deno run)\s+([^\s-]\S*\.[A-Za-z0-9]+)/)?.[1];
+    if (scriptFile && !(0, node_fs_1.existsSync)((0, node_path_1.resolve)(basePath, scriptFile))) {
         return {
             type: "stale-command",
-            message: `Script "${scriptName}" not found in package.json`,
+            message: `Script "${scriptFile}" not found`,
             path: command,
         };
     }
     return null;
 }
+function validateSymbolRef(file, name, basePath) {
+    const full = (0, node_path_1.resolve)(basePath, file);
+    if (!(0, node_fs_1.existsSync)(full)) {
+        return {
+            type: "stale-file",
+            message: `File not found: "${file}"`,
+            path: file,
+        };
+    }
+    if ((0, symbols_js_1.langForFile)(file) === null) {
+        return {
+            type: "stale-ref",
+            message: `Unsupported language for symbol check: "${file}"`,
+            path: file,
+        };
+    }
+    if (!(0, symbols_js_1.fileDefinesSymbol)(full, name)) {
+        return {
+            type: "stale-ref",
+            message: `"${name}" is not defined in ${file}`,
+            path: `${file}#${name}`,
+        };
+    }
+    return null;
+}
 function validateRefs(fragments, basePath) {
     const errors = [];
     for (const fragment of fragments) {
@@ -134,6 +169,12 @@ function validateRefs(fragments, basePath) {
                 }
                 break;
             }
+            case "symbol": {
+                const err = validateSymbolRef(r.file, r.symbol, basePath);
+                if (err)
+                    errors.push(err);
+                break;
+            }
         }
     }
     return errors;
@@ -141,14 +182,17 @@ function validateRefs(fragments, basePath) {
 function renderFragment(fragment) {
     if (typeof fragment === "string")
         return fragment;
-    const r = fragment;
-    switch (r._ref) {
+    switch (fragment._ref) {
         case "file":
-            return `\`${r.path}\``;
+            return `\`${fragment.path}\``;
         case "cmd":
-            return `\`${r.command}\``;
+            return `\`${fragment.command}\``;
         case "skill":
-            return `[${(0, node_path_1.basename)((0, node_path_1.dirname)(r.path))}](${r.path})`;
+            return `[${(0, node_path_1.basename)((0, node_path_1.dirname)(fragment.path))}](${fragment.path})`;
+        case "symbol":
+            return `\`vigiles:symbol ${fragment.file}#${fragment.symbol}\``;
+        default:
+            return (0, hash_js_1.assertNever)(fragment);
     }
 }
 // ---------------------------------------------------------------------------
@@ -168,15 +212,19 @@ function compileRule(id, rule) {
             ].join("\n");
         case "guidance":
             return [`### ${title}`, "", `**Guidance only** — ${rule.text}`].join("\n");
-        default: {
-            // Unknown rule kind — legacy compiled JS spec artifacts, JS caller,
-            // or cast bypass. Fail loudly rather than silently dropping the
-            // rule from output, which would remove constraints without any
-            // compile error.
-            const unknown = rule._kind;
-            throw new Error(`Unknown rule kind "${String(unknown)}" for rule "${id}". ` +
-                `Expected "enforce" or "guidance". Runtime data is out of sync with the Rule type.`);
+        case "guard": {
+            const patterns = Array.isArray(rule.watch)
+                ? rule.watch.join("`, `")
+                : rule.watch;
+            return [
+                `### ${title}`,
+                "",
+                `**Guard:** \`${patterns}\` → \`${rule.run}\``,
+                `**Why:** ${rule.description}`,
+            ].join("\n");
         }
+        default:
+            return (0, hash_js_1.assertNever)(rule);
     }
 }
 function validateSectionContent(name, text, maxSectionLines) {
@@ -404,6 +452,166 @@ function renderBody(body) {
         return body;
     return body.map(renderFragment).join("");
 }
+/** Derive the `argument-hint` frontmatter value from typed inputs. */
+function renderArgumentHint(inputs) {
+    return inputs
+        .map((i) => (i.required === false ? `[<${i.name}>]` : `<${i.name}>`))
+        .join(" ");
+}
+/** Render the `## Arguments` section from typed inputs. */
+function renderArguments(inputs) {
+    const lines = ["## Arguments", ""];
+    inputs.forEach((i, idx) => {
+        const opt = i.required === false ? " _(optional)_" : "";
+        lines.push(`- \`$${String(idx + 1)}\` **${i.name}**${opt} — ${i.hint}`);
+    });
+    return lines.join("\n");
+}
+/** The human prose + machine-readable marker for a gate. */
+function renderGate(gate, retry) {
+    if (gate._ref === "cmd") {
+        const r = retry && retry > 1 ? ` retry:${String(retry)}` : "";
+        const proseR = retry && retry > 1 ? ` (retry up to ${String(retry)}×)` : "";
+        return {
+            prose: `**Gate** — run \`${gate.command}\`${proseR}; do not proceed until it passes.`,
+            marker: `<!-- vigiles:gate "${gate.command}"${r} -->`,
+        };
+    }
+    if (gate._ref === "role") {
+        const proseR = retry && retry > 1 ? ` (retry up to ${String(retry)}×)` : "";
+        const r = retry && retry > 1 ? ` retry:${String(retry)}` : "";
+        return {
+            prose: `**Gate** — run the project's ${gate.role} command${proseR}; do not proceed until it passes.`,
+            marker: `<!-- vigiles:gate role:${gate.role}${r} -->`,
+        };
+    }
+    return {
+        prose: `**Gate** — \`${gate.path}\` must exist before proceeding.`,
+        marker: `<!-- vigiles:gate file:${gate.path} -->`,
+    };
+}
+/** Render the `## Steps` checklist with a gate per step. */
+function renderSteps(steps) {
+    const out = ["## Steps", ""];
+    steps.forEach((s, idx) => {
+        out.push(`### Step ${String(idx + 1)}`, "");
+        out.push(renderBody(s.do).trim(), "");
+        if (s.gate) {
+            const g = renderGate(s.gate, s.retry);
+            out.push(g.prose, "", g.marker, "");
+        }
+    });
+    return out.join("\n").trimEnd();
+}
+/** Render the `## Result` postcondition gate. */
+function renderResult(result) {
+    let target;
+    let marker;
+    if (result._ref === "cmd") {
+        target = `\`${result.command}\` passes`;
+        marker = `<!-- vigiles:result "${result.command}" -->`;
+    }
+    else if (result._ref === "role") {
+        target = `the project's ${result.role} command passes`;
+        marker = `<!-- vigiles:result role:${result.role} -->`;
+    }
+    else {
+        target = `\`${result.path}\` exists`;
+        marker = `<!-- vigiles:result file:${result.path} -->`;
+    }
+    return [
+        "## Result",
+        "",
+        `This skill is complete when ${target}.`,
+        "",
+        marker,
+    ].join("\n");
+}
+/** Gather every reference a skill carries that needs author-time verification. */
+function collectSkillRefs(spec) {
+    const refs = [];
+    if (Array.isArray(spec.body))
+        refs.push(...spec.body);
+    for (const s of spec.steps ?? []) {
+        if (Array.isArray(s.do))
+            refs.push(...s.do);
+        // Role gates resolve per host project at run time — nothing to verify here.
+        if (s.gate && s.gate._ref !== "role")
+            refs.push(s.gate);
+    }
+    if (spec.result && spec.result._ref !== "role")
+        refs.push(spec.result);
+    return refs;
+}
+/** Build the SKILL.md YAML frontmatter block. */
+function renderSkillFrontmatter(spec) {
+    const fm = [
+        "---",
+        "",
+        `name: ${spec.name}`,
+        `description: ${spec.description}`,
+    ];
+    if (spec.disableModelInvocation !== undefined) {
+        fm.push(`disable-model-invocation: ${String(spec.disableModelInvocation)}`);
+    }
+    const argHint = spec.inputs && spec.inputs.length > 0
+        ? renderArgumentHint(spec.inputs)
+        : spec.argumentHint;
+    if (argHint)
+        fm.push(`argument-hint: ${argHint}`);
+    fm.push("", "---");
+    return fm.join("\n");
+}
+/**
+ * Compose the body: Arguments, then the knowledge body (reference prose), then
+ * the gated Steps, then the Result. body + steps compose — a skill can carry
+ * both a rich reference body and a verified procedure.
+ */
+function renderSkillSections(spec) {
+    const sections = [];
+    if (spec.inputs && spec.inputs.length > 0) {
+        sections.push(renderArguments(spec.inputs));
+    }
+    if (spec.body !== undefined)
+        sections.push(renderBody(spec.body).trim());
+    if (spec.steps && spec.steps.length > 0) {
+        sections.push(renderSteps(spec.steps));
+    }
+    if (spec.result)
+        sections.push(renderResult(spec.result));
+    return sections.join("\n\n");
+}
+const DEFAULT_MAX_INLINE_CODE_LINES = 20;
+/** Flag inline fenced code blocks longer than `max` lines (0 = disabled). */
+function checkInlineCode(markdown, max) {
+    if (max <= 0)
+        return [];
+    const errs = [];
+    const lines = markdown.split("\n");
+    let start = -1;
+    let lang = "";
+    for (let i = 0; i < lines.length; i++) {
+        const m = /^```(\w*)/.exec(lines[i].trim());
+        if (!m)
+            continue;
+        if (start === -1) {
+            start = i;
+            lang = m[1];
+        }
+        else {
+            const len = i - start - 1;
+            if (len > max) {
+                errs.push({
+                    type: "section-too-long",
+                    message: `Inline ${lang || "code"} block is ${String(len)} lines (max ${String(max)}); extract it to a file and reference it with file().`,
+                });
+            }
+            start = -1;
+            lang = "";
+        }
+    }
+    return errs;
+}
 /**
  * Compile a SkillSpec into SKILL.md markdown with YAML frontmatter.
  */
@@ -427,25 +635,11 @@ function compileSkill(spec, options = {}) {
             });
         }
     }
-    // Validate refs in body
-    if (Array.isArray(spec.body)) {
-        errors.push(...validateRefs(spec.body, basePath));
-    }
-    // Build frontmatter (blank lines after opening/before closing --- for prettier)
-    const fm = ["---", ""];
-    fm.push(`name: ${spec.name}`);
-    fm.push(`description: ${spec.description}`);
-    if (spec.disableModelInvocation !== undefined) {
-        fm.push(`disable-model-invocation: ${String(spec.disableModelInvocation)}`);
-    }
-    if (spec.argumentHint) {
-        fm.push(`argument-hint: ${spec.argumentHint}`);
-    }
-    fm.push("", "---");
-    const body = renderBody(spec.body);
-    const content = fm.join("\n") + "\n\n" + body.trim() + "\n";
-    const markdown = addHash(content, specFile);
-    return { markdown, errors };
+    errors.push(...validateRefs(collectSkillRefs(spec), basePath));
+    const sections = renderSkillSections(spec);
+    errors.push(...checkInlineCode(sections, spec.maxInlineCodeLines ?? DEFAULT_MAX_INLINE_CODE_LINES));
+    const content = renderSkillFrontmatter(spec) + "\n\n" + sections.trim() + "\n";
+    return { markdown: addHash(content, specFile), errors };
 }
 /** Check if a generated file's hash is intact. */
 function checkFileHash(filePath) {

package/dist/coverage.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Spec coverage analysis: how much of the project surface is documented in specs.
+ *
+ * Two metrics:
+ * - Linter rule coverage: % of enabled linter rules with enforce() declarations
+ * - Script coverage: % of npm scripts documented in spec commands
+ *
+ * Configurable thresholds in .vigilesrc.json trigger warnings or errors when
+ * coverage drops below the minimum.
+ */
+import type { CoverageThresholds } from "./types.js";
+import type { ClaudeSpec } from "./spec.js";
+export interface CoverageMetric {
+    name: string;
+    total: number;
+    covered: number;
+    percent: number;
+    threshold: number | undefined;
+    passing: boolean;
+    /** Items that ARE covered. */
+    coveredItems: string[];
+    /** Items that are NOT covered. */
+    uncoveredItems: string[];
+}
+export interface CoverageReport {
+    metrics: CoverageMetric[];
+    passing: boolean;
+}
+/**
+ * Read npm script names from package.json. Reuses readPackageScripts
+ * from compile.ts and returns sorted keys.
+ */
+export declare function readNpmScripts(basePath: string): string[];
+/**
+ * Collect commands documented in specs by loading spec source files directly.
+ * Reads the structured `commands` field — no markdown parsing.
+ */
+export declare function collectDocumentedCommands(basePath: string, specs?: ClaudeSpec[]): Set<string>;
+/**
+ * Compute script coverage: what % of npm scripts are documented in specs.
+ */
+export declare function computeScriptCoverage(basePath: string, threshold?: number, specs?: ClaudeSpec[]): CoverageMetric;
+/**
+ * Compute linter rule coverage from pre-computed totals.
+ * The actual linter scanning is done by the existing discover() in cli.ts.
+ */
+export declare function computeLinterRuleCoverage(enabled: number, documented: number, threshold?: number): CoverageMetric;
+/**
+ * Check all coverage metrics against thresholds.
+ */
+export declare function checkCoverage(basePath: string, thresholds: CoverageThresholds, linterEnabled: number, linterDocumented: number, specs?: ClaudeSpec[]): CoverageReport;
+/**
+ * Format coverage report as human-readable text.
+ */
+export declare function formatCoverageReport(report: CoverageReport): string;
+//# sourceMappingURL=coverage.d.ts.map

package/dist/coverage.js

@@ -0,0 +1,178 @@
+"use strict";
+/**
+ * Spec coverage analysis: how much of the project surface is documented in specs.
+ *
+ * Two metrics:
+ * - Linter rule coverage: % of enabled linter rules with enforce() declarations
+ * - Script coverage: % of npm scripts documented in spec commands
+ *
+ * Configurable thresholds in .vigilesrc.json trigger warnings or errors when
+ * coverage drops below the minimum.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readNpmScripts = readNpmScripts;
+exports.collectDocumentedCommands = collectDocumentedCommands;
+exports.computeScriptCoverage = computeScriptCoverage;
+exports.computeLinterRuleCoverage = computeLinterRuleCoverage;
+exports.checkCoverage = checkCoverage;
+exports.formatCoverageReport = formatCoverageReport;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const glob_1 = require("glob");
+const compile_js_1 = require("./compile.js");
+// ---------------------------------------------------------------------------
+// Script coverage
+// ---------------------------------------------------------------------------
+/**
+ * Read npm script names from package.json. Reuses readPackageScripts
+ * from compile.ts and returns sorted keys.
+ */
+function readNpmScripts(basePath) {
+    const scripts = (0, compile_js_1.readPackageScripts)(basePath);
+    return scripts ? Object.keys(scripts).sort() : [];
+}
+/**
+ * Collect commands documented in specs by loading spec source files directly.
+ * Reads the structured `commands` field — no markdown parsing.
+ */
+function collectDocumentedCommands(basePath, specs) {
+    const commands = new Set();
+    if (specs) {
+        for (const spec of specs) {
+            if (spec.commands) {
+                for (const cmd of Object.keys(spec.commands))
+                    commands.add(cmd);
+            }
+        }
+        return commands;
+    }
+    // Fallback: scan compiled markdown for spec file references, then
+    // load the compiled JS spec from dist/. If that fails, try to
+    // extract commands from the compiled output (last resort).
+    const mdFiles = (0, glob_1.globSync)("**/*.md", {
+        ignore: ["node_modules/**", "dist/**", ".vigiles/**"],
+        cwd: basePath,
+    });
+    for (const mdFile of mdFiles) {
+        const fullPath = (0, node_path_1.resolve)(basePath, mdFile);
+        try {
+            const content = (0, node_fs_1.readFileSync)(fullPath, "utf-8");
+            const specMatch = content.match(/^<!-- vigiles:sha256:[a-f0-9]+ compiled from (.+) -->/);
+            if (!specMatch)
+                continue;
+            // Try to load the spec's compiled JS from dist/
+            const specFile = specMatch[1];
+            const jsPath = (0, node_path_1.resolve)(basePath, "dist", specFile.replace(/\.ts$/, ".js"));
+            if ((0, node_fs_1.existsSync)(jsPath)) {
+                try {
+                    const mod = require(jsPath);
+                    const spec = mod.default && "default" in mod.default
+                        ? mod.default.default
+                        : mod.default;
+                    if (spec?.commands) {
+                        for (const cmd of Object.keys(spec.commands))
+                            commands.add(cmd);
+                    }
+                    continue;
+                }
+                catch {
+                    // Fall through to next file
+                }
+            }
+        }
+        catch {
+            // Skip unreadable files
+        }
+    }
+    return commands;
+}
+/**
+ * Compute script coverage: what % of npm scripts are documented in specs.
+ */
+function computeScriptCoverage(basePath, threshold, specs) {
+    const allScripts = readNpmScripts(basePath);
+    const documented = collectDocumentedCommands(basePath, specs);
+    const covered = [];
+    const uncovered = [];
+    for (const script of allScripts) {
+        // Match the same forms compile-time validation accepts in cmd():
+        // "npm run <script>" or "npm <script>". Bare script names are not
+        // executable refs — accepting them here would let stale entries
+        // satisfy the coverage threshold without being verifiable.
+        const npmRun = `npm run ${script}`;
+        const npmDirect = `npm ${script}`;
+        if (documented.has(npmRun) || documented.has(npmDirect)) {
+            covered.push(script);
+        }
+        else {
+            uncovered.push(script);
+        }
+    }
+    const total = allScripts.length;
+    const percent = total > 0 ? Math.round((covered.length / total) * 100) : 100;
+    const passing = threshold === undefined || percent >= threshold;
+    return {
+        name: "scripts",
+        total,
+        covered: covered.length,
+        percent,
+        threshold,
+        passing,
+        coveredItems: covered,
+        uncoveredItems: uncovered,
+    };
+}
+/**
+ * Compute linter rule coverage from pre-computed totals.
+ * The actual linter scanning is done by the existing discover() in cli.ts.
+ */
+function computeLinterRuleCoverage(enabled, documented, threshold) {
+    const percent = enabled > 0 ? Math.round((documented / enabled) * 100) : 100;
+    const passing = threshold === undefined || percent >= threshold;
+    return {
+        name: "linterRules",
+        total: enabled,
+        covered: documented,
+        percent,
+        threshold,
+        passing,
+        coveredItems: [],
+        uncoveredItems: [],
+    };
+}
+/**
+ * Check all coverage metrics against thresholds.
+ */
+function checkCoverage(basePath, thresholds, linterEnabled, linterDocumented, specs) {
+    const metrics = [];
+    // Linter rule coverage
+    const linterMetric = computeLinterRuleCoverage(linterEnabled, linterDocumented, thresholds.linterRules);
+    metrics.push(linterMetric);
+    // Script coverage
+    const scriptMetric = computeScriptCoverage(basePath, thresholds.scripts, specs);
+    metrics.push(scriptMetric);
+    const passing = metrics.every((m) => m.passing);
+    return { metrics, passing };
+}
+/**
+ * Format coverage report as human-readable text.
+ */
+function formatCoverageReport(report) {
+    const lines = [];
+    for (const m of report.metrics) {
+        const status = m.threshold !== undefined ? (m.passing ? "✓" : "✗") : " ";
+        const thresholdStr = m.threshold !== undefined ? ` (threshold: ${String(m.threshold)}%)` : "";
+        lines.push(`  ${status} ${m.name}: ${String(m.covered)}/${String(m.total)} (${String(m.percent)}%)${thresholdStr}`);
+        if (!m.passing && m.uncoveredItems.length > 0) {
+            const show = m.uncoveredItems.slice(0, 5);
+            for (const item of show) {
+                lines.push(`      missing: ${item}`);
+            }
+            if (m.uncoveredItems.length > 5) {
+                lines.push(`      ... and ${String(m.uncoveredItems.length - 5)} more`);
+            }
+        }
+    }
+    return lines.join("\n");
+}
+//# sourceMappingURL=coverage.js.map

package/dist/doc-refs.d.ts

@@ -0,0 +1,60 @@
+/**
+ * vigiles — Validate vigiles-builder calls in markdown code blocks.
+ *
+ * Mirror of inline mode but inverted: inline mode skips fenced code blocks
+ * (so `<!-- vigiles:enforce -->` in prose doesn't accidentally match an
+ * example). This module enters fenced code blocks (ts/typescript/js/
+ * javascript) and validates the vigiles builder calls inside —
+ * `enforce("...")`, `file("...")`, `cmd("...")`, `ref("...")` — using the
+ * same engines that validate them in spec.ts.
+ *
+ * Default: validate every ref. Illustrative blocks opt out via
+ * `<!-- vigiles:ignore -->` immediately before the fence. Whole files
+ * opt out via `<!-- vigiles:ignore-file -->` anywhere in the file
+ * (intended for research/design docs that quote hypothetical refs).
+ *
+ * Scope: ONLY vigiles builder calls. Generic TS syntax / type checking
+ * in markdown is explicitly out of scope — use eslint-plugin-markdown or
+ * twoslash for that.
+ */
+export type DocRefKind = "enforce" | "file" | "cmd" | "ref";
+export interface DocRef {
+    readonly file: string;
+    readonly line: number;
+    readonly kind: DocRefKind;
+    readonly value: string;
+}
+export interface DocRefError extends DocRef {
+    readonly message: string;
+}
+export interface DocRefReport {
+    readonly filesScanned: number;
+    readonly filesIgnored: number;
+    readonly blocksIgnored: number;
+    readonly refs: readonly DocRef[];
+    readonly errors: readonly DocRefError[];
+    /** Refs that couldn't be verified because the underlying tool isn't available in this env. */
+    readonly unverified: number;
+    /** Refs that contained placeholder syntax (e.g. <linter>/<rule>) and were skipped. */
+    readonly placeholders: number;
+}
+export interface FindDocRefsOptions {
+    readonly basePath?: string;
+    readonly ignore?: readonly string[];
+}
+interface ExtractResult {
+    refs: DocRef[];
+    blocksIgnored: number;
+}
+/** @internal */ export declare function extractDocRefs(content: string, file: string): ExtractResult;
+/**
+ * Walk every `.md` under `basePath`, extract vigiles builder calls from
+ * fenced TS/JS code blocks, validate against the same engines used for
+ * spec.ts. Honors `<!-- vigiles:ignore-file -->` (skip the whole file)
+ * and `<!-- vigiles:ignore -->` (skip the next code block).
+ */
+export declare function findDocRefs(options?: FindDocRefsOptions): DocRefReport;
+/** Format a DocRefReport as human-readable text. */
+export declare function formatDocRefReport(report: DocRefReport): string;
+export {};
+//# sourceMappingURL=doc-refs.d.ts.map