@codefast/cli 0.10.0 → 0.12.0

package/dist/audit/{run-comments.d.ts → comments/run.d.ts}

@@ -1,7 +1,7 @@
-import type { CommentAuditResult } from "#/audit/domain/types";
-import { AppError } from "#/core/errors";
-import type { FilesystemPort } from "#/core/filesystem/port";
-import type { Result } from "#/core/result";
+import type { CommentAuditResult } from "#audit/domain/types";
+import { AppError } from "#core/errors";
+import type { Filesystem } from "#core/filesystem/filesystem";
+import type { Result } from "#core/result";
 /**
  * Reports every comment off the repo's conventions: divider form (which `fix` rewrites), banned
  * content — document pointers, JSDoc types, tag misuse — `{@link}` targets nothing declares, and
@@ -9,7 +9,7 @@ import type { Result } from "#/core/result";
  *
  * @since 0.6.0
  */
-export declare function runCommentAudit(fs: FilesystemPort, args: {
+export declare function runCommentAudit(fs: Filesystem, args: {
     readonly rootDir: string;
     readonly targetPath: string;
     readonly allowlist: ReadonlyArray<string>;

package/dist/audit/{run-comments.js → comments/run.js}

@@ -1,13 +1,13 @@
 import path from "node:path";
-import { scanCommentContent } from "#/audit/domain/comment-content";
-import { applyCommentDividerFixes, DIVIDER_COLUMN, scanCommentDividers } from "#/audit/domain/comment-dividers";
-import { countHeadMentions, isPathLinkTarget, linkTargetHead, scanLinkReferences, } from "#/audit/domain/link-references";
-import { scanImpossibleSinceTags } from "#/audit/domain/since-versions";
-import { scanTsdocSyntax } from "#/audit/domain/tsdoc-syntax";
-import { AppError, messageFrom } from "#/core/errors";
-import { err, ok } from "#/core/result";
-import { findNearestPackageVersion } from "#/core/workspace/package-version";
-import { sourceCommentLanguage, walkSourceFiles } from "#/core/workspace/source-walk";
+import { scanCommentContent } from "#audit/comments/domain/comment-content";
+import { applyCommentDividerFixes, DIVIDER_COLUMN, scanCommentDividers } from "#audit/comments/domain/comment-dividers";
+import { countHeadMentions, isPathLinkTarget, linkTargetHead, scanLinkReferences, } from "#audit/comments/domain/link-references";
+import { scanImpossibleSinceTags } from "#audit/comments/domain/since-versions";
+import { scanTsdocSyntax } from "#audit/comments/domain/tsdoc-syntax";
+import { AppError, messageFrom } from "#core/errors";
+import { err, ok } from "#core/result";
+import { findNearestPackageVersion } from "#core/workspace/package-version";
+import { sourceCommentLanguage, walkSourceFiles } from "#core/workspace/source-walk";
 const reasonByDefect = {
     "bad-width": `rule does not end at column ${DIVIDER_COLUMN}`,
     "dead-link": "{@link} target has no mention outside links — likely renamed",

package/dist/audit/display-names/cli-result.d.ts

@@ -0,0 +1,13 @@
+import type { DisplayNameAuditResult } from "#audit/domain/types";
+/**
+ * Exit `1` when any non-allowlisted display-name violation remains.
+ *
+ * @since 0.9.0
+ */
+export declare function exitCodeForDisplayNameAuditResult(result: DisplayNameAuditResult): number;
+/**
+ * Machine-readable display-name summary for `--json`.
+ *
+ * @since 0.9.0
+ */
+export declare function formatDisplayNameAuditJsonOutput(result: DisplayNameAuditResult, rootDir: string): string;

package/dist/audit/display-names/cli-result.js

@@ -0,0 +1,22 @@
+import { CLI_EXIT_GENERAL_ERROR, CLI_EXIT_SUCCESS } from "#core/exit-codes";
+/**
+ * Exit `1` when any non-allowlisted display-name violation remains.
+ *
+ * @since 0.9.0
+ */
+export function exitCodeForDisplayNameAuditResult(result) {
+    return result.violationCount > 0 ? CLI_EXIT_GENERAL_ERROR : CLI_EXIT_SUCCESS;
+}
+/**
+ * Machine-readable display-name summary for `--json`.
+ *
+ * @since 0.9.0
+ */
+export function formatDisplayNameAuditJsonOutput(result, rootDir) {
+    return JSON.stringify({
+        schemaVersion: 1,
+        ok: result.violationCount === 0,
+        cwd: rootDir,
+        result,
+    });
+}

package/dist/audit/display-names/cli-schema.d.ts

@@ -0,0 +1,18 @@
+import * as z from "zod";
+/**
+ * Resolved request for a single display-name audit run.
+ *
+ * @since 0.9.0
+ */
+export type DisplayNameAuditRunRequest = {
+    readonly rootDir: string;
+    readonly targetPath: string;
+    readonly allowlist?: ReadonlyArray<string> | undefined;
+    readonly json: boolean;
+};
+/**
+ * Zod schema for {@link DisplayNameAuditRunRequest}.
+ *
+ * @since 0.9.0
+ */
+export declare const displayNameAuditRunRequestSchema: z.ZodType<DisplayNameAuditRunRequest>;

package/dist/audit/display-names/cli-schema.js

@@ -0,0 +1,12 @@
+import * as z from "zod";
+/**
+ * Zod schema for {@link DisplayNameAuditRunRequest}.
+ *
+ * @since 0.9.0
+ */
+export const displayNameAuditRunRequestSchema = z.object({
+    rootDir: z.string().min(1),
+    targetPath: z.string().min(1),
+    allowlist: z.array(z.string()).optional(),
+    json: z.boolean(),
+});

package/dist/audit/{domain → display-names/domain}/display-names.d.ts

@@ -1,5 +1,5 @@
 /** The display-name convention: a name is spelled like the TS symbol it stands for, under its owner's namespace. */
-import type { DisplayNameViolation } from "#/audit/domain/types";
+import type { DisplayNameViolation } from "#audit/domain/types";
 /**
  * Scans one source or markdown text for `token()`, `tag()` and module display names that break the convention.
  *

package/dist/audit/display-names/output.d.ts

@@ -0,0 +1,7 @@
+import type { DisplayNameAuditResult } from "#audit/domain/types";
+/**
+ * Human-readable display-name report.
+ *
+ * @since 0.9.0
+ */
+export declare function presentDisplayNameAuditResult(result: DisplayNameAuditResult): void;

package/dist/audit/display-names/output.js

@@ -0,0 +1,21 @@
+import { logger } from "#core/logger";
+/**
+ * Human-readable display-name report.
+ *
+ * @since 0.9.0
+ */
+export function presentDisplayNameAuditResult(result) {
+    for (const file of result.files) {
+        logger.out(`\n${file.relativePath}`);
+        for (const { line, raw, reason } of file.violations) {
+            logger.out(`  ${line}: ${raw} → ${reason}`);
+        }
+    }
+    const allowlistSuffix = result.allowlistedCount > 0 ? ` (${result.allowlistedCount} allowlisted)` : "";
+    if (result.violationCount > 0) {
+        logger.out(`\n✖ ${result.violationCount} display name(s) off the convention${allowlistSuffix}`);
+    }
+    else {
+        logger.out(`✓ Every token, tag and module display name follows <namespace>:<Name> across ${result.scannedFileCount} file(s)${allowlistSuffix}`);
+    }
+}

package/dist/audit/display-names/prepare.d.ts

@@ -0,0 +1,16 @@
+import type { AuditCommandPrelude } from "#audit/prepare";
+import type { AppError } from "#core/errors";
+import type { Filesystem } from "#core/filesystem/filesystem";
+import type { Result } from "#core/result";
+/**
+ * Loads config and resolves the scan target for `audit display-names`.
+ *
+ * @remarks Defaults to the repo root: a display name collides across packages, so the convention
+ * has to hold across them.
+ *
+ * @since 0.9.0
+ */
+export declare function prepareDisplayNameAudit(fs: Filesystem, args: {
+    readonly currentWorkingDirectory: string;
+    readonly rawTarget: string | undefined;
+}): Promise<Result<AuditCommandPrelude, AppError>>;

package/dist/audit/display-names/prepare.js

@@ -0,0 +1,12 @@
+import { prepareRepoRootAudit } from "#audit/prepare";
+/**
+ * Loads config and resolves the scan target for `audit display-names`.
+ *
+ * @remarks Defaults to the repo root: a display name collides across packages, so the convention
+ * has to hold across them.
+ *
+ * @since 0.9.0
+ */
+export async function prepareDisplayNameAudit(fs, args) {
+    return prepareRepoRootAudit(fs, args, (config) => config.audit?.displayNames?.allowlist ?? []);
+}

package/dist/audit/display-names/run.d.ts

@@ -0,0 +1,14 @@
+import type { DisplayNameAuditResult } from "#audit/domain/types";
+import { AppError } from "#core/errors";
+import type { Filesystem } from "#core/filesystem/filesystem";
+import type { Result } from "#core/result";
+/**
+ * Scans a target path for `token()`, `tag()` and module display names that break the convention.
+ *
+ * @since 0.9.0
+ */
+export declare function runDisplayNameAudit(fs: Filesystem, args: {
+    readonly rootDir: string;
+    readonly targetPath: string;
+    readonly allowlist: ReadonlyArray<string>;
+}): Result<DisplayNameAuditResult, AppError>;

package/dist/audit/{run-display-names.js → display-names/run.js}

@@ -1,9 +1,9 @@
 import path from "node:path";
-import { auditDisplayNames } from "#/audit/domain/display-names";
-import { AppError, messageFrom } from "#/core/errors";
-import { err, ok } from "#/core/result";
-import { walkMarkdownFiles } from "#/core/workspace/markdown-walk";
-import { walkTsxFiles } from "#/core/workspace/typescript-walk";
+import { auditDisplayNames } from "#audit/display-names/domain/display-names";
+import { AppError, messageFrom } from "#core/errors";
+import { err, ok } from "#core/result";
+import { walkMarkdownFiles } from "#core/workspace/markdown-walk";
+import { walkTsxFiles } from "#core/workspace/typescript-walk";
 /**
  * Trees the convention does not reach: a test or benchmark token is scoped by its file and never
  * meets another author's, and a changelog quotes names as they were.

package/dist/audit/domain/types.d.ts

@@ -168,4 +168,47 @@ export type CommentAuditResult = {
     readonly fixedCount: number;
     readonly dividerCount: number;
     readonly scannedFileCount: number;
+};
+/**
+ * A `#/`-prefixed internal import specifier — valid to the in-repo runners but rejected by Node's ESM
+ * resolver on the supported floor, so it breaks the published package.
+ *
+ * @since 0.12.0
+ */
+export type LegacySubpathImport = {
+    readonly line: number;
+    /** The specifier as written, quotes included. */
+    readonly raw: string;
+};
+/**
+ * The `#/` imports found in one source file.
+ *
+ * @since 0.12.0
+ */
+export type LegacySubpathFile = {
+    readonly relativePath: string;
+    readonly imports: Array<LegacySubpathImport>;
+};
+/**
+ * A published package whose slimmed manifest exports or imports a target it does not ship.
+ *
+ * @since 0.12.0
+ */
+export type UnshippedTargetViolation = {
+    readonly packageName: string;
+    readonly field: string;
+    readonly subpath: string;
+    readonly target: string;
+};
+/**
+ * Outcome of one `audit publish` run.
+ *
+ * @since 0.12.0
+ */
+export type PublishAuditResult = {
+    readonly legacyImportFiles: Array<LegacySubpathFile>;
+    readonly unshipped: Array<UnshippedTargetViolation>;
+    readonly legacyImportCount: number;
+    readonly scannedFileCount: number;
+    readonly packageCount: number;
 };

package/dist/audit/imports/cli-result.d.ts

@@ -0,0 +1,13 @@
+import type { ImportsAuditResult } from "#audit/domain/types";
+/**
+ * Exit `1` when any non-allowlisted import-policy violation remains.
+ *
+ * @since 0.10.0
+ */
+export declare function exitCodeForImportsAuditResult(result: ImportsAuditResult): number;
+/**
+ * Machine-readable import-policy summary for `--json`.
+ *
+ * @since 0.10.0
+ */
+export declare function formatImportsAuditJsonOutput(result: ImportsAuditResult, rootDir: string): string;

package/dist/audit/imports/cli-result.js

@@ -0,0 +1,22 @@
+import { CLI_EXIT_GENERAL_ERROR, CLI_EXIT_SUCCESS } from "#core/exit-codes";
+/**
+ * Exit `1` when any non-allowlisted import-policy violation remains.
+ *
+ * @since 0.10.0
+ */
+export function exitCodeForImportsAuditResult(result) {
+    return result.violationCount > 0 ? CLI_EXIT_GENERAL_ERROR : CLI_EXIT_SUCCESS;
+}
+/**
+ * Machine-readable import-policy summary for `--json`.
+ *
+ * @since 0.10.0
+ */
+export function formatImportsAuditJsonOutput(result, rootDir) {
+    return JSON.stringify({
+        schemaVersion: 1,
+        ok: result.violationCount === 0,
+        cwd: rootDir,
+        result,
+    });
+}

package/dist/audit/imports/cli-schema.d.ts

@@ -0,0 +1,18 @@
+import * as z from "zod";
+/**
+ * Resolved request for a single import-policy audit run.
+ *
+ * @since 0.10.0
+ */
+export type ImportsAuditRunRequest = {
+    readonly rootDir: string;
+    readonly targetPath: string;
+    readonly allowlist?: ReadonlyArray<string> | undefined;
+    readonly json: boolean;
+};
+/**
+ * Zod schema for {@link ImportsAuditRunRequest}.
+ *
+ * @since 0.10.0
+ */
+export declare const importsAuditRunRequestSchema: z.ZodType<ImportsAuditRunRequest>;

package/dist/audit/imports/cli-schema.js

@@ -0,0 +1,12 @@
+import * as z from "zod";
+/**
+ * Zod schema for {@link ImportsAuditRunRequest}.
+ *
+ * @since 0.10.0
+ */
+export const importsAuditRunRequestSchema = z.object({
+    rootDir: z.string().min(1),
+    targetPath: z.string().min(1),
+    allowlist: z.array(z.string()).optional(),
+    json: z.boolean(),
+});

package/dist/audit/{domain → imports/domain}/import-policy.d.ts

@@ -1,4 +1,4 @@
-import type { ImportPolicyViolation } from "#/audit/domain/types";
+import type { ImportPolicyViolation } from "#audit/domain/types";
 /**
  * One library's import policy: which forms of importing `module` are banned, optionally limited to
  * files whose repo-relative path matches `scope`, plus an optional UMD-global name to flag when the
@@ -16,8 +16,8 @@ export interface ImportPolicyRule {
 }
 /**
  * The import policies enforced across the monorepo: React members by name (never a namespace,
- * default, or implicit `React.*` UMD global), and Zod as a namespace in front-end packages so
- * bundlers can tree-shake it (a named `import { z }` pins Zod's full locale set into the bundle).
+ * default, or implicit `React.*` UMD global), and Zod as a namespace repo-wide — the house form,
+ * so a named `import { z }` never pins Zod's full locale set into a package that ships bundled.
  *
  * @since 0.10.0
  */

package/dist/audit/{domain → imports/domain}/import-policy.js

@@ -1,8 +1,8 @@
 import { parseSync } from "oxc-parser";
 /**
  * The import policies enforced across the monorepo: React members by name (never a namespace,
- * default, or implicit `React.*` UMD global), and Zod as a namespace in front-end packages so
- * bundlers can tree-shake it (a named `import { z }` pins Zod's full locale set into the bundle).
+ * default, or implicit `React.*` UMD global), and Zod as a namespace repo-wide — the house form,
+ * so a named `import { z }` never pins Zod's full locale set into a package that ships bundled.
  *
  * @since 0.10.0
  */
@@ -16,15 +16,8 @@ export const defaultImportPolicyRules = [
     {
         module: "zod",
         ban: ["named:z"],
-        scope: [
-            "packages/theme/**",
-            "packages/ui/**",
-            "packages/tailwind-variants/**",
-            "apps/web/**",
-            "examples/*/**",
-            "internal/benchmark-viewer/**",
-        ],
-        message: 'import Zod as a namespace so bundlers can tree-shake it: import * as z from "zod"',
+        message: 'import Zod as a namespace: import * as z from "zod" (repo house form; a named import { z } pins Zod\'s full ' +
+            "locale set into any bundle that reaches it)",
     },
 ];
 function isOxcNode(value) {

package/dist/audit/imports/output.d.ts

@@ -0,0 +1,7 @@
+import type { ImportsAuditResult } from "#audit/domain/types";
+/**
+ * Human-readable import-policy report.
+ *
+ * @since 0.10.0
+ */
+export declare function presentImportsAuditResult(result: ImportsAuditResult): void;

package/dist/audit/imports/output.js

@@ -0,0 +1,21 @@
+import { logger } from "#core/logger";
+/**
+ * Human-readable import-policy report.
+ *
+ * @since 0.10.0
+ */
+export function presentImportsAuditResult(result) {
+    for (const file of result.files) {
+        logger.out(`\n${file.relativePath}`);
+        for (const { line, raw, reason } of file.violations) {
+            logger.out(`  ${line}: ${raw} → ${reason}`);
+        }
+    }
+    const allowlistSuffix = result.allowlistedCount > 0 ? ` (${result.allowlistedCount} allowlisted)` : "";
+    if (result.violationCount > 0) {
+        logger.out(`\n✖ ${result.violationCount} import-policy violation(s)${allowlistSuffix}`);
+    }
+    else {
+        logger.out(`✓ No import-policy violations across ${result.scannedFileCount} file(s)${allowlistSuffix}`);
+    }
+}

package/dist/audit/imports/prepare.d.ts

@@ -0,0 +1,16 @@
+import type { AuditCommandPrelude } from "#audit/prepare";
+import type { AppError } from "#core/errors";
+import type { Filesystem } from "#core/filesystem/filesystem";
+import type { Result } from "#core/result";
+/**
+ * Loads config and resolves the scan target for `audit imports`.
+ *
+ * @remarks Defaults to the repo root: the import policy is repo-wide, and generated or vendored
+ * trees are already excluded by the shared walk.
+ *
+ * @since 0.10.0
+ */
+export declare function prepareImportsAudit(fs: Filesystem, args: {
+    readonly currentWorkingDirectory: string;
+    readonly rawTarget: string | undefined;
+}): Promise<Result<AuditCommandPrelude, AppError>>;

package/dist/audit/imports/prepare.js

@@ -0,0 +1,12 @@
+import { prepareRepoRootAudit } from "#audit/prepare";
+/**
+ * Loads config and resolves the scan target for `audit imports`.
+ *
+ * @remarks Defaults to the repo root: the import policy is repo-wide, and generated or vendored
+ * trees are already excluded by the shared walk.
+ *
+ * @since 0.10.0
+ */
+export async function prepareImportsAudit(fs, args) {
+    return prepareRepoRootAudit(fs, args, (config) => config.audit?.imports?.allowlist ?? []);
+}

package/dist/audit/imports/run.d.ts

@@ -0,0 +1,14 @@
+import type { ImportsAuditResult } from "#audit/domain/types";
+import { AppError } from "#core/errors";
+import type { Filesystem } from "#core/filesystem/filesystem";
+import type { Result } from "#core/result";
+/**
+ * Scans a target path for import-policy violations, applying each rule only to files in its scope.
+ *
+ * @since 0.10.0
+ */
+export declare function runImportsAudit(fs: Filesystem, args: {
+    readonly rootDir: string;
+    readonly targetPath: string;
+    readonly allowlist: ReadonlyArray<string>;
+}): Result<ImportsAuditResult, AppError>;

package/dist/audit/{run-imports.js → imports/run.js}

@@ -1,10 +1,10 @@
 import path from "node:path";
-import { defaultImportPolicyRules } from "#/audit/domain/import-policy";
-import { auditImportPolicySource } from "#/audit/domain/import-policy";
-import { AppError, messageFrom } from "#/core/errors";
-import { createAnyGlobMatcher } from "#/core/glob";
-import { err, ok } from "#/core/result";
-import { walkTsxFiles } from "#/core/workspace/typescript-walk";
+import { defaultImportPolicyRules } from "#audit/imports/domain/import-policy";
+import { auditImportPolicySource } from "#audit/imports/domain/import-policy";
+import { AppError, messageFrom } from "#core/errors";
+import { createAnyGlobMatcher } from "#core/glob";
+import { err, ok } from "#core/result";
+import { walkTsxFiles } from "#core/workspace/typescript-walk";
 /**
  * Scans a target path for import-policy violations, applying each rule only to files in its scope.
  *

package/dist/audit/links/cli-result.d.ts

@@ -0,0 +1,13 @@
+import type { LinkAuditResult } from "#audit/domain/types";
+/**
+ * Exit `1` when any non-allowlisted broken link remains.
+ *
+ * @since 0.5.0
+ */
+export declare function exitCodeForLinkAuditResult(result: LinkAuditResult): number;
+/**
+ * Machine-readable link audit summary for `--json`.
+ *
+ * @since 0.5.0
+ */
+export declare function formatLinkAuditJsonOutput(result: LinkAuditResult, rootDir: string): string;

package/dist/audit/links/cli-result.js

@@ -0,0 +1,22 @@
+import { CLI_EXIT_GENERAL_ERROR, CLI_EXIT_SUCCESS } from "#core/exit-codes";
+/**
+ * Exit `1` when any non-allowlisted broken link remains.
+ *
+ * @since 0.5.0
+ */
+export function exitCodeForLinkAuditResult(result) {
+    return result.breakageCount > 0 ? CLI_EXIT_GENERAL_ERROR : CLI_EXIT_SUCCESS;
+}
+/**
+ * Machine-readable link audit summary for `--json`.
+ *
+ * @since 0.5.0
+ */
+export function formatLinkAuditJsonOutput(result, rootDir) {
+    return JSON.stringify({
+        schemaVersion: 1,
+        ok: result.breakageCount === 0,
+        cwd: rootDir,
+        result,
+    });
+}

package/dist/audit/links/cli-schema.d.ts

@@ -0,0 +1,18 @@
+import * as z from "zod";
+/**
+ * Resolved request for a single link audit run.
+ *
+ * @since 0.5.0
+ */
+export type LinkAuditRunRequest = {
+    readonly rootDir: string;
+    readonly targetPath: string;
+    readonly allowlist?: ReadonlyArray<string> | undefined;
+    readonly json: boolean;
+};
+/**
+ * Zod schema for {@link LinkAuditRunRequest}.
+ *
+ * @since 0.5.0
+ */
+export declare const linkAuditRunRequestSchema: z.ZodType<LinkAuditRunRequest>;

package/dist/audit/links/cli-schema.js

@@ -0,0 +1,12 @@
+import * as z from "zod";
+/**
+ * Zod schema for {@link LinkAuditRunRequest}.
+ *
+ * @since 0.5.0
+ */
+export const linkAuditRunRequestSchema = z.object({
+    rootDir: z.string().min(1),
+    targetPath: z.string().min(1),
+    allowlist: z.array(z.string()).optional(),
+    json: z.boolean(),
+});

package/dist/audit/{domain → links/domain}/markdown-links.d.ts

@@ -25,9 +25,9 @@ export type MarkdownLinkScan = {
 /**
  * The anchor ids a rendered document exposes: explicit `<a id>` targets plus every heading's slug.
  *
- * @remarks Slugging matches GitHub's — lowercase, drop everything that is not a letter, number, space
- * or hyphen, then hyphenate spaces. Duplicate headings get a `-1` suffix there; this returns the base
- * only, so a link to the second copy reads as dangling rather than being silently accepted.
+ * @remarks Slugs follow GitHub's own algorithm so a link that resolves on GitHub resolves here.
+ * Repeated slugs take a `-1`, `-2`, … suffix in heading order, exactly as GitHub disambiguates them,
+ * so a link to the second copy of a heading resolves instead of reading as dangling.
  *
  * @since 0.5.0
  */

package/dist/audit/{domain → links/domain}/markdown-links.js

@@ -6,9 +6,9 @@ const EXTERNAL = /^(?:[a-z][a-z0-9+.-]*:|\/\/)/i;
 /**
  * The anchor ids a rendered document exposes: explicit `<a id>` targets plus every heading's slug.
  *
- * @remarks Slugging matches GitHub's — lowercase, drop everything that is not a letter, number, space
- * or hyphen, then hyphenate spaces. Duplicate headings get a `-1` suffix there; this returns the base
- * only, so a link to the second copy reads as dangling rather than being silently accepted.
+ * @remarks Slugs follow GitHub's own algorithm so a link that resolves on GitHub resolves here.
+ * Repeated slugs take a `-1`, `-2`, … suffix in heading order, exactly as GitHub disambiguates them,
+ * so a link to the second copy of a heading resolves instead of reading as dangling.
  *
  * @since 0.5.0
  */
@@ -17,15 +17,29 @@ export function collectMarkdownAnchors(content) {
     for (const match of content.matchAll(/<a\s+id="([^"]+)"\s*><\/a>/g)) {
         anchors.add(match[1]);
     }
+    const occurrences = new Map();
     for (const match of content.matchAll(/^#{1,6}\s+(.+?)\s*$/gm)) {
-        anchors.add(match[1]
-            .toLowerCase()
-            .replaceAll(/[^\p{L}\p{N} -]/gu, "")
-            .trim()
-            .replaceAll(/\s+/g, "-"));
+        const base = slugifyHeading(match[1]);
+        let result = base;
+        while (occurrences.has(result)) {
+            occurrences.set(base, (occurrences.get(base) ?? 0) + 1);
+            result = `${base}-${occurrences.get(base)}`;
+        }
+        occurrences.set(result, 0);
+        anchors.add(result);
     }
     return anchors;
 }
+/**
+ * A heading's GitHub slug: lowercased, stripped to letters, numbers, marks, underscore and hyphen,
+ * with each remaining space turned into a hyphen — runs are kept, not collapsed, matching GitHub.
+ */
+function slugifyHeading(heading) {
+    return heading
+        .toLowerCase()
+        .replaceAll(/[^\p{L}\p{N}\p{M} _-]/gu, "")
+        .replaceAll(" ", "-");
+}
 /**
  * Every repo-local link a document makes, with the anchors it offers.
  *

package/dist/audit/links/output.d.ts

@@ -0,0 +1,7 @@
+import type { LinkAuditResult } from "#audit/domain/types";
+/**
+ * Human-readable link audit report.
+ *
+ * @since 0.5.0
+ */
+export declare function presentLinkAuditResult(result: LinkAuditResult): void;