@amsterdamdatalabs/adl-agent-control-linux-x64 0.1.30 → 0.1.32

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/repository/no_multiline_comments/test_check.py

@@ -0,0 +1,391 @@
+"""REP-007 (`repository.no-multiline-comments`), Bug 602."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from pathlib import Path
+
+import pytest
+from fixture_trees import fixture_trees
+
+from adl_compliance import runner
+from adl_compliance.core.verdict import Outcome, Verdict
+from adl_compliance.policy.registry import load
+
+ROW = load().by_id("REP-007")
+REGISTER_PATH = f"{fixture_trees()['compliance']}/ratchets/REP-007-multiline-comments.yaml"
+FIX = "move the explanation to docs/ and leave at most a one-line pointer"
+
+
+def tree(tmp_path: Path, files: Mapping[str, str], register: str | None = None) -> Path:
+    root = tmp_path / "repo"
+    root.mkdir(parents=True)
+    for rel, body in files.items():
+        target = root / rel
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(body, encoding="utf-8")
+    if register is not None:
+        target = root / REGISTER_PATH
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(register, encoding="utf-8")
+    return root
+
+
+def register_of(*paths: str) -> str:
+    return "schema_version: 1\nfiles:\n" + "".join(f"  - {p}\n" for p in paths) if paths else (
+        "schema_version: 1\nfiles: []\n"
+    )
+
+
+def grade(root: Path, *, files: tuple[str, ...] | None = None) -> Verdict:
+    given = files if files is not None else tuple(
+        sorted(
+            str(p.relative_to(root)) for p in root.rglob("*")
+            if p.is_file() and str(p.relative_to(root)) != REGISTER_PATH
+        )
+    )
+    return runner.run(ROW, root, given, exhaustive=True)
+
+
+BANNED = {
+    "two-line-comments.ts": "const a = 1;\n// one\n// two\nconst b = 2;\n",
+    "two-line-comments.tsx": "// one\n// two\nexport const x = 1;\n",
+    "two-line-comments.js": "// one\n// two\n",
+    "two-line-comments.mjs": "// one\n// two\n",
+    "two-line-comments.cjs": "// one\n// two\n",
+    "doc-block.ts": "/**\n * Explains.\n */\nexport const x = 1;\n",
+    "plain-block.ts": "/* one\n   two */\nexport const x = 1;\n",
+    "plain-block.rs": "/* one\n two */\nfn main() {}\n",
+    "doc-lines.rs": "/// one\n/// two\nfn main() {}\n",
+    "hash-pair.py": "x = 1\n# one\n# two\n",
+    "docstring.py": 'def f():\n    """One.\n\n    Two.\n    """\n',
+    "module-docstring.py": '"""One.\nTwo."""\n',
+    "hash-pair.sh": "#!/bin/sh\n# one\n# two\necho hi\n",
+    "hash-pair.bash": "# one\n# two\n",
+    "hash-pair.zsh": "# one\n# two\n",
+    "justfile": "# one\n# two\nbuild:\n    echo hi\n",
+    "nested/justfile": "build:\n    echo hi\n# one\n# two\n",
+    "Justfile": "# one\n# two\nbuild:\n    echo hi\n",
+    "two-line-comments.jsx": "// one\n// two\n",
+    "two-line-comments.mts": "// one\n// two\n",
+    "two-line-comments.cts": "// one\n// two\n",
+    "bin/py-tool": "#!/usr/bin/env python3\n# one\n# two\nx = 1\n",
+    "bin/py-direct": "#!/usr/bin/python\nx = 1\n# one\n# two\n",
+    "bin/sh-tool": "#!/bin/sh\n# one\n# two\n",
+    "bin/bash-env": "#!/usr/bin/env bash\n# one\n# two\n",
+    "bin/env-s": "#!/usr/bin/env -S bash -e\n# one\n# two\n",
+    "bin/node-tool": "#!/usr/bin/env node\n// one\n// two\n",
+    "heredoc-then-pair.sh": "cat <<'EOF'\n# not\n# comment\nEOF\n# real\n# pair\n",
+    "heredoc-dash-then-pair.sh": "cat <<-EOF\n\t# x\n\t# y\n\tEOF\n# real\n# pair\n",
+    "heredoc-in-string.sh": 'echo "use <<END here"\n# real\n# pair\n',
+    "heredoc-in-single-quotes.sh": "echo 'use <<END here'\n# real\n# pair\n",
+    "heredoc-in-comment.sh": "echo hi # <<EOF\n# real\n# pair\n",
+    "heredoc-arithmetic.sh": "x=$((1<<FOO))\n# real\n# pair\n",
+    "here-string.sh": "cat <<<WORD\n# real\n# pair\n",
+    "two-heredocs.sh": "cat <<A <<B\n# x\nA\n# y\nB\n# real\n# pair\n",
+    "shellcheck-pair.sh": "# explanation one\n# shellcheck is why\n",
+    "noqa-pair.py": "# a long explanation\n# see noqa policy\nx = 1\n",
+    "type-ignore-pair.py": "# first\n# the type: ignore story\nx = 1\n",
+    "pyright-pair.py": "# first\n# about pyright: modes\nx = 1\n",
+    "directive-pair.ts": "// first\n// why eslint-disable exists\nconst a = 1;\n",
+    "two-one-line-blocks.ts": "/* one */\n/* two */\nconst x = 1;\n",
+    "doc-then-line.ts": "/** one */\n// two\nconst x = 1;\n",
+    "line-then-block.ts": "// one\n/* two */\nconst x = 1;\n",
+    "cr-only.ts": "// a\r// b\rconst a = 1;\r",
+    "cr-only.py": "# a\r# b\rx = 1\r",
+    "bin/mksh-tool": "#!/bin/mksh\n# one\n# two\n",
+    "bin/ksh93-env": "#!/usr/bin/env ksh93\n# one\n# two\n",
+    "bin/env-glued-S": "#!/usr/bin/env -Sbash\n# one\n# two\n",
+    "bin/env-spaced-S": "#!/usr/bin/env -S bash\n# one\n# two\n",
+    "bin/env-split-string": "#!/usr/bin/env --split-string=bash -e\n# one\n# two\n",
+    "jsx-comments.tsx": "export const a = (\n  <div>\n    {/* a */}\n    {/* b */}\n  </div>\n);\n",
+    "jsx-comments.jsx": "export const a = (\n  <div>\n    {/* a */}\n    {/* b */}\n  </div>\n);\n",
+    "jsx-comments.js": "export const a = (\n  <div>\n    { /* a */ }\n    {/* b */}\n  </div>\n);\n",
+    "fstring-statement.py": 'f"""a\n{1}\nb"""\n',
+    "ansi-c-quote.sh": "echo $'it\\'s'\n# real one\n# real two\n",
+    "backslash-heredoc.sh": "cat <<\\EOF\ndon't\nEOF\n# real one\n# real two\n",
+    "heredoc-dash-delimiter.sh": "cat <<END-X\nbody\nEND-X\n# real one\n# real two\n",
+    "heredoc-dot-delimiter.sh": "cat <<E.O\nbody\nE.O\n# real one\n# real two\n",
+    "heredoc-partly-quoted.sh": 'cat <<E"OF"\nbody\nEOF\n# real one\n# real two\n',
+    "multiline-arith.sh": "((\n x = 1 << FOO\n))\n# real one\n# real two\n",
+    "old-arith.sh": "y=$[1<<FOO]\n# real one\n# real two\n",
+    "nested-quotes-in-subst.sh": 'x="$(echo "it\'s")"\n# real one\n# real two\n',
+    "nested-quotes-in-backticks.sh": 'x="`echo "it\'s"`"\n# real one\n# real two\n',
+    "nested-quotes-in-param.sh": 'x="${y:-"it\'s"}"\n# real one\n# real two\n',
+    "backtick-apostrophe.sh": "x=`echo it\\'s`\n# real one\n# real two\n",
+    "param-strip-quote.sh": "y=${x#'a'}\n# real one\n# real two\n",
+    "two-heredocs-then-pair.sh": "cat <<A <<'B'\n# a\nA\n# b\nB\n# real one\n# real two\n",
+    "heredoc-in-subst.sh": "x=$(cat <<EOF\n# a\n# b\nEOF\n)\n# real one\n# real two\n",
+    "directive-between-prose.sh": "# prose a\n# shellcheck disable=SC2034\n# prose b\n",
+    "directive-between-prose.py": "# prose a\n# noqa\n# prose b\nx = 1\n",
+    "directive-between-prose.ts": "// prose a\n// @ts-ignore\n// prose b\n",
+    "directive-then-prose.py": "# noqa: E501 this is a long explanation\n# noqa: E501 that continues here\nx = 1\n",
+    "type-ignore-prose.py": "# type: ignore because the library is\n# type: ignore untyped and we cannot fix\nx = 1\n",
+    "eslint-reason-prose.ts": "// eslint-disable-next-line no-x -- long reason\n// eslint-disable-next-line no-y -- more reason\nx;\n",
+    "two-blocks-per-line.ts": "/* a */ /* b */\n/* c */ /* d */\n",
+    "bytes-statement.py": "b'''a\nb'''\n",
+    "consecutive-string-statements.py": "'a'\n'b'\n'c'\n",
+    "bin/env-u-bash": "#!/usr/bin/env -u FOO bash\n# one\n# two\n",
+    "bin/uv-script": "#!/usr/bin/env -S uv run --script\n# one\n# two\nx = 1\n",
+    "bin/tsx-tool": "#!/usr/bin/env tsx\n// one\n// two\n",
+    "x.just": "# one\n# two\nbuild:\n    echo hi\n",
+    ".justfile": "# one\n# two\nbuild:\n    echo hi\n",
+}
+
+
+@pytest.mark.parametrize(("name", "body"), sorted(BANNED.items()))
+def test_each_banned_shape_is_reported_at_file_and_line(tmp_path: Path, name: str, body: str) -> None:
+    root = tree(tmp_path, {name: body})
+    verdict = grade(root)
+    assert verdict.outcome is Outcome.FINDINGS, verdict.render()
+    assert {f.rule for f in verdict.findings} == {"MLC-001"}
+    finding = verdict.findings[0]
+    assert finding.path == name
+    assert finding.line is not None and finding.line >= 1
+    assert f"{name}:{finding.line}:" in finding.render()
+    assert FIX in finding.fix
+
+
+def test_the_reported_line_is_where_the_comment_starts(tmp_path: Path) -> None:
+    root = tree(tmp_path, {"a.ts": "const a = 1;\n\n// one\n// two\n"})
+    assert [f.line for f in grade(root).findings] == [3]
+    root = tree(tmp_path / "b", {"a.ts": "const a = 1;\n/* one\n two */\n"})
+    assert [f.line for f in grade(root).findings] == [2]
+
+
+ALLOWED = {
+    "single.ts": "// one\nconst a = 1;\n// two\nconst b = 2;\n",
+    "single.py": "# one\nx = 1\n# two\ny = 2\n",
+    "one-line-docblock.ts": "/** One. */\nexport const x = 1;\n",
+    "one-line-block.ts": "/* one */\nexport const x = 1;\n",
+    "one-line-docstring.py": '"""One."""\n',
+    "shebang-then-one.sh": "#!/usr/bin/env bash\n# one\necho hi\n",
+    "shebang-only.py": "#!/usr/bin/env python3\nx = 1\n",
+    "ts-expect-error.ts": "// @ts-expect-error legacy\nconst a: number = 'x';\n// @ts-ignore\nconst b = 1;\n",
+    "eslint.ts": "// eslint-disable-next-line no-console\nconsole.log(1);\n",
+    "biome.ts": "// biome-ignore lint/suspicious/noExplicitAny: legacy\nconst a: any = 1;\n",
+    "noqa.py": "import os  # noqa: F401\nimport sys  # type: ignore\n",
+    "directive-pair-apart.py": "# type: ignore\nx = 1\n# noqa\ny = 2\n",
+    "trailing.ts": "const a = 1; // one\nconst b = 2; // two\n",
+    "trailing.sh": "echo a # one\necho b # two\n",
+    "string-lines.ts": "const s = `\n// not a comment\n// not a comment\n`;\n",
+    "string-url.ts": "const u = 'http://example.com'; const v = \"//x\";\n",
+    "string-block.ts": "const s = '/* not\\n a comment */';\n",
+    "regex.ts": "const r = /\\/\\/+/g;\nconst q = /[\"']/;\n",
+    "string-hash.py": 'x = """\n# not a comment\n# not a comment\n"""\n',
+    "heredoc.sh": "cat <<'EOF'\n# not a comment\n# not a comment\nEOF\n",
+    "rust-char.rs": "fn f() -> char { '\"' }\nfn g<'a>(x: &'a str) {}\n",
+    "rust-raw.rs": 'const S: &str = r#"\n// not\n// comments\n"#;\n',
+    "notes.md": "# one\n# two\n\n/* a\n b */\n",
+    "data.yaml": "# one\n# two\n",
+    "LICENSE": "# one\n# two\n",
+    "bin/plain-text": "not a script\n# one\n# two\n",
+    "bin/other-interpreter": "#!/usr/bin/env ruby\n# one\n# two\n",
+    "bin/one-comment": "#!/bin/sh\n# one\necho hi\n",
+    "multiline-string.sh": 'echo "\n# not\n# comment\n"\n',
+    "multiline-single-quote.sh": "echo '\n# not\n# comment\n'\n",
+    "arith-then-code.sh": "x=$((1<<FOO))\necho hi\n",
+    "directive-only-run.ts": "// eslint-disable-next-line a\n// @ts-expect-error b\nconst a = 1;\n",
+    "block-directive-pair.ts": "/* eslint-disable */\n/* eslint-enable */\nconst a = 1;\n",
+    "separated-blocks.ts": "/* one */\nconst a = 1;\n/* two */\nconst b = 2;\n",
+    "brace-then-line-comment.js": "{} // a\n// b\n",
+    "brace-then-line-comment.tsx": "{} // a\n// b\n",
+    "brace-block-in-ts.ts": "{/* a */}\n{/* b */}\n",
+    "brace-two-blocks.js": "{/* a */ /* b */}\n{/* c */ /* d */}\n",
+    "brace-wrong-order.js": "}/* a */{\n}/* b */{\n",
+    "jsx-single-comment.tsx": "export const a = (\n  <div>\n    {/* a */}\n    <b />\n  </div>\n);\n",
+    "jsx-brace-code.tsx": "const a = {\n  b: 1, /* a */\n};\nconst c = {};\n",
+    "trailing-blocks.ts": "const a = 1; /* one */\nconst b = 2; /* two */\n",
+    "backslash-heredoc-hashes.sh": "cat <<\\EOF\n# x\n# y\nEOF\necho\n",
+    "heredoc-indented-terminator.sh": "cat <<EOF\n  EOF\n# x\n# y\nEOF\necho\n",
+    "two-heredocs-hashes.sh": "cat <<A <<'B'\n# a\n# a2\nA\n# b\n# b2\nB\necho\n",
+    "heredoc-tab-hashes.sh": "cat <<-EOF\n\t# a\n\t# b\n\tEOF\necho\n",
+    "directive-then-one-prose.py": "# noqa\n# prose\nx = 1\n",
+    "directive-with-code-list.py": "# noqa: E501, F401\n# noqa: S101\nx = 1\n",
+    "single-string-statements-apart.py": "'a'\nx = 1\n'b'\n",
+}
+
+
+@pytest.mark.parametrize(("name", "body"), sorted(ALLOWED.items()))
+def test_each_allowed_shape_is_silent(tmp_path: Path, name: str, body: str) -> None:
+    root = tree(tmp_path, {name: body})
+    verdict = grade(root)
+    assert verdict.outcome is Outcome.CLEAN, verdict.render()
+
+
+def test_the_banned_and_allowed_corpora_are_not_empty() -> None:
+    assert len(BANNED) >= 15 and len(ALLOWED) >= 20
+
+
+def test_fixture_files_are_excluded_by_the_row_scope(tmp_path: Path) -> None:
+    root = tree(tmp_path, {"checks/x/fixtures/bad.ts": "// one\n// two\n", "ok.ts": "// one\n"})
+    verdict = grade(root)
+    assert verdict.outcome is Outcome.CLEAN, verdict.render()
+
+
+# ------------------------------------------------------------------ the register
+def test_an_absent_register_means_no_grants(tmp_path: Path) -> None:
+    root = tree(tmp_path, {"a.ts": "// one\n// two\n"})
+    assert not (root / REGISTER_PATH).exists()
+    verdict = grade(root)
+    assert verdict.outcome is Outcome.FINDINGS
+    assert [f.path for f in verdict.findings] == ["a.ts"]
+
+
+def test_a_file_on_the_register_is_exempt(tmp_path: Path) -> None:
+    root = tree(
+        tmp_path, {"a.ts": "// one\n// two\n", "b.py": "x = 1\n"}, register_of("a.ts")
+    )
+    verdict = grade(root)
+    assert verdict.outcome is Outcome.CLEAN, verdict.render()
+
+
+def test_every_file_off_the_register_must_still_be_clean(tmp_path: Path) -> None:
+    root = tree(
+        tmp_path,
+        {"a.ts": "// one\n// two\n", "new.ts": "// one\n// two\n"},
+        register_of("a.ts"),
+    )
+    verdict = grade(root)
+    assert [(f.rule, f.path) for f in verdict.findings] == [("MLC-001", "new.ts")]
+
+
+def test_a_register_entry_with_no_multiline_comment_left_is_stale(tmp_path: Path) -> None:
+    root = tree(tmp_path, {"a.ts": "// one\nconst a = 1;\n"}, register_of("a.ts"))
+    verdict = grade(root)
+    assert verdict.outcome is Outcome.FINDINGS, verdict.render()
+    [finding] = verdict.findings
+    assert (finding.rule, finding.path) == ("MLC-002", "a.ts")
+    assert "remove it from the register: the ratchet only shrinks" in finding.fix
+
+
+def test_a_register_entry_for_a_missing_file_is_stale(tmp_path: Path) -> None:
+    root = tree(tmp_path, {"a.ts": "const a = 1;\n"}, register_of("gone.ts"))
+    verdict = grade(root)
+    assert [(f.rule, f.path) for f in verdict.findings] == [("MLC-002", "gone.ts")]
+    assert "no longer exists" in verdict.findings[0].message
+
+
+def test_staleness_does_not_depend_on_the_set_naming_the_file(tmp_path: Path) -> None:
+    root = tree(tmp_path, {"a.ts": "// one\n// two\n", "b.ts": "x\n"}, register_of("a.ts"))
+    assert grade(root, files=("b.ts",)).outcome is Outcome.CLEAN
+    root = tree(tmp_path / "s", {"a.ts": "const a = 1;\n", "b.ts": "x\n"}, register_of("a.ts"))
+    verdict = grade(root, files=("b.ts",))
+    assert [(f.rule, f.path) for f in verdict.findings] == [("MLC-002", "a.ts")]
+
+
+@pytest.mark.parametrize(
+    "body",
+    [
+        "files: [a.ts]\n",
+        "schema_version: 2\nfiles: [a.ts]\n",
+        "schema_version: 1\n",
+        "schema_version: 1\nfiles: [a.ts, a.ts]\n",
+        "schema_version: 1\nfiles: ['../a.ts']\n",
+        "schema_version: 1\nfiles: [a.ts]\nextra: 1\n",
+        "schema_version: 1\nfiles: {a.ts: 3}\n",
+        "not: [valid\n",
+    ],
+)
+def test_a_register_that_exists_but_is_unusable_is_could_not_run(tmp_path: Path, body: str) -> None:
+    root = tree(tmp_path, {"a.ts": "// one\n// two\n"}, body)
+    verdict = grade(root)
+    assert verdict.outcome is Outcome.COULD_NOT_RUN, verdict.render()
+    assert "ratchet register" in verdict.message
+
+
+def test_the_register_row_scope_selects_the_register_itself() -> None:
+    from adl_compliance.core import scope
+
+    assert scope.in_scope(ROW.engine.scope, REGISTER_PATH)
+    assert not scope.in_scope(ROW.engine.scope, "x/fixtures/a.ts")
+
+
+def test_the_row_is_addressable_by_domain_and_name() -> None:
+    assert load().resolve("repository.no-multiline-comments").id == "REP-007"
+
+
+def test_the_committed_valid_register_exempts_exactly_what_it_names(tmp_path: Path) -> None:
+    body = (Path(__file__).parent / "fixtures" / "valid-register.yaml").read_text(encoding="utf-8")
+    both = "// one\n// two\n"
+    root = tree(
+        tmp_path,
+        {"packages/app/src/legacy.ts": both, "scripts/old.sh": "# one\n# two\n", "packages/app/src/new.ts": both},
+        body,
+    )
+    verdict = grade(root)
+    assert [(f.rule, f.path) for f in verdict.findings] == [("MLC-001", "packages/app/src/new.ts")]
+
+
+# ------------------------------------------------- parse failures and missing tools
+UNPARSEABLE = {
+    "broken.sh": "if then fi (\n",
+    "broken.py": "def f(:\n",
+}
+GOOD_PAIR = ("pair.ts", "// one\n// two\n")
+
+
+@pytest.mark.parametrize(("name", "body"), sorted(UNPARSEABLE.items()))
+def test_an_unparseable_file_is_a_per_file_finding_and_the_rest_is_still_graded(
+    tmp_path: Path, name: str, body: str
+) -> None:
+    root = tree(tmp_path, {name: body, GOOD_PAIR[0]: GOOD_PAIR[1]})
+    verdict = grade(root)
+    assert verdict.outcome is Outcome.FINDINGS, verdict.render()
+    by_rule = {(f.rule, f.path) for f in verdict.findings}
+    assert by_rule == {("MLC-003", name), ("MLC-001", GOOD_PAIR[0])}
+    parse = next(f for f in verdict.findings if f.rule == "MLC-003")
+    assert "cannot be parsed" in parse.message
+    assert ("shfmt" if name.endswith(".sh") else "python") in parse.message
+
+
+@pytest.mark.parametrize(("name", "body"), sorted(UNPARSEABLE.items()))
+def test_a_registered_unparseable_file_is_not_reported_or_stale(tmp_path: Path, name: str, body: str) -> None:
+    root = tree(tmp_path, {name: body}, register_of(name))
+    verdict = grade(root)
+    assert verdict.outcome is Outcome.CLEAN, verdict.render()
+
+
+@pytest.mark.parametrize(
+    ("name", "body"),
+    [
+        ("dash.sh", "#!/bin/sh\nx=1\n# one\n# two\n"),
+        ("posix-bad.sh", "#!/bin/sh\nx=(a b)\n"),
+        ("bin/ksh-tool", "#!/bin/ksh\n# one\n# two\n"),
+        ("zsh-tool.zsh", "# one\n# two\nprint -r x\n"),
+    ],
+)
+def test_a_shebang_selects_the_shfmt_dialect(tmp_path: Path, name: str, body: str) -> None:
+    root = tree(tmp_path, {name: body})
+    verdict = grade(root)
+    expected = "MLC-003" if name == "posix-bad.sh" else "MLC-001"
+    assert {f.rule for f in verdict.findings} == {expected}, verdict.render()
+
+
+def test_a_missing_shfmt_is_could_not_run_for_the_whole_gate(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    root = tree(tmp_path, {"a.sh": "# one\n# two\n", "b.ts": "// x\n"})
+    monkeypatch.setattr(runner.shutil, "which", lambda tool: None if tool == "shfmt" else "/usr/bin/" + tool)
+    verdict = grade(root)
+    assert verdict.outcome is Outcome.COULD_NOT_RUN, verdict.render()
+    assert "shfmt" in verdict.message
+
+
+def test_a_missing_ast_grep_is_could_not_run_for_the_whole_gate(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    root = tree(tmp_path, {"b.ts": "// x\n// y\n"})
+    monkeypatch.setattr(runner.shutil, "which", lambda tool: None if tool == "ast-grep" else "/usr/bin/" + tool)
+    verdict = grade(root)
+    assert verdict.outcome is Outcome.COULD_NOT_RUN, verdict.render()
+    assert "ast-grep" in verdict.message
+
+
+@pytest.mark.parametrize("name", ["a.sh", "b.ts"])
+def test_a_tool_that_cannot_be_launched_is_could_not_run_not_a_finding(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch, name: str
+) -> None:
+    root = tree(tmp_path, {name: "# one\n"})
+    empty = tmp_path / "empty-bin"
+    empty.mkdir()
+    monkeypatch.setattr(runner.shutil, "which", lambda tool: "/usr/bin/" + tool)
+    monkeypatch.setenv("PATH", str(empty))
+    verdict = grade(root)
+    assert verdict.outcome is Outcome.COULD_NOT_RUN, verdict.render()

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/repository/vcs_in_scripts/__init__.py

@@ -0,0 +1,7 @@
+"""The `repository.no-vcs-in-scripts` gate (REP-006, GIT-001). Scanner: `..banned_commands.base`."""
+
+from __future__ import annotations
+
+from .check import VcsInScripts
+
+__all__ = ["VcsInScripts"]

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/repository/vcs_in_scripts/check.py

@@ -0,0 +1,16 @@
+"""REP-006 (GIT-001) on the shared `banned_commands/base.py` scanner."""
+
+from __future__ import annotations
+
+from typing import ClassVar
+
+from ..banned_commands.base import BannedCommand
+
+
+class VcsInScripts(BannedCommand):
+    id: ClassVar[str] = "REP-006"
+    rule: ClassVar[str] = "GIT-001"
+    WORD: ClassVar[str] = "gi" + "t"
+    MESSAGE: ClassVar[str] = "version-control invocation is forbidden in shell scripts and justfiles"
+    FIX: ClassVar[str] = ("read the set the runner hands you, or drop the call if it only built "
+           "a repository the assertion never needed")

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/repository/vcs_in_scripts/test_check.py

@@ -0,0 +1,32 @@
+"""REP-006 (GIT-001) reports its own rule and no other."""
+
+from __future__ import annotations
+
+import pathlib
+
+from adl_compliance import runner
+from adl_compliance.core.verdict import Outcome
+from adl_compliance.policy.registry import load
+
+CORPUS = (
+    pathlib.Path(__file__).parent.parent / "banned_commands" / "fixtures" / "no-banned-commands"
+)
+ROW = load().by_id("REP-006")
+
+
+def _whole() -> tuple[str, ...]:
+    return tuple(
+        sorted(p.relative_to(CORPUS).as_posix() for p in CORPUS.rglob("*") if p.is_file())
+    )
+
+
+def test_reports_only_its_own_rule() -> None:
+    verdict = runner.run(ROW, CORPUS, _whole())
+    assert verdict.outcome is Outcome.FINDINGS
+    assert {f.rule for f in verdict.findings} == {"GIT-001"}
+    assert len(verdict.findings) == 2
+    assert "loose-git.sh" in {pathlib.PurePosixPath(f.path).name for f in verdict.findings}
+
+
+def test_is_addressable_by_its_registry_name() -> None:
+    assert load().resolve("repository.no-vcs-in-scripts").id == "REP-006"

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/cli.py

@@ -33,6 +33,7 @@ import yaml
 from pydantic import ValidationError
 
 from . import runner
+from .checks import lookup
 from .core.constants import Constants
 from .core.errors import CouldNotRun
 from .core.receipt import from_verdict
@@ -298,6 +299,13 @@ def write_logs(directory: Path, verdicts: Sequence[Verdict]) -> tuple[Path, Path
     return all_path, failures_path
 
 
+def _empty_scope_is_clean(gate: str) -> bool:
+    try:
+        return lookup(gate).empty_scope_is_clean
+    except KeyError:
+        return False
+
+
 def write_receipts(directory: Path, verdicts: Sequence[Verdict], *, exhaustive: bool) -> Path:
     """C1: one `core.receipt.Receipt` per row, JSONL, alongside the two logs.
 
@@ -310,7 +318,10 @@ def write_receipts(directory: Path, verdicts: Sequence[Verdict], *, exhaustive:
     directory.mkdir(parents=True, exist_ok=True)
     receipts_path = directory / Constants.RECEIPTS_LOG
     lines = [
-        from_verdict(verdict, exhaustive=exhaustive).model_dump_json() for verdict in verdicts
+        from_verdict(
+            verdict, exhaustive=exhaustive, nothing_to_grade_is_clean=_empty_scope_is_clean(verdict.row.id)
+        ).model_dump_json()
+        for verdict in verdicts
     ]
     receipts_path.write_text("\n".join(lines) + ("\n" if lines else ""), encoding="utf-8")
     return receipts_path

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/core/ast_grep.py

@@ -126,9 +126,8 @@ class AstGrepCheck(Check):
             )
 
     def _is_owned_suppression(self, ctx: Context, match: AstGrepMatch) -> bool:
-        """Owner ruling on TS-013's two `enact-m5` findings: "if it's
-        legitimate, own it" / "no exception". Synthesised into one mechanism
-        for every `engine.rule` row, not one gate's patch: a match is skipped
+        """Owner ruling: "if it's legitimate, own it" / "no exception". One
+        mechanism for every `engine.rule` row, not one gate's patch: a match is skipped
         only when the row DECLARES an equivalent biome rule (`engine.
         suppression`) and the match is immediately preceded — allowing a
         multi-line comment continuation — by a `// biome-ignore <rule>:

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/core/check.py

@@ -125,6 +125,9 @@ class Check(Constants, ABC):
     `adl.exception-catalog/v1` is a hard could-not-run.
     """
 
+    empty_scope_is_clean: ClassVar[bool] = False
+    """A scope selecting nothing is clean, not could-not-run (for gates whose subject exists only in some repositories)."""
+
     whole_scope: ClassVar[bool] = False
     """A triggered check grades its complete declared scope.
 

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/core/constants.py

@@ -47,7 +47,7 @@ class Constants:
     # Two directories, similar names, different owners, and conflating them is a
     # real bug rather than a tidiness question: the K-42 sweep converted
     # `.workflows/AGENTS.md` into `<workflows>/AGENTS.md`, which repoints a path
-    # this tool fixes everywhere at a tree the repository declares. enact-m5 has
+    # this tool fixes everywhere at a tree the repository declares. a managed repository has
     # BOTH and an AGENTS.md in each, so that conversion silently swapped which
     # file two gates were reading.
     #

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/core/declarations.py

@@ -0,0 +1,24 @@
+"""Declarations a repository sends the engine, validated once for every gate that reads them."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+
+from ..policy.root_shape import ROOT_FILES_DECLARATION, declared_root_names
+from .errors import CouldNotRun
+
+
+def declared_root_files(declarations: Mapping[str, str]) -> frozenset[str]:
+    """The repository-relative files declared under `root-files`; an absolute, dotted or glob entry is could-not-run."""
+    names = declared_root_names(declarations, ROOT_FILES_DECLARATION)
+    for name in sorted(names):
+        if name.startswith("/") or any(part in ("", ".", "..") for part in name.split("/")) or any(
+            char in name for char in "*?["
+        ):
+            raise CouldNotRun(
+                f"`{ROOT_FILES_DECLARATION}` declares {name!r}, which is not a repository-relative "
+                "file path (it is absolute, has a `.`, `..` or empty segment, or is a glob); fix "
+                "[controls.compliance.root].files in adl-config.toml -- a malformed name could "
+                "only widen the allowlist, so the gate does not grade against it"
+            )
+    return names

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/core/receipt.py

@@ -37,7 +37,7 @@ class Receipt(StrictModel):
     message: str
 
 
-def from_verdict(verdict: Verdict, *, exhaustive: bool) -> Receipt:
+def from_verdict(verdict: Verdict, *, exhaustive: bool, nothing_to_grade_is_clean: bool = False) -> Receipt:
     """Build one gate's receipt.
 
     `exhaustive` is the same fact `runner.applicable_files` used to decide
@@ -48,7 +48,7 @@ def from_verdict(verdict: Verdict, *, exhaustive: bool) -> Receipt:
     `runner.run` cannot produce one (it raises `CouldNotRun` first). This
     function checks that second claim rather than assuming it.
     """
-    if exhaustive and verdict.units == 0 and verdict.outcome is Outcome.CLEAN:
+    if exhaustive and verdict.units == 0 and verdict.outcome is Outcome.CLEAN and not nothing_to_grade_is_clean:
         raise ValueError(
             f"{verdict.row.id}: refusing to record a PASS receipt for a gate "
             "whose exhaustive scope resolved to zero units — a dead scope is "