@skyramp/mcp 0.4.1-rc.1 → 0.4.1

package/build/recommendation/verifiers/expectedValueSourced.js

@@ -2,6 +2,8 @@ import { allChangedFiles } from "../types.js";
 import { changedPathSet, normalizeCitedPath } from "./citedPath.js";
 import { EXPECTED_VALUE_SOURCED_CONTRACT as CONTRACT } from "../verifierContracts.js";
 import { appearsIn, searchable } from "../pullRequestText.js";
+import { escapeRegExp } from "../../utils/regex.js";
+import { renderCase } from "./coverage.js";
 function readSource(raw) {
     const source = typeof raw === "string" ? raw.trim() : "";
     if (source.length === 0)
@@ -28,6 +30,71 @@ function readSource(raw) {
 function caseLabel(change, entry) {
     return `${String(change?.id ?? "?")}:${String(entry?.param ?? "?")}`;
 }
+/** Every number the pull request writes, as a number. One value has many
+ *  spellings — `1e21`, `1e+21`, `1E21`, the digits in full — and matching the
+ *  value's OWN spelling refused every other one, so a pull request stating the
+ *  limit as `1e21` did not state `1e21`.
+ *
+ *  A token glued to a word or to another number is not a number the text states:
+ *  that is what keeps `3600` from stating 60, `159.9989` from stating 159.998, and
+ *  the `60` of `1e60` from being a number at all. The sign belongs to the token, so
+ *  `-60` states -60 and not 60, while `+60` states 60. `Number` reads the rest:
+ *  `1599.80` is 1599.8 and `10.0` is 10. */
+function statedNumbers(prText) {
+    const stated = [];
+    for (const match of prText.matchAll(/[+-]?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?/g)) {
+        const token = match[0];
+        const start = match.index ?? 0;
+        const end = start + token.length;
+        const before = prText[start - 1] ?? "";
+        const after = prText[end] ?? "";
+        if (/[\dA-Za-z.]/.test(before))
+            continue;
+        if (/[\dA-Za-z]/.test(after))
+            continue;
+        // A dot that carries more digits makes this the first part of something
+        // longer — a version, a list — rather than a number of its own.
+        if (after === "." && /\d/.test(prText[end + 1] ?? ""))
+            continue;
+        const parsed = Number(token);
+        if (Number.isFinite(parsed))
+            stated.push(parsed);
+    }
+    return stated;
+}
+/** Whether the pull request writes this word or phrase, on its own rather than
+ *  inside a longer word. A plain substring let `active` read itself out of
+ *  `inactive`. The boundary is a letter or a digit, so a phrase that ends in
+ *  punctuation still matches the sentence that carries it. */
+function statesTheString(prText, value) {
+    const folded = value.replace(/\s+/g, " ").trim().toLowerCase();
+    if (!folded)
+        return false;
+    return new RegExp(`(?<![\\p{L}\\p{N}])${escapeRegExp(folded)}(?![\\p{L}\\p{N}])`, "u").test(prText);
+}
+/** Whether the pull request writes this value, anywhere in the title or the
+ *  description. A string or a literal — `true`, `false`, `null` — has to appear as
+ *  a word of its own; a number is compared against the numbers the text writes,
+ *  whatever spelling either side uses.
+ *
+ *  TRUE for a value that is not there to state: a case whose expectation is only a
+ *  `derived` rule declares no value, and the rule is checked through the change's
+ *  quote instead. */
+function statesTheValue(prText, value) {
+    if (typeof value === "string")
+        return statesTheString(prText, value);
+    // Three values with no spelling of their own. An empty spelling list used to read
+    // as "stated", so a case could claim `true` from a pull request that writes the
+    // opposite.
+    if (value === true || value === false || value === null)
+        return statesTheString(prText, String(value));
+    // Nothing to state: `undefined` is the derived-only case, and a non-finite
+    // number has no spelling a pull request could carry.
+    if (typeof value !== "number" || !Number.isFinite(value))
+        return true;
+    return statedNumbers(prText).includes(value);
+}
+const text = (value) => (typeof value === "string" ? value.trim() : "");
 /** Verifier 10. A case that states what the response must carry says where that
  *  value came from, and the value did not come from the code under test.
  *
@@ -52,6 +119,7 @@ export const expectedValueSourced = {
         const changed = changedPathSet(allChangedFiles(ctx), true);
         const readable = typeof ctx?.citedFileExists === "function" ? ctx.citedFileExists : undefined;
         const prText = searchable(ctx?.pullRequest ?? { title: "", description: "" });
+        const raised = new Set();
         const changes = Array.isArray(registration.changes) ? registration.changes : [];
         for (const change of changes) {
             const changeId = String(change?.id ?? "?");
@@ -60,7 +128,11 @@ export const expectedValueSourced = {
                 // `undefined` is "this case states no expected value"; `null` is a stated
                 // expectation that the field comes back null, which needs a source like
                 // any other value.
-                if (!entry || entry.expectedValue === undefined)
+                // A case states an expectation either as a value or as the rule behind one,
+                // and BOTH are read from somewhere: crediting `derived` without reading its
+                // `expectedFrom` let a rule "read" off the running app satisfy the check
+                // this verifier exists to be.
+                if (!entry || (entry.expectedValue === undefined && text(entry.derived).length === 0))
                     return;
                 const label = caseLabel(change, entry);
                 const where = `${label} (source "${String(entry.expectedFrom ?? "")}")`;
@@ -69,27 +141,45 @@ export const expectedValueSourced = {
                 // answer that addressed two of them and closed, and the id an answer is
                 // carried forward by must therefore name the case as well as the change.
                 const param = String(entry?.param ?? "").trim() || `case-${index + 1}`;
-                const raise = (kind, objection, evidence) => objections.push({
-                    objectionId: `expectedValueSourced:${kind}:${changeId}:${param}`,
-                    verifier: "expectedValueSourced",
-                    message: objection.message,
-                    evidence,
-                    suggestion: objection.suggestion,
-                });
+                // The CASE, not its parameter. Two bound cases on one parameter each invent
+                // their own value, and keying on the parameter published one of them and
+                // carried its answer to the other. The rendering is the case's content, so
+                // it is the same string whatever order the cases arrive in — the identity
+                // `coverage:cases` already uses.
+                const caseId = renderCase({ param, value: entry.value, absent: entry.absent, expect: String(entry.expect ?? "") });
+                const raise = (kind, objection, evidence) => {
+                    if (raised.has(`${kind}:${changeId}:${caseId}`))
+                        return;
+                    raised.add(`${kind}:${changeId}:${caseId}`);
+                    objections.push({
+                        objectionId: `expectedValueSourced:${kind}:${changeId}:${caseId}`,
+                        verifier: "expectedValueSourced",
+                        message: objection.message,
+                        evidence,
+                        suggestion: objection.suggestion,
+                    });
+                };
                 if (source.kind === "none") {
                     raise("unsourced", CONTRACT.objections.missingSource, `expected value with no usable \`expectedFrom\`: ${where}`);
                 }
                 else if (source.kind === "code") {
-                    raise("code", CONTRACT.objections.sourcedFromCode, `expected value read from the code under test: ${label} (expected ${JSON.stringify(entry.expectedValue)})`);
+                    raise("code", CONTRACT.objections.sourcedFromCode, 
+                    // A derived-only case pins no value, so quoting one read `expected
+                    // undefined` — a sentence naming nothing the agent can act on.
+                    `expected value read from the code under test: ${label} (${entry.expectedValue === undefined
+                        ? `derived as "${text(entry.derived)}"`
+                        : `expected ${JSON.stringify(entry.expectedValue)}`})`);
                 }
                 else if (source.kind === "unresolvable") {
                     // A path no repository file can answer, so the citation opens nothing.
                     raise("unreadable", CONTRACT.objections.unreadableSource, `source file not in the checkout: ${where}`);
                 }
                 else if (source.kind === "pullRequest") {
-                    // The RULE is what the pull request states; the value is derived from it.
-                    // "over 60 is rejected" states no 61, so looking for the value itself
-                    // objected to five correct cases in run 34414643135.
+                    // Two readings, and the quote settles which one applies. A rule the pull
+                    // request states decides values it never writes — "over 60 is rejected"
+                    // states no 61, and demanding the value itself objected to five correct
+                    // cases in run 34414643135 — so a case whose source states a rule puts
+                    // that rule in `derived` and declares no number.
                     const quote = String(change?.quote ?? "").trim();
                     if (quote.length === 0) {
                         raise("noQuote", CONTRACT.objections.quoteMissing, `${label} reads its value from the pull request; change ${changeId} states no \`quote\``);
@@ -97,6 +187,11 @@ export const expectedValueSourced = {
                     else if (!appearsIn(prText, quote)) {
                         raise("noQuote", CONTRACT.objections.quoteMissing, `${label} reads its value from the pull request; change ${changeId} quotes \`${quote}\`, which is in neither the title nor the description`);
                     }
+                    else if (!statesTheValue(prText, entry.expectedValue)) {
+                        // `derived` is the case saying it pins NO number, so a case that still
+                        // carries one is not excused by it: the number is what has to be stated.
+                        raise("valueNotQuoted", CONTRACT.objections.valueNotQuoted, `${label} reads ${JSON.stringify(entry.expectedValue)} from the pull request, which writes no such value${text(entry.derived) ? " — and `derived` does not stand in for a value the case still declares" : ""}`);
+                    }
                 }
                 else if (!source.file) {
                     // A kind that names no file and is not the pull request has nothing to check.
@@ -129,7 +224,9 @@ export const expectedValueSourced = {
             const cited = changes.filter((change) => citedIds.includes(String(change?.id ?? "").trim()));
             if (cited.length === 0)
                 continue;
-            const statesAValue = cited.some((change) => (Array.isArray(change?.cases) ? change.cases : []).some((entry) => entry && entry.expectedValue !== undefined));
+            // `derived` counts: it states the rule the value follows from, which is a
+            // stated value in every sense except that no number is written down.
+            const statesAValue = cited.some((change) => (Array.isArray(change?.cases) ? change.cases : []).some((entry) => entry && (entry.expectedValue !== undefined || text(entry.derived).length > 0)));
             if (statesAValue)
                 continue;
             const plannedTestId = String(plannedTest?.plannedTestId ?? "").trim();
@@ -140,7 +237,7 @@ export const expectedValueSourced = {
                 message: CONTRACT.objections.failWithoutValue.message,
                 evidence: `planned test ${plannedTestId || "(unnamed)"} expects to fail and cites ${cited
                     .map((change) => String(change?.id ?? "?"))
-                    .join(", ")}; no case on those changes states an \`expectedValue\``,
+                    .join(", ")}; no case on those changes states an \`expectedValue\` or a \`derived\` rule`,
                 suggestion: CONTRACT.objections.failWithoutValue.suggestion,
             });
         }

package/build/services/TestGenerationService.js

@@ -438,7 +438,9 @@ The generated test file remains unchanged and ready to use as-is.
             if (generateOptions.authHeader === undefined) {
                 try {
                     const repoPath = generateOptions.outputDir || process.cwd();
-                    const resolved = await resolveAuthFromWorkspace(repoPath, generateOptions.authHeader, generateOptions.authScheme);
+                    const resolved = await resolveAuthFromWorkspace(repoPath, generateOptions.authHeader, generateOptions.authScheme, 
+                    // The directory the test is written into names the service it is for.
+                    generateOptions.outputDir);
                     if (resolved) {
                         generateOptions.authHeader = resolved.authHeader;
                         if (resolved.authScheme !== undefined) {

package/build/tools/code-refactor/codeReuseTool.js

@@ -31,7 +31,7 @@ const codeReuseSchema = z.object({
     verify: z
         .boolean()
         .default(false)
-        .describe("Verify a previously refactored test instead of returning the reuse prompt. POM path (browser tests): checks the test's POM calls against source; requires the discovery pass — this tool called for the same testFile without `verify` — to have run first. SkyrampUtils path (every other test type): stages the shared utils file for the output commit, checks its invariants, and — when skyramp_modularization recorded a baseline for this spec — compares the delivered assertion count and page.on('pageerror') guard against that hand-out, rejecting a net loss (API helpers: one helper per method+path, status-code-only assertions, method+resource names; browser helpers: actions and structural waits only, intent names). Call it after the reuse edits are written; skyramp_enhance_assertions and skyramp_execute_test refuse until it has passed."),
+        .describe("Verify a previously refactored test instead of returning the reuse prompt. POM path (browser tests): checks the test's POM calls against source; requires the discovery pass — this tool called for the same testFile without `verify` — to have run first. SkyrampUtils path (every other test type): stages the shared utils file for the output commit, checks its invariants, and — when skyramp_modularization recorded a baseline for this spec — compares the delivered assertion count and page.on('pageerror') guard against that hand-out, rejecting a net loss (API helpers: one helper per method+path, status-code-only assertions, method+resource names; browser helpers: actions and structural waits only, intent names, one helper per action sequence; every family: one name is defined once per module, with one parameter count across modules). Call it after the reuse edits are written; skyramp_enhance_assertions and skyramp_execute_test refuse until it has passed."),
     testType: z
         .nativeEnum(TestType)
         .optional()

package/build/tools/code-refactor/reuse-outcome.d.ts

@@ -21,7 +21,7 @@ export interface FlaggedMember {
  * moment the spec changes — and it does change: the execution fix-up may restore
  * `<testFile>.raw.bak` over the spec by plain `cp`, invisible to this tool. The
  * counts and the decline list are therefore derived at report time (see
- * `rederiveReuseOutcome`), never read back from here.
+ * `rederiveReuse`), never read back from here.
  *
  * And keeping the two types disjoint makes the report boundary opt-IN. When the
  * record extended the wire type, every field added here shipped to the

package/build/tools/code-refactor/reuse-state.d.ts

@@ -1,13 +1,14 @@
 import { type VerifyResult } from "../../utils/pom-verify/index.js";
 import { type ReuseOutcome, type ReuseRecord } from "./reuse-outcome.js";
 import { type UtilsVerifyResult } from "../../utils/utils-verify/index.js";
+import type { ReuseVerificationFailure } from "../../types/ReuseOutcome.js";
 /**
  * Record the tier-1 candidate count STEP 1 detected, plus the identity needed to
  * re-derive the counts from the delivered spec later.
  *
  * The identity is written here and not only by {@link recordVerifyOutcome} because
  * the verify pass is a call the agent decides whether to make. When it skips it,
- * a record holding the candidate count alone makes `rederiveReuseOutcome` bail out,
+ * a record holding the candidate count alone makes `rederiveReuse` bail out,
  * and the report states "N candidate POM files detected" with no reuse numbers —
  * indistinguishable from a run where reuse was measured and simply not summarized.
  * Recording it unconditionally is what makes the zero-reuse case reportable without
@@ -55,9 +56,11 @@ export declare function recordVerifyOutcome(testFile: string, r: VerifyResult, g
  * NOT terminal. A PASS is always reachable in one edit plus one call (substitute the
  * members, or document each candidate with a `// kept inline:` marker, which the gate
  * accepts), and an agent that resolves neither can still walk past these tools to
- * `skyramp_submit_report`, which does not block and reports the honest zero. So the
- * worst case degrades to the reporting half rather than to a run that produces
- * nothing — which is what a bound would have been protecting against.
+ * `skyramp_submit_report`. That tool refuses a blocking verdict on the delivered
+ * files too, but its refusal is BOUNDED (`REUSE_SUBMIT_MAX_REFUSALS`): past the bound
+ * it accepts the report with the fault recorded in the row. So the worst case still
+ * degrades to the reporting half rather than to a run that produces nothing — which
+ * is what a bound here would have been protecting against.
  */
 export declare function pendingReuseVerification(testFile: string, explicitStateFile?: string): Promise<string | undefined>;
 /**
@@ -81,7 +84,17 @@ export declare function recordUtilsVerifyError(testFile: string, explicitStateFi
 export declare function samePath(a: string, b: string): boolean;
 /** Exported for retrofit-state: the same canonicalisation the records use. */
 export declare function canonPath(p: string): string;
-/** The basename label a report row shows for a set of utils files. */
+/**
+ * The label a report row shows for a set of utils files: each file's path relative
+ * to its repository root, posix-separated, joined with `, `.
+ *
+ * Repository-relative, never absolute — an absolute path carries the runner's
+ * temporary directory and means nothing to a customer. Not a basename either: a
+ * fullstack delivery writes one module per test directory under the same
+ * conventional name, and two rows labelled `skyrampUtils.ts` cannot be told apart
+ * (a renderer keyed on the label then merges them into one aggregate). Outside a
+ * repository, or for a file the root does not contain, the basename stands in.
+ */
 export declare function utilsFileLabel(files: string[]): string;
 /** Verdict of one utils verify pass. The verdict alone is stored — counts and the
  *  file list are re-derived from the delivered files at report time. */
@@ -148,6 +161,64 @@ export declare function reuseChainSkipped(fileName: string, testType: string, re
     testType: string;
     language: string;
 }> | undefined): Promise<true | undefined>;
+/**
+ * A blocking reuse verdict measured on the DELIVERED files at report time — the
+ * same predicate the live `verify: true` pass refuses on, re-run on what ships.
+ *
+ * Verification is a one-time checkpoint on a file that keeps changing: the execution
+ * fix loop deletes a failing assertion after the gate recorded `passed`, and a
+ * post-verification full-file rewrite erases verified page-object reuse. Until this
+ * existed, the report re-derived the verdict, found the fault, wrote it into a field
+ * and shipped the work — the run committed the fault, detected it, disclosed it and
+ * delivered it. `skyramp_submit_report` refuses on this instead, and the agent
+ * repairs (or documents the decline) and resubmits.
+ *
+ * Only a BLOCKING verdict lands here. Advisories (`scenario-name`, untyped
+ * parameters, sibling inline call sites, single importers) never do: they are
+ * report-time signals whose number means something only on the final file, and
+ * they must stay free to be computed and reported at submit.
+ */
+export interface ReuseBlockingVerdict {
+    /** ABSOLUTE PATH of the spec the verdict is about — the refusal is agent-facing,
+     *  and two specs sharing a basename (one per repository) must stay two verdicts. */
+    file: string;
+    /** The blocking kinds found, each with its count and detail — what the row ships
+     *  with once the refusal bound is reached. */
+    failures: ReuseVerificationFailure[];
+    /** What failed and how to repair it — the text the live verify pass would have
+     *  returned for the delivered file, so the remediation is the one the agent knows. */
+    detail: string;
+    /** The exact `skyramp_reuse_code` verify call to make after the repair, so the
+     *  repaired files are re-checked. */
+    verifyCall: string;
+}
+/**
+ * How many times skyramp_submit_report refuses a report over one spec's blocking
+ * verdict before accepting it with the fault recorded in the row.
+ *
+ * The refusal is a repair loop, and a repair loop at the last step of a run needs a
+ * terminal state (SKYR-4059: an unbounded loop destroyed verified work). Without one,
+ * an agent that cannot reach a pass — out of turns, or a `guard-removed` it cannot
+ * restore, which no marker documents away — delivers no report at all, and a
+ * customer with no pull request is a worse outcome than one with a disclosed fault.
+ * Two refusals cover the common case, where the repair is one edit and one verify
+ * call away; the third call ships the row with `verificationFailures` set.
+ */
+export declare const REUSE_SUBMIT_MAX_REFUSALS = 2;
+/** What one report row's re-derivation established: the outcome to publish, and a
+ *  blocking verdict when the delivered files fail the live check. */
+export interface ReuseRederivation {
+    outcome: ReuseOutcome | undefined;
+    blocking?: ReuseBlockingVerdict;
+}
+/**
+ * The reason behind a failed shared-helper verdict, one entry per blocking kind in
+ * the order the verifier found them. The verify pass had these in hand and dropped
+ * them after computing `ok`; without them a `failed` row is a verdict nobody can act
+ * on. The detail text is the verifier's own — for an assertion loss it carries the
+ * counts (baseline, delivered, in the test, in the helpers) that decided the verdict.
+ */
+export declare function verificationFailures(r: UtilsVerifyResult): ReuseVerificationFailure[];
 /**
  * Re-derive a recorded outcome from the spec as it stands NOW, so the report
  * describes the delivered artifact rather than the state at verify time.
@@ -169,8 +240,15 @@ export declare function reuseChainSkipped(fileName: string, testType: string, re
  *
  * Returns the recorded outcome minus internals when re-derivation is impossible
  * (no path recorded — now only the no-POM-layer path, which has no spec to measure
- * and no candidates to contrast against), and `undefined` when it fails outright.
+ * and no candidates to contrast against), and no outcome when it fails outright.
  * Failing closed matters: falling back to the recorded counts is exactly the false
  * claim this exists to prevent.
+ *
+ * Beside the outcome comes the blocking verdict the delivered files earn under the
+ * live check — see {@link ReuseBlockingVerdict}. One measurement feeds both: the row
+ * the report publishes and the refusal `skyramp_submit_report` returns. That half
+ * fails OPEN like every reuse check: a re-derivation that throws yields no outcome
+ * and no verdict. A verifier that cannot run is not evidence against the file, and
+ * refusing a report on a malfunction would deliver nothing to the customer.
  */
-export declare function rederiveReuseOutcome(record: ReuseRecord): Promise<ReuseOutcome | undefined>;
+export declare function rederiveReuse(record: ReuseRecord): Promise<ReuseRederivation>;