docs: describe the package that exists, and give each subsystem its rule - #5
Conversation
CLAUDE.md still opened with "the barrels are empty on purpose", which stopped being true several releases of work ago: the barrels now carry three service contracts, the drivers behind them, the entitlement model and its vocabulary enums, and a three-command CLI. A contributor reading the file was told the tree was empty and then found 31 source files. The Rules section had the matching gap. It said a rule arrives with the subsystem it governs and that at 0.0.1 this meant tests.md alone, with the drivers, the manager and the CLI getting theirs when they got their code. They have code. The section now names the four rules that exist. The unreleased status is restated rather than dropped, because it is the part that is still true and still load-bearing downstream: nothing is on pub.dev, so a package naming magic_payments resolves only through a local override.
…s they earned Three rules, following the convention CLAUDE.md already states: a rule arrives with the subsystem it governs. None of them restate a docblock. The source in this package carries the reasoning for a given class and carries it well; what it cannot carry is the invariant that spans a directory, which is the thing that gets broken by somebody who opened one file. - contracts.md: why the three-contract split cannot absorb a fourth method, why a rail must never grow an isAvailable, the literals-not-.name rule for every wire vocabulary, and the test a new enum's fallback member has to pass (say out loud what that member claims). - drivers.md: the three-arm import graph and what dropping the dart:io guard costs, why the factory docblocks describe the guard strings without naming them (the raw-source count test), and why the stub throws rather than answering empty. - cli.md: the one-tool MCP policy as policy, manifest-only install, idempotence as a property of the construction rather than a guard, and the aliased DoctorCommand import. Verified against the source rather than written from the docblocks: boot modes read from the command files, the avoid_print scope read from analysis_options.yaml, the guard-count test read from test/drivers/billing_service_factory_test.dart.
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
|
Note Kodizm (AI-generated). May contain mistakes; verify before acting. Documentation-only, and the claims hold up against the source I checked - one paragraph in Major
Minor
What I verified
TestsNone expected or needed; no source file is touched. Checks I ran
|
The Command shape section described `name` / `description` / `boot` plus argument parsing in `configure(ArgParser)`. That is dusk's shape, carried over by hand rather than read out of this package. Verified against the source: `grep -rn "configure(|ArgParser|String get name" lib/src/cli/commands/*.dart` returns nothing. These commands declare a `signature` string with the flags embedded in the artisan DSL and read them back with `ctx.input.option(...)`. A contributor following the old text would have written a fourth command against an API that does not exist, which is the one failure a rules file is supposed to prevent rather than cause. Also: the `avoid_print` note quoted an intent the comment does not carry (the real one is `# CLI tools legitimately use print`), and the `ArtisanInstallCommand` boot claim now cites where it is declared, since it is in another repository and the reviewer could not resolve it.
|
Note Kodizm (AI-generated). May contain mistakes; verify before acting. The one new commit fixes both findings from my last review; the rewritten "Command shape" section now matches the source line for line. Since Minor
What I verified
TestsDocumentation only; no source file touched in this commit or the pull request. Checks I ran
|
… them `install` extends ArtisanInstallCommand and declares signature, description and pluginName; it has no `boot` override, it inherits one. Only `configure` and `doctor` declare all three. The paragraph two below already said this correctly, so the section was contradicting itself within ten lines. Now the opening states what every command declares and the split by base class right after it.
|
Note Kodizm (AI-generated). May contain mistakes; verify before acting. The one new commit fixes the last remaining Minor; the "Command shape" paragraph now matches all three commands. Since What I verified
TestsDocumentation only; no source file touched in this commit or the pull request. Checks I ran
|
1 participant
What
Documentation only. No source file is touched.
CLAUDE.mdstopped describing the tree. It opened with "0.0.1is a scaffold. The barrels are empty on purpose", which was true when it was written and has not been for several releases of work: the barrels now carry three service contracts, the drivers behind them, the entitlement model and its vocabulary enums, and a three-command CLI. 31 source files. The unreleased status is restated rather than dropped, because that part is still true and still load-bearing downstream (nothing is on pub.dev, so a package namingmagic_paymentsresolves only through a local override).Three new path-scoped rules, following the convention the same file already states, that a rule arrives with the subsystem it governs:
.claude/rules/contracts.md(lib/src/{contracts,models,enums}/**): why the three-contract split cannot absorb a fourth method, why a rail must never grow anisAvailable, the literals-not-.namerule every wire vocabulary follows, the additive-decode rule, and the test a new enum's fallback member has to pass. Plus the two standing bans:providerStatusnever reaching a decision, and catalogue rows passing through undecoded..claude/rules/drivers.md(lib/src/drivers/**): the three-arm conditional-import graph and what dropping thedart:ioguard costs, why the factory's own docblocks describe the guard strings without naming them, and why the stub throws rather than answering empty..claude/rules/cli.md(lib/src/cli/**,install.yaml): the one-tool MCP surface as a policy rather than an oversight, manifest-only install, idempotence as a property of the construction rather than a guard, and the aliasedDoctorCommandimport.CLAUDE.md's Rules section now names all four.Why
tests.mdwas the only rule, and the file explaining that said the others would arrive with their code. The code arrived.None of the three restate a docblock. The source here carries the reasoning for a given class and carries it well; what a docblock cannot carry is the invariant that spans a directory, which is exactly what gets broken by somebody who opened one file.
Testing
Every factual claim was read out of the source, not out of the docblocks it sits next to: boot modes from the command files (
CommandBoot.none,installinheriting it fromArtisanInstallCommand), theavoid_printscope fromanalysis_options.yaml(package-wide, not directory-scoped, so the rule says so), the guard-count discipline fromtest/drivers/billing_service_factory_test.dart.dart analyzeno issuesflutter test206 passing