@documentation-robotics/cli 0.1.0 → 0.1.7

package/dist/audit/relationships/spec/orchestrator.js

@@ -0,0 +1,157 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import * as yaml from "yaml";
+import { CoverageAnalyzer } from "../analysis/coverage-analyzer.js";
+import { DuplicateDetector } from "../analysis/duplicate-detector.js";
+import { GapAnalyzer } from "../analysis/gap-analyzer.js";
+import { BalanceAssessor } from "../analysis/balance-assessor.js";
+import { ConnectivityAnalyzer } from "../graph/connectivity.js";
+import { RelationshipCatalog } from "../../../core/relationship-catalog.js";
+import { RelationshipGraph } from "../graph/relationship-graph.js";
+import { getLayerById, getAllLayers } from "../../../generated/layer-registry.js";
+import { getErrorMessage } from "../../../utils/errors.js";
+class AuditOrchestrator {
+  catalog;
+  graph;
+  coverageAnalyzer;
+  duplicateDetector;
+  gapAnalyzer;
+  balanceAssessor;
+  connectivityAnalyzer;
+  initialized = !1;
+  constructor() {
+    this.catalog = new RelationshipCatalog(), this.graph = new RelationshipGraph(), this.coverageAnalyzer = new CoverageAnalyzer(this.catalog), this.duplicateDetector = new DuplicateDetector(this.catalog), this.gapAnalyzer = new GapAnalyzer(), this.balanceAssessor = new BalanceAssessor(), this.connectivityAnalyzer = new ConnectivityAnalyzer(this.graph, this.catalog);
+  }
+  /**
+   * Initialize the orchestrator (must be called before running audit)
+   */
+  async initialize() {
+    this.initialized || (await this.catalog.load(), this.initialized = !0);
+  }
+  /**
+   * Get predicates applicable to a specific layer
+   * Useful for AI evaluation to provide available relationship types
+   */
+  getPredicatesForLayer(layer) {
+    return this.catalog.getTypesForLayer(layer).map((t) => t.predicate);
+  }
+  /**
+   * Run coverage analysis
+   */
+  async runCoverageAnalysis(options) {
+    if (this.log(options, "Running coverage analysis..."), options.layer) {
+      const layer = getLayerById(options.layer);
+      if (!layer) {
+        const validLayerNames = getAllLayers().map((l) => l.id).join(", ");
+        throw new Error(`Layer not found: '${options.layer}'. Valid layers: ${validLayerNames}`);
+      }
+      return [await this.coverageAnalyzer.analyzeLayer(layer)];
+    }
+    return (await this.coverageAnalyzer.analyzeAll()).results;
+  }
+  /**
+   * Run duplicate detection
+   */
+  async runDuplicateDetection(options) {
+    if (this.log(options, "Running duplicate detection..."), options.layer) {
+      const layer = getLayerById(options.layer);
+      if (!layer)
+        throw new Error(`Layer not found: ${options.layer}`);
+      return this.duplicateDetector.detectDuplicatesByLayer(layer.id);
+    }
+    return this.duplicateDetector.detectDuplicates();
+  }
+  /**
+   * Run gap analysis
+   */
+  async runGapAnalysis(options) {
+    if (this.log(options, "Running gap analysis..."), options.layer) {
+      const layer = getLayerById(options.layer);
+      if (!layer)
+        throw new Error(`Layer not found: ${options.layer}`);
+      return this.gapAnalyzer.analyzeLayer(layer);
+    }
+    return this.gapAnalyzer.analyzeAll();
+  }
+  /**
+   * Run balance assessment
+   */
+  async runBalanceAssessment(options) {
+    if (this.log(options, "Running balance assessment..."), options.layer) {
+      const layer = getLayerById(options.layer);
+      if (!layer)
+        throw new Error(`Layer not found: ${options.layer}`);
+      return this.balanceAssessor.assessLayer(layer);
+    }
+    return this.balanceAssessor.assessAll();
+  }
+  /**
+   * Run connectivity analysis
+   */
+  async runConnectivityAnalysis(options) {
+    this.log(options, "Running connectivity analysis...");
+    const layerId = options.layer ? getLayerById(options.layer)?.id : void 0;
+    await this.graph.build(layerId);
+    const components = this.connectivityAnalyzer.findConnectedComponents(), degrees = this.connectivityAnalyzer.calculateDegreeDistribution(), transitiveChains = await this.connectivityAnalyzer.findTransitiveChains(), rawStats = this.connectivityAnalyzer.getConnectivityStats(), stats = {
+      totalNodes: rawStats.nodeCount,
+      totalEdges: rawStats.edgeCount,
+      connectedComponents: rawStats.componentCount,
+      largestComponentSize: rawStats.largestComponentSize,
+      isolatedNodes: rawStats.isolatedNodeCount,
+      averageDegree: rawStats.averageDegree,
+      transitiveChainCount: transitiveChains.length
+    };
+    return { components, degrees, transitiveChains, stats };
+  }
+  /**
+   * Load model metadata from manifest
+   */
+  async loadModelMetadata(options) {
+    this.log(options, "Loading model metadata...");
+    const projectRoot = options.projectRoot || process.cwd(), defaultMetadata = {
+      name: "Documentation Robotics Model",
+      version: "1.0.0"
+    };
+    try {
+      const manifestPath = join(projectRoot, "documentation-robotics", "model", "manifest.yaml"), manifestContent = await readFile(manifestPath, "utf-8");
+      let manifest;
+      try {
+        manifest = yaml.parse(manifestContent);
+      } catch (parseError) {
+        const parseErrorMsg = getErrorMessage(parseError);
+        return console.warn(`\u26A0\uFE0F  Warning: Manifest file is corrupted or has invalid YAML syntax (${parseErrorMsg}). Using default model metadata.`), defaultMetadata;
+      }
+      const name = manifest.name || manifest.project?.name, version = manifest.project?.version || manifest.version;
+      return !name || typeof name != "string" ? (console.warn("\u26A0\uFE0F  Warning: Manifest missing required field 'name'. Using default model metadata."), defaultMetadata) : !version || typeof version != "string" ? (console.warn("\u26A0\uFE0F  Warning: Manifest missing required field 'version'. Using default model metadata."), defaultMetadata) : { name, version };
+    } catch (error) {
+      const errorMsg = getErrorMessage(error);
+      return errorMsg.includes("ENOENT") || errorMsg.includes("no such file") ? this.log(options, "Using default model metadata (manifest not found)") : console.warn(`\u26A0\uFE0F  Warning: Cannot read manifest file (${errorMsg}). Using default model metadata.`), defaultMetadata;
+    }
+  }
+  /**
+   * Run complete audit and build report
+   */
+  async runAudit(options = {}) {
+    await this.initialize();
+    const coverage = await this.runCoverageAnalysis(options), duplicates = await this.runDuplicateDetection(options), gaps = await this.runGapAnalysis(options), balance = await this.runBalanceAssessment(options), connectivity = await this.runConnectivityAnalysis(options), modelMetadata = await this.loadModelMetadata(options);
+    return this.log(options, "Generating audit report..."), {
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      model: modelMetadata,
+      coverage,
+      duplicates,
+      gaps,
+      balance,
+      connectivity
+    };
+  }
+  /**
+   * Log helper that respects verbose/debug flags
+   */
+  log(options, message) {
+    (options.verbose || options.debug) && console.error(message);
+  }
+}
+export {
+  AuditOrchestrator
+};
+//# sourceMappingURL=orchestrator.js.map

package/dist/audit/relationships/spec/orchestrator.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/audit/relationships/spec/orchestrator.ts"],
+  "sourcesContent": ["/**\n * Audit Orchestrator - Centralized audit execution logic\n *\n * This class eliminates code duplication between cli/src/commands/audit.ts\n * and cli/scripts/relationship-audit.ts by extracting shared audit orchestration.\n */\n\nimport { readFile } from \"node:fs/promises\";\nimport { join } from \"node:path\";\nimport * as yaml from \"yaml\";\nimport { CoverageAnalyzer } from \"../analysis/coverage-analyzer.js\";\nimport { DuplicateDetector } from \"../analysis/duplicate-detector.js\";\nimport { GapAnalyzer } from \"../analysis/gap-analyzer.js\";\nimport { BalanceAssessor } from \"../analysis/balance-assessor.js\";\nimport { ConnectivityAnalyzer } from \"../graph/connectivity.js\";\nimport { RelationshipCatalog } from \"../../../core/relationship-catalog.js\";\nimport { RelationshipGraph } from \"../graph/relationship-graph.js\";\nimport { getLayerById, getAllLayers } from \"../../../generated/layer-registry.js\";\nimport type {\n  AuditReport,\n  ConnectivityStats,\n  CoverageMetrics,\n  DuplicateCandidate,\n  GapCandidate,\n  BalanceAssessment,\n} from \"../../types.js\";\nimport { getErrorMessage } from \"../../../utils/errors.js\";\n\nexport interface AuditOptions {\n  layer?: string;\n  verbose?: boolean;\n  debug?: boolean;\n  projectRoot?: string;\n}\n\nexport interface AuditComponents {\n  coverage: CoverageMetrics[];\n  duplicates: DuplicateCandidate[];\n  gaps: GapCandidate[];\n  balance: BalanceAssessment[];\n  connectivity: {\n    components: ReturnType<ConnectivityAnalyzer[\"findConnectedComponents\"]>;\n    degrees: ReturnType<ConnectivityAnalyzer[\"calculateDegreeDistribution\"]>;\n    transitiveChains: Awaited<\n      ReturnType<ConnectivityAnalyzer[\"findTransitiveChains\"]>\n    >;\n    stats: ConnectivityStats;\n  };\n}\n\n/**\n * Orchestrates the full audit pipeline\n */\nexport class AuditOrchestrator {\n  private catalog: RelationshipCatalog;\n  private graph: RelationshipGraph;\n  private coverageAnalyzer: CoverageAnalyzer;\n  private duplicateDetector: DuplicateDetector;\n  private gapAnalyzer: GapAnalyzer;\n  private balanceAssessor: BalanceAssessor;\n  private connectivityAnalyzer: ConnectivityAnalyzer;\n  private initialized = false;\n\n  constructor() {\n    this.catalog = new RelationshipCatalog();\n    this.graph = new RelationshipGraph();\n\n    this.coverageAnalyzer = new CoverageAnalyzer(this.catalog);\n    this.duplicateDetector = new DuplicateDetector(this.catalog);\n    this.gapAnalyzer = new GapAnalyzer();\n    this.balanceAssessor = new BalanceAssessor();\n    this.connectivityAnalyzer = new ConnectivityAnalyzer(this.graph, this.catalog);\n  }\n\n  /**\n   * Initialize the orchestrator (must be called before running audit)\n   */\n  async initialize(): Promise<void> {\n    if (!this.initialized) {\n      await this.catalog.load();\n      this.initialized = true;\n    }\n  }\n\n  /**\n   * Get predicates applicable to a specific layer\n   * Useful for AI evaluation to provide available relationship types\n   */\n  getPredicatesForLayer(layer: string): string[] {\n    const relationshipTypes = this.catalog.getTypesForLayer(layer);\n    return relationshipTypes.map((t) => t.predicate);\n  }\n\n  /**\n   * Run coverage analysis\n   */\n  async runCoverageAnalysis(options: AuditOptions): Promise<CoverageMetrics[]> {\n    this.log(options, \"Running coverage analysis...\");\n\n    if (options.layer) {\n      const layer = getLayerById(options.layer);\n      if (!layer) {\n        const allLayers = getAllLayers();\n        const validLayerNames = allLayers.map((l) => l.id).join(\", \");\n        throw new Error(\n          `Layer not found: '${options.layer}'. Valid layers: ${validLayerNames}`\n        );\n      }\n      const metrics = await this.coverageAnalyzer.analyzeLayer(layer);\n      return [metrics];\n    }\n    const result = await this.coverageAnalyzer.analyzeAll();\n    return result.results;\n  }\n\n  /**\n   * Run duplicate detection\n   */\n  async runDuplicateDetection(\n    options: AuditOptions\n  ): Promise<DuplicateCandidate[]> {\n    this.log(options, \"Running duplicate detection...\");\n\n    if (options.layer) {\n      const layer = getLayerById(options.layer);\n      if (!layer) {\n        throw new Error(`Layer not found: ${options.layer}`);\n      }\n      return this.duplicateDetector.detectDuplicatesByLayer(layer.id);\n    }\n    return this.duplicateDetector.detectDuplicates();\n  }\n\n  /**\n   * Run gap analysis\n   */\n  async runGapAnalysis(options: AuditOptions): Promise<GapCandidate[]> {\n    this.log(options, \"Running gap analysis...\");\n\n    if (options.layer) {\n      const layer = getLayerById(options.layer);\n      if (!layer) {\n        throw new Error(`Layer not found: ${options.layer}`);\n      }\n      return this.gapAnalyzer.analyzeLayer(layer);\n    }\n    return this.gapAnalyzer.analyzeAll();\n  }\n\n  /**\n   * Run balance assessment\n   */\n  async runBalanceAssessment(options: AuditOptions): Promise<BalanceAssessment[]> {\n    this.log(options, \"Running balance assessment...\");\n\n    if (options.layer) {\n      const layer = getLayerById(options.layer);\n      if (!layer) {\n        throw new Error(`Layer not found: ${options.layer}`);\n      }\n      return this.balanceAssessor.assessLayer(layer);\n    }\n    return this.balanceAssessor.assessAll();\n  }\n\n  /**\n   * Run connectivity analysis\n   */\n  async runConnectivityAnalysis(options: AuditOptions): Promise<{\n    components: ReturnType<ConnectivityAnalyzer[\"findConnectedComponents\"]>;\n    degrees: ReturnType<ConnectivityAnalyzer[\"calculateDegreeDistribution\"]>;\n    transitiveChains: Awaited<\n      ReturnType<ConnectivityAnalyzer[\"findTransitiveChains\"]>\n    >;\n    stats: ConnectivityStats;\n  }> {\n    this.log(options, \"Running connectivity analysis...\");\n\n    // Build the graph first if analyzing a specific layer or all relationships\n    const layerId = options.layer ? getLayerById(options.layer)?.id : undefined;\n    await this.graph.build(layerId);\n\n    const components = this.connectivityAnalyzer.findConnectedComponents();\n    const degrees = this.connectivityAnalyzer.calculateDegreeDistribution();\n    const transitiveChains =\n      await this.connectivityAnalyzer.findTransitiveChains();\n    const rawStats = this.connectivityAnalyzer.getConnectivityStats();\n\n    // Convert connectivity stats to match AuditReport format\n    const stats: ConnectivityStats = {\n      totalNodes: rawStats.nodeCount,\n      totalEdges: rawStats.edgeCount,\n      connectedComponents: rawStats.componentCount,\n      largestComponentSize: rawStats.largestComponentSize,\n      isolatedNodes: rawStats.isolatedNodeCount,\n      averageDegree: rawStats.averageDegree,\n      transitiveChainCount: transitiveChains.length,\n    };\n\n    return { components, degrees, transitiveChains, stats };\n  }\n\n  /**\n   * Load model metadata from manifest\n   */\n  async loadModelMetadata(options: AuditOptions): Promise<{\n    name: string;\n    version: string;\n  }> {\n    this.log(options, \"Loading model metadata...\");\n\n    const projectRoot = options.projectRoot || process.cwd();\n    const defaultMetadata = {\n      name: \"Documentation Robotics Model\",\n      version: \"1.0.0\",\n    };\n\n    try {\n      const manifestPath = join(\n        projectRoot,\n        \"documentation-robotics\",\n        \"model\",\n        \"manifest.yaml\"\n      );\n      const manifestContent = await readFile(manifestPath, \"utf-8\");\n      let manifest: { name?: string; version?: string; project?: { name?: string; version?: string } };\n\n      try {\n        manifest = yaml.parse(manifestContent) as typeof manifest;\n      } catch (parseError: unknown) {\n        // YAML parsing failed - file is corrupt\n        const parseErrorMsg = getErrorMessage(parseError);\n        console.warn(\n          `\u26A0\uFE0F  Warning: Manifest file is corrupted or has invalid YAML syntax (${parseErrorMsg}). Using default model metadata.`\n        );\n        return defaultMetadata;\n      }\n\n      // Name may be at top level or nested under project.name (CLI-generated manifests)\n      const name = manifest.name || manifest.project?.name;\n      // Version may be at top level or nested under project.version; top-level version is\n      // the manifest schema version, so prefer project.version when available\n      const version = manifest.project?.version || manifest.version;\n\n      if (!name || typeof name !== \"string\") {\n        console.warn(\n          `\u26A0\uFE0F  Warning: Manifest missing required field 'name'. Using default model metadata.`\n        );\n        return defaultMetadata;\n      }\n      if (!version || typeof version !== \"string\") {\n        console.warn(\n          `\u26A0\uFE0F  Warning: Manifest missing required field 'version'. Using default model metadata.`\n        );\n        return defaultMetadata;\n      }\n\n      return { name, version };\n    } catch (error: unknown) {\n      // Distinguish between file not found vs read error\n      const errorMsg = getErrorMessage(error);\n      if (errorMsg.includes(\"ENOENT\") || errorMsg.includes(\"no such file\")) {\n        // File not found - expected in tests, use defaults silently\n        this.log(\n          options,\n          \"Using default model metadata (manifest not found)\"\n        );\n      } else {\n        // File exists but cannot be read (permissions, disk error, etc)\n        console.warn(\n          `\u26A0\uFE0F  Warning: Cannot read manifest file (${errorMsg}). Using default model metadata.`\n        );\n      }\n      return defaultMetadata;\n    }\n  }\n\n  /**\n   * Run complete audit and build report\n   */\n  async runAudit(options: AuditOptions = {}): Promise<AuditReport> {\n    // Ensure catalog is loaded before running analysis\n    await this.initialize();\n\n    const coverage = await this.runCoverageAnalysis(options);\n    const duplicates = await this.runDuplicateDetection(options);\n    const gaps = await this.runGapAnalysis(options);\n    const balance = await this.runBalanceAssessment(options);\n    const connectivity = await this.runConnectivityAnalysis(options);\n    const modelMetadata = await this.loadModelMetadata(options);\n\n    this.log(options, \"Generating audit report...\");\n\n    return {\n      timestamp: new Date().toISOString(),\n      model: modelMetadata,\n      coverage,\n      duplicates,\n      gaps,\n      balance,\n      connectivity,\n    };\n  }\n\n  /**\n   * Log helper that respects verbose/debug flags\n   */\n  private log(options: AuditOptions, message: string): void {\n    if (options.verbose || options.debug) {\n      console.error(message);\n    }\n  }\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/audit/reports/index.js

@@ -0,0 +1,5 @@
+import { ReportGenerator } from "./report-generator.js";
+export {
+  ReportGenerator
+};
+//# sourceMappingURL=index.js.map

package/dist/audit/reports/index.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/audit/reports/index.ts"],
+  "sourcesContent": ["export { ReportGenerator, type ReportOptions, type ReportMetadata } from \"./report-generator.js\";\n"],
+  "mappings": "AAAA,SAAS,uBAAgE;",
+  "names": []
+}

package/dist/audit/reports/report-generator.js

@@ -0,0 +1,118 @@
+import fs from "fs/promises";
+import path from "path";
+class ReportGenerator {
+  /**
+   * Generate a complete audit report
+   */
+  async generateReport(result, options) {
+    try {
+      await fs.mkdir(options.outputDir, { recursive: !0 });
+    } catch (error) {
+      const errorMsg = error instanceof Error ? error.message : String(error);
+      throw new Error(`Failed to create output directory for ${options.format} report at ${options.outputDir}: ${errorMsg}`);
+    }
+    const totalNodeTypes = result.coverage.reduce((sum, c) => sum + c.nodeTypeCount, 0), totalRelationships = result.coverage.reduce((sum, c) => sum + c.relationshipCount, 0), metadata = {
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      phase: options.phase,
+      layer: options.layer,
+      totalNodeTypes,
+      totalRelationships
+    };
+    let reportContent, filename;
+    switch (options.format) {
+      case "json":
+        reportContent = this.generateJsonReport(result, metadata), filename = `audit-${options.phase}.json`;
+        break;
+      case "markdown":
+        reportContent = this.generateMarkdownReport(result, metadata, options.verbose), filename = `audit-${options.phase}.md`;
+        break;
+      case "text":
+      default:
+        reportContent = this.generateTextReport(result, metadata, options.verbose), filename = `audit-${options.phase}.txt`;
+        break;
+    }
+    const outputPath = path.join(options.outputDir, filename);
+    try {
+      await fs.writeFile(outputPath, reportContent, "utf-8");
+    } catch (error) {
+      const errorMsg = error instanceof Error ? error.message : String(error);
+      throw new Error(`Failed to write ${options.format} report to ${outputPath}: ${errorMsg}`);
+    }
+    return outputPath;
+  }
+  /**
+   * Generate JSON format report
+   */
+  generateJsonReport(result, metadata) {
+    return JSON.stringify({
+      metadata,
+      ...result
+    }, null, 2);
+  }
+  /**
+   * Generate Markdown format report
+   */
+  generateMarkdownReport(result, metadata, verbose = !1) {
+    const lines = [];
+    if (lines.push(`# Relationship Audit Report - ${metadata.phase.toUpperCase()}`), lines.push(""), lines.push(`**Timestamp**: ${metadata.timestamp}`), metadata.layer && lines.push(`**Layer**: ${metadata.layer}`), lines.push(`**Total Node Types**: ${metadata.totalNodeTypes}`), lines.push(`**Total Relationships**: ${metadata.totalRelationships}`), lines.push(""), result.coverage && result.coverage.length > 0 && (lines.push("## Coverage Metrics"), lines.push(""), result.coverage.forEach((coverage) => {
+      lines.push(`### Layer: ${coverage.layer}`), lines.push(`- **Isolation Rate**: ${coverage.isolationPercentage.toFixed(1)}%`), lines.push(`- **Density**: ${coverage.relationshipsPerNodeType.toFixed(2)} relationships/node type`), lines.push(`- **Predicate Utilization**: ${coverage.utilizationPercentage.toFixed(1)}%`), lines.push(""), verbose && coverage.isolatedNodeTypes.length > 0 && (lines.push("#### Isolated Node Types"), coverage.isolatedNodeTypes.forEach((nodeType) => {
+        lines.push(`- ${nodeType}`);
+      }), lines.push(""));
+    })), result.gaps && result.gaps.length > 0) {
+      lines.push("## Gap Analysis"), lines.push(""), lines.push(`Total Gaps Found: ${result.gaps.length}`), lines.push("");
+      const highPriorityGaps = result.gaps.filter((g) => g.priority === "high");
+      if (highPriorityGaps.length > 0 && (lines.push("### High Priority Gaps"), highPriorityGaps.forEach((gap) => {
+        lines.push(`- **${gap.sourceNodeType}** \u2192 **${gap.destinationNodeType}**: ${gap.suggestedPredicate} - ${gap.reason}`);
+      }), lines.push("")), verbose) {
+        const mediumPriorityGaps = result.gaps.filter((g) => g.priority === "medium");
+        mediumPriorityGaps.length > 0 && (lines.push("### Medium Priority Gaps"), mediumPriorityGaps.forEach((gap) => {
+          lines.push(`- **${gap.sourceNodeType}** \u2192 **${gap.destinationNodeType}**: ${gap.suggestedPredicate} - ${gap.reason}`);
+        }), lines.push(""));
+      }
+    }
+    if (result.duplicates && result.duplicates.length > 0 && (lines.push("## Duplicate Candidates"), lines.push(""), lines.push(`Total Duplicates Found: ${result.duplicates.length}`), lines.push(""), result.duplicates.slice(0, verbose ? void 0 : 10).forEach((dup) => {
+      lines.push(`- ${dup.relationships[0]} \u2194 ${dup.relationships[1]}`), lines.push(`  - Predicates: ${dup.predicates[0]} / ${dup.predicates[1]}`), lines.push(`  - Reason: ${dup.reason}`), lines.push(`  - Confidence: ${dup.confidence}`);
+    }), lines.push("")), result.balance && result.balance.length > 0) {
+      lines.push("## Balance Analysis"), lines.push("");
+      const summary = this.summarizeBalance(result.balance);
+      lines.push(`- **Structural Node Types**: ${summary.structural}`), lines.push(`- **Behavioral Node Types**: ${summary.behavioral}`), lines.push(`- **Under-connected**: ${summary.under}`), lines.push(`- **Well-balanced**: ${summary.balanced}`), lines.push(`- **Over-connected**: ${summary.over}`), lines.push("");
+    }
+    return result.connectivity && (lines.push("## Connectivity"), lines.push(""), lines.push(`- **Connected Components**: ${result.connectivity.stats.connectedComponents}`), lines.push(`- **Largest Component**: ${result.connectivity.stats.largestComponentSize} nodes`), lines.push(`- **Isolated Nodes**: ${result.connectivity.stats.isolatedNodes}`), lines.push(`- **Average Degree**: ${result.connectivity.stats.averageDegree.toFixed(2)}`), lines.push("")), lines.join(`
+`);
+  }
+  /**
+   * Summarize balance assessments
+   */
+  summarizeBalance(balance) {
+    return {
+      structural: balance.filter((b) => b.category === "structural").length,
+      behavioral: balance.filter((b) => b.category === "behavioral").length,
+      under: balance.filter((b) => b.status === "under").length,
+      balanced: balance.filter((b) => b.status === "balanced").length,
+      over: balance.filter((b) => b.status === "over").length
+    };
+  }
+  /**
+   * Generate Text format report
+   */
+  generateTextReport(result, metadata, verbose = !1) {
+    const lines = [];
+    if (lines.push("=".repeat(80)), lines.push(`RELATIONSHIP AUDIT REPORT - ${metadata.phase.toUpperCase()}`), lines.push("=".repeat(80)), lines.push(""), lines.push(`Timestamp: ${metadata.timestamp}`), metadata.layer && lines.push(`Layer: ${metadata.layer}`), lines.push(`Total Node Types: ${metadata.totalNodeTypes}`), lines.push(`Total Relationships: ${metadata.totalRelationships}`), lines.push(""), result.coverage && result.coverage.length > 0 && (lines.push("-".repeat(80)), lines.push("COVERAGE METRICS"), lines.push("-".repeat(80)), result.coverage.forEach((coverage) => {
+      lines.push(`Layer: ${coverage.layer}`), lines.push(`  Isolation Rate: ${coverage.isolationPercentage.toFixed(1)}%`), lines.push(`  Density: ${coverage.relationshipsPerNodeType.toFixed(2)} relationships/node type`), lines.push(`  Predicate Utilization: ${coverage.utilizationPercentage.toFixed(1)}%`), lines.push("");
+    })), result.gaps && result.gaps.length > 0) {
+      lines.push("-".repeat(80)), lines.push("GAP ANALYSIS"), lines.push("-".repeat(80)), lines.push(`Total Gaps: ${result.gaps.length}`), lines.push("");
+      const highPriorityGaps = result.gaps.filter((g) => g.priority === "high");
+      highPriorityGaps.length > 0 && (lines.push("High Priority Gaps:"), highPriorityGaps.forEach((gap, i) => {
+        lines.push(`  ${i + 1}. ${gap.sourceNodeType} \u2192 ${gap.destinationNodeType}`), lines.push(`     ${gap.suggestedPredicate}: ${gap.reason}`);
+      }), lines.push(""));
+    }
+    return result.duplicates && result.duplicates.length > 0 && (lines.push("-".repeat(80)), lines.push("DUPLICATE CANDIDATES"), lines.push("-".repeat(80)), lines.push(`Total Duplicates: ${result.duplicates.length}`), lines.push(""), result.duplicates.slice(0, verbose ? void 0 : 10).forEach((dup, i) => {
+      lines.push(`  ${i + 1}. ${dup.relationships[0]} \u2194 ${dup.relationships[1]}`), lines.push(`     Predicates: ${dup.predicates[0]} / ${dup.predicates[1]}`), lines.push(`     ${dup.reason} (${dup.confidence})`);
+    }), lines.push("")), result.connectivity && (lines.push("-".repeat(80)), lines.push("CONNECTIVITY"), lines.push("-".repeat(80)), lines.push(`Connected Components: ${result.connectivity.stats.connectedComponents}`), lines.push(`Largest Component: ${result.connectivity.stats.largestComponentSize} nodes`), lines.push(`Isolated Nodes: ${result.connectivity.stats.isolatedNodes}`), lines.push(`Average Degree: ${result.connectivity.stats.averageDegree.toFixed(2)}`), lines.push("")), lines.push("=".repeat(80)), lines.join(`
+`);
+  }
+}
+export {
+  ReportGenerator
+};
+//# sourceMappingURL=report-generator.js.map

package/dist/audit/reports/report-generator.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/audit/reports/report-generator.ts"],
+  "sourcesContent": ["import fs from \"fs/promises\";\nimport path from \"path\";\nimport type { AuditReport, GapCandidate, DuplicateCandidate, BalanceAssessment } from \"../types.js\";\n\nexport interface ReportOptions {\n  /**\n   * Phase of the audit pipeline - before or after AI evaluation\n   */\n  phase: \"before\" | \"after\";\n\n  /**\n   * Output directory for the report\n   */\n  outputDir: string;\n\n  /**\n   * Report format\n   */\n  format: \"text\" | \"json\" | \"markdown\";\n\n  /**\n   * Layer name (if audit is layer-specific)\n   */\n  layer?: string;\n\n  /**\n   * Whether to include verbose details\n   */\n  verbose?: boolean;\n}\n\nexport interface ReportMetadata {\n  timestamp: string;\n  phase: \"before\" | \"after\";\n  layer?: string;\n  totalNodeTypes: number;\n  totalRelationships: number;\n}\n\n/**\n * Generates audit reports with support for before/after phases\n */\nexport class ReportGenerator {\n  /**\n   * Generate a complete audit report\n   */\n  async generateReport(\n    result: AuditReport,\n    options: ReportOptions\n  ): Promise<string> {\n    // Ensure output directory exists\n    try {\n      await fs.mkdir(options.outputDir, { recursive: true });\n    } catch (error) {\n      const errorMsg = error instanceof Error ? error.message : String(error);\n      throw new Error(\n        `Failed to create output directory for ${options.format} report at ${options.outputDir}: ${errorMsg}`\n      );\n    }\n\n    // Calculate totals from all layers\n    const totalNodeTypes = result.coverage.reduce((sum, c) => sum + c.nodeTypeCount, 0);\n    const totalRelationships = result.coverage.reduce((sum, c) => sum + c.relationshipCount, 0);\n\n    const metadata: ReportMetadata = {\n      timestamp: new Date().toISOString(),\n      phase: options.phase,\n      layer: options.layer,\n      totalNodeTypes,\n      totalRelationships,\n    };\n\n    // Generate report based on format\n    let reportContent: string;\n    let filename: string;\n\n    switch (options.format) {\n      case \"json\":\n        reportContent = this.generateJsonReport(result, metadata);\n        filename = `audit-${options.phase}.json`;\n        break;\n      case \"markdown\":\n        reportContent = this.generateMarkdownReport(result, metadata, options.verbose);\n        filename = `audit-${options.phase}.md`;\n        break;\n      case \"text\":\n      default:\n        reportContent = this.generateTextReport(result, metadata, options.verbose);\n        filename = `audit-${options.phase}.txt`;\n        break;\n    }\n\n    const outputPath = path.join(options.outputDir, filename);\n    try {\n      await fs.writeFile(outputPath, reportContent, \"utf-8\");\n    } catch (error) {\n      const errorMsg = error instanceof Error ? error.message : String(error);\n      throw new Error(\n        `Failed to write ${options.format} report to ${outputPath}: ${errorMsg}`\n      );\n    }\n\n    return outputPath;\n  }\n\n  /**\n   * Generate JSON format report\n   */\n  private generateJsonReport(\n    result: AuditReport,\n    metadata: ReportMetadata\n  ): string {\n    return JSON.stringify(\n      {\n        metadata,\n        ...result,\n      },\n      null,\n      2\n    );\n  }\n\n  /**\n   * Generate Markdown format report\n   */\n  private generateMarkdownReport(\n    result: AuditReport,\n    metadata: ReportMetadata,\n    verbose = false\n  ): string {\n    const lines: string[] = [];\n\n    // Header\n    lines.push(`# Relationship Audit Report - ${metadata.phase.toUpperCase()}`);\n    lines.push(\"\");\n    lines.push(`**Timestamp**: ${metadata.timestamp}`);\n    if (metadata.layer) {\n      lines.push(`**Layer**: ${metadata.layer}`);\n    }\n    lines.push(`**Total Node Types**: ${metadata.totalNodeTypes}`);\n    lines.push(`**Total Relationships**: ${metadata.totalRelationships}`);\n    lines.push(\"\");\n\n    // Coverage Section\n    if (result.coverage && result.coverage.length > 0) {\n      lines.push(\"## Coverage Metrics\");\n      lines.push(\"\");\n\n      result.coverage.forEach((coverage) => {\n        lines.push(`### Layer: ${coverage.layer}`);\n        lines.push(`- **Isolation Rate**: ${coverage.isolationPercentage.toFixed(1)}%`);\n        lines.push(`- **Density**: ${coverage.relationshipsPerNodeType.toFixed(2)} relationships/node type`);\n        lines.push(`- **Predicate Utilization**: ${coverage.utilizationPercentage.toFixed(1)}%`);\n        lines.push(\"\");\n\n        if (verbose && coverage.isolatedNodeTypes.length > 0) {\n          lines.push(\"#### Isolated Node Types\");\n          coverage.isolatedNodeTypes.forEach((nodeType: string) => {\n            lines.push(`- ${nodeType}`);\n          });\n          lines.push(\"\");\n        }\n      });\n    }\n\n    // Gap Analysis Section\n    if (result.gaps && result.gaps.length > 0) {\n      lines.push(\"## Gap Analysis\");\n      lines.push(\"\");\n      lines.push(`Total Gaps Found: ${result.gaps.length}`);\n      lines.push(\"\");\n\n      const highPriorityGaps = result.gaps.filter((g: GapCandidate) => g.priority === \"high\");\n      if (highPriorityGaps.length > 0) {\n        lines.push(\"### High Priority Gaps\");\n        highPriorityGaps.forEach((gap: GapCandidate) => {\n          lines.push(`- **${gap.sourceNodeType}** \u2192 **${gap.destinationNodeType}**: ${gap.suggestedPredicate} - ${gap.reason}`);\n        });\n        lines.push(\"\");\n      }\n\n      if (verbose) {\n        const mediumPriorityGaps = result.gaps.filter((g: GapCandidate) => g.priority === \"medium\");\n        if (mediumPriorityGaps.length > 0) {\n          lines.push(\"### Medium Priority Gaps\");\n          mediumPriorityGaps.forEach((gap: GapCandidate) => {\n            lines.push(`- **${gap.sourceNodeType}** \u2192 **${gap.destinationNodeType}**: ${gap.suggestedPredicate} - ${gap.reason}`);\n          });\n          lines.push(\"\");\n        }\n      }\n    }\n\n    // Duplicates Section\n    if (result.duplicates && result.duplicates.length > 0) {\n      lines.push(\"## Duplicate Candidates\");\n      lines.push(\"\");\n      lines.push(`Total Duplicates Found: ${result.duplicates.length}`);\n      lines.push(\"\");\n\n      result.duplicates.slice(0, verbose ? undefined : 10).forEach((dup: DuplicateCandidate) => {\n        lines.push(`- ${dup.relationships[0]} \u2194 ${dup.relationships[1]}`);\n        lines.push(`  - Predicates: ${dup.predicates[0]} / ${dup.predicates[1]}`);\n        lines.push(`  - Reason: ${dup.reason}`);\n        lines.push(`  - Confidence: ${dup.confidence}`);\n      });\n      lines.push(\"\");\n    }\n\n    // Balance Section\n    if (result.balance && result.balance.length > 0) {\n      lines.push(\"## Balance Analysis\");\n      lines.push(\"\");\n\n      const summary = this.summarizeBalance(result.balance as BalanceAssessment[]);\n      lines.push(`- **Structural Node Types**: ${summary.structural}`);\n      lines.push(`- **Behavioral Node Types**: ${summary.behavioral}`);\n      lines.push(`- **Under-connected**: ${summary.under}`);\n      lines.push(`- **Well-balanced**: ${summary.balanced}`);\n      lines.push(`- **Over-connected**: ${summary.over}`);\n      lines.push(\"\");\n    }\n\n    // Connectivity Section\n    if (result.connectivity) {\n      lines.push(\"## Connectivity\");\n      lines.push(\"\");\n      lines.push(`- **Connected Components**: ${result.connectivity.stats.connectedComponents}`);\n      lines.push(`- **Largest Component**: ${result.connectivity.stats.largestComponentSize} nodes`);\n      lines.push(`- **Isolated Nodes**: ${result.connectivity.stats.isolatedNodes}`);\n      lines.push(`- **Average Degree**: ${result.connectivity.stats.averageDegree.toFixed(2)}`);\n      lines.push(\"\");\n    }\n\n    return lines.join(\"\\n\");\n  }\n\n  /**\n   * Summarize balance assessments\n   */\n  private summarizeBalance(balance: BalanceAssessment[]): {\n    structural: number;\n    behavioral: number;\n    under: number;\n    balanced: number;\n    over: number;\n  } {\n    return {\n      structural: balance.filter((b) => b.category === \"structural\").length,\n      behavioral: balance.filter((b) => b.category === \"behavioral\").length,\n      under: balance.filter((b) => b.status === \"under\").length,\n      balanced: balance.filter((b) => b.status === \"balanced\").length,\n      over: balance.filter((b) => b.status === \"over\").length,\n    };\n  }\n\n  /**\n   * Generate Text format report\n   */\n  private generateTextReport(\n    result: AuditReport,\n    metadata: ReportMetadata,\n    verbose = false\n  ): string {\n    const lines: string[] = [];\n\n    // Header\n    lines.push(\"=\".repeat(80));\n    lines.push(`RELATIONSHIP AUDIT REPORT - ${metadata.phase.toUpperCase()}`);\n    lines.push(\"=\".repeat(80));\n    lines.push(\"\");\n    lines.push(`Timestamp: ${metadata.timestamp}`);\n    if (metadata.layer) {\n      lines.push(`Layer: ${metadata.layer}`);\n    }\n    lines.push(`Total Node Types: ${metadata.totalNodeTypes}`);\n    lines.push(`Total Relationships: ${metadata.totalRelationships}`);\n    lines.push(\"\");\n\n    // Coverage Section\n    if (result.coverage && result.coverage.length > 0) {\n      lines.push(\"-\".repeat(80));\n      lines.push(\"COVERAGE METRICS\");\n      lines.push(\"-\".repeat(80));\n\n      result.coverage.forEach((coverage) => {\n        lines.push(`Layer: ${coverage.layer}`);\n        lines.push(`  Isolation Rate: ${coverage.isolationPercentage.toFixed(1)}%`);\n        lines.push(`  Density: ${coverage.relationshipsPerNodeType.toFixed(2)} relationships/node type`);\n        lines.push(`  Predicate Utilization: ${coverage.utilizationPercentage.toFixed(1)}%`);\n        lines.push(\"\");\n      });\n    }\n\n    // Gap Analysis Section\n    if (result.gaps && result.gaps.length > 0) {\n      lines.push(\"-\".repeat(80));\n      lines.push(\"GAP ANALYSIS\");\n      lines.push(\"-\".repeat(80));\n      lines.push(`Total Gaps: ${result.gaps.length}`);\n      lines.push(\"\");\n\n      const highPriorityGaps = result.gaps.filter((g: GapCandidate) => g.priority === \"high\");\n      if (highPriorityGaps.length > 0) {\n        lines.push(\"High Priority Gaps:\");\n        highPriorityGaps.forEach((gap: GapCandidate, i: number) => {\n          lines.push(`  ${i + 1}. ${gap.sourceNodeType} \u2192 ${gap.destinationNodeType}`);\n          lines.push(`     ${gap.suggestedPredicate}: ${gap.reason}`);\n        });\n        lines.push(\"\");\n      }\n    }\n\n    // Duplicates Section\n    if (result.duplicates && result.duplicates.length > 0) {\n      lines.push(\"-\".repeat(80));\n      lines.push(\"DUPLICATE CANDIDATES\");\n      lines.push(\"-\".repeat(80));\n      lines.push(`Total Duplicates: ${result.duplicates.length}`);\n      lines.push(\"\");\n\n      result.duplicates.slice(0, verbose ? undefined : 10).forEach((dup: DuplicateCandidate, i: number) => {\n        lines.push(`  ${i + 1}. ${dup.relationships[0]} \u2194 ${dup.relationships[1]}`);\n        lines.push(`     Predicates: ${dup.predicates[0]} / ${dup.predicates[1]}`);\n        lines.push(`     ${dup.reason} (${dup.confidence})`);\n      });\n      lines.push(\"\");\n    }\n\n    // Connectivity Section\n    if (result.connectivity) {\n      lines.push(\"-\".repeat(80));\n      lines.push(\"CONNECTIVITY\");\n      lines.push(\"-\".repeat(80));\n      lines.push(`Connected Components: ${result.connectivity.stats.connectedComponents}`);\n      lines.push(`Largest Component: ${result.connectivity.stats.largestComponentSize} nodes`);\n      lines.push(`Isolated Nodes: ${result.connectivity.stats.isolatedNodes}`);\n      lines.push(`Average Degree: ${result.connectivity.stats.averageDegree.toFixed(2)}`);\n      lines.push(\"\");\n    }\n\n    lines.push(\"=\".repeat(80));\n\n    return lines.join(\"\\n\");\n  }\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/audit/snapshot-storage.js

@@ -0,0 +1,163 @@
+import { promises as fs } from "fs";
+import * as path from "path";
+class SnapshotStorage {
+  storageDir;
+  maxSnapshots;
+  constructor(config = {}) {
+    this.storageDir = config.storageDir || path.join(process.cwd(), ".dr", "audit-snapshots"), this.maxSnapshots = config.maxSnapshots || 0;
+  }
+  /**
+   * Initialize storage directory
+   */
+  async ensureStorageDir() {
+    await fs.mkdir(this.storageDir, { recursive: !0 });
+  }
+  /**
+   * Generate snapshot ID from timestamp
+   */
+  generateSnapshotId(timestamp) {
+    return new Date(timestamp).toISOString().replace(/[-:]/g, "").replace(/\..+/, "").replace("T", "-");
+  }
+  /**
+   * Get snapshot file path
+   */
+  getSnapshotPath(id) {
+    return path.join(this.storageDir, `${id}.json`);
+  }
+  /**
+   * Get metadata file path
+   */
+  getMetadataPath(id) {
+    return path.join(this.storageDir, `${id}.meta.json`);
+  }
+  /**
+   * Save an audit report as a snapshot
+   */
+  async save(report) {
+    await this.ensureStorageDir();
+    const id = this.generateSnapshotId(report.timestamp), snapshotPath = this.getSnapshotPath(id), metadataPath = this.getMetadataPath(id), layers = report.coverage.map((c) => c.layer), metadata = {
+      id,
+      timestamp: report.timestamp,
+      modelName: report.model.name,
+      modelVersion: report.model.version,
+      layers,
+      snapshotPath
+    };
+    try {
+      await fs.writeFile(snapshotPath, JSON.stringify(report, null, 2), "utf-8");
+    } catch (error) {
+      throw new Error(`Failed to write snapshot file ${snapshotPath}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    try {
+      await fs.writeFile(metadataPath, JSON.stringify(metadata, null, 2), "utf-8");
+    } catch (error) {
+      try {
+        await fs.unlink(snapshotPath);
+      } catch {
+      }
+      throw new Error(`Failed to write snapshot metadata ${metadataPath}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    return this.maxSnapshots > 0 && await this.cleanupOldSnapshots(), metadata;
+  }
+  /**
+   * Load a snapshot by ID or timestamp
+   */
+  async load(idOrTimestamp) {
+    await this.ensureStorageDir();
+    let id;
+    /^\d{8}-\d{6}$/.test(idOrTimestamp) ? id = idOrTimestamp : id = this.generateSnapshotId(idOrTimestamp);
+    const snapshotPath = this.getSnapshotPath(id);
+    try {
+      const content = await fs.readFile(snapshotPath, "utf-8");
+      return JSON.parse(content);
+    } catch (error) {
+      throw error.code === "ENOENT" ? new Error(`Snapshot not found: ${id}. Use 'dr audit snapshots' to list available snapshots.`) : new Error(`Failed to parse snapshot ${id}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+  /**
+   * List all available snapshots
+   */
+  async list() {
+    await this.ensureStorageDir();
+    try {
+      const metadataFiles = (await fs.readdir(this.storageDir)).filter((f) => f.endsWith(".meta.json")), snapshots = [];
+      for (const file of metadataFiles) {
+        const content = await fs.readFile(path.join(this.storageDir, file), "utf-8");
+        snapshots.push(JSON.parse(content));
+      }
+      return snapshots.sort((a, b) => new Date(b.timestamp).getTime() - new Date(a.timestamp).getTime());
+    } catch (error) {
+      if (error.code === "ENOENT")
+        return [];
+      throw error;
+    }
+  }
+  /**
+   * Delete a snapshot
+   *
+   * Deletes both snapshot and metadata files sequentially with rollback on failure
+   * to prevent partial deletion state.
+   */
+  async delete(idOrTimestamp) {
+    await this.ensureStorageDir();
+    let id;
+    /^\d{8}-\d{6}$/.test(idOrTimestamp) ? id = idOrTimestamp : id = this.generateSnapshotId(idOrTimestamp);
+    const snapshotPath = this.getSnapshotPath(id), metadataPath = this.getMetadataPath(id);
+    try {
+      await fs.unlink(snapshotPath);
+    } catch (error) {
+      if (error.code !== "ENOENT")
+        throw new Error(`Failed to delete snapshot ${id}: ${error.message}`);
+    }
+    try {
+      await fs.unlink(metadataPath);
+    } catch (error) {
+      if (error.code !== "ENOENT")
+        throw new Error(`Failed to delete snapshot metadata ${id}: ${error.message}`);
+    }
+  }
+  /**
+   * Get the most recent snapshot
+   */
+  async getLatest() {
+    const snapshots = await this.list();
+    return snapshots.length === 0 ? null : this.load(snapshots[0].id);
+  }
+  /**
+   * Get the two most recent snapshots for comparison.
+   * Returns a tuple of [before, after] where 'before' is the older snapshot
+   * and 'after' is the more recent snapshot (for differential analysis).
+   * @returns [before, after] tuple where both are sorted chronologically, or [null, null] if fewer than 2 snapshots exist
+   */
+  async getLatestPair() {
+    const snapshots = await this.list();
+    if (snapshots.length < 2)
+      return [null, null];
+    const [after, before] = await Promise.all([
+      this.load(snapshots[0].id),
+      this.load(snapshots[1].id)
+    ]);
+    return [before, after];
+  }
+  /**
+   * Clean up old snapshots beyond the retention limit
+   */
+  async cleanupOldSnapshots() {
+    const snapshots = await this.list();
+    if (snapshots.length <= this.maxSnapshots)
+      return;
+    const toDelete = snapshots.slice(this.maxSnapshots);
+    await Promise.all(toDelete.map((s) => this.delete(s.id)));
+  }
+  /**
+   * Clear all snapshots
+   */
+  async clear() {
+    const snapshots = await this.list();
+    await Promise.all(snapshots.map((s) => this.delete(s.id)));
+  }
+}
+export {
+  SnapshotStorage
+};
+//# sourceMappingURL=snapshot-storage.js.map

package/dist/audit/snapshot-storage.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/audit/snapshot-storage.ts"],
+  "sourcesContent": ["/**\n * Audit snapshot storage and management\n *\n * Provides persistence for audit reports to enable temporal analysis\n * and before/after differential comparison.\n */\n\nimport { promises as fs } from \"fs\";\nimport * as path from \"path\";\nimport type { AuditReport } from \"./types.js\";\n\n/**\n * Metadata for a stored audit snapshot\n */\nexport interface SnapshotMetadata {\n  id: string; // Unique identifier (timestamp-based)\n  timestamp: string; // ISO 8601 timestamp\n  modelName: string;\n  modelVersion: string;\n  layers: string[]; // Layers included in this snapshot\n  snapshotPath: string; // Path to snapshot file\n}\n\n/**\n * Snapshot storage configuration\n */\nexport interface SnapshotStorageConfig {\n  storageDir?: string; // Override default storage directory\n  maxSnapshots?: number; // Maximum snapshots to retain (0 = unlimited)\n}\n\n/**\n * Manager for audit snapshot persistence\n */\nexport class SnapshotStorage {\n  private readonly storageDir: string;\n  private readonly maxSnapshots: number;\n\n  constructor(config: SnapshotStorageConfig = {}) {\n    this.storageDir =\n      config.storageDir || path.join(process.cwd(), \".dr\", \"audit-snapshots\");\n    this.maxSnapshots = config.maxSnapshots || 0; // Unlimited by default\n  }\n\n  /**\n   * Initialize storage directory\n   */\n  private async ensureStorageDir(): Promise<void> {\n    await fs.mkdir(this.storageDir, { recursive: true });\n  }\n\n  /**\n   * Generate snapshot ID from timestamp\n   */\n  private generateSnapshotId(timestamp: string): string {\n    // Format: YYYYMMDD-HHmmss\n    const date = new Date(timestamp);\n    const formatted = date\n      .toISOString()\n      .replace(/[-:]/g, \"\")\n      .replace(/\\..+/, \"\")\n      .replace(\"T\", \"-\");\n    return formatted;\n  }\n\n  /**\n   * Get snapshot file path\n   */\n  private getSnapshotPath(id: string): string {\n    return path.join(this.storageDir, `${id}.json`);\n  }\n\n  /**\n   * Get metadata file path\n   */\n  private getMetadataPath(id: string): string {\n    return path.join(this.storageDir, `${id}.meta.json`);\n  }\n\n  /**\n   * Save an audit report as a snapshot\n   */\n  async save(report: AuditReport): Promise<SnapshotMetadata> {\n    await this.ensureStorageDir();\n\n    const id = this.generateSnapshotId(report.timestamp);\n    const snapshotPath = this.getSnapshotPath(id);\n    const metadataPath = this.getMetadataPath(id);\n\n    // Extract layers from coverage data\n    const layers = report.coverage.map((c) => c.layer);\n\n    const metadata: SnapshotMetadata = {\n      id,\n      timestamp: report.timestamp,\n      modelName: report.model.name,\n      modelVersion: report.model.version,\n      layers,\n      snapshotPath,\n    };\n\n    // Write snapshot data\n    try {\n      await fs.writeFile(snapshotPath, JSON.stringify(report, null, 2), \"utf-8\");\n    } catch (error) {\n      throw new Error(\n        `Failed to write snapshot file ${snapshotPath}: ${error instanceof Error ? error.message : String(error)}`\n      );\n    }\n\n    // Write metadata\n    try {\n      await fs.writeFile(\n        metadataPath,\n        JSON.stringify(metadata, null, 2),\n        \"utf-8\",\n      );\n    } catch (error) {\n      // If metadata write fails, clean up orphaned snapshot file\n      try {\n        await fs.unlink(snapshotPath);\n      } catch (unlinkError) {\n        // Ignore cleanup errors\n      }\n      throw new Error(\n        `Failed to write snapshot metadata ${metadataPath}: ${error instanceof Error ? error.message : String(error)}`\n      );\n    }\n\n    // Cleanup old snapshots if limit exceeded\n    if (this.maxSnapshots > 0) {\n      await this.cleanupOldSnapshots();\n    }\n\n    return metadata;\n  }\n\n  /**\n   * Load a snapshot by ID or timestamp\n   */\n  async load(idOrTimestamp: string): Promise<AuditReport> {\n    await this.ensureStorageDir();\n\n    let id: string;\n\n    // Check if input is already a snapshot ID\n    if (/^\\d{8}-\\d{6}$/.test(idOrTimestamp)) {\n      id = idOrTimestamp;\n    } else {\n      // Assume it's a timestamp, convert to ID\n      id = this.generateSnapshotId(idOrTimestamp);\n    }\n\n    const snapshotPath = this.getSnapshotPath(id);\n\n    try {\n      const content = await fs.readFile(snapshotPath, \"utf-8\");\n      return JSON.parse(content) as AuditReport;\n    } catch (error) {\n      if ((error as NodeJS.ErrnoException).code === \"ENOENT\") {\n        throw new Error(\n          `Snapshot not found: ${id}. Use 'dr audit snapshots' to list available snapshots.`,\n        );\n      }\n      // Include snapshot ID in parse error context\n      throw new Error(\n        `Failed to parse snapshot ${id}: ${error instanceof Error ? error.message : String(error)}`\n      );\n    }\n  }\n\n  /**\n   * List all available snapshots\n   */\n  async list(): Promise<SnapshotMetadata[]> {\n    await this.ensureStorageDir();\n\n    try {\n      const files = await fs.readdir(this.storageDir);\n      const metadataFiles = files.filter((f) => f.endsWith(\".meta.json\"));\n\n      const snapshots: SnapshotMetadata[] = [];\n      for (const file of metadataFiles) {\n        const content = await fs.readFile(\n          path.join(this.storageDir, file),\n          \"utf-8\",\n        );\n        snapshots.push(JSON.parse(content) as SnapshotMetadata);\n      }\n\n      // Sort by timestamp (newest first)\n      return snapshots.sort(\n        (a, b) =>\n          new Date(b.timestamp).getTime() - new Date(a.timestamp).getTime(),\n      );\n    } catch (error) {\n      if ((error as NodeJS.ErrnoException).code === \"ENOENT\") {\n        return []; // Directory doesn't exist yet\n      }\n      throw error;\n    }\n  }\n\n  /**\n   * Delete a snapshot\n   *\n   * Deletes both snapshot and metadata files sequentially with rollback on failure\n   * to prevent partial deletion state.\n   */\n  async delete(idOrTimestamp: string): Promise<void> {\n    await this.ensureStorageDir();\n\n    let id: string;\n    if (/^\\d{8}-\\d{6}$/.test(idOrTimestamp)) {\n      id = idOrTimestamp;\n    } else {\n      id = this.generateSnapshotId(idOrTimestamp);\n    }\n\n    const snapshotPath = this.getSnapshotPath(id);\n    const metadataPath = this.getMetadataPath(id);\n\n    // Delete snapshot file first\n    try {\n      await fs.unlink(snapshotPath);\n    } catch (error) {\n      if ((error as NodeJS.ErrnoException).code !== \"ENOENT\") {\n        throw new Error(`Failed to delete snapshot ${id}: ${(error as NodeJS.ErrnoException).message}`);\n      }\n      // File doesn't exist, continue to metadata\n    }\n\n    // Delete metadata file\n    try {\n      await fs.unlink(metadataPath);\n    } catch (error) {\n      if ((error as NodeJS.ErrnoException).code !== \"ENOENT\") {\n        throw new Error(\n          `Failed to delete snapshot metadata ${id}: ${(error as NodeJS.ErrnoException).message}`\n        );\n      }\n      // File doesn't exist, both are gone\n    }\n  }\n\n  /**\n   * Get the most recent snapshot\n   */\n  async getLatest(): Promise<AuditReport | null> {\n    const snapshots = await this.list();\n    if (snapshots.length === 0) {\n      return null;\n    }\n    return this.load(snapshots[0].id);\n  }\n\n  /**\n   * Get the two most recent snapshots for comparison.\n   * Returns a tuple of [before, after] where 'before' is the older snapshot\n   * and 'after' is the more recent snapshot (for differential analysis).\n   * @returns [before, after] tuple where both are sorted chronologically, or [null, null] if fewer than 2 snapshots exist\n   */\n  async getLatestPair(): Promise<\n    [AuditReport, AuditReport] | [null, null]\n  > {\n    const snapshots = await this.list();\n    if (snapshots.length < 2) {\n      return [null, null];\n    }\n\n    const [after, before] = await Promise.all([\n      this.load(snapshots[0].id),\n      this.load(snapshots[1].id),\n    ]);\n\n    return [before, after];\n  }\n\n  /**\n   * Clean up old snapshots beyond the retention limit\n   */\n  private async cleanupOldSnapshots(): Promise<void> {\n    const snapshots = await this.list();\n\n    if (snapshots.length <= this.maxSnapshots) {\n      return;\n    }\n\n    const toDelete = snapshots.slice(this.maxSnapshots);\n    await Promise.all(toDelete.map((s) => this.delete(s.id)));\n  }\n\n  /**\n   * Clear all snapshots\n   */\n  async clear(): Promise<void> {\n    const snapshots = await this.list();\n    await Promise.all(snapshots.map((s) => this.delete(s.id)));\n  }\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/audit/types.js

@@ -0,0 +1,21 @@
+function createPercentage(value) {
+  if (value < 0 || value > 100 || !Number.isFinite(value))
+    throw new Error(`Invalid percentage: ${value}. Must be a number between 0 and 100.`);
+  return value;
+}
+function gapImpactScore(priority) {
+  return { high: 85, medium: 55, low: 25 }[priority];
+}
+function duplicateImpactScore(confidence) {
+  return { high: 75, medium: 45, low: 20 }[confidence];
+}
+function recommendationImpactScore(priority) {
+  return gapImpactScore(priority);
+}
+export {
+  createPercentage,
+  duplicateImpactScore,
+  gapImpactScore,
+  recommendationImpactScore
+};
+//# sourceMappingURL=types.js.map

package/dist/audit/types.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/audit/types.ts"],
+  "sourcesContent": ["/**\n * Type definitions for relationship audit system\n */\n\n/**\n * Percentage value constrained to 0-100 range\n * Use createPercentage() to construct safely\n */\nexport type Percentage = number & { readonly __brand: \"Percentage\" };\n\n/**\n * Create a validated percentage value (0-100)\n * @throws Error if value is not in valid range\n */\nexport function createPercentage(value: number): Percentage {\n  if (value < 0 || value > 100 || !Number.isFinite(value)) {\n    throw new Error(`Invalid percentage: ${value}. Must be a number between 0 and 100.`);\n  }\n  return value as Percentage;\n}\n\n/**\n * Coverage metrics for a layer\n */\nexport interface CoverageMetrics {\n  readonly layer: string;\n  readonly nodeTypeCount: number;\n  /** Intra-layer relationship instances (both endpoints in this layer) */\n  readonly relationshipCount: number;\n  /** Outgoing cross-layer relationship instances (source in this layer, target in another) */\n  readonly interLayerRelationshipCount: number;\n\n  // Node isolation\n  readonly isolatedNodeTypes: readonly string[]; // Zero relationships\n  /** Percentage of node types with zero relationships (0-100) */\n  readonly isolationPercentage: Percentage;\n\n  // Predicate utilization\n  readonly availablePredicates: readonly string[]; // Predicates applicable to this layer\n  readonly usedPredicates: readonly string[]; // Actually used\n  /** Percentage of available predicates actually used (0-100) */\n  readonly utilizationPercentage: Percentage;\n\n  // Density\n  readonly relationshipsPerNodeType: number;\n\n  // Standard alignment (for ArchiMate layers)\n  readonly standardAlignment?: {\n    readonly standard: string;\n    readonly expectedRelationships: number;\n    readonly missingFromStandard: readonly string[];\n  };\n}\n\n/**\n * Semantic duplicate candidate\n */\nexport interface DuplicateCandidate {\n  readonly relationships: readonly [string, string]; // IDs of duplicate pair\n  readonly predicates: readonly [string, string]; // Predicate names\n  readonly sourceNodeType: string;\n  readonly destinationNodeType: string;\n  readonly reason: string; // Explanation of semantic overlap\n  readonly confidence: \"high\" | \"medium\" | \"low\";\n  /** How necessary it is to clean up this duplicate (0\u2013100, higher = more urgent) */\n  readonly impactScore: number;\n  /** 100 - impactScore; aligns with NodeAIEvaluation.alignmentScore semantics (lower = more action needed) */\n  readonly alignmentScore: number;\n}\n\n/**\n * Missing relationship gap candidate\n */\nexport interface GapCandidate {\n  readonly sourceNodeType: string;\n  readonly destinationNodeType: string;\n  readonly suggestedPredicate: string;\n  readonly reason: string;\n  readonly priority: \"high\" | \"medium\" | \"low\";\n  readonly standardReference?: string; // e.g., \"ArchiMate 3.2 \u00A75.2\"\n  /** How necessary this gap is to fill (0\u2013100, higher = more urgent) */\n  readonly impactScore: number;\n  /** 100 - impactScore; aligns with NodeAIEvaluation.alignmentScore semantics (lower = more action needed) */\n  readonly alignmentScore: number;\n}\n\n/**\n * Balance assessment for node type relationship density\n */\nexport interface BalanceAssessment {\n  readonly nodeType: string;\n  readonly layer: string;\n  readonly category: \"structural\" | \"behavioral\" | \"enumeration\" | \"reference\";\n  readonly currentCount: number;\n  readonly targetRange: readonly [number, number];\n  readonly status: \"under\" | \"balanced\" | \"over\";\n  readonly recommendation?: string;\n}\n\n/**\n * Connected component in relationship graph\n */\nexport interface ConnectedComponent {\n  readonly nodes: readonly string[];\n}\n\n/**\n * Node degree information\n */\nexport interface NodeDegree {\n  readonly nodeType: string;\n  readonly inDegree: number;\n  readonly outDegree: number;\n  readonly totalDegree: number;\n}\n\n/**\n * Transitive relationship chain\n */\nexport interface TransitiveChain {\n  readonly predicate: string;\n  readonly chain: readonly string[]; // Node types in chain\n}\n\n/**\n * Connectivity statistics summary\n */\nexport interface ConnectivityStats {\n  readonly totalNodes: number;\n  readonly totalEdges: number;\n  readonly connectedComponents: number;\n  readonly largestComponentSize: number;\n  readonly isolatedNodes: number;\n  readonly averageDegree: number;\n  readonly transitiveChainCount: number;\n}\n\n/**\n * Comprehensive audit report combining all analysis results\n */\nexport interface AuditReport {\n  readonly timestamp: string;\n  readonly model: {\n    readonly name: string;\n    readonly version: string;\n  };\n  readonly coverage: readonly CoverageMetrics[];\n  readonly duplicates: readonly DuplicateCandidate[];\n  readonly gaps: readonly GapCandidate[];\n  readonly balance: readonly BalanceAssessment[];\n  readonly connectivity: {\n    readonly components: readonly ConnectedComponent[];\n    readonly degrees: readonly NodeDegree[];\n    readonly transitiveChains: readonly TransitiveChain[];\n    readonly stats: ConnectivityStats;\n  };\n}\n\n/**\n * Summary report comparing before/after audit states\n */\nexport interface SummaryReport {\n  readonly timestamp: string;\n  readonly coverageChanges: readonly {\n    readonly layer: string;\n    readonly before: { readonly isolation: number; readonly density: number };\n    readonly after: { readonly isolation: number; readonly density: number };\n    readonly delta: { readonly isolation: number; readonly density: number };\n  }[];\n  readonly relationshipsAdded: number;\n  readonly gapsResolved: number;\n  readonly remainingGaps: number;\n  readonly duplicatesResolved: number;\n  readonly balanceImprovements: readonly string[];\n}\n\n/**\n * Layer-specific aggregated data\n */\nexport interface LayerData {\n  readonly layer: string;\n  readonly coverage: CoverageMetrics;\n  readonly duplicates: readonly DuplicateCandidate[];\n  readonly gaps: readonly GapCandidate[];\n  readonly balance: readonly BalanceAssessment[];\n}\n\n// ---------------------------------------------------------------------------\n// Score helpers \u2014 shared by all gap/duplicate analyzers\n// ---------------------------------------------------------------------------\n\n/**\n * Impact score for a gap (missing relationship).\n * Higher = more urgently needed. Maps directly to priority.\n */\nexport function gapImpactScore(priority: \"high\" | \"medium\" | \"low\"): number {\n  const scores: Record<\"high\" | \"medium\" | \"low\", number> = { high: 85, medium: 55, low: 25 };\n  return scores[priority];\n}\n\n/**\n * Impact score for a duplicate candidate.\n * Higher = more confident it should be removed. Maps directly to confidence.\n */\nexport function duplicateImpactScore(confidence: \"high\" | \"medium\" | \"low\"): number {\n  const scores: Record<\"high\" | \"medium\" | \"low\", number> = { high: 75, medium: 45, low: 20 };\n  return scores[confidence];\n}\n\n/**\n * Impact score for an AI relationship recommendation.\n * Same scale as gap scores \u2014 recommendations describe missing relationships.\n */\nexport function recommendationImpactScore(priority: \"high\" | \"medium\" | \"low\"): number {\n  return gapImpactScore(priority);\n}\n"],
+  "mappings": "AAcM,SAAU,iBAAiB,OAAa;AAC5C,MAAI,QAAQ,KAAK,QAAQ,OAAO,CAAC,OAAO,SAAS,KAAK;AACpD,UAAM,IAAI,MAAM,uBAAuB,KAAK,uCAAuC;AAErF,SAAO;AACT;AAgLM,SAAU,eAAe,UAAmC;AAEhE,SAD0D,EAAE,MAAM,IAAI,QAAQ,IAAI,KAAK,GAAE,EAC3E,QAAQ;AACxB;AAMM,SAAU,qBAAqB,YAAqC;AAExE,SAD0D,EAAE,MAAM,IAAI,QAAQ,IAAI,KAAK,GAAE,EAC3E,UAAU;AAC1B;AAMM,SAAU,0BAA0B,UAAmC;AAC3E,SAAO,eAAe,QAAQ;AAChC;",
+  "names": []
+}