diff --git a/hooks/_lib/git_commit_titles.py b/hooks/_lib/git_commit_titles.py index 3a62d026..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 @@ -133,19 +137,32 @@ 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 `\\'`. + + 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). """ - runs: list[str] = [] + command = strip_heredoc_bodies(command) + runs: list[tuple[str, str]] = [] quote = "" start = 0 i, n = 0, len(command) @@ -153,7 +170,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 +179,21 @@ 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 + # `_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 == "'": + if ch in ("'", '"'): quote = ch start = i + 1 i += 1 @@ -195,13 +219,33 @@ 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 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). """ - 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..c0b83798 100644 --- a/tests/test_git_commit_titles.py +++ b/tests/test_git_commit_titles.py @@ -252,8 +252,78 @@ 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.""" 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) == []