@rawsql-ts/ddl-docs-cli 0.2.2

package/AGENTS.md

@@ -0,0 +1,27 @@
+# Package Scope
+- Applies to `packages/ddl-docs-cli`.
+- Defines contract rules for the development CLI package.
+
+# Policy
+## REQUIRED
+- SQL parsing behavior MUST stay AST-first through `rawsql-ts` APIs.
+- Regex parsing fallback MUST be guarded and limited to unsupported AST gaps.
+- Package dependency footprint MUST remain minimal.
+
+## ALLOWED
+- CLI-only development usage MAY depend on package-local tooling.
+
+## PROHIBITED
+- Treating this package as runtime application `src/` dependency.
+
+# Mandatory Workflow
+- Before committing changes under `packages/ddl-docs-cli`, run:
+  - `pnpm --filter @rawsql-ts/ddl-docs-cli lint`
+  - `pnpm --filter @rawsql-ts/ddl-docs-cli test`
+  - `pnpm --filter @rawsql-ts/ddl-docs-cli build`
+
+# Hygiene
+- Temporary debug output MUST be removed before commit.
+
+# References
+- Parent policy context: [../../AGENTS.md](../../AGENTS.md)

package/README.md

@@ -0,0 +1,86 @@
+# @rawsql-ts/ddl-docs-cli
+
+Generate Markdown table definition documents from DDL files.
+
+- DDL is treated as SSOT.
+- SQL parsing uses `rawsql-ts`.
+- `CREATE TABLE` and `ALTER TABLE ... ADD CONSTRAINT` are applied across the full DDL stream.
+- `COMMENT ON TABLE/COLUMN` is parsed via `rawsql-ts`.
+
+## Install
+
+```bash
+pnpm --filter @rawsql-ts/ddl-docs-cli build
+```
+
+## Usage
+
+```bash
+ddl-docs generate --ddl-dir ztd/ddl --out-dir ztd/docs/tables
+```
+
+Show help:
+
+```bash
+ddl-docs help
+ddl-docs help generate
+ddl-docs help prune
+```
+
+Generated layout:
+
+- `ztd/docs/tables/index.md`
+- `ztd/docs/tables/<schema>/index.md`
+- `ztd/docs/tables/<schema>/<table>.md`
+
+Options:
+
+- `--ddl-dir <directory>` repeatable recursive directory input
+- `--ddl-file <file>` repeatable explicit file input
+- `--ddl <file>` alias of `--ddl-file`
+- `--ddl-glob <pattern>` repeatable glob pattern input
+- `--extensions <csv>` default `.sql`
+- `--out-dir <directory>` output root (default `ztd/docs/tables`)
+- `--config <path>` optional `ztd.config.json` path
+- `--default-schema <name>` schema override for unqualified table names
+- `--search-path <csv>` schema search path override
+- `--no-index` skip index page generation
+- `--strict` fail when warnings exist
+- `--column-order <mode>` `definition` (default) or `name`
+
+Prune generated files:
+
+```bash
+ddl-docs prune --out-dir ztd/docs/tables
+```
+
+Prune preview:
+
+```bash
+ddl-docs prune --out-dir ztd/docs/tables --dry-run
+```
+
+Optional orphan cleanup:
+
+```bash
+ddl-docs prune --out-dir ztd/docs/tables --prune-orphans
+```
+
+## VitePress Integration
+
+This tool emits plain Markdown files and index pages.
+If you prefer VitePress-side navigation generation, run with `--no-index` and let your site config build navigation from the generated table pages.
+
+## Warnings
+
+Warnings are emitted to `<outDir>/_meta/warnings.json`.
+Use `--strict` in CI to treat warnings as failures.
+
+## Memory Notes
+
+Current implementation prioritizes correctness by applying the full DDL stream and aggregating table metadata before rendering.
+For large schemas (for example, ~300 tables), follow-up optimization should focus on reducing peak memory by keeping only compact table metadata and discarding statement-level objects early.
+
+## Minimal E2E Sample
+
+See `packages/ddl-docs-cli/examples/minimal-e2e`.

package/dist/src/analyzer/columnConcepts.d.ts

@@ -0,0 +1,12 @@
+import type { ColumnDictionary, FindingItem, ObservedColumnDictionary, SuggestionItem, TableDocModel } from '../types';
+interface AnalyzeOptions {
+    locale: string;
+    dictionary: ColumnDictionary | null;
+}
+export interface AnalyzeResult {
+    observed: ObservedColumnDictionary;
+    findings: FindingItem[];
+    suggestions: SuggestionItem[];
+}
+export declare function analyzeColumns(tables: TableDocModel[], options: AnalyzeOptions): AnalyzeResult;
+export {};

package/dist/src/analyzer/columnConcepts.js

@@ -0,0 +1,185 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.analyzeColumns = analyzeColumns;
+const KNOWN_RAW_TYPES = new Set(['text', 'date']);
+const FLEXIBLE_CANONICAL_TYPES = new Set(['date', 'text']);
+const PG_INT_ALIASES = {
+    int: 'integer',
+    int2: 'smallint',
+    int4: 'integer',
+    int8: 'bigint',
+};
+function analyzeColumns(tables, options) {
+    var _a, _b, _c, _d;
+    const conceptMap = new Map();
+    const findings = [];
+    const suggestions = [];
+    const commentCatalog = buildCommentCatalog(tables);
+    for (const table of tables) {
+        for (const column of table.columns) {
+            const concept = column.concept;
+            const conceptItem = (_a = conceptMap.get(concept)) !== null && _a !== void 0 ? _a : {
+                concept,
+                conceptSlug: column.conceptSlug,
+                typeDistribution: {},
+                usages: [],
+            };
+            conceptItem.typeDistribution[column.typeKey] = ((_b = conceptItem.typeDistribution[column.typeKey]) !== null && _b !== void 0 ? _b : 0) + 1;
+            conceptItem.usages.push({
+                schema: table.schema,
+                table: table.table,
+                column: column.name,
+                tableSlug: table.tableSlug,
+                schemaSlug: table.schemaSlug,
+                typeKey: column.typeKey,
+                canonicalType: column.canonicalType,
+                nullable: column.nullable,
+                defaultValue: column.defaultValue,
+                comment: column.comment.trim(),
+                hasComment: Boolean(column.comment.trim()),
+            });
+            conceptMap.set(concept, conceptItem);
+            if (column.unknownType && !KNOWN_RAW_TYPES.has(column.typeName.toLowerCase())) {
+                findings.push({
+                    kind: 'UNSUPPORTED_OR_UNKNOWN_TYPE',
+                    severity: 'info',
+                    message: `Unknown type treated as raw for ${table.schema}.${table.table}.${column.name}: ${column.typeName}`,
+                    scope: { schema: table.schema, table: table.table, column: column.name, concept },
+                });
+            }
+            const suggestedComment = pickCommentSuggestion(commentCatalog, table.schema, concept);
+            if (!column.comment.trim() && suggestedComment) {
+                findings.push({
+                    kind: 'MISSING_COMMENT_SUGGESTED',
+                    severity: 'warning',
+                    message: `Missing comment for ${table.schema}.${table.table}.${column.name}.`,
+                    scope: { schema: table.schema, table: table.table, column: column.name, concept },
+                });
+                suggestions.push({
+                    kind: 'column_comment',
+                    schema: table.schema,
+                    table: table.table,
+                    column: column.name,
+                    sql: `COMMENT ON COLUMN ${quoteQualifiedColumn(table.schema, table.table, column.name)} IS '${escapeSqlLiteral(suggestedComment)}';`,
+                });
+            }
+            const dictionaryEntry = (_d = (_c = options.dictionary) === null || _c === void 0 ? void 0 : _c.columns) === null || _d === void 0 ? void 0 : _d[concept];
+            if (!dictionaryEntry) {
+                continue;
+            }
+            const dictionaryComment = buildSuggestedComment(dictionaryEntry, options.locale);
+            if (column.comment.trim() && dictionaryComment && normalizeCompare(column.comment) !== normalizeCompare(dictionaryComment)) {
+                findings.push({
+                    kind: 'COMMENT_VS_DICTIONARY_MISMATCH',
+                    severity: 'warning',
+                    message: `Comment differs from dictionary for ${table.schema}.${table.table}.${column.name}.`,
+                    scope: { schema: table.schema, table: table.table, column: column.name, concept },
+                });
+            }
+        }
+    }
+    for (const conceptItem of conceptMap.values()) {
+        const divergenceBases = new Set(conceptItem.usages
+            .map((usage) => {
+            var _a;
+            const base = usage.canonicalType.replace(/\(.*\)/, '').replace(/\{serial\}/, '');
+            const normalizedBase = base.toLowerCase();
+            return (_a = PG_INT_ALIASES[normalizedBase]) !== null && _a !== void 0 ? _a : normalizedBase;
+        })
+            .filter((base) => !FLEXIBLE_CANONICAL_TYPES.has(base.toLowerCase())));
+        if (divergenceBases.size > 1) {
+            findings.push({
+                kind: 'COLUMN_NAME_TYPE_DIVERGENCE',
+                severity: 'info',
+                message: `Type variation detected for concept "${conceptItem.concept}".`,
+                scope: { concept: conceptItem.concept },
+            });
+        }
+    }
+    const concepts = Array.from(conceptMap.values())
+        .map((concept) => ({
+        ...concept,
+        usages: concept.usages.sort((a, b) => `${a.schema}.${a.table}.${a.column}|${a.typeKey}`.localeCompare(`${b.schema}.${b.table}.${b.column}|${b.typeKey}`)),
+    }))
+        .sort((a, b) => a.concept.localeCompare(b.concept));
+    return {
+        observed: {
+            version: 1,
+            generatedAt: '1970-01-01T00:00:00.000Z',
+            concepts,
+        },
+        findings: findings.sort((a, b) => `${a.kind}|${a.message}`.localeCompare(`${b.kind}|${b.message}`)),
+        suggestions: suggestions.sort((a, b) => a.sql.localeCompare(b.sql)),
+    };
+}
+function buildSuggestedComment(entry, locale) {
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l;
+    const label = (_d = (_b = (_a = entry.labels) === null || _a === void 0 ? void 0 : _a[locale]) !== null && _b !== void 0 ? _b : (_c = entry.labels) === null || _c === void 0 ? void 0 : _c.en) !== null && _d !== void 0 ? _d : Object.values((_e = entry.labels) !== null && _e !== void 0 ? _e : {})[0];
+    const note = (_j = (_g = (_f = entry.notes) === null || _f === void 0 ? void 0 : _f[locale]) !== null && _g !== void 0 ? _g : (_h = entry.notes) === null || _h === void 0 ? void 0 : _h.en) !== null && _j !== void 0 ? _j : Object.values((_k = entry.notes) !== null && _k !== void 0 ? _k : {})[0];
+    if (label && note) {
+        return `${label} - ${note}`;
+    }
+    return (_l = label !== null && label !== void 0 ? label : note) !== null && _l !== void 0 ? _l : '';
+}
+function escapeSqlLiteral(input) {
+    return input.replace(/'/g, "''");
+}
+function normalizeCompare(input) {
+    return input.trim().replace(/\s+/g, ' ').toLowerCase();
+}
+function buildCommentCatalog(tables) {
+    var _a, _b;
+    const catalog = new Map();
+    for (const table of tables) {
+        for (const column of table.columns) {
+            const comment = column.comment.trim();
+            if (!comment) {
+                continue;
+            }
+            const concept = column.concept;
+            const entry = (_a = catalog.get(concept)) !== null && _a !== void 0 ? _a : {
+                sameSchema: new Map(),
+                global: [],
+            };
+            const schemaComments = (_b = entry.sameSchema.get(table.schema)) !== null && _b !== void 0 ? _b : [];
+            schemaComments.push(comment);
+            entry.sameSchema.set(table.schema, schemaComments);
+            entry.global.push({ schema: table.schema, comment });
+            catalog.set(concept, entry);
+        }
+    }
+    for (const entry of catalog.values()) {
+        for (const [schema, comments] of entry.sameSchema.entries()) {
+            entry.sameSchema.set(schema, Array.from(new Set(comments)).sort((a, b) => a.localeCompare(b)));
+        }
+        const deduped = new Map();
+        for (const item of entry.global) {
+            deduped.set(`${item.schema}|${item.comment}`, item);
+        }
+        entry.global = Array.from(deduped.values()).sort((a, b) => `${a.schema}|${a.comment}`.localeCompare(`${b.schema}|${b.comment}`));
+    }
+    return catalog;
+}
+function pickCommentSuggestion(catalog, schema, concept) {
+    var _a, _b, _c, _d;
+    const entry = catalog.get(concept);
+    if (!entry) {
+        return '';
+    }
+    const sameSchema = (_a = entry.sameSchema.get(schema)) !== null && _a !== void 0 ? _a : [];
+    if (sameSchema.length > 0) {
+        return (_b = sameSchema[0]) !== null && _b !== void 0 ? _b : '';
+    }
+    if (entry.global.length > 0) {
+        return (_d = (_c = entry.global[0]) === null || _c === void 0 ? void 0 : _c.comment) !== null && _d !== void 0 ? _d : '';
+    }
+    return '';
+}
+function quoteQualifiedColumn(schema, table, column) {
+    return [schema, table, column].map(quoteIdentifier).join('.');
+}
+function quoteIdentifier(value) {
+    const normalized = value.replace(/^"|"$/g, '');
+    return `"${normalized.replace(/"/g, '""')}"`;
+}
+//# sourceMappingURL=columnConcepts.js.map

package/dist/src/analyzer/columnConcepts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"columnConcepts.js","sourceRoot":"","sources":["../../../src/analyzer/columnConcepts.ts"],"names":[],"mappings":"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"}

package/dist/src/analyzer/dictionary.d.ts

@@ -0,0 +1,3 @@
+import type { ColumnDictionary } from '../types';
+export declare function loadDictionary(pathValue: string | undefined): ColumnDictionary | null;
+export declare function resolveLocale(requested: string | undefined, dictionary: ColumnDictionary | null): string;

package/dist/src/analyzer/dictionary.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadDictionary = loadDictionary;
+exports.resolveLocale = resolveLocale;
+const node_fs_1 = require("node:fs");
+function loadDictionary(pathValue) {
+    var _a, _b;
+    if (!pathValue) {
+        return null;
+    }
+    if (!(0, node_fs_1.existsSync)(pathValue)) {
+        throw new Error(`Dictionary file not found: ${pathValue}`);
+    }
+    const raw = (0, node_fs_1.readFileSync)(pathValue, 'utf8');
+    const parsed = JSON.parse(raw);
+    if (typeof parsed !== 'object' || parsed === null || !parsed.columns) {
+        throw new Error(`Invalid dictionary format: ${pathValue}`);
+    }
+    return {
+        version: (_a = parsed.version) !== null && _a !== void 0 ? _a : 1,
+        locales: (_b = parsed.locales) !== null && _b !== void 0 ? _b : ['en'],
+        columns: parsed.columns,
+    };
+}
+function resolveLocale(requested, dictionary) {
+    var _a, _b, _c, _d, _e;
+    if (requested && requested.trim()) {
+        return requested.trim();
+    }
+    const lang = (_a = process.env.LANG) === null || _a === void 0 ? void 0 : _a.split(/[._-]/)[0];
+    if (lang && ((_b = dictionary === null || dictionary === void 0 ? void 0 : dictionary.locales) === null || _b === void 0 ? void 0 : _b.includes(lang))) {
+        return lang;
+    }
+    if ((_c = dictionary === null || dictionary === void 0 ? void 0 : dictionary.locales) === null || _c === void 0 ? void 0 : _c.includes('en')) {
+        return 'en';
+    }
+    return (_e = (_d = dictionary === null || dictionary === void 0 ? void 0 : dictionary.locales) === null || _d === void 0 ? void 0 : _d[0]) !== null && _e !== void 0 ? _e : 'en';
+}
+//# sourceMappingURL=dictionary.js.map

package/dist/src/analyzer/dictionary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dictionary.js","sourceRoot":"","sources":["../../../src/analyzer/dictionary.ts"],"names":[],"mappings":";;AAGA,wCAiBC;AAED,sCAYC;AAlCD,qCAAmD;AAGnD,SAAgB,cAAc,CAAC,SAA6B;;IAC1D,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,CAAC,IAAA,oBAAU,EAAC,SAAS,CAAC,EAAE,CAAC;QAC3B,MAAM,IAAI,KAAK,CAAC,8BAA8B,SAAS,EAAE,CAAC,CAAC;IAC7D,CAAC;IACD,MAAM,GAAG,GAAG,IAAA,sBAAY,EAAC,SAAS,EAAE,MAAM,CAAC,CAAC;IAC5C,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAA8B,CAAC;IAC5D,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACrE,MAAM,IAAI,KAAK,CAAC,8BAA8B,SAAS,EAAE,CAAC,CAAC;IAC7D,CAAC;IACD,OAAO;QACL,OAAO,EAAE,MAAA,MAAM,CAAC,OAAO,mCAAI,CAAC;QAC5B,OAAO,EAAE,MAAA,MAAM,CAAC,OAAO,mCAAI,CAAC,IAAI,CAAC;QACjC,OAAO,EAAE,MAAM,CAAC,OAAO;KACxB,CAAC;AACJ,CAAC;AAED,SAAgB,aAAa,CAAC,SAA6B,EAAE,UAAmC;;IAC9F,IAAI,SAAS,IAAI,SAAS,CAAC,IAAI,EAAE,EAAE,CAAC;QAClC,OAAO,SAAS,CAAC,IAAI,EAAE,CAAC;IAC1B,CAAC;IACD,MAAM,IAAI,GAAG,MAAA,OAAO,CAAC,GAAG,CAAC,IAAI,0CAAE,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;IACjD,IAAI,IAAI,KAAI,MAAA,UAAU,aAAV,UAAU,uBAAV,UAAU,CAAE,OAAO,0CAAE,QAAQ,CAAC,IAAI,CAAC,CAAA,EAAE,CAAC;QAChD,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,MAAA,UAAU,aAAV,UAAU,uBAAV,UAAU,CAAE,OAAO,0CAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QACxC,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,MAAA,MAAA,UAAU,aAAV,UAAU,uBAAV,UAAU,CAAE,OAAO,0CAAG,CAAC,CAAC,mCAAI,IAAI,CAAC;AAC1C,CAAC"}

package/dist/src/analyzer/typeNormalization.d.ts

@@ -0,0 +1,7 @@
+export interface NormalizedType {
+    canonicalType: string;
+    typeKey: string;
+    unknown: boolean;
+    baseForDivergence: string;
+}
+export declare function normalizePostgresType(rawTypeName: string): NormalizedType;

package/dist/src/analyzer/typeNormalization.js

@@ -0,0 +1,76 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizePostgresType = normalizePostgresType;
+function normalizePostgresType(rawTypeName) {
+    const raw = rawTypeName.trim();
+    const lower = raw.toLowerCase().replace(/\s+/g, ' ');
+    if (!lower) {
+        return asRaw('unknown');
+    }
+    if (lower === 'smallint' || lower === 'int2') {
+        return known('int2', 'int2');
+    }
+    if (lower === 'integer' || lower === 'int' || lower === 'int4') {
+        return known('int4', 'int4');
+    }
+    if (lower === 'bigint' || lower === 'int8') {
+        return known('int8', 'int8');
+    }
+    if (lower === 'smallserial' || lower === 'serial2') {
+        return known('int2', 'int2{serial}', 'int2');
+    }
+    if (lower === 'serial' || lower === 'serial4') {
+        return known('int4', 'int4{serial}', 'int4');
+    }
+    if (lower === 'bigserial' || lower === 'serial8') {
+        return known('int8', 'int8{serial}', 'int8');
+    }
+    if (lower === 'boolean' || lower === 'bool') {
+        return known('bool', 'bool');
+    }
+    if (lower === 'uuid') {
+        return known('uuid', 'uuid');
+    }
+    if (lower === 'timestamp without time zone' || lower === 'timestamp') {
+        return known('timestamp', 'timestamp');
+    }
+    if (lower === 'timestamp with time zone' || lower === 'timestamptz') {
+        return known('timestamptz', 'timestamptz');
+    }
+    const numeric = lower.match(/^(numeric|decimal)\s*\((\d+)\s*,\s*(\d+)\)$/);
+    if (numeric) {
+        const p = numeric[2];
+        const s = numeric[3];
+        return known(`numeric(${p},${s})`, `numeric(${p},${s})`, 'numeric');
+    }
+    if (lower === 'numeric' || lower === 'decimal') {
+        return known('numeric', 'numeric', 'numeric');
+    }
+    const varchar = lower.match(/^(character varying|varchar)\s*\((\d+)\)$/);
+    if (varchar) {
+        const n = varchar[2];
+        return known(`varchar(${n})`, `varchar(${n})`, 'varchar');
+    }
+    if (lower === 'character varying' || lower === 'varchar') {
+        return known('varchar', 'varchar', 'varchar');
+    }
+    return asRaw(raw);
+}
+function known(canonicalType, typeKey, baseForDivergence) {
+    return {
+        canonicalType,
+        typeKey,
+        unknown: false,
+        baseForDivergence: baseForDivergence !== null && baseForDivergence !== void 0 ? baseForDivergence : canonicalType.replace(/\(.*\)/, ''),
+    };
+}
+function asRaw(raw) {
+    const normalizedRaw = raw.replace(/\s+/g, ' ').trim();
+    return {
+        canonicalType: normalizedRaw,
+        typeKey: `raw:${normalizedRaw}`,
+        unknown: true,
+        baseForDivergence: `raw:${normalizedRaw.toLowerCase()}`,
+    };
+}
+//# sourceMappingURL=typeNormalization.js.map

package/dist/src/analyzer/typeNormalization.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"typeNormalization.js","sourceRoot":"","sources":["../../../src/analyzer/typeNormalization.ts"],"names":[],"mappings":"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"}

package/dist/src/cli.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Runs ddl-docs-cli command dispatch and executes generate/prune subcommands.
+ *
+ * @param argv Command-line arguments without the node executable and script path.
+ * @returns A promise that resolves when command execution completes.
+ * Side effects include console output and filesystem writes/removals via subcommands.
+ */
+export declare function runCli(argv: string[]): Promise<void>;