Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
80 changes: 62 additions & 18 deletions hooks/_lib/git_commit_titles.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -133,27 +137,40 @@ 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)
while i < n:
ch = command[i]
if quote == "'":
if ch == "'":
runs.append(command[start:i])
runs.append((quote, command[start:i]))
quote = ""
i += 1
continue
Expand All @@ -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
Expand All @@ -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:
Expand Down
6 changes: 6 additions & 0 deletions hooks/preflight-gate/commit-title-format-check/spec.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`
Expand Down
6 changes: 5 additions & 1 deletion hooks/preflight-gate/commit-title-length-check/spec.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 "Title<newline>Body"` (where `<newline>` is an unescaped LF
character inside the quoted string) is split by `_hook_utils.safe_tokenize`'s
Expand Down
70 changes: 70 additions & 0 deletions tests/test_git_commit_titles.py
Original file line number Diff line number Diff line change
Expand Up @@ -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) == []
Loading