@ipation/specbridge 1.2.1 → 2.0.0

package/dist/index.d.ts

@@ -33,6 +33,22 @@ interface DecisionContent {
     context?: string;
     consequences?: string[];
 }
+/**
+ * Exception to a constraint
+ */
+interface ConstraintException {
+    pattern: string;
+    reason: string;
+    approvedBy?: string;
+    expiresAt?: string;
+}
+/**
+ * Structured verifier check specification
+ */
+interface ConstraintCheck {
+    verifier: string;
+    params?: Record<string, unknown>;
+}
 /**
  * A single constraint within a decision
  */
@@ -43,18 +59,10 @@ interface Constraint {
     severity: Severity;
     scope: string;
     verifier?: string;
+    check?: ConstraintCheck;
     autofix?: boolean;
     exceptions?: ConstraintException[];
 }
-/**
- * Exception to a constraint
- */
-interface ConstraintException {
-    pattern: string;
-    reason: string;
-    approvedBy?: string;
-    expiresAt?: string;
-}
 /**
  * Automated verification configuration
  */
@@ -167,6 +175,27 @@ interface LevelConfig {
     timeout?: number;
     severity?: Severity[];
 }
+/**
+ * Warning during verification (non-blocking)
+ */
+interface VerificationWarning {
+    type: 'missing_verifier' | 'invalid_pattern' | 'other';
+    message: string;
+    decisionId: string;
+    constraintId: string;
+    file?: string;
+}
+/**
+ * Error during verification (continued after error)
+ */
+interface VerificationIssue {
+    type: 'verifier_exception' | 'file_read_error' | 'other';
+    message: string;
+    decisionId?: string;
+    constraintId?: string;
+    file?: string;
+    stack?: string;
+}
 /**
  * Result of a verification run
  */
@@ -178,6 +207,8 @@ interface VerificationResult {
     failed: number;
     skipped: number;
     duration: number;
+    warnings?: VerificationWarning[];
+    errors?: VerificationIssue[];
 }
 /**
  * Result of an inference run
@@ -219,6 +250,17 @@ interface DecisionCompliance {
     constraints: number;
     violations: number;
     compliance: number;
+    /** Breakdown of violations by severity (v2.0+) */
+    violationsBySeverity?: {
+        critical: number;
+        high: number;
+        medium: number;
+        low: number;
+    };
+    /** Raw weighted score before coverage penalty (v2.0+) */
+    weightedScore?: number;
+    /** Ratio of violations to constraints (v2.0+) */
+    coverageRate?: number;
 }
 /**
  * Trend data point
@@ -350,6 +392,16 @@ declare const ConstraintExceptionSchema: z.ZodObject<{
     approvedBy?: string | undefined;
     expiresAt?: string | undefined;
 }>;
+declare const ConstraintCheckSchema: z.ZodObject<{
+    verifier: z.ZodString;
+    params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    verifier: string;
+    params?: Record<string, unknown> | undefined;
+}, {
+    verifier: string;
+    params?: Record<string, unknown> | undefined;
+}>;
 declare const ConstraintSchema: z.ZodObject<{
     id: z.ZodString;
     type: z.ZodEnum<["invariant", "convention", "guideline"]>;
@@ -357,6 +409,16 @@ declare const ConstraintSchema: z.ZodObject<{
     severity: z.ZodEnum<["critical", "high", "medium", "low"]>;
     scope: z.ZodString;
     verifier: z.ZodOptional<z.ZodString>;
+    check: z.ZodOptional<z.ZodObject<{
+        verifier: z.ZodString;
+        params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, "strip", z.ZodTypeAny, {
+        verifier: string;
+        params?: Record<string, unknown> | undefined;
+    }, {
+        verifier: string;
+        params?: Record<string, unknown> | undefined;
+    }>>;
     autofix: z.ZodOptional<z.ZodBoolean>;
     exceptions: z.ZodOptional<z.ZodArray<z.ZodObject<{
         pattern: z.ZodString;
@@ -381,6 +443,10 @@ declare const ConstraintSchema: z.ZodObject<{
     severity: "critical" | "high" | "medium" | "low";
     scope: string;
     verifier?: string | undefined;
+    check?: {
+        verifier: string;
+        params?: Record<string, unknown> | undefined;
+    } | undefined;
     autofix?: boolean | undefined;
     exceptions?: {
         pattern: string;
@@ -395,6 +461,10 @@ declare const ConstraintSchema: z.ZodObject<{
     severity: "critical" | "high" | "medium" | "low";
     scope: string;
     verifier?: string | undefined;
+    check?: {
+        verifier: string;
+        params?: Record<string, unknown> | undefined;
+    } | undefined;
     autofix?: boolean | undefined;
     exceptions?: {
         pattern: string;
@@ -485,6 +555,16 @@ declare const DecisionSchema: z.ZodObject<{
         severity: z.ZodEnum<["critical", "high", "medium", "low"]>;
         scope: z.ZodString;
         verifier: z.ZodOptional<z.ZodString>;
+        check: z.ZodOptional<z.ZodObject<{
+            verifier: z.ZodString;
+            params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        }, "strip", z.ZodTypeAny, {
+            verifier: string;
+            params?: Record<string, unknown> | undefined;
+        }, {
+            verifier: string;
+            params?: Record<string, unknown> | undefined;
+        }>>;
         autofix: z.ZodOptional<z.ZodBoolean>;
         exceptions: z.ZodOptional<z.ZodArray<z.ZodObject<{
             pattern: z.ZodString;
@@ -509,6 +589,10 @@ declare const DecisionSchema: z.ZodObject<{
         severity: "critical" | "high" | "medium" | "low";
         scope: string;
         verifier?: string | undefined;
+        check?: {
+            verifier: string;
+            params?: Record<string, unknown> | undefined;
+        } | undefined;
         autofix?: boolean | undefined;
         exceptions?: {
             pattern: string;
@@ -523,6 +607,10 @@ declare const DecisionSchema: z.ZodObject<{
         severity: "critical" | "high" | "medium" | "low";
         scope: string;
         verifier?: string | undefined;
+        check?: {
+            verifier: string;
+            params?: Record<string, unknown> | undefined;
+        } | undefined;
         autofix?: boolean | undefined;
         exceptions?: {
             pattern: string;
@@ -601,6 +689,10 @@ declare const DecisionSchema: z.ZodObject<{
         severity: "critical" | "high" | "medium" | "low";
         scope: string;
         verifier?: string | undefined;
+        check?: {
+            verifier: string;
+            params?: Record<string, unknown> | undefined;
+        } | undefined;
         autofix?: boolean | undefined;
         exceptions?: {
             pattern: string;
@@ -647,6 +739,10 @@ declare const DecisionSchema: z.ZodObject<{
         severity: "critical" | "high" | "medium" | "low";
         scope: string;
         verifier?: string | undefined;
+        check?: {
+            verifier: string;
+            params?: Record<string, unknown> | undefined;
+        } | undefined;
         autofix?: boolean | undefined;
         exceptions?: {
             pattern: string;
@@ -676,6 +772,7 @@ type VerificationFrequencySchema_ = z.infer<typeof VerificationFrequencySchema>;
 type DecisionMetadataSchema_ = z.infer<typeof DecisionMetadataSchema>;
 type DecisionContentSchema_ = z.infer<typeof DecisionContentSchema>;
 type ConstraintExceptionSchema_ = z.infer<typeof ConstraintExceptionSchema>;
+type ConstraintCheckSchema_ = z.infer<typeof ConstraintCheckSchema>;
 type ConstraintSchema_ = z.infer<typeof ConstraintSchema>;
 type VerificationConfigSchema_ = z.infer<typeof VerificationConfigSchema>;
 type DecisionTypeSchema = z.infer<typeof DecisionSchema>;
@@ -1378,6 +1475,45 @@ declare function getAnalyzer(id: string): Analyzer | null;
  */
 declare function getAnalyzerIds(): string[];
 
+/**
+ * Entry in the explanation trace
+ */
+interface ExplanationEntry {
+    file: string;
+    decision: Decision;
+    constraint: Constraint;
+    applied: boolean;
+    reason: string;
+    selectedVerifier?: string;
+    verifierOutput?: {
+        violations: number;
+        duration: number;
+        error?: string;
+    };
+}
+/**
+ * Reporter for --explain mode
+ */
+declare class ExplainReporter {
+    private entries;
+    /**
+     * Add an entry to the explanation trace
+     */
+    add(entry: ExplanationEntry): void;
+    /**
+     * Print the explanation trace
+     */
+    print(): void;
+    /**
+     * Get all entries
+     */
+    getEntries(): ExplanationEntry[];
+    /**
+     * Clear all entries
+     */
+    clear(): void;
+}
+
 interface VerificationOptions {
     level?: VerificationLevel;
     files?: string[];
@@ -1385,6 +1521,7 @@ interface VerificationOptions {
     severity?: Severity[];
     timeout?: number;
     cwd?: string;
+    reporter?: ExplainReporter;
 }
 /**
  * Verification Engine class
@@ -1393,6 +1530,8 @@ declare class VerificationEngine {
     private registry;
     private project;
     private astCache;
+    private resultsCache;
+    private pluginsLoaded;
     constructor(registry?: Registry);
     /**
      * Run verification
@@ -1401,7 +1540,11 @@ declare class VerificationEngine {
     /**
      * Verify a single file
      */
-    verifyFile(filePath: string, decisions: Decision[], severityFilter?: Severity[], cwd?: string): Promise<Violation[]>;
+    verifyFile(filePath: string, decisions: Decision[], severityFilter?: Severity[], cwd?: string, reporter?: ExplainReporter): Promise<{
+        violations: Violation[];
+        warnings: VerificationWarning[];
+        errors: VerificationIssue[];
+    }>;
     /**
      * Verify multiple files
      */
@@ -1420,6 +1563,10 @@ declare class AstCache {
     private cache;
     get(filePath: string, project: Project): Promise<SourceFile | null>;
     clear(): void;
+    getStats(): {
+        entries: number;
+        memoryEstimate: number;
+    };
 }
 
 declare function getChangedFiles(cwd: string): Promise<string[]>;
@@ -1470,6 +1617,60 @@ interface Verifier {
      */
     verify(ctx: VerificationContext): Promise<Violation[]>;
 }
+/**
+ * Plugin metadata
+ */
+interface VerifierPluginMetadata {
+    /** Unique identifier matching /^[a-z][a-z0-9-]*$/ */
+    id: string;
+    /** Semver version string */
+    version: string;
+    /** Plugin author */
+    author?: string;
+    /** Brief description of what this verifier checks */
+    description?: string;
+}
+/**
+ * Verifier plugin interface
+ * Custom verifiers must export a default object implementing this interface
+ */
+interface VerifierPlugin {
+    /** Plugin metadata */
+    metadata: VerifierPluginMetadata;
+    /** Factory function that creates a new verifier instance */
+    createVerifier: () => Verifier;
+    /** Optional Zod schema for validating constraint.check.params */
+    paramsSchema?: unknown;
+}
+/**
+ * Helper to define a verifier plugin with type safety
+ *
+ * @example
+ * ```typescript
+ * import { defineVerifierPlugin, type Verifier } from '@ipation/specbridge';
+ *
+ * class MyVerifier implements Verifier {
+ *   readonly id = 'my-custom';
+ *   readonly name = 'My Custom Verifier';
+ *   readonly description = 'Checks custom patterns';
+ *
+ *   async verify(ctx) {
+ *     // Implementation
+ *     return [];
+ *   }
+ * }
+ *
+ * export default defineVerifierPlugin({
+ *   metadata: {
+ *     id: 'my-custom',
+ *     version: '1.0.0',
+ *     author: 'Your Name'
+ *   },
+ *   createVerifier: () => new MyVerifier()
+ * });
+ * ```
+ */
+declare function defineVerifierPlugin(plugin: VerifierPlugin): VerifierPlugin;
 /**
  * Helper to create a violation
  */
@@ -1566,16 +1767,25 @@ declare class ApiVerifier implements Verifier {
 declare const builtinVerifiers: Record<string, () => Verifier>;
 /**
  * Get verifier by ID
+ * Checks custom plugins first, then built-in verifiers
+ * Instances are pooled for performance
  */
 declare function getVerifier(id: string): Verifier | null;
 /**
- * Get all verifier IDs
+ * Get all verifier IDs (built-in + plugins)
  */
 declare function getVerifierIds(): string[];
 /**
- * Select appropriate verifier based on constraint rule
+ * Clear the verifier instance pool (for testing)
+ */
+declare function clearVerifierPool(): void;
+/**
+ * Select appropriate verifier based on constraint
  */
-declare function selectVerifierForConstraint(rule: string, specifiedVerifier?: string): Verifier | null;
+declare function selectVerifierForConstraint(rule: string, specifiedVerifier?: string, check?: {
+    verifier: string;
+    params?: Record<string, unknown>;
+}): Verifier | null;
 
 interface AutofixPatch {
     filePath: string;
@@ -1670,6 +1880,8 @@ declare function createPropagationEngine(registry?: Registry): PropagationEngine
 interface ReportOptions {
     includeAll?: boolean;
     cwd?: string;
+    /** Use v1.3 compliance formula instead of v2.0 severity-weighted formula */
+    legacyCompliance?: boolean;
 }
 /**
  * Generate a compliance report
@@ -1738,6 +1950,7 @@ declare class ReportStorage {
     loadLatest(): Promise<StoredReport | null>;
     /**
      * Load historical reports for the specified number of days
+     * Uses parallel I/O for better performance
      */
     loadHistory(days?: number): Promise<StoredReport[]>;
     /**
@@ -2020,4 +2233,4 @@ declare function matchesAnyPattern(filePath: string, patterns: string[], options
     cwd?: string;
 }): boolean;
 
-export { type AffectedFile, type AgentContext, AgentContextGenerator, AlreadyInitializedError, type Analyzer, AnalyzerNotFoundError, ApiVerifier, type ApplicableConstraint, type ApplicableDecision, AstCache, AutofixEngine, type AutofixPatch, type AutofixResult, CodeScanner, ComplexityVerifier, type ComplianceReport, ConfigError, type Constraint, type ConstraintException, ConstraintExceptionSchema, type ConstraintExceptionSchema_, ConstraintSchema, type ConstraintSchema_, type ConstraintType, ConstraintTypeSchema, type ConstraintTypeSchema_, type ContextOptions, type Decision, type DecisionCompliance, type DecisionContent, DecisionContentSchema, type DecisionContentSchema_, type DecisionFilter, type DecisionMetadata, DecisionMetadataSchema, type DecisionMetadataSchema_, DecisionNotFoundError, DecisionSchema, type DecisionStatus, DecisionStatusSchema, type DecisionStatusSchema_, type DecisionTypeSchema, DecisionValidationError, type DependencyGraph, DependencyVerifier, type DriftAnalysis, ErrorsAnalyzer, ErrorsVerifier, FileSystemError, type GlobOptions, type GraphNode, HookError, type ImpactAnalysis, ImportsAnalyzer, ImportsVerifier, InferenceEngine, InferenceError, type InferenceOptions, type InferenceResult, type LevelConfig, LinksSchema, type LoadError, type LoadResult, type LoadedDecision, type McpServerOptions, type MigrationStep, NamingAnalyzer, NamingVerifier, NotInitializedError, type OverallDrift, type Pattern, type PatternExample, type PromptTemplate, PropagationEngine, type PropagationOptions, RegexVerifier, Registry, type RegistryConstraintMatch, RegistryError, type RegistryOptions, type ReportOptions, ReportStorage, Reporter, type ScanOptions, type ScanResult, type ScannedFile, SecurityVerifier, type Severity, SeveritySchema, type SeveritySchema_, type SpecBridgeConfig, SpecBridgeConfigSchema, type SpecBridgeConfigType, SpecBridgeError, SpecBridgeMcpServer, type StoredReport, StructureAnalyzer, type TextEdit, type TrendAnalysis, type TrendData, type TrendDirection, type VerificationConfig, VerificationConfigSchema, type VerificationConfigSchema_, type VerificationContext, VerificationEngine, VerificationError, type VerificationFrequency, VerificationFrequencySchema, type VerificationFrequencySchema_, type VerificationLevel, type VerificationOptions, type VerificationResult, type Verifier, VerifierNotFoundError, type Violation, type ViolationFix, analyzeTrend, buildDependencyGraph, builtinAnalyzers, builtinVerifiers, calculateConfidence, checkDegradation, createInferenceEngine, createPattern, createPropagationEngine, createRegistry, createScannerFromConfig, createVerificationEngine, createViolation, defaultConfig, detectDrift, ensureDir, extractSnippet, formatConsoleReport, formatContextAsJson, formatContextAsMarkdown, formatContextAsMcp, formatError, formatMarkdownReport, formatValidationErrors, generateContext, generateFormattedContext, generateReport, getAffectedFiles, getAffectingDecisions, getAnalyzer, getAnalyzerIds, getChangedFiles, getConfigPath, getDecisionsDir, getInferredDir, getReportsDir, getSpecBridgeDir, getTransitiveDependencies, getVerifier, getVerifierIds, getVerifiersDir, glob, isConstraintExcepted, isDirectory, loadConfig, loadDecisionFile, loadDecisionsFromDir, matchesAnyPattern, matchesPattern, mergeWithDefaults, normalizePath, parseYaml, parseYamlDocument, pathExists, readFilesInDir, readTextFile, runInference, selectVerifierForConstraint, shouldApplyConstraintToFile, stringifyYaml, templates, updateYamlDocument, validateConfig, validateDecision, validateDecisionFile, writeTextFile };
+export { type AffectedFile, type AgentContext, AgentContextGenerator, AlreadyInitializedError, type Analyzer, AnalyzerNotFoundError, ApiVerifier, type ApplicableConstraint, type ApplicableDecision, AstCache, AutofixEngine, type AutofixPatch, type AutofixResult, CodeScanner, ComplexityVerifier, type ComplianceReport, ConfigError, type Constraint, type ConstraintCheck, ConstraintCheckSchema, type ConstraintCheckSchema_, type ConstraintException, ConstraintExceptionSchema, type ConstraintExceptionSchema_, ConstraintSchema, type ConstraintSchema_, type ConstraintType, ConstraintTypeSchema, type ConstraintTypeSchema_, type ContextOptions, type Decision, type DecisionCompliance, type DecisionContent, DecisionContentSchema, type DecisionContentSchema_, type DecisionFilter, type DecisionMetadata, DecisionMetadataSchema, type DecisionMetadataSchema_, DecisionNotFoundError, DecisionSchema, type DecisionStatus, DecisionStatusSchema, type DecisionStatusSchema_, type DecisionTypeSchema, DecisionValidationError, type DependencyGraph, DependencyVerifier, type DriftAnalysis, ErrorsAnalyzer, ErrorsVerifier, FileSystemError, type GlobOptions, type GraphNode, HookError, type ImpactAnalysis, ImportsAnalyzer, ImportsVerifier, InferenceEngine, InferenceError, type InferenceOptions, type InferenceResult, type LevelConfig, LinksSchema, type LoadError, type LoadResult, type LoadedDecision, type McpServerOptions, type MigrationStep, NamingAnalyzer, NamingVerifier, NotInitializedError, type OverallDrift, type Pattern, type PatternExample, type PromptTemplate, PropagationEngine, type PropagationOptions, RegexVerifier, Registry, type RegistryConstraintMatch, RegistryError, type RegistryOptions, type ReportOptions, ReportStorage, Reporter, type ScanOptions, type ScanResult, type ScannedFile, SecurityVerifier, type Severity, SeveritySchema, type SeveritySchema_, type SpecBridgeConfig, SpecBridgeConfigSchema, type SpecBridgeConfigType, SpecBridgeError, SpecBridgeMcpServer, type StoredReport, StructureAnalyzer, type TextEdit, type TrendAnalysis, type TrendData, type TrendDirection, type VerificationConfig, VerificationConfigSchema, type VerificationConfigSchema_, type VerificationContext, VerificationEngine, VerificationError, type VerificationFrequency, VerificationFrequencySchema, type VerificationFrequencySchema_, type VerificationIssue, type VerificationLevel, type VerificationOptions, type VerificationResult, type VerificationWarning, type Verifier, VerifierNotFoundError, type VerifierPlugin, type VerifierPluginMetadata, type Violation, type ViolationFix, analyzeTrend, buildDependencyGraph, builtinAnalyzers, builtinVerifiers, calculateConfidence, checkDegradation, clearVerifierPool, createInferenceEngine, createPattern, createPropagationEngine, createRegistry, createScannerFromConfig, createVerificationEngine, createViolation, defaultConfig, defineVerifierPlugin, detectDrift, ensureDir, extractSnippet, formatConsoleReport, formatContextAsJson, formatContextAsMarkdown, formatContextAsMcp, formatError, formatMarkdownReport, formatValidationErrors, generateContext, generateFormattedContext, generateReport, getAffectedFiles, getAffectingDecisions, getAnalyzer, getAnalyzerIds, getChangedFiles, getConfigPath, getDecisionsDir, getInferredDir, getReportsDir, getSpecBridgeDir, getTransitiveDependencies, getVerifier, getVerifierIds, getVerifiersDir, glob, isConstraintExcepted, isDirectory, loadConfig, loadDecisionFile, loadDecisionsFromDir, matchesAnyPattern, matchesPattern, mergeWithDefaults, normalizePath, parseYaml, parseYamlDocument, pathExists, readFilesInDir, readTextFile, runInference, selectVerifierForConstraint, shouldApplyConstraintToFile, stringifyYaml, templates, updateYamlDocument, validateConfig, validateDecision, validateDecisionFile, writeTextFile };