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

package/CHANGELOG.md

@@ -5,6 +5,22 @@ 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.1] - 2026-07-03
+
+### Fixed
+
+- Scalar properties with `persist: false` (MikroORM shadow properties) are no longer rendered as if they were real database columns in the ERD or the Markdown column table; `@Formula` columns (also `persist: false` internally) are unaffected and continue to render
+- A self-referencing owning 1:1 relation (e.g. `Node.twin: Node`) no longer renders a redundant self-loop relation edge in addition to the existing `"self-ref"` column comment — now matches the existing self-referencing m:1 behavior
+
+## [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

package/README.ko.md

@@ -1,13 +1,22 @@
 # mikro-orm-markdown
 
+<p align="center">
+  <img src="./assets/logo.png" alt="mikro-orm-markdown logo" width="400" />
+</p>
+
 [MikroORM](https://mikro-orm.io) 엔티티에서 **Mermaid ERD + Markdown 문서**를 자동으로 생성합니다.
 
-[![npm version](https://badge.fury.io/js/mikro-orm-markdown.svg)](https://badge.fury.io/js/mikro-orm-markdown)
+[![npm version](https://img.shields.io/npm/v/mikro-orm-markdown)](https://www.npmjs.com/package/mikro-orm-markdown)
+[![npm downloads](https://img.shields.io/npm/dm/mikro-orm-markdown)](https://www.npmjs.com/package/mikro-orm-markdown)
 [![CI](https://github.com/iamkanguk97/mikro-orm-markdown/actions/workflows/ci.yml/badge.svg)](https://github.com/iamkanguk97/mikro-orm-markdown/actions)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 [English](./README.md)
 
+예시 출력은 [여기](./examples/ERD.md)에서 확인하실 수 있습니다.
+
+Claude Code 또는 기타 Agent Skills 호환 도구를 사용한다면 `skills/mikro-orm-markdown/`의 선택적 Agent Skill로 MikroORM 프로젝트에 `mikro-orm-markdown`을 설정하고 문제를 진단할 수 있습니다. 이 Skill은 필요한 사용자가 저장소에서 가져가 쓰도록 제공되며, 일반적인 npm 사용에는 필요하지 않고 npm 패키지에는 포함되지 않습니다.
+
 > [@samchon](https://github.com/samchon)의 [prisma-markdown](https://github.com/samchon/prisma-markdown)에서 큰 영감을 받았습니다. 좋은 아이디어에 감사드립니다.
 
 ## 주요 기능
@@ -216,7 +225,7 @@ erDiagram
   Post {
     integer id PK
     string title
-    text body
+    string body
     integer author_id FK
   }
   Author {
@@ -453,6 +462,40 @@ erDiagram
 
 > `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

@@ -1,13 +1,22 @@
 # mikro-orm-markdown
 
+<p align="center">
+  <img src="./assets/logo.png" alt="mikro-orm-markdown logo" width="400" />
+</p>
+
 Generate **Mermaid ERD + Markdown documentation** from your [MikroORM](https://mikro-orm.io) entities.
 
-[![npm version](https://badge.fury.io/js/mikro-orm-markdown.svg)](https://badge.fury.io/js/mikro-orm-markdown)
+[![npm version](https://img.shields.io/npm/v/mikro-orm-markdown)](https://www.npmjs.com/package/mikro-orm-markdown)
+[![npm downloads](https://img.shields.io/npm/dm/mikro-orm-markdown)](https://www.npmjs.com/package/mikro-orm-markdown)
 [![CI](https://github.com/iamkanguk97/mikro-orm-markdown/actions/workflows/ci.yml/badge.svg)](https://github.com/iamkanguk97/mikro-orm-markdown/actions)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 [한국어 문서](./README.ko.md)
 
+You can see the example output [here](./examples/ERD.md).
+
+Agent users can also use the optional Agent Skill at `skills/mikro-orm-markdown/` with Claude Code or other Agent Skills-compatible tools to set up and troubleshoot `mikro-orm-markdown` in a MikroORM project. The skill is provided in this repository for users who want it; it is not required for normal npm usage and is not shipped in the npm package.
+
 > Heavily inspired by [prisma-markdown](https://github.com/samchon/prisma-markdown) by [@samchon](https://github.com/samchon). Thank you for the great idea.
 
 ## Features
@@ -216,7 +225,7 @@ erDiagram
   Post {
     integer id PK
     string title
-    text body
+    string body
     integer author_id FK
   }
   Author {
@@ -453,6 +462,43 @@ erDiagram
 
 > 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 = [];
@@ -342,6 +353,9 @@ function buildColumns(prop, metaByClass, owningMeta) {
       return [];
     }
     const formulaExpr = prop.formula !== void 0 ? resolveFormulaExpr(prop.formula) : void 0;
+    if (prop.persist === false && formulaExpr === void 0) {
+      return [];
+    }
     let embeddedIn;
     let embeddedPropName;
     if (prop.embedded !== void 0) {
@@ -528,6 +542,9 @@ function buildEdge(fromEntity, prop) {
     };
   }
   if (prop.kind === import_core2.ReferenceKind.ONE_TO_ONE && prop.owner === true) {
+    if (prop.type === fromEntity) {
+      return null;
+    }
     return {
       fromEntity,
       toEntity: prop.type,
@@ -776,7 +793,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
@@ -806,7 +824,7 @@ function renderMarkdown(docModel, mermaid) {
     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, mermaid));
@@ -820,12 +838,31 @@ 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 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) {
@@ -992,7 +1029,7 @@ async function generateMarkdown(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);
   }