code-standards 7.0.0__py3-none-any.whl

sarj_standards/libs/repository/rule_maintenance.py

@@ -0,0 +1,225 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from importlib import import_module
+import json
+from operator import itemgetter
+import re
+from typing import TYPE_CHECKING, Final, NamedTuple, Protocol
+
+from sarj_standards.libs.adoption.manifest import as_table, list_field
+from sarj_standards.libs.linting import textlint
+
+from . import ledger, repository
+
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+_FAMILIES: Final = (
+    ("python", "sarj_python_lint.rules", "packages/python"),
+    ("sql", "sarj_sql_lint.rules", "packages/sql"),
+    ("iac", "sarj_iac_lint.rules", "packages/iac"),
+)
+_RENAME_ENTRY: Final = re.compile(r'^\s*"(?P<old>[a-z0-9-]+)": "(?P<new>[a-z0-9-]+)",', re.MULTILINE)
+_PLACEHOLDER: Final = "TODO: say why it went, in one line a consumer can act on"
+
+
+class Rule(Protocol):
+    code: str
+    __module__: str
+    documentation: RuleDocumentation | None
+
+
+class RuleDocumentation(Protocol):
+    aliases: tuple[str, ...]
+
+
+class _NativeLedgerState(NamedTuple):
+    rules: dict[str, list[str]]
+    codes: dict[str, list[str]]
+    renames: dict[tuple[str, str], str]
+
+
+@dataclass(frozen=True, slots=True)
+class SyncResult:
+    status: int
+    message: str
+
+
+def inventory(root: Path) -> list[dict[str, str]]:
+    items: list[dict[str, str]] = []
+    for family, module_name, package in _FAMILIES:
+        registry = _registry(module_name)
+        for rule_id, rule in sorted(registry.items()):
+            module = rule.__module__.replace(".", "/")
+            source_name = module.rsplit("/", 1)[-1]
+            items.append(
+                {
+                    "family": family,
+                    "id": rule_id,
+                    "code": str(rule.code),
+                    "source": f"{package}/src/{module}.py",
+                    "test": f"{package}/tests/rules/test_{source_name}.py",
+                }
+            )
+    for rule_id, meta in sorted(textlint.REGISTRY.items()):
+        items.append(
+            {
+                "family": "text",
+                "id": rule_id,
+                "code": meta.code,
+                "source": "packages/standards/src/sarj_standards/libs/linting/textlint.py",
+                "test": "packages/standards/tests/test_textlint.py",
+            }
+        )
+    eslint_rules = (
+        repository.eslint_rule_names(root)
+        if (root / "packages/typescript/src/index.ts").is_file()
+        else list(ledger.load().rules.get(ledger.ESLINT, ()))
+    )
+    items.extend(
+        {
+            "family": "typescript",
+            "id": rule_id,
+            "code": f"@sarj/{rule_id}",
+            "source": f"packages/typescript/src/rules/{rule_id}.ts",
+            "test": f"packages/typescript/tests/rules/{rule_id}.test.ts",
+        }
+        for rule_id in eslint_rules
+    )
+    return sorted(items, key=itemgetter("family", "id"))
+
+
+def sync_ledger(root: Path, *, check: bool) -> SyncResult:
+    path = root / "packages/standards/src/sarj_standards/configs/rule-ledger.json"
+    previous = _load_ledger(path)
+    rules, codes, source_renames = _native_ledger_state()
+    rules["eslint"] = repository.eslint_rule_names(root)
+    rules["text"] = sorted(textlint.REGISTRY)
+    codes["text"] = sorted(meta.code for meta in textlint.REGISTRY.values())
+    for rule_id, meta in textlint.REGISTRY.items():
+        for old_id in meta.aliases:
+            source_renames["text", old_id] = rule_id
+    retired = _retired(previous, root, source_renames)
+    known = {str(entry.get("id")) for entry in retired}
+    old_rules = repository_table(previous.get("rules"))
+    old_codes = repository_table(previous.get("codes"))
+    for family, raw_names in old_rules.items():
+        prefix = "@sarj/" if family == "eslint" else ""
+        for name in _string_list(raw_names):
+            identifier = f"{prefix}{name}"
+            if name not in rules.get(family, []) and identifier not in known:
+                retired.append(_retired_entry(identifier, family))
+                known.add(identifier)
+    for family, raw_codes in old_codes.items():
+        for code in _string_list(raw_codes):
+            if code not in codes.get(family, []) and code not in known:
+                retired.append(_retired_entry(code, "code"))
+                known.add(code)
+    updated = {
+        "$comment": previous.get("$comment", "Rule compatibility ledger."),
+        "rules": rules,
+        "codes": codes,
+        "retired": sorted(retired, key=lambda entry: str(entry.get("id"))),
+    }
+    rendered = json.dumps(updated, indent=2) + "\n"
+    current = path.read_text(encoding="utf-8")
+    if rendered == current:
+        return SyncResult(0, f"ok: {path.name} matches the registries")
+    if check:
+        return SyncResult(1, f"drift: {path}")
+    path.write_text(rendered, encoding="utf-8")
+    status = 1 if any(entry.get("note") == _PLACEHOLDER for entry in retired) else 0
+    return SyncResult(status, f"wrote: {path}")
+
+
+def _native_ledger_state() -> _NativeLedgerState:
+    rules: dict[str, list[str]] = {}
+    codes: dict[str, list[str]] = {}
+    renames: dict[tuple[str, str], str] = {}
+    for family, module_name, _package in _FAMILIES:
+        registry = _registry(module_name)
+        rules[family] = sorted(registry)
+        codes[family] = sorted(str(rule.code) for rule in registry.values())
+        for rule_id, rule in registry.items():
+            if rule.documentation is None:
+                continue
+            for old_id in rule.documentation.aliases:
+                renames[family, old_id] = rule_id
+    return _NativeLedgerState(rules, codes, renames)
+
+
+def repository_table(value: object) -> dict[str, object]:
+    return as_table(value)
+
+
+def _load_ledger(path: Path) -> dict[str, object]:
+    value: object = json.loads(path.read_text(encoding="utf-8"))  # pyright: ignore[reportAny]
+    return repository_table(value)
+
+
+def _registry(module_name: str) -> Mapping[str, type[Rule]]:
+    module = import_module(module_name)
+    value = getattr(module, "REGISTRY", None)
+    if not isinstance(value, Mapping):
+        msg = f"{module_name} has no registry"
+        raise TypeError(msg)
+    return value  # pyright: ignore[reportUnknownVariableType]
+
+
+def _retired(
+    previous: Mapping[str, object],
+    root: Path,
+    source_renames: Mapping[tuple[str, str], str],
+) -> list[dict[str, object]]:
+    entries = [repository_table(item) for item in _object_list(previous.get("retired"))]
+    derived_kinds = {"eslint", *(kind for kind, _old_id in source_renames)}
+    kept = [entry for entry in entries if not (entry.get("kind") in derived_kinds and entry.get("status") == "renamed")]
+    existing = {str(entry.get("id")): entry for entry in entries}
+    for (kind, old), new in sorted(source_renames.items()):
+        prior = existing.get(old)
+        kept.append(
+            prior
+            if prior is not None and prior.get("replacement") == new
+            else {
+                "id": old,
+                "kind": kind,
+                "status": "renamed",
+                "replacement": new,
+                "note": f"Replace sarj-{old} with sarj-{new} before upgrading.",
+            }
+        )
+    renames_path = root / "packages/typescript/src/rules/_renames.ts"
+    for match in _RENAME_ENTRY.finditer(renames_path.read_text(encoding="utf-8")):
+        old = match.group("old")
+        new = match.group("new")
+        identifier = f"@sarj/{old}"
+        replacement = f"@sarj/{new}"
+        prior = existing.get(identifier)
+        kept.append(
+            prior
+            if prior is not None and prior.get("replacement") == replacement
+            else {
+                "id": identifier,
+                "kind": "eslint",
+                "status": "renamed",
+                "replacement": replacement,
+                "note": f"Replace @sarj/{old} with @sarj/{new} before upgrading.",
+            }
+        )
+    return kept
+
+
+def _retired_entry(identifier: str, kind: str) -> dict[str, object]:
+    return {"id": identifier, "kind": kind, "status": "removed", "replacement": None, "note": _PLACEHOLDER}
+
+
+def _object_list(value: object) -> list[object]:
+    return list_field({"value": value}, "value")
+
+
+def _string_list(value: object) -> list[str]:
+    return [item for item in _object_list(value) if isinstance(item, str)]

sarj_standards/libs/rules/__init__.py

@@ -0,0 +1,74 @@
+from .catalog import DocumentedRule, RuleCatalog, RuleCatalogDocument
+from .contracts import (
+    AutofixPolicy,
+    CatalogRule,
+    DefaultLevel,
+    EvaluationCase,
+    ExampleFile,
+    ExpectedOutcome,
+    Finding,
+    Language,
+    MessageId,
+    RuleCategory,
+    RuleEngine,
+    RuleExample,
+    RuleId,
+    RuleOrigin,
+    RuleProblem,
+    RuleSelection,
+    RuleSelector,
+    RuleSpec,
+    RuleStatus,
+)
+from .corpus_runner import (
+    CorpusBatchResult,
+    CorpusLintError,
+    IsolatedCorpusReport,
+    run_isolated_corpora,
+)
+from .evaluation import (
+    CaseEvaluation,
+    EvaluationEvidence,
+    EvaluationReport,
+    EvaluationThresholds,
+    PromotionDecision,
+    RuleEvaluator,
+    evaluate,
+)
+
+
+__all__ = [
+    "AutofixPolicy",
+    "CaseEvaluation",
+    "CatalogRule",
+    "CorpusBatchResult",
+    "CorpusLintError",
+    "DefaultLevel",
+    "DocumentedRule",
+    "EvaluationCase",
+    "EvaluationEvidence",
+    "EvaluationReport",
+    "EvaluationThresholds",
+    "ExampleFile",
+    "ExpectedOutcome",
+    "Finding",
+    "IsolatedCorpusReport",
+    "Language",
+    "MessageId",
+    "PromotionDecision",
+    "RuleCatalog",
+    "RuleCatalogDocument",
+    "RuleCategory",
+    "RuleEngine",
+    "RuleEvaluator",
+    "RuleExample",
+    "RuleId",
+    "RuleOrigin",
+    "RuleProblem",
+    "RuleSelection",
+    "RuleSelector",
+    "RuleSpec",
+    "RuleStatus",
+    "evaluate",
+    "run_isolated_corpora",
+]

sarj_standards/libs/rules/catalog.py

@@ -0,0 +1,145 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+import json
+from pathlib import PurePosixPath
+from typing import TYPE_CHECKING, Self
+
+from .contracts import (
+    CatalogRule,
+    DefaultLevel,
+    ExpectedOutcome,
+    Language,
+    RuleOrigin,
+    RuleSpec,
+    RuleStatus,
+)
+
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable
+
+
+@dataclass(frozen=True, slots=True)
+class RuleCatalog:
+    rules: tuple[CatalogRule, ...]
+
+    @classmethod
+    def from_rules(cls, rules: Iterable[CatalogRule]) -> Self:
+        collected = tuple(rules)
+        identifiers = [rule.identifier for rule in collected]
+        if len(identifiers) != len(set(identifiers)):
+            msg = "catalog rule identifiers must be unique"
+            raise ValueError(msg)
+        return cls(tuple(sorted(collected, key=lambda rule: rule.identifier)))
+
+    def get(self, identifier: str) -> CatalogRule | None:
+        return next((rule for rule in self.rules if rule.identifier == identifier), None)
+
+    def filter(
+        self,
+        *,
+        language: Language | None = None,
+        origin: RuleOrigin | None = None,
+        configurable: bool | None = None,
+    ) -> tuple[CatalogRule, ...]:
+        return tuple(
+            rule
+            for rule in self.rules
+            if (language is None or language in rule.languages)
+            and (origin is None or rule.origin is origin)
+            and (configurable is None or rule.configurable is configurable)
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class DocumentedRule:
+    spec: RuleSpec
+    default_level: DefaultLevel
+    source: PurePosixPath
+    test: PurePosixPath
+    status: RuleStatus = RuleStatus.ACTIVE
+
+    def __post_init__(self) -> None:
+        if self.status is not RuleStatus.ACTIVE:
+            msg = "documented live rules must have active status; lifecycle tombstones are separate"
+            raise ValueError(msg)
+        for path in (self.source, self.test):
+            if path.is_absolute() or ".." in path.parts or not path.name or "\\" in path.as_posix():
+                msg = "catalog source and test paths must be safe repository-relative paths"
+                raise ValueError(msg)
+
+
+@dataclass(frozen=True, slots=True)
+class RuleCatalogDocument:
+    rules: tuple[DocumentedRule, ...]
+    schema_version: int = 1
+
+    def __post_init__(self) -> None:
+        if self.schema_version != 1:
+            msg = "unsupported rule catalog schema version"
+            raise ValueError(msg)
+        keys = tuple(rule.spec.key for rule in self.rules)
+        if len(keys) != len(set(keys)):
+            msg = "catalog rule keys must be unique"
+            raise ValueError(msg)
+        aliases = tuple(f"{rule.spec.engine.value}:{alias}" for rule in self.rules for alias in rule.spec.aliases)
+        if len(aliases) != len(set(aliases)) or set(aliases) & set(keys):
+            msg = "catalog aliases must be unique and must not shadow live rule keys"
+            raise ValueError(msg)
+
+    def as_public_dict(self) -> dict[str, object]:
+        return {
+            "schemaVersion": self.schema_version,
+            "rules": [self._rule_dict(rule) for rule in sorted(self.rules, key=lambda item: item.spec.key)],
+        }
+
+    @staticmethod
+    def _rule_dict(rule: DocumentedRule) -> dict[str, object]:
+        spec = rule.spec
+        examples = sorted(
+            (example for example in spec.examples if example.public),
+            key=lambda example: example.example_id,
+        )
+        return {
+            "key": spec.key,
+            "engine": spec.engine.value,
+            "id": spec.rule_id,
+            "code": spec.code,
+            "summary": spec.summary,
+            "rationale": spec.rationale,
+            "remediation": spec.remediation,
+            "category": spec.category.value,
+            "languages": sorted(language.value for language in spec.languages),
+            "defaultLevel": rule.default_level.value,
+            "autofix": spec.autofix.value,
+            "status": rule.status.value,
+            "aliases": sorted(spec.aliases),
+            "limitations": list(spec.limitations),
+            "filePatterns": list(spec.file_patterns),
+            "messageIds": list(spec.message_ids),
+            "optionsSchema": json.loads(spec.options_schema) if spec.options_schema is not None else None,
+            "references": list(spec.references),
+            "since": spec.since,
+            "source": rule.source.as_posix(),
+            "test": rule.test.as_posix(),
+            "examples": [
+                {
+                    "id": example.example_id,
+                    "scenarioId": example.scenario,
+                    "title": example.title,
+                    "outcome": "reject" if example.outcome is ExpectedOutcome.MATCH else "accept",
+                    "focusPath": example.focus_path.as_posix(),
+                    "expectedCount": example.expected_count,
+                    "files": [
+                        {"path": item.path.as_posix(), "source": item.source}
+                        for item in sorted(example.files, key=lambda item: item.path)
+                    ],
+                    "fixedFiles": [
+                        {"path": item.path.as_posix(), "source": item.source}
+                        for item in sorted(example.fixed_files, key=lambda item: item.path)
+                    ],
+                }
+                for example in examples
+            ],
+        }