speckeeper 0.4.2 → 0.6.0

package/dist/model-2gVdKS3_.d.ts

@@ -0,0 +1,448 @@
+import { z, ZodType } from 'zod';
+
+/**
+ * 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;
+    }[];
+}
+/**
+ * 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;
+
+export { type CheckResult as C, type Exporter as E, type LintResult as L, type MergedDesign as M, RELATION_CONSTRAINTS as R, type SpecEntry as S, type CoverageChecker as a, type CoverageResult as b, type ExternalChecker as c, type LintRule as d, Model as e, type ModelLevel as f, RELATION_TYPES as g, type Relation as h, RelationSchema as i, type RelationValidationError as j, RelationsFieldSchema as k, type RenderContext as l, type Renderer as m, type SpecModule as n, buildRegistryFromConfig as o, defineSpecs as p, detectCycles as q, findModelTypeFromConfig as r, getLevelIndex as s, getSpecsFromConfig as t, inferModelIdFromSpecId as u, mergeSpecs as v, validateRelationLevel as w };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "speckeeper",
-  "version": "0.4.2",
+  "version": "0.6.0",
   "description": "TypeScript-first specification validation framework with external SSOT integration",
   "type": "module",
   "main": "./dist/index.js",
@@ -61,6 +61,7 @@
     "commander": "^12.1.0",
     "embedoc": "^0.10.1",
     "glob": "^10.3.10",
+    "node-sql-parser": "^5.4.0",
     "tsx": "^4.21.0",
     "yaml": "^2.3.4",
     "zod": "^3.22.4"
@@ -68,6 +69,7 @@
   "devDependencies": {
     "@eslint/js": "^9.39.2",
     "@types/node": "^20.11.0",
+    "@types/node-sql-parser": "^1.0.0",
     "@typescript-eslint/eslint-plugin": "^8.54.0",
     "@typescript-eslint/parser": "^8.54.0",
     "@vitest/coverage-v8": "^1.6.1",