@metaobjectsdev/codegen-ts 0.9.0 → 0.11.0-rc.1

package/dist/generators/docs-data-builder.js

@@ -2,166 +2,363 @@
 // templates consume. The previous hand-coded `renderDocsFile()` mixed data
 // extraction with string emission; this module is the data-only half — the
 // markdown structure now lives in templates/docs/entity-page.md.mustache.
-import { TYPE_TEMPLATE, TEMPLATE_ATTR_PAYLOAD_REF, OBJECT_SUBTYPE_VALUE, IDENTITY_SUBTYPE_PRIMARY, IDENTITY_SUBTYPE_SECONDARY, IDENTITY_SUBTYPE_REFERENCE, IDENTITY_ATTR_GENERATION, RELATIONSHIP_ATTR_CARDINALITY, RELATIONSHIP_ATTR_OBJECT_REF, RELATIONSHIP_SUBTYPE_COMPOSITION, RELATIONSHIP_SUBTYPE_AGGREGATION, RELATIONSHIP_SUBTYPE_ASSOCIATION, FIELD_SUBTYPE_ENUM, FIELD_SUBTYPE_OBJECT, FIELD_SUBTYPE_STRING, FIELD_SUBTYPE_CLASS, FIELD_SUBTYPE_UUID, FIELD_SUBTYPE_INT, FIELD_SUBTYPE_SHORT, FIELD_SUBTYPE_BYTE, FIELD_SUBTYPE_LONG, FIELD_SUBTYPE_DOUBLE, FIELD_SUBTYPE_FLOAT, FIELD_SUBTYPE_DECIMAL, FIELD_SUBTYPE_CURRENCY, FIELD_SUBTYPE_BOOLEAN, FIELD_SUBTYPE_DATE, FIELD_SUBTYPE_TIME, FIELD_SUBTYPE_TIMESTAMP, FIELD_ATTR_REQUIRED, FIELD_ATTR_UNIQUE, FIELD_ATTR_OBJECT_REF, FIELD_ATTR_MAX_LENGTH, FIELD_ATTR_DEFAULT, VALIDATOR_SUBTYPE_LENGTH, VALIDATOR_SUBTYPE_REGEX, VALIDATOR_SUBTYPE_NUMERIC, VALIDATOR_SUBTYPE_REQUIRED, VALIDATOR_ATTR_PATTERN, VALIDATOR_ATTR_MIN, VALIDATOR_ATTR_MAX, DOC_ATTR_DESCRIPTION, stripPackage, } from "@metaobjectsdev/metadata";
-import { mapColumnType } from "../column-mapper.js";
-import { toPascalCase } from "../naming.js";
+import { TYPE_TEMPLATE, TEMPLATE_ATTR_PAYLOAD_REF, OBJECT_SUBTYPE_VALUE, IDENTITY_SUBTYPE_PRIMARY, IDENTITY_SUBTYPE_SECONDARY, IDENTITY_SUBTYPE_REFERENCE, IDENTITY_ATTR_GENERATION, RELATIONSHIP_ATTR_CARDINALITY, RELATIONSHIP_ATTR_OBJECT_REF, RELATIONSHIP_ATTR_THROUGH, RELATIONSHIP_ATTR_SOURCE_REF_FIELD, RELATIONSHIP_ATTR_SYMMETRIC, RELATIONSHIP_SUBTYPE_COMPOSITION, RELATIONSHIP_SUBTYPE_AGGREGATION, RELATIONSHIP_SUBTYPE_ASSOCIATION, FIELD_SUBTYPE_ENUM, FIELD_SUBTYPE_OBJECT, FIELD_ATTR_REQUIRED, FIELD_ATTR_UNIQUE, FIELD_ATTR_OBJECT_REF, FIELD_ATTR_MAX_LENGTH, FIELD_ATTR_DEFAULT, VALIDATOR_SUBTYPE_LENGTH, VALIDATOR_SUBTYPE_REGEX, VALIDATOR_SUBTYPE_NUMERIC, VALIDATOR_SUBTYPE_REQUIRED, VALIDATOR_ATTR_PATTERN, VALIDATOR_ATTR_MIN, VALIDATOR_ATTR_MAX, DOC_ATTR_DESCRIPTION, DOC_ATTR_SUMMARY, FIELD_ATTR_DB_COLUMN_TYPE, stripPackage, } from "@metaobjectsdev/metadata";
+import { docPageHref, docPageNode } from "../docs-paths.js";
+import { fieldAnchorHtml } from "./field-anchor.js";
 import { enumValues } from "../enum-meta.js";
 import { hasWritableRdbSource } from "../source-detect.js";
 import { GENERATED_HEADER } from "../constants.js";
-const SCALAR_TS_BY_SUBTYPE = {
-    [FIELD_SUBTYPE_STRING]: "string",
-    [FIELD_SUBTYPE_CLASS]: "string",
-    [FIELD_SUBTYPE_UUID]: "string",
-    [FIELD_SUBTYPE_INT]: "number",
-    [FIELD_SUBTYPE_SHORT]: "number",
-    [FIELD_SUBTYPE_BYTE]: "number",
-    [FIELD_SUBTYPE_LONG]: "number",
-    [FIELD_SUBTYPE_DOUBLE]: "number",
-    [FIELD_SUBTYPE_FLOAT]: "number",
-    // field.decimal is precision-exact: surfaced as a TS `string` (Drizzle pg
-    // `numeric` infers `string`). Keep the docs scalar mapping in lockstep.
-    [FIELD_SUBTYPE_DECIMAL]: "string",
-    [FIELD_SUBTYPE_CURRENCY]: "number",
-    [FIELD_SUBTYPE_BOOLEAN]: "boolean",
-    [FIELD_SUBTYPE_DATE]: "string",
-    [FIELD_SUBTYPE_TIME]: "string",
-    [FIELD_SUBTYPE_TIMESTAMP]: "string",
-};
-function enumTypeAliasName(entity, field) {
-    const superField = field.resolveSuper();
-    return superField !== undefined
-        ? toPascalCase(superField.name)
-        : `${entity.name}${toPascalCase(field.name)}`;
-}
-function isFieldRequired(field) {
-    if (field.ownAttr(FIELD_ATTR_REQUIRED) === true)
+import { renderEntityNeighborhoodErBlock } from "../templates/mermaid-er.js";
+/** Whether a field is required — `@required` true OR a `validator.required`
+ *  child. The SINGLE source of truth for required-ness across the Constraints
+ *  table, the Storage nullable rule, and (via the api-docs field-shape builder)
+ *  the documented model-field optionality. Exported so the field-shape builder
+ *  reuses the EXACT same rule rather than re-deriving it. */
+export function isFieldRequired(field) {
+    if (field.attr(FIELD_ATTR_REQUIRED) === true)
         return true;
     return field.validators().some((v) => v.subType === VALIDATOR_SUBTYPE_REQUIRED);
 }
-function tsTypeForStorage(entity, field, pkFieldNames) {
-    let base;
-    if (field.subType === FIELD_SUBTYPE_ENUM) {
-        const values = enumValues(field);
-        if (values !== undefined && values.length > 0) {
-            if (field.isArray) {
-                base = `${enumTypeAliasName(entity, field)}[]`;
-            }
-            else {
-                base = values.map((v) => JSON.stringify(v)).join(" | ");
+function collectValidatorParts(field) {
+    const maxLenAttr = field.attr(FIELD_ATTR_MAX_LENGTH);
+    const regexParts = [];
+    const lengthParts = [];
+    const numericParts = [];
+    for (const v of field.validators()) {
+        if (v.subType === VALIDATOR_SUBTYPE_REGEX) {
+            const pattern = v.ownAttr(VALIDATOR_ATTR_PATTERN);
+            if (typeof pattern === "string" && pattern.length > 0) {
+                regexParts.push(`pattern \`${pattern}\``);
             }
         }
-        else {
-            base = field.isArray ? "string[]" : "string";
+        else if (v.subType === VALIDATOR_SUBTYPE_LENGTH) {
+            const min = v.ownAttr(VALIDATOR_ATTR_MIN);
+            const max = v.ownAttr(VALIDATOR_ATTR_MAX);
+            if (typeof min === "number")
+                lengthParts.push(`minLength: ${min}`);
+            if (typeof max === "number" && typeof maxLenAttr !== "number")
+                lengthParts.push(`maxLength: ${max}`);
+        }
+        else if (v.subType === VALIDATOR_SUBTYPE_NUMERIC) {
+            const min = v.ownAttr(VALIDATOR_ATTR_MIN);
+            const max = v.ownAttr(VALIDATOR_ATTR_MAX);
+            if (typeof min === "number")
+                numericParts.push(`min: ${min}`);
+            if (typeof max === "number")
+                numericParts.push(`max: ${max}`);
         }
     }
-    else if (field.subType === FIELD_SUBTYPE_OBJECT) {
-        const ref = field.ownAttr(FIELD_ATTR_OBJECT_REF);
-        const refName = typeof ref === "string" && ref.length > 0 ? ref : "unknown";
-        base = field.isArray ? `${refName}[]` : refName;
+    return {
+        maxLenAttr: typeof maxLenAttr === "number" ? maxLenAttr : undefined,
+        regexParts,
+        lengthParts,
+        numericParts,
+    };
+}
+/** The NEUTRAL logical type string (no backticks): the field's logical
+ *  subtype (e.g. `string`, `enum`, `decimal`), suffixed `[]` for arrays, and
+ *  the referenced object name for `field.object`. Language-agnostic — built
+ *  from declared metadata, never re-derived into ANSI/ORM SQL. Shared by the
+ *  Constraints table (`neutralTypeCell`) and the Storage table's physical-type
+ *  fallback (`storageTypeCell`). */
+export function neutralTypeStr(field) {
+    let base;
+    if (field.subType === FIELD_SUBTYPE_OBJECT) {
+        const ref = field.attr(FIELD_ATTR_OBJECT_REF);
+        base = typeof ref === "string" && ref.length > 0 ? stripPackage(ref) : "object";
     }
     else {
-        const scalar = SCALAR_TS_BY_SUBTYPE[field.subType] ?? "unknown";
-        base = field.isArray ? `${scalar}[]` : scalar;
+        base = field.subType;
     }
-    const required = pkFieldNames.has(field.name) || isFieldRequired(field);
-    return required ? base : `${base} | null`;
+    if (field.isArray)
+        base = `${base}[]`;
+    return base;
 }
-function sqlColumnExpr(spec) {
-    const dbName = JSON.stringify(spec.dbName);
-    if (spec.fnOptions !== undefined && Object.keys(spec.fnOptions).length > 0) {
-        const parts = [];
-        for (const [k, v] of Object.entries(spec.fnOptions)) {
-            const lit = JSON.stringify(v);
-            if (Array.isArray(v)) {
-                parts.push(`${k}: ${lit} as const`);
-            }
-            else {
-                parts.push(`${k}: ${lit}`);
-            }
+/** Neutral logical type cell for the Constraints table — `neutralTypeStr`
+ *  wrapped in backticks. */
+function neutralTypeCell(field) {
+    return `\`${neutralTypeStr(field)}\``;
+}
+/** Neutral PHYSICAL type cell for the Storage table. Metadata-driven, no DDL
+ *  re-derivation (ADR-0020): if the field declares a `@dbColumnType` physical
+ *  override (e.g. `uuid`, `jsonb`, `timestamp_with_tz`) show it UPPERCASED;
+ *  otherwise fall back to the same neutral LOGICAL type the Constraints table
+ *  uses. Deliberately does NOT derive ANSI/ORM SQL so it can't drift vs the
+ *  migrate engine or re-introduce language-specific DDL. Wrapped in backticks. */
+function storageTypeCell(field) {
+    const dbColumnType = field.attr(FIELD_ATTR_DB_COLUMN_TYPE);
+    if (typeof dbColumnType === "string" && dbColumnType.length > 0) {
+        return `\`${dbColumnType.toUpperCase()}\``;
+    }
+    return `\`${neutralTypeStr(field)}\``;
+}
+/** Build one neutral Constraints-table row for a field. Reuses the same
+ *  per-field constraint logic as `constraintsCell()` (required-ness, maxLength,
+ *  enum CHECK-sets, validators, default, unique, references), but splits the
+ *  facts across the Required / Limits / Rules columns instead of one cell.
+ *  Renders for every field, with or without storage. */
+function buildConstraintRow(entity, field, pkFieldNames, fkMap) {
+    const isPk = pkFieldNames.has(field.name);
+    const required = isPk || isFieldRequired(field);
+    const limits = [];
+    const rules = [];
+    if (isPk)
+        rules.push("primary key");
+    if (field.attr(FIELD_ATTR_UNIQUE) === true)
+        rules.push("unique");
+    if (field.subType === FIELD_SUBTYPE_ENUM && !field.isArray) {
+        const values = enumValues(field);
+        if (values !== undefined && values.length > 0) {
+            const list = values.map((v) => `\`${v}\``).join(", ");
+            rules.push(`one of ${list}`);
         }
-        return `${spec.fnName}(${dbName}, { ${parts.join(", ")} })`;
     }
-    return `${spec.fnName}(${dbName})`;
+    // Same validator facts as constraintsCell() (shared walk), arranged across
+    // the Limits / Rules columns instead of one cell.
+    const { maxLenAttr, regexParts, lengthParts, numericParts } = collectValidatorParts(field);
+    rules.push(...regexParts);
+    if (maxLenAttr !== undefined)
+        limits.push(`maxLength: ${maxLenAttr}`);
+    limits.push(...lengthParts, ...numericParts);
+    const fk = fkMap.get(field.name);
+    if (fk !== undefined) {
+        rules.push(`references \`${fk.targetEntity}.${fk.targetField}\``);
+    }
+    const def = field.attr(FIELD_ATTR_DEFAULT);
+    if (def !== undefined)
+        rules.push(`default: \`${String(def)}\``);
+    const sup = field.resolveSuper();
+    if (sup !== undefined)
+        rules.push(`extends \`${sup.name}\``);
+    return {
+        // The Field cell carries a stable HTML anchor (`<a id="field-<name>">`)
+        // before the backticked name, so the template-source annotator's
+        // `#field-<name>` links resolve. Slug = `fieldAnchorSlug(name)` — the SINGLE
+        // source shared with the annotator so anchor and link can't drift. The
+        // anchor is a language-independent HTML id, so the page stays neutral.
+        field: `${fieldAnchorHtml(field.name)}\`${field.name}\``,
+        required: required ? "yes" : "",
+        type: neutralTypeCell(field),
+        limits: limits.join(", "),
+        rules: rules.join(", "),
+    };
 }
-function constraintsCell(entity, field, pkFieldNames, fkMap) {
-    const parts = [];
-    if (pkFieldNames.has(field.name)) {
-        parts.push("primary key");
-        const primary = entity.primaryIdentity();
-        const gen = primary?.ownAttr(IDENTITY_ATTR_GENERATION);
-        if (typeof gen === "string") {
-            parts.push(`generation: \`${gen}\``);
+/** Build one row of the unified Fields table — collapses the per-field facts
+ *  the old Storage + Constraints tables split between into a single Markdown
+ *  row. PK/FK key role becomes a glyph prefix on the Field cell, the FK
+ *  target becomes a `→ \`Target\`` suffix on the Type cell, the @column
+ *  override (only when interesting) lands in the Storage cell, everything
+ *  else (validators, defaults, enum CHECK-sets, references, unique, extends)
+ *  goes into the Rules cell joined by " · ".
+ *
+ *  Identity bullets remain a separate section above — they describe the
+ *  *identity declarations* (composite keys, generation strategy, reference
+ *  topology), not the per-field facts. */
+function buildFieldRow(entity, field, pkFieldNames, fkMap) {
+    const isPk = pkFieldNames.has(field.name);
+    const fk = fkMap.get(field.name);
+    const required = isPk || isFieldRequired(field);
+    // Field cell — anchor + glyph + name.
+    let glyph = "";
+    if (isPk)
+        glyph = "🔑 ";
+    else if (fk !== undefined)
+        glyph = "🔗 ";
+    const fieldCell = `${fieldAnchorHtml(field.name)}${glyph}\`${field.name}\``;
+    // Type cell — neutral logical type; for FK, append the target as a link.
+    let typeCell = neutralTypeCell(field);
+    if (fk !== undefined) {
+        typeCell = `${typeCell} → \`${fk.targetEntity}\``;
+    }
+    // Storage cell — only populated when interesting:
+    //   - @column override that differs from the field name, OR
+    //   - @dbColumnType physical override set
+    // Otherwise empty. Keeps the column noise-free for the 90% case where
+    // field name and column name agree.
+    const columnName = field.column;
+    const dbColumnType = field.attr(FIELD_ATTR_DB_COLUMN_TYPE);
+    const columnDiffers = typeof columnName === "string" && columnName !== field.name;
+    const hasPhysicalOverride = typeof dbColumnType === "string" && dbColumnType.length > 0;
+    let storageCell = "";
+    if (columnDiffers && hasPhysicalOverride) {
+        storageCell = `\`${columnName}\` \`${dbColumnType.toUpperCase()}\``;
+    }
+    else if (columnDiffers) {
+        storageCell = `\`${columnName}\``;
+    }
+    else if (hasPhysicalOverride) {
+        storageCell = `\`${dbColumnType.toUpperCase()}\``;
+    }
+    // Rules cell — joined facts. Same logic as buildConstraintRow's Rules
+    // column, plus the maxLength/length/numeric limits that used to live in
+    // the separate Limits cell (collapsed in to keep the table to 5 columns).
+    const rules = [];
+    if (field.attr(FIELD_ATTR_UNIQUE) === true)
+        rules.push("unique");
+    if (field.subType === FIELD_SUBTYPE_ENUM && !field.isArray) {
+        const values = enumValues(field);
+        if (values !== undefined && values.length > 0) {
+            const list = values.map((v) => `\`${v}\``).join(", ");
+            rules.push(`one of ${list}`);
         }
     }
+    const { maxLenAttr, regexParts, lengthParts, numericParts } = collectValidatorParts(field);
+    rules.push(...regexParts);
+    if (maxLenAttr !== undefined)
+        rules.push(`maxLength: ${maxLenAttr}`);
+    rules.push(...lengthParts, ...numericParts);
+    // The FK reference is already encoded in typeCell — don't repeat it in rules.
+    const def = field.attr(FIELD_ATTR_DEFAULT);
+    if (def !== undefined)
+        rules.push(`default: \`${String(def)}\``);
+    const sup = field.resolveSuper();
+    if (sup !== undefined)
+        rules.push(`extends \`${sup.name}\``);
+    return {
+        field: field.name,
+        fieldCell,
+        typeCell,
+        requiredCell: required ? "yes" : "",
+        storageCell,
+        rulesCell: rules.join(" · "),
+    };
+}
+/** Build an expanded per-field detail block — `### \`name\`` heading, italic
+ *  @summary lead-in, @description paragraph, then a bullet list of every
+ *  notable rule (validators, default, FK, extends-enum, column override).
+ *  Returns `undefined` when the field has nothing extra to say (just type +
+ *  required) — the caller filters these out so the section stays tight.
+ *
+ *  The validator list is the most important value-add: the Fields table
+ *  collapses `pattern \`X\` · maxLength: 200 · minLength: 3` into a single
+ *  Rules cell; this section breaks them out as individual bullets so the
+ *  reader can scan each rule on its own line. */
+function buildFieldDetail(field, pkFieldNames, fkMap) {
+    const desc = field.attr(DOC_ATTR_DESCRIPTION);
+    const summary = field.attr(DOC_ATTR_SUMMARY);
+    const hasDesc = typeof desc === "string" && desc.length > 0;
+    const hasSummary = typeof summary === "string" && summary.length > 0;
+    const sup = field.resolveSuper();
+    const fk = fkMap.get(field.name);
+    const def = field.attr(FIELD_ATTR_DEFAULT);
+    const columnName = field.column;
+    const dbColumnType = field.attr(FIELD_ATTR_DB_COLUMN_TYPE);
+    const isUnique = field.attr(FIELD_ATTR_UNIQUE) === true;
+    const isEnum = field.subType === FIELD_SUBTYPE_ENUM && !field.isArray;
+    const enumVals = isEnum ? enumValues(field) : undefined;
+    const validators = field.validators();
+    const hasValidatorChildren = validators.some(v => v.subType === VALIDATOR_SUBTYPE_LENGTH
+        || v.subType === VALIDATOR_SUBTYPE_REGEX
+        || v.subType === VALIDATOR_SUBTYPE_NUMERIC);
+    const maxLenAttr = field.attr(FIELD_ATTR_MAX_LENGTH);
+    // "Interesting enough to render a detail block" predicate. Plain typed
+    // fields with no authored annotations get skipped — the at-a-glance Fields
+    // table covered them already.
+    //
+    // Deliberately NOT counted as "interesting":
+    //   - PK / required-ness (already a column in the table)
+    //   - mechanical @column overrides (adopters typically set
+    //     @column: PascalCase(name) wholesale; surfacing every field for
+    //     that alone would defeat the section's purpose)
+    // The detail section's value is surfacing AUTHORED docs + validators +
+    // business rules, not physical column mapping.
+    const isInteresting = hasDesc
+        || hasSummary
+        || sup !== undefined
+        || fk !== undefined
+        || def !== undefined
+        || hasValidatorChildren
+        || typeof maxLenAttr === "number"
+        || (enumVals !== undefined && enumVals.length > 0)
+        || isUnique
+        || (typeof dbColumnType === "string" && dbColumnType.length > 0);
+    if (!isInteresting)
+        return undefined;
+    const parts = [`### \`${field.name}\``];
+    if (hasSummary) {
+        parts.push("");
+        parts.push(`*${summary}*`);
+    }
+    if (hasDesc) {
+        parts.push("");
+        parts.push(String(desc).trim());
+    }
+    // Bullet list — one fact per line. Order: type → FK → required/PK → column
+    // → default → unique → extends → enum values → validators.
+    const bullets = [];
+    bullets.push(`**Type:** ${neutralTypeCell(field)}`);
+    if (fk !== undefined) {
+        bullets.push(`**References:** [\`${fk.targetEntity}.${fk.targetField}\`](${fk.targetEntity}.md)`);
+    }
+    if (pkFieldNames.has(field.name)) {
+        bullets.push("**Primary key**");
+    }
     else if (isFieldRequired(field)) {
-        parts.push("required");
+        bullets.push("**Required**");
     }
-    else {
-        parts.push("optional");
+    if (typeof columnName === "string" && columnName !== field.name) {
+        bullets.push(`**Column:** \`${columnName}\``);
     }
-    if (field.ownAttr(FIELD_ATTR_UNIQUE) === true) {
-        parts.push("unique");
+    if (typeof dbColumnType === "string" && dbColumnType.length > 0) {
+        bullets.push(`**Physical type:** \`${dbColumnType.toUpperCase()}\``);
     }
-    if (field.isArray) {
-        parts.push("JSON column");
+    if (def !== undefined) {
+        bullets.push(`**Default:** \`${String(def)}\``);
     }
-    if (field.subType === FIELD_SUBTYPE_ENUM && !field.isArray) {
-        const values = enumValues(field);
-        if (values !== undefined && values.length > 0) {
-            const list = values.map((v) => `'${v.replace(/'/g, "''")}'`).join(", ");
-            parts.push(`CHECK \`${field.column ?? field.name} IN (${list})\``);
-        }
+    if (isUnique)
+        bullets.push("**Unique**");
+    if (sup !== undefined) {
+        // The postprocess script rewrites `extends \`Name\`` → enum anchor link.
+        bullets.push(`**Extends:** \`${sup.name}\``);
     }
-    // Walk validators once, bucket by subtype. We re-emit in the original
-    // emission order to preserve byte-identity with the docs-file-basic
-    // conformance fixture: regex pattern → maxLength-from-@maxLength →
-    // length-validator (min/max) → numeric-validator (min/max).
-    const maxLenAttr = field.ownAttr(FIELD_ATTR_MAX_LENGTH);
-    const regexParts = [];
-    const lengthParts = [];
-    const numericParts = [];
-    for (const v of field.validators()) {
+    if (enumVals !== undefined && enumVals.length > 0) {
+        const vals = enumVals.map((v) => `\`${v}\``).join(" · ");
+        bullets.push(`**Enum values:** ${vals}`);
+    }
+    // Validators — one bullet per validator subtype (regex / length / numeric),
+    // rendered in declaration order so authors can rely on the order they
+    // wrote.
+    for (const v of validators) {
         if (v.subType === VALIDATOR_SUBTYPE_REGEX) {
             const pattern = v.ownAttr(VALIDATOR_ATTR_PATTERN);
             if (typeof pattern === "string" && pattern.length > 0) {
-                regexParts.push(`pattern \`${pattern}\``);
+                bullets.push(`**Validator (regex):** pattern \`${pattern}\``);
             }
         }
         else if (v.subType === VALIDATOR_SUBTYPE_LENGTH) {
             const min = v.ownAttr(VALIDATOR_ATTR_MIN);
             const max = v.ownAttr(VALIDATOR_ATTR_MAX);
+            const fragments = [];
             if (typeof min === "number")
-                lengthParts.push(`minLength: ${min}`);
-            if (typeof max === "number" && typeof maxLenAttr !== "number")
-                lengthParts.push(`maxLength: ${max}`);
+                fragments.push(`min ${min}`);
+            if (typeof max === "number")
+                fragments.push(`max ${max}`);
+            if (fragments.length > 0)
+                bullets.push(`**Validator (length):** ${fragments.join(", ")}`);
         }
         else if (v.subType === VALIDATOR_SUBTYPE_NUMERIC) {
             const min = v.ownAttr(VALIDATOR_ATTR_MIN);
             const max = v.ownAttr(VALIDATOR_ATTR_MAX);
+            const fragments = [];
             if (typeof min === "number")
-                numericParts.push(`min: ${min}`);
+                fragments.push(`min ${min}`);
             if (typeof max === "number")
-                numericParts.push(`max: ${max}`);
+                fragments.push(`max ${max}`);
+            if (fragments.length > 0)
+                bullets.push(`**Validator (numeric):** ${fragments.join(", ")}`);
         }
     }
-    parts.push(...regexParts);
+    // @maxLength is the shorthand; render alongside validators for consistency.
     if (typeof maxLenAttr === "number") {
-        parts.push(`maxLength: ${maxLenAttr}`);
-    }
-    parts.push(...lengthParts, ...numericParts);
-    const fk = fkMap.get(field.name);
-    if (fk !== undefined) {
-        parts.push(`references \`${fk.targetEntity}.${fk.targetField}\``);
-    }
-    const def = field.ownAttr(FIELD_ATTR_DEFAULT);
-    if (def !== undefined) {
-        parts.push(`default: \`${String(def)}\``);
-    }
-    const sup = field.resolveSuper();
-    if (sup !== undefined) {
-        parts.push(`extends \`${sup.name}\``);
-    }
-    return parts.join(", ");
+        bullets.push(`**Max length:** ${maxLenAttr}`);
+    }
+    parts.push("");
+    for (const b of bullets)
+        parts.push(`- ${b}`);
+    return {
+        field: field.name,
+        block: parts.join("\n"),
+    };
 }
 function buildFkMap(entity, root) {
     const out = new Map();
@@ -191,13 +388,17 @@ function entityDescription(entity) {
     const v = entity.attr(DOC_ATTR_DESCRIPTION);
     return typeof v === "string" && v.length > 0 ? v : undefined;
 }
+function entitySummary(entity) {
+    const v = entity.attr(DOC_ATTR_SUMMARY);
+    return typeof v === "string" && v.length > 0 ? v : undefined;
+}
 function describeIdentity(id) {
     const fields = id.fields;
     const fieldList = fields.length === 1
         ? `\`${fields[0]}\``
         : `(${fields.map((f) => `\`${f}\``).join(", ")})`;
     if (id.subType === IDENTITY_SUBTYPE_PRIMARY) {
-        const gen = id.ownAttr(IDENTITY_ATTR_GENERATION);
+        const gen = id.attr(IDENTITY_ATTR_GENERATION);
         const genSuffix = typeof gen === "string" ? ` — generation: \`${gen}\`` : "";
         return `**Primary key:** ${fieldList}${genSuffix}`;
     }
@@ -235,33 +436,72 @@ function relationshipBullet(r) {
             break;
         default: label = subtype;
     }
+    // M:N (FR-018): the relationship traverses a junction (`@through`). Describe
+    // the edge as related-target THROUGH junction, and mark the self-join shape:
+    //   symmetric (undirected) → "symmetric self-join"
+    //   @sourceRefField set (directed) → "directed self-join via `<field>`"
+    // The junction/disambiguator are DECLARED facts (ADR-0020 — no re-derivation).
+    const throughRaw = r.ownAttr(RELATIONSHIP_ATTR_THROUGH);
+    if (typeof throughRaw === "string" && throughRaw.length > 0) {
+        const through = stripPackage(throughRaw);
+        const noteParts = [`${label}, through \`${through}\``];
+        if (r.ownAttr(RELATIONSHIP_ATTR_SYMMETRIC) === true) {
+            noteParts.push("symmetric self-join");
+        }
+        else {
+            const srcRef = r.ownAttr(RELATIONSHIP_ATTR_SOURCE_REF_FIELD);
+            if (typeof srcRef === "string" && srcRef.length > 0) {
+                noteParts.push(`directed self-join via \`${srcRef}\``);
+            }
+        }
+        return `\`${r.name}\` — ${card} → \`${target}\` (${noteParts.join(", ")})`;
+    }
     return `\`${r.name}\` — ${card} → \`${target}\` (${label})`;
 }
 /** Build the EntityDocData payload for one entity. The single public-API
  *  entry point exported by this module; the markdown template applies
  *  against this shape. */
 export function buildEntityDocData(entity, opts) {
-    const strategy = opts.columnNamingStrategy ?? "snake_case";
     const root = opts.loadedRoot;
+    const layout = opts.layout ?? "flat";
     const primary = entity.primaryIdentity();
     const pkFields = primary?.fields ?? [];
     const pkFieldNames = new Set(pkFields);
     const fkMap = buildFkMap(entity, root);
-    // ---- Storage rows
+    // ---- Storage rows — NEUTRAL physical persistence MAPPING (ADR-0020): the
+    // physical column name, a neutral physical type (declared `@dbColumnType`
+    // override else the logical type), nullability, and the key role. NO
+    // TypeScript type, NO ORM DDL, NO ANSI re-derivation — declared metadata
+    // facts only. The value-add over the Constraints table is the field→column
+    // mapping + physical-type override + key role.
     const storageRows = entity.fields().map((field) => {
-        const spec = mapColumnType(field, opts.dialect, strategy);
-        const tsType = tsTypeForStorage(entity, field, pkFieldNames);
-        const tsTypeCell = tsType.split("|").map((s) => s.trim()).join(" \\| ");
-        const sqlExpr = sqlColumnExpr(spec);
-        const cons = constraintsCell(entity, field, pkFieldNames, fkMap);
-        const tsTypeCellStr = `\`${tsTypeCell}\``;
-        const sqlExprCellStr = `\`${sqlExpr}\``;
+        const isPk = pkFieldNames.has(field.name);
+        // Physical column name: the field's `@column` override if set, else the
+        // field name. (The Storage section shows the RAW declared mapping; column
+        // naming-strategy folding stays a codegen concern, not a docs fact.)
+        const columnName = field.column ?? field.name;
+        const columnCell = `\`${columnName}\``;
+        const typeCell = storageTypeCell(field);
+        // Nullable iff not required and not the PK (matches the Constraints table's
+        // required-ness rule).
+        const nullable = !(isPk || isFieldRequired(field));
+        const nullableCell = nullable ? "yes" : "no";
+        let keyCell = "";
+        if (isPk) {
+            keyCell = "primary key";
+        }
+        else {
+            const fk = fkMap.get(field.name);
+            if (fk !== undefined)
+                keyCell = `foreign key → \`${fk.targetEntity}\``;
+        }
         return {
             name: field.name,
-            tsTypeCell: tsTypeCellStr,
-            sqlExprCell: sqlExprCellStr,
-            constraintsCell: cons,
-            rowLine: `| \`${field.name}\` | ${tsTypeCellStr} | ${sqlExprCellStr} | ${cons} |`,
+            columnCell,
+            typeCell,
+            nullableCell,
+            keyCell,
+            rowLine: `| ${columnCell} | ${typeCell} | ${nullableCell} | ${keyCell} |`,
         };
     });
     const isValue = entity.subType === OBJECT_SUBTYPE_VALUE;
@@ -276,13 +516,39 @@ export function buildEntityDocData(entity, opts) {
     const relationships = rels.length > 0
         ? rels.map((r) => ({ bullet: relationshipBullet(r) }))
         : undefined;
-    // ---- Validation
-    const lower = entity.name.charAt(0).toLowerCase() + entity.name.slice(1);
-    const validation = {
-        insertSchema: `${entity.name}InsertSchema`,
-        updateSchema: `${entity.name}UpdateSchema`,
-        entityFile: `${entity.name}.ts`,
-        lower,
+    // ---- Constraints (NEUTRAL — built from the object's OWN field metadata, so
+    // it renders for every object including value objects with no storage).
+    // KEPT FOR BACK-COMPAT — new templates render `fields` instead.
+    const constraintRows = entity
+        .fields()
+        .map((field) => buildConstraintRow(entity, field, pkFieldNames, fkMap));
+    const constraints = {
+        hasConstraints: constraintRows.length > 0,
+        rows: constraintRows,
+    };
+    // ---- Fields (merged Storage + Constraints) — the single per-field table
+    // the new entity-page template renders. Same source of truth as the two
+    // legacy tables, just folded into one row.
+    const fieldRows = entity
+        .fields()
+        .map((field) => buildFieldRow(entity, field, pkFieldNames, fkMap));
+    const fields = {
+        hasFields: fieldRows.length > 0,
+        rows: fieldRows,
+    };
+    // ---- Field details — expanded per-field section, skipping plain fields
+    // that the at-a-glance table already covered. The deeper "field details
+    // below the table" pattern adopted by Stripe / FHIR / GraphQL — keep the
+    // table tight, surface authoring + validation depth below.
+    const fieldDetailRows = [];
+    for (const field of entity.fields()) {
+        const detail = buildFieldDetail(field, pkFieldNames, fkMap);
+        if (detail !== undefined)
+            fieldDetailRows.push(detail);
+    }
+    const fieldDetails = {
+        hasDetails: fieldDetailRows.length > 0,
+        rows: fieldDetailRows,
     };
     // ---- UsedBy
     const usedByMatches = [];
@@ -294,36 +560,16 @@ export function buildEntityDocData(entity, opts) {
             continue;
         if (stripPackage(ref) !== entity.name)
             continue;
+        // Link to the template's own doc page. The href is derived from the SAME
+        // page-placement function used to write the template page, so it resolves
+        // in BOTH layouts (flat → `./<Tmpl>.md`; package → a correct relative path
+        // like `../comms/OrderEmail.md`).
+        const href = docPageHref(layout, docPageNode(entity), docPageNode(child));
         usedByMatches.push({
-            bullet: `\`template.${child.subType} ${child.name}\` — uses \`${entity.name}\` as \`@payloadRef\``,
+            bullet: `[\`template.${child.subType} ${child.name}\`](${href}) — uses \`${entity.name}\` as \`@payloadRef\``,
         });
     }
     const usedBy = usedByMatches.length > 0 ? usedByMatches : undefined;
-    // ---- Generated
-    const gens = opts.generatorNames ?? new Set();
-    const generated = [];
-    generated.push({
-        filename: `${entity.name}.ts`,
-        description: "Drizzle table, Zod schemas, type aliases, enum literal unions.",
-    });
-    if (gens.has("queries-file") && !isValue) {
-        generated.push({
-            filename: `${entity.name}.queries.ts`,
-            description: "typed CRUD helpers (find / list / create / update / delete; takes `db` as first param per ADR-0008).",
-        });
-    }
-    if (gens.has("routes-file") && !isValue) {
-        generated.push({
-            filename: `${entity.name}.routes.ts`,
-            description: `Fastify CRUD-5 route registration (\`register${entity.name}Routes\`).`,
-        });
-    }
-    if (gens.has("routes-file-hono") && !isValue) {
-        generated.push({
-            filename: `${entity.name}.routes.hono.ts`,
-            description: `Hono CRUD-5 route registration (\`register${entity.name}Routes\`).`,
-        });
-    }
     // Preamble header — built up exactly as the legacy emitter did.
     const preambleLines = [];
     const typeStr = `${entity.type}.${entity.subType}`;
@@ -341,6 +587,10 @@ export function buildEntityDocData(entity, opts) {
     if (desc !== undefined) {
         descriptionQuote = desc.split("\n").map((l) => `> ${l}`.trimEnd()).join("\n");
     }
+    // Summary — short single-line tagline. Rendered as italic lead-in just under
+    // the H1, ABOVE @description. Distinct enough that an entity can carry both
+    // (description = paragraph; summary = headline).
+    const summary = entitySummary(entity);
     const data = {
         generatedMarker: `<!-- ${GENERATED_HEADER} — DO NOT EDIT. -->`,
         entity: {
@@ -348,13 +598,29 @@ export function buildEntityDocData(entity, opts) {
             type: typeStr,
         },
         preambleHeader,
-        validation,
-        generated,
+        fields,
+        fieldDetails,
+        constraints,
     };
     if (desc !== undefined)
         data.entity.description = desc;
+    if (summary !== undefined) {
+        data.entity.summary = summary;
+        data.summaryLead = `*${summary}*`;
+    }
     if (descriptionQuote !== undefined)
         data.descriptionQuote = descriptionQuote;
+    // 1-hop neighborhood diagram — every entity it FKs into + every entity that
+    // FKs into it. Rendered just above the Relationships section in the entity
+    // page template. Skipped when the entity has zero neighbors (no orphan
+    // empty diagram block).
+    const neighborhoodErBlock = hasStorage
+        ? renderEntityNeighborhoodErBlock(entity, root)
+        : undefined;
+    if (neighborhoodErBlock !== undefined) {
+        data.neighborhoodErBlock = neighborhoodErBlock;
+        data.hasNeighborhoodEr = true;
+    }
     if (src !== undefined)
         data.entity.source = src;
     if (entity.package !== undefined && entity.package !== "") {
@@ -362,7 +628,7 @@ export function buildEntityDocData(entity, opts) {
     }
     if (hasStorage) {
         data.storage = {
-            tableHeader: "| Field | TypeScript type | SQL column | Constraints |\n|---|---|---|---|",
+            tableHeader: "| Column | Type | Nullable | Key |\n|---|---|---|---|",
             rows: storageRows,
         };
         data.hasStorage = true;
@@ -379,6 +645,12 @@ export function buildEntityDocData(entity, opts) {
         data.usedBy = usedBy;
         data.hasUsedBy = true;
     }
+    // Cross-link to the api surfaces — present ONLY when the caller computed the
+    // hrefs (api surfaces emitted alongside model); model-only runs stay identical.
+    // `last` flags the final ref so the template renders an inline ` · ` separator.
+    if (opts.apiRefs !== undefined) {
+        data.apiRefs = opts.apiRefs.map((r, i, arr) => ({ ...r, last: i === arr.length - 1 }));
+    }
     return data;
 }
 //# sourceMappingURL=docs-data-builder.js.map