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

package/CHANGELOG.md

@@ -5,6 +5,24 @@ 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] - 2026-06-30
+
+First stable release. All alpha features are considered production-ready.
+
+### Added
+
+- `AGENTS.md` with project overview, source layout, development commands, and conventions for AI agent context
+- Planned Features section in README (en/ko) documenting `--check` mode, `--watch` mode, and `EntitySchema` support as upcoming work
+
+## [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

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)를 사용하세요 — 쉘 인용 부호 제약 없이 문자열을 그대로 전달할 수 있습니다.
 
@@ -214,7 +216,7 @@ erDiagram
   Post {
     integer id PK
     string title
-    text body
+    string body
     integer author_id FK
   }
   Author {
@@ -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,90 @@ 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는 출력되지 않습니다.
+
+## 추후 구현 예정 기능
+
+다음 기능들은 향후 릴리즈에서 지원할 예정입니다.
+
+### `--check` 모드
+
+출력 파일이 현재 엔티티 메타데이터와 다를 경우 non-zero 코드로 종료하는 `--check` 플래그입니다. 파일을 직접 수정하지 않으며, CI 파이프라인에서 `ERD.md`가 엔티티 변경 사항과 함께 항상 커밋되었는지 검증하는 용도로 사용합니다.
+
+```bash
+mikro-orm-markdown --config ./mikro-orm.config.ts --check
+```
+
+### `--watch` 모드
+
+엔티티 소스 파일을 감지하여 변경이 발생할 때마다 출력 문서를 자동으로 재생성하는 `--watch` 플래그입니다. CLI를 매번 수동으로 실행하지 않아도 ERD를 최신 상태로 유지할 수 있어 개발 중에 유용합니다.
+
+```bash
+mikro-orm-markdown --config ./mikro-orm.config.ts --watch
+```
+
+### `EntitySchema` 지원
+
+현재는 decorator 기반 엔티티(`@Entity()` 클래스)만 지원합니다. 향후 릴리즈에서는 TypeScript decorator 없이 Plain Object로 스키마를 정의하는 [`EntitySchema`](https://mikro-orm.io/docs/entity-schema) 방식도 지원할 예정입니다.
+
+```typescript
+const PostSchema = new EntitySchema({
+  name: 'Post',
+  properties: {
+    id: { primary: true, type: 'integer' },
+    title: { type: 'string' },
+  },
+});
+```
+
 ## 라이선스
 
 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.
 
@@ -214,7 +216,7 @@ erDiagram
   Post {
     integer id PK
     string title
-    text body
+    string body
     integer author_id FK
   }
   Author {
@@ -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,93 @@ 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.
+
+## Planned Features
+
+The following features are planned for future releases.
+
+### `--check` mode
+
+A `--check` flag that exits with a non-zero code when the output file is out of sync with the current entity metadata — without writing any files.
+Intended for CI pipelines to enforce that `ERD.md` is always committed alongside entity changes.
+
+```bash
+mikro-orm-markdown --config ./mikro-orm.config.ts --check
+```
+
+### `--watch` mode
+
+A `--watch` flag that monitors entity source files and regenerates the output document automatically on each change.
+Useful during active development when you want the ERD to stay current without running the CLI manually.
+
+```bash
+mikro-orm-markdown --config ./mikro-orm.config.ts --watch
+```
+
+### `EntitySchema` support
+
+Currently only decorator-based entities (`@Entity()` classes) are supported.
+A future release will add support for [`EntitySchema`](https://mikro-orm.io/docs/entity-schema)-defined entities, which describe the schema as a plain object without TypeScript decorators.
+
+```typescript
+const PostSchema = new EntitySchema({
+  name: 'Post',
+  properties: {
+    id: { primary: true, type: 'integer' },
+    title: { type: 'string' },
+  },
+});
+```
+
 ## License
 
 MIT

package/dist/cli.cjs

@@ -53,7 +53,7 @@ var import_commander = require("commander");
 
 // src/docs/jsdoc.ts
 var import_ts_morph = require("ts-morph");
-function loadJsDoc(filePaths) {
+function loadJsDoc(filePaths, onWarn) {
   const entities = /* @__PURE__ */ new Map();
   const props = /* @__PURE__ */ new Map();
   const classNames = /* @__PURE__ */ new Set();
@@ -70,8 +70,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();
@@ -102,11 +106,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 = [];
@@ -281,6 +292,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: "",
@@ -567,8 +580,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) {
@@ -763,7 +787,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
@@ -787,16 +812,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");
 }
@@ -807,20 +832,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));
@@ -976,15 +1020,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
@@ -1099,9 +1143,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);
@@ -1120,6 +1189,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}
 `)
     });
@@ -1144,7 +1214,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) {