@saptools/service-flow 0.1.47 → 0.1.49

package/dist/cli.js

@@ -15,13 +15,12 @@ import {
   parsePackageJson,
   parseServiceBindings,
   trace
-} from "./chunk-EGY2A4AT.js";
+} from "./chunk-XOROZHW4.js";
 
 // src/cli.ts
 import { Command } from "commander";
 import path6 from "path";
 import fs6 from "fs/promises";
-import pc from "picocolors";
 
 // src/config/defaults.ts
 var DEFAULT_IGNORES = [
@@ -211,7 +210,7 @@ function migrate(db) {
 // package.json
 var package_default = {
   name: "@saptools/service-flow",
-  version: "0.1.47",
+  version: "0.1.49",
   description: "Trace SAP CAP service-to-service flows across multi-repository workspaces with runtime-aware graph resolution",
   type: "module",
   publishConfig: {
@@ -555,11 +554,15 @@ function insertRegistrations(db, repoId, rows) {
 }
 function insertBindings(db, repoId, rows) {
   const stmt = db.prepare(
-    "INSERT INTO service_bindings(repo_id,variable_name,alias,alias_expr,destination_expr,service_path_expr,is_dynamic,placeholders_json,source_file,source_line,helper_chain_json) VALUES(?,?,?,?,?,?,?,?,?,?,?)"
+    "INSERT INTO service_bindings(repo_id,symbol_id,variable_name,alias,alias_expr,destination_expr,service_path_expr,is_dynamic,placeholders_json,source_file,source_line,helper_chain_json) VALUES(?,(SELECT id FROM symbols WHERE repo_id=? AND source_file=? AND start_line<=? AND end_line>=? ORDER BY (end_line-start_line),id LIMIT 1),?,?,?,?,?,?,?,?,?,?)"
   );
   for (const r of rows)
     stmt.run(
       repoId,
+      repoId,
+      r.sourceFile,
+      r.sourceLine,
+      r.sourceLine,
       r.variableName,
       r.alias,
       r.aliasExpr,
@@ -613,9 +616,14 @@ function resolveSymbolCallTarget(db, repoId, r) {
 }
 function insertCalls(db, repoId, rows) {
   const stmt = db.prepare(
-    "INSERT INTO outbound_calls(repo_id,source_symbol_id,call_type,method,operation_path_expr,query_entity,event_name_expr,payload_summary,source_file,source_line,confidence,unresolved_reason,local_service_name,local_service_lookup,alias_chain_json,evidence_json,external_target_kind,external_target_id,external_target_label,external_target_dynamic,service_binding_id) VALUES(?,COALESCE((SELECT id FROM symbols WHERE repo_id=? AND source_file=? AND qualified_name=? ORDER BY id LIMIT 1),(SELECT id FROM symbols WHERE repo_id=? AND source_file=? AND start_line<=? AND end_line>=? ORDER BY (end_line-start_line),id LIMIT 1)),?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,(SELECT id FROM service_bindings WHERE repo_id=? AND variable_name=? AND source_file=? ORDER BY CASE WHEN source_line<=? THEN 0 ELSE 1 END, ABS(source_line-?) ASC, id DESC LIMIT 1))"
+    "INSERT INTO outbound_calls(repo_id,source_symbol_id,call_type,method,operation_path_expr,query_entity,event_name_expr,payload_summary,source_file,source_line,confidence,unresolved_reason,local_service_name,local_service_lookup,alias_chain_json,evidence_json,external_target_kind,external_target_id,external_target_label,external_target_dynamic,service_binding_id) VALUES(?,COALESCE((SELECT id FROM symbols WHERE repo_id=? AND source_file=? AND qualified_name=? ORDER BY id LIMIT 1),(SELECT id FROM symbols WHERE repo_id=? AND source_file=? AND start_line<=? AND end_line>=? ORDER BY (end_line-start_line),id LIMIT 1)),?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)"
   );
-  for (const r of rows)
+  for (const r of rows) {
+    const binding = resolvePersistedBinding(db, repoId, r);
+    const evidence = {
+      ...r.evidence ?? {},
+      serviceBindingResolution: binding.evidence
+    };
     stmt.run(
       repoId,
       repoId,
@@ -634,21 +642,146 @@ function insertCalls(db, repoId, rows) {
       r.sourceFile,
       r.sourceLine,
       r.confidence,
-      r.unresolvedReason,
+      r.unresolvedReason ?? binding.unresolvedReason,
       r.localServiceName,
       r.localServiceLookup,
       r.aliasChain ? JSON.stringify(r.aliasChain) : null,
-      r.evidence ? JSON.stringify(r.evidence) : null,
+      JSON.stringify(evidence),
       r.externalTarget?.kind ?? null,
       r.externalTarget?.stableId ?? null,
       r.externalTarget?.label ?? null,
       r.externalTarget?.dynamic ? 1 : 0,
-      repoId,
-      r.serviceVariableName,
-      r.sourceFile,
-      r.sourceLine,
-      r.sourceLine
+      binding.bindingId
     );
+  }
+}
+function resolvePersistedBinding(db, repoId, call) {
+  if (!call.serviceVariableName)
+    return { bindingId: null, evidence: { status: "not_applicable", candidateCount: 0 } };
+  const candidates = bindingCandidates(db, repoId, call);
+  const prior = candidates.filter((candidate) => candidate.sourceLine <= call.sourceLine);
+  const families = new Set(prior.map(bindingSignature));
+  if (prior.length > 0 && families.size === 1) {
+    const selected = prior.at(-1);
+    return {
+      bindingId: selected?.id ?? null,
+      evidence: bindingEvidence("selected", prior, selected)
+    };
+  }
+  if (prior.length > 1) {
+    return {
+      bindingId: null,
+      unresolvedReason: "ambiguous_service_binding_candidates",
+      evidence: bindingEvidence("ambiguous", prior)
+    };
+  }
+  if (candidates.length > 0) {
+    return {
+      bindingId: null,
+      unresolvedReason: "service_binding_declared_after_call",
+      evidence: bindingEvidence("rejected_future_binding", candidates)
+    };
+  }
+  return {
+    bindingId: null,
+    evidence: bindingEvidence("unrecoverable", [])
+  };
+}
+function bindingCandidates(db, repoId, call) {
+  const ownerId = callSymbolId(db, repoId, call);
+  const rows = db.prepare(`
+    SELECT id,symbol_id symbolId,variable_name variableName,alias,alias_expr aliasExpr,
+      destination_expr destinationExpr,service_path_expr servicePathExpr,
+      source_file sourceFile,source_line sourceLine,helper_chain_json helperChainJson
+    FROM service_bindings
+    WHERE repo_id=? AND variable_name=? AND source_file=?
+      AND (? IS NULL OR symbol_id IS NULL OR symbol_id=?)
+    ORDER BY source_line,id
+  `).all(
+    repoId,
+    call.serviceVariableName,
+    call.sourceFile,
+    ownerId,
+    ownerId
+  );
+  return rows.flatMap((row) => {
+    if (typeof row.id !== "number" || typeof row.variableName !== "string" || typeof row.sourceFile !== "string" || typeof row.sourceLine !== "number")
+      return [];
+    return [{
+      id: row.id,
+      symbolId: nullableNumber(row.symbolId),
+      variableName: row.variableName,
+      alias: nullableString(row.alias),
+      aliasExpr: nullableString(row.aliasExpr),
+      destinationExpr: nullableString(row.destinationExpr),
+      servicePathExpr: nullableString(row.servicePathExpr),
+      sourceFile: row.sourceFile,
+      sourceLine: row.sourceLine,
+      helperChainJson: nullableString(row.helperChainJson)
+    }];
+  });
+}
+function nullableString(value) {
+  return value === null || typeof value === "string" ? value : void 0;
+}
+function nullableNumber(value) {
+  return value === null || typeof value === "number" ? value : void 0;
+}
+function callSymbolId(db, repoId, call) {
+  const row = db.prepare(`
+    SELECT id FROM symbols
+    WHERE repo_id=? AND source_file=?
+      AND ((? IS NOT NULL AND qualified_name=?)
+        OR (start_line<=? AND end_line>=?))
+    ORDER BY CASE WHEN qualified_name=? THEN 0 ELSE 1 END,
+      (end_line-start_line),id
+    LIMIT 1
+  `).get(
+    repoId,
+    call.sourceFile,
+    call.sourceSymbolQualifiedName,
+    call.sourceSymbolQualifiedName,
+    call.sourceLine,
+    call.sourceLine,
+    call.sourceSymbolQualifiedName
+  );
+  return typeof row?.id === "number" ? row.id : void 0;
+}
+function bindingEvidence(status, candidates, selected) {
+  return {
+    status,
+    candidateCount: candidates.length,
+    selectedBindingId: selected?.id,
+    sourceOrderRule: "binding_source_line_must_not_follow_call",
+    candidates: candidates.map((candidate) => ({
+      bindingId: candidate.id,
+      symbolId: candidate.symbolId,
+      variableName: candidate.variableName,
+      alias: candidate.alias,
+      aliasExpr: candidate.aliasExpr,
+      destinationExpr: candidate.destinationExpr,
+      servicePathExpr: candidate.servicePathExpr,
+      sourceFile: candidate.sourceFile,
+      sourceLine: candidate.sourceLine,
+      helperChain: parseBindingChain(candidate.helperChainJson)
+    }))
+  };
+}
+function bindingSignature(candidate) {
+  return JSON.stringify([
+    candidate.alias,
+    candidate.aliasExpr,
+    candidate.destinationExpr,
+    candidate.servicePathExpr
+  ]);
+}
+function parseBindingChain(value) {
+  if (!value) return void 0;
+  try {
+    return JSON.parse(value);
+  } catch {
+    return void 0;
+  }
 }
 
 // src/discovery/classify-repository.ts
@@ -1312,6 +1445,7 @@ function doctorDiagnostics(db, strict, options = {}) {
   return [
     ...diagnostics,
     ...healthDiagnostics(db, strict),
+    ...remoteTargetWithoutImplementationDiagnostics(db, strict, Boolean(options.detail)),
     ...localServiceDiagnostics(db, strict),
     ...schemaDriftDiagnostics(db, strict),
     ...analyzerVersionDiagnostics(db, strict),
@@ -1339,10 +1473,6 @@ function healthDiagnostics(db, strict) {
      SELECT 'warning','legacy_schema_weaker_foreign_keys','Legacy table lacks fresh-schema foreign-key metadata; rebuild the database or re-run init/index in a new database',NULL,NULL
      WHERE (SELECT COUNT(*) FROM pragma_foreign_key_list('graph_edges'))=0 OR (SELECT COUNT(*) FROM pragma_foreign_key_list('index_runs'))=0 OR (SELECT COUNT(*) FROM pragma_foreign_key_list('diagnostics'))=0
      UNION ALL
-     SELECT 'warning','remote_target_without_implementation','Remote target operation has no implementation edge: ' || s.service_path || o.operation_path,o.source_file,o.source_line
-     FROM graph_edges remote JOIN cds_operations o ON o.id=CAST(remote.to_id AS INTEGER) JOIN cds_services s ON s.id=o.service_id
-     WHERE remote.edge_type='REMOTE_CALL_RESOLVES_TO_OPERATION' AND remote.to_kind='operation' AND NOT EXISTS (SELECT 1 FROM graph_edges impl WHERE impl.edge_type='OPERATION_IMPLEMENTED_BY_HANDLER' AND impl.from_kind='operation' AND impl.from_id=remote.to_id) AND ?
-     UNION ALL
      SELECT CASE WHEN ? THEN 'warning' ELSE 'error' END,'local_service_calls_all_unresolved','All local service calls are unresolved; verify local service alias parsing and linking',NULL,NULL
      WHERE EXISTS (SELECT 1 FROM outbound_calls WHERE call_type='local_service_call') AND NOT EXISTS (SELECT 1 FROM graph_edges e JOIN outbound_calls c ON e.from_kind='call' AND c.id=CAST(e.from_id AS INTEGER) WHERE c.call_type='local_service_call' AND e.status='resolved')
      UNION ALL
@@ -1360,7 +1490,41 @@ function healthDiagnostics(db, strict) {
      UNION ALL
      SELECT 'warning','index_run_abandoned','Index run ' || id || ' started at ' || started_at || ' is still running after the 60 minute abandonment threshold',NULL,NULL
      FROM index_runs WHERE status='running' AND datetime(started_at) < datetime('now','-60 minutes')`
-  ).all(strict, strict, strict, strict, strict, strict, strict);
+  ).all(strict, strict, strict, strict, strict, strict);
+}
+function remoteTargetWithoutImplementationDiagnostics(db, strict, detail) {
+  if (!strict) return [];
+  const groups = db.prepare(`SELECT s.service_path servicePath,o.operation_path operationPath,o.source_file sourceFile,o.source_line sourceLine,COUNT(*) callSiteCount
+    FROM graph_edges remote JOIN cds_operations o ON o.id=CAST(remote.to_id AS INTEGER) JOIN cds_services s ON s.id=o.service_id
+    WHERE remote.edge_type='REMOTE_CALL_RESOLVES_TO_OPERATION' AND remote.to_kind='operation'
+      AND NOT EXISTS (SELECT 1 FROM graph_edges impl WHERE impl.edge_type='OPERATION_IMPLEMENTED_BY_HANDLER' AND impl.from_kind='operation' AND impl.from_id=remote.to_id)
+    GROUP BY s.service_path,o.operation_path,o.source_file,o.source_line
+    ORDER BY s.service_path,o.operation_path`).all();
+  return groups.map((group) => {
+    const examples = remoteTargetWithoutImplementationExamples(db, String(group.servicePath ?? ""), String(group.operationPath ?? ""));
+    return {
+      severity: "warning",
+      code: "remote_target_without_implementation",
+      message: `Remote target operation has no implementation edge: ${String(group.servicePath ?? "")}${String(group.operationPath ?? "")}`,
+      sourceFile: group.sourceFile,
+      sourceLine: group.sourceLine,
+      servicePath: group.servicePath,
+      operationPath: group.operationPath,
+      callSiteCount: Number(group.callSiteCount ?? 0),
+      examples: examples.slice(0, 3),
+      expandedExamples: detail ? examples : void 0
+    };
+  });
+}
+function remoteTargetWithoutImplementationExamples(db, servicePath, operationPath) {
+  return db.prepare(`SELECT r.name repo,c.source_file sourceFile,c.source_line sourceLine,c.operation_path_expr operationPathExpr
+    FROM graph_edges remote JOIN cds_operations o ON o.id=CAST(remote.to_id AS INTEGER) JOIN cds_services s ON s.id=o.service_id
+    LEFT JOIN outbound_calls c ON remote.from_kind='call' AND c.id=CAST(remote.from_id AS INTEGER)
+    LEFT JOIN repositories r ON r.id=c.repo_id
+    WHERE remote.edge_type='REMOTE_CALL_RESOLVES_TO_OPERATION' AND remote.to_kind='operation'
+      AND s.service_path=? AND o.operation_path=?
+      AND NOT EXISTS (SELECT 1 FROM graph_edges impl WHERE impl.edge_type='OPERATION_IMPLEMENTED_BY_HANDLER' AND impl.from_kind='operation' AND impl.from_id=remote.to_id)
+    ORDER BY r.name,c.source_file,c.source_line`).all(servicePath, operationPath);
 }
 function schemaDriftDiagnostics(db, strict) {
   if (!strict) return [];
@@ -1404,6 +1568,7 @@ function parserQualityDiagnostics(db, strict, options) {
     implementationCandidateQuality(db, Boolean(options.detail)),
     classInstanceNoiseQuality(db),
     contextualBindingPropagationQuality(db),
+    serviceBindingQuality(db, Boolean(options.detail)),
     nestedThisReceiverQuality(db),
     wrapperPathPropagationQuality(db),
     remoteQueryTargetQuality(db),
@@ -1598,6 +1763,83 @@ function contextualBindingPropagationQuality(db) {
   const opportunities = db.prepare("SELECT c.source_file sourceFile,c.source_line sourceLine,json_extract(c.evidence_json,'$.receiver') receiverName,c.operation_path_expr operationPath FROM outbound_calls c WHERE c.call_type='remote_action' AND json_extract(c.evidence_json,'$.receiver') IS NOT NULL AND c.service_binding_id IS NULL ORDER BY c.source_file,c.source_line LIMIT 8").all();
   return { severity: missing.count + opportunities.length > 0 ? "warning" : "info", code: "strict_contextual_binding_propagation_quality", message: "Contextual service-client propagation opportunities for trace-time helper resolution", calleeSymbolsMissingParameterMetadata: missing.count, traceTimeContextualOpportunities: opportunities.length, examples: opportunities };
 }
+function serviceBindingQuality(db, detail) {
+  const rows = db.prepare(`
+    SELECT c.source_file sourceFile,c.source_line sourceLine,
+      c.unresolved_reason unresolvedReason,c.evidence_json evidenceJson,
+      s.evidence_json symbolEvidenceJson
+    FROM outbound_calls c
+    LEFT JOIN symbols s ON s.id=c.source_symbol_id
+    WHERE c.call_type='remote_action'
+      AND c.operation_path_expr IS NOT NULL
+      AND c.service_binding_id IS NULL
+    ORDER BY c.source_file,c.source_line
+  `).all();
+  const groups = /* @__PURE__ */ new Map();
+  for (const row of rows) {
+    const category = bindingCategory(row);
+    groups.set(category, [...groups.get(category) ?? [], bindingExample(row)]);
+  }
+  const categories = [...groups.entries()].map(([category, examples]) => ({
+    category,
+    count: examples.length,
+    severity: "warning",
+    suggestedAction: bindingCategoryAction(category),
+    examples: examples.slice(0, 3),
+    expandedExamples: detail ? examples : void 0
+  }));
+  return {
+    severity: rows.length > 0 ? "warning" : "info",
+    code: "strict_service_binding_quality",
+    message: "Remote service-client binding quality aggregate",
+    total: rows.length,
+    categories
+  };
+}
+function bindingCategory(row) {
+  const evidence = parseObject(row.evidenceJson);
+  const resolution = parseObject(evidence.serviceBindingResolution);
+  if (resolution.status === "rejected_future_binding") return "direct_binding_missing";
+  if (resolution.status === "ambiguous") return "ambiguous_binding_candidates";
+  const receiver = evidence.receiver;
+  const symbolEvidence = parseObject(row.symbolEvidenceJson);
+  if (symbolHasReceiverParameter(symbolEvidence, receiver))
+    return "contextual_binding_recoverable";
+  if (!Array.isArray(symbolEvidence.parameterBindings))
+    return "missing_symbol_parameter_metadata";
+  return "unrecoverable_binding";
+}
+function symbolHasReceiverParameter(evidence, receiver) {
+  if (typeof receiver !== "string" || !Array.isArray(evidence.parameterBindings))
+    return false;
+  return asRecords(evidence.parameterBindings).some((binding) => {
+    if (binding.kind === "identifier") return binding.name === receiver;
+    if (binding.kind === "object_pattern")
+      return asRecords(binding.properties).some((property) => property.local === receiver);
+    return asRecords(binding.elements).some((element) => element.local === receiver);
+  });
+}
+function bindingExample(row) {
+  const evidence = parseObject(row.evidenceJson);
+  return {
+    sourceFile: row.sourceFile,
+    sourceLine: row.sourceLine,
+    receiver: evidence.receiver,
+    unresolvedReason: row.unresolvedReason,
+    bindingResolution: evidence.serviceBindingResolution
+  };
+}
+function bindingCategoryAction(category) {
+  if (category === "direct_binding_missing")
+    return "Move the binding before the call or bind the call to an earlier immutable client.";
+  if (category === "contextual_binding_recoverable")
+    return "Trace from the caller so parameter binding evidence can be applied.";
+  if (category === "ambiguous_binding_candidates")
+    return "Split mutable client alternatives or add a statically unique client assignment.";
+  if (category === "missing_symbol_parameter_metadata")
+    return "Use named or destructured parameters on an indexed helper symbol.";
+  return "Add a direct CAP client binding or statically provable helper-return binding.";
+}
 function wrapperPathPropagationQuality(db) {
   const examples = db.prepare("SELECT source_file sourceFile,source_line sourceLine,json_extract(evidence_json,'$.receiver') receiverName,json_extract(evidence_json,'$.operationPathExpression') pathIdentifier FROM outbound_calls WHERE call_type='remote_action' AND unresolved_reason='dynamic_operation_path_identifier' ORDER BY source_file,source_line LIMIT 5").all();
   return { severity: examples.length > 0 ? "warning" : "info", code: "strict_wrapper_path_propagation_quality", message: "Dynamic path sends where send({ path }) used a path identifier", dynamicPathIdentifierCalls: examples.length, examples };
@@ -1669,10 +1911,33 @@ function externalHttpTargetQuality(db) {
   return { severity: bad > 0 ? "warning" : "info", code: "strict_external_http_target_quality", message: "External HTTP semantic target aggregate", totalExternalHttpCalls: Number(row.total ?? 0), numericTargetCount: Number(row.numericTargets ?? 0), invalidOrMissingExternalTargetEvidence: Number(row.invalidEvidence ?? 0) };
 }
 function odataInvocationResolutionQuality(db) {
-  const rows = db.prepare("SELECT c.operation_path_expr operationPathExpr,e.status status FROM outbound_calls c JOIN graph_edges e ON e.from_kind='call' AND e.from_id=CAST(c.id AS TEXT) WHERE c.call_type='remote_action' AND c.operation_path_expr LIKE '%(%'").all();
+  const rows = db.prepare(`SELECT c.operation_path_expr operationPathExpr,
+    c.source_file sourceFile,c.source_line sourceLine,e.id graphEdgeId,
+    e.status status,e.evidence_json evidenceJson
+    FROM outbound_calls c JOIN graph_edges e
+      ON e.from_kind='call' AND e.from_id=CAST(c.id AS TEXT)
+    WHERE c.call_type='remote_action' AND c.operation_path_expr LIKE '%(%'
+    ORDER BY c.source_file,c.source_line`).all();
   const unresolved = rows.filter((row) => row.status === "unresolved" && normalizeODataOperationInvocationPath(row.operationPathExpr)?.wasInvocation).length;
   const ambiguous = rows.filter((row) => row.status === "ambiguous" && normalizeODataOperationInvocationPath(row.operationPathExpr)?.wasInvocation).length;
-  return { severity: unresolved + ambiguous > 0 ? "warning" : "info", code: "strict_odata_invocation_resolution_quality", message: "OData invocation-path resolution quality aggregate", totalInvocationRemoteActions: rows.length, resolvedInvocationCalls: rows.filter((row) => row.status === "resolved").length, dynamicInvocationCalls: rows.filter((row) => row.status === "dynamic").length, ambiguousInvocationCalls: rows.filter((row) => row.status === "ambiguous").length, unresolvedInvocationCalls: rows.filter((row) => row.status === "unresolved").length, ambiguousNormalizedCalls: ambiguous, unresolvedNormalizedCallsWithIndexedCandidates: unresolved };
+  const examples = rows.filter((row) => row.status === "ambiguous" || row.status === "unresolved").map(odataInvocationExample).slice(0, 5);
+  return { severity: unresolved + ambiguous > 0 ? "warning" : "info", code: "strict_odata_invocation_resolution_quality", message: "OData invocation-path resolution quality aggregate", totalInvocationRemoteActions: rows.length, resolvedInvocationCalls: rows.filter((row) => row.status === "resolved").length, dynamicInvocationCalls: rows.filter((row) => row.status === "dynamic").length, ambiguousInvocationCalls: rows.filter((row) => row.status === "ambiguous").length, unresolvedInvocationCalls: rows.filter((row) => row.status === "unresolved").length, ambiguousNormalizedCalls: ambiguous, unresolvedNormalizedCallsWithIndexedCandidates: unresolved, examples };
+}
+function odataInvocationExample(row) {
+  const evidence = parseObject(row.evidenceJson);
+  const normalized = normalizeODataOperationInvocationPath(row.operationPathExpr);
+  return {
+    sourceFile: row.sourceFile,
+    sourceLine: row.sourceLine,
+    graphEdgeId: row.graphEdgeId,
+    status: row.status,
+    rawPath: row.operationPathExpr,
+    normalizedOperationPath: normalized?.wasInvocation ? normalized.normalizedOperationPath : void 0,
+    indexedOperationCandidateCount: evidence.indexedOperationCandidateCount,
+    candidateScores: evidence.candidateScores,
+    entityOperationPrecedence: evidence.entityOperationPrecedence,
+    resolutionReasons: evidence.resolutionReasons
+  };
 }
 function identityAliasBindingQuality(db) {
   const examples = db.prepare("SELECT c.source_file sourceFile,c.source_line sourceLine FROM outbound_calls c WHERE c.call_type='remote_action' AND c.service_binding_id IS NULL AND json_extract(c.evidence_json,'$.receiver') IS NOT NULL ORDER BY c.source_file,c.source_line LIMIT 5").all();
@@ -1725,8 +1990,8 @@ function renderTraceTable(result) {
   const lines = ["Step  Type                 From                                To                                  Evidence"];
   for (const e of result.edges) {
     lines.push(`${String(e.step).padEnd(5)} ${e.type.padEnd(20)} ${e.from.slice(0, 34).padEnd(35)} ${e.to.slice(0, 35).padEnd(36)} ${location(e.evidence)}`);
-    const hint = firstHint(e.evidence);
-    if (e.unresolvedReason && hint) lines.push(`      try ${hint}`);
+    if (e.unresolvedReason)
+      lines.push(...hintLines(e.evidence).map((hint) => `      ${hint}`));
   }
   if (result.diagnostics.length > 0) lines.push("", "Diagnostics:", ...result.diagnostics.flatMap(diagnosticLines));
   return `${lines.join("\n")}
@@ -1734,14 +1999,20 @@ function renderTraceTable(result) {
 }
 function diagnosticLines(diagnostic) {
   const first = `${String(diagnostic.severity ?? "info")} ${String(diagnostic.code ?? "diagnostic")} ${String(diagnostic.message ?? "")}`;
-  const hint = firstHint(diagnostic);
-  return hint ? [first, `  try ${hint}`] : [first];
+  return [first, ...hintLines(diagnostic).map((hint) => `  ${hint}`)];
 }
-function firstHint(evidence) {
+function hintLines(evidence) {
   const suggestions = evidence.implementationHintSuggestions;
-  if (!Array.isArray(suggestions)) return void 0;
-  const first = suggestions.find((item) => Boolean(item) && typeof item === "object");
-  return typeof first?.cli === "string" ? first.cli : void 0;
+  if (!Array.isArray(suggestions)) return [];
+  const hints = suggestions.flatMap((item) => isRecord(item) && typeof item.cli === "string" ? [item.cli] : []);
+  const unique = [...new Set(hints)];
+  const shown = unique.slice(0, 3).map((hint) => `try ${hint}`);
+  if (unique.length > shown.length)
+    shown.push(`... ${unique.length - shown.length} more hint(s) available in JSON`);
+  return shown;
+}
+function isRecord(value) {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
 }
 
 // src/output/json-output.ts
@@ -1753,6 +2024,92 @@ function renderTraceJson(trace2) {
   return renderJson(trace2);
 }
 
+// src/output/doctor-output.ts
+import pc from "picocolors";
+function renderDoctorDiagnostics(diagnostics, format) {
+  if (format === "json") return renderJson(diagnostics);
+  if (format === "table") return renderDoctorTable(diagnostics);
+  if (format) throw new Error(`Unsupported doctor format: ${format}. Expected json or table.`);
+  return renderLegacyDoctorOutput(diagnostics);
+}
+function renderLegacyDoctorOutput(diagnostics) {
+  if (diagnostics.length === 0) return cleanDoctorMessage();
+  return renderJson(diagnostics);
+}
+function renderDoctorTable(diagnostics) {
+  if (diagnostics.length === 0) return cleanDoctorMessage();
+  const rows = diagnostics.map((diagnostic) => ({
+    severity: String(diagnostic.severity ?? "info"),
+    code: String(diagnostic.code ?? "diagnostic"),
+    location: diagnosticLocation(diagnostic),
+    message: compactMessage(diagnostic),
+    hints: suggestedHintLines(diagnostic)
+  }));
+  const widths = {
+    severity: columnWidth("Severity", rows.map((row) => row.severity), 10),
+    code: columnWidth("Code", rows.map((row) => row.code), 44),
+    location: columnWidth("Location", rows.map((row) => row.location), 28)
+  };
+  const lines = [
+    `${"Severity".padEnd(widths.severity)} ${"Code".padEnd(widths.code)} ${"Location".padEnd(widths.location)} Message`,
+    `${"-".repeat(widths.severity)} ${"-".repeat(widths.code)} ${"-".repeat(widths.location)} ${"-".repeat(7)}`
+  ];
+  for (const row of rows) {
+    lines.push(`${truncate(row.severity, widths.severity).padEnd(widths.severity)} ${truncate(row.code, widths.code).padEnd(widths.code)} ${truncate(row.location, widths.location).padEnd(widths.location)} ${row.message}`);
+    lines.push(...row.hints.map((hint) => `  try ${hint}`));
+  }
+  return `${lines.join("\n")}
+`;
+}
+function diagnosticLocation(diagnostic) {
+  const file = diagnostic.sourceFile ?? diagnostic.file;
+  const line = diagnostic.sourceLine ?? diagnostic.line;
+  if (file || line) return `${String(file ?? "")}:${String(line ?? "")}`;
+  return "-";
+}
+function compactMessage(diagnostic) {
+  const message = String(diagnostic.message ?? "");
+  const count = typeof diagnostic.count === "number" ? ` count=${diagnostic.count}` : "";
+  const total = typeof diagnostic.total === "number" ? ` total=${diagnostic.total}` : "";
+  return `${message}${count}${total}`.trim();
+}
+function suggestedHintLines(diagnostic) {
+  const direct = cliHints(diagnostic.suggestedHints);
+  if (direct.length > 0) return cappedHints(direct);
+  return cappedHints(cliHintsFromSuggestions(diagnostic.implementationHintSuggestions));
+}
+function cliHints(value) {
+  return Array.isArray(value) ? value.filter((item) => typeof item === "string") : [];
+}
+function cliHintsFromSuggestions(value) {
+  if (!Array.isArray(value)) return [];
+  return value.flatMap((item) => {
+    if (!isRecord2(item)) return [];
+    return typeof item.cli === "string" ? [item.cli] : [];
+  });
+}
+function isRecord2(value) {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+function cappedHints(hints) {
+  const unique = [...new Set(hints)];
+  const shown = unique.slice(0, 3);
+  if (unique.length > shown.length) shown.push(`... ${unique.length - shown.length} more hint(s) available in --format json`);
+  return shown;
+}
+function cleanDoctorMessage() {
+  return `${pc.green("No diagnostics recorded")}
+`;
+}
+function columnWidth(header, values, max) {
+  return Math.min(max, Math.max(header.length, ...values.map((value) => value.length)));
+}
+function truncate(value, width) {
+  if (value.length <= width) return value;
+  if (width <= 1) return value.slice(0, width);
+  return `${value.slice(0, width - 1)}\u2026`;
+}
+
 // src/output/mermaid-output.ts
 function safe(value) {
   return value.replace(/[^\w-]/g, "_").slice(0, 60);
@@ -1985,13 +2342,10 @@ function createProgram() {
       process.stdout.write(renderJson(rows));
     }).catch(fail)
   );
-  program.command("doctor").option("--workspace <path>").option("--strict").option("--detail").action(
+  program.command("doctor").option("--workspace <path>").option("--strict").option("--detail").option("--format <format>", "json|table").action(
     (opts) => void withReadOnlyWorkspace(opts.workspace, (db) => {
       const allDiagnostics = doctorDiagnostics(db, Boolean(opts.strict), { detail: Boolean(opts.detail) });
-      process.stdout.write(
-        allDiagnostics.length ? renderJson(allDiagnostics) : `${pc.green("No diagnostics recorded")}
-`
-      );
+      process.stdout.write(renderDoctorDiagnostics(allDiagnostics, opts.format));
     }).catch(fail)
   );
   program.command("clean").option("--workspace <path>").option("--db-only").action(