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

package/dist/cli.js

@@ -1,17 +1,20 @@
 #!/usr/bin/env node
 
 // src/cli.ts
+import * as syncFs from "fs";
 import * as fs from "fs/promises";
-import * as path from "path";
+import * as path2 from "path";
+import { fileURLToPath, pathToFileURL } from "url";
 import { Command } from "commander";
 
 // src/docs/jsdoc.ts
 import { Project } from "ts-morph";
-function loadJsDoc(srcGlobs) {
+function loadJsDoc(filePaths) {
   const entities = /* @__PURE__ */ new Map();
   const props = /* @__PURE__ */ new Map();
-  if (srcGlobs.length === 0) {
-    return { entities, props };
+  const classNames = /* @__PURE__ */ new Set();
+  if (filePaths.length === 0) {
+    return { entities, props, sourceFileCount: 0, classNames };
   }
   const project = new Project({
     skipAddingFilesFromTsConfig: true,
@@ -21,34 +24,44 @@ function loadJsDoc(srcGlobs) {
       skipLibCheck: true
     }
   });
-  project.addSourceFilesAtPaths(srcGlobs);
-  for (const sourceFile of project.getSourceFiles()) {
-    for (const cls of sourceFile.getClasses()) {
-      const className = cls.getName();
-      if (!className) {
-        continue;
-      }
-      const classDocs = cls.getJsDocs();
-      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) {
+  for (const filePath of filePaths) {
+    try {
+      project.addSourceFilesAtPaths(filePath);
+    } catch {
+    }
+  }
+  const sourceFiles = project.getSourceFiles();
+  for (const sourceFile of sourceFiles) {
+    try {
+      for (const cls of sourceFile.getClasses()) {
+        const className = cls.getName();
+        if (!className) {
           continue;
         }
-        const desc = extractDescription(propDocs);
-        if (desc !== void 0) {
-          propMap.set(prop.getName(), { description: desc });
+        classNames.add(className);
+        const classDocs = cls.getJsDocs();
+        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);
+          }
+        }
+        if (propMap.size > 0) {
+          props.set(className, propMap);
         }
       }
-      if (propMap.size > 0) {
-        props.set(className, propMap);
-      }
+    } catch {
     }
   }
-  return { entities, props };
+  return { entities, props, sourceFileCount: sourceFiles.length, classNames };
 }
 function parseEntityJsDoc(jsDocs) {
   const namespaces = [];
@@ -83,18 +96,26 @@ function parseEntityJsDoc(jsDocs) {
     hidden
   };
 }
-function extractDescription(jsDocs) {
+function parsePropJsDoc(jsDocs) {
+  let description;
+  let atLeastOne = false;
   for (const doc of jsDocs) {
     const desc = doc.getDescription().trim();
-    if (desc) {
-      return desc;
+    if (desc && description === void 0) {
+      description = desc;
+    }
+    for (const tag of doc.getTags()) {
+      if (tag.getTagName() === "atLeastOne") {
+        atLeastOne = true;
+      }
     }
   }
-  return void 0;
+  return { ...description !== void 0 && { description }, atLeastOne };
 }
 
 // src/metadata/load.ts
-import { MikroORM } from "@mikro-orm/core";
+import * as path from "path";
+import { EntitySchema, MikroORM } from "@mikro-orm/core";
 var MetadataLoadError = class extends Error {
   constructor(message, cause) {
     super(message);
@@ -102,13 +123,46 @@ var MetadataLoadError = class extends Error {
     this.name = "MetadataLoadError";
   }
 };
+async function closeDiscoveryResources(orm) {
+  await orm.config.getMetadataCacheAdapter()?.close?.();
+  await orm.config.getResultCacheAdapter()?.close?.();
+}
+function collectEntitySchemaNames(options) {
+  const configuredEntities = [...options.entities ?? [], ...options.entitiesTs ?? []];
+  const names = [];
+  for (const entity of configuredEntities) {
+    if (entity instanceof EntitySchema) {
+      names.push(entity.meta.className);
+      continue;
+    }
+    if (entity !== null && typeof entity === "object" && "schema" in entity && entity.schema instanceof EntitySchema) {
+      names.push(entity.schema.meta.className);
+    }
+  }
+  return names;
+}
+function assertNoEntitySchemaEntities(options) {
+  const schemaNames = collectEntitySchemaNames(options);
+  if (schemaNames.length === 0) {
+    return;
+  }
+  throw new MetadataLoadError(
+    `EntitySchema-defined entities are not currently supported: ${schemaNames.join(", ")}.
+Use decorator-based @Entity() classes instead.`
+  );
+}
 async function loadEntityMetadata(options) {
+  assertNoEntitySchemaEntities(options);
   let orm;
   try {
     orm = await MikroORM.init({
       ...options,
       debug: false,
-      connect: false
+      connect: false,
+      // Always disable the metadata cache for one-shot doc runs so the project
+      // is never littered with a temp/ folder, regardless of how metadataProvider
+      // was configured.
+      metadataCache: { ...options.metadataCache, enabled: false }
     });
   } catch (cause) {
     throw new MetadataLoadError(
@@ -116,23 +170,80 @@ async function loadEntityMetadata(options) {
       cause
     );
   }
-  const all = Object.values(orm.getMetadata().getAll());
-  if (all.length === 0) {
-    throw new MetadataLoadError(
-      "No entities were discovered. Check that your config specifies at least one entity path or class."
-    );
+  try {
+    const all = Object.values(orm.getMetadata().getAll());
+    if (all.length === 0) {
+      throw new MetadataLoadError(
+        "No entities were discovered. Check that your config specifies at least one entity path or class."
+      );
+    }
+    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 };
+  } finally {
+    await closeDiscoveryResources(orm);
   }
-  return all;
 }
 
+// src/model/build.ts
+import { ReferenceKind as ReferenceKind2 } from "@mikro-orm/core";
+
 // src/render/mermaid.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((run2) => run2.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: "",
   qualifiedName: "",
   toString: () => "e0"
 };
+var UNRESOLVED_FORMULA = "<unresolved>";
 function buildDiagramModel(metas) {
   const metaByClass = new Map(metas.map((m) => [m.className, m]));
   const entities = metas.filter((meta) => !meta.pivotTable && !meta.embeddable).map((meta) => buildEntityModel(meta, metaByClass));
@@ -140,17 +251,14 @@ function buildDiagramModel(metas) {
   return { entities, relations };
 }
 function buildEntityModel(meta, metaByClass) {
-  const isStiRoot = meta.discriminatorColumn !== void 0 && !meta.discriminatorValue;
+  const isStiRoot = meta.discriminatorColumn !== void 0 && !meta.extends;
   const isStiChild = Boolean(meta.extends) && meta.discriminatorValue !== void 0;
   const columns = [];
   for (const prop of Object.values(meta.properties)) {
     if (isStiRoot && prop.inherited === true) {
       continue;
     }
-    const col = buildColumn(prop, metaByClass, meta);
-    if (col !== null) {
-      columns.push(col);
-    }
+    columns.push(...buildColumns(prop, metaByClass, meta));
   }
   return {
     className: meta.className,
@@ -160,47 +268,73 @@ function buildEntityModel(meta, metaByClass) {
     isEmbeddable: meta.embeddable === true,
     ...isStiRoot && { discriminatorColumn: meta.discriminatorColumn },
     ...isStiChild && { extendsEntity: meta.extends },
+    ...isStiChild && meta.discriminatorValue !== void 0 && { discriminatorValue: String(meta.discriminatorValue) },
     constraints: buildConstraints(meta)
   };
 }
-function buildColumn(prop, metaByClass, owningMeta) {
+function buildColumns(prop, metaByClass, owningMeta) {
   if (prop.kind === ReferenceKind.EMBEDDED) {
-    return null;
+    if (prop.object === true || prop.array === true) {
+      return [
+        {
+          propName: prop.name,
+          fieldName: prop.fieldNames?.[0] ?? prop.name,
+          type: "json",
+          isPrimary: false,
+          isForeignKey: false,
+          isUnique: prop.unique === true,
+          isNullable: prop.nullable === true,
+          ...prop.comment !== void 0 && { comment: prop.comment },
+          embeddedIn: prop.array === true ? `${prop.type}[]` : prop.type
+        }
+      ];
+    }
+    return [];
   }
   if (prop.kind === ReferenceKind.SCALAR) {
+    if (prop.object === true && prop.embedded !== void 0) {
+      return [];
+    }
     const formulaExpr = prop.formula !== void 0 ? resolveFormulaExpr(prop.formula) : void 0;
     let embeddedIn;
+    let embeddedPropName;
     if (prop.embedded !== void 0) {
       const parentPropName = prop.embedded[0];
       embeddedIn = owningMeta.properties[parentPropName]?.type;
+      embeddedPropName = prop.embedded[1];
     }
     const isDiscriminator = owningMeta.discriminatorColumn !== void 0 && prop.name === owningMeta.discriminatorColumn;
-    return {
-      propName: prop.name,
-      fieldName: prop.fieldNames?.[0] ?? prop.name,
-      type: normalizeType(prop.type),
-      isPrimary: prop.primary === true,
-      isForeignKey: false,
-      isUnique: prop.unique === true,
-      isNullable: prop.nullable === true,
-      ...formulaExpr !== void 0 && { formula: formulaExpr },
-      ...embeddedIn !== void 0 && { embeddedIn },
-      ...isDiscriminator && { isDiscriminator: true }
-    };
+    const enumItems = prop.enum === true && Array.isArray(prop.items) && prop.items.length > 0 ? prop.items.map((item) => String(item)) : void 0;
+    return [
+      {
+        propName: prop.name,
+        fieldName: prop.fieldNames?.[0] ?? prop.name,
+        // Store the original type (e.g. `varchar(255)`); the Mermaid renderer
+        // sanitizes it for diagram identifiers, while the markdown table shows
+        // it verbatim. Guard against a missing type so downstream string
+        // handling never sees undefined (matches the FK path's defaulting).
+        type: prop.type ?? "unknown",
+        isPrimary: prop.primary === true,
+        isForeignKey: false,
+        isUnique: prop.unique === true,
+        isNullable: prop.nullable === true,
+        ...prop.comment !== void 0 && { comment: prop.comment },
+        ...formulaExpr !== void 0 && { formula: formulaExpr },
+        ...embeddedIn !== void 0 && { embeddedIn },
+        ...embeddedPropName !== void 0 && { embeddedPropName },
+        ...isDiscriminator && { isDiscriminator: true },
+        ...enumItems !== void 0 && { enumItems }
+      }
+    ];
   }
   if (prop.kind === ReferenceKind.MANY_TO_ONE || prop.kind === ReferenceKind.ONE_TO_ONE && prop.owner === true) {
-    const fkType = resolveFkType(prop.type, metaByClass);
-    return {
-      propName: prop.name,
-      fieldName: prop.fieldNames?.[0] ?? `${prop.name}_id`,
-      type: fkType,
-      isPrimary: false,
-      isForeignKey: true,
-      isUnique: prop.unique === true,
-      isNullable: prop.nullable === true
-    };
+    const cols = buildForeignKeyColumns(prop, metaByClass);
+    if (prop.type === owningMeta.className) {
+      return cols.map((col) => ({ ...col, isSelfReference: true }));
+    }
+    return cols;
   }
-  return null;
+  return [];
 }
 function resolveFormulaExpr(cb) {
   try {
@@ -210,18 +344,69 @@ function resolveFormulaExpr(cb) {
         get: (_target, key) => typeof key === "string" ? key : ""
       }
     );
-    return cb(FORMULA_DUMMY_TABLE, cols);
+    const result = cb(FORMULA_DUMMY_TABLE, cols);
+    return typeof result === "string" ? result : String(result);
   } catch {
-    return "";
+    return UNRESOLVED_FORMULA;
   }
 }
-function resolveFkType(referencedClassName, metaByClass) {
-  const refMeta = metaByClass.get(referencedClassName);
+function buildForeignKeyColumns(prop, metaByClass) {
+  const fieldNames = prop.fieldNames && prop.fieldNames.length > 0 ? prop.fieldNames : [`${prop.name}_id`];
+  const fkTypes = resolveFkTypes(prop, metaByClass, fieldNames.length);
+  return fieldNames.map((fieldName, index) => ({
+    propName: prop.name,
+    fieldName,
+    type: fkTypes[index] ?? fkTypes[0] ?? "integer",
+    isPrimary: prop.primary === true,
+    isForeignKey: true,
+    isUnique: prop.unique === true,
+    isNullable: prop.nullable === true,
+    ...prop.comment !== void 0 && { comment: prop.comment },
+    referencedEntity: prop.type
+  }));
+}
+function resolveFkTypes(prop, metaByClass, fieldNameCount) {
+  const refMeta = metaByClass.get(prop.type);
   if (!refMeta) {
+    return Array.from({ length: fieldNameCount }, () => "integer");
+  }
+  const primaryProps = getPrimaryProps(refMeta);
+  const referencedColumnNames = prop.referencedColumnNames ?? [];
+  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;
+    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 pkProp = Object.values(refMeta.properties).find((p) => p.primary === true);
-  return pkProp ? normalizeType(pkProp.type) : "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);
+  if (orderedPrimaryProps.length > 0) {
+    return orderedPrimaryProps;
+  }
+  return Object.values(meta.properties).filter((prop) => prop.primary === true);
 }
 function buildConstraints(meta) {
   const result = [];
@@ -229,7 +414,7 @@ function buildConstraints(meta) {
     const props = idx.properties;
     result.push({
       type: "index",
-      properties: Array.isArray(props) ? props.map(String) : props ? [String(props)] : [],
+      properties: resolveConstraintProperties(meta, props),
       ...idx.name !== void 0 && { name: idx.name }
     });
   }
@@ -237,7 +422,7 @@ function buildConstraints(meta) {
     const props = uniq.properties;
     result.push({
       type: "unique",
-      properties: Array.isArray(props) ? props.map(String) : props ? [String(props)] : [],
+      properties: resolveConstraintProperties(meta, props),
       ...uniq.name !== void 0 && { name: uniq.name }
     });
   }
@@ -254,6 +439,19 @@ function buildConstraints(meta) {
   }
   return result;
 }
+function resolveConstraintProperties(meta, props) {
+  const propNames = Array.isArray(props) ? props : props !== void 0 ? [props] : [];
+  return propNames.flatMap((propName) => {
+    const prop = meta.properties[String(propName)];
+    if (prop === void 0) {
+      return [String(propName)];
+    }
+    if (prop.fieldNames !== void 0 && prop.fieldNames.length > 0) {
+      return prop.fieldNames;
+    }
+    return [prop.name];
+  });
+}
 function buildRelationEdges(metas) {
   const edges = [];
   for (const meta of metas) {
@@ -272,6 +470,9 @@ function buildRelationEdges(metas) {
 function buildEdge(fromEntity, prop) {
   const isNullable = prop.nullable === true;
   if (prop.kind === ReferenceKind.MANY_TO_ONE) {
+    if (prop.type === fromEntity) {
+      return null;
+    }
     return {
       fromEntity,
       toEntity: prop.type,
@@ -300,17 +501,41 @@ 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) {
   const lines = ["erDiagram"];
   for (const entity of model.entities) {
-    lines.push(`  ${entity.className} {`);
+    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(`  ${rel.fromEntity} ${rel.fromCardinality}--${rel.toCardinality} ${rel.toEntity} : "${rel.label}"`);
+    lines.push(
+      `  ${toMermaidIdentifier(rel.fromEntity)} ${rel.fromCardinality}--${rel.toCardinality} ${toMermaidIdentifier(rel.toEntity)} : "${escapeMermaidQuotedText(rel.label)}"`
+    );
   }
   return lines.join("\n");
 }
@@ -318,8 +543,6 @@ function renderColumnLine(col) {
   let qualifier = "";
   if (col.isPrimary) {
     qualifier = " PK";
-  } else if (col.isForeignKey) {
-    qualifier = " FK";
   } else if (col.isUnique) {
     qualifier = " UK";
   }
@@ -330,27 +553,38 @@ function renderColumnLine(col) {
     comment = "discriminator";
   } else if (col.embeddedIn !== void 0) {
     comment = `[${col.embeddedIn}]`;
-  } else if (col.fieldName !== col.propName) {
-    comment = col.propName;
+  } else if (col.isSelfReference) {
+    comment = "self-ref";
   }
-  const commentStr = comment !== void 0 ? ` "${comment}"` : "";
-  return `${col.type} ${col.fieldName}${qualifier}${commentStr}`;
-}
-function normalizeType(type) {
-  return type.replace(/[^a-zA-Z0-9_]/g, "_");
+  const commentStr = comment !== void 0 ? ` "${escapeMermaidQuotedText(comment)}"` : "";
+  return `${toMermaidIdentifier(normalizeType(col.type))} ${toMermaidIdentifier(col.fieldName)}${qualifier}${commentStr}`;
 }
 
 // src/model/build.ts
-function buildDocumentModel(metas, jsDocResult, title, description) {
-  const { entities: diagramEntities, relations: allRelations } = buildDiagramModel(metas);
+var FROM_ONE_OR_MORE = "}|";
+var TO_ONE_OR_MORE = "|{";
+function buildDocumentModel(metas, jsDocResult, title, description, onWarn) {
+  const { entities: diagramEntities, relations } = buildDiagramModel(metas);
+  const allRelations = applyAtLeastOne(relations, metas, jsDocResult.props, onWarn);
+  const hiddenClasses = /* @__PURE__ */ new Set();
+  for (const model of diagramEntities) {
+    if (jsDocResult.entities.get(model.className)?.hidden) {
+      hiddenClasses.add(model.className);
+    }
+  }
   const enrichedByClass = /* @__PURE__ */ new Map();
   for (const model of diagramEntities) {
     const jsDoc = jsDocResult.entities.get(model.className);
     if (jsDoc?.hidden) {
       continue;
     }
-    const propDocs = jsDocResult.props.get(model.className) ?? /* @__PURE__ */ new Map();
-    enrichedByClass.set(model.className, { model, jsDoc, propDocs });
+    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 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 });
   }
   const groupNames = /* @__PURE__ */ new Set();
   let anyUntagged = false;
@@ -370,9 +604,16 @@ function buildDocumentModel(metas, jsDocResult, title, description) {
   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)
     );
@@ -391,6 +632,65 @@ function buildDocumentModel(metas, jsDocResult, title, description) {
   });
   return { title, groups, ...description !== void 0 && { description } };
 }
+function withEmbeddedPropDocs(ownPropDocs, columns, allPropDocs) {
+  const merged = new Map(ownPropDocs);
+  for (const col of columns) {
+    if (merged.has(col.propName) || col.embeddedIn === void 0 || col.embeddedPropName === void 0) {
+      continue;
+    }
+    const info = allPropDocs.get(col.embeddedIn)?.get(col.embeddedPropName);
+    if (info) {
+      merged.set(col.propName, info);
+    }
+  }
+  return merged;
+}
+function applyAtLeastOne(relations, metas, props, onWarn) {
+  const adjusted = relations.map((edge) => ({ ...edge }));
+  const metaByClass = new Map(metas.map((m) => [m.className, m]));
+  for (const [className, propMap] of props) {
+    const meta = metaByClass.get(className);
+    if (!meta) {
+      continue;
+    }
+    for (const [propName, info] of propMap) {
+      if (!info.atLeastOne) {
+        continue;
+      }
+      const prop = meta.properties[propName];
+      if (!prop) {
+        continue;
+      }
+      let edge;
+      if (prop.kind === ReferenceKind2.ONE_TO_MANY && prop.mappedBy) {
+        edge = adjusted.find(
+          (e) => e.fromEntity === prop.type && e.toEntity === className && e.label === prop.mappedBy
+        );
+        if (edge) {
+          edge.fromCardinality = FROM_ONE_OR_MORE;
+        }
+      } else if (prop.kind === ReferenceKind2.MANY_TO_MANY && prop.owner === true) {
+        edge = adjusted.find((e) => e.fromEntity === className && e.toEntity === prop.type && e.label === propName);
+        if (edge) {
+          edge.toCardinality = TO_ONE_OR_MORE;
+        }
+      } else if (prop.kind === ReferenceKind2.MANY_TO_MANY && prop.mappedBy) {
+        edge = adjusted.find(
+          (e) => e.fromEntity === prop.type && e.toEntity === className && e.label === prop.mappedBy
+        );
+        if (edge) {
+          edge.fromCardinality = FROM_ONE_OR_MORE;
+        }
+      }
+      if (!edge) {
+        onWarn?.(
+          `@atLeastOne on ${className}.${propName} had no effect: no matching relation edge was found. It applies only to collection relations that can be matched to a rendered edge: @OneToMany with mappedBy, or @ManyToMany on either the owning side or an inverse mappedBy side.`
+        );
+      }
+    }
+  }
+  return adjusted;
+}
 function hasNoNamespaceTags(jsDoc) {
   if (!jsDoc) {
     return true;
@@ -415,20 +715,62 @@ 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) {
+  if (options.metadataProvider !== void 0) {
+    return options;
+  }
+  try {
+    const { TsMorphMetadataProvider } = await import("@mikro-orm/reflection");
+    return { ...options, metadataProvider: TsMorphMetadataProvider };
+  } catch (err) {
+    const code = err !== null && typeof err === "object" && "code" in err ? err.code : void 0;
+    const isNotInstalled = code === "MODULE_NOT_FOUND" || code === "ERR_MODULE_NOT_FOUND";
+    if (!isNotInstalled && onWarn) {
+      onWarn(
+        `@mikro-orm/reflection is installed but failed to load: ${err instanceof Error ? err.message : String(err)}. Ensure all @mikro-orm/* packages are installed at the same version.`
+      );
+    }
+    return options;
+  }
+}
 
 // src/render/markdown.ts
 function renderMarkdown(docModel) {
-  const sections = [`# ${docModel.title}`];
+  const sections = [`# ${escapeMarkdownInline(docModel.title)}`];
   if (docModel.description) {
-    sections.push(docModel.description);
+    sections.push(escapeMarkdownParagraph(docModel.description));
+  }
+  if (docModel.groups.length > 1) {
+    sections.push(renderTableOfContents(docModel.groups));
   }
   for (const group of docModel.groups) {
     sections.push(renderGroupSection(group));
   }
   return sections.join("\n\n");
 }
+function renderBulletSection(header, items, renderItem) {
+  const lines = [header, ""];
+  for (const item of items) {
+    lines.push(renderItem(item));
+  }
+  return lines.join("\n");
+}
+function renderTableOfContents(groups) {
+  return renderBulletSection("## Contents", groups, (group) => {
+    const label = escapeMarkdownInline(group.name).replace(/[[\]]/g, "\\$&");
+    return `- [${label}](#${toMarkdownAnchor(group.name)})`;
+  });
+}
 function renderGroupSection(group) {
-  const parts = [`## ${group.name}`];
+  const parts = [`## ${escapeMarkdownInline(group.name)}`];
   if (group.erdEntities.length > 0) {
     const diagramModel = {
       entities: group.erdEntities.map((e) => e.model),
@@ -442,14 +784,18 @@ function renderGroupSection(group) {
   return parts.join("\n\n");
 }
 function renderEntitySection(entity) {
-  const parts = [`### ${entity.model.className}`];
+  const parts = [`### ${escapeMarkdownInline(entity.model.className)}`];
+  parts.push(`*Table: ${renderMarkdownInlineCode(entity.model.tableName)}*`);
   if (entity.jsDoc?.description) {
-    parts.push(`> ${entity.jsDoc.description}`);
+    parts.push(renderMarkdownBlockQuote(entity.jsDoc.description));
   }
   if (entity.model.discriminatorColumn) {
-    parts.push(`*STI root \u2014 discriminator column: \`${entity.model.discriminatorColumn}\`*`);
+    parts.push(`*STI root \u2014 discriminator column: ${renderMarkdownInlineCode(entity.model.discriminatorColumn)}*`);
   } else if (entity.model.extendsEntity) {
-    parts.push(`*Extends \`${entity.model.extendsEntity}\` (Single Table Inheritance)*`);
+    const discValue = entity.model.discriminatorValue !== void 0 ? `, discriminator value: ${renderMarkdownInlineCode(entity.model.discriminatorValue)}` : "";
+    parts.push(
+      `*Extends ${renderMarkdownInlineCode(entity.model.extendsEntity)} (Single Table Inheritance${discValue})*`
+    );
   }
   if (entity.model.columns.length > 0) {
     parts.push(renderColumnTable(entity));
@@ -457,6 +803,10 @@ function renderEntitySection(entity) {
   if (entity.model.constraints.length > 0) {
     parts.push(renderConstraints(entity.model.constraints));
   }
+  const computedColumns = entity.model.columns.filter((col) => col.formula !== void 0);
+  if (computedColumns.length > 0) {
+    parts.push(renderComputedColumns(computedColumns));
+  }
   return parts.join("\n\n");
 }
 function renderColumnTable(entity) {
@@ -465,24 +815,27 @@ function renderColumnTable(entity) {
   const rows = entity.model.columns.map((col) => {
     const key = resolveColumnKey(col);
     const nullable = col.isNullable && !col.isPrimary ? "Y" : "";
-    const desc = entity.propDocs.get(col.propName)?.description ?? "";
-    return `| ${col.fieldName} | ${col.type} | ${key} | ${nullable} | ${desc} |`;
+    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(normalizeType(col.type))} | ${escapeMarkdownTableCell(key)} | ${nullable} | ${escapeMarkdownTableCell(desc)} |`;
   });
   return [header, sep, ...rows].join("\n");
 }
 function resolveColumnKey(col) {
+  const fkKey = col.fieldName !== col.propName ? `FK (${col.propName})` : "FK";
+  if (col.isPrimary && col.isForeignKey) {
+    return `PK, ${fkKey}`;
+  }
   if (col.isPrimary) {
     return "PK";
   }
   if (col.isForeignKey) {
-    return col.fieldName !== col.propName ? `FK (${col.propName})` : "FK";
+    return fkKey;
   }
   if (col.isUnique) {
     return "UK";
   }
-  if (col.formula !== void 0) {
-    return `formula: ${col.formula}`;
-  }
   if (col.isDiscriminator) {
     return "discriminator";
   }
@@ -491,43 +844,227 @@ function resolveColumnKey(col) {
   }
   return "";
 }
+function renderComputedColumns(columns) {
+  return renderBulletSection("**Computed columns:**", columns, (col) => {
+    const expr = col.formula ? `: ${renderMarkdownInlineCode(col.formula)}` : "";
+    return `- ${renderMarkdownInlineCode(col.fieldName)}${expr}`;
+  });
+}
 function renderConstraints(constraints) {
-  const lines = ["**Constraints:**", ""];
-  for (const c of constraints) {
-    const name = c.name ? ` \`${c.name}\`` : "";
+  return renderBulletSection("**Constraints:**", constraints, (c) => {
+    const name = c.name ? ` ${renderMarkdownInlineCode(c.name)}` : "";
+    const properties = c.properties.map(escapeMarkdownInline).join(", ");
     if (c.type === "index") {
-      lines.push(`- Index${name}: (${c.properties.join(", ")})`);
-    } else if (c.type === "unique") {
-      lines.push(`- Unique${name}: (${c.properties.join(", ")})`);
-    } else if (c.type === "check") {
-      lines.push(`- Check${name}: \`${c.expression ?? ""}\``);
+      return `- Index${name}: (${properties})`;
     }
-  }
-  return lines.join("\n");
+    if (c.type === "unique") {
+      return `- Unique${name}: (${properties})`;
+    }
+    return `- Check${name}: ${renderMarkdownInlineCode(c.expression ?? "")}`;
+  });
 }
 
 // src/index.ts
+var COMPILED_JS = /\.(c|m)?js$/i;
+function resolveJsDocSources(sourcePaths, src, onWarn) {
+  if (src !== void 0 && src.length > 0) {
+    return src;
+  }
+  if (sourcePaths.some((p) => COMPILED_JS.test(p)) && onWarn) {
+    onWarn(
+      'Entities were discovered from compiled JavaScript, so JSDoc descriptions and @namespace/@hidden tags cannot be read (build tools strip comments). Hidden entities may be exposed. Pass --src "<glob to your .ts sources>" (or the `src` option) to read JSDoc from the original TypeScript files.'
+    );
+  }
+  return sourcePaths;
+}
+function assertExplicitJsDocSourceCoverage(metas, jsDocResult, src, onWarn) {
+  if (jsDocResult.sourceFileCount === 0) {
+    throw new Error(
+      `No source files matched the explicit src paths: ${src.join(", ")}
+Check the --src glob/path (or the \`src\` option). Without matching TypeScript sources, JSDoc tags such as @namespace and @hidden cannot be read.`
+    );
+  }
+  const isRenderable = (meta) => !meta.pivotTable && !meta.embeddable;
+  const missingConcrete = metas.filter((meta) => isRenderable(meta) && !meta.abstract).map((meta) => meta.className).filter((className) => !jsDocResult.classNames.has(className));
+  if (missingConcrete.length > 0) {
+    throw new Error(
+      `Explicit src paths did not include source declarations for discovered entities: ${missingConcrete.join(", ")}
+Check that --src (or the \`src\` option) points at all TypeScript entity files. JSDoc tags such as @namespace and @hidden for missing entities cannot be read.`
+    );
+  }
+  if (onWarn) {
+    const missingAbstract = metas.filter((meta) => isRenderable(meta) && meta.abstract).map((meta) => meta.className).filter((className) => !jsDocResult.classNames.has(className));
+    if (missingAbstract.length > 0) {
+      onWarn(
+        `Abstract STI parent entities were not found in the explicit src paths: ${missingAbstract.join(", ")}
+@hidden and @namespace tags for these entities will not be applied. Include their source files in --src to enable JSDoc tags for them.`
+      );
+    }
+  }
+}
+function errorMessages(err) {
+  const messages = [];
+  const seen = /* @__PURE__ */ new Set();
+  let current = err;
+  while (current instanceof Error && !seen.has(current)) {
+    seen.add(current);
+    messages.push(current.message);
+    current = current.cause;
+  }
+  return messages;
+}
+function isMissingTsMorphSourceFile(err) {
+  return errorMessages(err).some((message) => message.includes("Source file") && message.includes("not found"));
+}
+async function loadEntityMetadataWithTsMorphFallback(originalOrm, effectiveOrm) {
+  try {
+    return await loadEntityMetadata(effectiveOrm);
+  } catch (err) {
+    const wasAutoInjected = originalOrm.metadataProvider === void 0 && effectiveOrm.metadataProvider !== void 0;
+    if (!wasAutoInjected || !isMissingTsMorphSourceFile(err)) {
+      throw err;
+    }
+    try {
+      return await loadEntityMetadata(originalOrm);
+    } catch {
+      throw err;
+    }
+  }
+}
 async function generateMarkdown(options) {
-  const { orm, title = "Database Schema", description, src = [] } = options;
-  const metas = await loadEntityMetadata(orm);
-  const jsDocResult = loadJsDoc(src);
-  const docModel = buildDocumentModel(metas, jsDocResult, title, description);
+  const { orm, title = "Database Schema", description, src, onWarn } = options;
+  const effectiveOrm = await withTsMorphMetadataProvider(orm, onWarn);
+  const { metas, sourcePaths } = await loadEntityMetadataWithTsMorphFallback(orm, effectiveOrm);
+  const jsDocResult = loadJsDoc(resolveJsDocSources(sourcePaths, src, onWarn));
+  if (src !== void 0 && src.length > 0) {
+    assertExplicitJsDocSourceCoverage(metas, jsDocResult, src, onWarn);
+  }
+  const docModel = buildDocumentModel(metas, jsDocResult, title, description, onWarn);
   return renderMarkdown(docModel);
 }
 
 // src/cli.ts
+function toConfigImportSpecifier(configPath) {
+  return pathToFileURL(path2.resolve(configPath)).href;
+}
+function findNearestTsconfig(fromPath) {
+  let dir = path2.dirname(path2.resolve(fromPath));
+  for (; ; ) {
+    const candidate = path2.join(dir, "tsconfig.json");
+    if (syncFs.existsSync(candidate)) {
+      return candidate;
+    }
+    const parent = path2.dirname(dir);
+    if (parent === dir) {
+      return void 0;
+    }
+    dir = parent;
+  }
+}
+async function loadOrmOptions(configPath, tsconfigPath) {
+  const isTypeScriptConfig = configPath.endsWith(".ts");
+  if (isTypeScriptConfig) {
+    let register;
+    try {
+      ({ register } = await import("tsx/esm/api"));
+    } catch {
+      throw new Error('TypeScript config files require the "tsx" package.\nInstall it with: npm install -D tsx');
+    }
+    let tsconfig;
+    if (tsconfigPath !== void 0) {
+      tsconfig = path2.resolve(tsconfigPath);
+      if (!syncFs.existsSync(tsconfig)) {
+        throw new Error(`--tsconfig file not found: ${tsconfig}`);
+      }
+    } else {
+      tsconfig = findNearestTsconfig(configPath);
+    }
+    register(tsconfig !== void 0 ? { tsconfig } : {});
+  }
+  const configUrl = toConfigImportSpecifier(configPath);
+  let mod;
+  try {
+    mod = await import(
+      /* @vite-ignore */
+      configUrl
+    );
+  } catch (cause) {
+    if (isTypeScriptConfig) {
+      const detail = cause instanceof Error ? cause.message : String(cause);
+      throw new Error(
+        `Failed to load TypeScript config.
+${detail}
+
+If this looks like a decorator/metadata error, the tsconfig applied to your entity files is likely missing "experimentalDecorators" / "emitDecoratorMetadata".
+Make sure a tsconfig.json with those options sits next to your config file, or pass one explicitly with --tsconfig <path>.`,
+        { cause }
+      );
+    }
+    throw cause;
+  }
+  if (mod.default === void 0) {
+    throw new Error("Config file must use a default export, e.g. `export default defineConfig({ ... })`.");
+  }
+  const config = mod.default;
+  if (typeof config === "function" || config instanceof Promise) {
+    throw new Error(
+      "Config file default export must be a configuration object, not a function or Promise.\nResolve it first, or use the programmatic API instead (see README)."
+    );
+  }
+  if (typeof config !== "object" || config === null || Array.isArray(config)) {
+    throw new Error(
+      "Config file default export must be a configuration object, not a primitive value or array.\nExport a plain MikroORM options object instead."
+    );
+  }
+  const options = config;
+  const withPreferTs = isTypeScriptConfig && options.preferTs === void 0 ? { ...options, preferTs: true } : options;
+  return withPreferTs;
+}
+function formatErrorChain(err) {
+  const lines = [];
+  const seen = /* @__PURE__ */ new Set();
+  let current = err;
+  while (current instanceof Error && !seen.has(current)) {
+    seen.add(current);
+    lines.push(current.message);
+    current = current.cause;
+  }
+  if (current !== void 0 && !(current instanceof Error)) {
+    lines.push(String(current));
+  }
+  return lines.map((line, i) => i === 0 ? line : `  \u21B3 caused by: ${line}`).join("\n");
+}
+var REFLECTION_METADATA_HINT = "\n\nNote: this tool loads configs via tsx (esbuild), which does not emit 'emitDecoratorMetadata' reflection data, so enabling it will not help here.\nEither give each entity property an explicit 'type:'/'entity:' attribute, or install '@mikro-orm/reflection' \u2014 this tool then reads types from your TypeScript sources automatically.";
+function formatDiscoveryError(err) {
+  const chain = formatErrorChain(err);
+  return chain.includes("emitDecoratorMetadata") ? chain + REFLECTION_METADATA_HINT : chain;
+}
+function formatFileSystemError(cause) {
+  if (cause instanceof Error) {
+    const code = "code" in cause && typeof cause.code === "string" ? ` (${cause.code})` : "";
+    return `${cause.message}${code}`;
+  }
+  return String(cause);
+}
+async function writeMarkdownFile(outPath, markdown) {
+  try {
+    await fs.mkdir(path2.dirname(outPath), { recursive: true });
+    await fs.writeFile(outPath, markdown, "utf-8");
+  } catch (cause) {
+    throw new Error(`Cannot write output file: ${outPath}
+${formatFileSystemError(cause)}`, { cause });
+  }
+}
 async function run(opts) {
-  const configPath = path.resolve(opts.config);
-  const outPath = path.resolve(opts.out);
+  const configPath = path2.resolve(opts.config);
+  const outPath = path2.resolve(opts.out);
   let ormOptions;
   try {
-    const mod = await import(configPath);
-    ormOptions = mod.default ?? mod;
+    ormOptions = await loadOrmOptions(configPath, opts.tsconfig);
   } catch (err) {
-    const hint = configPath.endsWith(".ts") ? "\nHint: TypeScript configs require tsx or ts-node:\n  npx tsx ./node_modules/.bin/mikro-orm-markdown ..." : "";
     process.stderr.write(
       `Error: Cannot load config: ${configPath}
-${err instanceof Error ? err.message : String(err)}${hint}
+${err instanceof Error ? err.message : String(err)}
 `
     );
     process.exit(1);
@@ -537,23 +1074,57 @@ ${err instanceof Error ? err.message : String(err)}${hint}
     markdown = await generateMarkdown({
       orm: ormOptions,
       title: opts.title,
-      src: opts.src ?? [],
-      ...opts.description !== void 0 && { description: opts.description }
+      ...opts.description !== void 0 && { description: opts.description },
+      ...opts.src !== void 0 && { src: opts.src },
+      onWarn: (message) => void process.stderr.write(`Warning: ${message}
+`)
     });
   } catch (err) {
-    const msg = err instanceof MetadataLoadError ? err.message : err instanceof Error ? err.message : String(err);
-    process.stderr.write(`Error: ${msg}
+    process.stderr.write(`Error: ${formatDiscoveryError(err)}
 `);
     process.exit(1);
   }
-  await fs.writeFile(outPath, markdown, "utf-8");
-  process.stdout.write(`\u2713 Written to ${path.relative(process.cwd(), outPath)}
+  try {
+    await writeMarkdownFile(outPath, markdown);
+  } catch (err) {
+    process.stderr.write(`Error: ${err instanceof Error ? err.message : String(err)}
 `);
+    process.exit(1);
+  }
+  process.stdout.write(`\u2713 Written to ${path2.relative(process.cwd(), outPath)}
+`);
+}
+var program = new Command().name("mikro-orm-markdown").description("Generate Mermaid ERD + markdown docs from MikroORM entities").requiredOption("-c, --config <path>", "MikroORM config file path").option("-o, --out <path>", "Output markdown file path", "./ERD.md").option("-t, --title <string>", "Document title", "Database Schema").option("-d, --description <string>", "Optional description paragraph shown below the title").option(
+  "--tsconfig <path>",
+  "tsconfig.json to use when loading a .ts config (defaults to the nearest one beside the config file)"
+).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);
+function isDirectCliExecution() {
+  const entryPoint = process.argv[1];
+  if (entryPoint === void 0) {
+    return false;
+  }
+  try {
+    return syncFs.realpathSync(path2.resolve(entryPoint)) === syncFs.realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
 }
-var program = new Command().name("mikro-orm-markdown").description("Generate Mermaid ERD + markdown docs from MikroORM entities").requiredOption("-c, --config <path>", "MikroORM config file path").option("-o, --out <path>", "Output markdown file path", "./ERD.md").option("-t, --title <string>", "Document title", "Database Schema").option("-d, --description <string>", "Optional description paragraph shown below the title").option("-s, --src <glob>", "JSDoc source glob (repeatable)", (val, prev = []) => [...prev, val]).action(run);
-program.parseAsync(process.argv).catch((err) => {
-  process.stderr.write(`${err instanceof Error ? err.message : String(err)}
+if (isDirectCliExecution()) {
+  program.parseAsync(process.argv).catch((err) => {
+    process.stderr.write(`${err instanceof Error ? err.message : String(err)}
 `);
-  process.exit(1);
-});
+    process.exit(1);
+  });
+}
+export {
+  findNearestTsconfig,
+  formatDiscoveryError,
+  formatErrorChain,
+  loadOrmOptions,
+  toConfigImportSpecifier,
+  writeMarkdownFile
+};
 //# sourceMappingURL=cli.js.map