@trackunit/repo-checks 0.0.0-stage → 0.0.2

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

@@ -0,0 +1,430 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveReference = exports.MAX_VISITED_DIRECTORIES = exports.referenceTarget = exports.hasFileExtension = exports.referenceFragment = exports.splitReference = exports.isIgnoredPath = exports.canonicalCase = exports.RACY_WINDOW_MS = void 0;
+const tslib_1 = require("tslib");
+const fs = tslib_1.__importStar(require("fs"));
+const path = tslib_1.__importStar(require("path"));
+const picomatch_1 = tslib_1.__importDefault(require("picomatch"));
+const fs_errors_1 = require("./fs-errors");
+const placeholders_1 = require("./placeholders");
+/** Per-process listing cache, so each directory is listed once per run; revalidated by directory mtime. */
+const listingCache = new Map();
+/**
+ * A listing (or parsed file) read within this long of its mtime is never reused: a change in the
+ * same timestamp tick leaves the mtime unchanged. Covers the coarsest common granularity (FAT, 2s).
+ */
+exports.RACY_WINDOW_MS = 2000;
+/**
+ * The listing of `directory`, or `undefined` when it doesn't exist or isn't a directory.
+ *
+ * @throws {ReadError} when `directory` exists but can't be stat'ed or listed
+ */
+const listDirectory = (directory) => {
+    let mtimeMs;
+    try {
+        const stats = fs.statSync(directory);
+        if (!stats.isDirectory()) {
+            listingCache.delete(directory);
+            return undefined;
+        }
+        mtimeMs = stats.mtimeMs;
+    }
+    catch (error) {
+        listingCache.delete(directory);
+        if ((0, fs_errors_1.isNotFoundError)(error))
+            return undefined;
+        throw new fs_errors_1.ReadError(`Cannot read directory ${directory}: ${(0, fs_errors_1.errorMessage)(error)}`);
+    }
+    const cached = listingCache.get(directory);
+    if (cached?.mtimeMs === mtimeMs && cached.listedAtMs - mtimeMs > exports.RACY_WINDOW_MS) {
+        return cached;
+    }
+    try {
+        const listedAtMs = Date.now();
+        const names = fs.readdirSync(directory);
+        const byLowerCase = new Map();
+        const ambiguousLowerCase = new Set();
+        for (const name of names) {
+            const lowerCase = name.toLowerCase();
+            if (byLowerCase.has(lowerCase)) {
+                ambiguousLowerCase.add(lowerCase);
+            }
+            else {
+                byLowerCase.set(lowerCase, name);
+            }
+        }
+        const listing = {
+            mtimeMs,
+            listedAtMs,
+            names: new Set(names),
+            sortedNames: [...names].sort(),
+            byLowerCase,
+            ambiguousLowerCase,
+        };
+        listingCache.set(directory, listing);
+        return listing;
+    }
+    catch (error) {
+        listingCache.delete(directory);
+        if ((0, fs_errors_1.isNotFoundError)(error))
+            return undefined;
+        throw new fs_errors_1.ReadError(`Cannot read directory ${directory}: ${(0, fs_errors_1.errorMessage)(error)}`);
+    }
+};
+/** The listed entry named `segment`, exactly if possible, otherwise case-insensitively. */
+const findListedEntry = (listing, segment) => {
+    if (listing.names.has(segment)) {
+        return { name: segment, ambiguous: false };
+    }
+    const lowerCase = segment.toLowerCase();
+    const name = listing.byLowerCase.get(lowerCase);
+    return name === undefined ? undefined : { name, ambiguous: listing.ambiguousLowerCase.has(lowerCase) };
+};
+const findEntry = (directory, segment) => {
+    const listing = listDirectory(directory);
+    return listing && findListedEntry(listing, segment);
+};
+const isWithin = (absolutePath, directory) => absolutePath === directory || absolutePath.startsWith(directory + path.sep);
+const segmentsBelow = (base, absolutePath) => path
+    .relative(base, absolutePath)
+    .split(path.sep)
+    .filter(segment => segment !== "");
+/**
+ * What a reference's target may name: a trailing `/` needs a directory, a file extension a file,
+ * and anything else either. A stemless dot-name (`.github`, `.gitignore`) has no extension here,
+ * since it is as often a directory as a file. A multi-dot name (`apps/socket.io`) does, so it must
+ * name a file.
+ */
+const expectedKind = (target) => {
+    if (target.endsWith("/"))
+        return "directory";
+    const lastSegment = target.slice(target.lastIndexOf("/") + 1);
+    if (/^\.[^.]+$/.test(lastSegment))
+        return "any";
+    return (0, exports.hasFileExtension)(target) ? "file" : "any";
+};
+/**
+ * Whether `absolutePath` exists, following symlinks, and is of the `expected` kind.
+ *
+ * @throws {ReadError} when `absolutePath` exists but can't be stat'ed
+ */
+const isExpectedKind = (absolutePath, expected) => {
+    let stats;
+    try {
+        stats = fs.statSync(absolutePath);
+    }
+    catch (error) {
+        if ((0, fs_errors_1.isNotFoundError)(error))
+            return false; // e.g. a dangling symlink, which a directory listing still names
+        throw new fs_errors_1.ReadError(`Cannot read ${absolutePath}: ${(0, fs_errors_1.errorMessage)(error)}`);
+    }
+    return expected === "any" || stats.isDirectory() === (expected === "directory");
+};
+/**
+ * Walk `absolutePath` segment by segment below `trustedBase` (whose casing the caller has already
+ * canonicalised), comparing each name exactly against its parent's listing. The entry it ends on
+ * must be of the `expected` kind, or the reference is `missing` whatever its casing.
+ */
+const lookupCaseExact = (absolutePath, trustedBase, expected) => {
+    const start = isWithin(absolutePath, trustedBase) ? trustedBase : path.parse(absolutePath).root;
+    let actualPath = start;
+    let caseDiffers = false;
+    let ambiguous = false;
+    for (const segment of segmentsBelow(start, absolutePath)) {
+        const entry = findEntry(actualPath, segment);
+        if (entry === undefined) {
+            return { kind: "missing" };
+        }
+        caseDiffers || (caseDiffers = entry.name !== segment);
+        ambiguous || (ambiguous = entry.ambiguous);
+        actualPath = path.join(actualPath, entry.name);
+    }
+    if (!isExpectedKind(actualPath, expected)) {
+        return { kind: "missing" };
+    }
+    return caseDiffers ? { kind: "caseMismatch", actualPath, ambiguous } : { kind: "exact", path: absolutePath };
+};
+/**
+ * The on-disk casing of an absolute path, without following symlinks. Segments from the first one
+ * that doesn't exist, or whose parent can't be listed, onward are returned as given. Callers can be
+ * handed a differently cased path on case-insensitive filesystems; canonicalising the document's own
+ * path keeps its relative references from all reading as case mismatches.
+ */
+const canonicalCase = (absolutePath) => {
+    const root = path.parse(absolutePath).root;
+    const segments = segmentsBelow(root, absolutePath);
+    let actualPath = root;
+    for (const [index, segment] of segments.entries()) {
+        let entry;
+        try {
+            entry = findEntry(actualPath, segment);
+        }
+        catch {
+            // Ancestors outside the repository may be searchable but not listable (e.g. a `--x` home directory).
+            entry = undefined;
+        }
+        if (entry === undefined) {
+            return path.join(actualPath, ...segments.slice(index));
+        }
+        actualPath = path.join(actualPath, entry.name);
+    }
+    return actualPath;
+};
+exports.canonicalCase = canonicalCase;
+const compiledIgnores = new WeakMap();
+/** Whether a repo-relative path (either separator) matches any of the ignore globs. */
+const isIgnoredPath = (repoRelativePath, ignore) => {
+    let matchers = compiledIgnores.get(ignore);
+    if (!matchers) {
+        matchers = ignore.map(glob => (0, picomatch_1.default)(glob, { dot: true }));
+        compiledIgnores.set(ignore, matchers);
+    }
+    const normalized = repoRelativePath.split(path.sep).join("/");
+    return matchers.some(matcher => matcher(normalized));
+};
+exports.isIgnoredPath = isIgnoredPath;
+/**
+ * Split a reference into its path part and suffix. A URL's suffix starts at its `?query` or
+ * `#fragment`, whichever comes first. Inline code only drops a `#fragment`, since a `?` in a code
+ * span may be a literal part of the path.
+ */
+const splitReference = (reference, referenceKind) => {
+    const index = reference.search(referenceKind === "url" ? /[?#]/ : /#/);
+    return index === -1
+        ? { pathPart: reference, suffix: "" }
+        : { pathPart: reference.slice(0, index), suffix: reference.slice(index) };
+};
+exports.splitReference = splitReference;
+/** A reference's `#fragment` without the `#`, still percent-encoded for URLs; `""` when there is none. */
+const referenceFragment = (reference) => {
+    const index = reference.indexOf("#");
+    return index === -1 ? "" : reference.slice(index + 1);
+};
+exports.referenceFragment = referenceFragment;
+const EXTENSION_RE = /\.[A-Za-z0-9]{1,8}$/;
+/** Whether a reference target ends in a file extension. One ending in `/` never does. */
+const hasFileExtension = (target) => EXTENSION_RE.test(target);
+exports.hasFileExtension = hasFileExtension;
+/** mdast keeps `url` percent-encoded. A malformed escape is checked as written. */
+const decodeUrlPath = (value) => {
+    try {
+        return decodeURIComponent(value);
+    }
+    catch {
+        return value;
+    }
+};
+/** The path a reference names: its path part (see `splitReference`), percent-decoded for URLs. */
+const referenceTarget = (reference, referenceKind) => {
+    const { pathPart } = (0, exports.splitReference)(reference, referenceKind);
+    return referenceKind === "url" ? decodeUrlPath(pathPart) : pathPart;
+};
+exports.referenceTarget = referenceTarget;
+const candidatePaths = ({ referenceKind, documentDir, repoRoot }, target) => {
+    if (target.startsWith("/")) {
+        return [{ base: repoRoot, path: path.resolve(repoRoot, target.replace(/^\/+/, "")) }];
+    }
+    const relativeToDocument = { base: documentDir, path: path.resolve(documentDir, target) };
+    if (referenceKind === "url") {
+        return [relativeToDocument];
+    }
+    const relativeToRoot = { base: repoRoot, path: path.resolve(repoRoot, target) };
+    return relativeToRoot.path === relativeToDocument.path ? [relativeToDocument] : [relativeToDocument, relativeToRoot];
+};
+/** Hard cap on directory listings per placeholder reference; hitting it skips the reference. */
+exports.MAX_VISITED_DIRECTORIES = 10000;
+const compiledDirectoryIgnores = new WeakMap();
+/**
+ * Whether every descendant of a directory is ignored, so a wildcard walk must not list it. That
+ * holds exactly when some glob is `P/**` and the directory matches `P`: `**\/dist/**` prunes
+ * `libs/dist`, while `dist/*` or `**\/*.zip` never prune anything.
+ */
+const isIgnoredDirectory = (directory, { repoRoot, ignore }) => {
+    let matchers = compiledDirectoryIgnores.get(ignore);
+    if (!matchers) {
+        matchers = ignore.flatMap(glob => {
+            const prefix = glob.endsWith("/**") ? glob.slice(0, -"/**".length) : "";
+            return prefix === "" || prefix.startsWith("!") ? [] : [(0, picomatch_1.default)(prefix, { dot: true })];
+        });
+        compiledDirectoryIgnores.set(ignore, matchers);
+    }
+    const normalized = path.relative(repoRoot, directory).split(path.sep).join("/");
+    return normalized !== "" && matchers.some(matcher => matcher(normalized));
+};
+/**
+ * Whether a resolved path is ignored: it matches an ignore glob, or the reference may name a
+ * directory and this one is ignored entirely, so `dist/` counts as ignored generated output even
+ * before a build creates it.
+ */
+const isIgnoredTarget = (absolutePath, expected, input) => (0, exports.isIgnoredPath)(path.relative(input.repoRoot, absolutePath), input.ignore) ||
+    (expected !== "file" && isIgnoredDirectory(absolutePath, input));
+const lookupLiteral = (candidate, expected, input) => isIgnoredTarget(candidate.path, expected, input)
+    ? { kind: "ignored" }
+    : lookupCaseExact(candidate.path, input.repoRoot, expected);
+const CASE_EXACT = { caseDiffers: false, ambiguous: false };
+/** List `directory` for the walk, unless it is ignored or the budget is spent. */
+const visit = ({ input, budget }, directory) => {
+    if (budget.exhausted || isIgnoredDirectory(directory, input))
+        return undefined;
+    if (budget.remaining <= 0) {
+        budget.exhausted = true;
+        return undefined;
+    }
+    const listing = listDirectory(directory);
+    if (listing)
+        budget.remaining--;
+    return listing;
+};
+/** Entry names a wildcard step may take; `.git` is never entered. */
+const wildcardNames = (listing) => listing.sortedNames.filter(name => name !== ".git");
+/**
+ * Depth-first, backtracking walk of `walk.steps` from `directory` (already matching the first
+ * `index` steps).
+ *
+ * @yields every existing, non-ignored match of the expected kind, in sorted entry-name order
+ */
+function* walkMatches(walk, directory, index, bindings, matchCase) {
+    const step = walk.steps[index];
+    if (step === undefined) {
+        if (isExpectedKind(directory, walk.expected) && !isIgnoredTarget(directory, walk.expected, walk.input)) {
+            yield { ...matchCase, path: directory };
+        }
+        return;
+    }
+    const listing = visit(walk, directory);
+    if (!listing)
+        return;
+    if (step.kind === "literal") {
+        const entry = findListedEntry(listing, step.value);
+        if (entry) {
+            yield* walkMatches(walk, path.join(directory, entry.name), index + 1, bindings, {
+                caseDiffers: matchCase.caseDiffers || entry.name !== step.value,
+                ambiguous: matchCase.ambiguous || entry.ambiguous,
+            });
+        }
+    }
+    else {
+        const matchName = (0, placeholders_1.createSegmentMatcher)(step, bindings);
+        for (const name of wildcardNames(listing)) {
+            const bound = matchName(name);
+            if (bound)
+                yield* walkMatches(walk, path.join(directory, name), index + 1, bound, matchCase);
+        }
+    }
+}
+/**
+ * The walk's steps: the candidate base's segments as literals, then the compiled reference, with
+ * `.`, `..`, and empty segments applied lexically exactly as `path.resolve` would.
+ */
+const wildcardSteps = (base, compiled) => {
+    const steps = segmentsBelow(path.parse(base).root, base).map(value => ({
+        kind: "literal",
+        value,
+    }));
+    for (const segment of compiled.segments) {
+        if (segment.kind === "literal" && (segment.value === "" || segment.value === "."))
+            continue;
+        if (segment.kind === "literal" && segment.value === "..") {
+            steps.pop();
+            continue;
+        }
+        steps.push(segment);
+    }
+    return steps;
+};
+/**
+ * Resolve a placeholder reference against one candidate base. A reference whose path as written
+ * matches an ignore glob (`{name}/app.zip`) is `ignored`, and so is one whose literal prefix before
+ * the first placeholder is an ignored location, as a literal reference there would be. Beyond it the walk never lists an ignored directory or `.git`,
+ * so matches only there count as none. The first case-exact match is `exact`; otherwise a match
+ * whose literal steps differ only in case is a `caseMismatch`. A match must be of the `expected`
+ * kind, exactly as for a literal reference. Hitting the visit cap is `ignored`.
+ */
+const lookupWildcard = (candidate, compiled, { expected, budget }, input) => {
+    if (isIgnoredTarget(candidate.path, expected, input))
+        return { kind: "ignored" };
+    const steps = wildcardSteps(candidate.base, compiled);
+    const root = path.parse(candidate.base).root;
+    const literalCount = steps.findIndex(step => step.kind !== "literal");
+    if (literalCount === -1)
+        return lookupLiteral(candidate, expected, input);
+    const prefixSegments = steps.slice(0, literalCount).flatMap(step => (step.kind === "literal" ? [step.value] : []));
+    const prefix = path.join(root, ...prefixSegments);
+    if (isIgnoredDirectory(prefix, input))
+        return { kind: "ignored" };
+    const start = isWithin(prefix, input.repoRoot) ? input.repoRoot : root;
+    const walk = { input, steps, expected, budget };
+    const matches = walkMatches(walk, start, segmentsBelow(root, start).length, new Map(), CASE_EXACT);
+    let caseMismatch;
+    for (const match of matches) {
+        if (!match.caseDiffers)
+            return { kind: "exact", path: match.path };
+        caseMismatch ?? (caseMismatch = match);
+    }
+    if (budget.exhausted)
+        return { kind: "ignored" };
+    return caseMismatch
+        ? { kind: "caseMismatch", actualPath: caseMismatch.path, ambiguous: caseMismatch.ambiguous }
+        : { kind: "missing" };
+};
+/**
+ * Resolve a reference to `exact`, `caseMismatch`, `ignored`, or `missing`. Candidates inside an
+ * ignored location are never looked up. Across candidates, an exact match wins, then an ignored
+ * candidate, then the first case mismatch. A reference with placeholders (under
+ * `input.placeholders`) matches wildcards against the tree; see `lookupWildcard`. An illustrative
+ * `path/to/` reference, or one with adjacent placeholders, is `ignored` without any lookup.
+ *
+ * The reference as written says what it names: a trailing `/` must resolve to a directory, a file
+ * extension to a file (so a directory named `foo.md` is `missing`), and anything else to either. An
+ * entry of the wrong kind is `missing`, even when its name differs only in case.
+ *
+ * Only the repository is looked at: a candidate outside `repoRoot` is `missing` whether or not it
+ * exists on this machine, and a leading `..` in a root-relative reference stays at the root, as on
+ * GitHub (`/../x` is `/x`).
+ */
+const resolveReference = (input) => {
+    const written = (0, exports.referenceTarget)(input.reference, input.referenceKind);
+    const target = written.startsWith("/") ? path.posix.normalize(written) : written;
+    const pathPart = target.replace(/^\/+/, "");
+    const expected = expectedKind(written);
+    if ((0, placeholders_1.isIllustrativeReference)(pathPart, input.placeholders)) {
+        return { kind: "ignored" };
+    }
+    const compiled = (0, placeholders_1.compileReference)(pathPart, input.placeholders);
+    if (compiled && (0, placeholders_1.hasAdjacentSlots)(compiled)) {
+        return { kind: "ignored" };
+    }
+    const budget = { remaining: input.maxVisitedDirectories ?? exports.MAX_VISITED_DIRECTORIES, exhausted: false };
+    let ignored = false;
+    let caseMismatch;
+    for (const candidate of candidatePaths(input, target)) {
+        if (!isWithin(candidate.path, input.repoRoot))
+            continue;
+        const lookup = compiled
+            ? lookupWildcard(candidate, compiled, { expected, budget }, input)
+            : lookupLiteral(candidate, expected, input);
+        if (lookup.kind === "ignored") {
+            ignored = true;
+            continue;
+        }
+        if (lookup.kind === "exact") {
+            return compiled ? { kind: "exact", path: lookup.path, placeholder: true } : { kind: "exact", path: lookup.path };
+        }
+        if (lookup.kind === "caseMismatch" && !caseMismatch) {
+            caseMismatch = {
+                kind: "caseMismatch",
+                path: candidate.path,
+                actualPath: lookup.actualPath,
+                base: candidate.base,
+                ambiguous: lookup.ambiguous,
+                placeholder: compiled !== undefined,
+            };
+        }
+    }
+    if (ignored) {
+        return { kind: "ignored" };
+    }
+    return caseMismatch ?? { kind: "missing" };
+};
+exports.resolveReference = resolveReference;
+//# sourceMappingURL=resolver.js.map

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

@@ -0,0 +1,163 @@
+import { z } from "zod";
+/**
+ * Configuration for the doc-references check, validated with zod so a bad config fails with a
+ * message naming the offending key. Every default-bearing list takes `{ extend: [...] }` (add to
+ * the defaults) or `{ replace: [...] }` (swap them out, `[]` empties). A bare array is rejected
+ * because it can't say which of the two the author meant.
+ */
+/** Conventional generated-output locations, matched against the repo-relative path. */
+export declare const DEFAULT_IGNORE: ReadonlyArray<string>;
+/** Which markdown constructs are checked: `links`, `images`, `definitions`, and `inlineCode` spans. */
+export interface ConstructToggles {
+    readonly links: boolean;
+    readonly images: boolean;
+    readonly definitions: boolean;
+    readonly inlineCode: boolean;
+}
+/**
+ * Links, images, and definitions are checked; inline code only on opt-in, since measured on manager
+ * about 96% of inline-code findings were false positives, mostly paths relative to an implied
+ * project root. A `constructs` setting overrides only the keys it names.
+ */
+export declare const DEFAULT_CONSTRUCTS: ConstructToggles;
+/** Provisional: whether extensionless references with a `/` (`libs/react/components/`) are checked. */
+export declare const DEFAULT_DIRECTORIES = false;
+/**
+ * Provisional: whether inline code without a `/` (`` `README.md` ``) is checked. Link, image, and
+ * definition URLs without a `/` (`[x](README.md)`) are always checked; see `classify.ts`.
+ */
+export declare const DEFAULT_BARE_FILENAMES = false;
+/**
+ * A strict object whose unknown keys are reported as `unknown <noun> 'key'; expected <valid keys>`,
+ * and whose wrong type as `expected <expected>`.
+ */
+export declare const strictObjectNamingKeys: <TShape extends z.ZodRawShape>(shape: TShape, { noun, expected }: {
+    readonly noun: string;
+    readonly expected: string;
+}) => z.ZodObject<TShape, "strict">;
+/** The `docReferences` section of `repo-checks.config.json`, as written. */
+export declare const docReferencesConfigSchema: z.ZodObject<{
+    rootDir: z.ZodOptional<z.ZodString>;
+    ignore: z.ZodOptional<z.ZodEffects<z.ZodObject<{
+        extend: z.ZodOptional<z.ZodArray<z.ZodType<string, z.ZodTypeDef, string>, "many">>;
+        replace: z.ZodOptional<z.ZodArray<z.ZodType<string, z.ZodTypeDef, string>, "many">>;
+    }, "strict", z.ZodTypeAny, {
+        extend?: string[] | undefined;
+        replace?: string[] | undefined;
+    }, {
+        extend?: string[] | undefined;
+        replace?: string[] | undefined;
+    }>, {
+        extend?: string[] | undefined;
+        replace?: string[] | undefined;
+    }, {
+        extend?: string[] | undefined;
+        replace?: string[] | undefined;
+    }>>;
+    exclude: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>;
+    placeholders: z.ZodOptional<z.ZodEffects<z.ZodObject<{
+        extend: z.ZodOptional<z.ZodArray<z.ZodType<string, z.ZodTypeDef, string>, "many">>;
+        replace: z.ZodOptional<z.ZodArray<z.ZodType<string, z.ZodTypeDef, string>, "many">>;
+    }, "strict", z.ZodTypeAny, {
+        extend?: string[] | undefined;
+        replace?: string[] | undefined;
+    }, {
+        extend?: string[] | undefined;
+        replace?: string[] | undefined;
+    }>, {
+        extend?: string[] | undefined;
+        replace?: string[] | undefined;
+    }, {
+        extend?: string[] | undefined;
+        replace?: string[] | undefined;
+    }>>;
+    constructs: z.ZodOptional<z.ZodObject<{
+        links: z.ZodOptional<z.ZodBoolean>;
+        images: z.ZodOptional<z.ZodBoolean>;
+        definitions: z.ZodOptional<z.ZodBoolean>;
+        inlineCode: z.ZodOptional<z.ZodBoolean>;
+    }, "strict", z.ZodTypeAny, {
+        inlineCode?: boolean | undefined;
+        links?: boolean | undefined;
+        images?: boolean | undefined;
+        definitions?: boolean | undefined;
+    }, {
+        inlineCode?: boolean | undefined;
+        links?: boolean | undefined;
+        images?: boolean | undefined;
+        definitions?: boolean | undefined;
+    }>>;
+    directories: z.ZodOptional<z.ZodBoolean>;
+    bareFilenames: z.ZodOptional<z.ZodBoolean>;
+}, "strict", z.ZodTypeAny, {
+    rootDir?: string | undefined;
+    ignore?: {
+        extend?: string[] | undefined;
+        replace?: string[] | undefined;
+    } | undefined;
+    exclude?: string[] | undefined;
+    placeholders?: {
+        extend?: string[] | undefined;
+        replace?: string[] | undefined;
+    } | undefined;
+    constructs?: {
+        inlineCode?: boolean | undefined;
+        links?: boolean | undefined;
+        images?: boolean | undefined;
+        definitions?: boolean | undefined;
+    } | undefined;
+    directories?: boolean | undefined;
+    bareFilenames?: boolean | undefined;
+}, {
+    rootDir?: string | undefined;
+    ignore?: {
+        extend?: string[] | undefined;
+        replace?: string[] | undefined;
+    } | undefined;
+    exclude?: string[] | undefined;
+    placeholders?: {
+        extend?: string[] | undefined;
+        replace?: string[] | undefined;
+    } | undefined;
+    constructs?: {
+        inlineCode?: boolean | undefined;
+        links?: boolean | undefined;
+        images?: boolean | undefined;
+        definitions?: boolean | undefined;
+    } | undefined;
+    directories?: boolean | undefined;
+    bareFilenames?: boolean | undefined;
+}>;
+export type DocReferencesConfig = z.infer<typeof docReferencesConfigSchema>;
+/** Every issue as `path: message`, `;`-separated, with `(root)` for the top level. */
+export declare const formatConfigIssues: (error: z.ZodError) => string;
+export interface DocsSettings {
+    /** Repository root override. When unset, the nearest `.git` above the checked document is used. */
+    readonly rootDir: string | undefined;
+    /** Picomatch globs, matched against the repo-relative path, whose references are never reported. */
+    readonly ignore: ReadonlyArray<string>;
+    /**
+     * Picomatch globs, matched against the repo-relative path, of documents never read or checked.
+     * They stay valid targets: references to them, and anchors into them, are checked as usual. It has
+     * no defaults (discovery already skips gitignored files), so it is a plain list, not `{ extend }`
+     * or `{ replace }`.
+     */
+    readonly exclude: ReadonlyArray<string>;
+    /** Placeholder conventions (see `placeholders.ts`) that make a reference a wildcard pattern. */
+    readonly placeholders: ReadonlyArray<string>;
+    /** Which markdown constructs are checked. */
+    readonly constructs: ConstructToggles;
+    /** Check extensionless references with a `/` as file-or-directory references (see `classify.ts`). */
+    readonly directories: boolean;
+    /** Check inline code without a `/`, such as `` `README.md` `` (see `classify.ts`). */
+    readonly bareFilenames: boolean;
+}
+/** The resolved settings when no config is given. */
+export declare const DEFAULT_DOCS_SETTINGS: DocsSettings;
+/**
+ * Validate a raw doc-references config and resolve it onto the defaults. `undefined` yields
+ * {@link DEFAULT_DOCS_SETTINGS}.
+ *
+ * @throws {ConfigError} naming every offending key, when the config is invalid
+ */
+export declare const parseDocsSettings: (raw: unknown) => DocsSettings;