fix(plugin-documentation): address second round of CodeRabbit review feedback

sheldonj · sheldonj · commit e39823b7d366 · 2026-02-22T23:11:59.000Z
- Add pre-flight check in preview-themes.ts for missing .mmd input
- Use getAllFields() in collectRelationships to include inherited/mixin fields
- Track hasErdSvg/hasErdMmd separately to avoid broken index links when
  erdFormat is not 'both'
- Move Mermaid entity overflow indicator outside the block as a %% comment
  to avoid invalid erDiagram syntax
diff --git a/packages/plugins/documentation/preview-output/showcase/index.md b/packages/plugins/documentation/preview-output/showcase/index.md
@@ -85,7 +85,7 @@ This documentation describes a [ZModel](https://zenstack.dev/docs/reference/zmod
 | Metric | Value |
 | --- | --- |
 | **Files** | 29 |
-| **Duration** | 64.56 ms |
+| **Duration** | 143.23 ms |
 | **Source** | `showcase.zmodel` |
 | **Generated** | 2026-02-22 |
 
diff --git a/packages/plugins/documentation/preview-output/showcase/models/Activity.md b/packages/plugins/documentation/preview-output/showcase/models/Activity.md
@@ -99,8 +99,8 @@ erDiagram
         Priority priority
         DateTime dueDate
         Float estimatedHours
-        _more_ and_4_more_fields
     }
+    %% … and 4 more fields
     User {
         DateTime createdAt
         DateTime updatedAt
diff --git a/packages/plugins/documentation/preview-output/showcase/models/Comment.md b/packages/plugins/documentation/preview-output/showcase/models/Comment.md
@@ -108,8 +108,8 @@ erDiagram
         Priority priority
         DateTime dueDate
         Float estimatedHours
-        _more_ and_4_more_fields
     }
+    %% … and 4 more fields
     Comment }o--|| User : "author"
     Comment }o--|| Task : "task"
 ```
diff --git a/packages/plugins/documentation/preview-output/showcase/models/Organization.md b/packages/plugins/documentation/preview-output/showcase/models/Organization.md
@@ -104,8 +104,8 @@ erDiagram
         Float completionRate
         Boolean hasOverdueTasks
         String organizationId
-        _more_ and_1_more_fields
     }
+    %% … and 1 more fields
     Team {
         DateTime createdAt
         DateTime updatedAt
diff --git a/packages/plugins/documentation/preview-output/showcase/models/Project.md b/packages/plugins/documentation/preview-output/showcase/models/Project.md
@@ -133,8 +133,8 @@ erDiagram
         Priority priority
         DateTime dueDate
         Float estimatedHours
-        _more_ and_4_more_fields
     }
+    %% … and 4 more fields
     Team {
         DateTime createdAt
         DateTime updatedAt
diff --git a/packages/plugins/documentation/preview-output/showcase/models/Tag.md b/packages/plugins/documentation/preview-output/showcase/models/Tag.md
@@ -76,8 +76,8 @@ erDiagram
         Float completionRate
         Boolean hasOverdueTasks
         String organizationId
-        _more_ and_1_more_fields
     }
+    %% … and 1 more fields
     Task {
         DateTime createdAt
         DateTime updatedAt
@@ -89,8 +89,8 @@ erDiagram
         Priority priority
         DateTime dueDate
         Float estimatedHours
-        _more_ and_4_more_fields
     }
+    %% … and 4 more fields
     Tag ||--o{ Project : "projects"
     Tag ||--o{ Task : "tasks"
 ```
diff --git a/packages/plugins/documentation/preview-output/showcase/models/Task.md b/packages/plugins/documentation/preview-output/showcase/models/Task.md
@@ -160,8 +160,8 @@ erDiagram
         Priority priority
         DateTime dueDate
         Float estimatedHours
-        _more_ and_4_more_fields
     }
+    %% … and 4 more fields
     Comment {
         DateTime createdAt
         DateTime updatedAt
@@ -181,8 +181,8 @@ erDiagram
         Float completionRate
         Boolean hasOverdueTasks
         String organizationId
-        _more_ and_1_more_fields
     }
+    %% … and 1 more fields
     Tag {
         String id
         String name
diff --git a/packages/plugins/documentation/preview-output/showcase/models/Team.md b/packages/plugins/documentation/preview-output/showcase/models/Team.md
@@ -116,8 +116,8 @@ erDiagram
         Float completionRate
         Boolean hasOverdueTasks
         String organizationId
-        _more_ and_1_more_fields
     }
+    %% … and 1 more fields
     Team ||--o{ TeamMember : "members"
     Team }o--|| Organization : "organization"
     Team ||--o{ Project : "projects"
diff --git a/packages/plugins/documentation/preview-output/showcase/models/User.md b/packages/plugins/documentation/preview-output/showcase/models/User.md
@@ -127,8 +127,8 @@ erDiagram
         Priority priority
         DateTime dueDate
         Float estimatedHours
-        _more_ and_4_more_fields
     }
+    %% … and 4 more fields
     Comment {
         DateTime createdAt
         DateTime updatedAt
diff --git a/packages/plugins/documentation/preview-output/verbose/index.md b/packages/plugins/documentation/preview-output/verbose/index.md
@@ -89,7 +89,7 @@ This documentation describes a [ZModel](https://zenstack.dev/docs/reference/zmod
 | Metric | Value |
 | --- | --- |
 | **Files** | 33 |
-| **Duration** | 35.01 ms |
+| **Duration** | 34.22 ms |
 | **Source** | `schema.zmodel` |
 | **Generated** | 2026-02-22 |
 
diff --git a/packages/plugins/documentation/preview-output/verbose/models/Article.md b/packages/plugins/documentation/preview-output/verbose/models/Article.md
@@ -173,8 +173,8 @@ erDiagram
         String handle
         String avatarUrl
         String timezone
-        _more_ and_3_more_fields
     }
+    %% … and 3 more fields
     Category {
         DateTime createdAt
         DateTime updatedAt
diff --git a/packages/plugins/documentation/preview-output/verbose/models/Category.md b/packages/plugins/documentation/preview-output/verbose/models/Category.md
@@ -110,8 +110,8 @@ erDiagram
         String body
         String excerpt
         ArticleStatus status
-        _more_ and_11_more_fields
     }
+    %% … and 11 more fields
     Workspace {
         DateTime createdAt
         DateTime updatedAt
diff --git a/packages/plugins/documentation/preview-output/verbose/models/Comment.md b/packages/plugins/documentation/preview-output/verbose/models/Comment.md
@@ -129,8 +129,8 @@ erDiagram
         String body
         String excerpt
         ArticleStatus status
-        _more_ and_11_more_fields
     }
+    %% … and 11 more fields
     User {
         DateTime createdAt
         DateTime updatedAt
@@ -142,8 +142,8 @@ erDiagram
         String handle
         String avatarUrl
         String timezone
-        _more_ and_3_more_fields
     }
+    %% … and 3 more fields
     Comment {
         DateTime createdAt
         DateTime updatedAt
diff --git a/packages/plugins/documentation/preview-output/verbose/models/Invoice.md b/packages/plugins/documentation/preview-output/verbose/models/Invoice.md
@@ -126,8 +126,8 @@ erDiagram
         BillingInterval billingInterval
         DateTime currentPeriodStart
         DateTime currentPeriodEnd
-        _more_ and_5_more_fields
     }
+    %% … and 5 more fields
     Invoice }o--|| Subscription : "subscription"
 ```
 
diff --git a/packages/plugins/documentation/preview-output/verbose/models/Notification.md b/packages/plugins/documentation/preview-output/verbose/models/Notification.md
@@ -123,8 +123,8 @@ erDiagram
         String handle
         String avatarUrl
         String timezone
-        _more_ and_3_more_fields
     }
+    %% … and 3 more fields
     Notification }o--|| User : "recipient"
 ```
 
diff --git a/packages/plugins/documentation/preview-output/verbose/models/NotificationPreference.md b/packages/plugins/documentation/preview-output/verbose/models/NotificationPreference.md
@@ -106,8 +106,8 @@ erDiagram
         String handle
         String avatarUrl
         String timezone
-        _more_ and_3_more_fields
     }
+    %% … and 3 more fields
     NotificationPreference }o--|| User : "user"
 ```
 
diff --git a/packages/plugins/documentation/preview-output/verbose/models/Subscription.md b/packages/plugins/documentation/preview-output/verbose/models/Subscription.md
@@ -144,8 +144,8 @@ erDiagram
         DateTime lastPaymentAttempt
         Int paymentAttempts
         String stripeInvoiceId
-        _more_ and_2_more_fields
     }
+    %% … and 2 more fields
     Workspace {
         DateTime createdAt
         DateTime updatedAt
diff --git a/packages/plugins/documentation/preview-output/verbose/models/User.md b/packages/plugins/documentation/preview-output/verbose/models/User.md
@@ -142,8 +142,8 @@ erDiagram
         String body
         String excerpt
         ArticleStatus status
-        _more_ and_11_more_fields
     }
+    %% … and 11 more fields
     Comment {
         DateTime createdAt
         DateTime updatedAt
@@ -186,8 +186,8 @@ erDiagram
         NotificationSeverity severity
         Boolean read
         String actionUrl
-        _more_ and_2_more_fields
     }
+    %% … and 2 more fields
     User ||--o{ Article : "articles"
     User ||--o{ Comment : "comments"
     User ||--o{ WorkspaceMember : "memberships"
diff --git a/packages/plugins/documentation/preview-output/verbose/models/Workspace.md b/packages/plugins/documentation/preview-output/verbose/models/Workspace.md
@@ -130,8 +130,8 @@ erDiagram
         String body
         String excerpt
         ArticleStatus status
-        _more_ and_11_more_fields
     }
+    %% … and 11 more fields
     Category {
         DateTime createdAt
         DateTime updatedAt
@@ -175,8 +175,8 @@ erDiagram
         BillingInterval billingInterval
         DateTime currentPeriodStart
         DateTime currentPeriodEnd
-        _more_ and_5_more_fields
     }
+    %% … and 5 more fields
     Workspace ||--o{ Article : "articles"
     Workspace ||--o{ Category : "categories"
     Workspace ||--o{ Comment : "comments"
diff --git a/packages/plugins/documentation/preview-output/verbose/models/WorkspaceMember.md b/packages/plugins/documentation/preview-output/verbose/models/WorkspaceMember.md
@@ -116,8 +116,8 @@ erDiagram
         String handle
         String avatarUrl
         String timezone
-        _more_ and_3_more_fields
     }
+    %% … and 3 more fields
     Workspace {
         DateTime createdAt
         DateTime updatedAt
diff --git a/packages/plugins/documentation/scripts/preview-themes.ts b/packages/plugins/documentation/scripts/preview-themes.ts
@@ -8,6 +8,11 @@ const mmdPath = path.resolve(__dirname, '../preview-output/showcase/schema-erd.m
 const outDir = path.resolve(__dirname, '../preview-output/themes');
 
 async function run() {
+    if (!fs.existsSync(mmdPath)) {
+        console.error(`Input file not found: ${mmdPath}`);
+        console.error('Run `npx tsx scripts/preview.ts` first to generate the showcase ERD.');
+        process.exit(1);
+    }
     const mermaidSource = fs.readFileSync(mmdPath, 'utf-8');
     fs.mkdirSync(outDir, { recursive: true });
 
diff --git a/packages/plugins/documentation/src/extractors.ts b/packages/plugins/documentation/src/extractors.ts
@@ -7,6 +7,7 @@ import {
     type DataModel,
     type DataModelAttribute,
 } from '@zenstackhq/language/ast';
+import { getAllFields } from '@zenstackhq/language/utils';
 import path from 'node:path';
 import type { DocMeta, PluginOptions, Relationship, RelationType, RenderOptions } from './types';
 
@@ -214,7 +215,7 @@ export function collectFKFieldNames(fields: DataField[]): Set<string> {
 export function collectRelationships(models: DataModel[]): Relationship[] {
     const rels: Relationship[] = [];
     for (const model of models) {
-        for (const field of model.fields) {
+        for (const field of getAllFields(model)) {
             if (field.type.reference?.ref && isDataModel(field.type.reference.ref)) {
                 const to = field.type.reference.ref.name;
                 let relType: RelationType;
diff --git a/packages/plugins/documentation/src/generator.ts b/packages/plugins/documentation/src/generator.ts
@@ -171,36 +171,39 @@ export async function generate(context: CliGeneratorContext): Promise<void> {
         filesGenerated++;
     }
 
+    let hasErdSvg = false;
+    let hasErdMmd = false;
     if (pluginOpts.generateErd) {
         const mermaidSource = buildFullErDiagram({ models, relations: allRelations });
         const format = pluginOpts.erdFormat ?? 'both';
 
         if (format === 'mmd' || format === 'both') {
             writeFile(path.join(outputDir, 'schema-erd.mmd'), mermaidSource);
             filesGenerated++;
+            hasErdMmd = true;
         }
 
         if (format === 'svg' || format === 'both') {
             const svg = await renderErdSvg(mermaidSource, pluginOpts.erdTheme);
             if (svg) {
                 writeFile(path.join(outputDir, 'schema-erd.svg'), svg);
                 filesGenerated++;
+                hasErdSvg = true;
             } else if (format === 'svg') {
                 writeFile(path.join(outputDir, 'schema-erd.mmd'), mermaidSource);
                 filesGenerated++;
+                hasErdMmd = true;
             }
         }
     }
 
-    const hasErd = pluginOpts.generateErd === true;
-
     filesGenerated++;
     genCtx.durationMs = Math.round((performance.now() - startTime) * 100) / 100;
     genCtx.filesGenerated = filesGenerated;
 
     writeFile(
         path.join(outputDir, 'index.md'),
-        renderIndexPage({ astModel: context.model, pluginOptions: pluginOpts, hasRelationships, hasErd, genCtx }),
+        renderIndexPage({ astModel: context.model, pluginOptions: pluginOpts, hasRelationships, hasErdSvg, hasErdMmd, genCtx }),
     );
 }
 
diff --git a/packages/plugins/documentation/src/renderers/index-page.ts b/packages/plugins/documentation/src/renderers/index-page.ts
@@ -28,7 +28,8 @@ interface IndexData {
     enums: Enum[];
     procedures: Procedure[];
     hasRelationships: boolean;
-    hasErd: boolean;
+    hasErdSvg: boolean;
+    hasErdMmd: boolean;
     genCtx?: GenerationContext;
 }
 
@@ -50,7 +51,8 @@ function resolveIndexData(props: IndexPageProps): IndexData {
         enums: astModel.declarations.filter(isEnum).sort((a, b) => a.name.localeCompare(b.name)),
         procedures: astModel.declarations.filter(isProcedure).sort((a, b) => a.name.localeCompare(b.name)),
         hasRelationships,
-        hasErd: props.hasErd === true,
+        hasErdSvg: props.hasErdSvg === true,
+        hasErdMmd: props.hasErdMmd === true,
         genCtx,
     };
 }
@@ -86,7 +88,7 @@ function renderTableOfContents(data: IndexData): string[] {
     if (data.enums.length > 0) parts.push('[Enums](#enums)');
     if (data.procedures.length > 0) parts.push('[Procedures](#procedures)');
     if (data.hasRelationships) parts.push('[Relationships](./relationships.md)');
-    if (data.hasErd) parts.push('[ERD](#erd)');
+    if (data.hasErdSvg || data.hasErdMmd) parts.push('[ERD](#erd)');
     if (parts.length === 0) return [];
     return [parts.join(' · '), ''];
 }
@@ -157,15 +159,17 @@ function renderProceduresSection(data: IndexData): string[] {
     return lines;
 }
 
-/** Renders the ERD section with an embedded SVG image and link to the Mermaid source. */
+/** Renders the ERD section, conditionally embedding SVG and/or linking Mermaid source. */
 function renderErdSection(data: IndexData): string[] {
-    if (!data.hasErd) return [];
-    return [
-        '<a id="erd"></a>', '',
-        '## 🗺️ Entity Relationship Diagram', '',
-        '![Entity Relationship Diagram](./schema-erd.svg)', '',
-        '> [Mermaid source](./schema-erd.mmd)', '',
-    ];
+    if (!data.hasErdSvg && !data.hasErdMmd) return [];
+    const lines = ['<a id="erd"></a>', '', '## 🗺️ Entity Relationship Diagram', ''];
+    if (data.hasErdSvg) {
+        lines.push('![Entity Relationship Diagram](./schema-erd.svg)', '');
+    }
+    if (data.hasErdMmd) {
+        lines.push(`> [Mermaid source](./schema-erd.mmd)`, '');
+    }
+    return lines;
 }
 
 /** Renders a "See Also" section linking to the relationships page. */
diff --git a/packages/plugins/documentation/src/renderers/model-page.ts b/packages/plugins/documentation/src/renderers/model-page.ts
@@ -119,11 +119,11 @@ function renderRelatedEntityFields(model: DataModel): string[] {
     for (const field of capped) {
         lines.push(`        ${resolveTypeName(field.type)} ${field.name}`);
     }
+    lines.push('    }');
     if (fields.length > MAX_RELATED_FIELDS) {
         const remaining = fields.length - MAX_RELATED_FIELDS;
-        lines.push(`        _more_ and_${remaining}_more_fields`);
+        lines.push(`    %% … and ${remaining} more fields`);
     }
-    lines.push('    }');
     return lines;
 }
 
diff --git a/packages/plugins/documentation/src/types.ts b/packages/plugins/documentation/src/types.ts
@@ -111,7 +111,8 @@ export interface IndexPageProps {
     astModel: Model;
     pluginOptions: PluginOptions;
     hasRelationships: boolean;
-    hasErd?: boolean;
+    hasErdSvg?: boolean;
+    hasErdMmd?: boolean;
     genCtx?: GenerationContext;
 }
 
diff --git a/packages/plugins/documentation/test/generator/model-page.test.ts b/packages/plugins/documentation/test/generator/model-page.test.ts
