Skip to content

chore: close the remaining immich parity gaps - #19

Merged
ttncode merged 9 commits into
mainfrom
chore/immich-parity
Sep 13, 2026
Merged

ttncode merged 9 commits into
mainfrom
chore/immich-parity

Conversation

@ttncode

@ttncode ttncode commented Sep 13, 2026

Copy link
Copy Markdown
Owner

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.md and
CODEOWNERS into every generated project and carried neither itself. It
enforces 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 this
repository and for generated ones — recommending shellcheck and
shell-format, which mise.toml already pins, and telling an editor that the
extensionless scaffold file 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's install.sh is 107
lines with three comments because main() reads as prose and the function names
narrate. local -r is function scope, unlike the file-level readonly this
repository correctly rejects: these libraries are re-sourced into child
processes by design. 98 declarations converted.

The data files. adapters/*/adapter.env ran to 76%, common/.dockerignore
to 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-runner at every task — 263 tests, 0 failures, under the
    runner's own environment.
  • mise run lint and mise exec -- zizmor --min-severity medium at every task.
  • A whole-branch review on the most capable model, which independently parsed
    all 98 local -r declarations into their function bodies and searched each
    for a later write — reassignment, +=, read, unset, printf -v, indexed
    assignment, env-prefix use. Zero real hits.
  • Structural checks run directly rather than taken on report: the exact string
    mise exec -- bash -c "$2" still appears once in lib/adapter.sh;
    lib/publish.sh still opens { and closes EOF at column zero twice each;
    no file-level readonly exists; double-sourcing lib/log.sh and
    lib/service.sh in one shell under set -euo pipefail still succeeds; every
    ADAPTER_* and SERVICE_* assignment is byte-identical.
  • Generated a project with an explicit owner: CODEOWNERS resolves to it, the
    new .vscode/extensions.json and .github/pull_request_template.md arrive,
    and no file carries a surviving placeholder.
  • The new assertion was proven red: common/CODEOWNERS was temporarily set to a
    wrong-but-non-placeholder account, the test failed with the expected message,
    and the file was restored.

One local -r broke three tests during implementation — block="$2" in
lib/service.sh, where the line below uses the env-prefix form
block="$block" awk ..., which bash refuses on a readonly name. Reverted to
plain local and caught by the suite, not by review.

Checklist

  • mise run lint passes
  • mise run test-runner passes
  • New behaviour has a test that fails without the change
  • Docs that describe changed behaviour were updated in the same commit
  • No unrelated changes

iam-truongtrungnghia and others added 9 commits September 13, 2026 13:01
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.
@ttncode
ttncode merged commit 218d4d4 into main Sep 13, 2026
19 checks passed
@ttncode
ttncode deleted the chore/immich-parity branch September 13, 2026 10:51
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant