edsger 0.69.0 → 0.70.0

package/dist/phases/er-diagram/index.js

@@ -0,0 +1,290 @@
+/**
+ * er-diagram phase: clone the product's repo, ask Claude to map every
+ * persistence entity (table / view / enum / junction) and the relationships
+ * between them into a structured ErDiagramExtraction, then persist the result
+ * to diagrams / diagram_nodes / diagram_edges (rows tagged `type = 'er'`) via the
+ * Supabase SDK.
+ *
+ * Companion to data-flow / screen-flow: same generation pattern (workspace
+ * clone + Claude Agent SDK + in-process MCP server), same storage tables,
+ * different domain.
+ */
+import { query } from '@anthropic-ai/claude-agent-sdk';
+import { getRepositoryBasics } from '../../api/github.js';
+import { DEFAULT_MODEL } from '../../constants.js';
+import { getSupabase } from '../../supabase/client.js';
+import { logError, logInfo, logSuccess, logWarning, } from '../../utils/logger.js';
+import { cleanupIssueRepo } from '../../workspace/workspace-manager.js';
+import { fetchProductBasics } from '../find-shared/mcp.js';
+import { cloneDiagramRepos, describeRepoScope, } from '../diagram-shared/clone-repos.js';
+import { createPromptGenerator, extractTextFromContent, tryExtractResult, } from '../pr-shared/agent-utils.js';
+import { createErDiagramCaptureState, createErDiagramMcpServer, validateConsistency, } from './mcp-server.js';
+import { createErDiagramSystemPrompt, createErDiagramUserPrompt, } from './prompts.js';
+import { isErDiagramExtraction, } from './types.js';
+const WORKSPACE_KEY = 'er-diagram';
+const MAX_TURNS = 150;
+// Auto-layout: simple grid; users can drag afterwards and we persist positions.
+const COLUMN_WIDTH = 320;
+const ROW_HEIGHT = 260;
+const COLUMNS = 4;
+export async function runErDiagramPhase(options) {
+    const { productId, repoId, diagramId, guidance, verbose } = options;
+    const repoOnly = !productId && Boolean(repoId);
+    if (productId) {
+        logInfo(`Starting er-diagram generation for product ${productId}`);
+    }
+    else {
+        logInfo(`Starting er-diagram generation for repository ${repoId}`);
+    }
+    const supabase = getSupabase();
+    await markDiagramRunning(supabase, diagramId);
+    const repositoryIds = await getDiagramRepositoryIds(supabase, diagramId);
+    const cloneResult = await cloneDiagramRepos({
+        productId,
+        repoId,
+        repositoryIds,
+        workspaceKey: WORKSPACE_KEY,
+        verbose,
+    });
+    if (!cloneResult.ok) {
+        await markDiagramFailed(supabase, diagramId, cloneResult.message);
+        return { status: 'error', message: cloneResult.message };
+    }
+    const { projectDir, cleanupDir, repos } = cloneResult;
+    let succeeded = false;
+    try {
+        const product = repoOnly
+            ? await resolveRepoBasics(repoId, repos)
+            : await fetchProductBasics(productId);
+        const systemPrompt = await createErDiagramSystemPrompt({
+            projectDir,
+            hasCodebase: true,
+        });
+        const repoScope = describeRepoScope(repos);
+        const userPrompt = createErDiagramUserPrompt({
+            productName: product.name,
+            productDescription: product.description,
+            guidance: [guidance, repoScope].filter(Boolean).join('\n\n') || undefined,
+        });
+        logInfo('Running Claude er-diagram extraction...');
+        const captureState = createErDiagramCaptureState();
+        const mcpServer = createErDiagramMcpServer(captureState, {
+            onProgress: ({ phase, message }) => {
+                logInfo(`[${phase}] ${message}`);
+            },
+        });
+        let lastAssistantResponse = '';
+        let extraction = null;
+        for await (const message of query({
+            prompt: createPromptGenerator(userPrompt),
+            options: {
+                systemPrompt: {
+                    type: 'preset',
+                    preset: 'claude_code',
+                    append: systemPrompt,
+                },
+                model: DEFAULT_MODEL,
+                maxTurns: MAX_TURNS,
+                permissionMode: 'bypassPermissions',
+                cwd: projectDir,
+                mcpServers: {
+                    'er-diagram': mcpServer,
+                },
+            },
+        })) {
+            const { assistantBuffer, extraction: nextExtraction } = processSdkMessage(message, lastAssistantResponse, captureState, verbose);
+            lastAssistantResponse = assistantBuffer;
+            if (nextExtraction) {
+                extraction = nextExtraction;
+            }
+        }
+        if (!extraction) {
+            const msg = 'ER diagram extraction failed: agent did not call submit_er_diagram and no parseable er_diagram block was found in the response';
+            await markDiagramFailed(supabase, diagramId, msg);
+            return { status: 'error', message: msg };
+        }
+        logInfo(`Extraction produced ${extraction.entities.length} entities / ${extraction.relations.length} relationships`);
+        const { nodesCreated, edgesCreated } = await persistDiagram(supabase, diagramId, extraction);
+        await markDiagramSuccess(supabase, diagramId, extraction.summary);
+        succeeded = true;
+        logSuccess(`ER diagram generated: ${nodesCreated} entities, ${edgesCreated} relationships`);
+        return {
+            status: 'success',
+            message: `ER diagram generated (${nodesCreated} entities, ${edgesCreated} relationships)`,
+            nodesCreated,
+            edgesCreated,
+            summary: extraction.summary,
+        };
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        logError(`ER diagram failed: ${errorMessage}`);
+        await markDiagramFailed(supabase, diagramId, errorMessage);
+        return { status: 'error', message: errorMessage };
+    }
+    finally {
+        if (succeeded) {
+            cleanupIssueRepo(cleanupDir);
+        }
+    }
+}
+/**
+ * Build "product basics" for repo-only mode from the repositories row,
+ * falling back to the cloned repo's full name when the row has no name.
+ */
+async function resolveRepoBasics(repositoryId, repos) {
+    const basics = await getRepositoryBasics(repositoryId).catch(() => null);
+    return {
+        name: basics?.fullName ?? repos[0]?.fullName ?? repositoryId,
+        description: basics?.description ?? undefined,
+    };
+}
+/** Read the ordered repo set a diagram was scoped to (may be empty). */
+async function getDiagramRepositoryIds(supabase, diagramId) {
+    const { data } = await supabase
+        .from('diagrams')
+        .select('repository_ids')
+        .eq('id', diagramId)
+        .single();
+    return (data?.repository_ids ?? []).filter(Boolean);
+}
+function processSdkMessage(
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+message, assistantBuffer, captureState, verbose) {
+    if (message.type === 'assistant') {
+        const next = assistantBuffer +
+            extractTextFromContent(message.message?.content ?? [], verbose);
+        return { assistantBuffer: next, extraction: null };
+    }
+    if (message.type === 'user' && verbose) {
+        const userContent = message.message?.content;
+        if (Array.isArray(userContent)) {
+            extractTextFromContent(userContent, verbose);
+        }
+        return { assistantBuffer, extraction: null };
+    }
+    if (message.type !== 'result') {
+        return { assistantBuffer, extraction: null };
+    }
+    if (captureState.captured) {
+        return { assistantBuffer, extraction: captureState.captured };
+    }
+    const fallback = tryFallbackParse(message, assistantBuffer);
+    if (fallback) {
+        logWarning('Agent emitted a fenced er_diagram block instead of calling submit_er_diagram; using the parsed text as a fallback.');
+        return { assistantBuffer, extraction: fallback };
+    }
+    if (message.subtype !== 'success') {
+        logError(`Extraction incomplete: ${message.subtype}`);
+    }
+    return { assistantBuffer, extraction: null };
+}
+function tryFallbackParse(resultMessage, assistantText) {
+    const responseText = resultMessage.subtype === 'success'
+        ? resultMessage.result || assistantText
+        : assistantText;
+    const parsed = tryExtractResult(responseText, 'er_diagram');
+    if (!isErDiagramExtraction(parsed)) {
+        return null;
+    }
+    const { error } = validateConsistency(parsed);
+    if (error) {
+        logWarning(`Fallback extraction failed consistency check: ${error}`);
+        return null;
+    }
+    return parsed;
+}
+// ============================================================================
+// Persistence
+// ============================================================================
+async function markDiagramRunning(supabase, diagramId) {
+    const { error } = await supabase
+        .from('diagrams')
+        .update({ status: 'running', error: null })
+        .eq('id', diagramId);
+    if (error) {
+        logWarning(`Could not mark diagram as running: ${error.message}`);
+    }
+}
+async function markDiagramFailed(supabase, diagramId, errorMessage) {
+    await supabase
+        .from('diagrams')
+        .update({
+        status: 'failed',
+        error: errorMessage,
+        completed_at: new Date().toISOString(),
+    })
+        .eq('id', diagramId);
+}
+async function markDiagramSuccess(supabase, diagramId, summary) {
+    await supabase
+        .from('diagrams')
+        .update({
+        status: 'success',
+        summary,
+        error: null,
+        completed_at: new Date().toISOString(),
+    })
+        .eq('id', diagramId);
+}
+async function persistDiagram(supabase, diagramId, extraction) {
+    await supabase.from('diagram_edges').delete().eq('diagram_id', diagramId);
+    await supabase.from('diagram_nodes').delete().eq('diagram_id', diagramId);
+    if (extraction.entities.length === 0) {
+        return { nodesCreated: 0, edgesCreated: 0 };
+    }
+    const nodeRows = extraction.entities.map((e, i) => buildNodeRow(diagramId, e, i));
+    const { data: insertedNodes, error: nodesError } = await supabase
+        .from('diagram_nodes')
+        .insert(nodeRows)
+        .select('id, slug');
+    if (nodesError) {
+        throw new Error(`Failed to insert entities: ${nodesError.message}`);
+    }
+    const slugToId = new Map((insertedNodes ?? []).map((n) => [n.slug, n.id]));
+    const edgeRows = extraction.relations
+        .map((r) => buildEdgeRow(diagramId, r, slugToId))
+        .filter((e) => e !== null);
+    if (edgeRows.length > 0) {
+        const { error: edgesError } = await supabase
+            .from('diagram_edges')
+            .insert(edgeRows);
+        if (edgesError) {
+            throw new Error(`Failed to insert relationships: ${edgesError.message}`);
+        }
+    }
+    return {
+        nodesCreated: nodeRows.length,
+        edgesCreated: edgeRows.length,
+    };
+}
+function buildNodeRow(diagramId, entity, index) {
+    return {
+        diagram_id: diagramId,
+        slug: entity.slug,
+        name: entity.name,
+        kind: entity.kind,
+        schema: entity,
+        position_x: (index % COLUMNS) * COLUMN_WIDTH,
+        position_y: Math.floor(index / COLUMNS) * ROW_HEIGHT,
+    };
+}
+function buildEdgeRow(diagramId, relation, slugToId) {
+    const fromId = slugToId.get(relation.fromSlug);
+    const toId = slugToId.get(relation.toSlug);
+    if (!fromId || !toId) {
+        return null;
+    }
+    return {
+        diagram_id: diagramId,
+        from_node_id: fromId,
+        to_node_id: toId,
+        label: relation.label ?? null,
+        source_anchor: relation.sourceFile ?? null,
+        kind: relation.kind,
+        metadata: {
+            sourceColumn: relation.sourceColumn ?? null,
+            targetColumn: relation.targetColumn ?? null,
+        },
+    };
+}

package/dist/phases/er-diagram/mcp-server.d.ts

@@ -0,0 +1,77 @@
+/**
+ * In-process MCP server for the er-diagram phase. Exposes a single tool —
+ * `submit_er_diagram` — that the agent calls with the structured extraction,
+ * plus `record_progress` for streaming status messages.
+ *
+ * Mirrors the shape of phases/data-flow/mcp-server.ts; see that file for
+ * the design rationale (zod schema + cross-field consistency + capture state).
+ */
+import { z } from 'zod';
+import type { ErDiagramExtraction } from './types.js';
+export interface ErDiagramCaptureState {
+    captured: ErDiagramExtraction | null;
+}
+export declare function createErDiagramCaptureState(): ErDiagramCaptureState;
+export type ErDiagramProgressSink = (event: {
+    phase: 'detection' | 'enumeration' | 'entities' | 'relations' | 'submission';
+    message: string;
+}) => void;
+export declare function validateConsistency(extraction: ErDiagramExtraction): {
+    error: string | null;
+};
+export declare function createSubmitErDiagramTool(state: ErDiagramCaptureState): import("@anthropic-ai/claude-agent-sdk").SdkMcpToolDefinition<{
+    summary: z.ZodString;
+    entities: z.ZodArray<z.ZodObject<{
+        slug: z.ZodString;
+        name: z.ZodString;
+        kind: z.ZodEnum<{
+            enum: "enum";
+            entity: "entity";
+            view: "view";
+            junction: "junction";
+        }>;
+        file: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+        columns: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            type: z.ZodOptional<z.ZodString>;
+            isPrimaryKey: z.ZodOptional<z.ZodBoolean>;
+            isForeignKey: z.ZodOptional<z.ZodBoolean>;
+            isNullable: z.ZodOptional<z.ZodBoolean>;
+            isUnique: z.ZodOptional<z.ZodBoolean>;
+            description: z.ZodOptional<z.ZodString>;
+            references: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
+        stats: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            label: z.ZodString;
+            value: z.ZodString;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>;
+    relations: z.ZodArray<z.ZodObject<{
+        fromSlug: z.ZodString;
+        toSlug: z.ZodString;
+        kind: z.ZodEnum<{
+            "one-to-one": "one-to-one";
+            "one-to-many": "one-to-many";
+            "many-to-many": "many-to-many";
+            inherits: "inherits";
+        }>;
+        label: z.ZodOptional<z.ZodString>;
+        sourceColumn: z.ZodOptional<z.ZodString>;
+        targetColumn: z.ZodOptional<z.ZodString>;
+        sourceFile: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}>;
+export declare function createRecordProgressTool(sink?: ErDiagramProgressSink): import("@anthropic-ai/claude-agent-sdk").SdkMcpToolDefinition<{
+    phase: z.ZodEnum<{
+        detection: "detection";
+        enumeration: "enumeration";
+        submission: "submission";
+        entities: "entities";
+        relations: "relations";
+    }>;
+    message: z.ZodString;
+}>;
+export declare function createErDiagramMcpServer(state: ErDiagramCaptureState, options?: {
+    onProgress?: ErDiagramProgressSink;
+}): import("@anthropic-ai/claude-agent-sdk").McpSdkServerConfigWithInstance;

package/dist/phases/er-diagram/mcp-server.js

@@ -0,0 +1,144 @@
+/**
+ * In-process MCP server for the er-diagram phase. Exposes a single tool —
+ * `submit_er_diagram` — that the agent calls with the structured extraction,
+ * plus `record_progress` for streaming status messages.
+ *
+ * Mirrors the shape of phases/data-flow/mcp-server.ts; see that file for
+ * the design rationale (zod schema + cross-field consistency + capture state).
+ */
+import { createSdkMcpServer, tool } from '@anthropic-ai/claude-agent-sdk';
+import { z } from 'zod';
+export function createErDiagramCaptureState() {
+    return { captured: null };
+}
+// ---------------------------------------------------------------------------
+// Zod schemas (mirror types.ts)
+// ---------------------------------------------------------------------------
+const erColumnSchema = z.object({
+    name: z.string().min(1),
+    type: z.string().optional(),
+    isPrimaryKey: z.boolean().optional(),
+    isForeignKey: z.boolean().optional(),
+    isNullable: z.boolean().optional(),
+    isUnique: z.boolean().optional(),
+    description: z.string().optional(),
+    references: z.string().optional(),
+});
+const erStatSchema = z.object({
+    label: z.string(),
+    value: z.string(),
+});
+const erEntitySchema = z.object({
+    slug: z.string().min(1),
+    name: z.string().min(1),
+    kind: z.enum(['entity', 'view', 'enum', 'junction']),
+    file: z.string().optional(),
+    description: z.string().optional(),
+    columns: z.array(erColumnSchema).optional(),
+    stats: z.array(erStatSchema).optional(),
+});
+const erRelationSchema = z.object({
+    fromSlug: z.string().min(1),
+    toSlug: z.string().min(1),
+    kind: z.enum(['one-to-one', 'one-to-many', 'many-to-many', 'inherits']),
+    label: z.string().optional(),
+    sourceColumn: z.string().optional(),
+    targetColumn: z.string().optional(),
+    sourceFile: z.string().optional(),
+});
+export function validateConsistency(extraction) {
+    const slugs = new Set();
+    for (const entity of extraction.entities) {
+        if (slugs.has(entity.slug)) {
+            return {
+                error: `Duplicate entity slug "${entity.slug}". Each entity.slug MUST be unique within the diagram. Re-call submit_er_diagram with deduplicated entities.`,
+            };
+        }
+        slugs.add(entity.slug);
+    }
+    for (const relation of extraction.relations) {
+        if (!slugs.has(relation.fromSlug)) {
+            return {
+                error: `Relation fromSlug "${relation.fromSlug}" → "${relation.toSlug}" does not match any entity slug. Either add the missing entity or drop the relation, then re-call submit_er_diagram.`,
+            };
+        }
+        if (!slugs.has(relation.toSlug)) {
+            return {
+                error: `Relation fromSlug "${relation.fromSlug}" → toSlug "${relation.toSlug}" does not match any entity slug. Either add the missing entity or drop the relation, then re-call submit_er_diagram.`,
+            };
+        }
+    }
+    return { error: null };
+}
+export function createSubmitErDiagramTool(state) {
+    return tool('submit_er_diagram', [
+        'Submit the final entity-relationship diagram. Call this EXACTLY once,',
+        'when you have finished mapping every entity and relationship. Pass',
+        'the full structured diagram as the argument. After this call succeeds,',
+        'end your turn — do NOT also paste the same data as a fenced code',
+        'block. If validation fails, the error message tells you what to fix;',
+        'call the tool again with corrected data.',
+    ].join(' '), {
+        summary: z
+            .string()
+            .min(1)
+            .describe("1-3 sentence narrative of the data model: the core entities and how they're related."),
+        entities: z
+            .array(erEntitySchema)
+            .describe('Every entity: table / view / enum / junction table. entity.slug MUST be unique within the diagram.'),
+        relations: z
+            .array(erRelationSchema)
+            .describe('Relationships. fromSlug = entity holding the foreign key (child / "many" side), toSlug = referenced entity (parent / "one" side). Every fromSlug / toSlug MUST reference a slug present in entities; drop relations whose endpoints you did not emit.'),
+    }, async (args) => {
+        const extraction = {
+            summary: args.summary,
+            entities: args.entities,
+            relations: args.relations,
+        };
+        const { error } = validateConsistency(extraction);
+        if (error) {
+            return {
+                content: [{ type: 'text', text: error }],
+                isError: true,
+            };
+        }
+        state.captured = extraction;
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Captured ${extraction.entities.length} entities / ${extraction.relations.length} relationships. End your turn now.`,
+                },
+            ],
+        };
+    });
+}
+export function createRecordProgressTool(sink) {
+    return tool('record_progress', 'Send a short status update to the user. Does not affect the extraction. Call it at each phase boundary so the user sees progress.', {
+        phase: z
+            .enum([
+            'detection',
+            'enumeration',
+            'entities',
+            'relations',
+            'submission',
+        ])
+            .describe('Which phase the message belongs to.'),
+        message: z.string().min(1).describe('Human-readable status update.'),
+    }, async (args) => {
+        sink?.({ phase: args.phase, message: args.message });
+        return {
+            content: [{ type: 'text', text: 'ok' }],
+        };
+    });
+}
+export function createErDiagramMcpServer(state, options) {
+    return createSdkMcpServer({
+        name: 'er-diagram',
+        version: '1.0.0',
+        tools: [
+            createSubmitErDiagramTool(state),
+            createRecordProgressTool(options?.onProgress),
+        ],
+    });
+}

package/dist/phases/er-diagram/prompts.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Prompts for the er-diagram phase. Loads the system prompt body from
+ * `skills/phase/er-diagram/SKILL.md` (with optional project override) and
+ * appends the JSON output contract.
+ */
+export declare function createErDiagramSystemPrompt(options?: {
+    projectDir?: string;
+    hasCodebase?: boolean;
+}): Promise<string>;
+export declare function createErDiagramUserPrompt(args: {
+    productName: string;
+    productDescription?: string;
+    guidance?: string;
+}): string;

package/dist/phases/er-diagram/prompts.js

@@ -0,0 +1,36 @@
+/**
+ * Prompts for the er-diagram phase. Loads the system prompt body from
+ * `skills/phase/er-diagram/SKILL.md` (with optional project override) and
+ * appends the JSON output contract.
+ */
+import { processConditionals, resolveSkill, } from '../../services/skill-resolver.js';
+import { OUTPUT_CONTRACTS } from '../output-contracts.js';
+export async function createErDiagramSystemPrompt(options) {
+    const skill = await resolveSkill('phase/er-diagram', {
+        projectDir: options?.projectDir,
+    });
+    if (!skill) {
+        throw new Error('Failed to load skill: phase/er-diagram');
+    }
+    const prompt = processConditionals(skill.prompt, {
+        hasCodebase: options?.hasCodebase ?? true,
+    });
+    return `${prompt}
+
+${OUTPUT_CONTRACTS['er-diagram']}`;
+}
+export function createErDiagramUserPrompt(args) {
+    const guidanceBlock = args.guidance
+        ? `\n\n**Human guidance for this run** (focus or exclude as instructed):\n${args.guidance}`
+        : '';
+    const descBlock = args.productDescription
+        ? `\n**Product description**: ${args.productDescription}`
+        : '';
+    return `Map the entity-relationship model for **${args.productName}**.${descBlock}${guidanceBlock}
+
+Start by detecting the stack and locating the schema source of truth (database migrations, ORM models — Prisma / SQLAlchemy / TypeORM / ActiveRecord / Drizzle, \`CREATE TABLE\` SQL, or typed schema files). Read just enough per entity to fill in a useful set of columns and the relationships — you do not need to read everything.
+
+Call \`mcp__er-diagram__record_progress\` at each phase boundary so the user can see your progress (otherwise the CLI looks frozen).
+
+When you are done, return the result by **calling the \`mcp__er-diagram__submit_er_diagram\` tool exactly once** with \`summary\`, \`entities\`, and \`relations\` as arguments. Do not paste the JSON as a fenced text block — the tool call is the deliverable. If the tool returns an error, fix the issue it describes and call the tool again.`;
+}

package/dist/phases/er-diagram/types.d.ts

@@ -0,0 +1,76 @@
+/**
+ * ER Diagram domain types.
+ *
+ * An ErEntity is a structured description of one persistence entity in a
+ * product — a table, a view, or an enum. The CLI extracts these from schema
+ * files (migrations, ORM models, type definitions) and the desktop renders
+ * them as an entity-relationship diagram.
+ *
+ * Companion to DataNodeSchema / ScreenSchema: same flow-graph shape (nodes +
+ * edges sharing the `diagrams` table storing the JSONB schema), different domain.
+ * ER edges describe foreign-key / inheritance relationships between entities,
+ * with a cardinality, not data movement or user navigation.
+ */
+export type ErEntityKind = 'entity' | 'view' | 'enum' | 'junction';
+export interface ErColumn {
+    /** Column / field name. */
+    name: string;
+    /** Data type as written in the schema (e.g. 'uuid', 'varchar(255)', 'jsonb'). */
+    type?: string;
+    /** True if part of the primary key. */
+    isPrimaryKey?: boolean;
+    /** True if a foreign key referencing another entity. */
+    isForeignKey?: boolean;
+    /** True if the column is nullable. */
+    isNullable?: boolean;
+    /** True if the column has a unique constraint. */
+    isUnique?: boolean;
+    /** One short note about the column's purpose. */
+    description?: string;
+    /** For foreign keys: 'entity-slug.column' the FK points at. */
+    references?: string;
+}
+export interface ErStat {
+    label: string;
+    value: string;
+}
+export interface ErEntity {
+    /** Stable slug within the diagram (e.g. 'users', 'order-items'). */
+    slug: string;
+    /** Human-readable name (usually the table name). */
+    name: string;
+    kind: ErEntityKind;
+    /** Source file path (jump anchor): the migration / model / schema file. */
+    file?: string;
+    /** One-sentence description. */
+    description?: string;
+    /** Columns / fields of the entity. */
+    columns?: ErColumn[];
+    /** Volume / cardinality hints — free-form key/value pairs. */
+    stats?: ErStat[];
+}
+/**
+ * Relationship kinds. Direction: fromSlug is the entity that owns the
+ * foreign key (the "many"/child side), toSlug is the referenced entity
+ * (the "one"/parent side). `inherits` models table inheritance / subtyping.
+ */
+export type ErRelationKind = 'one-to-one' | 'one-to-many' | 'many-to-many' | 'inherits';
+export interface ErRelation {
+    fromSlug: string;
+    toSlug: string;
+    kind: ErRelationKind;
+    /** Free-form descriptor: 'placed by', 'belongs to', 'tagged with'. */
+    label?: string;
+    /** Column on the from-entity that holds the foreign key. */
+    sourceColumn?: string;
+    /** Column on the to-entity being referenced (usually its primary key). */
+    targetColumn?: string;
+    /** File containing the relationship definition (FK constraint / model). */
+    sourceFile?: string;
+}
+export interface ErDiagramExtraction {
+    summary: string;
+    entities: ErEntity[];
+    relations: ErRelation[];
+}
+export declare function isErDiagramExtraction(value: unknown): value is ErDiagramExtraction;