From 5a1458d8828665eea4ff0a545d94e845d3905c10 Mon Sep 17 00:00:00 2001 From: "richmond-avenal[bot]" <323733923+richmond-avenal[bot]@users.noreply.github.com> Date: Tue, 17 Nov 2026 04:31:44 +0000 Subject: [PATCH 1/4] fix: read a brace group that spans lines as one command logbook#73. `cmd || {` held the logical line open for exactly one more line, so echo hi | grep -qxF X || { echo "no" exit 1 } came out as `... || { echo "no"`, the `exit 1` was never seen, and a working assertion was reported `decorative` -- a false positive on the one shape the tool exists to defend. A brace group now holds the line open until it closes, and the newlines inside it join as the command separators they are. The separator is the fix: `_FAILING` wants an `exit` that starts a command, and `"no" exit 1` does not. The joined text is valid shell, which is how it is tested. A script whose braces do not balance keeps the old line-at-a-time reading, so a `{` in a heredoc cannot swallow the rest of the file. --- src/deadassert/shell.py | 164 +++++++++++++++++++++++++++++++++++++++- tests/test_shell.py | 53 +++++++++++++ 2 files changed, 214 insertions(+), 3 deletions(-) diff --git a/src/deadassert/shell.py b/src/deadassert/shell.py index f3d0d97..732c7f4 100644 --- a/src/deadassert/shell.py +++ b/src/deadassert/shell.py @@ -99,18 +99,165 @@ def _strip_comment(line: str) -> str: return "".join(out) +#: A `{` opens a brace group only in word position. `${VAR}`, `awk '{print}'` +#: and a brace expansion are all part of a word and open nothing. +_GROUP_OPEN_AFTER = " \t;&|(" + +#: A function definition: `name() {`, `function name {`, either with a body +#: that opens on the same line. Both forms are bash; the first is POSIX. +_FUNCTION = re.compile( + r"^(?:function\s+([A-Za-z_]\w*)\s*(?:\(\s*\))?|([A-Za-z_]\w*)\s*\(\s*\))\s*\{" +) + + +def group_delta(text: str) -> int: + """Net brace-group depth across one physical line. + + Counts only a `{` or `}` that stands as a word of its own, outside quotes + and outside `$(...)`, `${...}` and backticks. Everything that rule leaves + out is there because of what the depth is used for: a logical line stays + open while the depth is positive, so a stray `{` that never closes would + swallow the rest of the script. Quote state is per line, matching + `_strip_comment`; a brace inside a string that spans lines is the one + thing this miscounts, and `logical_lines` falls back when the script does + not balance. + """ + delta = 0 + quote: str | None = None + #: Closers owed to `$(`, `${` and backticks. A brace is only a group + #: while this is empty. + stack: list[str] = [] + index = 0 + while index < len(text): + ch = text[index] + if quote: + if ch == quote: + quote = None + index += 1 + continue + if ch in "'\"": + quote = ch + index += 1 + continue + if ch == "`": + if stack and stack[-1] == "`": + stack.pop() + else: + stack.append("`") + index += 1 + continue + if ch == "$" and index + 1 < len(text) and text[index + 1] in "({": + stack.append(")" if text[index + 1] == "(" else "}") + index += 2 + continue + if ch == "(" and stack: + stack.append(")") + index += 1 + continue + if ch in ")}" and stack and stack[-1] == ch: + stack.pop() + index += 1 + continue + if not stack: + if ch == "{" and (index == 0 or text[index - 1] in _GROUP_OPEN_AFTER): + after = text[index + 1 : index + 2] + if after in ("", " ", "\t"): + delta += 1 + elif ch == "}" and (index == 0 or text[index - 1] in " \t;&("): + delta -= 1 + index += 1 + return delta + + +def function_spans(script: str) -> list[tuple[int, int, str]]: + """`(first line, last line, name)` for each function definition. + + Over physical lines, so the span is usable for reporting the line a + command inside the body is really on. An unclosed body runs to the end of + the script: that is a malformed function, and claiming it ends earlier + would put commands that are inside it outside. + """ + spans: list[tuple[int, int, str]] = [] + depth = 0 + start = 0 + name = "" + for number, raw in enumerate(script.split("\n"), 1): + body = _strip_comment(raw).rstrip() + if depth == 0: + match = _FUNCTION.match(body.strip()) + if match: + start = number + name = match.group(1) or match.group(2) + depth = group_delta(body) + if depth <= 0: + spans.append((number, number, name)) + depth = 0 + continue + continue + depth += group_delta(body) + if depth <= 0: + spans.append((start, number, name)) + depth = 0 + if depth > 0: + spans.append((start, len(script.split("\n")), name)) + return spans + + +def in_function(spans: list[tuple[int, int, str]], line: int) -> str | None: + """The name of the function whose body holds `line`, if any.""" + for first, last, name in spans: + if first <= line <= last: + return name + return None + + +#: A logical line is still open after one of these: the newline that follows +#: is not a command separator, it is whitespace before the next word. +_OPEN = re.compile(r"(?:\|\||&&|&|\||;|\{)$") + +#: The same, for the keywords that can only be followed by a command list. +#: Only consulted inside a brace group, because at the top level an `if ...; +#: then` line is deliberately left as its own logical line for +#: `_branch_polarity` to walk. +_OPEN_KEYWORD = re.compile(r"(?:\bthen|\bdo|\belse|\bin)$") + + def logical_lines(script: str) -> list[tuple[int, str]]: """The script as logical lines, each with the 1-based line it starts on. Joins backslash continuations and lines left open by a trailing `|`, `||`, `&&`, `;` or `{`, because an assertion is routinely written across two physical lines and its polarity lives on the second one. + + A brace group holds the line open until it closes, and the newlines inside + it are joined as the command separators they are -- logbook#73. Before + that, `cmd || {` joined one line and stopped, so + + echo hi | grep -qxF X || { + echo "no" + exit 1 + } + + came out as `echo hi | grep -qxF X || { echo "no"`, the `exit 1` was never + seen, and a working assertion was reported as `decorative`. Joining with + `; ` rather than a space is the whole fix: `_FAILING` looks for an `exit` + that starts a command, and `"no" exit 1` does not. + + A script whose braces do not balance gets the old line-at-a-time + behaviour. That is the conservative direction -- an unclosed `{`, whether + in a heredoc or from a brace this miscounts, would otherwise swallow every + line after it. """ + lines = script.split("\n") + bodies = [_strip_comment(raw).rstrip() for raw in lines] + groups = sum(group_delta(body) for body in bodies) == 0 + out: list[tuple[int, str]] = [] buffer = "" start = 0 - for number, raw in enumerate(script.split("\n"), 1): - body = _strip_comment(raw).rstrip() + depth = 0 + separate = False + for number, body in enumerate(bodies, 1): stripped = body.strip() if not buffer: if not stripped: @@ -118,13 +265,24 @@ def logical_lines(script: str) -> list[tuple[int, str]]: start = number if body.endswith("\\"): buffer += body[:-1].strip() + " " + if groups: + depth += group_delta(body[:-1]) continue + if separate and stripped: + buffer += "; " + separate = False buffer += stripped - if re.search(r"(?:\|\||&&|&|\||;|\{)$", buffer): + if groups: + depth += group_delta(body) + if _OPEN.search(buffer) or (depth > 0 and _OPEN_KEYWORD.search(buffer)): buffer += " " continue + if depth > 0: + separate = True + continue out.append((start, buffer.strip())) buffer = "" + depth = 0 if buffer.strip(): out.append((start, buffer.strip())) return out diff --git a/tests/test_shell.py b/tests/test_shell.py index 1804d3d..8c376c2 100644 --- a/tests/test_shell.py +++ b/tests/test_shell.py @@ -187,3 +187,56 @@ def test_hash_inside_a_pattern_is_not_a_comment(self): def test_line_number_is_within_the_script(self): script = "set -e\n\ncat out.txt\ngrep -qF 'x' out.txt" assert one(script).line == 4 + + +class TestBraceGroups: + """logbook#73: a `|| { ... }` spanning lines read as `decorative`. + + The four shapes below all fail the step when the pattern is absent, and + were checked under `bash -e` before this class was written. Any of them + coming out as anything but `needs-match` is a false positive on a working + assertion -- the mirror of what the tool exists to find. + """ + + def test_multi_line_brace_group_is_an_assertion(self): + script = 'echo hi | grep -qxF \'x\' || {\n echo "no"\n exit 1\n }' + assert polarity(script) == "needs-match" + + def test_single_line_brace_group_still_is(self): + assert polarity("echo hi | grep -qxF 'x' || { echo no; exit 1; }") == "needs-match" + + def test_multi_line_and_brace_group_needs_no_match(self): + script = "grep -qF 'oops' out.txt && {\n echo bad\n exit 1\n }" + assert polarity(script) == "needs-no-match" + + def test_newlines_in_the_group_become_separators(self): + # The bug was not the joining, it was joining with a space: `_FAILING` + # wants an `exit` that starts a command, and `"no" exit 1` does not. + script = 'grep -qF \'x\' f || {\n echo "no"\n exit 1\n}' + assert one(script).text == 'grep -qF \'x\' f || { echo "no"; exit 1; }' + + def test_a_group_holding_only_a_message_is_still_decorative(self): + # Fixing the join must not make every brace group look like a failure. + script = 'grep -qF \'x\' f || {\n echo "just saying"\n}' + assert polarity(script) == "decorative" + + def test_an_unclosed_brace_does_not_swallow_the_script(self): + # A `{` this miscounts -- in a heredoc, say -- must not take the rest + # of the file with it. Unbalanced scripts get line-at-a-time reading. + script = "cat <<'EOF'\n{\nEOF\ngrep -qF 'x' out.txt" + assert polarity(script) == "needs-match" + + def test_braces_in_quotes_and_expansions_open_nothing(self): + assert shell.group_delta("awk '{print $1}' f") == 0 + assert shell.group_delta('echo "${VAR}"') == 0 + assert shell.group_delta("x=$(f); echo {") == 1 + + def test_if_then_at_the_top_level_is_still_its_own_line(self): + # `_branch_polarity` walks logical lines to find the `else`, so an + # `if` outside a brace group must not be joined to its body. + script = "if grep -qF 'oops' out.txt; then\n exit 1\nfi" + assert [text for _, text in shell.logical_lines(script)] == [ + "if grep -qF 'oops' out.txt; then", + "exit 1", + "fi", + ] From 4c245206ef64b2ed3600ac7b4fdc56077ac63c24 Mon Sep 17 00:00:00 2001 From: "richmond-avenal[bot]" <323733923+richmond-avenal[bot]@users.noreply.github.com> Date: Tue, 17 Nov 2026 04:38:40 +0000 Subject: [PATCH 2/4] fix: an `exit` after `then` is still an `exit` Found while fixing logbook#73, and it is the same blindness one newline earlier. `_FAILING` wanted a `;`, `&&`, `|`, `{` or `(` in front of the `exit`; in if grep -q 'y' f; then exit 1; fi what is in front of it is `then`. The only statement in the branch was invisible, so a working negated guard read as `decorative` -- a false positive on the shape this tool exists to judge. Add a statement in front of the exit, or spread it over four lines, and it was already correct; only the one-line single-statement form was wrong. `then`, `else` and `do` now count as the command separators they are. That alone would misattribute a one-line `if ...; then ...; else ...`, whose two branches share one line, and inverting a polarity is worse than the `decorative` it replaces -- so the branches are split before either is judged. The test is that a one-line `if` reads the same as the same `if` spread over four, in all six shapes. Not live in the org: the shape appears once, inside a comment in whichrc, quoting a guard the logbook#64 sweep had already rewritten. --- src/deadassert/shell.py | 40 +++++++++++++++++++++++---- tests/test_shell.py | 61 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 95 insertions(+), 6 deletions(-) diff --git a/src/deadassert/shell.py b/src/deadassert/shell.py index 732c7f4..837969c 100644 --- a/src/deadassert/shell.py +++ b/src/deadassert/shell.py @@ -47,7 +47,16 @@ #: Polarities for which the step's pass/fail actually depends on the match. LIVE = ("needs-match", "needs-no-match") -_FAILING = re.compile(r"(?:^|[;&|{(]\s*)(?:exit\s+[1-9]|exit\s*$|false\b|return\s+[1-9])") +#: A command that fails the step, at the start of a command list. The +#: keyword alternative is not decoration: `then` and `do` separate commands +#: exactly as `;` does, so without it the only statement in +#: `if grep -q x f; then exit 1; fi` is invisible and a working guard reads +#: as `decorative`. Found while fixing logbook#73, which is the same +#: blindness one newline further along. +_FAILING = re.compile( + r"(?:^|[;&|{(]\s*|\b(?:then|else|do)\s+)" + r"(?:exit\s+[1-9]|exit\s*$|false\b|return\s+[1-9])" +) _SWALLOW = re.compile(r"\|\|\s*(?:true\b|:\s*(?:;|$))") _LONG_PRODUCING = ("--only-matching", "--count", "--files-with-matches", "--files-without-match") @@ -105,7 +114,7 @@ def _strip_comment(line: str) -> str: #: A function definition: `name() {`, `function name {`, either with a body #: that opens on the same line. Both forms are bash; the first is POSIX. -_FUNCTION = re.compile( +FUNCTION = re.compile( r"^(?:function\s+([A-Za-z_]\w*)\s*(?:\(\s*\))?|([A-Za-z_]\w*)\s*\(\s*\))\s*\{" ) @@ -184,7 +193,7 @@ def function_spans(script: str) -> list[tuple[int, int, str]]: for number, raw in enumerate(script.split("\n"), 1): body = _strip_comment(raw).rstrip() if depth == 0: - match = _FUNCTION.match(body.strip()) + match = FUNCTION.match(body.strip()) if match: start = number name = match.group(1) or match.group(2) @@ -500,14 +509,22 @@ def _branch_polarity(lines: list[tuple[int, str]], index: int) -> tuple[str | No for _, text in lines[index:]: for token in re.findall(r"(?:^|[;\s])(if|fi)(?=[;\s]|$)", text): depth += 1 if token == "if" else -1 - if depth == 1 and (re.match(r"^(?:else|elif)\b", text) or re.search(r";\s*else\b", text)): + if depth == 1 and re.match(r"^(?:else|elif)\b", text): branch = "else" body = text head = re.match(r"^(?:el)?if\s+(.*?)(?:;\s*then\b|$)", text) if head and text.startswith(("if", "elif")): # The condition is not the branch; a matcher in it is the subject. body = text[head.end(1) :] - if _FAILING.search(body) or _bare_assertion(body): + # A one-line `if` carries both branches in `body`, and crediting an + # `exit` to the wrong one inverts the polarity -- worse than the + # `decorative` it replaces. Split before deciding. + inline = re.split(r";\s*(?:else|elif)\b", body, maxsplit=1) + if len(inline) == 2: + for part, which in zip((piece.strip() for piece in inline), ("then", "else")): + if _FAILING.search(part) or _bare_assertion(part): + fails[which] = True + elif _FAILING.search(body) or _bare_assertion(body): fails[branch] = True if depth <= 0: break @@ -545,8 +562,19 @@ def _split(text: str) -> list[str] | None: def scan(script: str) -> list[Assertion]: - """Every matcher command in `script` whose status reaches the step.""" + """Every matcher command in `script` whose status reaches the step. + + A matcher inside a function body is not one of them, and is skipped here + rather than read -- logbook#66. Whether such a matcher decides the step + depends on where the function is *called*: bare under `set -e` its + verdict reaches the step, inside an `if` condition it does not, and an + uncalled function asserts nothing at all. This module does not work that + out, so it declines, and `unread.scan` announces what was declined. What + it must not do is the thing it did before: read some of them, by accident, + on whichever body lines happened to start with a matcher. + """ lines = logical_lines(script) + spans = function_spans(script) found: list[Assertion] = [] for index, (lineno, text) in enumerate(lines): diff --git a/tests/test_shell.py b/tests/test_shell.py index 8c376c2..ed05ad5 100644 --- a/tests/test_shell.py +++ b/tests/test_shell.py @@ -240,3 +240,64 @@ def test_if_then_at_the_top_level_is_still_its_own_line(self): "exit 1", "fi", ] + + +class TestOneLineIf: + """An `if` must read the same whether it is written on one line or four. + + logbook#73's blindness again, one newline earlier: `_FAILING` wanted a + `;`, `&&`, `|`, `{` or `(` in front of the `exit`, and in + `if grep -q x f; then exit 1; fi` what is in front of it is `then`. The + only statement in the branch was invisible, so a working negated guard -- + the shape this tool exists to judge -- read as `decorative`. + """ + + SHAPES = [ + ("then exits", "if grep -q 'y' f; then exit 1; fi", "if grep -q 'y' f; then\n exit 1\nfi"), + ( + "bang, then exits", + "if ! grep -q 'y' f; then exit 1; fi", + "if ! grep -q 'y' f; then\n exit 1\nfi", + ), + ( + "then exits, else does not", + "if grep -q 'y' f; then exit 1; else :; fi", + "if grep -q 'y' f; then\n exit 1\nelse\n :\nfi", + ), + ( + "else exits, then does not", + "if grep -q 'y' f; then :; else exit 1; fi", + "if grep -q 'y' f; then\n :\nelse\n exit 1\nfi", + ), + ( + "both branches exit", + "if grep -q 'y' f; then exit 1; else exit 2; fi", + "if grep -q 'y' f; then\n exit 1\nelse\n exit 2\nfi", + ), + ( + "neither branch can fail", + "if grep -q 'y' f; then echo noted; fi", + "if grep -q 'y' f; then\n echo noted\nfi", + ), + ] + + @pytest.mark.parametrize("name,inline,spread", SHAPES, ids=[s[0] for s in SHAPES]) + def test_one_line_reads_as_the_spread_form(self, name, inline, spread): + folded = one(inline) + opened = one(spread) + assert (folded.polarity, folded.undecided) == (opened.polarity, opened.undecided) + + def test_the_shape_itself(self): + # Spelled out rather than left to the comparison above, so that a + # change making *both* forms wrong cannot pass this file. + assert polarity("if grep -q 'y' f; then exit 1; fi") == "needs-no-match" + + def test_an_exit_is_not_credited_to_the_wrong_branch(self): + # The dangerous half: a one-line `if` holds both branches, and + # crediting the `exit` to the other one inverts the polarity, which + # is worse than the `decorative` it replaced. + assert polarity("if grep -q 'y' f; then :; else exit 1; fi") == "needs-match" + + def test_then_false_and_then_return_also_fail(self): + assert polarity("if grep -q 'y' f; then false; fi") == "needs-no-match" + assert polarity("if grep -q 'y' f; then return 1; fi") == "needs-no-match" From 67a30c588a20ae2494cc78efd64546643d89fa50 Mon Sep 17 00:00:00 2001 From: "richmond-avenal[bot]" <323733923+richmond-avenal[bot]@users.noreply.github.com> Date: Tue, 17 Nov 2026 04:38:49 +0000 Subject: [PATCH 3/4] feat: say when a matcher is inside a function body logbook#66. Two byte-identical guards in unbuilt's ci.yml, one at the top level of a `run:` script and one inside a function that is then called: the first was reported, the second was not, and nothing anywhere said so. `scripts` counted the file, so the denominator looked right, and a repository whose guards all live in functions got No assertions here. [...] Nothing to check. over a file holding two of them. Whether a matcher in a function body decides the step depends on where the function is *called* -- bare under `set -e` its verdict reaches the step, in an `if` condition it does not, and an uncalled function asserts nothing. `shell.scan` does not work that out, so it now declines explicitly instead of reading whichever body lines happened to start with a matcher, and `unread.scan` announces what was declined. That is the module built for exactly this (logbook#69): printed, never a finding, never in the exit code. The line reported is the matcher's own, not the `name() {` above it. Across the org this adds one line of output -- unbuilt ci.yml:321, the instance the issue was filed about -- and changes no verdict anywhere: 183 assertions, 22 negated, 0 findings, before and after. --- src/deadassert/shell.py | 2 ++ src/deadassert/unread.py | 61 ++++++++++++++++++++++++++++++++++++++-- tests/test_shell.py | 39 +++++++++++++++++++++++++ tests/test_unread.py | 54 +++++++++++++++++++++++++++++++++++ 4 files changed, 154 insertions(+), 2 deletions(-) diff --git a/src/deadassert/shell.py b/src/deadassert/shell.py index 837969c..308659c 100644 --- a/src/deadassert/shell.py +++ b/src/deadassert/shell.py @@ -580,6 +580,8 @@ def scan(script: str) -> list[Assertion]: for index, (lineno, text) in enumerate(lines): if not any(name in text for name in MATCHERS): continue + if in_function(spans, lineno): + continue polarity: str | None = None undecided: str | None = None diff --git a/src/deadassert/unread.py b/src/deadassert/unread.py index 76e54af..1719acc 100644 --- a/src/deadassert/unread.py +++ b/src/deadassert/unread.py @@ -36,6 +36,13 @@ that takes the advice ends up with a tool that reads almost none of its assertions and does not currently admit it. * `jq -e` -- the one jq invocation whose exit status is a verdict. +* `in function` -- a matcher inside a shell function body. The one shape + here that `deadassert` could read and declines to: whether the body's + verdict reaches the step depends on where the function is called, which + `shell.scan` does not work out (logbook#66). It used to be silent about + them, which is worse than either answer -- a repository whose guards all + live in functions reported `Every assertion here fails when the thing it + names stops being true.` over a file it had not read. `test "$s" -eq 0` and `[ -f x ]` are deliberately **not** counted, per the caveat on `logbook#69`. They are the most common assertion in the org and @@ -91,7 +98,7 @@ class Unread: #: 1-based, within the script. line: int - #: One of `assert`, `diff`, `jq -e`. + #: One of `assert`, `diff`, `jq -e`, `in function`. kind: str #: The line it was found in, stripped, as one line. text: str @@ -222,9 +229,59 @@ def _commands(script: str) -> list[Unread]: return found +def _in_functions(script: str) -> list[Unread]: + """Matchers inside a function body, on the physical line they sit on. + + Physical lines, like `_asserts` and for the same reason: the body is one + logical line once `shell.logical_lines` has joined it, and a reader sent + to the `name() {` line to look at a grep three lines below it will not + thank us. + + Two exclusions, the same two `shell.scan` applies to a matcher it does + read: a producing flag (`-o`, `-c`, `-l`) means the command is being run + for its output, and `$(...)` means it is feeding a variable. Everything + else in a function body is announced. Over-announcing here costs a line + of output; under-announcing is the defect this exists to fix. + """ + found: list[Unread] = [] + spans = shell.function_spans(script) + if not spans: + return [] + lines = script.split("\n") + for first, last, _name in spans: + for number in range(first, min(last, len(lines)) + 1): + text = lines[number - 1].strip() + if not text or text.startswith(_COMMENT): + continue + body = text + if number == first: + # `check() { grep -q x f; }` -- the definition's own prefix + # hides the first command behind a head word that is the + # function's name. + head = shell.FUNCTION.match(text) + if head: + body = text[head.end() :] + for offset, segment in _simple_commands(body): + command = shell.command_head(segment, shell.MATCHERS) + if command is None: + continue + words = shell.split(command[0]) + if words is None: + continue + if shell.in_substitution(body, offset): + continue + if shell.parse_matcher(words)[4]: + continue + found.append(Unread(line=number, kind="in function", text=text)) + return found + + def scan(script: str) -> list[Unread]: """Every assertion-shaped construct in `script` that `shell.scan` ignores. Sorted by line, so the report reads in file order. """ - return sorted(_asserts(script) + _commands(script), key=lambda item: item.line) + return sorted( + _asserts(script) + _commands(script) + _in_functions(script), + key=lambda item: item.line, + ) diff --git a/tests/test_shell.py b/tests/test_shell.py index ed05ad5..6c98d7d 100644 --- a/tests/test_shell.py +++ b/tests/test_shell.py @@ -301,3 +301,42 @@ def test_an_exit_is_not_credited_to_the_wrong_branch(self): def test_then_false_and_then_return_also_fail(self): assert polarity("if grep -q 'y' f; then false; fi") == "needs-no-match" assert polarity("if grep -q 'y' f; then return 1; fi") == "needs-no-match" + + +class TestFunctionBodies: + """logbook#66: `scan` declines a function body rather than half-reading it. + + `unread.scan` announces what is declined -- see tests/test_unread.py. The + contract here is only that nothing in a body is silently treated as + top-level code, because whether it reaches the step depends on where the + function is called and this module does not work that out. + """ + + def test_a_matcher_in_a_function_body_is_not_an_assertion(self): + script = "guard() {\n if grep -q 'y' f; then exit 1; fi\n}\nguard" + assert shell.scan(script) == [] + + def test_nor_on_a_body_line_below_the_definition(self): + # Before this, the first body line was joined to `name() {` and the + # rest were read as though they were top-level code. + script = "guard() {\n echo x\n grep -q 'y' f\n}\nguard" + assert shell.scan(script) == [] + + def test_nor_one_the_joined_line_would_have_surfaced(self): + # The case the skip is actually load bearing for. The body is one + # logical line whose head word is the function's name, so most + # matchers in there are invisible anyway -- but `pipeline_parts` + # splits on `|`, and without the skip this one was read as a + # top-level assertion and reported against the definition's line. + script = 'check() {\n printf \'%s\' "$out" | grep -q Y || exit 1\n}\ncheck' + assert shell.scan(script) == [] + + def test_a_matcher_after_the_body_is_still_read(self): + script = "guard() {\n grep -q 'y' f\n}\nguard\ngrep -qF 'after' out.txt" + assert [a.pattern for a in shell.scan(script)] == ["after"] + + def test_spans_cover_both_definition_forms(self): + assert shell.function_spans("f() {\n :\n}") == [(1, 3, "f")] + assert shell.function_spans("function f {\n :\n}") == [(1, 3, "f")] + assert shell.function_spans("f() { :; }") == [(1, 1, "f")] + assert shell.function_spans("echo not-a-function") == [] diff --git a/tests/test_unread.py b/tests/test_unread.py index ed27796..11e0680 100644 --- a/tests/test_unread.py +++ b/tests/test_unread.py @@ -170,3 +170,57 @@ def test_constructs_come_back_in_line_order(self): """ assert [item.line for item in unread.scan(script)] == [2, 4, 6] assert kinds(script) == ["diff", "assert", "jq -e"] + + +class TestInFunction: + """logbook#66: matchers in a function body were read by neither half. + + `shell.scan` skipped them (silently, and not even consistently) and this + module did not know about them, so a file whose guards all live in + functions got an all-clear measured over nothing. + """ + + def test_the_logbook_66_instance(self): + # Verbatim shape from unbuilt's ci.yml, the file this was found in. + script = """ +no_diagnostic_on_stdout() { + if grep -qF 'unbuilt: ' out.txt; then + echo "diagnostic reached stdout:" >&2 + exit 1 + fi +} + +run_typo +no_diagnostic_on_stdout +""" + assert kinds(script) == ["in function"] + + def test_the_line_is_the_matcher_not_the_definition(self): + # A reader sent to the `name() {` line to look at a grep three lines + # below it will not thank us. + script = "guard() {\n echo x\n grep -q 'y' f\n}\nguard" + assert one(script).line == 3 + + def test_a_one_line_definition_is_found_too(self): + # The definition's own prefix hides the first command behind a head + # word that is the function's name. + assert kinds("check() { grep -q 'y' f && exit 1; }") == ["in function"] + + def test_a_matcher_outside_any_function_is_not_counted(self): + # It is read properly by shell.scan; counting it here would double it. + assert kinds("grep -q 'y' f") == [] + + def test_a_function_with_no_matcher_is_not_counted(self): + assert kinds("flat() {\n tr '\\n' ' ' <\"$1\" | tr -s ' '\n}") == [] + + def test_a_producing_matcher_in_a_body_is_not_counted(self): + # Run for its output, not its verdict -- the same exclusion shell.scan + # applies to a matcher it does read. + assert kinds("count() {\n grep -c 'y' f > n.txt\n}") == [] + + def test_a_captured_matcher_in_a_body_is_not_counted(self): + assert kinds("get() {\n line=$(grep 'y' f)\n}") == [] + + def test_two_matchers_in_one_body_are_two(self): + script = "guard() {\n grep -q 'a' f\n grep -q 'b' f\n}\nguard" + assert kinds(script) == ["in function", "in function"] From 10c863ae8af021b1cbc3c6a95110dd165835d969 Mon Sep 17 00:00:00 2001 From: "richmond-avenal[bot]" <323733923+richmond-avenal[bot]@users.noreply.github.com> Date: Tue, 17 Nov 2026 04:41:50 +0000 Subject: [PATCH 4/4] test: guard both shapes at the CLI, and re-measure the README The unit tests cover the reading; this covers what the tool prints for a whole file, which is what both issues were actually about. The fixture is built with `printf` rather than a heredoc on purpose: a heredoc's lines are physical lines of this script, so a fixture about dead assertions written that way would put its own greps into this repository's assertion count and arrive as findings against the file that built it. Run against main the step goes red and prints the two false positives side by side, which is the only reason it is worth having. README: the measured table was taken before the logbook#64 sweep closed the last of the findings. Re-measured tonight over the same 31 repositories -- 183 assertions read, 0 findings, 79 not read -- and the self-run output quoted above re-taken with the new step in place. --- .github/workflows/ci.yml | 53 +++++++++++++++++++++++++++++++++++++++ README.md | 54 ++++++++++++++++++++++++---------------- tests/test_shell.py | 10 ++++---- 3 files changed, 91 insertions(+), 26 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 69561a7..8b43374 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -189,6 +189,59 @@ jobs: assert any(c.startswith(wanted) for c in commands), commands PY + # logbook#73 and logbook#66, at the CLI rather than in pytest: both + # were about what the tool does to a whole file, and both were false + # on shapes this file does not itself contain. + # + # `printf` rather than a heredoc, for the reason the `exit codes` step + # uses it: a heredoc's lines are physical lines of *this* script, so a + # fixture written that way puts its greps into this repository's own + # assertion count, and a fixture about dead assertions would start + # arriving as findings against the file that built it. + - name: the shapes logbook#73 and logbook#66 were filed for + run: | + set -euo pipefail + mkdir -p shapes/.github/workflows + printf '%s\n' \ + "'on': push" \ + "jobs:" \ + " j:" \ + " steps:" \ + " - run: |" \ + " grep -qxF 'ok' out.txt" \ + " echo hi | grep -qxF 'ok' out.txt || {" \ + " echo 'absent'" \ + " exit 1" \ + " }" \ + " if grep -qxF 'ok' out.txt; then exit 1; fi" \ + " - run: |" \ + " guard() {" \ + " grep -qF 'ok' out.txt" \ + " }" \ + " guard" \ + > shapes/.github/workflows/ci.yml + deadassert shapes | tee shapes.txt + deadassert shapes --json > shapes.json + python - <<'PY' + import json + d = json.load(open("shapes.json")) + + # Three assertions read, not two: the multi-line `|| { ... }` is one + # of them, and it used to be reported `decorative` because the + # `exit 1` two lines down was never seen. + assert d["findings"] == [], d["findings"] + assert d["assertions"] == 3, d["assertions"] + + # The one-line `if ... then exit 1; fi`. Read as `decorative` until + # `then` counted as a command separator, so the negated count is + # what pins it. + assert d["negated"] == 1, d["negated"] + + # The guard in the function body: declined, and said so. + unread = [(x["kind"], x["command"]) for x in d["unread"]] + assert unread == [("in function", "grep -qF 'ok' out.txt")], unread + PY + # The assertion above is only worth anything if it can go red. Break # one assertion in a copy of this file and check that it does. - name: a broken assertion in this file is caught diff --git a/README.md b/README.md index 0982c47..ab523e9 100644 --- a/README.md +++ b/README.md @@ -164,6 +164,12 @@ stops being reported. verdict reached by `diff`, `test` or a language's own assert is not read — which is a reason to prefer those, not a gap to fill. See below. It is no longer *invisible*, though: those get counted, and the count is printed. +- **A matcher inside a shell function body is not read.** Whether its + verdict reaches the step depends on where the function is *called* — bare + under `set -e` it does, in an `if` condition it does not, and an uncalled + function asserts nothing at all. That is not worked out here, so the body + is declined rather than half-read, and every matcher in one is printed + under `not read:`. - **`unwitnessed` is a smell, not a proof.** It says nothing in *these workflows* establishes the string can appear. The proof may well live in a unit test, where it is arguably better placed. What the finding is really @@ -194,7 +200,7 @@ So it counts them now: ```console $ deadassert . Every assertion here fails when the thing it names stops being true. -2 assertions in 15 scripts across 1 workflow file, 0 of them negated. Not counted above: 11 assertions in 5 of those scripts (9 assert, 2 diff), listed below. +2 assertions in 16 scripts across 1 workflow file, 0 of them negated. Not counted above: 15 assertions in 6 of those scripts (13 assert, 2 diff), listed below. not read: ci.yml:37 assert assert total >= 110, f"only {total} tests collected" @@ -202,9 +208,14 @@ not read: ... ``` -Three shapes, picked by counting what the workflow files in this +Four shapes. Three were picked by counting what the workflow files in this organisation actually use: a language's own `assert` (nearly always Python, -via `-c` or a heredoc), `diff` and `cmp`, and `jq -e`. +via `-c` or a heredoc), `diff` and `cmp`, and `jq -e`. The fourth is +`in function`, and it is the only one here that is a `grep` — a matcher in a +function body, which this tool could read and declines to, for the reason in +the caveat above. It was silent about those until it wasn't: two identical +guards in one file, one at the top level and one in a function, and only the +first was ever reported. **This decides nothing.** It does not judge whether a `diff` can fail; it reports that one is there and was not read. The same move the tool already @@ -255,21 +266,22 @@ is small on purpose, and it is printed rather than hidden. ## Measured on something real Run across the 31 repositories of the organisation this was written in — 37 -workflow files, 360 `run:` scripts: +workflow files, 364 `run:` scripts: | | count | | --- | --- | -| assertions read | 170 | -| negated (`needs-no-match`) | 24 | -| `unwitnessed` | 6 | -| `prefix` | 3 | +| assertions read | 183 | +| negated (`needs-no-match`) | 22 | +| `unwitnessed` | 0 | +| `prefix` | 0 | | `swallowed` / `masked` / `decorative` | 0 | -| not read | 74, in 24 scripts | +| not read | 79, in 24 scripts | -Seven of the thirty-one repositories have at least one finding. The first -run of this tool found 33 — 12 `unwitnessed` and 21 `prefix`, across 12 -repositories — and the 24 that have gone are a repo-at-a-time sweep, not a -`sed`; the remaining 9 are the tail of it. +No findings left anywhere, which is not the tool scoring zero — it is the +end of a sweep. The first run found 33, 12 `unwitnessed` and 21 `prefix` +across 12 repositories, and they were closed a repository at a time over +three weeks rather than with a `sed`. The number to watch now is the last +row, not the empty ones. The three can't-fail kinds scoring zero is the result I did not expect: every `|| true` in that organisation is on a *tool invocation*, deliberately @@ -277,14 +289,14 @@ allowing a non-zero findings exit before the output is asserted, which is correct usage. An early version of this tool reported all of them and was wrong to. -The last row is the one that changes how you should read the others. **74 -assertions in these files are not read at all** — 67 Python asserts, 5 -`diff`, 2 `jq -e` — against 170 that are, and they are concentrated: 15 -repositories have at least one, and 3 have nothing *but* unread assertions, -so the verdict on them used to be `Nothing to check.` The 9 findings above -are a verdict about the greps in this organisation, which is a smaller thing -than it looks, and the point of printing the number is that you no longer -have to take my word for how much smaller. +The last row is the one that changes how you should read the others. **79 +assertions in these files are not read at all** — 71 Python asserts, 5 +`diff`, 2 `jq -e` and 1 in a function body — against 183 that are, and they +are concentrated: 15 repositories have at least one, and 3 have nothing +*but* unread assertions, so the verdict on them used to be `Nothing to +check.` An all-clear here is a verdict about the greps in this organisation, +which is a smaller thing than it looks, and the point of printing the number +is that you no longer have to take my word for how much smaller. `shellcheck` 0.9.0 reports none of these at default settings. With `--enable=all` it finds the two pipeline cases as `SC2312` (info) and diff --git a/tests/test_shell.py b/tests/test_shell.py index 6c98d7d..faec729 100644 --- a/tests/test_shell.py +++ b/tests/test_shell.py @@ -199,7 +199,7 @@ class TestBraceGroups: """ def test_multi_line_brace_group_is_an_assertion(self): - script = 'echo hi | grep -qxF \'x\' || {\n echo "no"\n exit 1\n }' + script = "echo hi | grep -qxF 'x' || {\n echo \"no\"\n exit 1\n }" assert polarity(script) == "needs-match" def test_single_line_brace_group_still_is(self): @@ -212,12 +212,12 @@ def test_multi_line_and_brace_group_needs_no_match(self): def test_newlines_in_the_group_become_separators(self): # The bug was not the joining, it was joining with a space: `_FAILING` # wants an `exit` that starts a command, and `"no" exit 1` does not. - script = 'grep -qF \'x\' f || {\n echo "no"\n exit 1\n}' - assert one(script).text == 'grep -qF \'x\' f || { echo "no"; exit 1; }' + script = "grep -qF 'x' f || {\n echo \"no\"\n exit 1\n}" + assert one(script).text == "grep -qF 'x' f || { echo \"no\"; exit 1; }" def test_a_group_holding_only_a_message_is_still_decorative(self): # Fixing the join must not make every brace group look like a failure. - script = 'grep -qF \'x\' f || {\n echo "just saying"\n}' + script = "grep -qF 'x' f || {\n echo \"just saying\"\n}" assert polarity(script) == "decorative" def test_an_unclosed_brace_does_not_swallow_the_script(self): @@ -328,7 +328,7 @@ def test_nor_one_the_joined_line_would_have_surfaced(self): # matchers in there are invisible anyway -- but `pipeline_parts` # splits on `|`, and without the skip this one was read as a # top-level assertion and reported against the definition's line. - script = 'check() {\n printf \'%s\' "$out" | grep -q Y || exit 1\n}\ncheck' + script = "check() {\n printf '%s' \"$out\" | grep -q Y || exit 1\n}\ncheck" assert shell.scan(script) == [] def test_a_matcher_after_the_body_is_still_read(self):