@davidbyoung/software-factory 0.0.0-stage → 0.1.1
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.
- package/.claude-plugin/plugin.json +5 -0
- package/LICENSE +21 -0
- package/README.md +135 -2
- package/actions/factory-agent/action.yml +218 -0
- package/agents/factory-test-reviewer.md +129 -0
- package/agents/factory-ticket-readiness.md +107 -0
- package/agents/factory-ui-reviewer.md +160 -0
- package/bin/factory.js +45 -0
- package/bin/launch.js +67 -0
- package/dist/board.d.mts +128 -0
- package/dist/board.mjs +456 -0
- package/dist/build.d.mts +18 -0
- package/dist/build.mjs +60 -0
- package/dist/cli.d.mts +17 -0
- package/dist/cli.mjs +264 -0
- package/dist/code-host/github.d.mts +118 -0
- package/dist/code-host/github.mjs +419 -0
- package/dist/code-host/index.d.mts +9 -0
- package/dist/code-host/index.mjs +18 -0
- package/dist/code-host/types.d.mts +205 -0
- package/dist/code-host/types.mjs +12 -0
- package/dist/config.d.mts +166 -0
- package/dist/config.mjs +548 -0
- package/dist/deps.d.mts +32 -0
- package/dist/deps.mjs +126 -0
- package/dist/doctor.d.mts +34 -0
- package/dist/doctor.mjs +188 -0
- package/dist/guard-commit.d.mts +41 -0
- package/dist/guard-commit.mjs +209 -0
- package/dist/guard-permission.d.mts +15 -0
- package/dist/guard-permission.mjs +52 -0
- package/dist/guard-ticket-text.d.mts +27 -0
- package/dist/guard-ticket-text.mjs +288 -0
- package/dist/guard.d.mts +4 -0
- package/dist/guard.mjs +37 -0
- package/dist/init.d.mts +58 -0
- package/dist/init.mjs +556 -0
- package/dist/lib/clock.d.mts +14 -0
- package/dist/lib/clock.mjs +36 -0
- package/dist/lib/gh.d.mts +28 -0
- package/dist/lib/gh.mjs +92 -0
- package/dist/lib/glob.d.mts +2 -0
- package/dist/lib/glob.mjs +41 -0
- package/dist/lib/pricing.d.mts +25 -0
- package/dist/lib/pricing.mjs +77 -0
- package/dist/lib/usage.d.mts +34 -0
- package/dist/lib/usage.mjs +128 -0
- package/dist/lib/work-status.d.mts +251 -0
- package/dist/lib/work-status.mjs +510 -0
- package/dist/merge-policy.d.mts +66 -0
- package/dist/merge-policy.mjs +146 -0
- package/dist/parts.d.mts +39 -0
- package/dist/parts.mjs +138 -0
- package/dist/poller.d.mts +61 -0
- package/dist/poller.mjs +247 -0
- package/dist/pr-watch.d.mts +45 -0
- package/dist/pr-watch.mjs +244 -0
- package/dist/pr.d.mts +65 -0
- package/dist/pr.mjs +571 -0
- package/dist/review-cost.d.mts +18 -0
- package/dist/review-cost.mjs +95 -0
- package/dist/review-tools.d.mts +5 -0
- package/dist/review-tools.mjs +46 -0
- package/dist/review-verdict.d.mts +50 -0
- package/dist/review-verdict.mjs +171 -0
- package/dist/reviewers.d.mts +54 -0
- package/dist/reviewers.mjs +312 -0
- package/dist/runner/github-actions.d.mts +12 -0
- package/dist/runner/github-actions.mjs +97 -0
- package/dist/runner/index.d.mts +9 -0
- package/dist/runner/index.mjs +22 -0
- package/dist/runner/types.d.mts +60 -0
- package/dist/runner/types.mjs +7 -0
- package/dist/session-start.d.mts +20 -0
- package/dist/session-start.mjs +115 -0
- package/dist/site/capture.d.mts +44 -0
- package/dist/site/capture.mjs +114 -0
- package/dist/site/measure.d.mts +83 -0
- package/dist/site/measure.mjs +225 -0
- package/dist/site/pages.d.mts +10 -0
- package/dist/site/pages.mjs +71 -0
- package/dist/site/pixels.d.mts +47 -0
- package/dist/site/pixels.mjs +157 -0
- package/dist/site/servers.d.mts +47 -0
- package/dist/site/servers.mjs +141 -0
- package/dist/site.d.mts +60 -0
- package/dist/site.mjs +341 -0
- package/dist/status.d.mts +100 -0
- package/dist/status.mjs +514 -0
- package/dist/sync.d.mts +59 -0
- package/dist/sync.mjs +292 -0
- package/dist/ticket.d.mts +61 -0
- package/dist/ticket.mjs +562 -0
- package/dist/tickets/github.d.mts +128 -0
- package/dist/tickets/github.mjs +491 -0
- package/dist/tickets/index.d.mts +15 -0
- package/dist/tickets/index.mjs +27 -0
- package/dist/tickets/transport.d.mts +42 -0
- package/dist/tickets/transport.mjs +158 -0
- package/dist/tickets/types.d.mts +191 -0
- package/dist/tickets/types.mjs +76 -0
- package/docs/builds.md +227 -0
- package/docs/cli.md +221 -0
- package/docs/configuration.md +809 -0
- package/docs/design.md +106 -0
- package/docs/developing.md +400 -0
- package/docs/existing-repo.md +138 -0
- package/docs/github/reference.md +288 -0
- package/docs/github/setup.md +312 -0
- package/docs/glossary.md +106 -0
- package/docs/limitations.md +115 -0
- package/docs/plugins.md +192 -0
- package/docs/quick-start.md +222 -0
- package/docs/removing.md +76 -0
- package/docs/skills.md +270 -0
- package/docs/updating.md +108 -0
- package/docs/workflow.md +195 -0
- package/package.json +67 -4
- package/poller.Dockerfile +21 -0
- package/review.md +170 -0
- package/rules.md +313 -0
- package/settings.schema.json +411 -0
- package/skills/factory-address-review/SKILL.md +547 -0
- package/skills/factory-address-review/patch-coverage.py +68 -0
- package/skills/factory-build/SKILL.md +412 -0
- package/skills/factory-deps/SKILL.md +185 -0
- package/skills/factory-design/SKILL.md +159 -0
- package/skills/factory-diagnose/SKILL.md +93 -0
- package/skills/factory-mutate/SKILL.md +76 -0
- package/skills/factory-refine/SKILL.md +417 -0
- package/skills/factory-resolve-conflicts/SKILL.md +235 -0
- package/workflows/factory-board-sync.yml +91 -0
- package/workflows/factory-build.yml +72 -0
- package/workflows/factory-check.yml +37 -0
- package/workflows/factory-claude-review.yml +133 -0
- package/workflows/factory-conflicts.yml +69 -0
- package/workflows/factory-deps-auto-merge.yml +43 -0
- package/workflows/factory-deps.yml +59 -0
- package/workflows/factory-merge-policy.yml +121 -0
- package/workflows/factory-review-verdict.yml +54 -0
- package/workflows/factory-review.yml +75 -0
|
@@ -0,0 +1,159 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: factory-design
|
|
3
|
+
description: Design a visible change to a website, a new page or a redesign, as the designer rather than asking the owner to be one: real-content mockups built from the site itself, pictured at its widths in light and dark, reviewed before anyone sees them, and one recommended design. Use when asked to redesign, restyle, or rethink how a page looks or what it says, when an issue asks for renderings to approve, and as the `mockups` plug-in `factory-refine` calls.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Designing a change
|
|
7
|
+
|
|
8
|
+
The owner hired an expert. Decide what an expert would decide, and bring
|
|
9
|
+
them a recommendation, not a menu. Each round the owner has to spend
|
|
10
|
+
catching a defect or making a design call is a round this skill exists to
|
|
11
|
+
remove.
|
|
12
|
+
|
|
13
|
+
It works on any site whose `.claude/factory.yaml` has a `site` block:
|
|
14
|
+
`site.start` says how to build and serve it, and `factory site compare`
|
|
15
|
+
pictures it.
|
|
16
|
+
|
|
17
|
+
## 0. Is there a look to choose?
|
|
18
|
+
|
|
19
|
+
A mockup answers one question: which look does the owner want? When there
|
|
20
|
+
is one acceptable look, there is no question, and a mockup round spends
|
|
21
|
+
the owner's time on nothing. Before drawing, read the issue's acceptance
|
|
22
|
+
criteria and Decisions. Stop here, and say why, when:
|
|
23
|
+
|
|
24
|
+
- the criteria say the page must look the same at rest, or the change is
|
|
25
|
+
to targets, focus rings, contrast, or markup, and no Decision says the
|
|
26
|
+
look changes; or
|
|
27
|
+
- the only choice is one the design guide already makes; or
|
|
28
|
+
- the change is small ("Small changes" in `.claude/factory/rules.md`): its
|
|
29
|
+
pull request carries the built result, and that is the picture.
|
|
30
|
+
|
|
31
|
+
The proof for a change with no look to choose is not a picture of it. It
|
|
32
|
+
is `npx --no-install factory site compare` on the branch, whose
|
|
33
|
+
measurements and the site's own `checks` say whether anything got worse,
|
|
34
|
+
and, for a change to a state such as an open menu or keyboard focus, that
|
|
35
|
+
state measured as section 3 step 4 says. Say so in the report, so the
|
|
36
|
+
issue's acceptance criteria can name it.
|
|
37
|
+
|
|
38
|
+
## 1. Know the site before drawing
|
|
39
|
+
|
|
40
|
+
- **The design guide.** `npx --no-install factory config get
|
|
41
|
+
site.design-guide` names it. Read it first: its rules, each with its
|
|
42
|
+
check. When it prints `none`, the site has no guide: design from the
|
|
43
|
+
site's own pages, and say in the round that there was no guide.
|
|
44
|
+
- **The audience and the copy's rules.** They are in the project's own
|
|
45
|
+
instructions, which you have read already: who the visitors are, what
|
|
46
|
+
each should do next, and what copy must keep. When they say nothing about
|
|
47
|
+
the visitors, work it out from the site's pages, its home page first,
|
|
48
|
+
and say in the round what you took from them, so the owner can correct
|
|
49
|
+
it.
|
|
50
|
+
|
|
51
|
+
A design that breaks a rule of the guide names the rule and the reason
|
|
52
|
+
under "Decisions" in its issue, for the owner to approve.
|
|
53
|
+
|
|
54
|
+
Then write down, for yourself:
|
|
55
|
+
|
|
56
|
+
- the page's audiences and the one action each should take
|
|
57
|
+
- what a visitor needs to know, in the order they will want it
|
|
58
|
+
- what the page must prove about the business
|
|
59
|
+
- the existing element each new piece copies
|
|
60
|
+
|
|
61
|
+
## 2. Draft one design, in real content
|
|
62
|
+
|
|
63
|
+
- Use the site's real copy, counts, images, fonts, and colors. Write the
|
|
64
|
+
copy yourself; never leave "lorem" or a generic tagline for the owner to
|
|
65
|
+
fix.
|
|
66
|
+
- **A mockup is a real build of the change,** pictured by `factory site
|
|
67
|
+
compare` (section 3), so it carries the site's own styles. Markup put
|
|
68
|
+
into a running page is for posing a passing state only, such as an open
|
|
69
|
+
menu, with inline styles, never for the design itself: a stylesheet
|
|
70
|
+
built from the source may leave out a class the source has never used.
|
|
71
|
+
- **Nothing in a mockup misleads.** Sample text typed into one says
|
|
72
|
+
nothing false about the site's real content, since a made-up complaint
|
|
73
|
+
about a real page reads as a finding.
|
|
74
|
+
- **Every line of copy the Spec promises is in the mockup,** so no line
|
|
75
|
+
points at a picture that does not exist.
|
|
76
|
+
- Make the calls that have a conventional answer yourself: section order,
|
|
77
|
+
which button is primary, link and label styling, spacing, line length.
|
|
78
|
+
Say what you decided and why in one line each.
|
|
79
|
+
- Offer alternatives only where the choice is genuinely the owner's: brand
|
|
80
|
+
voice, which image, a headline that trades clarity for warmth. At most
|
|
81
|
+
three, each shown, with your pick marked.
|
|
82
|
+
|
|
83
|
+
## 3. Make the round
|
|
84
|
+
|
|
85
|
+
Each round, fix rounds included, is these steps in this order. Each
|
|
86
|
+
depends on the one before.
|
|
87
|
+
|
|
88
|
+
1. **A scratch worktree of the default branch**, and the change made in
|
|
89
|
+
it. Note what `git worktree list` shows first. From the checkout this
|
|
90
|
+
session works in, with the repository's default branch in place of
|
|
91
|
+
`main`:
|
|
92
|
+
|
|
93
|
+
```bash
|
|
94
|
+
git worktree add --detach ../mockup-SLUG origin/main
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
An option is its own worktree, made the same way. The change need not
|
|
98
|
+
be committed: the comparison pictures the worktree as it stands.
|
|
99
|
+
|
|
100
|
+
2. **Install it,** from the scratch worktree: `npm ci` where the
|
|
101
|
+
repository has a lock file, then each command `npx --no-install factory
|
|
102
|
+
config get build-setup` prints. The comparison installs the default
|
|
103
|
+
branch's side, not this one, and the factory, the browser, and
|
|
104
|
+
`site.start` all run from here.
|
|
105
|
+
3. **Picture it,** from the scratch worktree:
|
|
106
|
+
|
|
107
|
+
```bash
|
|
108
|
+
npx --no-install factory site compare --keep
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
It builds the change and the default branch, pictures every page at the
|
|
112
|
+
site's widths in light and dark, outlines what changed, measures each
|
|
113
|
+
changed view, and runs the site's own `checks`. It leaves both sites
|
|
114
|
+
running and prints their addresses. Its pictures are under the scratch
|
|
115
|
+
worktree's `node_modules/.cache/factory/site/`.
|
|
116
|
+
|
|
117
|
+
4. **Pose the states** the design is about, such as a menu open or a form
|
|
118
|
+
with an error, against the two addresses, as `factory-ui-reviewer`'s
|
|
119
|
+
step 3 says, in the same views. Pose each the same way in light and
|
|
120
|
+
dark, so a pair differs only in its scheme: the same content, any
|
|
121
|
+
randomness the page uses seeded, phone emulation for a phone view (so
|
|
122
|
+
no desktop scrollbar shows), and the pointer moved off the page. Picture
|
|
123
|
+
each state, and measure it the way the site's design guide says to
|
|
124
|
+
measure a posed state, when it says.
|
|
125
|
+
5. **Copy the round out** before anything else goes: the changed views'
|
|
126
|
+
pictures, the posed states' pictures, the comparison's lines, and each
|
|
127
|
+
posed state's measurements, into a folder git ignores in the checkout
|
|
128
|
+
this session works in, `node_modules/.cache/factory/design/` with the
|
|
129
|
+
time in its name.
|
|
130
|
+
6. **Review it,** as section 4 says, from that folder.
|
|
131
|
+
7. **Stop and clean up,** from the scratch worktree:
|
|
132
|
+
`npx --no-install factory site stop`, which ends both sites and removes
|
|
133
|
+
the default branch's worktree. Then, from the checkout this session
|
|
134
|
+
works in, `git worktree remove --force ../mockup-SLUG`, and check that
|
|
135
|
+
`git worktree list` shows what it showed before step 1.
|
|
136
|
+
|
|
137
|
+
A round that stops partway still runs step 7.
|
|
138
|
+
|
|
139
|
+
## 4. Review every round before anyone else sees it
|
|
140
|
+
|
|
141
|
+
1. Have `factory-ui-reviewer` read the round in its "From screenshots"
|
|
142
|
+
mode, handed the round's folder from step 5: the pictures, every
|
|
143
|
+
`measured:` line and `checks` line the comparison printed, and each
|
|
144
|
+
posed state's measurements. Fix every high and medium finding, or
|
|
145
|
+
record the break as a Decision, then make the round again.
|
|
146
|
+
2. Put the comparison's lines and what the reviewer found in the round you
|
|
147
|
+
send, quoted.
|
|
148
|
+
|
|
149
|
+
## 5. Present, then build
|
|
150
|
+
|
|
151
|
+
Show each mockup beside the current design, its before and after pictures
|
|
152
|
+
together, with the recommendation first and a short "what changed and
|
|
153
|
+
why". In a session with the owner, send the pictures rendered; in a
|
|
154
|
+
comment round, attach them. Every option offered to the owner is mocked;
|
|
155
|
+
an option with no picture is not offered. Ask only the question that
|
|
156
|
+
changes direction.
|
|
157
|
+
|
|
158
|
+
Once approved, the build makes it in code, and its pull request carries
|
|
159
|
+
`factory-ui-reviewer`'s pictures of the real page.
|
|
@@ -0,0 +1,93 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: factory-diagnose
|
|
3
|
+
description: Find the cause of a bug, a failing or flaky test, or a slowdown before changing any code, from one command that fails on the exact symptom. Use when something is broken, failing, flaky, or slow and the cause is not already known.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Diagnosing a bug
|
|
7
|
+
|
|
8
|
+
Reading code to build a theory before anything fails on demand is the
|
|
9
|
+
failure this skill prevents. A theory with no failing command behind it
|
|
10
|
+
gets a fix that fixes something else.
|
|
11
|
+
|
|
12
|
+
## 1. Build the loop
|
|
13
|
+
|
|
14
|
+
The loop is one command that fails on this bug and passes once it is
|
|
15
|
+
fixed. Everything after it only spends it, so spend the effort here.
|
|
16
|
+
Reach for the cheapest that gets to the symptom:
|
|
17
|
+
|
|
18
|
+
1. A unit test at the seam nearest the bug, run alone with the command
|
|
19
|
+
"After every code change" in `CLAUDE.md` gives. A decision buried in a component
|
|
20
|
+
moves into its `.ts` sibling first, as `AGENTS.md` prefers, where a
|
|
21
|
+
unit test reaches it without a DOM.
|
|
22
|
+
2. A script in the scratchpad that imports the module and calls it with
|
|
23
|
+
the failing input, run with `node`.
|
|
24
|
+
3. For a script under `scripts/`, the real invocation on a fixture input,
|
|
25
|
+
its output diffed against a known-good copy.
|
|
26
|
+
4. An end-to-end spec, when the symptom needs a browser, run alone and
|
|
27
|
+
repeated with the command "After every code change" in `CLAUDE.md`
|
|
28
|
+
gives. It builds the site first,
|
|
29
|
+
so it is the slowest loop; never `next dev`, which rewrites
|
|
30
|
+
`AGENTS.md`.
|
|
31
|
+
5. `git bisect run` with any of the above, when the bug arrived between
|
|
32
|
+
two known commits.
|
|
33
|
+
6. A CI failure that will not reproduce locally: read the failed job's log
|
|
34
|
+
(`npx --no-install factory pr failed N`), then close the gap between the two
|
|
35
|
+
environments one difference at a time (CI runs Playwright on 2
|
|
36
|
+
workers, against a fresh build, with `CI` set).
|
|
37
|
+
|
|
38
|
+
Then tighten it: faster (one file, one test, a filtered page), sharper (it
|
|
39
|
+
asserts the symptom the report names, not "did not throw"), and steadier
|
|
40
|
+
(`page.clock` or fake timers, a seeded `Math.random`).
|
|
41
|
+
|
|
42
|
+
**A flaky failure** needs a reproduction rate, not a clean repro. Repeat
|
|
43
|
+
it (`--repeat-each=50`, or `{ repeats: 50 }` on a Vitest test), and add
|
|
44
|
+
the load CI has, more workers or a second suite at once, until it fails
|
|
45
|
+
often enough to tell a fix from luck. A 1-in-100 flake cannot be
|
|
46
|
+
debugged; a 1-in-3 can.
|
|
47
|
+
|
|
48
|
+
**Done when** you can show the command and its output, already run, and
|
|
49
|
+
it fails on the symptom the report describes, gives the same verdict
|
|
50
|
+
every run (or a pinned rate for a flake), and runs unattended. When no
|
|
51
|
+
such command can be built, stop and say what was tried, and ask for what
|
|
52
|
+
would make one: a log, a recording, steps, or access.
|
|
53
|
+
|
|
54
|
+
## 2. Shrink it
|
|
55
|
+
|
|
56
|
+
Check that it fails on the reported symptom, not on a neighbor. Then cut
|
|
57
|
+
the input, the setup, and the steps one at a time, re-running after each
|
|
58
|
+
cut, until removing anything else makes it pass. What is left is the
|
|
59
|
+
regression test in step 5.
|
|
60
|
+
|
|
61
|
+
## 3. Rank hypotheses
|
|
62
|
+
|
|
63
|
+
Write three to five causes before testing any, each with the prediction
|
|
64
|
+
that would prove it: "if X is the cause, changing Y makes it pass." One
|
|
65
|
+
that predicts nothing is dropped. When the owner is in the session, show
|
|
66
|
+
the list before testing it, since they may rule one out at a glance;
|
|
67
|
+
otherwise go on.
|
|
68
|
+
|
|
69
|
+
## 4. Test them, one change at a time
|
|
70
|
+
|
|
71
|
+
Each probe tests one prediction. Prefer a breakpoint or a REPL to logs;
|
|
72
|
+
when logging, tag every line `[DEBUG-xxxx]` with one random tag, so
|
|
73
|
+
removing them is one grep. For a slowdown, measure before changing
|
|
74
|
+
anything (a timer, the profiler, Playwright's trace), and bisect against
|
|
75
|
+
the number.
|
|
76
|
+
|
|
77
|
+
## 5. Fix it
|
|
78
|
+
|
|
79
|
+
Turn the shrunk repro into a test at a seam that runs the real path the
|
|
80
|
+
bug took. Run it red before the fix, then green after, as
|
|
81
|
+
`tests/CLAUDE.md` says. When no seam reaches the bug, the test would pass
|
|
82
|
+
either way: say so in the pull request rather than ship it, and name the
|
|
83
|
+
decision that should move into a plain function.
|
|
84
|
+
|
|
85
|
+
Then run step 1's loop on the original, unshrunk case.
|
|
86
|
+
|
|
87
|
+
## 6. Clean up
|
|
88
|
+
|
|
89
|
+
- the original loop passes
|
|
90
|
+
- the regression test failed before the fix and passes after
|
|
91
|
+
- `git grep -n 'DEBUG-xxxx'` finds nothing
|
|
92
|
+
- scratch scripts stay in the scratchpad, not the repository
|
|
93
|
+
- the commit message names the cause the evidence confirmed
|
|
@@ -0,0 +1,76 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: factory-mutate
|
|
3
|
+
description: Prove a test can fail by breaking the code under test one way at a time and watching the test go red. Use for a new or changed test written after the code, or never seen failing on its own symptom, and when asked whether a test locks anything in.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Checking that a test can fail
|
|
7
|
+
|
|
8
|
+
A test that passes whether or not the fix is there has locked nothing in.
|
|
9
|
+
This has shipped more than once. The check is to break the code and watch
|
|
10
|
+
the test go red.
|
|
11
|
+
|
|
12
|
+
## 1. Pick the mutations
|
|
13
|
+
|
|
14
|
+
For each behavior the new tests claim to cover, write the smallest edit to
|
|
15
|
+
the **source** (never the test) that removes that behavior:
|
|
16
|
+
|
|
17
|
+
- delete the line that does it
|
|
18
|
+
- invert or drop a condition: `a && b` to `a`, `>` to `>=`
|
|
19
|
+
- return a constant: `return true`, `return []`, `return null`
|
|
20
|
+
- skip a call: `cleanup()`, `setState(x)`, `focus()`
|
|
21
|
+
|
|
22
|
+
One mutation per behavior, except where "Small changes" in `.claude/factory/rules.md`
|
|
23
|
+
says otherwise. A mutation that leaves the code
|
|
24
|
+
not compiling proves nothing; choose another.
|
|
25
|
+
|
|
26
|
+
## 2. Run them
|
|
27
|
+
|
|
28
|
+
Each one copies the file aside, applies the edit, runs only the relevant test
|
|
29
|
+
file, and restores the original whatever happens. Put the script in the
|
|
30
|
+
scratchpad, not the repo:
|
|
31
|
+
|
|
32
|
+
```python
|
|
33
|
+
import shutil, subprocess
|
|
34
|
+
|
|
35
|
+
MUTATIONS = [
|
|
36
|
+
# (source file, exact text, replacement, test file)
|
|
37
|
+
("lib/x.ts", "if (a && b)", "if (a)", "tests/x.test.ts"),
|
|
38
|
+
]
|
|
39
|
+
for path, old, new, test in MUTATIONS:
|
|
40
|
+
original = open(path).read()
|
|
41
|
+
assert original.count(old) == 1, (path, old)
|
|
42
|
+
try:
|
|
43
|
+
open(path, "w").write(original.replace(old, new))
|
|
44
|
+
failed = subprocess.run(["npx", "vitest", "run", test],
|
|
45
|
+
capture_output=True).returncode != 0
|
|
46
|
+
finally:
|
|
47
|
+
open(path, "w").write(original)
|
|
48
|
+
print("RED " if failed else "GREEN", path, old)
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
Use the project's own test command. For a coverage-instrumented runner,
|
|
52
|
+
disable coverage for speed. For Playwright, rebuild before each run if the
|
|
53
|
+
tests run against a build. Not `next dev`: it rewrites `AGENTS.md`, and a
|
|
54
|
+
test can time out there with nothing broken, which reads as red.
|
|
55
|
+
|
|
56
|
+
## 3. Confirm the tree is clean
|
|
57
|
+
|
|
58
|
+
```bash
|
|
59
|
+
git status --short
|
|
60
|
+
git diff --stat
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
Only the changes that were there before should show. If a source file is
|
|
64
|
+
still modified, restore it before doing anything else.
|
|
65
|
+
|
|
66
|
+
## 4. Act on the result
|
|
67
|
+
|
|
68
|
+
- **RED** for every mutation: report it in one line.
|
|
69
|
+
- **GREEN**: the test did not notice the behavior break. Either the test
|
|
70
|
+
asserts something else, the behavior is covered only by a slower suite, or
|
|
71
|
+
the test environment cannot reproduce the condition. Fix the test, or, when
|
|
72
|
+
the environment is the limit, move the decision into a plain function a
|
|
73
|
+
unit test can reach and test it there. Say which.
|
|
74
|
+
|
|
75
|
+
Never weaken a mutation to get a RED. If the honest mutation stays green, the
|
|
76
|
+
test is what needs work.
|