@agent-surface/cli 0.11.1 → 0.12.1

package/dist/{chunk-2FG527AM.js → chunk-Q5WOLWEW.js}

@@ -4,24 +4,40 @@ import {
 } from "./chunk-QIVOZAWX.js";
 
 // src/baseline.ts
-import { mkdirSync, readFileSync, writeFileSync } from "fs";
-import { dirname, join, resolve } from "path";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { dirname, join, resolve, sep } from "path";
 import { serializeSurfaceSnapshot } from "@agent-surface/testing";
 var DEFAULT_BASELINE_DIR = ".agent-surface";
+var SCENARIO_MANIFEST_FILE = "scenarios.json";
 function baselineDirFor(configPath, configured) {
   return resolve(dirname(configPath), configured ?? DEFAULT_BASELINE_DIR);
 }
 function baselinePath(dir, scenario) {
-  return join(dir, `${scenario}.json`);
+  const reserved = /* @__PURE__ */ new Set(["scenarios", "coverage-allow", "unresolved-allow"]);
+  if (scenario.length === 0 || scenario === "." || scenario === ".." || scenario.includes("/") || scenario.includes("\\") || scenario.includes("\0") || reserved.has(scenario)) {
+    throw new Error(`invalid scenario name ${JSON.stringify(scenario)} \u2014 use a filename-safe name`);
+  }
+  const root = resolve(dir);
+  const path = resolve(root, `${scenario}.json`);
+  if (!path.startsWith(`${root}${sep}`)) {
+    throw new Error(`scenario ${JSON.stringify(scenario)} escapes the baseline directory`);
+  }
+  return path;
+}
+function scenarioManifestPath(dir) {
+  return join(dir, SCENARIO_MANIFEST_FILE);
 }
 function normalize(snapshot) {
   return serializeSurfaceSnapshot(snapshot);
 }
 function readBaseline(path) {
+  if (!existsSync(path)) return void 0;
   try {
     return JSON.parse(readFileSync(path, "utf8"));
-  } catch {
-    return void 0;
+  } catch (error) {
+    throw new Error(
+      `could not read baseline ${path}: ${error instanceof Error ? error.message : String(error)}`
+    );
   }
 }
 function writeBaseline(path, value) {
@@ -29,6 +45,18 @@ function writeBaseline(path, value) {
   writeFileSync(path, `${JSON.stringify(value, null, 2)}
 `, "utf8");
 }
+function readScenarioManifest(dir) {
+  const path = scenarioManifestPath(dir);
+  const value = readBaseline(path);
+  if (value === void 0) return void 0;
+  if (typeof value !== "object" || value === null || !Array.isArray(value.scenarios) || !value.scenarios.every((name) => typeof name === "string")) {
+    throw new Error(`${path} must contain { "scenarios": string[] }`);
+  }
+  return [...value.scenarios].sort();
+}
+function writeScenarioManifest(dir, scenarios) {
+  writeBaseline(scenarioManifestPath(dir), { scenarios: [...scenarios].sort() });
+}
 var PATH_SEGMENT = /([^.[\]]+)|\[(\d+)\]/g;
 function subjectFor(document, path) {
   let node = document;
@@ -97,7 +125,7 @@ function formatValue(value) {
 }
 
 // src/coverage.ts
-import { existsSync, readFileSync as readFileSync2 } from "fs";
+import { existsSync as existsSync2, readFileSync as readFileSync2 } from "fs";
 import { join as join2 } from "path";
 var ALLOWLIST_FILE = "coverage-allow.json";
 var UNREAD_ALLOWLIST_FILE = "unresolved-allow.json";
@@ -108,7 +136,7 @@ function unreadAllowlistPathFor(baselineDir) {
   return join2(baselineDir, UNREAD_ALLOWLIST_FILE);
 }
 function readAllowlist(path, keyName = "capabilityId") {
-  if (!existsSync(path)) return {};
+  if (!existsSync2(path)) return {};
   let parsed;
   try {
     parsed = JSON.parse(readFileSync2(path, "utf8"));
@@ -130,7 +158,7 @@ function readAllowlist(path, keyName = "capabilityId") {
   return allowlist;
 }
 function unreadKey(entry) {
-  return `${entry.origin.file}#${entry.reason ?? "unknown"}`;
+  return `${entry.origin.file}#${entry.reason ?? "unknown"}#${entry.origin.site}`;
 }
 function buildCoverageReport(input) {
   const unreached = [];
@@ -155,7 +183,8 @@ function buildCoverageReport(input) {
   const stillUnread = new Set(input.unresolved.map(unreadKey));
   const staleUnreadAllowlist = Object.keys(unreadAllowlist).filter((key) => !stillUnread.has(key)).sort();
   const unaccounted = [...input.reachedIds].filter((id) => !input.authored.has(id)).sort();
-  const domainReached = unaccounted.filter((id) => id.startsWith("domain:"));
+  const domainReached = [...input.reachedIds].filter((id) => id.startsWith("domain:")).sort();
+  const unmanifestedDomain = input.domainAuthoritative ? unaccounted.filter((id) => id.startsWith("domain:")) : [];
   const undeclared = unaccounted.filter((id) => !id.startsWith("domain:"));
   return {
     authored: input.authored.size,
@@ -166,6 +195,8 @@ function buildCoverageReport(input) {
     unreached,
     undeclared,
     domainReached,
+    unmanifestedDomain,
+    domainAuthoritative: input.domainAuthoritative === true,
     unresolved: unread,
     allowed,
     staleAllowlist,
@@ -177,6 +208,7 @@ function buildCoverageReport(input) {
 }
 function coverageExitCode(report, options = {}) {
   if (report.unreached.length > 0) return 1;
+  if (report.unmanifestedDomain.length > 0) return 1;
   if (report.unresolved.length > 0 && !options.allowUnresolved) return 1;
   if (report.staleAllowlist.length > 0) return 1;
   if (report.staleUnreadAllowlist.length > 0) return 1;
@@ -184,13 +216,34 @@ function coverageExitCode(report, options = {}) {
 }
 
 // src/extract.ts
-import { existsSync as existsSync2 } from "fs";
+import { createHash } from "crypto";
+import { existsSync as existsSync3, readFileSync as readFileSync3 } from "fs";
 import { dirname as dirname2, isAbsolute, join as join3, relative, resolve as resolve2 } from "path";
 import ts from "typescript";
 var UNRESOLVED_ID = "<unresolved>";
 function findTsconfig(from) {
   return ts.findConfigFile(resolve2(from), ts.sys.fileExists, "tsconfig.json");
 }
+function readLiteralConfigScope(configPath) {
+  const source = ts.createSourceFile(
+    configPath,
+    readFileSync3(configPath, "utf8"),
+    ts.ScriptTarget.Latest,
+    true,
+    configPath.endsWith("x") ? ts.ScriptKind.TSX : ts.ScriptKind.TS
+  );
+  let scope;
+  const visit = (node) => {
+    if (scope) return;
+    if (ts.isPropertyAssignment(node) && propertyName(node.name) === "scope" && ts.isArrayLiteralExpression(node.initializer)) {
+      const values = node.initializer.elements.map((entry) => literalText(entry));
+      if (values.every((value) => value !== void 0)) scope = values;
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(source);
+  return scope;
+}
 function readProgramFiles(tsconfigPath) {
   const read = ts.readConfigFile(tsconfigPath, ts.sys.readFile);
   if (read.error) {
@@ -210,9 +263,65 @@ function readProgramFiles(tsconfigPath) {
   }
   return { fileNames: parsed.fileNames, options: parsed.options };
 }
-function calleeName(call) {
-  if (ts.isIdentifier(call.expression)) return call.expression.text;
-  if (ts.isPropertyAccessExpression(call.expression)) return call.expression.name.text;
+var REGISTRATION_HOOKS = /* @__PURE__ */ new Set(["useAgentComponent", "useAgentAction", "useAgentObservation"]);
+function isRegistrationModule(specifier) {
+  return specifier.startsWith("@agent-surface/");
+}
+var NO_IMPORTS = { locals: /* @__PURE__ */ new Map(), namespaces: /* @__PURE__ */ new Set() };
+function importedRegistrations(source) {
+  const locals = /* @__PURE__ */ new Map();
+  const namespaces = /* @__PURE__ */ new Set();
+  for (const statement of source.statements) {
+    if (!ts.isImportDeclaration(statement)) continue;
+    if (!ts.isStringLiteral(statement.moduleSpecifier)) continue;
+    if (!isRegistrationModule(statement.moduleSpecifier.text)) continue;
+    const clause = statement.importClause;
+    if (!clause || clause.isTypeOnly || !clause.namedBindings) continue;
+    if (ts.isNamespaceImport(clause.namedBindings)) {
+      namespaces.add(clause.namedBindings.name.text);
+      continue;
+    }
+    for (const element of clause.namedBindings.elements) {
+      if (element.isTypeOnly) continue;
+      const imported = (element.propertyName ?? element.name).text;
+      if (REGISTRATION_HOOKS.has(imported)) locals.set(element.name.text, imported);
+    }
+  }
+  return { locals, namespaces };
+}
+function renamedRegistrationExports(source, imports) {
+  const renamed = [];
+  for (const statement of source.statements) {
+    if (!ts.isExportDeclaration(statement) || statement.isTypeOnly) continue;
+    const clause = statement.exportClause;
+    if (!clause || !ts.isNamedExports(clause)) continue;
+    const from = statement.moduleSpecifier;
+    const fromOurs = from !== void 0 && ts.isStringLiteral(from) && isRegistrationModule(from.text);
+    if (from && !fromOurs) continue;
+    for (const element of clause.elements) {
+      if (element.isTypeOnly) continue;
+      const local = (element.propertyName ?? element.name).text;
+      const hook = fromOurs ? REGISTRATION_HOOKS.has(local) ? local : void 0 : imports.locals.get(local);
+      if (hook === void 0 || element.name.text === hook) continue;
+      renamed.push({ node: element, hook, exported: element.name.text });
+    }
+  }
+  return renamed;
+}
+function namespaceMember(object, member, imports) {
+  return ts.isIdentifier(object) && imports.namespaces.has(object.text) && REGISTRATION_HOOKS.has(member);
+}
+function calleeName(call, imports = NO_IMPORTS) {
+  const callee = call.expression;
+  if (ts.isIdentifier(callee)) return imports.locals.get(callee.text) ?? callee.text;
+  if (ts.isPropertyAccessExpression(callee)) {
+    if (namespaceMember(callee.expression, callee.name.text, imports)) return callee.name.text;
+    return callee.name.text;
+  }
+  if (ts.isElementAccessExpression(callee)) {
+    const member = literalText(callee.argumentExpression);
+    if (member !== void 0 && namespaceMember(callee.expression, member, imports)) return member;
+  }
   return void 0;
 }
 function propertyName(name) {
@@ -375,9 +484,22 @@ function capabilitiesFromGroup(group, kind, componentType, componentPartial, emi
     emit.push(capability);
   }
 }
-function visitCall(call, emit, source, deferred, enclosing) {
-  const callee = calleeName(call);
-  if (callee === void 0) return;
+function visitCall(call, emit, source, imports, deferred, enclosing) {
+  const callee = calleeName(call, imports);
+  if (callee === void 0) {
+    const object = ts.isElementAccessExpression(call.expression) ? call.expression.expression : void 0;
+    if (object && ts.isIdentifier(object) && imports.namespaces.has(object.text)) {
+      emit.push({
+        capabilityId: UNRESOLVED_ID,
+        kind: "action",
+        origin: emit.origin(call),
+        resolution: "unresolved",
+        reason: "dynamic-callee",
+        note: `a call reads a computed member of \`${object.text}\`, a namespace of this library \u2014 which export it calls, and so whether it registers anything, cannot be read here`
+      });
+    }
+    return;
+  }
   if (GRANULAR_HOOKS.has(callee)) {
     emit.push({
       capabilityId: UNRESOLVED_ID,
@@ -502,10 +624,84 @@ function callsWrapper(site, wrapper, compilerOptions) {
   }
   return false;
 }
+function normalizedText(node, source) {
+  return node.getText(source).replace(/\s+/g, " ").trim();
+}
+function siteIdentity(source, node) {
+  const labels = [];
+  let enclosingCall = "";
+  let scope;
+  for (let parent = node.parent; parent && parent !== source; parent = parent.parent) {
+    if (!enclosingCall && ts.isCallExpression(parent)) {
+      enclosingCall = normalizedText(parent, source);
+    }
+    const named = (ts.isFunctionDeclaration(parent) || ts.isMethodDeclaration(parent)) && parent.name && (ts.isIdentifier(parent.name) || ts.isStringLiteral(parent.name)) ? parent.name.text : ts.isVariableDeclaration(parent) && ts.isIdentifier(parent.name) ? parent.name.text : void 0;
+    if (named !== void 0) {
+      labels.push(named);
+      scope ??= parent;
+    }
+  }
+  return { labels: labels.reverse(), enclosingCall, scope: scope ?? source };
+}
+function occurrence(scope, node, source) {
+  const text = normalizedText(node, source);
+  const start = node.getStart(source);
+  let rank = 0;
+  const visit = (candidate) => {
+    if (candidate.kind === node.kind && candidate.getStart(source) < start && normalizedText(candidate, source) === text) {
+      rank += 1;
+    }
+    ts.forEachChild(candidate, visit);
+  };
+  ts.forEachChild(scope, visit);
+  return rank;
+}
+function stableSite(source, node) {
+  const { labels, enclosingCall, scope } = siteIdentity(source, node);
+  return createHash("sha256").update(
+    `${labels.join("/")}\0${enclosingCall}\0${normalizedText(node, source)}\0${occurrence(
+      scope,
+      node,
+      source
+    )}`
+  ).digest("hex").slice(0, 12);
+}
+var packageNameCache = /* @__PURE__ */ new Map();
+function packageNameFor(file) {
+  let dir = dirname2(file);
+  for (; ; ) {
+    if (packageNameCache.has(dir)) return packageNameCache.get(dir);
+    const packagePath = join3(dir, "package.json");
+    if (existsSync3(packagePath)) {
+      let name;
+      try {
+        const parsed = JSON.parse(readFileSync3(packagePath, "utf8"));
+        if (typeof parsed.name === "string") name = parsed.name;
+      } catch {
+      }
+      packageNameCache.set(dir, name);
+      return name;
+    }
+    const parent = dirname2(dir);
+    if (parent === dir) return void 0;
+    dir = parent;
+  }
+}
+var IMPLEMENTATION_PACKAGES = /* @__PURE__ */ new Set([
+  "@agent-surface/core",
+  "@agent-surface/react",
+  "@agent-surface/orpc",
+  "@agent-surface/testing",
+  "@agent-surface/webmcp",
+  "@agent-surface/cli"
+]);
+function isAgentSurfaceImplementation(file) {
+  return IMPLEMENTATION_PACKAGES.has(packageNameFor(file) ?? "");
+}
 function extractCapabilities(options) {
   const root = resolve2(options.root);
   const tsconfigPath = options.tsconfig ? isAbsolute(options.tsconfig) ? options.tsconfig : join3(root, options.tsconfig) : findTsconfig(root);
-  if (!tsconfigPath || !existsSync2(tsconfigPath)) {
+  if (!tsconfigPath || !existsSync3(tsconfigPath)) {
     throw new Error(
       `no tsconfig.json found from ${root} \u2014 \`capabilities\` reads the TypeScript program, so it needs one (pass --tsconfig to point at it)`
     );
@@ -520,7 +716,7 @@ function extractCapabilities(options) {
   for (const source of program.getSourceFiles()) {
     if (source.isDeclarationFile) continue;
     if (source.fileName.includes("/node_modules/")) continue;
-    if (!isInside(root, source.fileName)) {
+    if (!isInside(root, source.fileName) && isAgentSurfaceImplementation(source.fileName)) {
       filesOutsideRoot += 1;
       continue;
     }
@@ -529,9 +725,21 @@ function extractCapabilities(options) {
       push: (capability) => capabilities.push(capability),
       origin: (node) => ({
         file: relative(root, source.fileName),
-        line: source.getLineAndCharacterOfPosition(node.getStart(source)).line + 1
+        line: source.getLineAndCharacterOfPosition(node.getStart(source)).line + 1,
+        site: stableSite(source, node)
       })
     };
+    const imports = importedRegistrations(source);
+    for (const renamed of renamedRegistrationExports(source, imports)) {
+      emit.push({
+        capabilityId: UNRESOLVED_ID,
+        kind: "action",
+        origin: emit.origin(renamed.node),
+        resolution: "unresolved",
+        reason: "dynamic-callee",
+        note: `${renamed.hook}() leaves this module as \`${renamed.exported}\`, so nothing at its call sites elsewhere proves they register anything \u2014 whatever they author is not in this catalog`
+      });
+    }
     let pendingName;
     const visit = (node, enclosing) => {
       const fn = functionLike(node);
@@ -543,7 +751,7 @@ function extractCapabilities(options) {
         pendingName = node.name.text;
       }
       if (ts.isCallExpression(node)) {
-        visitCall(node, emit, source, deferred, enclosing);
+        visitCall(node, emit, source, imports, deferred, enclosing);
         if (ts.isIdentifier(node.expression)) {
           const name = node.expression.text;
           const sites = callsByName.get(name) ?? [];
@@ -634,6 +842,9 @@ function readInventory(options) {
     ...options.tsconfig ? { tsconfig: options.tsconfig } : {}
   });
 }
+function staticConfigScope(options) {
+  return options.scope ?? readLiteralConfigScope(options.configPath);
+}
 async function mountScenarios(options, onEach) {
   if (options.depth === "static") return void 0;
   const runner = await createSurfaceRunner(options.configPath);
@@ -644,6 +855,7 @@ async function mountScenarios(options, onEach) {
       );
     }
     const scenarios = options.scenario ? [options.scenario] : runner.scenarioNames;
+    const effectiveScope = options.scope ?? runner.config.scope;
     const results = [];
     const failures = [];
     for (const scenario of scenarios) {
@@ -665,12 +877,16 @@ async function mountScenarios(options, onEach) {
     }
     return {
       scenarios,
+      declaredScenarios: runner.scenarioNames,
       results,
       failures,
       baselineDir: baselineDirFor(
         options.configPath,
         options.baselineDir ?? runner.config.baselineDir
-      )
+      ),
+      ...effectiveScope ? { scope: effectiveScope } : {},
+      domainCapabilities: Object.keys(runner.config.manifest?.tools ?? {}).map((path) => `domain:${path}`).sort(),
+      domainManifestConfigured: runner.config.manifest !== void 0
     };
   } finally {
     await runner.close();
@@ -681,10 +897,23 @@ function componentTypeOf(capabilityId) {
   const dot = withoutPlane.lastIndexOf(".");
   return dot === -1 ? withoutPlane : withoutPlane.slice(0, dot);
 }
+function scopeInventory(inventory, scope) {
+  if (!inventory || !scope) return inventory;
+  return {
+    ...inventory,
+    capabilities: inventory.capabilities.filter(
+      (capability) => capability.resolution === "unresolved" || matchesScope(componentTypeOf(capability.capabilityId), scope)
+    )
+  };
+}
+function scopeCapabilityIds(ids, scope) {
+  return scope ? ids.filter((id) => matchesScope(componentTypeOf(id), scope)) : ids;
+}
 function joinCoverage(inventory, runtime, options) {
   if (!inventory || !runtime) return void 0;
   if (runtime.failures.length > 0) return void 0;
-  const inScope = (capabilityId) => matchesScope(componentTypeOf(capabilityId), options.scope);
+  const effectiveScope = options.scope ?? runtime.scope;
+  const inScope = (capabilityId) => matchesScope(componentTypeOf(capabilityId), effectiveScope);
   const origins = /* @__PURE__ */ new Map();
   for (const capability of inventory.capabilities) {
     if (!origins.has(capability.capabilityId)) {
@@ -692,6 +921,12 @@ function joinCoverage(inventory, runtime, options) {
     }
   }
   const authored = new Set([...authoredIds(inventory)].filter(inScope));
+  for (const capabilityId of runtime.domainCapabilities) {
+    if (inScope(capabilityId)) authored.add(capabilityId);
+    if (!origins.has(capabilityId)) {
+      origins.set(capabilityId, { file: "oRPC manifest", line: 0 });
+    }
+  }
   const reachedIds = /* @__PURE__ */ new Set();
   for (const result of runtime.results) {
     for (const capability of result.explanation.capabilities) {
@@ -705,13 +940,14 @@ function joinCoverage(inventory, runtime, options) {
   );
   const unreadAllowlistPath = unreadAllowlistPathFor(runtime.baselineDir);
   return buildCoverageReport({
-    unreadAllowlist: readAllowlist(unreadAllowlistPath, "file#reason"),
+    unreadAllowlist: readAllowlist(unreadAllowlistPath, "file#reason#site"),
     unreadAllowlistPath,
+    domainAuthoritative: runtime.domainManifestConfigured,
     authored,
     origins,
     reachedIds,
     scenarios: runtime.scenarios,
-    ...options.scope ? { scope: options.scope } : {},
+    ...effectiveScope ? { scope: effectiveScope } : {},
     unresolved: unresolved(inventory),
     allowlist,
     allowlistOutOfScope: Object.keys(wholeAllowlist).length - Object.keys(allowlist).length,
@@ -720,13 +956,18 @@ function joinCoverage(inventory, runtime, options) {
 }
 
 export {
+  SCENARIO_MANIFEST_FILE,
   baselinePath,
   normalize,
   readBaseline,
   writeBaseline,
+  readScenarioManifest,
+  writeScenarioManifest,
   annotate,
   diff,
   formatValue,
+  ALLOWLIST_FILE,
+  UNREAD_ALLOWLIST_FILE,
   unreadKey,
   coverageExitCode,
   findTsconfig,
@@ -734,7 +975,10 @@ export {
   authoredIds,
   unresolved,
   readInventory,
+  staticConfigScope,
   mountScenarios,
+  scopeInventory,
+  scopeCapabilityIds,
   joinCoverage
 };
-//# sourceMappingURL=chunk-2FG527AM.js.map
+//# sourceMappingURL=chunk-Q5WOLWEW.js.map