@matserdam/prisma-neighborhood 0.0.1

package/README.md

@@ -0,0 +1,141 @@
+# prisma-subgraph-cli
+
+CLI tool that generates Entity-Relationship Diagrams from Prisma schemas, starting from a specified model and traversing relationships to a configurable depth.
+
+## Installation
+
+```bash
+bun install
+```
+
+## Usage
+
+```bash
+# Basic usage - generate ERD starting from User model (stdout)
+bun src/index.ts -s ./prisma/schema.prisma -m User
+
+# With custom depth (default is 3)
+bun src/index.ts -s ./prisma/schema.prisma -m User -d 5
+
+# Output to Mermaid file
+bun src/index.ts -s ./prisma/schema.prisma -m User -o diagram.mmd
+
+# Export to PNG
+bun src/index.ts -s ./prisma/schema.prisma -m User -o diagram.png
+
+# Export to PDF
+bun src/index.ts -s ./prisma/schema.prisma -m User -o diagram.pdf
+
+# List available renderers
+bun src/index.ts --list-renderers
+
+# Show help
+bun src/index.ts --help
+```
+
+## Options
+
+| Option | Alias | Description | Default |
+|--------|-------|-------------|---------|
+| `--schema <path>` | `-s` | Path to the Prisma schema file | (required) |
+| `--model <name>` | `-m` | Name of the model to start traversal from | (required) |
+| `--depth <n>` | `-d` | Traversal depth | 3 |
+| `--renderer <name>` | `-r` | Diagram renderer | mermaid |
+| `--output <file>` | `-o` | Output file (stdout if omitted) | - |
+| `--list-renderers` | - | Show available renderers | - |
+| `--help` | `-h` | Display help | - |
+| `--version` | `-V` | Output version | - |
+
+### Output Formats
+
+The output format is determined by the file extension:
+
+| Extension | Format |
+|-----------|--------|
+| `.mmd` | Mermaid text |
+| `.md` | Mermaid text |
+| `.png` | PNG image |
+| `.pdf` | PDF document |
+
+### PNG/PDF Export Requirements
+
+PNG and PDF export uses `@mermaid-js/mermaid-cli` which relies on Puppeteer (headless Chromium).
+
+#### Platform Compatibility
+
+| Platform | Status | Notes |
+|----------|--------|-------|
+| macOS | Works out of the box | No additional setup needed |
+| Windows | Works out of the box | No additional setup needed |
+| Linux | Requires dependencies | See below |
+
+#### Linux Dependencies
+
+On Linux, Puppeteer requires additional system libraries:
+
+```bash
+# Debian/Ubuntu
+sudo apt-get install -y \
+  libnss3 \
+  libatk1.0-0 \
+  libatk-bridge2.0-0 \
+  libcups2 \
+  libdrm2 \
+  libxkbcommon0 \
+  libxcomposite1 \
+  libxdamage1 \
+  libxrandr2 \
+  libgbm1 \
+  libasound2 \
+  libpangocairo-1.0-0 \
+  libgtk-3-0
+
+# Alpine (Docker)
+apk add chromium
+```
+
+#### CI/CD Environments
+
+For CI pipelines, either:
+- Install the dependencies listed above
+- Use a Docker image with Chromium pre-installed (e.g., `node:18-bullseye`)
+
+#### Alternative: Text-only Mode
+
+If PNG/PDF export is problematic, you can:
+1. Output to `.mmd` file and use an online renderer like [mermaid.live](https://mermaid.live)
+2. Use VS Code with a Mermaid preview extension
+3. Embed the Mermaid syntax directly in Markdown documentation
+
+## Example Output
+
+Given a Prisma schema with User, Post, and Profile models:
+
+```mermaid
+erDiagram
+  User {
+    Int id PK
+    String email UK
+    String name
+    DateTime createdAt
+  }
+  Post {
+    Int id PK
+    String title
+    String content
+    Boolean published
+    Int authorId
+    DateTime createdAt
+  }
+  Profile {
+    Int id PK
+    String bio
+    Int userId UK
+  }
+  User ||--o{ Post : "posts"
+  User ||--|| Profile : "profile"
+```
+
+## License
+
+MIT

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

@@ -0,0 +1,6 @@
+/**
+ * @fileoverview Tests for the CLI interface.
+ * Tests cover command-line argument parsing, renderer selection, and output.
+ */
+export {};
+//# sourceMappingURL=cli.test.d.ts.map

package/dist/_tests_/cli.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.test.d.ts","sourceRoot":"","sources":["../../src/_tests_/cli.test.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

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

@@ -0,0 +1,6 @@
+/**
+ * @fileoverview Tests for the Prisma schema parser.
+ * Tests cover parsing of models, fields, relations, and edge cases.
+ */
+export {};
+//# sourceMappingURL=parser.test.d.ts.map

package/dist/_tests_/parser.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parser.test.d.ts","sourceRoot":"","sources":["../../src/_tests_/parser.test.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

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

@@ -0,0 +1,6 @@
+/**
+ * @fileoverview Tests for the renderer system.
+ * Tests cover DiagramRenderer interface compliance, Mermaid output, and registry.
+ */
+export {};
+//# sourceMappingURL=renderer.test.d.ts.map

package/dist/_tests_/renderer.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"renderer.test.d.ts","sourceRoot":"","sources":["../../src/_tests_/renderer.test.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"traverser.test.d.ts","sourceRoot":"","sources":["../../src/_tests_/traverser.test.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/dist/cli/commands.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @fileoverview CLI command definitions using Commander.
+ * Defines the main CLI program and its commands.
+ */
+import { Command } from "commander";
+/**
+ * Creates and configures the CLI program.
+ *
+ * @returns The configured Commander program
+ */
+export declare function createProgram(): Command;
+/**
+ * Runs the CLI with the provided arguments.
+ *
+ * @param args - Command-line arguments (typically process.argv)
+ */
+export declare function runCli(args: string[]): Promise<void>;
+//# sourceMappingURL=commands.d.ts.map

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

@@ -0,0 +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;AAkCpC;;;;GAIG;AACH,wBAAgB,aAAa,IAAI,OAAO,CA2BvC;AAqID;;;;GAIG;AACH,wBAAsB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAG1D"}

package/dist/cli/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @fileoverview CLI module exports.
+ * Provides CLI functionality and type definitions.
+ */
+export { createProgram, runCli } from "./commands";
+export { parseCliOptions } from "./options";
+export type { CliOptions } from "./types";
+export { DEFAULT_CLI_OPTIONS } from "./types";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AACnD,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAC5C,YAAY,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAC1C,OAAO,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC"}

package/dist/cli/options.d.ts

@@ -0,0 +1,42 @@
+/**
+ * @fileoverview CLI option parsing utilities.
+ * Parses command-line arguments into structured options.
+ */
+import type { CliOptions } from "./types";
+/**
+ * Result of CLI option parsing.
+ */
+export type ParseResult = {
+    readonly success: true;
+    readonly options: CliOptions;
+} | {
+    readonly success: false;
+    readonly error: string;
+};
+/**
+ * Parse CLI arguments into structured options.
+ *
+ * Arguments format:
+ *   prisma-erd [options]
+ *
+ * Options:
+ *   -s, --schema <path>    Path to the Prisma schema file
+ *   -m, --model <name>     Name of the model to start traversal from
+ *   -d, --depth <n>        Traversal depth (default: 3)
+ *   -r, --renderer <name>  Diagram renderer (default: "mermaid")
+ *   -o, --output <file>    Output file: .mmd, .md (text), .png, .pdf (image)
+ *   --list-renderers       Show available renderers
+ *
+ * @param args - Command-line arguments (without node and script path)
+ * @returns A ParseResult containing the parsed options or an error
+ *
+ * @example
+ * ```typescript
+ * const result = parseCliOptions(['--schema', './schema.prisma', '--model', 'User', '-d', '5']);
+ * if (result.success) {
+ *   console.log(result.options);
+ * }
+ * ```
+ */
+export declare function parseCliOptions(args: string[]): ParseResult;
+//# sourceMappingURL=options.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"options.d.ts","sourceRoot":"","sources":["../../src/cli/options.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAG1C;;GAEG;AACH,MAAM,MAAM,WAAW,GACpB;IAAE,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAA;CAAE,GACxD;IAAE,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEvD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,WAAW,CAkK3D"}

package/dist/cli/types.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @fileoverview Type definitions for CLI options and configuration.
+ */
+/**
+ * CLI command options parsed from command-line arguments.
+ */
+export interface CliOptions {
+    /** Path to the Prisma schema file */
+    readonly schema: string;
+    /** Name of the model to start traversal from */
+    readonly model: string;
+    /** Maximum traversal depth (default: 3) */
+    readonly depth: number;
+    /** Renderer to use (default: "mermaid") */
+    readonly renderer: string;
+    /** Output file path (stdout if not specified). Extension determines format: .mmd/.md (text), .png/.pdf (image) */
+    readonly output?: string;
+    /** List available renderers and exit */
+    readonly listRenderers: boolean;
+}
+/**
+ * Default CLI options.
+ */
+export declare const DEFAULT_CLI_OPTIONS: {
+    depth: number;
+    renderer: string;
+    listRenderers: boolean;
+};
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/cli/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;GAEG;AACH,MAAM,WAAW,UAAU;IAC1B,qCAAqC;IACrC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAExB,gDAAgD;IAChD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAEvB,2CAA2C;IAC3C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAEvB,2CAA2C;IAC3C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE1B,kHAAkH;IAClH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAEzB,wCAAwC;IACxC,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;CAChC;AAED;;GAEG;AACH,eAAO,MAAM,mBAAmB,EAAE;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,OAAO,CAAC;CAKvB,CAAC"}

package/dist/cli.d.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+/**
+ * @fileoverview Entry point for the prisma-neighborhood CLI.
+ * Generates Entity-Relationship Diagrams from Prisma schemas.
+ */
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;GAGG"}