tripwire-e2e 0.0.0-stage → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (52) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +201 -3
  3. package/bin/tripwire.js +8 -0
  4. package/operators/_util.js +127 -0
  5. package/operators/agent-proposed.js +41 -0
  6. package/operators/auth-drop.js +30 -0
  7. package/operators/dead-control.js +23 -0
  8. package/operators/double-apply.js +20 -0
  9. package/operators/fake-success.js +21 -0
  10. package/operators/field-swap.js +42 -0
  11. package/operators/hide-control.js +30 -0
  12. package/operators/index.js +81 -0
  13. package/operators/item-drop.js +36 -0
  14. package/operators/item-dup.js +20 -0
  15. package/operators/label-swap.js +30 -0
  16. package/operators/missing-row-action.js +24 -0
  17. package/operators/number-drift.js +40 -0
  18. package/operators/rendered-item-drop.js +31 -0
  19. package/operators/rendered-item-dup.js +20 -0
  20. package/operators/rendered-number-drift.js +24 -0
  21. package/operators/silent-fail.js +19 -0
  22. package/operators/stale-read.js +34 -0
  23. package/operators/text-change.js +43 -0
  24. package/operators/validation-off.js +21 -0
  25. package/operators/wrong-link.js +28 -0
  26. package/operators/wrong-owner.js +41 -0
  27. package/package.json +41 -4
  28. package/policies/tripwire.clean.policy.yaml +23 -0
  29. package/policies/tripwire.mutant.policy.yaml +13 -0
  30. package/src/actions.js +59 -0
  31. package/src/agent.js +30 -0
  32. package/src/browser/mutate.js +156 -0
  33. package/src/browser/recorder.js +102 -0
  34. package/src/cli.js +41 -0
  35. package/src/commands/check.js +45 -0
  36. package/src/commands/coverage.js +110 -0
  37. package/src/commands/doctor.js +28 -0
  38. package/src/commands/fix.js +208 -0
  39. package/src/commands/list.js +24 -0
  40. package/src/commands/proxy.js +28 -0
  41. package/src/commands/report.js +11 -0
  42. package/src/commands/run.js +370 -0
  43. package/src/commands/sabotage.js +85 -0
  44. package/src/config.js +52 -0
  45. package/src/jsonpath.js +58 -0
  46. package/src/kane.js +158 -0
  47. package/src/ledger.js +53 -0
  48. package/src/mutant.js +26 -0
  49. package/src/orphans.js +40 -0
  50. package/src/profile.js +46 -0
  51. package/src/proxy.js +292 -0
  52. package/src/report.js +183 -0
package/src/agent.js ADDED
@@ -0,0 +1,30 @@
1
+ // Calls the coding agent headlessly. The prompt goes in on stdin, so no shell quoting is involved.
2
+ import { spawn } from 'node:child_process';
3
+
4
+ const AGENTS = {
5
+ claude: { cmd: 'claude', args: ['-p', '--permission-mode', 'acceptEdits', '--output-format', 'text'] },
6
+ codex: { cmd: 'codex', args: ['exec', '--full-auto', '-'] }
7
+ };
8
+
9
+ export function agentCommand(name) {
10
+ if (process.env.TRIPWIRE_AGENT_CMD) return { cmd: process.env.TRIPWIRE_AGENT_CMD, args: [], raw: true };
11
+ const a = AGENTS[name];
12
+ if (!a) throw new Error(`unknown agent "${name}" (use claude or codex, or set TRIPWIRE_AGENT_CMD)`);
13
+ return a;
14
+ }
15
+
16
+ export function runAgent(name, prompt, { cwd = process.cwd(), timeoutMs = 600000 } = {}) {
17
+ const { cmd, args, raw } = agentCommand(name);
18
+ return new Promise((resolve) => {
19
+ const shell = process.platform === 'win32' || raw;
20
+ const child = spawn(shell ? [cmd, ...args].join(' ') : cmd, shell ? [] : args, { cwd, shell, stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true, env: { ...process.env, TRIPWIRE_AGENT: '1' } });
21
+ let out = '';
22
+ let err = '';
23
+ child.stdout.on('data', (c) => (out += c));
24
+ child.stderr.on('data', (c) => (err += c));
25
+ const timer = setTimeout(() => child.kill(), timeoutMs);
26
+ child.on('close', (code) => { clearTimeout(timer); resolve({ code, stdout: out, stderr: err }); });
27
+ child.on('error', (e) => { clearTimeout(timer); resolve({ code: 127, stdout: out, stderr: String(e) }); });
28
+ child.stdin.end(prompt);
29
+ });
30
+ }
@@ -0,0 +1,156 @@
1
+ // Injected by the Tripwire proxy when an interface mutant is armed.
2
+ // window.__TW_MUTANT = { id, op, target: { role, text, count? }, ... } is set just before this script.
3
+ // The change is re-applied whenever the page re-renders, and the proxy is told once it really fired.
4
+ (function () {
5
+ var M = window.__TW_MUTANT;
6
+ if (!M || window.__twMutating) return;
7
+ window.__twMutating = true;
8
+ var fired = false;
9
+ var clean = function (s) { return (s || '').replace(/\s+/g, ' ').trim(); };
10
+ var ROLE_SEL = {
11
+ button: 'button, [role=button], input[type=submit], input[type=button]',
12
+ link: 'a[href]',
13
+ heading: 'h1, h2, h3',
14
+ text: '[role=status], .status, .badge, .tag, strong, label, p, span, td, dd, h1, h2, h3',
15
+ checkbox: 'input[type=checkbox]'
16
+ };
17
+ function report() {
18
+ if (fired) return;
19
+ fired = true;
20
+ try { navigator.sendBeacon('/_tw/fired', new Blob([JSON.stringify({ id: M.id })], { type: 'application/json' })); } catch (e) { /* ignore */ }
21
+ }
22
+ function find(target) {
23
+ // "[tag.class]" targets a control that has no visible text
24
+ var anon = /^\[([a-z0-9-]+)(?:\.([\w-]+))?\]$/i.exec(target.text || '');
25
+ if (anon) {
26
+ var els = Array.prototype.slice.call(document.querySelectorAll(anon[1] + (anon[2] ? '.' + anon[2] : '')));
27
+ return target.count ? (els[target.count - 1] ? [els[target.count - 1]] : []) : els;
28
+ }
29
+ var all = Array.prototype.slice.call(document.querySelectorAll(ROLE_SEL[target.role] || ROLE_SEL.text));
30
+ var re = target.pattern ? new RegExp(target.pattern) : null;
31
+ var hits = all.filter(function (el) {
32
+ var t = clean(el.innerText || el.value);
33
+ return re ? re.test(t) : t === target.text;
34
+ });
35
+ if (target.role === 'text') hits = hits.filter(function (el) { return !hits.some(function (o) { return o !== el && el.contains(o); }); });
36
+ if (target.count) return hits[target.count - 1] ? [hits[target.count - 1]] : [];
37
+ return hits;
38
+ }
39
+ function setText(el, text) {
40
+ if (el.tagName === 'INPUT') { el.value = text; return; }
41
+ // keep child elements (icons, badges) when the label is a single text node
42
+ var nodes = Array.prototype.filter.call(el.childNodes, function (n) { return n.nodeType === 3 && clean(n.nodeValue); });
43
+ if (nodes.length === 1 && el.children.length) nodes[0].nodeValue = text; else el.textContent = text;
44
+ }
45
+ var ops = {
46
+ 'hide': function () {
47
+ find(M.target).forEach(function (el) {
48
+ if (el.dataset.twDone) return;
49
+ el.dataset.twDone = '1';
50
+ el.style.setProperty('display', 'none', 'important');
51
+ report();
52
+ });
53
+ },
54
+ 'dead': function () {
55
+ find(M.target).forEach(function (el) {
56
+ if (el.dataset.twDone) return;
57
+ el.dataset.twDone = '1';
58
+ report();
59
+ });
60
+ },
61
+ 'swap-labels': function () {
62
+ var a = find(M.target), b = find(M.other);
63
+ a.forEach(function (el) { if (!el.dataset.twDone) { el.dataset.twDone = '1'; setText(el, M.other.text); report(); } });
64
+ b.forEach(function (el) { if (!el.dataset.twDone) { el.dataset.twDone = '1'; setText(el, M.target.text); report(); } });
65
+ },
66
+ 'replace-text': function () {
67
+ find(M.target).forEach(function (el) {
68
+ if (el.dataset.twDone) return;
69
+ el.dataset.twDone = '1';
70
+ setText(el, M.replacement);
71
+ report();
72
+ });
73
+ },
74
+ 'relink': function () {
75
+ find(M.target).forEach(function (el) {
76
+ if (el.dataset.twDone) return;
77
+ el.dataset.twDone = '1';
78
+ el.setAttribute('href', M.href);
79
+ report();
80
+ });
81
+ },
82
+ // A number shown on the page is off by one (works without any JSON API: SSR, local state).
83
+ // Re-applied after every re-render, but never twice to the same rendered value.
84
+ 'drift-number': function () {
85
+ find(M.target).forEach(function (el) {
86
+ var t = clean(el.innerText || el.value);
87
+ if (el.dataset.twWrote === t) return;
88
+ // +1 unit, keeping the decimals ("2" -> "3", "18.00" -> "19.00")
89
+ var next = t.replace(/\d+(?:\.\d+)?/, function (n) {
90
+ return (Number(n) + 1).toFixed((n.split('.')[1] || '').length);
91
+ });
92
+ if (next === t) return;
93
+ setText(el, next);
94
+ el.dataset.twWrote = clean(el.innerText || el.value);
95
+ report();
96
+ });
97
+ },
98
+ // A list row the user saw disappears, or shows twice (the in-page form of item-drop/item-dup).
99
+ 'hide-row': function () {
100
+ var el = find(M.target)[0];
101
+ var row = el && el.closest('li, tr');
102
+ if (!row || row.dataset.twDone) return;
103
+ row.dataset.twDone = '1';
104
+ row.style.setProperty('display', 'none', 'important');
105
+ report();
106
+ },
107
+ 'dup-row': function () {
108
+ var el = find(M.target)[0];
109
+ var row = el && el.closest('li, tr');
110
+ if (!row || row.dataset.twDone) return;
111
+ row.dataset.twDone = '1';
112
+ var copy = row.cloneNode(true);
113
+ row.parentNode.insertBefore(copy, row.nextSibling);
114
+ report();
115
+ },
116
+ 'remove-row-action': function () {
117
+ // the same lookup as everywhere else (text, pattern or "[tag.class]"), kept to the first row
118
+ var matching = find({ role: M.target.role, text: M.target.text, pattern: M.target.pattern });
119
+ var rows = document.querySelectorAll('tr, li');
120
+ for (var i = 0; i < rows.length; i++) {
121
+ var els = matching.filter(function (el) { return rows[i].contains(el); });
122
+ if (!els.length) continue;
123
+ if (rows[i].dataset.twDone) return;
124
+ rows[i].dataset.twDone = '1';
125
+ els.forEach(function (el) { el.remove(); });
126
+ report();
127
+ return; // first matching row only
128
+ }
129
+ }
130
+ };
131
+ if (M.op === 'dead') {
132
+ // swallow clicks on the dead control before the app's own handlers run
133
+ var swallow = function (ev) {
134
+ var el = ev.target && ev.target.closest && ev.target.closest('[data-tw-done]');
135
+ if (el && find(M.target).indexOf(el) !== -1) { ev.preventDefault(); ev.stopImmediatePropagation(); }
136
+ };
137
+ window.addEventListener('click', swallow, true);
138
+ window.addEventListener('submit', function (ev) {
139
+ var btn = ev.submitter;
140
+ if (btn && btn.dataset && btn.dataset.twDone) { ev.preventDefault(); ev.stopImmediatePropagation(); }
141
+ }, true);
142
+ }
143
+ var apply = ops[M.op];
144
+ if (!apply) return;
145
+ var busy = false;
146
+ var run = function () {
147
+ if (busy) return;
148
+ busy = true;
149
+ try { apply(); } finally { busy = false; }
150
+ };
151
+ var start = function () {
152
+ run();
153
+ new MutationObserver(run).observe(document.documentElement, { childList: true, subtree: true, characterData: true });
154
+ };
155
+ if (document.readyState === 'loading') document.addEventListener('DOMContentLoaded', start); else start();
156
+ })();
@@ -0,0 +1,102 @@
1
+ // Injected by the Tripwire proxy during the baseline run only.
2
+ // Reports which controls and texts each page showed and which ones the test clicked,
3
+ // so mutants can target things a test saw (visible) but never interacted with.
4
+ (function () {
5
+ if (window.__twRecorder) return;
6
+ window.__twRecorder = true;
7
+ var ENDPOINT = '/_tw/dom';
8
+ var clean = function (s) { return (s || '').replace(/\s+/g, ' ').trim().slice(0, 120); };
9
+ var roleOf = function (el) {
10
+ var t = el.tagName;
11
+ if (t === 'BUTTON' || el.getAttribute('role') === 'button' || (t === 'INPUT' && /submit|button/.test(el.type))) return 'button';
12
+ if (t === 'A' && el.hasAttribute('href')) return 'link';
13
+ if (/^H[1-3]$/.test(t)) return 'heading';
14
+ if (t === 'INPUT' && el.type === 'checkbox') return 'checkbox';
15
+ return 'text';
16
+ };
17
+ var visible = function (el) {
18
+ var r = el.getBoundingClientRect();
19
+ var cs = getComputedStyle(el);
20
+ return r.width > 0 && r.height > 0 && cs.visibility !== 'hidden' && cs.display !== 'none';
21
+ };
22
+ // A control without visible text (icon button, checkbox) is identified by tag and first class:
23
+ // "[input.toggle]". The mutator finds it again the same way.
24
+ var anonKey = function (el) {
25
+ var c = (typeof el.className === 'string' && el.className.trim().split(/\s+/)[0]) || '';
26
+ return '[' + el.tagName.toLowerCase() + (c ? '.' + c : '') + ']';
27
+ };
28
+ var textOf = function (el) {
29
+ if (el.tagName === 'INPUT' && /checkbox|radio/.test(el.type)) return clean(el.getAttribute('aria-label') || el.title) || anonKey(el);
30
+ return clean(el.innerText || (el.tagName === 'INPUT' ? el.value : '') || el.getAttribute('aria-label') || el.title) || (el.tagName === 'BUTTON' ? anonKey(el) : '');
31
+ };
32
+ // A row is named by its title (heading, label or link), else its first cell, else its first line.
33
+ var rowName = function (row) {
34
+ var t = row.querySelector('h1, h2, h3, h4, label, a[href]');
35
+ var cell = row.tagName === 'TR' ? row.querySelector('td, th') : null;
36
+ var s = (t && clean(t.innerText)) || (cell && clean(cell.innerText)) || clean((row.innerText || '').split(/\n|\t/)[0]);
37
+ return s.slice(0, 60);
38
+ };
39
+ var describe = function (el) {
40
+ var row = el.closest('tr, li');
41
+ return {
42
+ role: roleOf(el),
43
+ text: textOf(el),
44
+ row: row ? rowName(row) : undefined,
45
+ // the words around a short text ("3" inside "3 items left"), for readable descriptions
46
+ ctx: (el.parentElement && clean(el.innerText).length < 12) ? clean(el.parentElement.innerText).slice(0, 60) : undefined,
47
+ label: clean(el.getAttribute('aria-label')),
48
+ href: el.getAttribute('href') || undefined,
49
+ inRow: !!el.closest('tr, li'),
50
+ tag: el.tagName.toLowerCase(),
51
+ cls: (el.className && typeof el.className === 'string') ? el.className.slice(0, 60) : undefined
52
+ };
53
+ };
54
+ var SELECTOR = 'button, [role=button], a[href], input[type=submit], input[type=checkbox], label, h1, h2, h3, [role=status], .status, .badge, .tag, strong';
55
+ var queue = [];
56
+ var timer = null;
57
+ function snapshot() {
58
+ var controls = [];
59
+ var seen = {};
60
+ document.querySelectorAll(SELECTOR).forEach(function (el) {
61
+ if (el.closest('#__tw')) return;
62
+ if (!visible(el)) return;
63
+ var d = describe(el);
64
+ if (!d.text) return;
65
+ var k = d.role + '|' + d.text;
66
+ seen[k] = (seen[k] || 0) + 1;
67
+ d.count = seen[k];
68
+ controls.push(d);
69
+ });
70
+ queue.push({ kind: 'page', url: location.pathname + location.search + location.hash, controls: controls, text: clean(document.body ? document.body.innerText : '').length ? (document.body.innerText || '').slice(0, 20000) : '' });
71
+ flushSoon();
72
+ }
73
+ function flushSoon() {
74
+ clearTimeout(timer);
75
+ timer = setTimeout(flush, 300);
76
+ }
77
+ function flush() {
78
+ if (!queue.length) return;
79
+ var batch = queue.splice(0, queue.length);
80
+ var body = JSON.stringify({ events: batch });
81
+ try {
82
+ if (navigator.sendBeacon) navigator.sendBeacon(ENDPOINT, new Blob([body], { type: 'application/json' }));
83
+ else fetch(ENDPOINT, { method: 'POST', body: body, keepalive: true, headers: { 'content-type': 'application/json' } });
84
+ } catch (e) { /* recording must never break the page */ }
85
+ }
86
+ var snapTimer = null;
87
+ function scheduleSnapshot() { clearTimeout(snapTimer); snapTimer = setTimeout(snapshot, 250); }
88
+ document.addEventListener('click', function (ev) {
89
+ var el = ev.target && ev.target.closest && ev.target.closest(SELECTOR);
90
+ if (!el) return;
91
+ var d = describe(el);
92
+ queue.push({ kind: 'click', url: location.pathname + location.search + location.hash, control: d });
93
+ flushSoon();
94
+ }, true);
95
+ window.addEventListener('hashchange', scheduleSnapshot);
96
+ window.addEventListener('pagehide', function () { snapshot(); flush(); });
97
+ var start = function () {
98
+ scheduleSnapshot();
99
+ new MutationObserver(scheduleSnapshot).observe(document.documentElement, { childList: true, subtree: true, characterData: true });
100
+ };
101
+ if (document.readyState === 'loading') document.addEventListener('DOMContentLoaded', start); else start();
102
+ })();
package/src/cli.js ADDED
@@ -0,0 +1,41 @@
1
+ // Command-line entry. Subcommands are loaded lazily so `tripwire proxy` starts instantly.
2
+ import { parseArgs } from 'node:util';
3
+
4
+ const HELP = `tripwire: break the app on purpose to find out whether a green Kane suite means anything
5
+
6
+ Usage:
7
+ tripwire proxy --target <url> [--port 8080] run the fault-injecting proxy in front of an app
8
+ tripwire run [--tests <glob>] [--max-mutants 40] baseline, generate mutants, replay, score
9
+ tripwire fix [--agent claude|codex] [--max-attempts 3] strengthen tests for every survivor
10
+ tripwire sabotage [--agent claude|codex] ask the agent for domain-specific mutants
11
+ tripwire report rebuild the HTML report and badge
12
+ tripwire list show the mutant catalogue for the last baseline
13
+ tripwire check [--threshold 80] exit 1 if the score is below the threshold (for hooks)
14
+ tripwire coverage [--criteria ACCEPTANCE.md] acceptance criteria: owed, proven, or proven but unguarded
15
+ tripwire doctor [--kill] check kane-cli, login, and leftover Kane browsers
16
+
17
+ Run "tripwire <command> --help" for the options of one command.`;
18
+
19
+ export async function main(argv) {
20
+ const [cmd, ...rest] = argv;
21
+ if (!cmd || cmd === '--help' || cmd === '-h' || cmd === 'help') { console.log(HELP); return 0; }
22
+ if (cmd === '--version' || cmd === '-v') {
23
+ const { readFileSync } = await import('node:fs');
24
+ console.log(JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version);
25
+ return 0;
26
+ }
27
+ switch (cmd) {
28
+ case 'proxy': return (await import('./commands/proxy.js')).default(rest, parseArgs);
29
+ case 'run': return (await import('./commands/run.js')).default(rest, parseArgs);
30
+ case 'fix': return (await import('./commands/fix.js')).default(rest, parseArgs);
31
+ case 'sabotage': return (await import('./commands/sabotage.js')).default(rest, parseArgs);
32
+ case 'report': return (await import('./commands/report.js')).default(rest, parseArgs);
33
+ case 'list': return (await import('./commands/list.js')).default(rest, parseArgs);
34
+ case 'check': return (await import('./commands/check.js')).default(rest, parseArgs);
35
+ case 'coverage': return (await import('./commands/coverage.js')).default(rest, parseArgs);
36
+ case 'doctor': return (await import('./commands/doctor.js')).default(rest, parseArgs);
37
+ default:
38
+ console.error(`Unknown command "${cmd}".\n\n${HELP}`);
39
+ return 2;
40
+ }
41
+ }
@@ -0,0 +1,45 @@
1
+ // tripwire check: exit 1 when the latest score is below the threshold. Used by the Stop hook and CI.
2
+ import fs from 'node:fs';
3
+ import path from 'node:path';
4
+ import { loadConfig } from '../config.js';
5
+ import { readLedger, latest, lastRunId, score } from '../ledger.js';
6
+
7
+ const HELP = `tripwire check [--threshold 80] [--json] [--allow-suspected-equivalents]
8
+
9
+ exit 1 if the latest mutation score is below the threshold
10
+
11
+ --allow-suspected-equivalents for the pass/fail decision only, leave out survivors that Tripwire
12
+ flagged as suspected equivalents (they fired but no page ever
13
+ changed). The reported score still counts them.`;
14
+
15
+ // The score the gate decides on: optionally without flagged suspected equivalents.
16
+ export function gateScore(rows, allowSuspected) {
17
+ const kept = allowSuspected ? rows.filter((r) => !(r.status === 'survived' && r.suspectedEquivalent)) : rows;
18
+ return { ...score(kept), setAside: rows.length - kept.length };
19
+ }
20
+
21
+ export default async function check(argv, parseArgs) {
22
+ const { values } = parseArgs({ args: argv, options: { threshold: { type: 'string' }, dir: { type: 'string' }, json: { type: 'boolean' }, 'allow-suspected-equivalents': { type: 'boolean' }, help: { type: 'boolean', short: 'h' } } });
23
+ if (values.help) { console.log(HELP); return 0; }
24
+ const cfg = loadConfig();
25
+ const dir = path.resolve(values.dir || cfg.dir);
26
+ const threshold = Number(values.threshold ?? cfg.threshold);
27
+ const rows = readLedger(dir);
28
+ if (!rows.length) {
29
+ console.log('tripwire: no runs yet. Run `tripwire run` first.');
30
+ return 1;
31
+ }
32
+ const current = latest(rows, lastRunId(rows));
33
+ const s = score(current);
34
+ const g = gateScore(current, values['allow-suspected-equivalents']);
35
+ const survivors = current.filter((r) => r.status === 'survived' || r.status === 'masked');
36
+ const ok = g.score !== null && g.score >= threshold;
37
+ if (values.json) console.log(JSON.stringify({ ok, threshold, ...s, gateScore: g.score, setAside: g.setAside, survivors: survivors.map((r) => r.describe) }));
38
+ else {
39
+ console.log(`tripwire: score ${s.score ?? '-'}% (threshold ${threshold}%) · killed ${s.killed} · survived ${s.survived} · masked ${s.masked}`);
40
+ if (g.setAside) console.log(` gate: ${g.score ?? '-'}% with ${g.setAside} suspected equivalent(s) set aside (--allow-suspected-equivalents)`);
41
+ if (!ok) for (const r of survivors.filter((r) => !(values['allow-suspected-equivalents'] && r.suspectedEquivalent)).slice(0, 8)) console.log(` - not caught: ${r.describe}`);
42
+ }
43
+ if (fs.existsSync(path.join(dir, 'report', 'index.html')) && !values.json) console.log(` report: ${path.join(dir, 'report', 'index.html')}`);
44
+ return ok ? 0 : 1;
45
+ }
@@ -0,0 +1,110 @@
1
+ // tripwire coverage: a third state on top of Kane's "proven vs owed".
2
+ // owed no test checks the criterion
3
+ // proven its tests pass on the real app and caught every mutant that broke it
4
+ // proven but unguarded its tests pass, but a mutant that broke the criterion got past them
5
+ // The agent maps criteria to tests and mutants to criteria (written to .tripwire/criteria.json,
6
+ // reviewable and editable); the states are computed from the ledger. When the project has a Kane
7
+ // assurance store (.context/), Kane's own per-criterion status is shown alongside.
8
+ import fs from 'node:fs';
9
+ import path from 'node:path';
10
+ import { loadConfig, findTests } from '../config.js';
11
+ import { readLedger, latest, lastRunId } from '../ledger.js';
12
+ import { runAgent } from '../agent.js';
13
+ import { runKane } from '../kane.js';
14
+ import { writeReport } from '../report.js';
15
+
16
+ const HELP = `tripwire coverage [options]
17
+
18
+ --criteria <file> acceptance criteria with ids like AC1, AC2 (default ACCEPTANCE.md)
19
+ --remap ask the agent to rebuild .tripwire/criteria.json
20
+ --agent claude|codex which agent maps criteria (default from config)
21
+ --dir <path> state directory (default .tripwire)`;
22
+
23
+ export function parseCriteria(md) {
24
+ const out = [];
25
+ for (const m of md.matchAll(/^\s*[-*]?\s*(AC\d+)[.:)]\s*(.+)$/gm)) out.push({ id: m[1], text: m[2].trim() });
26
+ return out;
27
+ }
28
+
29
+ // Pure: compute each criterion's state from the mapping and the ledger rows.
30
+ export function computeCoverage(criteria, mapping, rows, kaneStatus = {}) {
31
+ const testsFor = mapping.criteria || {};
32
+ const mutantsFor = {};
33
+ for (const [mid, acs] of Object.entries(mapping.mutants || {})) for (const ac of [].concat(acs)) (mutantsFor[ac] ||= []).push(mid);
34
+ const byId = new Map(rows.map((r) => [r.id, r]));
35
+ return criteria.map((c) => {
36
+ const tests = testsFor[c.id] || [];
37
+ const related = (mutantsFor[c.id] || []).map((id) => byId.get(id)).filter(Boolean).filter((r) => r.status !== 'not-reached' && r.status !== 'error');
38
+ const escaped = related.filter((r) => r.status === 'survived' || r.status === 'masked');
39
+ const caught = related.filter((r) => r.status === 'killed');
40
+ let state;
41
+ if (!tests.length) state = 'owed';
42
+ else if (escaped.length) state = 'proven but unguarded';
43
+ else if (caught.length) state = 'proven and guarded';
44
+ else state = 'proven, untested by mutants';
45
+ return {
46
+ id: c.id, criterion: `${c.id}. ${c.text}`, tests, state,
47
+ kane: kaneStatus[c.id] || (tests.length ? 'green (tests pass)' : 'owed'),
48
+ caught: caught.map((r) => r.describe), escaped: escaped.map((r) => r.describe)
49
+ };
50
+ });
51
+ }
52
+
53
+ async function kaneCover(cwd) {
54
+ if (!fs.existsSync(path.join(cwd, '.context'))) return {};
55
+ const r = await runKane(['cover', '--json'], { cwd, killAfterMs: 120000 });
56
+ const status = {};
57
+ try {
58
+ const doc = JSON.parse(r.stdout.slice(r.stdout.indexOf('{')));
59
+ JSON.stringify(doc, (k, v) => { if (v && typeof v === 'object' && /^AC\d+$/i.test(v.ac_ref || v.ref || '') && v.execution) status[(v.ac_ref || v.ref).toUpperCase()] = v.execution; return v; });
60
+ } catch { /* no usable Kane coverage */ }
61
+ return status;
62
+ }
63
+
64
+ export default async function coverage(argv, parseArgs) {
65
+ const { values } = parseArgs({ args: argv, options: { criteria: { type: 'string' }, remap: { type: 'boolean' }, agent: { type: 'string' }, dir: { type: 'string' }, help: { type: 'boolean', short: 'h' } } });
66
+ if (values.help) { console.log(HELP); return 0; }
67
+ const cfg = loadConfig();
68
+ const dir = path.resolve(values.dir || cfg.dir);
69
+ const critFile = values.criteria || 'ACCEPTANCE.md';
70
+ if (!fs.existsSync(critFile)) throw new Error(`no acceptance criteria at ${critFile}`);
71
+ const criteria = parseCriteria(fs.readFileSync(critFile, 'utf8'));
72
+ if (!criteria.length) throw new Error(`${critFile} has no criteria in the form "AC1. ..."`);
73
+ const rowsAll = readLedger(dir);
74
+ if (!rowsAll.length) throw new Error('no ledger yet: run `tripwire run` first');
75
+ const rows = latest(rowsAll, lastRunId(rowsAll));
76
+ const mapFile = path.join(dir, 'criteria.json');
77
+
78
+ if (values.remap || !fs.existsSync(mapFile)) {
79
+ const tests = findTests(cfg.tests);
80
+ const prompt = `Map acceptance criteria to end-to-end tests and to planted bugs. Write JSON to ${mapFile}:
81
+ { "criteria": { "AC1": ["tests/x_test.md", ...], ... }, "mutants": { "<mutant id>": ["AC3", ...], ... } }
82
+ - criteria: for each AC, the test files that contain a step which actually CHECKS that criterion (a "Verify ..." of its outcome). A test that only passes through a page does not count. Use [] when no test checks it.
83
+ - mutants: for each mutant id below, the ACs that the bug breaks. Use [] when it breaks none.
84
+ Be strict and literal. Do not edit any other file.
85
+
86
+ ----- Acceptance criteria -----
87
+ ${criteria.map((c) => `${c.id}. ${c.text}`).join('\n')}
88
+
89
+ ----- Tests -----
90
+ ${tests.map((t) => `# ${t}\n${fs.readFileSync(t, 'utf8')}`).join('\n\n')}
91
+
92
+ ----- Mutants (id: what breaks) -----
93
+ ${rows.map((r) => `${r.id}: ${r.describe}`).join('\n')}
94
+
95
+ Reply with "done" when the file is written.`;
96
+ fs.writeFileSync(path.join(dir, 'coverage_prompt.txt'), prompt);
97
+ console.log(`Asking ${values.agent || cfg.agent} to map ${criteria.length} criteria to tests and mutants...`);
98
+ const r = await runAgent(values.agent || cfg.agent, prompt);
99
+ if (r.code === 127) throw new Error(`could not start the agent CLI: ${r.stderr.trim()}`);
100
+ if (!fs.existsSync(mapFile)) throw new Error(`the agent did not write ${mapFile}; its reply: ${r.stdout.slice(-500)}`);
101
+ }
102
+ const mapping = JSON.parse(fs.readFileSync(mapFile, 'utf8'));
103
+ const result = computeCoverage(criteria, mapping, rows, await kaneCover(process.cwd()));
104
+ fs.writeFileSync(path.join(dir, 'coverage.json'), JSON.stringify(result, null, 2));
105
+ const count = (s) => result.filter((x) => x.state === s).length;
106
+ for (const x of result) console.log(` ${x.state.padEnd(28)} ${x.criterion.slice(0, 90)}${x.escaped.length ? `\n${' '.repeat(32)}got past: ${x.escaped.join('; ')}` : ''}`);
107
+ console.log(`\n${criteria.length} criteria: ${count('proven and guarded')} proven and guarded · ${count('proven but unguarded')} proven but unguarded · ${count('proven, untested by mutants')} proven, no mutant touched them · ${count('owed')} owed`);
108
+ writeReport(dir);
109
+ return 0;
110
+ }
@@ -0,0 +1,28 @@
1
+ // tripwire doctor: environment checks that have bitten real runs.
2
+ import { findOrphanKaneBrowsers, killKaneBrowser } from '../orphans.js';
3
+ import { runKane } from '../kane.js';
4
+
5
+ export default async function doctor(argv, parseArgs) {
6
+ const { values } = parseArgs({ args: argv, options: { kill: { type: 'boolean' }, 'min-age': { type: 'string' }, help: { type: 'boolean', short: 'h' } } });
7
+ if (values.help) { console.log('tripwire doctor [--kill] [--min-age 120]\n\nChecks kane-cli and lists Kane Chrome browsers left over from earlier runs (older than --min-age minutes). --kill stops them.'); return 0; }
8
+ let problems = 0;
9
+ const v = await runKane(['--version'], { killAfterMs: 30000 });
10
+ if (v.code !== 0) { console.log('✗ kane-cli not found: npm install -g @testmuai/kane-cli'); problems++; }
11
+ else console.log(`✓ kane-cli ${v.stdout.trim().split('\n').pop()}`);
12
+ if (/runtime not found|runtime package missing/i.test(v.stderr + v.stdout)) {
13
+ console.log('✗ kane-cli is missing its platform packages (a download probably failed). Reinstall: npm install -g @testmuai/kane-cli');
14
+ problems++;
15
+ }
16
+ const w = await runKane(['whoami'], { killAfterMs: 30000 });
17
+ if (!/Authenticated|valid/i.test(w.stdout)) { console.log('✗ not logged in: kane-cli login'); problems++; } else console.log('✓ logged in to Kane');
18
+ const orphans = findOrphanKaneBrowsers(Number(values['min-age'] || 120));
19
+ if (!orphans.length) console.log('✓ no leftover Kane browsers');
20
+ else {
21
+ problems++;
22
+ console.log(`✗ ${orphans.length} Kane browser(s) left over from earlier runs (they can change a shared app's state):`);
23
+ for (const o of orphans) console.log(` pid ${o.pid}, ${Math.round(o.ageMinutes / 60)} h old, profile ${o.profile}`);
24
+ if (values.kill) { for (const o of orphans) killKaneBrowser(o.profile); console.log(' stopped.'); problems--; }
25
+ else console.log(' stop them with: tripwire doctor --kill');
26
+ }
27
+ return problems ? 1 : 0;
28
+ }