@skyramp/mcp 0.3.8 → 0.4.0-rc.1

package/build/types/TestbotReport.d.ts

@@ -1,8 +1,9 @@
 import type { DriftAction } from "./TestAnalysis.js";
 import type { TestExecutionStatus } from "./TestExecution.js";
-import type { HttpMethod, TestType } from "./TestTypes.js";
+import type { TestType } from "./TestTypes.js";
 import type { ReuseOutcome } from "./ReuseOutcome.js";
 import type { AssertionOutcome } from "./AssertionOutcome.js";
+import type { StepMethod } from "./StepMethod.js";
 /** Classification of an issuesFound entry. Bug is a product/code defect; the
  *  other values are tooling noise that the Testbot report renders in its
  *  Configuration Errors section instead of Issues Found. */
@@ -23,6 +24,11 @@ export interface TestbotReport {
     businessCaseAnalysis: string;
     newTestsCreated: {
         testId: string;
+        /** Recommendation v2: the id of the plan entry this test was approved under.
+         *  Required by the submit schema whenever v2 is on, on every entry including
+         *  UI, because it is the exact key the report is joined back to the plan on.
+         *  Absent in reports from a v1 run, which has no plan to take an id from. */
+        plannedTestId?: string;
         testType: TestType;
         endpoint: string;
         fileName: string;
@@ -34,6 +40,11 @@ export interface TestbotReport {
         scenarioFile?: string;
         traceFile?: string;
         frontendTrace?: string;
+        /** True when the plan entry this test was approved under expected it to FAIL:
+         *  its category is `bug_caught` or it declared `fail`. Server-derived from the
+         *  plan by `plannedTestId`, because the report enum has no `bug_caught` value.
+         *  Absent when it is not one, when no plan exists, or when the id matches none. */
+        expectedToFail?: boolean;
         /** UI tests only: POM code-reuse outcome, present when skyramp_reuse_code ran
          *  for this test. Server-derived — imported from its source of truth rather
          *  than re-declared, since that module already exports a plain interface (the
@@ -54,6 +65,11 @@ export interface TestbotReport {
         testType: TestType;
         endpoint: string;
         fileName: string;
+        /** The file the maintenance edit actually landed in, when that is not
+         *  `fileName` — a page object the spec delegates its selectors to. `fileName`
+         *  stays the SPEC, which is what ran and what `beforeStatus`/`afterStatus`
+         *  describe. Absent when the edit landed in the spec, the normal case. */
+        editedFileName?: string;
         description: string;
         action: DriftAction;
         beforeStatus: TestExecutionStatus;
@@ -81,7 +97,11 @@ export interface TestbotReport {
         primaryEndpoint?: string;
         scenarioName?: string;
         steps: {
-            method?: HttpMethod;
+            /** An HTTP method for a request, one of the page interactions for a UI step,
+             *  or `OPERATION` for a call with no HTTP verb, whose own name goes in `path`.
+             *  Three closed sets rather than a string: `HttpMethod` alone refused a UI
+             *  recommendation, and `HttpMethod | UiVerb` would refuse every operation. */
+            method?: StepMethod;
             path?: string;
             description: string;
             expectedStatusCode?: number;
@@ -99,6 +119,10 @@ export interface TestbotReport {
     }[];
     issuesFound: {
         description: string;
+        /** The planned test this issue is about, when it is about one — set on the
+         *  issue that writes up a `requirement_conflict` so the conflict names the
+         *  test that asserts it. Absent on an issue about no particular test. */
+        plannedTestId?: string;
         severity?: "critical" | "high" | "medium" | "low";
         /** Required by the submit_report schema since 0.3.4; absent in reports
          *  written by older MCP versions. Readers treat absence as Bug. */
@@ -116,5 +140,43 @@ export interface TestbotReport {
         repository?: string;
     }[];
     nextSteps: string[];
+    /** Recommendation v2 only. Every change the plan declared, with the tests
+     *  delivered against it and the agent's answer where it planned none. This is
+     *  the line a developer reads: every change the diff makes is tested,
+     *  or has a reason. Absent for a v1 run, and for a v2 run whose plan declared
+     *  no changes. */
+    changes?: {
+        id: string;
+        text: string;
+        source: string;
+        /** `plannedTestId` of each delivered test citing this change. Empty where the
+         *  agent answered instead of planning one. */
+        testedBy: string[];
+        /** The agent's answer to `coverage:change:<id>`, where it gave one. */
+        answer?: string;
+    }[];
+    /** Recommendation v2 only. Every plan-time objection, then those raised when the
+     *  report was submitted, `stage` saying which. All a record, not a gate: the
+     *  tests exist by the time any is raised. Absent for a v1 run and for a v2 run
+     *  whose agent never registered a plan. */
+    objections?: {
+        objectionId: string;
+        verifier: string;
+        /** Absent for a plan-level objection such as `coverage:noChanges`. */
+        plannedTestId?: string;
+        message: string;
+        evidence: string;
+        suggestion: string;
+        stage: "plan" | "post-execution";
+        /** The agent's answer, where it answered — at plan time through
+         *  `skyramp_register_test_plan`, after execution through `skyramp_submit_report`.
+         *  Any non-blank text closes an objection and the server does not judge it, so
+         *  the answer travels with the objection and the reader decides. */
+        answer?: string;
+        /** Set on an objection a LATER report call stopped raising: the agent fixed what
+         *  it named instead of answering. Says which call noticed. Absent on every
+         *  objection still raised, answered or not — the two are different outcomes. */
+        resolvedBy?: string;
+    }[];
     commitMessage: string;
 }

package/build/utils/AnalysisStateManager.d.ts

@@ -3,25 +3,21 @@ import type { AssertionRecord } from "../types/AssertionOutcome.js";
 import { TestAnalysisResult, MaintenanceActionCore } from "../types/TestAnalysis.js";
 import { RepositoryAnalysis, AnalysisScope } from "../types/RepositoryAnalysis.js";
 import { PRTestContext } from "./pr-comment-parser.js";
-import { ParsedDiffEndpoint } from "./routeParsers.js";
-import type { CandidateUiPage } from "./uiPageEnumerator.js";
-import type { FrontendFileIntegration } from "../types/FrontendIntegration.js";
-import type { ApprovedPlanItem } from "../types/Recommendation.js";
+import type { RemovedUiElement } from "./removedUiElements.js";
 import type { ExternalTestRunRecord } from "../types/ExternalTestExecution.js";
 import type { VideoRecord } from "../types/TestExecution.js";
 import type { RepoCheckout } from "./reportVerification.js";
-export type { CandidateUiPage } from "./uiPageEnumerator.js";
+import type { Plan } from "../recommendation/registerPlan.js";
+import type { Objection } from "../recommendation/types.js";
 export declare function setTestsRepoDir(dir: string | undefined): void;
 /**
  * Record the run's tests repo without ever clearing a known value.
  *
  * The tests repo is a RUN-scoped fact, but analyze_changes is called once per
  * repository and only the PRIMARY call carries `testsRepoDir` — a related
- * repo's call omits it. An unconditional set therefore wiped the primary's
- * value on the second call of every multi-repo run, and by report time the
- * tests repo was unknown: a UI test generated there looked unbacked by any
- * working tree and the agent demoted it out of newTestsCreated (SKYR-4204,
- * run 32536569467). Callers that mean to clear it use setTestsRepoDir.
+ * repo's call omits it. An unconditional set therefore wipes the primary's
+ * value on the second call of every multi-repo run, leaving the tests repo
+ * unknown by report time. Callers that mean to clear it use setTestsRepoDir.
  */
 export declare function rememberTestsRepoDir(dir: string | undefined): void;
 export declare function getTestsRepoDir(): string | undefined;
@@ -29,6 +25,9 @@ export declare function getTestsRepoDir(): string | undefined;
  *  Single-sourced so the constructor that WRITES there and `resolveRunStatePath`
  *  which LOOKS there cannot drift apart. */
 export declare const RUN_STATE_FILE_NAME = "analyze-changes-state.json";
+/** Filename of the pointer that carries the multi-repo anchor across a server
+ *  restart. It holds one line: the absolute path of the run's state file. */
+export declare const RUN_STATE_POINTER_FILE_NAME = "run-state-path";
 /**
  * Directory holding this run's Skyramp artifacts — the state file, and the report written
  * beside it (SKYR-4147) — or undefined outside a run.
@@ -37,15 +36,13 @@ export declare const RUN_STATE_FILE_NAME = "analyze-changes-state.json";
  * work it out from the environment on their own. So neither has to tell the other where
  * the run's files live, and the path never passes through the model.
  *
- * The GitHub Action is the only caller customers run, and GitHub sets `RUNNER_TEMP` for
- * it; the eval harness sets it itself. Nothing customers run is on another CI system, so
- * the GitHub-specific name is only a naming problem — it does not break anything today.
- * If a caller on another CI system is added, rename this then, or let it read that
- * system's variable. Do not add a second variable for a caller that does not exist.
+ * The GitHub Action is the only caller customers run and GitHub sets `RUNNER_TEMP` for it;
+ * the eval harness sets it itself. If a caller on another CI system is added, rename this
+ * then, or let it read that system's variable. Do not add a second variable for a caller
+ * that does not exist.
  *
- * Kept in one place for the same reason `RUN_STATE_FILE_NAME` is: the directory used to be
- * written out at three call sites, so only the filename was safe from the three copies
- * drifting apart. testbot keeps its matching copy in one place too, in `skyrampTempDir()`.
+ * Kept in ONE place, like `RUN_STATE_FILE_NAME`: written out per call site, the copies
+ * drift. testbot keeps its matching copy in `skyrampTempDir()`.
  */
 export declare function runArtifactDir(): string | undefined;
 export declare function setActiveRunStatePath(stateFilePath: string): void;
@@ -57,15 +54,15 @@ export declare function clearActiveRunStatePath(): void;
  * agent naming it.
  *
  * `setActiveRunStatePath` is only called by skyramp_analyze_changes on multi-repo
- * runs (the ones carrying a `repository` param), but a single-repo Testbot run's
- * path is still deterministic in CI: the StateManager constructor above roots
- * "analysis" state under `runArtifactDir()`. Falling back to that covers
- * single-repo runs without a new anchor mechanism. Standalone/IDE usage has no
- * RUNNER_TEMP and resolves to undefined — correct, since there is no run state.
+ * runs (the ones carrying a `repository` param). It is read back two ways: from
+ * memory in this process, and from the pointer file a previous stage of the same
+ * run wrote — a staged run starts a fresh server per stage, so memory alone would
+ * send later stages to the wrong file.
  *
- * Lives here rather than in each caller so the convention has one home: this is
- * the module that decides where the file goes, so it is the module that should
- * decide where to look for it.
+ * A single-repo Testbot run's path is still deterministic in CI: the StateManager
+ * constructor above roots "analysis" state under `runArtifactDir()`. Falling back
+ * to that covers single-repo runs. Standalone/IDE usage has no RUNNER_TEMP and
+ * resolves to undefined — correct, since there is no run state.
  */
 export declare function resolveRunStatePath(explicitPath?: string): string | undefined;
 /**
@@ -79,7 +76,7 @@ export declare function resolveRunStatePath(explicitPath?: string): string | und
  * write to a file that holds no run data is already a no-op.
  *
  * Returns the path rather than a boolean so a caller can also key per-run state on
- * it, and lives here because this is the module that decides where the file goes.
+ * it. It lives here because this is the module that decides where the file goes.
  */
 export declare function currentRunStateFile(): string | undefined;
 export declare function registerSession(sessionId: string, stateFilePath: string): void;
@@ -122,65 +119,12 @@ type TestTypeScores = Record<string, number>;
  */
 type TestTypeMapping = Record<string, string | string[]>;
 export interface UiAnalysisContext {
-    /** Frontend source files changed in this diff. */
-    changedFrontendFiles: string[];
     /**
-     * Candidate pages for blueprint capture, enumerated from route analysis.
-     * Empty when no resolvable frontend baseUrl — agent falls back to prose-driven enumeration.
+     * data-testids the diff removed from files whose page survives (SKYR-4305).
+     * Present only when non-empty. The testbot records a removal guard
+     * (`toBeHidden()` on the id + a positive sibling assertion) for each entry.
      */
-    candidateUiPages: CandidateUiPage[];
-    /**
-     * Per-file production-importer check (SKYR-3855) — server-computed so the
-     * "is this component actually integrated?" skip decision doesn't rely on
-     * the agent running its own grep mid-task. Same order as changedFrontendFiles.
-     */
-    frontendFileIntegration?: FrontendFileIntegration[];
-}
-/**
- * SKYR-3879 Path B — the server-side selection checkpoint's persisted result.
- * Written by skyramp_register_test_plan (and pre-seeded by skyramp_analyze_changes
- * when it has its own pre-ranked GENERATE items). `generate` is the mandated,
- * final list generation tools gate against (see planGuard.ts); `additional` is
- * report-only; `demotions` carries discriminator claims that failed structural
- * verification — the demotion drops the CLAIM, never the candidate, but it does
- * not keep the candidate either: budgeting can still cut it, so the same id may
- * appear in both `demotions` and `dropped`;
- * `dropped` carries candidates the selection stage removed outright from
- * `generate`/`additional` (SKYR-4214) — the visible record of what got cut
- * and why, since neither list says anything about what is missing from it.
- */
-export interface ApprovedPlan {
-    planId: string;
-    createdAt: string;
-    generate: ApprovedPlanItem[];
-    additional: ApprovedPlanItem[];
-    demotions: Array<{
-        candidateId: string;
-        reason: string;
-    }>;
-    dropped: Array<{
-        candidateId: string;
-        reason: string;
-    }>;
-}
-/**
- * Budget inputs computed once by skyramp_analyze_changes (from the same
- * classification the Execution Plan prompt is built from) and reused by
- * skyramp_register_test_plan, so re-ranking the agent's candidates never
- * drifts from the budget the agent was shown. Persisted even when no
- * `approvedPlan` is pre-seeded (e.g. no pre-drafted scenarios) so a
- * register_test_plan call with only agent-drafted candidates still budgets
- * against the correct maxGenerate/maxTotal/UI split.
- */
-export interface PlanBudgetContext {
-    maxGenerate: number;
-    maxTotal: number;
-    isUIOnlyPR: boolean;
-    hasFrontendChanges: boolean;
-    /** Serialized form of the BudgetContext.externalCoverage Set. */
-    externalCoverageKeys: string[];
-    /** Whether the PR diff changes any test file; see BudgetContext. */
-    diffChangesTestFiles?: boolean;
+    removedElements?: RemovedUiElement[];
 }
 /** A pre-existing Skyramp-generated test the reuse pass edited to import from a
  *  shared utils file (STEP 5c / the sibling-inline advisory). Keyed by ABSOLUTE
@@ -209,7 +153,6 @@ export interface UnifiedAnalysisState {
     testTypeScores?: TestTypeScores;
     testTypeMapping?: TestTypeMapping;
     analysisScope: AnalysisScope;
-    newEndpoints: ParsedDiffEndpoint[];
     /**
      * UI-specific state populated when the diff contains frontend files.
      * Absent on backend-only PRs.
@@ -220,17 +163,6 @@ export interface UnifiedAnalysisState {
     /** Maintenance actions applied via skyramp_actions — skyramp_submit_report derives
      *  testMaintenance from this. */
     maintenanceVerdicts?: MaintenanceActionCore[];
-    /**
-     * Raw branch-diff text, size-capped (~200KB), persisted so
-     * skyramp_register_test_plan can verify a discriminator's `changedCodeAnchor`
-     * occurs verbatim in the actual diff. Absent when the analysis wasn't
-     * diff-scoped or no diff content was produced.
-     */
-    diffText?: string;
-    /** SKYR-3879 Path B — see {@link PlanBudgetContext}. */
-    planBudgetContext?: PlanBudgetContext;
-    /** SKYR-3879 Path B — see {@link ApprovedPlan}. */
-    approvedPlan?: ApprovedPlan;
     /**
      * External (repo-owned) test runs recorded by skyramp_run_existing_tests, one
      * record per confirm/verify invocation. Drift analysis and the report fold in
@@ -264,6 +196,41 @@ export interface UnifiedAnalysisState {
      * the earlier attempt's now-stale directory.
      */
     executionVideos?: Record<string, VideoRecord>;
+    /** The registered plan with its answered and open objections. Run-wide, so it
+     *  lives at the ROOT whichever repository the registration names, and the newest
+     *  registration REPLACES it. No fallback: no registration means no plan.
+     *  skyramp_submit_report and eval-framework both read this key by name. */
+    plan?: Plan;
+    /** How many v2 registrations this run has had. The tool owns the number — it is
+     *  what makes `PlanInput.registrationNumber` independent of the agent. */
+    registrationCount?: number;
+    /** The answers to REPORT-stage objections, written by skyramp_submit_report.
+     *  Separate from `plan`'s lists because a plan registration replaces that
+     *  whole object. Only the answers: the objections are recomputed every call, and
+     *  each answer carries its objection so the pair matches on wording as well. */
+    reportObjections?: {
+        answeredObjections: Array<{
+            objection: Objection;
+            answer: string;
+        }>;
+        /** The post-execution objections the LAST call raised, and the submission
+         *  number it was. A later call that no longer raises one is how the server
+         *  learns the agent FIXED it rather than answered it — without this the
+         *  objection simply vanishes and only the log shows it ever fired. */
+        raisedObjections?: Array<{
+            objection: Objection;
+            submission: number;
+        }>;
+        /** Objections a later submission stopped raising, kept so they stay in every
+         *  report after the one that noticed. Dropped again if the objection comes
+         *  back. */
+        resolvedObjections?: Array<{
+            objection: Objection;
+            resolvedBy: string;
+        }>;
+        /** How many times `skyramp_submit_report` has been called this run. */
+        submissionCount?: number;
+    };
     /** Assertion-enhancement baseline + verify verdict per test file, keyed by
      *  CANONICAL ABSOLUTE PATH (path.resolve — unlike `reuseOutcomes`, nothing
      *  here matches report rows, and path keying removes basename collisions and
@@ -313,14 +280,6 @@ type StateFile<T> = T & {
     metadata: StateMetadata;
     relatedRepos?: Record<string, RepoStateSection<T>>;
 };
-/**
- * Generic State Manager for persisting workflow data
- * Reduces token usage by storing intermediate results in filesystem
- *
- * Supports two state types:
- * - analysis: Test maintenance workflow (discovery, drift, execution, health)
- * - recommendation: Test recommendation workflow (analyze repo, map tests, recommendations)
- */
 export declare class StateManager<T = any> {
     private stateFile;
     private sessionId;
@@ -360,23 +319,31 @@ export declare class StateManager<T = any> {
          *  Preserved when omitted. */
         repository?: string;
     }): Promise<void>;
-    /** Is `repo` the primary section? Primary when `repo` is falsy (single-repo /
-     *  legacy callers), when no state file exists yet (the FIRST write of a run is
-     *  the primary — the testbot prompt mandates the primary is analyzed first), or
-     *  when `repo` matches the `repo` recorded on the root metadata. A non-empty
-     *  `repo` that doesn't match an already-recorded root is a RELATED repo. */
+    /** Is `repo` the primary section? By NAME when the caller declares one: the run
+     *  says which repo is primary, so whichever call lands first cannot decide it.
+     *  Otherwise the legacy rule — falsy `repo` (single-repo callers), the first
+     *  write of the run, or a `repo` matching the root metadata (SKYR-4333: a
+     *  docs-only primary diff let the related repo write first and take the root). */
     private isPrimaryRepo;
     /**
      * Write one repo's analysis into the run-scoped state file. The primary repo
-     * (repo absent, or matching the root's recorded repo, or the first write of the
-     * run) is written to the root via writeData(); a related repo is upserted into
+     * (repo absent, matching the declared `primaryRepo`, matching the root's
+     * recorded repo, or the first write of a run that declares no primary) is
+     * written to the root via writeData(); a related repo is upserted into
      * `relatedRepos[repo]`, preserving the primary + other sections. Used by
      * skyramp_analyze_changes — every repo in the run writes the SAME stateFile path.
      */
+    /** Fields another tool owns, carried forward when this caller's payload omits
+     *  them: `writeData` rebuilds the root from its payload, and an analyze call that
+     *  did so deleted the plan the agent had registered. NAMED rather than "keep
+     *  everything omitted", which would resurrect fields a re-analysis clears. */
     writeRepoData(data: T, options: {
         repo?: string;
         repositoryPath?: string;
         step?: string;
+        /** The run's declared primary, passed on EVERY call of a multi-repo run.
+         *  Given it, write order decides nothing. */
+        primaryRepo?: string;
     }): Promise<void>;
     /**
      * Read one repo's analysis payload from the run-scoped state file. `repo`
@@ -405,8 +372,6 @@ export declare class StateManager<T = any> {
     getStateType(): StateType;
     exists(): boolean;
     delete(): Promise<void>;
-    getSize(): Promise<number>;
-    getSizeFormatted(): Promise<string>;
     /**
      * Cleanup old state files
      * @param maxAgeHours Maximum age in hours
@@ -416,3 +381,4 @@ export declare class StateManager<T = any> {
      */
     static cleanupOldFiles(maxAgeHours?: number, stateDir?: string, stateTypes?: StateType[]): Promise<number>;
 }
+export {};