@suss/checker-intent 0.33.1 → 0.34.1

package/dist/index.d.cts

@@ -1,8 +1,87 @@
-import { BehavioralSummary } from '@suss/behavioral-ir';
-import { IntentFinding, IntentSummary } from '@suss/intent-ir';
+import { BehavioralSummary, ReceiverClass, TypeShape, ProvenanceEntry, BoundaryGuard, Interaction, Transition, Deployment } from '@suss/behavioral-ir';
+import { CoveringTestSpelling, IntentFinding, IntentSummary, IntentEffect, IntentOutcome } from '@suss/intent-ir';
 export { IntentFinding } from '@suss/intent-ir';
-import { SuppressionRule, Semantics } from '@suss/ir-core';
+import { Relation, BoundaryBinding, SuppressionRule, Semantics } from '@suss/ir-core';
+import { CallFacts, ReachTarget } from '@suss/checker';
 
+/**
+ * Checks the tests a PRD scenario lists under `coveredBy`: that each
+ * one exists, that it runs, and that its calls reach what the scenario
+ * is about without going through a mock.
+ *
+ * Turning a spelled test or subject into summaries is the caller's
+ * job, through the resolver its commands already use, and arrives here
+ * as a `CoveringTestLookup`. The reach question is asked once for every
+ * test, through the call facts in @suss/checker, rather than once per
+ * scenario. It is asked a second time without honouring mocks only for
+ * the tests that missed, to tell a test that never reaches its subject
+ * from one that reaches it only through something it replaced.
+ */
+
+type FoundTest = {
+    found: true;
+    unit: BehavioralSummary;
+} | {
+    found: false;
+    message: string;
+};
+type FoundSubject = {
+    found: true;
+    target: ReachTarget;
+    label: string;
+    /**
+     * The classes the subject is, when it was spelled as a class or as
+     * a file a class is written in. A call a test sends to one of them
+     * reaches the subject. Empty for a single unit or a boundary.
+     */
+    classes?: ReadonlyArray<ReceiverClass>;
+} | {
+    found: false;
+    message: string;
+};
+/** How the check finds the summaries a PRD's spellings mean. */
+interface CoveringTestLookup {
+    /** The call facts over the summaries being checked. */
+    facts: CallFacts;
+    /** The test unit a `coveredBy` entry means, or why there is none. */
+    test(spelled: CoveringTestSpelling): FoundTest;
+    /** What a boundary or unit spelling means, the way `suss ask` reads it. */
+    subject(spelledAs: string): FoundSubject;
+}
+
+/**
+ * Compares the intent a team wrote with the summaries derived from code.
+ *
+ * This is kept apart from @suss/checker because the inputs and outputs
+ * differ: one side is an `IntentSummary`, and a finding says the code
+ * does not do what the team declared. It takes only the call facts from
+ * @suss/checker, to see whether a test reaches what a scenario is about.
+ *
+ * A boundary intent is paired with the code at its boundary key. A PRD
+ * has its scenario links resolved and its covering tests checked. Which
+ * severity each finding gets, and why a finding against inferred intent
+ * drops a level, is in the package design notes.
+ */
+
+/** A code transition's terminal, reduced to the dimensions intent compares. */
+interface CodeOutcome {
+    kind: "response" | "return" | "throw" | "exit";
+    /** A response's status, or the code an `exit` output ends the process with. */
+    status: number | null;
+    body: TypeShape | null;
+    errorType: string | null;
+    /**
+     * The literal a return hands back when the unit's return becomes the
+     * process's exit code, so `exits: 1` can match `return 1` there.
+     */
+    exitCode: number | null;
+    /** What the transition that ends this way did at other boundaries. */
+    effects: CodeEffect[];
+    /** The boundaries the branch leading here turned on. */
+    turnsOn: BoundaryGuard[];
+    /** The line the transition starts on, for a finding about one transition. */
+    line: number;
+}
 /** A boundary intent that was paired and compared against code. */
 interface CheckedBoundaryIntent {
     kind: "boundary";
@@ -22,34 +101,46 @@ interface CheckedPrd {
     scenarios: number;
     /** Scenarios whose every link resolved to a declared outcome (had >=1 link). */
     resolved: number;
-    /** Scenarios carrying no structured link (a valid pending state). */
+    /**
+     * Scenarios whose every covering test exists, runs and reaches its
+     * subject. Zero when the check was given no way to look tests up.
+     */
+    covered: number;
+    /** Scenarios with neither a link nor a covering test. */
     unlinked: number;
 }
 /**
  * A declared intent that was compared, either a boundary intent paired
  * against code or a PRD whose scenario links were resolved. Discriminated
- * on `kind` so callers render both without a parallel structure; when a
- * third doc kind (workflow) ships it extends this union.
+ * on `kind`, so a caller renders both from one list.
  */
 type CheckedIntent = CheckedBoundaryIntent | CheckedPrd;
-/** An intent doc that was loaded but not compared, and why. */
+/**
+ * Intent that was loaded and not compared, and why. `unkeyable` is a
+ * whole document whose boundary cannot be paired. `unreadValue` is one
+ * `from` source the code gave no answer to compare against.
+ * `unfollowedCall` is a covering test that never reaches its subject
+ * through the calls suss followed, and makes calls suss did not follow.
+ */
 interface UncheckedIntent {
     /** The intent doc's `name` (boundary) or `title` (prd). */
     intent: string;
-    reason: "unkeyable";
+    reason: "unkeyable" | "unreadValue" | "unfollowedCall";
+    /** The outcome the claim is on, for a claim narrower than the document. */
+    outcomeId?: string;
+    /** The scenario the claim is on, by its title or its position, for a covering test. */
+    scenario?: string;
+    /** The covering test, as the scenario lists it. */
+    coveredBy?: string;
     /** Human-readable explanation, render-ready. */
     detail: string;
 }
 /**
- * The full result of an intent-agreement pass. Mirrors the behavioural
- * checker's shape philosophy (`checkAll` → findings + pairs +
- * unmatched): findings are what to fix; checked / unchecked are the
- * coverage accounting: which declared intent was actually compared.
- * Callers render or gate on this without knowing which doc kinds the
- * checker compared: boundary intents and PRDs both land in `checked`
- * (a discriminated union). `unchecked` is reserved for intent that
- * couldn't be compared at all (an unkeyable boundary), never silently
- * dropped.
+ * The result of an intent-agreement pass, laid out like the behavioural
+ * checker's `checkAll` result. `findings` are what to fix. `checked`
+ * lists every declared intent that was compared, boundary intents and
+ * PRDs alike. `unchecked` lists intent that could not be compared at
+ * all, such as an unkeyable boundary, so nothing is dropped silently.
  */
 interface CheckIntentResult {
     findings: IntentFinding[];
@@ -59,33 +150,82 @@ interface CheckIntentResult {
 /**
  * Compare every loaded intent doc against what's known. Boundary intents
  * pair against the code summaries sharing their boundary key; PRDs resolve
- * each scenario's link against the loaded boundary intents (coverage). An
- * intent that can't be compared (an unkeyable boundary) is reported in
- * `unchecked`, never silently dropped.
+ * each scenario's link against the loaded boundary intents, and check the
+ * tests it lists under `coveredBy` through `tests`. Without `tests`, those
+ * scenarios count as backed and their tests go unchecked. An unkeyable
+ * boundary is reported in `unchecked`, never silently dropped.
  *
  * Findings against `source: "inferred"` intent are downgraded one severity
  * level: the intent describes what the code did when the inference ran, so
  * a divergence is most likely a code change since, not an authoring error.
  * Curation (`"inferred, curated"`) restores full severity.
  */
-declare function checkIntentAgreement(intents: IntentSummary[], code: BehavioralSummary[]): CheckIntentResult;
+declare function checkIntentAgreement(intents: IntentSummary[], code: BehavioralSummary[], tests?: CoveringTestLookup): CheckIntentResult;
 /**
- * Apply .sussignore rules to intent findings, using the shared
- * pipeline from @suss/ir-core (same rule shape and semantics as the
- * behavioural checker's `applySuppressions`). Rule discriminators map
- * as: `kind` → the intent finding kind; `boundary` → the finding's
- * boundary key (exact for `fn:` / `gql:` keys, path-normalized for
- * REST). A rule that specifies `consumer` or `provider` never matches
- * an intent finding: it has neither side.
+ * Apply .sussignore rules to intent findings, through the same pipeline
+ * in @suss/ir-core that the behavioural checker's `applySuppressions`
+ * uses. A rule's `kind` matches the finding kind, and its `boundary`
+ * matches the finding's boundary key, exactly for `fn:` and `gql:` keys
+ * and path-normalized for REST. A rule's `scenario` matches the title
+ * of the PRD scenario the finding is about. A rule that gives
+ * `consumer` or `provider` never matches, since an intent finding has
+ * neither side.
  */
 declare function applyIntentSuppressions(findings: IntentFinding[], rules: SuppressionRule[], opts?: {
     keepHidden?: boolean;
 }): IntentFinding[];
+/**
+ * Whether an effect the code makes is the one the intent declared. The
+ * boundary is resolved with `namesBoundary`, the matcher that resolves
+ * what somebody types at `suss ask`, so a document and a question that
+ * spell a store the same way pick out the same one.
+ */
+declare function effectMatches(declared: IntentEffect, made: CodeEffect): boolean;
+/** How a transition ends, in the terms intent states an ending in. */
+type CodeEnding = Pick<CodeOutcome, "kind" | "status" | "body" | "errorType" | "exitCode">;
+/**
+ * How a transition ends, or null for an ending intent has no word for,
+ * such as a render. A status the code computes has no literal, so it
+ * comes back null and matches no declared status. `returnIsExitCode`
+ * says the unit's return becomes the process's exit code.
+ */
+declare function endingOf(t: Transition, returnIsExitCode?: boolean): CodeEnding | null;
+/** One verb and one boundary this transition reaches. */
+interface CodeEffect {
+    does: Relation;
+    binding: BoundaryBinding;
+    /** How a report writes that boundary, for a message about it. */
+    label: string;
+    /** The columns the access states, empty when it states none. */
+    fields: string[];
+    /** What the access picks the item out by, empty when it states none. */
+    by: string[];
+    /** The shape of what a write put out, when the code says. */
+    payload?: TypeShape;
+    /** Where the values in this effect's slots came from, when the summary says. */
+    slots?: ProvenanceEntry[];
+    /** The line the transition that has this effect starts on. */
+    line?: number;
+}
+/** Every verb and boundary the transition reaches, grounded against the deployment. */
+declare function codeEffectsOf(t: Transition, deployment: Deployment): CodeEffect[];
+/**
+ * The fields an access states: a storage access's columns and key, or
+ * the variable a config read takes, which is a field of the runtime's
+ * contract. Nothing for any other class.
+ */
+declare function accessDetail(interaction: Interaction): {
+    fields: string[];
+    by: string[];
+    payload?: TypeShape;
+};
+/** Whether the code ends the way the intent says. The body is compared elsewhere. */
+declare function outcomeMatches(intent: Pick<IntentOutcome, "kind" | "status" | "errorType">, code: CodeEnding): boolean;
 /**
  * What each protocol needs before an intent doc written against one of
  * its boundaries can be paired, in the doc author's terms. The
- * drafter says the same thing about a boundary it could not write.
+ * drafter gives the same reason for a boundary it could not write.
  */
 declare function whatWouldKeyIt(protocol: Semantics["name"]): string;
 
-export { type CheckIntentResult, type CheckedBoundaryIntent, type CheckedIntent, type CheckedPrd, type UncheckedIntent, applyIntentSuppressions, checkIntentAgreement, whatWouldKeyIt };
+export { type CheckIntentResult, type CheckedBoundaryIntent, type CheckedIntent, type CheckedPrd, type CodeEffect, type CodeEnding, type CoveringTestLookup, type FoundSubject, type FoundTest, type UncheckedIntent, accessDetail, applyIntentSuppressions, checkIntentAgreement, codeEffectsOf, effectMatches, endingOf, outcomeMatches, whatWouldKeyIt };

package/dist/index.d.ts

@@ -1,8 +1,87 @@
-import { BehavioralSummary } from '@suss/behavioral-ir';
-import { IntentFinding, IntentSummary } from '@suss/intent-ir';
+import { BehavioralSummary, ReceiverClass, TypeShape, ProvenanceEntry, BoundaryGuard, Interaction, Transition, Deployment } from '@suss/behavioral-ir';
+import { CoveringTestSpelling, IntentFinding, IntentSummary, IntentEffect, IntentOutcome } from '@suss/intent-ir';
 export { IntentFinding } from '@suss/intent-ir';
-import { SuppressionRule, Semantics } from '@suss/ir-core';
+import { Relation, BoundaryBinding, SuppressionRule, Semantics } from '@suss/ir-core';
+import { CallFacts, ReachTarget } from '@suss/checker';
 
+/**
+ * Checks the tests a PRD scenario lists under `coveredBy`: that each
+ * one exists, that it runs, and that its calls reach what the scenario
+ * is about without going through a mock.
+ *
+ * Turning a spelled test or subject into summaries is the caller's
+ * job, through the resolver its commands already use, and arrives here
+ * as a `CoveringTestLookup`. The reach question is asked once for every
+ * test, through the call facts in @suss/checker, rather than once per
+ * scenario. It is asked a second time without honouring mocks only for
+ * the tests that missed, to tell a test that never reaches its subject
+ * from one that reaches it only through something it replaced.
+ */
+
+type FoundTest = {
+    found: true;
+    unit: BehavioralSummary;
+} | {
+    found: false;
+    message: string;
+};
+type FoundSubject = {
+    found: true;
+    target: ReachTarget;
+    label: string;
+    /**
+     * The classes the subject is, when it was spelled as a class or as
+     * a file a class is written in. A call a test sends to one of them
+     * reaches the subject. Empty for a single unit or a boundary.
+     */
+    classes?: ReadonlyArray<ReceiverClass>;
+} | {
+    found: false;
+    message: string;
+};
+/** How the check finds the summaries a PRD's spellings mean. */
+interface CoveringTestLookup {
+    /** The call facts over the summaries being checked. */
+    facts: CallFacts;
+    /** The test unit a `coveredBy` entry means, or why there is none. */
+    test(spelled: CoveringTestSpelling): FoundTest;
+    /** What a boundary or unit spelling means, the way `suss ask` reads it. */
+    subject(spelledAs: string): FoundSubject;
+}
+
+/**
+ * Compares the intent a team wrote with the summaries derived from code.
+ *
+ * This is kept apart from @suss/checker because the inputs and outputs
+ * differ: one side is an `IntentSummary`, and a finding says the code
+ * does not do what the team declared. It takes only the call facts from
+ * @suss/checker, to see whether a test reaches what a scenario is about.
+ *
+ * A boundary intent is paired with the code at its boundary key. A PRD
+ * has its scenario links resolved and its covering tests checked. Which
+ * severity each finding gets, and why a finding against inferred intent
+ * drops a level, is in the package design notes.
+ */
+
+/** A code transition's terminal, reduced to the dimensions intent compares. */
+interface CodeOutcome {
+    kind: "response" | "return" | "throw" | "exit";
+    /** A response's status, or the code an `exit` output ends the process with. */
+    status: number | null;
+    body: TypeShape | null;
+    errorType: string | null;
+    /**
+     * The literal a return hands back when the unit's return becomes the
+     * process's exit code, so `exits: 1` can match `return 1` there.
+     */
+    exitCode: number | null;
+    /** What the transition that ends this way did at other boundaries. */
+    effects: CodeEffect[];
+    /** The boundaries the branch leading here turned on. */
+    turnsOn: BoundaryGuard[];
+    /** The line the transition starts on, for a finding about one transition. */
+    line: number;
+}
 /** A boundary intent that was paired and compared against code. */
 interface CheckedBoundaryIntent {
     kind: "boundary";
@@ -22,34 +101,46 @@ interface CheckedPrd {
     scenarios: number;
     /** Scenarios whose every link resolved to a declared outcome (had >=1 link). */
     resolved: number;
-    /** Scenarios carrying no structured link (a valid pending state). */
+    /**
+     * Scenarios whose every covering test exists, runs and reaches its
+     * subject. Zero when the check was given no way to look tests up.
+     */
+    covered: number;
+    /** Scenarios with neither a link nor a covering test. */
     unlinked: number;
 }
 /**
  * A declared intent that was compared, either a boundary intent paired
  * against code or a PRD whose scenario links were resolved. Discriminated
- * on `kind` so callers render both without a parallel structure; when a
- * third doc kind (workflow) ships it extends this union.
+ * on `kind`, so a caller renders both from one list.
  */
 type CheckedIntent = CheckedBoundaryIntent | CheckedPrd;
-/** An intent doc that was loaded but not compared, and why. */
+/**
+ * Intent that was loaded and not compared, and why. `unkeyable` is a
+ * whole document whose boundary cannot be paired. `unreadValue` is one
+ * `from` source the code gave no answer to compare against.
+ * `unfollowedCall` is a covering test that never reaches its subject
+ * through the calls suss followed, and makes calls suss did not follow.
+ */
 interface UncheckedIntent {
     /** The intent doc's `name` (boundary) or `title` (prd). */
     intent: string;
-    reason: "unkeyable";
+    reason: "unkeyable" | "unreadValue" | "unfollowedCall";
+    /** The outcome the claim is on, for a claim narrower than the document. */
+    outcomeId?: string;
+    /** The scenario the claim is on, by its title or its position, for a covering test. */
+    scenario?: string;
+    /** The covering test, as the scenario lists it. */
+    coveredBy?: string;
     /** Human-readable explanation, render-ready. */
     detail: string;
 }
 /**
- * The full result of an intent-agreement pass. Mirrors the behavioural
- * checker's shape philosophy (`checkAll` → findings + pairs +
- * unmatched): findings are what to fix; checked / unchecked are the
- * coverage accounting: which declared intent was actually compared.
- * Callers render or gate on this without knowing which doc kinds the
- * checker compared: boundary intents and PRDs both land in `checked`
- * (a discriminated union). `unchecked` is reserved for intent that
- * couldn't be compared at all (an unkeyable boundary), never silently
- * dropped.
+ * The result of an intent-agreement pass, laid out like the behavioural
+ * checker's `checkAll` result. `findings` are what to fix. `checked`
+ * lists every declared intent that was compared, boundary intents and
+ * PRDs alike. `unchecked` lists intent that could not be compared at
+ * all, such as an unkeyable boundary, so nothing is dropped silently.
  */
 interface CheckIntentResult {
     findings: IntentFinding[];
@@ -59,33 +150,82 @@ interface CheckIntentResult {
 /**
  * Compare every loaded intent doc against what's known. Boundary intents
  * pair against the code summaries sharing their boundary key; PRDs resolve
- * each scenario's link against the loaded boundary intents (coverage). An
- * intent that can't be compared (an unkeyable boundary) is reported in
- * `unchecked`, never silently dropped.
+ * each scenario's link against the loaded boundary intents, and check the
+ * tests it lists under `coveredBy` through `tests`. Without `tests`, those
+ * scenarios count as backed and their tests go unchecked. An unkeyable
+ * boundary is reported in `unchecked`, never silently dropped.
  *
  * Findings against `source: "inferred"` intent are downgraded one severity
  * level: the intent describes what the code did when the inference ran, so
  * a divergence is most likely a code change since, not an authoring error.
  * Curation (`"inferred, curated"`) restores full severity.
  */
-declare function checkIntentAgreement(intents: IntentSummary[], code: BehavioralSummary[]): CheckIntentResult;
+declare function checkIntentAgreement(intents: IntentSummary[], code: BehavioralSummary[], tests?: CoveringTestLookup): CheckIntentResult;
 /**
- * Apply .sussignore rules to intent findings, using the shared
- * pipeline from @suss/ir-core (same rule shape and semantics as the
- * behavioural checker's `applySuppressions`). Rule discriminators map
- * as: `kind` → the intent finding kind; `boundary` → the finding's
- * boundary key (exact for `fn:` / `gql:` keys, path-normalized for
- * REST). A rule that specifies `consumer` or `provider` never matches
- * an intent finding: it has neither side.
+ * Apply .sussignore rules to intent findings, through the same pipeline
+ * in @suss/ir-core that the behavioural checker's `applySuppressions`
+ * uses. A rule's `kind` matches the finding kind, and its `boundary`
+ * matches the finding's boundary key, exactly for `fn:` and `gql:` keys
+ * and path-normalized for REST. A rule's `scenario` matches the title
+ * of the PRD scenario the finding is about. A rule that gives
+ * `consumer` or `provider` never matches, since an intent finding has
+ * neither side.
  */
 declare function applyIntentSuppressions(findings: IntentFinding[], rules: SuppressionRule[], opts?: {
     keepHidden?: boolean;
 }): IntentFinding[];
+/**
+ * Whether an effect the code makes is the one the intent declared. The
+ * boundary is resolved with `namesBoundary`, the matcher that resolves
+ * what somebody types at `suss ask`, so a document and a question that
+ * spell a store the same way pick out the same one.
+ */
+declare function effectMatches(declared: IntentEffect, made: CodeEffect): boolean;
+/** How a transition ends, in the terms intent states an ending in. */
+type CodeEnding = Pick<CodeOutcome, "kind" | "status" | "body" | "errorType" | "exitCode">;
+/**
+ * How a transition ends, or null for an ending intent has no word for,
+ * such as a render. A status the code computes has no literal, so it
+ * comes back null and matches no declared status. `returnIsExitCode`
+ * says the unit's return becomes the process's exit code.
+ */
+declare function endingOf(t: Transition, returnIsExitCode?: boolean): CodeEnding | null;
+/** One verb and one boundary this transition reaches. */
+interface CodeEffect {
+    does: Relation;
+    binding: BoundaryBinding;
+    /** How a report writes that boundary, for a message about it. */
+    label: string;
+    /** The columns the access states, empty when it states none. */
+    fields: string[];
+    /** What the access picks the item out by, empty when it states none. */
+    by: string[];
+    /** The shape of what a write put out, when the code says. */
+    payload?: TypeShape;
+    /** Where the values in this effect's slots came from, when the summary says. */
+    slots?: ProvenanceEntry[];
+    /** The line the transition that has this effect starts on. */
+    line?: number;
+}
+/** Every verb and boundary the transition reaches, grounded against the deployment. */
+declare function codeEffectsOf(t: Transition, deployment: Deployment): CodeEffect[];
+/**
+ * The fields an access states: a storage access's columns and key, or
+ * the variable a config read takes, which is a field of the runtime's
+ * contract. Nothing for any other class.
+ */
+declare function accessDetail(interaction: Interaction): {
+    fields: string[];
+    by: string[];
+    payload?: TypeShape;
+};
+/** Whether the code ends the way the intent says. The body is compared elsewhere. */
+declare function outcomeMatches(intent: Pick<IntentOutcome, "kind" | "status" | "errorType">, code: CodeEnding): boolean;
 /**
  * What each protocol needs before an intent doc written against one of
  * its boundaries can be paired, in the doc author's terms. The
- * drafter says the same thing about a boundary it could not write.
+ * drafter gives the same reason for a boundary it could not write.
  */
 declare function whatWouldKeyIt(protocol: Semantics["name"]): string;
 
-export { type CheckIntentResult, type CheckedBoundaryIntent, type CheckedIntent, type CheckedPrd, type UncheckedIntent, applyIntentSuppressions, checkIntentAgreement, whatWouldKeyIt };
+export { type CheckIntentResult, type CheckedBoundaryIntent, type CheckedIntent, type CheckedPrd, type CodeEffect, type CodeEnding, type CoveringTestLookup, type FoundSubject, type FoundTest, type UncheckedIntent, accessDetail, applyIntentSuppressions, checkIntentAgreement, codeEffectsOf, effectMatches, endingOf, outcomeMatches, whatWouldKeyIt };