@refrakt-md/content 0.36.0 → 0.37.0

package/dist/edges/git-scan.d.ts

@@ -0,0 +1,69 @@
+/**
+ * The git scan (SPEC-136 D5, WORK-594).
+ *
+ * One pass over the repository's history, producing for every path the commits
+ * that touched it. Adapted from `timestamps.ts`'s scan rather than rewritten —
+ * the shallow-clone and git-root handling there are the parts most easily got
+ * wrong.
+ *
+ * **`--full-history`, and no pathspec.** This is the single easiest way to ship
+ * this feature with quietly wrong numbers, and it was found by measuring
+ * SPEC-136's own base rate:
+ *
+ * ```
+ * git log --name-only -- site/content/docs/cli/cli-overview.md   → 2 commits
+ * git log --full-history --name-only        (no pathspec)        → 5 commits
+ * ```
+ *
+ * A pathspec makes git apply history simplification. Both outputs are correct
+ * git answering different questions — but this command does *arithmetic* on
+ * those timestamps, since the referrer's last-changed time is one half of every
+ * score. A simplified history inflates every edge out of a file and deflates
+ * every edge into it, and the failure is invisible: the report still renders,
+ * still ranks, still looks plausible.
+ */
+export interface Commit {
+    sha: string;
+    /** Unix seconds. */
+    at: number;
+    subject: string;
+}
+export interface GitHistory {
+    /** Path (relative to the git root) → commits touching it, newest first. */
+    byPath: Map<string, Commit[]>;
+    /** Prefix from the git root to the scanned directory, '' at the root. */
+    prefix: string;
+}
+/** Why the scan could not run. A refusal is never a zero — D5. */
+export declare class GitScanRefusal extends Error {
+    constructor(message: string);
+}
+/** A shallow clone reports one commit per path, so every edge scores zero and
+ *  the tool confidently reports a clean corpus. That is the silent-wrong class
+ *  this feature exists to avoid, so it refuses instead. */
+export declare function isShallowClone(cwd: string): boolean;
+export declare function isGitRepository(cwd: string): boolean;
+/** Path from the git root to `cwd`, '' when already at the root. */
+export declare function gitRelativePrefix(cwd: string): string;
+/**
+ * Scan the whole history once.
+ *
+ * @throws {GitScanRefusal} on a non-git tree or a shallow clone. Both are
+ *   "could not measure", which is a different event from "measured, nothing
+ *   wrong" and must not be reported as the latter.
+ */
+export declare function scanHistory(cwd: string): GitHistory;
+/** The most recent commit timestamp for a path, or undefined if untracked. */
+export declare function lastChanged(history: GitHistory, path: string): number | undefined;
+/** Commits touching `path` strictly after `since`, newest first. */
+export declare function commitsSince(history: GitHistory, path: string, since: number): Commit[];
+/**
+ * Paths changed since a git ref — the `since:` query's input.
+ *
+ * A PR-scoped sweep: resolve what the branch touched, then ask the same
+ * question `touching` asks. Returns an empty list rather than throwing when the
+ * ref cannot be resolved, because a missing ref is the caller's mistake to
+ * report, not a reason to fail the whole query.
+ */
+export declare function changedSince(cwd: string, ref: string): string[];
+//# sourceMappingURL=git-scan.d.ts.map

package/dist/edges/git-scan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-scan.d.ts","sourceRoot":"","sources":["../../src/edges/git-scan.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAIH,MAAM,WAAW,MAAM;IACtB,GAAG,EAAE,MAAM,CAAC;IACZ,oBAAoB;IACpB,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,UAAU;IAC1B,2EAA2E;IAC3E,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IAC9B,yEAAyE;IACzE,MAAM,EAAE,MAAM,CAAC;CACf;AAED,kEAAkE;AAClE,qBAAa,cAAe,SAAQ,KAAK;gBAC5B,OAAO,EAAE,MAAM;CAI3B;AAWD;;2DAE2D;AAC3D,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAMnD;AAED,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAMpD;AAED,oEAAoE;AACpE,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAMrD;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,CAyCnD;AAED,8EAA8E;AAC9E,wBAAgB,WAAW,CAAC,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAKjF;AAED,oEAAoE;AACpE,wBAAgB,YAAY,CAAC,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAIvF;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CAM/D"}

package/dist/edges/git-scan.js

@@ -0,0 +1,138 @@
+/**
+ * The git scan (SPEC-136 D5, WORK-594).
+ *
+ * One pass over the repository's history, producing for every path the commits
+ * that touched it. Adapted from `timestamps.ts`'s scan rather than rewritten —
+ * the shallow-clone and git-root handling there are the parts most easily got
+ * wrong.
+ *
+ * **`--full-history`, and no pathspec.** This is the single easiest way to ship
+ * this feature with quietly wrong numbers, and it was found by measuring
+ * SPEC-136's own base rate:
+ *
+ * ```
+ * git log --name-only -- site/content/docs/cli/cli-overview.md   → 2 commits
+ * git log --full-history --name-only        (no pathspec)        → 5 commits
+ * ```
+ *
+ * A pathspec makes git apply history simplification. Both outputs are correct
+ * git answering different questions — but this command does *arithmetic* on
+ * those timestamps, since the referrer's last-changed time is one half of every
+ * score. A simplified history inflates every edge out of a file and deflates
+ * every edge into it, and the failure is invisible: the report still renders,
+ * still ranks, still looks plausible.
+ */
+import { execSync } from 'node:child_process';
+/** Why the scan could not run. A refusal is never a zero — D5. */
+export class GitScanRefusal extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'GitScanRefusal';
+    }
+}
+function git(command, cwd) {
+    return execSync(command, {
+        cwd,
+        encoding: 'utf-8',
+        maxBuffer: 256 * 1024 * 1024,
+        stdio: ['pipe', 'pipe', 'pipe'],
+    });
+}
+/** A shallow clone reports one commit per path, so every edge scores zero and
+ *  the tool confidently reports a clean corpus. That is the silent-wrong class
+ *  this feature exists to avoid, so it refuses instead. */
+export function isShallowClone(cwd) {
+    try {
+        return git('git rev-parse --is-shallow-repository', cwd).trim() === 'true';
+    }
+    catch {
+        return false;
+    }
+}
+export function isGitRepository(cwd) {
+    try {
+        return git('git rev-parse --is-inside-work-tree', cwd).trim() === 'true';
+    }
+    catch {
+        return false;
+    }
+}
+/** Path from the git root to `cwd`, '' when already at the root. */
+export function gitRelativePrefix(cwd) {
+    const root = git('git rev-parse --show-toplevel', cwd).trim();
+    const abs = git('pwd', cwd).trim();
+    if (abs === root)
+        return '';
+    const rel = abs.slice(root.length + 1);
+    return rel ? `${rel}/` : '';
+}
+/**
+ * Scan the whole history once.
+ *
+ * @throws {GitScanRefusal} on a non-git tree or a shallow clone. Both are
+ *   "could not measure", which is a different event from "measured, nothing
+ *   wrong" and must not be reported as the latter.
+ */
+export function scanHistory(cwd) {
+    if (!isGitRepository(cwd)) {
+        throw new GitScanRefusal('not a git repository — `refrakt stale` measures commits against a file, and has no ' +
+            'non-git fallback. Run it inside a checkout.');
+    }
+    if (isShallowClone(cwd)) {
+        throw new GitScanRefusal('shallow clone — every path would report a single commit and every edge would score ' +
+            'zero, which is indistinguishable from a clean corpus. Set `fetch-depth: 0` on the ' +
+            'checkout step (actions/checkout defaults to 1) and run again.');
+    }
+    // `%x00` separates the subject so a subject containing the field separator
+    // cannot split the record.
+    const output = git('git log --full-history --format="__C__%H%x00%at%x00%s" --name-only --diff-filter=ACMR HEAD', cwd);
+    const byPath = new Map();
+    let current;
+    for (const raw of output.split('\n')) {
+        const line = raw.replace(/\r$/, '');
+        if (line.startsWith('__C__')) {
+            const [sha, at, ...rest] = line.slice(5).split('\u0000');
+            current = { sha: sha.slice(0, 7), at: Number(at), subject: rest.join('\u0000') };
+            continue;
+        }
+        if (line.length === 0 || current === undefined)
+            continue;
+        const list = byPath.get(line);
+        if (list)
+            list.push(current);
+        else
+            byPath.set(line, [current]);
+    }
+    return { byPath, prefix: gitRelativePrefix(cwd) };
+}
+/** The most recent commit timestamp for a path, or undefined if untracked. */
+export function lastChanged(history, path) {
+    const commits = history.byPath.get(path);
+    if (!commits || commits.length === 0)
+        return undefined;
+    // `git log` emits newest first, so the head is the most recent.
+    return commits[0].at;
+}
+/** Commits touching `path` strictly after `since`, newest first. */
+export function commitsSince(history, path, since) {
+    const commits = history.byPath.get(path);
+    if (!commits)
+        return [];
+    return commits.filter((c) => c.at > since);
+}
+/**
+ * Paths changed since a git ref — the `since:` query's input.
+ *
+ * A PR-scoped sweep: resolve what the branch touched, then ask the same
+ * question `touching` asks. Returns an empty list rather than throwing when the
+ * ref cannot be resolved, because a missing ref is the caller's mistake to
+ * report, not a reason to fail the whole query.
+ */
+export function changedSince(cwd, ref) {
+    const out = git(`git diff --name-only ${ref}...HEAD`, cwd);
+    return out
+        .split('\n')
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0);
+}
+//# sourceMappingURL=git-scan.js.map

package/dist/edges/git-scan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-scan.js","sourceRoot":"","sources":["../../src/edges/git-scan.ts"],"names":[],"mappings":"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"}

package/dist/edges/index.d.ts

@@ -0,0 +1,119 @@
+/**
+ * The edge index (SPEC-136 D12, WORK-594).
+ *
+ * **Built as an addressable index, with ranking as one reader of it.** The
+ * tempting shape is a function that walks content, scores as it goes, and
+ * prints. That shape cannot answer WORK-596's `touching` query, which runs in
+ * the opposite direction — from a changed file to the pages that document it —
+ * and without the git scan at all. The cost of doing it properly is an
+ * afternoon here and a rewrite avoided later.
+ */
+import { type DeclaredEdgeError, type Edge, type EdgeClass } from './extract.js';
+import { type Commit, type GitHistory } from './git-scan.js';
+export type { Edge, EdgeClass, DeclaredEdgeError } from './extract.js';
+export type { Commit, GitHistory } from './git-scan.js';
+export { changedSince, GitScanRefusal, scanHistory } from './git-scan.js';
+export { globMatcher, globToRegExp, resolveStaleSettings, StaleConfigRefusal, type StaleSettings, } from './exclude.js';
+export interface EdgeIndex {
+    edges: Edge[];
+    /** Declared edges that resolve to nothing — D14 reports these loudly, where
+     *  every inferred class stays silent. */
+    errors: DeclaredEdgeError[];
+    /** target path → edges pointing at it. The `touching` direction. */
+    byTarget: Map<string, Edge[]>;
+    /** referrer page → edges it declares. */
+    byReferrer: Map<string, Edge[]>;
+    /** What the project's `stale` config removed. Reported, never silent: an
+     *  exclusion list that hides its own effect is how the report converges on
+     *  empty without anyone deciding that it should. */
+    excluded: ExclusionCount;
+}
+export interface ExclusionCount {
+    /** Pages skipped whole, matching an `archival` glob. */
+    archivalPages: number;
+    /** Edges dropped because their target matched a `generated` glob. */
+    generatedTargets: number;
+}
+/**
+ * Build the index from a content directory.
+ *
+ * Needs no git and no build, so `touching` can answer for a file created in the
+ * working tree and never committed.
+ */
+export declare function buildEdgeIndex(opts: {
+    repoRoot: string;
+    contentDirs: string[];
+    /** Referrer globs — matching pages contribute no edges at all. */
+    archival?: string[];
+    /** Target globs — edges pointing at a match are dropped. */
+    generated?: string[];
+}): EdgeIndex;
+/** Index a list of edges in both directions. */
+export declare function indexEdges(edges: Edge[]): EdgeIndex;
+/**
+ * The `touching` query — every page whose edges point at any of `paths`.
+ *
+ * Not a staleness measurement and not a filter over the ranked report: there is
+ * no commit count, because the change has not happened yet. It takes no git
+ * history, is unbounded by `--top`, and is the query that makes this feature
+ * preventive rather than retrospective.
+ */
+export declare function edgesTouching(index: EdgeIndex, paths: string[]): Edge[];
+export interface RankedEdge {
+    edge: Edge;
+    /** Commits touching the target since the referrer last changed. */
+    score: number;
+    /** Unix seconds; undefined when the referrer is untracked. */
+    referrerChanged?: number;
+    targetChanged?: number;
+    commits: Commit[];
+}
+export interface RankOptions {
+    /** Narrow to one edge class. */
+    edgeClass?: EdgeClass;
+    /** Floor on the commit count. */
+    min?: number;
+}
+/** Per-class base rate — how many edges of that class scored non-zero out of
+ *  how many were scanned. Printed in the footer so degradation is visible
+ *  rather than inferred. */
+export interface BaseRate {
+    class: EdgeClass;
+    nonZero: number;
+    scanned: number;
+}
+export interface RankResult {
+    ranked: RankedEdge[];
+    baseRates: BaseRate[];
+    /** Total non-zero edges before `--top` truncation. */
+    totalNonZero: number;
+}
+/**
+ * Rank the index against a git history.
+ *
+ * One reader of the index among several — `touching` is another, and neither
+ * owns it.
+ *
+ * An edge whose referrer is newer than every change to its target scores zero
+ * and is omitted. A zero score is **the absence of evidence of staleness, not
+ * evidence of freshness**: the referrer side resets on any edit, including a
+ * typo fix (D6, a known and accepted false negative).
+ */
+export declare function rankEdges(index: EdgeIndex, history: GitHistory, opts?: RankOptions): RankResult;
+/** Build the index and rank it in one call — the report's entry point.
+ *
+ *  `contentDirs`, `archival` and `generated` all come from the project's
+ *  `refrakt.config.json` when not passed explicitly (tests pass fixtures). None
+ *  of the three has a built-in value: a directory layout is a property of the
+ *  project, not of the tool. */
+export declare function runStale(opts: {
+    repoRoot: string;
+    contentDirs?: string[];
+    archival?: string[];
+    generated?: string[];
+    edgeClass?: EdgeClass;
+    min?: number;
+}): RankResult & {
+    index: EdgeIndex;
+};
+//# sourceMappingURL=index.d.ts.map

package/dist/edges/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/edges/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH,OAAO,EACN,KAAK,iBAAiB,EAEtB,KAAK,IAAI,EACT,KAAK,SAAS,EAKd,MAAM,cAAc,CAAC;AAGtB,OAAO,EACN,KAAK,MAAM,EAEX,KAAK,UAAU,EAGf,MAAM,eAAe,CAAC;AAEvB,YAAY,EAAE,IAAI,EAAE,SAAS,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACvE,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AACxD,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC1E,OAAO,EACN,WAAW,EACX,YAAY,EACZ,oBAAoB,EACpB,kBAAkB,EAClB,KAAK,aAAa,GAClB,MAAM,cAAc,CAAC;AAEtB,MAAM,WAAW,SAAS;IACzB,KAAK,EAAE,IAAI,EAAE,CAAC;IACd;6CACyC;IACzC,MAAM,EAAE,iBAAiB,EAAE,CAAC;IAC5B,oEAAoE;IACpE,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;IAC9B,yCAAyC;IACzC,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;IAChC;;wDAEoD;IACpD,QAAQ,EAAE,cAAc,CAAC;CACzB;AAED,MAAM,WAAW,cAAc;IAC9B,wDAAwD;IACxD,aAAa,EAAE,MAAM,CAAC;IACtB,qEAAqE;IACrE,gBAAgB,EAAE,MAAM,CAAC;CACzB;AAkBD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE;IACpC,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,kEAAkE;IAClE,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,4DAA4D;IAC5D,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB,GAAG,SAAS,CAmFZ;AAkCD,gDAAgD;AAChD,wBAAgB,UAAU,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,SAAS,CAqBnD;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,CAMvE;AAED,MAAM,WAAW,UAAU;IAC1B,IAAI,EAAE,IAAI,CAAC;IACX,mEAAmE;IACnE,KAAK,EAAE,MAAM,CAAC;IACd,8DAA8D;IAC9D,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,OAAO,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,MAAM,WAAW,WAAW;IAC3B,gCAAgC;IAChC,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,iCAAiC;IACjC,GAAG,CAAC,EAAE,MAAM,CAAC;CACb;AAED;;4BAE4B;AAC5B,MAAM,WAAW,QAAQ;IACxB,KAAK,EAAE,SAAS,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,UAAU;IAC1B,MAAM,EAAE,UAAU,EAAE,CAAC;IACrB,SAAS,EAAE,QAAQ,EAAE,CAAC;IACtB,sDAAsD;IACtD,YAAY,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,SAAS,CACxB,KAAK,EAAE,SAAS,EAChB,OAAO,EAAE,UAAU,EACnB,IAAI,GAAE,WAAgB,GACpB,UAAU,CAgDZ;AAED;;;;;gCAKgC;AAChC,wBAAgB,QAAQ,CAAC,IAAI,EAAE;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,GAAG,CAAC,EAAE,MAAM,CAAC;CACb,GAAG,UAAU,GAAG;IAAE,KAAK,EAAE,SAAS,CAAA;CAAE,CAmBpC"}

package/dist/edges/index.js

@@ -0,0 +1,264 @@
+/**
+ * The edge index (SPEC-136 D12, WORK-594).
+ *
+ * **Built as an addressable index, with ranking as one reader of it.** The
+ * tempting shape is a function that walks content, scores as it goes, and
+ * prints. That shape cannot answer WORK-596's `touching` query, which runs in
+ * the opposite direction — from a changed file to the pages that document it —
+ * and without the git scan at all. The cost of doing it properly is an
+ * afternoon here and a rewrite avoided later.
+ */
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { join, relative, sep } from 'node:path';
+import { compareMarker, parseMarker, sliceForInvocation } from '@refrakt-md/runes';
+import { dedupeEdges, extractDeclaredEdges, extractDescribedLinkEdges, extractEmbeddedEdges, extractProseEdges, } from './extract.js';
+import { parseFrontmatter } from '../frontmatter.js';
+import { globMatcher, resolveStaleSettings } from './exclude.js';
+import { commitsSince, lastChanged, scanHistory, } from './git-scan.js';
+export { changedSince, GitScanRefusal, scanHistory } from './git-scan.js';
+export { globMatcher, globToRegExp, resolveStaleSettings, StaleConfigRefusal, } from './exclude.js';
+/** Collect content files under a directory, repo-root-relative POSIX. */
+function collectPages(contentDir, repoRoot, out = []) {
+    let entries;
+    try {
+        entries = readdirSync(contentDir);
+    }
+    catch {
+        return out;
+    }
+    for (const entry of entries) {
+        const full = join(contentDir, entry);
+        if (statSync(full).isDirectory())
+            collectPages(full, repoRoot, out);
+        else if (entry.endsWith('.md'))
+            out.push(relative(repoRoot, full).split(sep).join('/'));
+    }
+    return out;
+}
+/**
+ * Build the index from a content directory.
+ *
+ * Needs no git and no build, so `touching` can answer for a file created in the
+ * working tree and never committed.
+ */
+export function buildEdgeIndex(opts) {
+    const edges = [];
+    const errors = [];
+    const isArchival = globMatcher(opts.archival);
+    const isGenerated = globMatcher(opts.generated);
+    const excluded = { archivalPages: 0, generatedTargets: 0 };
+    const exists = (path) => {
+        try {
+            return statSync(join(opts.repoRoot, path)).isFile();
+        }
+        catch {
+            return false;
+        }
+    };
+    // Every content page, for resolving described-link targets. A link points
+    // at a route; the edge needs the file behind it.
+    const allPages = opts.contentDirs.flatMap((d) => collectPages(join(opts.repoRoot, d), opts.repoRoot));
+    const byRoute = new Map();
+    for (const page of allPages) {
+        for (const dir of opts.contentDirs) {
+            if (!page.startsWith(`${dir}/`))
+                continue;
+            const rel = page.slice(dir.length + 1);
+            const route = `/${rel.replace(/\.md$/, '').replace(/\/index$/, '')}`;
+            byRoute.set(route === '/index' ? '/' : route, page);
+        }
+    }
+    // Both `<path>.md` and `<path>/index.md` resolve. The anchor is already
+    // stripped by the extractor.
+    const resolvePage = (route) => byRoute.get(route) ?? byRoute.get(`${route}/index`);
+    for (const page of allPages) {
+        // An archival page is skipped before extraction, not filtered after it,
+        // so it disappears from `touching` too — "what documents this file"
+        // must not answer with a record of what was once true.
+        if (isArchival(page)) {
+            excluded.archivalPages++;
+            continue;
+        }
+        let source;
+        try {
+            source = readFileSync(join(opts.repoRoot, page), 'utf8');
+        }
+        catch {
+            continue;
+        }
+        const { frontmatter } = parseFrontmatter(source);
+        edges.push(...extractEmbeddedEdges(page, source));
+        // A `_layout.md` declares nothing on behalf of the pages beneath it
+        // (D13) — that claim would be attributed to every one of them.
+        if (!page.endsWith('/_layout.md')) {
+            const declared = extractDeclaredEdges(page, frontmatter, exists);
+            edges.push(...declared.edges);
+            errors.push(...declared.errors);
+        }
+        edges.push(...extractDescribedLinkEdges(page, source, resolvePage));
+        edges.push(...extractProseEdges(page, source, exists));
+    }
+    // A marker outranks a commit count, but only while it is still true. This
+    // is where the two are told apart — here rather than in `rankEdges`, which
+    // reads no files, and against the same slice `snippet review` hashes.
+    for (const edge of edges) {
+        if (!edge.reviewed || edge.attrs === undefined)
+            continue;
+        edge.markerStale = !markerIsCurrent(opts.repoRoot, edge.target, edge.attrs, edge.reviewed);
+        edge.attrs = undefined;
+    }
+    const deduped = dedupeEdges(edges);
+    const kept = deduped.filter((edge) => {
+        if (!isGenerated(edge.target))
+            return true;
+        excluded.generatedTargets++;
+        return false;
+    });
+    return { ...indexEdges(kept), errors, excluded };
+}
+/**
+ * Does an attached marker still certify the target's current content?
+ *
+ * A formatting-only change counts as current: SPEC-134 D3 already decided that
+ * a reformat does not cost a review, and re-deciding it here would make the two
+ * tools disagree.
+ *
+ * An anchor that refuses, or a target that cannot be read, answers `true`. The
+ * refusal is SPEC-131's to report, and treating "could not check" as "stale"
+ * would put every broken anchor at the top of a report about documentation.
+ */
+function markerIsCurrent(repoRoot, target, attrs, reviewed) {
+    let source;
+    try {
+        source = readFileSync(join(repoRoot, target), 'utf8');
+    }
+    catch {
+        return true;
+    }
+    const current = sliceForInvocation(attrs, target, source);
+    if (current === undefined)
+        return true;
+    const stored = parseMarker(reviewed);
+    const verdict = compareMarker(stored.strict, current, stored.loose).verdict;
+    return verdict === 'current' || verdict === 'formatting-only';
+}
+/** Index a list of edges in both directions. */
+export function indexEdges(edges) {
+    const byTarget = new Map();
+    const byReferrer = new Map();
+    for (const edge of edges) {
+        const t = byTarget.get(edge.target);
+        if (t)
+            t.push(edge);
+        else
+            byTarget.set(edge.target, [edge]);
+        const r = byReferrer.get(edge.referrer);
+        if (r)
+            r.push(edge);
+        else
+            byReferrer.set(edge.referrer, [edge]);
+    }
+    return {
+        edges,
+        errors: [],
+        byTarget,
+        byReferrer,
+        excluded: { archivalPages: 0, generatedTargets: 0 },
+    };
+}
+/**
+ * The `touching` query — every page whose edges point at any of `paths`.
+ *
+ * Not a staleness measurement and not a filter over the ranked report: there is
+ * no commit count, because the change has not happened yet. It takes no git
+ * history, is unbounded by `--top`, and is the query that makes this feature
+ * preventive rather than retrospective.
+ */
+export function edgesTouching(index, paths) {
+    const out = [];
+    for (const path of paths) {
+        out.push(...(index.byTarget.get(path) ?? []));
+    }
+    return out;
+}
+/**
+ * Rank the index against a git history.
+ *
+ * One reader of the index among several — `touching` is another, and neither
+ * owns it.
+ *
+ * An edge whose referrer is newer than every change to its target scores zero
+ * and is omitted. A zero score is **the absence of evidence of staleness, not
+ * evidence of freshness**: the referrer side resets on any edit, including a
+ * typo fix (D6, a known and accepted false negative).
+ */
+export function rankEdges(index, history, opts = {}) {
+    const ranked = [];
+    const rates = new Map();
+    for (const edge of index.edges) {
+        if (opts.edgeClass && edge.class !== opts.edgeClass)
+            continue;
+        let rate = rates.get(edge.class);
+        if (!rate) {
+            rate = { class: edge.class, nonZero: 0, scanned: 0 };
+            rates.set(edge.class, rate);
+        }
+        rate.scanned++;
+        const referrerChanged = lastChanged(history, `${history.prefix}${edge.referrer}`);
+        const targetChanged = lastChanged(history, `${history.prefix}${edge.target}`);
+        // An untracked referrer has no "since" to measure from. Reporting it as
+        // maximally stale would put every new page at the top of the report.
+        if (referrerChanged === undefined)
+            continue;
+        // A SPEC-134 marker is a stronger statement than a commit count, so
+        // where one exists it wins (D3) — but only while it is still true. A
+        // marker the target has outgrown has expired as a statement, so the
+        // commit count stands again.
+        if (edge.reviewed && !edge.markerStale)
+            continue;
+        const commits = commitsSince(history, `${history.prefix}${edge.target}`, referrerChanged);
+        if (commits.length === 0)
+            continue;
+        if (opts.min !== undefined && commits.length < opts.min)
+            continue;
+        rate.nonZero++;
+        ranked.push({
+            edge,
+            score: commits.length,
+            referrerChanged,
+            targetChanged,
+            commits,
+        });
+    }
+    ranked.sort((a, b) => b.score - a.score || a.edge.referrer.localeCompare(b.edge.referrer));
+    return {
+        ranked,
+        baseRates: [...rates.values()].sort((a, b) => a.class.localeCompare(b.class)),
+        totalNonZero: ranked.length,
+    };
+}
+/** Build the index and rank it in one call — the report's entry point.
+ *
+ *  `contentDirs`, `archival` and `generated` all come from the project's
+ *  `refrakt.config.json` when not passed explicitly (tests pass fixtures). None
+ *  of the three has a built-in value: a directory layout is a property of the
+ *  project, not of the tool. */
+export function runStale(opts) {
+    const settings = opts.contentDirs === undefined
+        ? resolveStaleSettings(opts.repoRoot)
+        : {
+            contentDirs: opts.contentDirs,
+            archival: opts.archival ?? [],
+            generated: opts.generated ?? [],
+        };
+    const index = buildEdgeIndex({
+        repoRoot: opts.repoRoot,
+        contentDirs: settings.contentDirs,
+        archival: opts.archival ?? settings.archival,
+        generated: opts.generated ?? settings.generated,
+    });
+    const history = scanHistory(opts.repoRoot);
+    const result = rankEdges(index, history, { edgeClass: opts.edgeClass, min: opts.min });
+    return { ...result, index };
+}
+//# sourceMappingURL=index.js.map

package/dist/edges/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/edges/index.ts"],"names":[],"mappings":"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"}

package/dist/frontmatter.d.ts

@@ -40,6 +40,31 @@ export interface Frontmatter {
     /** Last-modified date (ISO 8601), overriding what git history or the
      *  filesystem reports. Read by `timestamps.ts`. */
     modified?: string;
+    /**
+     * Repository paths this page is *about* (SPEC-136 D13).
+     *
+     * The highest-precision edge class `refrakt stale` and `refrakt_stale`
+     * read, because there is no extraction heuristic to be wrong: an author who
+     * lists three files has chosen three files the page actually describes.
+     *
+     * It exists because a page's subject is not always in its words — 209 of
+     * 237 pages in this repository name no file at all, and no extraction rule
+     * reaches them.
+     *
+     * Unlike a `reviewed` marker, this does not decay: it names what the page
+     * is about, which survives every edit to the code it describes. Written
+     * once, it keeps producing edges for years.
+     *
+     * Paths are repo-root-relative POSIX, resolved through the same containment
+     * as `snippet path=`. **A declared path that resolves to nothing is an
+     * error**, not a skip — the author asserted the relationship, so a miss
+     * means the file moved and the declaration did not. Declared edges fail
+     * loudly; inferred ones fail quietly.
+     *
+     * Deliberately does **not** cascade from a `_layout.md`: a layout declaring
+     * what it documents would attribute that claim to every page beneath it.
+     */
+    documents?: string[];
     /** Arbitrary author fields. Deliberately open: runes and pipeline hooks read
      *  frontmatter keys refrakt itself knows nothing about, so the declared
      *  members above describe what refrakt consumes rather than closing the set. */

package/dist/frontmatter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"frontmatter.d.ts","sourceRoot":"","sources":["../src/frontmatter.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,WAAW;IAC3B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;qDACiD;IACjD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;yDAEqD;IACrD,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB;;;wBAGoB;IACpB,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,CAAC;IACxC;;;+BAG2B;IAC3B,WAAW,CAAC,EAAE,OAAO,CAAC;IAMtB;;;8BAG0B;IAC1B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;+CAC2C;IAC3C,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ;4CACwC;IACxC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;uDACmD;IACnD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;oFAEgF;IAChF,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACvB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG;IAAE,WAAW,EAAE,WAAW,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAW3F;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAKtF"}
+{"version":3,"file":"frontmatter.d.ts","sourceRoot":"","sources":["../src/frontmatter.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,WAAW;IAC3B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;qDACiD;IACjD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;yDAEqD;IACrD,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB;;;wBAGoB;IACpB,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,CAAC;IACxC;;;+BAG2B;IAC3B,WAAW,CAAC,EAAE,OAAO,CAAC;IAMtB;;;8BAG0B;IAC1B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;+CAC2C;IAC3C,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ;4CACwC;IACxC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;uDACmD;IACnD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IAErB;;oFAEgF;IAChF,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACvB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG;IAAE,WAAW,EAAE,WAAW,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAW3F;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAKtF"}