/**
 * Orphan-docs detection: the inverse of stale-reference validation.
 *
 * Stale-ref detection catches specs that point at files which no longer
 * exist. Orphan detection catches files which exist but no spec or README
 * points at — docs that quietly rot in `docs/` and `research/` because
 * nothing tells the agent they're still load-bearing.
 *
 * The detector operates purely on the filesystem: it enumerates markdown
 * files under configured doc roots and scans every `.md` in the repo for
 * references (markdown links and backtick paths). Works against source
 * README plus compiled CLAUDE.md — no spec loading required.
 */
import { type GlobIgnore } from "./glob-ignore.js";
import type { PluginLayout } from "./layout.js";
export interface OrphanReport {
    /** Include globs that were scanned. */
    readonly include: readonly string[];
    /** Total docs discovered under those globs. */
    readonly totalDocs: number;
    /** Docs referenced from at least one other `.md` file. */
    readonly referencedDocs: readonly string[];
    /** Docs that exist but no other `.md` references them. */
    readonly orphans: readonly string[];
}
export interface FindOrphansOptions {
    /** Repository root. Required: no cwd fallback. */
    readonly basePath: string;
    /**
     * Glob patterns of `.md` files to scan. Defaults to `["docs/**\/*.md"]`
     * (`docs/` is the near-universal convention; a vigiles-specific dir like
     * `research/` is opted into explicitly). Set to `[]` to disable scanning,
     * or to your project's doc globs (e.g. `["wiki/**\/*.md"]`) to override.
     */
    readonly include?: readonly string[];
    /**
     * The repo-wide `.vigilesrc.json#exclude` (`ExcludeSet.globIgnore`,
     * src/exclude.ts — correct from any glob cwd; a plain list is relative to
     * `basePath`). Applied to BOTH walks — candidates AND the reference scan —
     * so an excluded corpus can neither be an orphan nor keep one alive (#192).
     * The CLI always passes it; a direct library caller may omit it.
     */
    readonly repoExclude?: GlobIgnore;
    /**
     * Harnesses whose surface files (instruction file, `SKILL.md`, subagents,
     * commands) are load-bearing by location and thus never orphan CANDIDATES
     * (still counted as referencers). Injected by the CLI from the registered
     * adapters so core stays harness-agnostic; a direct caller passes its own.
     * Omitted ⇒ only the universal `SKILL.md` convention is exempt.
     */
    readonly layouts?: readonly PluginLayout[];
}
/**
 * Find docs under `include` globs that no other markdown file references.
 *
 * A doc is considered referenced when some OTHER `.md` file in the repo
 * links to it via `[text](path.md)` or mentions it in a backtick span like
 * `` `docs/foo.md` ``. Self-references don't count — an orphan that only
 * links to itself is still an orphan.
 *
 * `include` and `exclude` are tsconfig-style glob arrays. Default include
 * is `["docs/**\/*.md"]` (the common convention); override per-project via
 * `.vigilesrc.json` → `orphans.include` (whose presence also opts the repo
 * into the scan — see the CLI gate in `vigiles lint`).
 */
export declare function findOrphanDocs(options: FindOrphansOptions): OrphanReport;
/** Format an orphan report as human-readable text. */
export declare function formatOrphanReport(report: OrphanReport): string;
//# sourceMappingURL=orphans.d.ts.map