@skyramp/mcp 0.4.1 → 0.4.2-rc.1

package/build/prompts/enhance-assertions/sharedAssertionRules.js

@@ -1,284 +0,0 @@
-import { getPersonaPrefix } from "../personas.js";
-export const MAINTENANCE_SCOPE_NOTE = "Apply only to new test functions you are adding and existing test functions affected by changes in the diff. Do NOT modify test functions unrelated to the diff. A test function you do touch is held to the same standard as a new one: the behaviour the diff changed must be asserted by its exact value there too, so an existing `is not None` on a field the diff gives a knowable value becomes that value.";
-export function maintenanceTaskSuffix(enhanceType) {
-    return enhanceType === "maintenance" ? ` ${MAINTENANCE_SCOPE_NOTE}` : "";
-}
-const SHARED_RULES = [
-    {
-        title: "Assert the behaviour under test",
-        description: "Every test needs at least one assertion that fails when the behaviour it claims is broken. This is the rule the others support; a test that satisfies every rule below and still does not distinguish the behaviour working from the behaviour broken has not been enhanced.",
-        subPoints: [
-            "Name the behaviour, then ask what value in the response changes when it breaks. Assert that value exactly.",
-            'When the test claims a state change ("Updates X", "Increments Y", "rejects Z"), the assertion must prove the change, not merely that the call succeeded.',
-            "When the PR changed the behaviour, the expected value is the one the diff, the PR description, or the referenced spec establishes — even when the running service still returns the old value. The test is expected to fail until the code is fixed.",
-        ],
-        examples: [
-            {
-                language: "javascript",
-                code: `// "PATCH /orders applies the coupon discount" — the discount is the behaviour.
-expect(getResponseValue(patchResponse, "discount_amount"), 'discount applied').toBe(20);
-expect(getResponseValue(patchResponse, "total_amount"), 'total after discount').toBe(80);`,
-            },
-        ],
-    },
-    {
-        title: "Echo-back the request fields",
-        description: "For every field returned unchanged from the request body, assert the exact sent value.",
-        subPoints: [
-            "`is not None` / `not.toBeNull()` is only acceptable when the value is genuinely unknown — for server-generated timestamps or opaque IDs. This rule does not apply to computed fields.",
-            "When a response field's value equals the value sent in the request body, path, or query, assert that exact value rather than a null-check — the sent value is known and reproducible.",
-            "Assert the exact value of a response-only field when the request this test sends determines it (`filename_download`, `content_type`, `size`, an enum status after creation). A value the app generates gets a format check when the test case depends on that value; leave the rest unasserted. When the behaviour is that a resource was created with the fields sent, the id alone does not prove it — assert those fields.",
-            "Range matchers like `toBeGreaterThanOrEqual(0)` and type-only checks like `typeof X === 'number'` are not acceptable for fields whose exact values are known.",
-            "Assert the exact status code from the recorded trace or `expected_response_body` — for example, `201` for resource-creation endpoints. Action-style endpoints with verb path segments like `/run`, `/trigger`, `/execute`, `/deploy`, `/submit`, `/start`, `/stop`, or `/cancel` often use `200`, but assert the recorded or expected code. Permissive status matchers are never acceptable.",
-        ],
-        examples: [
-            {
-                language: "javascript",
-                code: `expect(getValue(response, "data.filename_download")).toBe("invoice.pdf");
-expect(getValue(response, "data.type")).toBe("application/pdf");
-expect(response.statusCode).toBe(201);`,
-            },
-            {
-                language: "javascript",
-                code: `expect(getResponseValue(productsPostResponse, "name"), 'name').toBe("Skyramp Tester");`,
-            },
-        ],
-    },
-    {
-        title: "Error path (HTTP 4xx/5xx, or a 2xx carrying only an error body)",
-        description: "For every error response that includes a body, assert every error body field with its exact value — including `error.code`, `error.message`, `detail`, `errors[0].message`, and `errors[0].extensions.code`. An error response is any 4xx/5xx with a body, and any 2xx whose body is an error object (`error`, `message`, `errors[]`) with no resource payload.",
-        subPoints: [
-            "Also apply the array-validation rule to any errors array.",
-            "Asserting only the status code is never sufficient when a body is present.",
-            "For no-body responses such as a successful DELETE (204): assert the status code only.",
-            'For a 2xx error body, assert the exact status code, the error field\'s exact value, and that the resource fields carry no value (`toBeNull()` / `is None` — the SDK helper reads a missing path and an explicit null the same way, so this asserts "no payload", not "key absent"; use `checkSchema` when the two must be told apart). Never assert the success shape (a non-empty collection, `error` absent) against a response the recorded trace or `expected_response_body` shows returning an error or no-match body — classify the response by what this request returns, not by the outcome the test was meant to check for. The one exception is a test the plan declared `expected.outcome: fail` (typically a `bug_caught` or `requirement_conflict` candidate; the category is only the fallback when nothing was declared): it asserts the intended behaviour established by the diff, the PR statement, or the code\'s evident intent — keep that assertion and let the test fail.',
-        ],
-        examples: [
-            {
-                language: "javascript",
-                code: `expect(response.statusCode).toBe(404);
-expect(getValue(response, "errors.0.message")).toBe("Item not found");
-expect(getValue(response, "errors.0.extensions.code")).toBe("RECORD_NOT_FOUND");
-expect(getValue(response, "errors.1")).toBeNull();`,
-            },
-            {
-                language: "javascript",
-                code: `// Recorded response is a 200 carrying an error object and no payload
-expect(searchPostResponse.statusCode, 'status code').toBe(200);
-expect(getResponseValue(searchPostResponse, "error"), 'error').toBe("No items matched the criteria.");
-expect(getResponseValue(searchPostResponse, "results"), 'results carries no value').toBeNull();`,
-            },
-            {
-                language: "python",
-                code: `# Recorded response: 400 {"error": "level must be one of Intern, Junior, Senior"}
-assert record_post_response.status_code == 400
-assert skyramp.get_response_value(record_post_response, "error") == "level must be one of Intern, Junior, Senior"
-assert skyramp.get_response_value(record_post_response, "insertedId") is None`,
-            },
-        ],
-    },
-    {
-        title: "Specific known values",
-        description: "For enum or status fields where only one outcome is valid for this flow, assert the exact expected value.",
-        subPoints: [
-            "When the OpenAPI schema defines allowed values, assert the schema-defined value.",
-            "Also assert cross-field invariants when one field encodes the count or summary of another (e.g. `total_count == results.length`).",
-        ],
-        examples: [
-            {
-                language: "javascript",
-                code: `expect(getResponseValue(ordersPostResponse, "status"), 'status').toBe("pending");`,
-            },
-        ],
-    },
-    {
-        title: "Array / Items validation",
-        description: "Only assert indices that exist in the recorded response — never infer array length from the request or scenario name.",
-        subPoints: [
-            "When the response is an empty array: assert the length is 0 and that the first index is absent. Never assert a field on index 0 of an empty array.",
-            "When the response is a non-empty array: assert the exact length, key fields on each item, and that the index after the last item is absent.",
-            "Shape-only checks such as `Array.isArray` or `typeof` are not sufficient when the response contains actual values.",
-            "If the response is sorted or ordered: assert the ordering direction across the first two items.",
-            "When the response is an empty or minimal body (an empty object, empty array, null, or only a few keys): assert the empty or minimal shape and the absence of error fields — do not stop at the status code. A minimal body that is itself an error object falls under the Error path rule instead: assert its error field exactly.",
-            "When the request includes pagination or filter parameters, assert the response reflects them.",
-        ],
-        examples: [
-            {
-                language: "javascript",
-                code: `expect(getResponseValue(patchResponse, "items.0.product_id")).toBe(getResponseValue(productPostResponse, "id"));
-expect(getResponseValue(patchResponse, "items.0.quantity")).toBe(2);
-expect(getResponseValue(patchResponse, "items.1.product_id")).toBeNull();
-expect(getValue(response, "data").length).toBeLessThanOrEqual(10);  // request sent limit=10`,
-            },
-            {
-                language: "javascript",
-                code: `expect(getValue(response, "results").length).toBe(2);
-expect(getValue(response, "results.0.id")).toBe("prod_001");
-expect(getValue(response, "results.2")).toBeNull();`,
-            },
-            {
-                language: "javascript",
-                code: `expect(getValue(response, "data").length).toBe(0);
-expect(getValue(response, "data.0")).toBeNull();`,
-            },
-        ],
-    },
-    {
-        title: "Fields whose value varies across runs",
-        description: "For a field whose exact value varies across runs — a UUID, an auto-incremented ID, an ISO timestamp, an IP address, an email, a URL, or a number with no knowable exact value — assert its format or its range instead of its value, and only when the behaviour under test depends on that field. A generated id the test chains onward needs a format check; the same id on a response nothing reads again needs no assertion at all.",
-        subPoints: [
-            "UUID matches `/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i`.",
-            "Auto-incremented ID is greater than 0.",
-            "ISO timestamp matches `/^\\d{4}-\\d{2}-\\d{2}T/`.",
-            "IP address matches IPv4 or IPv6 format.",
-            "Email contains `@` and a domain.",
-            "URL starts with `http://` or `https://`.",
-            "Use `not.toBeNull()` / `is not None` only for truly opaque random tokens where no format is recognizable.",
-            "Use format info from the OpenAPI schema (`format: uuid`, `format: date-time`) to identify these fields.",
-            "A numeric field with no knowable exact value takes a range from the field name, the domain, or the OpenAPI `minimum` / `maximum` — a range is the weakest assertion in this rule set, so use it only where no exact value exists and the behaviour depends on the field.",
-        ],
-        examples: [
-            {
-                language: "javascript",
-                code: `expect(getResponseValue(productsPostResponse, "id")).toMatch(/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i);
-expect(getResponseValue(productsPostResponse, "created_at")).toMatch(/^\\d{4}-\\d{2}-\\d{2}T/);`,
-            },
-        ],
-    },
-    {
-        title: "Use exact recorded JSON paths",
-        description: 'Read every field at the path the recorded body actually uses. A wrapper prefix the response does not have makes the assertion read null and the test fail for a reason that is not the behaviour — if the body is flat (`{"id": "acc_...", "tax_exempt": true}`), the path is `"tax_exempt"`, never `"account.tax_exempt"`.',
-        subPoints: [
-            "Only use dot notation when the recorded response genuinely nests the field under that key.",
-        ],
-        examples: [
-            {
-                language: "javascript",
-                code: `expect(getResponseValue(accountResponse, "tax_exempt")).toBe(true);`,
-            },
-        ],
-    },
-    {
-        title: "Computed response fields, derived using dynamic formulas",
-        description: "When the response contains a field whose value is derived from a calculation, assert the result using a formula built from prior response values and request inputs, not a hardcoded literal.",
-        subPoints: [
-            "Use a dynamic formula when the formula is visible in source.",
-            "Fall back to the exact pre-computed value from `expected_response_body` only when no formula is knowable — all inputs must come from the inline request body or the response.",
-        ],
-        examples: [
-            {
-                language: "javascript",
-                code: `expect(getResponseValue(patchResponse, "discount_amount")).toBe(getResponseValue(patchResponse, "total_amount") * (getResponseValue(patchResponse, "discount_value") / 100));`,
-            },
-            {
-                language: "javascript",
-                code: `expect(getResponseValue(patchResponse, "total_amount")).toBe(getResponseValue(productPostResponse, "price") * quantitySent);`,
-            },
-        ],
-    },
-    {
-        title: "Assert a nullable field is present, not merely null",
-        description: "Reading a field's value cannot tell a null field from a missing one — `get_response_value` / `getValue` return the same result for both, so `is None` does not prove the field exists. Use a schema check with an example body instead.",
-        subPoints: [
-            "An example carrying `null` for the field asserts presence and nullness together, and fails when the field is absent.",
-            "An example carrying a concrete value only asserts that value's type, so a nullable field checked against a string example fails once the real value is null.",
-            "`check_schema` / `checkSchema` takes the RESPONSE OBJECT, not a parsed body. The `@skyramp/skyramp` type declaration says otherwise and is wrong — passing a plain object makes every check silently return false (SKYR-4189).",
-        ],
-        examples: [
-            {
-                language: "python",
-                code: `assert skyramp.check_schema(order_response, '{"cancelled_at": null}')`,
-            },
-            {
-                language: "javascript",
-                code: `expect(checkSchema(orderResponse, '{"cancelled_at": null}')).toBe(true);`,
-            },
-        ],
-    },
-];
-export function renderRule(index, rule) {
-    const subPoints = rule.subPoints && rule.subPoints.length > 0
-        ? "\n" + rule.subPoints.map((p) => `- ${p}`).join("\n")
-        : "";
-    const examplesBlock = rule.examples.length > 0
-        ? "\n" +
-            rule.examples
-                .map((ex) => `<example language="${ex.language}">
-${ex.code}
-</example>`)
-                .join("\n")
-        : "";
-    return `${index}. ${rule.title}\n${rule.description}${subPoints}${examplesBlock}`;
-}
-function renderRules(rules) {
-    return rules.map((rule, i) => renderRule(i + 1, rule)).join("\n\n");
-}
-export function renderSharedAssertionRules() {
-    return renderRules(SHARED_RULES);
-}
-export function getAssertionsPrompt(specificRules, scope, testFile, enhanceType) {
-    const allRules = [...SHARED_RULES, ...specificRules];
-    const ruleChecklistKeys = allRules
-        .map((rule) => `    "${rule.title}": []`)
-        .join(",\n");
-    return `${getPersonaPrefix()}Your task is to enhance response body assertions in the given test file: \`${testFile}\`.${maintenanceTaskSuffix(enhanceType)}
-
-### What to assert
-Each test evaluates ONE behaviour — the one the recommendation it came from asked for. Assert that behaviour, and the values it depends on, exactly. Leave the rest of the response alone.
-
-A field belongs in the test when a wrong value in it would mean the behaviour is broken. A field does not belong when its value can change for reasons that have nothing to do with the behaviour — a generated id, a timestamp, an unrelated sibling field. Asserting those does not make the test stronger. It makes the test fail for reasons the test is not about, and it buries the one assertion a reader needs to understand what the test is for.
-
-So the rules below say how to assert a value, not how many values to assert. Apply a rule to the fields the behaviour depends on. \`[]\` is the correct answer for a rule whose fields this test does not depend on.
-
-If nothing in the response distinguishes the behaviour working from the behaviour broken, the test is exercising the wrong request or reading the wrong response. Say so; do not pad it with assertions on whatever else the body carries.
-
-### Pre-Edit Assertion Analysis
-Before editing the given file, you must output a \`<thinking>\` block. It states the behaviour each test evaluates, then works through the rules for the responses that behaviour depends on, so no rule that applies is overlooked. The JSON array should match the template below — every assertion rule title must appear as a key in the \`rule_checklist\`, with \`[]\` where the rule does not apply.
-1. For each test function in scope, name the behaviour it evaluates in one line, taken from the recommendation it came from. Generated test functions are usually named \`test_integration\` or \`testUi\`, which claim nothing — use the name only when it is specific enough to add something, and never treat a generic one as evidence the test has no single behaviour. Then scan the given test file and the expected responses for the code change tested.
-2. Classify each response first by its response status type and then assign the applicable assertion rules to the response.
-   1. Success with body (2xx with a response body): all assertion rules below may apply — echo-back of request fields, computed response fields, array / items validation, and chained values across steps.
-   2. Success with no body (200/202/204 with an empty body — e.g. logout/cancel/submit action endpoints): assert the status code only. Also apply chained-values rules if a follow-up step uses this response's ID.
-   3. Error response (4xx/5xx with a body, or any status whose body is an error object such as \`{"error": "..."}\` with no resource payload): assert every error body field with its exact value plus array / items validation on the \`errors[]\` array (exact length + per-item fields + next index null). Status code alone is never sufficient when a body is present — for example, also assert \`errors.0.extensions.code == 'INVALID_PAYLOAD'\` and that \`errors.1\` is null.
-   Classify by the response the recorded trace or \`expected_response_body\` shows this request returning. The one exception is a test the plan declared \`expected.outcome: fail\` (typically a \`bug_caught\` or \`requirement_conflict\` candidate; read the declaration first and fall back to the category only when none was made): there the expected response is the intended behaviour established by the diff, the PR statement, or the code's evident intent, and the test is expected to fail until the code is fixed.
-3. For each in-scope response, output one JSON object using the template below. The output is an array — one object per in-scope response.
-   - \`step\`: the HTTP method, path, and response variable name for this request (e.g. \`POST /products → products_POST_response\`).
-   - \`response_status\`: one of \`success\`, \`no_body\`, or \`error\` based on the classification in step 2.
-   - \`behaviour_under_test\`: the one-line behaviour from step 1 that this response is evidence for. When a response is evidence for no behaviour any test in scope claims, write \`none\` and add nothing for it.
-   - \`rule_checklist\`: an object that MUST contain every rule title below as a key. For each rule, the value is the assertion lines you will add for this response under that rule. \`[]\` means the rule does not apply here, which is a normal and expected answer: it is the right one whenever the rule's fields are not part of \`behaviour_under_test\`. Listing every key keeps a rule that DOES apply from being skipped; it is not a quota to fill.
-
-\`\`\`json
-[{
-  "step": "<METHOD> <path> → <responseVar>",
-  "response_status": "success | no_body | error",
-  "behaviour_under_test": "<the one-line behaviour this response is evidence for, or none>",
-  "rule_checklist": {
-${ruleChecklistKeys}
-  }
-}]
-\`\`\`
-
-### SDK Helpers
-Access response body fields via the SDK helper already imported in the generated file (never dict/attribute access on the response variable): Python \`skyramp.get_response_value(response, "json.path")\`; TypeScript / JavaScript \`getValue(response, "json.path")\` or \`getResponseValue(response, "json.path")\` from \`@skyramp/skyramp\`; Java \`getValue(response, "json.path")\`.
-
-### Assertion Rules with Examples
-${renderRules(allRules)}
-
-${scope}
-
-### What not to do
-- Do not access response fields via dict syntax (\`response["field"]\`) or attribute access (\`response.field\`) — always use the SDK helper.
-- Do not assert \`not.toBeNull()\` / \`is not None\` on a field whose exact value is in the request body or a prior response.
-- Do not assert an exact value you learned only from a request you sent yourself while writing the test. Take the value from the diff, from what the request determines, or from a response this test received earlier.
-- Do not assert a field only because the body carries it. If a wrong value there would not mean the behaviour under test is broken, leave it alone.
-- Do not leave a test whose assertions would all still pass with the behaviour under test broken.
-- Do not use permissive status matchers (\`.toMatch(/^2/)\`, \`.toBeGreaterThanOrEqual(200)\`, \`checkStatusCode(response, '20x')\`).
-- Do not use shape-only or type-only assertions as a substitute for exact value validation. Forbidden patterns: \`Array.isArray(...)\`, \`typeof X === '...'\`, \`X instanceof Array\`, \`Object.keys(X).length > 0\`. When a field's value comes from one of those sources, assert it exactly.
-- Do not use shape-only, containment-only, range-only, or weak-length as the sole assertion on a populated array.
-- Do not swap between \`getValue\` and \`getResponseValue\` — keep whichever SDK helper the file already imports.
-- Do not restructure, reformat, reorder, or modify existing code; do not add comments or docstrings.
-- Do not change function signatures or variable names. You may add an import when a new assertion or a fix needs a helper — from \`@skyramp/skyramp\` or from the test's own helper module.
-- Do not remove existing assertions.
-
-### Verification of Assertions
-After adding the assertion lines in the given test file, re-read each test and check two things: every rule that applies to the behaviour under test has been applied correctly, and the test now fails if that behaviour breaks. Fix anything missing or weakly applied before completing. Remove any assertion you added that the behaviour does not depend on.`;
-}

package/build/prompts/enhance-assertions/uiAssertionsPrompt.d.ts

@@ -1,2 +0,0 @@
-import { EnhanceType } from "./sharedAssertionRules.js";
-export declare function getUIAssertionsPrompt(testFile: string, enhanceType: EnhanceType): string;