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/src/deadassert/shell.py b/src/deadassert/shell.py index f3d0d97..308659c 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") @@ -99,18 +108,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 +274,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 @@ -342,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 @@ -387,13 +562,26 @@ 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): 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 1804d3d..faec729 100644 --- a/tests/test_shell.py +++ b/tests/test_shell.py @@ -187,3 +187,156 @@ 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", + ] + + +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" + + +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"]