@trackunit/repo-checks 0.0.0-stage → 0.0.3

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

@@ -0,0 +1,219 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hasAnchor = exports.readDocumentAnchors = exports.knownDocumentAnchors = exports.documentAnchors = exports.MAX_ANCHOR_DOCUMENT_BYTES = void 0;
+const tslib_1 = require("tslib");
+const fs = tslib_1.__importStar(require("fs"));
+const github_slugger_1 = tslib_1.__importDefault(require("github-slugger"));
+const parse_1 = require("./parse");
+const resolver_1 = require("./resolver");
+/**
+ * The fragment ids a markdown document defines: upstream's anchors plus GitHub's. Upstream's are
+ * those `@eslint/markdown`'s `no-missing-link-fragments` computes for in-document `#anchor` links,
+ * so every fragment that passes there passes here too. GitHub's only add anchors, so they can only
+ * remove false positives.
+ *
+ * The document is parsed with GFM and YAML frontmatter, as `parseMarkdown` parses it (so a
+ * leading `---` block never yields a heading, while `+++` fences are plain markdown, as on GitHub),
+ * and one `github-slugger` per document slugs, in document order:
+ *   - every heading (ATX or setext): the concatenated `value` of its non-HTML descendants, so
+ *     inline code, emphasis, and link text count while image alt text and inline HTML don't; a
+ *     trailing custom `{#id}` replaces the text;
+ *   - in every HTML node, outside `<!-- comments -->`: each `id=`/`name=` attribute value, and the
+ *     tag-stripped text of each `<h1>`-`<h6>` element.
+ * The slugger suffixes repeats (`setup`, `setup-1`, ...) across all of these, and `top` is always
+ * defined. `.mdx` targets are parsed with the MDX extensions too (`parseMarkdown` decides by the
+ * file extension): ESM and `{expressions}` yield no headings, markdown inside JSX children does, and
+ * a JSX element's string `id`/`name` attribute counts like the HTML one. An `{expression}` inside a
+ * heading adds no text, as in the ids Storybook's `rehype-slug` gives the rendered heading, so
+ * `# Hi {name}` defines `hi-` (the space before the expression stays), not `hi` or `hi-name`. A
+ * target that is not valid MDX, has MDX whose rendering parsing can't see (`knownDocumentAnchors`),
+ * or is larger than `MAX_ANCHOR_DOCUMENT_BYTES`, has no known anchors.
+ *
+ * GitHub's anchors, on top of those:
+ *   - each explicit `id`/`name` value as written (lower-cased), since GitHub keeps `.` and `:`
+ *     (`v1.2.0`, `a:b`) that slugging drops;
+ *   - every markdown heading slugged by a second `github-slugger` of its own, over its full text
+ *     with emoji shortcodes removed: GitHub has no `{#id}` (`## Setup {#install}` is `setup-install`)
+ *     and renders `:rocket:` as an emoji the slug drops (`## :rocket: Deploy` is `-deploy`);
+ *   - footnote ids as GitHub renders them: `fn-<label>` per definition, and `fnref-<label>`,
+ *     `fnref-<label>-2`, ... per reference.
+ * `hasAnchor` also accepts each of these behind GitHub's `user-content-` prefix.
+ *
+ * `.mdx` documents get the same GFM and frontmatter reading, which deliberately differs from a
+ * Storybook build without those plugins: there `# Title[^1]` keeps `[^1]` as text (`title1`, not
+ * `title`), and a leading `---` block renders as a rule and a setext heading. So a `.mdx` document
+ * with frontmatter, or with a footnote reference inside a heading, has no known anchors
+ * (`knownDocumentAnchors`).
+ */
+/**
+ * Documents above this size are skipped rather than parsed: a 1.1 MB CHANGELOG took 2 s and 417 MB
+ * of heap. A skipped target has no known anchors, so it is never reported.
+ */
+exports.MAX_ANCHOR_DOCUMENT_BYTES = 1024 * 1024;
+const CUSTOM_HEADING_ID_RE = /\{#(?<id>[^}\s]+)\}\s*$/u;
+const HTML_HEADING_RE = /<h(?<depth>[1-6])[^>]*>(?<children>[\s\S]*?)<\/h\k<depth>\s*>/giu;
+const HTML_ID_NAME_RE = /(?<!<)<[^>]+\s(?:id|name)\s*=\s*["']?(?<id>[^"'\s>]+)["']?/giu;
+const HTML_TAG_RE = /<\/?[a-z0-9]+(?:-[a-z0-9]+)*(?:\s(?:[^>"']|"[^"]*"|'[^']*')*)?(?:\/\s*)?>/giu;
+const HTML_COMMENT_RE = /<!--[\s\S]*?-->/gu;
+const GITHUB_LINE_REFERENCE_RE = /^L\d+(?:C\d+)?(?:-L\d+(?:C\d+)?)?$/u;
+const EMOJI_SHORTCODE_RE = /:[a-z0-9_+-]+:/giu;
+const GITHUB_USER_CONTENT_PREFIX = "user-content-";
+const JSX_ELEMENT_TYPES = new Set(["mdxJsxFlowElement", "mdxJsxTextElement"]);
+/** The string `id`/`name` attribute values of a JSX element, the MDX counterpart of HTML's `id=`/`name=`. */
+const jsxAnchorAttributes = (node) => JSX_ELEMENT_TYPES.has(node.type)
+    ? (node.attributes ?? []).flatMap(attribute => attribute.type === "mdxJsxAttribute" &&
+        (attribute.name === "id" || attribute.name === "name") &&
+        typeof attribute.value === "string"
+        ? [attribute.value]
+        : [])
+    : [];
+const HEADING_TEXT_SKIPPED_TYPES = new Set(["html", "mdxTextExpression"]);
+const headingText = (node) => (node.children ?? [])
+    .map(child => (HEADING_TEXT_SKIPPED_TYPES.has(child.type) ? "" : (child.value ?? "") + headingText(child)))
+    .join("");
+/**
+ * The fragment ids an already-parsed document defines (see the module comment): upstream's anchors
+ * (every HTML node's, and every heading's once its own HTML is collected), plus GitHub's.
+ */
+const documentAnchors = (root) => {
+    const anchors = new Set(["top"]);
+    const slugger = new github_slugger_1.default();
+    const githubSlugger = new github_slugger_1.default();
+    const footnoteReferences = new Map();
+    const addExplicit = (id) => {
+        anchors.add(slugger.slug(id));
+        anchors.add(id.toLowerCase());
+    };
+    const visit = (node) => {
+        if (node.type === "html") {
+            const html = (node.value ?? "").replace(HTML_COMMENT_RE, "");
+            for (const match of html.matchAll(HTML_ID_NAME_RE))
+                addExplicit(match.groups?.id ?? "");
+            for (const match of html.matchAll(HTML_HEADING_RE)) {
+                anchors.add(slugger.slug((match.groups?.children ?? "").replace(HTML_TAG_RE, "")));
+            }
+        }
+        for (const id of jsxAnchorAttributes(node))
+            addExplicit(id);
+        const footnoteLabel = (node.label ?? node.identifier)?.toLowerCase();
+        if (footnoteLabel !== undefined && node.type === "footnoteDefinition")
+            anchors.add(`fn-${footnoteLabel}`);
+        if (footnoteLabel !== undefined && node.type === "footnoteReference") {
+            const count = (footnoteReferences.get(footnoteLabel) ?? 0) + 1;
+            footnoteReferences.set(footnoteLabel, count);
+            anchors.add(count === 1 ? `fnref-${footnoteLabel}` : `fnref-${footnoteLabel}-${count}`);
+        }
+        node.children?.forEach(visit);
+        if (node.type === "heading") {
+            const text = headingText(node);
+            anchors.add(slugger.slug(CUSTOM_HEADING_ID_RE.exec(text)?.groups?.id ?? text));
+            anchors.add(githubSlugger.slug(text.replace(EMOJI_SHORTCODE_RE, "")));
+        }
+    };
+    visit(root);
+    return anchors;
+};
+exports.documentAnchors = documentAnchors;
+const MDX_EXPRESSION_TYPES = new Set(["mdxFlowExpression", "mdxTextExpression"]);
+/**
+ * A built-in HTML element MDX renders as itself; anything else is a component (`Meta`,
+ * `Docs.Block`) or a custom element (`doc-toc`), either of which may render anything.
+ */
+const INTRINSIC_JSX_NAME_RE = /^[a-z][a-z0-9]*$/u;
+const JSX_HEADING_NAME_RE = /^h[1-6]$/u;
+/** A spread, or any `{expression}` value (`children={...}`, `dangerouslySetInnerHTML={...}`), may render anchors. */
+const isOpaqueJsxAttribute = (attribute) => attribute.type !== "mdxJsxAttribute" || (typeof attribute.value === "object" && attribute.value !== null);
+/** Whether `node` may render anchors, or headings with ids, that parsing the document can't see. */
+const isOpaqueMdxNode = (node) => {
+    if (node.type === "mdxjsEsm")
+        return true;
+    if (MDX_EXPRESSION_TYPES.has(node.type))
+        return !(0, parse_1.isCommentExpression)(node);
+    if (!JSX_ELEMENT_TYPES.has(node.type) || node.name === null || node.name === undefined)
+        return false;
+    return (!INTRINSIC_JSX_NAME_RE.test(node.name) ||
+        JSX_HEADING_NAME_RE.test(node.name) ||
+        (node.attributes ?? []).some(isOpaqueJsxAttribute));
+};
+const hasOpaqueMdx = (node) => isOpaqueMdxNode(node) || (node.children ?? []).some(hasOpaqueMdx);
+const hasFootnoteReference = (node) => node.type === "footnoteReference" || (node.children ?? []).some(hasFootnoteReference);
+/** GFM and frontmatter readings Storybook may not share (see the module comment), so an `.mdx`'s anchors there are unknown. */
+const hasStorybookReadingGap = (node) => node.type === "yaml" ||
+    (node.type === "heading" && hasFootnoteReference(node)) ||
+    (node.children ?? []).some(hasStorybookReadingGap);
+/**
+ * The fragment ids a parsed document defines, as `documentAnchors` computes them, or `undefined`
+ * when MDX in it may render anchors that parsing can't see, so a caller never reports a fragment
+ * that the rendered page might define. That is any ESM (an import brings in components or content,
+ * an `export default` wraps the page in a layout); any JSX element that is a component (`<Meta>`,
+ * Storybook's `<Title />` and `<Stories />`, `<Markdown>{...}</Markdown>`) or a custom element
+ * (`<doc-toc>`); a JSX `<h1>`-`<h6>`, whose rendered id may differ between renderers (GitHub,
+ * Storybook); a spread or any `{expression}` attribute value; and any `{expression}` holding code
+ * (see `isCommentExpression`), which covers a heading like `# Hi {name}`. In a `.mdx` `file`,
+ * frontmatter and a footnote reference inside a heading count too (see the module comment).
+ * Built-in HTML elements with string attributes and comment-only expressions are seen in full.
+ * Plain markdown has none of these nodes, and its frontmatter and footnotes read as on GitHub, so a
+ * `.md` document's anchors are always known.
+ */
+const knownDocumentAnchors = (root, file) => hasOpaqueMdx(root) || ((0, parse_1.isMdxFile)(file) && hasStorybookReadingGap(root)) ? undefined : (0, exports.documentAnchors)(root);
+exports.knownDocumentAnchors = knownDocumentAnchors;
+/** Per-process cache keyed by absolute path, so each target is parsed once per run; revalidated by mtime and size. */
+const documentCache = new Map();
+const parseAnchors = (absolutePath, text) => {
+    try {
+        return (0, exports.knownDocumentAnchors)((0, parse_1.parseMarkdown)(text, absolutePath), absolutePath);
+    }
+    catch {
+        return undefined;
+    }
+};
+/**
+ * The fragment ids `absolutePath` defines (see the module comment), or `undefined` when it can't be
+ * read or parsed, is larger than `MAX_ANCHOR_DOCUMENT_BYTES`, or has MDX whose rendered anchors
+ * can't be seen (see `knownDocumentAnchors`), so a caller never reports against a document it
+ * didn't fully inspect.
+ */
+const readDocumentAnchors = (absolutePath) => {
+    try {
+        const { mtimeMs, size } = fs.statSync(absolutePath);
+        if (size > exports.MAX_ANCHOR_DOCUMENT_BYTES) {
+            documentCache.delete(absolutePath);
+            return undefined;
+        }
+        const cached = documentCache.get(absolutePath);
+        if (cached?.mtimeMs === mtimeMs && cached.size === size && cached.readAtMs - mtimeMs > resolver_1.RACY_WINDOW_MS) {
+            return cached.anchors;
+        }
+        const readAtMs = Date.now();
+        const anchors = parseAnchors(absolutePath, fs.readFileSync(absolutePath, "utf8"));
+        documentCache.set(absolutePath, { mtimeMs, size, readAtMs, anchors });
+        return anchors;
+    }
+    catch {
+        documentCache.delete(absolutePath);
+        return undefined;
+    }
+};
+exports.readDocumentAnchors = readDocumentAnchors;
+/**
+ * Whether a written fragment names one of `anchors`, compared as `no-missing-link-fragments` does by
+ * default: percent-decoded (a malformed escape as written) and case-insensitively. GitHub line
+ * references (`L10`, `L10C2-L12C5`) always match, and so does an anchor behind the `user-content-`
+ * prefix GitHub gives the ids it renders (`#user-content-setup`).
+ */
+const hasAnchor = (anchors, fragment) => {
+    let decoded = fragment;
+    try {
+        decoded = decodeURIComponent(fragment);
+    }
+    catch {
+        // checked as written
+    }
+    const lowerCase = decoded.toLowerCase();
+    return (GITHUB_LINE_REFERENCE_RE.test(decoded) ||
+        anchors.has(lowerCase) ||
+        (lowerCase.startsWith(GITHUB_USER_CONTENT_PREFIX) &&
+            anchors.has(lowerCase.slice(GITHUB_USER_CONTENT_PREFIX.length))));
+};
+exports.hasAnchor = hasAnchor;
+//# sourceMappingURL=headings.js.map

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;