@skyramp/mcp 0.4.0 → 0.4.1-rc.2

package/build/recommendation/pullRequestText.js

@@ -0,0 +1,31 @@
+/** The pull request's own title and description, as the run rendered its prompt with.
+ *
+ *  IN PROCESS, never the state file: the prompt and the plan tool are registered on
+ *  the same server, so the text is already here, and writing it would put the pull
+ *  request's prose on disk once per registration for a reader in the same process.
+ *
+ *  ONE SLOT, last write wins. A run renders the prompt once, and a second render is
+ *  a second run whose text replaces the first. */
+let recorded;
+const asText = (value) => (typeof value === "string" ? value : "");
+/** Called by every entry point that renders the testbot prompt, with the values it
+ *  renders. */
+export function recordPullRequestText(title, description) {
+    recorded = { title: asText(title), description: asText(description) };
+}
+/** UNDEFINED when this process never rendered the prompt — a caller that drives the
+ *  tools directly, or a test. A check that reads the pull request stays silent then;
+ *  it cannot tell an empty pull request from one it never saw. */
+export function pullRequestText() {
+    return recorded;
+}
+export function clearPullRequestText() {
+    recorded = undefined;
+}
+/** The pull request as one searchable string. Whitespace runs fold to one space, so
+ *  a quote wrapped across lines still matches the sentence it was taken from. */
+export const searchable = (pr) => `${pr.title}\n${pr.description}`.replace(/\s+/g, " ").trim().toLowerCase();
+export const appearsIn = (haystack, needle) => {
+    const folded = needle.replace(/\s+/g, " ").trim().toLowerCase();
+    return folded.length > 0 && haystack.includes(folded);
+};

package/build/recommendation/registerPlan.d.ts

@@ -1,11 +1,19 @@
-import { Objection, ObjectionAnswer, PlanChange, PlanInput, PlannedTest, VerifyContext } from "./types.js";
+import { Objection, ObjectionAnswer, PlanChange, PlanDefect, PlanInput, PlanMaintenance, PlannedTest, VerifyContext } from "./types.js";
 /** The plan as stored for the run. Every registration produces one; the newest
  *  replaces the last. */
 export interface Plan {
     /** The changes the agent said the diff makes. Published in the report
      *  beside the tests delivered against each one. */
     changes: PlanChange[];
+    /** The defects the code review found. skyramp_submit_report reads them to hold
+     *  the report to the review: every one is an issue, and every issue names the
+     *  test that proves it. */
+    defects: PlanDefect[];
     plannedTests: PlannedTest[];
+    /** Existing tests this run edits instead of planning new ones. Stored because
+     *  `coverage` counts the changes they cite, so a reader of the plan has to be
+     *  able to see which coverage came from maintenance rather than a new test. */
+    maintains?: PlanMaintenance[];
     /** Objections the agent answered, with the answers. */
     answeredObjections: Array<{
         objection: Objection;

package/build/recommendation/registerPlan.js

@@ -53,12 +53,13 @@ export function registerPlan(registration, ctx, previous) {
     const acknowledged = Array.isArray(registration.answers) ? registration.answers : [];
     const plannedTests = Array.isArray(registration.plannedTests) ? registration.plannedTests : [];
     const changes = Array.isArray(registration.changes) ? registration.changes : [];
+    const defects = Array.isArray(registration.defects) ? registration.defects : [];
     const registrationNumber = storedRegistrationNumber(registration);
     // The verifiers see the same normalised fields the STORED plan gets, not the raw
     // registration: handing them the raw one let a malformed top-level field crash
     // every check at once, giving eight `:crashed` objections and no real ones.
     // Crash containment is for a malformed field INSIDE a planned test.
-    const verified = runPlanTimeVerifiers({ ...registration, plannedTests, changes, answers: acknowledged }, ctx);
+    const verified = runPlanTimeVerifiers({ ...registration, plannedTests, changes, defects, answers: acknowledged }, ctx);
     const objections = [
         ...verified,
         ...unknownAnswerObjections(verified, acknowledged, {
@@ -107,7 +108,13 @@ export function registerPlan(registration, ctx, previous) {
             : {}),
         plan: {
             changes,
+            defects,
             plannedTests,
+            // Only when declared: the field is optional, and writing `[]` on every plan
+            // would change the stored shape of every run that maintains nothing.
+            ...(Array.isArray(registration.maintains) && registration.maintains.length > 0
+                ? { maintains: registration.maintains }
+                : {}),
             answeredObjections,
             unverifiedCloses,
             openObjections,

package/build/recommendation/runVerifiers.js

@@ -6,7 +6,10 @@ import { expectedOutcomeAtPlanTime } from "./verifiers/expectedOutcome.js";
 import { uiElementGrounded } from "./verifiers/uiElementGrounded.js";
 import { screenRoute } from "./verifiers/screenRoute.js";
 import { coverage } from "./verifiers/coverage.js";
+import { expectedValueSourced } from "./verifiers/expectedValueSourced.js";
 import { removedElementGuarded } from "./verifiers/removedElementGuarded.js";
+import { requirementSourced } from "./verifiers/requirementSourced.js";
+import { defects } from "./verifiers/defects.js";
 /** Verifiers that need only the plan and the run's facts. The order is the order
  *  objections are reported in; it carries no priority. */
 export const PLAN_TIME_VERIFIERS = [
@@ -18,7 +21,10 @@ export const PLAN_TIME_VERIFIERS = [
     uiElementGrounded,
     screenRoute,
     coverage,
+    expectedValueSourced,
     removedElementGuarded,
+    requirementSourced,
+    defects,
 ];
 /** How a crashed verifier reads back. The id is the verifier's name plus a fixed
  *  word, so it stays stable across registrations and can be answered. */

package/build/recommendation/types.d.ts

@@ -23,6 +23,9 @@ export interface PlanChange {
     id: string;
     text: string;
     source: string;
+    /** The requirement in the pull request's own words, when `source` names the pull
+     *  request. Checked against the text the run rendered its prompt with. */
+    quote?: string;
     /** Where a user or caller meets this change. Every change states it: an optional
      *  field the agent skips gives the check nothing to read. */
     surfaces: Array<"api" | "page">;
@@ -34,8 +37,32 @@ export interface PlanChange {
         value?: string | number | boolean | null;
         absent?: true;
         expect: "accept" | "reject";
+        /** What the response must carry when this case is sent. Declared here so the
+         *  test asserts a value the plan decided, not the value the running app
+         *  happened to return — the one source that always agrees with a defect. */
+        expectedValue?: string | number | boolean | null;
+        /** Where the agent read `expectedValue` OR `derived` — the check reads it for
+         *  either one: `pr-description`, `spec:<path>`, `convention:<file:line>`, or
+         *  `code`. */
+        expectedFrom?: string;
+        /** The rule the value follows from, in the source's words, when the source
+         *  states a rule and not a value. Stands in for `expectedValue`: the test
+         *  computes the number from what it sent, so nothing pins one the source
+         *  never wrote. */
+        derived?: string;
     }>;
 }
+/** One defect the code review found, as the agent read it. Nothing on the server
+ *  parses the description or opens the file: the check reads the id, and a test
+ *  that cites it and expects to fail is what proves it. */
+export interface PlanDefect {
+    id: string;
+    file: string;
+    /** Advisory. Line numbers drift, so nothing checks it. */
+    line?: number;
+    description: string;
+    severity: "critical" | "high" | "medium" | "low";
+}
 /** What a planned test states so a verifier has a checkable change. Kept in step with
  *  `declarationFieldsSchema`, which the plan tool asserts against this type. */
 export interface PlannedTestDetails {
@@ -74,6 +101,9 @@ export interface PlannedTestDetails {
     };
     /** The ids of the declared changes this test proves. */
     changes?: string[];
+    /** The ids of the declared defects this test proves. A test proves a defect
+     *  only when it expects to fail; the defects check reads both. */
+    defects?: string[];
     /** The state the mutated record is in before the mutation. Presence only. */
     startState?: string;
     /** UI planned tests only. `items` entries are COPIES of elements a capture of
@@ -100,10 +130,31 @@ export interface ObjectionAnswer {
      *  An objection about an untested change closes only with one of these. */
     blocker?: string;
 }
+/** An existing test this run maintains instead of planning a new one, and the
+ *  declared changes that maintenance covers. A removal already covered by a spec
+ *  is maintained, not duplicated, so the plan needs a way to say "this change is
+ *  tested by a file I am editing" — without it, `coverage:change:` is unanswerable
+ *  for a correct maintenance decision, and it closes only with a `blocker`. */
+export interface PlanMaintenance {
+    /** Repository-relative path of the existing test. Only its presence in the
+     *  checkout is checked, the same rule `declarations.existingTests` follows. */
+    file: string;
+    /** The edit this run makes to it, in one sentence. */
+    differsBy: string;
+    /** The ids of the declared changes this maintenance covers. */
+    changes: string[];
+}
 export interface PlanInput {
     /** The changes the diff makes. Each planned test cites the ones it tests. */
     changes: PlanChange[];
+    /** The defects the code review found. Each planned test cites the ones it
+     *  proves. Empty is a statement — the review found none — and draws an
+     *  objection the agent answers. */
+    defects: PlanDefect[];
     plannedTests: PlannedTest[];
+    /** Existing tests this run edits rather than replacing with new ones. Coverage
+     *  counts the changes these cite, so a maintenance-only plan is a complete plan. */
+    maintains?: PlanMaintenance[];
     answers: ObjectionAnswer[];
     /** The tool owns this and overwrites whatever the caller sends. */
     registrationNumber: number;
@@ -141,6 +192,13 @@ export interface VerifyContext {
     /** Identifiers a rename replaced, empty when the diff renames nothing. Only the
      *  server pairs the two sides of a diff. */
     retiredUiElements: RemovedUiElement[];
+    /** The pull request's title and description, as the run rendered its prompt with.
+     *  The plan tool fills it from the process the prompt was rendered in. Both fields
+     *  blank MEANS the run had no title and no description. */
+    pullRequest: {
+        title: string;
+        description: string;
+    };
     /** Whether a cited path names a file in any of the run's repositories. Injected
      *  to keep the verifiers filesystem-free. */
     citedFileExists(relativePath: string): boolean;

package/build/recommendation/verifierContracts.d.ts

@@ -17,8 +17,6 @@ export interface ContractObjection {
 export interface VerifierContract {
     /** The verifier's own `Verifier.name`. */
     readonly id: string;
-    /** What the registered plan has to carry for the check to have anything to read. */
-    readonly declarationFields: readonly string[];
     /** One entry per message the verifier can emit, keyed by the case. A key naming a
      *  segment of the `objectionId` uses that segment's spelling. The keys are widened
      *  here so every contract satisfies the interface, while each contract is `as
@@ -31,7 +29,6 @@ export interface VerifierContract {
 }
 export declare const CHANGED_FILE_CONTRACT: {
     readonly id: "changedFile";
-    readonly declarationFields: readonly ["declarations.changedFile", "declarations.screenEvidence.file"];
     readonly objections: {
         readonly notStated: {
             readonly message: "This test does not state which changed file it targets.";
@@ -54,7 +51,6 @@ export declare const CHANGED_FILE_CONTRACT: {
 };
 export declare const SCREEN_ROUTE_CONTRACT: {
     readonly id: "screenRoute";
-    readonly declarationFields: readonly ["declarations.elements.pageUrl", "declarations.screenEvidence.file", "declarations.changedFile"];
     readonly objections: {
         readonly mismatch: {
             readonly message: "The page this UI test opens is not a page that renders the changed file it is about.";
@@ -69,7 +65,6 @@ export declare const SCREEN_ROUTE_CONTRACT: {
 };
 export declare const ENDPOINT_GROUNDED_CONTRACT: {
     readonly id: "endpointGrounded";
-    readonly declarationFields: readonly ["steps[]", "testType", "declarations.routes"];
     readonly objections: {
         readonly uncited: {
             readonly message: "A call this test makes cites no file that declares it.";
@@ -88,7 +83,6 @@ export declare const ENDPOINT_GROUNDED_CONTRACT: {
 };
 export declare const STATED_DIFFERENCE_CONTRACT: {
     readonly id: "statedDifference";
-    readonly declarationFields: readonly ["steps[]", "testType", "scenarioName", "declarations.differsFrom"];
     readonly objections: {
         readonly unexplainedPair: {
             readonly message: "Another planned test in this plan tests the same endpoint and neither says how they differ.";
@@ -107,18 +101,24 @@ export declare const STATED_DIFFERENCE_CONTRACT: {
 };
 export declare const EXISTING_COVERAGE_CONTRACT: {
     readonly id: "existingCoverage";
-    readonly declarationFields: readonly ["declarations.existingTests"];
     readonly objections: {
         readonly citedTestMissing: {
             readonly message: "This planned test names an existing test file that is not in the checkout.";
             readonly suggestion: "Name the file repository-relative, spelled as the analysis lists it. Drop the entry if it names a test you did not read — naming none is an answer too.";
         };
+        readonly maintainedTestMissing: {
+            readonly message: "`maintains` names an existing test file that is not in the checkout.";
+            readonly suggestion: "Name the file repository-relative, spelled as the analysis lists it. A maintenance entry is what makes its changes count as covered, so it has to name a file this run can edit.";
+        };
+        readonly maintainedUnknownChange: {
+            readonly message: "A `maintains` entry cites a change id that this plan does not declare.";
+            readonly suggestion: "Spell the change's `id` exactly as your own `changes` list gives it — the match is exact apart from surrounding space. Declare the change if it is missing.";
+        };
     };
-    readonly suggestion: "Which existing tests did you read on this change, and how does this planned test differ from them?";
+    readonly suggestion: "Which existing tests did you read on this change, how does this planned test differ from them, and which changes does the maintenance you are doing cover?";
 };
 export declare const EXPECTED_OUTCOME_CONTRACT: {
     readonly id: "expectedOutcome";
-    readonly declarationFields: readonly ["category", "declarations.expected.outcome", "declarations.expected.why"];
     readonly objections: {
         readonly passInShouldFailCategory: {
             readonly message: "This planned test is categorised \"{category}\" but expects to pass on the app as it stands.";
@@ -133,7 +133,6 @@ export declare const EXPECTED_OUTCOME_CONTRACT: {
 };
 export declare const UI_ELEMENT_GROUNDED_CONTRACT: {
     readonly id: "uiElementGrounded";
-    readonly declarationFields: readonly ["testType", "steps[]", "declarations.elements.items", "declarations.elements.pageUrl", "declarations.asserts", "scenarioName", "description", "declarations.expected.why"];
     readonly objections: {
         readonly nogrounding: {
             readonly message: "This UI test names no `elements.items`, so nothing says the elements it targets are on the page.";
@@ -156,11 +155,10 @@ export declare const UI_ELEMENT_GROUNDED_CONTRACT: {
 };
 export declare const COVERAGE_CONTRACT: {
     readonly id: "coverage";
-    readonly declarationFields: readonly ["changes", "declarations.changes", "declarations.changedFile", "declarations.routes", "declarations.screenEvidence.file", "declarations.startState", "changes[].cases", "changes[].surfaces"];
     readonly objections: {
         readonly change: {
             readonly message: "This declared change has no test in the plan.";
-            readonly suggestion: "Plan a test that exercises it. If this run cannot write one, answer it and set `blocker` to what stopped the run — a service that is not running, a paired branch that no longer exists, the one credential the run holds. An answer with no blocker leaves this open: a change nothing prevented a test from reaching takes the test. Coverage per file is the basic minimum; coverage per change is what the plan is judged by, so a file covered by a shape test still leaves the change it makes untested.";
+            readonly suggestion: "Plan a test that exercises it. If an existing test already covers it and this run edits that test rather than writing a new one, declare it in `maintains` with the file, what your edit changes, and this change's id — maintenance is coverage, and a duplicate spec beside the one you edited is the mistake. If this run cannot write one, answer it and set `blocker` to what stopped the run — a service that is not running, a paired branch that no longer exists, the one credential the run holds. An answer with no blocker leaves this open: a change nothing prevented a test from reaching takes the test. Coverage per file is the basic minimum; coverage per change is what the plan is judged by, so a file covered by a shape test still leaves the change it makes untested.";
         };
         readonly noChanges: {
             readonly message: "The plan declares no changes, so nothing says what the pull request must make different.";
@@ -195,7 +193,6 @@ export declare const COVERAGE_CONTRACT: {
 };
 export declare const REMOVED_ELEMENT_GUARDED_CONTRACT: {
     readonly id: "removedElementGuarded";
-    readonly declarationFields: readonly ["declarations.elements.items", "declarations.asserts"];
     readonly objections: {
         readonly missing: {
             readonly message: "The diff removes `{element}` and no planned test says it is gone.";
@@ -208,6 +205,104 @@ export declare const REMOVED_ELEMENT_GUARDED_CONTRACT: {
     };
     readonly suggestion: "Does every element this diff removes have a planned test that asserts it is gone, and does no test claim a renamed identifier is gone?";
 };
+export declare const EXPECTED_VALUE_SOURCED_CONTRACT: {
+    readonly id: "expectedValueSourced";
+    readonly objections: {
+        readonly sourcedFromCode: {
+            readonly message: "This case expects a value it read from the code as it stands, so a defect in that code becomes what the test demands.";
+            readonly suggestion: "Read the value from the pull request title or description, from a requirements file the description names, or from a convention the application already follows elsewhere, and name that source. If none of them states it, leave `expectedValue` out and assert the shape instead.";
+        };
+        readonly missingSource: {
+            readonly message: "This case states an expected value and does not say where the value came from.";
+            readonly suggestion: "Set `expectedFrom` to `pr-title`, `pr-description`, `spec:<path>`, `convention:<file:line>` or `code`.";
+        };
+        readonly unreadableSource: {
+            readonly message: "This case names a file as the source of its expected value, and that file is not in the checkout.";
+            readonly suggestion: "Give the path as the repository spells it, from the repository root. If the file is not there, the value has no source: read it from the pull request title or description instead, or leave `expectedValue` out and assert the shape.";
+        };
+        readonly changedConvention: {
+            readonly message: "This case reads its expected value from a line this pull request writes, so the same change decides both the behaviour and what counts as correct.";
+            readonly suggestion: "Cite a file the pull request leaves alone, or read the value from the description or a requirements file. If the cited file is changed but has nothing to do with this case, say so as the answer.";
+        };
+        readonly quoteMissing: {
+            readonly message: "This case reads its value from the pull request, and its change does not quote the sentence that states the rule.";
+            readonly suggestion: "Put the sentence from the title or description on the change as `quote`, as written there. If that sentence states the rule and not the number, put the rule in `derived` and leave `expectedValue` out.";
+        };
+        readonly valueNotQuoted: {
+            readonly message: "This case reads its value from the pull request, and the pull request does not state this value.";
+            readonly suggestion: "Quote the sentence that states it, or, if the pull request states a rule, put the rule in `derived` and leave `expectedValue` out; the test computes the value from what it sent.";
+        };
+        readonly failWithoutValue: {
+            readonly message: "This test expects to fail, and no case on the changes it cites states the value it must assert.";
+            readonly suggestion: "Put the value the code does not return today on the case this test sends, as `expectedValue`, and name where you read it. If the source states a rule rather than a number, put the rule in `derived` instead. If no source states either, answer with what the test asserts instead and where that comes from.";
+        };
+    };
+    readonly suggestion: "Where does the correct value for this case come from?";
+};
+export declare const REQUIREMENT_SOURCED_CONTRACT: {
+    readonly id: "requirementSourced";
+    readonly objections: {
+        readonly unsourced: {
+            readonly message: "Change `{change}` does not name a source the plan accepts: `pr-title`, `pr-description`, `spec:<path>` or `diff`.";
+            readonly suggestion: "Set `source` on this change to `pr-title` or `pr-description`, to `spec:<path>` for the requirements file that states it, or to `diff`.";
+        };
+        readonly unreadable: {
+            readonly message: "Change `{change}` cites `{source}`, and the checkout holds no file at that path.";
+            readonly suggestion: "Cite the requirements file by the path the checkout holds, or name the source you actually read this change in.";
+        };
+        readonly fromDiff: {
+            readonly message: "This test reports a requirement conflict, and none of the changes it cites was read from the pull request or a requirements file.";
+            readonly suggestion: "Cite a change you read in the pull request or in a requirements file, or report this test as something other than a requirement conflict.";
+        };
+        readonly notNamed: {
+            readonly message: "Change `{change}` cites `{source}`, and the pull request names no such file.";
+            readonly suggestion: "Cite a file the title or description names. If neither names it, you read the change in the repository, so set `source` to `diff`.";
+        };
+        readonly emptyPullRequest: {
+            readonly message: "Change `{change}` says it was read from the pull request, and the pull request has no title or description.";
+            readonly suggestion: "Set `source` to `spec:<path>` for the requirements file that states this change, or to `diff` if only the code states it.";
+        };
+        readonly notQuoted: {
+            readonly message: "This test reports a requirement conflict, and change `{change}` quotes words the pull request does not carry.";
+            readonly suggestion: "Quote the requirement as the title or description spells it, word for word. If you cannot find those words there, the change came from somewhere else: say where in `source`.";
+        };
+        readonly unquoted: {
+            readonly message: "This test reports a requirement conflict, and change `{change}` does not quote the requirement.";
+            readonly suggestion: "Set `quote` on that change to the sentence in the title or description that states the requirement.";
+        };
+        readonly noChange: {
+            readonly message: "This test reports a requirement conflict and cites no change, so nothing says where the requirement came from.";
+            readonly suggestion: "Name in `changes` the change that states the requirement, or report this test as something other than a requirement conflict.";
+        };
+    };
+    readonly suggestion: "Does every change name where you read it, and does every requirement-conflict test cite a change that came from the pull request or a requirements file?";
+};
+export declare const DEFECTS_CONTRACT: {
+    readonly id: "defects";
+    readonly objections: {
+        readonly none: {
+            readonly message: "The plan declares no defects, so nothing says the code review happened before the plan.";
+            readonly suggestion: "Review the code that serves each change — the handler, the functions it calls to read or write data, the component and what it calls — and list each defect in `defects`. If the review found none, answer in one line what you read.";
+        };
+        readonly untested: {
+            readonly message: "This declared defect has no test in the plan.";
+            readonly suggestion: "Add a planned test that cites the defect in `defects` and sets `expected.outcome` to `fail`. A defect in a file this pull request touches gets the test whether or not this pull request introduced it. If something stopped this run from writing the test, answer it and set `blocker` to what stopped it.";
+        };
+        readonly expectedPass: {
+            readonly message: "Every test that cites this defect expects to pass, and a test that passes today proves nothing about a defect.";
+            readonly suggestion: "Assert what the fixed code returns, set `expected.outcome` to `fail` with `why`, or answer in one line why a passing test is the proof.";
+        };
+        readonly unknownId: {
+            readonly message: "A planned test cites a defect id that this plan does not declare.";
+            readonly suggestion: "Spell the defect's `id` exactly as your own `defects` list gives it — the match is exact apart from surrounding space. Declare the defect if it is missing.";
+        };
+        readonly conflictWithoutDefect: {
+            readonly message: "This test reports a requirement conflict and cites no defect.";
+            readonly suggestion: "List the conflict in `defects`: the file and line that contradict the requirement, and a description that quotes the requirement. Cite that id from this test.";
+        };
+    };
+    readonly suggestion: "Which planned test proves each defect the review found, and for one nothing proves, why does it need no test?";
+};
 /** Fills a contract sentence's `{placeholder}` spans from the run's or the
  *  planned test's own values. A placeholder with no value is left as written rather
  *  than blanked, so a missed key shows up as `{knob}` instead of reading as a gap