mikro-orm-markdown 0.1.0-alpha.3 → 0.1.0-alpha.5

package/CHANGELOG.md

@@ -5,6 +5,28 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.1.0-alpha.5] - 2026-06-29
+
+### Added
+
+- `--mermaid-layout <layout>` and `--mermaid-theme <theme>` CLI options to inject Mermaid YAML frontmatter into each `erDiagram` fence
+- `mermaid` option in the programmatic API (`generateMarkdown({ mermaid: { layout, theme } })`) with the same effect
+- `MermaidLayout`, `MermaidTheme`, and `MermaidRenderOptions` types exported from the public API
+- When neither option is set, output is identical to previous versions — no frontmatter is emitted
+
+## [0.1.0-alpha.4] - 2026-06-29
+
+### Fixed
+
+- `resolveScalarType` now preserves composite primary-key column alignment through FK-as-PK chains
+- `resolveScalarType` now falls back to `integer` after depth 5 instead of leaking an entity class name
+- Cross-namespace ERD filtering now treats `@describe` as a home namespace when checking `@erd` guests
+- Cross-namespace ERD guest entities with no visible primary-key columns are excluded instead of rendering empty boxes
+
+### Changed
+
+- Markdown tables and Mermaid ERDs now render database-specific scalar types as generic, database-agnostic types
+
 ## [0.1.0-alpha.3] - 2026-06-29
 
 ### Added

package/README.ko.md

@@ -79,6 +79,8 @@ npm run erd
 | `-d, --description <string>` | —           | 제목 아래에 표시할 설명 문단 (선택)                                   |
 | `--tsconfig <path>`    | —                 | `.ts` config 로드 시 사용할 `tsconfig.json`; 기본값은 config 파일 근처의 가장 가까운 파일 |
 | `--src <paths...>`     | —                 | 원본 TypeScript 엔티티 소스 경로/glob; MikroORM이 컴파일된 JavaScript에서 엔티티를 discovery할 때만 필요 |
+| `--mermaid-layout <layout>` | —           | Mermaid 레이아웃 엔진 (`dagre\|elk\|elk.stress`). 생략하면 뷰어 기본값 사용. |
+| `--mermaid-theme <theme>`   | —           | Mermaid 테마 (`default\|neutral\|dark\|forest\|base`). 생략하면 뷰어 기본값 사용. |
 
 > 설명이 길거나 여러 줄이라면 CLI 대신 [프로그래밍 API](#프로그래밍-api)를 사용하세요 — 쉘 인용 부호 제약 없이 문자열을 그대로 전달할 수 있습니다.
 
@@ -392,6 +394,7 @@ await writeFile('./ERD.md', markdown, 'utf-8');
 | `description` | 제목 아래에 표시할 설명 문단입니다. CLI flag와 달리 쉘 quoting 제약 없이 문자열을 그대로 전달할 수 있습니다. |
 | `src` | 원본 TypeScript 엔티티 소스 경로/glob입니다. `orm.entities`가 컴파일된 JavaScript를 discovery할 때만 필요합니다. |
 | `onWarn` | 컴파일된 JavaScript에서 JSDoc을 읽지 못하는 상황 같은 non-fatal warning을 받을 callback입니다. |
+| `mermaid` | Mermaid 렌더링 옵션입니다. 아래 [Mermaid 렌더링 옵션](#mermaid-렌더링-옵션)을 참고하세요. |
 
 MikroORM config를 비동기적으로 만들어야 한다면 직접 resolve한 뒤 결과 options object를 전달하세요:
 
@@ -400,6 +403,56 @@ const ormConfig = await createOrmConfig();
 const markdown = await generateMarkdown({ orm: ormConfig });
 ```
 
+### Mermaid 렌더링 옵션
+
+기본적으로 mikro-orm-markdown은 Mermaid frontmatter config를 출력하지 않습니다. 이렇게 해야 각 Markdown 뷰어의 기본 Mermaid 렌더링 동작이 유지됩니다.
+
+CLI에서 Mermaid 렌더링 옵션을 사용하려면:
+
+```bash
+mikro-orm-markdown --config ./mikro-orm.config.ts --mermaid-layout elk
+mikro-orm-markdown --config ./mikro-orm.config.ts --mermaid-theme forest
+mikro-orm-markdown --config ./mikro-orm.config.ts --mermaid-layout elk --mermaid-theme neutral
+```
+
+프로그래밍 API에서는:
+
+```typescript
+const markdown = await generateMarkdown({
+  orm: ormConfig,
+  mermaid: {
+    layout: 'elk',
+    theme: 'forest',
+  },
+});
+```
+
+layout 또는 theme을 지정하면 각 `erDiagram` 펜스 앞에 YAML frontmatter 블록이 삽입됩니다:
+
+````markdown
+```mermaid
+---
+config:
+  layout: elk
+  theme: forest
+---
+erDiagram
+  ...
+```
+````
+
+**사용 가능한 layout 값:**
+
+| 값 | 설명 |
+| -- | ---- |
+| `dagre` | Mermaid 기본 레이아웃 엔진. |
+| `elk` | 대체 레이아웃 엔진. 엔티티가 많거나 관계선이 복잡한 ERD에서 선 라우팅을 개선할 수 있습니다. |
+| `elk.stress` | ELK stress 레이아웃 변형. Mermaid 버전과 뷰어에 따라 지원 여부가 다릅니다. |
+
+**사용 가능한 theme 값:** `default`, `neutral`, `dark`, `forest`, `base`.
+
+> `elk`와 theme 지원 여부는 뷰어마다 다릅니다. `--mermaid-layout`이나 `--mermaid-theme`을 지정하지 않으면 frontmatter는 출력되지 않습니다.
+
 ## 라이선스
 
 MIT

package/README.md

@@ -79,6 +79,8 @@ npm run erd
 | `-d, --description <string>` | —           | Optional description paragraph shown below the title                            |
 | `--tsconfig <path>`    | —                 | `tsconfig.json` used when loading a `.ts` config; defaults to the nearest one beside the config file |
 | `--src <paths...>`     | —                 | Original TypeScript entity source paths/globs; only needed when MikroORM discovers entities from compiled JavaScript |
+| `--mermaid-layout <layout>` | —            | Mermaid layout engine (`dagre\|elk\|elk.stress`). Omit to use the viewer's default. |
+| `--mermaid-theme <theme>`   | —            | Mermaid theme (`default\|neutral\|dark\|forest\|base`). Omit to use the viewer's default. |
 
 > For a long or multiline description, use the [programmatic API](#programmatic-api) instead — it accepts any string directly, without shell quoting limits.
 
@@ -392,6 +394,7 @@ Programmatic options:
 | `description` | Optional paragraph below the title. Unlike the CLI flag, this can be any string without shell quoting concerns. |
 | `src` | Original TypeScript entity source paths/globs. Only needed when `orm.entities` discovers compiled JavaScript. |
 | `onWarn` | Callback for non-fatal warnings, such as compiled JavaScript JSDoc loss. |
+| `mermaid` | Optional Mermaid rendering options. See [Mermaid rendering options](#mermaid-rendering-options) below. |
 
 If your MikroORM config is asynchronous, resolve it yourself and pass the resulting options object:
 
@@ -400,6 +403,56 @@ const ormConfig = await createOrmConfig();
 const markdown = await generateMarkdown({ orm: ormConfig });
 ```
 
+### Mermaid rendering options
+
+By default, mikro-orm-markdown does not emit Mermaid frontmatter config. This preserves each Markdown viewer's default Mermaid rendering behavior.
+
+You can opt into Mermaid rendering options via the CLI:
+
+```bash
+mikro-orm-markdown --config ./mikro-orm.config.ts --mermaid-layout elk
+mikro-orm-markdown --config ./mikro-orm.config.ts --mermaid-theme forest
+mikro-orm-markdown --config ./mikro-orm.config.ts --mermaid-layout elk --mermaid-theme neutral
+```
+
+Or via the programmatic API:
+
+```typescript
+const markdown = await generateMarkdown({
+  orm: ormConfig,
+  mermaid: {
+    layout: 'elk',
+    theme: 'forest',
+  },
+});
+```
+
+When a layout or theme is set, a YAML frontmatter block is prepended to each `erDiagram` fence:
+
+````markdown
+```mermaid
+---
+config:
+  layout: elk
+  theme: forest
+---
+erDiagram
+  ...
+```
+````
+
+**Available layout values:**
+
+| Value | Description |
+| ----- | ----------- |
+| `dagre` | Mermaid's default layered layout. |
+| `elk` | Alternative layout engine; can improve line routing on larger or denser ERDs. |
+| `elk.stress` | ELK stress layout variant. Support varies by Mermaid version and viewer. |
+
+**Available theme values:** `default`, `neutral`, `dark`, `forest`, `base`.
+
+> Viewer support for `elk` and theme values varies. If no `--mermaid-layout` or `--mermaid-theme` is provided, no frontmatter is emitted.
+
 ## License
 
 MIT

package/dist/cli.cjs

@@ -281,6 +281,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: "",
@@ -419,9 +421,31 @@ function resolveFkTypes(prop, metaByClass, fieldNameCount) {
   return Array.from({ length: fieldNameCount }, (_value, index) => {
     const referencedColumnName = referencedColumnNames[index];
     const pkProp = referencedColumnName !== void 0 ? primaryProps.find((candidate) => candidate.fieldNames.includes(referencedColumnName)) : void 0;
-    return (pkProp ?? primaryProps[index] ?? primaryProps[0])?.type ?? "integer";
+    const resolvedProp = pkProp ?? primaryProps[index] ?? primaryProps[0];
+    const rawType = resolvedProp?.type ?? "integer";
+    const pkIndex = resolvedProp !== void 0 ? primaryProps.indexOf(resolvedProp) : 0;
+    return resolveScalarType(rawType, metaByClass, pkIndex);
   });
 }
+function resolveScalarType(type, metaByClass, pkIndex = 0, depth = 0) {
+  if (depth >= 5) {
+    return "integer";
+  }
+  const refMeta = metaByClass.get(type);
+  if (!refMeta) {
+    return type;
+  }
+  const primaryProps = getPrimaryProps(refMeta);
+  if (primaryProps.length === 0) {
+    return type;
+  }
+  const targetProp = primaryProps[pkIndex] ?? primaryProps[0];
+  const nextType = targetProp?.type ?? type;
+  if (nextType === type) {
+    return type;
+  }
+  return resolveScalarType(nextType, metaByClass, pkIndex, depth + 1);
+}
 function getPrimaryProps(meta) {
   const primaryKeys = meta.primaryKeys ?? [];
   const orderedPrimaryProps = primaryKeys.map((key) => meta.properties[String(key)]).filter((prop) => prop !== void 0);
@@ -523,8 +547,41 @@ function buildEdge(fromEntity, prop) {
   }
   return null;
 }
-function renderErDiagram(model) {
-  const lines = ["erDiagram"];
+function normalizeType(type) {
+  const t = type.toLowerCase().trim();
+  if (t === "uuid" || t === "text" || t === "string" || t.startsWith("varchar")) {
+    return "string";
+  }
+  if (t === "timestamptz" || t === "timestamp" || t === "datetime") {
+    return "datetime";
+  }
+  if (t === "integer" || t === "int" || t === "bigint" || t === "smallint") {
+    return "integer";
+  }
+  if (t === "doubletype" || t === "double precision" || t === "double" || t === "float" || t === "decimal") {
+    return "float";
+  }
+  if (t === "boolean" || t === "bool") {
+    return "boolean";
+  }
+  if (t === "jsonb") {
+    return "json";
+  }
+  return type;
+}
+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) {
@@ -557,7 +614,7 @@ function renderColumnLine(col) {
     comment = "self-ref";
   }
   const commentStr = comment !== void 0 ? ` "${escapeMermaidQuotedText(comment)}"` : "";
-  return `${toMermaidIdentifier(col.type)} ${toMermaidIdentifier(col.fieldName)}${qualifier}${commentStr}`;
+  return `${toMermaidIdentifier(normalizeType(col.type))} ${toMermaidIdentifier(col.fieldName)}${qualifier}${commentStr}`;
 }
 
 // src/model/build.ts
@@ -604,9 +661,16 @@ function buildDocumentModel(metas, jsDocResult, title, description, onWarn) {
   const groups = [];
   for (const groupName of groupNames) {
     const isDefault = groupName === "default";
-    const erdEntities = [...enrichedByClass.values()].filter(
-      ({ jsDoc }) => belongsToGroupForErd(jsDoc, groupName, isDefault)
-    );
+    const erdEntities = [...enrichedByClass.values()].filter(({ jsDoc }) => belongsToGroupForErd(jsDoc, groupName, isDefault)).map((entity) => {
+      if (isCrossNamespaceInGroup(entity.jsDoc, groupName, isDefault)) {
+        const pkColumns = entity.model.columns.filter((col) => col.isPrimary);
+        if (pkColumns.length === 0) {
+          return null;
+        }
+        return { ...entity, model: { ...entity.model, columns: pkColumns } };
+      }
+      return entity;
+    }).filter((entity) => entity !== null);
     const textEntities = [...enrichedByClass.values()].filter(
       ({ jsDoc }) => belongsToGroupForText(jsDoc, groupName, isDefault)
     );
@@ -708,6 +772,12 @@ function belongsToGroupForText(jsDoc, groupName, isDefault) {
   }
   return jsDoc.namespaces.includes(groupName) || jsDoc.describeNamespaces.includes(groupName);
 }
+function isCrossNamespaceInGroup(jsDoc, groupName, isDefault) {
+  if (isDefault || !jsDoc) {
+    return false;
+  }
+  return jsDoc.erdNamespaces.includes(groupName) && !jsDoc.namespaces.includes(groupName) && !jsDoc.describeNamespaces.includes(groupName);
+}
 
 // src/provider.ts
 async function withTsMorphMetadataProvider(options, onWarn) {
@@ -730,7 +800,7 @@ 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));
@@ -739,7 +809,7 @@ function renderMarkdown(docModel) {
     sections.push(renderTableOfContents(docModel.groups));
   }
   for (const group of docModel.groups) {
-    sections.push(renderGroupSection(group));
+    sections.push(renderGroupSection(group, mermaid));
   }
   return sections.join("\n\n");
 }
@@ -756,14 +826,14 @@ function renderTableOfContents(groups) {
     return `- [${label}](#${toMarkdownAnchor(group.name)})`;
   });
 }
-function renderGroupSection(group) {
+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));
@@ -805,7 +875,7 @@ function renderColumnTable(entity) {
     const docDesc = entity.propDocs.get(col.propName)?.description ?? col.comment ?? "";
     const enumDesc = col.enumItems !== void 0 ? `One of: ${col.enumItems.join(", ")}` : "";
     const desc = [docDesc, enumDesc].filter((part) => part !== "").join("\n");
-    return `| ${escapeMarkdownTableCell(col.fieldName)} | ${escapeMarkdownTableCell(col.type)} | ${escapeMarkdownTableCell(key)} | ${nullable} | ${escapeMarkdownTableCell(desc)} |`;
+    return `| ${escapeMarkdownTableCell(col.fieldName)} | ${escapeMarkdownTableCell(normalizeType(col.type))} | ${escapeMarkdownTableCell(key)} | ${nullable} | ${escapeMarkdownTableCell(desc)} |`;
   });
   return [header, sep, ...rows].join("\n");
 }
@@ -919,7 +989,7 @@ 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));
@@ -927,7 +997,7 @@ async function generateMarkdown(options) {
     assertExplicitJsDocSourceCoverage(metas, jsDocResult, src, onWarn);
   }
   const docModel = buildDocumentModel(metas, jsDocResult, title, description, onWarn);
-  return renderMarkdown(docModel);
+  return renderMarkdown(docModel, mermaid);
 }
 
 // src/cli.ts
@@ -1042,9 +1112,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);
@@ -1063,6 +1158,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}
 `)
     });
@@ -1087,7 +1183,7 @@ var program = new import_commander.Command().name("mikro-orm-markdown").descript
 ).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) {