speckeeper 0.8.1 → 0.9.1

package/dist/{config-api-U2pt1aHJ.d.ts → config-api-CfxXt9Zt.d.ts}

@@ -511,6 +511,56 @@ interface CheckResult {
         relationType: 'verifiedBy' | 'implements' | 'traces';
     }>;
 }
+/** OpenAPI deep validation mapping */
+interface OpenAPIValidationMapping {
+    path: string;
+    method?: string;
+    parameters?: Array<{
+        name: string;
+        in?: string;
+        type?: string;
+    }>;
+    responseProperties?: Array<{
+        name: string;
+        type?: string;
+    }>;
+}
+/** DDL deep validation mapping */
+interface DDLValidationMapping {
+    tableName: string;
+    columns?: Array<{
+        name: string;
+        type?: string;
+    }>;
+    checkTypes?: boolean;
+}
+/**
+ * Deep validation rule for a specific source type.
+ * The mapper extracts expected structure from a spec for detailed comparison
+ * against the matched source object.
+ */
+interface DeepValidationRule<T, TMapping = unknown> {
+    mapper: (spec: T) => TMapping;
+}
+/**
+ * Deep validation configuration keyed by source type.
+ * Models define this to enable Level 2/3 checks beyond existence.
+ */
+interface DeepValidationConfig<T> {
+    openapi?: DeepValidationRule<T, OpenAPIValidationMapping>;
+    ddl?: DeepValidationRule<T, DDLValidationMapping>;
+    [sourceType: string]: DeepValidationRule<T, unknown> | undefined;
+}
+/**
+ * Lookup key configuration keyed by source type.
+ * When a model's spec ID differs from the external identifier
+ * (e.g. entity ID "user" vs DDL table name "users"),
+ * define a mapper per source type to derive the external key.
+ * If not defined for a source type, spec.id is used as-is.
+ */
+interface LookupKeyConfig<T> {
+    [sourceType: string]: ((spec: T) => string) | undefined;
+}
 /**
  * Coverage result
  */
@@ -604,8 +654,12 @@ declare abstract class Model<TSchema extends ZodType> {
     protected lintRules: LintRule<z.infer<TSchema>>[];
     /** Exporters (override in subclass) */
     protected exporters: Exporter<z.infer<TSchema>>[];
-    /** External checker (optional) */
+    /** External checker (optional) — deprecated, use deepValidation instead */
     protected externalChecker?: ExternalChecker<z.infer<TSchema>>;
+    /** Deep validation rules keyed by source type (replaces externalChecker) */
+    protected deepValidation?: DeepValidationConfig<z.infer<TSchema>>;
+    /** Lookup key overrides per source type (when spec ID differs from external identifier) */
+    protected lookupKeys?: LookupKeyConfig<z.infer<TSchema>>;
     /** Coverage checker (optional) */
     protected coverageChecker?: CoverageChecker<z.infer<TSchema>>;
     /** Model level (set in _models/) */
@@ -683,6 +737,19 @@ declare abstract class Model<TSchema extends ZodType> {
      * Get coverage checker
      */
     getCoverageChecker(): CoverageChecker<z.infer<TSchema>> | undefined;
+    /**
+     * Get deep validation config
+     */
+    getDeepValidation(): DeepValidationConfig<z.infer<TSchema>> | undefined;
+    /**
+     * Get lookup key config
+     */
+    getLookupKeys(): LookupKeyConfig<z.infer<TSchema>> | undefined;
+    /**
+     * Resolve the lookup key for a spec and source type.
+     * Returns the lookup key if an override is defined, otherwise spec.id.
+     */
+    resolveLookupKey(spec: z.infer<TSchema>, sourceType: string): string;
     /**
      * Get lint rules
      */
@@ -791,6 +858,45 @@ interface ArtifactConfig {
     /** Content search patterns (RegExp). First capture group = spec IDs (comma or space separated) */
     contentPatterns?: RegExp[];
 }
+/** A single match found by a source scanner */
+interface SourceMatch {
+    /** Matched spec ID */
+    specId: string;
+    /** Match location description (path key, table name, file:line, etc.) */
+    location: string;
+    /** Parsed object context for deep validation (e.g. OpenAPI operation, DDL table) */
+    context?: unknown;
+}
+/**
+ * Source scanner plugin interface.
+ * Built-in scanners exist for 'openapi', 'ddl', and 'annotation'.
+ * Users can provide custom scanners for additional file types.
+ */
+interface SourceScanner {
+    /**
+     * Search for spec IDs in a parsed document or raw content.
+     * @param content - Parsed document (object for openapi/ddl) or raw string
+     * @param specIds - Set of all known spec IDs to search for
+     * @param filePath - Path to the source file being scanned
+     * @returns Array of matches found
+     */
+    findSpecIds(content: unknown, specIds: string[], filePath: string): SourceMatch[];
+}
+/** Source configuration for global scan */
+interface SourceConfig {
+    /** Source type identifier. Built-in: 'openapi', 'ddl', 'annotation' */
+    type: string;
+    /** File path glob patterns to scan */
+    paths: string[];
+    /** Exclusion patterns */
+    exclude?: string[];
+    /** Relation type: how matches relate to specs */
+    relation: 'implements' | 'verifiedBy';
+    /** Content search patterns (for annotation type) */
+    contentPatterns?: RegExp[];
+    /** Custom scanner plugin (required when type is not a built-in) */
+    scanner?: SourceScanner;
+}
 /**
  * speckeeper configuration type
  */
@@ -837,6 +943,8 @@ interface SpeckeeperConfigInput {
     };
     /** Artifact scan configurations keyed by artifact class (e.g. 'test', 'typescript', 'openapi') */
     artifacts?: Record<string, ArtifactConfig>;
+    /** Global source definitions for spec ID scanning */
+    sources?: SourceConfig[];
 }
 /**
  * Resolved speckeeper configuration
@@ -967,4 +1075,4 @@ declare function createLintRule<T>(config: {
  */
 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 };
+export { type SpeckeeperConfigInput as $, type ArtifactConfig as A, type BaseModelInstance as B, type CheckContext as C, type DDLValidationMapping as D, type ExportContext as E, type ModelDefinitionInput as F, type ModelLevel as G, RELATION_TYPES as H, type InferModelType as I, type JsonSchemaExporter as J, type ReferenceDefinition as K, type LintContext as L, type ModelDefinition as M, ReferenceDefinitionSchema as N, type OpenAPIValidationMapping as O, type Relation as P, RelationSchema as Q, RELATION_CONSTRAINTS as R, type SourceConfig as S, type RelationValidationError as T, RelationsFieldSchema as U, type RenderContext as V, type Renderer as W, type ResolvedSpeckeeperConfig as X, type SourceMatch as Y, type SourceScanner as Z, type SpecModule as _, type CheckResult$1 as a, buildRegistryFromConfig as a0, createLintRule as a1, createMarkdownExporter as a2, createMermaidExporter as a3, defineConfig as a4, defineModel as a5, defineSpecs as a6, detectCycles as a7, findModelTypeFromConfig as a8, getLevelIndex as a9, getSpecsFromConfig as aa, inferModelIdFromSpecId as ab, loadSpeckeeperConfig as ac, mergeSpecs as ad, validateRelationLevel as ae, type MetaModelRegistry as b, type LintRule$1 as c, type LintIssue as d, type SpecEntry as e, type CheckError as f, CheckErrorSchema as g, type CheckResult as h, CheckResultSchema as i, type CheckWarning as j, CheckWarningSchema as k, type CoverageChecker as l, type CoverageResult as m, type DeepValidationConfig as n, type DeepValidationRule as o, type Exporter as p, type ExternalChecker as q, LintIssueSchema as r, type LintResult as s, type LintRule as t, type LookupKeyConfig as u, type MarkdownExporter as v, type MergedDesign as w, type MermaidExporter as x, type MetaModelConfig as y, Model as z };

package/dist/dsl/index.d.ts

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { q as LintRule, m as Exporter, n as ExternalChecker, k as CoverageChecker, A as ArtifactConfig } from '../config-api-U2pt1aHJ.js';
+import { t as LintRule, p as Exporter, l as CoverageChecker, A as ArtifactConfig, Y as SourceMatch, Z as SourceScanner, n as DeepValidationConfig, h as CheckResult, S as SourceConfig } from '../config-api-CfxXt9Zt.js';
 
 /**
  * Core DSL — Base spec schema
@@ -116,37 +116,9 @@ declare function markdownExporter<T extends {
     id: string;
 }>(config: MarkdownExporterConfig<T>): Exporter<T>;
 
-interface TestCheckerConfig<T> {
-    sourcePath?: (spec: T) => string;
-}
-/**
- * Creates an ExternalChecker that verifies test file existence and spec ID references.
- */
-declare function testChecker<T extends {
-    id: string;
-}>(config?: TestCheckerConfig<T>): ExternalChecker<T>;
 type AnnotationRelationType = 'verifiedBy' | 'implements' | 'traces';
-interface AnnotationCheckEntry {
-    artifact: string;
-    relationType: AnnotationRelationType;
-    contentPatterns?: RegExp[];
-    checker?: ExternalChecker<{
-        id: string;
-    }>;
-}
-interface AnnotationCheckerConfig<_T extends {
-    id: string;
-}> {
-    artifact?: string;
-    relationType?: AnnotationRelationType;
-    checks?: AnnotationCheckEntry[];
-    contentPatterns?: RegExp[];
-}
 declare function setArtifactsConfig(config: Record<string, ArtifactConfig>): void;
 declare function getArtifactsConfig(): Record<string, ArtifactConfig> | undefined;
-declare function annotationChecker<T extends {
-    id: string;
-}>(config?: AnnotationCheckerConfig<T>): ExternalChecker<T>;
 interface AnnotationCoverageConfig {
     artifact: string;
     relationType: AnnotationRelationType;
@@ -156,64 +128,12 @@ interface AnnotationCoverageConfig {
 declare function annotationCoverage<T extends {
     id: string;
 }>(config: AnnotationCoverageConfig): CoverageChecker<T>;
-interface OpenAPICheckerConfig<T> {
-    sourcePath?: (spec: T) => string;
-    mapper: (spec: T) => {
-        path: string;
-        method?: string;
-        parameters?: Array<{
-            name: string;
-            in?: string;
-            type?: string;
-        }>;
-        responseProperties?: Array<{
-            name: string;
-            type?: string;
-        }>;
-    };
-}
-/**
- * Creates an ExternalChecker that verifies consistency with an OpenAPI spec file.
- *
- * Three validation levels:
- * 1. Existence: spec ID found in operationId, path segment, schema name, or x-spec-id
- * 2. Structural: HTTP method matches the matched path
- * 3. Type: parameter/response property names and types match
- */
-declare function externalOpenAPIChecker<T extends {
-    id: string;
-}>(config?: OpenAPICheckerConfig<T>): ExternalChecker<T>;
-interface SqlSchemaCheckerConfig<T> {
-    sourcePath?: (spec: T) => string;
-    mapper: (spec: T) => {
-        tableName: string;
-        columns?: Array<{
-            name: string;
-            type?: string;
-        }>;
-    };
-    checkTypes?: boolean;
-}
-/**
- * Creates an ExternalChecker that verifies consistency with a SQL schema (DDL).
- *
- * Three validation levels:
- * 1. Existence: table name found in DDL
- * 2. Structural: column names exist in the DDL table
- * 3. Type: column types use containment-based comparison
- */
-declare function externalSqlSchemaChecker<T extends {
-    id: string;
-}>(config?: SqlSchemaCheckerConfig<T>): ExternalChecker<T>;
 interface RelationCoverageConfig {
     targetModel: string;
     description: string;
     relationType?: string;
     targetPrefix?: string;
 }
-/**
- * Creates a CoverageChecker that computes coverage of a target model via relations.
- */
 declare function relationCoverage<T extends {
     id: string;
     relations?: Array<{
@@ -281,4 +201,52 @@ declare const VerifiedByRelationSchema: z.ZodObject<{
 }>;
 type VerifiedByRelation = z.infer<typeof VerifiedByRelationSchema>;
 
-export { type AnnotationCheckEntry, type AnnotationCheckerConfig, type AnnotationCoverageConfig, type BaseSpec, type ImplementsRelation, ImplementsRelationSchema, type MarkdownExporterConfig, type VerifiedByRelation, VerifiedByRelationSchema, annotationChecker, annotationCoverage, arrayMinLength, baseSpecSchema, childIdFormat, externalOpenAPIChecker, externalSqlSchemaChecker, getArtifactsConfig, idFormat, isTypeContainedBy, markdownExporter, relationCoverage, requireField, setArtifactsConfig, testChecker };
+interface GlobalScanMatch extends SourceMatch {
+    /** Which source config produced this match */
+    sourceType: string;
+    /** Relation type from the source config */
+    relation: 'implements' | 'verifiedBy';
+    /** File path where the match was found */
+    filePath: string;
+}
+type GlobalScanResult = Map<string, GlobalScanMatch[]>;
+declare const openapiScanner: SourceScanner;
+declare const ddlScanner: SourceScanner;
+declare const annotationScanner: SourceScanner;
+/**
+ * Create an annotation scanner with custom content patterns.
+ */
+declare function createAnnotationScanner(contentPatterns: RegExp[]): SourceScanner;
+interface ScanWarning {
+    message: string;
+    sourceType: string;
+    filePath?: string;
+}
+interface GlobalScanOutput {
+    matches: GlobalScanResult;
+    warnings: ScanWarning[];
+}
+/**
+ * Lookup key map: specId -> Record<sourceType, lookupKey>.
+ * When a model's spec ID differs from the external identifier
+ * (e.g. entity "user" vs DDL table "users"), the check command
+ * builds this map so the scanner searches for the correct key.
+ */
+type LookupKeyMap = Map<string, Record<string, string>>;
+/**
+ * Run global scan across all configured sources.
+ * Returns a map of specId -> matches for all spec IDs found.
+ *
+ * @param sources - Source configurations to scan
+ * @param specIds - All known spec IDs
+ * @param basePath - Base directory for resolving file paths
+ * @param lookupKeyMap - Optional per-spec, per-source-type key overrides
+ */
+declare function runGlobalScan(sources: SourceConfig[], specIds: string[], basePath?: string, lookupKeyMap?: LookupKeyMap): GlobalScanOutput;
+/**
+ * Run deep validation for a spec against its matched sources.
+ * Uses the model's deepValidation config to perform Level 2/3 checks.
+ */
+declare function runDeepValidation(specId: string, matches: GlobalScanMatch[], deepValidation: DeepValidationConfig<any>, spec: unknown): CheckResult;
+
+export { type AnnotationCoverageConfig, type BaseSpec, type GlobalScanMatch, type GlobalScanOutput, type GlobalScanResult, type ImplementsRelation, ImplementsRelationSchema, type LookupKeyMap, type MarkdownExporterConfig, type ScanWarning, type VerifiedByRelation, VerifiedByRelationSchema, annotationCoverage, annotationScanner, arrayMinLength, baseSpecSchema, childIdFormat, createAnnotationScanner, ddlScanner, getArtifactsConfig, idFormat, isTypeContainedBy, markdownExporter, openapiScanner, relationCoverage, requireField, runDeepValidation, runGlobalScan, setArtifactsConfig };