@aarwitz/tapp 0.15.0

package/scripts/mutation_operators.py

@@ -0,0 +1,144 @@
+#!/usr/bin/env python3
+"""Mutation operators for the mutation-recall benchmark (scripts/mutation-recall.sh).
+
+SKETCH / WIP — grounded in the real corpus (SwiftUI source in <App>/Sources/*.swift) and the
+real detector taxonomy (the OCQA_ISSUE `type` values the harness emits). Each operator injects
+ONE seeded fault and declares the ground truth: which detector *class* it should trip (or None
+if no detector exists for it). That in/out-of-taxonomy split is the whole point — see
+docs/COMPETITIVE-MAP.md §0.
+
+LIMITATIONS (honest):
+  - Regex/line transforms, not a real Swift AST. Robust version: swiftsyntax, one mutant per
+    (operator, matched node). Here we take the FIRST matching site per (operator, file).
+  - Screen attribution is heuristic (nearest .navigationTitle above the site). The fiddliest
+    part of honest matching; a wrong screen name shows up as a coverage miss, not a detect miss.
+
+Usage:
+  mutation_operators.py list  <App/Sources>              -> JSON array of applicable sites
+  mutation_operators.py apply <file> <op_id>  (in place; caller backs up + restores)
+"""
+import sys, re, json, glob, os
+from dataclasses import dataclass
+from typing import Callable, Optional
+
+
+@dataclass
+class Op:
+    id: str
+    bug_class: str            # human label for the fault
+    expected_type: Optional[str]  # OCQA_ISSUE `type` a detector should emit; None => out-of-taxonomy
+    in_taxonomy: bool
+    find: str                 # regex that identifies an applicable site
+    apply: Callable[[str], str]  # src -> mutated src (mutates the FIRST match only)
+
+
+def _sub_first(pattern, repl, src, flags=re.S):
+    return re.sub(pattern, repl, src, count=1, flags=flags)
+
+
+OPS = [
+    # ---------- IN-TAXONOMY: a detector class exists; measures "do we catch what we claim?" ----------
+    # Skips labels the harness's isSelectionOrValueControl deliberately EXCLUDES from dead-control
+    # detection (increment/decrement — steppers legitimately no-op at boundaries). Measured: a
+    # gutted 'Decrement' is invisible 4/4 runs BY DESIGN (the FP guard), so mutating it measures
+    # the documented precision/recall trade, not the detector. This operator measures what the
+    # detector claims to catch; a future dead_stepper op can price the known gap explicitly.
+    Op("dead_button", "button action gutted (dead control)", "unresponsive_element", True,
+       r'Button\("(?![^"]*(?:ncrement|ecrement))([^"]+)"\)\s*\{.*?\}',
+       lambda s: _sub_first(r'(Button\("(?![^"]*(?:ncrement|ecrement))[^"]+"\)\s*\{).*?(\})',
+                            r'\1 /* MUT: no-op */ \2', s)),
+
+    Op("infinite_spinner", "loading flag never cleared (perpetual spinner)", "app_hang", True,
+       r'(isLoading|loaded|isReady)\s*=\s*false',   # the line that would END loading
+       lambda s: _sub_first(r'((?:isLoading|loaded|isReady)\s*=\s*false)', r'/* MUT */ // \1', s)),
+
+    # NOTE: must attach to a view that actually RENDERS. The first sketch inserted
+    # `let _mut = Text(...)` after `var body {` — a local never added to the view tree, so the
+    # "fault" was invisible to the a11y tree and the benchmark misread it as a detector miss.
+    # Overlaying the .navigationTitle-bearing view guarantees the error text is really on screen.
+    Op("inject_error", "always-visible error surface", "error_surface", True,
+       r'\.navigationTitle\("[^"]+"\)',
+       lambda s: _sub_first(r'(\.navigationTitle\("[^"]+"\))',
+                            r'\1.overlay(Text("Something went wrong. Error 500.")) /* MUT */', s)),
+
+    Op("broken_nav", "NavigationLink destination blanked", "blank_screen", True,
+       r'NavigationLink\s*\{[^}]*\}',
+       lambda s: _sub_first(r'(NavigationLink\s*\{)[^}]*(\})', r'\1 EmptyView() /* MUT */ \2', s)),
+
+    # Same inert-let lesson as inject_error: fatalError must live inside a closure that FIRES.
+    # Injecting into an existing .task/.onAppear guarantees it runs when the screen appears.
+    Op("crash_on_appear", "fatalError on screen appear", "crash", True,
+       r'\.(?:task|onAppear)\s*\{',
+       lambda s: _sub_first(r'(\.(?:task|onAppear)\s*\{)',
+                            r'\1 fatalError("MUT crash"); ', s)),
+
+    # ---------- OUT-OF-TAXONOMY: no detector; measures the CEILING of deterministic detection ----------
+    # These should score ~0. That number is the argument for regression-diff + oracle/Flows.
+    Op("mislabel_button", "button label typo (still works, wrong text)", None, False,
+       r'Button\("[A-Za-z]{4,}"\)',
+       lambda s: _sub_first(r'Button\("([A-Za-z])([A-Za-z])([A-Za-z]+)"\)',
+                            r'Button("\2\1\3")', s)),   # transpose first two letters
+
+    Op("wrong_arithmetic", "arithmetic operator flipped (wrong number, UI fine)", None, False,
+       r'\w+\s*\+\s*\w+',
+       lambda s: _sub_first(r'(\w+)\s*\+\s*(\w+)', r'\1 - \2', s)),
+
+    # Skip `Enum.allCases` sites (static pickers/segments) so the mutation lands on real DATA
+    # (e.g. ForEach(filteredItems)) — dropping the last row of a data list is the silent-loss
+    # bug this operator exists to model; dropping the last segment of a picker is much weaker.
+    Op("off_by_one", "list drops its last row (silent data loss)", None, False,
+       r'ForEach\((?![A-Za-z_][\w\.]*\.allCases\))([A-Za-z_][\w\.]*)\)',
+       lambda s: _sub_first(r'ForEach\((?![A-Za-z_][\w\.]*\.allCases\))([A-Za-z_][\w\.]*)\)',
+                            r'ForEach(\1.dropLast())', s)),
+
+    Op("swap_fields", "two field bindings swapped (wrong wiring)", None, False,
+       r'TextField\(',   # NOTE: real swap needs 2 sites; sketch marks it, apply is a TODO
+       lambda s: s),  # TODO: locate two adjacent TextField bindings and swap $values
+]
+
+OPS_BY_ID = {o.id: o for o in OPS}
+
+
+def infer_screen(src: str, upto: int) -> str:
+    """Nearest .navigationTitle("X") at or above char offset `upto` — the harness names screens
+    by nav title, so this is our ground-truth screen for match. Fallback: last title in file."""
+    titles = [(m.start(), m.group(1)) for m in re.finditer(r'\.navigationTitle\("([^"]+)"\)', src)]
+    above = [t for pos, t in titles if pos <= upto] or [t for _, t in titles]
+    return above[-1] if above else "?"
+
+
+def list_sites(sources_dir: str):
+    sites = []
+    for path in sorted(glob.glob(os.path.join(sources_dir, "*.swift"))):
+        src = open(path, encoding="utf-8", errors="replace").read()
+        for op in OPS:
+            m = re.search(op.find, src, flags=re.S)
+            if not m:
+                continue
+            sites.append({
+                "file": path, "op": op.id, "bug_class": op.bug_class,
+                "expected_type": op.expected_type, "in_taxonomy": op.in_taxonomy,
+                "screen": infer_screen(src, m.start()),
+            })
+    return sites
+
+
+def apply(path: str, op_id: str) -> bool:
+    op = OPS_BY_ID[op_id]
+    src = open(path, encoding="utf-8", errors="replace").read()
+    mutated = op.apply(src)
+    if mutated == src:
+        return False   # no-op (e.g. swap_fields TODO) — caller skips
+    open(path, "w", encoding="utf-8").write(mutated)
+    return True
+
+
+if __name__ == "__main__":
+    cmd = sys.argv[1] if len(sys.argv) > 1 else ""
+    if cmd == "list":
+        print(json.dumps(list_sites(sys.argv[2]), indent=2))
+    elif cmd == "apply":
+        ok = apply(sys.argv[2], sys.argv[3])
+        sys.exit(0 if ok else 3)
+    else:
+        print(__doc__); sys.exit(2)

package/scripts/platform-gate.js

@@ -0,0 +1,186 @@
+#!/usr/bin/env node
+// CI orchestration for the platform drivers that do not need Xcode. The report,
+// baseline, Flow, and merge-gate behavior is the same ci-report.js used by iOS.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { runQaAndroid, runQaWeb, startManagedWebTarget, stopManagedWebTarget } from "../mcp-server/src/index.js";
+import { runAndroidFlow } from "../mcp-server/src/android-flow.js";
+import { inferFlowPlatform, loadFlowFile } from "../mcp-server/src/flow-runtime.js";
+import { runWebFlow } from "../mcp-server/src/web-flow.js";
+import { runWebScenario, validateScenario } from "../mcp-server/src/scenario-runtime.js";
+import { compileReleaseContract, loadReleaseContractFile } from "../mcp-server/src/release-contract.js";
+import { prExplorationTargetsFromPlan } from "../mcp-server/src/pr-selection.js";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const args = { flows: [], scenarios: [], contracts: [], actions: 40, timeout: 600, failOn: "gate" };
+for (let i = 2; i < process.argv.length; i += 1) {
+  const key = process.argv[i];
+  const value = process.argv[++i];
+  if (key === "--flow") args.flows.push(value);
+  else if (key === "--scenario") args.scenarios.push(value);
+  else if (key === "--contract") args.contracts.push(value);
+  else if (key === "--platform") args.platform = value;
+  else if (key === "--url") args.url = value;
+  else if (key === "--project-dir") args.projectDir = value;
+  else if (key === "--web-target") args.webTarget = value;
+  else if (key === "--target-key") args.targetKey = value;
+  else if (key === "--app-id") args.appId = value;
+  else if (key === "--apk") args.apk = value;
+  else if (key === "--serial") args.serial = value;
+  else if (key === "--actions") args.actions = Number(value);
+  else if (key === "--timeout") args.timeout = Number(value);
+  else if (key === "--baseline") args.baseline = value;
+  else if (key === "--fail-on") args.failOn = value;
+  else if (key === "--json-out") args.jsonOut = value;
+  else if (key === "--md-out") args.mdOut = value;
+  else if (key === "--pr-plan") args.prPlan = value;
+  else throw new Error(`Unknown argument: ${key}`);
+}
+if (!["web", "android"].includes(args.platform)) throw new Error("--platform must be web|android");
+if (args.platform === "web" && !args.url && !args.projectDir) throw new Error("Web gate requires --url or --project-dir for managed build/start");
+if (args.platform === "android" && !args.appId) throw new Error("Android gate requires --app-id");
+if (args.projectDir) {
+  args.projectDir = fs.realpathSync(path.resolve(args.projectDir));
+  if (!fs.statSync(args.projectDir).isDirectory()) throw new Error(`Project directory not found: ${args.projectDir}`);
+}
+
+// Parse and platform-filter before launching a browser/device so a typo cannot
+// spend the entire CI budget and then silently run zero committed tests.
+const selectedFlows = args.flows.map((flowPath) => ({ flowPath, flow: loadFlowFile(flowPath) }))
+  .filter(({ flow }) => inferFlowPlatform(flow) === args.platform);
+if (args.flows.length && selectedFlows.length === 0) {
+  console.error(`❌ None of the supplied Flows target platform '${args.platform}'`);
+  process.exit(2);
+}
+const selectedScenarios = args.scenarios.map((scenarioPath) => ({ scenarioPath, scenario: loadFlowFile(scenarioPath) }));
+for (const { scenarioPath, scenario } of selectedScenarios) {
+  const errors = validateScenario({ ...scenario, platform: scenario.platform || args.platform });
+  if (errors.length) {
+    console.error(`❌ Invalid Scenario ${scenarioPath}: ${errors.join("; ")}`);
+    process.exit(2);
+  }
+  if (args.platform !== "web") {
+    console.error(`❌ Multi-actor Scenario ${scenarioPath} requires platform 'web'; ${args.platform} actor isolation is not implemented`);
+    process.exit(2);
+  }
+}
+const selectedContracts = [];
+for (const contractPath of args.contracts) {
+  let contract;
+  try { contract = await loadReleaseContractFile(contractPath); }
+  catch (error) { console.error(`❌ Invalid Release Contract ${contractPath}: ${error.message}`); process.exit(2); }
+  if (!contract.platforms.includes(args.platform)) continue;
+  try {
+    selectedContracts.push({ contractPath, contract, execution: compileReleaseContract(contract, { platform: args.platform, sourcePath: contractPath }) });
+  } catch (error) {
+    console.error(`❌ Could not compile Release Contract ${contractPath}: ${error.message}`);
+    process.exit(2);
+  }
+}
+
+let prPlan = null;
+let prExplorationTargets = [];
+if (args.prPlan) {
+  try {
+    prPlan = JSON.parse(fs.readFileSync(path.resolve(args.prPlan), "utf8"));
+    prExplorationTargets = prExplorationTargetsFromPlan(prPlan, args.platform);
+  } catch (error) {
+    console.error(`❌ Could not read PR plan ${args.prPlan}: ${error.message || error}`);
+    process.exit(2);
+  }
+}
+
+let managedRuntime = null;
+let exitCode = 1;
+try {
+  if (args.platform === "web" && !args.url) {
+    const started = await startManagedWebTarget({
+      root: args.projectDir,
+      requestedTarget: args.webTarget || "",
+      timeout: args.timeout,
+      onStatus: (status) => console.error(`⏳ ${status}`),
+    });
+    if (started.error) {
+      console.error(`❌ ${started.error}`);
+      if (started.details?.remediation) console.error(`   ${started.details.remediation}`);
+      process.exitCode = 1;
+    } else {
+      managedRuntime = started;
+      args.url = started.url;
+      console.error(`🎯 Managed web target ready at ${args.url}; it will be stopped after the gate.`);
+    }
+  }
+  if (args.platform === "web" && !args.url) {
+    exitCode = 1;
+  } else {
+    const qa = args.platform === "web"
+      ? await runQaWeb({ url: args.url, maxActions: args.actions, timeout: args.timeout, testEmail: process.env.OCQA_TEST_EMAIL, testPassword: process.env.OCQA_TEST_PASSWORD, seedTargets: prExplorationTargets })
+      : await runQaAndroid({ appId: args.appId, apkPath: args.apk, serial: args.serial, maxActions: args.actions, timeout: args.timeout,
+          testEmail: process.env.OCQA_TEST_EMAIL, testPassword: process.env.OCQA_TEST_PASSWORD, seedTargets: prExplorationTargets });
+    if (qa.error) {
+      console.error(`❌ ${qa.error}`);
+      exitCode = 1;
+    } else {
+      const captureDir = qa.structured.capture.path;
+      const markers = path.join(captureDir, "ocqa-markers.txt");
+      const flowLogs = [];
+      for (const { flowPath, flow } of selectedFlows) {
+  const logPath = path.join(os.tmpdir(), `tapp-ci-${args.platform}-${path.basename(flowPath).replace(/\.ya?ml$/i, "")}-${Date.now()}.log`);
+  const evidenceDir = path.join(captureDir, "flows", path.basename(flowPath).replace(/\.ya?ml$/i, ""));
+  try {
+    if (args.platform === "web") await runWebFlow({ flow, url: args.url, logPath, screenshotDir: evidenceDir });
+    else await runAndroidFlow({ flow, appId: args.appId, apkPath: undefined, serial: args.serial, logPath, screenshotDir: evidenceDir });
+  } catch (error) {
+    fs.writeFileSync(logPath, `OCQA_FLOW_RESULT:${JSON.stringify({ passed: false, total: flow.steps.length, failed: 1, error: error.message || String(error) })}\n`);
+  }
+        flowLogs.push({ kind: "flow", path: logPath });
+      }
+      for (const { scenarioPath, scenario } of selectedScenarios) {
+  const logPath = path.join(os.tmpdir(), `tapp-ci-scenario-${path.basename(scenarioPath).replace(/\.ya?ml$/i, "")}-${Date.now()}.log`);
+  const evidenceDir = path.join(captureDir, "scenarios", path.basename(scenarioPath).replace(/\.ya?ml$/i, ""));
+  try {
+    await runWebScenario({ scenario, url: args.url, logPath, screenshotDir: evidenceDir });
+  } catch (error) {
+    fs.writeFileSync(logPath, `OCQA_FLOW_RESULT:${JSON.stringify({ passed: false, name: scenario.name, kind: "scenario", total: scenario.steps.length, executed: 0, failed: 1, error: error.message || String(error) })}\n`);
+  }
+        flowLogs.push({ kind: "scenario", path: logPath });
+      }
+      for (const { contractPath, contract, execution } of selectedContracts) {
+  const stem = path.basename(contractPath).replace(/\.contract\.(?:ts|mts|mjs|js|json)$/i, "");
+  const logPath = path.join(os.tmpdir(), `tapp-ci-contract-${stem}-${Date.now()}.log`);
+  const evidenceDir = path.join(captureDir, "contracts", stem);
+  try {
+    if (execution.kind === "scenario") await runWebScenario({ scenario: execution, url: args.url, logPath, screenshotDir: evidenceDir });
+    else if (args.platform === "web") await runWebFlow({ flow: execution, url: args.url, logPath, screenshotDir: evidenceDir });
+    else await runAndroidFlow({ flow: execution, appId: args.appId, apkPath: undefined, serial: args.serial, logPath, screenshotDir: evidenceDir });
+  } catch (error) {
+    fs.writeFileSync(logPath, `OCQA_FLOW_RESULT:${JSON.stringify({ passed: false, name: contract.title, kind: "release-contract", contract: contract.name, criticality: contract.criticality, total: execution.steps.length, executed: 0, failed: 1, error: error.message || String(error) })}\n`);
+  }
+        flowLogs.push({ kind: "contract", path: logPath });
+      }
+
+      const reportArgs = [path.join(root, "mcp-server", "src", "ci-report.js"), "--markers", markers, "--platform", args.platform,
+        "--fail-on", args.failOn, "--html-dir", captureDir, "--label", args.url || args.appId];
+      if (args.targetKey) reportArgs.push("--target-key", args.targetKey);
+      if (args.baseline) reportArgs.push("--baseline", args.baseline);
+      if (args.jsonOut) reportArgs.push("--json-out", args.jsonOut);
+      if (args.mdOut) reportArgs.push("--md-out", args.mdOut);
+      if (args.prPlan) reportArgs.push("--pr-plan", args.prPlan);
+      if (args.prPlan && args.platform === "web" && args.projectDir) {
+        reportArgs.push("--project-dir", args.projectDir, "--maintenance-url", args.url);
+      }
+      for (const log of flowLogs) reportArgs.push(log.kind === "contract" ? "--contract-log" : log.kind === "scenario" ? "--scenario-log" : "--flow-log", log.path);
+      const report = spawnSync(process.execPath, reportArgs, { stdio: "inherit" });
+      exitCode = report.status ?? 1;
+    }
+  }
+} finally {
+  if (managedRuntime) {
+    await stopManagedWebTarget(managedRuntime);
+    console.error("🧹 Managed web target stopped.");
+  }
+}
+process.exit(exitCode);

package/scripts/pr-plan.js

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+// Portable PR planning entrypoint used by the local gate and GitHub Action.
+// It never invokes a shell, edits repository artifacts, or guesses ownership.
+import fs from "node:fs";
+import path from "node:path";
+import { buildPrContractPlan, changedFilesFromGit, changedSymbolEvidenceFromGit, prExplorationTargetsFromPlan, readChangedFilesFile } from "../mcp-server/src/pr-selection.js";
+
+const args = { contracts: [], head: "HEAD" };
+for (let index = 2; index < process.argv.length; index += 1) {
+  const key = process.argv[index];
+  const value = process.argv[++index];
+  if (key === "--project-dir") args.projectDir = value;
+  else if (key === "--platform") args.platform = value;
+  else if (key === "--base") args.base = value;
+  else if (key === "--head") args.head = value;
+  else if (key === "--changed-files-file") args.changedFilesFile = value;
+  else if (key === "--map") args.mapPath = value;
+  else if (key === "--contract") args.contracts.push(value);
+  else if (key === "--json-out") args.jsonOut = value;
+  else if (key === "--selection-out") args.selectionOut = value;
+  else if (key === "--exploration-target-out") args.explorationTargetOut = value;
+  else throw new Error(`Unknown argument: ${key}`);
+}
+if (!args.projectDir || !args.platform || !args.jsonOut) {
+  console.error("usage: pr-plan.js --project-dir DIR --platform ios|android|web (--base REF [--head REF] | --changed-files-file FILE) --json-out FILE [--contract FILE ...]");
+  process.exit(2);
+}
+try {
+  const changedFiles = args.changedFilesFile
+    ? readChangedFilesFile(args.changedFilesFile)
+    : changedFilesFromGit({ projectDir: args.projectDir, base: args.base, head: args.head });
+  const changedSymbolEvidence = args.changedFilesFile
+    ? []
+    : changedSymbolEvidenceFromGit({ projectDir: args.projectDir, base: args.base, head: args.head });
+  const plan = await buildPrContractPlan({
+    projectDir: args.projectDir,
+    platform: args.platform,
+    changedFiles,
+    changedSymbolEvidence,
+    mapPath: args.mapPath || "",
+    contractPaths: args.contracts,
+    discoverContracts: args.contracts.length === 0,
+  });
+  const output = path.resolve(args.jsonOut);
+  fs.mkdirSync(path.dirname(output), { recursive: true });
+  fs.writeFileSync(output, JSON.stringify(plan, null, 2) + "\n");
+  if (args.selectionOut) {
+    const root = fs.realpathSync(path.resolve(args.projectDir));
+    const selectedPaths = plan.selected.map((item) => {
+      const candidate = fs.realpathSync(path.resolve(root, item.path));
+      if (candidate !== root && !candidate.startsWith(root + path.sep)) throw new Error(`selected contract escapes project directory: ${item.path}`);
+      return candidate;
+    });
+    const selectionOutput = path.resolve(args.selectionOut);
+    fs.mkdirSync(path.dirname(selectionOutput), { recursive: true });
+    fs.writeFileSync(selectionOutput, JSON.stringify(selectedPaths, null, 2) + "\n");
+  }
+  if (args.explorationTargetOut) {
+    const targetOutput = path.resolve(args.explorationTargetOut);
+    fs.mkdirSync(path.dirname(targetOutput), { recursive: true });
+    const target = prExplorationTargetsFromPlan(plan, args.platform)[0] || null;
+    fs.writeFileSync(targetOutput, JSON.stringify(target, null, 2) + "\n");
+  }
+  console.log(`PR plan: ${plan.selected.length} selected, ${plan.skipped.length} skipped, ${plan.uncoveredChangedFiles.length} unknown file(s), ${plan.uncoveredUiMap.nodes.length + plan.uncoveredUiMap.edges.length} mapped coverage gap(s)`);
+} catch (error) {
+  console.error(error.message || String(error));
+  process.exit(2);
+}