docs: run only the test legs a change can break
A new rule in CLAUDE.md: weigh which legs the change touches, run each once when its input is final, no up-front baseline round. Reclaimed the four lines it costs by tightening the commit-message and documenting-a-change rules. Claude-Session: https://claude.ai/code/session_01Wzs2qG6Y5qm7mKmJHfu44G
This commit is contained in:
1 parent
fd82080115
commit
280726f730
1 file changed
+15
-15
@@ -27,12 +27,9 @@ node scripts/showcase/run.mjs # rebuild docs/showcase/ (sample .odt/.docx +
|
|||||||
```
|
```
|
||||||
|
|
||||||
Tests live in `tests/` (outside `src/`, so `svelte-check` ignores them), jsdom via Vitest.
|
Tests live in `tests/` (outside `src/`, so `svelte-check` ignores them), jsdom via Vitest.
|
||||||
`roundtrip.test.ts` covers the ODF export↔import round trip + a foreign-doc/style-resolver leg;
|
`roundtrip.test.ts` covers the ODF export↔import round trip + a foreign-doc/style-resolver leg; `lo-roundtrip.test.ts` re-saves through LibreOffice and `lo-fuzz.test.ts` reads the fuzz seeds back through it (`LO_SEEDS`, `LO_DUMP=<file>` for triage) — both **self-skip** without `soffice`, so `npm test`/CI stay green;
|
||||||
`lo-roundtrip.test.ts` re-saves through LibreOffice and `lo-fuzz.test.ts` reads the fuzz seeds back through it (`LO_SEEDS`, `LO_DUMP=<file>` for triage) — both **self-skip** without `soffice`, so `npm test`/CI stay green;
|
`corpus.test.ts` round-trips the committed `tests/corpus/` documents (by `make-fixtures.mjs` + Word re-saves in `corpus/word/`, never our exporter); `fuzz-roundtrip.test.ts` round-trips seeded random documents under random export options (`fuzzDoc.ts`, `fuzzOptions.ts`) through both formats and validates every export against the schemas (`schemaValidate.ts`; `FUZZ_SEEDS=500` widens it);
|
||||||
`corpus.test.ts` round-trips the committed `tests/corpus/` documents (by `make-fixtures.mjs` + Word re-saves in `corpus/word/`, never our exporter);
|
`schema-validation.test.ts` validates the `kitchenSink.ts` exports against the vendored schemas in `tests/schemas/` (self-skips without `xmllint`); `package-lint.test.ts` checks the semantic invariants schemas can't express (unique ids, dangling references); `tests/unit/` holds fast helper tests; the five browser runs (`tests/smoke/`, `tests/dom/`, `tests/layout/`, `tests/monkey/`, `tests/tabs/`) share `tests/browser.mjs`. All test tooling stays a `devDependency`. No linter/formatter. CI (`.github/workflows/ci.yml`) runs `check` + `test`.
|
||||||
`fuzz-roundtrip.test.ts` round-trips seeded random documents under random export options (`fuzzDoc.ts`, `fuzzOptions.ts`) through both formats and validates every export against the schemas (`schemaValidate.ts`; `FUZZ_SEEDS=500` widens it);
|
|
||||||
`schema-validation.test.ts` validates the `kitchenSink.ts` exports against the vendored schemas in `tests/schemas/` (self-skips without `xmllint`); `package-lint.test.ts` checks the semantic invariants schemas can't express (unique ids, dangling references); `tests/unit/` holds fast helper tests;
|
|
||||||
the five browser runs (`tests/smoke/`, `tests/dom/`, `tests/layout/`, `tests/monkey/`, `tests/tabs/`) share `tests/browser.mjs`. All test tooling stays a `devDependency`. No linter/formatter. CI (`.github/workflows/ci.yml`) runs `check` + `test`.
|
|
||||||
|
|
||||||
## Rules
|
## Rules
|
||||||
|
|
||||||
@@ -42,13 +39,12 @@ the five browser runs (`tests/smoke/`, `tests/dom/`, `tests/layout/`, `tests/mon
|
|||||||
- **Never describe how the current code differs from an older version** (no "previously…", "this used to…", "changed from…"). Comment only what the current code does and why — git history covers the rest.
|
- **Never describe how the current code differs from an older version** (no "previously…", "this used to…", "changed from…"). Comment only what the current code does and why — git history covers the rest.
|
||||||
- **Don't use Word as a placeholder for "a word processor".** Where LibreOffice does the same thing, describe the behaviour itself ("the caret moves", "the zone auto-grows") instead of "Word-style" / "like Word" / "as in Word". Name a product only where the statement really is about that product: its file format (`w:tblLook`, DOCX), or a quirk only it has — then name both if both apply.
|
- **Don't use Word as a placeholder for "a word processor".** Where LibreOffice does the same thing, describe the behaviour itself ("the caret moves", "the zone auto-grows") instead of "Word-style" / "like Word" / "as in Word". Name a product only where the statement really is about that product: its file format (`w:tblLook`, DOCX), or a quirk only it has — then name both if both apply.
|
||||||
|
|
||||||
**Commit messages** — a clear description, never an essay: a subject line plus **at most ~8
|
**Commit messages** — a subject line plus **at most ~8 lines**, however large the change. Probed
|
||||||
lines**, however large the change. Probed behaviour, measurements and rationale lists belong
|
behaviour, measurements and rationale belong in `docs/architecture/` or the nearest `CLAUDE.md`.
|
||||||
in `docs/architecture/` or the nearest `CLAUDE.md`, not repeated in the history.
|
|
||||||
|
|
||||||
**IMPORTANT: no real-world document's name anywhere in the repo, and a commit message
|
**IMPORTANT: no real-world document's name anywhere in the repo, and a commit message names no
|
||||||
names no document at all** — not even "the thesis": describe the fix and its measurement,
|
document at all** — not even "the thesis": describe the fix and its measurement, never the file it
|
||||||
never the file it helped. Detail in `tests/render-parity/README.md`.
|
helped. Detail in `tests/render-parity/README.md`.
|
||||||
|
|
||||||
**IMPORTANT: never introduce a default only this editor has.** Both importers suppress values equal
|
**IMPORTANT: never introduce a default only this editor has.** Both importers suppress values equal
|
||||||
to the defaults, so an editor-only default is indistinguishable from a failed style resolution and
|
to the defaults, so an editor-only default is indistinguishable from a failed style resolution and
|
||||||
@@ -68,15 +64,19 @@ silently lands in every imported document as direct formatting. The defaults fol
|
|||||||
fetches an x86-64 Chrome that cannot run on arm64). Recipe and the three-engine CI matrix in
|
fetches an x86-64 Chrome that cannot run on arm64). Recipe and the three-engine CI matrix in
|
||||||
`docs/headless-testing.md`; driving the live app is the only way to verify rendering or NodeViews.
|
`docs/headless-testing.md`; driving the live app is the only way to verify rendering or NodeViews.
|
||||||
|
|
||||||
|
**Running tests** — weigh which legs the change can actually break and run only those: `npm test`
|
||||||
|
(or the one file) for logic, the LO legs for export/import, the browser runs for rendering,
|
||||||
|
`test:parity` for layout. Each leg once, at the point its input is final — no up-front baseline
|
||||||
|
round, no re-run of a leg that is still green.
|
||||||
|
|
||||||
**Naming** — components `PascalCase.svelte`, every `.ts` module `camelCase`; extension files are
|
**Naming** — components `PascalCase.svelte`, every `.ts` module `camelCase`; extension files are
|
||||||
named by feature (`image.ts`, `indent.ts`), not `XyzExtension.ts`.
|
named by feature (`image.ts`, `indent.ts`), not `XyzExtension.ts`.
|
||||||
|
|
||||||
**Documenting a change** — a feature that changes how this codebase behaves gets documented where
|
**Documenting a change** — a feature that changes how this codebase behaves gets documented where
|
||||||
it loads on demand, not here. **This file** only grows for a new command, a new hard rule, or a new
|
it loads on demand, not here. **This file** only grows for a new command, a new hard rule, or a new
|
||||||
top-level directory; everything else is one line in the nearest directory `CLAUDE.md`, or a section
|
top-level directory; everything else is one line in the nearest directory `CLAUDE.md`, or a section
|
||||||
in its `docs/architecture/` file. Write only what the code can't say — probed Word/LibreOffice
|
in its `docs/architecture/` file. Write only what the code can't say — probed behaviour, sentinel
|
||||||
behaviour, sentinel order, constants that must agree across files. Keep this file under 120 lines:
|
order, cross-file constants. Keep this file under 120 lines: a section past ~5 lines moves out.
|
||||||
a section growing past ~5 lines belongs somewhere else.
|
|
||||||
|
|
||||||
## Source layout
|
## Source layout
|
||||||
|
|
||||||
|
|||||||
Reference in new issue
Block a user