@rawsql-ts/ddl-docs-cli 0.2.2

package/dist/src/render/tableMarkdown.js

@@ -0,0 +1,243 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderTableMarkdown = renderTableMarkdown;
+exports.tableDocPath = tableDocPath;
+const node_path_1 = __importDefault(require("node:path"));
+const markdown_1 = require("../utils/markdown");
+/**
+ * Renders one table documentation page as markdown.
+ *
+ * @param table Table metadata to render.
+ * @param suggestedSql Suggested SQL statements grouped by table.
+ * @param renderOptions Optional rendering options such as label/comment splitting.
+ * @returns A markdown document string for the table page.
+ */
+function renderTableMarkdown(table, suggestedSql, renderOptions) {
+    const labelSeparator = renderOptions === null || renderOptions === void 0 ? void 0 : renderOptions.labelSeparator;
+    const lines = [];
+    lines.push('<!-- generated-by: @rawsql-ts/ddl-docs-cli -->');
+    lines.push('');
+    lines.push(`# ${table.schema}.${table.table}`);
+    lines.push('');
+    lines.push('[<- All Schemas](../index.md) | [Table Index](./index.md)');
+    lines.push('');
+    lines.push('## Overview');
+    lines.push('');
+    lines.push(`- Instance: ${(0, markdown_1.formatTableCell)(table.instance || '-')}`);
+    lines.push(`- Comment: ${(0, markdown_1.formatTableCell)(table.tableComment)}`);
+    lines.push(`- Source Files: ${(0, markdown_1.formatTableCell)(table.sourceFiles.map((entry) => `\`${entry}\``).join('<br>'))}`);
+    lines.push('');
+    lines.push('## Columns');
+    lines.push('');
+    if (labelSeparator) {
+        lines.push('| Key | Label | Column | Type | Nullable | Default | Seq | Comment | Usages |');
+        lines.push('| --- | --- | --- | --- | --- | --- | --- | --- | --- |');
+    }
+    else {
+        lines.push('| Key | Column | Type | Nullable | Default | Seq | Comment | Usages |');
+        lines.push('| --- | --- | --- | --- | --- | --- | --- | --- |');
+    }
+    for (const column of table.columns) {
+        lines.push(renderColumnRow(column, labelSeparator));
+    }
+    lines.push('');
+    lines.push('## Indexes & Constraints');
+    lines.push('');
+    const nonKeyConstraints = table.constraints.filter((constraint) => constraint.kind !== 'PK' && constraint.kind !== 'FK');
+    if (nonKeyConstraints.length === 0) {
+        lines.push('- None');
+    }
+    else {
+        lines.push('| Kind | Name | Expression |');
+        lines.push('| --- | --- | --- |');
+        for (const constraint of nonKeyConstraints) {
+            lines.push(`| ${constraint.kind} | ${(0, markdown_1.formatCodeCell)(constraint.name)} | ${(0, markdown_1.formatTableCell)(constraint.expression)} |`);
+        }
+    }
+    lines.push('');
+    lines.push('## References');
+    lines.push('');
+    const outgoingAll = sortDirectionalReferences([...table.outgoingReferences]);
+    const incomingAll = sortDirectionalReferences([...table.incomingReferences]);
+    if (outgoingAll.length === 0 && incomingAll.length === 0) {
+        lines.push('- None');
+    }
+    else {
+        if (outgoingAll.length > 0) {
+            lines.push(`::: details To (outgoing): ${outgoingAll.length}`);
+            lines.push('');
+            lines.push(...renderUnifiedReferenceTable(outgoingAll, table));
+            lines.push('');
+            lines.push(':::');
+            lines.push('');
+        }
+        if (incomingAll.length > 0) {
+            lines.push(`::: details From (incoming): ${incomingAll.length}`);
+            lines.push('');
+            lines.push(...renderUnifiedReferenceTable(incomingAll, table));
+            lines.push('');
+            lines.push(':::');
+            lines.push('');
+        }
+    }
+    lines.push('');
+    lines.push('## Triggers');
+    lines.push('');
+    if (table.triggers.length === 0) {
+        lines.push('- None');
+    }
+    else {
+        lines.push('| Name | Timing | Events | For Each | Function |');
+        lines.push('| --- | --- | --- | --- | --- |');
+        for (const trigger of table.triggers) {
+            const nameCell = (0, markdown_1.formatCodeCell)(trigger.name);
+            const eventsCell = trigger.events.join(', ');
+            const funcCell = (0, markdown_1.formatCodeCell)(trigger.functionName);
+            lines.push(`| ${nameCell} | ${trigger.timing} | ${eventsCell} | ${trigger.forEach} | ${funcCell} |`);
+        }
+    }
+    lines.push('');
+    lines.push('## Appendix');
+    lines.push('');
+    lines.push('::: details Definition');
+    lines.push('');
+    lines.push('```sql');
+    lines.push(table.normalizedSql.definition);
+    lines.push('```');
+    lines.push('');
+    lines.push(':::');
+    if (table.normalizedSql.comments) {
+        lines.push('');
+        lines.push('::: details Comments');
+        lines.push('');
+        lines.push('```sql');
+        lines.push(table.normalizedSql.comments);
+        lines.push('```');
+        lines.push('');
+        lines.push(':::');
+    }
+    if (table.normalizedSql.triggers) {
+        lines.push('');
+        lines.push('::: details Triggers (raw)');
+        lines.push('');
+        lines.push('```sql');
+        lines.push(table.normalizedSql.triggers);
+        lines.push('```');
+        lines.push('');
+        lines.push(':::');
+    }
+    if (suggestedSql.columnCommentSql.length > 0) {
+        lines.push('');
+        lines.push('### Suggested Column Comment SQL (Optional)');
+        lines.push('');
+        lines.push('```sql');
+        lines.push('-- suggested: v1 (not applied)');
+        lines.push(...suggestedSql.columnCommentSql);
+        lines.push('```');
+    }
+    if (suggestedSql.foreignKeySql.length > 0) {
+        lines.push('');
+        lines.push('### Suggested Foreign Key Constraint SQL (Optional)');
+        lines.push('');
+        lines.push('```sql');
+        lines.push('-- suggested: v1 (not applied)');
+        lines.push(...suggestedSql.foreignKeySql);
+        lines.push('```');
+    }
+    lines.push('');
+    return lines.join('\n');
+}
+/**
+ * Returns output path for a rendered table markdown page.
+ */
+function tableDocPath(outDir, schemaSlug, tableSlug) {
+    return node_path_1.default.join(outDir, schemaSlug, `${tableSlug}.md`);
+}
+function linkFromTablePage(current, targetSchemaSlug, targetTableSlug) {
+    if (current.schemaSlug === targetSchemaSlug) {
+        return `./${targetTableSlug}.md`;
+    }
+    return `../${targetSchemaSlug}/${targetTableSlug}.md`;
+}
+const SERIAL_TYPES = new Set(['serial', 'serial2', 'serial4', 'serial8', 'bigserial', 'smallserial']);
+function isSequenceColumn(column) {
+    return SERIAL_TYPES.has(column.typeName.toLowerCase()) || column.defaultValue.toLowerCase().includes('nextval(');
+}
+function splitComment(comment, separator) {
+    const regex = safeSeparatorRegExp(separator);
+    const match = regex.exec(comment);
+    if (match !== null) {
+        return {
+            label: comment.slice(0, match.index).trim(),
+            description: comment.slice(match.index + match[0].length).trim(),
+        };
+    }
+    return { label: comment, description: '' };
+}
+function safeSeparatorRegExp(separator) {
+    try {
+        return new RegExp(separator);
+    }
+    catch {
+        return new RegExp(escapeRegExp(separator));
+    }
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+function renderColumnRow(column, labelSeparator) {
+    const keyCell = column.isPrimaryKey ? 'PK' : '';
+    const nameCell = (0, markdown_1.formatCodeCell)(column.name);
+    const typeCell = (0, markdown_1.formatCodeCell)(column.typeName);
+    const nullableCell = column.nullable ? 'YES' : 'NO';
+    const defaultCell = (0, markdown_1.formatCodeCell)(column.defaultValue);
+    const seqCell = isSequenceColumn(column) ? 'YES' : '';
+    const usagesCell = `[usages](./columns/${column.conceptSlug}.md)`;
+    if (labelSeparator) {
+        const { label, description } = splitComment(column.comment, labelSeparator);
+        const labelCell = (0, markdown_1.formatTableCell)(label);
+        const commentCell = (0, markdown_1.formatTableCell)(description);
+        return `| ${keyCell} | ${labelCell} | ${nameCell} | ${typeCell} | ${nullableCell} | ${defaultCell} | ${seqCell} | ${commentCell} | ${usagesCell} |`;
+    }
+    const commentCell = (0, markdown_1.formatTableCell)(column.comment);
+    return `| ${keyCell} | ${nameCell} | ${typeCell} | ${nullableCell} | ${defaultCell} | ${seqCell} | ${commentCell} | ${usagesCell} |`;
+}
+function renderUnifiedReferenceTable(references, table) {
+    var _a, _b;
+    const lines = [];
+    lines.push('| Source | Table | Comment | Columns | On Delete | On Update | Match |');
+    lines.push('| --- | --- | --- | --- | --- | --- | --- |');
+    for (const reference of references) {
+        const sourceCell = (0, markdown_1.formatCodeCell)(reference.source);
+        const otherTableCell = renderOtherTableCell(reference, table);
+        const otherComment = reference.direction === 'outgoing' ? reference.targetTableComment : reference.fromTableComment;
+        const commentCell = (0, markdown_1.formatTableCell)(otherComment);
+        const columnsCell = (0, markdown_1.formatCodeCell)(`${reference.fromColumns.join(', ') || '?'} -> ${reference.targetColumns.join(', ') || '?'}`);
+        const onDeleteCell = reference.source === 'ddl' ? (0, markdown_1.formatCodeCell)((_a = reference.onDeleteAction) !== null && _a !== void 0 ? _a : 'none') : '-';
+        const onUpdateCell = reference.source === 'ddl' ? (0, markdown_1.formatCodeCell)((_b = reference.onUpdateAction) !== null && _b !== void 0 ? _b : 'none') : '-';
+        const matchCell = reference.source === 'suggested' && reference.matchRule ? (0, markdown_1.formatCodeCell)(reference.matchRule) : '-';
+        lines.push(`| ${sourceCell} | ${otherTableCell} | ${commentCell} | ${columnsCell} | ${onDeleteCell} | ${onUpdateCell} | ${matchCell} |`);
+    }
+    return lines;
+}
+function renderOtherTableCell(reference, table) {
+    if (reference.direction === 'outgoing') {
+        const linkPath = linkFromTablePage(table, reference.targetSchemaSlug, reference.targetTableSlug);
+        return `[${reference.targetTableKey}](${linkPath})`;
+    }
+    const linkPath = linkFromTablePage(table, reference.fromSchemaSlug, reference.fromTableSlug);
+    return `[${reference.fromTableKey}](${linkPath})`;
+}
+function sortDirectionalReferences(references) {
+    return references.sort((left, right) => {
+        const leftOther = left.direction === 'outgoing' ? left.targetTableKey : left.fromTableKey;
+        const rightOther = right.direction === 'outgoing' ? right.targetTableKey : right.fromTableKey;
+        const leftComment = left.direction === 'outgoing' ? left.targetTableComment : left.fromTableComment;
+        const rightComment = right.direction === 'outgoing' ? right.targetTableComment : right.fromTableComment;
+        return `${left.source}|${leftOther}|${leftComment}|${left.expression}`.localeCompare(`${right.source}|${rightOther}|${rightComment}|${right.expression}`);
+    });
+}
+//# sourceMappingURL=tableMarkdown.js.map

package/dist/src/render/tableMarkdown.js.map

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

package/dist/src/render/types.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Represents a generated markdown file output.
+ */
+export interface RenderedPage {
+    path: string;
+    content: string;
+}

package/dist/src/render/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/src/render/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/render/types.ts"],"names":[],"mappings":""}

package/dist/src/state/manifest.d.ts

@@ -0,0 +1,14 @@
+import type { DocsManifest, PruneResult } from '../types';
+export interface ManifestWriteOptions {
+    outDir: string;
+    generatorVersion: string;
+    dialect: 'postgres';
+    optionsForHash: Record<string, unknown>;
+    nameMap: Record<string, string>;
+    tableOutputs: string[];
+    columnOutputs: string[];
+}
+export declare function manifestPath(outDir: string): string;
+export declare function writeManifest(options: ManifestWriteOptions): string;
+export declare function readManifest(outDir: string): DocsManifest | null;
+export declare function pruneManagedFiles(outDir: string, dryRun: boolean, pruneOrphans: boolean): PruneResult;

package/dist/src/state/manifest.js

@@ -0,0 +1,153 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.manifestPath = manifestPath;
+exports.writeManifest = writeManifest;
+exports.readManifest = readManifest;
+exports.pruneManagedFiles = pruneManagedFiles;
+const node_crypto_1 = require("node:crypto");
+const node_fs_1 = require("node:fs");
+const node_path_1 = __importDefault(require("node:path"));
+const fs_1 = require("../utils/fs");
+const io_1 = require("../utils/io");
+const MANIFEST_FILE = 'manifest.json';
+const GENERATED_HEADER = '<!-- generated-by: @rawsql-ts/ddl-docs-cli -->';
+function manifestPath(outDir) {
+    return node_path_1.default.join(outDir, '_meta', MANIFEST_FILE);
+}
+function writeManifest(options) {
+    (0, fs_1.ensureDirectory)(node_path_1.default.join(options.outDir, '_meta'));
+    const manifest = {
+        generator: {
+            version: options.generatorVersion,
+            dialect: options.dialect,
+            optionsHash: hashOptions(options.optionsForHash),
+        },
+        naming: {
+            slugRules: 'lowercase; replace non [a-z0-9] with -; trim dashes; fallback unnamed',
+            nameMap: options.nameMap,
+        },
+        outputs: {
+            tables: toSortedPosix(options.outDir, options.tableOutputs),
+            columns: toSortedPosix(options.outDir, options.columnOutputs),
+        },
+    };
+    const outputPath = manifestPath(options.outDir);
+    (0, node_fs_1.writeFileSync)(outputPath, (0, io_1.normalizeLf)(JSON.stringify(manifest, null, 2)), 'utf8');
+    return outputPath;
+}
+function readManifest(outDir) {
+    var _a, _b;
+    const filePath = manifestPath(outDir);
+    if (!(0, node_fs_1.existsSync)(filePath)) {
+        return null;
+    }
+    const raw = (0, node_fs_1.readFileSync)(filePath, 'utf8');
+    const parsed = JSON.parse(raw);
+    if (!(parsed === null || parsed === void 0 ? void 0 : parsed.generator) || !(parsed === null || parsed === void 0 ? void 0 : parsed.naming) || !(parsed === null || parsed === void 0 ? void 0 : parsed.outputs)) {
+        throw new Error(`Invalid manifest format: ${filePath}`);
+    }
+    return {
+        generator: parsed.generator,
+        naming: parsed.naming,
+        outputs: {
+            tables: (_a = parsed.outputs.tables) !== null && _a !== void 0 ? _a : [],
+            columns: (_b = parsed.outputs.columns) !== null && _b !== void 0 ? _b : [],
+        },
+    };
+}
+function pruneManagedFiles(outDir, dryRun, pruneOrphans) {
+    const manifest = readManifest(outDir);
+    if (!manifest) {
+        return { removed: [], dryRun };
+    }
+    const managed = [...manifest.outputs.tables, ...manifest.outputs.columns];
+    const removed = [];
+    for (const relativeFile of managed) {
+        const resolvedFile = node_path_1.default.resolve(outDir, relativeFile);
+        if (!(0, node_fs_1.existsSync)(resolvedFile) || !isManagedGeneratedFile(resolvedFile)) {
+            continue;
+        }
+        if (!dryRun) {
+            (0, node_fs_1.rmSync)(resolvedFile, { force: true });
+        }
+        removed.push(resolvedFile);
+    }
+    if (pruneOrphans) {
+        const orphanCandidates = findGeneratedMarkdownFiles(outDir);
+        const managedSet = new Set(managed.map((entry) => node_path_1.default.resolve(outDir, entry)));
+        for (const candidate of orphanCandidates) {
+            if (managedSet.has(candidate)) {
+                continue;
+            }
+            if (!dryRun) {
+                (0, node_fs_1.rmSync)(candidate, { force: true });
+            }
+            removed.push(candidate);
+        }
+    }
+    const metaFiles = [
+        manifestPath(outDir),
+        node_path_1.default.join(outDir, '_meta', 'warnings.json'),
+        node_path_1.default.join(outDir, '_meta', 'warnings.md'),
+        node_path_1.default.join(outDir, '_meta', 'findings.json'),
+        node_path_1.default.join(outDir, '_meta', 'findings.md'),
+        node_path_1.default.join(outDir, '_meta', 'snapshot.json'),
+        node_path_1.default.join(outDir, '_meta', 'observed-column-dictionary.json'),
+        node_path_1.default.join(outDir, '_meta', 'suggested.sql'),
+    ];
+    if (!dryRun) {
+        for (const metaFile of metaFiles) {
+            if ((0, node_fs_1.existsSync)(metaFile)) {
+                (0, node_fs_1.rmSync)(metaFile, { force: true });
+            }
+        }
+    }
+    return { removed: Array.from(new Set(removed)).sort(), dryRun };
+}
+function hashOptions(options) {
+    const hash = (0, node_crypto_1.createHash)('sha256');
+    hash.update(JSON.stringify(options, Object.keys(options).sort()));
+    return hash.digest('hex');
+}
+function toSortedPosix(outDir, files) {
+    return Array.from(new Set(files.map((entry) => node_path_1.default.relative(outDir, entry).replace(/\\/g, '/')))).sort();
+}
+function isManagedGeneratedFile(filePath) {
+    if (!filePath.toLowerCase().endsWith('.md')) {
+        return false;
+    }
+    const content = (0, node_fs_1.readFileSync)(filePath, 'utf8');
+    return content.includes(GENERATED_HEADER);
+}
+function findGeneratedMarkdownFiles(rootDir) {
+    const files = [];
+    walk(rootDir, files);
+    return files.sort();
+}
+function walk(currentDir, files) {
+    const entries = (0, node_fs_1.readdirSync)(currentDir, { withFileTypes: true });
+    for (const entry of entries) {
+        const resolved = node_path_1.default.join(currentDir, entry.name);
+        if (entry.isDirectory()) {
+            if (entry.name === '_meta' || entry.name === 'node_modules') {
+                continue;
+            }
+            walk(resolved, files);
+            continue;
+        }
+        if (!entry.isFile()) {
+            continue;
+        }
+        if (!resolved.toLowerCase().endsWith('.md')) {
+            continue;
+        }
+        if (!isManagedGeneratedFile(resolved)) {
+            continue;
+        }
+        files.push(resolved);
+    }
+}
+//# sourceMappingURL=manifest.js.map

package/dist/src/state/manifest.js.map

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

package/dist/src/types.d.ts

@@ -0,0 +1,193 @@
+export interface SqlSource {
+    path: string;
+    sql: string;
+    instance: string;
+}
+export interface DdlInput {
+    path: string;
+    instance: string;
+}
+export interface GenerateDocsOptions {
+    ddlDirectories: DdlInput[];
+    ddlFiles: DdlInput[];
+    ddlGlobs: DdlInput[];
+    extensions: string[];
+    outDir: string;
+    includeIndexes: boolean;
+    strict: boolean;
+    dialect: 'postgres';
+    columnOrder: 'definition' | 'name';
+    labelSeparator?: string;
+    locale?: string;
+    dictionaryPath?: string;
+    configPath?: string;
+    defaultSchema?: string;
+    searchPath?: string[];
+    filterPgDump?: boolean;
+}
+export interface PruneDocsOptions {
+    outDir: string;
+    dryRun: boolean;
+    pruneOrphans: boolean;
+}
+export interface ResolvedSchemaSettings {
+    defaultSchema: string;
+    searchPath: string[];
+}
+export interface ColumnDocModel {
+    name: string;
+    concept: string;
+    conceptSlug: string;
+    typeName: string;
+    canonicalType: string;
+    typeKey: string;
+    nullable: boolean;
+    defaultValue: string;
+    isPrimaryKey: boolean;
+    comment: string;
+    checks: string[];
+    unknownType: boolean;
+}
+export interface TriggerDocModel {
+    name: string;
+    timing: string;
+    events: string[];
+    forEach: string;
+    functionName: string;
+    rawSql: string;
+}
+export interface TableDocModel {
+    schema: string;
+    table: string;
+    schemaSlug: string;
+    tableSlug: string;
+    instance: string;
+    tableComment: string;
+    sourceFiles: string[];
+    columns: ColumnDocModel[];
+    primaryKey: string[];
+    constraints: TableConstraintDocModel[];
+    triggers: TriggerDocModel[];
+    outgoingReferences: ReferenceDocModel[];
+    incomingReferences: ReferenceDocModel[];
+    normalizedSql: NormalizedSql;
+}
+export interface DocsManifest {
+    generator: {
+        version: string;
+        dialect: 'postgres';
+        optionsHash: string;
+    };
+    naming: {
+        slugRules: string;
+        nameMap: Record<string, string>;
+    };
+    outputs: {
+        tables: string[];
+        columns: string[];
+    };
+}
+export interface WarningSource {
+    filePath: string;
+    statementIndex?: number;
+}
+export interface WarningItem {
+    kind: 'UNSUPPORTED_DDL' | 'PARSE_FAILED' | 'AMBIGUOUS';
+    message: string;
+    statementPreview: string;
+    source: WarningSource;
+}
+export interface SnapshotResult {
+    tables: TableDocModel[];
+    warnings: WarningItem[];
+}
+export interface TableConstraintDocModel {
+    kind: 'PK' | 'UK' | 'CHECK' | 'FK' | 'INDEX';
+    name: string;
+    expression: string;
+    /** true when this constraint originated from CREATE [UNIQUE] INDEX */
+    isIndex?: boolean;
+}
+export interface NormalizedSql {
+    /** CREATE TABLE + ALTER TABLE constraints + CREATE [UNIQUE] INDEX */
+    definition: string;
+    /** COMMENT ON TABLE + COMMENT ON COLUMN */
+    comments: string;
+    /** CREATE TRIGGER statements (raw, not normalized) */
+    triggers: string;
+}
+export interface ReferenceDocModel {
+    direction: 'outgoing' | 'incoming';
+    source: 'ddl' | 'suggested';
+    fromTableKey: string;
+    fromTableComment: string;
+    targetTableKey: string;
+    targetTableComment: string;
+    fromColumns: string[];
+    targetColumns: string[];
+    onDeleteAction: 'cascade' | 'restrict' | 'no action' | 'set null' | 'set default' | null;
+    onUpdateAction: 'cascade' | 'restrict' | 'no action' | 'set null' | 'set default' | null;
+    fromSchemaSlug: string;
+    fromTableSlug: string;
+    targetSchemaSlug: string;
+    targetTableSlug: string;
+    matchRule?: 'exact';
+    expression: string;
+}
+export interface PruneResult {
+    removed: string[];
+    dryRun: boolean;
+}
+export interface DictionaryEntry {
+    preferredTypes?: string[];
+    labels?: Record<string, string>;
+    notes?: Record<string, string>;
+}
+export interface ColumnDictionary {
+    version: number;
+    locales?: string[];
+    columns: Record<string, DictionaryEntry>;
+}
+export interface ObservedColumnUsage {
+    schema: string;
+    table: string;
+    column: string;
+    tableSlug: string;
+    schemaSlug: string;
+    typeKey: string;
+    canonicalType: string;
+    nullable: boolean;
+    defaultValue: string;
+    comment: string;
+    hasComment: boolean;
+}
+export interface ObservedColumnConcept {
+    concept: string;
+    conceptSlug: string;
+    typeDistribution: Record<string, number>;
+    usages: ObservedColumnUsage[];
+}
+export interface ObservedColumnDictionary {
+    version: 1;
+    generatedAt: string;
+    concepts: ObservedColumnConcept[];
+}
+export type FindingKind = 'COLUMN_NAME_TYPE_DIVERGENCE' | 'MISSING_COMMENT_SUGGESTED' | 'COMMENT_VS_DICTIONARY_MISMATCH' | 'UNSUPPORTED_OR_UNKNOWN_TYPE';
+export interface FindingItem {
+    kind: FindingKind;
+    severity: 'info' | 'warning';
+    message: string;
+    scope: {
+        schema?: string;
+        table?: string;
+        column?: string;
+        concept?: string;
+    };
+}
+export interface SuggestionItem {
+    kind: 'column_comment' | 'foreign_key';
+    schema: string;
+    table: string;
+    column: string;
+    sql: string;
+}

package/dist/src/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/src/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":""}

package/dist/src/utils/ddlInputDedupe.d.ts

@@ -0,0 +1,9 @@
+import type { DdlInput } from '../types';
+/**
+ * Dedupe DDL inputs by the tuple key of (instance, path).
+ *
+ * Inputs sharing only the path are preserved when their instance differs.
+ * The key format intentionally uses a NUL separator to avoid collisions with
+ * common path characters on Windows and POSIX.
+ */
+export declare function dedupeDdlInputsByInstanceAndPath(inputs: DdlInput[]): DdlInput[];