@trackunit/repo-checks 0.0.0-stage → 0.0.2

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

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.classifyReference = void 0;
+const resolver_1 = require("./resolver");
+const settings_1 = require("./settings");
+/**
+ * A registry host (has a dot, or is `localhost`, optionally with a port), a repository path, and a
+ * `:tag` or `@sha256:` digest, e.g. `ghcr.io/org/img:1.2` or `123.dkr.ecr.eu-west-1.amazonaws.com/app:latest`.
+ * Checked before the URL-scheme test because `localhost:5000/...` would otherwise read as a scheme.
+ */
+const REGISTRY_IMAGE_RE = /^(?:[a-z0-9-]+(?:\.[a-z0-9-]+)+|localhost)(?::\d+)?\/[^\s:@]+(?::\w[\w.-]*|@sha256:[a-f0-9]+)$/i;
+const URL_SCHEME_RE = /^[a-z][a-z0-9+.-]*:/i;
+const STORYBOOK_PATH_QUERY_RE = /[?&]path=/u;
+const DEFAULT_OPTIONS = { directories: settings_1.DEFAULT_DIRECTORIES, bareFilenames: settings_1.DEFAULT_BARE_FILENAMES };
+const skip = (reason) => ({ check: false, reason });
+const isCheckedShape = (base, referenceKind, { directories, bareFilenames }) => {
+    const hasExtension = (0, resolver_1.hasFileExtension)(base);
+    if (base.includes("/"))
+        return hasExtension || directories;
+    // A bare *named* file (has an extension, e.g. `README.md`) in a URL (link/image/definition) is
+    // unambiguously a relative path, so it is always checked. The same shape in inline code is often
+    // a package name or a version (`eslint@9`, `v1.2`), so it stays gated by `bareFilenames` there.
+    // An extensionless bare word (`README`) is ambiguous either way and keeps needing both
+    // `bareFilenames` and `directories`.
+    if (referenceKind === "url" && hasExtension)
+        return true;
+    return bareFilenames && (hasExtension || directories);
+};
+/**
+ * Whether a reference is checked as a repo path, or the reason it is skipped: empty, anchor-only,
+ * URL-, shell- or glob-shaped, a registry image, a Storybook path, or not shaped like a file path.
+ */
+const classifyReference = (reference, referenceKind, options = DEFAULT_OPTIONS) => {
+    if (!reference)
+        return skip("empty");
+    if (reference.startsWith("#"))
+        return skip("anchorOnly");
+    if (/\s/.test(reference))
+        return skip("multiWord");
+    if (REGISTRY_IMAGE_RE.test(reference))
+        return skip("registryImage");
+    // `//host/path` is a protocol-relative URL, not a repo-root path.
+    if (URL_SCHEME_RE.test(reference) || reference.startsWith("//"))
+        return skip("urlScheme");
+    if (reference.startsWith("~"))
+        return skip("homePath");
+    if (reference.includes("$"))
+        return skip("shellVariable");
+    if (reference.includes("*"))
+        return skip("glob");
+    // A Storybook link (`?path=/docs/...`) addresses a page of the running Storybook, whatever path precedes it.
+    if (STORYBOOK_PATH_QUERY_RE.test(reference))
+        return skip("storybookPath");
+    if (!isCheckedShape((0, resolver_1.referenceTarget)(reference, referenceKind), referenceKind, options))
+        return skip("notAFilePath");
+    return { check: true };
+};
+exports.classifyReference = classifyReference;
+//# sourceMappingURL=classify.js.map

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

@@ -0,0 +1,6 @@
+/**
+ * Every `.md` and `.mdx` document (extension in any case) under `rootDir`, as sorted absolute paths. Inside a git work tree
+ * these are git's tracked and untracked, non-ignored files that exist on disk; outside one, a
+ * filesystem walk that skips `.git` and conventional generated output.
+ */
+export declare const discoverDocuments: (rootDir: string) => Array<string>;

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

@@ -0,0 +1,84 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.discoverDocuments = void 0;
+const tslib_1 = require("tslib");
+const child_process_1 = require("child_process");
+const fs = tslib_1.__importStar(require("fs"));
+const path = tslib_1.__importStar(require("path"));
+const fs_errors_1 = require("./fs-errors");
+/** Document extensions discovered and checked, in any case (`.MD`), as `parseMarkdown` and the anchor check read them. */
+const DOCUMENT_PATHSPECS = [":(icase)*.md", ":(icase)*.mdx"];
+/** Directories the filesystem walk never enters: VCS metadata and conventional generated output. */
+const WALK_SKIPPED_DIRECTORIES = new Set([".git", "node_modules", "dist", "build", "coverage"]);
+/** Set by git hooks; inherited, they would point `git ls-files` at the hook's repository instead of `rootDir`'s. */
+const GIT_LOCATION_VARIABLES = new Set(["GIT_DIR", "GIT_WORK_TREE", "GIT_INDEX_FILE"]);
+const isDocument = (name) => /\.mdx?$/iu.test(name);
+/**
+ * Tracked and untracked, non-ignored documents under `rootDir`, as absolute paths, or `undefined`
+ * when `rootDir` is not inside a git work tree (or git is unavailable).
+ */
+const listWithGit = (rootDir) => {
+    const env = Object.fromEntries(Object.entries(process.env).filter(([name]) => !GIT_LOCATION_VARIABLES.has(name)));
+    const result = (0, child_process_1.spawnSync)("git", ["ls-files", "-z", "--cached", "--others", "--exclude-standard", "--", ...DOCUMENT_PATHSPECS], { cwd: rootDir, encoding: "utf8", maxBuffer: 256 * 1024 * 1024, env: { ...env, LC_ALL: "C", LANGUAGE: "C" } });
+    if (result.error) {
+        if ("code" in result.error && result.error.code === "ENOENT")
+            return undefined;
+        throw new fs_errors_1.ReadError(`Failed to list documents with git in ${rootDir}: ${result.error.message}`);
+    }
+    if (result.status !== 0) {
+        if (/not a git repository/i.test(result.stderr))
+            return undefined;
+        throw new fs_errors_1.ReadError(`git ls-files failed in ${rootDir}: ${result.stderr.trim()}`);
+    }
+    const files = new Set(result.stdout.split("\0").filter(file => file !== ""));
+    return [...files].map(file => path.join(rootDir, file));
+};
+const readDirectory = (directory) => {
+    try {
+        return fs.readdirSync(directory, { withFileTypes: true });
+    }
+    catch (error) {
+        throw new fs_errors_1.ReadError(`Cannot read directory ${directory}: ${(0, fs_errors_1.errorMessage)(error)}`);
+    }
+};
+const walk = (directory, documents) => {
+    for (const entry of readDirectory(directory)) {
+        const entryPath = path.join(directory, entry.name);
+        if (entry.isDirectory()) {
+            if (!WALK_SKIPPED_DIRECTORIES.has(entry.name))
+                walk(entryPath, documents);
+        }
+        else if (isDocument(entry.name)) {
+            documents.push(entryPath);
+        }
+    }
+};
+/**
+ * Whether `file` is a regular file on disk; `git ls-files --cached` still lists tracked files deleted from the work tree.
+ *
+ * @throws {ReadError} when `file` can't be stat'ed for any reason other than not existing
+ */
+const existsAsFile = (file) => {
+    try {
+        return fs.statSync(file).isFile();
+    }
+    catch (error) {
+        if ((0, fs_errors_1.isNotFoundError)(error))
+            return false;
+        throw new fs_errors_1.ReadError(`Cannot read ${file}: ${(0, fs_errors_1.errorMessage)(error)}`);
+    }
+};
+/**
+ * Every `.md` and `.mdx` document (extension in any case) under `rootDir`, as sorted absolute paths. Inside a git work tree
+ * these are git's tracked and untracked, non-ignored files that exist on disk; outside one, a
+ * filesystem walk that skips `.git` and conventional generated output.
+ */
+const discoverDocuments = (rootDir) => {
+    const listed = listWithGit(rootDir);
+    const documents = listed ?? [];
+    if (listed === undefined)
+        walk(rootDir, documents);
+    return documents.filter(existsAsFile).sort();
+};
+exports.discoverDocuments = discoverDocuments;
+//# sourceMappingURL=discover.js.map

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

@@ -0,0 +1,29 @@
+import type { MarkdownNode } from "./parse";
+import type { ReferenceKind } from "./resolver";
+import type { DocsSettings } from "./settings";
+/** The markdown construct a reference was written in; the keys of {@link ConstructToggles}, singular. */
+export type ReferenceConstruct = "link" | "image" | "definition" | "inlineCode";
+/** A reference as written in a document, before it is classified or resolved. */
+export interface ExtractedReference {
+    readonly kind: ReferenceConstruct;
+    /** The link, image, or definition URL as the parser decoded it, or the inline-code span's text. */
+    readonly target: string;
+    /** 1-based line of the construct's start. */
+    readonly line: number;
+    /** 1-based column of the construct's start. */
+    readonly column: number;
+}
+/** The resolver's reading of a construct: inline code is resolved as a bare path, everything else as a URL. */
+export declare const referenceKindOf: (construct: ReferenceConstruct) => ReferenceKind;
+/**
+ * Every reference in `tree` whose construct `settings.constructs` enables, in document order.
+ * Code blocks (fenced or indented) and frontmatter are leaves, so nothing inside them is extracted;
+ * so are MDX ESM and `{expressions}`, and a JSX element's attributes aren't children, so only the
+ * markdown in its children is.
+ * A link reference (`[x][r]`) is reported through its definition only, so each target is reported
+ * once. Autolinks and GFM literal URLs are links like any other; deciding which targets to check is
+ * the caller's job (see `classify.ts`).
+ * References starting on the line after an ignore-next-line comment are dropped (see
+ * `suppressions.ts`); a link reference's is decided on its definition's line.
+ */
+export declare const extractReferences: (tree: MarkdownNode, settings: Pick<DocsSettings, "constructs">) => Array<ExtractedReference>;

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

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractReferences = exports.referenceKindOf = void 0;
+const suppressions_1 = require("./suppressions");
+const CONSTRUCT_TOGGLE = {
+    link: "links",
+    image: "images",
+    definition: "definitions",
+    inlineCode: "inlineCode",
+};
+const isReferenceConstruct = (type) => Object.hasOwn(CONSTRUCT_TOGGLE, type);
+/** The resolver's reading of a construct: inline code is resolved as a bare path, everything else as a URL. */
+const referenceKindOf = (construct) => construct === "inlineCode" ? "inline" : "url";
+exports.referenceKindOf = referenceKindOf;
+/**
+ * Every reference in `tree` whose construct `settings.constructs` enables, in document order.
+ * Code blocks (fenced or indented) and frontmatter are leaves, so nothing inside them is extracted;
+ * so are MDX ESM and `{expressions}`, and a JSX element's attributes aren't children, so only the
+ * markdown in its children is.
+ * A link reference (`[x][r]`) is reported through its definition only, so each target is reported
+ * once. Autolinks and GFM literal URLs are links like any other; deciding which targets to check is
+ * the caller's job (see `classify.ts`).
+ * References starting on the line after an ignore-next-line comment are dropped (see
+ * `suppressions.ts`); a link reference's is decided on its definition's line.
+ */
+const extractReferences = (tree, settings) => {
+    const references = [];
+    const ignoredLines = new Set();
+    const visit = (node) => {
+        const ignoredLine = (0, suppressions_1.ignoredNextLine)(node);
+        if (ignoredLine !== undefined)
+            ignoredLines.add(ignoredLine);
+        if (isReferenceConstruct(node.type) && settings.constructs[CONSTRUCT_TOGGLE[node.type]]) {
+            const target = node.type === "inlineCode" ? node.value : node.url;
+            if (target !== undefined) {
+                const start = node.position?.start;
+                references.push({ kind: node.type, target, line: start?.line ?? 1, column: start?.column ?? 1 });
+            }
+        }
+        node.children?.forEach(visit);
+    };
+    visit(tree);
+    return references.filter(reference => !ignoredLines.has(reference.line));
+};
+exports.extractReferences = extractReferences;
+//# sourceMappingURL=extract.js.map

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

@@ -0,0 +1,24 @@
+import type { ReferenceConstruct } from "./extract";
+/**
+ * Why a reference was reported: its target doesn't exist on disk (`missing`), exists only under
+ * different letter case (`caseMismatch`), or exists but its `#fragment` names no heading or anchor
+ * in it (`missingAnchor`).
+ */
+export type FindingReason = "missing" | "caseMismatch" | "missingAnchor";
+/** One reported doc reference. */
+export interface Finding {
+    /** The document, as a POSIX path relative to the repository root. */
+    readonly file: string;
+    /** 1-based line of the reference's construct. */
+    readonly line: number;
+    /** 1-based column of the reference's construct. */
+    readonly column: number;
+    /** The reference as the parser read it: a link, image, or definition URL, or an inline-code span. */
+    readonly target: string;
+    readonly kind: ReferenceConstruct;
+    readonly reason: FindingReason;
+    /** A replacement for `target` that would resolve, when exactly one is known: the on-disk casing of a `caseMismatch`. */
+    readonly suggestion?: string;
+}
+/** Order findings by file, then line, then column, so output is the same on every host. */
+export declare const compareFindings: (a: Finding, b: Finding) => number;

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

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.compareFindings = void 0;
+/** Order findings by file, then line, then column, so output is the same on every host. */
+const compareFindings = (a, b) => {
+    if (a.file !== b.file)
+        return a.file < b.file ? -1 : 1;
+    return a.line - b.line || a.column - b.column;
+};
+exports.compareFindings = compareFindings;
+//# sourceMappingURL=finding.js.map

package/src/lib/doc-references/fs-errors.d.ts

@@ -0,0 +1,14 @@
+/** Whether a filesystem error means the path doesn't exist, as opposed to existing but being unreadable. */
+export declare const isNotFoundError: (error: unknown) => boolean;
+/** Whether `error` is a Node system error (`EACCES`, `ELOOP`, ...) from a failed system call. */
+export declare const isSystemError: (error: unknown) => boolean;
+/** An error's message, or the thrown value as a string when it isn't an `Error`. */
+export declare const errorMessage: (error: unknown) => string;
+/**
+ * A document, directory, or git's document listing that couldn't be read: the environment, not the
+ * documents or the config, stopped the check.
+ */
+export declare class ReadError extends Error {
+    /** @param message What couldn't be read, and why. */
+    constructor(message: string);
+}

package/src/lib/doc-references/fs-errors.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ReadError = exports.errorMessage = exports.isSystemError = exports.isNotFoundError = void 0;
+/** Whether a filesystem error means the path doesn't exist, as opposed to existing but being unreadable. */
+const isNotFoundError = (error) => error instanceof Error && "code" in error && (error.code === "ENOENT" || error.code === "ENOTDIR");
+exports.isNotFoundError = isNotFoundError;
+/** Whether `error` is a Node system error (`EACCES`, `ELOOP`, ...) from a failed system call. */
+const isSystemError = (error) => error instanceof Error && "code" in error && typeof error.code === "string" && "syscall" in error;
+exports.isSystemError = isSystemError;
+/** An error's message, or the thrown value as a string when it isn't an `Error`. */
+const errorMessage = (error) => (error instanceof Error ? error.message : String(error));
+exports.errorMessage = errorMessage;
+/**
+ * A document, directory, or git's document listing that couldn't be read: the environment, not the
+ * documents or the config, stopped the check.
+ */
+class ReadError extends Error {
+    /** @param message What couldn't be read, and why. */
+    constructor(message) {
+        super(message);
+        this.name = "ReadError";
+    }
+}
+exports.ReadError = ReadError;
+//# sourceMappingURL=fs-errors.js.map

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

@@ -0,0 +1,79 @@
+import { type MarkdownNode } from "./parse";
+/**
+ * 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.
+ */
+export declare const MAX_ANCHOR_DOCUMENT_BYTES: number;
+/**
+ * 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.
+ */
+export declare const documentAnchors: (root: MarkdownNode) => Set<string>;
+/**
+ * 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.
+ */
+export declare const knownDocumentAnchors: (root: MarkdownNode, file: string) => Set<string> | 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.
+ */
+export declare const readDocumentAnchors: (absolutePath: string) => ReadonlySet<string> | undefined;
+/**
+ * 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`).
+ */
+export declare const hasAnchor: (anchors: ReadonlySet<string>, fragment: string) => boolean;

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