@trackunit/repo-checks 0.0.0-stage → 0.0.3

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;

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