@trackunit/repo-checks 0.0.0-stage → 0.0.2

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

@@ -0,0 +1,72 @@
+/** A 1-based source location, as mdast reports it. */
+export interface MarkdownPoint {
+    readonly line: number;
+    readonly column: number;
+    readonly offset?: number;
+}
+/**
+ * The structural subset of an mdast node the doc-reference checks read. Declared here rather than
+ * imported from `mdast` so the library doesn't depend on the parser's type packages.
+ */
+export interface MarkdownNode {
+    readonly type: string;
+    /** Text content: `code`, `inlineCode`, `yaml`, `html`, `text`, and similar leaves. */
+    readonly value?: string;
+    /** Destination of `link`, `image`, and `definition`. */
+    readonly url?: string;
+    readonly children?: ReadonlyArray<MarkdownNode>;
+    readonly position?: {
+        readonly start: MarkdownPoint;
+        readonly end: MarkdownPoint;
+    };
+    /** The label as written, on `footnoteDefinition` and `footnoteReference` (and other reference nodes). */
+    readonly label?: string | null;
+    /** The normalised label, on the same nodes as `label`. */
+    readonly identifier?: string;
+    /** An MDX JSX element's name (`div`, `Meta`, `Docs.Block`), or `null` for a fragment. */
+    readonly name?: string | null;
+    /** On MDX JSX elements only. */
+    readonly attributes?: ReadonlyArray<{
+        readonly type: string;
+        readonly name?: string;
+        readonly value?: unknown;
+    }>;
+    /** On MDX ESM and `{expression}` nodes: the program the parser built from `value`. */
+    readonly data?: {
+        readonly estree?: {
+            readonly body: ReadonlyArray<unknown>;
+        } | null;
+    };
+}
+/**
+ * Whether `node` is an MDX `{expression}` holding no code, only comments if anything (`{/* note *\/}`,
+ * `{// note}`), so it renders nothing; its source text, comments included, is its `value`. Decided
+ * from the program the parser built, so `{/* a *\/ x /* b *\/}` is code; an expression without one is.
+ */
+export declare const isCommentExpression: (node: MarkdownNode) => boolean;
+/** A document that could not be parsed, located at the 1-based line and column the parser stopped at. */
+export declare class DocumentParseError extends Error {
+    readonly file: string;
+    readonly line: number;
+    readonly column: number;
+    readonly reason: string;
+    /**
+     * @param file The document, as it was passed to the parser.
+     * @param line 1-based line the parser stopped at.
+     * @param column 1-based column the parser stopped at.
+     * @param reason The parser's message.
+     */
+    constructor(file: string, line: number, column: number, reason: string);
+}
+/** Whether `file` is parsed as MDX: its extension is `.mdx`, in any case. */
+export declare const isMdxFile: (file: string) => boolean;
+/**
+ * Parse a markdown document into mdast with GFM and YAML frontmatter, the way every document this
+ * library checks is read: a leading `---` block becomes a `yaml` node rather than content, while `+++` fences stay plain
+ * markdown, as on GitHub. A `.mdx` `file` is parsed with the MDX extensions too, as Storybook's MDX 3
+ * compiler reads it: ESM becomes `mdxjsEsm`, JSX `mdxJsxFlowElement`/`mdxJsxTextElement` (markdown in
+ * their children stays mdast; attributes are not children), and `{expressions}`, comments included,
+ * `mdxFlowExpression`/`mdxTextExpression` leaves. Plain markdown always parses; invalid MDX throws a
+ * {@link DocumentParseError} naming `file` and the location.
+ */
+export declare const parseMarkdown: (source: string, file: string) => MarkdownNode;

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

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseMarkdown = exports.isMdxFile = exports.DocumentParseError = exports.isCommentExpression = void 0;
+const mdast_util_from_markdown_1 = require("mdast-util-from-markdown");
+const mdast_util_frontmatter_1 = require("mdast-util-frontmatter");
+const mdast_util_gfm_1 = require("mdast-util-gfm");
+const mdast_util_mdx_1 = require("mdast-util-mdx");
+const micromark_extension_frontmatter_1 = require("micromark-extension-frontmatter");
+const micromark_extension_gfm_1 = require("micromark-extension-gfm");
+const micromark_extension_mdxjs_1 = require("micromark-extension-mdxjs");
+const MDX_EXPRESSION_TYPES = new Set(["mdxFlowExpression", "mdxTextExpression"]);
+/**
+ * Whether `node` is an MDX `{expression}` holding no code, only comments if anything (`{/* note *\/}`,
+ * `{// note}`), so it renders nothing; its source text, comments included, is its `value`. Decided
+ * from the program the parser built, so `{/* a *\/ x /* b *\/}` is code; an expression without one is.
+ */
+const isCommentExpression = (node) => MDX_EXPRESSION_TYPES.has(node.type) && node.data?.estree?.body.length === 0;
+exports.isCommentExpression = isCommentExpression;
+/** A document that could not be parsed, located at the 1-based line and column the parser stopped at. */
+class DocumentParseError extends Error {
+    /**
+     * @param file The document, as it was passed to the parser.
+     * @param line 1-based line the parser stopped at.
+     * @param column 1-based column the parser stopped at.
+     * @param reason The parser's message.
+     */
+    constructor(file, line, column, reason) {
+        super(`${file}:${line}:${column}: ${reason}`);
+        this.file = file;
+        this.line = line;
+        this.column = column;
+        this.reason = reason;
+        this.name = "DocumentParseError";
+    }
+}
+exports.DocumentParseError = DocumentParseError;
+const positiveInteger = (value) => typeof value === "number" && Number.isInteger(value) && value > 0 ? value : undefined;
+const toParseError = (error, file) => {
+    const message = typeof error === "object" && error !== null ? error : {};
+    const reason = typeof message.reason === "string"
+        ? message.reason
+        : typeof message.message === "string"
+            ? message.message
+            : String(error);
+    return new DocumentParseError(file, positiveInteger(message.line) ?? 1, positiveInteger(message.column) ?? 1, reason);
+};
+/** Whether `file` is parsed as MDX: its extension is `.mdx`, in any case. */
+const isMdxFile = (file) => file.toLowerCase().endsWith(".mdx");
+exports.isMdxFile = isMdxFile;
+/**
+ * Parse a markdown document into mdast with GFM and YAML frontmatter, the way every document this
+ * library checks is read: a leading `---` block becomes a `yaml` node rather than content, while `+++` fences stay plain
+ * markdown, as on GitHub. A `.mdx` `file` is parsed with the MDX extensions too, as Storybook's MDX 3
+ * compiler reads it: ESM becomes `mdxjsEsm`, JSX `mdxJsxFlowElement`/`mdxJsxTextElement` (markdown in
+ * their children stays mdast; attributes are not children), and `{expressions}`, comments included,
+ * `mdxFlowExpression`/`mdxTextExpression` leaves. Plain markdown always parses; invalid MDX throws a
+ * {@link DocumentParseError} naming `file` and the location.
+ */
+const parseMarkdown = (source, file) => {
+    const mdx = (0, exports.isMdxFile)(file);
+    try {
+        return (0, mdast_util_from_markdown_1.fromMarkdown)(source, {
+            extensions: [(0, micromark_extension_gfm_1.gfm)(), (0, micromark_extension_frontmatter_1.frontmatter)(["yaml"]), ...(mdx ? [(0, micromark_extension_mdxjs_1.mdxjs)()] : [])],
+            mdastExtensions: [(0, mdast_util_gfm_1.gfmFromMarkdown)(), (0, mdast_util_frontmatter_1.frontmatterFromMarkdown)(["yaml"]), ...(mdx ? [(0, mdast_util_mdx_1.mdxFromMarkdown)()] : [])],
+        });
+    }
+    catch (error) {
+        throw toParseError(error, file);
+    }
+};
+exports.parseMarkdown = parseMarkdown;
+//# sourceMappingURL=parse.js.map

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

@@ -0,0 +1,74 @@
+/**
+ * Placeholder conventions in documented paths, such as `docs/<skill>/SKILL.md`.
+ *
+ * A reference's path part is compiled segment by segment (split on `/`). A segment without a
+ * placeholder is `literal`; one with placeholders is a `pattern` of text and named slots. Each slot
+ * matches one or more characters of a single directory entry name, so it never matches across `/`
+ * and never matches the empty string. Slots with the same name, in any segment and from any
+ * convention, must bind to the same value. Text beside a slot (`eval-` in `eval-<skill>`) is matched
+ * case-exactly, so a case difference there reads as no match rather than a case mismatch.
+ *
+ * Named conventions:
+ *   - `angle`: `<name>`.
+ *   - `curly`: `{name}`, but not a brace pair that is part of `{{name}}`.
+ *   - `double-curly`: `{{name}}`.
+ *   - `colon`: `:name` (a letter or `_`, then word characters), only at the start of a segment, so
+ *     `/:id/` and `:id.md` are placeholders but `app:build` is literal.
+ *   - `path-to`: a leading `path/to/` (after any `./`) followed by at least one segment marks the
+ *     whole reference as illustrative, so it is never checked (see `isIllustrativeReference`).
+ *
+ * Any other string is a custom regex, applied within a segment, whose single capture group is the
+ * placeholder name, e.g. `\[(\w+)\]` for `[slug]`. Where conventions overlap at a position, the
+ * longest match wins. `*` is not a placeholder: globs are skipped before resolution.
+ */
+export declare const NAMED_PLACEHOLDERS: readonly ["angle", "curly", "double-curly", "colon", "path-to"];
+export type NamedPlaceholder = (typeof NAMED_PLACEHOLDERS)[number];
+/** Every named convention; a single constant so measurement can narrow the defaults in one place. */
+export declare const DEFAULT_PLACEHOLDERS: ReadonlyArray<string>;
+export type PatternPart = {
+    readonly kind: "text";
+    readonly value: string;
+} | {
+    readonly kind: "slot";
+    readonly name: string;
+};
+export type SegmentPattern = {
+    readonly kind: "literal";
+    readonly value: string;
+} | {
+    readonly kind: "pattern";
+    readonly parts: ReadonlyArray<PatternPart>;
+};
+export interface CompiledReference {
+    readonly segments: ReadonlyArray<SegmentPattern>;
+}
+/** Placeholder name to the entry-name substring it matched. */
+export type Bindings = ReadonlyMap<string, string>;
+/** The number of capture groups in a regex source, or `undefined` when it doesn't compile. */
+export declare const countCaptureGroups: (source: string) => number | undefined;
+/**
+ * Whether `pathPart` starts with `path/to/` (after any `./`) and names something below it, with
+ * `path-to` enabled. Such a reference stands for "some file in your project", not a real path.
+ */
+export declare const isIllustrativeReference: (pathPart: string, conventions: ReadonlyArray<string>) => boolean;
+/**
+ * Compile a reference's path part (fragment stripped, URL-decoded, leading `/` removed) into
+ * per-segment matchers. Returns `undefined` when it has no placeholder under `conventions`, so the
+ * literal resolution applies unchanged. `.`, `..`, and empty segments stay literal; the resolver
+ * applies them lexically.
+ */
+export declare const compileReference: (pathPart: string, conventions: ReadonlyArray<string>) => CompiledReference | undefined;
+/**
+ * Whether some segment has two placeholders with no text between them (`<a><b>.md`). Such a split
+ * is arbitrary and its regex backtracks polynomially on names that don't match, so it is skipped.
+ */
+export declare const hasAdjacentSlots: ({ segments }: CompiledReference) => boolean;
+/**
+ * A matcher for one directory entry name against `segment`, given the names bound by earlier
+ * segments. It returns the extended bindings, or `undefined` when the name doesn't match. Already
+ * bound names must reappear verbatim. When a segment has several unbound slots, only the regex
+ * engine's first split is tried (e.g. `<a>-<b>` on `x-y-z` binds `a=x-y`).
+ */
+export declare const createSegmentMatcher: (segment: Extract<SegmentPattern, {
+    kind: "pattern";
+}>, bindings: Bindings) => ((name: string) => Bindings | undefined);

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

@@ -0,0 +1,176 @@
+"use strict";
+/**
+ * Placeholder conventions in documented paths, such as `docs/<skill>/SKILL.md`.
+ *
+ * A reference's path part is compiled segment by segment (split on `/`). A segment without a
+ * placeholder is `literal`; one with placeholders is a `pattern` of text and named slots. Each slot
+ * matches one or more characters of a single directory entry name, so it never matches across `/`
+ * and never matches the empty string. Slots with the same name, in any segment and from any
+ * convention, must bind to the same value. Text beside a slot (`eval-` in `eval-<skill>`) is matched
+ * case-exactly, so a case difference there reads as no match rather than a case mismatch.
+ *
+ * Named conventions:
+ *   - `angle`: `<name>`.
+ *   - `curly`: `{name}`, but not a brace pair that is part of `{{name}}`.
+ *   - `double-curly`: `{{name}}`.
+ *   - `colon`: `:name` (a letter or `_`, then word characters), only at the start of a segment, so
+ *     `/:id/` and `:id.md` are placeholders but `app:build` is literal.
+ *   - `path-to`: a leading `path/to/` (after any `./`) followed by at least one segment marks the
+ *     whole reference as illustrative, so it is never checked (see `isIllustrativeReference`).
+ *
+ * Any other string is a custom regex, applied within a segment, whose single capture group is the
+ * placeholder name, e.g. `\[(\w+)\]` for `[slug]`. Where conventions overlap at a position, the
+ * longest match wins. `*` is not a placeholder: globs are skipped before resolution.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSegmentMatcher = exports.hasAdjacentSlots = exports.compileReference = exports.isIllustrativeReference = exports.countCaptureGroups = exports.DEFAULT_PLACEHOLDERS = exports.NAMED_PLACEHOLDERS = void 0;
+exports.NAMED_PLACEHOLDERS = ["angle", "curly", "double-curly", "colon", "path-to"];
+/** Every named convention; a single constant so measurement can narrow the defaults in one place. */
+exports.DEFAULT_PLACEHOLDERS = exports.NAMED_PLACEHOLDERS;
+/** `path-to` marks a whole reference, so it has no in-segment token. */
+const NAMED_TOKEN_SOURCES = {
+    angle: "<([^<>]+)>",
+    curly: "(?<!\\{)\\{([^{}]+)\\}(?!\\})",
+    "double-curly": "\\{\\{([^{}]+)\\}\\}",
+    colon: ":([A-Za-z_]\\w*)",
+    "path-to": undefined,
+};
+const isNamedPlaceholder = (convention) => exports.NAMED_PLACEHOLDERS.some(named => named === convention);
+/** The number of capture groups in a regex source, or `undefined` when it doesn't compile. */
+const countCaptureGroups = (source) => {
+    try {
+        return (new RegExp(`${source}|`).exec("")?.length ?? 1) - 1;
+    }
+    catch {
+        return undefined;
+    }
+};
+exports.countCaptureGroups = countCaptureGroups;
+const scannerFor = (convention) => {
+    const source = isNamedPlaceholder(convention) ? NAMED_TOKEN_SOURCES[convention] : convention;
+    return source === undefined
+        ? undefined
+        : { regex: new RegExp(source, "y"), segmentStartOnly: convention === "colon" };
+};
+const compiledScanners = new WeakMap();
+const scannersFor = (conventions) => {
+    let scanners = compiledScanners.get(conventions);
+    if (!scanners) {
+        scanners = conventions.flatMap(convention => scannerFor(convention) ?? []);
+        compiledScanners.set(conventions, scanners);
+    }
+    return scanners;
+};
+/** The longest placeholder token starting at `index`, if any. */
+const tokenAt = (segment, index, scanners) => {
+    let best;
+    for (const { regex, segmentStartOnly } of scanners) {
+        if (segmentStartOnly && index !== 0)
+            continue;
+        regex.lastIndex = index;
+        const match = regex.exec(segment);
+        const name = match?.[1];
+        if (match && name && match[0].length > (best?.length ?? 0)) {
+            best = { length: match[0].length, name };
+        }
+    }
+    return best;
+};
+const compileSegment = (segment, scanners) => {
+    const parts = [];
+    let text = "";
+    let index = 0;
+    while (index < segment.length) {
+        const token = tokenAt(segment, index, scanners);
+        if (token) {
+            if (text !== "")
+                parts.push({ kind: "text", value: text });
+            text = "";
+            parts.push({ kind: "slot", name: token.name });
+            index += token.length;
+        }
+        else {
+            text += segment[index];
+            index++;
+        }
+    }
+    if (!parts.some(part => part.kind === "slot")) {
+        return { kind: "literal", value: segment };
+    }
+    if (text !== "")
+        parts.push({ kind: "text", value: text });
+    return { kind: "pattern", parts };
+};
+/**
+ * Whether `pathPart` starts with `path/to/` (after any `./`) and names something below it, with
+ * `path-to` enabled. Such a reference stands for "some file in your project", not a real path.
+ */
+const isIllustrativeReference = (pathPart, conventions) => {
+    if (!conventions.includes("path-to"))
+        return false;
+    const segments = pathPart.split("/");
+    let start = 0;
+    while (segments[start] === ".")
+        start++;
+    return segments[start] === "path" && segments[start + 1] === "to" && segments.slice(start + 2).join("/") !== "";
+};
+exports.isIllustrativeReference = isIllustrativeReference;
+/**
+ * Compile a reference's path part (fragment stripped, URL-decoded, leading `/` removed) into
+ * per-segment matchers. Returns `undefined` when it has no placeholder under `conventions`, so the
+ * literal resolution applies unchanged. `.`, `..`, and empty segments stay literal; the resolver
+ * applies them lexically.
+ */
+const compileReference = (pathPart, conventions) => {
+    const scanners = scannersFor(conventions);
+    const segments = pathPart.split("/").map(segment => compileSegment(segment, scanners));
+    return segments.some(segment => segment.kind !== "literal") ? { segments } : undefined;
+};
+exports.compileReference = compileReference;
+/**
+ * Whether some segment has two placeholders with no text between them (`<a><b>.md`). Such a split
+ * is arbitrary and its regex backtracks polynomially on names that don't match, so it is skipped.
+ */
+const hasAdjacentSlots = ({ segments }) => segments.some(segment => segment.kind === "pattern" &&
+    segment.parts.some((part, index) => part.kind === "slot" && segment.parts[index + 1]?.kind === "slot"));
+exports.hasAdjacentSlots = hasAdjacentSlots;
+const escapeRegExp = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+/**
+ * A matcher for one directory entry name against `segment`, given the names bound by earlier
+ * segments. It returns the extended bindings, or `undefined` when the name doesn't match. Already
+ * bound names must reappear verbatim. When a segment has several unbound slots, only the regex
+ * engine's first split is tried (e.g. `<a>-<b>` on `x-y-z` binds `a=x-y`).
+ */
+const createSegmentMatcher = (segment, bindings) => {
+    const groups = new Map();
+    const source = segment.parts
+        .map(part => {
+        if (part.kind === "text")
+            return escapeRegExp(part.value);
+        const bound = bindings.get(part.name);
+        if (bound !== undefined)
+            return escapeRegExp(bound);
+        const group = groups.get(part.name);
+        if (group !== undefined)
+            return `\\k<${group}>`;
+        const newGroup = `p${groups.size}`;
+        groups.set(part.name, newGroup);
+        return `(?<${newGroup}>[^/]+)`;
+    })
+        .join("");
+    const regex = new RegExp(`^${source}$`);
+    return name => {
+        const match = regex.exec(name);
+        if (!match)
+            return undefined;
+        const next = new Map(bindings);
+        for (const [placeholder, group] of groups) {
+            const value = match.groups?.[group];
+            if (value !== undefined)
+                next.set(placeholder, value);
+        }
+        return next;
+    };
+};
+exports.createSegmentMatcher = createSegmentMatcher;
+//# sourceMappingURL=placeholders.js.map

package/src/lib/doc-references/repo-root.d.ts

@@ -0,0 +1,18 @@
+export interface RepoRootOptions {
+    /** Explicit repository root; a relative value resolves against `cwd`. */
+    readonly rootDir?: string;
+    /** Working directory a relative `rootDir` resolves against. Defaults to `process.cwd()`. */
+    readonly cwd?: string;
+}
+/**
+ * Find the repository root for a directory: `rootDir` when configured, otherwise `startDir` or its
+ * nearest ancestor containing a `.git` directory or a `.git` file (a git worktree or submodule).
+ * Returns `undefined` when no repository encloses `startDir`.
+ */
+export declare const findRepoRootFromDir: (startDir: string, { rootDir, cwd }?: RepoRootOptions) => string | undefined;
+/**
+ * Find the repository root for a checked document, as {@link findRepoRootFromDir} does from the
+ * document's directory. Walks up from the document rather than from `process.cwd()`, so checking
+ * from a subdirectory or a worktree resolves the same root.
+ */
+export declare const findRepoRoot: (documentPath: string, options?: RepoRootOptions) => string | undefined;

package/src/lib/doc-references/repo-root.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findRepoRoot = exports.findRepoRootFromDir = void 0;
+const tslib_1 = require("tslib");
+const fs = tslib_1.__importStar(require("fs"));
+const path = tslib_1.__importStar(require("path"));
+/**
+ * Find the repository root for a directory: `rootDir` when configured, otherwise `startDir` or its
+ * nearest ancestor containing a `.git` directory or a `.git` file (a git worktree or submodule).
+ * Returns `undefined` when no repository encloses `startDir`.
+ */
+const findRepoRootFromDir = (startDir, { rootDir, cwd } = {}) => {
+    if (rootDir !== undefined) {
+        return path.resolve(cwd ?? process.cwd(), rootDir);
+    }
+    let directory = path.resolve(startDir);
+    for (;;) {
+        if (fs.existsSync(path.join(directory, ".git"))) {
+            return directory;
+        }
+        const parent = path.dirname(directory);
+        if (parent === directory) {
+            return undefined;
+        }
+        directory = parent;
+    }
+};
+exports.findRepoRootFromDir = findRepoRootFromDir;
+/**
+ * Find the repository root for a checked document, as {@link findRepoRootFromDir} does from the
+ * document's directory. Walks up from the document rather than from `process.cwd()`, so checking
+ * from a subdirectory or a worktree resolves the same root.
+ */
+const findRepoRoot = (documentPath, options = {}) => (0, exports.findRepoRootFromDir)(path.dirname(path.resolve(documentPath)), options);
+exports.findRepoRoot = findRepoRoot;
+//# sourceMappingURL=repo-root.js.map

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

@@ -0,0 +1,96 @@
+/**
+ * Case-exact resolution of markdown file references.
+ *
+ * Existence is decided by listing directories and comparing names exactly, never with
+ * `fs.existsSync`, which is case-insensitive on macOS. A reference that only matches
+ * case-insensitively is a `caseMismatch` on every host, so macOS and Linux CI agree on case.
+ *
+ * Existence is checked against the working tree, not the git index. A gitignored or uncommitted
+ * file counts as present, so a checkout that has one (e.g. generated by a setup script) can pass
+ * where a fresh CI checkout reports it missing, and a link to a new file passes before it is staged.
+ */
+export type ReferenceKind = "url" | "inline";
+export type Resolution = {
+    readonly kind: "exact";
+    readonly path: string;
+    /** Set when the reference has placeholders, so `path` is one arbitrary match of it. */
+    readonly placeholder?: true;
+} | {
+    readonly kind: "caseMismatch";
+    readonly path: string;
+    readonly actualPath: string;
+    /** The directory the reference's path was resolved against: the document's directory or the repo root. */
+    readonly base: string;
+    /** A recased segment had several siblings matching it case-insensitively, so `actualPath` is one guess of several. */
+    readonly ambiguous: boolean;
+    /** The reference has placeholders, so `actualPath` is one instance of it rather than its corrected form. */
+    readonly placeholder: boolean;
+} | {
+    readonly kind: "ignored";
+} | {
+    readonly kind: "missing";
+};
+export interface ResolveInput {
+    /** The reference as written: a link/image/definition URL or an inline-code span. */
+    readonly reference: string;
+    /** URLs resolve against the document (or the repo root with a leading `/`); inline code also tries the repo root. */
+    readonly referenceKind: ReferenceKind;
+    readonly documentDir: string;
+    readonly repoRoot: string;
+    /** Picomatch globs matched against the repo-relative path. */
+    readonly ignore: ReadonlyArray<string>;
+    /** Placeholder conventions that turn the reference into a wildcard pattern (see `placeholders.ts`). */
+    readonly placeholders: ReadonlyArray<string>;
+    /** Directory listings one placeholder reference may make before it is skipped. */
+    readonly maxVisitedDirectories?: number;
+}
+/**
+ * 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).
+ */
+export declare const RACY_WINDOW_MS = 2000;
+/**
+ * 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.
+ */
+export declare const canonicalCase: (absolutePath: string) => string;
+/** Whether a repo-relative path (either separator) matches any of the ignore globs. */
+export declare const isIgnoredPath: (repoRelativePath: string, ignore: ReadonlyArray<string>) => boolean;
+export interface SplitReference {
+    /** The reference as written up to its suffix, still percent-encoded for URLs. */
+    readonly pathPart: string;
+    /** Everything from the first `?` (URLs only) or `#` on, e.g. `?plain=1#L3`; `""` when there is none. */
+    readonly suffix: string;
+}
+/**
+ * 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.
+ */
+export declare const splitReference: (reference: string, referenceKind: ReferenceKind) => SplitReference;
+/** A reference's `#fragment` without the `#`, still percent-encoded for URLs; `""` when there is none. */
+export declare const referenceFragment: (reference: string) => string;
+/** Whether a reference target ends in a file extension. One ending in `/` never does. */
+export declare const hasFileExtension: (target: string) => boolean;
+/** The path a reference names: its path part (see `splitReference`), percent-decoded for URLs. */
+export declare const referenceTarget: (reference: string, referenceKind: ReferenceKind) => string;
+/** Hard cap on directory listings per placeholder reference; hitting it skips the reference. */
+export declare const MAX_VISITED_DIRECTORIES = 10000;
+/**
+ * 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`).
+ */
+export declare const resolveReference: (input: ResolveInput) => Resolution;