/**
 * Orphan scan service (Slice 4/6 — karpathy-enforcement).
 *
 * Detects 4 kinds of orphans that RD/QA should clean up before merge:
 *  - exportOrphan:     declared export with no in-repo importer
 *  - importOrphan:     import whose source no longer exports the symbol
 *                     (working-tree vs HEAD diff focus)
 *  - cliSubcommandOrphan: `.command('x')` registered but never wired
 *                     into the group registration call
 *  - docEndpointOrphan: tech-doc declares an endpoint / subcommand
 *                     that the codebase does not implement
 *
 * Pattern follows `api-surface-service.ts` (readFile + readdir; pure
 * data shape; no AST parsing). karpathy §2: minimum code, no abstractions.
 */
export type OrphanScope = 'working-tree' | 'git-diff' | 'all';
export type OrphanScanOptions = {
    projectRoot: string;
    /** Limit the walk to changed files only (default: working-tree). */
    scope?: OrphanScope;
    /** Strict mode: report exportOrphans even outside the working tree. */
    strict?: boolean;
    /**
     * Slice 2.6.1.A.4: git ref to diff against (default: HEAD).
     * When supplied, `git diff --name-status <baseRef>` is used instead of
     * the implicit `git diff --name-status HEAD`. Useful for branch-vs-main
     * scans and for cross-branch orphan detection.
     */
    baseRef?: string;
};
export type ExportOrphan = {
    name: string;
    kind: 'function' | 'class' | 'const' | 'interface' | 'type' | 'enum';
    sourceFile: string;
    line: number;
};
export type ImportOrphan = {
    importedFrom: string;
    symbol: string;
    importer: string;
    line: number;
};
export type CliSubcommandOrphan = {
    name: string;
    sourceFile: string;
    reason: string;
};
export type DocEndpointOrphan = {
    endpoint: string;
    declaredIn: string;
};
export type OrphanReport = {
    projectRoot: string;
    scannedAt: string;
    scope: OrphanScope;
    strict: boolean;
    counts: {
        export: number;
        import: number;
        cliSubcommand: number;
        docEndpoint: number;
    };
    exportOrphans: ExportOrphan[];
    importOrphans: ImportOrphan[];
    cliSubcommandOrphans: CliSubcommandOrphan[];
    docEndpointOrphans: DocEndpointOrphan[];
    warnings: string[];
};
/**
 * Scan the project for orphan symbols. Read-only. Never throws;
 * failures surface as warnings in the report.
 */
export declare function scanOrphans(options: OrphanScanOptions): Promise<OrphanReport>;
export declare function formatOrphanMarkdown(report: OrphanReport, opts?: {
    maxPerKind?: number;
}): string;