urtext 0.1.0

package/dist/analyze/citations.d.ts

@@ -0,0 +1,256 @@
+import { type AnalysisContext, type Analyzer, type Changeset } from "../types.js";
+/**
+ * A repository-relative path followed by a line, or a line range. The path
+ * must contain at least one directory separator — see
+ * CITATION_GUARD_SEPARATOR in the design's false-positive guards for why a
+ * bare `Something.js:14` is not treated as a citation at all.
+ *
+ * Left to right: a lookbehind rejecting a preceding path character, so a
+ * match cannot start in the middle of a longer path; one or more `segment/`
+ * groups, which is what makes the separator mandatory; a final segment with
+ * a dot and an alphanumeric extension; a colon; a line number with no
+ * leading zero; optionally a hyphen and an end line; and a lookahead
+ * rejecting a trailing digit, letter, underscore, slash, or hyphen, so a
+ * citation is not matched inside a longer line number or a longer path.
+ * Capture groups: path, start line, end line or undefined.
+ *
+ * A trailing period is not rejected, so a citation ending a sentence is
+ * extracted like any other — see `test/analyze/citations.test.ts`,
+ * "extracts a citation a sentence's closing period touches, in both forms".
+ */
+export declare const LINE_CITATION: RegExp;
+/**
+ * A backticked repository-relative path, then a quoted phrase — urtext's own
+ * comment-contract form, and the most checkable citation form in the
+ * repository, because the quoted text either appears in the named file or it
+ * does not. The same mandatory-separator path, inside backticks; an optional
+ * comma, semicolon, or colon; a short run of whitespace; then a straight or
+ * left curly double quote, the phrase, and a straight or right curly close.
+ * Capture groups: path, phrase.
+ */
+export declare const QUOTED_CITATION: RegExp;
+/**
+ * The most code points a quoted phrase, or a stored was/now line, carries.
+ * Longer than this is a block quotation rather than a pointer.
+ */
+export declare const MAX_QUOTE_CHARS = 240;
+/** Appended to a was/now line the cap cut, so no line merely appears to end. */
+export declare const CITATION_TRUNCATION_MARKER = "\u2026 [line truncated]";
+/** Tracked files scanned as raw text, after masking. */
+export declare const PROSE_EXTENSIONS: readonly [".md", ".markdown", ".txt"];
+/**
+ * The pathspecs the candidate-file queries in this file's scan half pass to
+ * git. Narrower than `isTypeScriptFile` accepts — it also takes the
+ * module-explicit extensions, which no pathspec here names — so a citation
+ * written in one of those files is not checked at all. An under-report, the
+ * direction every approximation in this feature leans.
+ */
+export declare const CITATION_PATHSPECS: readonly ["*.md", "*.markdown", "*.txt", "*.ts", "*.tsx"];
+export type CitationForm = "line" | "quote";
+export interface Citation {
+    form: CitationForm;
+    /** The path exactly as the prose spelled it, before any resolution. */
+    path: string;
+    /** Form A only: the cited start line, and the end line for a range. */
+    line?: number;
+    endLine?: number;
+    /** Form B only: the quoted phrase, already normalized. */
+    quote?: string;
+    /** One-based line in the citing file where `path` sits. */
+    citingLine: number;
+    /** That line's text, trimmed, for the fact's anchor evidence. */
+    citingText: string;
+}
+/**
+ * Every whitespace run, newlines included, collapsed to a single space, then
+ * trimmed. Matching and comparison both run on normalized text, and the
+ * cited file is normalized identically before a containment test. Without
+ * this, every comment-contract citation in `src/` would fail: they wrap
+ * across continuation lines, so the phrase as written carries newlines and
+ * asterisks the cited file never had.
+ */
+export declare function normalizeText(text: string): string;
+/**
+ * CITATION_GUARD_FENCE. Spans from a line opening a fence through the next
+ * line closing that fence — same character, at least as long a run —
+ * inclusive, are blanked. A path and line inside a fence is sample output,
+ * and treating sample output as an assertion about the repository is the
+ * most common false positive available. An unclosed fence blanks to the end
+ * of the text: silence about a run of prose costs less than a finding built
+ * on a code block nobody closed. Indented blocks are deliberately not
+ * masked — they are indistinguishable from list continuations in this
+ * repository's prose, and the baseline gate already covers the illustrative
+ * ones. A blockquote prefix on the fence line is tolerated: a fence inside a
+ * quotation is still a fence, and the indent allowance alone cannot see past
+ * the marker. See `test/analyze/citations.test.ts`, "CITATION_GUARD_FENCE: a
+ * citation inside a fenced block is not one, and the same text outside it
+ * is" and "CITATION_GUARD_FENCE: a fenced block inside a blockquote is masked
+ * like any other".
+ */
+export declare function maskFences(text: string): string;
+/**
+ * CITATION_GUARD_URL. A link to another host is a link to another host, and
+ * its path-and-line tail says nothing about this repository. The regexes'
+ * lookbehind is a second line of defense, not a substitute: masking is what
+ * makes the intent explicit and testable.
+ */
+export declare function maskUrls(text: string): string;
+export declare function isProseFile(path: string): boolean;
+export declare function citationsInProse(text: string): Citation[];
+/**
+ * Comments only. A path and line inside a string literal is usually a test
+ * fixture's expected output, and inside code it is not prose making a claim.
+ * Fences are not masked here — a fence is a prose construct — but URLs are,
+ * for the same reason they are in prose.
+ */
+export declare function citationsInComments(source: string, fileName: string): Citation[];
+/** Every citation in one file, scanned the way that file's kind is scanned. */
+export declare function citationsIn(path: string, text: string): Citation[];
+/**
+ * The most citations one run checks, across both modes. Bounds a sweep of a
+ * repository whose prose cites code everywhere; the default mode is already
+ * bounded by the change and reaches this only on a very large diff. A cap
+ * that bites is disclosed — see `citationsCappedNote`.
+ */
+export declare const MAX_CITATIONS_CHECKED = 2000;
+/**
+ * The most citing files one run opens. Bounds the blame calls, which are the
+ * expensive per-file work; the citation cap above bounds the per-citation
+ * work. Files are taken in path order so a capped run is deterministic.
+ */
+export declare const MAX_CITING_FILES = 320;
+/**
+ * The most distinct (revision, cited file) pairs one run reads historically.
+ * A repository whose prose cites a hundred files from a hundred different
+ * baseline commits would otherwise pay a `git show` per pair with no bound
+ * at all; every citation past this is checked existence-only and said so.
+ */
+export declare const MAX_BASELINE_READS = 480;
+/**
+ * The most basenames passed to one `git grep` invocation. Terms are chunked
+ * at this width and the results unioned, so unlike the caps above this one
+ * loses nothing and discloses nothing.
+ */
+export declare const MAX_GREP_TERMS = 96;
+/**
+ * Pluralized inline in the style `review` in `../cli.ts` already uses, and
+ * phrased as reasons so they read alongside the existing warnings. They land
+ * in `warnings`, which becomes `ReportModel.notes`, which trips the "This
+ * review is partial." banner — correctly. A capped run genuinely did not
+ * check everything it was asked to.
+ */
+export declare function citingFilesCappedNote(scanned: number, found: number): string;
+export declare function citationsCappedNote(checked: number, found: number): string;
+/**
+ * No order clause, unlike the two caps above, and the difference is in what
+ * this sentence claims rather than in how its budget is spent. The budget is
+ * spent front to back like theirs — a citation is refused a historical read
+ * only once the distinct-pair allowance is gone, so the ones that degrade are
+ * the later ones in the same path order, minus any whose baseline pair had
+ * already been read. But this note states no fraction and no share of the
+ * repository: every citation it counts was checked, and the sentence says
+ * exactly how far that check went. There is no coverage claim here for an
+ * order to qualify, so the clause the caps carry would attach to a sentence
+ * that never said it had covered anything.
+ */
+export declare function baselineReadsCappedNote(unchecked: number): string;
+/**
+ * Copy for a shallow repository, where blame answers but cannot be believed.
+ * Phrased as a skip rather than a partial check, because that is what it is.
+ */
+export declare function shallowRepositoryNote(): string;
+/** Copy for citations whose history could not be read. */
+export declare function blameUnavailableNote(count: number, reason: string): string;
+export type RotKind = "missing_file" | "line_out_of_range" | "quote_absent" | "content_drift";
+export interface CitationRot {
+    rot: RotKind;
+    citingFile: string;
+    citingLine: number;
+    citingText: string;
+    /** The resolved cited path, not the path as written. */
+    citedFile: string;
+    citedLine?: number;
+    /**
+     * The citation's end line, for a range. Absent on `content_drift`, whose
+     * `citedLine` is the one line that actually differs rather than the
+     * range's start: pairing this end with that start would print a span the
+     * prose never wrote. What the prose did write is carried whole in
+     * `writtenLine`/`writtenEndLine` below.
+     */
+    citedEndLine?: number;
+    /**
+     * `content_drift` only: the citation exactly as the prose wrote it. Carried
+     * apart from `citedLine`, which on a drift names the one line whose content
+     * differs, because a drift finding has to say both things and must never
+     * mix them. The title and body name this pair — it is the string a reader
+     * searches their own document for, and the text they will edit — while the
+     * evidence points at the line that actually moved. Separate fields, so no
+     * sentence can compose a span out of one number from each.
+     *
+     * On the other three rot kinds `citedLine`/`citedEndLine` already are the
+     * citation as written, and these stay absent.
+     */
+    writtenLine?: number;
+    writtenEndLine?: number;
+    quote?: string;
+    /** content_drift only: the first differing line, both sides, truncated. */
+    was?: string;
+    now?: string;
+    /** Abbreviated baseline commit. Absent means history could not be read. */
+    baseline?: string;
+    /** line_out_of_range only: the cited file's line count at this revision. */
+    lineCount?: number;
+    /** The cited line's current text, when the file and line exist now. */
+    citedText?: string;
+    /** True when the reviewed range touched `citedFile`. Proven, not inferred. */
+    citedTouched: boolean;
+}
+export interface CitationScanOptions {
+    /**
+     * Check every citation in the repository rather than only those pointing
+     * into files the reviewed range touched. Set by `--citations`.
+     */
+    sweep?: boolean;
+    /**
+     * Called once per cap that bit and once for unreadable history, with the
+     * sentence the user is owed. An analyzer returns facts and nothing else, so
+     * this is the only channel a disclosure has; `review` in `../cli.ts` passes
+     * one that pushes into `warnings`. A caller that passes none gets the facts
+     * and no indication anything was skipped — the same contract, and the same
+     * hazard, as `runAnalyzers`'s `onFailure`.
+     */
+    onNote?: (note: string) => void;
+}
+/**
+ * The name the design gives this option bag where the analyzer takes it, and
+ * an alias rather than a second declaration on purpose: one field list cannot
+ * drift against itself, and the scan half of this module already documents
+ * every field above.
+ */
+export type CitationsOptions = CitationScanOptions;
+export declare function parseBlame(out: string): Map<number, string>;
+export declare function findCitationRot(changeset: Changeset, ctx: AnalysisContext, options?: CitationScanOptions): Promise<CitationRot[]>;
+/**
+ * Returns its analyzer under a name it states outright, and that is
+ * load-bearing: `runAnalyzers` reports a failed analyzer by
+ * `analyzers[i].name` in a warning a user reads, and an arrow returned
+ * directly from a factory has no name at all, so a citation analyzer that
+ * threw would be disclosed as a numbered anonymous one.
+ *
+ * The other analyzers get their names for free, from NamedEvaluation of the
+ * variable declaration they are assigned to. That mechanism is not enough
+ * here. This binding sits one scope in and shadows the module-level
+ * singleton below, and a transform that renames shadowed symbols to keep
+ * every binding unique — esbuild, which is what runs this repository's tests
+ * — rewrites the binding, and the inferred name goes with it, turning the
+ * disclosed name into a near-miss of itself. So the name is written down
+ * rather than derived. See `test/analyze/citations-rot.test.ts`, "names
+ * itself when it throws, so the disclosure never says analyzer #N".
+ */
+export declare function makeCitationsAnalyzer(options?: CitationsOptions): Analyzer;
+/**
+ * The default-mode instance, and the member of ANALYZERS. Also the identity
+ * `review` matches on when it swaps in a configured instance, so it must stay
+ * a single shared value rather than being reconstructed per call.
+ */
+export declare const citationsAnalyzer: Analyzer;