@trackunit/repo-checks 0.0.0-stage → 0.0.2

package/migrations/entry.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=entry.js.map

package/migrations.json

@@ -0,0 +1,3 @@
+{
+  "generators": {}
+}

package/package.json

@@ -1,6 +1,37 @@
 {
   "name": "@trackunit/repo-checks",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.0.2",
+  "license": "SEE LICENSE IN LICENSE.txt",
+  "engines": {
+    "node": ">=24.x"
+  },
+  "type": "commonjs",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "require": "./src/index.js",
+      "default": "./src/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "repo-checks": "./bin/index.js"
+  },
+  "dependencies": {
+    "github-slugger": "^2.0.0",
+    "mdast-util-from-markdown": "^2.0.2",
+    "mdast-util-frontmatter": "^2.0.1",
+    "mdast-util-gfm": "^3.1.0",
+    "mdast-util-mdx": "^3.0.0",
+    "micromark-extension-frontmatter": "^2.0.0",
+    "micromark-extension-gfm": "^3.0.0",
+    "micromark-extension-mdxjs": "^3.0.0",
+    "picomatch": "^4.0.4",
+    "tslib": "^2.6.2",
+    "zod": "^3.25.76"
+  },
+  "repository": "https://github.com/Trackunit/manager",
+  "migrations": "./migrations.json"
 }

package/src/cli.d.ts

@@ -0,0 +1,27 @@
+import { type OutputFormat } from "./lib/format";
+type WritableStream = {
+    readonly write: (message: string) => void;
+};
+export type CliStreams = {
+    readonly stdout: WritableStream;
+    readonly stderr: WritableStream;
+};
+export type CliOptions = {
+    /** The directory a relative `--root`, and the default root, resolve from. Defaults to `process.cwd()`. */
+    readonly cwd?: string;
+};
+export type CliCommand = {
+    readonly kind: "help";
+} | {
+    readonly kind: "usageError";
+    readonly message: string;
+} | {
+    readonly kind: "doc-references";
+    readonly root: string | undefined;
+    readonly format: OutputFormat;
+};
+/** Parse the command line into the command to run, without touching the file system. */
+export declare const parseCliArgs: (argv: ReadonlyArray<string>) => CliCommand;
+/** Run the CLI and return its exit code; output goes to `streams`, never to `process` directly. */
+export declare const runCli: (argv: ReadonlyArray<string>, streams: CliStreams, { cwd }?: CliOptions) => number;
+export {};

package/src/cli.js

@@ -0,0 +1,109 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runCli = exports.parseCliArgs = void 0;
+const tslib_1 = require("tslib");
+const fs = tslib_1.__importStar(require("fs"));
+const path = tslib_1.__importStar(require("path"));
+const util_1 = require("util");
+const config_1 = require("./lib/config");
+const check_doc_references_1 = require("./lib/doc-references/check-doc-references");
+const fs_errors_1 = require("./lib/doc-references/fs-errors");
+const repo_root_1 = require("./lib/doc-references/repo-root");
+const format_1 = require("./lib/format");
+/** Exit codes: findings (1) are kept apart from a tool, usage, config, or parse failure (2), so CI can tell them apart. */
+const EXIT_CLEAN = 0;
+const EXIT_FINDINGS = 1;
+const EXIT_ERROR = 2;
+const USAGE = `Usage: repo-checks doc-references [--root <dir>] [--format text|json]
+
+Repository-wide checks for Trackunit repositories.
+
+Commands:
+  doc-references
+    Report file references in .md and .mdx documents whose target or #anchor doesn't exist.
+    Exits 0 when clean, 1 with findings, 2 on a usage, config, document parse, or other tool error.
+
+Options:
+  --root <dir>       Directory to check. Defaults to the repository root of the current directory
+                     (or the current directory outside a repository).
+  --format <format>  text (default): one "file:line:col  target  reason[  did you mean <path>]"
+                     line per finding. json: an array of findings.
+  --help, -h         Show this help message.
+`;
+const isOutputFormat = (value) => format_1.OUTPUT_FORMATS.some(format => format === value);
+const parseCliOptions = (argv) => (0, util_1.parseArgs)({
+    args: [...argv],
+    allowPositionals: true,
+    strict: true,
+    tokens: true,
+    options: {
+        root: { type: "string" },
+        format: { type: "string" },
+        help: { type: "boolean", short: "h" },
+    },
+});
+/** Parse the command line into the command to run, without touching the file system. */
+const parseCliArgs = (argv) => {
+    let parsed;
+    try {
+        parsed = parseCliOptions(argv);
+    }
+    catch (error) {
+        return { kind: "usageError", message: (0, fs_errors_1.errorMessage)(error) };
+    }
+    const { values, positionals, tokens } = parsed;
+    if (values.help)
+        return { kind: "help" };
+    const optionNames = tokens.flatMap(token => (token.kind === "option" ? [token.name] : []));
+    const repeated = optionNames.find((name, index) => optionNames.indexOf(name) !== index);
+    if (repeated !== undefined)
+        return { kind: "usageError", message: `--${repeated} given more than once` };
+    if (values.root === "")
+        return { kind: "usageError", message: "--root requires a directory" };
+    const [subcommand, ...extra] = positionals;
+    if (subcommand === undefined)
+        return { kind: "usageError", message: "Missing command" };
+    if (subcommand !== "doc-references")
+        return { kind: "usageError", message: `Unknown command "${subcommand}"` };
+    if (extra.length > 0)
+        return { kind: "usageError", message: `Unexpected argument "${extra.join(" ")}"` };
+    const format = values.format ?? "text";
+    if (!isOutputFormat(format)) {
+        return { kind: "usageError", message: `Unknown --format "${format}". Expected ${format_1.OUTPUT_FORMATS.join(" or ")}` };
+    }
+    return { kind: "doc-references", root: values.root, format };
+};
+exports.parseCliArgs = parseCliArgs;
+/** Run the CLI and return its exit code; output goes to `streams`, never to `process` directly. */
+const runCli = (argv, streams, { cwd } = {}) => {
+    const command = (0, exports.parseCliArgs)(argv);
+    if (command.kind === "help") {
+        streams.stdout.write(USAGE);
+        return EXIT_CLEAN;
+    }
+    if (command.kind === "usageError") {
+        streams.stderr.write(`Error: ${command.message}\n\n${USAGE}`);
+        return EXIT_ERROR;
+    }
+    const workingDir = path.resolve(cwd ?? process.cwd());
+    const rootDir = command.root === undefined
+        ? ((0, repo_root_1.findRepoRootFromDir)(workingDir) ?? workingDir)
+        : path.resolve(workingDir, command.root);
+    try {
+        const rootStat = fs.statSync(rootDir, { throwIfNoEntry: false });
+        if (!rootStat?.isDirectory()) {
+            streams.stderr.write(`Error: --root ${rootDir} ${rootStat ? "is not a directory" : "does not exist"}\n`);
+            return EXIT_ERROR;
+        }
+        const { config } = (0, config_1.loadConfig)(rootDir);
+        const findings = (0, check_doc_references_1.checkDocReferences)({ rootDir, config: config.docReferences });
+        streams.stdout.write((0, format_1.formatFindings)(findings, command.format));
+        return findings.length === 0 ? EXIT_CLEAN : EXIT_FINDINGS;
+    }
+    catch (error) {
+        streams.stderr.write((0, format_1.formatError)(error));
+        return EXIT_ERROR;
+    }
+};
+exports.runCli = runCli;
+//# sourceMappingURL=cli.js.map

package/src/index.d.ts

@@ -0,0 +1,8 @@
+export { CONFIG_FILE_NAME, ConfigError, loadConfig, type LoadedConfig, type RepoChecksConfig } from "./lib/config";
+export { checkDocReferences, type CheckDocReferencesOptions } from "./lib/doc-references/check-doc-references";
+export type { ReferenceConstruct } from "./lib/doc-references/extract";
+export type { Finding, FindingReason } from "./lib/doc-references/finding";
+export { ReadError } from "./lib/doc-references/fs-errors";
+export { DocumentParseError } from "./lib/doc-references/parse";
+export { DEFAULT_DOCS_SETTINGS, parseDocsSettings, type DocReferencesConfig, type DocsSettings, } from "./lib/doc-references/settings";
+export { OUTPUT_FORMATS, formatFinding, formatFindings, type OutputFormat } from "./lib/format";

package/src/index.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatFindings = exports.formatFinding = exports.OUTPUT_FORMATS = exports.parseDocsSettings = exports.DEFAULT_DOCS_SETTINGS = exports.DocumentParseError = exports.ReadError = exports.checkDocReferences = exports.loadConfig = exports.ConfigError = exports.CONFIG_FILE_NAME = void 0;
+var config_1 = require("./lib/config");
+Object.defineProperty(exports, "CONFIG_FILE_NAME", { enumerable: true, get: function () { return config_1.CONFIG_FILE_NAME; } });
+Object.defineProperty(exports, "ConfigError", { enumerable: true, get: function () { return config_1.ConfigError; } });
+Object.defineProperty(exports, "loadConfig", { enumerable: true, get: function () { return config_1.loadConfig; } });
+var check_doc_references_1 = require("./lib/doc-references/check-doc-references");
+Object.defineProperty(exports, "checkDocReferences", { enumerable: true, get: function () { return check_doc_references_1.checkDocReferences; } });
+var fs_errors_1 = require("./lib/doc-references/fs-errors");
+Object.defineProperty(exports, "ReadError", { enumerable: true, get: function () { return fs_errors_1.ReadError; } });
+var parse_1 = require("./lib/doc-references/parse");
+Object.defineProperty(exports, "DocumentParseError", { enumerable: true, get: function () { return parse_1.DocumentParseError; } });
+var settings_1 = require("./lib/doc-references/settings");
+Object.defineProperty(exports, "DEFAULT_DOCS_SETTINGS", { enumerable: true, get: function () { return settings_1.DEFAULT_DOCS_SETTINGS; } });
+Object.defineProperty(exports, "parseDocsSettings", { enumerable: true, get: function () { return settings_1.parseDocsSettings; } });
+var format_1 = require("./lib/format");
+Object.defineProperty(exports, "OUTPUT_FORMATS", { enumerable: true, get: function () { return format_1.OUTPUT_FORMATS; } });
+Object.defineProperty(exports, "formatFinding", { enumerable: true, get: function () { return format_1.formatFinding; } });
+Object.defineProperty(exports, "formatFindings", { enumerable: true, get: function () { return format_1.formatFindings; } });
+//# sourceMappingURL=index.js.map

package/src/lib/config-error.d.ts

@@ -0,0 +1,8 @@
+/**
+ * A configuration that can't be read or is invalid: the checks never ran, so it is distinct from
+ * findings and from a {@link DocumentParseError} about a checked document.
+ */
+export declare class ConfigError extends Error {
+    /** @param message What is wrong, naming the config file or the setting. */
+    constructor(message: string);
+}

package/src/lib/config-error.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConfigError = void 0;
+/**
+ * A configuration that can't be read or is invalid: the checks never ran, so it is distinct from
+ * findings and from a {@link DocumentParseError} about a checked document.
+ */
+class ConfigError extends Error {
+    /** @param message What is wrong, naming the config file or the setting. */
+    constructor(message) {
+        super(message);
+        this.name = "ConfigError";
+    }
+}
+exports.ConfigError = ConfigError;
+//# sourceMappingURL=config-error.js.map

package/src/lib/config.d.ts

@@ -0,0 +1,22 @@
+import { type DocReferencesConfig } from "./doc-references/settings";
+export { ConfigError } from "./config-error";
+/** The config file, read from the repository root. */
+export declare const CONFIG_FILE_NAME = "repo-checks.config.json";
+/** A validated `repo-checks.config.json`; each section is passed as-is to its check, which resolves it onto the defaults. */
+export interface RepoChecksConfig {
+    readonly docReferences?: DocReferencesConfig;
+}
+export interface LoadedConfig {
+    /** The absolute path of the file read, or `undefined` when there is none. */
+    readonly file: string | undefined;
+    readonly config: RepoChecksConfig;
+}
+/**
+ * Read and validate `repo-checks.config.json` at the root of the repository enclosing `rootDir`
+ * (the nearest `.git` at or above it, so a subdirectory or git worktree finds its own checkout's
+ * file), or in `rootDir` itself outside a repository. No file is an empty config: every default.
+ * A relative `docReferences.rootDir` is returned resolved against the file's directory.
+ *
+ * @throws {ConfigError} when the file can't be read, isn't valid JSON, or fails validation
+ */
+export declare const loadConfig: (rootDir: string) => LoadedConfig;

package/src/lib/config.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadConfig = exports.CONFIG_FILE_NAME = exports.ConfigError = void 0;
+const tslib_1 = require("tslib");
+const fs = tslib_1.__importStar(require("fs"));
+const path = tslib_1.__importStar(require("path"));
+const config_error_1 = require("./config-error");
+const fs_errors_1 = require("./doc-references/fs-errors");
+const repo_root_1 = require("./doc-references/repo-root");
+const settings_1 = require("./doc-references/settings");
+var config_error_2 = require("./config-error");
+Object.defineProperty(exports, "ConfigError", { enumerable: true, get: function () { return config_error_2.ConfigError; } });
+/** The config file, read from the repository root. */
+exports.CONFIG_FILE_NAME = "repo-checks.config.json";
+const repoChecksConfigSchema = (0, settings_1.strictObjectNamingKeys)({ docReferences: settings_1.docReferencesConfigSchema.optional() }, { noun: "key", expected: "a JSON object" });
+const readConfigFile = (file) => {
+    try {
+        return fs.readFileSync(file, "utf8");
+    }
+    catch (error) {
+        if ((0, fs_errors_1.isNotFoundError)(error))
+            return undefined;
+        throw new config_error_1.ConfigError(`Cannot read ${file}: ${(0, fs_errors_1.errorMessage)(error)}`);
+    }
+};
+/** A relative `rootDir` is relative to the config file, so it means the same from any checked directory. */
+const resolveRootDir = (config, file) => {
+    const rootDir = config.docReferences?.rootDir;
+    return rootDir === undefined
+        ? config
+        : { ...config, docReferences: { ...config.docReferences, rootDir: path.resolve(path.dirname(file), rootDir) } };
+};
+/**
+ * Read and validate `repo-checks.config.json` at the root of the repository enclosing `rootDir`
+ * (the nearest `.git` at or above it, so a subdirectory or git worktree finds its own checkout's
+ * file), or in `rootDir` itself outside a repository. No file is an empty config: every default.
+ * A relative `docReferences.rootDir` is returned resolved against the file's directory.
+ *
+ * @throws {ConfigError} when the file can't be read, isn't valid JSON, or fails validation
+ */
+const loadConfig = (rootDir) => {
+    const directory = path.resolve(rootDir);
+    const file = path.join((0, repo_root_1.findRepoRootFromDir)(directory) ?? directory, exports.CONFIG_FILE_NAME);
+    const source = readConfigFile(file);
+    if (source === undefined)
+        return { file: undefined, config: {} };
+    let json;
+    try {
+        json = JSON.parse(source.replace(/^\uFEFF/u, ""));
+    }
+    catch (error) {
+        throw new config_error_1.ConfigError(`Invalid JSON in ${file}: ${(0, fs_errors_1.errorMessage)(error)}`);
+    }
+    const parsed = repoChecksConfigSchema.safeParse(json);
+    if (!parsed.success) {
+        throw new config_error_1.ConfigError(`Invalid config ${file}: ${(0, settings_1.formatConfigIssues)(parsed.error)}`);
+    }
+    return { file, config: resolveRootDir(parsed.data, file) };
+};
+exports.loadConfig = loadConfig;
+//# sourceMappingURL=config.js.map

package/src/lib/doc-references/case-fix.d.ts

@@ -0,0 +1,21 @@
+import { type ReferenceKind } from "./resolver";
+export interface CaseFixInput {
+    /** The reference as written, including any `?query` (URLs) and `#fragment`. */
+    readonly reference: string;
+    readonly referenceKind: ReferenceKind;
+    /** The directory the reference resolved against (`caseMismatch.base`). */
+    readonly base: string;
+    /** The absolute path the resolver derived from the reference (`caseMismatch.path`). */
+    readonly resolvedPath: string;
+    /** The on-disk path it matched case-insensitively (`caseMismatch.actualPath`). */
+    readonly actualPath: string;
+}
+/**
+ * Rewrite `reference` to the on-disk casing, changing only the path segments whose case differs.
+ * Everything else — `./` and `../` prefixes, a leading `/`, a URL's query, the fragment, and untouched segments
+ * (including their percent-encoding) — is kept exactly as written.
+ *
+ * Returns `undefined` when no safe rewrite exists: a segment that needs recasing is percent-encoded
+ * (re-encoding it could change more than case), or the segments don't line up with `actualPath`.
+ */
+export declare const correctReferenceCase: ({ reference, referenceKind, base, resolvedPath, actualPath, }: CaseFixInput) => string | undefined;

package/src/lib/doc-references/case-fix.js

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.correctReferenceCase = void 0;
+const tslib_1 = require("tslib");
+const path = tslib_1.__importStar(require("path"));
+const resolver_1 = require("./resolver");
+const decodeSegment = (segment, referenceKind) => {
+    if (referenceKind === "inline")
+        return segment;
+    try {
+        return decodeURIComponent(segment);
+    }
+    catch {
+        return segment;
+    }
+};
+const isAncestorOrSelf = (ancestor, descendant) => descendant === ancestor || descendant.startsWith(ancestor + path.sep);
+/**
+ * Rewrite `reference` to the on-disk casing, changing only the path segments whose case differs.
+ * Everything else — `./` and `../` prefixes, a leading `/`, a URL's query, the fragment, and untouched segments
+ * (including their percent-encoding) — is kept exactly as written.
+ *
+ * Returns `undefined` when no safe rewrite exists: a segment that needs recasing is percent-encoded
+ * (re-encoding it could change more than case), or the segments don't line up with `actualPath`.
+ */
+const correctReferenceCase = ({ reference, referenceKind, base, resolvedPath, actualPath, }) => {
+    const { pathPart, suffix } = (0, resolver_1.splitReference)(reference, referenceKind);
+    const rawSegments = pathPart.split("/");
+    const decodedSegments = rawSegments.map(segment => decodeSegment(segment, referenceKind));
+    const positions = [];
+    let position = base;
+    for (const segment of decodedSegments) {
+        position = path.resolve(position, segment);
+        positions.push(position);
+    }
+    const actualSegments = actualPath.split(path.sep);
+    if (position !== resolvedPath || actualSegments.length !== resolvedPath.split(path.sep).length) {
+        return undefined;
+    }
+    let changed = false;
+    const fixedSegments = [];
+    for (const [index, raw] of rawSegments.entries()) {
+        const decoded = decodedSegments[index] ?? raw;
+        const segmentPosition = positions[index] ?? base;
+        if (decoded === "" || decoded === "." || decoded === ".." || !isAncestorOrSelf(segmentPosition, resolvedPath)) {
+            fixedSegments.push(raw);
+            continue;
+        }
+        const actual = actualSegments[segmentPosition.split(path.sep).length - 1];
+        if (actual === undefined || actual.toLowerCase() !== decoded.toLowerCase()) {
+            return undefined;
+        }
+        if (actual === decoded) {
+            fixedSegments.push(raw);
+            continue;
+        }
+        if (referenceKind === "url" && raw.includes("%")) {
+            return undefined;
+        }
+        fixedSegments.push(actual);
+        changed = true;
+    }
+    return changed ? fixedSegments.join("/") + suffix : undefined;
+};
+exports.correctReferenceCase = correctReferenceCase;
+//# sourceMappingURL=case-fix.js.map

package/src/lib/doc-references/check-doc-references.d.ts

@@ -0,0 +1,28 @@
+import { type Finding } from "./finding";
+import { type DocReferencesConfig } from "./settings";
+export interface CheckDocReferencesOptions {
+    /** The directory whose documents are checked: a repository, a git worktree, or a subdirectory of one. */
+    readonly rootDir: string;
+    /**
+     * The `docReferences` section of a config, as `loadConfig` returns it or written inline, validated
+     * with `parseDocsSettings`; the defaults when omitted.
+     */
+    readonly config?: DocReferencesConfig;
+}
+/**
+ * Check every `.md` and `.mdx` document under `rootDir`, except those the config excludes, for
+ * references whose targets don't exist, or exist only under different letter case (decided
+ * case-exactly on every filesystem), and for `#fragment`s that name no heading or anchor in the
+ * `.md` or `.mdx` document they point into, or in their own document when they have no path; never
+ * against an `.mdx` document whose MDX may render anchors parsing can't see (see
+ * `knownDocumentAnchors`). Each reference gives at most one finding.
+ *
+ * Relative references resolve from the document's directory and a leading `/` from the repository
+ * root (the nearest `.git` at or above `rootDir`, or the config's `rootDir`). Findings are sorted by
+ * file, line, and column, with `file` relative to the repository root.
+ *
+ * @throws {ConfigError} when the config is invalid, before any document is read
+ * @throws {DocumentParseError} when a document can't be parsed
+ * @throws {ReadError} when a document or directory can't be read
+ */
+export declare const checkDocReferences: ({ rootDir, config }: CheckDocReferencesOptions) => Array<Finding>;

package/src/lib/doc-references/check-doc-references.js

@@ -0,0 +1,147 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkDocReferences = void 0;
+const tslib_1 = require("tslib");
+const fs = tslib_1.__importStar(require("fs"));
+const path = tslib_1.__importStar(require("path"));
+const case_fix_1 = require("./case-fix");
+const classify_1 = require("./classify");
+const discover_1 = require("./discover");
+const extract_1 = require("./extract");
+const finding_1 = require("./finding");
+const fs_errors_1 = require("./fs-errors");
+const headings_1 = require("./headings");
+const parse_1 = require("./parse");
+const placeholders_1 = require("./placeholders");
+const repo_root_1 = require("./repo-root");
+const resolver_1 = require("./resolver");
+const settings_1 = require("./settings");
+const toPosix = (relativePath) => relativePath.split(path.sep).join("/");
+const readDocument = (absolutePath, file) => {
+    try {
+        return fs.readFileSync(absolutePath, "utf8");
+    }
+    catch (error) {
+        throw new fs_errors_1.ReadError(`Cannot read ${file}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+};
+/**
+ * The reference rewritten to the on-disk casing, or `undefined` when there's no single safe rewrite:
+ * several siblings match case-insensitively, the reference has placeholders (so `actualPath` is one
+ * instance of it), or a segment needing recasing is percent-encoded.
+ */
+const caseSuggestion = (reference, referenceKind, resolution) => resolution.ambiguous || resolution.placeholder
+    ? undefined
+    : (0, case_fix_1.correctReferenceCase)({
+        reference,
+        referenceKind,
+        base: resolution.base,
+        resolvedPath: resolution.path,
+        actualPath: resolution.actualPath,
+    });
+const ANCHOR_CHECKED_EXTENSIONS = new Set([".md", ".mdx"]);
+/** Whether a fragment, percent-decoded, is written in a placeholder convention (`#<name>`, `#{name}`, `#:name`). */
+const isPlaceholderFragment = (fragment, placeholders) => {
+    let decoded = fragment;
+    try {
+        decoded = decodeURIComponent(fragment);
+    }
+    catch {
+        // checked as written
+    }
+    return (0, placeholders_1.compileReference)(decoded, placeholders) !== undefined;
+};
+/**
+ * Whether a reference that resolved exactly has a `#fragment` naming no heading or anchor in its
+ * `.md` or `.mdx` target. A placeholder reference's match is one arbitrary instance, a placeholder
+ * fragment names no particular anchor, and a target that can't be read or parsed, is too large, or
+ * has MDX that may render anchors parsing can't see (Storybook's `<Title />`, imports,
+ * `{expressions}`), has no known anchors, so none of these is ever reported.
+ */
+const isMissingAnchor = (reference, resolution, placeholders) => {
+    const fragment = (0, resolver_1.referenceFragment)(reference);
+    const extension = path.extname(resolution.path).toLowerCase();
+    if (fragment === "" || resolution.placeholder || !ANCHOR_CHECKED_EXTENSIONS.has(extension))
+        return false;
+    if (isPlaceholderFragment(fragment, placeholders))
+        return false;
+    const anchors = (0, headings_1.readDocumentAnchors)(resolution.path);
+    return anchors !== undefined && !(0, headings_1.hasAnchor)(anchors, fragment);
+};
+const checkDocument = (absolutePath, repoRoot, settings) => {
+    const file = toPosix(path.relative(repoRoot, absolutePath));
+    const tree = (0, parse_1.parseMarkdown)(readDocument(absolutePath, file), file);
+    const documentDir = path.dirname(absolutePath);
+    let own;
+    return (0, extract_1.extractReferences)(tree, settings).flatMap(({ kind, target, line, column }) => {
+        const referenceKind = (0, extract_1.referenceKindOf)(kind);
+        // A fragment-only URL points into this document; inline code like `#channel` isn't a link.
+        if (referenceKind === "url" && target.startsWith("#")) {
+            const fragment = target.slice(1);
+            if (fragment === "" || isPlaceholderFragment(fragment, settings.placeholders))
+                return [];
+            own ?? (own = { anchors: (0, headings_1.knownDocumentAnchors)(tree, file) });
+            return own.anchors === undefined || (0, headings_1.hasAnchor)(own.anchors, fragment)
+                ? []
+                : [{ file, line, column, target, kind, reason: "missingAnchor" }];
+        }
+        if (!(0, classify_1.classifyReference)(target, referenceKind, settings).check)
+            return [];
+        const resolution = (0, resolver_1.resolveReference)({
+            reference: target,
+            referenceKind,
+            documentDir,
+            repoRoot,
+            ignore: settings.ignore,
+            placeholders: settings.placeholders,
+        });
+        if (resolution.kind === "missing")
+            return [{ file, line, column, target, kind, reason: "missing" }];
+        if (resolution.kind === "caseMismatch") {
+            const suggestion = caseSuggestion(target, referenceKind, resolution);
+            return [
+                {
+                    file,
+                    line,
+                    column,
+                    target,
+                    kind,
+                    reason: "caseMismatch",
+                    ...(suggestion === undefined ? {} : { suggestion }),
+                },
+            ];
+        }
+        if (resolution.kind === "exact" && isMissingAnchor(target, resolution, settings.placeholders)) {
+            return [{ file, line, column, target, kind, reason: "missingAnchor" }];
+        }
+        return [];
+    });
+};
+/**
+ * Check every `.md` and `.mdx` document under `rootDir`, except those the config excludes, for
+ * references whose targets don't exist, or exist only under different letter case (decided
+ * case-exactly on every filesystem), and for `#fragment`s that name no heading or anchor in the
+ * `.md` or `.mdx` document they point into, or in their own document when they have no path; never
+ * against an `.mdx` document whose MDX may render anchors parsing can't see (see
+ * `knownDocumentAnchors`). Each reference gives at most one finding.
+ *
+ * Relative references resolve from the document's directory and a leading `/` from the repository
+ * root (the nearest `.git` at or above `rootDir`, or the config's `rootDir`). Findings are sorted by
+ * file, line, and column, with `file` relative to the repository root.
+ *
+ * @throws {ConfigError} when the config is invalid, before any document is read
+ * @throws {DocumentParseError} when a document can't be parsed
+ * @throws {ReadError} when a document or directory can't be read
+ */
+const checkDocReferences = ({ rootDir, config }) => {
+    const settings = (0, settings_1.parseDocsSettings)(config);
+    const checkedDir = (0, resolver_1.canonicalCase)(path.resolve(rootDir));
+    const repoRoot = (0, resolver_1.canonicalCase)((0, repo_root_1.findRepoRootFromDir)(checkedDir, { rootDir: settings.rootDir, cwd: checkedDir }) ?? checkedDir);
+    return (0, discover_1.discoverDocuments)(checkedDir)
+        .map(resolver_1.canonicalCase)
+        .filter(document => !(0, resolver_1.isIgnoredPath)(path.relative(repoRoot, document), settings.exclude))
+        .flatMap(document => checkDocument(document, repoRoot, settings))
+        .sort(finding_1.compareFindings);
+};
+exports.checkDocReferences = checkDocReferences;
+//# sourceMappingURL=check-doc-references.js.map

package/src/lib/doc-references/classify.d.ts

@@ -0,0 +1,49 @@
+import { type ReferenceKind } from "./resolver";
+/**
+ * Decide whether a markdown reference looks like a repository path worth resolving.
+ *
+ * The non-configurable exclusions are categorically not repo-relative paths: URLs with a scheme,
+ * container/registry image references, home-directory paths, globs, shell variables, multi-word
+ * command spans, Storybook `?path=` links, and bare `#anchor`s. The configurable `ignore` list is applied by the resolver,
+ * because globs match the repo-relative path, which depends on where the reference resolves.
+ *
+ * Beyond those, the shape of the target decides. The target is the resolver's `referenceTarget`: a
+ * URL's `?query` and `#fragment` are stripped and it is percent-decoded (`guide%2Emd` has an
+ * extension), while inline code only loses a `#fragment`.
+ *   - a `/` and a file extension (`docs/guide.md`): always checked;
+ *   - a `/` and no extension (`libs/react/components/`, `docs/guides`): checked with `directories`;
+ *   - no `/` and a file extension, in a link, image, or definition URL (`[x](README.md)`): always
+ *     checked, since a URL with no `/` and no scheme is unambiguously a path relative to the
+ *     document;
+ *   - no `/` and a file extension, in inline code (`` `README.md` ``, `` `package.json` ``):
+ *     checked with `bareFilenames`, since most inline-code spans with no `/` are package names,
+ *     versions, or commands rather than paths (see `bareFilenames`'s doc comment in `settings.ts`);
+ *   - no `/` and no extension, either way (`` `README` ``, `[x](README)`): checked only when both
+ *     `bareFilenames` and `directories` are on.
+ * An extension is a final `.` and 1-8 letters or digits, so a bare `v1.2` or `console.log` counts
+ * as a filename too.
+ * The resolver then expects a file for an extension, a directory for a trailing `/`, and either
+ * otherwise (including a stemless dot-name such as `.github`, which is still checked here).
+ *
+ * Placeholder references (`docs/<name>.md`, `path/to/file.ts`) are passed on: the resolver matches
+ * them as wildcards, or skips illustrative `path/to/` ones, under the configured conventions. The file-path test is applied to the target, not
+ * to what its placeholders expand to, so a placeholder counts as having an extension only when a literal `.ext` ends it
+ * (`<name>.md` does, `<file>` and `file.<ext>` don't).
+ */
+export type SkipReason = "empty" | "anchorOnly" | "multiWord" | "registryImage" | "urlScheme" | "homePath" | "shellVariable" | "glob" | "storybookPath" | "notAFilePath";
+export type Classification = {
+    readonly check: true;
+} | {
+    readonly check: false;
+    readonly reason: SkipReason;
+};
+/** The doc-references settings that widen which reference shapes are checked. */
+export interface ClassifyOptions {
+    readonly directories: boolean;
+    readonly bareFilenames: boolean;
+}
+/**
+ * Whether a reference is checked as a repo path, or the reason it is skipped: empty, anchor-only,
+ * URL-, shell- or glob-shaped, a registry image, a Storybook path, or not shaped like a file path.
+ */
+export declare const classifyReference: (reference: string | undefined, referenceKind: ReferenceKind, options?: ClassifyOptions) => Classification;