speckeeper 0.8.0 → 0.9.0

package/dist/{config-api-Bh0zX8W7.d.ts → config-api-BDl4otlv.d.ts}

@@ -474,7 +474,10 @@ interface Exporter<T> {
     format: 'markdown' | 'json' | 'mermaid';
     single?: (spec: T) => string;
     index?: (specs: T[]) => string;
+    /** Subdirectory under docsDir (used with single + index/index.md) */
     outputDir?: string;
+    /** Direct output file path relative to docsDir (used with index-only exporters) */
+    outputFile?: string;
     filename?: (spec: T) => string;
 }
 /**
@@ -508,6 +511,46 @@ 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;
+}
 /**
  * Coverage result
  */
@@ -601,8 +644,10 @@ 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>>;
     /** Coverage checker (optional) */
     protected coverageChecker?: CoverageChecker<z.infer<TSchema>>;
     /** Model level (set in _models/) */
@@ -680,6 +725,10 @@ 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 lint rules
      */
@@ -788,6 +837,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
  */
@@ -834,6 +922,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
@@ -964,4 +1054,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 { defineConfig as $, type ArtifactConfig as A, type BaseModelInstance as B, type CheckContext as C, type ReferenceDefinition as D, type ExportContext as E, ReferenceDefinitionSchema as F, type Relation as G, RelationSchema as H, type InferModelType as I, type JsonSchemaExporter as J, type RelationValidationError as K, type LintContext as L, type ModelDefinition as M, RelationsFieldSchema as N, type RenderContext as O, type Renderer as P, type ResolvedSpeckeeperConfig as Q, RELATION_CONSTRAINTS as R, type SourceConfig as S, type SourceMatch as T, type SourceScanner as U, type SpecModule as V, type SpeckeeperConfigInput as W, buildRegistryFromConfig as X, createLintRule as Y, createMarkdownExporter as Z, createMermaidExporter as _, type CheckResult$1 as a, defineModel as a0, defineSpecs as a1, detectCycles as a2, findModelTypeFromConfig as a3, getLevelIndex as a4, getSpecsFromConfig as a5, inferModelIdFromSpecId as a6, loadSpeckeeperConfig as a7, mergeSpecs as a8, validateRelationLevel as a9, type DeepValidationConfig as aa, 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 Exporter as n, type ExternalChecker as o, LintIssueSchema as p, type LintResult as q, type LintRule as r, type MarkdownExporter as s, type MergedDesign as t, type MermaidExporter as u, type MetaModelConfig as v, Model as w, type ModelDefinitionInput as x, type ModelLevel as y, RELATION_TYPES 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-Bh0zX8W7.js';
+import { r as LintRule, n as Exporter, l as CoverageChecker, A as ArtifactConfig, T as SourceMatch, U as SourceScanner, aa as DeepValidationConfig, h as CheckResult, S as SourceConfig } from '../config-api-BDl4otlv.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,40 @@ 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[];
+}
+/**
+ * Run global scan across all configured sources.
+ * Returns a map of specId -> matches for all spec IDs found.
+ */
+declare function runGlobalScan(sources: SourceConfig[], specIds: string[], basePath?: string): 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 MarkdownExporterConfig, type ScanWarning, type VerifiedByRelation, VerifiedByRelationSchema, annotationCoverage, annotationScanner, arrayMinLength, baseSpecSchema, childIdFormat, createAnnotationScanner, ddlScanner, getArtifactsConfig, idFormat, isTypeContainedBy, markdownExporter, openapiScanner, relationCoverage, requireField, runDeepValidation, runGlobalScan, setArtifactsConfig };