candor-ts 0.7.0 → 0.7.2

package/AGENTS.md

@@ -75,6 +75,7 @@ Q impact   $P <fn-query>            # THE BLAST RADIUS: {fn, affectedCount, affe
 Q callers  $P <fn-query> 1          # the lower-level form: {of, direct, transitive} — works for pure fns
 Q path     $P <fn> <Effect>         # how a fn reaches an effect: the chain to the nearest source
 Q map      $P 1                     # {module: {effects, functions}}
+Q containment $P [baseline-prefix]  # §6.1 boundary-effect dispersion; with a baseline = AS-EFF-010 ratchet (exit 1 on a leak)
 Q whatif   $P <fn> <Effect> [policy]  # pre-edit gate verdict (exit 1 if it would violate)
 Q diff     $P <baseline-prefix> 1   # per-function effect delta (exit 1 on a gained effect)
 Q gains    $P <baseline-prefix>     # supply-chain alarm: {gained, byFunction} — effects a surface grew

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "candor-ts",
-  "version": "0.7.0",
+  "version": "0.7.2",
   "description": "candor for TypeScript — per-function side effects, transitively, with a policy gate (candor-spec 0.5)",
   "type": "module",
   "dependencies": {

package/query-core.mjs

@@ -229,6 +229,74 @@ export function map(fns) {
     .map(([k, v]) => [k, { effects: [...v.effects].sort(), functions: v.functions }]));
 }
 
+// containment (SPEC §6.1) — how well each BOUNDARY effect stays in one layer (dispersion, NOT a count),
+// with the AS-EFF-010 ratchet when a baseline is given. Mirrors candor-java Query.containment and
+// candor-query cmd_containment: boundary effects are scored, ambient ones reported-not-scored; a layer is
+// the segment AFTER the common dotted prefix ("(root)" when no package layer follows). Uses DIRECT effects.
+export const CONTAINED = ["Db", "Net", "Exec", "Fs", "Ipc", "Clipboard"];
+export const AMBIENT = ["Log", "Clock", "Rand", "Env"];
+function commonPrefixLen(fns) {
+  let best = null;
+  for (const e of fns) {
+    const segs = e.fn.split(".");
+    if (best === null) { best = segs; continue; }
+    let i = 0; const n = Math.min(best.length, segs.length);
+    while (i < n && best[i] === segs[i]) i++;
+    best = best.slice(0, i);
+  }
+  return (best ?? []).length;
+}
+function layerOf(fn, prefixLen) {
+  // The layer = the first segment after the common prefix, the leaf excluded. candor-ts names functions
+  // with a FILE.fn (free fns) or FILE.Class.method tail — a SHALLOW 1-segment-minimum tail — so the rule is
+  // `prefixLen + 1 < length` (matching candor-rust's layer_of). candor-java uses `+2` because its names carry
+  // an extra Package.Class.method segment; copying that here collapsed every 2-segment free function to
+  // "(root)", killing the dispersion signal on real TS reports.
+  const segs = fn.split(".");
+  return prefixLen + 1 < segs.length ? segs[prefixLen] : "(root)";
+}
+export function containment(fns, baseFns) {
+  const pl = commonPrefixLen(fns);
+  const known = new Set([...CONTAINED, ...AMBIENT]);
+  const byEff = {}; // effect -> { layer -> count }, over DIRECT effects
+  for (const e of fns) for (const eff of (e.direct ?? [])) {
+    if (!known.has(eff)) continue;
+    const layer = layerOf(e.fn, pl);
+    (byEff[eff] ??= {})[layer] = (byEff[eff][layer] ?? 0) + 1;
+  }
+  // RATCHET: a baseline was given — flag any contained effect now in a layer it wasn't in (a leak), note removals.
+  if (baseFns) {
+    const bpl = commonPrefixLen(baseFns);
+    const baseLayers = {};
+    for (const e of baseFns) for (const eff of (e.direct ?? [])) {
+      if (!CONTAINED.includes(eff)) continue;
+      (baseLayers[eff] ??= new Set()).add(layerOf(e.fn, bpl));
+    }
+    const leaks = [], cleanups = [];
+    for (const eff of CONTAINED) {
+      const now = new Set(Object.keys(byEff[eff] ?? {}));
+      const was = baseLayers[eff] ?? new Set();
+      for (const l of now) if (!was.has(l)) leaks.push(`${eff} → ${l}`);
+      for (const l of was) if (!now.has(l)) cleanups.push(`${eff} ⊘ ${l}`);
+    }
+    return { leaks: leaks.sort(), cleanups: cleanups.sort() };
+  }
+  // REPORT: the containment diagnostic.
+  const contained = [];
+  for (const eff of CONTAINED) {
+    const layers = byEff[eff]; if (!layers) continue;
+    const entries = Object.entries(layers);
+    const tot = entries.reduce((a, [, n]) => a + n, 0);
+    const owner = entries.slice().sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))[0];
+    const placement = Object.fromEntries(entries.slice().sort((a, b) => a[0].localeCompare(b[0])));
+    contained.push({ effect: eff, containmentPct: Math.floor((100 * owner[1]) / tot),
+                     layers: entries.length, owner: owner[0], placement });
+  }
+  const ambient = {};
+  for (const eff of AMBIENT) if (byEff[eff]) ambient[eff] = Object.keys(byEff[eff]).length;
+  return { contained, ambient };
+}
+
 export function reachable(fns) {
   const roots = fns.filter((e) => e.entryPoint);
   const byEff = {};

package/query.mjs

@@ -27,6 +27,7 @@ import { printAgents } from "./contract.mjs";
 import { impact as coreImpact, path as corePath, gains as coreGains,
          show as coreShow, blindspots as coreBlindspots,
          callers as coreCallers, callersFrontier, loadHierarchy,
+         containment as coreContainment,
          loadReport, loadCallgraph, matches } from "./query-core.mjs";
 const emit = (v) => console.log(JSON.stringify(v, null, 1));
 
@@ -83,6 +84,23 @@ switch (cmd) {
       .map(([k, v]) => [k, { effects: [...v.effects].sort(), functions: v.functions }])));
     break;
   }
+  case "containment": {
+    // SPEC §6.1 boundary-effect dispersion; with a baseline prefix it's the AS-EFF-010 ratchet (exit 1 on a
+    // new leak), matching candor-java / candor-query. JSON-only, like every other candor-ts query command.
+    const [prefix, basePrefix] = args;
+    if (basePrefix) {
+      const baseFns = loadReport(basePrefix);
+      if (baseFns.length === 0) {   // fail CLOSED (exit 2), not a wall of bogus "everything leaked" (exit 1)
+        console.error(`candor-ts: no report at baseline prefix '${basePrefix}' — check the path`);
+        process.exit(2);
+      }
+      const r = coreContainment(loadReport(prefix), baseFns);
+      emit(r);
+      process.exit(r.leaks.length ? 1 : 0);
+    }
+    emit(coreContainment(loadReport(prefix)));
+    break;
+  }
   case "diff": {
     // per-function effect delta vs a baseline: {changes: [{fn, gained, lost}]} — the envelope shape
     // the conformance suite pins (diff-vs-self must be {changes: []}).