@saptools/service-flow 0.1.4 → 0.1.6

package/dist/cli.js

@@ -10,7 +10,7 @@ import {
   parsePackageJson,
   parseServiceBindings,
   trace
-} from "./chunk-JY6GBGZT.js";
+} from "./chunk-6C5HZ6IR.js";
 
 // src/cli.ts
 import { Command } from "commander";
@@ -84,14 +84,13 @@ function createWorkspaceConfig(rootPath, dbPath, ignore = [...DEFAULT_IGNORES])
 }
 
 // src/db/connection.ts
-import { execFileSync } from "child_process";
 import fs2 from "fs";
 import path2 from "path";
 
 // src/db/schema.ts
 var schemaSql = `
 CREATE TABLE IF NOT EXISTS workspaces (id INTEGER PRIMARY KEY, root_path TEXT UNIQUE NOT NULL, db_path TEXT NOT NULL, created_at TEXT NOT NULL, updated_at TEXT NOT NULL);
-CREATE TABLE IF NOT EXISTS repositories (id INTEGER PRIMARY KEY, workspace_id INTEGER NOT NULL, name TEXT NOT NULL, absolute_path TEXT NOT NULL, relative_path TEXT NOT NULL, package_name TEXT, package_version TEXT, dependencies_json TEXT DEFAULT '{}', kind TEXT NOT NULL, is_git_repo INTEGER NOT NULL, last_indexed_at TEXT, index_status TEXT DEFAULT 'pending', error_count INTEGER DEFAULT 0, UNIQUE(workspace_id, absolute_path), FOREIGN KEY(workspace_id) REFERENCES workspaces(id) ON DELETE CASCADE);
+CREATE TABLE IF NOT EXISTS repositories (id INTEGER PRIMARY KEY, workspace_id INTEGER NOT NULL, name TEXT NOT NULL, absolute_path TEXT NOT NULL, relative_path TEXT NOT NULL, package_name TEXT, package_version TEXT, dependencies_json TEXT DEFAULT '{}', kind TEXT NOT NULL, is_git_repo INTEGER NOT NULL, last_indexed_at TEXT, index_status TEXT DEFAULT 'pending', error_count INTEGER DEFAULT 0, fingerprint TEXT, UNIQUE(workspace_id, absolute_path), FOREIGN KEY(workspace_id) REFERENCES workspaces(id) ON DELETE CASCADE);
 CREATE TABLE IF NOT EXISTS files (id INTEGER PRIMARY KEY, repo_id INTEGER NOT NULL, relative_path TEXT NOT NULL, extension TEXT NOT NULL, sha256 TEXT NOT NULL, size_bytes INTEGER NOT NULL, last_indexed_at TEXT NOT NULL, UNIQUE(repo_id, relative_path), FOREIGN KEY(repo_id) REFERENCES repositories(id) ON DELETE CASCADE);
 CREATE TABLE IF NOT EXISTS cds_requires (id INTEGER PRIMARY KEY, repo_id INTEGER NOT NULL, alias TEXT NOT NULL, kind TEXT, model TEXT, destination TEXT, service_path TEXT, request_timeout INTEGER, raw_json TEXT NOT NULL, FOREIGN KEY(repo_id) REFERENCES repositories(id) ON DELETE CASCADE);
 CREATE TABLE IF NOT EXISTS cds_services (id INTEGER PRIMARY KEY, repo_id INTEGER NOT NULL, namespace TEXT, service_name TEXT NOT NULL, qualified_name TEXT NOT NULL, service_path TEXT NOT NULL, is_extend INTEGER NOT NULL, source_file TEXT NOT NULL, source_line INTEGER NOT NULL, FOREIGN KEY(repo_id) REFERENCES repositories(id) ON DELETE CASCADE);
@@ -102,9 +101,9 @@ CREATE TABLE IF NOT EXISTS handler_methods (id INTEGER PRIMARY KEY, handler_clas
 CREATE TABLE IF NOT EXISTS handler_registrations (id INTEGER PRIMARY KEY, repo_id INTEGER NOT NULL, handler_class_id INTEGER, registration_file TEXT NOT NULL, registration_line INTEGER NOT NULL, registration_kind TEXT NOT NULL, confidence REAL NOT NULL, FOREIGN KEY(repo_id) REFERENCES repositories(id) ON DELETE CASCADE, FOREIGN KEY(handler_class_id) REFERENCES handler_classes(id) ON DELETE SET NULL);
 CREATE TABLE IF NOT EXISTS service_bindings (id INTEGER PRIMARY KEY, repo_id INTEGER NOT NULL, symbol_id INTEGER, variable_name TEXT NOT NULL, alias TEXT, alias_expr TEXT, destination_expr TEXT, service_path_expr TEXT, is_dynamic INTEGER NOT NULL, placeholders_json TEXT NOT NULL, source_file TEXT NOT NULL, source_line INTEGER NOT NULL, helper_chain_json TEXT, FOREIGN KEY(repo_id) REFERENCES repositories(id) ON DELETE CASCADE, FOREIGN KEY(symbol_id) REFERENCES symbols(id) ON DELETE SET NULL);
 CREATE TABLE IF NOT EXISTS outbound_calls (id INTEGER PRIMARY KEY, repo_id INTEGER NOT NULL, source_symbol_id INTEGER, call_type TEXT NOT NULL, service_binding_id INTEGER, method TEXT, operation_path_expr TEXT, query_entity TEXT, event_name_expr TEXT, payload_summary TEXT, source_file TEXT NOT NULL, source_line INTEGER NOT NULL, confidence REAL NOT NULL, unresolved_reason TEXT, FOREIGN KEY(repo_id) REFERENCES repositories(id) ON DELETE CASCADE, FOREIGN KEY(source_symbol_id) REFERENCES symbols(id) ON DELETE SET NULL, FOREIGN KEY(service_binding_id) REFERENCES service_bindings(id) ON DELETE SET NULL);
-CREATE TABLE IF NOT EXISTS graph_edges (id INTEGER PRIMARY KEY, workspace_id INTEGER NOT NULL, edge_type TEXT NOT NULL, from_kind TEXT NOT NULL, from_id TEXT NOT NULL, to_kind TEXT NOT NULL, to_id TEXT NOT NULL, confidence REAL NOT NULL, evidence_json TEXT NOT NULL, is_dynamic INTEGER NOT NULL, unresolved_reason TEXT);
-CREATE TABLE IF NOT EXISTS index_runs (id INTEGER PRIMARY KEY, workspace_id INTEGER NOT NULL, started_at TEXT NOT NULL, finished_at TEXT, status TEXT NOT NULL, repo_count INTEGER NOT NULL, file_count INTEGER NOT NULL, diagnostic_count INTEGER NOT NULL);
-CREATE TABLE IF NOT EXISTS diagnostics (id INTEGER PRIMARY KEY, repo_id INTEGER, file_id INTEGER, severity TEXT NOT NULL, code TEXT NOT NULL, message TEXT NOT NULL, source_file TEXT, source_line INTEGER);
+CREATE TABLE IF NOT EXISTS graph_edges (id INTEGER PRIMARY KEY, workspace_id INTEGER NOT NULL, edge_type TEXT NOT NULL, status TEXT NOT NULL DEFAULT 'unresolved', from_kind TEXT NOT NULL, from_id TEXT NOT NULL, to_kind TEXT NOT NULL, to_id TEXT NOT NULL, confidence REAL NOT NULL, evidence_json TEXT NOT NULL, is_dynamic INTEGER NOT NULL, unresolved_reason TEXT, FOREIGN KEY(workspace_id) REFERENCES workspaces(id) ON DELETE CASCADE);
+CREATE TABLE IF NOT EXISTS index_runs (id INTEGER PRIMARY KEY, workspace_id INTEGER NOT NULL, started_at TEXT NOT NULL, finished_at TEXT, status TEXT NOT NULL, repo_count INTEGER NOT NULL, file_count INTEGER NOT NULL, diagnostic_count INTEGER NOT NULL, FOREIGN KEY(workspace_id) REFERENCES workspaces(id) ON DELETE CASCADE);
+CREATE TABLE IF NOT EXISTS diagnostics (id INTEGER PRIMARY KEY, repo_id INTEGER, file_id INTEGER, severity TEXT NOT NULL, code TEXT NOT NULL, message TEXT NOT NULL, source_file TEXT, source_line INTEGER, FOREIGN KEY(repo_id) REFERENCES repositories(id) ON DELETE CASCADE, FOREIGN KEY(file_id) REFERENCES files(id) ON DELETE SET NULL);
 CREATE INDEX IF NOT EXISTS idx_repo_name ON repositories(name);
 CREATE INDEX IF NOT EXISTS idx_service_path ON cds_services(service_path);
 CREATE INDEX IF NOT EXISTS idx_operation_name ON cds_operations(operation_name, operation_path);
@@ -113,89 +112,108 @@ CREATE VIRTUAL TABLE IF NOT EXISTS search_index USING fts5(kind, name, path, rep
 `;
 
 // src/db/migrations.ts
+var CURRENT_SCHEMA_VERSION = 2;
+function hasColumn(db, table, column) {
+  return db.prepare(`PRAGMA table_info(${table})`).all().some((row) => row.name === column);
+}
+function userVersion(db) {
+  const row = db.pragma("user_version")[0];
+  return Number(row?.user_version ?? 0);
+}
 function migrate(db) {
-  db.exec(schemaSql);
-  const columns = db.prepare("PRAGMA table_info(service_bindings)").all();
-  if (!columns.some((column) => column.name === "helper_chain_json"))
-    db.prepare(
-      "ALTER TABLE service_bindings ADD COLUMN helper_chain_json TEXT"
-    ).run();
-  if (!columns.some((column) => column.name === "alias_expr"))
-    db.prepare("ALTER TABLE service_bindings ADD COLUMN alias_expr TEXT").run();
+  db.transaction(() => {
+    db.exec(schemaSql);
+    if (!hasColumn(db, "service_bindings", "helper_chain_json")) db.prepare("ALTER TABLE service_bindings ADD COLUMN helper_chain_json TEXT").run();
+    if (!hasColumn(db, "service_bindings", "alias_expr")) db.prepare("ALTER TABLE service_bindings ADD COLUMN alias_expr TEXT").run();
+    if (!hasColumn(db, "repositories", "fingerprint")) db.prepare("ALTER TABLE repositories ADD COLUMN fingerprint TEXT").run();
+    if (!hasColumn(db, "graph_edges", "status")) db.prepare("ALTER TABLE graph_edges ADD COLUMN status TEXT NOT NULL DEFAULT 'unresolved'").run();
+    db.prepare("UPDATE graph_edges SET status=CASE WHEN edge_type='REMOTE_CALL_RESOLVES_TO_OPERATION' THEN 'resolved' WHEN edge_type IN ('HANDLER_RUNS_DB_QUERY','HANDLER_CALLS_EXTERNAL_HTTP','HANDLER_EMITS_EVENT','EVENT_CONSUMED_BY_HANDLER') THEN 'terminal' WHEN edge_type='DYNAMIC_EDGE_CANDIDATE' THEN 'dynamic' ELSE status END").run();
+    db.pragma(`user_version = ${Math.max(userVersion(db), CURRENT_SCHEMA_VERSION)}`);
+  });
 }
 
 // src/db/connection.ts
-function quote(value) {
-  if (value === null || value === void 0) return "NULL";
-  if (typeof value === "number")
-    return Number.isFinite(value) ? String(value) : "NULL";
-  if (typeof value === "boolean") return value ? "1" : "0";
-  return `'${String(value).replaceAll("'", "''")}'`;
-}
-function bind(sql, params) {
-  let index = 0;
-  return sql.replaceAll("?", () => quote(params[index++]));
-}
-function isBusy(error) {
-  return error instanceof Error && /SQLITE_BUSY|database is locked|database is busy/i.test(error.message);
-}
-function sleep(ms) {
-  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
-}
-function call(dbPath, args, attempt = 0) {
+function loadSqlite() {
   try {
-    return execFileSync("sqlite3", [dbPath, ...args], {
-      encoding: "utf8",
-      maxBuffer: 128 * 1024 * 1024,
-      env: { ...process.env, SQLITE_BUSY_TIMEOUT: "10000" }
-    });
+    const moduleValue = process.getBuiltinModule("node:sqlite");
+    if (!moduleValue || typeof moduleValue !== "object" || !("DatabaseSync" in moduleValue))
+      throw new Error("node:sqlite DatabaseSync is unavailable");
+    const sqlite = moduleValue;
+    if (typeof sqlite.DatabaseSync !== "function")
+      throw new Error("node:sqlite DatabaseSync is not a constructor");
+    return sqlite;
   } catch (error) {
-    if (isBusy(error) && attempt < 5) {
-      sleep(50 * 2 ** attempt);
-      return call(dbPath, args, attempt + 1);
-    }
-    if (isBusy(error))
-      throw new Error(
-        "SQLite database is busy or locked. Another service-flow writer may be active; retry after it finishes.",
-        { cause: error }
-      );
-    throw error;
+    throw new Error(
+      "service-flow 0.1.6 requires Node.js >=24 with node:sqlite DatabaseSync support. Upgrade Node.js or install a service-flow build with a compatible SQLite driver.",
+      { cause: error }
+    );
   }
 }
-function jsonRows(dbPath, sql) {
-  const out = call(dbPath, ["-json", sql]);
-  if (!out.trim()) return [];
-  return JSON.parse(out);
+function bindParams(params) {
+  return params.map((param) => {
+    if (param === void 0 || param === null) return null;
+    if (typeof param === "string" || typeof param === "number" || typeof param === "bigint" || Buffer.isBuffer(param)) return param;
+    if (typeof param === "boolean") return param ? 1 : 0;
+    return JSON.stringify(param);
+  });
 }
-function openDatabase(dbPath) {
+function openDatabase(dbPath, options = {}) {
   fs2.mkdirSync(path2.dirname(dbPath), { recursive: true });
+  const sqlite = loadSqlite();
+  const native = new sqlite.DatabaseSync(dbPath, { readOnly: Boolean(options.readonly) });
+  let inTransaction = false;
   const db = {
     path: dbPath,
+    readonly: Boolean(options.readonly),
     exec(sql) {
-      call(dbPath, [sql]);
+      native.exec(sql);
     },
     prepare(sql) {
+      const statement = native.prepare(sql);
       return {
-        run: (...params) => {
-          call(dbPath, [bind(sql, params)]);
-          return { changes: 0 };
-        },
-        get: (...params) => jsonRows(dbPath, bind(sql, params))[0],
-        all: (...params) => jsonRows(dbPath, bind(sql, params))
+        run: (...params) => statement.run(...bindParams(params)),
+        get: (...params) => statement.get(...bindParams(params)),
+        all: (...params) => statement.all(...bindParams(params))
       };
     },
     pragma(sql) {
-      call(dbPath, [`PRAGMA ${sql}`]);
+      const normalized = sql.trim().replace(/;$/, "");
+      if (/=/.test(normalized)) {
+        native.exec(`PRAGMA ${normalized}`);
+        return [];
+      }
+      return native.prepare(`PRAGMA ${normalized}`).all();
+    },
+    transaction(fn) {
+      if (inTransaction) return fn();
+      inTransaction = true;
+      native.exec("BEGIN IMMEDIATE");
+      try {
+        const result = fn();
+        native.exec("COMMIT");
+        return result;
+      } catch (error) {
+        native.exec("ROLLBACK");
+        throw error;
+      } finally {
+        inTransaction = false;
+      }
     },
     close() {
+      native.close();
     }
   };
   db.pragma("busy_timeout = 10000");
-  db.pragma("journal_mode = WAL");
   db.pragma("foreign_keys = ON");
-  migrate(db);
+  if (!options.readonly) {
+    db.pragma("journal_mode = WAL");
+    if (options.migrate !== false) migrate(db);
+  }
   return db;
 }
+function openReadOnlyDatabase(dbPath) {
+  return openDatabase(dbPath, { readonly: true, migrate: false });
+}
 
 // src/db/repositories.ts
 function upsertWorkspace(db, rootPath, dbPath) {
@@ -449,6 +467,9 @@ import { readFile } from "fs/promises";
 async function sha256File(filePath) {
   return createHash("sha256").update(await readFile(filePath)).digest("hex");
 }
+function sha256Text(text) {
+  return createHash("sha256").update(text).digest("hex");
+}
 
 // src/indexer/incremental-index.ts
 async function recordFile(db, repoId, repoPath, relativeFile) {
@@ -472,12 +493,91 @@ function errorMessage(error) {
   return error instanceof Error ? error.message : String(error);
 }
 
+// package.json
+var package_default = {
+  name: "@saptools/service-flow",
+  version: "0.1.6",
+  description: "Trace SAP CAP service-to-service flows across multi-repository workspaces with runtime-aware graph resolution",
+  type: "module",
+  publishConfig: {
+    access: "public",
+    registry: "https://registry.npmjs.org/"
+  },
+  bin: {
+    "service-flow": "dist/cli.js"
+  },
+  main: "./dist/index.js",
+  types: "./dist/index.d.ts",
+  exports: {
+    ".": {
+      types: "./dist/index.d.ts",
+      import: "./dist/index.js"
+    }
+  },
+  files: [
+    "CHANGELOG.md",
+    "README.md",
+    "TECHNICAL-NOTE.md",
+    "dist"
+  ],
+  engines: {
+    node: ">=24.0.0"
+  },
+  scripts: {
+    build: "tsup",
+    typecheck: "tsc --noEmit",
+    lint: "eslint src tests",
+    "test:unit": "vitest run tests/unit",
+    "test:e2e": "vitest run tests/e2e",
+    "test:e2e:fake": "vitest run tests/e2e"
+  },
+  keywords: [
+    "sap",
+    "cap",
+    "cds",
+    "btp",
+    "cli",
+    "service-graph",
+    "call-graph",
+    "sqlite",
+    "saptools"
+  ],
+  author: "Dong Tran",
+  license: "MIT",
+  repository: {
+    type: "git",
+    url: "git+https://github.com/dongitran/saptools.git",
+    directory: "packages/service-flow"
+  },
+  homepage: "https://github.com/dongitran/saptools/tree/main/packages/service-flow#readme",
+  bugs: {
+    url: "https://github.com/dongitran/saptools/issues"
+  },
+  dependencies: {
+    commander: "13.1.0",
+    picocolors: "1.1.1",
+    typescript: "5.9.3",
+    zod: "4.4.3"
+  },
+  devDependencies: {
+    "@vitest/coverage-v8": "3.2.4",
+    tsup: "8.5.1",
+    vitest: "3.2.4"
+  }
+};
+
+// src/version.ts
+var VERSION = package_default.version;
+var ANALYZER_VERSION = package_default.version;
+
 // src/indexer/repository-indexer.ts
 async function indexRepository(db, repo, force) {
-  void force;
   let diagnostics = 0;
   let files = 0;
+  const sourceFiles = await findSourceFiles(repo.absolute_path);
   const facts = await parsePackageJson(repo.absolute_path);
+  const fingerprint = await repositoryFingerprint(repo.absolute_path, sourceFiles, facts, Boolean(force));
+  if (!force && repo.fingerprint === fingerprint) return { fileCount: 0, diagnosticCount: 0, skipped: true };
   const kind = await classifyRepository(repo.absolute_path, facts);
   db.prepare(
     "UPDATE repositories SET package_name=?, package_version=?, dependencies_json=?, kind=?, index_status=? WHERE id=?"
@@ -491,7 +591,6 @@ async function indexRepository(db, repo, force) {
   );
   clearRepoFacts(db, repo.id);
   insertRequires(db, repo.id, facts.cdsRequires);
-  const sourceFiles = await findSourceFiles(repo.absolute_path);
   for (const file of sourceFiles) {
     try {
       await recordFile(db, repo.id, repo.absolute_path, file);
@@ -526,14 +625,15 @@ async function indexRepository(db, repo, force) {
     }
   }
   db.prepare(
-    "UPDATE repositories SET last_indexed_at=?, index_status=?, error_count=? WHERE id=?"
+    "UPDATE repositories SET last_indexed_at=?, index_status=?, error_count=?, fingerprint=? WHERE id=?"
   ).run(
     (/* @__PURE__ */ new Date()).toISOString(),
     diagnostics ? "partial" : "indexed",
     diagnostics,
+    fingerprint,
     repo.id
   );
-  return { fileCount: files, diagnosticCount: diagnostics };
+  return { fileCount: files, diagnosticCount: diagnostics, skipped: false };
 }
 async function findSourceFiles(root) {
   const out = [];
@@ -557,6 +657,26 @@ function isDefaultTestFile(relativeFile) {
     return true;
   return /\.(test|spec)\.[jt]s$/.test(parts.at(-1) ?? "");
 }
+async function repositoryFingerprint(root, files, facts, force) {
+  void force;
+  const packageJson = await fs5.readFile(path5.join(root, "package.json"), "utf8").catch(() => "");
+  const normalizedFacts = {
+    analyzerVersion: ANALYZER_VERSION,
+    packageName: facts.packageName,
+    packageVersion: facts.packageVersion,
+    dependencies: Object.fromEntries(Object.entries(facts.dependencies).sort()),
+    cdsRequires: [...facts.cdsRequires].sort((a, b) => a.alias.localeCompare(b.alias)),
+    scripts: Object.fromEntries(Object.entries(facts.scripts).sort()),
+    includeTests: false,
+    packageJsonHash: sha256Text(packageJson)
+  };
+  const entries = [`facts:${JSON.stringify(normalizedFacts)}`];
+  for (const file of files) {
+    const content = await fs5.readFile(path5.join(root, file), "utf8").catch(() => "");
+    entries.push(`${file}:${sha256Text(content)}`);
+  }
+  return sha256Text(entries.join("\n"));
+}
 
 // src/indexer/workspace-indexer.ts
 async function indexWorkspace(db, workspaceId, options) {
@@ -569,10 +689,12 @@ async function indexWorkspace(db, workspaceId, options) {
   );
   let fileCount = 0;
   let diagnosticCount = 0;
+  let skippedCount = 0;
   for (const repo of repos) {
     const result = await indexRepository(db, repo, options.force);
     fileCount += result.fileCount;
     diagnosticCount += result.diagnosticCount;
+    skippedCount += result.skipped ? 1 : 0;
   }
   db.prepare(
     "UPDATE index_runs SET finished_at=?, status=?, file_count=?, diagnostic_count=? WHERE id=?"
@@ -583,7 +705,7 @@ async function indexWorkspace(db, workspaceId, options) {
     diagnosticCount,
     runId
   );
-  return { repoCount: repos.length, fileCount, diagnosticCount };
+  return { repoCount: repos.length, indexedCount: repos.length - skippedCount, skippedCount, fileCount, diagnosticCount };
 }
 
 // src/trace/selectors.ts
@@ -684,11 +806,22 @@ async function withWorkspace(workspace, fn) {
     db.close();
   }
 }
+async function withReadOnlyWorkspace(workspace, fn) {
+  const config = await loadWorkspaceConfig(workspace);
+  const db = openReadOnlyDatabase(config.dbPath);
+  try {
+    const row = getWorkspace(db, config.rootPath);
+    if (!row) throw new Error(`Workspace is not initialized in ${config.dbPath}`);
+    return await fn(db, row.id, config.rootPath);
+  } finally {
+    db.close();
+  }
+}
 function createProgram() {
   const program = new Command();
   program.name("service-flow").description(
     "Trace SAP CAP service-to-service flows across multi-repository workspaces"
-  ).version("0.1.3");
+  ).version(VERSION);
   program.command("init").argument("<workspace>").option("--db <path>").option("--ignore <pattern...>").action(
     (workspace, opts) => void init(workspace, opts).catch(fail)
   );
@@ -699,7 +832,7 @@ function createProgram() {
         force: Boolean(opts.force)
       });
       process.stdout.write(
-        `Indexed ${r.repoCount} repositories, ${r.fileCount} files, ${r.diagnosticCount} diagnostics
+        `Indexed ${r.indexedCount} repositories, skipped ${r.skippedCount}, ${r.fileCount} files, ${r.diagnosticCount} diagnostics
 `
       );
     }).catch(fail)
@@ -708,13 +841,13 @@ function createProgram() {
     (opts) => void withWorkspace(opts.workspace, (db, workspaceId) => {
       const r = linkWorkspace(db, workspaceId);
       process.stdout.write(
-        `Linked ${r.edgeCount} edges, ${r.unresolvedCount} unresolved
+        `Linked ${r.edgeCount} edges: ${r.resolvedCount} remote resolved, ${r.unresolvedCount} remote unresolved, ${r.ambiguousCount} ambiguous, ${r.dynamicCount} dynamic, ${r.terminalCount} terminal
 `
       );
     }).catch(fail)
   );
   program.command("trace").option("--workspace <path>").option("--repo <name>").option("--operation <name>").option("--service <path>").option("--path <operationPath>").option("--handler <name>").option("--depth <n>", "trace depth", "25").option("--format <format>", "table|json|mermaid", "table").option("--include-external").option("--include-db").option("--include-async").option("--var <key=value>", "dynamic variable", collect, []).action(
-    (opts) => void withWorkspace(opts.workspace, (db) => {
+    (opts) => void withReadOnlyWorkspace(opts.workspace, (db) => {
       const result = trace(
         db,
         {
@@ -739,7 +872,7 @@ function createProgram() {
   );
   const list = program.command("list");
   list.command("repos").option("--workspace <path>").action(
-    (opts) => void withWorkspace(
+    (opts) => void withReadOnlyWorkspace(
       opts.workspace,
       (db) => process.stdout.write(
         renderJson(
@@ -753,8 +886,12 @@ function createProgram() {
     ).catch(fail)
   );
   list.command("services").option("--workspace <path>").option("--repo <name>").action(
-    (opts) => void withWorkspace(opts.workspace, (db) => {
+    (opts) => void withReadOnlyWorkspace(opts.workspace, (db) => {
       const repo = opts.repo ? repoByName(db, opts.repo) : void 0;
+      if (opts.repo && !repo) {
+        process.stdout.write(renderJson([{ severity: "warning", code: "selector_repo_not_found", message: `Repository selector not found: ${opts.repo}` }]));
+        return;
+      }
       const rows = db.prepare(
         "SELECT r.name repo,s.service_path servicePath,s.qualified_name qualifiedName FROM cds_services s JOIN repositories r ON r.id=s.repo_id WHERE (? IS NULL OR s.repo_id=?) ORDER BY r.name,s.service_path"
       ).all(repo?.id, repo?.id);
@@ -762,8 +899,12 @@ function createProgram() {
     }).catch(fail)
   );
   list.command("operations").option("--workspace <path>").option("--repo <name>").option("--service <path>").action(
-    (opts) => void withWorkspace(opts.workspace, (db) => {
+    (opts) => void withReadOnlyWorkspace(opts.workspace, (db) => {
       const repo = opts.repo ? repoByName(db, opts.repo) : void 0;
+      if (opts.repo && !repo) {
+        process.stdout.write(renderJson([{ severity: "warning", code: "selector_repo_not_found", message: `Repository selector not found: ${opts.repo}` }]));
+        return;
+      }
       const rows = db.prepare(
         "SELECT r.name repo,s.service_path servicePath,o.operation_name operation,o.operation_path path FROM cds_operations o JOIN cds_services s ON s.id=o.service_id JOIN repositories r ON r.id=s.repo_id WHERE (? IS NULL OR s.repo_id=?) AND (? IS NULL OR s.service_path=?)"
       ).all(repo?.id, repo?.id, opts.service, opts.service);
@@ -771,8 +912,12 @@ function createProgram() {
     }).catch(fail)
   );
   list.command("calls").option("--workspace <path>").option("--repo <name>").option("--operation <name>").action(
-    (opts) => void withWorkspace(opts.workspace, (db) => {
+    (opts) => void withReadOnlyWorkspace(opts.workspace, (db) => {
       const repo = opts.repo ? repoByName(db, opts.repo) : void 0;
+      if (opts.repo && !repo) {
+        process.stdout.write(renderJson([{ severity: "warning", code: "selector_repo_not_found", message: `Repository selector not found: ${opts.repo}` }]));
+        return;
+      }
       const rows = db.prepare(
         "SELECT r.name repo,c.call_type type,c.operation_path_expr path,c.source_file file,c.source_line line FROM outbound_calls c JOIN repositories r ON r.id=c.repo_id WHERE (? IS NULL OR c.repo_id=?) AND (? IS NULL OR c.operation_path_expr=? OR c.operation_path_expr=? OR c.payload_summary LIKE ?)"
       ).all(
@@ -786,8 +931,8 @@ function createProgram() {
       process.stdout.write(renderJson(rows));
     }).catch(fail)
   );
-  program.command("graph").option("--workspace <path>").option("--repo <name>").option("--operation <name>").option("--service <path>").option("--path <operationPath>").option("--format <format>", "mermaid|json", "mermaid").action(
-    (opts) => void withWorkspace(opts.workspace, (db) => {
+  program.command("graph").option("--workspace <path>").option("--repo <name>").option("--operation <name>").option("--service <path>").option("--path <operationPath>").option("--format <format>", "mermaid|json", "mermaid").option("--var <key=value>", "dynamic variable", collect, []).action(
+    (opts) => void withReadOnlyWorkspace(opts.workspace, (db) => {
       const result = trace(
         db,
         {
@@ -800,7 +945,8 @@ function createProgram() {
           depth: 100,
           includeAsync: true,
           includeDb: true,
-          includeExternal: true
+          includeExternal: true,
+          vars: parseVars(opts.var)
         }
       );
       process.stdout.write(
@@ -810,7 +956,7 @@ function createProgram() {
   );
   const inspect = program.command("inspect");
   inspect.command("repo").argument("<name>").option("--workspace <path>").action(
-    (name, opts) => void withWorkspace(
+    (name, opts) => void withReadOnlyWorkspace(
       opts.workspace,
       (db) => process.stdout.write(
         renderJson(repoByName(db, name) ?? { error: "repo not found" })
@@ -818,7 +964,7 @@ function createProgram() {
     ).catch(fail)
   );
   inspect.command("operation").argument("<selector>").option("--workspace <path>").action(
-    (selector, opts) => void withWorkspace(opts.workspace, (db) => {
+    (selector, opts) => void withReadOnlyWorkspace(opts.workspace, (db) => {
       const rows = db.prepare(
         "SELECT * FROM cds_operations WHERE operation_name=? OR operation_path=?"
       ).all(selector, selector);
@@ -826,24 +972,27 @@ function createProgram() {
     }).catch(fail)
   );
   program.command("doctor").option("--workspace <path>").option("--strict").action(
-    (opts) => void withWorkspace(opts.workspace, (db) => {
+    (opts) => void withReadOnlyWorkspace(opts.workspace, (db) => {
       const diagnostics = db.prepare(
         "SELECT severity,code,message,source_file sourceFile,source_line sourceLine FROM diagnostics ORDER BY id"
-      ).all(Boolean(opts.strict));
+      ).all();
       const health = db.prepare(
         `SELECT 'info' severity,'entity_only_service' code,'CDS service has no action/function/event operations; this can be valid for entity-only services' message,s.source_file sourceFile,s.source_line sourceLine
                FROM cds_services s LEFT JOIN cds_operations o ON o.service_id=s.id WHERE o.id IS NULL AND ?
                UNION ALL
                SELECT 'warning','extend_service_unresolved_base','Extend service has no indexed local operations; verify base service resolution',s.source_file,s.source_line
-               FROM cds_services s LEFT JOIN cds_operations o ON o.service_id=s.id WHERE o.id IS NULL AND s.is_extend=1
+               FROM cds_services s LEFT JOIN cds_operations o ON o.service_id=s.id WHERE o.id IS NULL AND s.is_extend=1 AND ?
                UNION ALL
                SELECT 'warning','handler_without_service','Repository has handlers but no CDS services',hc.source_file,hc.source_line
                FROM handler_classes hc JOIN repositories r ON r.id=hc.repo_id
                WHERE r.kind IN ('cap-service','mixed') AND NOT EXISTS (SELECT 1 FROM cds_services s WHERE s.repo_id=hc.repo_id)
                UNION ALL
                SELECT 'warning','search_index_empty','Search index is empty after indexing',NULL,NULL
-               WHERE NOT EXISTS (SELECT 1 FROM search_index)`
-      ).all(Boolean(opts.strict));
+               WHERE NOT EXISTS (SELECT 1 FROM search_index)
+               UNION ALL
+               SELECT 'error','foreign_key_violation','SQLite foreign_key_check reported integrity failures',NULL,NULL
+               WHERE EXISTS (SELECT 1 FROM pragma_foreign_key_check)`
+      ).all(Boolean(opts.strict), Boolean(opts.strict));
       const allDiagnostics = [...diagnostics, ...health];
       process.stdout.write(
         allDiagnostics.length ? renderJson(allDiagnostics) : `${pc.green("No diagnostics recorded")}