@ipation/specbridge 1.1.1 → 1.2.0

package/dist/index.d.ts

@@ -1718,6 +1718,121 @@ declare function formatConsoleReport(report: ComplianceReport): string;
  */
 declare function formatMarkdownReport(report: ComplianceReport): string;
 
+interface StoredReport {
+    timestamp: string;
+    report: ComplianceReport;
+}
+/**
+ * ReportStorage - Handles persistence and retrieval of historical reports
+ */
+declare class ReportStorage {
+    private storageDir;
+    constructor(basePath: string);
+    /**
+     * Save a compliance report to storage
+     */
+    save(report: ComplianceReport): Promise<string>;
+    /**
+     * Load the most recent report
+     */
+    loadLatest(): Promise<StoredReport | null>;
+    /**
+     * Load historical reports for the specified number of days
+     */
+    loadHistory(days?: number): Promise<StoredReport[]>;
+    /**
+     * Load a specific report by date
+     */
+    loadByDate(date: string): Promise<ComplianceReport | null>;
+    /**
+     * Get all available report dates
+     */
+    getAvailableDates(): Promise<string[]>;
+    /**
+     * Clear old reports (keep only the most recent N days)
+     */
+    cleanup(keepDays?: number): Promise<number>;
+}
+
+/**
+ * Drift detection - Analyze compliance trends between reports
+ */
+
+type TrendDirection = 'improving' | 'stable' | 'degrading';
+interface DriftAnalysis {
+    decisionId: string;
+    title: string;
+    trend: TrendDirection;
+    complianceChange: number;
+    newViolations: number;
+    fixedViolations: number;
+    currentCompliance: number;
+    previousCompliance: number;
+}
+interface OverallDrift {
+    trend: TrendDirection;
+    complianceChange: number;
+    summary: {
+        newViolations: {
+            critical: number;
+            high: number;
+            medium: number;
+            low: number;
+            total: number;
+        };
+        fixedViolations: {
+            critical: number;
+            high: number;
+            medium: number;
+            low: number;
+            total: number;
+        };
+    };
+    byDecision: DriftAnalysis[];
+    mostImproved: DriftAnalysis[];
+    mostDegraded: DriftAnalysis[];
+}
+/**
+ * Detect drift between current and previous compliance reports
+ */
+declare function detectDrift(current: ComplianceReport, previous: ComplianceReport): Promise<OverallDrift>;
+/**
+ * Analyze compliance trend over multiple reports
+ */
+interface TrendAnalysis {
+    period: {
+        start: string;
+        end: string;
+        days: number;
+    };
+    overall: {
+        startCompliance: number;
+        endCompliance: number;
+        change: number;
+        trend: TrendDirection;
+        dataPoints: Array<{
+            date: string;
+            compliance: number;
+        }>;
+    };
+    decisions: Array<{
+        decisionId: string;
+        title: string;
+        startCompliance: number;
+        endCompliance: number;
+        change: number;
+        trend: TrendDirection;
+        dataPoints: Array<{
+            date: string;
+            compliance: number;
+        }>;
+    }>;
+}
+declare function analyzeTrend(reports: Array<{
+    timestamp: string;
+    report: ComplianceReport;
+}>): Promise<TrendAnalysis>;
+
 /**
  * Agent context generator
  */
@@ -1905,4 +2020,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, 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 Pattern, type PatternExample, type PromptTemplate, PropagationEngine, type PropagationOptions, RegexVerifier, Registry, type RegistryConstraintMatch, RegistryError, type RegistryOptions, type ReportOptions, Reporter, type ScanOptions, type ScanResult, type ScannedFile, SecurityVerifier, type Severity, SeveritySchema, type SeveritySchema_, type SpecBridgeConfig, SpecBridgeConfigSchema, type SpecBridgeConfigType, SpecBridgeError, SpecBridgeMcpServer, StructureAnalyzer, type TextEdit, type TrendData, 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, buildDependencyGraph, builtinAnalyzers, builtinVerifiers, calculateConfidence, checkDegradation, createInferenceEngine, createPattern, createPropagationEngine, createRegistry, createScannerFromConfig, createVerificationEngine, createViolation, defaultConfig, 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 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 };

package/dist/index.js

@@ -3552,6 +3552,291 @@ function formatProgressBar(percentage) {
   return `\`${filledChar.repeat(filled)}${emptyChar.repeat(empty)}\` ${percentage}%`;
 }
 
+// src/reporting/storage.ts
+import { join as join3 } from "path";
+var ReportStorage = class {
+  storageDir;
+  constructor(basePath) {
+    this.storageDir = join3(getSpecBridgeDir(basePath), "reports", "history");
+  }
+  /**
+   * Save a compliance report to storage
+   */
+  async save(report) {
+    await ensureDir(this.storageDir);
+    const date = new Date(report.timestamp).toISOString().split("T")[0];
+    const filename = `report-${date}.json`;
+    const filepath = join3(this.storageDir, filename);
+    await writeTextFile(filepath, JSON.stringify(report, null, 2));
+    return filepath;
+  }
+  /**
+   * Load the most recent report
+   */
+  async loadLatest() {
+    if (!await pathExists(this.storageDir)) {
+      return null;
+    }
+    const files = await readFilesInDir(this.storageDir);
+    if (files.length === 0) {
+      return null;
+    }
+    const sortedFiles = files.filter((f) => f.startsWith("report-") && f.endsWith(".json")).sort().reverse();
+    if (sortedFiles.length === 0) {
+      return null;
+    }
+    const latestFile = sortedFiles[0];
+    if (!latestFile) {
+      return null;
+    }
+    const content = await readTextFile(join3(this.storageDir, latestFile));
+    const report = JSON.parse(content);
+    return {
+      timestamp: latestFile.replace("report-", "").replace(".json", ""),
+      report
+    };
+  }
+  /**
+   * Load historical reports for the specified number of days
+   */
+  async loadHistory(days = 30) {
+    if (!await pathExists(this.storageDir)) {
+      return [];
+    }
+    const files = await readFilesInDir(this.storageDir);
+    const reportFiles = files.filter((f) => f.startsWith("report-") && f.endsWith(".json")).sort().reverse();
+    const recentFiles = reportFiles.slice(0, days);
+    const reports = [];
+    for (const file of recentFiles) {
+      try {
+        const content = await readTextFile(join3(this.storageDir, file));
+        const report = JSON.parse(content);
+        const timestamp = file.replace("report-", "").replace(".json", "");
+        reports.push({ timestamp, report });
+      } catch (error) {
+        console.warn(`Warning: Failed to load report ${file}:`, error);
+      }
+    }
+    return reports;
+  }
+  /**
+   * Load a specific report by date
+   */
+  async loadByDate(date) {
+    const filepath = join3(this.storageDir, `report-${date}.json`);
+    if (!await pathExists(filepath)) {
+      return null;
+    }
+    const content = await readTextFile(filepath);
+    return JSON.parse(content);
+  }
+  /**
+   * Get all available report dates
+   */
+  async getAvailableDates() {
+    if (!await pathExists(this.storageDir)) {
+      return [];
+    }
+    const files = await readFilesInDir(this.storageDir);
+    return files.filter((f) => f.startsWith("report-") && f.endsWith(".json")).map((f) => f.replace("report-", "").replace(".json", "")).sort().reverse();
+  }
+  /**
+   * Clear old reports (keep only the most recent N days)
+   */
+  async cleanup(keepDays = 90) {
+    if (!await pathExists(this.storageDir)) {
+      return 0;
+    }
+    const files = await readFilesInDir(this.storageDir);
+    const reportFiles = files.filter((f) => f.startsWith("report-") && f.endsWith(".json")).sort().reverse();
+    const filesToDelete = reportFiles.slice(keepDays);
+    for (const file of filesToDelete) {
+      try {
+        const filepath = join3(this.storageDir, file);
+        const fs = await import("fs/promises");
+        await fs.unlink(filepath);
+      } catch (error) {
+        console.warn(`Warning: Failed to delete old report ${file}:`, error);
+      }
+    }
+    return filesToDelete.length;
+  }
+};
+
+// src/reporting/drift.ts
+async function detectDrift(current, previous) {
+  const byDecision = [];
+  for (const currDecision of current.byDecision) {
+    const prevDecision = previous.byDecision.find(
+      (d) => d.decisionId === currDecision.decisionId
+    );
+    if (!prevDecision) {
+      byDecision.push({
+        decisionId: currDecision.decisionId,
+        title: currDecision.title,
+        trend: "stable",
+        complianceChange: 0,
+        newViolations: currDecision.violations,
+        fixedViolations: 0,
+        currentCompliance: currDecision.compliance,
+        previousCompliance: currDecision.compliance
+      });
+      continue;
+    }
+    const complianceChange = currDecision.compliance - prevDecision.compliance;
+    const violationDiff = currDecision.violations - prevDecision.violations;
+    let trend;
+    if (complianceChange > 5) {
+      trend = "improving";
+    } else if (complianceChange < -5) {
+      trend = "degrading";
+    } else {
+      trend = "stable";
+    }
+    byDecision.push({
+      decisionId: currDecision.decisionId,
+      title: currDecision.title,
+      trend,
+      complianceChange,
+      newViolations: Math.max(0, violationDiff),
+      fixedViolations: Math.max(0, -violationDiff),
+      currentCompliance: currDecision.compliance,
+      previousCompliance: prevDecision.compliance
+    });
+  }
+  const overallComplianceChange = current.summary.compliance - previous.summary.compliance;
+  let overallTrend;
+  if (overallComplianceChange > 5) {
+    overallTrend = "improving";
+  } else if (overallComplianceChange < -5) {
+    overallTrend = "degrading";
+  } else {
+    overallTrend = "stable";
+  }
+  const newViolations = {
+    critical: Math.max(
+      0,
+      current.summary.violations.critical - previous.summary.violations.critical
+    ),
+    high: Math.max(0, current.summary.violations.high - previous.summary.violations.high),
+    medium: Math.max(0, current.summary.violations.medium - previous.summary.violations.medium),
+    low: Math.max(0, current.summary.violations.low - previous.summary.violations.low),
+    total: 0
+  };
+  newViolations.total = newViolations.critical + newViolations.high + newViolations.medium + newViolations.low;
+  const fixedViolations = {
+    critical: Math.max(
+      0,
+      previous.summary.violations.critical - current.summary.violations.critical
+    ),
+    high: Math.max(0, previous.summary.violations.high - current.summary.violations.high),
+    medium: Math.max(0, previous.summary.violations.medium - current.summary.violations.medium),
+    low: Math.max(0, previous.summary.violations.low - current.summary.violations.low),
+    total: 0
+  };
+  fixedViolations.total = fixedViolations.critical + fixedViolations.high + fixedViolations.medium + fixedViolations.low;
+  const improving = byDecision.filter((d) => d.trend === "improving");
+  const degrading = byDecision.filter((d) => d.trend === "degrading");
+  const mostImproved = improving.sort((a, b) => b.complianceChange - a.complianceChange).slice(0, 5);
+  const mostDegraded = degrading.sort((a, b) => a.complianceChange - b.complianceChange).slice(0, 5);
+  return {
+    trend: overallTrend,
+    complianceChange: overallComplianceChange,
+    summary: {
+      newViolations,
+      fixedViolations
+    },
+    byDecision,
+    mostImproved,
+    mostDegraded
+  };
+}
+async function analyzeTrend(reports) {
+  if (reports.length === 0) {
+    throw new Error("No reports provided for trend analysis");
+  }
+  const sortedReports = reports.sort((a, b) => a.timestamp.localeCompare(b.timestamp));
+  const firstReport = sortedReports[0]?.report;
+  const lastReport = sortedReports[sortedReports.length - 1]?.report;
+  if (!firstReport || !lastReport) {
+    throw new Error("Invalid reports data");
+  }
+  const overallChange = lastReport.summary.compliance - firstReport.summary.compliance;
+  let overallTrend;
+  if (overallChange > 5) {
+    overallTrend = "improving";
+  } else if (overallChange < -5) {
+    overallTrend = "degrading";
+  } else {
+    overallTrend = "stable";
+  }
+  const overallDataPoints = sortedReports.map((r) => ({
+    date: r.timestamp,
+    compliance: r.report.summary.compliance
+  }));
+  const decisionMap = /* @__PURE__ */ new Map();
+  for (const { report } of sortedReports) {
+    for (const decision of report.byDecision) {
+      if (!decisionMap.has(decision.decisionId)) {
+        decisionMap.set(decision.decisionId, []);
+      }
+      decisionMap.get(decision.decisionId).push(decision);
+    }
+  }
+  const decisions = Array.from(decisionMap.entries()).map(([decisionId, data]) => {
+    const first = data[0];
+    const last = data[data.length - 1];
+    if (!first || !last) {
+      throw new Error(`Invalid decision data for ${decisionId}`);
+    }
+    const change = last.compliance - first.compliance;
+    let trend;
+    if (change > 5) {
+      trend = "improving";
+    } else if (change < -5) {
+      trend = "degrading";
+    } else {
+      trend = "stable";
+    }
+    const dataPoints = sortedReports.map((r) => {
+      const decision = r.report.byDecision.find((d) => d.decisionId === decisionId);
+      return {
+        date: r.timestamp,
+        compliance: decision?.compliance ?? 0
+      };
+    });
+    return {
+      decisionId,
+      title: last.title,
+      startCompliance: first.compliance,
+      endCompliance: last.compliance,
+      change,
+      trend,
+      dataPoints
+    };
+  });
+  const firstTimestamp = sortedReports[0]?.timestamp;
+  const lastTimestamp = sortedReports[sortedReports.length - 1]?.timestamp;
+  if (!firstTimestamp || !lastTimestamp) {
+    throw new Error("Invalid report timestamps");
+  }
+  return {
+    period: {
+      start: firstTimestamp,
+      end: lastTimestamp,
+      days: sortedReports.length
+    },
+    overall: {
+      startCompliance: firstReport.summary.compliance,
+      endCompliance: lastReport.summary.compliance,
+      change: overallChange,
+      trend: overallTrend,
+      dataPoints: overallDataPoints
+    },
+    decisions
+  };
+}
+
 // src/agent/context.generator.ts
 async function generateContext(filePath, config, options = {}) {
   const { includeRationale = config.agent?.includeRationale ?? true, cwd = process.cwd() } = options;
@@ -4010,6 +4295,7 @@ export {
   RegexVerifier,
   Registry,
   RegistryError,
+  ReportStorage,
   Reporter,
   SecurityVerifier,
   SeveritySchema,
@@ -4022,6 +4308,7 @@ export {
   VerificationError,
   VerificationFrequencySchema,
   VerifierNotFoundError,
+  analyzeTrend,
   buildDependencyGraph2 as buildDependencyGraph,
   builtinAnalyzers,
   builtinVerifiers,
@@ -4035,6 +4322,7 @@ export {
   createVerificationEngine,
   createViolation,
   defaultConfig,
+  detectDrift,
   ensureDir,
   extractSnippet,
   formatConsoleReport,