@cuongph.dev/dbdocgen 0.1.0 → 0.1.1

package/README.md

@@ -10,11 +10,12 @@ The database schema is the **single source of truth**. All table names, column t
 
 - Parse `schema.sql` (PostgreSQL, MySQL/MariaDB primary support)
 - Export to 5 formats: Excel, Markdown, HTML, Mermaid, Word
-- A5:SQL-style layout: per-table definition tables with metadata headers
-- Excel workbook with **Overview** sheet (summary + hyperlinks) and one sheet per table
+- Excel workbook with **Overview** sheet (summary + hyperlinks), **ER Diagram** sheet, and one sheet per table
+- **ER diagram** embedded in Excel/HTML/Markdown/Word (ELK layout PNG + Mermaid); HTML page with pan/zoom
+- A5:SQL-style **10-column** definition tables (Size, Min, Max, Unique, Notes, …)
 - HTML with **index page** and per-table detail pages (PK/FK highlighting)
 - Localized output labels: English (`en`) and Japanese (`jp`)
-- Timestamped output directory per run (`./output/db_doc_gen_{yymmddhhmm}`)
+- Configurable **output parent folder** (`outDir`); each run creates `{outDir}/db_doc_gen_{yymmddhhmm}`
 - Step-by-step progress logging during generation
 - Config file support via [cosmiconfig](https://github.com/cosmiconfig/cosmiconfig)
 - Programmatic API for integration into CI or custom tooling
@@ -46,7 +47,7 @@ dbdocgen init
 dbdocgen generate
 
 # Or pass options directly
-dbdocgen generate --schema ./database/schema.sql --out ./docs/db
+dbdocgen generate --schema ./database/schema.sql --out ./output
 ```
 
 ### Development (from source)
@@ -71,7 +72,7 @@ dbdocgen generate [options]
 | Option | Description |
 | ------ | ----------- |
 | `--schema <path>` | Path to the SQL schema file (default: from config or `./schema.sql`) |
-| `--out <path>` | Output directory (default: `./output/db_doc_gen_{yymmddhhmm}`) |
+| `--out <path>` | Parent output directory (default: `./output`; each run creates `db_doc_gen_{yymmddhhmm}` inside) |
 | `--format <list>` | Comma-separated formats: `excel`, `markdown`, `html`, `diagram`, `word` (default: all) |
 | `--config <path>` | Config file path (default: auto-detected) |
 
@@ -81,6 +82,7 @@ dbdocgen generate [options]
 [dbdocgen] Loading configuration...
 [dbdocgen] Configuration loaded
   schema: ./database/schema.sql
+  outputParent: ./output
   outDir: ./output/db_doc_gen_2606281947
   formats: excel, markdown, html, diagram, word
   language: en
@@ -116,12 +118,23 @@ dbdocgen validate --schema ./database/schema.sql
 
 ### `clean`
 
-Remove the output directory.
+Remove generated documentation folders.
 
 ```bash
-dbdocgen clean --out ./docs/db
+# Remove all db_doc_gen_* run folders under the parent directory
+dbdocgen clean --out ./output
+
+# Remove one specific run
+dbdocgen clean --out ./output/db_doc_gen_2606281947
 ```
 
+| Target path | Behavior |
+| ----------- | -------- |
+| Parent dir (e.g. `./output`) | Deletes every `db_doc_gen_*` subdirectory inside |
+| Run dir (e.g. `./output/db_doc_gen_2606281947`) | Deletes that folder only |
+
+Uses `outDir` from config when `--out` is omitted (default parent: `./output`).
+
 ### `config show`
 
 Print the resolved configuration (merges config file + CLI defaults).
@@ -164,6 +177,7 @@ CLI options override config file values.
 ```json
 {
   "schema": "./database/schema.sql",
+  "outDir": "./output",
   "dialect": "mysql",
   "output": {
     "formats": ["excel", "markdown", "html", "diagram", "word"],
@@ -172,6 +186,12 @@ CLI options override config file values.
 }
 ```
 
+`outDir` is the **parent folder only**. The CLI always writes into a new timestamped subdirectory:
+
+```
+{outDir}/db_doc_gen_{yymmddhhmm}/
+```
+
 ### Config fields
 
 | Field | Type | Default | Description |
@@ -180,8 +200,7 @@ CLI options override config file values.
 | `dialect` | `string` | auto-detected | SQL dialect hint: `postgres`, `mysql`, `mariadb`, `sqlite`, `mssql` |
 | `output.formats` | `string[]` | all formats | Which output formats to generate |
 | `output.language` | `string` | `"en"` | Label language: `en` or `jp` |
-
-> **Note:** `outDir` is not set in config. Each `generate` run uses `--out` if provided, otherwise a new timestamped directory under `./output/`.
+| `outDir` | `string` | `"./output"` | Parent folder for generated runs (`{outDir}/db_doc_gen_{yymmddhhmm}`) |
 
 ## Output Structure
 
@@ -189,14 +208,17 @@ Each `generate` run writes to a dedicated directory:
 
 ```
 output/db_doc_gen_2606281947/
-├── database_dictionary.xlsx    # Excel — Overview + one sheet per table
-├── database_document.docx      # Word document (all tables)
-├── er_diagram.mmd              # Mermaid ER diagram
+├── database_dictionary.xlsx    # Excel — Overview + ER Diagram + one sheet per table
+├── database_document.docx      # Word document (all tables + ER diagram)
+├── er_diagram.mmd              # Mermaid ER diagram (when `diagram` format is enabled)
+├── er_diagram.png              # PNG preview of ER diagram (excel/word/markdown/html)
+├── ER_DIAGRAM.md               # Standalone Mermaid ER diagram (markdown format)
 ├── tables/
 │   ├── users.md                # Per-table Markdown
 │   └── orders.md
 └── html/
     ├── index.html              # Table list with links
+    ├── er-diagram.html         # Interactive Mermaid ER diagram page
     └── tables/
         ├── users.html          # Per-table HTML
         └── orders.html
@@ -206,22 +228,28 @@ output/db_doc_gen_2606281947/
 
 | Format | Output file(s) | Description |
 | ------ | -------------- | ----------- |
-| `excel` | `database_dictionary.xlsx` | A5:SQL-style workbook (see below) |
-| `markdown` | `tables/<name>.md` | Per-table Markdown with metadata + column table |
-| `html` | `html/index.html`, `html/tables/<name>.html` | Index page + per-table pages with PK/FK badges |
-| `diagram` | `er_diagram.mmd` | Mermaid `erDiagram` source |
-| `word` | `database_document.docx` | Word document with all tables |
+| `excel` | `database_dictionary.xlsx`, `er_diagram.png` | A5:SQL-style workbook with **Overview**, **ER Diagram** sheet (PNG + Mermaid source), and per-table sheets |
+| `markdown` | `tables/<name>.md`, `ER_DIAGRAM.md` | Per-table Markdown + standalone Mermaid ER diagram file |
+| `html` | `html/index.html`, `html/er-diagram.html`, `html/tables/<name>.html` | Index page, interactive Mermaid ER page, and per-table pages |
+| `diagram` | `er_diagram.mmd` | Mermaid `erDiagram` source only |
+| `word` | `database_document.docx`, `er_diagram.png` | Word document with overview, ER diagram section (PNG), and all tables |
 
 ### A5:SQL-style column definition
 
-All text exporters (Excel, Markdown, HTML, Word) use the same six-column definition table:
+All text exporters (Excel, Markdown, HTML, Word) use the same ten-column definition table:
+
+| Physical Name | Logical Name | Type | Size | Required | Default Value | Min | Max | Unique | Notes |
+| ------------- | ------------ | ---- | ---- | -------- | ------------- | --- | --- | ------ | ----- |
+| `id` | | `bigint` | | Yes | `-` | | | No | PK |
+| `email` | | `varchar(255)` | `255` | Yes | `-` | | | Yes | |
+| `age` | | `int` | | Yes | `-` | `0` | `150` | No | CHECK |
 
-| Physical Name | Logical Name | Type | Required | Default Value | Notes |
-| ------------- | ------------ | ---- | -------- | ------------- | ----- |
-| `id` | | `bigint` | Yes | `-` | PK |
-| `user_id` | | `bigint` | Yes | `-` | FK |
+- **Size** — length/precision from the column type (e.g. `varchar(128)` → `128`, `numeric(12,2)` → `12,2`)
+- **Min / Max** — extracted from `CHECK` constraints when possible (e.g. `age >= 0 AND age <= 150`)
+- **Unique** — column-level `UNIQUE`, table `UNIQUE` constraints, and `UNIQUE` indexes
+- **Notes** — PK/FK markers, `AUTO_INCREMENT`, `GENERATED` columns, `ENUM` values, composite `UNIQUE`, `CHECK` text, and other constraint hints
 
-Column headers are localized based on `output.language` (e.g. Japanese: 物理名 | 論理名 | 型 | 必須 | デフォルト値 | 備考).
+Column headers are localized based on `output.language` (e.g. Japanese: 物理名 | 論理名 | 型 | 桁数 | 必須 | デフォルト値 | 最小値 | 最大値 | 一意 | 備考).
 
 ### Excel workbook layout
 
@@ -233,6 +261,13 @@ Column headers are localized based on `output.language` (e.g. Japanese: 物理
 - Hyperlinks from table names to their detail sheets
 - Auto-filter enabled on the table list
 
+**ER Diagram sheet**
+
+- Title bar with ER diagram heading
+- Embedded PNG preview (**ELK** layered layout + orthogonal routing; table boxes list PK/FK columns first)
+- Full-resolution copy also written as `er_diagram.png` beside the workbook
+- Mermaid source block below the image for copy/paste into Mermaid-compatible tools
+
 **Per-table sheet**
 
 - Title bar with table physical name
@@ -243,9 +278,23 @@ Column headers are localized based on `output.language` (e.g. Japanese: 物理
 
 ### HTML layout
 
-- `html/index.html` — summary cards + sortable table list with links to each table
+- `html/index.html` — summary cards + sortable table list with links to each table and ER diagram
+- `html/er-diagram.html` — interactive Mermaid ER diagram with **pan, zoom, fit, reset** toolbar
 - `html/tables/<name>.html` — metadata, column table, PK/FK row highlighting, back link to index
 
+### ER diagram embedding
+
+When you generate `excel`, `html`, `markdown`, or `word` output, an ER diagram is embedded automatically — you do not need to enable the `diagram` format separately.
+
+| Output | ER diagram location |
+| ------ | ------------------- |
+| Excel | **ER Diagram** worksheet (ELK orthogonal PNG + Mermaid source text) |
+| HTML | `html/er-diagram.html` (linked from index) |
+| Markdown | `ER_DIAGRAM.md` (fenced `mermaid` block) |
+| Word | ER Diagram section after overview (PNG + Mermaid source) |
+
+The standalone `diagram` format still writes `er_diagram.mmd` for tooling that consumes raw Mermaid files.
+
 ### Output languages
 
 | Language | Config value | Notes |
@@ -261,9 +310,10 @@ Set via config or ensure `output.language` is set before generation:
 
 ### Logical names and comments
 
-**Logical Name** and **Notes** columns reflect SQL `COMMENT` annotations from the schema. If your schema has no comments, these fields show `(none)`.
+- **Logical Name** — from SQL `COMMENT` on the column (empty → `(none)`)
+- **Notes** — constraint metadata (PK, FK, `AUTO_INCREMENT`, `CHECK`, …), not the same as logical name
 
-To populate them, add comments in your DDL:
+To populate logical names, add comments in your DDL:
 
 ```sql
 CREATE TABLE users (
@@ -277,9 +327,10 @@ CREATE TABLE users (
 ```ts
 import { generateDbDocs } from "@cuongph.dev/dbdocgen";
 
+// API outDir is the exact run directory (no auto timestamp — create the path yourself if needed)
 const doc = await generateDbDocs({
   schema: "./database/schema.sql",
-  outDir: "./docs/db",
+  outDir: "./output/db_doc_gen_manual",
   dialect: "mysql",          // optional — auto-detected if omitted
   output: {
     formats: ["excel", "markdown", "html", "diagram", "word"],
@@ -344,19 +395,21 @@ schema.sql
     ▼
  Normalized Metadata Model (DatabaseDoc)
     │
-    ├──► Excel Exporter   → database_dictionary.xlsx
-    ├──► Markdown Exporter → tables/*.md
-    ├──► HTML Exporter    → html/index.html + html/tables/*.html
-    ├──► Mermaid Exporter  → er_diagram.mmd
-    └──► Word Exporter     → database_document.docx
+    ├──► Excel Exporter    → database_dictionary.xlsx + er_diagram.png
+    ├──► Markdown Exporter → tables/*.md + ER_DIAGRAM.md
+    ├──► HTML Exporter     → html/index.html + html/er-diagram.html + html/tables/*.html
+    ├──► Mermaid Exporter  → er_diagram.mmd (optional `diagram` format)
+    └──► Word Exporter     → database_document.docx + er_diagram.png
 ```
 
+ER diagram PNG/SVG uses **elkjs** (orthogonal layout). Rasterization uses **sharp**.
+
 ### Metadata model
 
 The internal `DatabaseDoc` structure contains:
 
 - `dialect` — detected SQL dialect
-- `tables[]` — table name, comment, columns, primary keys, foreign keys, indexes
+- `tables[]` — table name, comment, columns (`size`, `minValue`, `maxValue`, `isUnique`, `constraintNotes`, …), PK, FK, indexes
 - `relationships[]` — FK relationships derived from schema
 - `indexes[]` — standalone index definitions
 - `warnings[]` — parser limitations, unsupported syntax
@@ -377,6 +430,8 @@ Schema facts (names, types, constraints) are never modified after parsing.
 | SQL parser | node-sql-parser |
 | Excel | exceljs |
 | Word | docx |
+| ER layout | elkjs |
+| ER PNG | sharp |
 | Tests | vitest |
 | Lint / format | eslint, prettier |
 
@@ -388,15 +443,16 @@ src/
 ├── core/
 │   ├── config/               # Config schema, loader, defaults
 │   ├── model/                # DatabaseDoc types + Zod validation
+│   ├── output-path.ts        # db_doc_gen_* run directory helpers
 │   └── pipeline/             # generateDbDocs orchestration
-├── parsers/sql/              # SQL parser + normalizer
+├── parsers/sql/              # SQL parser, normalizer, column-meta
 ├── exporters/
 │   ├── excel/                # A5-style Excel workbook
 │   ├── markdown/             # Per-table Markdown
 │   ├── html/                 # Index + per-table HTML
-│   ├── diagram/              # Mermaid ER diagram
+│   ├── diagram/              # Mermaid, ELK SVG/PNG, ER embed helpers
 │   ├── word/                 # Word document
-│   └── shared/               # i18n output labels
+│   └── shared/               # i18n labels + A5 column-definition helpers
 └── index.ts                  # Public API barrel
 ```
 
@@ -412,6 +468,8 @@ pnpm lint             # eslint
 pnpm format           # prettier
 ```
 
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the full guide on contributing and publishing to npm.
+
 ## Limitations
 
 | Limitation | Notes |
@@ -421,7 +479,9 @@ pnpm format           # prettier
 | Dialect coverage | PostgreSQL and MySQL/MariaDB are primary targets |
 | No incremental gen | Each run regenerates all output files |
 | No web UI | Outputs are static files |
-| Comments required for logical names | Logical Name fields need SQL `COMMENT` annotations |
+| Complex CHECK / ENUM | Simple bounds extracted; complex expressions may appear only in Notes |
+| ER PNG in Excel | Large schemas show up to 6 key columns per table (PK/FK first); use HTML Mermaid for full interactive view |
+| API vs CLI `outDir` | CLI appends `db_doc_gen_*` under parent; API `outDir` is the exact destination path |
 
 ## Roadmap