feat(engine): VERIFY-COMMAND — the one command a stranger has instead of CI
The forge has no Actions runners, so this org publishes no CI badge; the stated substitute is one command runnable from a clean clone. A repo with something runnable and no such command in its README is a WARN — and the finding names what the repo already has, so the remedy is one line. The subject is MEASURED, never read off a class. Five of 21 clones have nothing runnable at all and answer VERIFY-NONE at OK; they span plugin, shared-asset AND standalone, so every class-level phrasing of this rule would fail a correct repository somewhere. Measured: 10 document a command, 6 do not, 5 have no subject. Two things bound the rule. It adds no API call, so it has no SKIP at all — copying the null-input guard from every check since PIN-DEAD would print a false "not run". And it runs nothing, so its OK says documented, never passing. Not built, with distinct reasons recorded as invariants: RELEASE-ASSETS is rejected permanently for having NO SUBJECT (0 of 21 READMEs mention an asset download; the 18/18 fire rate is a proxy and must not be quoted as the reason). TAG-SIGNED is BLOCKED ON AN OPERATOR DECISION, not rejected — filing it with the rejections would read as settled when it is one yes/no from acquiring its whole subject. Also fixes this repo's own surface, which had drifted behind its engine: four checks had shipped without a row in the README check table, and Requirements still said "two network calls" after the third was added. 230 tests (from 213). Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LwZeAZ8cHmGZofM9dryuT9
This commit is contained in:
parent
0a4373c29b
commit
e00ed3340c
7 changed files with 449 additions and 14 deletions
49
README.md
49
README.md
|
|
@ -10,7 +10,7 @@ checks that surface in one repository and reports what it finds.
|
|||
|
||||
*AI-generated: all code produced by Claude Code through dialog-driven development.*
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
|
@ -41,12 +41,17 @@ a replacement for the two commands above:
|
|||
|
||||
## Requirements
|
||||
|
||||
Node 18 or newer. No dependencies. Two network calls: the org listing (for a
|
||||
repo's published description) and the catalog manifest (to confirm the install
|
||||
command resolves). Both read anonymously, so no token is needed, and `--offline`
|
||||
skips both — the checks that depended on them then report `SKIP`, not `OK`.
|
||||
Those land as `notRun` and clear on a networked re-run, so an offline pass is
|
||||
never a fully judged one.
|
||||
Node 18 or newer. No dependencies. Three API calls: the org listing (for a
|
||||
repo's published description), the catalog manifest (to confirm the install
|
||||
command resolves), and the repo's releases listing (to see the version page a
|
||||
stranger reads). Refs come over the git protocol instead — `git ls-remote
|
||||
--tags`, which does not spend the API budget — and a release is not a ref, which
|
||||
is why it is the one subject that needs a call of its own.
|
||||
|
||||
All of it reads anonymously, so no token is needed, and `--offline` skips every
|
||||
one — the checks that depended on them then report `SKIP`, not `OK`. Those land
|
||||
as `notRun` and clear on a networked re-run, so an offline pass is never a fully
|
||||
judged one.
|
||||
|
||||
## What it does
|
||||
|
||||
|
|
@ -63,6 +68,7 @@ The repository's **class** decides what each check means:
|
|||
| First screen | no H1 on line 1, or the line under it is not the published description. An H1 that merely differs from the repo name is a `WARN` — that is a naming choice, not a defect |
|
||||
| Install block | the form for this class is missing, incomplete, shown over `ssh://`, or points at the wrong marketplace |
|
||||
| Install truth | the plugin is not pinned in the catalog, so the documented command cannot succeed for anyone |
|
||||
| Install pins | a `@v…` or `--branch v…` in an install command names a tag the forge does not have, so the command a stranger copies 404s |
|
||||
| Required headings | `## Install`, `## Non-goals`, `## Changelog` — per class. Present at the wrong depth is its own finding |
|
||||
| Required files | a file this class (or trait) needs is absent |
|
||||
| Repo references | an `open/<name>` in URL position resolves to nothing |
|
||||
|
|
@ -73,6 +79,10 @@ The repository's **class** decides what each check means:
|
|||
| README language | the prose is not in the language this repo's readers were declared to speak |
|
||||
| Boilerplate | template text nobody filled in |
|
||||
| Version consistency | manifest, README badge, newest CHANGELOG entry and the git tag disagree |
|
||||
| Tag integrity | the newest tag is lightweight — movable without a trace, under a catalog that pins by tag. Older ones are exposed once as a count, because their only "fix" is force-moving a published ref |
|
||||
| Release current | the newest release the forge publishes is older than the newest tag it lists, so the version page shows a version older than the code. `WARN` — publishing a release for an existing tag moves nothing |
|
||||
| Remote sync | a tag exists only in this clone. The manifest can read as correctly tagged while no stranger can resolve the version |
|
||||
| Verify command | the repo has something runnable and the README shows no command to run it. With no CI badge in this org, that command is the only evidence a stranger gets |
|
||||
| Description | empty, or past the length bound |
|
||||
|
||||
Findings carry two independent things: a **level** (`ERROR`, `WARN`, `SKIP`,
|
||||
|
|
@ -114,9 +124,9 @@ catalog, an unregistered repo, a repo that has not been tagged yet.
|
|||
The summary line names only what someone has an action on:
|
||||
|
||||
```
|
||||
✓ portfolio-optimiser [standalone] — OK (repo-standard v0.9.0 @<sha>)
|
||||
✗ some-plugin [plugin] — ERROR · 2 not run (repo-standard v0.9.0 @<sha>)
|
||||
· stranger — SKIP · 1 not run (repo-standard v0.9.0 @<sha>)
|
||||
✓ portfolio-optimiser [standalone] — OK (repo-standard v0.10.0 @<sha>)
|
||||
✗ some-plugin [plugin] — ERROR · 2 not run (repo-standard v0.10.0 @<sha>)
|
||||
· stranger — SKIP · 1 not run (repo-standard v0.10.0 @<sha>)
|
||||
```
|
||||
|
||||
The deliberate ones are not silenced: they keep their own `NOT JUDGED` heading
|
||||
|
|
@ -186,6 +196,25 @@ A class turns the demand off with `readme_desc_match: false` in the register.
|
|||
The exemption is still reported as a finding that names the reason: an exception
|
||||
nobody can see is indistinguishable from a check that silently stopped running.
|
||||
|
||||
### One command, because there is no CI
|
||||
|
||||
The forge has no Actions runners registered. A green badge here would assert a
|
||||
run that never happens, which is the dishonest-badge finding one row up. The
|
||||
substitute this project publishes is one command a stranger can run from a clean
|
||||
clone, said plainly — so a repository with something runnable and no such command
|
||||
in its README is a `WARN`.
|
||||
|
||||
Two things bound it. It fires only where a subject was **measured**: a
|
||||
`scripts.test` entry, or a tracked file that is unambiguously an executable
|
||||
test. Five of the twenty-one clones have neither — they hold prose, output styles
|
||||
and domain packs — and they answer `VERIFY-NONE` at `OK`, because a check that
|
||||
ran and found nothing to judge has produced a verdict. Those five span three
|
||||
different classes, which is why the subject is measured and not read off a class.
|
||||
|
||||
And it can only ever fell a **missing** command. Nothing here runs anything, so a
|
||||
green line means documented, never passing. Measured across the org: six
|
||||
repositories have a suite their README never mentions.
|
||||
|
||||
### What is deliberately not required
|
||||
|
||||
`CONTRIBUTING.md`, `CODE_OF_CONDUCT.md` and `MAINTAINERS.md` are required by no
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue