@suss/checker-intent 0.32.0 → 0.33.1

package/README.md

@@ -100,8 +100,8 @@ It does **not** depend on
 
 ## More
 
-- [Documentation](https://nimbuscloud-ai.github.io/suss/)
-- [Every package and pack suss ships](https://nimbuscloud-ai.github.io/suss/reference/packages)
+- [Documentation](https://suss.sh/)
+- [Every package and pack suss ships](https://suss.sh/packs/catalog)
 - [Source and issues](https://github.com/nimbuscloud-ai/suss)
 
 ## Coverage

package/dist/index.cjs

@@ -25,15 +25,109 @@ __export(index_exports, {
   whatWouldKeyIt: () => whatWouldKeyIt
 });
 module.exports = __toCommonJS(index_exports);
-var import_behavioral_ir = require("@suss/behavioral-ir");
+var import_behavioral_ir2 = require("@suss/behavioral-ir");
 var import_ir_core = require("@suss/ir-core");
+
+// src/receivedInput.ts
+var import_behavioral_ir = require("@suss/behavioral-ir");
+function overlaps(a, b) {
+  const left = comparable(a);
+  const right = comparable(b);
+  const shared = Math.min(left.length, right.length);
+  for (let i = 0; i < shared; i += 1) {
+    if (left[i] !== right[i]) {
+      return false;
+    }
+  }
+  return true;
+}
+function comparable(path) {
+  if (path[0] !== "headers") {
+    return [...path];
+  }
+  return path.map(
+    (segment, index) => index === 1 ? segment.toLowerCase() : segment
+  );
+}
+function checkReceivesBlock(pairing) {
+  const declared = pairing.intent.receives;
+  if (declared.length === 0) {
+    return [];
+  }
+  const result = (0, import_behavioral_ir.boundaryInputReads)(
+    pairing.impl,
+    pairing.intent.boundary,
+    pairing.wrappers
+  );
+  if (!result.read) {
+    return [];
+  }
+  const read = result.reads.paths;
+  const unread = declared.filter(
+    (field) => !read.some((path) => overlaps(path, field.path))
+  );
+  const alreadyDescribed = DESCRIBED_WITHOUT_LISTING[pairing.intent.boundary.semantics.name];
+  const undeclared = read.filter(
+    (path) => !declared.some((field) => overlaps(path, field.path)) && !alreadyDescribed(declared, path)
+  );
+  return [
+    ...unread.map((field) => unreadFinding(pairing, field)),
+    ...undeclaredFindings(pairing, undeclared)
+  ];
+}
+var LISTS_EVERYTHING = () => false;
+var DESCRIBED_WITHOUT_LISTING = {
+  rest: (declared, path) => path[0] === "body" && declared.some((field) => field.path[0] === "body"),
+  "function-call": LISTS_EVERYTHING,
+  "message-bus": LISTS_EVERYTHING,
+  storage: LISTS_EVERYTHING,
+  "unit-invocation": LISTS_EVERYTHING,
+  "graphql-resolver": LISTS_EVERYTHING,
+  "graphql-operation": LISTS_EVERYTHING,
+  "runtime-config": LISTS_EVERYTHING,
+  metric: LISTS_EVERYTHING
+};
+function unreadFinding(pairing, field) {
+  const needsIt = field.required ? " and needs it" : "";
+  return {
+    kind: "unreadInputField",
+    severity: field.required ? "warning" : "info",
+    boundary: pairing.boundary,
+    intent: { name: pairing.intent.name },
+    code: pairing.code,
+    message: `Intent "${pairing.intent.name}" says ${pairing.boundary} receives ${(0, import_behavioral_ir.formatPath)(field.path)}${needsIt}; ${pairing.impl.identity.name} never reads it.`
+  };
+}
+function undeclaredFindings(pairing, undeclared) {
+  const said = /* @__PURE__ */ new Set();
+  const findings = [];
+  for (const path of undeclared) {
+    const spelled = (0, import_behavioral_ir.formatPath)(path);
+    if (said.has(spelled)) {
+      continue;
+    }
+    said.add(spelled);
+    findings.push({
+      kind: "undeclaredInputRead",
+      severity: "info",
+      boundary: pairing.boundary,
+      intent: { name: pairing.intent.name },
+      code: pairing.code,
+      message: `${pairing.impl.identity.name} reads ${spelled} off what it was handed at ${pairing.boundary}; intent "${pairing.intent.name}" does not declare it under receives.`
+    });
+  }
+  return findings;
+}
+
+// src/index.ts
 function checkIntentAgreement(intents, code) {
   const findings = [];
   const checked = [];
   const unchecked = [];
   const codeByBoundary = indexCodeByBoundary(code);
   const boundaryByName = indexBoundaryIntentsByName(intents);
-  const deploymentOfUnit = (0, import_behavioral_ir.deploymentOf)(code);
+  const deploymentOfUnit = (0, import_behavioral_ir2.deploymentOf)(code);
+  const wrappersOfUnit = (0, import_behavioral_ir2.wrappersAround)(code);
   for (const intent of intents) {
     if (intent.kind === "prd") {
       const result2 = checkPrdCoverage(intent, boundaryByName);
@@ -44,7 +138,8 @@ function checkIntentAgreement(intents, code) {
     const result = checkBoundaryIntent(
       intent,
       codeByBoundary,
-      deploymentOfUnit
+      deploymentOfUnit,
+      wrappersOfUnit
     );
     findings.push(...withProvenance(result.findings, intent.source));
     checked.push(...result.checked);
@@ -88,7 +183,7 @@ function checkOutcomesDescribed(intents) {
   }
   return findings;
 }
-function checkBoundaryIntent(intent, codeByBoundary, deploymentOfUnit) {
+function checkBoundaryIntent(intent, codeByBoundary, deploymentOfUnit, wrappersOfUnit) {
   const key = (0, import_ir_core.pairingKey)(intent.boundary);
   if (key === null) {
     return {
@@ -142,7 +237,13 @@ function checkBoundaryIntent(intent, codeByBoundary, deploymentOfUnit) {
   const findings = [];
   for (const impl of impls) {
     findings.push(
-      ...compareIntentToImpl(intent, impl, label, deploymentOfUnit(impl))
+      ...compareIntentToImpl(
+        intent,
+        impl,
+        label,
+        deploymentOfUnit(impl),
+        wrappersOfUnit(impl)
+      )
     );
   }
   return {
@@ -159,7 +260,7 @@ function checkBoundaryIntent(intent, codeByBoundary, deploymentOfUnit) {
   };
 }
 function codeRef(impl) {
-  return (0, import_behavioral_ir.summaryRef)(impl);
+  return (0, import_behavioral_ir2.summaryRef)(impl);
 }
 function checkPrdCoverage(prd, boundaryByName) {
   const findings = [];
@@ -303,8 +404,8 @@ function applyIntentSuppressions(findings, rules, opts = {}) {
 }
 function indexCodeByBoundary(code) {
   const byKey = /* @__PURE__ */ new Map();
-  for (const summary of (0, import_behavioral_ir.withDeclaredDelivery)(code)) {
-    if (import_behavioral_ir.BOUNDARY_ROLE[summary.kind] !== "provider") {
+  for (const summary of (0, import_behavioral_ir2.withDeclaredDelivery)(code)) {
+    if (import_behavioral_ir2.BOUNDARY_ROLE[summary.kind] !== "provider") {
       continue;
     }
     if (summary.confidence.source === "declared") {
@@ -327,10 +428,10 @@ function indexCodeByBoundary(code) {
   }
   return byKey;
 }
-function compareIntentToImpl(intent, impl, boundary, deployment) {
+function compareIntentToImpl(intent, impl, boundary, deployment, wrappers) {
   const findings = [];
   const ref = codeRef(impl);
-  const calls = (0, import_behavioral_ir.boundaryCalls)(impl);
+  const calls = (0, import_behavioral_ir2.boundaryCalls)(impl);
   const codeOutcomes = impl.transitions.map((t) => toCodeOutcome(t, calls, deployment)).filter((o) => o !== null);
   const everyEffect = impl.transitions.flatMap(
     (t) => codeEffectsOf(t, deployment)
@@ -478,6 +579,9 @@ function compareIntentToImpl(intent, impl, boundary, deployment) {
     findings.push(finding);
     undeclared.push({ finding, boundary: made.label, does: made.does });
   }
+  findings.push(
+    ...checkReceivesBlock({ intent, impl, wrappers, boundary, code: ref })
+  );
   return foldRenamedBoundaries(
     intent,
     impl,
@@ -657,9 +761,9 @@ function conditionMet(declared, turnsOn) {
 function toCodeOutcome(t, calls, deployment) {
   const output = t.output;
   const effects = codeEffectsOf(t, deployment);
-  const turnsOn = (0, import_behavioral_ir.boundaryGuardsOf)(t, calls).map((guard) => ({
+  const turnsOn = (0, import_behavioral_ir2.boundaryGuardsOf)(t, calls).map((guard) => ({
     ...guard,
-    binding: (0, import_behavioral_ir.groundBinding)(guard.binding, deployment)
+    binding: (0, import_behavioral_ir2.groundBinding)(guard.binding, deployment)
   }));
   if (output.type === "response") {
     const status = output.statusCode !== null && output.statusCode.type === "literal" ? Number(output.statusCode.value) : null;
@@ -700,13 +804,13 @@ function codeEffectsOf(t, deployment) {
     if (effect.type !== "interaction") {
       continue;
     }
-    if ((0, import_behavioral_ir.goesThroughRelation)(effect.interaction)) {
+    if ((0, import_behavioral_ir2.goesThroughRelation)(effect.interaction)) {
       continue;
     }
-    const binding = (0, import_behavioral_ir.groundBinding)(effect.binding, deployment);
+    const binding = (0, import_behavioral_ir2.groundBinding)(effect.binding, deployment);
     const label = (0, import_ir_core.displayLabel)(binding);
     const touched = accessDetail(effect.interaction);
-    for (const does of (0, import_behavioral_ir.relationsOf)(effect.interaction)) {
+    for (const does of (0, import_behavioral_ir2.relationsOf)(effect.interaction)) {
       reached.push({ does, binding, label, ...touched });
     }
   }

package/dist/index.js

@@ -8,7 +8,8 @@ import {
   groundBinding,
   relationsOf,
   summaryRef,
-  withDeclaredDelivery
+  withDeclaredDelivery,
+  wrappersAround
 } from "@suss/behavioral-ir";
 import {
   applySuppressionsToFindings,
@@ -22,6 +23,99 @@ import {
   ruleBoundaryMatchesKey,
   semanticsAgree
 } from "@suss/ir-core";
+
+// src/receivedInput.ts
+import { boundaryInputReads, formatPath } from "@suss/behavioral-ir";
+function overlaps(a, b) {
+  const left = comparable(a);
+  const right = comparable(b);
+  const shared = Math.min(left.length, right.length);
+  for (let i = 0; i < shared; i += 1) {
+    if (left[i] !== right[i]) {
+      return false;
+    }
+  }
+  return true;
+}
+function comparable(path) {
+  if (path[0] !== "headers") {
+    return [...path];
+  }
+  return path.map(
+    (segment, index) => index === 1 ? segment.toLowerCase() : segment
+  );
+}
+function checkReceivesBlock(pairing) {
+  const declared = pairing.intent.receives;
+  if (declared.length === 0) {
+    return [];
+  }
+  const result = boundaryInputReads(
+    pairing.impl,
+    pairing.intent.boundary,
+    pairing.wrappers
+  );
+  if (!result.read) {
+    return [];
+  }
+  const read = result.reads.paths;
+  const unread = declared.filter(
+    (field) => !read.some((path) => overlaps(path, field.path))
+  );
+  const alreadyDescribed = DESCRIBED_WITHOUT_LISTING[pairing.intent.boundary.semantics.name];
+  const undeclared = read.filter(
+    (path) => !declared.some((field) => overlaps(path, field.path)) && !alreadyDescribed(declared, path)
+  );
+  return [
+    ...unread.map((field) => unreadFinding(pairing, field)),
+    ...undeclaredFindings(pairing, undeclared)
+  ];
+}
+var LISTS_EVERYTHING = () => false;
+var DESCRIBED_WITHOUT_LISTING = {
+  rest: (declared, path) => path[0] === "body" && declared.some((field) => field.path[0] === "body"),
+  "function-call": LISTS_EVERYTHING,
+  "message-bus": LISTS_EVERYTHING,
+  storage: LISTS_EVERYTHING,
+  "unit-invocation": LISTS_EVERYTHING,
+  "graphql-resolver": LISTS_EVERYTHING,
+  "graphql-operation": LISTS_EVERYTHING,
+  "runtime-config": LISTS_EVERYTHING,
+  metric: LISTS_EVERYTHING
+};
+function unreadFinding(pairing, field) {
+  const needsIt = field.required ? " and needs it" : "";
+  return {
+    kind: "unreadInputField",
+    severity: field.required ? "warning" : "info",
+    boundary: pairing.boundary,
+    intent: { name: pairing.intent.name },
+    code: pairing.code,
+    message: `Intent "${pairing.intent.name}" says ${pairing.boundary} receives ${formatPath(field.path)}${needsIt}; ${pairing.impl.identity.name} never reads it.`
+  };
+}
+function undeclaredFindings(pairing, undeclared) {
+  const said = /* @__PURE__ */ new Set();
+  const findings = [];
+  for (const path of undeclared) {
+    const spelled = formatPath(path);
+    if (said.has(spelled)) {
+      continue;
+    }
+    said.add(spelled);
+    findings.push({
+      kind: "undeclaredInputRead",
+      severity: "info",
+      boundary: pairing.boundary,
+      intent: { name: pairing.intent.name },
+      code: pairing.code,
+      message: `${pairing.impl.identity.name} reads ${spelled} off what it was handed at ${pairing.boundary}; intent "${pairing.intent.name}" does not declare it under receives.`
+    });
+  }
+  return findings;
+}
+
+// src/index.ts
 function checkIntentAgreement(intents, code) {
   const findings = [];
   const checked = [];
@@ -29,6 +123,7 @@ function checkIntentAgreement(intents, code) {
   const codeByBoundary = indexCodeByBoundary(code);
   const boundaryByName = indexBoundaryIntentsByName(intents);
   const deploymentOfUnit = deploymentOf(code);
+  const wrappersOfUnit = wrappersAround(code);
   for (const intent of intents) {
     if (intent.kind === "prd") {
       const result2 = checkPrdCoverage(intent, boundaryByName);
@@ -39,7 +134,8 @@ function checkIntentAgreement(intents, code) {
     const result = checkBoundaryIntent(
       intent,
       codeByBoundary,
-      deploymentOfUnit
+      deploymentOfUnit,
+      wrappersOfUnit
     );
     findings.push(...withProvenance(result.findings, intent.source));
     checked.push(...result.checked);
@@ -83,7 +179,7 @@ function checkOutcomesDescribed(intents) {
   }
   return findings;
 }
-function checkBoundaryIntent(intent, codeByBoundary, deploymentOfUnit) {
+function checkBoundaryIntent(intent, codeByBoundary, deploymentOfUnit, wrappersOfUnit) {
   const key = pairingKey(intent.boundary);
   if (key === null) {
     return {
@@ -137,7 +233,13 @@ function checkBoundaryIntent(intent, codeByBoundary, deploymentOfUnit) {
   const findings = [];
   for (const impl of impls) {
     findings.push(
-      ...compareIntentToImpl(intent, impl, label, deploymentOfUnit(impl))
+      ...compareIntentToImpl(
+        intent,
+        impl,
+        label,
+        deploymentOfUnit(impl),
+        wrappersOfUnit(impl)
+      )
     );
   }
   return {
@@ -322,7 +424,7 @@ function indexCodeByBoundary(code) {
   }
   return byKey;
 }
-function compareIntentToImpl(intent, impl, boundary, deployment) {
+function compareIntentToImpl(intent, impl, boundary, deployment, wrappers) {
   const findings = [];
   const ref = codeRef(impl);
   const calls = boundaryCalls(impl);
@@ -473,6 +575,9 @@ function compareIntentToImpl(intent, impl, boundary, deployment) {
     findings.push(finding);
     undeclared.push({ finding, boundary: made.label, does: made.does });
   }
+  findings.push(
+    ...checkReceivesBlock({ intent, impl, wrappers, boundary, code: ref })
+  );
   return foldRenamedBoundaries(
     intent,
     impl,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suss/checker-intent",
-  "version": "0.32.0",
+  "version": "0.33.1",
   "type": "module",
   "description": "Compare the intent your team wrote down against what suss read out of the code, and report where the two have drifted apart.",
   "keywords": [
@@ -49,9 +49,9 @@
     "zod": "^4.0.0"
   },
   "dependencies": {
-    "@suss/behavioral-ir": "0.32.0",
-    "@suss/intent-ir": "0.32.0",
-    "@suss/ir-core": "0.32.0"
+    "@suss/behavioral-ir": "0.33.1",
+    "@suss/intent-ir": "0.33.1",
+    "@suss/ir-core": "0.33.1"
   },
   "devDependencies": {
     "tsup": "*",