chore: close the remaining immich parity gaps - #19
Merged
Merged
Conversation
SECURITY.md and CODEOWNERS ship to every generated project and were missing here. A pull request template is enforced on this repository's own pull requests by a CI job and was shipped to nobody. .vscode recommends the tools mise.toml already pins, and tells an editor that the extensionless scaffold file is bash. The placeholder test asserted that no @you survived generation, which a hardcoded account passes. It now asserts CODEOWNERS names the account the run resolved.
63 steps across four workflows, none with a name. immich names 297 of its own and sits at 3.8% comments against our 17.5% — the difference is not that they explain less, it is where. A step's name appears in the GitHub log while the job runs; a comment above it appears only to someone reading the file. No comment was deleted. Every one that survives annotates a key that is not a step — a timeout and the measurement behind it, fetch-depth: 0 for a test that walks this repository's history, the zizmor path scope, the `edited` trigger, and the pull-request-body job name being load-bearing for branch protection. None of those is a fact a step's name could carry.
immich's install.sh is 107 lines with three comments because main() reads as prose and the function names narrate. Ours has that shape already and still carried a paragraph above each function. local -r for locals assigned once, which is function scope and unlike the file-level readonly this repository rejects — these libraries are re-sourced into child processes by design. What stays is the third-party landmines: jq rather than grep for an asset id, two endpoints for a private release, the trap baking its path and naming its signals, sed delimited on | because a base64 value contains /, and BASH_SOURCE[0]:-$0 because a curl-piped script has none.
…acts
adapter.env ran to 53-76% comments, common/.dockerignore to 79%, where
immich's equivalents carry none at all. What stays is the traps: the laravel
starter kit's inert .github failing zizmor with exit 13, the sed wiring
routes/health.php into bootstrap/app.php because Laravel auto-loads neither,
the nest v11/v12 jest-vitest regression, and the generator env vars
(SHELL_VERBOSITY, COMPOSER_PROCESS_TIMEOUT) with their reasons. Deleted:
comments restating what the assignment beside them already says (ADAPTER_TIER
citing ADR-0012, the /up note beside ADAPTER_READINESS_PATH) and boilerplate
("never belongs in an image").
tests/*.bats were audited against the same rule — delete a comment the test
name already says, keep one that records why the test exists — and found
already compliant: every comment explains a shipped defect, an ADR, or a
measured behavior no test name conveys. None restated a name, so no test file
changed.
Co-authored-by: Claude <noreply@anthropic.com>
Final review on chore/immich-parity found one Important and three Minor findings where compression lost a fact with nowhere else to land in the shipped repo: .dockerignore's build-context scope, example.env's appended variables, project.sh's mise.root.toml substitution order, and adapter.env's Nest major-bump validation step. Folded each back in as a clause on the surviving comment.
A plan is a work order. The five left behind before this one claimed 305 undone tasks in a repository where all of it had shipped; PR #18 deleted 8,703 lines of them. The design stays in docs/superpowers/specs/, which is the record.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What this changes
Closes the gaps a full survey found between this toolbox and immich, the project
it was derived from. Nine commits, one intended behaviour change — a test that
can now fail for the reason it was written.
Files immich has and this repository did not. It ships
SECURITY.mdandCODEOWNERSinto every generated project and carried neither itself. Itenforces a pull request body on its own pull requests, with a CI job, and
shipped no template to clients. Both are fixed, plus
.vscode/for thisrepository and for generated ones — recommending
shellcheckandshell-format, whichmise.tomlalready pins, and telling an editor that theextensionless
scaffoldfile is bash.A name on every workflow step. 63 steps across four workflows had none.
immich names 297 of its own and sits at 3.8% comments against our 17.5%; the
difference is not that they explain less, it is where. A step's name appears in
the GitHub log while the job runs. No comment was deleted — every one that
survives annotates a key that is not a step.
local -r, and comments down to their facts. immich'sinstall.shis 107lines with three comments because
main()reads as prose and the function namesnarrate.
local -ris function scope, unlike the file-levelreadonlythisrepository correctly rejects: these libraries are re-sourced into child
processes by design. 98 declarations converted.
The data files.
adapters/*/adapter.envran to 76%,common/.dockerignoreto 79% where immich's carries none at all.
What the survey found and left alone. The bats suites are at 19% against
immich's 0.9%, and nothing was cut there. The premise this task was written on —
that the dominant pattern is a comment restating the test name — turned out
false when measured: only 13 of ~298 tests carry any comment above them, and
none restates its name. The 836 comment lines live inside test bodies recording
why an assertion is shaped as it is, which is the category worth keeping.
How it was verified
mise run test-runnerat every task — 263 tests, 0 failures, under therunner's own environment.
mise run lintandmise exec -- zizmor --min-severity mediumat every task.all 98
local -rdeclarations into their function bodies and searched eachfor a later write — reassignment,
+=,read,unset,printf -v, indexedassignment, env-prefix use. Zero real hits.
mise exec -- bash -c "$2"still appears once inlib/adapter.sh;lib/publish.shstill opens{and closesEOFat column zero twice each;no file-level
readonlyexists; double-sourcinglib/log.shandlib/service.shin one shell underset -euo pipefailstill succeeds; everyADAPTER_*andSERVICE_*assignment is byte-identical.CODEOWNERSresolves to it, thenew
.vscode/extensions.jsonand.github/pull_request_template.mdarrive,and no file carries a surviving placeholder.
common/CODEOWNERSwas temporarily set to awrong-but-non-placeholder account, the test failed with the expected message,
and the file was restored.
One
local -rbroke three tests during implementation —block="$2"inlib/service.sh, where the line below uses the env-prefix formblock="$block" awk ..., which bash refuses on a readonly name. Reverted toplain
localand caught by the suite, not by review.Checklist
mise run lintpassesmise run test-runnerpasses