Skip to content

perf(bash-format): lint each distinct staged file once in shell-check - #16659

Merged
kyle-sexton merged 1 commit into
mainfrom
perf/shell-check-dedupe-identical-blobs
Nov 16, 2026
Merged

kyle-sexton merged 1 commit into
mainfrom
perf/shell-check-dedupe-identical-blobs

Conversation

@kyle-sexton

Copy link
Copy Markdown
Member

No related issue: a measured speed defect in the bash-format pre-commit entry, found while timing the repository's git hooks.

Summary

bash-format's pre-commit entry plugins/bash-format/git-hooks/shell-check.sh ran ShellCheck on every staged shell path. Commit 83fb17c179 changes 21 byte-identical copies of the 5,174-line hook-utils.sh (plugins/*/hooks/hook-utils.sh; lib/hook-utils.sh itself is a different blob), and ShellCheck spends about 1.8 s on each copy (shellcheck -x -f gcc -S warning plugins/animation/hooks/hook-utils.sh: 1.76 s). A trace of the entry on that commit put 53.2 s of a 54.5 s run in the one ShellCheck call.

The entry now lints each distinct script once and copies the findings to every path that shares it. On that commit the median falls from 56.9 s to 25.7 s; the 1-file and 10-file samples are unchanged.

Fix

Grouping, in shell-check.sh only (no change to the synced check-lib.sh):

  • Paths are grouped by the bytes ShellCheck reads (git hash-object --no-filters --stdin-paths, so it holds for --worktree mode and for untracked files, and an autocrlf host hashes the bytes on disk), plus the extension, plus the directory of the nearest .shellcheckrc/shellcheckrc at or above the script, up to the top level.
  • A group whose paths sit in more than one directory stays whole only when a probe of its first path finds no source statement: shellcheck --norc -s bash -S info on the script's text with every # shellcheck directive neutralised and SHELLCHECK_OPTS unset. Any SC1090/SC1091, any error (a parse error can hide a later source), or an exit above 1 splits the group by directory.
  • Each group is linted once from its first path. Before the changed-line filter, each finding of that path is repeated under every copy's path, so each copy's own added lines still decide what blocks. Exit status semantics are unchanged: a copy has the same status as the path linted for it, and the highest status still wins.
  • Any failure while grouping lints every path as before. A failure while copying the findings marks the run failed through checks_tool_failed, so findings are never silently dropped.

Dedupe rule and its Basis. Two paths are linted once only when they hold the same bytes, the same extension and the same nearest rc, and when they are in different directories, the probe finds nothing they source. Basis: the ShellCheck manual (https://github.com/koalaman/shellcheck/blob/master/shellcheck.1.md, read this session) names the inputs that depend on the path:

  • the rc lookup: "look for a file .shellcheckrc or shellcheckrc in the script's directory and each parent directory";
  • source-path: "The special path SCRIPTDIR can be used to specify the currently checked script's directory";
  • the dialect: "deduce the shell from the file's shell directive, shebang, or .bash/.bats/.dash/.ksh extension".

Paths with the same nearest rc share the whole rc chain above it, so the key stays correct whether ShellCheck reads one rc or merges several. This repository's own .shellcheckrc sets source-path=SCRIPTDIR, which is why directory matters for scripts that source. I checked that it can change the result: identical source helper.sh scripts in x/ and y/ under that rc lint differently (y/a.sh:3:7: warning: v is referenced but not assigned. [SC2154], nothing for x/a.sh).

Verification

Timing. hyperfine -N --warmup 1 --runs 10 on Linux WSL2 (24 CPUs, load average about 4). Each sample commit was staged on its parent in a throwaway worktree. Before means origin/main at 3ad9535c79; after means this branch. The two ran back to back on the same tree state.

Sample Staged files Before median After median
83fb17c179 44 (24 shell) 56.87 s (σ 1.82) 25.67 s (σ 0.83)
dedc4fd990 10 0.532 s (σ 0.018) 0.541 s (σ 0.034)
55c8ce6fea 1 0.404 s (σ 0.044) 0.388 s (σ 0.012)

The 10-file and 1-file differences are within one standard deviation. The 98.9 s figure in the timing table on #16645 came from a different measurement session. In this session one unbenchmarked baseline run took 104.8 s and a traced run 54.5 s, so this host's wall time varies with load. The before and after above were measured together.

The 44-file sample is still above the 10 s commit budget (docs/contracts/check-placement/README.md, "Duration budgets"). The remaining time goes to distinct files, measured one at a time: lib/hook-utils.test.sh 13.4 s and plugins/guardrails/hooks/block-root-delete-target.sh 10.1 s (each follows a sourced hook-utils.sh under -x), plus lib/hook-utils.sh 1.8 s, the deduplicated copy 1.8 s, and its probe about 2 s.

Tests. I added these to plugins/bash-format/git-hooks/shell-check.test.sh first and confirmed that 2 of them failed on the old entry:

  • (stub, no real shellcheck needed) three identical copies plus one different script: identical copies reach ShellCheck once, the different script still reaches it, every copy whose added lines hold the finding reports it, and a copy whose finding line was not added does not block;
  • (real shellcheck) copies in two directories that source nothing are linted once and both report;
  • a copy under its own .shellcheckrc is linted apart, and its rc's disable holds;
  • copies that source helper.sh under source-path=SCRIPTDIR are linted apart, and only the copy whose helper leaves the variable unset reports;
  • copies with a parse error before the source line and a disable=SC1091 directive are linted apart.

The batching fixtures (250 long paths, a-finding.sh, z-finding.sh, a-broken.sh) held identical bytes. They now hold distinct bytes so they keep testing batching rather than grouping. Their expectations are unchanged.

Results:

  • bash plugins/bash-format/git-hooks/shell-check.test.sh: 82 passed, 0 failed.
  • bash plugins/bash-format/hooks/bash-format.test.sh: 38 passed, 2 failed.
  • bash plugins/bash-format/hooks/bash-format-end-of-turn.test.sh: 7 passed, 2 failed.
  • The same 4 cases fail on unchanged origin/main in this environment: "shfmt absent", "a missing shellcheck passes silently" and the two "spawn budget" cases. This change does not touch those files.
  • shellcheck -x --rcfile .shellcheckrc on both changed shell files: clean. shfmt -ln bash -i 2 -d: clean.
  • scripts/validate-plugins.sh --only bash-format: passed.

Related

  • fix(scripts): fail checks that checked nothing and record the hook timings #16645 holds the check-placement timing table. It has not merged, so this PR does not edit the table. The row for that table: bash-format shell-check (pre-commit), 83fb17c179, 44 files: 56.9 s before, 25.7 s after (median of 10, hyperfine, Linux WSL2 24 CPUs), plus the 1-file and 10-file rows above.
  • The entry is installed as a copied git-hook script whose stamp the installer computes (plugins/bash-format/lib/git-hooks/install.mjs), so no committed stamp or synced copy changes. The changelog fragment is .changes/bash-format/perf-shell-check-dedupe-identical-blobs-66766b51.md.

🤖 Generated with Claude Code

The pre-commit entry ran ShellCheck on every staged shell path, so a commit
that changes 21 byte-identical copies of the 5,174-line hook-utils.sh linted
the same bytes 21 times, about 1.8 s each.

shell-check.sh now groups the paths it lints by the bytes ShellCheck reads
(git hash-object --no-filters), the extension and the nearest .shellcheckrc,
lints each group once from its first path, and copies that path's findings to
every other member before the changed-line filter, so each copy's own added
lines still decide what blocks. A group spread over directories stays whole
only when a probe (no rc, no SHELLCHECK_OPTS, directives neutralised) finds no
source statement and no error; otherwise it splits by directory, since a
SCRIPTDIR search path resolves a sourced file from each script's directory.
Any failure while grouping lints every path, as before; a failure copying the
findings fails the commit.

The batching fixtures in shell-check.test.sh now hold distinct bytes, since
identical ones are now linted once.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@kyle-sexton
kyle-sexton marked this pull request as ready for review November 16, 2026 23:04
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-16T23:06:42.704093Z ea60338 Draft marked ready
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@github-actions

Copy link
Copy Markdown
Contributor

claude-security-review reviewed ea60338d12fb3a2cc7242b5926e23000ca48caf5: read 3 of 3 changed file(s); 0 finding(s), 0 as inline comments.

Security review: PR #16659, perf(bash-format): lint each distinct staged file once

No security issues found.

I read every hunk of all 3 changed files: the changelog fragment, plugins/bash-format/git-hooks/shell-check.sh and plugins/bash-format/git-hooks/shell-check.test.sh. None of them matches a trusted-path glob. The change touches no trust control, merge hold, token scope, kill switch, plugin manifest or standing instruction.

What I checked in the new grouping code in shell-check.sh:

  • Command or argument injection from staged path names: no path found.
    • Paths reach git hash-object --stdin-paths one per line. Paths that contain a tab or newline are left out of grouping and linted on their own.
    • sed gets the path after --.
    • The probe runs shellcheck on stdin, not on a path argument.
    • The awk programs treat paths as data fields and never evaluate them.
    • No path is interpolated into a shell string or an eval.
  • Weakening of the lint gate: none that carries a security impact.
    • Copies are linted together only when they have the same blob hash, extension and nearest rc directory. Copies in different directories are also probed for source statements first.
    • Any failure while grouping falls back to linting every path.
    • A failure while copying findings goes through checks_tool_failed and is not dropped silently.
    • Even a grouping mistake would only change a local pre-commit ShellCheck result. It would not expose a token, compromise an account or machine, or start a charge.
  • The changed hook runs only on the developer's own staged files. No untrusted input reaches a credentialed context through it.

Spend: none (a local pre-commit hook; no lane, model or schedule changes).

This is the first review of this PR, not blocking only. No prior findings or settled threads apply.

critical-findings: 0

@github-actions

Copy link
Copy Markdown
Contributor

claude-review reviewed ea60338d12fb3a2cc7242b5926e23000ca48caf5: read 3 of 3 changed file(s); 0 finding(s), 0 as inline comments.

Code review: no findings

What changed. plugins/bash-format/git-hooks/shell-check.sh now runs ShellCheck once for each group of staged scripts that ShellCheck would read the same way, then copies each finding to every other path in the group. A group shares the same bytes (git hash-object --no-filters --stdin-paths), the same extension and the same nearest .shellcheckrc. A group that spans directories is split by directory when a probe finds a source statement or a parse error. The test file adds cases for this, and the changelog fragment declares bump: patch.

What I checked (by reading the code; I had no shell, so I ran nothing):

  • Grouping is safe.
    • Copies in the same directory under the same nearest rc resolve SCRIPTDIR, any path relative to the working directory, and the rc chain identically, so linting them once gives the same result.
    • Copies in different directories are merged only when the probe finds nothing sourced. The probe runs --norc, with no -x, with SHELLCHECK_OPTS unset and with # shellcheck directives neutralised, so every source/. call shows up as SC1090/SC1091.
    • A parse error, or an exit status above 1, splits the group. Any other error-level finding also splits it, which costs time but never accuracy.
  • Awk stages.
    • The spread detection compares each path's directory with the one before it in its group, so any group that spans directories is caught.
    • Keys contain spaces but no tabs, so the tab-separated files parse correctly.
    • Paths holding a tab or newline skip grouping and are linted on their own.
    • A missing or failed probe file (getline < 0) makes dedupe_files return 1, and the fallback lints every path.
  • Copying findings. The copy step matches the first :<line>:<col>: in each line, exact-matches the linted path, and writes the copy's path in its place. This runs before checks_filter_findings, so each copy's own added lines still decide what blocks. Exit status is unchanged, since a copy shares the status of the path linted for it. A failure in this awk step goes through checks_tool_failed instead of silently dropping findings.
  • Unaffected paths. Scripts read from the index (partly staged or deleted from the work tree) are still linted one at a time after the copy step.
  • Tests.
    • The batching fixtures were given distinct bytes so they still test batching rather than grouping.
    • The new stub case checks both the single lint call and that a copy whose finding line was not added does not block.
    • The real-ShellCheck cases cover the rc split, the SCRIPTDIR sourcing split and the probe's parse-error / disabled-SC1091 defence.
    • The linted() grep anchors on a leading space, so a.sh does not match pkg/a.sh.

The PR's timing and test results are the author's claims; I did not verify them.

Closing issue: none. The PR context says it closes no issue, so there are no acceptance criteria to check.

Manifests: no plugin.json or marketplace.json changes. The changelog fragment's bump: patch fits a performance change with no behaviour change.

No changed file matches a trusted-path glob, the PR context contains no embedded instructions, and this is the first review of this pull request (blocking only: no).

Verifier dropped 0 of 0 candidates.

@kyle-sexton
kyle-sexton added this pull request to the merge queue Nov 16, 2026
Merged via the queue into main with commit 547e422 Nov 16, 2026
77 checks passed
@kyle-sexton
kyle-sexton deleted the perf/shell-check-dedupe-identical-blobs branch November 16, 2026 23:17
@github-actions github-actions Bot added the merge-path: owner-agent Post-merge accounting record (README.md, Merge paths) label Nov 16, 2026
@github-actions

Copy link
Copy Markdown
Contributor

Post-merge mutation testing

Killed 3, survived 4, timeout 0, no coverage 0, invalid 0, not run 0.
Covered-code score 43%; mutation score 43%.

File Killed Survived Timeout No coverage Invalid Not run
plugins/bash-format/git-hooks/shell-check.sh 3 4 0 0 0 0

Surviving mutants

Location Operator Disposition Cause
plugins/bash-format/git-hooks/shell-check.sh:142 LCR unclassified none
plugins/bash-format/git-hooks/shell-check.sh:154 ROR unclassified none
plugins/bash-format/git-hooks/shell-check.sh:181 SBR unclassified none
plugins/bash-format/git-hooks/shell-check.sh:195 SBR unclassified none

The run's summary has the full report.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

merge-path: owner-agent Post-merge accounting record (README.md, Merge paths)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant