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

package/CHANGELOG.md

@@ -5,6 +5,15 @@ 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

package/README.ko.md

@@ -216,7 +216,7 @@ erDiagram
   Post {
     integer id PK
     string title
-    text body
+    string body
     integer author_id FK
   }
   Author {
@@ -453,6 +453,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

@@ -216,7 +216,7 @@ erDiagram
   Post {
     integer id PK
     string title
-    text body
+    string body
     integer author_id FK
   }
   Author {
@@ -453,6 +453,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 = [];
@@ -776,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
@@ -806,7 +818,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 +832,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 +1023,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);
   }