fix(typescript): fix stale .mjs refs the port missed, and type the three dev scripts for real

3 test files (iterate-loop-load-test-script, miner-benchmark-script,
miner-cross-repo-evaluation) still imported the OLD .mjs paths for
load-test-iterate-loop/benchmark/cross-repo-evaluation after their #9527 rename
to .ts -- the package.json runners were updated but these direct test imports
were missed. Broke CI on #9534 (Cannot find module ... .mjs). Fixed, plus the
same stale path in two docs, a manifest description string, a script's own
--help text, and a code comment, none of which the original port's grep sweep
caught.

Typing the three scripts for the first time (they were always .mjs, so tsc
never saw them) surfaced real gaps, not just missing annotations:

- cross-repo-evaluation.ts's main() called parseCrossRepoEvaluationArgs() with
  zero arguments against a REQUIRED parameter -- silently fine in untyped JS
  because the function internally falls back via ,
  but the parameter needed to actually be optional to say what was always true.
- benchmark.ts's buildSyntheticCandidates() was missing owner/repo/assignees
  entirely and mixed real booleans into a field opportunity-fanout.ts types as
  literal -only. Traced rankCandidateIssues' actual runtime check
  () before deciding how to type it: it
  genuinely branches on false, so narrowing the benchmark's synthetic mix to
  true-only would have silently dropped real exercised coverage. Added the
  missing fields for real, kept the deliberate true/false mix with a documented
  cast rather than narrowing it away.
- load-test-iterate-loop.ts's fake driver was typed to a hand-narrowed
  { attemptId: string } task shape until the test file's own fuller task
  literal (workingDirectory, acceptanceCriteriaPath, ...) failed against it --
  switched to the real CodingAgentDriverTask/Result types instead of the
  narrower hand-rolled ones.

Refs #9527

Author: JSONbored

control-plane/src/worker.ts

@@ -5,7 +5,7 @@
 // driver-factory.ts) into the plain, already-tested Hono app (http-app.ts). Adds NO route logic of its own.
 //
 // Not unit-tested: exercised only by real Cloudflare Workers/KV/Containers infrastructure, matching
-// packages/discovery-index/src/worker.ts's own identical exclusion (see scripts/control-plane-coverage.mjs).
+// packages/discovery-index/src/worker.ts's own identical exclusion (see scripts/control-plane-coverage.ts).
 import { Container } from "@cloudflare/containers";
 import { wakeDueAmsTenants } from "./ams-wake.js";
 import { createTenantProvisioningDriver } from "./driver-factory.js";

package-lock.json

@@ -14,7 +14,7 @@ mirrors; #5224 is the AMS-side counterpart this harness was built for.
 npm run loadtest:iterate-loop
 # or, from a workspace checkout, after building the engine:
 npm --workspace @loopover/engine run build
-node packages/loopover-engine/scripts/load-test-iterate-loop.mjs
+node --experimental-strip-types packages/loopover-engine/scripts/load-test-iterate-loop.ts
 ```
 
 This prints a short text report to stdout and exits `0`. It does not fail the build or a CI job on its own

packages/loopover-engine/docs/iterate-loop-load-test.md

@@ -1,6 +1,24 @@
 #!/usr/bin/env node
 import { performance } from "node:perf_hooks";
-import { parseFocusManifest, runIterateLoop } from "../dist/index.js";
+import {
+  parseFocusManifest,
+  runIterateLoop,
+  type IterateLoopInput,
+  type IterateLoopDeps,
+  type CodingAgentExecutionMode,
+  type CodingAgentDriverTask,
+  type CodingAgentDriverResult,
+} from "../dist/index.js";
+
+/** A driver implementing only `run()` -- the single member iterate-loop's own dependency injection
+ *  calls -- rather than the full CodingAgentDriver interface, which this harness never otherwise
+ *  touches. The task/result shapes themselves are the real CodingAgentDriverTask/Result types, not
+ *  narrowed, so a caller building a full realistic task (as the test double coverage below does)
+ *  gets real type checking on it. */
+type FakeLoadTestDriver = { run: (task: CodingAgentDriverTask) => Promise<CodingAgentDriverResult> };
+type ConcurrencyLevelOptions = { attemptCount?: number; latencyMs?: number };
+type ConcurrencyLevelResult = { concurrency: number; attemptCount: number; latencyMs: number; wallMs: number; handoffCount: number; attemptsPerSecond: number };
+type LoadTestOptions = ConcurrencyLevelOptions & { levels?: number[] };
 
 // Load-testing harness for the AMS iterate-loop orchestrator (#5224): every existing iterate-loop test is
 // correctness-oriented (single attempt, fake driver returns instantly), so there is no signal today for how
@@ -20,7 +38,7 @@ const SYNTHETIC_ISSUE_NUMBER = 7;
 /** One open issue per synthetic tenant repo, matching that tenant's own `passesPredictedGate` linkage below --
  *  each tenant is a fully independent repo/contributor pair (`buildSelfReviewPredictedGateInput`'s own identity
  *  fields), the same "multi-tenant-like" shape the issue's Problem section asks this harness to load-test. */
-function buildReviewContext(tenantRepoFullName) {
+function buildReviewContext(tenantRepoFullName: string) {
   return {
     manifest: parseFocusManifest({ gate: { duplicates: "block", linkedIssue: "advisory" } }),
     repo: { fullName: tenantRepoFullName, owner: tenantRepoFullName.split("/")[0], name: tenantRepoFullName.split("/")[1], isInstalled: true, isRegistered: true, isPrivate: false },
@@ -33,7 +51,7 @@ function buildReviewContext(tenantRepoFullName) {
  *  it resolves after `latencyMs` (simulating the wall-clock an iteration of a real coding-agent invocation
  *  would take) with a scripted, always-passing result. `latencyMs` uses a real `setTimeout`, not a busy-loop, so
  *  concurrent attempts genuinely interleave on the event loop the way concurrent live attempts would. */
-export function buildFakeLoadTestDriver(latencyMs) {
+export function buildFakeLoadTestDriver(latencyMs: number): FakeLoadTestDriver {
   return {
     async run(task) {
       await new Promise((resolve) => setTimeout(resolve, latencyMs));
@@ -48,15 +66,16 @@ const NOOP_SLOP_ASSESSMENT = { slopRisk: 0, band: "clean", findings: [] };
  *  issue that matches on the first iteration, so every attempt hands off in exactly one iteration -- isolating
  *  the measurement to iterate-loop's own per-attempt orchestration overhead rather than varying iteration counts
  *  across runs. */
-async function runOneAttempt(tenantIndex, driver) {
+async function runOneAttempt(tenantIndex: number, driver: FakeLoadTestDriver) {
   const repoFullName = `load-test-tenant-${tenantIndex}/repo`;
   const attemptId = `attempt-${tenantIndex}`;
+  const mode: CodingAgentExecutionMode = "live";
   const input = {
     attemptId,
     workingDirectory: `/tmp/${attemptId}`,
     acceptanceCriteriaPath: `/tmp/${attemptId}/acceptance-criteria.json`,
     instructions: "Synthetic load-test instructions",
-    mode: "live",
+    mode,
     maxIterations: 3,
     maxTurnsPerIteration: 20,
     repoFullName,
@@ -66,12 +85,16 @@ async function runOneAttempt(tenantIndex, driver) {
     linkedIssues: [SYNTHETIC_ISSUE_NUMBER],
     reviewContext: buildReviewContext(repoFullName),
     rejectionSignaled: false,
-  };
+  } as IterateLoopInput;
+  // FakeLoadTestDriver only implements the single `run()` member iterate-loop actually calls, not
+  // the full CodingAgentDriver interface -- deliberately narrow, matching this package's existing
+  // injection-seam convention of typing a test/harness double to the minimal surface exercised
+  // rather than the full production interface.
   const deps = {
     driver,
     runSlopAssessment: () => NOOP_SLOP_ASSESSMENT,
     appendAttemptLogEvent: () => {},
-  };
+  } as IterateLoopDeps;
   const start = performance.now();
   const result = await runIterateLoop(input, deps);
   return { elapsedMs: performance.now() - start, result };
@@ -83,13 +106,13 @@ async function runOneAttempt(tenantIndex, driver) {
  * to hand off after its first iteration (see {@link runOneAttempt}) -- a non-`"handoff"` outcome or a driver
  * error would silently understate real concurrent load, so both are counted and surfaced rather than ignored.
  */
-export async function runConcurrencyLevel(concurrency, options = {}) {
+export async function runConcurrencyLevel(concurrency: number, options: ConcurrencyLevelOptions = {}): Promise<ConcurrencyLevelResult> {
   const attemptCount = options.attemptCount ?? DEFAULT_ATTEMPTS_PER_LEVEL;
   const latencyMs = options.latencyMs ?? DEFAULT_SIMULATED_DRIVER_LATENCY_MS;
   const driver = buildFakeLoadTestDriver(latencyMs);
 
   const start = performance.now();
-  const outcomes = [];
+  const outcomes: Awaited<ReturnType<typeof runOneAttempt>>[] = [];
   for (let batchStart = 0; batchStart < attemptCount; batchStart += concurrency) {
     const batchSize = Math.min(concurrency, attemptCount - batchStart);
     const batch = await Promise.all(
@@ -112,17 +135,17 @@ export async function runConcurrencyLevel(concurrency, options = {}) {
 
 /** Run every concurrency level in `levels` in sequence (never overlapping each other), so one level's
  *  scheduling contention never bleeds into the next level's measurement. */
-export async function runLoadTest(options = {}) {
+export async function runLoadTest(options: LoadTestOptions = {}): Promise<ConcurrencyLevelResult[]> {
   const levels = options.levels ?? DEFAULT_CONCURRENCY_LEVELS;
-  const results = [];
+  const results: ConcurrencyLevelResult[] = [];
   for (const concurrency of levels) {
     results.push(await runConcurrencyLevel(concurrency, options));
   }
   return results;
 }
 
 /** Render load-test results as a stable, greppable text report (no locale-dependent number formatting). */
-export function formatLoadTestReport(results) {
+export function formatLoadTestReport(results: ConcurrencyLevelResult[]): string {
   const lines = ["iterate-loop load test", ""];
   for (const r of results) {
     lines.push(

packages/loopover-engine/scripts/load-test-iterate-loop.ts

@@ -1,5 +1,5 @@
 {
-  "description": "Cross-repo evaluation benchmark set (#4788). Diverse public repos exercised by `node packages/loopover-miner/scripts/cross-repo-evaluation.mjs` after cloning into LOOPOVER_MINER_REPO_CLONE_DIR.",
+  "description": "Cross-repo evaluation benchmark set (#4788). Diverse public repos exercised by `node --experimental-strip-types packages/loopover-miner/scripts/cross-repo-evaluation.ts` after cloning into LOOPOVER_MINER_REPO_CLONE_DIR.",
   "repos": [
     {
       "repoFullName": "sindresorhus/is",

packages/loopover-miner/benchmarks/cross-repo/manifest.json

@@ -51,7 +51,7 @@ fleet run-manifest).
 2. Run the harness from the repo root:
 
    ```bash
-   node packages/loopover-miner/scripts/cross-repo-evaluation.mjs
+   node --experimental-strip-types packages/loopover-miner/scripts/cross-repo-evaluation.ts
    ```
 
    Useful flags:
@@ -70,7 +70,7 @@ the coding agent runs against a synthetic benchmark issue inside that copy, and
 test commands are executed there. The scratch tree is removed afterward in every outcome — execute-locally-and-discard.
 
 ```bash
-node packages/loopover-miner/scripts/cross-repo-evaluation.mjs --full-execution
+node --experimental-strip-types packages/loopover-miner/scripts/cross-repo-evaluation.ts --full-execution
 ```
 
 Prerequisites beyond the readiness mode: a configured coding-agent provider (`MINER_CODING_AGENT_PROVIDER`, see
@@ -93,7 +93,7 @@ defaults to `DEFAULT_CROSS_REPO_EXECUTION_MAX_TURNS` (24).
 
 ## Library API
 
-Pure functions live in [`lib/cross-repo-evaluation.js`](../lib/cross-repo-evaluation.js):
+Pure functions live in [`lib/cross-repo-evaluation.ts`](../lib/cross-repo-evaluation.ts):
 
 - `parseCrossRepoEvaluationManifest(content)`
 - `evaluateRepoReadiness(entry, options)` — inject `existsSync`, `detectRepoStack`, etc. for unit tests

packages/loopover-miner/docs/cross-repo-evaluation.md

@@ -1,8 +1,13 @@
 #!/usr/bin/env node
 import { performance } from "node:perf_hooks";
 import { rankCandidateIssues } from "../dist/lib/opportunity-ranker.js";
+import type { RawCandidateIssue } from "../dist/lib/opportunity-fanout.js";
 import { initPortfolioQueueStore } from "../dist/lib/portfolio-queue.js";
 
+type RankingBenchmarkOptions = { candidateCount?: number; iterations?: number };
+type LocalStoreBenchmarkOptions = { operationCount?: number; iterations?: number };
+type BenchmarkResult = { name: string; unitCount: number; iterations: number; medianMs: number; opsPerSecond: number };
+
 // Committed micro-benchmark for the two hot local paths that have no other way to notice a regression: the
 // discovery fan-out ranking pass (opportunity-ranker.js, run once per repo per discovery cycle over every open
 // candidate) and the local-store read/write path (portfolio-queue.js, run on every enqueue/claim). Neither is
@@ -21,44 +26,53 @@ const SYNTHETIC_EPOCH_MS = Date.UTC(2024, 0, 1);
  * `Date.now()`, so `buildSyntheticCandidates(n)` returns byte-identical input on every call/machine/run -- the
  * benchmark's numbers are comparable across runs precisely because its input never varies.
  */
-export function buildSyntheticCandidates(count) {
-  const candidates = [];
+export function buildSyntheticCandidates(count: number): RawCandidateIssue[] {
+  const candidates: RawCandidateIssue[] = [];
   for (let i = 0; i < count; i += 1) {
     const timestamp = new Date(SYNTHETIC_EPOCH_MS + i * 3_600_000).toISOString();
     candidates.push({
+      owner: "bench-owner",
+      repo: `bench-repo-${i % 7}`,
       repoFullName: `bench-owner/bench-repo-${i % 7}`,
       issueNumber: i + 1,
       title: `Synthetic benchmark issue #${i + 1}`,
-      labels: [LABEL_POOL[i % LABEL_POOL.length]],
+      labels: [LABEL_POOL[i % LABEL_POOL.length]!],
+      assignees: [],
       commentsCount: i % 11,
       createdAt: timestamp,
       updatedAt: timestamp,
       htmlUrl: `https://github.com/bench-owner/bench-repo-${i % 7}/issues/${i + 1}`,
+      // RawCandidateIssue's aiPolicyAllowed is typed `true`-only (real production candidates
+      // are pre-filtered to allowed-only before reaching this stage), but rankCandidateIssues'
+      // own logic checks `candidate.aiPolicyAllowed !== false` at runtime -- it genuinely
+      // tolerates and branches on a false value. The benchmark deliberately mixes in some
+      // aiPolicyAllowed:false candidates to exercise that branch, so this is cast below rather
+      // than narrowed to true-only, which would silently drop real exercised coverage.
       aiPolicyAllowed: i % 5 !== 0,
       aiPolicySource: i % 5 === 0 ? "AI-USAGE.md" : "none",
-    });
+    } as RawCandidateIssue);
   }
   return candidates;
 }
 
-function timeMs(fn) {
+function timeMs(fn: () => void): number {
   const start = performance.now();
   fn();
   return performance.now() - start;
 }
 
-function median(values) {
+function median(values: number[]): number {
   const sorted = [...values].sort((a, b) => a - b);
   const mid = Math.floor(sorted.length / 2);
-  return sorted.length % 2 === 0 ? (sorted[mid - 1] + sorted[mid]) / 2 : sorted[mid];
+  return sorted.length % 2 === 0 ? (sorted[mid - 1]! + sorted[mid]!) / 2 : sorted[mid]!;
 }
 
 /** Rank the same synthetic candidate set `iterations` times and report the median wall time (#4845). */
-export function runRankingBenchmark(options = {}) {
+export function runRankingBenchmark(options: RankingBenchmarkOptions = {}): BenchmarkResult {
   const candidateCount = options.candidateCount ?? DEFAULT_CANDIDATE_COUNT;
   const iterations = options.iterations ?? DEFAULT_ITERATIONS;
   const candidates = buildSyntheticCandidates(candidateCount);
-  const samples = [];
+  const samples: number[] = [];
   for (let i = 0; i < iterations; i += 1) {
     samples.push(timeMs(() => rankCandidateIssues(candidates, { nowMs: SYNTHETIC_EPOCH_MS })));
   }
@@ -77,10 +91,10 @@ export function runRankingBenchmark(options = {}) {
  * the median wall time -- the same read/write path every real enqueue/claim exercises against the on-disk file,
  * minus filesystem I/O, so the number isolates the query-plan/schema cost this package actually controls.
  */
-export function runLocalStoreBenchmark(options = {}) {
+export function runLocalStoreBenchmark(options: LocalStoreBenchmarkOptions = {}): BenchmarkResult {
   const operationCount = options.operationCount ?? DEFAULT_QUEUE_OPERATION_COUNT;
   const iterations = options.iterations ?? DEFAULT_ITERATIONS;
-  const samples = [];
+  const samples: number[] = [];
   for (let i = 0; i < iterations; i += 1) {
     const store = initPortfolioQueueStore(":memory:");
     try {
@@ -113,7 +127,7 @@ export function runLocalStoreBenchmark(options = {}) {
 }
 
 /** Render benchmark results as a stable, greppable text report (no locale-dependent number formatting). */
-export function formatBenchmarkReport(results) {
+export function formatBenchmarkReport(results: BenchmarkResult[]): string {
   const lines = ["loopover-miner benchmark", ""];
   for (const result of results) {
     lines.push(

packages/loopover-miner/scripts/benchmark.ts

@@ -9,15 +9,22 @@ import {
   runCrossRepoEvaluation,
   runCrossRepoFullExecution,
   summarizeCrossRepoEvaluation,
+  type ParsedCrossRepoEvaluationManifest,
 } from "../dist/lib/cross-repo-evaluation.js";
 
 const PACKAGE_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
 
+// dist/lib/cross-repo-evaluation.js DOES ship a sibling .d.ts (that package's declaration: true),
+// so the real ParsedCrossRepoEvaluationManifest type is available -- reused here rather than
+// duplicated. repoFilter is string | null (not string | undefined) to match
+// parseCrossRepoEvaluationArgs' own inferred return shape below.
+type CliOptions = { parsed?: ParsedCrossRepoEvaluationManifest; manifestPath?: string; repoFilter?: string | null };
+
 export function resolveDefaultManifestPath() {
   return join(PACKAGE_ROOT, DEFAULT_CROSS_REPO_MANIFEST_RELATIVE_PATH);
 }
 
-export function parseCrossRepoEvaluationArgs(argv) {
+export function parseCrossRepoEvaluationArgs(argv?: string[]) {
   const args = argv ?? process.argv.slice(2);
   let manifestPath = resolveDefaultManifestPath();
   let json = false;
@@ -60,23 +67,27 @@ export function parseCrossRepoEvaluationArgs(argv) {
   return { manifestPath, json, repoFilter, requireMajority, fullExecution };
 }
 
-export function loadCrossRepoEvaluationManifest(manifestPath) {
+export function loadCrossRepoEvaluationManifest(manifestPath: string): ParsedCrossRepoEvaluationManifest {
   const content = readFileSync(manifestPath, "utf8");
   return parseCrossRepoEvaluationManifest(content);
 }
 
-export function runCrossRepoEvaluationCli(options = {}) {
+export function runCrossRepoEvaluationCli(options: CliOptions = {}) {
   const parsed = options.parsed ?? loadCrossRepoEvaluationManifest(options.manifestPath ?? resolveDefaultManifestPath());
-  const results = runCrossRepoEvaluation(parsed, { repoFilter: options.repoFilter ?? null });
+  // exactOptionalPropertyTypes: conditionally spread rather than always set repoFilter to a
+  // possibly-undefined/null value -- the target type's repoFilter?: string admits "absent", not
+  // "present and undefined". null and undefined are equally falsy at every downstream truthiness
+  // check either way, so this is a type-only normalization, not a behavior change.
+  const results = runCrossRepoEvaluation(parsed, options.repoFilter ? { repoFilter: options.repoFilter } : {});
   const summary = summarizeCrossRepoEvaluation(results);
   return { parsed, results, summary };
 }
 
 /** Full-execution counterpart of runCrossRepoEvaluationCli (#7634) — same shape, async because agent runs and
  *  the benchmark repos' own test suites are. Dry-run: see runCrossRepoFullExecution. */
-export async function runCrossRepoFullExecutionCli(options = {}) {
+export async function runCrossRepoFullExecutionCli(options: CliOptions = {}) {
   const parsed = options.parsed ?? loadCrossRepoEvaluationManifest(options.manifestPath ?? resolveDefaultManifestPath());
-  const results = await runCrossRepoFullExecution(parsed, { repoFilter: options.repoFilter ?? null });
+  const results = await runCrossRepoFullExecution(parsed, options.repoFilter ? { repoFilter: options.repoFilter } : {});
   const summary = summarizeCrossRepoEvaluation(results);
   return { parsed, results, summary };
 }
@@ -87,7 +98,7 @@ function printHelp() {
       "loopover-miner cross-repo evaluation (#4788)",
       "",
       "Usage:",
-      "  node packages/loopover-miner/scripts/cross-repo-evaluation.mjs [options]",
+      "  node --experimental-strip-types packages/loopover-miner/scripts/cross-repo-evaluation.ts [options]",
       "",
       "Options:",
       "  --manifest <path>     Benchmark manifest (default: benchmarks/cross-repo/manifest.json)",

packages/loopover-miner/scripts/cross-repo-evaluation.ts

@@ -9,7 +9,7 @@ import {
   formatLoadTestReport,
   runConcurrencyLevel,
   runLoadTest,
-} from "../../packages/loopover-engine/scripts/load-test-iterate-loop.mjs";
+} from "../../packages/loopover-engine/scripts/load-test-iterate-loop";
 
 describe("iterate-loop load-test script (#5224)", () => {
   it("the fake driver never spawns a real subprocess and resolves a scripted ok result after the configured latency", async () => {
@@ -76,7 +76,7 @@ describe("iterate-loop load-test script (#5224)", () => {
   });
 
   it("runs end-to-end as a CLI script and prints the report header plus every default concurrency level", () => {
-    const result = spawnSync(process.execPath, ["packages/loopover-engine/scripts/load-test-iterate-loop.mjs"], {
+    const result = spawnSync(process.execPath, ["--experimental-strip-types", "packages/loopover-engine/scripts/load-test-iterate-loop.ts"], {
       cwd: process.cwd(),
       encoding: "utf8",
     });