@skyramp/mcp 0.4.1 → 0.4.2-rc.2

package/build/utils/reportVerification.js

@@ -5,7 +5,7 @@ import { execFile } from "child_process";
 import { promisify } from "util";
 import { testFileMatches } from "./utils.js";
 import { DriftAction } from "../types/TestAnalysis.js";
-import { baselineFileMatchesStem, baselineStem } from "./rebaselineSnapshots.js";
+import { baselineFileMatchesStem, baselineStem, } from "./rebaselineSnapshots.js";
 const execFileAsync = promisify(execFile);
 /**
  * Enumerate every path that differs from HEAD in the working tree — staged,
@@ -122,11 +122,13 @@ export async function listChangedFiles(repoRoot) {
  *  - DELETE verdicts — applied deterministically by the delivery step, not
  *    necessarily reflected in the tree at report time.
  *  - IGNORE / VERIFY verdicts — assert that NO edit was needed.
- *  - Claims for files outside this checkout (cross-repo `repository`, or an
- *    absolute path resolving outside `repoRoot`) — a different checkout owns them.
+ *  - Claims for files outside this checkout (a `repository` naming another
+ *    checkout THIS RUN ANALYZED, or an absolute path resolving outside
+ *    `repoRoot`) — a different checkout owns them. A name the run does not know
+ *    owns nothing, so it is reported rather than exempted.
  */
 export function findUnchangedFileClaims(input) {
-    const { repoRoot, changedFiles, newTests, verdicts, primaryRepository, planOnly, } = input;
+    const { repoRoot, changedFiles, newTests, verdicts, primaryRepository, knownRepositories, planOnly, } = input;
     const unbacked = [];
     const isBacked = (claimedPath) => {
         let candidate = claimedPath;
@@ -182,12 +184,14 @@ export function findUnchangedFileClaims(input) {
         if (!t.fileName)
             continue;
         // Cross-repo finding — its file lives in a different checkout, not this tree.
-        // Exempt any claim explicitly attributed to a repo that isn't the primary.
-        // When the primary repo is unknown (primaryRepository undefined) we can't
-        // confirm the file belongs to this checkout, so any explicitly-attributed
-        // claim is exempted rather than risk a false rejection.
-        if (t.repository && t.repository !== primaryRepository)
+        // Exempt it only when the run actually analyzed that checkout: any other name
+        // points at no tree, and waving it through is how an uncreated test ships.
+        if (t.repository !== primaryRepository) {
+            if (knownRepositories.includes(t.repository))
+                continue;
+            unbacked.push(`newTestsCreated "${t.testId ?? t.fileName}" names repository "${t.repository}", which this run did not analyze (it analyzed ${knownRepositories.join(", ")})`);
             continue;
+        }
         if (!isBacked(t.fileName)) {
             unbacked.push(`newTestsCreated "${t.testId ?? t.fileName}" claims file "${t.fileName}", but no matching file was created or modified in the working tree`);
         }
@@ -395,7 +399,7 @@ export async function findInvalidSourceCitations(input) {
             entry: `issuesFound[${i}]`,
             cited,
             symbol,
-            declared: input.issues[i].repository?.trim(),
+            declared: input.issues[i].repository,
             resolved: resolved.map((hit) => hit.checkout),
         });
         if (attribution.message)
@@ -408,9 +412,7 @@ export async function findInvalidSourceCitations(input) {
  *  A checkout the run could not name contributes nothing: it can be neither
  *  stamped nor offered as a candidate. */
 function namesOf(resolved) {
-    return [
-        ...new Set(resolved.map((c) => c.repository).filter((r) => !!r)),
-    ];
+    return [...new Set(resolved.map((c) => c.repository))];
 }
 /**
  * Reconcile where a citation resolved with what the entry says about it, giving
@@ -425,7 +427,7 @@ function attributeCitation(args) {
         // owner/repo is case-insensitive on GitHub, so a differently-cased attribution
         // is the same repo — accepted, and re-stamped in the run's own spelling rather
         // than sent back for a rewrite that would change nothing.
-        const match = resolved.find((c) => c.repository && c.repository.toLowerCase() === declared.toLowerCase());
+        const match = resolved.find((c) => c.repository.toLowerCase() === declared.toLowerCase());
         if (match)
             return match.repository === declared
                 ? {}
@@ -449,10 +451,8 @@ function attributeCitation(args) {
         }
         return {}; // Cannot name the alternatives — accept, and stamp nothing.
     }
-    // Exactly one checkout. Stamp it unless it is the primary, whose findings are
-    // identified downstream by having NO repository — see SourceCitationCheck.
+    // Exactly one checkout. Stamp it, the primary included: an item names its repo
+    // whichever checkout it came from, so absence no longer means "the primary".
     const [only] = resolved;
-    return only.primary || !only.repository
-        ? {}
-        : { repository: only.repository };
+    return { repository: only.repository };
 }

package/build/utils/repositorySlug.d.ts

@@ -0,0 +1,32 @@
+/**
+ * `owner/repo` from a git remote URL. Accepts the two spellings a checkout's
+ * `origin` carries — ssh (`git@host:owner/repo.git`) and https
+ * (`https://host/owner/repo`) — with or without the `.git` suffix.
+ *
+ * Returns undefined when the URL yields no owner/repo pair, which the callers
+ * treat differently: see `repositorySlugOf` and `tryRepositorySlug` below.
+ */
+export declare function parseOwnerRepo(remoteUrl: string): string | undefined;
+/**
+ * `owner/repo` of the checkout at `dir`, or undefined when it is not a git repo,
+ * has no `origin` remote, or the remote URL names no owner/repo pair.
+ *
+ * For a caller that cannot proceed without the name, use `repositorySlugOf`.
+ */
+export declare function tryRepositorySlug(dir: string): Promise<string | undefined>;
+/**
+ * `owner/repo` of the checkout at `dir`. Throws, naming the path, when the
+ * directory cannot name one: every repository attribution in a run comes from
+ * here, so a missing name is a run that cannot attribute anything rather than
+ * one that attributes it to a guess.
+ */
+export declare function repositorySlugOf(dir: string): Promise<string>;
+/** Test seam: drop the memoized lookups so a fixture can rebuild a checkout. */
+export declare function clearRepositorySlugCache(): void;
+/**
+ * A checkout path in the spelling two calls can be compared in: symlinks
+ * resolved, relative spellings absolute. Falls back to the absolute path when
+ * the directory does not exist, so a caller comparing paths still gets an
+ * answer rather than an error about a path it only means to name.
+ */
+export declare function resolveRealPath(dir: string): Promise<string>;

package/build/utils/repositorySlug.js

@@ -0,0 +1,77 @@
+import { execFile } from "child_process";
+import { promisify } from "util";
+import fs from "fs/promises";
+import path from "path";
+const execFileAsync = promisify(execFile);
+/**
+ * `owner/repo` from a git remote URL. Accepts the two spellings a checkout's
+ * `origin` carries — ssh (`git@host:owner/repo.git`) and https
+ * (`https://host/owner/repo`) — with or without the `.git` suffix.
+ *
+ * Returns undefined when the URL yields no owner/repo pair, which the callers
+ * treat differently: see `repositorySlugOf` and `tryRepositorySlug` below.
+ */
+export function parseOwnerRepo(remoteUrl) {
+    const match = remoteUrl.trim().match(/[:/]([^/]+)\/([^/]+?)(?:\.git)?\/?$/);
+    if (!match)
+        return undefined;
+    const [, owner, repo] = match;
+    return `${owner}/${repo}`;
+}
+// One `git remote get-url` per directory for the life of the process. The
+// value is the resolved slug, or undefined when the directory cannot name one.
+const slugCache = new Map();
+/**
+ * `owner/repo` of the checkout at `dir`, or undefined when it is not a git repo,
+ * has no `origin` remote, or the remote URL names no owner/repo pair.
+ *
+ * For a caller that cannot proceed without the name, use `repositorySlugOf`.
+ */
+export function tryRepositorySlug(dir) {
+    const cached = slugCache.get(dir);
+    if (cached)
+        return cached;
+    const lookup = (async () => {
+        try {
+            const { stdout } = await execFileAsync("git", ["-C", dir, "remote", "get-url", "origin"], { timeout: 5_000 });
+            return parseOwnerRepo(stdout);
+        }
+        catch {
+            return undefined;
+        }
+    })();
+    slugCache.set(dir, lookup);
+    return lookup;
+}
+/**
+ * `owner/repo` of the checkout at `dir`. Throws, naming the path, when the
+ * directory cannot name one: every repository attribution in a run comes from
+ * here, so a missing name is a run that cannot attribute anything rather than
+ * one that attributes it to a guess.
+ */
+export async function repositorySlugOf(dir) {
+    const slug = await tryRepositorySlug(dir);
+    if (!slug) {
+        throw new Error(`cannot read owner/repo from the origin remote of ${dir}: the checkout has no origin, or its URL names no owner/repo`);
+    }
+    return slug;
+}
+/** Test seam: drop the memoized lookups so a fixture can rebuild a checkout. */
+export function clearRepositorySlugCache() {
+    slugCache.clear();
+}
+/**
+ * A checkout path in the spelling two calls can be compared in: symlinks
+ * resolved, relative spellings absolute. Falls back to the absolute path when
+ * the directory does not exist, so a caller comparing paths still gets an
+ * answer rather than an error about a path it only means to name.
+ */
+export async function resolveRealPath(dir) {
+    const absolute = path.resolve(dir);
+    try {
+        return await fs.realpath(absolute);
+    }
+    catch {
+        return absolute;
+    }
+}

package/build/utils/reuseRouting.d.ts

@@ -1,3 +1,13 @@
 export declare function isBrowserTestType(testType?: string): boolean;
 export declare function isModularizeFirstTarget(testType?: string, language?: string): boolean;
 export declare function isPomAwareTarget(language: string, framework?: string, testType?: string): boolean;
+/**
+ * Which family's inline call-site rule and sibling scan a test gets — the ONE gate
+ * for both. `api` for integration, whatever the flags (the rule is stated in API
+ * terms and predates the flag); `browser` for the seeded UI flow, where a Skyramp
+ * browser module exists to call into; `undefined` everywhere else (`contract`, `load`,
+ * e2e, an absent type, UI with the flag off or page-object reuse on), where an
+ * advisory would describe reuse the feature could not have taken. The prompt renders
+ * the rule and STEP 5c on it; the verify pass runs the scan on it.
+ */
+export declare function inlineCallSiteFamily(testType?: string, language?: string): "api" | "browser" | undefined;

package/build/utils/reuseRouting.js

@@ -14,8 +14,12 @@ export function isBrowserTestType(testType) {
 // skyramp_modularization runs BEFORE skyramp_reuse_code and the reuse pass seeds
 // the shared utils file from the helpers it created. The utils flag is the
 // single gate for every test type — the modularization prompts' per-step
-// extraction reads the same predicate, so the hand-off, the extraction and the
-// seeding step agree on every codeReuse flow. Integration qualifies whenever the flag is on;
+// extraction reads this predicate, so the extraction and the seeding step agree
+// on every codeReuse flow. The two hand-off sites (generation and the
+// maintenance step) read isModularizeFirstHandOffTarget in prompts/reuse-hand-off.ts,
+// which is THIS predicate plus a utils spec for the language: a language the
+// verifier does not cover has no payable reuse half, so no hand-off is owed for
+// it. Integration qualifies whenever the flag is on;
 // UI only while the POM path is off (POM refactoring supersedes modularization,
 // and the testbot UI flow asks for codeReuse unconditionally, so the flag is what
 // keeps the default-off behavior a no-op reuse pass). e2e and load are not
@@ -48,3 +52,18 @@ export function isPomAwareTarget(language, framework, testType) {
     return ((lang === "typescript" || lang === "javascript") &&
         framework?.toLowerCase() === "playwright");
 }
+/**
+ * Which family's inline call-site rule and sibling scan a test gets — the ONE gate
+ * for both. `api` for integration, whatever the flags (the rule is stated in API
+ * terms and predates the flag); `browser` for the seeded UI flow, where a Skyramp
+ * browser module exists to call into; `undefined` everywhere else (`contract`, `load`,
+ * e2e, an absent type, UI with the flag off or page-object reuse on), where an
+ * advisory would describe reuse the feature could not have taken. The prompt renders
+ * the rule and STEP 5c on it; the verify pass runs the scan on it.
+ */
+export function inlineCallSiteFamily(testType, language) {
+    if (testType?.toLowerCase() === "integration")
+        return "api";
+    // A modularize-first target that is not integration is the seeded UI flow.
+    return isModularizeFirstTarget(testType, language) ? "browser" : undefined;
+}

package/build/utils/runContextGauge.d.ts

@@ -0,0 +1,27 @@
+export interface ContextReading {
+    /** Tokens the last request actually carried: fresh input, cache reads and cache
+     *  writes together. This is the number that fills the window. */
+    tokens: number;
+    window: number;
+    /** `tokens` as a whole percentage of `window`, for printing. */
+    percent: number;
+}
+/** This run's context usage, or undefined when it cannot be read.
+ *
+ *  Undefined is ORDINARY, not an error: a local or IDE run has no `RUNNER_TEMP`
+ *  and no agent log, and an agent whose CLI writes no NDJSON log never produces
+ *  one. Every caller prints nothing and carries on. */
+export declare function readRunContext(): ContextReading | undefined;
+/** One sentence naming the measurement, for a refusal that has already told the
+ *  agent not to stop on a context it believes it is short of. Empty when there is
+ *  no reading — the refusal reads correctly without it.
+ *
+ *  It states the reading and nothing else. It does not say the run has room: the
+ *  reading can be 95% and the refusal still stands on its own grounds, and a
+ *  sentence that argued headroom would be wrong exactly when it mattered most.
+ *
+ *  CARRIES ITS OWN TRAILING SPACE, so a caller concatenates it unconditionally
+ *  and an empty reading leaves no gap. */
+export declare function contextGaugeSentence(): string;
+/** Test seam: drop the per-run window cache. */
+export declare function resetRunContextGaugeForTests(): void;

package/build/utils/runContextGauge.js

@@ -0,0 +1,181 @@
+import * as fs from "fs";
+import * as path from "path";
+import { runArtifactDir } from "./AnalysisStateManager.js";
+import { logger } from "./logger.js";
+/** What the agent's own context usage is, read from the agent log the Testbot
+ *  action streams beside this run's artifacts.
+ *
+ *  WHY THIS EXISTS. Two runs cut planned work citing a "context budget" they
+ *  could not measure: one declared itself out at 357k of a 1M window, the next at
+ *  457k, and neither had a warning from anywhere. The agent has no reading of its
+ *  own context and the prompt cannot give it one, so a refusal that says "do not
+ *  stop because you believe you are low on context" is arguing with a feeling.
+ *  This turns it into a number the server can put in the refusal.
+ *
+ *  It is a MEASUREMENT, never a limit. Nothing here refuses anything or decides
+ *  anything; the callers do, on grounds that hold without it, and every one of
+ *  them still works when this returns undefined. */
+/** The Testbot action streams the agent CLI's `--output-format stream-json` here,
+ *  live, in the same directory this server already writes `testbot-result.txt` to. */
+const AGENT_LOG_NAME = "agent-log.ndjson";
+/** Enough of the tail to hold the last assistant record with a usage block. These
+ *  records carry whole tool results, so a fixed slice can miss one — 512 KiB covers
+ *  it with room, and a miss costs a sentence, not a refusal. */
+const TAIL_BYTES = 512 * 1024;
+/** Enough of the head to hold the `init` record, which is the FIRST line. */
+const HEAD_BYTES = 64 * 1024;
+/** Windows for models with no `[1m]`-style suffix on the init record, first
+ *  match wins. Opus 5 and Sonnet 5 are 1M by default — reading them as
+ *  200k is the same error the suffix rule below guards against, one level up.
+ *  Bedrock prefixes the id (`us.anthropic.claude-opus-5`), so these match
+ *  anywhere in the string rather than at the start. */
+const MODEL_WINDOWS = [
+    [/claude-(opus|sonnet)-5/i, 1_000_000],
+    [/claude-haiku/i, 200_000],
+];
+/** A model none of the above names. ERRS LARGE on purpose: too small a window
+ *  overstates the percentage, which is how this file manufactures the scarcity
+ *  it exists to disprove, and no caller acts on the number — the refusals stand
+ *  on their own grounds. Too large only understates it. */
+const DEFAULT_CONTEXT_WINDOW = 1_000_000;
+function windowForModel(model) {
+    for (const [pattern, window] of MODEL_WINDOWS) {
+        if (pattern.test(model))
+            return window;
+    }
+    return DEFAULT_CONTEXT_WINDOW;
+}
+/** Window and log path do not change within a run, so they are read once and kept
+ *  against the directory they came from — a new run is a new directory. The token
+ *  count is NOT cached: it is the thing that moves. */
+let cachedForDir;
+let cachedWindow;
+function readSlice(file, bytes, fromEnd) {
+    const fd = fs.openSync(file, "r");
+    try {
+        const size = fs.fstatSync(fd).size;
+        const length = Math.min(size, bytes);
+        const buffer = Buffer.alloc(length);
+        fs.readSync(fd, buffer, 0, length, fromEnd ? size - length : 0);
+        return buffer.toString("utf8");
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+/** The context window this run's model was started with.
+ *
+ *  READ FROM THE INIT RECORD, not from the per-message model. The two disagree:
+ *  `message.model` is `claude-opus-5` while the init record says
+ *  `claude-opus-5[1m]`, and taking the former turns 46% of a 1M window into 228%
+ *  of a 200k one — a gauge that manufactures the panic it exists to prevent. */
+function contextWindowFrom(head) {
+    for (const line of head.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed.startsWith("{"))
+            continue;
+        let record;
+        try {
+            record = JSON.parse(trimmed);
+        }
+        catch {
+            // The head slice ends mid-record on any file longer than it. Only the first
+            // line matters here and it is whole.
+            break;
+        }
+        if (record.type !== "system" || record.subtype !== "init")
+            break;
+        const model = typeof record.model === "string" ? record.model : "";
+        const suffix = /\[(\d+)(m|k)\]/i.exec(model);
+        if (!suffix)
+            return windowForModel(model);
+        const scale = suffix[2].toLowerCase() === "m" ? 1_000_000 : 1_000;
+        return Number(suffix[1]) * scale;
+    }
+    return DEFAULT_CONTEXT_WINDOW;
+}
+/** Tokens on the most recent assistant request in the log, or undefined.
+ *
+ *  Walks BACKWARDS to the first record that has them: the tail ends with the turn
+ *  that called the tool now running, and every later line is that turn's own
+ *  output. Records with no usage — heartbeats, progress, tool results — are
+ *  skipped, so the reading is always the newest real request. */
+function tokensFrom(tail) {
+    const lines = tail.split("\n");
+    for (let index = lines.length - 1; index >= 0; index--) {
+        const line = lines[index].trim();
+        // Cheap rejects first: this runs over a few thousand lines per call.
+        if (!line.startsWith("{") || !line.includes('"usage"'))
+            continue;
+        let record;
+        try {
+            record = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        const usage = record.message?.usage;
+        if (!usage)
+            continue;
+        const count = (key) => typeof usage[key] === "number" ? usage[key] : 0;
+        const tokens = count("input_tokens") +
+            count("cache_read_input_tokens") +
+            count("cache_creation_input_tokens");
+        if (tokens > 0)
+            return tokens;
+    }
+    return undefined;
+}
+/** This run's context usage, or undefined when it cannot be read.
+ *
+ *  Undefined is ORDINARY, not an error: a local or IDE run has no `RUNNER_TEMP`
+ *  and no agent log, and an agent whose CLI writes no NDJSON log never produces
+ *  one. Every caller prints nothing and carries on. */
+export function readRunContext() {
+    try {
+        const directory = runArtifactDir();
+        if (!directory)
+            return undefined;
+        const file = path.join(directory, AGENT_LOG_NAME);
+        if (!fs.existsSync(file))
+            return undefined;
+        if (directory !== cachedForDir) {
+            cachedForDir = directory;
+            cachedWindow = contextWindowFrom(readSlice(file, HEAD_BYTES, false));
+        }
+        const window = cachedWindow ?? DEFAULT_CONTEXT_WINDOW;
+        const tokens = tokensFrom(readSlice(file, TAIL_BYTES, true));
+        if (tokens === undefined || tokens <= 0)
+            return undefined;
+        return { tokens, window, percent: Math.round((tokens / window) * 100) };
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        logger.warning(`readRunContext failed: ${detail}`);
+        return undefined;
+    }
+}
+/** One sentence naming the measurement, for a refusal that has already told the
+ *  agent not to stop on a context it believes it is short of. Empty when there is
+ *  no reading — the refusal reads correctly without it.
+ *
+ *  It states the reading and nothing else. It does not say the run has room: the
+ *  reading can be 95% and the refusal still stands on its own grounds, and a
+ *  sentence that argued headroom would be wrong exactly when it mattered most.
+ *
+ *  CARRIES ITS OWN TRAILING SPACE, so a caller concatenates it unconditionally
+ *  and an empty reading leaves no gap. */
+export function contextGaugeSentence() {
+    const reading = readRunContext();
+    if (!reading)
+        return "";
+    const k = (value) => `${Math.round(value / 1000)}k`;
+    return (`Measured, not estimated: this run's last request carried ${k(reading.tokens)} of a ` +
+        `${k(reading.window)} token context window (${reading.percent}%). ` +
+        "Use that number rather than an impression of it. ");
+}
+/** Test seam: drop the per-run window cache. */
+export function resetRunContextGaugeForTests() {
+    cachedForDir = undefined;
+    cachedWindow = undefined;
+}

package/build/utils/runSerialized.d.ts

@@ -0,0 +1,3 @@
+export declare function runSerialized<T>(key: string, fn: () => Promise<T>): Promise<T>;
+/** Test seam: how many keys currently have work queued or running. */
+export declare function pendingSerializedKeys(): number;

package/build/utils/runSerialized.js

@@ -0,0 +1,39 @@
+/**
+ * Run async work one at a time per key, in arrival order, within this process.
+ *
+ * A caller that must read some state, act, and write the state back cannot be
+ * interleaved with another caller on the same key without both reading the
+ * same starting state. Callers on different keys never wait for each other.
+ * A rejected run releases the key like a resolved one.
+ *
+ * Re-entrant: work that already holds a key (it is running inside a
+ * runSerialized on that key, however deep) runs immediately instead of
+ * queueing behind itself — otherwise a helper that serializes on the state
+ * file, called from a handler that already serializes on it, would wait for
+ * its own caller to finish and deadlock.
+ */
+import { AsyncLocalStorage } from "async_hooks";
+const tails = new Map();
+const held = new AsyncLocalStorage();
+export async function runSerialized(key, fn) {
+    const holding = held.getStore() ?? new Set();
+    if (holding.has(key))
+        return fn();
+    const previous = tails.get(key) ?? Promise.resolve();
+    const run = previous.then(() => held.run(new Set([...holding, key]), fn));
+    // What the next caller waits on: settled either way, so one failure does not
+    // wedge the key.
+    const tail = run.then(() => undefined, () => undefined);
+    tails.set(key, tail);
+    try {
+        return await run;
+    }
+    finally {
+        if (tails.get(key) === tail)
+            tails.delete(key);
+    }
+}
+/** Test seam: how many keys currently have work queued or running. */
+export function pendingSerializedKeys() {
+    return tails.size;
+}