@skyramp/mcp 0.4.1-rc.1 → 0.4.1

package/build/tools/test-management/analyzeChangesTool.js

@@ -4,7 +4,7 @@ import * as fs from "fs";
 import * as path from "path";
 import yaml from "js-yaml";
 import { logger } from "../../utils/logger.js";
-import { parseWorkspaceAuthType, getDefaultAuthHeader, WorkspaceAuthType, readWorkspaceConfigRaw } from "../../utils/workspaceAuth.js";
+import { parseWorkspaceAuthType, getDefaultAuthHeader, WorkspaceAuthType, readWorkspaceConfigRaw, resolveWorkspaceApiService, findWorkspaceAuthDisagreement } from "../../utils/workspaceAuth.js";
 import { AnalyticsService } from "../../services/AnalyticsService.js";
 import { makeProgressReporter } from "../../utils/progress.js";
 import { StateManager, registerSession, storeSessionData, rememberTestsRepoDir, getActiveRunStatePath, setActiveRunStatePath, } from "../../utils/AnalysisStateManager.js";
@@ -101,6 +101,20 @@ export const analyzeChangesInputSchema = {
         .default(false)
         .describe("When true, diffs the base ref against the working tree (captures uncommitted and unstaged changes). Use for local-dev workflows. Defaults to false (CI mode — committed changes only)."),
 };
+/** The shape an auth finding takes. Declared here beside the other output shapes;
+ *  the assignment below fails to compile if it drifts from `AuthFinding`. */
+const authFindingShape = z.object({
+    kind: z.literal("workspace-disagreement"),
+    message: z.string(),
+    serviceName: z.string(),
+    field: z.enum(["authType", "authHeader", "authScheme"]),
+    primary: z.string(),
+    analysed: z.string(),
+    primaryWorkspaceFile: z.string(),
+    analysedWorkspaceFile: z.string(),
+});
+const _authFindingShapeMatchesType = {};
+void _authFindingShapeMatchesType;
 /** Both halves of `uiContext` carry the same record, so the shape is declared once.
  *  It mirrors `RemovedUiElement`; the assignment below fails to compile if either drifts. */
 const uiIdentifierShape = z.object({ attribute: z.string(), value: z.string(), file: z.string() });
@@ -135,6 +149,7 @@ export const analyzeChangesOutputSchema = {
         authHeader: z.string().optional(),
         openApiSpecPath: z.string().optional(),
         openApiSpecLoaded: z.boolean(),
+        authFindings: z.array(authFindingShape).optional(),
     })
         .optional(),
     uiContext: z
@@ -285,9 +300,12 @@ export function registerAnalyzeChangesTool(server) {
             let wsAuthMethod = "none";
             let wsAuthType;
             let wsAuthScheme;
+            // What the agent has to decide about this repository's auth. Empty on a
+            // workspace whose config and code agree, which is every clean run.
+            const authFindings = [];
             const rawConfig = await readWorkspaceConfigRaw(params.repositoryPath);
             if (rawConfig) {
-                const svc = rawConfig.services?.[0];
+                const svc = resolveWorkspaceApiService(rawConfig);
                 if (svc?.api?.baseUrl)
                     wsBaseUrl = svc.api.baseUrl;
                 if (svc?.api?.authHeader !== undefined)
@@ -626,6 +644,40 @@ export function registerAnalyzeChangesTool(server) {
             if (params.repository)
                 setActiveRunStatePath(stateFile);
             registerSession(sessionId, stateFile);
+            // A related repo reads its OWN .skyramp/workspace.yml, so it can disagree
+            // with the primary's unified entry for the same service and nothing would
+            // say so.
+            //
+            // Runs AFTER the state write, because both checkout paths come off the run's
+            // state file and this call's own path is not in it until then. Write order is
+            // not fixed: given a declared `primaryRepository`, a related repo may write
+            // first and the root is then created empty (AnalysisStateManager.writeRepoData).
+            // So whichever call arrives second holds both sides and is the one that
+            // reports — the primary against the related repos already recorded, a related
+            // repo against the primary.
+            if (rawConfig && params.repository) {
+                try {
+                    const checkouts = await stateManager.listRepoCheckouts();
+                    const analysingPrimary = checkouts.some((checkout) => checkout.primary && checkout.root === params.repositoryPath);
+                    const others = checkouts.filter((checkout) => checkout.primary !== analysingPrimary &&
+                        checkout.root !== params.repositoryPath);
+                    for (const other of others) {
+                        const otherConfig = await readWorkspaceConfigRaw(other.root);
+                        const disagreement = analysingPrimary
+                            ? findWorkspaceAuthDisagreement(rawConfig, otherConfig, params.repositoryPath, other.root, other.repository)
+                            : findWorkspaceAuthDisagreement(otherConfig, rawConfig, other.root, params.repositoryPath, params.repository);
+                        if (disagreement) {
+                            authFindings.push(disagreement);
+                            break;
+                        }
+                    }
+                }
+                catch (error) {
+                    logger.debug("Could not compare this repository's workspace against the run's others", {
+                        error: error instanceof Error ? error.message : String(error),
+                    });
+                }
+            }
             try {
                 await server.server.sendResourceListChanged();
             }
@@ -672,6 +724,7 @@ export function registerAnalyzeChangesTool(server) {
                     ...(wsAuthHeader ? { authHeader: wsAuthHeader } : {}),
                     ...(wsSchemaPath ? { openApiSpecPath: wsSchemaPath } : {}),
                     openApiSpecLoaded: specFetchSucceeded,
+                    ...(authFindings.length ? { authFindings } : {}),
                 },
                 // Removed half only. No prompt describes `retiredElements`, and beside the guard
                 // list it reads as more guards to record; the plan checks read the state file.

package/build/tools/test-management/registerTestPlanTool.d.ts

@@ -3,7 +3,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StateManager, UnifiedAnalysisState } from "../../utils/AnalysisStateManager.js";
 import { TestType } from "../../types/TestTypes.js";
 import { PlanResult } from "../../recommendation/registerPlan.js";
-import { ObjectionAnswer, PlanChange, PlanDefect, PlanInput, VerifyContext } from "../../recommendation/types.js";
+import { ObjectionAnswer, PlanChange, PlanDefect, PlanInput, PlanMaintenance, VerifyContext } from "../../recommendation/types.js";
 /** The whole run's state file: the primary repository at the root, every related
  *  repository under `relatedRepos`. */
 type RunState = Awaited<ReturnType<StateManager<UnifiedAnalysisState>["readFullState"]>>;
@@ -794,6 +794,7 @@ export interface RegisterTestPlanParams {
     changes?: PlanChange[];
     defects?: PlanDefect[];
     plannedTests?: RegisterPlannedTestInput[];
+    maintains?: PlanMaintenance[];
     answers?: ObjectionAnswer[];
 }
 /** Map the schema-validated input onto a `PlanInput`. `subjectEndpoints` is

package/build/tools/test-management/registerTestPlanTool.js

@@ -3,6 +3,7 @@ import * as fs from "fs";
 import * as path from "path";
 import { TOOL_REGISTER_TEST_PLAN } from "../../toolNames.js";
 import { logger } from "../../utils/logger.js";
+import { canonicalJson, isPlainObject } from "../../utils/canonicalJson.js";
 import { StateManager, resolveRunStatePath } from "../../utils/AnalysisStateManager.js";
 import { toolError } from "../../utils/utils.js";
 import { TestType } from "../../types/TestTypes.js";
@@ -80,7 +81,7 @@ export const declarationFieldsSchema = z.object({
         .object({
         outcome: z
             .enum(["fail", "pass"])
-            .describe("Whether this test should fail or pass against the app as it stands. A `fail` test's cases carry `expectedValue`."),
+            .describe("Whether this test should fail or pass against the app as it stands. Every case a `fail` test sends carries `expectedValue` or `derived`, never both."),
         why: z
             .string()
             .describe("Why it has that outcome. A test that documents a defect asserts what the FIXED code returns — the rejection, the preserved value, the correct status — so it is red today and green after the fix, never today's defective response as correct."),
@@ -176,17 +177,6 @@ function namesAScreen(url) {
  *  missing `stepUnderTest`, so a stray one stayed at planned test level and zod
  *  dropped it. */
 const DECLARATION_FIELDS = Object.keys(declarationFieldsSchema.shape);
-function isPlainObject(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-/** One value as text with object keys sorted, so the same declaration written
- *  twice by hand is not a conflict merely because its keys are ordered
- *  differently. List order still counts: two orders are two different lists. */
-function canonicalJson(value) {
-    return JSON.stringify(value, (_key, entry) => isPlainObject(entry)
-        ? Object.fromEntries(Object.keys(entry).sort().map((key) => [key, entry[key]]))
-        : entry);
-}
 /** Move a declaration field written one level too high into `declarations`.
  *  MEASURED: about one planned test in five did this across 141 eval planned tests, and
  *  every stray planned test-level key was a declaration field. A field in BOTH places
@@ -328,18 +318,28 @@ const registerTestPlanSchema = {
             expectedValue: z
                 .union([z.string(), z.number(), z.boolean(), z.null()])
                 .optional()
-                .describe("What the response must carry when this case is sent — the value itself, not a description of it. Declare it here so the test asserts what the change is supposed to do; a value decided while the test is being written can only be the value the running app returned, which is the one value a defect cannot contradict. Leave it out when no source states the value, and the test will assert the shape instead. A test that expects to fail declares this on every case it sends."),
+                .describe("What the response must carry when this case is sent — the value itself, not a description of it. Declare it here so the test asserts what the change is supposed to do; a value decided while the test is being written can only be the value the running app returned, which is the one value a defect cannot contradict. Leave it out when no source states the value, and the test will assert the shape instead. `expectedValue` and `derived` are alternatives: a case declares one of them, never both. A test that expects to fail declares one of them on every case it sends."),
+            derived: z
+                .string()
+                .optional()
+                .describe("The rule the value follows from, in the source's words, when the source states a rule and not the value: `10 percent of the subtotal`. A test computes the value from what it sent. Use this instead of `expectedValue` whenever the pull request states the rule but never writes the number."),
             expectedFrom: z
                 .string()
                 .refine((value) => /^(pr-title|pr-description|code|spec:\S.*|convention:\S.*)$/i.test(value.trim()), {
                 message: "expectedFrom must be `pr-title`, `pr-description`, `code`, `spec:<path>`, or `convention:<file:line>`",
             })
                 .optional()
-                .describe("Where you read `expectedValue`: `pr-title`, `pr-description`, `spec:<path>` for a requirements file the description names, `convention:<file:line>` for a rule the application already follows in code this pull request did not change, or `code` for the code under test. `code` draws an objection — it is the one source that agrees with a defect — so name it only when nothing else states the value. A value read from the pull request is derived from the rule its change quotes in `quote`."),
+                .describe("Where you read `expectedValue` or `derived`: `pr-title`, `pr-description`, `spec:<path>` for a requirements file the description names, `convention:<file:line>` for a rule the application already follows in code this pull request did not change, or `code` for the code under test. `code` draws an objection — it is the one source that agrees with a defect — so name it only when nothing else states the value. A value read from the pull request has to be WRITTEN there — in the quoted sentence or elsewhere in the title or description. If the pull request states the rule and never writes the number, leave `expectedValue` out and put the rule in `derived`. A case that declares `expectedValue` or `derived` and names no source here draws an objection."),
         })
             .strict()
             .refine((entry) => (entry.value !== undefined) !== (entry.absent === true), {
             message: "a case states either `value` or `absent`, never both and never neither",
+        })
+            // The description called them alternatives and the schema took both,
+            // which left generation told to pin a number AND to compute it.
+            .refine((entry) => entry.expectedValue === undefined || String(entry.derived ?? "").trim().length === 0, {
+            message: "a case states either `expectedValue` or `derived`, never both: `derived` is the case saying no source writes the value",
+            path: ["derived"],
         }))
             .min(1, { message: "a `cases` list with no entry states no input — leave it out instead" })
             .optional()
@@ -434,6 +434,20 @@ const registerTestPlanSchema = {
         });
     })
         .describe("Your complete plan, unordered. Nothing ranks, dedups, reorders or trims it, and the server adds no planned test of its own."),
+    maintains: z
+        .array(z
+        .object({
+        file: z
+            .string()
+            .describe("Repository-relative path of the existing test this run edits. It has to resolve in the checkout: a change is credited as covered only when it does, and `existingCoverage` objects when it does not."),
+        differsBy: z.string().describe("What your edit changes in that test, in one sentence."),
+        changes: z
+            .array(z.string())
+            .describe("The ids of the declared changes this maintenance covers, spelled as your own `changes` list gives them."),
+    })
+        .strict())
+        .optional()
+        .describe("Existing tests this run edits instead of planning new ones. Coverage counts the changes these cite, so a change already covered by a spec you are updating needs no planned test — and a duplicate spec beside the one you edited is the mistake. Declare maintenance here even when the plan holds no planned tests at all: a maintenance-only plan is a complete plan."),
     answers: z
         .array(z.object({
         objectionId: z.string().describe("The objection's id, exactly as this tool reported it. Answers are matched by id, never by position."),
@@ -456,6 +470,7 @@ export function buildRegistration(params, registrationNumber) {
         changes: params.changes ?? [],
         defects: params.defects ?? [],
         answers: params.answers ?? [],
+        ...(params.maintains?.length ? { maintains: params.maintains } : {}),
         // The tool counts the run's registrations; whatever the caller sent is ignored.
         registrationNumber,
         plannedTests: (params.plannedTests ?? []).map((input) => {

package/build/types/ReuseOutcome.d.ts

@@ -1,4 +1,5 @@
 import type { TestExecutionStatus } from "./TestExecution.js";
+import type { UtilsViolationKind } from "../utils/utils-verify/allow.js";
 /**
  * The code-reuse observability shape carried in a TestbotReport — the wire contract
  * between this server and the consumers that render it (test-bot.git). It covers
@@ -86,6 +87,26 @@ export declare enum HelperVerificationOutcome {
     /** The test neither wrote nor imports a shared utils file. */
     NoUtilsFile = "no-utils-file"
 }
+/** Every blocking kind a report-time reuse verification can find. Shared-helper
+ *  path: the `UtilsViolationKind`s, plus `malformed-allow-marker` for an allow
+ *  marker the grammar cannot read (which fails a verify on its own). Page-object
+ *  path: a POM member the spec calls that its source does not define, a spec that
+ *  does not parse, a spec whose Skyramp runtime imports were stripped, and a spec
+ *  with no page-object reuse whose selectors match detected page objects and carry
+ *  no `// kept inline:` decline. A union, so a misspelled kind is a compile error. */
+export type ReuseVerificationFailureKind = UtilsViolationKind | "malformed-allow-marker" | "pom-member-missing" | "parse-error" | "skyramp-infra-missing" | "zero-reuse";
+/** One blocking kind a failed reuse verification found in the delivered files,
+ *  aggregated: the verifier reports a finding per helper, import line or POM call,
+ *  and the row states the kind once with its count. `detail` is the findings' own
+ *  detail text (joined with `; ` when there are several) — for an `assertion-loss`
+ *  that is the sentence `verify.ts` builds with the counts behind the verdict
+ *  (baseline, delivered, in the test, in the helpers); it is NOT the gate's
+ *  PASSED/FAILED prose. */
+export interface ReuseVerificationFailure {
+    kind: ReuseVerificationFailureKind;
+    count: number;
+    detail: string;
+}
 /** A pre-existing Skyramp-generated test the reuse pass edited to import from the
  *  shared utils file. `execution` is the recorded post-edit run; a retrofit without
  *  one cannot be reported (skyramp_submit_report refuses). */
@@ -99,13 +120,24 @@ export interface RetrofitOutcome {
  *  Absent altogether when no utils file exists for the test (the same omission rule
  *  as the POM fields at zero candidates: a zero says nothing "no file" does not). */
 export interface HelperReuseOutcome {
-    /** BASENAME of the shared utils file the test imports from or this run wrote —
-     *  found by its header, never by a conventional name (the reuse prompt allows "a
-     *  new file with a different name" once the conventional one is large). Several
-     *  files are joined with `, `. */
+    /** REPOSITORY-RELATIVE PATH (posix) of the shared utils file the test imports
+     *  from or this run wrote — found by its header, never by a conventional name (the
+     *  reuse prompt allows "a new file with a different name" once the conventional
+     *  one is large). A path, not a basename, so two same-named modules in one
+     *  delivery (an API and a UI `skyrampUtils.ts`) stay distinguishable; never
+     *  absolute, which would leak the runner's temp directory. Unique within ONE
+     *  repository only: in a multi-repo report the same path can occur in two
+     *  checkouts, so a renderer must key on the row's `repository` plus this field.
+     *  Several files are joined with `, `. */
     utilsFile: string;
     /** Helpers the delivered test imports from that file that the file defines. */
     helpersImported?: number;
+    /** Those helpers by name, sorted; empty when nothing is imported. Always equals
+     *  `helpersImported` in length — both come from the same set.
+     *
+     *  TODO: remove `helpersImported` once the testbot renderer reads this field. The
+     *  two carry one fact; the count stays only because testbot#349 reads it today. */
+    helperNames: string[];
     /** Inline request calls in OTHER Skyramp-generated tests beside this one that a
      *  helper in `utilsFile` already wraps — reuse that was available and not taken.
      *  Omitted at zero. Informational, like {@link ReuseOutcome.missedReuse}. */
@@ -114,13 +146,35 @@ export interface HelperReuseOutcome {
      *  per method+path, status-code-only assertions, method+resource names — with
      *  documented declines (`reuse-verify: allow …`) counted as holding. */
     verification?: HelperVerificationOutcome;
+    /** Why `verification` is `failed`: one entry per blocking kind found, with how
+     *  many findings of it and the finding's own detail text — see
+     *  {@link ReuseVerificationFailure}. Present only on a `failed` row. A bare
+     *  `failed` cannot be acted on and its cause cannot be reconstructed from the
+     *  artifacts; this is the statement of what failed.
+     *
+     *  How it reaches a report: skyramp_submit_report refuses a report carrying a
+     *  blocking verdict and names these entries to the agent, up to a bound per file
+     *  (`REUSE_SUBMIT_MAX_REFUSALS`); past the bound the report is accepted and the
+     *  row ships with this field set, so the fault is disclosed rather than delivered
+     *  in silence — or not delivered at all. */
+    verificationFailures?: ReuseVerificationFailure[];
     /** Pre-existing generated tests this spec's reuse pass rewired onto the utils
      *  file, each with its recorded execution. Omitted when none. */
     retrofits?: RetrofitOutcome[];
-    /** Whether the delivered test plus the helpers it imports still hold every
-     *  assertion (and page-error guard) present when modularization was handed out.
-     *  Present only when that baseline exists. */
+    /** Whether the delivered test plus the helpers it imports and calls still hold at
+     *  least as many assertions as when modularization was handed out. A measured
+     *  count: a documented decline (`reuse-verify: allow assertion-loss …`) clears
+     *  `verification` and leaves this `false`. Present only when that baseline exists.
+     *  Says nothing about the page-error guard — that is
+     *  {@link pageErrorGuardPreserved}; folding the two into one flag once sent an
+     *  investigation after a lost assertion when a guard had been deleted. */
     assertionsPreserved?: boolean;
+    /** Whether the `page.on('pageerror', …)` guard present at the modularization
+     *  hand-out is still registered, in the test or in a shared helper it imports and
+     *  calls. `true` when the hand-out had no guard to lose. Present whenever the
+     *  baseline exists, absent otherwise — like every optional member here, absent
+     *  means "not measured", never "false". */
+    pageErrorGuardPreserved?: boolean;
 }
 /**
  * What lands in a report's `reuse` field for a generated test. Every member is
@@ -161,7 +215,19 @@ export interface ReuseOutcome {
     /** The subset of those raw locators that a catalogued POM member covers.
      *  Informational; see {@link ReuseMissedEntry}. */
     missedReuse?: ReuseMissedEntry[];
+    /** Copies of operations written in two or more Skyramp-generated tests beside (and
+     *  including) this one that NO shared helper wraps — extraction that was due and
+     *  not performed, the counterpart of `helpers.siblingInlineCallSites` (use not
+     *  taken). Top level, not on the helpers row: it describes the spec's directory,
+     *  not the module, and is most telling when no module exists at all — the case
+     *  where `helpers` is rightly absent. Omitted at zero. Informational. */
+    unextractedDuplicateSites?: number;
     verification?: ReuseVerificationOutcome;
+    /** Why `verification` is `failed` on the page-object path, on the same terms as
+     *  {@link HelperReuseOutcome.verificationFailures}: present only when the
+     *  delivered spec fails the live POM check at report time and the report was
+     *  accepted past the refusal bound. */
+    verificationFailures?: ReuseVerificationFailure[];
     skipped?: ReuseSkippedEntry[];
     /** Shared-helper (SkyrampUtils) reuse. See {@link HelperReuseOutcome}. */
     helpers?: HelperReuseOutcome;

package/build/types/TestAnalysis.d.ts

@@ -53,6 +53,12 @@ export interface MaintenanceActionCore {
      *  the rewritten PNG — a listed baseline must never exempt the selector edit the same
      *  verdict claimed (SKYR-3883 stays in force). */
     rebaselineOnly?: boolean;
+    /** True when the action is a RECOMMENDATION the developer applies by hand and this run
+     *  touched nothing: a REGENERATE or DELETE on an external (user-authored) test. Part of
+     *  the core shape because the action stays REAL rather than flattening to VERIFY, so
+     *  without this a downstream stage cannot tell a regeneration that rewrote a file from
+     *  one that only advised it — and maintenance coverage would credit the advice. */
+    reportOnly?: boolean;
 }
 /** Normalized internal recommendation built from LLM-supplied args.recommendations. */
 export interface DriftRecommendation extends MaintenanceActionCore {

package/build/types/TestbotReport.d.ts

@@ -72,6 +72,10 @@ export interface TestbotReport {
         editedFileName?: string;
         description: string;
         action: DriftAction;
+        /** `owner/repo` the maintained test lives in. Always set, unlike the other
+         *  sections: `fileName` is a basename, so in a multi-repo run this is the
+         *  only thing separating two same-named test files (SKYR-4233). */
+        repository: string;
         beforeStatus: TestExecutionStatus;
         beforeDetails: string;
         afterStatus: TestExecutionStatus;
@@ -154,8 +158,18 @@ export interface TestbotReport {
         text: string;
         source: string;
         /** `plannedTestId` of each delivered test citing this change. Empty where the
-         *  agent answered instead of planning one. */
+         *  agent answered instead of planning one, and where the change is covered by
+         *  an existing test the run maintained — `maintainedBy` carries those. */
         testedBy: string[];
+        /** Path of each existing test the run edited that cites this change: a
+         *  `maintains` entry from the plan, kept only where a `testMaintenance` row
+         *  names the same file. Checked at name level, which is the level v2 allows
+         *  for a file, so this says the run reported editing it and not that the edit
+         *  is known to be right. A claim no maintenance row corroborates is left out
+         *  and draws `deliveredMatchesPlan:maintains:` instead. A change covered this
+         *  way has no planned test and needs no answer, so without this field the
+         *  change table would read as untested. */
+        maintainedBy?: string[];
         /** The agent's answer to `coverage:change:<id>`, where it gave one. */
         answer?: string;
     }[];

package/build/utils/AnalysisStateManager.d.ts

@@ -133,7 +133,7 @@ export interface UiAnalysisContext {
  *  PATH. Recorded in-process where staging finds the edit; skyramp_submit_report
  *  refuses a report that leaves one undisclosed or unexecuted. */
 export interface ReuseRetrofit {
-    /** BASENAME(s) of the utils file(s) it now imports from. */
+    /** Repository-relative path(s) of the utils file(s) it now imports from. */
     utilsFile: string;
     /** Absolute path of the generated test whose reuse pass caused the edit. */
     testFile: string;
@@ -184,6 +184,12 @@ export interface UnifiedAnalysisState {
     reuseHandOffs?: Record<string, ReuseHandOff>;
     /** See {@link ReuseRetrofit}. Never supplied by the LLM. */
     reuseRetrofits?: Record<string, ReuseRetrofit>;
+    /** How many times skyramp_submit_report has refused the report over a blocking
+     *  reuse verdict on each spec, keyed by the spec's ABSOLUTE PATH (the verdict's
+     *  `file`). The refusal is bounded (`REUSE_SUBMIT_MAX_REFUSALS`): past the bound
+     *  the report is accepted with the fault recorded in the row. Written by
+     *  skyramp_submit_report only; never supplied by the LLM. */
+    reuseRefusals?: Record<string, number>;
     /**
      * SKYR-4156. Recorded video per executed browser test, keyed by test-file
      * BASENAME (the same key `reuseOutcomes` uses, so matching needs no path

package/build/utils/AnalysisStateManager.js

@@ -295,7 +295,11 @@ async function writeFileAtomically(target, contents) {
         throw error;
     }
 }
-const ROOT_FIELDS_OWNED_ELSEWHERE = ["plan", "registrationCount", "reportObjections"];
+const ROOT_FIELDS_OWNED_ELSEWHERE = [
+    "plan",
+    "registrationCount",
+    "reportObjections",
+];
 function carryForwardRootFields(data, existing) {
     if (!existing)
         return {};

package/build/utils/assertion-verify/api-shared-lints.js

@@ -1,6 +1,6 @@
 import { escapeRegExp } from "../regex.js";
 import { strippedSources } from "./strip-dispatch.js";
-import { balancedCloseIndex, identifierRe, inScope, interpolationRe, lineOfOffset, } from "./lint-types.js";
+import { balancedCloseIndex, identifierRe, inScope, interpolationRe, lineOfOffset, testBlockIndex, testStartOffsets, } from "./lint-types.js";
 /**
  * Deterministic checks shared by integration and provider-contract tests — the
  * machine-checkable slice of the D5 rubric's echo_computed and array_depth
@@ -12,6 +12,12 @@ const RESPONSE_BINDING_RES = {
     python: /^[ \t]*([A-Za-z_]\w*)\s*=\s*[\w.]*send_request\s*\(/gm,
 };
 const STATUS_USE_RE = /^\s*\.\s*(?:statusCode|status_code|status)\b/;
+/** The SDK body-read call for a binding, spelled for the language. */
+function helperCall(language, varName) {
+    return language === "python"
+        ? `skyramp.get_response_value(${varName}, "json.path")`
+        : `getValue(${varName}, "json.path")`;
+}
 /** All send_request/sendRequest bindings in the stripped source. */
 function responseBindings(stripped, language) {
     const bindings = [];
@@ -148,11 +154,17 @@ function lintStatusOnlyResponses(stripped, commentless, language, bindings) {
             message: statusUses > 0
                 ? severity === "hard"
                     ? `Error response \`${varName}\` is only checked for its status code — the error body (code/message/detail) must be asserted.`
-                    : `Response \`${varName}\` is only checked for its status code — if this endpoint returns a body, assert its fields (skip only for genuinely empty-body responses).`
+                    : `Response \`${varName}\` is only checked for its status code.`
                 : `Response \`${varName}\` is captured but never asserted.`,
-            remediation: language === "python"
-                ? `Assert body fields via \`skyramp.get_response_value(${varName}, "json.path")\` after the status assertion.`
-                : `Assert body fields via \`getValue(${varName}, "json.path")\` after the status assertion.`,
+            // The advisory case is phrased as a question, not an instruction. A
+            // response no behaviour in the file depends on is CORRECT with its
+            // status code and nothing more (SKYR-4310) — telling the agent to
+            // assert the body regardless is how a 136-assertion test gets written
+            // to prove a default page size. The hard case is unchanged: an error
+            // body carries the evidence, so it is never optional.
+            remediation: severity === "warn"
+                ? `If a behaviour this file tests depends on this response's body, assert the fields it depends on via \`${helperCall(language, varName)}\`. If no behaviour depends on it, the status code alone is the right answer — leave it.`
+                : `Assert the error body's fields via \`${helperCall(language, varName)}\` after the status assertion.`,
         });
     }
     return findings;
@@ -303,23 +315,6 @@ const ERROR_ABSENT_RE = /(?:getValue|getResponseValue|get_response_value)\s*\(\s
 //   expect(getValue(r, "items").length).toBeGreaterThan(0)
 //   assert len(skyramp.get_response_value(r, "items")) > 0
 const NON_EMPTY_RE = /(?:getValue|getResponseValue)\s*\(\s*([\w$.]+)\s*,\s*['"][^'"]+['"]\s*\)\s*\.\s*length\s*(?:,\s*['"][^'"]*['"]\s*)?\)\s*\.\s*toBeGreaterThan\s*\(\s*0\s*\)|len\s*\(\s*[\w.]*get_response_value\s*\(\s*([\w$.]+)\s*,\s*['"][^'"]+['"]\s*\)\s*\)\s*>\s*0/g;
-// Starts of test bodies: JS/TS `it(` / `test(` (with `.only`/`.skip`/`.each`
-// modifiers) and Python `def test_`. Two assertions belong to the same test
-// only when no such start lies between them — a `const r = …` re-bound in the
-// next `it` block is a different response, not the same one.
-const TEST_START_RE = /(?<![\w$.])(?:it|test)(?:\s*\.\s*\w+)*\s*\(|^[ \t]*(?:async\s+)?def\s+test_/gm;
-function testBlockIndex(starts, offset) {
-    let lo = 0;
-    let hi = starts.length;
-    while (lo < hi) {
-        const mid = (lo + hi) >> 1;
-        if (starts[mid] <= offset)
-            lo = mid + 1;
-        else
-            hi = mid;
-    }
-    return lo;
-}
 /** A success shape asserted together with the absence of an error field on the
  *  same response binding, inside the same test body. Both are legitimate on a
  *  real success body, so this is advisory only: the pattern is exactly what a
@@ -328,11 +323,8 @@ function testBlockIndex(starts, offset) {
  *  validation error carried in `error`). The verifier cannot see the response,
  *  so it asks the author to confirm the classification rather than blocking. */
 function lintSuccessShapeWithErrorAbsent(commentless) {
-    const starts = [];
-    TEST_START_RE.lastIndex = 0;
+    const starts = testStartOffsets(commentless);
     let m;
-    while ((m = TEST_START_RE.exec(commentless)) !== null)
-        starts.push(m.index);
     // key: `<testBlock>:<binding>` → { offset, field }
     const errorAbsent = new Map();
     ERROR_ABSENT_RE.lastIndex = 0;
@@ -358,7 +350,39 @@ function lintSuccessShapeWithErrorAbsent(commentless) {
             severity: "warn",
             line: lineOfOffset(commentless, absent.offset),
             message: `\`${varName}\` is asserted to have no \`${absent.field}\` field and a non-empty collection — a success shape.`,
-            remediation: "Confirm the recorded response for this exact request is a success body. If the endpoint answers this request with an error or no-match body (a validation 4xx, or a 2xx carrying `{\"error\": ...}`), assert that body's exact fields instead and report the gap in issuesFound. Keep the assertion as written only when the plan declared this test `expected.outcome: fail` (a bug_caught or requirement_conflict test that deliberately asserts the intended behaviour).",
+            remediation: 'Confirm the recorded response for this exact request is a success body. If the endpoint answers this request with an error or no-match body (a validation 4xx, or a 2xx carrying `{"error": ...}`), assert that body\'s exact fields instead and report the gap in issuesFound. Keep the assertion as written only when the plan declared this test `expected.outcome: fail` (a bug_caught or requirement_conflict test that deliberately asserts the intended behaviour).',
+        });
+    }
+    return findings;
+}
+// The existence idiom on an SDK-helper read: `not.toBeNull()` / `is not None`.
+// Weight 1 in the strength model, and the one shape MAINTENANCE_SCOPE_NOTE
+// names by example.
+const WEAK_EXISTENCE_RE = /(?:getValue|getResponseValue)\s*\(\s*[\w$.]+\s*,\s*['"]([^'"]+)['"][^)]*\)\s*(?:,\s*['"][^'"]*['"]\s*)?\)\s*\.\s*not\s*\.\s*toBeNull\s*\(|get_response_value\s*\(\s*[\w.]+\s*,\s*['"]([^'"]+)['"]\s*\)\s*is\s+not\s+None\b/g;
+/** Maintenance only: an existence-tier assertion left standing inside a test
+ *  function the agent TOUCHED. `MAINTENANCE_SCOPE_NOTE` holds such a function
+ *  to the same standard as a new test — "an existing `is not None` on a field
+ *  the diff gives a knowable value becomes that value".
+ *
+ *  Warn, never hard: the verifier has no diff, so it cannot tell which fields
+ *  the change made knowable. It reports the candidates and lets the agent
+ *  decide, which is the honest split — the alternative is blocking a spec on a
+ *  field whose value genuinely still varies. */
+function lintWeakAssertionInTouchedTest(commentless, opts) {
+    const findings = [];
+    WEAK_EXISTENCE_RE.lastIndex = 0;
+    let m;
+    while ((m = WEAK_EXISTENCE_RE.exec(commentless)) !== null) {
+        const line = lineOfOffset(commentless, m.index);
+        if (!inScope(line, opts))
+            continue;
+        const field = m[1] ?? m[2];
+        findings.push({
+            rule: "weak-assertion-in-touched-test",
+            severity: "warn",
+            line,
+            message: `\`${field}\` is asserted only to exist, in a test function this change touches.`,
+            remediation: `A test function you touch is held to the same standard as a new one. If the diff gives \`${field}\` a knowable value, assert that value exactly. Leave the existence check only when the value genuinely varies across runs.`,
         });
     }
     return findings;
@@ -371,15 +395,28 @@ export function lintApiShared(raw, language, opts) {
     const maintenance = opts?.scopeLines !== undefined;
     const { commentless, stripped } = strippedSources(raw, language);
     const findings = [];
+    // Bindings discovered once, shared by both binding-scoped lints.
+    const bindings = responseBindings(stripped, language);
+    findings.push(...lintStatusOnlyResponses(stripped, commentless, language, bindings));
+    findings.push(...lintSdkHelperBypass(stripped, bindings, language));
+    findings.push(...lintShapeOnlyChecks(commentless));
+    findings.push(...lintSuccessShapeWithErrorAbsent(commentless));
     if (!maintenance) {
-        // Bindings discovered once, shared by both binding-scoped lints.
-        const bindings = responseBindings(stripped, language);
-        findings.push(...lintStatusOnlyResponses(stripped, commentless, language, bindings));
-        findings.push(...lintSdkHelperBypass(stripped, bindings, language));
-        findings.push(...lintShapeOnlyChecks(commentless));
+        // Array-depth findings anchor to a path, not a line, so there is nothing
+        // to scope them by — running them in maintenance would report untouched
+        // customer arrays with no way to filter them out.
         findings.push(...lintArrayDepth(commentless));
-        findings.push(...lintSuccessShapeWithErrorAbsent(commentless));
+    }
+    else {
+        findings.push(...lintWeakAssertionInTouchedTest(commentless, opts));
     }
     findings.push(...lintPermissiveStatusMatchers(commentless, opts));
-    return findings;
+    // Maintenance used to skip every lint above except the status-matcher one,
+    // because line-scoping to the ADDED lines would have flagged pre-existing
+    // customer code. The scope is now the touched test FUNCTION (SKYR-4310), so
+    // these can run: each finding is kept only when it lands inside a function
+    // the agent edited. A finding with no line cannot be placed and is dropped.
+    return maintenance
+        ? findings.filter((f) => f.line !== undefined && inScope(f.line, opts))
+        : findings;
 }

package/build/utils/assertion-verify/format.js

@@ -51,8 +51,8 @@ export function formatAssertionVerifyReport(r, testFile) {
     if (r.strengthGateFailed) {
         lines.push("- Assertion strength did not increase over the generated baseline: no assertion was added and no weak matcher was strengthened (e.g. `toBeVisible` → `toHaveText`). Apply the enhancement rules. A documented decline (`assertions complete` comment) is accepted only AFTER at least one assertion was added or replaced — a marker-only edit does not pass this gate.");
     }
-    if (r.weakAdditionsOnly) {
-        lines.push("- Every assertion added since the baseline is existence/visibility-tier (`toBeVisible`, `not.toBeNull`, `is not None`, ranges). When the exact text/value/count is knowable from the trace, source, or request, assert it exactly (`toHaveText`/`toHaveCount`/`toBe`/`==`). If only existence is genuinely knowable, document the decline:", `    ${token} assertions complete: ${spec} — <reason exact values are not knowable>`);
+    if (r.weakAdditionsDominant) {
+        lines.push(`- The assertions added since the baseline are mostly existence/visibility-tier (\`toBeVisible\`, \`not.toBeNull\`, \`is not None\`, ranges)${r.meanAddedWeight !== undefined ? ` — mean strength ${r.meanAddedWeight.toFixed(1)} against a bar of 2.0` : ""}. When the exact text/value/count is knowable from the trace, source, or request, assert it exactly (\`toHaveText\`/\`toHaveCount\`/\`toBe\`/\`==\`). Adding MORE weak assertions lowers this figure — the fix is to strengthen the ones the behaviour under test depends on, and to drop the ones it does not. If only existence is genuinely knowable, document the decline:`, `    ${token} assertions complete: ${spec} — <reason exact values are not knowable>`);
     }
     lines.push(...warningsBlock(r.warnings, finding));
     lines.push("Re-run this verification (verify: true) after every fix pass — skyramp_execute_test runs the same checks automatically and will not execute this test until they pass.");

package/build/utils/assertion-verify/helper-imports.d.ts

@@ -4,3 +4,10 @@
  * uncalled helper is skipped, so its subjects don't excuse anything.
  */
 export declare function importedHelperSubjects(testFile: string, content: string): Promise<Set<string>>;
+/**
+ * The same subjects with their CAPACITY — how many removals each may excuse:
+ * one per call site of the helper function that asserts it (an assertion the
+ * parser cannot place in a function gets one per call through the import).
+ * The removal gate consumes this budget per removed baseline subject.
+ */
+export declare function importedHelperSubjectCapacities(testFile: string, content: string): Promise<Map<string, number>>;