/**
 * Comment-only views of a source file, and whether a citation it makes holds.
 *
 * The shape and candidate rules live in `citation-rules.ts`, shared with the
 * repository's citation guard; this module holds the two things that rule needs in
 * order to be applied: the comment lines of a file, and the probes that answer
 * "does this path resolve here".
 *
 * Deliberately NOT `ts.getLeadingCommentRanges`:
 * `src/services/qa/bdd-test-style-verifier.ts` records that the API returns zero
 * ranges for comment-only blocks, which would silently read a header comment as no
 * comment at all. The spans come from `comment-spans.ts` instead, which keeps both
 * order and line numbers — what the worklist and the prune both need — and knows
 * what character it is inside, which a per-line rule cannot.
 */
import { type Citation } from './citation-rules.js';
/** One source line, with its 1-based number, as the classifier sees it. */
export type CommentLine = {
    readonly line: number;
    readonly text: string;
};
/**
 * The comment lines of a file: full-line comments, plus the trailing comment of a
 * code line. Non-comment lines are omitted but their numbers survive, so a report
 * can point at the code a comment is attached to.
 *
 * Derived from `commentSpans`, which reads the text as a stream. The previous version
 * decided per line and was wrong in both directions at once: a `//` inside a template
 * literal became a comment (and then a deletion that cut the literal open), while a
 * block comment's interior line that does not start with `*` was missed.
 */
export declare function commentLines(source: string): CommentLine[];
/**
 * The path-shaped backtick spans in a line, in order, with their bounds kept.
 *
 * The bounds are not decoration: two of the candidate rules read the text OUTSIDE
 * the span — an illustration cue sits immediately before it, a `<…>` fill-in wraps
 * it — so a caller that discards positions cannot apply them.
 */
export declare function citations(text: string): Citation[];
/** Every path-shaped span in a line, without its bounds. */
export declare function citedPaths(text: string): string[];
/**
 * The workspace package a citing file belongs to, or null at the repository root.
 *
 * In a pnpm workspace, `src/x.ts` written inside `packages/<name>/src/` names that
 * package's own file, not a repository-root one: three comments in this repository cite
 * `packages/peaks-loop-internal-runtime/src/status-protocol.ts` and
 * `packages/peaks-loop-shared-channel/src/index.ts` by their package-relative spelling,
 * and both files exist. Treating those as dead references would seed a ratchet with
 * findings that refuse the next honest package-internal citation, so the package root is
 * an origin — for a citing file that is itself inside a package, and never for a
 * top-level one.
 */
export declare function packageRootOf(citingFileRel: string): string | null;
/**
 * Does this path-shaped citation resolve anywhere it is allowed to resolve?
 *
 * `installed` must be a filesystem-only probe, not the ignore-widened one:
 * `node_modules` is itself in `.gitignore`, so an ignore-aware answer here is
 * "yes, installed" for every first segment, and the whole dead-reference count
 * collapses to zero while looking perfectly healthy. Measured, not theorised.
 */
export declare function citationResolves(citation: string, citingFileRel: string, exists: (relPath: string) => boolean, installed?: (relPath: string) => boolean): boolean;
/** The default existence probe, against a real working tree. */
export declare function treeExists(repoRoot: string): (relPath: string) => boolean;