supercov 0.0.43 → 0.0.44

package/analyzers/typescript/src/pragmas.ts

@@ -1,5 +1,13 @@
 import type ts from "typescript";
 import type { Site } from "./types.js";
+import type { AwaitedObservationSource } from "./awaited-observations.js";
+import type {
+  CallOmissionEvidence,
+  CountSensitivityEvidence,
+  PayloadSensitivityEvidence,
+  DirectReturnSensitivityEvidence,
+  CompletionSensitivityEvidence,
+} from "./mock-counts.js";
 
 export type AssertionPhase = { source?: string; op: string; status?: string };
 export function assertionWitnessIssue(
@@ -31,6 +39,7 @@ interface Attachment {
   source: string;
   method: string;
   inert: boolean;
+  awaitedObservation?: AwaitedObservationSource;
 }
 interface Comment {
   id: string;
@@ -40,6 +49,7 @@ interface Comment {
   candidateSites: string[];
   issue?: string;
   attachments: Attachment[];
+  check?: "missing-call" | "count" | "value" | "completion";
 }
 export interface PragmaHint {
   id: string;
@@ -53,6 +63,13 @@ export interface PragmaHint {
   assertionMethod?: string;
   witness: "passed" | "unavailable";
   witnessIssue?: string;
+  awaitedObservation?: AwaitedObservationSource;
+  check?: "missing-call" | "count" | "value" | "completion";
+  callOmission?: CallOmissionEvidence;
+  countSensitivity?: CountSensitivityEvidence;
+  payloadSensitivity?: PayloadSensitivityEvidence;
+  directReturnSensitivity?: DirectReturnSensitivityEvidence;
+  completionSensitivity?: CompletionSensitivityEvidence;
 }
 
 /** Source hints are kept OUT of observations. A comment never adds a boundary. */
@@ -74,8 +91,21 @@ export function collectPragmas(
         const raw = sf.text.slice(range.pos, range.end);
         if (!/^\/\/\s*observes:/.test(raw) || comments.has(key(sf, range.pos)))
           continue;
+        const parts = raw.split(/;\s*check\s+/);
+        const check =
+          parts.length === 2 && parts[1].trim() === "missing call"
+            ? ("missing-call" as const)
+            : parts.length === 2 && parts[1].trim() === "count"
+              ? ("count" as const)
+              : parts.length === 2 && parts[1].trim() === "value"
+                ? ("value" as const)
+                : parts.length === 2 && parts[1].trim() === "completion"
+                  ? ("completion" as const)
+                  : undefined;
+        const checkIssue =
+          parts.length > 1 && !check ? "unsupported-check-recipe" : undefined;
         const parsed = /^\/\/\s*observes:\s*(\S+?)#(\S+)(?:\s+(.+?))?\s*$/.exec(
-          raw,
+          parts[0],
         );
         const suffix = parsed?.[3]?.split(/(?:^|\s+)via\s+/);
         const target = parsed
@@ -92,31 +122,51 @@ export function collectPragmas(
           target.file
             .split("/")
             .every((part) => part && part !== "." && part !== "..");
-        const candidates = validPath
-          ? sites
-              .filter(
-                (s) =>
-                  s.file === target.file &&
-                  (s.owner === target.function || s.fn === target.function) &&
-                  (!target.snippet || s.text.includes(target.snippet)),
-              )
-              .map((s) => s.id)
+        const matchingSites = validPath
+          ? sites.filter(
+              (s) =>
+                s.file === target.file &&
+                // The recipe selects the emission, not a containing callback-return site.
+                (!check ||
+                  (check === "missing-call"
+                    ? s.category === "log"
+                    : check === "completion"
+                      ? s.category === "return" || s.category === "throw"
+                      : s.kind === "decision" || s.category === "return")) &&
+                (s.owner === target.function || s.fn === target.function) &&
+                (!target.snippet || s.text.includes(target.snippet)),
+            )
           : [];
+        // An exact whole-site selector is more specific than a containing return
+        // whose display text happens to include that expression. Equal sibling
+        // sites remain ambiguous. This only selects a node; it proves no behavior.
+        const exact =
+          check && target?.snippet
+            ? matchingSites.filter(
+                (s) => s.text.trim() === target.snippet!.trim(),
+              )
+            : [];
+        const candidates = (exact.length ? exact : matchingSites).map(
+          (s) => s.id,
+        );
         comments.set(key(sf, range.pos), {
           id: location(sf, range.pos),
           where: location(sf, range.pos),
           raw,
           target,
+          ...(check ? { check } : {}),
           candidateSites: candidates,
-          issue: !target
-            ? "invalid-syntax"
-            : !validPath
-              ? "invalid-target-path"
-              : !candidates.length
-                ? "target-not-in-inventory"
-                : candidates.length > 1
-                  ? "ambiguous-target"
-                  : undefined,
+          issue:
+            checkIssue ??
+            (!target
+              ? "invalid-syntax"
+              : !validPath
+                ? "invalid-target-path"
+                : !candidates.length
+                  ? "target-not-in-inventory"
+                  : candidates.length > 1
+                    ? "ambiguous-target"
+                    : undefined),
           attachments: [],
         });
       }
@@ -129,11 +179,23 @@ export function collectPragmas(
     visit(sf);
   }
   return {
+    hasHint(node: ts.Node) {
+      let statement = node;
+      while (statement.parent && !compiler.isStatement(statement))
+        statement = statement.parent;
+      if (!compiler.isExpressionStatement(statement)) return false;
+      const sf = node.getSourceFile();
+      return (
+        compiler.getLeadingCommentRanges(sf.text, statement.getFullStart()) ??
+        []
+      ).some((range) => comments.has(key(sf, range.pos)));
+    },
     register(
       node: ts.CallExpression,
       method: string,
       testKey: string,
       inert: boolean,
+      awaitedObservation?: AwaitedObservationSource,
     ) {
       let statement: ts.Node = node;
       while (statement.parent && !compiler.isStatement(statement))
@@ -152,6 +214,7 @@ export function collectPragmas(
           source: location(sf, node.getStart(sf)),
           method,
           inert,
+          ...(awaitedObservation ? { awaitedObservation } : {}),
         };
         if (
           !comment.attachments.some(
@@ -193,11 +256,11 @@ export function collectPragmas(
               },
             ];
           return matched.map(({ a, b }) => {
-            const witnessIssue = assertionWitnessIssue(
-              b.phases,
-              a.source,
-              a.method,
-            );
+            // A source-checked poll is not an explicit assertion phase. Neither
+            // a matching phase name nor a passing test can supply its read receipt.
+            const witnessIssue = a.awaitedObservation
+              ? "observation-capture-unavailable"
+              : assertionWitnessIssue(b.phases, a.source, a.method);
             return {
               ...comment,
               id: `${comment.id}@${b.id}`,
@@ -205,6 +268,9 @@ export function collectPragmas(
               test: b.id,
               assertionSource: a.source,
               assertionMethod: a.method,
+              ...(a.awaitedObservation
+                ? { awaitedObservation: a.awaitedObservation }
+                : {}),
               witness: witnessIssue
                 ? ("unavailable" as const)
                 : ("passed" as const),

package/docs/agent-loop.md

@@ -1,41 +1,33 @@
 # Agent workflow
 
-Supercov works best as a small, repeatable loop: run the suite, choose one useful
-gap, write one test, rerun, and prove what improved.
+Use Supercov with your coding agent and the test suite you already have.
+Supercov reports coverage and gaps. Your agent writes a test, reruns the suite,
+and checks what improved.
 
-```text
-run the suite  →  choose a gap  →  write one test  →  rerun  →  compare
-      ↑                                                            |
-      └────────────────────────────────────────────────────────────┘
-```
-
-Supercov supplies the coverage signal and evidence. Your coding agent writes
-the tests.
+## Start with one test
 
-## Choose the job
+Open your own repository in your coding agent and paste this prompt. You don't
+need to install Supercov first; the agent can handle that.
 
-For one careful first pass, ask:
-
-```text
-Measure code coverage with `npx supercov` and write the first useful test based
-on coverage. Only edit tests. Rerun the complete suite and report what improved.
+```text supercov-prompt
+Measure code coverage with npx supercov and write one missing test.
+Only change tests. Rerun the full test suite and show me the test you
+added and the before-and-after coverage.
 ```
 
-For an overnight run or leftover token budget, ask:
-
-```text
-Use `npx supercov` to improve coverage. Only write tests. Keep going while
-useful gaps remain. Never weaken assertions or change application code to make
-coverage easier. Stop at a measurement limit, unreachable behavior, or the end
-of the available time budget. Report the run ids compared and what improved.
-```
+If the project has several test commands, tell the agent which full suite to
+use. Let it run the commands and edit the tests, approving those actions if
+your agent asks.
 
-The second prompt is intentionally open-ended, but 100% is a direction rather
-than permission to write meaningless tests or reshape application code.
+The result is a normal test-file change and a coverage comparison in the
+conversation. Ask separately if you want a commit or pull request.
 
 ## One safe pass
 
-```sh
+The agent should run the suite, inspect a gap, write a test, then rerun the
+same suite and compare. These are the commands it can use:
+
+```sh supercov-example
 # 1. Establish a baseline.
 npx supercov -- npm test
 
@@ -52,8 +44,10 @@ npx supercov -- npm test
 npx supercov diff <previous-run-id> latest
 ```
 
-For Rust, use `cargo test` or `cargo nextest run` in both runs. Keep the baseline
-and verification commands identical.
+Everything after `--` is your project's test command. Use your actual command
+and file paths in place of the examples. For example,
+Rust projects can use `cargo test`, Python projects `pytest`, and Ruby projects
+`bundle exec rspec`. Keep the baseline and verification commands identical.
 
 The `line` query is useful before writing a test because it shows which tests
 already reach that line. Extending a nearby test is often better than adding a
@@ -72,9 +66,100 @@ test gaps separate from analysis limits. Follow the returned evidence pointers
 and `pagination.nextOffset`, pinning `--analysis` and the run id while paging.
 See [assertion evidence](assertion-evidence.md) for requirements and examples.
 
-## A complete prompt for longer runs
+## Example
+
+Here's a recorded Codex run in a JavaScript project, using the first prompt.
+The files are from our checkout example; you don't need to add them to your
+project.
+
+[`src/session.js`](https://github.com/supercorp-ai/supercov/blob/main/examples/checkout-verification/starter/src/session.js)
+allows checkout only when the customer is signed in and their session has
+not expired:
+
+```js
+export function canCheckout(signedIn, expired) {
+  if (signedIn && !expired) return true;
+  return false;
+}
+```
+
+The two tests in
+[`tests/session.test.js`](https://github.com/supercorp-ai/supercov/blob/main/examples/checkout-verification/starter/tests/session.test.js)
+check a valid session and a signed-out visitor:
+
+```js
+assert.equal(canCheckout(true, false), true);
+assert.equal(canCheckout(false, false), false);
+```
+
+The agent ran `npx supercov -- npm test`. Both tests passed, and the summary
+from `npx supercov runs latest` showed:
 
 ```text
+Coverage
+  Lines      100.00% (3/3)
+  Branches   100.00% (2/2)
+  MC/DC      50.00% (1/2)
+```
+
+It listed the gaps and inspected the file. You can open those views with:
+
+```sh
+npx supercov runs latest gaps
+npx supercov runs latest file src/session.js
+```
+
+The file query explained the gap:
+
+```text
+ LINE  STATUS        SOURCE
+    2  PARTIAL       signedIn && !expired
+       Unobserved: no witness pair shows `!expired` independently changing the decision result
+```
+
+Both return paths had run, but neither test checked an expired session. MC/DC
+checks whether each condition has been shown to affect the decision
+independently. Here, `signedIn` had; `!expired` had not.
+
+The agent added one test to `tests/session.test.js`, leaving the application
+code and existing tests unchanged:
+
+```js
+test('a signed-in visitor with an expired session cannot check out', () => {
+  assert.equal(canCheckout(true, true), false);
+});
+```
+
+It reran the same full suite. All three tests passed, and MC/DC reached 100%.
+The comparison from `npx supercov diff <before-run-id> latest` showed:
+
+```text
+lines +0pp, branches +0pp, MC/DC +50pp
+gained: 0 lines, 0 branches, 1 MC/DC conditions
+lost: 0 lines, 0 branches, 0 MC/DC conditions
++ MC/DC src/session.js:2 C2 !expired
+```
+
+The new assertion checks that checkout is denied when a signed-in customer's
+session has expired. Removing the expiry check makes this test fail; the
+original two tests still pass.
+
+In your project, look for the same evidence: the test checks the behavior the
+agent identified, and the full suite passes. One useful test won't necessarily
+take coverage to 100%.
+
+To try these exact files, [download the starter](https://supercov.com/downloads/supercov-tutorial.zip),
+extract it, open the `supercov-tutorial` folder in your agent, and run `npm ci`.
+Then use the JavaScript prompt above. The completed test is not included in the
+download. The [recorded run](https://github.com/supercorp-ai/supercov/tree/main/examples/checkout-verification/agent-run)
+includes the commands, full output, and completed test.
+
+## A complete prompt for longer runs
+
+Once you've reviewed the first test, use this prompt to continue through
+useful gaps—for example, during an overnight run:
+
+```text supercov-prompt
 Use `npx supercov` to improve coverage. Only write tests. Keep going while
 useful gaps remain.
 
@@ -110,7 +195,7 @@ reason to manufacture a test.
 
 If the repository separates test levels, narrow the view:
 
-```sh
+```sh supercov
 npx supercov runs latest gaps --kind e2e --limit 10
 ```