From 93c4f98ef84be017d46e30b748b7630dfd271920 Mon Sep 17 00:00:00 2001 From: Seunggwan Song Date: Sat, 22 Aug 2026 11:21:31 +0900 Subject: [PATCH 1/2] fix(hooks): disqualify a title quoted both ways MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 같은 텍스트가 한 명령 안에서 작은따옴표와 큰따옴표로 모두 등장하면, 토큰 스트림에는 제목이 어느 쪽에서 왔는지 말해주는 것이 없다. 값 대조만으로는 앞 세그먼트의 작은따옴표 구간이 제목을 리터럴로 만들어 버려서, 셸이 실제로 확장하는 제목을 format·length 게이트가 채점했다. 정상 커밋이 막히는 경로다. `_single_quoted_runs` 를 `_quoted_runs` 로 넓혀 큰따옴표 구간도 수집하고, 제목이 양쪽 모두에 나타나면 리터럴 판정을 무효화한다. `safe_tokenize` 와 `iter_command_starts` 는 건드리지 않으므로 84개 소비자는 정의상 무영향이다. 이슈가 제안한 source span 확장 대신 값 무효화를 택했다. span 은 두 방향을 모두 정확히 가르지만 공용 토크나이저의 반환 형태를 바꾼다. 값 무효화는 거울 케이스(`git commit -m '$(x)' && echo "$(x)"`, 제목이 진짜 리터럴인데 침묵)를 새로 만든다 — 방향이 오차단이 아니라 침묵이라 게이트의 fail-open 자세와 맞고, 잔여는 테스트로 고정했다. Confidence: high Not-tested: 실제 Claude Code 세션에서의 게이트 발화는 미검증 — 합성 입력 기반 단위 테스트로만 확인 Constraint: source span 방식은 공용 토크나이저 반환 형태 변경을 요구해 기각 --- hooks/_lib/git_commit_titles.py | 50 ++++++++++++------- .../commit-title-format-check/spec.md | 6 +++ .../commit-title-length-check/spec.md | 6 ++- tests/test_git_commit_titles.py | 30 +++++++++++ 4 files changed, 73 insertions(+), 19 deletions(-) diff --git a/hooks/_lib/git_commit_titles.py b/hooks/_lib/git_commit_titles.py index 3a62d026..da56a885 100644 --- a/hooks/_lib/git_commit_titles.py +++ b/hooks/_lib/git_commit_titles.py @@ -133,19 +133,23 @@ def strip_git_global_flags(argv: list[str]) -> tuple[list[str], str | None]: return argv[i:], c_dir -def _single_quoted_runs(command: str) -> list[str]: - """Every single-quoted run in `command`, contents only, in source order. +def _quoted_runs(command: str) -> list[tuple[str, str]]: + """Every quoted run in `command` as `(quote_char, contents)`, in source order. A single-quoted run is the one place the shell substitutes nothing at all, so its contents reach the tokenizer byte-for-byte. That property is what lets the caller below match a token back to its source without tracking positions through the tokenizer. - Double-quoted spans and backslash escapes are walked so their quotes cannot - open or close a run: `"it's"` holds no single-quoted run, and neither does - `\\'`. + Double-quoted runs are reported too, and for the opposite reason: their + contents are what the shell *does* substitute, so a title that also appears + as one cannot be attributed to the single-quoted run by value alone. + + Each quote style is walked while inside the other, so a quote character + that is data cannot open or close a run: `"it's"` holds no single-quoted + run, and neither does `\\'`. """ - runs: list[str] = [] + runs: list[tuple[str, str]] = [] quote = "" start = 0 i, n = 0, len(command) @@ -153,7 +157,7 @@ def _single_quoted_runs(command: str) -> list[str]: ch = command[i] if quote == "'": if ch == "'": - runs.append(command[start:i]) + runs.append((quote, command[start:i])) quote = "" i += 1 continue @@ -162,14 +166,11 @@ def _single_quoted_runs(command: str) -> list[str]: continue if quote == '"': if ch == '"': + runs.append((quote, command[start:i])) quote = "" i += 1 continue - if ch == '"': - quote = ch - i += 1 - continue - if ch == "'": + if ch in ("'", '"'): quote = ch start = i + 1 i += 1 @@ -195,13 +196,26 @@ def _title_is_single_quoted_literal(command: str, title: str) -> bool: Matching the token against the runs needs no position tracking through the tokenizer and is unaffected by anything in another segment. - Residual, stated because the match is by value rather than by position: a - command that quotes the SAME text both ways — `echo '$(x)'; git commit -m - "$(x)"` — reads as literal here. The direction of that error is to grade a - title the shell expanded, so the gates speak up rather than fall silent; - closing it needs raw source spans, which the tokenizer does not carry. + Because the match is by value, a command that quotes the SAME text both + ways — `echo '$(x)'; git commit -m "$(x)"` — offers two source runs that + tokenize identically, and nothing in the token stream says which one this + title came from. That is not a literal we failed to recognise; it is a + title whose value is genuinely unknown at hook time, so the double-quoted + run disqualifies the match and the gates stay silent (issue #1036). Reading + it as a literal instead graded a title the shell expands, which blocked a + legitimate commit. + + The disqualification is by value, so it also silences the mirror case — + `git commit -m '$(x)' && echo "$(x)"`, where the title really is the + literal and the double-quoted run belongs to another segment. Separating + those two needs the source spans the tokenizer discards. Silence is the + fail-open direction and the one this repo chooses for a gate, so the + residual is pinned by test rather than closed. """ - return title in _single_quoted_runs(command) + runs = _quoted_runs(command) + single = any(q == "'" and body == title for q, body in runs) + double = any(q == '"' and body == title for q, body in runs) + return single and not double def title_is_unresolved_substitution(title: str, command: str | None = None) -> bool: diff --git a/hooks/preflight-gate/commit-title-format-check/spec.md b/hooks/preflight-gate/commit-title-format-check/spec.md index de0d6011..e4c6a693 100644 --- a/hooks/preflight-gate/commit-title-format-check/spec.md +++ b/hooks/preflight-gate/commit-title-format-check/spec.md @@ -109,6 +109,12 @@ Inherits `safe_tokenize` / `iter_command_starts` / `strip_prefix` from (`sudo`, `env`), and shell control-flow keywords are peeled before matching. - Quoted strings protect their contents — `echo "git commit -m 'fake'"` does not trigger the hook because `echo` is argv[0] of that segment. +- A title that OPENS a substitution (`$(`, `` ` ``) is graded only when the raw + command shows it came from a single-quoted run, where the shell substitutes + nothing. `-m "$(cat …)"` is unknowable at hook time and stays silent. The + match is by value, so when the same text appears both single- and + double-quoted (`echo '$(x)'; git commit -m "$(x)"`) neither run can be + attributed to the title and the gate stays silent (issue #1036). - Backslash-newline continuations are collapsed before tokenization — multi-line invocations like `git commit \\\n -m "..."` parse correctly. - Only the FIRST `-m` / `--message` value is checked (title); subsequent `-m` diff --git a/hooks/preflight-gate/commit-title-length-check/spec.md b/hooks/preflight-gate/commit-title-length-check/spec.md index 3ae38251..91da60b1 100644 --- a/hooks/preflight-gate/commit-title-length-check/spec.md +++ b/hooks/preflight-gate/commit-title-length-check/spec.md @@ -145,7 +145,11 @@ Inherits `safe_tokenize` / `iter_command_starts` / `strip_prefix` from - Second `-m` flag is body, not title — `git commit -m "short" -m "long body"` only checks the first `-m` value. - Subshells (`$(...)`) are opaque — acknowledged limitation shared with all - sibling hooks. + sibling hooks. A title that OPENS one is measured only when the raw command + shows it came from a single-quoted run, where the shell substitutes nothing. + The match is by value, so when the same text appears both single- and + double-quoted (`echo '$(x)'; git commit -m "$(x)"`) neither run can be + attributed to the title and the gate stays silent (issue #1036). - **Literal newline inside a single quoted `-m` value bypasses the check.** `git commit -m "TitleBody"` (where `` is an unescaped LF character inside the quoted string) is split by `_hook_utils.safe_tokenize`'s diff --git a/tests/test_git_commit_titles.py b/tests/test_git_commit_titles.py index 46c78d08..2dea6883 100644 --- a/tests/test_git_commit_titles.py +++ b/tests/test_git_commit_titles.py @@ -252,6 +252,36 @@ def test_another_segments_substitution_does_not_reach_the_title(command, expecte assert _titles_from_all_segments(command) == expected +@pytest.mark.parametrize( + "command, expected", + [ + # The reported case: the SAME text quoted both ways. Nothing in the + # token stream says which run produced the title, so its value is + # genuinely unknown and the gates must stay silent (issue #1036). + # Before the fix the earlier single-quoted run made this read as a + # literal and the format gate blocked a legitimate commit. + ("""echo '$(x)'; git commit -m "$(x)\"""", []), + ("""git commit -m "$(x)" && echo '$(x)'""", []), + ("echo '`x`'; git commit -m \"`x`\"", []), + # Positive control — a title that IS a single-quoted literal keeps + # being graded. Without it the change above is indistinguishable from + # disabling literal detection outright. + ("""echo "$(y)"; git commit -m '$(x) title'""", ["$(x) title"]), + ], +) +def test_same_text_quoted_both_ways_is_unknowable(command, expected): + assert _titles_from_all_segments(command) == expected + + +def test_value_disqualification_also_silences_the_mirror_case(): + """Pins the cost of matching by value: here the title IS the literal and + the double-quoted run is another segment's, yet the gates stay silent. + Closing this needs source spans; silence is the fail-open direction, so the + residual is recorded rather than fixed.""" + command = """git commit -m '$(x)' && echo "$(x)\"""" + assert _titles_from_all_segments(command) == [] + + def test_argv_only_callers_keep_the_conservative_behaviour(): """Without the raw command there is nothing to disambiguate with, so the opener alone still suppresses — old callers must not start hard-blocking.""" From 3e478d3f283f12fc46dd0ecfff4486c91708dfcc Mon Sep 17 00:00:00 2001 From: Seunggwan Song Date: Sat, 22 Aug 2026 18:17:31 +0900 Subject: [PATCH 2/2] fix(hooks): exclude comments/heredocs from literal match MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `_quoted_runs` scanned the whole raw command, including a trailing comment and a heredoc body — regions the shell never executes. A double-quoted run living in either one disqualified a genuine single-quoted literal title by value, silencing the format/length gates on a title they should have graded. Blank heredoc bodies via the shared `strip_heredoc_bodies` (same pass `safe_tokenize` uses) and skip unquoted `#…` comments using the shared `_starts_unquoted_comment` boundary rule, extended with an explicit newline check since this scanner walks the whole multi-line command rather than one line at a time. The documented residual (a double-quoted run in a sibling EXECUTED segment, e.g. `'$(x)' && echo "$(x)"`) is unaffected — closing that needs source spans this PR does not add, and a pinning test confirms it still stays silent. Confidence: high Not-tested: hook-level PreToolUse integration (only the module's own unit/shell suites ran; no live Bash-tool commit was fired through the actual hooks) --- hooks/_lib/git_commit_titles.py | 40 ++++++++++++++++++++++++++++----- tests/test_git_commit_titles.py | 40 +++++++++++++++++++++++++++++++++ 2 files changed, 75 insertions(+), 5 deletions(-) diff --git a/hooks/_lib/git_commit_titles.py b/hooks/_lib/git_commit_titles.py index da56a885..3c3eb18d 100644 --- a/hooks/_lib/git_commit_titles.py +++ b/hooks/_lib/git_commit_titles.py @@ -30,7 +30,11 @@ # here too keeps the module self-contained (e.g. when imported directly by a # differential test) without depending on the importer's path setup. _sys.path.insert(0, str(_Path(__file__).resolve().parent)) -from _hook_utils import strip_prefix # type: ignore[import-not-found] # noqa: E402 +from _hook_utils import ( # type: ignore[import-not-found] # noqa: E402 + _starts_unquoted_comment, + strip_heredoc_bodies, + strip_prefix, +) # --------------------------------------------------------------------------- # Constants @@ -148,7 +152,16 @@ def _quoted_runs(command: str) -> list[tuple[str, str]]: Each quote style is walked while inside the other, so a quote character that is data cannot open or close a run: `"it's"` holds no single-quoted run, and neither does `\\'`. + + Two regions the shell never executes are excluded first, so a quote there + cannot disqualify a literal title that lives in the real command: + heredoc bodies (blanked via the shared `strip_heredoc_bodies`, same as + `safe_tokenize` uses) and unquoted `#…` comments, whose word-boundary rule + is the shared `_starts_unquoted_comment` so this scanner and + `_quote_open_at_eol` cannot disagree on where a comment starts (issue + #1036 follow-up). """ + command = strip_heredoc_bodies(command) runs: list[tuple[str, str]] = [] quote = "" start = 0 @@ -170,6 +183,16 @@ def _quoted_runs(command: str) -> list[tuple[str, str]]: quote = "" i += 1 continue + # `_starts_unquoted_comment`'s word-boundary set has no newline in it + # because its two callers only ever see one physical line at a time; + # this scanner walks the whole multi-line command, so a `#` right + # after a line break is a boundary here too, even though the shared + # helper alone cannot see it. + at_line_start = i == 0 or command[i - 1] == "\n" + if ch == "#" and (at_line_start or _starts_unquoted_comment(command, i)): + nl = command.find("\n", i) + i = n if nl == -1 else nl + continue if ch in ("'", '"'): quote = ch start = i + 1 @@ -207,10 +230,17 @@ def _title_is_single_quoted_literal(command: str, title: str) -> bool: The disqualification is by value, so it also silences the mirror case — `git commit -m '$(x)' && echo "$(x)"`, where the title really is the - literal and the double-quoted run belongs to another segment. Separating - those two needs the source spans the tokenizer discards. Silence is the - fail-open direction and the one this repo chooses for a gate, so the - residual is pinned by test rather than closed. + literal and the double-quoted run belongs to another EXECUTED segment. + Separating those two needs the source spans the tokenizer discards. + Silence is the fail-open direction and the one this repo chooses for a + gate, so that residual is pinned by test rather than closed. + + A narrower case IS closed: `_quoted_runs` excludes comments and heredoc + bodies before matching, so `git commit -m '$(x)' # "$(x)"` and a `"$(x)"` + sitting inside an unrelated heredoc body no longer disqualify the literal + — neither region is code the shell ever runs, so a quoted run found there + cannot be "the other segment" the mirror-case paragraph above is about + (issue #1036 follow-up). """ runs = _quoted_runs(command) single = any(q == "'" and body == title for q, body in runs) diff --git a/tests/test_git_commit_titles.py b/tests/test_git_commit_titles.py index 2dea6883..c0b83798 100644 --- a/tests/test_git_commit_titles.py +++ b/tests/test_git_commit_titles.py @@ -287,3 +287,43 @@ def test_argv_only_callers_keep_the_conservative_behaviour(): opener alone still suppresses — old callers must not start hard-blocking.""" assert extract_git_titles(["git", "commit", "-m", "$(literal) title"]) == [] assert extract_git_titles(["git", "commit", "-m", "$(literal) title"], None) == [] + + +# --------------------------------------------------------------------------- +# 7. Value-disqualification ignores regions the shell never executes +# --------------------------------------------------------------------------- +# +# `_quoted_runs` used to scan the whole raw command, including a trailing +# comment and a heredoc body — text the shell parses as data, not code. A +# double-quoted run living in either region disqualified a genuine +# single-quoted literal title, silencing the gates on a title they should +# have graded (issue #1036 follow-up). + +def test_comment_double_quote_does_not_disqualify_the_literal(): + # The `#` starts a real comment here (preceded by whitespace), so its + # double-quoted run never executes and must not cancel the literal. + command = """git commit -m '$(x)' # "$(x)\"""" + assert _titles_from(command) == ["$(x)"] + + +def test_comment_at_the_start_of_a_continuation_line(): + # A `#` that opens a fresh physical line is a boundary too, even though + # `_starts_unquoted_comment`'s callers only ever see one line at a time. + command = "echo hi\n# \"$(x)\"\ngit commit -m '$(x)'" + assert _titles_from_all_segments(command) == ["$(x)"] + + +def test_heredoc_body_double_quote_does_not_disqualify_the_literal(): + # The double-quoted text lives inside a heredoc body (data written to a + # file), not inside any executed shell segment. + command = "cat <<'EOF' > /tmp/x\n\"$(x)\"\nEOF\ngit commit -m '$(x)'" + assert _titles_from_all_segments(command) == ["$(x)"] + + +def test_mirror_case_residual_is_unaffected_by_the_region_exclusion(): + """The comment/heredoc fix must not touch the documented residual: a + double-quoted run in a SIBLING executed segment still disqualifies the + literal by value, because closing that needs source spans this PR does + not add.""" + command = """git commit -m '$(x)' && echo "$(x)\"""" + assert _titles_from_all_segments(command) == []