Marcos Paulo
68 lines
2.7 KiB
Markdown
68 lines
2.7 KiB
Markdown
---
|
|
name: verify-contract
|
|
description:
|
|
Evolve scripts/verify.mjs across the Astro migration without losing coverage.
|
|
Use whenever a verify assertion fails because of a refactor, or when adding
|
|
checks for new architecture.
|
|
---
|
|
|
|
# The verification contract
|
|
|
|
Read [`../../context/verification.md`](../../context/verification.md) first.
|
|
|
|
`verify.mjs` has 42 assertions pinning real content and interactions. They are
|
|
the only thing preventing silent content loss during this migration, and they
|
|
will all break, because they assert against files that stop existing.
|
|
|
|
## The rule
|
|
|
|
**A failing assertion is a question, not a bug to delete.**
|
|
|
|
```
|
|
assertion fails
|
|
↓
|
|
does the user-visible fact it pins still exist?
|
|
├── yes → re-point the assertion at the new location
|
|
└── no → you deleted content. Put it back, or get sign-off.
|
|
```
|
|
|
|
`grep -c 'throw new Error' scripts/verify.mjs` must not decrease. If it must,
|
|
the `verification-engineer` writes a one-line reason per removal in the task
|
|
report. Nobody else may reduce coverage.
|
|
|
|
## Translating assertions
|
|
|
|
| Kind | Old | New |
|
|
| --------------------- | ------------------------------------ | ----------------------------------------------------------------------------- |
|
|
| Content presence | `html.includes('data-phase="plan"')` | same token, read from `dist/full-guide/index.html` |
|
|
| Implementation detail | `js.includes('renderTree')` | assert the rendered output has the tree UI, not that a function is named that |
|
|
| Asset version | `'app.js?v=20260904-vote-widget'` | assert the built HTML references a hashed asset |
|
|
|
|
Implementation-detail assertions are the dangerous ones: they _look_ deletable.
|
|
They are pinning a feature. Replace with an output-level assertion of the same
|
|
feature; never drop.
|
|
|
|
## Add the stronger check
|
|
|
|
Token matching cannot catch a dropped paragraph. Add rendered-text snapshots:
|
|
|
|
```bash
|
|
# before migrating
|
|
node .agents/scripts/snapshot-route.mjs http://localhost:4173/models/ > .agents/snapshots/models.txt
|
|
# after
|
|
node .agents/scripts/snapshot-route.mjs dist/models/index.html | diff .agents/snapshots/models.txt -
|
|
```
|
|
|
|
Commit the snapshots. They are the migration's regression net.
|
|
|
|
## Extend audit-ui.mjs
|
|
|
|
It rejects external `<script>`/`<link>` but **misses external URLs inside CSS**
|
|
— which is exactly how the broken Google Fonts `@font-face` in `styles.css:1`
|
|
got into a "dependency-free" site. Add:
|
|
|
|
```js
|
|
if (/@import|src:\s*url\(['"]?https?:|url\(['"]?https?:/i.test(css))
|
|
throw new Error(`${file} has an external CSS dependency`);
|
|
```
|