/**
 * 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.
 */
import { type GlobIgnore } from "./glob-ignore.js";
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 {
    /** The repo root. Required: no cwd fallback. */
    readonly basePath: string;
    /** The repo exclude (`ExcludeSet.globIgnore`), or patterns relative to `basePath`. */
    readonly ignore?: GlobIgnore;
}
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, 
/**
 * The severity `doc-refs` is configured at. A `✗` next to an exit code of 0
 * reads as a gate that failed to gate, so the marker follows the severity the
 * user actually set rather than always claiming the hard tier.
 */
severity?: "error" | "warn"): string;
export {};
//# sourceMappingURL=doc-refs.d.ts.map