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

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/repository/lockfile_integrity/test_root_lockfiles.py

@@ -0,0 +1,101 @@
+"""REP-002 grades the repository-root manifests by itself (PBI 598)."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from pathlib import Path
+
+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-002")
+
+
+def _write(root: Path, files: Mapping[str, str]) -> tuple[str, ...]:
+    for relative, body in files.items():
+        target = root / relative
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(body, encoding="utf-8")
+    return tuple(sorted(files))
+
+
+def _grade(root: Path, files: tuple[str, ...], declarations: Mapping[str, str] | None = None) -> Verdict:
+    return runner.run(
+        ROW, root, files, exhaustive=True, universe=files,
+        declarations=dict(declarations or {}), trees={}, declared_trees={},
+    )
+
+
+def test_a_root_cargo_manifest_without_a_lockfile_fails(tmp_path: Path) -> None:
+    files = _write(tmp_path, {"Cargo.toml": '[package]\nname = "x"\nversion = "0.1.0"\n'})
+    verdict = _grade(tmp_path, files)
+    assert verdict.outcome is Outcome.FINDINGS, verdict.render()
+    assert [(f.rule, f.path) for f in verdict.findings] == [("LCK-001", "Cargo.lock")]
+
+
+def test_a_root_package_json_with_a_bun_lock_passes(tmp_path: Path) -> None:
+    files = _write(tmp_path, {"package.json": "{}\n", "bun.lock": "lock\n"})
+    verdict = _grade(tmp_path, files)
+    assert verdict.outcome is Outcome.CLEAN, verdict.render()
+
+
+def test_a_root_package_json_without_a_bun_lock_fails(tmp_path: Path) -> None:
+    files = _write(tmp_path, {"package.json": "{}\n"})
+    verdict = _grade(tmp_path, files)
+    assert [(f.rule, f.path) for f in verdict.findings] == [("LCK-001", "bun.lock")], verdict.render()
+
+
+def test_an_empty_root_bun_lock_fails(tmp_path: Path) -> None:
+    files = _write(tmp_path, {"package.json": "{}\n", "bun.lock": ""})
+    verdict = _grade(tmp_path, files)
+    assert [f.path for f in verdict.findings] == ["bun.lock"], verdict.render()
+
+
+def test_a_declared_lockfile_elsewhere_is_graded(tmp_path: Path) -> None:
+    declarations = {"bun-manifests": "apps/web/package.json", "bun-lockfiles": "apps/web/bun.lock"}
+    files = _write(tmp_path, {"apps/web/package.json": "{}\n"})
+    verdict = _grade(tmp_path, files, declarations)
+    assert [(f.rule, f.path) for f in verdict.findings] == [("LCK-001", "apps/web/bun.lock")], verdict.render()
+
+
+def test_a_declared_lockfile_that_is_present_passes(tmp_path: Path) -> None:
+    declarations = {"bun-manifests": "apps/web/package.json", "bun-lockfiles": "apps/web/bun.lock"}
+    files = _write(tmp_path, {"apps/web/package.json": "{}\n", "apps/web/bun.lock": "lock\n"})
+    verdict = _grade(tmp_path, files, declarations)
+    assert verdict.outcome is Outcome.CLEAN, verdict.render()
+
+
+def test_a_nested_manifest_is_not_graded_unless_declared(tmp_path: Path) -> None:
+    """REWORKED, Tarun 2026-10-08: nothing to grade is a pass, not an error."""
+    files = _write(tmp_path, {"apps/web/package.json": "{}\n", "README.md": "x\n"})
+    verdict = _grade(tmp_path, files)
+    assert verdict.outcome is Outcome.CLEAN, verdict.render()
+
+
+def test_the_root_pair_is_graded_beside_a_declaration(tmp_path: Path) -> None:
+    """Declaring another lockfile adds to the root pair; it does not replace it."""
+    declarations = {"bun-manifests": "apps/web/package.json", "bun-lockfiles": "apps/web/bun.lock"}
+    files = _write(tmp_path, {"package.json": "{}\n", "apps/web/package.json": "{}\n", "apps/web/bun.lock": "l\n"})
+    verdict = _grade(tmp_path, files, declarations)
+    assert [f.path for f in verdict.findings] == ["bun.lock"], verdict.render()
+
+
+def test_no_root_manifest_and_no_declaration_is_clean(tmp_path: Path) -> None:
+    """REWORKED, Tarun 2026-10-08: a repository with no manifest has nothing to lock."""
+    files = _write(tmp_path, {"README.md": "x\n"})
+    verdict = _grade(tmp_path, files)
+    assert verdict.outcome is Outcome.CLEAN, verdict.render()
+
+
+def test_a_lockfile_without_a_manifest_and_no_declaration_is_clean(tmp_path: Path) -> None:
+    files = _write(tmp_path, {"bun.lock": "lock\n"})
+    verdict = _grade(tmp_path, files)
+    assert verdict.outcome is Outcome.CLEAN, verdict.render()
+
+
+def test_a_declared_manifest_matching_nothing_is_still_could_not_run(tmp_path: Path) -> None:
+    declarations = {"bun-manifests": "apps/web/package.json", "bun-lockfiles": "apps/web/bun.lock"}
+    files = _write(tmp_path, {"README.md": "x\n"})
+    verdict = _grade(tmp_path, files, declarations)
+    assert verdict.outcome is Outcome.COULD_NOT_RUN, verdict.render()

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/repository/lockfile_integrity/test_stale_lock.py

@@ -36,7 +36,6 @@ from types import SimpleNamespace
 from typing import NamedTuple
 
 import pytest
-from fixture_trees import fixture_trees
 from helpers import corpus_files
 
 from adl_compliance import runner
@@ -293,7 +292,7 @@ SHAPES = [
 
 
 def lay(root: Path, files: Mapping[str, str], lock: str | bytes, *, where: str = "backend") -> None:
-    """Write a cargo workspace under `root/where` plus the TypeScript lock the gate also wants.
+    """Write a cargo workspace under `root/where`.
 
     A manifest with a `[package]` gets a `src/lib.rs`, so the very same files are also valid
     input to the real `cargo metadata`. `where` is the cargo workspace directory.
@@ -311,15 +310,16 @@ def lay(root: Path, files: Mapping[str, str], lock: str | bytes, *, where: str =
         lockfile.write_bytes(lock)
     else:
         lockfile.write_text(lock, encoding="utf-8")
-    (root / "frontend").mkdir(exist_ok=True)
-    (root / "frontend" / "bun.lock").write_text("# fixture lock\n", encoding="utf-8")
 
 
-def grade(
-    root: Path, *, declarations: Mapping[str, str] | None = None, trees: Mapping[str, str] | None = None
-) -> Verdict:
+#: Most tests lay their workspace under `backend/`; `grade` declares it unless a test passes its own.
+BACKEND = {"cargo-manifests": "backend/Cargo.toml", "cargo-lockfiles": "backend/Cargo.lock"}
+
+
+def grade(root: Path, *, declarations: Mapping[str, str] | None = None) -> Verdict:
     """The real dispatch path, whole tree, exhaustive."""
-    trees = fixture_trees() if trees is None else trees
+    declarations = BACKEND if declarations is None else declarations
+    trees: dict[str, str] = {}
     files = corpus_files(root)
     return runner.run(
         ROW,
@@ -327,7 +327,7 @@ def grade(
         files,
         exhaustive=True,
         universe=files,
-        declarations=declarations or {},
+        declarations=declarations,
         trees=trees,
         declared_trees=trees,
     )
@@ -1071,12 +1071,24 @@ def test_a_cargo_rejection_is_the_only_finding_for_that_lock(
     assert [argv[:2] for argv in calls] == [["cargo", "--version"], ["cargo", "metadata"]]
 
 
-def test_the_undeclared_mode_grades_the_tree_default_lockfile(
+def test_the_root_pair_is_graded_without_any_declaration(
     tmp_path: Path, cargo_accepts: list[list[str]]
 ) -> None:
-    verdict = stale_lock(tmp_path, SINGLE.files, "version = 99\n")
-    assert {f.path for f in verdict.findings} == {"backend/Cargo.lock"}
-    assert {f.fix for f in verdict.findings} == {FIX}
+    lay(tmp_path, SINGLE.files, "version = 99\n", where=".")
+    verdict = grade(tmp_path, declarations={})
+    assert {f.path for f in verdict.findings} == {"Cargo.lock"}
+    assert {f.fix for f in verdict.findings} == {
+        "run: (cd . && cargo update) to resync Cargo.lock with Cargo.toml, then commit the result"
+    }
+
+
+def test_a_workspace_below_the_root_is_not_graded_unless_declared(
+    tmp_path: Path, cargo_accepts: list[list[str]]
+) -> None:
+    lay(tmp_path, SINGLE.files, "version = 99\n")
+    verdict = grade(tmp_path, declarations={})
+    assert verdict.outcome is Outcome.CLEAN, verdict.render()
+    assert cargo_accepts == []
 
 
 DECLARED = {"cargo-manifests": "nested/*/Cargo.toml", "cargo-lockfiles": "nested/ws/Cargo.lock"}

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

@@ -0,0 +1,7 @@
+"""The `repository.no-multiline-comments` gate (REP-007)."""
+
+from __future__ import annotations
+
+from .check import NoMultilineComments
+
+__all__ = ["NoMultilineComments"]

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

@@ -0,0 +1,124 @@
+"""REP-007 (MLC-001, MLC-002): no multi-line comment in code (Bug 602)."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import ClassVar, Literal
+
+import yaml
+from pydantic import field_validator
+
+from ....core.check import Check
+from ....core.context import Context, FileSet
+from ....core.errors import CouldNotRun, SchemaInvalid
+from ....core.finding import Report
+from ....core.models import StrictModel
+from ...lfs.integrity.check import UniqueKeyLoader
+from . import scanner
+
+
+class Register(StrictModel):
+    """The repository's recorded debt: the files that already carry one."""
+
+    schema_version: Literal[1]
+    files: list[str]
+
+    @field_validator("files")
+    @classmethod
+    def _paths_are_normalised_and_unique(cls, value: list[str]) -> list[str]:
+        for path in value:
+            if "\\" in path or any(part in ("", ".", "..") for part in path.split("/")):
+                raise ValueError(f"{path!r} is not a normalised repository-relative file path")
+        if len(set(value)) != len(value):
+            raise ValueError("a path is listed more than once")
+        return value
+
+
+class NoMultilineComments(Check):
+    id: ClassVar[str] = "REP-007"
+    rule: ClassVar[str] = "MLC-001"
+    STALE: ClassVar[str] = "MLC-002"
+    UNPARSEABLE: ClassVar[str] = "MLC-003"
+
+    requires: ClassVar[tuple[str, ...]] = ("ast-grep", "shfmt")
+
+    FIX: ClassVar[str] = (
+        "move the explanation to docs/ and leave at most a one-line pointer"
+    )
+
+    inputs: ClassVar[dict[str, str]] = {
+        "register": "<compliance>/ratchets/REP-007-multiline-comments.yaml",
+    }
+    widening_inputs: ClassVar[frozenset[str]] = frozenset({"register"})
+
+    def structural(self, ctx: Context) -> Iterable[Report]:
+        for rel in sorted(self._register(ctx)):
+            why = self._why_stale(ctx, rel)
+            if why is not None:
+                yield self.report(
+                    rel,
+                    f"ratchet entry for {rel} is no longer required: {why}",
+                    f"remove it from the register: the ratchet only shrinks "
+                    f"(delete {rel} from files in {self._shown(ctx)})",
+                    rule=self.STALE,
+                )
+
+    def graded(self, ctx: Context, files: FileSet) -> Iterable[Report]:
+        granted = set(self._register(ctx))
+        for rel in files:
+            if rel in granted or not scanner.is_code_file(rel, lambda rel=rel: self.text(ctx, rel)):
+                continue
+            try:
+                hits = self._hits(ctx, rel)
+            except scanner.Unparseable as exc:
+                yield self.report(
+                    rel, str(exc), "fix the file so it parses, or register it in the REP-007 ratchet",
+                    rule=self.UNPARSEABLE,
+                )
+                continue
+            for line, what in hits:
+                yield self.report(
+                    rel,
+                    f"multi-line comment ({what})",
+                    self.FIX,
+                    line=line,
+                )
+
+    def _hits(self, ctx: Context, rel: str) -> list[tuple[int, str]]:
+        body = self.text(ctx, rel)
+        return [] if body is None else scanner.find(rel, body)
+
+    def _why_stale(self, ctx: Context, rel: str) -> str | None:
+        if not ctx.path(rel).is_file():
+            return "it no longer exists"
+        if not scanner.is_code_file(rel, lambda: self.text(ctx, rel)):
+            return "it is not a code file this gate grades"
+        try:
+            hits = self._hits(ctx, rel)
+        except scanner.Unparseable:
+            return None
+        if not hits:
+            return "it no longer has a multi-line comment"
+        return None
+
+    # ------------------------------------------------------------ the register
+
+    def _register(self, ctx: Context) -> tuple[str, ...]:
+        """The files granted, or `()` when the repository records none."""
+        target = ctx.inputs.get("register")
+        if target is None or not target.exists():
+            return ()
+        shown = self._shown(ctx)
+        if not target.is_file():
+            raise CouldNotRun(f"REP-007 ratchet register {shown} exists but is not a file")
+        body = self.text(ctx, target)
+        try:
+            loaded = yaml.load(body, Loader=UniqueKeyLoader)  # noqa: S506 - a SafeLoader
+            return tuple(self._validate(loaded, Register, shown).files)
+        except yaml.YAMLError as exc:
+            raise CouldNotRun(f"REP-007 ratchet register {shown} is not valid YAML: {exc}") from exc
+        except SchemaInvalid as exc:
+            raise CouldNotRun(f"REP-007 ratchet register is unusable: {exc.detail}") from exc
+
+    def _shown(self, ctx: Context) -> str:
+        return ctx.relative(ctx.inputs["register"])

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/repository/no_multiline_comments/fixtures/valid-register.yaml

@@ -0,0 +1,4 @@
+schema_version: 1
+files:
+  - packages/app/src/legacy.ts
+  - scripts/old.sh

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

@@ -0,0 +1,217 @@
+"""Where multi-line comments are, per language: python by tokenize and ast, shell by shfmt, the rest by ast-grep."""
+
+from __future__ import annotations
+
+import ast
+import io
+import json
+import re
+import subprocess
+import tokenize
+from dataclasses import dataclass
+
+from ....core.errors import CouldNotRun
+from ....core.scripts import is_code_file, language
+
+__all__ = ["Unparseable", "find", "is_code_file"]
+
+
+class Unparseable(Exception):
+    """The file cannot be parsed by the tool that reads its language: a finding about that file, not a failed gate."""
+
+    def __init__(self, relative: str, tool: str, detail: str) -> None:
+        super().__init__(f"{relative} cannot be parsed: {tool} {detail}")
+
+
+class Syntax:
+    """The scanner's literals, on a class like every gate's."""
+
+    DIRECTIVE = re.compile(
+        r"(?:@ts-expect-error|@ts-ignore|@ts-nocheck"
+        r"|eslint-(?:disable|enable)(?:-next-line|-line)?(?:\s+[\w@/.-]+(?:\s*,\s*[\w@/.-]+)*)?"
+        r"|noqa(?::\s*[A-Z]+[0-9]+(?:[,\s]+[A-Z]+[0-9]+)*)?"
+        r"|type:\s*ignore(?:\[[\w, -]+\])?"
+        r"|biome-ignore(?:-all|-start|-end)?(?:\s+[\w/.-]+)*:?"
+        r"|shellcheck\s+(?:disable|enable|source|shell)=\S+"
+        r"|pyright:\s*(?:ignore|basic|strict|standard|off|report\w+)(?:\[[\w, -]+\])?(?:\s*=\s*\w+)?)"
+        r"\s*"
+    )
+
+    GRAMMARS = {"rust": "Rust", "slash": "Tsx", "typescript": "TypeScript", "justfile": "Bash"}
+    SHFMT_DIALECTS = {"shell": "bash", "posix": "posix", "mksh": "mksh", "zsh": "zsh"}
+    BRACES = "{}"
+    JSX_LANGUAGES = frozenset({"slash"})
+    RUST_RULE = "any:\n    - kind: line_comment\n    - kind: block_comment"
+    COMMENT_RULE = "kind: comment"
+    SG_TIMEOUT = 60
+
+
+def _is_directive(body: str) -> bool:
+    """A comment that is solely a tool directive; prose after it makes it prose."""
+    return Syntax.DIRECTIVE.fullmatch(body.strip()) is not None
+
+
+def find(relative: str, text: str) -> list[tuple[int, str]]:
+    """Every multi-line comment in `text`, ordered by line."""
+    text = text.replace("\r\n", "\n").replace("\r", "\n")
+    kind = language(relative, text)
+    if kind == "python":
+        hits = _python(relative, text)
+    elif kind is not None:
+        hits = _tree(relative, text, kind)
+    else:
+        hits = []
+    return sorted(hits)
+
+
+def _runs(lines: dict[int, bool], what: str) -> list[tuple[int, str]]:
+    """Runs of consecutive lines with two or more prose lines (a directive-only line is transparent), at the first."""
+    hits: list[tuple[int, str]] = []
+    run: list[int] = []
+    for line in [*sorted(lines), -1]:
+        if run and line == run[-1] + 1:
+            run.append(line)
+            continue
+        if sum(1 for n in run if not lines[n]) > 1:
+            hits.append((run[0], f"{len(run)} consecutive {what}"))
+        run = [line]
+    return hits
+
+
+# ------------------------------------------------------------------- python
+def _python(relative: str, text: str) -> list[tuple[int, str]]:
+    try:
+        tree = ast.parse(text)
+        tokens = list(tokenize.generate_tokens(io.StringIO(text).readline))
+    except (SyntaxError, ValueError, tokenize.TokenError) as exc:
+        raise Unparseable(relative, "python", str(exc)) from exc
+    comment_lines: dict[int, bool] = {}
+    for token in tokens:
+        if token.type != tokenize.COMMENT:
+            continue
+        row, col = token.start
+        if token.line[:col].strip():
+            continue  # trailing
+        if row == 1 and token.string.startswith("#!"):
+            continue
+        comment_lines[row] = _is_directive(token.string.lstrip("#"))
+    hits = _runs(comment_lines, "line comments")
+    single: dict[int, bool] = {}
+    for node in ast.walk(tree):
+        if not (isinstance(node, ast.Expr) and node.end_lineno is not None and _is_string(node.value)):
+            continue
+        if node.end_lineno > node.lineno:
+            hits.append((node.lineno, f"string statement (docstring) spanning {node.end_lineno - node.lineno + 1} lines"))
+        else:
+            single[node.lineno] = False
+    return hits + _runs(single, "string statements")
+
+
+def _is_string(node: ast.expr) -> bool:
+    return isinstance(node, ast.JoinedStr) or (
+        isinstance(node, ast.Constant) and isinstance(node.value, (str, bytes))
+    )
+
+
+# ------------------------------------------------------- every other language
+@dataclass(frozen=True)
+class _Comment:
+    """One comment node: its 1-based first and last line, the text, and its start column."""
+
+    line: int
+    end: int
+    text: str
+    column: int
+
+
+def _tree(relative: str, text: str, language: str) -> list[tuple[int, str]]:
+    lines = text.split("\n")
+    hits: list[tuple[int, str]] = []
+    per_line: dict[int, list[_Comment]] = {}
+    found = _shell_comments(relative, text, language) if language in Syntax.SHFMT_DIALECTS else _comments(
+        relative, text, Syntax.GRAMMARS[language]
+    )
+    for comment in found:
+        if comment.line == 1 and comment.text.startswith("#!"):
+            continue
+        if comment.end > comment.line:
+            hits.append((comment.line, f"block comment spanning {comment.end - comment.line + 1} lines"))
+        else:
+            per_line.setdefault(comment.line, []).append(comment)
+    standalone: dict[int, bool] = {}
+    for number, comments in per_line.items():
+        rest = lines[number - 1]
+        for comment in sorted(comments, key=lambda c: -c.column):
+            rest = rest[: comment.column] + rest[comment.column + len(comment.text) :]
+        if "".join(rest.split()) != "" and not _jsx_comment_line(lines[number - 1], comments, language):
+            continue  # trailing
+        standalone[number] = all(_is_directive(_body(c.text)) for c in comments)
+    return hits + _runs(standalone, "line comments")
+
+
+def _jsx_comment_line(line: str, comments: list[_Comment], language: str) -> bool:
+    """A JSX comment line: `{`, one block comment, `}` and nothing else, in a language that has JSX."""
+    if language not in Syntax.JSX_LANGUAGES or len(comments) != 1 or not comments[0].text.startswith("/*"):
+        return False
+    comment = comments[0]
+    before, after = line[: comment.column], line[comment.column + len(comment.text) :]
+    return before.strip() == "{" and after.strip() == "}"
+
+
+def _body(text: str) -> str:
+    """A comment without its delimiters."""
+    if text.startswith("/*"):
+        return text[2:-2].lstrip("*!")
+    return text.lstrip("/#!")
+
+
+def _comments(relative: str, text: str, grammar: str) -> list[_Comment]:
+    rule = Syntax.RUST_RULE if grammar == "Rust" else Syntax.COMMENT_RULE
+    inline = f"id: comments\nseverity: hint\nlanguage: {grammar}\nrule:\n  {rule}\n"
+    try:
+        done = subprocess.run(
+            ["ast-grep", "scan", "--stdin", "--inline-rules", inline, "--json=stream"],
+            input=text, capture_output=True, text=True, check=False, timeout=Syntax.SG_TIMEOUT,
+        )
+    except (OSError, subprocess.TimeoutExpired) as exc:
+        raise CouldNotRun(f"{relative} cannot be parsed: ast-grep: {exc}") from exc
+    if done.returncode != 0:
+        raise Unparseable(relative, "ast-grep", done.stderr.strip() or f"exited {done.returncode}")
+    found: list[_Comment] = []
+    for record in done.stdout.splitlines():
+        if not record.strip():
+            continue
+        node = json.loads(record)
+        body = node["text"].rstrip("\n")
+        start = node["range"]["start"]
+        found.append(_Comment(start["line"] + 1, start["line"] + 1 + body.count("\n"), body, start["column"]))
+    return found
+
+
+def _shell_comments(relative: str, text: str, language: str) -> list[_Comment]:
+    command = ["shfmt", "--tojson", "--language-dialect", Syntax.SHFMT_DIALECTS[language]]
+    try:
+        done = subprocess.run(
+            command, input=text, capture_output=True, text=True, check=False, timeout=Syntax.SG_TIMEOUT
+        )
+    except (OSError, subprocess.TimeoutExpired) as exc:
+        raise CouldNotRun(f"{relative} cannot be parsed: shfmt: {exc}") from exc
+    if done.returncode != 0:
+        raise Unparseable(relative, "shfmt", done.stderr.strip() or f"exited {done.returncode}")
+    found: dict[tuple[int, int], _Comment] = {}
+    lines = text.split("\n")
+    for node in _comment_nodes(json.loads(done.stdout)):
+        line, column = node["Pos"]["Line"], node["Pos"]["Col"] - 1
+        body = "#" + node["Text"]
+        found[(line, column)] = _Comment(line, line, body, len(lines[line - 1].encode()[:column].decode(errors="ignore")))
+    return list(found.values())
+
+
+def _comment_nodes(tree: object) -> list[dict]:
+    """Every comment node in a shfmt syntax tree: the objects carrying a `Hash` and a `Text`."""
+    if isinstance(tree, dict):
+        own = [tree] if "Hash" in tree and "Text" in tree else []
+        return own + [n for value in tree.values() for n in _comment_nodes(value)]
+    if isinstance(tree, list):
+        return [n for value in tree for n in _comment_nodes(value)]
+    return []