@rodavel/vite-plugin-content-tree 0.1.0

package/dist/index.js

@@ -0,0 +1,484 @@
+// src/config.ts
+var INDEX_SUFFIX = "/index";
+var DEFAULT_META_FILE = "_meta.json";
+var DEFAULT_PAGE_FILE = "index.mdx";
+var DEFAULT_ORDER = 999;
+
+// src/generator.ts
+import { randomUUID } from "crypto";
+import { mkdir, rename, unlink, writeFile } from "fs/promises";
+import { dirname as dirname2, join as join2 } from "path";
+
+// src/scanner.ts
+import { readdir, readFile } from "fs/promises";
+import { dirname, join, relative, resolve } from "path";
+import matter from "gray-matter";
+var BASE_FIELDS = /* @__PURE__ */ new Set(["title", "description", "order", "nav"]);
+var META_BASE_FIELDS = /* @__PURE__ */ new Set(["name", "order"]);
+var defaultMapFrontmatter = (raw) => {
+  const result = {
+    title: typeof raw.title === "string" ? raw.title : "",
+    description: typeof raw.description === "string" ? raw.description : void 0,
+    nav: typeof raw.nav === "string" ? raw.nav : void 0,
+    order: typeof raw.order === "number" ? raw.order : void 0
+  };
+  const extra = {};
+  let hasExtra = false;
+  for (const key of Object.keys(raw)) {
+    if (!BASE_FIELDS.has(key)) {
+      extra[key] = raw[key];
+      hasExtra = true;
+    }
+  }
+  if (hasExtra) {
+    result.extra = extra;
+  }
+  return result;
+};
+async function readDirectoryMeta(docsDir, dirPath, metaFile) {
+  const metaPath = join(docsDir, dirPath, metaFile);
+  const resolvedMeta = resolve(metaPath);
+  const resolvedRoot = resolve(docsDir);
+  if (!resolvedMeta.startsWith(`${resolvedRoot}/`) && resolvedMeta !== resolvedRoot) {
+    throw new Error(`Metadata path escapes content root: ${metaPath}`);
+  }
+  let content;
+  try {
+    content = await readFile(resolvedMeta, "utf-8");
+  } catch (err) {
+    if (err.code === "ENOENT") {
+      return {};
+    }
+    throw new Error(`Failed to read metadata file: ${metaPath}`, { cause: err });
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(content);
+  } catch (err) {
+    throw new Error(`Failed to parse metadata file: ${metaPath}`, { cause: err });
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    const actual = Array.isArray(parsed) ? "array" : typeof parsed;
+    throw new Error(`Metadata file must contain a JSON object, got ${actual}: ${metaPath}`);
+  }
+  const obj = parsed;
+  const meta = {};
+  if (typeof obj.name === "string") meta.name = obj.name;
+  if (typeof obj.order === "number" && Number.isFinite(obj.order)) meta.order = obj.order;
+  const extra = {};
+  let hasExtra = false;
+  for (const key of Object.keys(obj)) {
+    if (!META_BASE_FIELDS.has(key)) {
+      extra[key] = obj[key];
+      hasExtra = true;
+    }
+  }
+  if (hasExtra) {
+    meta.extra = extra;
+  }
+  return meta;
+}
+async function scanPages(docsDir, pageFile, mapFrontmatter = defaultMapFrontmatter) {
+  const pages = [];
+  async function walk(dir) {
+    const entries = await readdir(dir, { withFileTypes: true });
+    const subdirs = [];
+    for (const entry of entries) {
+      const full = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        subdirs.push(full);
+      } else if (entry.name === pageFile) {
+        const relPath = relative(docsDir, full).replace(/\\/g, "/");
+        const dirRel = dirname(relPath);
+        const key = dirRel === "." ? "" : dirRel;
+        const segments = key ? key.split("/") : [];
+        let content;
+        try {
+          content = await readFile(full, "utf-8");
+        } catch (err) {
+          throw new Error(`Failed to read page file: ${full}`, { cause: err });
+        }
+        let data;
+        try {
+          data = matter(content).data;
+        } catch (err) {
+          throw new Error(`Failed to parse frontmatter in: ${full}`, { cause: err });
+        }
+        const result = mapFrontmatter(data, relPath);
+        pages.push({
+          key,
+          title: result.title,
+          description: result.description,
+          nav: result.nav,
+          order: result.order ?? DEFAULT_ORDER,
+          file: relPath,
+          segments,
+          extra: result.extra
+        });
+      }
+    }
+    await Promise.all(subdirs.map(walk));
+  }
+  await walk(docsDir);
+  return pages;
+}
+function resolveModules(pages, pageByKey) {
+  for (const page of pages) {
+    if (page.extra?.module) continue;
+    if (page.segments.length === 0) continue;
+    const moduleRoot = pageByKey.get(page.segments[0]);
+    const mod = moduleRoot?.extra?.module;
+    if (mod) {
+      page.extra = { ...page.extra, module: mod };
+    }
+  }
+}
+
+// src/tree-builder.ts
+function buildPageIndex(pages) {
+  const directChildren = /* @__PURE__ */ new Map();
+  const subDirNames = /* @__PURE__ */ new Map();
+  for (const page of pages) {
+    if (page.key === "") continue;
+    const parentPath = page.segments.slice(0, -1).join("/") || "";
+    let children = directChildren.get(parentPath);
+    if (!children) {
+      children = [];
+      directChildren.set(parentPath, children);
+    }
+    children.push(page);
+    for (let depth = 0; depth < page.segments.length - 1; depth++) {
+      const ancestor = page.segments.slice(0, depth).join("/") || "";
+      let dirs = subDirNames.get(ancestor);
+      if (!dirs) {
+        dirs = /* @__PURE__ */ new Set();
+        subDirNames.set(ancestor, dirs);
+      }
+      dirs.add(page.segments[depth]);
+    }
+  }
+  return { directChildren, subDirNames };
+}
+function humanize(slug, acronyms) {
+  return slug.split("-").map((w) => acronyms.has(w) ? w.toUpperCase() : w.charAt(0).toUpperCase() + w.slice(1)).join(" ");
+}
+var defaultResolveDirectoryLabel = (dirName, meta, indexPage, acronyms) => {
+  const mod = indexPage?.extra?.module;
+  if (mod) return mod;
+  if (meta.name) return meta.name;
+  return humanize(dirName, acronyms);
+};
+function buildChildren(parentPath, ctx) {
+  const parentSegments = parentPath ? parentPath.split("/") : [];
+  const directPages = ctx.pageIndex.directChildren.get(parentPath) ?? [];
+  const dirNames = ctx.pageIndex.subDirNames.get(parentPath) ?? /* @__PURE__ */ new Set();
+  const pageBySegment = /* @__PURE__ */ new Map();
+  for (const page of directPages) {
+    pageBySegment.set(page.segments[parentSegments.length], page);
+  }
+  const results = [];
+  for (const page of directPages) {
+    const lastSegment = page.segments[page.segments.length - 1];
+    if (dirNames.has(lastSegment)) continue;
+    const pageNode = {
+      type: "page",
+      name: page.nav ?? page.title,
+      id: page.key,
+      url: `${ctx.urlPrefix}/${page.key}`,
+      order: page.order
+    };
+    results.push(pageNode);
+  }
+  for (const dirName of dirNames) {
+    const dirPath = parentPath ? `${parentPath}/${dirName}` : dirName;
+    const indexPage = pageBySegment.get(dirName);
+    const meta = ctx.metas.get(dirPath) ?? {};
+    const children = buildChildren(dirPath, ctx);
+    if (children.length === 0 && !indexPage) continue;
+    const dirLabel = ctx.resolveDirectoryLabel(dirName, meta, indexPage, ctx.acronyms);
+    const directory = {
+      type: "directory",
+      name: dirLabel,
+      id: dirPath,
+      children,
+      order: indexPage?.order ?? meta.order ?? DEFAULT_ORDER
+    };
+    if (indexPage) {
+      directory.index = {
+        type: "page",
+        name: indexPage.nav ?? indexPage.title,
+        url: `${ctx.urlPrefix}/${indexPage.key}`,
+        id: `${indexPage.key}${INDEX_SUFFIX}`
+      };
+    }
+    results.push(directory);
+  }
+  results.sort((a, b) => {
+    if (a.order !== b.order) return a.order - b.order;
+    return a.name.localeCompare(b.name);
+  });
+  return results;
+}
+function stripOrder(node) {
+  if (node.type === "page") {
+    const { order: _2, ...rest2 } = node;
+    return rest2;
+  }
+  const { order: _, children, index, ...rest } = node;
+  return {
+    ...rest,
+    children: children.map(stripOrder),
+    ...index && { index }
+  };
+}
+
+// src/generator.ts
+var SAFE_IDENTIFIER = /^[a-zA-Z_$][\w$]*$/;
+var SAFE_IMPORT_PATH = /^(?:\.\.?\/[\w@._$/-]+|@[\w-]+\/[\w._-]+(?:\/[\w._-]+)*|[a-zA-Z][\w._-]*(?:\/[\w._-]+)*)$/;
+function normalizeAcronyms(acronyms) {
+  if (acronyms instanceof Set) return acronyms;
+  return new Set(acronyms ?? []);
+}
+var defaultMapPageEntry = (page) => {
+  const entry = { ...page.extra };
+  entry.title = page.title;
+  if (page.description) entry.description = page.description;
+  entry.file = page.file;
+  return entry;
+};
+async function preloadMetas(docsDir, metaFile, subDirNames) {
+  const dirPaths = /* @__PURE__ */ new Set();
+  for (const [parentPath, dirs] of subDirNames) {
+    for (const dir of dirs) {
+      dirPaths.add(parentPath ? `${parentPath}/${dir}` : dir);
+    }
+  }
+  const metas = /* @__PURE__ */ new Map();
+  await Promise.all(
+    [...dirPaths].map(async (dirPath) => {
+      const meta = await readDirectoryMeta(docsDir, dirPath, metaFile);
+      if (meta.name !== void 0 || meta.order !== void 0 || meta.extra !== void 0) {
+        metas.set(dirPath, meta);
+      }
+    })
+  );
+  return metas;
+}
+async function generateData(opts) {
+  const metaFile = opts.metaFile ?? DEFAULT_META_FILE;
+  const pageFile = opts.pageFile ?? DEFAULT_PAGE_FILE;
+  const acronyms = normalizeAcronyms(opts.acronyms);
+  const pages = await scanPages(opts.docsDir, pageFile, opts.mapFrontmatter);
+  const pageByKey = new Map(pages.map((p) => [p.key, p]));
+  const enrich = opts.enrichPages ?? (() => {
+  });
+  enrich(pages, pageByKey);
+  const resolveLabel = opts.resolveDirectoryLabel ?? defaultResolveDirectoryLabel;
+  const pageIndex = buildPageIndex(pages);
+  const metas = await preloadMetas(opts.docsDir, metaFile, pageIndex.subDirNames);
+  const ctx = {
+    pageIndex,
+    metas,
+    urlPrefix: opts.urlPrefix,
+    acronyms,
+    resolveDirectoryLabel: resolveLabel
+  };
+  const topChildren = buildChildren("", ctx);
+  let tree;
+  const rootPage = pageByKey.get("");
+  if (opts.root) {
+    const rootDirectory = {
+      type: "directory",
+      name: opts.root.name,
+      id: opts.root.id,
+      children: [],
+      order: DEFAULT_ORDER
+    };
+    if (rootPage) {
+      rootDirectory.index = {
+        type: "page",
+        name: rootPage.nav ?? rootPage.title,
+        url: opts.urlPrefix,
+        id: `${opts.root.id}${INDEX_SUFFIX}`
+      };
+    }
+    const treeChildren = [stripOrder(rootDirectory), ...topChildren.map(stripOrder)];
+    tree = { type: "directory", name: opts.treeName, id: opts.treeName, children: treeChildren };
+  } else {
+    tree = {
+      type: "directory",
+      name: opts.treeName,
+      id: opts.treeName,
+      children: topChildren.map(stripOrder)
+    };
+    if (rootPage) {
+      tree.index = {
+        type: "page",
+        name: rootPage.nav ?? rootPage.title,
+        url: opts.urlPrefix,
+        id: `${opts.treeName}${INDEX_SUFFIX}`
+      };
+    }
+  }
+  return { pages, tree };
+}
+async function writeOutput(opts, data) {
+  const { treeType, pageType } = opts;
+  const pagesExport = opts.pagesExportName ?? "pages";
+  const treeExport = opts.treeExportName ?? "docsTree";
+  const mapEntry = opts.mapPageEntry ?? defaultMapPageEntry;
+  if (!SAFE_IDENTIFIER.test(pagesExport)) {
+    throw new Error(`Invalid pagesExportName: "${pagesExport}" \u2014 must be a valid JS identifier`);
+  }
+  if (!SAFE_IDENTIFIER.test(treeExport)) {
+    throw new Error(`Invalid treeExportName: "${treeExport}" \u2014 must be a valid JS identifier`);
+  }
+  if (treeType) {
+    if (!SAFE_IDENTIFIER.test(treeType.name)) {
+      throw new Error(`Invalid treeType.name: "${treeType.name}" \u2014 must be a valid JS identifier`);
+    }
+    if (!SAFE_IMPORT_PATH.test(treeType.from)) {
+      throw new Error(`Invalid treeType.from: "${treeType.from}" \u2014 must be a valid import path`);
+    }
+  }
+  if (pageType) {
+    if (!SAFE_IDENTIFIER.test(pageType.name)) {
+      throw new Error(`Invalid pageType.name: "${pageType.name}" \u2014 must be a valid JS identifier`);
+    }
+    if (!SAFE_IMPORT_PATH.test(pageType.from)) {
+      throw new Error(`Invalid pageType.from: "${pageType.from}" \u2014 must be a valid import path`);
+    }
+  }
+  const pagesEntries = data.pages.map((p) => [
+    p.key,
+    mapEntry(p)
+  ]);
+  const pagesJson = JSON.stringify(pagesEntries, null, "	");
+  const treeJson = JSON.stringify(data.tree, null, "	");
+  const lines = [
+    "// This file is auto-generated by the content-tree plugin. Do not edit."
+  ];
+  if (treeType && pageType && treeType.from === pageType.from) {
+    lines.push(`import type { ${pageType.name}, ${treeType.name} } from "${treeType.from}";`);
+  } else {
+    if (pageType) {
+      lines.push(`import type { ${pageType.name} } from "${pageType.from}";`);
+    }
+    if (treeType) {
+      lines.push(`import type { ${treeType.name} } from "${treeType.from}";`);
+    }
+  }
+  const pagesValueType = pageType ? pageType.name : "Record<string, unknown>";
+  lines.push("");
+  lines.push(`export const ${pagesExport} = new Map<string, ${pagesValueType}>(${pagesJson});`);
+  lines.push("");
+  if (treeType) {
+    lines.push(`export const ${treeExport}: ${treeType.name} = ${treeJson};`);
+  } else {
+    lines.push(`export const ${treeExport} = ${treeJson};`);
+  }
+  const outDir = dirname2(opts.outFile);
+  await mkdir(outDir, { recursive: true });
+  const tmpFile = join2(outDir, `.${randomUUID()}.content-tree.tmp`);
+  try {
+    await writeFile(tmpFile, `${lines.join("\n")}
+`);
+    await rename(tmpFile, opts.outFile);
+  } catch (err) {
+    try {
+      await unlink(tmpFile);
+    } catch {
+    }
+    throw err;
+  }
+}
+async function generate(opts) {
+  const data = await generateData(opts);
+  await writeOutput(opts, data);
+}
+
+// src/plugin.ts
+import { resolve as resolve2 } from "path";
+import { normalizePath } from "vite";
+function contentTreeGeneratorPlugin(opts) {
+  let resolved;
+  const metaFile = opts.metaFile ?? DEFAULT_META_FILE;
+  const pageFile = opts.pageFile ?? DEFAULT_PAGE_FILE;
+  return {
+    name: "content-tree",
+    enforce: "pre",
+    configResolved(config) {
+      resolved = {
+        ...opts,
+        docsDir: normalizePath(resolve2(config.root, opts.docsDir)),
+        outFile: normalizePath(resolve2(config.root, opts.outFile))
+      };
+    },
+    async buildStart() {
+      await generate(resolved);
+    },
+    configureServer(server) {
+      let debounceTimer;
+      let generating = false;
+      let pendingRegeneration = false;
+      async function regenerate() {
+        generating = true;
+        try {
+          await generate(resolved);
+          const mod = server.moduleGraph.getModuleById(resolved.outFile);
+          if (mod) {
+            server.moduleGraph.invalidateModule(mod);
+          }
+          server.hot.send({ type: "full-reload" });
+        } catch (err) {
+          server.config.logger.error(
+            `[content-tree] Generation failed: ${err instanceof Error ? err.message : err}`
+          );
+        } finally {
+          generating = false;
+          if (pendingRegeneration) {
+            pendingRegeneration = false;
+            debounceTimer = setTimeout(regenerate, 150);
+          }
+        }
+      }
+      const handler = (file) => {
+        const normalized = normalizePath(file);
+        if (normalized === resolved.outFile) return;
+        if (normalized.startsWith(`${resolved.docsDir}/`) && (normalized.endsWith(`/${pageFile}`) || normalized.endsWith(`/${metaFile}`))) {
+          if (generating) {
+            pendingRegeneration = true;
+            return;
+          }
+          clearTimeout(debounceTimer);
+          debounceTimer = setTimeout(regenerate, 150);
+        }
+      };
+      server.watcher.on("change", handler);
+      server.watcher.on("add", handler);
+      server.watcher.on("unlink", handler);
+      server.httpServer?.on("close", () => {
+        clearTimeout(debounceTimer);
+      });
+    }
+  };
+}
+export {
+  DEFAULT_META_FILE,
+  DEFAULT_ORDER,
+  DEFAULT_PAGE_FILE,
+  INDEX_SUFFIX,
+  buildChildren,
+  buildPageIndex,
+  contentTreeGeneratorPlugin,
+  defaultMapFrontmatter,
+  defaultResolveDirectoryLabel,
+  generate,
+  generateData,
+  humanize,
+  readDirectoryMeta,
+  resolveModules,
+  scanPages,
+  stripOrder,
+  writeOutput
+};

package/package.json

@@ -0,0 +1,71 @@
+{
+	"name": "@rodavel/vite-plugin-content-tree",
+	"version": "0.1.0",
+	"description": "Vite plugin that scans content directories, extracts frontmatter, and generates a typed navigation tree",
+	"type": "module",
+	"keywords": [
+		"vite",
+		"vite-plugin",
+		"content-tree",
+		"frontmatter",
+		"navigation"
+	],
+	"sideEffects": false,
+	"engines": {
+		"node": ">=18"
+	},
+	"exports": {
+		".": {
+			"import": {
+				"types": "./dist/index.d.ts",
+				"default": "./dist/index.js"
+			},
+			"require": {
+				"types": "./dist/index.d.cts",
+				"default": "./dist/index.cjs"
+			}
+		}
+	},
+	"main": "./dist/index.cjs",
+	"module": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"files": [
+		"dist"
+	],
+	"scripts": {
+		"build": "tsup",
+		"dev": "tsup --watch",
+		"test": "vitest run",
+		"test:watch": "vitest",
+		"typecheck": "tsc --noEmit",
+		"lint": "biome check .",
+		"lint:fix": "biome check --write .",
+		"prepublishOnly": "bun run build && bun run test",
+		"changeset": "changeset",
+		"release": "changeset publish"
+	},
+	"peerDependencies": {
+		"vite": ">=5"
+	},
+	"dependencies": {
+		"gray-matter": "^4.0.3"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "^2.4.8",
+		"@changesets/cli": "^2.30.0",
+		"@types/node": "^25.5.0",
+		"tsup": "^8.4.0",
+		"typescript": "^5.7.0",
+		"vite": "^6.0.0",
+		"vitest": "^3.0.0"
+	},
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/rodavel/vite-plugin-content-tree.git"
+	},
+	"bugs": {
+		"url": "https://github.com/rodavel/vite-plugin-content-tree/issues"
+	},
+	"homepage": "https://github.com/rodavel/vite-plugin-content-tree#readme",
+	"license": "MIT"
+}