@ipation/specbridge 2.4.5 → 2.4.7

package/dist/index.d.ts

@@ -5,6 +5,43 @@ import { Logger as Logger$1 } from 'pino';
 import { Application } from 'express';
 export { minimatch } from 'minimatch';
 
+/**
+ * Shared execution context contract for CLI commands.
+ */
+type CommandOutputFormat = 'console' | 'json' | 'markdown';
+interface CommandContext {
+    cwd: string;
+    outputFormat: CommandOutputFormat;
+}
+interface ConfiguredCommandContext<TConfig> {
+    context: CommandContext;
+    config: TConfig;
+}
+
+/**
+ * Normalized verification request/response contracts shared across modules.
+ */
+
+interface VerificationRunRequest {
+    level?: VerificationLevel;
+    files?: string[];
+    decisions?: string[];
+    severity?: Severity[];
+    timeout?: number;
+    cwd?: string;
+}
+interface VerificationRunResult {
+    success: boolean;
+    violations: Violation[];
+    checked: number;
+    passed: number;
+    failed: number;
+    skipped: number;
+    duration: number;
+    warnings?: VerificationWarning[];
+    errors?: VerificationIssue[];
+}
+
 /**
  * Core type definitions for SpecBridge
  */
@@ -572,8 +609,8 @@ declare const SpecBridgeConfigSchema: z.ZodObject<{
     }, z.core.$strip>>;
     agent: z.ZodOptional<z.ZodObject<{
         format: z.ZodOptional<z.ZodEnum<{
-            markdown: "markdown";
             json: "json";
+            markdown: "markdown";
             mcp: "mcp";
         }>>;
         includeRationale: z.ZodOptional<z.ZodBoolean>;
@@ -1110,13 +1147,7 @@ declare class ExplainReporter {
     clear(): void;
 }
 
-interface VerificationOptions {
-    level?: VerificationLevel;
-    files?: string[];
-    decisions?: string[];
-    severity?: Severity[];
-    timeout?: number;
-    cwd?: string;
+interface VerificationOptions extends VerificationRunRequest {
     reporter?: ExplainReporter;
 }
 /**
@@ -1133,7 +1164,7 @@ declare class VerificationEngine {
     /**
      * Run verification
      */
-    verify(config: SpecBridgeConfig, options?: VerificationOptions): Promise<VerificationResult>;
+    verify(config: SpecBridgeConfig, options?: VerificationOptions): Promise<VerificationRunResult>;
     /**
      * Verify a single file
      */
@@ -1489,8 +1520,7 @@ interface ReportOptions {
  * Generic verification result shape for Reporter class
  * Supports various result formats from different verification engines
  */
-interface ReporterResult {
-    violations?: Violation[];
+interface ReporterResult extends Partial<VerificationRunResult> {
     summary?: {
         totalViolations?: number;
         decisionsChecked?: number;
@@ -2014,4 +2044,4 @@ interface GitHubPrCommentOptions {
 declare function formatViolationsForGitHub(violations: Violation[], limit?: number): string;
 declare function postPrComment(violations: Violation[], options: GitHubPrCommentOptions): Promise<void>;
 
-export { type AffectedFile, type AgentContext, AgentContextGenerator, AlreadyInitializedError, AnalyticsEngine, type AnalyticsSummary, type Analyzer, AnalyzerNotFoundError, ApiVerifier, type ApplicableConstraint, type ApplicableDecision, AstCache, AutofixEngine, type AutofixPatch, type AutofixResult, type BuildDependencyGraphOptions, 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, DashboardServer, type Decision, type DecisionCompliance, type DecisionContent, DecisionContentSchema, type DecisionContentSchema_, type DecisionFilter, type DecisionMetadata, DecisionMetadataSchema, type DecisionMetadataSchema_, type DecisionMetrics, DecisionNotFoundError, DecisionSchema, type DecisionStatus, DecisionStatusSchema, type DecisionStatusSchema_, type DecisionTypeSchema, DecisionValidationError, type DependencyGraph, DependencyVerifier, type DriftAnalysis, ErrorsAnalyzer, ErrorsVerifier, FileSystemError, type GitHubPrCommentOptions, type GlobOptions, type GraphNode, HookError, type ImpactAnalysis, ImportsAnalyzer, ImportsVerifier, InferenceEngine, InferenceError, type InferenceOptions, type InferenceResult, type Insight, type LevelConfig, LinksSchema, type LoadError, type LoadResult, type LoadedDecision, type Logger, 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 ReporterResult, 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, createDashboardServer, createInferenceEngine, createPattern, createPropagationEngine, createRegistry, createScannerFromConfig, createVerificationEngine, createViolation, defaultConfig, defineVerifierPlugin, detectDrift, ensureDir, extractSnippet, formatConsoleReport, formatContextAsJson, formatContextAsMarkdown, formatContextAsMcp, formatError, formatMarkdownReport, formatValidationErrors, formatViolationsForGitHub, generateContext, generateFormattedContext, generateReport, getAffectedFiles, getAffectingDecisions, getAnalyzer, getAnalyzerIds, getChangedFiles, getConfigPath, getDecisionsDir, getInferredDir, getLogger, getReportsDir, getSpecBridgeDir, getTransitiveDependencies, getVerifier, getVerifierIds, getVerifiersDir, glob, isConstraintExcepted, isDirectory, loadConfig, loadDecisionFile, loadDecisionsFromDir, logger, matchesAnyPattern, matchesPattern, mergeWithDefaults, normalizePath, parseYaml, parseYamlDocument, pathExists, postPrComment, readFilesInDir, readTextFile, runInference, selectVerifierForConstraint, shouldApplyConstraintToFile, startLspServer, stringifyYaml, templates, updateYamlDocument, validateConfig, validateDecision, validateDecisionFile, writeTextFile };
+export { type AffectedFile, type AgentContext, AgentContextGenerator, AlreadyInitializedError, AnalyticsEngine, type AnalyticsSummary, type Analyzer, AnalyzerNotFoundError, ApiVerifier, type ApplicableConstraint, type ApplicableDecision, AstCache, AutofixEngine, type AutofixPatch, type AutofixResult, type BuildDependencyGraphOptions, CodeScanner, type CommandContext, type CommandOutputFormat, ComplexityVerifier, type ComplianceReport, ConfigError, type ConfiguredCommandContext, type Constraint, type ConstraintCheck, ConstraintCheckSchema, type ConstraintCheckSchema_, type ConstraintException, ConstraintExceptionSchema, type ConstraintExceptionSchema_, ConstraintSchema, type ConstraintSchema_, type ConstraintType, ConstraintTypeSchema, type ConstraintTypeSchema_, type ContextOptions, DashboardServer, type Decision, type DecisionCompliance, type DecisionContent, DecisionContentSchema, type DecisionContentSchema_, type DecisionFilter, type DecisionMetadata, DecisionMetadataSchema, type DecisionMetadataSchema_, type DecisionMetrics, DecisionNotFoundError, DecisionSchema, type DecisionStatus, DecisionStatusSchema, type DecisionStatusSchema_, type DecisionTypeSchema, DecisionValidationError, type DependencyGraph, DependencyVerifier, type DriftAnalysis, ErrorsAnalyzer, ErrorsVerifier, ExplainReporter, type ExplanationEntry, FileSystemError, type GitHubPrCommentOptions, type GlobOptions, type GraphNode, HookError, type ImpactAnalysis, ImportsAnalyzer, ImportsVerifier, InferenceEngine, InferenceError, type InferenceOptions, type InferenceResult, type Insight, type LevelConfig, LinksSchema, type LoadError, type LoadResult, type LoadedDecision, type Logger, 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 ReporterResult, 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 VerificationRunRequest, type VerificationRunResult, type VerificationWarning, type Verifier, VerifierNotFoundError, type VerifierPlugin, type VerifierPluginMetadata, type Violation, type ViolationFix, analyzeTrend, buildDependencyGraph, builtinAnalyzers, builtinVerifiers, calculateConfidence, checkDegradation, clearVerifierPool, createDashboardServer, createInferenceEngine, createPattern, createPropagationEngine, createRegistry, createScannerFromConfig, createVerificationEngine, createViolation, defaultConfig, defineVerifierPlugin, detectDrift, ensureDir, extractSnippet, formatConsoleReport, formatContextAsJson, formatContextAsMarkdown, formatContextAsMcp, formatError, formatMarkdownReport, formatValidationErrors, formatViolationsForGitHub, generateContext, generateFormattedContext, generateReport, getAffectedFiles, getAffectingDecisions, getAnalyzer, getAnalyzerIds, getChangedFiles, getConfigPath, getDecisionsDir, getInferredDir, getLogger, getReportsDir, getSpecBridgeDir, getTransitiveDependencies, getVerifier, getVerifierIds, getVerifiersDir, glob, isConstraintExcepted, isDirectory, loadConfig, loadDecisionFile, loadDecisionsFromDir, logger, matchesAnyPattern, matchesPattern, mergeWithDefaults, normalizePath, parseYaml, parseYamlDocument, pathExists, postPrComment, readFilesInDir, readTextFile, runInference, selectVerifierForConstraint, shouldApplyConstraintToFile, startLspServer, stringifyYaml, templates, updateYamlDocument, validateConfig, validateDecision, validateDecisionFile, writeTextFile };

package/dist/index.js

@@ -3529,6 +3529,75 @@ async function getChangedFiles(cwd) {
   }
 }
 
+// src/verification/explain.ts
+import chalk from "chalk";
+var ExplainReporter = class {
+  entries = [];
+  /**
+   * Add an entry to the explanation trace
+   */
+  add(entry) {
+    this.entries.push(entry);
+  }
+  /**
+   * Print the explanation trace
+   */
+  print() {
+    if (this.entries.length === 0) {
+      console.log(chalk.dim("No constraints were evaluated."));
+      return;
+    }
+    console.log(chalk.bold("\n=== Verification Explanation ===\n"));
+    const byFile = /* @__PURE__ */ new Map();
+    for (const entry of this.entries) {
+      const existing = byFile.get(entry.file) || [];
+      existing.push(entry);
+      byFile.set(entry.file, existing);
+    }
+    for (const [file, entries] of byFile) {
+      console.log(chalk.underline(file));
+      for (const entry of entries) {
+        const icon = entry.applied ? chalk.green("\u2713") : chalk.dim("\u2298");
+        const constraintId = `${entry.decision.metadata.id}/${entry.constraint.id}`;
+        console.log(`  ${icon} ${constraintId}`);
+        console.log(chalk.dim(`    ${entry.reason}`));
+        if (entry.applied && entry.selectedVerifier) {
+          console.log(chalk.dim(`    Verifier: ${entry.selectedVerifier}`));
+          if (entry.verifierOutput) {
+            if (entry.verifierOutput.error) {
+              console.log(chalk.red(`    Error: ${entry.verifierOutput.error}`));
+            } else {
+              const violationText = entry.verifierOutput.violations === 1 ? "1 violation" : `${entry.verifierOutput.violations} violations`;
+              const resultColor = entry.verifierOutput.violations > 0 ? chalk.red : chalk.green;
+              console.log(
+                chalk.dim(`    Result: `) + resultColor(violationText) + chalk.dim(` in ${entry.verifierOutput.duration}ms`)
+              );
+            }
+          }
+        }
+        console.log("");
+      }
+    }
+    const applied = this.entries.filter((e) => e.applied).length;
+    const skipped = this.entries.filter((e) => !e.applied).length;
+    console.log(chalk.bold("Summary:"));
+    console.log(`  Constraints Applied: ${chalk.green(applied)}`);
+    console.log(`  Constraints Skipped: ${chalk.dim(skipped)}`);
+  }
+  /**
+   * Get all entries
+   */
+  getEntries() {
+    return [...this.entries];
+  }
+  /**
+   * Clear all entries
+   */
+  clear() {
+    this.entries = [];
+  }
+};
+
 // src/verification/autofix/engine.ts
 import { readFile as readFile4, writeFile as writeFile2 } from "fs/promises";
 import readline from "readline/promises";
@@ -4116,58 +4185,58 @@ var Reporter = class {
 };
 
 // src/reporting/formats/console.ts
-import chalk from "chalk";
+import chalk2 from "chalk";
 import { table } from "table";
 function formatConsoleReport(report) {
   const lines = [];
   lines.push("");
-  lines.push(chalk.bold.blue("SpecBridge Compliance Report"));
-  lines.push(chalk.dim(`Generated: ${new Date(report.timestamp).toLocaleString()}`));
-  lines.push(chalk.dim(`Project: ${report.project}`));
+  lines.push(chalk2.bold.blue("SpecBridge Compliance Report"));
+  lines.push(chalk2.dim(`Generated: ${new Date(report.timestamp).toLocaleString()}`));
+  lines.push(chalk2.dim(`Project: ${report.project}`));
   lines.push("");
   const complianceColor = getComplianceColor(report.summary.compliance);
-  lines.push(chalk.bold("Overall Compliance"));
+  lines.push(chalk2.bold("Overall Compliance"));
   lines.push(
     `  ${complianceColor(formatComplianceBar(report.summary.compliance))} ${complianceColor(`${report.summary.compliance}%`)}`
   );
   lines.push("");
-  lines.push(chalk.bold("Summary"));
+  lines.push(chalk2.bold("Summary"));
   lines.push(
     `  Decisions: ${report.summary.activeDecisions} active / ${report.summary.totalDecisions} total`
   );
   lines.push(`  Constraints: ${report.summary.totalConstraints}`);
   lines.push("");
-  lines.push(chalk.bold("Violations"));
+  lines.push(chalk2.bold("Violations"));
   const { violations } = report.summary;
   const violationParts = [];
   if (violations.critical > 0) {
-    violationParts.push(chalk.red(`${violations.critical} critical`));
+    violationParts.push(chalk2.red(`${violations.critical} critical`));
   }
   if (violations.high > 0) {
-    violationParts.push(chalk.yellow(`${violations.high} high`));
+    violationParts.push(chalk2.yellow(`${violations.high} high`));
   }
   if (violations.medium > 0) {
-    violationParts.push(chalk.cyan(`${violations.medium} medium`));
+    violationParts.push(chalk2.cyan(`${violations.medium} medium`));
   }
   if (violations.low > 0) {
-    violationParts.push(chalk.dim(`${violations.low} low`));
+    violationParts.push(chalk2.dim(`${violations.low} low`));
   }
   if (violationParts.length > 0) {
     lines.push(`  ${violationParts.join(" | ")}`);
   } else {
-    lines.push(chalk.green("  No violations"));
+    lines.push(chalk2.green("  No violations"));
   }
   lines.push("");
   if (report.byDecision.length > 0) {
-    lines.push(chalk.bold("By Decision"));
+    lines.push(chalk2.bold("By Decision"));
     lines.push("");
     const tableData = [
       [
-        chalk.bold("Decision"),
-        chalk.bold("Status"),
-        chalk.bold("Constraints"),
-        chalk.bold("Violations"),
-        chalk.bold("Compliance")
+        chalk2.bold("Decision"),
+        chalk2.bold("Status"),
+        chalk2.bold("Constraints"),
+        chalk2.bold("Violations"),
+        chalk2.bold("Compliance")
       ]
     ];
     for (const dec of report.byDecision) {
@@ -4177,7 +4246,7 @@ function formatConsoleReport(report) {
         truncate(dec.title, 40),
         statusColor(dec.status),
         String(dec.constraints),
-        dec.violations > 0 ? chalk.red(String(dec.violations)) : chalk.green("0"),
+        dec.violations > 0 ? chalk2.red(String(dec.violations)) : chalk2.green("0"),
         compColor(`${dec.compliance}%`)
       ]);
     }
@@ -4211,23 +4280,23 @@ function formatComplianceBar(compliance) {
   return "\u2588".repeat(filled) + "\u2591".repeat(empty);
 }
 function getComplianceColor(compliance) {
-  if (compliance >= 90) return chalk.green;
-  if (compliance >= 70) return chalk.yellow;
-  if (compliance >= 50) return chalk.hex("#FFA500");
-  return chalk.red;
+  if (compliance >= 90) return chalk2.green;
+  if (compliance >= 70) return chalk2.yellow;
+  if (compliance >= 50) return chalk2.hex("#FFA500");
+  return chalk2.red;
 }
 function getStatusColor(status) {
   switch (status) {
     case "active":
-      return chalk.green;
+      return chalk2.green;
     case "draft":
-      return chalk.yellow;
+      return chalk2.yellow;
     case "deprecated":
-      return chalk.gray;
+      return chalk2.gray;
     case "superseded":
-      return chalk.blue;
+      return chalk2.blue;
     default:
-      return chalk.white;
+      return chalk2.white;
   }
 }
 function truncate(str, length) {
@@ -5560,7 +5629,7 @@ import { TextDocument } from "vscode-languageserver-textdocument";
 import { fileURLToPath as fileURLToPath2 } from "url";
 import path3 from "path";
 import { Project as Project3 } from "ts-morph";
-import chalk2 from "chalk";
+import chalk3 from "chalk";
 function severityToDiagnostic(severity) {
   switch (severity) {
     case "critical":
@@ -5671,7 +5740,7 @@ var SpecBridgeLspServer = class {
     if (!await pathExists(getSpecBridgeDir(this.cwd))) {
       const err = new NotInitializedError();
       this.initError = err.message;
-      if (this.options.verbose) this.connection.console.error(chalk2.red(this.initError));
+      if (this.options.verbose) this.connection.console.error(chalk3.red(this.initError));
       return;
     }
     try {
@@ -5681,7 +5750,7 @@ var SpecBridgeLspServer = class {
       } catch (error) {
         const msg = error instanceof Error ? error.message : String(error);
         if (this.options.verbose)
-          this.connection.console.error(chalk2.red(`Plugin load failed: ${msg}`));
+          this.connection.console.error(chalk3.red(`Plugin load failed: ${msg}`));
       }
       this.registry = createRegistry({ basePath: this.cwd });
       await this.registry.load();
@@ -5695,12 +5764,12 @@ var SpecBridgeLspServer = class {
       }
       if (this.options.verbose) {
         this.connection.console.log(
-          chalk2.dim(`Loaded ${this.decisions.length} active decision(s)`)
+          chalk3.dim(`Loaded ${this.decisions.length} active decision(s)`)
         );
       }
     } catch (error) {
       this.initError = error instanceof Error ? error.message : String(error);
-      if (this.options.verbose) this.connection.console.error(chalk2.red(this.initError));
+      if (this.options.verbose) this.connection.console.error(chalk3.red(this.initError));
     }
   }
   async verifyTextDocument(doc) {
@@ -5855,6 +5924,7 @@ export {
   DependencyVerifier,
   ErrorsAnalyzer,
   ErrorsVerifier,
+  ExplainReporter,
   FileSystemError,
   HookError,
   ImportsAnalyzer,