@documentation-robotics/cli 0.1.0 → 0.1.5

package/dist/analyzers/types.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/analyzers/types.ts"],
+  "sourcesContent": ["/**\n * Shared types for analyzer adapters\n *\n * These types define the contract between:\n * - The analyzer backend implementations\n * - The registry and commands\n * - The mapping loader\n */\n\nimport type { SourceReference } from \"../types/source-reference.js\";\n\n/**\n * Binary detection result - whether an analyzer is installed and functional\n * Discriminated union on `installed` field to make binary_path required when installed\n */\nexport type DetectionResult =\n  | {\n      installed: true;\n      binary_path: string;\n      version?: string;\n      mcp_registered?: boolean;\n      contract_ok?: boolean;\n    }\n  | {\n      installed: false;\n      binary_path?: never;\n      version?: never;\n      mcp_registered?: never;\n      contract_ok?: never;\n    };\n\n/**\n * Information about an available analyzer\n * Used in discovery results to report analyzer availability and installation status\n */\nexport interface AvailableAnalyzer {\n  name: string;\n  display_name: string;\n  description: string;\n  homepage: string;\n  installed: boolean;\n}\n\n/**\n * Result of analyzer discovery\n * Lists all available analyzers and their installation status\n */\nexport interface DiscoveryResult {\n  found: AvailableAnalyzer[];\n  installed_count: number;\n  selected?: string | null;\n}\n\n/**\n * Confidence level for mappings and detections\n */\nexport type ConfidenceLevel = \"high\" | \"medium\" | \"low\";\n\n/**\n * Valid HTTP methods - single source of truth for both type and runtime validation\n */\nexport const VALID_HTTP_METHODS = [\n  \"GET\",\n  \"POST\",\n  \"PUT\",\n  \"DELETE\",\n  \"PATCH\",\n  \"HEAD\",\n  \"OPTIONS\",\n  \"TRACE\",\n  \"CONNECT\",\n] as const;\n\n/**\n * Heuristic parameters - shape depends on heuristic type\n * Known parameter types:\n * - min_fan_in: { threshold: number }\n * - directory_match: { patterns: string[] }\n * - naming_patterns: { service_suffixes: string[] }\n * - class_is_service: { threshold: number }\n * - service_class_naming: { service_method_prefixes: string[] }\n * - is_entry_point: { entry_point_patterns: string[] }\n * - datastore_detection: { patterns: string[], naming_indicators: string[] }\n * - handles_route: (no parameters required)\n */\nexport interface HeuristicParameters {\n  threshold?: number;\n  patterns?: string[];\n  service_suffixes?: string[];\n  service_method_prefixes?: string[];\n  entry_point_patterns?: string[];\n  naming_indicators?: string[];\n  [key: string]: unknown;\n}\n\n// TODO: MappingConditions currently remain untyped as Record<string, unknown> because the\n// mapping schema defines conditions as a flexible object without known fields. If specific\n// condition properties are identified in future mapping iterations, define them here.\n\n/**\n * HTTP method type derived from VALID_HTTP_METHODS constant\n */\nexport type HttpMethod = (typeof VALID_HTTP_METHODS)[number];\n\n/**\n * An API endpoint candidate discovered from code analysis\n * Maps to `dr add api operation` command arguments\n *\n * These 13 fields directly support the downstream extraction workflow:\n * - Layer: api\n * - Element type: operation\n * - Name: constructed from suggested_name\n * - ID fragment: suggested_id_fragment (kebab-case for element ID)\n * - HTTP method/path: required for OpenAPI compliance\n * - Source information: for traceability and provenance\n */\nexport interface EndpointCandidate {\n  /** Relative path from project root */\n  source_file: string;\n  /** Confidence in the detection (high, medium, low) */\n  confidence: ConfidenceLevel;\n  /** Suggested DR layer for this endpoint (must be \"api\") */\n  suggested_layer: \"api\";\n  /** Suggested element type for this endpoint (must be \"operation\") */\n  suggested_element_type: \"operation\";\n  /** Suggested kebab-case name for the endpoint */\n  suggested_name: string;\n  /** Suggested kebab-case ID fragment for constructing element ID */\n  suggested_id_fragment: string;\n  /** HTTP method (GET, POST, PUT, DELETE, etc.) - REQUIRED */\n  http_method: HttpMethod;\n  /** HTTP path or resource identifier - REQUIRED */\n  http_path: string;\n  /** Qualified name of the handler/implementation */\n  handler_qualified_name: string;\n  /** Source symbol or identifier where handler is defined */\n  source_symbol: string;\n  /** Starting line number of handler in source file */\n  source_start_line: number;\n  /** Ending line number of handler in source file */\n  source_end_line: number;\n  /** Source reference linking this endpoint to its implementation */\n  source_reference: SourceReference;\n}\n\n/**\n * Index metadata - tracks when a project was indexed and freshness\n */\nexport interface IndexMeta {\n  git_head: string;\n  timestamp: string;\n  node_count: number;\n  edge_count: number;\n}\n\n/**\n * Result of an index operation\n * Contains counts and metadata from indexing.\n * Failures are signaled by throwing CLIError, not by success: false.\n */\nexport interface IndexResult {\n  git_head: string;\n  timestamp: string;\n  node_count: number;\n  edge_count: number;\n}\n\n/**\n * Current status of an analyzer for a project\n * Discriminated union on `indexed` field to enforce index_meta presence when indexed: true\n */\nexport type AnalyzerStatus =\n  | {\n      detected: DetectionResult;\n      indexed: true;\n      index_meta: IndexMeta;\n      fresh: boolean;\n      last_indexed?: string;\n    }\n  | {\n      detected: DetectionResult;\n      indexed: false;\n      index_meta?: never;\n      fresh: boolean;\n      last_indexed?: string;\n    };\n\n/**\n * Session state - tracks which analyzer is currently active\n */\nexport interface SessionState {\n  active_analyzer: string;\n  selected_at: string;\n}\n\n/**\n * Mapping for a single CBM node label to DR element type\n * Matches the structure in cbm.json nodes_by_label\n */\nexport interface AnalyzerNodeMapping {\n  cbm_label: string;\n  dr_layer: string;\n  dr_element_type: string;\n  confidence: ConfidenceLevel;\n  description: string;\n  source_reference: {\n    provenance: string;\n    file: {\n      from: string;\n    };\n    symbol?: {\n      from: string;\n    };\n  };\n  dr_element_fields?: Record<\n    string,\n    {\n      name_template?: string;\n      template?: string;\n      id_source?: string;\n      id_transform?: string;\n    }\n  >;\n  verify_role?: string;\n  attribute_mappings?: Array<{\n    from: string;\n    dr_attribute: string;\n  }>;\n  dr_element_type_promoted?: string;\n  promotion_heuristics?: string[];\n  evidence_fields?: Record<string, { from: string }>;\n  conditions?: Record<string, unknown>;\n}\n\n/**\n * Mapping for a single CBM edge type to DR relationship\n * Matches the structure in cbm.json edges_by_type\n */\nexport interface AnalyzerEdgeMapping {\n  cbm_edge: string;\n  dr_relationship: string | null;\n  confidence: ConfidenceLevel;\n  description: string;\n  usage: string;\n  dr_scope?: string;\n  direction?: string;\n  confidence_from_property?: string;\n  dr_pattern?: string;\n  implementation_note?: string;\n  conditions?: Record<string, unknown>;\n}\n\n/**\n * Single heuristic rule from the mapping\n */\nexport interface AnalyzerHeuristic {\n  name: string;\n  description: string;\n  applies_to?: string[];\n  parameters?: HeuristicParameters;\n  rule?: string;\n  confidence_adjustment?: number;\n  conditions?: Record<string, unknown>;\n}\n\n/**\n * Confidence rubric - threshold ranges for confidence levels\n */\nexport interface ConfidenceRubric {\n  high: {\n    min: number;\n    max: number;\n    description: string;\n  };\n  medium: {\n    min: number;\n    max: number;\n    description: string;\n  };\n  low: {\n    min: number;\n    max: number;\n    description: string;\n  };\n}\n\n/**\n * Filtering rule to exclude mappings\n */\nexport interface FilteringRule {\n  name: string;\n  description: string;\n  filter_type: string;\n  threshold?: number;\n  pattern?: string;\n  enabled: boolean;\n}\n\n/**\n * A service candidate discovered from code analysis\n * Maps to `dr add application service` or similar command arguments\n */\nexport interface ServiceCandidate {\n  /** Suggested DR layer for this service (always \"application\") */\n  suggested_layer: \"application\";\n  /** Suggested element type for this service */\n  suggested_element_type: \"applicationservice\" | \"applicationcomponent\";\n  /** Suggested kebab-case ID fragment for constructing element ID */\n  suggested_id_fragment: string;\n  /** Suggested name for the service */\n  suggested_name: string;\n  /** Relative path from project root */\n  source_file: string;\n  /** Source symbol or identifier where service is defined */\n  source_symbol: string;\n  /** Fully qualified name of the service */\n  qualified_name: string;\n  /** List of heuristics that qualified this as a service candidate */\n  qualifying_heuristics: string[];\n  /** Confidence in the detection (medium or low only) */\n  confidence: \"medium\" | \"low\";\n  /** Number of incoming calls/references */\n  fan_in: number;\n  /** Number of outgoing calls/references */\n  fan_out: number;\n}\n\n/**\n * A datastore candidate inferred from code analysis\n */\nexport interface DatastoreCandidate {\n  /** Suggested DR layer for this datastore (always \"data-store\") */\n  suggested_layer: \"data-store\";\n  /** Suggested name for the datastore */\n  suggested_name: string;\n  /** Array of evidence sources for this datastore inference */\n  inferred_from: Array<{\n    /** Relative path from project root */\n    source_file: string;\n    /** Pattern used to match imports (e.g., \"mongodb\", \"pg\") */\n    import_pattern: string;\n    /** Array of function/method call patterns that suggest datastore usage */\n    function_patterns: string[];\n  }>;\n  /** Confidence in the detection (always \"low\") */\n  confidence: \"low\";\n  /** Additional notes about the inference */\n  notes: string;\n}\n\n/**\n * A node in the call graph\n */\nexport interface CallGraphNode {\n  /** Fully qualified name of the node */\n  qualified_name: string;\n  /** Relative path from project root */\n  source_file: string;\n  /** Source symbol or identifier */\n  source_symbol: string;\n  /** Depth in the call graph (0 = root node) */\n  depth: number;\n  /** Type of edge (CALLS, HTTP_CALLS, HANDLES) */\n  edge_type: \"CALLS\" | \"HTTP_CALLS\" | \"HANDLES\";\n}\n\n/**\n * Options for the verify operation\n */\nexport interface VerifyOptions {\n  /** Array of layer names to verify (empty = verify all layers) */\n  layers?: string[];\n  /** Whether to use changeset view if active (default: true) */\n  changesetAware?: boolean;\n  /** Optional path to custom ignore file */\n  ignoreFilePath?: string;\n}\n\n/**\n * Entry for a matched route/element in verify report\n */\nexport interface MatchedEntry {\n  /** Identifier for the matched entry */\n  id: string;\n  /** Type of the entry (e.g., \"operation\") */\n  type: string;\n  /** Source file where this entry is located */\n  source_file: string;\n  /** Source symbol */\n  source_symbol: string;\n}\n\n/**\n * Entry for routes found in graph but not in model\n */\nexport interface GraphOnlyEntry {\n  /** Identifier for the entry */\n  id: string;\n  /** HTTP method (GET, POST, etc.) */\n  http_method?: string;\n  /** HTTP path */\n  http_path?: string;\n  /** Source file where this route is located */\n  source_file: string;\n  /** Source symbol */\n  source_symbol: string;\n}\n\n/**\n * Entry for elements in model but not found in graph\n */\nexport interface ModelOnlyEntry {\n  /** Identifier for the model element */\n  id: string;\n  /** Type of the element (e.g., \"operation\") */\n  type: string;\n  /** Source file referenced in the model */\n  source_file: string;\n  /** Source symbol referenced in the model */\n  source_symbol: string;\n}\n\n/**\n * Entry for matches that were ignored by rules\n */\nexport interface IgnoredEntry {\n  /** Identifier for the ignored entry */\n  id: string;\n  /** Type of the entry (route or element) */\n  entry_type: \"route\" | \"element\";\n  /** Reason for ignoring */\n  reason: string;\n}\n\n/**\n * Summary statistics for verify report\n */\nexport interface VerifySummary {\n  /** Number of routes matched to model elements */\n  matched_count: number;\n  /** Number of routes found in graph only (gaps in model) */\n  gap_count: number;\n  /** Number of elements found in model only (drift from model) */\n  drift_count: number;\n  /** Number of entries ignored by rules */\n  ignored_count: number;\n  /** Total graph entries analyzed */\n  total_graph_entries: number;\n  /** Total elements in the API layer (all elements, regardless of source attribution) */\n  total_model_entries: number;\n  /** Elements excluded from drift detection because they have no source_reference.\n   *  These are documentation-only elements with no code linkage. */\n  elements_without_source_ref: number;\n}\n\n/**\n * Changeset context information in verify report\n * Discriminated union to prevent impossible states like active_changeset: \"cs-1\" with verified_against: \"base_model\"\n */\nexport type VerifyChangesetContext =\n  | {\n      /** ID of the active changeset */\n      active_changeset: string;\n      /** Report was verified against changeset view */\n      verified_against: \"changeset_view\";\n    }\n  | {\n      /** No active changeset */\n      active_changeset: null;\n      /** Report was verified against base model */\n      verified_against: \"base_model\";\n    };\n\n/**\n * Buckets of categorized entries from verify operation\n */\nexport interface VerifyBuckets {\n  /** Routes matched to model elements */\n  matched: MatchedEntry[];\n  /** Routes found in graph only */\n  in_graph_only: GraphOnlyEntry[];\n  /** Elements in model only */\n  in_model_only: ModelOnlyEntry[];\n  /** Entries ignored by rules */\n  ignored: IgnoredEntry[];\n}\n\n/**\n * Detailed verification report for a project\n *\n * This is a public API contract consumed by /dr-verify Claude Code command.\n * Treat as stable from issue #654 forward.\n */\nexport interface VerifyReport {\n  /** ISO 8601 timestamp when report was generated */\n  generated_at: string;\n  /** Absolute path to the project root */\n  project_root: string;\n  /** Name of the analyzer used */\n  analyzer: string;\n  /** ISO 8601 timestamp when analyzer was indexed */\n  analyzer_indexed_at: string;\n  /** Changeset context information */\n  changeset_context: VerifyChangesetContext;\n  /** Array of layer names that were verified */\n  layers_verified: string[];\n  /** Buckets of categorized entries */\n  buckets: VerifyBuckets;\n  /** Summary statistics */\n  summary: VerifySummary;\n  /** Actionable hints for resolving gaps or drift, present when issues are detected */\n  hints?: string[];\n}\n"],
+  "mappings": "AA6DO,MAAM,qBAAqB;EAChC;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;;",
+  "names": []
+}

package/dist/analyzers/verify-engine.js

@@ -0,0 +1,209 @@
+import * as path from "path";
+import { access } from "fs/promises";
+import { Model } from "../core/model.js";
+import { IgnoreFileLoader } from "./verify-ignore.js";
+import { SOURCE_CODE_EXT_RE } from "./cbm-analyzer.js";
+class VerifyEngine {
+  /**
+   * Compute a comprehensive verification report
+   *
+   * Implements the five-step algorithm:
+   * 1. Resolve model view via Model.load() + getActiveChangesetId() + getLayer("api")
+   * 2. Build primary index on source_reference.locations[0].file + ":" + symbol
+   *    and optional secondary index on http_method + ":" + http_path
+   * 3. Load ignore rules
+   * 4. Compute four buckets (matched, in_graph_only, in_model_only, ignored)
+   * 5. Assemble VerifyReport
+   *
+   * @param projectRoot Absolute path to the project root
+   * @param routes Array of discovered routes from the graph
+   * @param options Verification options
+   * @returns Comprehensive verification report
+   */
+  async computeReport(projectRoot, routes, options, analyzerName = "codebase-memory-mcp", indexMeta) {
+    let model;
+    try {
+      model = await Model.load(projectRoot);
+    } catch (error) {
+      const err = error;
+      throw err.code === "ENOENT" || err.code === "ENOTDIR" ? new Error(`Failed to load DR model at ${projectRoot}: Model directory not found or inaccessible. Please run 'dr init' to initialize the documentation robotics model.`) : new Error(`Failed to load DR model at ${projectRoot}: ${err.message}. Please check that the model directory exists and is accessible.`);
+    }
+    const activeChangesetId = model.getActiveChangesetId(), apiLayer = options.changesetAware === !1 ? await model.getBaseLayer("api") : await model.getLayer("api");
+    if (!apiLayer)
+      return this.assembleReport(projectRoot, model, {
+        matched: [],
+        in_graph_only: routes.map((r) => ({
+          id: r.id,
+          http_method: r.http_method,
+          http_path: r.http_path,
+          source_file: r.source_file || "",
+          source_symbol: r.source_symbol || ""
+        })),
+        in_model_only: [],
+        ignored: []
+      }, activeChangesetId, options, analyzerName, indexMeta);
+    const primaryIndex = /* @__PURE__ */ new Map(), secondaryIndex = /* @__PURE__ */ new Map();
+    for (const element of apiLayer.elements.values()) {
+      const firstLocation = element.source_reference?.locations?.[0];
+      if (firstLocation && firstLocation.file) {
+        const symbol = firstLocation.symbol || "", key = `${firstLocation.file}:${symbol}`;
+        primaryIndex.set(key, {
+          modelEntry: {
+            id: element.id,
+            source_file: firstLocation.file,
+            source_symbol: symbol
+          },
+          key
+        });
+      }
+      const attrs = element.attributes;
+      if (attrs?.http_method && attrs?.http_path) {
+        const key = `${attrs.http_method}:${attrs.http_path}`;
+        secondaryIndex.set(key, {
+          modelEntry: {
+            id: element.id,
+            http_method: attrs.http_method,
+            http_path: attrs.http_path
+          },
+          key
+        });
+      }
+    }
+    const emptySymbolCount = routes.filter((r) => !r.source_symbol).length;
+    emptySymbolCount > 0 && console.warn(`
+Warning: ${emptySymbolCount}/${routes.length} graph route(s) have empty source_symbol. Primary-index matching by (source_file, source_symbol) will skip them.
+  Likely cause: the code graph analyzer did not extract handler function names for this language.
+  Secondary-index matching (http_method + http_path) requires those attributes on model operations.
+  To fix: re-index after the analyzer is updated, or manually set http_method/http_path on operations.
+`);
+    const ignoreFilePath = options.ignoreFilePath || path.join(projectRoot, ".dr-verify-ignore.yaml"), ignoreRules = await IgnoreFileLoader.load(ignoreFilePath), matched = [], inGraphOnly = [], ignored = [], matchedRouteIds = /* @__PURE__ */ new Set();
+    for (const route of routes) {
+      let matchedElement;
+      if (route.source_file && route.source_symbol) {
+        const key = `${route.source_file}:${route.source_symbol}`, primaryMatch = primaryIndex.get(key);
+        primaryMatch && (matchedElement = primaryMatch.modelEntry);
+      }
+      if (!matchedElement && route.http_method && route.http_path) {
+        const key = `${route.http_method}:${route.http_path}`, secondaryMatch = secondaryIndex.get(key);
+        secondaryMatch && (matchedElement = secondaryMatch.modelEntry);
+      }
+      const ignoreReason = IgnoreFileLoader.matches({
+        handler: route.handler,
+        path: route.http_path,
+        element_id: route.id
+      }, "route", ignoreRules);
+      ignoreReason ? (ignored.push({
+        id: route.id,
+        entry_type: "route",
+        reason: ignoreReason
+      }), matchedElement && matchedRouteIds.add(matchedElement.id)) : matchedElement ? (matched.push({
+        id: matchedElement.id,
+        type: "operation",
+        source_file: route.source_file || "",
+        source_symbol: route.source_symbol || ""
+      }), matchedRouteIds.add(matchedElement.id)) : inGraphOnly.push({
+        id: route.id,
+        http_method: route.http_method,
+        http_path: route.http_path,
+        source_file: route.source_file || "",
+        source_symbol: route.source_symbol || ""
+      });
+    }
+    const inModelOnly = [], fileChecks = [], elementsToCheck = [];
+    let elementsWithoutSourceRef = 0, elementsWithNonIndexableSource = 0;
+    for (const element of apiLayer.elements.values()) {
+      if (matchedRouteIds.has(element.id))
+        continue;
+      const firstLocation = element.source_reference?.locations?.[0];
+      if (!firstLocation || !firstLocation.file) {
+        elementsWithoutSourceRef++;
+        continue;
+      }
+      if (!SOURCE_CODE_EXT_RE.test(firstLocation.file)) {
+        elementsWithNonIndexableSource++;
+        continue;
+      }
+      elementsToCheck.push({
+        id: element.id,
+        path: element.path,
+        file: firstLocation.file,
+        symbol: firstLocation.symbol || ""
+      });
+      const filePath = path.join(projectRoot, firstLocation.file);
+      fileChecks.push(access(filePath).then(() => !0).catch((err) => err.code !== "ENOENT"));
+    }
+    elementsWithoutSourceRef > 0 && console.warn(`
+Warning: ${elementsWithoutSourceRef} API model element(s) excluded from drift detection \u2014 they have no source_reference with a file location.
+  Drift detection requires a linked source file to compare against the code graph.
+  Fix: dr update <element-id> --source-file <relative-path> --source-symbol <symbol>
+  Elements ingested via /dr-map or dr analyzer endpoints are automatically attributed.
+`), elementsWithNonIndexableSource > 0 && console.warn(`
+Warning: ${elementsWithNonIndexableSource} API model element(s) excluded from drift detection \u2014 their source files are not indexable source-code files.
+  Point source_reference to a source-code file (.ts, .js, .py, etc.) for drift detection,
+  or use dr analyzer endpoints to discover routes automatically.
+`);
+    const fileExistsResults = await Promise.all(fileChecks);
+    for (let i = 0; i < elementsToCheck.length; i++)
+      if (fileExistsResults[i]) {
+        const elem = elementsToCheck[i], ignoreReason = IgnoreFileLoader.matches({
+          element_id: elem.path
+        }, "element", ignoreRules);
+        ignoreReason ? ignored.push({
+          id: elem.id,
+          entry_type: "element",
+          reason: ignoreReason
+        }) : inModelOnly.push({
+          id: elem.id,
+          type: "operation",
+          source_file: elem.file,
+          source_symbol: elem.symbol
+        });
+      }
+    const buckets = {
+      matched,
+      in_graph_only: inGraphOnly,
+      in_model_only: inModelOnly,
+      ignored
+    };
+    return this.assembleReport(projectRoot, model, buckets, activeChangesetId, options, analyzerName, indexMeta, elementsWithoutSourceRef + elementsWithNonIndexableSource);
+  }
+  /**
+   * Assemble the final verification report
+   *
+   * @private
+   */
+  assembleReport(projectRoot, model, buckets, activeChangesetId, options, analyzerName = "codebase-memory-mcp", indexMeta, elementsWithoutSourceRef = 0) {
+    const matchedElements = buckets.matched.length, inModelOnly = buckets.in_model_only.length, ignoredElements = buckets.ignored.filter((e) => e.entry_type === "element").length, summary = {
+      matched_count: matchedElements,
+      gap_count: buckets.in_graph_only.length,
+      drift_count: inModelOnly,
+      ignored_count: buckets.ignored.length,
+      total_graph_entries: matchedElements + buckets.in_graph_only.length + buckets.ignored.filter((e) => e.entry_type === "route").length,
+      // Count all API layer elements: those that participated in matching plus those
+      // excluded because they lack source_reference (documentation-only elements).
+      total_model_entries: matchedElements + inModelOnly + ignoredElements + elementsWithoutSourceRef,
+      elements_without_source_ref: elementsWithoutSourceRef
+    }, hasActiveChangeset = (options.changesetAware ?? !0) && activeChangesetId !== null, analyzerIndexedAt = indexMeta?.timestamp || model.manifest.modified, changeset_context = hasActiveChangeset ? {
+      active_changeset: activeChangesetId,
+      verified_against: "changeset_view"
+    } : {
+      active_changeset: null,
+      verified_against: "base_model"
+    }, hints = [];
+    return buckets.in_graph_only.length > 0 && hints.push("To close gaps with source attribution, use /dr-map or `dr analyzer endpoints` ingestion \u2014 manual `dr add` operations cannot be matched by the verifier."), {
+      generated_at: (/* @__PURE__ */ new Date()).toISOString(),
+      project_root: projectRoot,
+      analyzer: analyzerName,
+      analyzer_indexed_at: analyzerIndexedAt,
+      changeset_context,
+      layers_verified: ["api"],
+      buckets,
+      summary,
+      ...hints.length > 0 ? { hints } : {}
+    };
+  }
+}
+export {
+  VerifyEngine
+};
+//# sourceMappingURL=verify-engine.js.map

package/dist/analyzers/verify-engine.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/analyzers/verify-engine.ts"],
+  "sourcesContent": ["/**\n * Verify Engine - computes verification reports for API endpoints\n *\n * Implements the core algorithm for comparing graph-discovered routes against\n * model-defined operations, supporting dual-index matching and changeset awareness.\n */\n\nimport * as path from \"path\";\nimport { access } from \"fs/promises\";\nimport { Model } from \"../core/model.js\";\nimport type {\n  VerifyReport,\n  VerifyOptions,\n  MatchedEntry,\n  GraphOnlyEntry,\n  ModelOnlyEntry,\n  IgnoredEntry,\n  VerifyBuckets,\n  VerifySummary,\n  IndexMeta,\n  VerifyChangesetContext,\n} from \"./types.js\";\nimport { IgnoreFileLoader } from \"./verify-ignore.js\";\nimport { SOURCE_CODE_EXT_RE } from \"./cbm-analyzer.js\";\n\n/**\n * A discovered route from the graph\n */\nexport interface DiscoveredRoute {\n  id: string;\n  http_method?: string;\n  http_path?: string;\n  handler?: string;\n  source_file?: string;\n  source_symbol?: string;\n}\n\n/**\n * Model element reference extracted from the API layer\n * Contains the minimal set of fields needed for dual-index matching\n */\ninterface ModelElementRef {\n  /** Element ID from the model */\n  id: string;\n  /** Source file path for primary index matching */\n  source_file?: string;\n  /** Source symbol for primary index matching */\n  source_symbol?: string;\n  /** HTTP method for secondary index matching */\n  http_method?: string;\n  /** HTTP path for secondary index matching */\n  http_path?: string;\n}\n\n/**\n * Primary or secondary index entry (holds model element data, not discovered route data)\n */\ninterface IndexEntry {\n  modelEntry: ModelElementRef;\n  key: string;\n}\n\n/**\n * VerifyEngine - computes verification reports for API endpoints\n */\nexport class VerifyEngine {\n  /**\n   * Compute a comprehensive verification report\n   *\n   * Implements the five-step algorithm:\n   * 1. Resolve model view via Model.load() + getActiveChangesetId() + getLayer(\"api\")\n   * 2. Build primary index on source_reference.locations[0].file + \":\" + symbol\n   *    and optional secondary index on http_method + \":\" + http_path\n   * 3. Load ignore rules\n   * 4. Compute four buckets (matched, in_graph_only, in_model_only, ignored)\n   * 5. Assemble VerifyReport\n   *\n   * @param projectRoot Absolute path to the project root\n   * @param routes Array of discovered routes from the graph\n   * @param options Verification options\n   * @returns Comprehensive verification report\n   */\n  async computeReport(\n    projectRoot: string,\n    routes: DiscoveredRoute[],\n    options: VerifyOptions,\n    analyzerName: string = \"codebase-memory-mcp\",\n    indexMeta?: IndexMeta\n  ): Promise<VerifyReport> {\n    // Step 1: Resolve model view\n    let model: Model;\n    try {\n      model = await Model.load(projectRoot);\n    } catch (error) {\n      const err = error as NodeJS.ErrnoException;\n      // Provide helpful error message if model directory is missing or corrupted\n      if (err.code === \"ENOENT\" || err.code === \"ENOTDIR\") {\n        throw new Error(\n          `Failed to load DR model at ${projectRoot}: Model directory not found or inaccessible. ` +\n          `Please run 'dr init' to initialize the documentation robotics model.`\n        );\n      }\n      throw new Error(\n        `Failed to load DR model at ${projectRoot}: ${err.message}. ` +\n        `Please check that the model directory exists and is accessible.`\n      );\n    }\n\n    const activeChangesetId = model.getActiveChangesetId();\n\n    // Use base layer if changesetAware is explicitly false\n    const apiLayer = options.changesetAware === false\n      ? await model.getBaseLayer(\"api\")\n      : await model.getLayer(\"api\");\n\n    if (!apiLayer) {\n      // No API layer found - all routes are in_graph_only\n      return this.assembleReport(\n        projectRoot,\n        model,\n        {\n          matched: [],\n          in_graph_only: routes.map((r) => ({\n            id: r.id,\n            http_method: r.http_method,\n            http_path: r.http_path,\n            source_file: r.source_file || \"\",\n            source_symbol: r.source_symbol || \"\",\n          })),\n          in_model_only: [],\n          ignored: [],\n        },\n        activeChangesetId,\n        options,\n        analyzerName,\n        indexMeta\n      );\n    }\n\n    // Step 2: Build dual-index\n    const primaryIndex = new Map<string, IndexEntry>();\n    const secondaryIndex = new Map<string, IndexEntry>();\n\n    for (const element of apiLayer.elements.values()) {\n      const firstLocation = element.source_reference?.locations?.[0];\n\n      // Primary index: file:symbol\n      if (firstLocation && firstLocation.file) {\n        const symbol = firstLocation.symbol || \"\";\n        const key = `${firstLocation.file}:${symbol}`;\n        primaryIndex.set(key, {\n          modelEntry: {\n            id: element.id,\n            source_file: firstLocation.file,\n            source_symbol: symbol,\n          },\n          key,\n        });\n      }\n\n      // Secondary index: http_method:http_path\n      const attrs = element.attributes as any;\n      if (attrs?.http_method && attrs?.http_path) {\n        const key = `${attrs.http_method}:${attrs.http_path}`;\n        secondaryIndex.set(key, {\n          modelEntry: {\n            id: element.id,\n            http_method: attrs.http_method,\n            http_path: attrs.http_path,\n          },\n          key,\n        });\n      }\n    }\n\n    // Warn if any graph routes have no source_symbol \u2014 they will be skipped by primary-index matching\n    const emptySymbolCount = routes.filter((r) => !r.source_symbol).length;\n    if (emptySymbolCount > 0) {\n      console.warn(\n        `\\nWarning: ${emptySymbolCount}/${routes.length} graph route(s) have empty source_symbol.` +\n        ` Primary-index matching by (source_file, source_symbol) will skip them.\\n` +\n        `  Likely cause: the code graph analyzer did not extract handler function names for this language.\\n` +\n        `  Secondary-index matching (http_method + http_path) requires those attributes on model operations.\\n` +\n        `  To fix: re-index after the analyzer is updated, or manually set http_method/http_path on operations.\\n`\n      );\n    }\n\n    // Step 3: Load ignore rules\n    const ignoreFilePath =\n      options.ignoreFilePath || path.join(projectRoot, \".dr-verify-ignore.yaml\");\n    const ignoreRules = await IgnoreFileLoader.load(ignoreFilePath);\n\n    // Step 4: Compute buckets\n    const matched: MatchedEntry[] = [];\n    const inGraphOnly: GraphOnlyEntry[] = [];\n    const ignored: IgnoredEntry[] = [];\n    const matchedRouteIds = new Set<string>();\n\n    for (const route of routes) {\n      let matchedElement: { id: string } | undefined;\n\n      // Try primary index match\n      if (route.source_file && route.source_symbol) {\n        const key = `${route.source_file}:${route.source_symbol}`;\n        const primaryMatch = primaryIndex.get(key);\n        if (primaryMatch) {\n          matchedElement = primaryMatch.modelEntry;\n        }\n      }\n\n      // Fallback to secondary index match\n      if (!matchedElement && route.http_method && route.http_path) {\n        const key = `${route.http_method}:${route.http_path}`;\n        const secondaryMatch = secondaryIndex.get(key);\n        if (secondaryMatch) {\n          matchedElement = secondaryMatch.modelEntry;\n        }\n      }\n\n      // Check if ignored\n      const ignoreReason = IgnoreFileLoader.matches(\n        {\n          handler: route.handler,\n          path: route.http_path,\n          element_id: route.id,\n        },\n        \"route\",\n        ignoreRules\n      );\n\n      if (ignoreReason) {\n        ignored.push({\n          id: route.id,\n          entry_type: \"route\",\n          reason: ignoreReason,\n        });\n        // Update matchedRouteIds even when ignored to prevent false drift\n        if (matchedElement) {\n          matchedRouteIds.add(matchedElement.id);\n        }\n      } else if (matchedElement) {\n        matched.push({\n          id: matchedElement.id,\n          type: \"operation\",\n          source_file: route.source_file || \"\",\n          source_symbol: route.source_symbol || \"\",\n        });\n        matchedRouteIds.add(matchedElement.id);\n      } else {\n        inGraphOnly.push({\n          id: route.id,\n          http_method: route.http_method,\n          http_path: route.http_path,\n          source_file: route.source_file || \"\",\n          source_symbol: route.source_symbol || \"\",\n        });\n      }\n    }\n\n    // Compute in_model_only: model elements not matched in graph\n    const inModelOnly: ModelOnlyEntry[] = [];\n\n    // Batch file-existence checks\n    const fileChecks: Promise<boolean>[] = [];\n    const elementsToCheck: Array<{ id: string; path: string; file: string; symbol: string }> = [];\n    let elementsWithoutSourceRef = 0;\n    let elementsWithNonIndexableSource = 0;\n\n    for (const element of apiLayer.elements.values()) {\n      if (matchedRouteIds.has(element.id)) {\n        continue; // Already matched\n      }\n\n      const firstLocation = element.source_reference?.locations?.[0];\n\n      if (!firstLocation || !firstLocation.file) {\n        // Skip elements with no source_reference file - they cannot drift since they have no code linkage.\n        // This includes manually-created elements that are documentation-only.\n        elementsWithoutSourceRef++;\n        continue;\n      }\n\n      // CBM only indexes source-code files \u2014 non-code source files (e.g. openapi.yaml)\n      // will never appear in the graph, so including them in drift detection produces false positives.\n      if (!SOURCE_CODE_EXT_RE.test(firstLocation.file)) {\n        elementsWithNonIndexableSource++;\n        continue;\n      }\n\n      elementsToCheck.push({\n        id: element.id,\n        path: element.path,\n        file: firstLocation.file,\n        symbol: firstLocation.symbol || \"\",\n      });\n\n      const filePath = path.join(projectRoot, firstLocation.file);\n      fileChecks.push(\n        access(filePath)\n          .then(() => true)\n          .catch((err: NodeJS.ErrnoException) => {\n            // Only treat ENOENT (file not found) as \"file doesn't exist\"\n            // Other errors (EACCES, EMFILE, etc.) are treated as \"file exists\" to avoid false negatives\n            if (err.code === \"ENOENT\") {\n              return false;\n            }\n            // For permission errors and other issues, assume file exists to be conservative\n            return true;\n          })\n      );\n    }\n\n    if (elementsWithoutSourceRef > 0) {\n      console.warn(\n        `\\nWarning: ${elementsWithoutSourceRef} API model element(s) excluded from drift detection` +\n        ` \u2014 they have no source_reference with a file location.\\n` +\n        `  Drift detection requires a linked source file to compare against the code graph.\\n` +\n        `  Fix: dr update <element-id> --source-file <relative-path> --source-symbol <symbol>\\n` +\n        `  Elements ingested via /dr-map or dr analyzer endpoints are automatically attributed.\\n`\n      );\n    }\n\n    if (elementsWithNonIndexableSource > 0) {\n      console.warn(\n        `\\nWarning: ${elementsWithNonIndexableSource} API model element(s) excluded from drift detection` +\n        ` \u2014 their source files are not indexable source-code files.\\n` +\n        `  Point source_reference to a source-code file (.ts, .js, .py, etc.) for drift detection,\\n` +\n        `  or use dr analyzer endpoints to discover routes automatically.\\n`\n      );\n    }\n\n    // Wait for all file checks. All promises have .catch() handlers that return booleans,\n    // so they will never reject - Promise.all() is safe and simpler than allSettled.\n    const fileExistsResults = await Promise.all(fileChecks);\n\n    // Add to in_model_only only if file exists, then check against ignore rules\n    for (let i = 0; i < elementsToCheck.length; i++) {\n      const fileExists = fileExistsResults[i];\n\n      if (fileExists) {\n        const elem = elementsToCheck[i];\n\n        // Check if element matches any ignore rule\n        // Use element.path (semantic path) instead of elem.id (UUID)\n        const ignoreReason = IgnoreFileLoader.matches(\n          {\n            element_id: elem.path,\n          },\n          \"element\",\n          ignoreRules\n        );\n\n        if (ignoreReason) {\n          ignored.push({\n            id: elem.id,\n            entry_type: \"element\",\n            reason: ignoreReason,\n          });\n        } else {\n          inModelOnly.push({\n            id: elem.id,\n            type: \"operation\",\n            source_file: elem.file,\n            source_symbol: elem.symbol,\n          });\n        }\n      }\n    }\n\n    // Step 5: Assemble report\n    const buckets: VerifyBuckets = {\n      matched,\n      in_graph_only: inGraphOnly,\n      in_model_only: inModelOnly,\n      ignored,\n    };\n\n    return this.assembleReport(\n      projectRoot,\n      model,\n      buckets,\n      activeChangesetId,\n      options,\n      analyzerName,\n      indexMeta,\n      elementsWithoutSourceRef + elementsWithNonIndexableSource\n    );\n  }\n\n  /**\n   * Assemble the final verification report\n   *\n   * @private\n   */\n  private assembleReport(\n    projectRoot: string,\n    model: Model,\n    buckets: VerifyBuckets,\n    activeChangesetId: string | null,\n    options: VerifyOptions,\n    analyzerName: string = \"codebase-memory-mcp\",\n    indexMeta?: IndexMeta,\n    elementsWithoutSourceRef: number = 0\n  ): VerifyReport {\n    const matchedElements = buckets.matched.length;\n    const inModelOnly = buckets.in_model_only.length;\n    const ignoredElements = buckets.ignored.filter((e) => e.entry_type === \"element\").length;\n    const summary: VerifySummary = {\n      matched_count: matchedElements,\n      gap_count: buckets.in_graph_only.length,\n      drift_count: inModelOnly,\n      ignored_count: buckets.ignored.length,\n      total_graph_entries: matchedElements + buckets.in_graph_only.length + buckets.ignored.filter((e) => e.entry_type === \"route\").length,\n      // Count all API layer elements: those that participated in matching plus those\n      // excluded because they lack source_reference (documentation-only elements).\n      total_model_entries: matchedElements + inModelOnly + ignoredElements + elementsWithoutSourceRef,\n      elements_without_source_ref: elementsWithoutSourceRef,\n    };\n\n    // Determine changeset context\n    const changesetAware = options.changesetAware ?? true;\n    const hasActiveChangeset = changesetAware && activeChangesetId !== null;\n\n    // Use analyzer index timestamp if provided, otherwise fall back to model manifest modified time\n    const analyzerIndexedAt = indexMeta?.timestamp || model.manifest.modified;\n\n    // Construct changeset context as discriminated union\n    const changeset_context: VerifyChangesetContext = hasActiveChangeset\n      ? {\n          active_changeset: activeChangesetId,\n          verified_against: \"changeset_view\",\n        }\n      : {\n          active_changeset: null,\n          verified_against: \"base_model\",\n        };\n\n    const hints: string[] = [];\n    if (buckets.in_graph_only.length > 0) {\n      hints.push(\n        \"To close gaps with source attribution, use /dr-map or `dr analyzer endpoints` ingestion \u2014 \"\n        + \"manual `dr add` operations cannot be matched by the verifier.\"\n      );\n    }\n\n    return {\n      generated_at: new Date().toISOString(),\n      project_root: projectRoot,\n      analyzer: analyzerName,\n      analyzer_indexed_at: analyzerIndexedAt,\n      changeset_context,\n      layers_verified: [\"api\"],\n      buckets,\n      summary,\n      ...(hints.length > 0 ? { hints } : {}),\n    };\n  }\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/analyzers/verify-ignore.js

@@ -0,0 +1,130 @@
+import { readFile } from "fs/promises";
+import yaml from "yaml";
+import { minimatch } from "minimatch";
+class IgnoreFileLoader {
+  /**
+   * Load ignore rules from a YAML file
+   *
+   * Returns an empty array if the file doesn't exist (no error).
+   * Throws if the file exists but contains structural errors:
+   * - Invalid YAML syntax
+   * - Parsed YAML is not an object with version and ignore fields
+   * - version != 1
+   * - ignore is not an array
+   * - Rule missing required fields (patterns, reason, match)
+   * - Rule has unknown fields (only patterns, reason, match, element_ids allowed)
+   * - Pattern objects with unsupported fields (only handler, path allowed)
+   * - Invalid match values
+   * - element_ids not an array of strings
+   *
+   * @param filePath Path to the .dr-verify-ignore.yaml file
+   * @returns Array of validated ignore rules
+   * @throws Error on structural issues with the ignore file
+   */
+  static async load(filePath) {
+    try {
+      const content = await readFile(filePath, "utf-8"), parsed = yaml.parse(content);
+      if (!parsed || typeof parsed != "object")
+        throw new Error("Invalid ignore file: expected an object with 'version' and 'ignore' fields");
+      const { version, ignore } = parsed;
+      if (version !== 1)
+        throw new Error(`Invalid ignore file version: expected 1, got ${version ?? "missing"}`);
+      if (!Array.isArray(ignore))
+        throw new Error("Invalid ignore file: 'ignore' field must be an array of rules");
+      const rules = [];
+      for (let i = 0; i < ignore.length; i++) {
+        const ruleObj = ignore[i];
+        if (!ruleObj || typeof ruleObj != "object")
+          throw new Error(`Rule at index ${i} is not an object`);
+        const rule = ruleObj, reason = rule.reason, match = rule.match, patterns = rule.patterns, elementIds = rule.element_ids;
+        if (!reason || typeof reason != "string")
+          throw new Error(`Rule at index ${i} missing required field: 'reason' (must be a string)`);
+        if (!match || typeof match != "string")
+          throw new Error(`Rule at index ${i} missing required field: 'match' (must be a string)`);
+        if (match !== "graph_only" && match !== "model_only")
+          throw new Error(`Rule at index ${i} has invalid 'match' value: '${match}' (must be 'graph_only' or 'model_only')`);
+        if (!Array.isArray(patterns))
+          throw new Error(`Rule at index ${i} missing required field: 'patterns' (must be an array of pattern objects)`);
+        if (patterns.length === 0)
+          throw new Error(`Rule at index ${i} has empty 'patterns' array (must contain at least one pattern)`);
+        let normalizedElementIds;
+        if (elementIds !== void 0) {
+          if (!Array.isArray(elementIds))
+            throw new Error(`Rule at index ${i}: 'element_ids' must be an array`);
+          if (!elementIds.every((id) => typeof id == "string"))
+            throw new Error(`Rule at index ${i}: 'element_ids' must contain only strings`);
+          normalizedElementIds = elementIds;
+        }
+        const validRuleFields = /* @__PURE__ */ new Set(["patterns", "reason", "match", "element_ids"]);
+        for (const field of Object.keys(rule))
+          if (!validRuleFields.has(field))
+            throw new Error(`Rule at index ${i}: unknown field '${field}' (valid fields: patterns, reason, match, element_ids)`);
+        const normalizedPatterns = [];
+        for (let j = 0; j < patterns.length; j++) {
+          const patternObj = patterns[j];
+          if (!patternObj || typeof patternObj != "object")
+            throw new Error(`Rule at index ${i}, pattern at index ${j} is not an object`);
+          const pattern = patternObj, normalizedPattern = {};
+          if ("handler" in pattern) {
+            if (typeof pattern.handler != "string")
+              throw new Error(`Rule at index ${i}, pattern at index ${j}: 'handler' must be a string`);
+            normalizedPattern.handler = pattern.handler;
+          }
+          if ("path" in pattern) {
+            if (typeof pattern.path != "string")
+              throw new Error(`Rule at index ${i}, pattern at index ${j}: 'path' must be a string`);
+            normalizedPattern.path = pattern.path;
+          }
+          const validFields = /* @__PURE__ */ new Set(["handler", "path"]);
+          for (const field of Object.keys(pattern))
+            if (!validFields.has(field))
+              throw new Error(`Rule at index ${i}, pattern at index ${j}: unknown field '${field}' (valid fields: handler, path)`);
+          if (Object.keys(normalizedPattern).length === 0)
+            throw new Error(`Rule at index ${i}, pattern at index ${j} has no matching criteria (must have at least one of: handler, path)`);
+          normalizedPatterns.push(normalizedPattern);
+        }
+        const ignoreRule = {
+          patterns: normalizedPatterns,
+          reason,
+          match
+        };
+        normalizedElementIds !== void 0 && (ignoreRule.element_ids = normalizedElementIds), rules.push(ignoreRule);
+      }
+      return rules;
+    } catch (error) {
+      if (error.code === "ENOENT")
+        return [];
+      throw error;
+    }
+  }
+  /**
+   * Check if an entry matches any ignore rule and return the matching rule's reason
+   *
+   * Only considers rules that apply to the specified entry type:
+   * - "route" entries: only rules with match: "graph_only"
+   * - "element" entries: only rules with match: "model_only"
+   *
+   * A rule matches if ANY of its patterns match (OR semantics within patterns),
+   * or if the entry's element_id matches the rule's element_ids list.
+   *
+   * @param entry Object with optional handler, path, and element_id properties
+   * @param type Type of entry ("route" for graph entries, "element" for model entries)
+   * @param rules Array of ignore rules
+   * @returns The reason string from the matched rule, or null if no match
+   */
+  static matches(entry, type, rules) {
+    for (const rule of rules)
+      if (!(type === "route" && rule.match !== "graph_only") && !(type === "element" && rule.match !== "model_only")) {
+        if (rule.element_ids && entry.element_id && rule.element_ids.includes(entry.element_id))
+          return rule.reason;
+        for (const pattern of rule.patterns)
+          if (pattern.handler && entry.handler && minimatch(entry.handler, pattern.handler) || pattern.path && entry.path && entry.path === pattern.path)
+            return rule.reason;
+      }
+    return null;
+  }
+}
+export {
+  IgnoreFileLoader
+};
+//# sourceMappingURL=verify-ignore.js.map

package/dist/analyzers/verify-ignore.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/analyzers/verify-ignore.ts"],
+  "sourcesContent": ["/**\n * Ignore file loader for verify operations\n *\n * Parses .dr-verify-ignore.yaml and provides pattern matching for routes/elements\n * to exclude from verification reports.\n */\n\nimport { readFile } from \"fs/promises\";\nimport yaml from \"yaml\";\nimport { minimatch } from \"minimatch\";\n\n/**\n * A pattern within an ignore rule\n *\n * Each pattern object contains one or more matching criteria.\n */\nexport interface IgnorePattern {\n  handler?: string;\n  path?: string;\n}\n\n/**\n * A single ignore rule from the ignore file\n *\n * Rules must specify:\n * - patterns: list of matching criteria (OR semantics - any match applies the rule)\n * - reason: explanation for why the rule exists\n * - match: scope of the rule (graph_only for routes, model_only for elements)\n *\n * Optional fields:\n * - element_ids: list of element IDs to ignore (only used with match: model_only)\n */\nexport interface IgnoreRule {\n  patterns: IgnorePattern[];\n  element_ids?: string[];\n  reason: string;\n  match: \"graph_only\" | \"model_only\";\n}\n\n/**\n * Loader for .dr-verify-ignore.yaml files\n *\n * Supports:\n * - Glob patterns for handler names (e.g., \"*HealthHandler*\")\n * - Exact matching for paths (e.g., \"/health\")\n * - Exact matching for element IDs (e.g., \"api.operation.get-health\")\n * - Bucket scoping via match field (graph_only for routes, model_only for elements)\n *\n * Expected YAML format:\n * ```yaml\n * version: 1\n * ignore:\n *   - patterns:\n *       - handler: \"*HealthHandler*\"\n *       - path: \"/health\"\n *     reason: \"Health check endpoints\"\n *     match: \"graph_only\"\n *   - patterns:\n *       - handler: \"*StatusHandler*\"\n *     element_ids: [\"api.operation.get-status\"]\n *     reason: \"Status endpoint ignored\"\n *     match: \"model_only\"\n * ```\n */\nexport class IgnoreFileLoader {\n  /**\n   * Load ignore rules from a YAML file\n   *\n   * Returns an empty array if the file doesn't exist (no error).\n   * Throws if the file exists but contains structural errors:\n   * - Invalid YAML syntax\n   * - Parsed YAML is not an object with version and ignore fields\n   * - version != 1\n   * - ignore is not an array\n   * - Rule missing required fields (patterns, reason, match)\n   * - Rule has unknown fields (only patterns, reason, match, element_ids allowed)\n   * - Pattern objects with unsupported fields (only handler, path allowed)\n   * - Invalid match values\n   * - element_ids not an array of strings\n   *\n   * @param filePath Path to the .dr-verify-ignore.yaml file\n   * @returns Array of validated ignore rules\n   * @throws Error on structural issues with the ignore file\n   */\n  static async load(filePath: string): Promise<IgnoreRule[]> {\n    try {\n      const content = await readFile(filePath, \"utf-8\");\n      const parsed = yaml.parse(content);\n\n      // Validate schema: expect version 1 and an ignore array\n      if (!parsed || typeof parsed !== \"object\") {\n        throw new Error(\n          \"Invalid ignore file: expected an object with 'version' and 'ignore' fields\"\n        );\n      }\n\n      const { version, ignore } = parsed as { version?: number; ignore?: unknown[] };\n\n      if (version !== 1) {\n        throw new Error(\n          `Invalid ignore file version: expected 1, got ${version ?? \"missing\"}`\n        );\n      }\n\n      if (!Array.isArray(ignore)) {\n        throw new Error(\n          \"Invalid ignore file: 'ignore' field must be an array of rules\"\n        );\n      }\n\n      // Validate and collect rules\n      const rules: IgnoreRule[] = [];\n      for (let i = 0; i < ignore.length; i++) {\n        const ruleObj = ignore[i];\n\n        // Validate rule is an object\n        if (!ruleObj || typeof ruleObj !== \"object\") {\n          throw new Error(\n            `Rule at index ${i} is not an object`\n          );\n        }\n\n        const rule = ruleObj as any;\n        const reason = rule.reason as string | undefined;\n        const match = rule.match as string | undefined;\n        const patterns = rule.patterns as unknown[] | undefined;\n        const elementIds = rule.element_ids as unknown[] | undefined;\n\n        // Validate required fields\n        if (!reason || typeof reason !== \"string\") {\n          throw new Error(\n            `Rule at index ${i} missing required field: 'reason' (must be a string)`\n          );\n        }\n\n        if (!match || typeof match !== \"string\") {\n          throw new Error(\n            `Rule at index ${i} missing required field: 'match' (must be a string)`\n          );\n        }\n\n        if (match !== \"graph_only\" && match !== \"model_only\") {\n          throw new Error(\n            `Rule at index ${i} has invalid 'match' value: '${match}' (must be 'graph_only' or 'model_only')`\n          );\n        }\n\n        if (!Array.isArray(patterns)) {\n          throw new Error(\n            `Rule at index ${i} missing required field: 'patterns' (must be an array of pattern objects)`\n          );\n        }\n\n        if (patterns.length === 0) {\n          throw new Error(\n            `Rule at index ${i} has empty 'patterns' array (must contain at least one pattern)`\n          );\n        }\n\n        // Validate element_ids if present\n        let normalizedElementIds: string[] | undefined;\n        if (elementIds !== undefined) {\n          if (!Array.isArray(elementIds)) {\n            throw new Error(\n              `Rule at index ${i}: 'element_ids' must be an array`\n            );\n          }\n          if (!elementIds.every((id: unknown) => typeof id === \"string\")) {\n            throw new Error(\n              `Rule at index ${i}: 'element_ids' must contain only strings`\n            );\n          }\n          normalizedElementIds = elementIds;\n        }\n\n        // Check for unknown fields at rule level\n        const validRuleFields = new Set([\"patterns\", \"reason\", \"match\", \"element_ids\"]);\n        for (const field of Object.keys(rule)) {\n          if (!validRuleFields.has(field)) {\n            throw new Error(\n              `Rule at index ${i}: unknown field '${field}' (valid fields: patterns, reason, match, element_ids)`\n            );\n          }\n        }\n\n        // Validate and normalize patterns\n        const normalizedPatterns: IgnorePattern[] = [];\n        for (let j = 0; j < patterns.length; j++) {\n          const patternObj = patterns[j];\n\n          if (!patternObj || typeof patternObj !== \"object\") {\n            throw new Error(\n              `Rule at index ${i}, pattern at index ${j} is not an object`\n            );\n          }\n\n          const pattern = patternObj as any;\n          const normalizedPattern: IgnorePattern = {};\n\n          // Extract handler if present\n          if (\"handler\" in pattern) {\n            if (typeof pattern.handler !== \"string\") {\n              throw new Error(\n                `Rule at index ${i}, pattern at index ${j}: 'handler' must be a string`\n              );\n            }\n            normalizedPattern.handler = pattern.handler;\n          }\n\n          // Extract path if present\n          if (\"path\" in pattern) {\n            if (typeof pattern.path !== \"string\") {\n              throw new Error(\n                `Rule at index ${i}, pattern at index ${j}: 'path' must be a string`\n              );\n            }\n            normalizedPattern.path = pattern.path;\n          }\n\n          // Check for unknown fields (element_ids should not be in patterns)\n          const validFields = new Set([\"handler\", \"path\"]);\n          for (const field of Object.keys(pattern)) {\n            if (!validFields.has(field)) {\n              throw new Error(\n                `Rule at index ${i}, pattern at index ${j}: unknown field '${field}' (valid fields: handler, path)`\n              );\n            }\n          }\n\n          // At least one matching criterion must be present\n          if (Object.keys(normalizedPattern).length === 0) {\n            throw new Error(\n              `Rule at index ${i}, pattern at index ${j} has no matching criteria (must have at least one of: handler, path)`\n            );\n          }\n\n          normalizedPatterns.push(normalizedPattern);\n        }\n\n        const ignoreRule: IgnoreRule = {\n          patterns: normalizedPatterns,\n          reason,\n          match,\n        };\n\n        if (normalizedElementIds !== undefined) {\n          ignoreRule.element_ids = normalizedElementIds;\n        }\n\n        rules.push(ignoreRule);\n      }\n\n      return rules;\n    } catch (error) {\n      // File not found is expected (return empty rules, no error)\n      const err = error as NodeJS.ErrnoException;\n      if (err.code === \"ENOENT\") {\n        return [];\n      }\n\n      // YAML parse errors and validation errors should be thrown\n      throw error;\n    }\n  }\n\n  /**\n   * Check if an entry matches any ignore rule and return the matching rule's reason\n   *\n   * Only considers rules that apply to the specified entry type:\n   * - \"route\" entries: only rules with match: \"graph_only\"\n   * - \"element\" entries: only rules with match: \"model_only\"\n   *\n   * A rule matches if ANY of its patterns match (OR semantics within patterns),\n   * or if the entry's element_id matches the rule's element_ids list.\n   *\n   * @param entry Object with optional handler, path, and element_id properties\n   * @param type Type of entry (\"route\" for graph entries, \"element\" for model entries)\n   * @param rules Array of ignore rules\n   * @returns The reason string from the matched rule, or null if no match\n   */\n  static matches(\n    entry: { handler?: string; path?: string; element_id?: string },\n    type: \"route\" | \"element\",\n    rules: IgnoreRule[]\n  ): string | null {\n    for (const rule of rules) {\n      // Filter by match bucket type\n      if (type === \"route\" && rule.match !== \"graph_only\") {\n        continue;\n      }\n      if (type === \"element\" && rule.match !== \"model_only\") {\n        continue;\n      }\n\n      // Check rule-level element_ids (exact match)\n      if (rule.element_ids && entry.element_id) {\n        if (rule.element_ids.includes(entry.element_id)) {\n          return rule.reason;\n        }\n      }\n\n      // Check if any pattern in this rule matches (OR semantics)\n      for (const pattern of rule.patterns) {\n        // Check handler glob pattern\n        if (pattern.handler && entry.handler) {\n          if (minimatch(entry.handler, pattern.handler)) {\n            return rule.reason;\n          }\n        }\n\n        // Check path exact match\n        if (pattern.path && entry.path) {\n          if (entry.path === pattern.path) {\n            return rule.reason;\n          }\n        }\n      }\n    }\n\n    return null;\n  }\n}\n"],
+  "mappings": "AAOA,SAAS,gBAAgB;AACzB,OAAO,UAAU;AACjB,SAAS,iBAAiB;AAuDpB,MAAO,iBAAgB;;;;;;;;;;;;;;;;;;;;EAoB3B,aAAa,KAAK,UAAgB;AAChC,QAAI;AACF,YAAM,UAAU,MAAM,SAAS,UAAU,OAAO,GAC1C,SAAS,KAAK,MAAM,OAAO;AAGjC,UAAI,CAAC,UAAU,OAAO,UAAW;AAC/B,cAAM,IAAI,MACR,4EAA4E;AAIhF,YAAM,EAAE,SAAS,OAAM,IAAK;AAE5B,UAAI,YAAY;AACd,cAAM,IAAI,MACR,gDAAgD,WAAW,SAAS,EAAE;AAI1E,UAAI,CAAC,MAAM,QAAQ,MAAM;AACvB,cAAM,IAAI,MACR,+DAA+D;AAKnE,YAAM,QAAsB,CAAA;AAC5B,eAAS,IAAI,GAAG,IAAI,OAAO,QAAQ,KAAK;AACtC,cAAM,UAAU,OAAO,CAAC;AAGxB,YAAI,CAAC,WAAW,OAAO,WAAY;AACjC,gBAAM,IAAI,MACR,iBAAiB,CAAC,mBAAmB;AAIzC,cAAM,OAAO,SACP,SAAS,KAAK,QACd,QAAQ,KAAK,OACb,WAAW,KAAK,UAChB,aAAa,KAAK;AAGxB,YAAI,CAAC,UAAU,OAAO,UAAW;AAC/B,gBAAM,IAAI,MACR,iBAAiB,CAAC,sDAAsD;AAI5E,YAAI,CAAC,SAAS,OAAO,SAAU;AAC7B,gBAAM,IAAI,MACR,iBAAiB,CAAC,qDAAqD;AAI3E,YAAI,UAAU,gBAAgB,UAAU;AACtC,gBAAM,IAAI,MACR,iBAAiB,CAAC,gCAAgC,KAAK,0CAA0C;AAIrG,YAAI,CAAC,MAAM,QAAQ,QAAQ;AACzB,gBAAM,IAAI,MACR,iBAAiB,CAAC,2EAA2E;AAIjG,YAAI,SAAS,WAAW;AACtB,gBAAM,IAAI,MACR,iBAAiB,CAAC,iEAAiE;AAKvF,YAAI;AACJ,YAAI,eAAe,QAAW;AAC5B,cAAI,CAAC,MAAM,QAAQ,UAAU;AAC3B,kBAAM,IAAI,MACR,iBAAiB,CAAC,kCAAkC;AAGxD,cAAI,CAAC,WAAW,MAAM,CAAC,OAAgB,OAAO,MAAO,QAAQ;AAC3D,kBAAM,IAAI,MACR,iBAAiB,CAAC,2CAA2C;AAGjE,iCAAuB;QACzB;AAGA,cAAM,kBAAkB,oBAAI,IAAI,CAAC,YAAY,UAAU,SAAS,aAAa,CAAC;AAC9E,mBAAW,SAAS,OAAO,KAAK,IAAI;AAClC,cAAI,CAAC,gBAAgB,IAAI,KAAK;AAC5B,kBAAM,IAAI,MACR,iBAAiB,CAAC,oBAAoB,KAAK,wDAAwD;AAMzG,cAAM,qBAAsC,CAAA;AAC5C,iBAAS,IAAI,GAAG,IAAI,SAAS,QAAQ,KAAK;AACxC,gBAAM,aAAa,SAAS,CAAC;AAE7B,cAAI,CAAC,cAAc,OAAO,cAAe;AACvC,kBAAM,IAAI,MACR,iBAAiB,CAAC,sBAAsB,CAAC,mBAAmB;AAIhE,gBAAM,UAAU,YACV,oBAAmC,CAAA;AAGzC,cAAI,aAAa,SAAS;AACxB,gBAAI,OAAO,QAAQ,WAAY;AAC7B,oBAAM,IAAI,MACR,iBAAiB,CAAC,sBAAsB,CAAC,8BAA8B;AAG3E,8BAAkB,UAAU,QAAQ;UACtC;AAGA,cAAI,UAAU,SAAS;AACrB,gBAAI,OAAO,QAAQ,QAAS;AAC1B,oBAAM,IAAI,MACR,iBAAiB,CAAC,sBAAsB,CAAC,2BAA2B;AAGxE,8BAAkB,OAAO,QAAQ;UACnC;AAGA,gBAAM,cAAc,oBAAI,IAAI,CAAC,WAAW,MAAM,CAAC;AAC/C,qBAAW,SAAS,OAAO,KAAK,OAAO;AACrC,gBAAI,CAAC,YAAY,IAAI,KAAK;AACxB,oBAAM,IAAI,MACR,iBAAiB,CAAC,sBAAsB,CAAC,oBAAoB,KAAK,iCAAiC;AAMzG,cAAI,OAAO,KAAK,iBAAiB,EAAE,WAAW;AAC5C,kBAAM,IAAI,MACR,iBAAiB,CAAC,sBAAsB,CAAC,sEAAsE;AAInH,6BAAmB,KAAK,iBAAiB;QAC3C;AAEA,cAAM,aAAyB;UAC7B,UAAU;UACV;UACA;;AAGF,QAAI,yBAAyB,WAC3B,WAAW,cAAc,uBAG3B,MAAM,KAAK,UAAU;MACvB;AAEA,aAAO;IACT,SAAS,OAAO;AAGd,UADY,MACJ,SAAS;AACf,eAAO,CAAA;AAIT,YAAM;IACR;EACF;;;;;;;;;;;;;;;;EAiBA,OAAO,QACL,OACA,MACA,OAAmB;AAEnB,eAAW,QAAQ;AAEjB,UAAI,WAAS,WAAW,KAAK,UAAU,iBAGnC,WAAS,aAAa,KAAK,UAAU,eAKzC;YAAI,KAAK,eAAe,MAAM,cACxB,KAAK,YAAY,SAAS,MAAM,UAAU;AAC5C,iBAAO,KAAK;AAKhB,mBAAW,WAAW,KAAK;AASzB,cAPI,QAAQ,WAAW,MAAM,WACvB,UAAU,MAAM,SAAS,QAAQ,OAAO,KAM1C,QAAQ,QAAQ,MAAM,QACpB,MAAM,SAAS,QAAQ;AACzB,mBAAO,KAAK;;AAMpB,WAAO;EACT;;",
+  "names": []
+}

package/dist/analyzers/version.js

@@ -0,0 +1,8 @@
+import { getCliVersion as getCliVersionImpl } from "../utils/spec-version.js";
+async function getCliVersion() {
+  return getCliVersionImpl();
+}
+export {
+  getCliVersion
+};
+//# sourceMappingURL=version.js.map

package/dist/analyzers/version.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/analyzers/version.ts"],
+  "sourcesContent": ["/**\n * CLI Version - used by analyzers for MCP client initialization\n *\n * Re-exports the CLI version from spec-version.ts, which is the single source of truth.\n * This ensures consistency across all components (CLI commands, integrations, analyzers).\n */\n\nimport { getCliVersion as getCliVersionImpl } from \"../utils/spec-version.js\";\n\n/**\n * Get the CLI version for analyzer initialization\n * Wrapped as async for compatibility with existing analyzer code,\n * but delegates to the synchronous source-of-truth in spec-version.ts\n */\nexport async function getCliVersion(): Promise<string> {\n  return getCliVersionImpl();\n}\n"],
+  "mappings": "AAOA,SAAS,iBAAiB,yBAAyB;AAOnD,eAAsB,gBAAa;AACjC,SAAO,kBAAiB;AAC1B;",
+  "names": []
+}

package/dist/audit/ai/runner.js

@@ -0,0 +1,41 @@
+import { invokeClaudeStreaming } from "../../utils/claude-stream.js";
+class AIEvaluationAbortError extends Error {
+  constructor(maxFailures, cause) {
+    super(`AI evaluation aborted after ${maxFailures} consecutive failures. Is Claude CLI installed and authenticated? Run 'claude --version' to verify.`, { cause }), this.name = "AIEvaluationAbortError";
+  }
+}
+class AuditAIRunner {
+  rateLimitMs;
+  maxConsecutiveFailures;
+  consecutiveFailures = 0;
+  constructor(rateLimitMs = 1500, maxConsecutiveFailures = 3) {
+    this.rateLimitMs = rateLimitMs, this.maxConsecutiveFailures = maxConsecutiveFailures;
+  }
+  /**
+   * Invoke Claude with a prompt, streaming output and returning the response text.
+   * Adds a rate-limiting delay after each successful invocation.
+   * Throws AIEvaluationAbortError after maxConsecutiveFailures consecutive failures.
+   */
+  async invoke(prompt, label, timeoutMs) {
+    try {
+      const invocation = invokeClaudeStreaming(prompt), result = timeoutMs ? await Promise.race([
+        invocation,
+        this.rejectAfter(timeoutMs, label ?? "AI invocation")
+      ]) : await invocation;
+      return this.consecutiveFailures = 0, await this.delay(this.rateLimitMs), result;
+    } catch (error) {
+      throw this.consecutiveFailures++, this.consecutiveFailures >= this.maxConsecutiveFailures ? new AIEvaluationAbortError(this.maxConsecutiveFailures, error) : error;
+    }
+  }
+  delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+  rejectAfter(ms, label) {
+    return new Promise((_, reject) => setTimeout(() => reject(new Error(`${label} timed out after ${ms}ms`)), ms));
+  }
+}
+export {
+  AIEvaluationAbortError,
+  AuditAIRunner
+};
+//# sourceMappingURL=runner.js.map

package/dist/audit/ai/runner.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/audit/ai/runner.ts"],
+  "sourcesContent": ["import { invokeClaudeStreaming } from \"../../utils/claude-stream.js\";\n\n/**\n * Thrown by AuditAIRunner when consecutive failure limit is reached.\n * Use `instanceof AIEvaluationAbortError` in catch blocks to distinguish\n * this hard abort from transient per-item failures.\n */\nexport class AIEvaluationAbortError extends Error {\n  constructor(maxFailures: number, cause: unknown) {\n    super(\n      `AI evaluation aborted after ${maxFailures} consecutive failures. ` +\n        `Is Claude CLI installed and authenticated? Run 'claude --version' to verify.`,\n      { cause }\n    );\n    this.name = \"AIEvaluationAbortError\";\n  }\n}\n\n/**\n * Shared AI invocation runner for audit evaluators.\n * Wraps invokeClaudeStreaming with rate limiting and fail-fast on consecutive failures.\n */\nexport class AuditAIRunner {\n  private consecutiveFailures = 0;\n\n  constructor(\n    private readonly rateLimitMs: number = 1500,\n    private readonly maxConsecutiveFailures: number = 3\n  ) {}\n\n  /**\n   * Invoke Claude with a prompt, streaming output and returning the response text.\n   * Adds a rate-limiting delay after each successful invocation.\n   * Throws AIEvaluationAbortError after maxConsecutiveFailures consecutive failures.\n   */\n  async invoke(prompt: string, label?: string, timeoutMs?: number): Promise<string> {\n    try {\n      const invocation = invokeClaudeStreaming(prompt);\n      const result = timeoutMs\n        ? await Promise.race([\n            invocation,\n            this.rejectAfter(timeoutMs, label ?? \"AI invocation\"),\n          ])\n        : await invocation;\n      this.consecutiveFailures = 0;\n      await this.delay(this.rateLimitMs);\n      return result;\n    } catch (error: unknown) {\n      this.consecutiveFailures++;\n      if (this.consecutiveFailures >= this.maxConsecutiveFailures) {\n        throw new AIEvaluationAbortError(this.maxConsecutiveFailures, error);\n      }\n      throw error;\n    }\n  }\n\n  private delay(ms: number): Promise<void> {\n    return new Promise((resolve) => setTimeout(resolve, ms));\n  }\n\n  private rejectAfter(ms: number, label: string): Promise<never> {\n    return new Promise((_, reject) =>\n      setTimeout(() => reject(new Error(`${label} timed out after ${ms}ms`)), ms)\n    );\n  }\n}\n"],
+  "mappings": "AAAA,SAAS,6BAA6B;AAOhC,MAAO,+BAA+B,MAAK;EAC/C,YAAY,aAAqB,OAAc;AAC7C,UACE,+BAA+B,WAAW,uGAE1C,EAAE,MAAK,CAAE,GAEX,KAAK,OAAO;EACd;;AAOI,MAAO,cAAa;EAIL;EACA;EAJX,sBAAsB;EAE9B,YACmB,cAAsB,MACtB,yBAAiC,GAAC;AADlC,SAAA,cAAA,aACA,KAAA,yBAAA;EAChB;;;;;;EAOH,MAAM,OAAO,QAAgB,OAAgB,WAAkB;AAC7D,QAAI;AACF,YAAM,aAAa,sBAAsB,MAAM,GACzC,SAAS,YACX,MAAM,QAAQ,KAAK;QACjB;QACA,KAAK,YAAY,WAAW,SAAS,eAAe;OACrD,IACD,MAAM;AACV,kBAAK,sBAAsB,GAC3B,MAAM,KAAK,MAAM,KAAK,WAAW,GAC1B;IACT,SAAS,OAAgB;AAEvB,YADA,KAAK,uBACD,KAAK,uBAAuB,KAAK,yBAC7B,IAAI,uBAAuB,KAAK,wBAAwB,KAAK,IAE/D;IACR;EACF;EAEQ,MAAM,IAAU;AACtB,WAAO,IAAI,QAAQ,CAAC,YAAY,WAAW,SAAS,EAAE,CAAC;EACzD;EAEQ,YAAY,IAAY,OAAa;AAC3C,WAAO,IAAI,QAAQ,CAAC,GAAG,WACrB,WAAW,MAAM,OAAO,IAAI,MAAM,GAAG,KAAK,oBAAoB,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC;EAE/E;;",
+  "names": []
+}