@suss/checker-intent 0.21.1 → 0.22.0

package/README.md

@@ -27,6 +27,7 @@ the same boundary key, and emits:
 - `undeclaredOutcome`: code produces a REST status, or reaches a boundary, that the intent doesn't declare (info; intent under-specifies).
 - `unkeyableBoundary`: the intent's boundary has no key to pair on, so nothing was compared (warning).
 - `undescribedOutcome`: a declared outcome no PRD scenario links to (info).
+- `renamedBoundary`: a declared store the unit never touches, paired with an undeclared store of the same system it touches with the same verbs on the same outcomes instead.
 
 v0 checks system intent (`kind: boundary`). PRD outcome intent
 (`kind: prd`), which covers scenarios and links, is a separate pass.
@@ -53,10 +54,16 @@ An access whose container the code cannot settle (a wrapper handed its table as
 
 A `when` clause that says which boundary the branch read is compared too, which is what makes `when` more than prose.
 
-`boundaryGuardsOf` in `@suss/behavioral-ir` says, for each branch of the code, which boundary its guards turned on and whether the guard passed because something was there. A declared outcome then narrows to the branches whose guards match every boundary clause the intent stated, and `uncoveredOutcome` reports one that produces the ending on a different condition. So an intent saying "404 when a read of `aws.dynamodb:Invoices` finds nothing" fails when the code's 404 turns on the row being present.
+`boundaryGuardsOf` in `@suss/behavioral-ir` says, for each branch of the code, which boundary its guards turned on and whether the guard passed because something was there. A declared outcome then narrows to the branches whose guards match every boundary clause the intent stated, and `uncoveredOutcome` reports one that produces the ending on a different condition. So an intent saying "404 when a read of `aws.dynamodb:Invoices` finds nothing" fails when the code's 404 turns on the row being present. When the unit makes no effect against that boundary anywhere, in any transition, the message points at the boundary as the cause instead.
 
 The boundary resolves through `namesBoundary` again, and `finds` has to agree when the clause states it. A clause about an input, and a clause left as a sentence, are prose to this pass and are not compared: the paths and the words have no counterpart in the summary to check against.
 
+## When a store was renamed
+
+A store that gets renamed in code without the intent doc catching up produces a pile of findings from one cause: the old name is declared and never touched, the new one is touched and never declared, and both an `uncoveredOutcome` (for the vanished store) and an `undeclaredOutcome` (for the one that appeared) fire for every verb and every outcome that used it. `renamedBoundary` folds all of those into one finding when the pairing is unambiguous: the two boundaries share a system prefix, their verbs match exactly, the new one satisfies every declared use the old one had, and each side has exactly one candidate on the other. It stays an error, same as the findings it replaces: the document and the code still disagree, and folding is a guess about the cause rather than a change in whether that disagreement matters.
+
+Pairing only considers reads and writes. A queue channel or a deployed unit is addressed by name, so a different callee produces its own uncoveredOutcome and undeclaredOutcome findings without folding.
+
 ## The coverage question, both ways
 
 The three scenario kinds ask whether a scenario points at an outcome that exists. `undescribedOutcome` asks it the other way: which declared behaviour has nobody written down a reason for. That is the question a product reader has, and the two artifacts to answer it from are the same two.

package/dist/index.cjs

@@ -335,20 +335,33 @@ function compareIntentToImpl(intent, impl, boundary, deployment) {
   const everyEffect = impl.transitions.flatMap(
     (t) => codeEffectsOf(t, deployment)
   );
+  const vanished = [];
+  const undeclared = [];
   for (const outcome of intent.outcomes) {
     const reached = outcome.kind === "effect" ? everyEffect : codeOutcomes.filter((co) => outcomeMatches(outcome, co)).flatMap((co) => co.effects);
     for (const effect of outcome.effects) {
       if (reached.some((made) => effectMatches(effect, made))) {
         continue;
       }
-      findings.push({
+      const finding = {
         kind: "uncoveredOutcome",
         severity: "error",
         boundary,
         intent: { name: intent.name, outcomeId: outcome.id },
         code: ref,
         message: `Intent "${intent.name}" declares that ${outcome.id} results in ${describeEffect(effect)} at ${boundary}; no transition of ${impl.identity.name} does that.${unsettledNote(reached, effect, deployment)}`
-      });
+      };
+      findings.push(finding);
+      if (neverTouchesBoundary(effect.names, everyEffect)) {
+        vanished.push({
+          finding,
+          boundary: effect.names,
+          does: effect.does,
+          kind: "effect",
+          effect,
+          reached
+        });
+      }
     }
     if (outcome.kind === "effect") {
       continue;
@@ -375,14 +388,32 @@ function compareIntentToImpl(intent, impl, boundary, deployment) {
       const unmet = stated.find(
         (c) => !ending.some((co) => conditionMet(c, co.turnsOn))
       );
-      findings.push({
+      const finding = {
         kind: "uncoveredOutcome",
         severity: "error",
         boundary,
         intent: { name: intent.name, outcomeId: outcome.id },
         code: ref,
-        message: `Intent "${intent.name}" declares ${describeOutcome(outcome)} at ${boundary} when ${unmet?.said ?? outcome.when}; ${impl.identity.name} produces it on a different condition.`
-      });
+        message: unmetConditionMessage(
+          intent,
+          outcome,
+          boundary,
+          impl,
+          unmet,
+          everyEffect
+        )
+      };
+      findings.push(finding);
+      if (unmet !== void 0 && neverTouchesBoundary(unmet.at.names, everyEffect)) {
+        vanished.push({
+          finding,
+          boundary: unmet.at.names,
+          does: unmet.at.does,
+          kind: "condition",
+          unmet,
+          ending
+        });
+      }
       continue;
     }
     const declaredBody = outcome.body;
@@ -436,16 +467,163 @@ function compareIntentToImpl(intent, impl, boundary, deployment) {
       continue;
     }
     said.add(spelled);
-    findings.push({
+    const finding = {
       kind: "undeclaredOutcome",
       severity: "info",
       boundary,
       intent: { name: intent.name },
       code: ref,
       message: `${impl.identity.name} ${spelled} at ${boundary}; intent "${intent.name}" does not declare it.`
+    };
+    findings.push(finding);
+    undeclared.push({ finding, boundary: made.label, does: made.does });
+  }
+  return foldRenamedBoundaries(
+    intent,
+    impl,
+    boundary,
+    ref,
+    findings,
+    vanished,
+    undeclared
+  );
+}
+function neverTouchesBoundary(names, everyEffect) {
+  return everyEffect.every((made) => !(0, import_ir_core.namesBoundary)(names, made.binding));
+}
+function unmetConditionMessage(intent, outcome, boundary, impl, unmet, everyEffect) {
+  const declared = `Intent "${intent.name}" declares ${describeOutcome(outcome)} at ${boundary} when ${unmet?.said ?? outcome.when}`;
+  if (unmet !== void 0 && neverTouchesBoundary(unmet.at.names, everyEffect)) {
+    return `${declared}; ${impl.identity.name} never ${unmet.at.does} ${unmet.at.names}.`;
+  }
+  return `${declared}; ${impl.identity.name} produces it on a different condition.`;
+}
+function satisfiedBy(use, candidate) {
+  if (use.kind === "effect") {
+    return use.reached.some(
+      (made) => effectMatches({ ...use.effect, names: candidate }, made)
+    );
+  }
+  return use.ending.some(
+    (co) => conditionMet(
+      { ...use.unmet, at: { ...use.unmet.at, names: candidate } },
+      co.turnsOn
+    )
+  );
+}
+function foldRenamedBoundaries(intent, impl, boundary, ref, findings, vanished, undeclared) {
+  const vanishedByBoundary = groupByBoundary(vanished);
+  const undeclaredByBoundary = groupByBoundary(undeclared);
+  const pairings = matchRenamedBoundaries(
+    vanishedByBoundary,
+    undeclaredByBoundary
+  );
+  if (pairings.length === 0) {
+    return findings;
+  }
+  const explained = /* @__PURE__ */ new Set();
+  const renamed = [];
+  for (const pairing of pairings) {
+    for (const use of pairing.vanishedUses) {
+      explained.add(use.finding);
+    }
+    for (const use of pairing.undeclaredUses) {
+      explained.add(use.finding);
+    }
+    renamed.push({
+      kind: "renamedBoundary",
+      severity: "error",
+      boundary,
+      intent: { name: intent.name },
+      code: ref,
+      message: `Intent "${intent.name}" declares ${pairing.from}; ${impl.identity.name} ${joinVerbs(pairing.does)} ${pairing.to} instead, with the same outcomes. If the store was renamed, update the intent.`
     });
   }
-  return findings;
+  return [...findings.filter((finding) => !explained.has(finding)), ...renamed];
+}
+function matchRenamedBoundaries(vanishedByBoundary, undeclaredByBoundary) {
+  const candidatesFor = /* @__PURE__ */ new Map();
+  const candidateCountAgainst = /* @__PURE__ */ new Map();
+  for (const [from, uses] of vanishedByBoundary) {
+    const verbs = new Set(uses.map((use) => use.does));
+    if (!isStorageVerbs(verbs)) {
+      continue;
+    }
+    for (const [to, madeUses] of undeclaredByBoundary) {
+      if (!sameSystem(from, to)) {
+        continue;
+      }
+      if (!sameVerbs(verbs, new Set(madeUses.map((use) => use.does)))) {
+        continue;
+      }
+      if (!uses.every((use) => satisfiedBy(use, to))) {
+        continue;
+      }
+      pushCandidate(candidatesFor, from, {
+        from,
+        to,
+        does: verbs,
+        vanishedUses: uses,
+        undeclaredUses: madeUses
+      });
+      incrementCount(candidateCountAgainst, to);
+    }
+  }
+  const pairings = [];
+  for (const [, candidates] of candidatesFor) {
+    if (candidates.length !== 1) {
+      continue;
+    }
+    const [pairing] = candidates;
+    if (candidateCountAgainst.get(pairing.to) !== 1) {
+      continue;
+    }
+    pairings.push(pairing);
+  }
+  return pairings;
+}
+function pushCandidate(map, key, value) {
+  const existing = map.get(key);
+  if (existing === void 0) {
+    map.set(key, [value]);
+    return;
+  }
+  existing.push(value);
+}
+function incrementCount(map, key) {
+  map.set(key, (map.get(key) ?? 0) + 1);
+}
+function isStorageVerbs(verbs) {
+  return [...verbs].every((verb) => verb === "reads" || verb === "writes");
+}
+function sameVerbs(a, b) {
+  return a.size === b.size && [...a].every((verb) => b.has(verb));
+}
+function sameSystem(a, b) {
+  return a !== b && systemPrefix(a) === systemPrefix(b);
+}
+function systemPrefix(name) {
+  const colon = name.indexOf(":");
+  return colon === -1 ? name : name.slice(0, colon + 1);
+}
+function joinVerbs(verbs) {
+  const list = [...verbs];
+  if (list.length < 2) {
+    return list.join("");
+  }
+  return `${list.slice(0, -1).join(", ")} and ${list[list.length - 1]}`;
+}
+function groupByBoundary(items) {
+  const groups = /* @__PURE__ */ new Map();
+  for (const item of items) {
+    const bucket = groups.get(item.boundary);
+    if (bucket === void 0) {
+      groups.set(item.boundary, [item]);
+      continue;
+    }
+    bucket.push(item);
+  }
+  return groups;
 }
 function unsettledNote(reached, declared, deployment) {
   const variables = /* @__PURE__ */ new Set();

package/dist/index.js

@@ -330,20 +330,33 @@ function compareIntentToImpl(intent, impl, boundary, deployment) {
   const everyEffect = impl.transitions.flatMap(
     (t) => codeEffectsOf(t, deployment)
   );
+  const vanished = [];
+  const undeclared = [];
   for (const outcome of intent.outcomes) {
     const reached = outcome.kind === "effect" ? everyEffect : codeOutcomes.filter((co) => outcomeMatches(outcome, co)).flatMap((co) => co.effects);
     for (const effect of outcome.effects) {
       if (reached.some((made) => effectMatches(effect, made))) {
         continue;
       }
-      findings.push({
+      const finding = {
         kind: "uncoveredOutcome",
         severity: "error",
         boundary,
         intent: { name: intent.name, outcomeId: outcome.id },
         code: ref,
         message: `Intent "${intent.name}" declares that ${outcome.id} results in ${describeEffect(effect)} at ${boundary}; no transition of ${impl.identity.name} does that.${unsettledNote(reached, effect, deployment)}`
-      });
+      };
+      findings.push(finding);
+      if (neverTouchesBoundary(effect.names, everyEffect)) {
+        vanished.push({
+          finding,
+          boundary: effect.names,
+          does: effect.does,
+          kind: "effect",
+          effect,
+          reached
+        });
+      }
     }
     if (outcome.kind === "effect") {
       continue;
@@ -370,14 +383,32 @@ function compareIntentToImpl(intent, impl, boundary, deployment) {
       const unmet = stated.find(
         (c) => !ending.some((co) => conditionMet(c, co.turnsOn))
       );
-      findings.push({
+      const finding = {
         kind: "uncoveredOutcome",
         severity: "error",
         boundary,
         intent: { name: intent.name, outcomeId: outcome.id },
         code: ref,
-        message: `Intent "${intent.name}" declares ${describeOutcome(outcome)} at ${boundary} when ${unmet?.said ?? outcome.when}; ${impl.identity.name} produces it on a different condition.`
-      });
+        message: unmetConditionMessage(
+          intent,
+          outcome,
+          boundary,
+          impl,
+          unmet,
+          everyEffect
+        )
+      };
+      findings.push(finding);
+      if (unmet !== void 0 && neverTouchesBoundary(unmet.at.names, everyEffect)) {
+        vanished.push({
+          finding,
+          boundary: unmet.at.names,
+          does: unmet.at.does,
+          kind: "condition",
+          unmet,
+          ending
+        });
+      }
       continue;
     }
     const declaredBody = outcome.body;
@@ -431,16 +462,163 @@ function compareIntentToImpl(intent, impl, boundary, deployment) {
       continue;
     }
     said.add(spelled);
-    findings.push({
+    const finding = {
       kind: "undeclaredOutcome",
       severity: "info",
       boundary,
       intent: { name: intent.name },
       code: ref,
       message: `${impl.identity.name} ${spelled} at ${boundary}; intent "${intent.name}" does not declare it.`
+    };
+    findings.push(finding);
+    undeclared.push({ finding, boundary: made.label, does: made.does });
+  }
+  return foldRenamedBoundaries(
+    intent,
+    impl,
+    boundary,
+    ref,
+    findings,
+    vanished,
+    undeclared
+  );
+}
+function neverTouchesBoundary(names, everyEffect) {
+  return everyEffect.every((made) => !namesBoundary(names, made.binding));
+}
+function unmetConditionMessage(intent, outcome, boundary, impl, unmet, everyEffect) {
+  const declared = `Intent "${intent.name}" declares ${describeOutcome(outcome)} at ${boundary} when ${unmet?.said ?? outcome.when}`;
+  if (unmet !== void 0 && neverTouchesBoundary(unmet.at.names, everyEffect)) {
+    return `${declared}; ${impl.identity.name} never ${unmet.at.does} ${unmet.at.names}.`;
+  }
+  return `${declared}; ${impl.identity.name} produces it on a different condition.`;
+}
+function satisfiedBy(use, candidate) {
+  if (use.kind === "effect") {
+    return use.reached.some(
+      (made) => effectMatches({ ...use.effect, names: candidate }, made)
+    );
+  }
+  return use.ending.some(
+    (co) => conditionMet(
+      { ...use.unmet, at: { ...use.unmet.at, names: candidate } },
+      co.turnsOn
+    )
+  );
+}
+function foldRenamedBoundaries(intent, impl, boundary, ref, findings, vanished, undeclared) {
+  const vanishedByBoundary = groupByBoundary(vanished);
+  const undeclaredByBoundary = groupByBoundary(undeclared);
+  const pairings = matchRenamedBoundaries(
+    vanishedByBoundary,
+    undeclaredByBoundary
+  );
+  if (pairings.length === 0) {
+    return findings;
+  }
+  const explained = /* @__PURE__ */ new Set();
+  const renamed = [];
+  for (const pairing of pairings) {
+    for (const use of pairing.vanishedUses) {
+      explained.add(use.finding);
+    }
+    for (const use of pairing.undeclaredUses) {
+      explained.add(use.finding);
+    }
+    renamed.push({
+      kind: "renamedBoundary",
+      severity: "error",
+      boundary,
+      intent: { name: intent.name },
+      code: ref,
+      message: `Intent "${intent.name}" declares ${pairing.from}; ${impl.identity.name} ${joinVerbs(pairing.does)} ${pairing.to} instead, with the same outcomes. If the store was renamed, update the intent.`
     });
   }
-  return findings;
+  return [...findings.filter((finding) => !explained.has(finding)), ...renamed];
+}
+function matchRenamedBoundaries(vanishedByBoundary, undeclaredByBoundary) {
+  const candidatesFor = /* @__PURE__ */ new Map();
+  const candidateCountAgainst = /* @__PURE__ */ new Map();
+  for (const [from, uses] of vanishedByBoundary) {
+    const verbs = new Set(uses.map((use) => use.does));
+    if (!isStorageVerbs(verbs)) {
+      continue;
+    }
+    for (const [to, madeUses] of undeclaredByBoundary) {
+      if (!sameSystem(from, to)) {
+        continue;
+      }
+      if (!sameVerbs(verbs, new Set(madeUses.map((use) => use.does)))) {
+        continue;
+      }
+      if (!uses.every((use) => satisfiedBy(use, to))) {
+        continue;
+      }
+      pushCandidate(candidatesFor, from, {
+        from,
+        to,
+        does: verbs,
+        vanishedUses: uses,
+        undeclaredUses: madeUses
+      });
+      incrementCount(candidateCountAgainst, to);
+    }
+  }
+  const pairings = [];
+  for (const [, candidates] of candidatesFor) {
+    if (candidates.length !== 1) {
+      continue;
+    }
+    const [pairing] = candidates;
+    if (candidateCountAgainst.get(pairing.to) !== 1) {
+      continue;
+    }
+    pairings.push(pairing);
+  }
+  return pairings;
+}
+function pushCandidate(map, key, value) {
+  const existing = map.get(key);
+  if (existing === void 0) {
+    map.set(key, [value]);
+    return;
+  }
+  existing.push(value);
+}
+function incrementCount(map, key) {
+  map.set(key, (map.get(key) ?? 0) + 1);
+}
+function isStorageVerbs(verbs) {
+  return [...verbs].every((verb) => verb === "reads" || verb === "writes");
+}
+function sameVerbs(a, b) {
+  return a.size === b.size && [...a].every((verb) => b.has(verb));
+}
+function sameSystem(a, b) {
+  return a !== b && systemPrefix(a) === systemPrefix(b);
+}
+function systemPrefix(name) {
+  const colon = name.indexOf(":");
+  return colon === -1 ? name : name.slice(0, colon + 1);
+}
+function joinVerbs(verbs) {
+  const list = [...verbs];
+  if (list.length < 2) {
+    return list.join("");
+  }
+  return `${list.slice(0, -1).join(", ")} and ${list[list.length - 1]}`;
+}
+function groupByBoundary(items) {
+  const groups = /* @__PURE__ */ new Map();
+  for (const item of items) {
+    const bucket = groups.get(item.boundary);
+    if (bucket === void 0) {
+      groups.set(item.boundary, [item]);
+      continue;
+    }
+    bucket.push(item);
+  }
+  return groups;
 }
 function unsettledNote(reached, declared, deployment) {
   const variables = /* @__PURE__ */ new Set();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suss/checker-intent",
-  "version": "0.21.1",
+  "version": "0.22.0",
   "type": "module",
   "description": "Pair team-authored intent (IntentSummary) against derived code (BehavioralSummary) and report where they diverge.",
   "keywords": [
@@ -47,9 +47,9 @@
     "zod": "^4.0.0"
   },
   "dependencies": {
-    "@suss/behavioral-ir": "0.21.1",
-    "@suss/intent-ir": "0.21.1",
-    "@suss/ir-core": "0.21.1"
+    "@suss/behavioral-ir": "0.22.0",
+    "@suss/intent-ir": "0.22.0",
+    "@suss/ir-core": "0.22.0"
   },
   "devDependencies": {
     "tsup": "*",