code-standards 7.0.0__py3-none-any.whl

sarj_standards/libs/repository/docs.py

@@ -0,0 +1,347 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+import json
+import os
+from pathlib import Path
+import re
+import shlex
+import subprocess  # ruff: ignore[suspicious-subprocess-import] -- validates fixed local CLI examples.
+import sys
+import tomllib
+from typing import Final, TypeGuard
+
+from sarj_standards.libs.adoption import transaction
+
+
+_GENERATED_SENTINEL: Final = "<!-- Generated by `code-standards maintain docs sync`; do not edit. -->"
+_LOCAL_LINK: Final = re.compile(r"\[[^]]+\]\((?!https?://|mailto:)([^)#]*)(?:#([^)]+))?\)")
+_HEADING: Final = re.compile(r"^#{1,6}\s+(.+?)\s*#*\s*$", re.MULTILINE)
+_STANDARDS_COMMAND: Final = re.compile(r"^\s*(code-standards(?:\s+.+)?)\s*$", re.MULTILINE)
+_DOCUMENT_SUFFIXES: Final = frozenset({".md", ".mdx", ".rst"})
+_WALK_EXCLUDES: Final = frozenset(
+    {".git", ".mypy_cache", ".pytest_cache", ".ruff_cache", ".venv", "build", "coverage", "dist", "node_modules"}
+)
+_GENERATED_READMES: Final = (
+    Path("README.md"),
+    Path("packages/bootstrap/README.md"),
+    Path("packages/standards/README.md"),
+    Path("packages/standards-compat/README.md"),
+    Path("packages/python/README.md"),
+    Path("packages/sql/README.md"),
+    Path("packages/iac/README.md"),
+    Path("packages/typescript/README.md"),
+    Path("packages/tsconfig/README.md"),
+    Path("packages/docs-ui/README.md"),
+    Path("plugins/sarj-audit/README.md"),
+)
+_EXECUTABLE_OR_LEGAL_DOCUMENTS: Final = (Path("CLAUDE.md"),)
+_AUTHORED_DOCUMENTS: Final = (Path("docs/audits/rule-usefulness-audit.md"),)
+_PACKAGE_DEFINITIONS: Final = (
+    ("packages/standards/pyproject.toml", "PyPI", "text"),
+    ("packages/standards-compat/pyproject.toml", "PyPI", None),
+    ("packages/bootstrap/pyproject.toml", "PyPI", None),
+    ("packages/python/pyproject.toml", "PyPI", "python"),
+    ("packages/sql/pyproject.toml", "PyPI", "sql"),
+    ("packages/iac/pyproject.toml", "PyPI", "iac"),
+    ("packages/typescript/package.json", "npm", "eslint"),
+    ("packages/tsconfig/package.json", "npm", None),
+    ("packages/docs-ui/package.json", "npm", None),
+)
+_DOCUMENTATION_URL: Final = "https://code-standards.sarj.ai/"
+
+
+@dataclass(frozen=True, slots=True)
+class DocumentationResult:
+    changed: tuple[Path, ...]
+    checked: tuple[Path, ...]
+
+    @property
+    def status(self) -> int:
+        """Return a process-compatible status: one means generated drift."""
+        return int(bool(self.changed))
+
+
+def check(root: Path) -> DocumentationResult:
+    return _update(root.resolve(), write=False)
+
+
+def sync(root: Path) -> DocumentationResult:
+    return _update(root.resolve(), write=True)
+
+
+def _update(root: Path, *, write: bool) -> DocumentationResult:
+    rendered = _render_readmes(root)
+    _validate_markdown_allowlist(root)
+    changed = tuple(
+        path for path, content in rendered.items() if not path.is_file() or path.read_text(encoding="utf-8") != content
+    )
+    checked = _documentation_paths(root)
+    _validate_documents(
+        {**{path: path.read_text(encoding="utf-8") for path in checked if path not in rendered}, **rendered}
+    )
+    if write:
+        for path in changed:
+            transaction.atomic_write_text(root, path, rendered[path])
+    return DocumentationResult(changed=changed, checked=checked)
+
+
+def _render_readmes(root: Path) -> dict[Path, str]:
+    packages = [
+        (root / relative, registry, engine, _manifest(root / relative))
+        for relative, registry, engine in _PACKAGE_DEFINITIONS
+    ]
+    rendered = {root / "README.md": _root_readme(root, packages)}
+    for manifest_path, registry, engine, metadata in packages:
+        rendered[manifest_path.parent / "README.md"] = _package_readme(root, manifest_path, registry, engine, metadata)
+    rendered[root / "plugins/sarj-audit/README.md"] = _plugin_readme(root)
+    return dict(sorted(rendered.items()))
+
+
+def _root_readme(
+    root: Path,
+    packages: list[tuple[Path, str, str | None, dict[str, object]]],
+) -> str:
+    del root
+    standards = packages[0][3]
+    title = _title(_string(standards, "name"))
+    sections = [
+        _GENERATED_SENTINEL,
+        f"# {title}",
+        _string(standards, "description"),
+        "```bash\nuv tool install --python 3.14 code-standards\n```",
+        (
+            "## Contributing\n\n"
+            "Install uv 0.12.5, Python 3.14, Node 24.19, and GNU Make. Then bootstrap a fresh checkout:\n\n"
+            "```bash\nmake setup\nmake verify\n```"
+            "\n\nOnce a new rule and its tests are registered, stage it as a warning and validate it locally:\n\n"
+            "```bash\n"
+            "code-standards --root . maintain rules stage-warning python:no-string-concat-in-loop\n"
+            "code-standards --root . maintain rules evaluate --rule python:no-string-concat-in-loop --scope corpus\n"
+            "make verify\n"
+            "```\n\nAfter committing the resulting changes, review the complete rule diff:\n\n"
+            "```bash\n"
+            "code-standards --root . maintain rules changes --before origin/main --after HEAD\n"
+            "```\n\n"
+            "Fleet calibration and downstream PR creation run automatically after review and release."
+        ),
+        f"[Documentation]({_DOCUMENTATION_URL}) · [Source]({_source_url(standards)})",
+    ]
+    return "\n\n".join(sections) + "\n"
+
+
+def _package_readme(
+    root: Path,
+    manifest_path: Path,
+    registry: str,
+    engine: str | None,
+    metadata: dict[str, object],
+) -> str:
+    del root, manifest_path
+    name = _string(metadata, "name")
+    sections = [
+        _GENERATED_SENTINEL,
+        f"# {name}",
+        _string(metadata, "description"),
+        f"```bash\n{_install_command(name, registry)}\n```",
+        _package_usage(name, engine, version=_string(metadata, "version")),
+        f"[Documentation]({_homepage(metadata)}) · [Source]({_source_url(metadata)})",
+    ]
+    return "\n\n".join(sections) + "\n"
+
+
+def _package_usage(name: str, engine: str | None, *, version: str) -> str:
+    if name == "code-standards":
+        return (
+            "Use it from pre-commit with a coding agent so violations are flagged and fixed before commit.\n\n"
+            "```bash\n"
+            "code-standards setup\n"
+            "code-standards check\n"
+            "code-standards fix\n"
+            "code-standards doctor\n"
+            "code-standards update\n"
+            "```"
+        )
+    if name == "sarj-standards":
+        return (
+            "Compatibility bridge for existing exact launchers after the distribution was renamed to "
+            "`code-standards`. New installations should use `code-standards` directly."
+        )
+    if name == "sarj-standards-bootstrap":
+        return (
+            "Generated CI and hooks pin this protocol package exactly; ordinary Standards upgrades change only "
+            "`.sarj-standards.toml`.\n\n"
+            "```bash\n"
+            "uvx --no-config --isolated --python 3.14 --from "
+            f"sarj-standards-bootstrap=={version} code-standards check\n"
+            "```\n\n"
+            "The bootstrap deliberately inherits UV/PIP registry, proxy, certificate, cache, and offline environment "
+            "policy. `--no-config --isolated` prevents consumer project configuration and installed tools from "
+            "changing the selected bootstrap or Standards bundle."
+        )
+    executable = (
+        None
+        if engine is None
+        else {
+            "python": "sarj-python-lint",
+            "sql": "sarj-sql-lint",
+            "iac": "sarj-iac-lint",
+        }.get(engine)
+    )
+    if executable is None:
+        return "Rules and configuration are documented in the generated rule directory."
+    return f"```bash\n{executable} --help\n```"
+
+
+def _plugin_readme(root: Path) -> str:
+    manifest_path = root / "plugins/sarj-audit/.claude-plugin/plugin.json"
+    metadata = _manifest(manifest_path)
+    sections = [
+        _GENERATED_SENTINEL,
+        f"# {_title(_string(metadata, 'name'))}",
+        _string(metadata, "description"),
+        f"[Documentation]({_DOCUMENTATION_URL}) · [Source](https://github.com/sarj-ai/code-standards/tree/main/plugins/sarj-audit)",
+    ]
+    return "\n\n".join(sections) + "\n"
+
+
+def _install_command(name: str, registry: str) -> str:
+    if registry == "npm":
+        return f"npm install --save-dev {name}"
+    python = " --python 3.14" if name == "code-standards" else ""
+    return f"uv tool install{python} {name}"
+
+
+def _homepage(metadata: dict[str, object]) -> str:
+    urls = metadata.get("urls")
+    value = urls.get("Homepage") if _is_object_table(urls) else metadata.get("homepage")
+    return value if isinstance(value, str) and value else _DOCUMENTATION_URL
+
+
+def _source_url(metadata: dict[str, object]) -> str:
+    urls = metadata.get("urls")
+    value: object = urls.get("Repository") if _is_object_table(urls) else metadata.get("repository")
+    if _is_object_table(value):
+        value = value.get("url")
+    if not isinstance(value, str) or not value:
+        return "https://github.com/sarj-ai/code-standards"
+    return value.removeprefix("git+").removesuffix(".git")
+
+
+def _validate_markdown_allowlist(root: Path) -> None:
+    rejected: list[Path] = []
+    for parent, directories, names in os.walk(root):
+        directories[:] = sorted(name for name in directories if name not in _WALK_EXCLUDES)
+        for name in sorted(names):
+            path = Path(parent) / name
+            if path.suffix.lower() in _DOCUMENT_SUFFIXES and not _allowed_document(path.relative_to(root)):
+                rejected.append(path.relative_to(root))
+    if rejected:
+        msg = "documentation is not generated or executable-policy allowlisted: " + ", ".join(map(str, rejected))
+        raise ValueError(msg)
+
+
+def _allowed_document(relative: Path) -> bool:
+    if relative in _GENERATED_READMES or relative in _EXECUTABLE_OR_LEGAL_DOCUMENTS or relative in _AUTHORED_DOCUMENTS:
+        return True
+    match relative.parts:
+        case ("plugins", _plugin, "commands", filename):
+            return filename.endswith(".md")
+        case ("plugins", _plugin, "skills", _skill, "SKILL.md"):
+            return True
+        case ("plugins", _plugin, "skills", _skill, "references", filename):
+            return filename.endswith(".md")
+        case _:
+            return False
+
+
+def _documentation_paths(root: Path) -> tuple[Path, ...]:
+    required = {
+        *(root / path for path in _GENERATED_READMES),
+        *(root / path for path in _EXECUTABLE_OR_LEGAL_DOCUMENTS),
+    }
+    maintained = {
+        *(root / path for path in _AUTHORED_DOCUMENTS if (root / path).is_file()),
+        *root.glob("plugins/*/commands/*.md"),
+        *root.glob("plugins/*/skills/*/SKILL.md"),
+        *root.glob("plugins/*/skills/*/references/*.md"),
+    }
+    missing = [
+        path for path in sorted(required) if not path.is_file() and path.relative_to(root) not in _GENERATED_READMES
+    ]
+    if missing:
+        msg = f"required documentation is missing: {', '.join(str(path) for path in missing)}"
+        raise ValueError(msg)
+    return tuple(sorted(required | maintained))
+
+
+def _validate_documents(documents: dict[Path, str]) -> None:
+    for path, source in documents.items():
+        _validate_local_links(path, source, documents)
+        _validate_cli_examples(path, source)
+
+
+def _validate_local_links(path: Path, source: str, documents: dict[Path, str]) -> None:
+    for match in _LOCAL_LINK.finditer(source):
+        relative, anchor = match.groups()
+        target = (path.parent / relative).resolve() if relative else path
+        generated_target = documents.get(target)
+        if generated_target is None and not target.exists():
+            msg = f"{path} links to missing local target {relative!r}"
+            raise ValueError(msg)
+        if anchor and target.suffix.lower() == ".md":
+            target_source = generated_target if generated_target is not None else target.read_text(encoding="utf-8")
+            headings = {_heading_slug(heading.group(1)) for heading in _HEADING.finditer(target_source)}
+            if anchor not in headings:
+                msg = f"{path} links to missing Markdown heading {anchor!r} in {relative or path.name!r}"
+                raise ValueError(msg)
+
+
+def _heading_slug(heading: str) -> str:
+    normalized = re.sub(r"[^a-z0-9 -]", "", heading.lower()).replace(" ", "-")
+    return re.sub(r"-+", "-", normalized)
+
+
+def _validate_cli_examples(path: Path, source: str) -> None:
+    for match in _STANDARDS_COMMAND.finditer(source):
+        command = shlex.split(match.group(1))
+        completed = subprocess.run(  # ruff: ignore[subprocess-without-shell-equals-true] -- fixed interpreter and argv.
+            [sys.executable, "-m", "sarj_standards", *command[1:], "--help"],
+            check=False,
+            capture_output=True,
+            text=True,
+        )
+        if completed.returncode != 0:
+            msg = f"{path} contains an invalid command example: {match.group(1)!r}"
+            raise ValueError(msg)
+
+
+def _manifest(path: Path) -> dict[str, object]:
+    if path.suffix == ".toml":
+        document = tomllib.loads(path.read_text(encoding="utf-8"))
+        project: object = document.get("project")
+        if not _is_object_table(project):
+            msg = f"{path} has no project table"
+            raise ValueError(msg)
+        return project
+    document: object = json.loads(path.read_text(encoding="utf-8"))  # pyright: ignore[reportAny]
+    if not _is_object_table(document):
+        msg = f"{path} is not an object"
+        raise TypeError(msg)
+    return document
+
+
+def _string(table: dict[str, object], key: str) -> str:
+    value = table.get(key)
+    if not isinstance(value, str) or not value:
+        msg = f"manifest or catalog entry does not declare {key!r}"
+        raise ValueError(msg)
+    return value
+
+
+def _title(name: str) -> str:
+    return " ".join(part.capitalize() for part in name.replace("@", "").replace("/", " ").replace("-", " ").split())
+
+
+def _is_object_table(value: object) -> TypeGuard[dict[str, object]]:
+    return isinstance(value, dict)

sarj_standards/libs/repository/hooks.py

@@ -0,0 +1,118 @@
+from __future__ import annotations
+
+from pathlib import Path
+import platform
+import shlex
+import shutil
+import stat
+import subprocess  # ruff: ignore[suspicious-subprocess-import] -- fixed-argument git and Lefthook calls are required.
+import sys
+import sysconfig
+from types import MappingProxyType
+from typing import Final
+
+from sarj_standards.libs.adoption import transaction
+
+
+_VERSION: Final = "2.1.10"
+_ARCHITECTURES: Final = MappingProxyType({"aarch64": "arm64", "amd64": "x86_64"})
+
+
+def install(root: Path) -> int:
+    if not any((root / name).is_file() for name in ("lefthook.yml", "lefthook.yaml")):
+        msg = f"no Lefthook configuration found in {root}"
+        raise ValueError(msg)
+    binary = _binary("lefthook")
+    native_binary = _native_binary()
+    durable_binary = _hook_path(root, "pre-commit").parent / f".sarj-lefthook{native_binary.suffix}"
+    transaction.validate_targets(durable_binary.parent, (durable_binary,))
+    subprocess.run([str(binary), "install", "-f"], cwd=root, check=True)  # ruff: ignore[subprocess-without-shell-equals-true]
+    hook_paths = _hook_paths(root)
+    if hook_paths:
+        transaction.atomic_write_bytes(
+            durable_binary.parent,
+            durable_binary,
+            native_binary.read_bytes(),
+            mode=stat.S_IMODE(native_binary.stat(follow_symlinks=False).st_mode),
+        )
+        marker = f"export LEFTHOOK_BIN={shlex.quote(durable_binary.as_posix())}"
+        for hook_path in hook_paths:
+            lines = [line for line in hook_path.read_text(encoding="utf-8").splitlines() if "LEFTHOOK_BIN=" not in line]
+            lines.insert(1, marker)
+            transaction.atomic_write_text(hook_path.parent, hook_path, "\n".join(lines) + "\n")
+    subprocess.run([str(binary), "validate"], cwd=root, check=True)  # ruff: ignore[subprocess-without-shell-equals-true]
+    subprocess.run([str(binary), "check-install"], cwd=root, check=True)  # ruff: ignore[subprocess-without-shell-equals-true]
+    return 0
+
+
+def run(argv: list[str] | None = None) -> int:
+    try:
+        return _run(list(sys.argv[1:] if argv is None else argv))
+    except (OSError, RuntimeError, subprocess.SubprocessError) as exc:
+        sys.stderr.write(f"error: {exc}\n")
+        return 2
+
+
+def _run(args: list[str]) -> int:
+    root = Path(_git(Path.cwd(), "rev-parse", "--show-toplevel").strip())
+    binary = _binary("lefthook")
+    if _installed_version(binary) != _VERSION:
+        msg = f"lefthook {_VERSION} is required; reinstall code-standards"
+        raise RuntimeError(msg)
+    return subprocess.run(  # ruff: ignore[subprocess-without-shell-equals-true]
+        [str(binary), *args], cwd=root, check=False
+    ).returncode
+
+
+def _binary(name: str) -> Path:
+    executable = shutil.which(name, path=str(Path(sys.executable).parent))
+    if executable is None:
+        msg = f"{name} is missing from the code-standards environment"
+        raise OSError(msg)
+    return Path(executable)
+
+
+def _native_binary() -> Path:
+    system = platform.system().lower()
+    machine = platform.machine().lower()
+    architecture = _ARCHITECTURES.get(machine, machine)
+    suffix = ".exe" if system == "windows" else ""
+    binary = (
+        Path(sysconfig.get_path("purelib"))
+        / "lefthook"
+        / "bin"
+        / f"lefthook-{system}-{architecture}"
+        / f"lefthook{suffix}"
+    )
+    if not binary.is_file():
+        msg = f"native Lefthook binary is missing from the code-standards environment: {binary}"
+        raise OSError(msg)
+    return binary
+
+
+def _hook_paths(root: Path) -> list[Path]:
+    return [path for hook_name in ("pre-commit", "pre-push") if (path := _hook_path(root, hook_name)).is_file()]
+
+
+def _hook_path(root: Path, hook_name: str) -> Path:
+    path = Path(_git(root, "rev-parse", "--git-path", f"hooks/{hook_name}").strip())
+    return path if path.is_absolute() else root / path
+
+
+def _installed_version(binary: Path) -> str | None:
+    if not binary.is_file():
+        return None
+    completed = subprocess.run(  # ruff: ignore[subprocess-without-shell-equals-true]
+        [str(binary), "version"], check=False, capture_output=True, text=True
+    )
+    return completed.stdout.strip() if completed.returncode == 0 else None
+
+
+def _git(root: Path, *args: str) -> str:
+    executable = shutil.which("git")
+    if executable is None:
+        msg = "git is required to manage repository hooks"
+        raise OSError(msg)
+    return subprocess.run(  # ruff: ignore[subprocess-without-shell-equals-true]
+        [executable, *args], cwd=root, check=True, capture_output=True, text=True
+    ).stdout

sarj_standards/libs/repository/ledger.py

@@ -0,0 +1,99 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from enum import StrEnum
+import json
+import re
+from typing import TYPE_CHECKING, Final
+
+from sarj_standards._meta import CONFIGS_DIR
+from sarj_standards.libs.adoption.manifest import as_table, list_field, text_field
+
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+
+LEDGER_JSON: Final = CONFIGS_DIR / "rule-ledger.json"
+
+#: The `kind` values that name an ESLint rule and a bare `SARJnnn` code; the rest
+#: (`python`, `sql`, `iac`) are rule ids, which double as pre-commit hook ids.
+ESLINT: Final = "eslint"
+CODE: Final = "code"
+
+
+class Status(StrEnum):
+    REMOVED = "removed"
+    RENAMED = "renamed"
+
+
+@dataclass(frozen=True)
+class Retired:
+    id: str
+    kind: str
+    status: Status
+    replacement: str | None
+    note: str
+
+    @property
+    def pattern(self) -> re.Pattern[str]:
+        if self.kind == ESLINT:
+            return re.compile(rf"(?<![\w/-]){re.escape(self.id)}(?![\w-])")
+        if self.kind == CODE:
+            return re.compile(rf"\b{re.escape(self.id)}\b")
+        return re.compile(rf"(?<![\w-])(?:sarj-{re.escape(self.id)}|--rule[ =]{re.escape(self.id)})(?![\w-])")
+
+    @property
+    def advice(self) -> str:
+        if self.status is Status.RENAMED and self.replacement is not None:
+            return f"renamed to {self.replacement} -- {self.note}"
+        return f"no longer exists -- {self.note}"
+
+
+@dataclass(frozen=True)
+class Ledger:
+    rules: Mapping[str, tuple[str, ...]]
+    codes: Mapping[str, tuple[str, ...]]
+    retired: tuple[Retired, ...]
+
+    def active_ids(self) -> frozenset[str]:
+        live = {code for family in self.codes.values() for code in family}
+        for family, names in self.rules.items():
+            prefix = "@sarj/" if family == ESLINT else ""
+            live.update(f"{prefix}{name}" for name in names)
+        return frozenset(live)
+
+
+def load() -> Ledger:
+    parsed: object = json.loads(  # pyright: ignore[reportAny] -- json.loads is an untyped stdlib boundary; the shape is narrowed below
+        LEDGER_JSON.read_text(encoding="utf-8")
+    )
+    data = as_table(parsed)
+    return Ledger(
+        rules=_families(data, "rules"),
+        codes=_families(data, "codes"),
+        retired=tuple(_retired(data)),
+    )
+
+
+def _families(data: Mapping[str, object], key: str) -> dict[str, tuple[str, ...]]:
+    table = as_table(data.get(key))
+    return {family: tuple(name for name in list_field(table, family) if isinstance(name, str)) for family in table}
+
+
+def _retired(data: Mapping[str, object]) -> Iterator[Retired]:
+    for entry in list_field(data, "retired"):
+        row = as_table(entry)
+        identifier = text_field(row, "id")
+        kind = text_field(row, "kind")
+        status = text_field(row, "status")
+        if identifier is None or kind is None or status not in tuple(Status):
+            continue
+        yield Retired(
+            id=identifier,
+            kind=kind,
+            status=Status(status),
+            replacement=text_field(row, "replacement"),
+            note=text_field(row, "note") or "",
+        )