@matserdam/prisma-neighborhood 0.2.0 → 0.3.0

package/README.md

@@ -1,6 +1,6 @@
 # prisma-neighbourhood
 
-Generate focused ERD diagrams from a Prisma schema by starting from one model and traversing relationships up to a configurable depth.
+Generate focused ERD diagrams from a Prisma schema by starting from any entity (model, view, or enum) and traversing relationships up to a configurable depth.
 
 The npm package is **`@matserdam/prisma-neighborhood`** and it exposes two CLI commands:
 
@@ -20,6 +20,12 @@ bunx @matserdam/prisma-neighborhood -s ./prisma/schema.prisma -m User
 # Limit to direct relationships only (depth 1)
 bunx @matserdam/prisma-neighborhood -s ./prisma/schema.prisma -m User -d 1
 
+# Start from a view (shows view + related enums/models)
+bunx @matserdam/prisma-neighborhood -s ./prisma/schema.prisma -m UserSummary -d 2
+
+# Start from an enum (shows enum + all models/views using it)
+bunx @matserdam/prisma-neighborhood -s ./prisma/schema.prisma -m UserRole -d 2
+
 # Write Mermaid to a file (use .mmd or .md)
 bunx @matserdam/prisma-neighborhood -s ./prisma/schema.prisma -m User -o erd.mmd
 
@@ -50,7 +56,7 @@ prisma-hood -s ./prisma/schema.prisma -m User
 | Option | Alias | Description | Default |
 |--------|-------|-------------|---------|
 | `--schema <path>` | `-s` | Path to the Prisma schema file | required |
-| `--model <name>` | `-m` | Model to start traversal from | required |
+| `--model <name>` | `-m` | Entity to start traversal from (model, view, or enum) | required |
 | `--depth <n>` | `-d` | Relationship levels to traverse | `3` |
 | `--renderer <name>` | `-r` | Renderer to use | `vector` |
 | `--output <file>` | `-o` | Write to a file instead of stdout | stdout |
@@ -69,6 +75,32 @@ The output format is determined by the file extension:
 | `.png` | PNG image |
 | `.pdf` | PDF |
 
-## No Puppeteer / Chromium
+## Entity types
+
+### Models
+Standard Prisma models are rendered as plain ERD entities.
+
+### Views
+Views (requires `previewFeatures = ["views"]`) are rendered with a `[view]` prefix:
+```
+"[view] UserSummary" {
+  Int id UK
+  String email
+}
+```
+
+### Enums
+Enums are rendered with an `[enum]` prefix, with the enum name as the type for each value:
+```
+"[enum] UserRole" {
+  UserRole ADMIN
+  UserRole USER
+  UserRole GUEST
+}
+```
+
+## Traversal behavior
 
-SVG/PNG/PDF export is implemented without headless Chromium, so you no longer need to install OS-level Chromium dependencies.
+- **From a model**: Traverses relations to other models/views, and enum fields to enums
+- **From a view**: Traverses relations to models/views, and enum fields to enums
+- **From an enum**: Finds all models/views using this enum, then traverses their relations

package/dist/_tests_/traverser.test.d.ts

@@ -1,6 +1,6 @@
 /**
- * @fileoverview Tests for the model traverser.
- * Tests cover BFS traversal, depth limiting, and cycle detection.
+ * @fileoverview Tests for the entity traverser.
+ * Tests cover BFS traversal of models, views, and enums with depth limiting.
  */
 export {};
 //# sourceMappingURL=traverser.test.d.ts.map

package/dist/cli/commands.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["../../src/cli/commands.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAmCpC;;;;GAIG;AACH,wBAAgB,aAAa,IAAI,OAAO,CA2BvC;AAqID;;;;GAIG;AACH,wBAAsB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAG1D"}
+{"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["../../src/cli/commands.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAmCpC;;;;GAIG;AACH,wBAAgB,aAAa,IAAI,OAAO,CA8BvC;AAqID;;;;GAIG;AACH,wBAAsB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAG1D"}

package/dist/cli.js

@@ -2155,6 +2155,48 @@ function isPrimaryKeyField(field) {
 function isUniqueField(field) {
   return field.isUnique;
 }
+function extractViewNames(schemaContent) {
+  const viewNames = new Set;
+  const viewRegex = /^\s*view\s+(\w+)\s*\{/gm;
+  const matches = schemaContent.matchAll(viewRegex);
+  for (const match of matches) {
+    viewNames.add(match[1]);
+  }
+  return viewNames;
+}
+function parseFieldsAndRelations(dmmfEntity, entityLookup) {
+  const fields = [];
+  const relations = [];
+  for (const dmmfField of dmmfEntity.fields) {
+    const field = {
+      name: dmmfField.name,
+      type: dmmfField.type,
+      isRequired: dmmfField.isRequired,
+      isList: dmmfField.isList,
+      isPrimaryKey: isPrimaryKeyField(dmmfField),
+      isUnique: isUniqueField(dmmfField),
+      isRelation: isRelationField(dmmfField)
+    };
+    fields.push(field);
+    if (isRelationField(dmmfField)) {
+      const relatedEntity = entityLookup.get(dmmfField.type);
+      const relatedField = relatedEntity?.fields.find((f) => f.relationName === dmmfField.relationName && f.name !== dmmfField.name);
+      const relationType = determineRelationType({ isList: dmmfField.isList, isRequired: dmmfField.isRequired }, relatedField ? {
+        isList: relatedField.isList,
+        isRequired: relatedField.isRequired
+      } : undefined);
+      const isOwner = dmmfField.relationFromFields !== undefined && dmmfField.relationFromFields.length > 0;
+      const relation = {
+        relatedModel: dmmfField.type,
+        type: relationType,
+        fieldName: dmmfField.name,
+        isOwner
+      };
+      relations.push(relation);
+    }
+  }
+  return { fields, relations };
+}
 async function parseSchema(options) {
   const { schemaPath } = options;
   try {
@@ -2168,53 +2210,44 @@ async function parseSchema(options) {
       };
     }
     const dmmf = await import_internals.getDMMF({ datamodel: schemaContent });
+    const viewNamesFromSchema = extractViewNames(schemaContent);
     const dmmfModels = dmmf.datamodel.models;
-    const modelMap = new Map;
+    const dmmfEnums = dmmf.datamodel.enums ?? [];
+    const entityLookup = new Map;
     for (const model of dmmfModels) {
-      modelMap.set(model.name, model);
+      entityLookup.set(model.name, model);
     }
     const models = new Map;
+    const views = new Map;
     for (const dmmfModel of dmmfModels) {
-      const fields = [];
-      const relations = [];
-      for (const dmmfField of dmmfModel.fields) {
-        const field = {
-          name: dmmfField.name,
-          type: dmmfField.type,
-          isRequired: dmmfField.isRequired,
-          isList: dmmfField.isList,
-          isPrimaryKey: isPrimaryKeyField(dmmfField),
-          isUnique: isUniqueField(dmmfField),
-          isRelation: isRelationField(dmmfField)
+      const { fields, relations } = parseFieldsAndRelations(dmmfModel, entityLookup);
+      if (viewNamesFromSchema.has(dmmfModel.name)) {
+        const view = {
+          name: dmmfModel.name,
+          fields,
+          relations
         };
-        fields.push(field);
-        if (isRelationField(dmmfField)) {
-          const relatedModel = modelMap.get(dmmfField.type);
-          const relatedField = relatedModel?.fields.find((f) => f.relationName === dmmfField.relationName && f.name !== dmmfField.name);
-          const relationType = determineRelationType({ isList: dmmfField.isList, isRequired: dmmfField.isRequired }, relatedField ? {
-            isList: relatedField.isList,
-            isRequired: relatedField.isRequired
-          } : undefined);
-          const isOwner = dmmfField.relationFromFields !== undefined && dmmfField.relationFromFields.length > 0;
-          const relation = {
-            relatedModel: dmmfField.type,
-            type: relationType,
-            fieldName: dmmfField.name,
-            isOwner
-          };
-          relations.push(relation);
-        }
+        views.set(view.name, view);
+      } else {
+        const model = {
+          name: dmmfModel.name,
+          fields,
+          relations
+        };
+        models.set(model.name, model);
       }
-      const model = {
-        name: dmmfModel.name,
-        fields,
-        relations
+    }
+    const enums = new Map;
+    for (const dmmfEnum of dmmfEnums) {
+      const enumDef = {
+        name: dmmfEnum.name,
+        values: dmmfEnum.values.map((v) => v.name)
       };
-      models.set(model.name, model);
+      enums.set(enumDef.name, enumDef);
     }
     return {
       success: true,
-      schema: { models }
+      schema: { models, views, enums }
     };
   } catch (error) {
     const errorMessage = error instanceof Error ? error.message : "Unknown error occurred";
@@ -2230,43 +2263,88 @@ var RELATION_SYMBOLS = {
   ONE_TO_MANY: "||--o{",
   MANY_TO_MANY: "}o--o{"
 };
-function renderMermaidErd(models) {
+var ENUM_USAGE_SYMBOL = "}o--||";
+function renderModelOrView(entity, isView, lines) {
+  const displayName = isView ? `"[view] ${entity.name}"` : entity.name;
+  lines.push(`  ${displayName} {`);
+  for (const field of entity.fields) {
+    if (field.isRelation) {
+      continue;
+    }
+    const modifiers = [];
+    if (field.isPrimaryKey) {
+      modifiers.push("PK");
+    }
+    if (field.isUnique && !field.isPrimaryKey) {
+      modifiers.push("UK");
+    }
+    const modifierStr = modifiers.length > 0 ? ` ${modifiers.join(",")}` : "";
+    lines.push(`    ${field.type} ${field.name}${modifierStr}`);
+  }
+  lines.push("  }");
+}
+function renderEnum(enumDef, lines) {
+  lines.push(`  "[enum] ${enumDef.name}" {`);
+  for (const value of enumDef.values) {
+    lines.push(`    ${enumDef.name} ${value}`);
+  }
+  lines.push("  }");
+}
+function renderMermaidErd(entities) {
   const lines = ["erDiagram"];
   const renderedRelations = new Set;
-  for (const { model } of models) {
-    lines.push(`  ${model.name} {`);
-    for (const field of model.fields) {
-      if (field.isRelation) {
-        continue;
-      }
-      const modifiers = [];
-      if (field.isPrimaryKey) {
-        modifiers.push("PK");
-      }
-      if (field.isUnique && !field.isPrimaryKey) {
-        modifiers.push("UK");
-      }
-      const modifierStr = modifiers.length > 0 ? ` ${modifiers.join(",")}` : "";
-      lines.push(`    ${field.type} ${field.name}${modifierStr}`);
+  const modelViewNames = new Set;
+  const enumNames = new Set;
+  const displayNames = new Map;
+  for (const { entity, kind } of entities) {
+    if (kind === "enum") {
+      enumNames.add(entity.name);
+      displayNames.set(entity.name, `"[enum] ${entity.name}"`);
+    } else if (kind === "view") {
+      modelViewNames.add(entity.name);
+      displayNames.set(entity.name, `"[view] ${entity.name}"`);
+    } else {
+      modelViewNames.add(entity.name);
+      displayNames.set(entity.name, entity.name);
     }
-    lines.push("  }");
   }
-  const modelNames = new Set(models.map((m) => m.model.name));
-  for (const { model } of models) {
-    for (const relation of model.relations) {
-      if (!modelNames.has(relation.relatedModel)) {
+  const getDisplayName = (name) => displayNames.get(name) ?? name;
+  for (const { entity, kind } of entities) {
+    if (kind === "enum") {
+      renderEnum(entity, lines);
+    } else {
+      renderModelOrView(entity, kind === "view", lines);
+    }
+  }
+  for (const { entity, kind } of entities) {
+    if (kind === "enum") {
+      continue;
+    }
+    const modelOrView = entity;
+    for (const relation of modelOrView.relations) {
+      if (!modelViewNames.has(relation.relatedModel)) {
         continue;
       }
-      const sortedNames = [model.name, relation.relatedModel].sort();
-      const relationKey = `${sortedNames[0]}-${sortedNames[1]}`;
+      const sortedNames = [entity.name, relation.relatedModel].sort();
+      const relationKey = `model:${sortedNames[0]}-${sortedNames[1]}`;
       if (renderedRelations.has(relationKey)) {
         continue;
       }
       const symbol = RELATION_SYMBOLS[relation.type];
-      const label = relation.fieldName;
-      lines.push(`  ${model.name} ${symbol} ${relation.relatedModel} : "${label}"`);
+      lines.push(`  ${getDisplayName(entity.name)} ${symbol} ${getDisplayName(relation.relatedModel)} : "${relation.fieldName}"`);
       renderedRelations.add(relationKey);
     }
+    for (const field of modelOrView.fields) {
+      if (!enumNames.has(field.type)) {
+        continue;
+      }
+      const enumRelationKey = `enum:${entity.name}-${field.type}-${field.name}`;
+      if (renderedRelations.has(enumRelationKey)) {
+        continue;
+      }
+      lines.push(`  ${getDisplayName(entity.name)} ${ENUM_USAGE_SYMBOL} ${getDisplayName(field.type)} : "${field.name}"`);
+      renderedRelations.add(enumRelationKey);
+    }
   }
   return lines.join(`
 `);
@@ -2328,8 +2406,8 @@ async function runMermaidCli(mermaidContent, options) {
 class MermaidRenderer {
   name = "mermaid";
   description = "Mermaid ERD syntax (text). Supports export via mermaid-cli.";
-  render(models) {
-    return renderMermaidErd(models);
+  render(entities) {
+    return renderMermaidErd(entities);
   }
   async export(content, outputPath, format) {
     await runMermaidCli(content, { outputFormat: format, outputPath });
@@ -2385,8 +2463,8 @@ var import_sharp = __toESM(require("sharp"));
 class VectorRenderer {
   name = "vector";
   description = "Vector-first Mermaid ERD renderer (default). Exports SVG/PNG/PDF using mermaid-cli with sharp for high-DPI output.";
-  render(models) {
-    return renderMermaidErd(models);
+  render(entities) {
+    return renderMermaidErd(entities);
   }
   async export(content, outputPath, format) {
     const svg = await runMermaidCli(content, {
@@ -2443,47 +2521,127 @@ if (!rendererRegistry.has("mermaid")) {
   });
 }
 
-// src/traversal/model-traverser.ts
+// src/traversal/entity-traverser.ts
 var DEFAULT_MAX_DEPTH = 3;
-function traverseModels(schema, options) {
-  const { startModel: startModelName, maxDepth = DEFAULT_MAX_DEPTH } = options;
-  const startModel = schema.models.get(startModelName);
-  if (!startModel) {
+function entityKey(kind, name) {
+  return `${kind}:${name}`;
+}
+function findEntity(schema, name) {
+  const model = schema.models.get(name);
+  if (model) {
+    return { entity: model, kind: "model" };
+  }
+  const view = schema.views.get(name);
+  if (view) {
+    return { entity: view, kind: "view" };
+  }
+  const enumDef = schema.enums.get(name);
+  if (enumDef) {
+    return { entity: enumDef, kind: "enum" };
+  }
+  return;
+}
+function findEntitiesUsingEnum(schema, enumName) {
+  const result = [];
+  for (const model of schema.models.values()) {
+    const usesEnum = model.fields.some((f) => f.type === enumName);
+    if (usesEnum) {
+      result.push({ entity: model, kind: "model" });
+    }
+  }
+  for (const view of schema.views.values()) {
+    const usesEnum = view.fields.some((f) => f.type === enumName);
+    if (usesEnum) {
+      result.push({ entity: view, kind: "view" });
+    }
+  }
+  return result;
+}
+function getReferencedEnums(entity, schema) {
+  const enums = [];
+  for (const field of entity.fields) {
+    const enumDef = schema.enums.get(field.type);
+    if (enumDef) {
+      enums.push(enumDef);
+    }
+  }
+  return enums;
+}
+function getRelatedEntities(entity, schema) {
+  const result = [];
+  for (const relation of entity.relations) {
+    const relatedModel = schema.models.get(relation.relatedModel);
+    if (relatedModel) {
+      result.push({ entity: relatedModel, kind: "model" });
+      continue;
+    }
+    const relatedView = schema.views.get(relation.relatedModel);
+    if (relatedView) {
+      result.push({ entity: relatedView, kind: "view" });
+    }
+  }
+  return result;
+}
+function traverseEntities(schema, options) {
+  const { startEntity: startEntityName, maxDepth = DEFAULT_MAX_DEPTH } = options;
+  const startFound = findEntity(schema, startEntityName);
+  if (!startFound) {
     return {
       success: false,
-      error: `Start model "${startModelName}" not found in schema`
+      error: `Entity "${startEntityName}" not found in schema (searched models, views, and enums)`
     };
   }
+  const { entity: startEntity, kind: startKind } = startFound;
   const visited = new Set;
   const result = [];
   const queue = [];
-  queue.push({ model: startModel, depth: 0 });
-  visited.add(startModelName);
+  queue.push({ entity: startEntity, kind: startKind, depth: 0 });
+  visited.add(entityKey(startKind, startEntity.name));
   while (queue.length > 0) {
     const current = queue.shift();
     if (!current)
       break;
-    const { model, depth } = current;
-    result.push({ model, depth });
+    const { entity, kind, depth } = current;
+    result.push({ entity, kind, depth });
     if (depth >= maxDepth) {
       continue;
     }
-    for (const relation of model.relations) {
-      const relatedModelName = relation.relatedModel;
-      if (visited.has(relatedModelName)) {
-        continue;
+    if (kind === "enum") {
+      const users = findEntitiesUsingEnum(schema, entity.name);
+      for (const { entity: user, kind: userKind } of users) {
+        const key = entityKey(userKind, user.name);
+        if (!visited.has(key)) {
+          visited.add(key);
+          queue.push({ entity: user, kind: userKind, depth: depth + 1 });
+        }
       }
-      const relatedModel = schema.models.get(relatedModelName);
-      if (!relatedModel) {
-        continue;
+    } else {
+      const modelOrView = entity;
+      const related = getRelatedEntities(modelOrView, schema);
+      for (const { entity: relatedEntity, kind: relatedKind } of related) {
+        const key = entityKey(relatedKind, relatedEntity.name);
+        if (!visited.has(key)) {
+          visited.add(key);
+          queue.push({
+            entity: relatedEntity,
+            kind: relatedKind,
+            depth: depth + 1
+          });
+        }
+      }
+      const enums = getReferencedEnums(modelOrView, schema);
+      for (const enumDef of enums) {
+        const key = entityKey("enum", enumDef.name);
+        if (!visited.has(key)) {
+          visited.add(key);
+          queue.push({ entity: enumDef, kind: "enum", depth: depth + 1 });
+        }
       }
-      visited.add(relatedModelName);
-      queue.push({ model: relatedModel, depth: depth + 1 });
     }
   }
   return {
     success: true,
-    models: result
+    entities: result
   };
 }
 // src/cli/types.ts
@@ -2509,7 +2667,7 @@ function isSupportedExtension(ext) {
 }
 function createProgram() {
   const program2 = new Command;
-  program2.name("prisma-neighborhood").description("Generate Entity-Relationship Diagrams from Prisma schemas").version("0.1.0").option("-s, --schema <path>", "Path to the Prisma schema file").option("-m, --model <name>", "Name of the model to start traversal from").option("-d, --depth <n>", "Traversal depth", String(DEFAULT_CLI_OPTIONS.depth)).option("-r, --renderer <name>", "Diagram renderer", DEFAULT_CLI_OPTIONS.renderer).option("-o, --output <file>", "Output file: .mmd, .md (text), .svg, .png, .pdf (export)").option("--list-renderers", "Show available renderers").action(runCommand);
+  program2.name("prisma-neighborhood").description("Generate Entity-Relationship Diagrams from Prisma schemas").version("0.3.0").option("-s, --schema <path>", "Path to the Prisma schema file").option("-m, --model <name>", "Name of the entity (model, view, or enum) to start traversal from").option("-d, --depth <n>", "Traversal depth", String(DEFAULT_CLI_OPTIONS.depth)).option("-r, --renderer <name>", "Diagram renderer", DEFAULT_CLI_OPTIONS.renderer).option("-o, --output <file>", "Output file: .mmd, .md (text), .svg, .png, .pdf (export)").option("--list-renderers", "Show available renderers").action(runCommand);
   return program2;
 }
 function listRenderers() {
@@ -2565,15 +2723,15 @@ async function runCommand(options) {
       process.exit(1);
     }
     const depth = parseInt(options.depth, 10);
-    const traversalResult = traverseModels(parseResult.schema, {
-      startModel: options.model,
+    const traversalResult = traverseEntities(parseResult.schema, {
+      startEntity: options.model,
       maxDepth: depth
     });
     if (!traversalResult.success) {
       console.error(`Error: ${traversalResult.error}`);
       process.exit(1);
     }
-    const output = renderer.render(traversalResult.models);
+    const output = renderer.render(traversalResult.entities);
     if (options.output) {
       if (format && renderer.export) {
         await renderer.export(output, options.output, format);