@saptools/service-flow 0.1.46 → 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`
@@ -481,39 +485,3 @@ MIT
 ---
 
 Made with ❤️ to make your work life easier!
-
-
-### Service-only trace policy
-
-`service-flow trace --service <path>` is intentionally not a broad workspace traversal. Provide `--operation`, `--path`, or `--handler`; otherwise the command returns a typed `trace_start_not_found` diagnostic and no edges.
-
-### Graph freshness and last-good snapshots
-
-Repository facts are parsed before publication and committed atomically. Failed indexing attempts record diagnostics and retain the last complete published snapshot and successful fingerprint. Successful fact publication marks the workspace graph stale until `service-flow link` rebuilds dependency, remote-call, and implementation edges for the current fact generation.
-
-### Cross-package implementation evidence
-
-Handler registrations persist parsed class names and import sources. Linking resolves implementation edges only through registered application evidence plus model and handler package dependency edges; a decorator-name match alone is not enough.
-
-### Graph variables
-
-The `graph` command accepts repeatable `--var key=value` options, matching `trace`, for runtime substitution previews in JSON or Mermaid output.
-
-
-### 0.1.17 parser ownership policy
-
-Outbound call extraction is AST-based and ignores comments, block comments, and string literals. CAP/service `.on(...)` registrations are indexed only when the receiver has CAP/service evidence, and top-level registrations receive `module:<relative-file>#event:<event-name>:<line>` synthetic owners. Generic event emitters such as desktop or window events are ignored by default rather than guessed as CAP async edges. Unsupported source shapes are surfaced through diagnostics and strict doctor ownerless categories instead of guessed graph edges.
-
-
-## 0.1.32 hardening notes
-
-Operation trace starts resolve indexed CDS operations before handler fallback. Ambiguous operation matches, ambiguous/rejected implementation edges, and resolved edges without an executable handler scope now fail closed with structured `resolutionStage` and `resolutionStatus` diagnostics and no speculative traversal. Handler fallback is only considered when no indexed CDS operation matches and the fallback is unique under the existing registration and ownership policy.
-
-Decorator signals are interpreted as resolved, absent, unsupported, or malformed. Only resolved string/template values, generated `Action<Name>.name`/`Func<Name>.name` constants, qualified generated constants ending in `.name`, and narrow safe `String(identifier)` wrappers can contradict method-name fallback. Unsupported expressions are preserved as evidence but are not treated as proof that a handler targets another operation.
-
-External HTTP facts persist queryable target kind, stable id, safe label, and dynamic flag on `outbound_calls`; graph evidence uses the same sanitized model. URL user info, fragments, query values, headers, cookies, credentials, tokens, API keys, and request/response bodies are not persisted. Legacy workspaces may relink from old evidence when possible, but full semantic enrichment requires re-index plus relink when old parser facts did not contain safe target metadata.
-
-Graph taxonomy now keeps CAP operation candidates separate from external HTTP targets. Dynamic, ambiguous, and unresolved CAP calls use operation-candidate semantics, external destinations/endpoints are produced only by `external_http` calls, and terminal local transport-client methods use transport-method semantics rather than external HTTP edges. `doctor --strict` reports external target quality and taxonomy consistency.
-### Runtime and parser hardening
-
-`service-flow` treats URL and destination templates with substitutions as dynamic external targets, preserves operation-path template evidence without promoting unrelated variables, and parses CDS `@(path: ...)` annotations from original source text. Service extension declarations using both `extend Name` and `extend service Name` are recognized for routing provenance.

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.46",
+  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(