@skyramp/mcp 0.4.2 → 0.4.3-rc.1

package/build/tools/code-refactor/pom-pass-state.js

@@ -0,0 +1,115 @@
+import * as path from "path";
+import { logger } from "../../utils/logger.js";
+import { isPomFirstTarget } from "../../utils/reuseRouting.js";
+import { ReuseVerificationOutcome } from "./reuse-outcome.js";
+import { freshRecord, owns, readHandOff, readReuseRecord, runStateWritable, updateReuseOutcome, } from "./reuse-record-store.js";
+/**
+ * The page-object pass as run state, for a target both reuse settings serve
+ * (isPomFirstTarget): whether the pass has finished for a spec, the mark that
+ * finishes it, the checkpoint that holds modularization until it has, and the
+ * merge of the two halves one such spec's report row carries.
+ */
+/** Whether a hand-off's chain starts with the page-object pass. Derived from what the
+ *  hand-off already stores, never recorded beside it: generation writes the hand-off
+ *  from exactly these three values, and maintenance arms none for such a target. */
+export function pomFirstHandOff(handOff) {
+    return isPomFirstTarget(handOff.language, handOff.testType);
+}
+/**
+ * With both reuse settings on (isPomFirstTarget), where this spec's page-object pass
+ * stands. `undefined` while it is open; `"finished"` once its verify pass PASSED;
+ * `"no-layer"` when discovery found no page-object layer to reuse. From then on the
+ * reuse tool serves the SkyrampUtils flow for the spec, and the page-object gates
+ * have already judged the spec while every step they did not substitute was still raw
+ * and inline — the state they were written for.
+ *
+ * A FAILED verdict keeps the pass open: the page-object report says to fix and
+ * re-verify, and `pendingReuseVerification` refuses the tools after it until that
+ * happens. A record owned by another spec, or no run state, reads as open; the caller
+ * then serves the page-object pass, which is what the spec gets without composition.
+ */
+export async function pomPassOutcome(testFile, explicitStateFile) {
+    try {
+        const record = await readReuseRecord(testFile, explicitStateFile);
+        if (!record?.pomPassFinished || !owns(record, testFile))
+            return undefined;
+        return record.verification === ReuseVerificationOutcome.SkippedNoPom
+            ? "no-layer"
+            : "finished";
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Mark the page-object pass finished for a spec (see `pomPassOutcome`). Written by
+ *  the reuse tool at the two points that finish it: a PASSED page-object verify, and
+ *  discovery that found no page-object layer. */
+export async function recordPomPassFinished(testFile, explicitStateFile) {
+    await updateReuseOutcome(testFile, (existing) => owns(existing, testFile)
+        ? { pomPassFinished: true }
+        : { ...freshRecord(), testFilePath: testFile, pomPassFinished: true }, explicitStateFile);
+}
+/**
+ * Does this spec owe its page-object pass before `skyramp_modularization`? Only a spec
+ * generation handed off with the page-object pass first. Modularizing first would move
+ * the raw steps the page-object pass maps into helpers it cannot see, and its gates
+ * would then judge a spec with nothing left inline. Fails open without a hand-off, on
+ * an unreadable or unwritable state file.
+ */
+export async function pendingPomPass(testFile, explicitStateFile) {
+    try {
+        const handOff = (await readHandOff(testFile, explicitStateFile))?.handOff;
+        if (!handOff || !pomFirstHandOff(handOff))
+            return undefined;
+        if ((await pomPassOutcome(testFile, explicitStateFile)) !== undefined)
+            return undefined;
+        if (!(await runStateWritable(explicitStateFile)))
+            return undefined;
+        return (`${path.basename(testFile)} takes the page-object pass BEFORE modularization. Call skyramp_reuse_code with ` +
+            `{ testFile: "${testFile}", language: "${handOff.language}", framework: "${handOff.framework}", testType: "${handOff.testType}" }, ` +
+            `follow its steps to a PASSED verification (or its "No reusable POM layer detected" answer), then call skyramp_modularization again.`);
+    }
+    catch (err) {
+        logger.warning("Could not check for a pending page-object pass — proceeding", {
+            testFile,
+            error: String(err),
+        });
+        return undefined;
+    }
+}
+/**
+ * One row, both halves. The outcome fields are disjoint by construction (the
+ * page-object fields sit at the top level, the shared-helper ones under `helpers` and
+ * `inHouse`). The two blocking verdicts become ONE, because the report refuses per
+ * spec and one `verify: true` call re-checks both halves (the reuse tool's combined
+ * verify). Declines are retired only where the half that owns them was measured: the
+ * page-object half measures a `kept inline` decline only when its zero-reuse gate
+ * walked the candidates, which it does not at non-zero reuse.
+ */
+export function combineRederivations(pom, helper, carriesKeptInline, 
+/** The call that re-checks both halves — the shared-helper verify call, which the
+ *  reuse tool routes to its combined verify for such a spec. */
+combinedVerifyCall) {
+    const outcome = pom.outcome || helper.outcome
+        ? { ...(pom.outcome ?? {}), ...(helper.outcome ?? {}) }
+        : undefined;
+    const verdicts = [pom.blocking, helper.blocking].filter((v) => v !== undefined);
+    const blocking = verdicts.length === 0
+        ? undefined
+        : {
+            file: verdicts[0].file,
+            failures: verdicts.flatMap((v) => v.failures),
+            detail: verdicts.map((v) => v.detail).join("\n\n"),
+            verifyCall: combinedVerifyCall ?? verdicts[0].verifyCall,
+        };
+    return {
+        outcome,
+        ...(blocking ? { blocking } : {}),
+        carriedConsumed: [
+            ...(pom.carriedConsumed ?? []),
+            ...(helper.carriedConsumed ?? []),
+        ],
+        carriedEvaluated: !!helper.carriedEvaluated &&
+            (!!pom.carriedEvaluated || !carriesKeptInline),
+    };
+}

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

@@ -6,8 +6,9 @@ import { type StagingResult } from "../../utils/utils-verify/index.js";
  * sibling-inline advisory). Staging carries the edit into the output commit, so the
  * report must disclose it — with an execution that ran the edited bytes.
  *
- * Whether an execution counts is answered by TIME, not by a stored hash: the
- * execution record already carries `executedAt`, and the file's mtime says when it
+ * Whether an execution counts is answered by TIME, not by a stored hash (the rule
+ * itself is `freshExecution`, shared with the changed-helper gate): the execution
+ * record already carries `executedAt`, and the file's mtime says when it
  * was last edited — an execution older than the last edit ran bytes that no longer
  * exist. That also covers a bare editor write with no tool call in between, which a
  * record-time hash cannot see. (Same identity pattern as VideoRecord's

package/build/tools/code-refactor/retrofit-state.js

@@ -6,14 +6,16 @@ import { stageUtilsArtifacts, } from "../../utils/utils-verify/index.js";
 import { importFormViolations, locateUtilsFiles, retrofitMismatches, utilsSpecForFile, } from "../../utils/utils-verify/index.js";
 import { realpath } from "../../utils/utils-verify/index.js";
 import { canonPath, samePath, utilsFileLabel } from "./reuse-state.js";
+import { freshExecution } from "../../types/TestExecution.js";
 /**
  * Retrofit tracking (SKYR-4276 A4): a RETROFIT is a pre-existing Skyramp-generated
  * test the reuse pass edited to import from the shared utils file (STEP 5c / the
  * sibling-inline advisory). Staging carries the edit into the output commit, so the
  * report must disclose it — with an execution that ran the edited bytes.
  *
- * Whether an execution counts is answered by TIME, not by a stored hash: the
- * execution record already carries `executedAt`, and the file's mtime says when it
+ * Whether an execution counts is answered by TIME, not by a stored hash (the rule
+ * itself is `freshExecution`, shared with the changed-helper gate): the execution
+ * record already carries `executedAt`, and the file's mtime says when it
  * was last edited — an execution older than the last edit ran bytes that no longer
  * exist. That also covers a bare editor write with no tool call in between, which a
  * record-time hash cannot see. (Same identity pattern as VideoRecord's
@@ -70,17 +72,14 @@ export async function standingRetrofits(state, changedFilesAbs) {
         if (!changed.has(canonPath(file)))
             continue;
         const recorded = state.existingTests?.find((t) => samePath(t.testFile, file))?.executionAfter;
-        let execution = recorded?.status;
-        if (recorded) {
-            try {
-                const mtime = (await stat(file)).mtimeMs;
-                if (Date.parse(recorded.executedAt) < mtime)
-                    execution = undefined;
-            }
-            catch {
-                /* fail open: an unreadable mtime must not demand a re-run */
-            }
+        let mtime = 0; // fail open: an unreadable mtime must not demand a re-run
+        try {
+            mtime = (await stat(file)).mtimeMs;
+        }
+        catch {
+            /* see above */
         }
+        const execution = freshExecution(recorded, mtime);
         out.push({ file, utilsFile: r.utilsFile, testFile: r.testFile, execution });
     }
     return uncrossAttributions(out);

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

@@ -60,6 +60,12 @@ export interface ReuseRecord {
      *  enforceable unit, as with every other debt here). Read by the reuse tool on a
      *  hand-off target: modularize-first flows owe modularization BEFORE reuse. */
     modularized?: true;
+    /** Both reuse settings on (isPomFirstTarget): the page-object pass finished for this
+     *  spec — its verify pass PASSED, or it found no page-object layer. Sticky: a later
+     *  page-object verdict (the combined verify of the SkyrampUtils flow re-checks the
+     *  page-object calls) does not reopen the pass, so routing never flips back to it.
+     *  Not recoverable from the spec: it is a fact about the run's order. */
+    pomPassFinished?: true;
     /** The spec as it stood when `skyramp_modularization` handed out its instructions —
      *  after the enhancer, before any code moved (SKYR-4276 A7/A8). The verify pass
      *  compares the delivered spec plus the helpers it imports against this. */

package/build/tools/code-refactor/reuse-record-store.d.ts

@@ -0,0 +1,52 @@
+import { StateManager, type ReuseHandOff, type UnifiedAnalysisState } from "../../utils/AnalysisStateManager.js";
+import type { ReuseRecord } from "./reuse-outcome.js";
+/**
+ * The run-state store behind every reuse record and hand-off: one read, one
+ * read-modify-write, one ownership rule, one canonical path comparison. The reuse
+ * checkpoints (reuse-state.ts) and the page-object-pass state (pom-pass-state.ts)
+ * both build on these and nothing else touches the file.
+ *
+ * Every write is best-effort. Reuse observability must never be able to fail a
+ * refactor that otherwise succeeded, so a missing/unreadable/unwritable state
+ * file degrades to "no reuse summary in the report" — the same outcome as running
+ * outside a Testbot run, where there is no run state to record into.
+ */
+/**
+ * Read-modify-write one spec's outcome. `patch` receives the entry recorded so
+ * far, so a caller that needs prior state (the verify pass, which accumulates
+ * flagged members) uses the same path as one that does not.
+ *
+ * Fields the patch omits are preserved: the prompt-generation call knows the
+ * candidate count, each verify pass knows the counts and verdict.
+ */
+export declare function updateReuseOutcome(testFile: string, patch: (existing: ReuseRecord) => Partial<ReuseRecord>, explicitStateFile?: string): Promise<boolean>;
+/** The run state as one read — the state manager (for a write-back) and what it
+ *  holds — or `undefined` when there is no run state to read. */
+export declare function readRunState(explicitStateFile?: string): Promise<{
+    manager: StateManager<UnifiedAnalysisState>;
+    data: UnifiedAnalysisState;
+} | undefined>;
+/** This spec's hand-off, keyed by realpath, with the run state it was read from —
+ *  the ONE read every hand-off checkpoint makes. `handOff` is `undefined` when the
+ *  file was never handed off; the whole result is when there is no run state. */
+export declare function readHandOff(testFile: string, explicitStateFile?: string): Promise<{
+    data: UnifiedAnalysisState;
+    handOff: ReuseHandOff | undefined;
+} | undefined>;
+/** Read one spec's record, or `undefined` when there is no run state, no record, or the
+ * state file cannot be read. Shares `updateReuseOutcome`'s resolve-read-basename plumbing
+ * so the two cannot disagree about which key a spec maps to. */
+export declare function readReuseRecord(testFile: string, explicitStateFile?: string): Promise<ReuseRecord | undefined>;
+/** Every field cleared — the patch spread onto a record owned by another spec. */
+export declare function freshRecord(): Partial<ReuseRecord>;
+/** Whether `record` describes `testFile` (or nobody yet). Basename-keyed run state
+ *  means two specs can share one record; only the owner's history carries over. */
+export declare function owns(record: ReuseRecord, testFile: string): boolean;
+/** Canonical comparison: a record written through a symlinked path (macOS /var →
+ *  /private/var) must still be recognised as this spec's when checked by realpath. */
+export declare function samePath(a: string, b: string): boolean;
+/** Exported for retrofit-state: the same canonicalisation the records use. */
+export declare function canonPath(p: string): string;
+/** Whether the run state file can be written — the precondition for any debt this
+ *  module holds, since only a write clears it. */
+export declare function runStateWritable(explicitStateFile?: string): Promise<boolean>;

package/build/tools/code-refactor/reuse-record-store.js

@@ -0,0 +1,126 @@
+import * as path from "path";
+import { access, constants as fsConstants } from "fs/promises";
+import { realpathSync } from "fs";
+import { logger } from "../../utils/logger.js";
+import { resolveRunStatePath, StateManager, } from "../../utils/AnalysisStateManager.js";
+import { realpath } from "../../utils/utils-verify/index.js";
+/**
+ * The run-state store behind every reuse record and hand-off: one read, one
+ * read-modify-write, one ownership rule, one canonical path comparison. The reuse
+ * checkpoints (reuse-state.ts) and the page-object-pass state (pom-pass-state.ts)
+ * both build on these and nothing else touches the file.
+ *
+ * Every write is best-effort. Reuse observability must never be able to fail a
+ * refactor that otherwise succeeded, so a missing/unreadable/unwritable state
+ * file degrades to "no reuse summary in the report" — the same outcome as running
+ * outside a Testbot run, where there is no run state to record into.
+ */
+/**
+ * Read-modify-write one spec's outcome. `patch` receives the entry recorded so
+ * far, so a caller that needs prior state (the verify pass, which accumulates
+ * flagged members) uses the same path as one that does not.
+ *
+ * Fields the patch omits are preserved: the prompt-generation call knows the
+ * candidate count, each verify pass knows the counts and verdict.
+ */
+export async function updateReuseOutcome(testFile, patch, explicitStateFile) {
+    try {
+        const state = await readRunState(explicitStateFile);
+        if (!state)
+            return false;
+        const { manager, data } = state;
+        const key = path.basename(testFile);
+        const existing = data.reuseOutcomes?.[key] ?? {};
+        await manager.appendData({
+            ...data,
+            reuseOutcomes: {
+                ...data.reuseOutcomes,
+                [key]: { ...existing, ...patch(existing) },
+            },
+        });
+        return true;
+    }
+    catch (err) {
+        logger.warning("Could not record POM-reuse outcome — report will omit the reuse summary", {
+            testFile,
+            error: String(err),
+        });
+        return false;
+    }
+}
+/** The run state as one read — the state manager (for a write-back) and what it
+ *  holds — or `undefined` when there is no run state to read. */
+export async function readRunState(explicitStateFile) {
+    const stateFile = resolveRunStatePath(explicitStateFile);
+    if (!stateFile)
+        return undefined;
+    const manager = StateManager.fromStatePath(stateFile);
+    const data = await manager.readData();
+    return data ? { manager, data } : undefined;
+}
+/** This spec's hand-off, keyed by realpath, with the run state it was read from —
+ *  the ONE read every hand-off checkpoint makes. `handOff` is `undefined` when the
+ *  file was never handed off; the whole result is when there is no run state. */
+export async function readHandOff(testFile, explicitStateFile) {
+    const state = await readRunState(explicitStateFile);
+    if (!state)
+        return undefined;
+    return {
+        data: state.data,
+        handOff: state.data.reuseHandOffs?.[await realpath(testFile)],
+    };
+}
+/** Read one spec's record, or `undefined` when there is no run state, no record, or the
+ * state file cannot be read. Shares `updateReuseOutcome`'s resolve-read-basename plumbing
+ * so the two cannot disagree about which key a spec maps to. */
+export async function readReuseRecord(testFile, explicitStateFile) {
+    return (await readRunState(explicitStateFile))?.data.reuseOutcomes?.[path.basename(testFile)];
+}
+/** Every field cleared — the patch spread onto a record owned by another spec. */
+export function freshRecord() {
+    return {
+        candidatesDetected: undefined,
+        verification: undefined,
+        flagged: undefined,
+        language: undefined,
+        utils: undefined,
+        modularized: undefined,
+        pomPassFinished: undefined,
+    };
+}
+/** Whether `record` describes `testFile` (or nobody yet). Basename-keyed run state
+ *  means two specs can share one record; only the owner's history carries over. */
+export function owns(record, testFile) {
+    return !record.testFilePath || samePath(record.testFilePath, testFile);
+}
+/** Canonical comparison: a record written through a symlinked path (macOS /var →
+ *  /private/var) must still be recognised as this spec's when checked by realpath. */
+export function samePath(a, b) {
+    return canon(a) === canon(b);
+}
+/** Exported for retrofit-state: the same canonicalisation the records use. */
+export function canonPath(p) {
+    return canon(p);
+}
+function canon(p) {
+    try {
+        return realpathSync(p);
+    }
+    catch {
+        return path.resolve(p);
+    }
+}
+/** Whether the run state file can be written — the precondition for any debt this
+ *  module holds, since only a write clears it. */
+export async function runStateWritable(explicitStateFile) {
+    const stateFile = resolveRunStatePath(explicitStateFile);
+    if (!stateFile)
+        return false;
+    try {
+        await access(stateFile, fsConstants.W_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

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

@@ -2,7 +2,20 @@ import { type ReuseHandOff, type ReuseHandOffSource } from "../../utils/Analysis
 import { type VerifyResult } from "../../utils/pom-verify/index.js";
 import { type InHouseDeclaration, type ReuseOutcome, type ReuseRecord } from "./reuse-outcome.js";
 import { type UtilsVerifyResult, type UtilsViolationKind } from "../../utils/utils-verify/index.js";
-import type { ReuseVerificationFailure } from "../../types/ReuseOutcome.js";
+import type { HelperReuseOutcome, ReuseVerificationFailure } from "../../types/ReuseOutcome.js";
+/** The canonical path comparison the records use — declared in the store, re-exported
+ *  here for the readers that always imported it from this module. */
+export { samePath, canonPath } from "./reuse-record-store.js";
+/**
+ * Persistence for the server-derived POM-reuse outcome, keyed by test-file
+ * basename (what `newTestsCreated[].fileName` carries, so
+ * `skyramp_submit_report` can match without path normalization).
+ *
+ * Every write is best-effort. Reuse observability must never be able to fail a
+ * refactor that otherwise succeeded, so a missing/unreadable/unwritable state
+ * file degrades to "no reuse summary in the report" — the same outcome as running
+ * outside a Testbot run, where there is no run state to record into.
+ */
 /**
  * Record the tier-1 candidate count STEP 1 detected, plus the identity needed to
  * re-derive the counts from the delivered spec later.
@@ -80,11 +93,6 @@ export declare function recordUtilsReuseIssued(testFile: string, language: strin
 /** A verify pass that threw. Recorded so the debt FAILS OPEN — a verifier that cannot
  *  run must not leave a debt nothing can pay — and cleared by the next successful pass. */
 export declare function recordUtilsVerifyError(testFile: string, explicitStateFile?: string): Promise<void>;
-/** Canonical comparison: a record written through a symlinked path (macOS /var →
- *  /private/var) must still be recognised as this spec's when checked by realpath. */
-export declare function samePath(a: string, b: string): boolean;
-/** Exported for retrofit-state: the same canonicalisation the records use. */
-export declare function canonPath(p: string): string;
 /**
  * The label a report row shows for a set of utils files: each file's path relative
  * to its repository root, posix-separated, joined with `, `.
@@ -233,6 +241,10 @@ export interface ReuseRederivation {
     outcome: ReuseOutcome | undefined;
     blocking?: ReuseBlockingVerdict;
 }
+/** The orphan fields of a report row: the helpers nothing imports, or the statement
+ *  that the walk could not tell. Exactly one of the two, and neither when the walk ran
+ *  and found none. Exported for its tests — the derivation is the whole behaviour. */
+export declare function orphanFields(r: UtilsVerifyResult): Pick<HelperReuseOutcome, "orphanedHelpers" | "orphanScanIncomplete">;
 /**
  * The reason behind a failed shared-helper verdict, one entry per blocking kind in
  * the order the verifier found them. The verify pass had these in hand and dropped