speckeeper 0.7.1 → 0.8.0

package/dist/config-api-Bh0zX8W7.d.ts

@@ -0,0 +1,967 @@
+import { z, ZodType } from 'zod';
+
+/**
+ * Export Context
+ * Context information passed to exporter functions
+ */
+interface ExportContext {
+    /** Access to all models (MetaModelRegistry type, using unknown to avoid circular references) */
+    registry: unknown;
+    /** Configuration (SpeckeeperConfig type, using unknown to avoid circular references) */
+    config: unknown;
+    /** Output base directory */
+    outputDir: string;
+    /** Current date/time */
+    generatedAt: Date;
+}
+/**
+ * Lint Context
+ * Context information passed to lint functions
+ */
+interface LintContext {
+    /** Access to all models (MetaModelRegistry type) */
+    registry: unknown;
+    /** Current phase */
+    phase?: 'REQ' | 'HLD' | 'LLD' | 'OPS';
+    /** Strict mode */
+    strict?: boolean;
+}
+/**
+ * Check Context
+ * Context information passed to external SSOT check functions
+ */
+interface CheckContext {
+    /** Access to all models (MetaModelRegistry type) */
+    registry: unknown;
+    /** External SSOT file path */
+    sourcePath: string;
+    /** Configuration (SpeckeeperConfig type) */
+    config: unknown;
+}
+/**
+ * Lint Issue
+ */
+interface LintIssue {
+    /** Issue message */
+    message: string;
+    /** Problematic field (optional) */
+    field?: string;
+    /** Fix suggestion (optional) */
+    suggestion?: string;
+}
+/**
+ * Check Result
+ */
+interface CheckResult$1 {
+    /** Whether successful */
+    success: boolean;
+    /** List of error messages */
+    errors: CheckError[];
+    /** List of warning messages */
+    warnings: CheckWarning[];
+}
+interface CheckError {
+    /** Error message */
+    message: string;
+    /** Target model ID */
+    modelId: string;
+    /** External SSOT reference */
+    externalRef?: string;
+}
+interface CheckWarning {
+    /** Warning message */
+    message: string;
+    /** Target model ID */
+    modelId: string;
+}
+/**
+ * Markdown Exporter
+ */
+interface MarkdownExporter<T> {
+    /** Single document generation */
+    single: (model: T, context: ExportContext) => string;
+    /** Index page generation (optional) */
+    index?: (models: T[], context: ExportContext) => string;
+    /** Output directory (relative path from docs/) */
+    outputDir: string;
+    /** Filename generation (default is model.id) */
+    filename?: (model: T) => string;
+}
+/**
+ * Mermaid Diagram Exporter
+ */
+interface MermaidExporter<T> {
+    /** Diagram type */
+    diagramType: 'flowchart' | 'sequenceDiagram' | 'erDiagram' | 'stateDiagram' | 'C4Context' | 'C4Container' | 'C4Component' | 'custom';
+    /** Diagram generation function */
+    generate: (models: T[], context: ExportContext) => string;
+    /** Output file path (relative path from docs/) */
+    outputPath: string;
+    /** Diagram title */
+    title?: string;
+}
+/**
+ * JSON Schema Exporter Settings
+ */
+interface JsonSchemaExporter {
+    /** Enabled */
+    enabled: boolean;
+    /** Output directory (relative path from specs/) */
+    outputDir: string;
+}
+/**
+ * Lint Rule
+ */
+interface LintRule$1<T> {
+    /** Rule ID */
+    id: string;
+    /** Rule description */
+    description: string;
+    /** Severity */
+    severity: 'error' | 'warning' | 'info';
+    /** Check function */
+    check: (model: T, context: LintContext) => LintIssue | null;
+}
+/**
+ * External SSOT Checker
+ */
+interface ExternalChecker$1<T> {
+    /** External SSOT type to check */
+    targetType: 'openapi' | 'ddl' | 'iac' | 'custom';
+    /** Execute check */
+    check: (model: T, externalSource: unknown, context: CheckContext) => CheckResult$1;
+    /** Get external SSOT file path (from model) */
+    getSourcePath?: (model: T) => string | undefined;
+}
+/**
+ * Inter-model Reference Definition (for traceability)
+ */
+interface ReferenceDefinition {
+    /** Field name with reference */
+    field: string;
+    /** Referenced model ID */
+    targetModel: string;
+    /** Whether reference is required */
+    required?: boolean;
+    /** Whether reference is array */
+    isArray?: boolean;
+}
+/**
+ * Model Definition
+ * Interface for users to define new entities
+ */
+interface ModelDefinition<T extends z.ZodTypeAny = z.ZodTypeAny> {
+    /** Model unique identifier (kebab-case recommended) */
+    id: string;
+    /** Model name (PascalCase recommended) */
+    name: string;
+    /** Model description */
+    description: string;
+    /** Zod Schema */
+    schema: T;
+    /** ID prefix for generation */
+    idPrefix: string;
+    /** Exporter settings */
+    exporters?: {
+        /** Markdown exporter */
+        markdown?: MarkdownExporter<z.infer<T>>;
+        /** Mermaid diagram exporter (multiple allowed) */
+        mermaid?: MermaidExporter<z.infer<T>> | MermaidExporter<z.infer<T>>[];
+        /** JSON Schema exporter */
+        jsonSchema?: JsonSchemaExporter;
+    };
+    /** Lint rules */
+    lintRules?: LintRule$1<z.infer<T>>[];
+    /** External SSOT checker */
+    externalChecker?: ExternalChecker$1<z.infer<T>>;
+    /** Reference definitions (for traceability) */
+    references?: ReferenceDefinition[];
+    /** DSL function name (the Xxx part of defineXxx) */
+    dslName?: string;
+    /** Phase (the phase where this model is primarily used) */
+    phase?: 'REQ' | 'HLD' | 'LLD' | 'OPS';
+}
+/**
+ * Meta Model Registry
+ * Manages registered model definitions and model instances
+ */
+interface MetaModelRegistry {
+    /** Registered model definitions */
+    definitions: Map<string, ModelDefinition>;
+    /** Model instances (Map<instanceId, instance> for each model ID) */
+    instances: Map<string, Map<string, unknown>>;
+}
+/**
+ * Additional settings for meta model
+ */
+interface MetaModelConfig {
+    /** Custom model definitions */
+    models?: ModelDefinition[];
+    /** External SSOT settings */
+    externalSsot?: {
+        openapi?: {
+            enabled: boolean;
+            paths: string[];
+        };
+        ddl?: {
+            enabled: boolean;
+            type: 'ddl' | 'prisma' | 'typeorm' | 'drizzle';
+            path: string;
+        };
+        iac?: {
+            enabled: boolean;
+            type: 'cloudformation' | 'cdk' | 'terraform';
+            path: string;
+        };
+    };
+}
+/**
+ * Base type for model instances
+ * All model instances have an id
+ */
+interface BaseModelInstance {
+    id: string;
+}
+/**
+ * Helper type for creating type-safe model definitions
+ */
+type InferModelType<T extends ModelDefinition> = z.infer<T['schema']>;
+declare const ReferenceDefinitionSchema: z.ZodObject<{
+    field: z.ZodString;
+    targetModel: z.ZodString;
+    required: z.ZodOptional<z.ZodBoolean>;
+    isArray: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    field: string;
+    targetModel: string;
+    required?: boolean | undefined;
+    isArray?: boolean | undefined;
+}, {
+    field: string;
+    targetModel: string;
+    required?: boolean | undefined;
+    isArray?: boolean | undefined;
+}>;
+declare const LintIssueSchema: z.ZodObject<{
+    message: z.ZodString;
+    field: z.ZodOptional<z.ZodString>;
+    suggestion: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    message: string;
+    field?: string | undefined;
+    suggestion?: string | undefined;
+}, {
+    message: string;
+    field?: string | undefined;
+    suggestion?: string | undefined;
+}>;
+declare const CheckErrorSchema: z.ZodObject<{
+    message: z.ZodString;
+    modelId: z.ZodString;
+    externalRef: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    message: string;
+    modelId: string;
+    externalRef?: string | undefined;
+}, {
+    message: string;
+    modelId: string;
+    externalRef?: string | undefined;
+}>;
+declare const CheckWarningSchema: z.ZodObject<{
+    message: z.ZodString;
+    modelId: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    message: string;
+    modelId: string;
+}, {
+    message: string;
+    modelId: string;
+}>;
+declare const CheckResultSchema: z.ZodObject<{
+    success: z.ZodBoolean;
+    errors: z.ZodArray<z.ZodObject<{
+        message: z.ZodString;
+        modelId: z.ZodString;
+        externalRef: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        message: string;
+        modelId: string;
+        externalRef?: string | undefined;
+    }, {
+        message: string;
+        modelId: string;
+        externalRef?: string | undefined;
+    }>, "many">;
+    warnings: z.ZodArray<z.ZodObject<{
+        message: z.ZodString;
+        modelId: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        message: string;
+        modelId: string;
+    }, {
+        message: string;
+        modelId: string;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    success: boolean;
+    errors: {
+        message: string;
+        modelId: string;
+        externalRef?: string | undefined;
+    }[];
+    warnings: {
+        message: string;
+        modelId: string;
+    }[];
+}, {
+    success: boolean;
+    errors: {
+        message: string;
+        modelId: string;
+        externalRef?: string | undefined;
+    }[];
+    warnings: {
+        message: string;
+        modelId: string;
+    }[];
+}>;
+
+/**
+ * Definition and validation of model relations
+ */
+
+/**
+ * Model abstraction level
+ *
+ * - L0: Business + Domain Analysis (Why / Problem space)
+ *       Desired outcomes/value, business flows, actors, terminology, business rules
+ * - L1: Requirements (What)
+ *       Functional/non-functional requirements, constraints, acceptance criteria
+ * - L2: Design (How / Direction)
+ *       Architecture, component breakdown, domain model, key sequences
+ * - L3: Detailed Design/Implementation (How to build / Concrete artifacts)
+ *       Screen/API/DB definitions, external SSOT references
+ */
+type ModelLevel = 'L0' | 'L1' | 'L2' | 'L3';
+/**
+ * Get numeric index of level
+ */
+declare function getLevelIndex(level: ModelLevel): number;
+/**
+ * Relation types
+ */
+declare const RELATION_TYPES: readonly ["dependsOn", "uses", "includes", "implements", "refines", "verifies", "verifiedBy", "satisfies", "traces", "relatedTo"];
+type RelationType = typeof RELATION_TYPES[number];
+/**
+ * Relation schema
+ */
+declare const RelationSchema: z.ZodObject<{
+    /** Relation type */
+    type: z.ZodEnum<["dependsOn", "uses", "includes", "implements", "refines", "verifies", "verifiedBy", "satisfies", "traces", "relatedTo"]>;
+    /** Target ID */
+    target: z.ZodString;
+    /** Description (optional) */
+    description: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    type: "includes" | "dependsOn" | "uses" | "implements" | "refines" | "verifies" | "verifiedBy" | "satisfies" | "traces" | "relatedTo";
+    target: string;
+    description?: string | undefined;
+}, {
+    type: "includes" | "dependsOn" | "uses" | "implements" | "refines" | "verifies" | "verifiedBy" | "satisfies" | "traces" | "relatedTo";
+    target: string;
+    description?: string | undefined;
+}>;
+/**
+ * Relation field to add to model schemas
+ * Usage: schema.extend({ relations: RelationsFieldSchema })
+ */
+declare const RelationsFieldSchema: z.ZodOptional<z.ZodArray<z.ZodObject<{
+    /** Relation type */
+    type: z.ZodEnum<["dependsOn", "uses", "includes", "implements", "refines", "verifies", "verifiedBy", "satisfies", "traces", "relatedTo"]>;
+    /** Target ID */
+    target: z.ZodString;
+    /** Description (optional) */
+    description: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    type: "includes" | "dependsOn" | "uses" | "implements" | "refines" | "verifies" | "verifiedBy" | "satisfies" | "traces" | "relatedTo";
+    target: string;
+    description?: string | undefined;
+}, {
+    type: "includes" | "dependsOn" | "uses" | "implements" | "refines" | "verifies" | "verifiedBy" | "satisfies" | "traces" | "relatedTo";
+    target: string;
+    description?: string | undefined;
+}>, "many">>;
+type Relation = z.infer<typeof RelationSchema>;
+/**
+ * Definition of relation constraints
+ */
+interface RelationConstraint {
+    /** Allowed target levels (all levels allowed if not specified) */
+    allowedTargetLevels?: ModelLevel[];
+    /** Level constraint rule */
+    levelRule: 'source>target' | 'source>=target' | 'same' | 'any';
+    /** Direction of impact propagation */
+    propagation: 'forward' | 'backward' | 'both';
+}
+/**
+ * Constraint definitions per relation type
+ *
+ * Level hierarchy:
+ *   L0 (Business) → L1 (Requirements) → L2 (Design) → L3 (Implementation)
+ *   Abstract ───────────────────────────→ Concrete
+ */
+declare const RELATION_CONSTRAINTS: Record<RelationType, RelationConstraint>;
+/**
+ * Relation validation error
+ */
+interface RelationValidationError {
+    type: 'level_violation' | 'target_level_violation' | 'self_reference' | 'cycle_detected';
+    message: string;
+    relation: Relation;
+    sourceId: string;
+}
+/**
+ * Validate level constraint for single relation
+ *
+ * @param sourceLevel - Source model level (set in _models/)
+ * @param sourceSpecId - Source spec ID
+ * @param relation - Relation
+ * @param targetLevel - Target model level
+ */
+declare function validateRelationLevel(sourceLevel: ModelLevel | undefined, sourceSpecId: string, relation: Relation, targetLevel: ModelLevel | undefined): RelationValidationError | null;
+/**
+ * Detect circular references
+ */
+declare function detectCycles(relations: Array<{
+    sourceId: string;
+    targetId: string;
+    type: RelationType;
+}>): RelationValidationError[];
+/**
+ * Infer model ID from spec ID (prefix-based)
+ */
+declare function inferModelIdFromSpecId(specId: string): string | undefined;
+
+/**
+ * Model base class
+ *
+ * All model definitions inherit from this class
+ */
+
+/**
+ * Lint rule definition
+ */
+interface LintRule<T> {
+    id: string;
+    severity: 'error' | 'warning' | 'info';
+    message: string;
+    check: (spec: T) => boolean;
+}
+/**
+ * Lint result
+ */
+interface LintResult {
+    ruleId: string;
+    severity: 'error' | 'warning' | 'info';
+    message: string;
+    specId?: string;
+}
+/**
+ * Exporter definition
+ */
+interface Exporter<T> {
+    format: 'markdown' | 'json' | 'mermaid';
+    single?: (spec: T) => string;
+    index?: (specs: T[]) => string;
+    outputDir?: string;
+    filename?: (spec: T) => string;
+}
+/**
+ * External checker definition
+ */
+interface ExternalChecker<T> {
+    targetType: string;
+    sourcePath: (spec: T) => string;
+    check: (spec: T, externalData: unknown) => CheckResult;
+}
+/**
+ * Check result
+ */
+interface CheckResult {
+    success: boolean;
+    errors: {
+        message: string;
+        field?: string;
+        specId?: string;
+    }[];
+    warnings: {
+        message: string;
+        field?: string;
+        specId?: string;
+    }[];
+    /** Files where annotations matching this spec were found */
+    matchedFiles?: Array<{
+        specId: string;
+        filePath: string;
+        line: number;
+        relationType: 'verifiedBy' | 'implements' | 'traces';
+    }>;
+}
+/**
+ * Coverage result
+ */
+interface CoverageResult {
+    /** Total target count */
+    total: number;
+    /** Covered count */
+    covered: number;
+    /** Uncovered count */
+    uncovered: number;
+    /** Coverage rate (%) */
+    coveragePercent: number;
+    /** Details of covered items */
+    coveredItems: {
+        id: string;
+        description?: string;
+    }[];
+    /** Details of uncovered items */
+    uncoveredItems: {
+        id: string;
+        description?: string;
+        sourceId?: string;
+    }[];
+}
+/**
+ * Coverage checker definition
+ *
+ * Verify cross-model consistency (coverage).
+ * Example: Whether TestRef covers acceptanceCriteria of Requirement
+ */
+interface CoverageChecker<T> {
+    /** Target model ID for coverage (e.g. 'requirement') */
+    targetModel: string;
+    /** Description of coverage check */
+    description: string;
+    /** Execute coverage check */
+    check: (specs: T[], registry: Record<string, Map<string, unknown>>) => CoverageResult;
+}
+/**
+ * Render context
+ * Simplified version compatible with embedoc's EmbedContext
+ */
+interface RenderContext {
+    /** Parameters (filter conditions other than format, etc.) */
+    params: Record<string, string | undefined>;
+    /** Markdown helpers */
+    markdown: {
+        /** Generate table */
+        table: (headers: string[], rows: (string | unknown)[][]) => string;
+    };
+}
+/**
+ * Renderer definition
+ *
+ * Model-specific rendering called from embeds
+ */
+interface Renderer<T> {
+    /** Format ID ('table', 'list', 'detail', 'spec-chapter', etc.) */
+    format: string;
+    /** Rendering process */
+    render: (specs: T[], ctx: RenderContext) => string;
+}
+/**
+ * Model base class
+ *
+ * @template TSchema - Zod schema type
+ */
+declare abstract class Model<TSchema extends ZodType> {
+    /** Singleton instance storage (per subclass) */
+    private static _instances;
+    /**
+     * Get singleton instance of the model
+     * Usage: RequirementModel.instance
+     */
+    static get instance(): Model<ZodType>;
+    /** Model ID ('requirement', 'usecase', etc.) */
+    abstract readonly id: string;
+    /** Model name ('Requirement', 'UseCase', etc.) */
+    abstract readonly name: string;
+    /** ID prefix ('REQ', 'UC', etc.) */
+    abstract readonly idPrefix: string;
+    /** Zod schema */
+    abstract readonly schema: TSchema;
+    /** Model description (optional) */
+    readonly description?: string;
+    /** External SSOT type (optional, e.g. 'OpenAPI', 'DDL/Prisma') */
+    readonly externalSsotType?: string;
+    /** Spec instance type */
+    protected get specType(): z.infer<TSchema>;
+    /** Lint rules (override in subclass) */
+    protected lintRules: LintRule<z.infer<TSchema>>[];
+    /** Exporters (override in subclass) */
+    protected exporters: Exporter<z.infer<TSchema>>[];
+    /** External checker (optional) */
+    protected externalChecker?: ExternalChecker<z.infer<TSchema>>;
+    /** Coverage checker (optional) */
+    protected coverageChecker?: CoverageChecker<z.infer<TSchema>>;
+    /** Model level (set in _models/) */
+    protected modelLevel?: ModelLevel;
+    /** Renderers (for embeds, override in subclass) */
+    protected renderers: Renderer<z.infer<TSchema>>[];
+    /**
+     * Get model level
+     * Returns modelLevel set in _models/
+     */
+    get level(): ModelLevel | undefined;
+    /**
+     * Execute schema validation
+     */
+    validate(spec: unknown): z.infer<TSchema>;
+    /**
+     * Schema validation (safe version, returns error object on failure)
+     */
+    safeParse(spec: unknown): {
+        success: true;
+        data: z.infer<TSchema>;
+    } | {
+        success: false;
+        error: z.ZodError;
+    };
+    /**
+     * Execute lint
+     */
+    lint(spec: z.infer<TSchema>): LintResult[];
+    /**
+     * Execute lint for multiple specs
+     */
+    lintAll(specs: z.infer<TSchema>[]): LintResult[];
+    /**
+     * Validate level constraints of relations
+     * @param spec - Spec instance (if it has relations property)
+     * @returns Array of validation errors
+     */
+    validateRelations(spec: z.infer<TSchema>): RelationValidationError[];
+    /**
+     * Validate relations of multiple specs (including circular reference check)
+     */
+    validateAllRelations(specs: z.infer<TSchema>[]): RelationValidationError[];
+    /**
+     * Export in specified format (single spec)
+     */
+    exportSingle(spec: z.infer<TSchema>, format: string): string | null;
+    /**
+     * Export in specified format (index)
+     */
+    exportIndex(specs: z.infer<TSchema>[], format: string): string | null;
+    /**
+     * Get exporter output directory
+     */
+    getOutputDir(format: string): string | null;
+    /**
+     * Get filename
+     */
+    getFilename(spec: z.infer<TSchema>, format: string): string | null;
+    /**
+     * Check consistency with external SSOT
+     */
+    check(spec: z.infer<TSchema>, externalData: unknown): CheckResult;
+    /**
+     * Get external SSOT path
+     */
+    getExternalSourcePath(spec: z.infer<TSchema>): string | null;
+    /**
+     * Execute coverage check
+     * @param specs - Array of spec instances for this model
+     * @param registry - Registry of all models
+     */
+    checkCoverage(specs: z.infer<TSchema>[], registry: Record<string, Map<string, unknown>>): CoverageResult | null;
+    /**
+     * Get coverage checker
+     */
+    getCoverageChecker(): CoverageChecker<z.infer<TSchema>> | undefined;
+    /**
+     * Get lint rules
+     */
+    getLintRules(): LintRule<z.infer<TSchema>>[];
+    /**
+     * Get exporters
+     */
+    getExporters(): Exporter<z.infer<TSchema>>[];
+    /**
+     * Render in specified format
+     * @param format - Format ID ('table', 'list', 'detail', etc.)
+     * @param specs - Array of specs to render
+     * @param ctx - Render context
+     * @returns Rendered result (Markdown string), null if no matching renderer
+     */
+    render(format: string, specs: z.infer<TSchema>[], ctx: RenderContext): string | null;
+    /**
+     * Get list of available formats
+     */
+    getAvailableFormats(): string[];
+    /**
+     * Get renderers
+     */
+    getRenderers(): Renderer<z.infer<TSchema>>[];
+    /**
+     * Check if renderer exists for specific format
+     */
+    hasRenderer(format: string): boolean;
+    /**
+     * Register spec instances for this model.
+     * Stores specs in the global specStore keyed by this model's id.
+     */
+    register(specs: z.infer<TSchema>[]): void;
+}
+/**
+ * A single (Model, data[]) pair.
+ * Uses structural typing (not nominal Model<any>) so that
+ * compiled dist/ Model instances are compatible with src/ types.
+ */
+interface SpecEntry {
+    model: {
+        id: string;
+        register: (data: unknown[]) => void;
+    };
+    data: unknown[];
+}
+/**
+ * Common export interface for spec data files.
+ * Each spec file exports a SpecModule via defineSpecs().
+ */
+interface SpecModule {
+    entries: SpecEntry[];
+}
+/**
+ * Aggregated result from mergeSpecs().
+ */
+interface MergedDesign {
+    models: SpecEntry['model'][];
+    specs: SpecEntry[];
+}
+/**
+ * Define spec data in a spec file. Returns a SpecModule.
+ *
+ * @example
+ * ```typescript
+ * export default defineSpecs(
+ *   [FunctionalRequirementModel.instance, functionalRequirements],
+ *   [NonFunctionalRequirementModel.instance, nonFunctionalRequirements],
+ * );
+ * ```
+ */
+declare function defineSpecs(...entries: [SpecEntry['model'], unknown[]][]): SpecModule;
+/**
+ * Merge multiple SpecModules into a single MergedDesign.
+ * Models are deduplicated by model.id.
+ *
+ * @example
+ * ```typescript
+ * // design/index.ts
+ * export default mergeSpecs(requirements, usecases, glossary);
+ * ```
+ */
+declare function mergeSpecs(...modules: SpecModule[]): MergedDesign;
+/**
+ * Build a registry (modelId -> Map<specId, spec>) from config.specs.
+ * Pure function — no global state.
+ */
+declare function buildRegistryFromConfig(specs: SpecEntry[] | undefined): Record<string, Map<string, unknown>>;
+/**
+ * Get specs for a model ID from config.specs.
+ * Pure function — no global state.
+ */
+declare function getSpecsFromConfig(specs: SpecEntry[] | undefined, modelId: string): unknown[];
+/**
+ * Find which model type a spec ID belongs to, from config.specs.
+ * Pure function — no global state.
+ */
+declare function findModelTypeFromConfig(specs: SpecEntry[] | undefined, specId: string): string | null;
+
+/** Artifact scan configuration */
+interface ArtifactConfig {
+    /** File path glob patterns to scan */
+    globs: string[];
+    /** Exclusion patterns */
+    exclude?: string[];
+    /** Content search patterns (RegExp). First capture group = spec IDs (comma or space separated) */
+    contentPatterns?: RegExp[];
+}
+/**
+ * speckeeper configuration type
+ */
+interface SpeckeeperConfigInput {
+    /** Project name */
+    projectName?: string;
+    /** Project version */
+    version?: string;
+    /** Design files directory */
+    designDir?: string;
+    /** Docs output directory */
+    docsDir?: string;
+    /** Specs output directory */
+    specsDir?: string;
+    /** Custom model definitions (Model instances or ModelDefinition objects) */
+    models?: any[];
+    /** Spec data entries from design/index.ts via mergeSpecs() */
+    specs?: SpecEntry[];
+    /** External SSOT configuration */
+    externalSsot?: {
+        openapi?: {
+            enabled: boolean;
+            paths: string[];
+        };
+        ddl?: {
+            enabled: boolean;
+            type: 'ddl' | 'prisma' | 'typeorm' | 'drizzle';
+            path: string;
+        };
+        iac?: {
+            enabled: boolean;
+            type: 'cloudformation' | 'cdk' | 'terraform';
+            path: string;
+        };
+    };
+    /** External SSOT file paths — maps node IDs to file paths/globs */
+    externalPaths?: Record<string, string>;
+    /** Lint configuration */
+    lint?: {
+        /** Strict mode */
+        strict?: boolean;
+        /** Disable specific rules */
+        disabledRules?: string[];
+    };
+    /** Artifact scan configurations keyed by artifact class (e.g. 'test', 'typescript', 'openapi') */
+    artifacts?: Record<string, ArtifactConfig>;
+}
+/**
+ * Resolved speckeeper configuration
+ */
+interface ResolvedSpeckeeperConfig extends SpeckeeperConfigInput {
+    designDir: string;
+    docsDir: string;
+    specsDir: string;
+}
+/**
+ * Define speckeeper configuration
+ *
+ * @example
+ * ```typescript
+ * // speckeeper.config.ts
+ * import { defineConfig, defineModel } from 'speckeeper';
+ *
+ * export default defineConfig({
+ *   projectName: 'My Project',
+ *   models: [
+ *     // Custom model definitions
+ *   ],
+ * });
+ * ```
+ */
+declare function defineConfig(input: SpeckeeperConfigInput): ResolvedSpeckeeperConfig;
+/**
+ * Model definition input type
+ */
+interface ModelDefinitionInput<T extends z.ZodTypeAny> {
+    /** Unique identifier for the model (kebab-case recommended) */
+    id: string;
+    /** Model name (PascalCase recommended) */
+    name: string;
+    /** Model description */
+    description: string;
+    /** Zod schema */
+    schema: T;
+    /** Prefix for ID generation */
+    idPrefix: string;
+    /** Exporter configuration */
+    exporters?: {
+        markdown?: MarkdownExporter<z.infer<T>>;
+        mermaid?: MermaidExporter<z.infer<T>> | MermaidExporter<z.infer<T>>[];
+        jsonSchema?: JsonSchemaExporter;
+    };
+    /** Lint rules */
+    lintRules?: LintRule$1<z.infer<T>>[];
+    /** External SSOT checker */
+    externalChecker?: ExternalChecker$1<z.infer<T>>;
+    /** Reference definitions */
+    references?: ReferenceDefinition[];
+    /** DSL function name */
+    dslName?: string;
+    /** Phase */
+    phase?: 'REQ' | 'HLD' | 'LLD' | 'OPS';
+}
+/**
+ * Create a custom model definition
+ *
+ * @example
+ * ```typescript
+ * const RetryPolicyModel = defineModel({
+ *   id: 'retry-policy',
+ *   name: 'RetryPolicy',
+ *   description: 'Retry policy definition',
+ *   schema: z.object({
+ *     id: z.string(),
+ *     name: z.string(),
+ *     maxAttempts: z.number().min(1),
+ *     initialDelay: z.number().min(0),
+ *     backoffMultiplier: z.number().min(1),
+ *   }),
+ *   idPrefix: 'RETRY',
+ *   exporters: {
+ *     markdown: {
+ *       single: (m) => `# ${m.name}\n\n- Max Attempts: ${m.maxAttempts}`,
+ *       outputDir: 'docs/retry-policies',
+ *     },
+ *   },
+ *   lintRules: [
+ *     {
+ *       id: 'retry-max-limit',
+ *       description: 'maxAttempts should not exceed 10',
+ *       severity: 'warning',
+ *       check: (m) => m.maxAttempts > 10
+ *         ? { message: `maxAttempts ${m.maxAttempts} exceeds recommended limit` }
+ *         : null,
+ *     },
+ *   ],
+ * });
+ * ```
+ */
+declare function defineModel<T extends z.ZodTypeAny>(input: ModelDefinitionInput<T>): ModelDefinition<T>;
+/**
+ * Helper to create Markdown exporter
+ */
+declare function createMarkdownExporter<T>(config: {
+    outputDir: string;
+    single: (model: T, context: unknown) => string;
+    index?: (models: T[], context: unknown) => string;
+    filename?: (model: T) => string;
+}): MarkdownExporter<T>;
+/**
+ * Helper to create Mermaid diagram exporter
+ */
+declare function createMermaidExporter<T>(config: {
+    diagramType: MermaidExporter<T>['diagramType'];
+    outputPath: string;
+    generate: (models: T[], context: unknown) => string;
+    title?: string;
+}): MermaidExporter<T>;
+/**
+ * Helper to create lint rule
+ */
+declare function createLintRule<T>(config: {
+    id: string;
+    description: string;
+    severity: 'error' | 'warning' | 'info';
+    check: (model: T, context: unknown) => {
+        message: string;
+        field?: string;
+        suggestion?: string;
+    } | null;
+}): LintRule$1<T>;
+/**
+ * Load speckeeper.config.ts file and register custom models
+ */
+declare function loadSpeckeeperConfig(configPath?: string): Promise<ResolvedSpeckeeperConfig | null>;
+
+export { detectCycles as $, type ArtifactConfig as A, type BaseModelInstance as B, type CheckContext as C, ReferenceDefinitionSchema as D, type ExportContext as E, type Relation as F, RelationSchema as G, type RelationValidationError as H, type InferModelType as I, type JsonSchemaExporter as J, RelationsFieldSchema as K, type LintContext as L, type ModelDefinition as M, type RenderContext as N, type Renderer as O, type ResolvedSpeckeeperConfig as P, type SpecModule as Q, RELATION_CONSTRAINTS as R, type SpecEntry as S, type SpeckeeperConfigInput as T, buildRegistryFromConfig as U, createLintRule as V, createMarkdownExporter as W, createMermaidExporter as X, defineConfig as Y, defineModel as Z, defineSpecs as _, type CheckResult$1 as a, findModelTypeFromConfig as a0, getLevelIndex as a1, getSpecsFromConfig as a2, inferModelIdFromSpecId as a3, loadSpeckeeperConfig as a4, mergeSpecs as a5, validateRelationLevel as a6, type MetaModelRegistry as b, type LintRule$1 as c, type LintIssue as d, type CheckError as e, CheckErrorSchema as f, type CheckResult as g, CheckResultSchema as h, type CheckWarning as i, CheckWarningSchema as j, type CoverageChecker as k, type CoverageResult as l, type Exporter as m, type ExternalChecker as n, LintIssueSchema as o, type LintResult as p, type LintRule as q, type MarkdownExporter as r, type MergedDesign as s, type MermaidExporter as t, type MetaModelConfig as u, Model as v, type ModelDefinitionInput as w, type ModelLevel as x, RELATION_TYPES as y, type ReferenceDefinition as z };