@eqtylab/docs 0.3.5 → 0.4.0

package/dist/index.js

@@ -1,14 +1,15 @@
 import './chunk-55J6XMHW.js';
-import { rehypeBaseUrl } from './chunk-GSSSQTEV.js';
-import { resolveConfig } from './chunk-K7PJRTK3.js';
-export { resolveConfig } from './chunk-K7PJRTK3.js';
+import { rehypeBaseUrl, versionFromPath } from './chunk-OM7745ZQ.js';
+import { resolveConfig } from './chunk-X4LT7ASQ.js';
+export { resolveConfig } from './chunk-X4LT7ASQ.js';
 import { resolveDocsEnv } from './chunk-ZZ45WAVR.js';
 export { resolveDocsEnv } from './chunk-ZZ45WAVR.js';
-import { docsHref, isExternalHref } from './chunk-VJN3HXKM.js';
-export { badgeSchema, docsSchema, groupSchema } from './chunk-IWKZQ4CW.js';
-import path4 from 'path';
+import { docsHref, isExternalHref } from './chunk-LNQV7TVH.js';
+export { badgeSchema, docsSchema, groupSchema } from './chunk-VNQZJMDO.js';
+import path5 from 'path';
 import { fileURLToPath } from 'url';
 import { globSync } from 'tinyglobby';
+import { execFileSync } from 'child_process';
 import fs, { readdirSync, readFileSync } from 'fs';
 import { createRequire } from 'module';
 import { visit, SKIP } from 'unist-util-visit';
@@ -24,7 +25,7 @@ function assertMdxOnly(contentDir) {
   if (strays.length === 0) return;
   const list = strays.sort().map((file) => `  - ${file}  ->  ${file.replace(/\.md$/i, ".mdx")}`).join("\n");
   throw new Error(
-    `[@eqtylab/docs] Found ${strays.length} Markdown file${strays.length > 1 ? "s" : ""} in ${path4.relative(process.cwd(), dir) || dir}:
+    `[@eqtylab/docs] Found ${strays.length} Markdown file${strays.length > 1 ? "s" : ""} in ${path5.relative(process.cwd(), dir) || dir}:
 ${list}
 
 Docs content must be .mdx. Only MDX supports the component overrides that render
@@ -33,12 +34,242 @@ different from every other page. Renaming is usually the only change needed --
 MDX is a superset of Markdown.`
   );
 }
+
+// src/versions.ts
+var SEMVER = /(?:^|[^0-9.])(\d+)\.(\d+)\.(\d+)$/;
+var LEVELS = ["patch", "minor", "major"];
+function parseTag(tag) {
+  const m = SEMVER.exec(tag.trim());
+  if (!m) return null;
+  const major = Number(m[1]);
+  const minor = Number(m[2]);
+  const patch = Number(m[3]);
+  return { tag, major, minor, patch, version: `${major}.${minor}.${patch}` };
+}
+function compareTags(a, b) {
+  return a.major - b.major || a.minor - b.minor || a.patch - b.patch;
+}
+function groupOf(v, granularity) {
+  if (granularity === "major") return `${v.major}`;
+  if (granularity === "minor") return `${v.major}.${v.minor}`;
+  return v.version;
+}
+function idOf(group) {
+  return `v${group}`;
+}
+function suffixOf(id) {
+  return id.replace(/\./g, "_");
+}
+function highestTag(tags) {
+  const parsed = tags.map(parseTag).filter((t) => t !== null);
+  if (!parsed.length) return null;
+  return parsed.sort(compareTags)[parsed.length - 1];
+}
+function selectVersions(tags, current, granularity, skippedGroups = []) {
+  const cur = parseTag(current);
+  if (!cur) {
+    throw new Error(`[@eqtylab/docs] versions.current "${current}" is not MAJOR.MINOR.PATCH`);
+  }
+  const skipped = [];
+  const above = [];
+  const parsed = [];
+  for (const tag of tags) {
+    const p = parseTag(tag);
+    if (p) parsed.push(p);
+    else skipped.push(tag);
+  }
+  parsed.sort(compareTags);
+  const currentGroup = groupOf(cur, granularity);
+  const skip = new Set(skippedGroups);
+  const byGroup = /* @__PURE__ */ new Map();
+  const inCurrent = [];
+  const covered = [];
+  for (const p of parsed) {
+    if (compareTags(p, cur) > 0) {
+      above.push(p.tag);
+      continue;
+    }
+    covered.push(p);
+    const g = groupOf(p, granularity);
+    if (g === currentGroup) {
+      inCurrent.push(p);
+      continue;
+    }
+    if (!byGroup.has(g)) byGroup.set(g, []);
+    byGroup.get(g).push(p);
+  }
+  const copies = [];
+  const picks = [];
+  const coverOf = /* @__PURE__ */ new Map();
+  let lastCovered = null;
+  for (const [g, members] of byGroup) {
+    if (skip.has(g)) {
+      coverOf.set(g, lastCovered);
+      continue;
+    }
+    const pick = members[members.length - 1];
+    const id = idOf(g);
+    copies.push({ id, suffix: suffixOf(id), group: g, tag: pick.tag });
+    picks.push(pick);
+    coverOf.set(g, id);
+    lastCovered = id;
+  }
+  const redirects = [];
+  for (const [g, members] of byGroup) {
+    const to = coverOf.get(g) ?? null;
+    for (const p of members) {
+      const id = idOf(p.version);
+      if (id === to) continue;
+      redirects.push({ id, to });
+    }
+  }
+  for (const p of inCurrent) redirects.push({ id: idOf(p.version), to: null });
+  copies.reverse();
+  picks.reverse();
+  const emittedIds = new Set(redirects.map((r) => r.id));
+  const copyIds = new Set(copies.map((c) => c.id));
+  const stubSources = copies.length ? covered.some((p) => p.version === cur.version) ? covered : [...covered, cur] : [];
+  for (const level of LEVELS.slice(LEVELS.indexOf(granularity))) {
+    const seenGroups = /* @__PURE__ */ new Set();
+    for (let i = stubSources.length - 1; i >= 0; i--) {
+      const group = groupOf(stubSources[i], level);
+      if (seenGroups.has(group)) continue;
+      seenGroups.add(group);
+      const id = idOf(group);
+      if (copyIds.has(id) || emittedIds.has(id)) continue;
+      const holdsCurrent = groupOf(cur, level) === group;
+      let cover = null;
+      for (let c = 0; !holdsCurrent && c < copies.length; c++) {
+        if (groupOf(picks[c], level) === group) {
+          cover = copies[c].id;
+          break;
+        }
+      }
+      if (!holdsCurrent && cover === null) continue;
+      redirects.push({ id, to: cover });
+      emittedIds.add(id);
+    }
+  }
+  return { copies, redirects, skipped, above };
+}
+
+// src/internal/extract-versions.ts
+var EMPTY_VERSIONS = {
+  currentVersion: null,
+  versionManifest: [],
+  versionRedirects: []
+};
+var TAG = "[@eqtylab/docs] versions:";
+function git(cwd, ...args) {
+  return execFileSync("git", args, {
+    cwd,
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"]
+  }).trim();
+}
+function realpath(p) {
+  try {
+    return fs.realpathSync(p);
+  } catch {
+    return p;
+  }
+}
+function hasPathAtTag(repoRoot, tag, rel) {
+  try {
+    execFileSync("git", ["cat-file", "-e", `${tag}:${rel}`], { cwd: repoRoot, stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+function extractVersions(o) {
+  let repoRoot;
+  try {
+    repoRoot = git(o.root, "rev-parse", "--show-toplevel");
+  } catch {
+    o.logger.warn(
+      `${TAG} not a git repository, or git is missing. Versioning is off for this build.`
+    );
+    return EMPTY_VERSIONS;
+  }
+  if (git(o.root, "rev-parse", "--is-shallow-repository") === "true") {
+    o.logger.warn(`${TAG} shallow clone; tags may be incomplete. Check out with fetch-depth: 0.`);
+  }
+  const tags = git(o.root, "tag", "--list", o.tags).split("\n").filter(Boolean);
+  const currentVersion = o.current ?? highestTag(tags)?.version;
+  if (!currentVersion) {
+    o.logger.info(
+      `${TAG} on and dormant. No tag matches "${o.tags}"; versioning activates at the first release tag.`
+    );
+    return EMPTY_VERSIONS;
+  }
+  const contentRel = path5.relative(realpath(repoRoot), realpath(o.contentDirAbs)).split(path5.sep).join("/");
+  let selection = selectVersions(tags, currentVersion, o.granularity);
+  for (const tag of selection.skipped) {
+    o.logger.warn(`${TAG} tag "${tag}" is not MAJOR.MINOR.PATCH; skipped.`);
+  }
+  if (selection.above.length) {
+    o.logger.warn(
+      `${TAG} tags above current ${currentVersion} ignored: ${selection.above.join(", ")}.`
+    );
+  }
+  const missing = selection.copies.filter((c) => !hasPathAtTag(repoRoot, c.tag, contentRel));
+  if (missing.length) {
+    for (const c of missing) {
+      o.logger.warn(
+        `${TAG} ${c.tag} has no ${contentRel}; skipping ${c.id}. Its releases redirect to the copy below.`
+      );
+    }
+    selection = selectVersions(
+      tags,
+      currentVersion,
+      o.granularity,
+      missing.map((c) => c.group)
+    );
+  }
+  const versionsDir = path5.join(o.cacheDir, "versions");
+  fs.rmSync(versionsDir, { recursive: true, force: true });
+  const versionManifest = selection.copies.map((c) => {
+    const dir = path5.join(versionsDir, c.id);
+    fs.mkdirSync(dir, { recursive: true });
+    try {
+      const archive = execFileSync("git", ["archive", `${c.tag}:${contentRel}`], {
+        cwd: repoRoot,
+        maxBuffer: 512 * 1024 * 1024,
+        stdio: ["ignore", "pipe", "inherit"]
+      });
+      execFileSync("tar", ["-x", "-C", dir], {
+        input: archive,
+        stdio: ["pipe", "ignore", "inherit"]
+      });
+    } catch (cause) {
+      throw new Error(`${TAG} ${c.tag} failed to extract ${contentRel} into ${dir}`, { cause });
+    }
+    if (!fs.readdirSync(dir).length) {
+      throw new Error(`${TAG} ${c.tag} extracted no files into ${dir}`);
+    }
+    return { ...c, dir };
+  });
+  const cur = parseTag(currentVersion);
+  const group = groupOf(cur, o.granularity);
+  const result = {
+    currentVersion: { id: idOf(group), group, version: cur.version },
+    versionManifest,
+    versionRedirects: selection.redirects
+  };
+  fs.mkdirSync(o.cacheDir, { recursive: true });
+  fs.writeFileSync(path5.join(o.cacheDir, "versions.json"), JSON.stringify(result, null, 2));
+  o.logger.info(
+    `${TAG} current ${result.currentVersion.id}; ${versionManifest.length} older ${versionManifest.length === 1 ? "copy" : "copies"}, ${selection.redirects.length} redirects.`
+  );
+  return result;
+}
 var GRAMMAR_IMPORT = "grammars/${";
 function findGrammarDir(projectRoot) {
   const requireFromProject = createRequire(new URL("package.json", projectRoot));
   const equalityEntry = requireFromProject.resolve("@eqtylab/equality");
   const requireFromEquality = createRequire(equalityEntry);
-  return path4.resolve(path4.dirname(requireFromEquality.resolve("microlighter")), "grammars");
+  return path5.resolve(path5.dirname(requireFromEquality.resolve("microlighter")), "grammars");
 }
 function microlighterGrammarsPlugin(projectRoot, logger) {
   return {
@@ -46,7 +277,7 @@ function microlighterGrammarsPlugin(projectRoot, logger) {
     apply: "build",
     generateBundle(_options, bundle) {
       const directories = new Set(
-        Object.values(bundle).filter((output) => output.type === "chunk" && output.code.includes(GRAMMAR_IMPORT)).map((output) => path4.posix.dirname(output.fileName))
+        Object.values(bundle).filter((output) => output.type === "chunk" && output.code.includes(GRAMMAR_IMPORT)).map((output) => path5.posix.dirname(output.fileName))
       );
       if (directories.size === 0) return;
       let grammarDir;
@@ -66,7 +297,7 @@ function microlighterGrammarsPlugin(projectRoot, logger) {
           this.emitFile({
             type: "asset",
             fileName: directory === "." ? `grammars/${grammar}` : `${directory}/grammars/${grammar}`,
-            source: readFileSync(path4.resolve(grammarDir, grammar), "utf8")
+            source: readFileSync(path5.resolve(grammarDir, grammar), "utf8")
           });
         }
       }
@@ -97,7 +328,7 @@ function pagefindIntegration() {
     name: "@eqtylab/docs/pagefind",
     hooks: {
       "astro:config:setup"({ config, logger }) {
-        indexDir = path4.join(fileURLToPath(config.outDir), INDEX_DIR);
+        indexDir = path5.join(fileURLToPath(config.outDir), INDEX_DIR);
         if (config.output === "server") {
           logger.warn(
             'Output "server" emits no static HTML, so there is nothing for Pagefind to index.'
@@ -113,9 +344,9 @@ function pagefindIntegration() {
         server.middlewares.use((req, res, next) => {
           const requested = indexRequest(req.url, base);
           if (requested === null) return next();
-          const file = path4.join(indexDir, requested);
-          if (!file.startsWith(indexDir + path4.sep) || !fs.existsSync(file)) return next();
-          res.setHeader("Content-Type", MIME[path4.extname(file)] ?? "application/octet-stream");
+          const file = path5.join(indexDir, requested);
+          if (!file.startsWith(indexDir + path5.sep) || !fs.existsSync(file)) return next();
+          res.setHeader("Content-Type", MIME[path5.extname(file)] ?? "application/octet-stream");
           res.setHeader("Cache-Control", "no-store");
           fs.createReadStream(file).pipe(res);
         });
@@ -130,7 +361,7 @@ function pagefindIntegration() {
         const { page_count, errors: addErrors } = await index.addDirectory({ path: outDir });
         failOn(addErrors, logger, "index the built output");
         const { outputPath, errors: writeErrors } = await index.writeFiles({
-          outputPath: path4.join(outDir, INDEX_DIR)
+          outputPath: path5.join(outDir, INDEX_DIR)
         });
         failOn(writeErrors, logger, "write the index");
         logger.info(`indexed ${page_count} pages to ${outputPath}`);
@@ -202,9 +433,9 @@ function rehypeProseScope() {
 }
 var CONTENT_EXTENSIONS = [".mdx", ".md"];
 function hasEntry(contentRoot, id) {
-  const stem = path4.join(contentRoot, id);
+  const stem = path5.join(contentRoot, id);
   return CONTENT_EXTENSIONS.some(
-    (ext) => fs.existsSync(stem + ext) || fs.existsSync(path4.join(stem, `index${ext}`))
+    (ext) => fs.existsSync(stem + ext) || fs.existsSync(path5.join(stem, `index${ext}`))
   );
 }
 function splitTarget(href) {
@@ -220,18 +451,18 @@ function rehypeRelativeLinks(options) {
   return function transformer(tree, file) {
     const filePath = file?.path;
     if (!filePath) return;
-    const fromRoot = path4.relative(contentRoot, filePath);
-    if (!fromRoot || fromRoot.startsWith("..") || path4.isAbsolute(fromRoot)) return;
+    const fromRoot = path5.relative(contentRoot, filePath);
+    if (!fromRoot || fromRoot.startsWith("..") || path5.isAbsolute(fromRoot)) return;
     visit(tree, "element", (node) => {
       const props = node.properties;
       const href = props?.href;
       if (!props || typeof href !== "string") return;
       const split = splitTarget(href);
       if (!split) return;
-      const absolute = path4.resolve(path4.dirname(filePath), split.target);
-      const relative = path4.relative(contentRoot, absolute);
-      if (!relative || relative.startsWith("..") || path4.isAbsolute(relative)) return;
-      const id = relative.split(path4.sep).join("/").replace(/\.mdx?$/i, "").replace(/\/index$/, "");
+      const absolute = path5.resolve(path5.dirname(filePath), split.target);
+      const relative = path5.relative(contentRoot, absolute);
+      if (!relative || relative.startsWith("..") || path5.isAbsolute(relative)) return;
+      const id = relative.split(path5.sep).join("/").replace(/\.mdx?$/i, "").replace(/\/index$/, "");
       if (!hasEntry(contentRoot, id)) onMissing?.(href, filePath);
       props.href = docsHref(id, ctx) + split.suffix;
     });
@@ -268,10 +499,31 @@ function rehypeTableColumns() {
     });
   };
 }
+
+// src/internal/remark-archive-document.ts
+var MDX_NODES = /* @__PURE__ */ new Set([
+  "mdxjsEsm",
+  "mdxJsxFlowElement",
+  "mdxJsxTextElement",
+  "mdxFlowExpression",
+  "mdxTextExpression"
+]);
+function prune(node) {
+  if (!Array.isArray(node.children)) return;
+  node.children = node.children.filter((child) => !MDX_NODES.has(child.type));
+  for (const child of node.children) prune(child);
+}
+function remarkArchiveDocument(options) {
+  return function transformer(tree, file) {
+    const version = versionFromPath(file?.path ?? file?.history?.[0], options.versionsDir);
+    if (!version) return;
+    prune(tree);
+  };
+}
 var PAGE_EXTENSIONS = ["astro", "md", "mdx", "html", "ts", "js"];
 function toRoutePath(relative) {
   const withoutExt = relative.replace(/\.[^./]+$/, "");
-  const segments = withoutExt.split(path4.sep).join("/").split("/").filter(Boolean);
+  const segments = withoutExt.split(path5.sep).join("/").split("/").filter(Boolean);
   if (segments.at(-1) === "index") segments.pop();
   return "/" + segments.join("/");
 }
@@ -289,7 +541,7 @@ function scanConsumerPages(srcDir) {
   const ownedPaths = [];
   const claimedPatterns = /* @__PURE__ */ new Set();
   for (const file of files) {
-    if (file.split(path4.sep).some((segment) => segment.startsWith("_"))) continue;
+    if (file.split(path5.sep).some((segment) => segment.startsWith("_"))) continue;
     const routePath = toRoutePath(file);
     claimedPatterns.add(routePath === "" ? "/" : routePath);
     if (!/[[\]]/.test(file)) {
@@ -353,6 +605,15 @@ function docs(options = {}) {
       async "astro:config:setup"(params) {
         const { config, injectRoute, injectScript, updateConfig, addWatchFile, logger, command } = params;
         assertMdxOnly(new URL(`./${cfg.contentDir}/`, config.srcDir));
+        const versionData = cfg.versions === false ? EMPTY_VERSIONS : extractVersions({
+          root: fileURLToPath(config.root),
+          contentDirAbs: fileURLToPath(new URL(`./${cfg.contentDir}/`, config.srcDir)),
+          cacheDir: fileURLToPath(new URL("./.astro/eqty-docs/", config.root)),
+          current: cfg.versions.current,
+          tags: cfg.versions.tags,
+          granularity: cfg.versions.granularity,
+          logger
+        });
         const consumer = scanConsumerPages(config.srcDir);
         for (const route of plannedRoutes(cfg)) {
           if (consumer.claimedPatterns.has(route.pattern)) {
@@ -367,7 +628,8 @@ function docs(options = {}) {
           ...cfg,
           env,
           // Read by the catch-all's getStaticPaths so no path is emitted twice.
-          ownedByConsumer: consumer.ownedPaths
+          ownedByConsumer: consumer.ownedPaths,
+          ...versionData
         };
         if (command === "dev") {
           addWatchFile(new URL(`./${cfg.contentDir}/`, config.srcDir));
@@ -414,8 +676,10 @@ function docs(options = {}) {
         };
         markdown.gfm = true;
         markdown.smartypants = true;
+        const versionsDir = fileURLToPath(new URL("./.astro/eqty-docs/versions/", config.root));
+        markdown.remarkPlugins = [[remarkArchiveDocument, { versionsDir }]];
         markdown.rehypePlugins = [
-          [rehypeBaseUrl, { base: config.base }],
+          [rehypeBaseUrl, { base: config.base, pathPrefix: cfg.pathPrefix, versionsDir }],
           // Must follow rehypeBaseUrl: the hrefs this emits already carry `base`, and
           // rehypeBaseUrl would prefix them a second time.
           [
@@ -425,7 +689,7 @@ function docs(options = {}) {
               base: config.base,
               pathPrefix: cfg.pathPrefix,
               onMissing: (href, filePath) => logger.warn(
-                `${path4.relative(fileURLToPath(config.root), filePath)} links to ${href}, which is not a page in ${cfg.contentDir}`
+                `${path5.relative(fileURLToPath(config.root), filePath)} links to ${href}, which is not a page in ${cfg.contentDir}`
               )
             }
           ],
@@ -454,6 +718,9 @@ function docs(options = {}) {
             `  const config: import('@eqtylab/docs').DocsConfig & {`,
             `    env: import('@eqtylab/docs').DocsEnv;`,
             `    ownedByConsumer: string[];`,
+            `    currentVersion: { id: string; group: string; version: string } | null;`,
+            `    versionManifest: Array<{ id: string; suffix: string; group: string; tag: string; dir: string }>;`,
+            `    versionRedirects: Array<{ id: string; to: string | null }>;`,
             `  };`,
             `  export default config;`,
             `}`,