@takazudo/zudo-doc 0.2.21 → 1.0.0

package/dist/tag-pages/index.d.ts

@@ -0,0 +1,114 @@
+/** @jsxRuntime automatic */
+/** @jsxImportSource preact */
+import type { ComponentChildren, JSX } from "preact";
+/** Minimal docs entry shape needed by the tag-pages factory. */
+export interface TagPagesDocsEntry {
+    id: string;
+    data: {
+        slug?: string;
+        draft?: boolean;
+        unlisted?: boolean;
+        category_no_page?: boolean;
+        tags?: string[];
+        title: string;
+        description?: string;
+        [key: string]: unknown;
+    };
+}
+/** Tag info produced and consumed by the tag-pages factory. */
+export interface TagInfo {
+    tag: string;
+    count: number;
+    docs: {
+        slug: string;
+        title: string;
+        description?: string;
+    }[];
+}
+/** Settings subset read by the tag-pages factory. */
+export interface TagPagesSettings {
+    noindex?: boolean;
+    dynamicPageTransition?: boolean;
+    docTags?: boolean;
+    base: string;
+}
+/** Host-supplied component bindings injected into the tag-pages factory. */
+export interface TagPagesComponents {
+    HeadWithDefaults: (props: {
+        title: string;
+    }) => JSX.Element;
+    HeaderWithDefaults: (props: {
+        lang?: string;
+        currentPath?: string;
+    }) => JSX.Element;
+    FooterWithDefaults: (props: {
+        lang?: string;
+    }) => JSX.Element;
+    BodyEndIslands: (props: {
+        basePath: string;
+    }) => JSX.Element;
+    DocHistoryArea: (props: {
+        slug: string;
+        locale: string;
+    }) => JSX.Element | null;
+}
+/** Injected dependencies for {@link createTagPages}. */
+export interface TagPagesDeps {
+    settings: TagPagesSettings;
+    /** Default locale code (e.g. `"en"`). */
+    defaultLocale: string;
+    /** Translate a UI string key for a locale. */
+    t: (key: string, locale: string) => string;
+    /** Prefix a path with the configured base directory. */
+    withBase: (path: string) => string;
+    /** Build a docs URL for the given slug and lang. */
+    docsUrl: (slug: string, lang?: string) => string;
+    /** Compose the meta `<title>` value. */
+    composeMetaTitle: (title: string) => string;
+    /**
+     * Collect tags from a docs array, producing a Map<tag, TagInfo>.
+     * Host passes `collectTags` from `@/utils/tags`.
+     */
+    collectTags: (entries: TagPagesDocsEntry[], slugFn: (id: string, data: {
+        slug?: string;
+    }) => string) => Map<string, TagInfo>;
+    /**
+     * Identity-stable, draft-filtered docs array for a collection.
+     * Host passes `stableDocs` from `pages/lib/_nav-source-cache.ts`.
+     */
+    stableDocs: (collectionName: string) => TagPagesDocsEntry[];
+    /**
+     * Returns true for paths that are only shown in the default locale.
+     * Host passes `isDefaultLocaleOnlyPath` from `@/utils/base`.
+     */
+    isDefaultLocaleOnlyPath?: (path: string) => boolean;
+    components: TagPagesComponents;
+}
+/** Result of {@link createTagPages}. */
+export interface TagPagesAPI {
+    /**
+     * Build the { tag → TagInfo } map for one locale, preserving each original
+     * page's exact data path (see the module-header branch notes).
+     *
+     * Memoized on the snapshot-anchored stableDocs identity (same pattern as
+     * _nav-source-cache) so the collection bridging and tag aggregation run once
+     * per locale per build rather than once per built tag page.
+     */
+    collectTagMapForLocale: (locale: string) => Map<string, TagInfo>;
+    /** Per-tag detail page (chip target). */
+    TagDetailPageView: (props: {
+        locale: string;
+        tag: string;
+        tagInfo: TagInfo;
+    }) => JSX.Element;
+    /** "All Tags" index page — computes the tag map at render time. */
+    TagsIndexPageView: (props: {
+        locale: string;
+        children?: ComponentChildren;
+    }) => JSX.Element;
+}
+/**
+ * Create the tag-pages functions bound to the host's settings and
+ * component dependencies.
+ */
+export declare function createTagPages(deps: TagPagesDeps): TagPagesAPI;

package/dist/tag-pages/index.js

@@ -0,0 +1,146 @@
+import { Fragment, jsx, jsxs } from "preact/jsx-runtime";
+import { DocLayoutWithDefaults } from "../doclayout/index.js";
+import { Breadcrumb } from "../breadcrumb/index.js";
+import { DocCardGrid, TagNav } from "../nav-indexing/index.js";
+import { memoizeDerived } from "../nav-source-cache/index.js";
+import { mergeLocaleDocs } from "../locale-merge/index.js";
+import { toRouteSlug } from "../slug/index.js";
+function createTagPages(deps) {
+  const {
+    settings,
+    defaultLocale,
+    t,
+    withBase,
+    docsUrl,
+    composeMetaTitle,
+    collectTags,
+    stableDocs,
+    isDefaultLocaleOnlyPath,
+    components: {
+      HeadWithDefaults,
+      HeaderWithDefaults,
+      FooterWithDefaults,
+      BodyEndIslands,
+      DocHistoryArea
+    }
+  } = deps;
+  function localePrefix(locale) {
+    return locale === defaultLocale ? "" : `/${locale}`;
+  }
+  function collectTagMapForLocale(locale) {
+    if (locale === defaultLocale) {
+      const baseDocs2 = stableDocs("docs");
+      return memoizeDerived([baseDocs2], "tagMap;default", () => {
+        const docs = baseDocs2.filter(
+          (doc) => !doc.data.unlisted && !doc.data.draft && !doc.data.category_no_page
+        );
+        return collectTags(docs, (id, data) => data.slug ?? toRouteSlug(id));
+      });
+    }
+    const baseDocs = stableDocs("docs");
+    const localeDocs = stableDocs(`docs-${locale}`);
+    return memoizeDerived([baseDocs, localeDocs], `tagMap;${locale}`, () => {
+      const { docs: mergedDocs } = mergeLocaleDocs({
+        baseDocs: baseDocs.filter((d) => !d.data.draft),
+        localeDocs: localeDocs.filter((d) => !d.data.draft),
+        applyDefaultLocaleOnlyFilter: true,
+        isDefaultLocaleOnlyPath
+      });
+      const docs = mergedDocs.filter((d) => !d.data.category_no_page);
+      return collectTags(docs, (id, data) => data.slug ?? toRouteSlug(id));
+    });
+  }
+  function TagDetailPageView({
+    locale,
+    tag,
+    tagInfo
+  }) {
+    const isDefault = locale === defaultLocale;
+    const prefix = localePrefix(locale);
+    const countText = tagInfo.count === 1 ? t("doc.pageCountSingle", locale).replace("{count}", String(tagInfo.count)) : t("doc.pageCount", locale).replace("{count}", String(tagInfo.count));
+    const pageTitle = `${t("doc.taggedWith", locale)}: ${tag}`;
+    const breadcrumbItems = [
+      { label: "Docs" },
+      { label: t("doc.allTags", locale), href: withBase(`${prefix}/docs/tags`) },
+      { label: tag }
+    ];
+    const cardItems = tagInfo.docs.map((doc) => ({
+      href: docsUrl(doc.slug, locale),
+      title: doc.title,
+      description: doc.description
+    }));
+    return /* @__PURE__ */ jsxs(
+      DocLayoutWithDefaults,
+      {
+        title: composeMetaTitle(pageTitle),
+        head: /* @__PURE__ */ jsx(HeadWithDefaults, { title: pageTitle }),
+        lang: isDefault ? void 0 : locale,
+        noindex: settings.noindex,
+        hideSidebar: true,
+        hideToc: true,
+        sidebarOverride: /* @__PURE__ */ jsx(Fragment, {}),
+        headerOverride: /* @__PURE__ */ jsx(HeaderWithDefaults, { lang: locale, currentPath: withBase(`${prefix}/docs/tags/${encodeURIComponent(tag)}`) }),
+        breadcrumbOverride: /* @__PURE__ */ jsx(Breadcrumb, { items: breadcrumbItems }),
+        footerOverride: /* @__PURE__ */ jsx(FooterWithDefaults, { lang: locale }),
+        bodyEndComponents: /* @__PURE__ */ jsx(BodyEndIslands, { basePath: settings.base ?? "/" }),
+        enableClientRouter: settings.dynamicPageTransition,
+        children: [
+          /* @__PURE__ */ jsx("h1", { class: "text-heading font-bold mb-vsp-xs", children: pageTitle }),
+          /* @__PURE__ */ jsx("p", { class: "text-muted mb-vsp-lg", children: countText }),
+          /* @__PURE__ */ jsx(DocCardGrid, { ariaLabel: pageTitle, items: cardItems }),
+          /* @__PURE__ */ jsx(DocHistoryArea, { slug: `tags/${tag}`, locale })
+        ]
+      }
+    );
+  }
+  function TagsIndexPageView({ locale }) {
+    const isDefault = locale === defaultLocale;
+    const prefix = localePrefix(locale);
+    const pageTitle = t("doc.allTags", locale);
+    const tagMap = collectTagMapForLocale(locale);
+    const labels = {
+      tags: t("doc.tags", locale),
+      taggedWith: t("doc.taggedWith", locale)
+    };
+    const tags = [...tagMap.values()].sort((a, b) => a.tag.localeCompare(b.tag, locale)).map((info) => ({
+      tag: info.tag,
+      count: info.count,
+      // Tag segment URL-encoded — href sites only; route params stay raw.
+      href: withBase(`${prefix}/docs/tags/${encodeURIComponent(info.tag)}`)
+    }));
+    const breadcrumbItems = [
+      { label: "Docs" },
+      { label: pageTitle }
+    ];
+    return /* @__PURE__ */ jsxs(
+      DocLayoutWithDefaults,
+      {
+        title: composeMetaTitle(pageTitle),
+        head: /* @__PURE__ */ jsx(HeadWithDefaults, { title: pageTitle }),
+        lang: isDefault ? void 0 : locale,
+        noindex: settings.noindex,
+        hideSidebar: true,
+        hideToc: true,
+        sidebarOverride: /* @__PURE__ */ jsx(Fragment, {}),
+        headerOverride: /* @__PURE__ */ jsx(HeaderWithDefaults, { lang: locale, currentPath: withBase(`${prefix}/docs/tags`) }),
+        breadcrumbOverride: /* @__PURE__ */ jsx(Breadcrumb, { items: breadcrumbItems }),
+        footerOverride: /* @__PURE__ */ jsx(FooterWithDefaults, { lang: locale }),
+        bodyEndComponents: /* @__PURE__ */ jsx(BodyEndIslands, { basePath: settings.base ?? "/" }),
+        enableClientRouter: settings.dynamicPageTransition,
+        children: [
+          /* @__PURE__ */ jsx("h1", { class: "text-heading font-bold mb-vsp-lg", children: pageTitle }),
+          !settings.docTags || tags.length === 0 ? /* @__PURE__ */ jsx("p", { class: "text-muted", children: t("doc.noTags", locale) }) : /* @__PURE__ */ jsx(TagNav, { variant: "all", tags, labels }),
+          /* @__PURE__ */ jsx(DocHistoryArea, { slug: "tags", locale })
+        ]
+      }
+    );
+  }
+  return {
+    collectTagMapForLocale,
+    TagDetailPageView,
+    TagsIndexPageView
+  };
+}
+export {
+  createTagPages
+};

package/dist/tags-audit.d.ts

@@ -0,0 +1,107 @@
+/**
+ * @takazudo/zudo-doc/tags-audit
+ *
+ * Core library for vocabulary-aware frontmatter tag auditing.
+ *
+ * Exports pure functions and types consumed by:
+ *   - the package bin  (packages/zudo-doc/bin/tags-audit.mjs)
+ *   - the project-side tags-suggest script (scripts/tags-suggest.ts)
+ *   - custom integrations
+ *
+ * Does NOT import from project-specific config (settings, tag-vocabulary).
+ * The caller passes those in via AuditOptions.
+ */
+/** Minimal shape required by this library. Matches src/config/tag-vocabulary-types. */
+export interface TagVocabularyEntry {
+    id: string;
+    label?: string;
+    description?: string;
+    group?: string;
+    aliases?: readonly string[];
+    deprecated?: boolean | {
+        redirect?: string;
+    };
+}
+interface VocabularyIndex {
+    byId: Map<string, TagVocabularyEntry>;
+    byAlias: Map<string, TagVocabularyEntry>;
+    aliasToId: Map<string, string>;
+}
+export interface UnknownIssue {
+    file: string;
+    raw: string;
+}
+export interface DeprecatedIssue {
+    file: string;
+    raw: string;
+    canonical: string;
+    redirect?: string;
+}
+export interface AliasIssue {
+    file: string;
+    raw: string;
+    canonical: string;
+}
+export interface NearDuplicatePair {
+    a: string;
+    b: string;
+    reason: "similarity" | "plural";
+    score?: number;
+}
+export interface AuditReport {
+    unknowns: UnknownIssue[];
+    deprecated: DeprecatedIssue[];
+    aliases: AliasIssue[];
+    nearDuplicates: NearDuplicatePair[];
+    orphans: string[];
+    filesScanned: number;
+    /** Totals keyed by canonical id after alias/deprecation resolution. */
+    frequency: Record<string, number>;
+}
+export interface AuditOptions {
+    rootDir: string;
+    contentDirs: string[];
+    vocabulary: readonly TagVocabularyEntry[];
+    governance: "off" | "warn" | "strict";
+    vocabularyActive: boolean;
+    /**
+     * Near-duplicate detection callbacks. Optional — if omitted the relevant
+     * checks are silently skipped so callers without pluralize / string-similarity
+     * can still use the core functions.
+     */
+    nearDupHelpers?: NearDupHelpers;
+}
+export interface NearDupHelpers {
+    singular: (word: string) => string;
+    compareTwoStrings: (a: string, b: string) => number;
+}
+export declare function buildIndex(vocab: readonly TagVocabularyEntry[]): VocabularyIndex;
+export declare function collectMdxFiles(dir: string): Promise<string[]>;
+export declare function normalizeTags(value: unknown): string[];
+export declare function findNearDuplicates(tags: string[], helpers: NearDupHelpers): NearDuplicatePair[];
+export declare function audit(opts: AuditOptions): Promise<AuditReport>;
+export declare function hasHardIssues(report: AuditReport): boolean;
+export declare function computeRewrites(vocabulary: readonly TagVocabularyEntry[]): Map<string, string>;
+export declare function applyFixes(contentDirs: string[], rewrites: Map<string, string>, rootDir: string): Promise<string[]>;
+/**
+ * Rewrite alias tags to canonical ids within a single MDX file, preserving
+ * every other byte of the file verbatim. Returns `{ content, changed }`.
+ *
+ * Supports block-style (`tags:\n  - foo\n`) and flow-style
+ * (`tags: [foo, bar]`) YAML sequences. Quoted string values are handled.
+ */
+export declare function rewriteAliasesByteStable(content: string, rewrites: Map<string, string>): {
+    content: string;
+    changed: boolean;
+};
+/** Format a human-readable text report. Requires picocolors for coloring. */
+export declare function formatTextReport(report: AuditReport, governance: AuditOptions["governance"], vocabularyActive: boolean, pc: {
+    bold: (s: string) => string;
+    cyan: (s: string) => string;
+    dim: (s: string) => string;
+    red: (s: string) => string;
+    yellow: (s: string) => string;
+    blue: (s: string) => string;
+    green: (s: string) => string;
+}): string;
+export {};

package/dist/tags-audit.js

@@ -0,0 +1,321 @@
+import { readFile, readdir, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { join, relative } from "node:path";
+import matter from "gray-matter";
+function buildIndex(vocab) {
+  const byId = /* @__PURE__ */ new Map();
+  const byAlias = /* @__PURE__ */ new Map();
+  const aliasToId = /* @__PURE__ */ new Map();
+  for (const entry of vocab) {
+    byId.set(entry.id, entry);
+    for (const alias of entry.aliases ?? []) {
+      byAlias.set(alias, entry);
+      aliasToId.set(alias, entry.id);
+    }
+  }
+  return { byId, byAlias, aliasToId };
+}
+async function collectMdxFiles(dir) {
+  const out = [];
+  async function walk(current) {
+    let entries;
+    try {
+      entries = await readdir(current, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const full = join(current, entry.name);
+      if (entry.isDirectory()) {
+        await walk(full);
+      } else if (entry.name.endsWith(".mdx") || entry.name.endsWith(".md")) {
+        out.push(full);
+      }
+    }
+  }
+  await walk(dir);
+  return out.sort();
+}
+function normalizeTags(value) {
+  if (!Array.isArray(value)) return [];
+  return value.filter((v) => typeof v === "string");
+}
+const NEAR_DUP_THRESHOLD = 0.82;
+function findNearDuplicates(tags, helpers) {
+  const pairs = [];
+  const seen = /* @__PURE__ */ new Set();
+  const sorted = [...tags].sort();
+  for (let i = 0; i < sorted.length; i++) {
+    for (let j = i + 1; j < sorted.length; j++) {
+      const a = sorted[i];
+      const b = sorted[j];
+      const key = `${a}||${b}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      const singA = helpers.singular(a);
+      const singB = helpers.singular(b);
+      if (singA === singB && a !== b) {
+        pairs.push({ a, b, reason: "plural" });
+        continue;
+      }
+      const score = helpers.compareTwoStrings(a, b);
+      if (score >= NEAR_DUP_THRESHOLD) {
+        pairs.push({ a, b, reason: "similarity", score });
+      }
+    }
+  }
+  return pairs;
+}
+async function audit(opts) {
+  const index = buildIndex(opts.vocabulary);
+  const unknowns = [];
+  const deprecated = [];
+  const aliases = [];
+  const frequency = {};
+  const canonicalsUsed = /* @__PURE__ */ new Set();
+  const rawTagsUsed = /* @__PURE__ */ new Set();
+  let filesScanned = 0;
+  for (const dir of opts.contentDirs) {
+    if (!existsSync(dir)) continue;
+    const files = await collectMdxFiles(dir);
+    for (const file of files) {
+      filesScanned++;
+      const raw = await readFile(file, "utf-8");
+      const parsed = matter(raw);
+      const tags = normalizeTags(parsed.data.tags);
+      const rel = relative(opts.rootDir, file);
+      for (const tag of tags) {
+        rawTagsUsed.add(tag);
+        const idEntry = index.byId.get(tag);
+        const aliasEntry = index.byAlias.get(tag);
+        if (!opts.vocabularyActive) {
+          frequency[tag] = (frequency[tag] ?? 0) + 1;
+          canonicalsUsed.add(tag);
+          continue;
+        }
+        if (!idEntry && !aliasEntry) {
+          unknowns.push({ file: rel, raw: tag });
+          frequency[tag] = (frequency[tag] ?? 0) + 1;
+          canonicalsUsed.add(tag);
+          continue;
+        }
+        const entry = idEntry ?? aliasEntry;
+        let canonical = entry.id;
+        const dep = entry.deprecated;
+        if (dep) {
+          if (typeof dep === "object" && dep.redirect) {
+            const target = index.byId.get(dep.redirect);
+            if (target) {
+              deprecated.push({ file: rel, raw: tag, canonical: entry.id, redirect: target.id });
+              canonical = target.id;
+            } else {
+              deprecated.push({ file: rel, raw: tag, canonical: entry.id });
+            }
+          } else {
+            deprecated.push({ file: rel, raw: tag, canonical: entry.id });
+          }
+        } else if (aliasEntry && tag !== entry.id) {
+          aliases.push({ file: rel, raw: tag, canonical: entry.id });
+        }
+        frequency[canonical] = (frequency[canonical] ?? 0) + 1;
+        canonicalsUsed.add(canonical);
+      }
+    }
+  }
+  const nearDuplicates = [];
+  if (opts.nearDupHelpers) {
+    const nearDupSource = opts.vocabularyActive ? Array.from(canonicalsUsed) : Array.from(rawTagsUsed);
+    nearDuplicates.push(...findNearDuplicates(nearDupSource, opts.nearDupHelpers));
+  }
+  const orphans = opts.vocabularyActive ? opts.vocabulary.filter((entry) => {
+    if (entry.deprecated) return false;
+    if (canonicalsUsed.has(entry.id)) return false;
+    for (const alias of entry.aliases ?? []) {
+      if (rawTagsUsed.has(alias)) return false;
+    }
+    return true;
+  }).map((entry) => entry.id) : [];
+  return {
+    unknowns,
+    deprecated,
+    aliases,
+    nearDuplicates,
+    orphans,
+    filesScanned,
+    frequency
+  };
+}
+function hasHardIssues(report) {
+  return report.unknowns.length > 0 || report.deprecated.length > 0;
+}
+function computeRewrites(vocabulary) {
+  const rewrites = /* @__PURE__ */ new Map();
+  const { byId } = buildIndex(vocabulary);
+  for (const entry of vocabulary) {
+    for (const alias of entry.aliases ?? []) {
+      if (alias === entry.id) continue;
+      const dep2 = entry.deprecated;
+      if (dep2 && typeof dep2 === "object" && dep2.redirect) {
+        const target = byId.get(dep2.redirect);
+        rewrites.set(alias, target ? target.id : entry.id);
+      } else {
+        rewrites.set(alias, entry.id);
+      }
+    }
+    const dep = entry.deprecated;
+    if (dep && typeof dep === "object" && dep.redirect) {
+      const target = byId.get(dep.redirect);
+      if (target) rewrites.set(entry.id, target.id);
+    }
+  }
+  return rewrites;
+}
+async function applyFixes(contentDirs, rewrites, rootDir) {
+  const touched = [];
+  for (const dir of contentDirs) {
+    if (!existsSync(dir)) continue;
+    const files = await collectMdxFiles(dir);
+    for (const file of files) {
+      const original = await readFile(file, "utf-8");
+      const { content, changed } = rewriteAliasesByteStable(original, rewrites);
+      if (changed) {
+        await writeFile(file, content, "utf-8");
+        touched.push(relative(rootDir, file));
+      }
+    }
+  }
+  return touched;
+}
+function rewriteAliasesByteStable(content, rewrites) {
+  if (rewrites.size === 0) return { content, changed: false };
+  const fmMatch = content.match(/^(---\r?\n)([\s\S]*?)(\r?\n---(?:\r?\n|$))/);
+  if (!fmMatch) return { content, changed: false };
+  const whole = fmMatch[0] ?? "";
+  const open = fmMatch[1] ?? "";
+  const fmBody = fmMatch[2] ?? "";
+  const close = fmMatch[3] ?? "";
+  let changed = false;
+  let newBody = fmBody;
+  newBody = newBody.replace(
+    /^(tags[ \t]*:[ \t]*\[)([^\]\n]*)(\])/m,
+    (_full, pre, inner, post) => {
+      const rewritten = inner.replace(
+        /(^|,)([ \t]*)(?:(")([^"]*)(")|(')([^']*)(')|([^,\s"'][^,]*?))([ \t]*)(?=,|$)/g,
+        (_m, lead, leadWs, dq1, dqVal, dq2, sq1, sqVal, sq2, bareVal, trailWs) => {
+          const val = dqVal ?? sqVal ?? bareVal ?? "";
+          const target = rewrites.get(val.trim());
+          if (!target || target === val) return _m;
+          changed = true;
+          if (dq1) return `${lead}${leadWs}"${target}"${trailWs}`;
+          if (sq1) return `${lead}${leadWs}'${target}'${trailWs}`;
+          return `${lead}${leadWs}${target}${trailWs}`;
+        }
+      );
+      return pre + rewritten + post;
+    }
+  );
+  newBody = newBody.replace(
+    /^(tags[ \t]*:[ \t]*\r?\n)((?:[ \t]+-[^\n]*\r?\n?)+)/m,
+    (_full, pre, items) => {
+      const rewritten = items.replace(
+        /^([ \t]+-[ \t]+)(?:(")([^"]*)(")|(')([^']*)('))?([^\n]*)$/gm,
+        (line, dash, dq1, dqVal, dq2, sq1, sqVal, sq2, bare) => {
+          if (dq1) {
+            const target2 = rewrites.get(dqVal);
+            if (target2 && target2 !== dqVal) {
+              changed = true;
+              return `${dash}"${target2}"${bare}`;
+            }
+            return line;
+          }
+          if (sq1) {
+            const target2 = rewrites.get(sqVal);
+            if (target2 && target2 !== sqVal) {
+              changed = true;
+              return `${dash}'${target2}'${bare}`;
+            }
+            return line;
+          }
+          const trimmed = bare.replace(/[ \t\r]+$/, "");
+          const trailing = bare.slice(trimmed.length);
+          const target = rewrites.get(trimmed);
+          if (target && target !== trimmed) {
+            changed = true;
+            return `${dash}${target}${trailing}`;
+          }
+          return line;
+        }
+      );
+      return pre + rewritten;
+    }
+  );
+  if (!changed) return { content, changed: false };
+  return {
+    content: open + newBody + close + content.slice(whole.length),
+    changed: true
+  };
+}
+function formatTextReport(report, governance, vocabularyActive, pc) {
+  const lines = [];
+  lines.push(pc.bold(pc.cyan(`tags:audit \u2014 scanned ${report.filesScanned} file(s)`)));
+  lines.push(
+    pc.dim(
+      `vocabulary: ${vocabularyActive ? "active" : "inactive"}, governance: ${governance}`
+    )
+  );
+  lines.push("");
+  if (report.unknowns.length > 0) {
+    lines.push(pc.bold(pc.red(`\u2717 Unknown tags (${report.unknowns.length})`)));
+    for (const { file, raw } of report.unknowns) {
+      lines.push(`  ${pc.red("\u2022")} ${file}  ${pc.yellow(raw)}`);
+    }
+    lines.push("");
+  }
+  if (report.deprecated.length > 0) {
+    lines.push(pc.bold(pc.yellow(`\u26A0 Deprecated tags (${report.deprecated.length})`)));
+    for (const { file, raw, redirect } of report.deprecated) {
+      const suffix = redirect ? pc.dim(` \u2192 ${redirect}`) : pc.dim(" (dropped)");
+      lines.push(`  ${pc.yellow("\u2022")} ${file}  ${raw}${suffix}`);
+    }
+    lines.push("");
+  }
+  if (report.aliases.length > 0) {
+    lines.push(pc.bold(pc.blue(`\u2139 Alias usage (${report.aliases.length})`)));
+    for (const { file, raw, canonical } of report.aliases) {
+      lines.push(`  ${pc.blue("\u2022")} ${file}  ${raw} ${pc.dim(`\u2192 ${canonical}`)}`);
+    }
+    lines.push(pc.dim(`  (run with --fix to rewrite these in place)`));
+    lines.push("");
+  }
+  if (report.nearDuplicates.length > 0) {
+    lines.push(pc.bold(pc.yellow(`\u26A0 Near-duplicate tags (${report.nearDuplicates.length})`)));
+    for (const pair of report.nearDuplicates) {
+      const hint = pair.reason === "plural" ? "same singular" : `similarity ${(pair.score ?? 0).toFixed(2)}`;
+      lines.push(`  ${pc.yellow("\u2022")} ${pair.a} \u2194 ${pair.b} ${pc.dim(`(${hint})`)}`);
+    }
+    lines.push("");
+  }
+  if (report.orphans.length > 0) {
+    lines.push(pc.bold(pc.dim(`\u2026 Orphan vocabulary entries (${report.orphans.length})`)));
+    for (const id of report.orphans) {
+      lines.push(`  ${pc.dim("\u2022")} ${id}`);
+    }
+    lines.push("");
+  }
+  if (report.unknowns.length === 0 && report.deprecated.length === 0 && report.aliases.length === 0 && report.nearDuplicates.length === 0 && report.orphans.length === 0) {
+    lines.push(pc.green("\u2713 No tag issues found"));
+  }
+  return lines.join("\n");
+}
+export {
+  applyFixes,
+  audit,
+  buildIndex,
+  collectMdxFiles,
+  computeRewrites,
+  findNearDuplicates,
+  formatTextReport,
+  hasHardIssues,
+  normalizeTags,
+  rewriteAliasesByteStable
+};