mikro-orm-markdown 0.1.0 → 0.1.2

package/dist/index.js

@@ -1,5 +1,5 @@
 // src/docs/jsdoc.ts
-import { Project } from "ts-morph";
+import { Project, ts } from "ts-morph";
 function loadJsDoc(filePaths, onWarn) {
   const entities = /* @__PURE__ */ new Map();
   const props = /* @__PURE__ */ new Map();
@@ -38,17 +38,7 @@ function loadJsDoc(filePaths, onWarn) {
         if (classDocs.length > 0) {
           entities.set(className, parseEntityJsDoc(classDocs));
         }
-        const propMap = /* @__PURE__ */ new Map();
-        for (const prop of cls.getProperties()) {
-          const propDocs = prop.getJsDocs();
-          if (propDocs.length === 0) {
-            continue;
-          }
-          const info = parsePropJsDoc(propDocs);
-          if (info.description !== void 0 || info.atLeastOne) {
-            propMap.set(prop.getName(), info);
-          }
-        }
+        const propMap = collectPropJsDocs(cls);
         if (propMap.size > 0) {
           props.set(className, propMap);
         }
@@ -65,6 +55,28 @@ function formatUnknownError(err) {
 function hasGlobPattern(filePath) {
   return /[*?[\]{}]/.test(filePath);
 }
+function collectPropJsDocs(cls) {
+  const propMap = /* @__PURE__ */ new Map();
+  for (const prop of [...cls.getProperties(), ...cls.getGetAccessors()]) {
+    const info = parsePropJsDoc(prop.getJsDocs());
+    addPropInfo(propMap, prop.getName(), info);
+  }
+  for (const prop of getConstructorParameterProperties(cls)) {
+    const info = parseCompilerPropJsDoc(ts.getJSDocCommentsAndTags(prop.compilerNode));
+    addPropInfo(propMap, prop.getName(), info);
+  }
+  return propMap;
+}
+function getConstructorParameterProperties(cls) {
+  return cls.getConstructors().flatMap(
+    (constructorDeclaration) => constructorDeclaration.getParameters().filter((param) => param.isParameterProperty())
+  );
+}
+function addPropInfo(propMap, propName, info) {
+  if (info.description !== void 0 || info.atLeastOne) {
+    propMap.set(propName, info);
+  }
+}
 function parseEntityJsDoc(jsDocs) {
   const namespaces = [];
   const erdNamespaces = [];
@@ -114,10 +126,39 @@ function parsePropJsDoc(jsDocs) {
   }
   return { ...description !== void 0 && { description }, atLeastOne };
 }
+function parseCompilerPropJsDoc(jsDocs) {
+  let description;
+  let atLeastOne = false;
+  for (const doc of jsDocs) {
+    if (ts.isJSDoc(doc)) {
+      const desc = formatCompilerJsDocComment(doc.comment);
+      if (desc && description === void 0) {
+        description = desc;
+      }
+      for (const tag of doc.tags ?? []) {
+        if (tag.tagName.getText() === "atLeastOne") {
+          atLeastOne = true;
+        }
+      }
+      continue;
+    }
+    if (doc.tagName.getText() === "atLeastOne") {
+      atLeastOne = true;
+    }
+  }
+  return { ...description !== void 0 && { description }, atLeastOne };
+}
+function formatCompilerJsDocComment(comment) {
+  if (comment === void 0) {
+    return void 0;
+  }
+  const trimmed = ts.getTextOfJSDocComment(comment)?.trim();
+  return trimmed === void 0 || trimmed === "" ? void 0 : trimmed;
+}
 
 // src/metadata/load.ts
 import * as path from "path";
-import { EntitySchema, MikroORM } from "@mikro-orm/core";
+import { EntitySchema, MetadataStorage, MikroORM } from "@mikro-orm/core";
 var MetadataLoadError = class extends Error {
   constructor(message, cause) {
     super(message);
@@ -153,6 +194,44 @@ function assertNoEntitySchemaEntities(options) {
 Use decorator-based @Entity() classes instead.`
   );
 }
+function hasDecoratorMarker(target) {
+  const pathSymbol = MetadataStorage.PATH_SYMBOL;
+  if (typeof pathSymbol === "symbol" && pathSymbol in target) {
+    return true;
+  }
+  return "__path" in target;
+}
+function isRenderableMeta(meta) {
+  return !meta.pivotTable && !meta.embeddable;
+}
+function assertDiscoveredEntitiesAreSupported(metas) {
+  const confirmed = [];
+  const unconfirmed = [];
+  for (const meta of metas) {
+    if (!isRenderableMeta(meta)) {
+      continue;
+    }
+    if (EntitySchema.REGISTRY.has(meta.class)) {
+      confirmed.push(meta.className);
+    } else if (!hasDecoratorMarker(meta.class)) {
+      unconfirmed.push(meta.className);
+    }
+  }
+  if (confirmed.length === 0 && unconfirmed.length === 0) {
+    return;
+  }
+  const lines = [];
+  if (confirmed.length > 0) {
+    lines.push(`EntitySchema-defined entities are not currently supported: ${confirmed.join(", ")}.`);
+  }
+  if (unconfirmed.length > 0) {
+    lines.push(
+      `Could not confirm these entities are decorator-based @Entity() classes: ${unconfirmed.join(", ")}. This usually means they are EntitySchema-defined entities (also not currently supported). If you're certain these are valid @Entity() classes, this may be a detection false positive in mikro-orm-markdown \u2014 please open an issue: https://github.com/iamkanguk97/mikro-orm-markdown/issues`
+    );
+  }
+  lines.push("Use decorator-based @Entity() classes instead.");
+  throw new MetadataLoadError(lines.join("\n"));
+}
 async function loadEntityMetadata(options) {
   assertNoEntitySchemaEntities(options);
   let orm;
@@ -179,6 +258,7 @@ async function loadEntityMetadata(options) {
         "No entities were discovered. Check that your config specifies at least one entity path or class."
       );
     }
+    assertDiscoveredEntitiesAreSupported(all);
     const baseDir = orm.config.get("baseDir");
     const sourcePaths = [...new Set(all.filter((m) => m.path).map((m) => path.resolve(baseDir, m.path)))];
     return { metas: all, sourcePaths };
@@ -190,55 +270,8 @@ async function loadEntityMetadata(options) {
 // src/model/build.ts
 import { ReferenceKind as ReferenceKind2 } from "@mikro-orm/core";
 
-// src/render/mermaid.ts
+// src/model/diagram.ts
 import { ReferenceKind } from "@mikro-orm/core";
-
-// src/render/escape.ts
-var MARKDOWN_INLINE_SPECIAL_CHARS = /[\\`|*#]/g;
-var MERMAID_IDENTIFIER_INVALID_CHARS = /[^a-zA-Z0-9_]/g;
-function normalizeInlineText(value) {
-  return value.replace(/\r\n?/g, "\n").replace(/[\n\t]+/g, " ").replace(/\s{2,}/g, " ").trim();
-}
-function splitNormalizedLines(value) {
-  return value.replace(/\r\n?/g, "\n").split("\n");
-}
-function escapeHtmlText(value) {
-  return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
-}
-function escapeMarkdownInline(value) {
-  return escapeHtmlText(normalizeInlineText(value)).replace(MARKDOWN_INLINE_SPECIAL_CHARS, "\\$&");
-}
-function escapeMarkdownTableCell(value) {
-  return splitNormalizedLines(value).map((line) => escapeMarkdownInline(line)).join("<br>");
-}
-function escapeMarkdownParagraph(value) {
-  return splitNormalizedLines(value).map((line) => escapeMarkdownInline(line)).join("  \n");
-}
-function renderMarkdownBlockQuote(value) {
-  return splitNormalizedLines(value).map((line) => `> ${escapeMarkdownInline(line)}`).join("\n");
-}
-function renderMarkdownInlineCode(value) {
-  const normalized = normalizeInlineText(value);
-  const backtickRuns = normalized.match(/`+/g) ?? [];
-  const longestRun = Math.max(0, ...backtickRuns.map((run) => run.length));
-  const fence = "`".repeat(longestRun + 1);
-  const needsPadding = normalized.startsWith("`") || normalized.endsWith("`");
-  const content = needsPadding ? ` ${normalized} ` : normalized;
-  return `${fence}${content}${fence}`;
-}
-function toMermaidIdentifier(value) {
-  const normalized = normalizeInlineText(value).replace(MERMAID_IDENTIFIER_INVALID_CHARS, "_").replace(/_+/g, "_");
-  const identifier = normalized === "" ? "_" : normalized;
-  return /^[a-zA-Z_]/.test(identifier) ? identifier : `_${identifier}`;
-}
-function escapeMermaidQuotedText(value) {
-  return normalizeInlineText(value).replace(/\\/g, "\\\\").replace(/"/g, '\\"');
-}
-function toMarkdownAnchor(value) {
-  return normalizeInlineText(value).toLowerCase().replace(/[^\p{L}\p{N}\s_-]/gu, "").replace(/\s+/g, "-");
-}
-
-// src/render/mermaid.ts
 var FORMULA_DUMMY_TABLE = {
   alias: "e0",
   name: "",
@@ -298,6 +331,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) {
@@ -484,6 +520,9 @@ function buildEdge(fromEntity, prop) {
     };
   }
   if (prop.kind === ReferenceKind.ONE_TO_ONE && prop.owner === true) {
+    if (prop.type === fromEntity) {
+      return null;
+    }
     return {
       fromEntity,
       toEntity: prop.type,
@@ -503,75 +542,6 @@ function buildEdge(fromEntity, prop) {
   }
   return null;
 }
-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) {
-      lines.push(`    ${renderColumnLine(col)}`);
-    }
-    lines.push("  }");
-  }
-  for (const rel of model.relations) {
-    lines.push(
-      `  ${toMermaidIdentifier(rel.fromEntity)} ${rel.fromCardinality}--${rel.toCardinality} ${toMermaidIdentifier(rel.toEntity)} : "${escapeMermaidQuotedText(rel.label)}"`
-    );
-  }
-  return lines.join("\n");
-}
-function renderColumnLine(col) {
-  let qualifier = "";
-  if (col.isPrimary) {
-    qualifier = " PK";
-  } else if (col.isUnique) {
-    qualifier = " UK";
-  }
-  let comment;
-  if (col.formula !== void 0) {
-    comment = col.formula ? `formula: ${col.formula}` : "formula";
-  } else if (col.isDiscriminator) {
-    comment = "discriminator";
-  } else if (col.embeddedIn !== void 0) {
-    comment = `[${col.embeddedIn}]`;
-  } else if (col.isSelfReference) {
-    comment = "self-ref";
-  }
-  const commentStr = comment !== void 0 ? ` "${escapeMermaidQuotedText(comment)}"` : "";
-  return `${toMermaidIdentifier(normalizeType(col.type))} ${toMermaidIdentifier(col.fieldName)}${qualifier}${commentStr}`;
-}
 
 // src/model/build.ts
 var FROM_ONE_OR_MORE = "}|";
@@ -594,7 +564,10 @@ function buildDocumentModel(metas, jsDocResult, title, description, onWarn) {
     const columns = model.columns.filter(
       (col) => !(col.isForeignKey && col.referencedEntity !== void 0 && hiddenClasses.has(col.referencedEntity))
     );
-    const visibleModel = columns.length === model.columns.length ? model : { ...model, columns };
+    const visibleModel = removeHiddenEntityReferences(
+      columns.length === model.columns.length ? model : { ...model, columns },
+      hiddenClasses
+    );
     const ownPropDocs = jsDocResult.props.get(model.className) ?? /* @__PURE__ */ new Map();
     const propDocs = withEmbeddedPropDocs(ownPropDocs, visibleModel.columns, jsDocResult.props);
     enrichedByClass.set(model.className, { model: visibleModel, jsDoc, propDocs });
@@ -645,6 +618,14 @@ function buildDocumentModel(metas, jsDocResult, title, description, onWarn) {
   });
   return { title, groups, ...description !== void 0 && { description } };
 }
+function removeHiddenEntityReferences(model, hiddenClasses) {
+  if (model.extendsEntity === void 0 || !hiddenClasses.has(model.extendsEntity)) {
+    return model;
+  }
+  const visibleModel = { ...model };
+  delete visibleModel.extendsEntity;
+  return visibleModel;
+}
 function withEmbeddedPropDocs(ownPropDocs, columns, allPropDocs) {
   const merged = new Map(ownPropDocs);
   for (const col of columns) {
@@ -756,6 +737,142 @@ async function withTsMorphMetadataProvider(options, onWarn) {
   }
 }
 
+// src/render/escape.ts
+var MARKDOWN_INLINE_SPECIAL_CHARS = /[\\`|*#\[\]]/g;
+var MARKDOWN_EMPHASIS_UNDERSCORE = /(?<![a-zA-Z0-9])_|_(?![a-zA-Z0-9])/g;
+var MERMAID_IDENTIFIER_INVALID_CHARS = /[^a-zA-Z0-9_]/g;
+function normalizeInlineText(value) {
+  return value.replace(/\r\n?/g, "\n").replace(/[\n\t]+/g, " ").replace(/\s{2,}/g, " ").trim();
+}
+function splitNormalizedLines(value) {
+  return value.replace(/\r\n?/g, "\n").split("\n");
+}
+function escapeHtmlText(value) {
+  return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+function escapeMarkdownInline(value) {
+  return escapeHtmlText(normalizeInlineText(value)).replace(MARKDOWN_INLINE_SPECIAL_CHARS, "\\$&").replace(MARKDOWN_EMPHASIS_UNDERSCORE, "\\_");
+}
+function escapeMarkdownTableCell(value) {
+  return splitNormalizedLines(value).map((line) => escapeMarkdownInline(line)).join("<br>");
+}
+function escapeMarkdownParagraph(value) {
+  return splitNormalizedLines(value).map((line) => escapeMarkdownInline(line)).join("  \n");
+}
+function renderMarkdownBlockQuote(value) {
+  return splitNormalizedLines(value).map((line) => `> ${escapeMarkdownInline(line)}`).join("\n");
+}
+function renderMarkdownInlineCode(value) {
+  const normalized = normalizeInlineText(value);
+  const backtickRuns = normalized.match(/`+/g) ?? [];
+  const longestRun = Math.max(0, ...backtickRuns.map((run) => run.length));
+  const fence = "`".repeat(longestRun + 1);
+  const needsPadding = normalized.startsWith("`") || normalized.endsWith("`");
+  const content = needsPadding ? ` ${normalized} ` : normalized;
+  return `${fence}${content}${fence}`;
+}
+function toMermaidIdentifier(value) {
+  const normalized = normalizeInlineText(value).replace(MERMAID_IDENTIFIER_INVALID_CHARS, "_").replace(/_+/g, "_");
+  const identifier = normalized === "" ? "_" : normalized;
+  return /^[a-zA-Z_]/.test(identifier) ? identifier : `_${identifier}`;
+}
+function escapeMermaidQuotedText(value) {
+  return normalizeInlineText(value).replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+function toMarkdownAnchor(value) {
+  return normalizeInlineText(value).toLowerCase().replace(/[^\p{L}\p{N}\s_-]/gu, "").replace(/\s+/g, "-");
+}
+
+// src/render/mermaid.ts
+var GENERIC_TYPE_BY_BASE_NAME = /* @__PURE__ */ new Map([
+  ["uuid", "string"],
+  ["text", "string"],
+  ["string", "string"],
+  ["varchar", "string"],
+  ["character varying", "string"],
+  ["character", "string"],
+  ["char", "string"],
+  ["tinytext", "string"],
+  ["mediumtext", "string"],
+  ["longtext", "string"],
+  ["timestamptz", "datetime"],
+  ["timestamp", "datetime"],
+  ["datetime", "datetime"],
+  ["integer", "integer"],
+  ["int", "integer"],
+  ["bigint", "integer"],
+  ["smallint", "integer"],
+  ["tinyint", "integer"],
+  ["mediumint", "integer"],
+  ["serial", "integer"],
+  ["bigserial", "integer"],
+  ["doubletype", "float"],
+  ["double precision", "float"],
+  ["double", "float"],
+  ["float", "float"],
+  ["decimal", "float"],
+  ["numeric", "float"],
+  ["real", "float"],
+  ["boolean", "boolean"],
+  ["bool", "boolean"],
+  ["jsonb", "json"]
+]);
+function normalizeType(type) {
+  const t = type.toLowerCase().replace(/\s+/g, " ").trim();
+  if (/^tinyint\s*\(\s*1\s*\)$/.test(t)) {
+    return "boolean";
+  }
+  const baseName = t.replace(/\(.*\)/, "").replace(/\b(un)?signed\b/, "").trim();
+  return GENERIC_TYPE_BY_BASE_NAME.get(baseName) ?? 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) {
+      lines.push(`    ${renderColumnLine(col)}`);
+    }
+    lines.push("  }");
+  }
+  for (const rel of model.relations) {
+    lines.push(
+      `  ${toMermaidIdentifier(rel.fromEntity)} ${rel.fromCardinality}--${rel.toCardinality} ${toMermaidIdentifier(rel.toEntity)} : "${escapeMermaidQuotedText(rel.label)}"`
+    );
+  }
+  return lines.join("\n");
+}
+function renderColumnLine(col) {
+  let qualifier = "";
+  if (col.isPrimary) {
+    qualifier = " PK";
+  } else if (col.isUnique) {
+    qualifier = " UK";
+  }
+  let comment;
+  if (col.formula !== void 0) {
+    comment = col.formula ? `formula: ${col.formula}` : "formula";
+  } else if (col.isDiscriminator) {
+    comment = "discriminator";
+  } else if (col.embeddedIn !== void 0) {
+    comment = `[${col.embeddedIn}]`;
+  } else if (col.isSelfReference) {
+    comment = "self-ref";
+  }
+  const commentStr = comment !== void 0 ? ` "${escapeMermaidQuotedText(comment)}"` : "";
+  return `${toMermaidIdentifier(normalizeType(col.type))} ${toMermaidIdentifier(col.fieldName)}${qualifier}${commentStr}`;
+}
+
 // src/render/markdown.ts
 function renderMarkdown(docModel, mermaid) {
   const sections = [`# ${escapeMarkdownInline(docModel.title)}`];
@@ -779,7 +896,7 @@ function renderBulletSection(header, items, renderItem) {
 }
 function renderTableOfContents(groups, anchors) {
   return renderBulletSection("## Contents", groups, (group) => {
-    const label = escapeMarkdownInline(group.name).replace(/[[\]]/g, "\\$&");
+    const label = escapeMarkdownInline(group.name);
     return `- [${label}](#${anchors.get(group) ?? toMarkdownAnchor(group.name)})`;
   });
 }
@@ -864,7 +981,7 @@ function resolveColumnKey(col) {
     return "PK";
   }
   if (col.isForeignKey) {
-    return fkKey;
+    return col.isUnique ? `${fkKey}, UK` : fkKey;
   }
   if (col.isUnique) {
     return "UK";