@saptools/service-flow 0.1.47 → 0.1.48

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.1.48
+
+- Added deterministic `doctor --format json|table` output while preserving legacy-compatible default doctor output; JSON mode returns `[]` for clean workspaces and table mode renders concise diagnostic rows with capped hint lines.
+- Documented the 0.1.47 audit follow-up evidence fields for service-client ownership chains, normalized OData operation paths, wrapper path candidates, and implementation hint suggestions.
+- Bumped the package patch version for the service-flow audit follow-up release.
+
 ## 0.1.46
 
 - Improved ambiguous implementation diagnostics with ready-to-copy scoped hint suggestions for each blocked helper hop.

package/README.md

@@ -277,14 +277,18 @@ service-flow inspect operation /doWork --workspace /path/to/workspace
 
 ### 🩺 `service-flow doctor`
 
-Print stored diagnostics. Default output suppresses high-noise entity-only service checks; `--strict` includes them. A clean workspace prints `No diagnostics recorded`.
+Print stored diagnostics. Default output suppresses high-noise entity-only service checks; `--strict` includes them. Without `--format`, doctor keeps the legacy-compatible behavior: JSON when diagnostics exist and `No diagnostics recorded` for a clean workspace. Deterministic JSON mode prints `[]` when clean.
 
 ```bash
 service-flow doctor --workspace /path/to/workspace
 service-flow doctor --workspace /path/to/workspace --strict
 service-flow doctor --workspace /path/to/workspace --strict --detail
+service-flow doctor --workspace /path/to/workspace --strict --format json
+service-flow doctor --workspace /path/to/workspace --strict --format table
 ```
 
+`--format json` always returns a JSON array, including `[]` for clean workspaces. `--format table` prints a concise human-readable table with capped copyable hint lines; use JSON when automation needs every field or every hint alternative. Omit `--format` when relying on the pre-0.1.48 compatible output contract.
+
 Strict output keeps stable category, count, severity, and capped example fields. Use `--detail` to include full `expandedExamples` for implementation candidate, parameter metadata, and dynamic wrapper categories.
 
 ### 🧹 `service-flow clean`

package/dist/cli.js

@@ -21,7 +21,6 @@ import {
 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.48",
   description: "Trace SAP CAP service-to-service flows across multi-repository workspaces with runtime-aware graph resolution",
   type: "module",
   publishConfig: {
@@ -1312,6 +1311,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 +1339,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 +1356,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 [];
@@ -1753,6 +1783,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 (!isRecord(item)) return [];
+    return typeof item.cli === "string" ? [item.cli] : [];
+  });
+}
+function isRecord(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 +2101,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(