mikro-orm-markdown 0.1.0-alpha.4 → 0.1.0

package/dist/cli.js

@@ -9,7 +9,7 @@ import { Command } from "commander";
 
 // src/docs/jsdoc.ts
 import { Project } from "ts-morph";
-function loadJsDoc(filePaths) {
+function loadJsDoc(filePaths, onWarn) {
   const entities = /* @__PURE__ */ new Map();
   const props = /* @__PURE__ */ new Map();
   const classNames = /* @__PURE__ */ new Set();
@@ -26,8 +26,12 @@ function loadJsDoc(filePaths) {
   });
   for (const filePath of filePaths) {
     try {
-      project.addSourceFilesAtPaths(filePath);
-    } catch {
+      const sourceFiles2 = project.addSourceFilesAtPaths(filePath);
+      if (sourceFiles2.length === 0 && !hasGlobPattern(filePath)) {
+        onWarn?.(`No JSDoc source file matched path: ${filePath}`);
+      }
+    } catch (err) {
+      onWarn?.(`Could not load JSDoc source path "${filePath}": ${formatUnknownError(err)}`);
     }
   }
   const sourceFiles = project.getSourceFiles();
@@ -58,11 +62,18 @@ function loadJsDoc(filePaths) {
           props.set(className, propMap);
         }
       }
-    } catch {
+    } catch (err) {
+      onWarn?.(`Could not parse JSDoc source file "${sourceFile.getFilePath()}": ${formatUnknownError(err)}`);
     }
   }
   return { entities, props, sourceFileCount: sourceFiles.length, classNames };
 }
+function formatUnknownError(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+function hasGlobPattern(filePath) {
+  return /[*?[\]{}]/.test(filePath);
+}
 function parseEntityJsDoc(jsDocs) {
   const namespaces = [];
   const erdNamespaces = [];
@@ -237,6 +248,8 @@ function toMarkdownAnchor(value) {
 }
 
 // src/render/mermaid.ts
+var MERMAID_LAYOUTS = ["dagre", "elk", "elk.stress"];
+var MERMAID_THEMES = ["default", "neutral", "dark", "forest", "base"];
 var FORMULA_DUMMY_TABLE = {
   alias: "e0",
   name: "",
@@ -523,8 +536,19 @@ function normalizeType(type) {
   }
   return type;
 }
-function renderErDiagram(model) {
-  const lines = ["erDiagram"];
+function renderErDiagram(model, mermaid) {
+  const lines = [];
+  if (mermaid?.layout !== void 0 || mermaid?.theme !== void 0) {
+    lines.push("---", "config:");
+    if (mermaid.layout !== void 0) {
+      lines.push(`  layout: ${mermaid.layout}`);
+    }
+    if (mermaid.theme !== void 0) {
+      lines.push(`  theme: ${mermaid.theme}`);
+    }
+    lines.push("---");
+  }
+  lines.push("erDiagram");
   for (const entity of model.entities) {
     lines.push(`  ${toMermaidIdentifier(entity.className)} {`);
     for (const col of entity.columns) {
@@ -719,7 +743,8 @@ function isCrossNamespaceInGroup(jsDoc, groupName, isDefault) {
   if (isDefault || !jsDoc) {
     return false;
   }
-  return jsDoc.erdNamespaces.includes(groupName) && !jsDoc.namespaces.includes(groupName) && !jsDoc.describeNamespaces.includes(groupName);
+  const hasHomeNamespace = jsDoc.namespaces.length > 0 || jsDoc.describeNamespaces.length > 0;
+  return hasHomeNamespace && jsDoc.erdNamespaces.includes(groupName) && !jsDoc.namespaces.includes(groupName) && !jsDoc.describeNamespaces.includes(groupName);
 }
 
 // src/provider.ts
@@ -743,16 +768,16 @@ async function withTsMorphMetadataProvider(options, onWarn) {
 }
 
 // src/render/markdown.ts
-function renderMarkdown(docModel) {
+function renderMarkdown(docModel, mermaid) {
   const sections = [`# ${escapeMarkdownInline(docModel.title)}`];
   if (docModel.description) {
     sections.push(escapeMarkdownParagraph(docModel.description));
   }
   if (docModel.groups.length > 1) {
-    sections.push(renderTableOfContents(docModel.groups));
+    sections.push(renderTableOfContents(docModel.groups, resolveGroupAnchors(docModel)));
   }
   for (const group of docModel.groups) {
-    sections.push(renderGroupSection(group));
+    sections.push(renderGroupSection(group, mermaid));
   }
   return sections.join("\n\n");
 }
@@ -763,20 +788,39 @@ function renderBulletSection(header, items, renderItem) {
   }
   return lines.join("\n");
 }
-function renderTableOfContents(groups) {
+function renderTableOfContents(groups, anchors) {
   return renderBulletSection("## Contents", groups, (group) => {
     const label = escapeMarkdownInline(group.name).replace(/[[\]]/g, "\\$&");
-    return `- [${label}](#${toMarkdownAnchor(group.name)})`;
+    return `- [${label}](#${anchors.get(group) ?? toMarkdownAnchor(group.name)})`;
   });
 }
-function renderGroupSection(group) {
+function resolveGroupAnchors(docModel) {
+  const seenAnchors = /* @__PURE__ */ new Map();
+  const groupAnchors = /* @__PURE__ */ new Map();
+  resolveHeadingAnchor(docModel.title, seenAnchors);
+  resolveHeadingAnchor("Contents", seenAnchors);
+  for (const group of docModel.groups) {
+    groupAnchors.set(group, resolveHeadingAnchor(group.name, seenAnchors));
+    for (const entity of group.textEntities) {
+      resolveHeadingAnchor(entity.model.className, seenAnchors);
+    }
+  }
+  return groupAnchors;
+}
+function resolveHeadingAnchor(value, seenAnchors) {
+  const baseAnchor = toMarkdownAnchor(value);
+  const previousCount = seenAnchors.get(baseAnchor) ?? 0;
+  seenAnchors.set(baseAnchor, previousCount + 1);
+  return previousCount === 0 ? baseAnchor : `${baseAnchor}-${previousCount}`;
+}
+function renderGroupSection(group, mermaid) {
   const parts = [`## ${escapeMarkdownInline(group.name)}`];
   if (group.erdEntities.length > 0) {
     const diagramModel = {
       entities: group.erdEntities.map((e) => e.model),
       relations: group.erdRelations
     };
-    parts.push("```mermaid\n" + renderErDiagram(diagramModel) + "\n```");
+    parts.push("```mermaid\n" + renderErDiagram(diagramModel, mermaid) + "\n```");
   }
   for (const entity of group.textEntities) {
     parts.push(renderEntitySection(entity));
@@ -932,15 +976,15 @@ async function loadEntityMetadataWithTsMorphFallback(originalOrm, effectiveOrm)
   }
 }
 async function generateMarkdown(options) {
-  const { orm, title = "Database Schema", description, src, onWarn } = options;
+  const { orm, title = "Database Schema", description, src, onWarn, mermaid } = options;
   const effectiveOrm = await withTsMorphMetadataProvider(orm, onWarn);
   const { metas, sourcePaths } = await loadEntityMetadataWithTsMorphFallback(orm, effectiveOrm);
-  const jsDocResult = loadJsDoc(resolveJsDocSources(sourcePaths, src, onWarn));
+  const jsDocResult = loadJsDoc(resolveJsDocSources(sourcePaths, src, onWarn), onWarn);
   if (src !== void 0 && src.length > 0) {
     assertExplicitJsDocSourceCoverage(metas, jsDocResult, src, onWarn);
   }
   const docModel = buildDocumentModel(metas, jsDocResult, title, description, onWarn);
-  return renderMarkdown(docModel);
+  return renderMarkdown(docModel, mermaid);
 }
 
 // src/cli.ts
@@ -1055,9 +1099,34 @@ async function writeMarkdownFile(outPath, markdown) {
 ${formatFileSystemError(cause)}`, { cause });
   }
 }
+function parseMermaidOptions(opts) {
+  const { mermaidLayout, mermaidTheme } = opts;
+  if (mermaidLayout !== void 0 && !MERMAID_LAYOUTS.includes(mermaidLayout)) {
+    process.stderr.write(
+      `Error: Invalid --mermaid-layout "${mermaidLayout}". Allowed values: ${MERMAID_LAYOUTS.join(", ")}
+`
+    );
+    process.exit(1);
+  }
+  if (mermaidTheme !== void 0 && !MERMAID_THEMES.includes(mermaidTheme)) {
+    process.stderr.write(
+      `Error: Invalid --mermaid-theme "${mermaidTheme}". Allowed values: ${MERMAID_THEMES.join(", ")}
+`
+    );
+    process.exit(1);
+  }
+  if (mermaidLayout === void 0 && mermaidTheme === void 0) {
+    return void 0;
+  }
+  return {
+    ...mermaidLayout !== void 0 && { layout: mermaidLayout },
+    ...mermaidTheme !== void 0 && { theme: mermaidTheme }
+  };
+}
 async function run(opts) {
   const configPath = path2.resolve(opts.config);
   const outPath = path2.resolve(opts.out);
+  const mermaid = parseMermaidOptions(opts);
   let ormOptions;
   try {
     ormOptions = await loadOrmOptions(configPath, opts.tsconfig);
@@ -1076,6 +1145,7 @@ ${err instanceof Error ? err.message : String(err)}
       title: opts.title,
       ...opts.description !== void 0 && { description: opts.description },
       ...opts.src !== void 0 && { src: opts.src },
+      ...mermaid !== void 0 && { mermaid },
       onWarn: (message) => void process.stderr.write(`Warning: ${message}
 `)
     });
@@ -1100,7 +1170,7 @@ var program = new Command().name("mikro-orm-markdown").description("Generate Mer
 ).option(
   "--src <paths...>",
   "Source .ts file globs to read JSDoc from when entities run from compiled .js (comments are stripped at build time)"
-).action(run);
+).option("--mermaid-layout <layout>", `Mermaid layout engine injected as frontmatter (${MERMAID_LAYOUTS.join("|")})`).option("--mermaid-theme <theme>", `Mermaid theme injected as frontmatter (${MERMAID_THEMES.join("|")})`).action(run);
 function isDirectCliExecution() {
   const entryPoint = process.argv[1];
   if (entryPoint === void 0) {