@amsterdamdatalabs/adl-agent-control-linux-x64 0.1.12 → 0.1.26

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/layout/root_markdown_allowlist/test_check.py

@@ -242,6 +242,27 @@ def test_a_tree_that_does_not_exist_is_not_asked_for_a_guide() -> None:
     assert ".specs/AGENTS.md" not in reported
 
 
+def test_a_workflows_tree_without_a_guide_is_not_a_finding(tmp_path: pathlib.Path) -> None:
+    """`.workflows/` is machine-managed: `adl-repo-controls install` writes it
+    wholesale, so nobody hand-authors a guide there and the tree does not need
+    one. Owner decision 2026-10-01 (reversing the earlier requirement).
+
+    `plans/` and `docs/` are hand-authored trees and still need their guide, so
+    this also fails against a check that stopped asking any tree for one."""
+    (tmp_path / ".workflows").mkdir()
+    (tmp_path / ".workflows" / "promote.ts").write_text("// managed\n")
+    assert structural(tmp_path).findings == ()
+
+    (tmp_path / "plans").mkdir()
+    (tmp_path / "docs").mkdir()
+    verdict = structural(tmp_path)
+    assert sorted(f.path for f in verdict.findings) == [
+        "docs/AGENTS.md",
+        "plans/AGENTS.md",
+    ], verdict.render()
+    assert all(f.message == "tree has no AGENTS.md guide" for f in verdict.findings)
+
+
 def test_the_missing_guide_corpus_reports_only_the_structural_finding() -> None:
     """The whole corpus, both hooks combined: none of its files violate the
     graded rules (README.md at root, AGENTS.md by basename), so the only
@@ -327,3 +348,143 @@ def test_a_redeclared_estate_still_allows_the_resolved_tree_exceptions(
         f"real files under redeclared roots were wrongly reported outside "
         f"the allowlist: {verdict.render()}"
     )
+
+
+# ---------------------------------------------- per-repository root declarations
+def graded_declaring(root: pathlib.Path, declarations: dict[str, str], given: tuple[str, ...]):
+    """`graded`, plus what the repository declared about its own root
+    (`[controls.compliance.root]` arrives as the `root-files` / `root-dirs`
+    declarations). The graded rule only reads files that exist on disk, so the
+    caller creates them."""
+    ctx = Context(
+        root=root, row=ROW, declarations=declarations,
+        inputs={
+            "workflows_root": root / ".workflows",
+            "plans_root": root / "plans",
+            "specs_root": root / ".specs",
+            "docs_root": root / "docs",
+            "rust_root": root / "backend",
+            "frontend_root": root / "frontend",
+        },
+    )
+    findings = tuple(RootMarkdownAllowlist().graded(ctx, FileSet(paths=given)))
+    return decide(ROW, findings, 0, ())
+
+
+def _touch(root: pathlib.Path, *names: str) -> None:
+    for name in names:
+        target = root / name
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text("# x\n")
+
+
+def test_a_non_standard_root_register_is_reported_without_a_declaration(
+    tmp_path: pathlib.Path,
+) -> None:
+    """STATUS.md and DRIFT.md are not on the central list any more."""
+    _touch(tmp_path, "STATUS.md", "DRIFT.md")
+    verdict = graded_declaring(tmp_path, {}, ("STATUS.md", "DRIFT.md"))
+    assert sorted(f.path for f in verdict.findings) == ["DRIFT.md", "STATUS.md"], verdict.render()
+    assert all(
+        f.message == "tracked Markdown is outside the root allowlist" for f in verdict.findings
+    )
+
+
+def test_a_declared_root_markdown_name_is_allowed(tmp_path: pathlib.Path) -> None:
+    _touch(tmp_path, "STATUS.md", "DRIFT.md")
+    verdict = graded_declaring(
+        tmp_path, {"root-files": "STATUS.md, DRIFT.md"}, ("STATUS.md", "DRIFT.md"),
+    )
+    assert verdict.outcome is Outcome.CLEAN, verdict.render()
+
+
+def test_a_declaration_admits_only_the_names_it_lists(tmp_path: pathlib.Path) -> None:
+    """Without this, the case above also passes against a gate that stops
+    grading root Markdown as soon as any declaration is present."""
+    _touch(tmp_path, "STATUS.md", "STRAY.md")
+    verdict = graded_declaring(tmp_path, {"root-files": "STATUS.md"}, ("STATUS.md", "STRAY.md"))
+    assert [f.path for f in verdict.findings] == ["STRAY.md"], verdict.render()
+
+
+def test_a_declared_root_name_does_not_admit_the_same_name_nested(
+    tmp_path: pathlib.Path,
+) -> None:
+    """The declaration is about the repository ROOT: `STATUS.md` declared does
+    not make `notes/STATUS.md` (a path with a `/`) allowed."""
+    _touch(tmp_path, "notes/STATUS.md")
+    verdict = graded_declaring(tmp_path, {"root-files": "STATUS.md"}, ("notes/STATUS.md",))
+    assert [f.path for f in verdict.findings] == ["notes/STATUS.md"], verdict.render()
+
+
+def test_a_root_dirs_declaration_does_not_admit_a_root_markdown_file(
+    tmp_path: pathlib.Path,
+) -> None:
+    _touch(tmp_path, "STATUS.md")
+    verdict = graded_declaring(tmp_path, {"root-dirs": "STATUS.md"}, ("STATUS.md",))
+    assert [f.path for f in verdict.findings] == ["STATUS.md"], verdict.render()
+
+
+def test_a_stray_root_markdown_fix_names_the_declaration_route(tmp_path: pathlib.Path) -> None:
+    """The fix for a root-level stray `.md` must say how a repository carries
+    such a file legitimately -- declare it under `[controls.compliance.root]`
+    in its own `adl-config.toml` -- and must not send the user to edit this
+    gate's source (`check.py`) to add an exception."""
+    _touch(tmp_path, "STATUS.md")
+    verdict = graded_declaring(tmp_path, {}, ("STATUS.md",))
+    assert len(verdict.findings) == 1, verdict.render()
+    fix = verdict.findings[0].fix
+    assert "[controls.compliance.root]" in fix, fix
+    assert "adl-config.toml" in fix, fix
+    assert "check.py" not in fix, fix
+    # The other half of the advice -- moving the file under an allowed tree --
+    # is kept, so the declaration route is an addition and not a replacement.
+    assert "docs/" in fix, fix
+
+
+def test_the_central_names_are_allowed_without_reading_the_context() -> None:
+    """`tests/core/test_root_shape.py` asks about the central names with no
+    Context at all, so the declaration lookup must come after that answer."""
+    assert RootMarkdownAllowlist()._allowed_markdown(None, "AGENTS.md")  # type: ignore[arg-type]
+    assert RootMarkdownAllowlist()._allowed_markdown(None, "GAPS-AND-FINDINGS.md")  # type: ignore[arg-type]
+
+
+# ------------------------------------------------- a tree declared absent
+def test_rust_and_frontend_declared_absent_contribute_nothing_to_the_allowlist(
+    tmp_path: pathlib.Path,
+) -> None:
+    """`rust = ""` and `frontend = ""` drop `rust_root` and `frontend_root` from
+    the resolved inputs. Here they only ever ADD allowlist entries (the governance
+    suffixes and code-asset roots beneath them), so absent they contribute
+    nothing and the file is reported -- strictly stricter, never a silent pass.
+    A stray root-level Markdown file reached `ctx.inputs["rust_root"]` unguarded
+    and raised `KeyError`, a traceback with exit 1, measured against enact-combined
+    with `--tree rust= --tree frontend=`."""
+    _touch(tmp_path, "NOTES.md", "backend/crates/enact-app/assets/builtin-skills/s.md")
+    ctx = Context(
+        root=tmp_path, row=ROW,
+        inputs={
+            "workflows_root": tmp_path / "workflows",
+            "plans_root": tmp_path / "plans",
+            "docs_root": tmp_path / "docs",
+        },
+    )
+    given = ("NOTES.md", "backend/crates/enact-app/assets/builtin-skills/s.md")
+    findings = tuple(RootMarkdownAllowlist().graded(ctx, FileSet(paths=given)))
+    assert sorted(f.path for f in findings) == sorted(given), findings
+    assert all(f.message == "tracked Markdown is outside the root allowlist" for f in findings)
+
+
+def test_a_declared_rust_tree_still_admits_its_governance_files(tmp_path: pathlib.Path) -> None:
+    """The other half: with the tree declared, the same entries still admit."""
+    _touch(tmp_path, "rust/CHANGELOG.md")
+    ctx = Context(
+        root=tmp_path, row=ROW,
+        inputs={
+            "workflows_root": tmp_path / "workflows",
+            "plans_root": tmp_path / "plans",
+            "docs_root": tmp_path / "docs",
+            "rust_root": tmp_path / "rust",
+            "frontend_root": tmp_path / "web",
+        },
+    )
+    assert tuple(RootMarkdownAllowlist().graded(ctx, FileSet(paths=("rust/CHANGELOG.md",)))) == ()

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/layout/scripts_size_depth/check.py

@@ -11,7 +11,13 @@ row's `engine.scope` (`<workflows>/scripts/**`, excluding its own
 Two measurements, both taken over the given set alone — never a walk:
 
   LAY-014  a directory directly under the CI scripts root holding more than
-           `MAX_DIRECT_FILES` files.
+           the direct-file limit: `MAX_DIRECT_FILES` (15) unless the
+           repository declares its own, as `--declare scripts-direct-files=N`
+           (`[controls.compliance.limits].scripts_direct_files` in its
+           adl-config.toml). `direct_file_limit` resolves it: absent is the
+           default, and a value that is not a base-10 positive integer is
+           could-not-run, never a quiet fall back to the default. The depth
+           limit is not configurable.
   LAY-014  a directory nested more than `MAX_SUBFOLDER_DEPTH` levels below
            that same root.
 
@@ -37,11 +43,13 @@ source being ported, not reinvented.
 
 from __future__ import annotations
 
+import re
 from collections.abc import Iterable
 from typing import ClassVar
 
 from ....core.check import Check
 from ....core.context import Context, FileSet
+from ....core.errors import CouldNotRun
 from ....core.finding import Finding, Report
 
 
@@ -49,9 +57,13 @@ class ScriptsSizeDepth(Check):
     id: ClassVar[str] = "LAY-014"
     rule: ClassVar[str] = "LAY-014"
 
+    # The engine default. A repository states its own with the
+    # `scripts-direct-files` declaration; see `direct_file_limit`.
     MAX_DIRECT_FILES: ClassVar[int] = 15
     MAX_SUBFOLDER_DEPTH: ClassVar[int] = 4
 
+    DIRECT_FILES_DECLARATION: ClassVar[str] = "scripts-direct-files"
+
     # `<workflows>` indirection, not the literal `.workflows/scripts` this held
     # until 2026-09-15. That literal is a consumer path inside the package
     # (K-42), and it was not a near-miss: enact-m5 keeps CI in `workflows/`
@@ -68,6 +80,25 @@ class ScriptsSizeDepth(Check):
         """Repository-relative, for both probing and display."""
         return ctx.relative(ctx.inputs["scripts_root"])
 
+    def direct_file_limit(self, ctx: Context) -> int:
+        """The direct-file limit in force: the declared one, else `MAX_DIRECT_FILES`.
+
+        ASCII digits only, so `+20`, `1_0`, ` 20` and full-width digits are
+        refused, which `int()` alone would accept. A declaration that cannot be
+        read as a positive integer is could-not-run: falling back to the default
+        would grade the repository against a limit it explicitly replaced.
+        """
+        declared = ctx.declarations.get(self.DIRECT_FILES_DECLARATION)
+        if declared is None:
+            return self.MAX_DIRECT_FILES
+        if re.fullmatch(r"[0-9]+", declared) is None or int(declared) < 1:
+            raise CouldNotRun(
+                f"declaration {self.DIRECT_FILES_DECLARATION}={declared!r} is not a "
+                "base-10 positive integer; set [controls.compliance.limits]."
+                "scripts_direct_files to a whole number of at least 1"
+            )
+        return int(declared)
+
     def structural(self, ctx: Context) -> Iterable[Report]:
         root = self._root(ctx)
         if not ctx.inputs["scripts_root"].is_dir():
@@ -81,6 +112,7 @@ class ScriptsSizeDepth(Check):
     def graded(self, ctx: Context, files: FileSet) -> Iterable[Report]:
         root = self._root(ctx)
         prefix = f"{root}/"
+        direct_limit = self.direct_file_limit(ctx)
 
         direct_files: dict[str, int] = {}
         deep_directories: dict[str, int] = {}
@@ -107,10 +139,10 @@ class ScriptsSizeDepth(Check):
                 deep_directories[directory] = depth
 
         for directory, count in direct_files.items():
-            if count > self.MAX_DIRECT_FILES:
+            if count > direct_limit:
                 findings.append(self.report(
                     directory,
-                    f"has {count} direct files; limit is {self.MAX_DIRECT_FILES}",
+                    f"has {count} direct files; limit is {direct_limit}",
                     f"split the files in {directory} into subdirectories by "
                     "responsibility",
                 ))

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/layout/scripts_size_depth/test_check.py

@@ -34,13 +34,15 @@ import pathlib
 
 from pathlib import Path
 
+import pytest
 from helpers import corpus_files
 
 from adl_compliance.checks.layout.scripts_size_depth import ScriptsSizeDepth
 from adl_compliance.core import scope
 from adl_compliance.core.context import Context, FileSet
+from adl_compliance.core.errors import CouldNotRun
 from adl_compliance.core.finding import Finding
-from adl_compliance.core.verdict import Outcome, decide
+from adl_compliance.core.verdict import Outcome, could_not_run, decide
 from adl_compliance.policy.registry import load
 
 FIXTURES = pathlib.Path(__file__).parent / "fixtures"
@@ -161,3 +163,108 @@ def test_a_missing_scripts_root_names_the_declared_path_not_a_constant(tmp_path:
     text = result.render()
     assert "missing ci/scripts" in text, text
     assert ".workflows" not in text, text
+
+
+# ----------------------------------------- the direct-file limit is declarable
+# `[controls.compliance.limits].scripts_direct_files` reaches the engine as
+# `--declare scripts-direct-files=N`. The engine default stays 15; a repository
+# that needs more says so in its own adl-config.toml, and a value the engine
+# cannot read is a could-not-run, never a quiet fall back to 15.
+DECLARATION = "scripts-direct-files"
+
+
+def declared_verdict(
+    given: tuple[str, ...],
+    declarations: dict[str, str],
+    root: Path = CORPUS,
+    scripts_root: str = ".workflows/scripts",
+):
+    ctx = Context(
+        root=root, row=ROW, declarations=declarations,
+        inputs={"scripts_root": root / scripts_root},
+    )
+    findings = tuple(
+        r for r in ScriptsSizeDepth().run(ctx, FileSet(paths=given))
+        if isinstance(r, Finding)
+    )
+    return decide(ROW, findings, 0, ())
+
+
+def flat_scripts_repo(tmp_path: Path, count: int) -> tuple[Path, tuple[str, ...]]:
+    """A repository whose `.workflows/scripts` holds `count` direct files and nothing else."""
+    root = tmp_path / "repo"
+    scripts = root / ".workflows/scripts"
+    scripts.mkdir(parents=True)
+    given = []
+    for index in range(count):
+        (scripts / f"s{index}.sh").write_text("#!/bin/sh\n")
+        given.append(f".workflows/scripts/s{index}.sh")
+    return root, tuple(given)
+
+
+def test_no_declaration_keeps_the_engine_default_of_fifteen() -> None:
+    ctx = Context(root=CORPUS, row=ROW)
+    assert ScriptsSizeDepth().direct_file_limit(ctx) == 15
+    assert ScriptsSizeDepth.MAX_DIRECT_FILES == 15
+
+
+def test_a_declared_limit_is_the_effective_limit() -> None:
+    ctx = Context(root=CORPUS, row=ROW, declarations={DECLARATION: "20"})
+    assert ScriptsSizeDepth().direct_file_limit(ctx) == 20
+
+
+def test_declared_twenty_accepts_the_sixteen_file_fixture() -> None:
+    """NARROWED holds 16 direct files, one over the default and well under 20."""
+    result = declared_verdict(NARROWED, {DECLARATION: "20"})
+    assert result.outcome is Outcome.CLEAN, result.render()
+    assert result.findings == ()
+
+
+def test_declared_twenty_leaves_only_the_depth_finding_on_the_full_fixture() -> None:
+    """The depth limit is not configurable: the direct-file finding goes, the depth one stays."""
+    result = declared_verdict(GIVEN, {DECLARATION: "20"})
+    assert result.outcome is Outcome.FINDINGS, result.render()
+    text = result.render()
+    assert "direct files" not in text, text
+    assert "a/b/c/d/e: is 5 levels below .workflows/scripts; limit is 4" in text
+    assert len(result.findings) == 1
+
+
+def test_declared_twenty_with_twenty_one_files_reports_the_declared_limit(tmp_path: Path) -> None:
+    root, given = flat_scripts_repo(tmp_path, 21)
+    result = declared_verdict(given, {DECLARATION: "20"}, root=root)
+    assert result.outcome is Outcome.FINDINGS, result.render()
+    assert len(result.findings) == 1
+    text = result.render()
+    assert ".workflows/scripts: has 21 direct files; limit is 20" in text, text
+    assert "limit is 15" not in text, text
+
+
+def test_declared_twenty_with_exactly_twenty_files_is_clean(tmp_path: Path) -> None:
+    root, given = flat_scripts_repo(tmp_path, 20)
+    result = declared_verdict(given, {DECLARATION: "20"}, root=root)
+    assert result.outcome is Outcome.CLEAN, result.render()
+
+
+def test_declared_fifteen_grades_exactly_like_no_declaration() -> None:
+    declared = declared_verdict(GIVEN, {DECLARATION: "15"})
+    default = verdict(GIVEN)
+    assert declared.outcome is default.outcome
+    assert [f.render() for f in declared.findings] == [f.render() for f in default.findings]
+    assert ".workflows/scripts: has 16 direct files; limit is 15" in declared.render()
+
+
+def test_an_unrelated_declaration_does_not_change_the_limit() -> None:
+    result = declared_verdict(GIVEN, {"license": "Proprietary", "root-dirs": "apps"})
+    assert ".workflows/scripts: has 16 direct files; limit is 15" in result.render()
+
+
+@pytest.mark.parametrize("value", ["abc", "0", "-3", "2.5", "", "+20", "1_0", "２０"])
+def test_an_unreadable_declared_limit_could_not_run(value: str) -> None:
+    """Never a silent fall back to 15: a value that is not a base-10 positive integer is loud."""
+    with pytest.raises(CouldNotRun) as raised:
+        declared_verdict(GIVEN, {DECLARATION: value})
+    message = str(raised.value)
+    assert DECLARATION in message, message
+    assert repr(value) in message, message
+    assert could_not_run(ROW, message).outcome is Outcome.COULD_NOT_RUN