strict-module 0.5.0__py3-none-any.whl

strict_module/cli.py

@@ -0,0 +1,152 @@
+"""Command-line interface for strict-module (formerly dto-strict)."""
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from .config import Config
+from .linter import DtoStrictLinter
+from .loc_cap import run_loc_cap
+
+
+def handle_loc_cap(args: list[str]) -> int:
+    """Handle loc-cap subcommand (invoked when sys.argv[1] == 'loc-cap')."""
+    parser = argparse.ArgumentParser(
+        prog="dto-strict loc-cap",
+        description="LOC cap enforcer with configurable hard/soft limits and ratchet baseline.",
+    )
+    parser.add_argument("path", help="Path to directory to scan")
+    parser.add_argument(
+        "--config",
+        default="pyproject.toml",
+        help="Path to pyproject.toml config file (default: pyproject.toml)",
+    )
+    parser.add_argument(
+        "--hard-cap",
+        type=int,
+        help="Hard cap limit (default: 694, or from [tool.strict-module.loc-cap].hard_cap)",
+    )
+    parser.add_argument(
+        "--soft-target",
+        type=int,
+        help="Soft target limit (default: 500, or from [tool.strict-module.loc-cap].soft_target)",
+    )
+    parser.add_argument(
+        "--baseline",
+        help="Baseline file path (default: .loc-cap-baseline.txt, or from [tool.strict-module.loc-cap].baseline_file)",
+    )
+    parser.add_argument(
+        "--generate-baseline",
+        action="store_true",
+        help="Generate baseline from all Python files in path (stdout)",
+    )
+
+    parsed = parser.parse_args(args[2:])  # Skip 'dto-strict' and 'loc-cap'
+
+    # Load config from pyproject
+    config_path = Path(parsed.config)
+    config = Config.from_pyproject(config_path)
+
+    # Determine final values: CLI flag > config file > default
+    hard_cap = (
+        parsed.hard_cap if parsed.hard_cap is not None else config.loc_cap.hard_cap
+    )
+    soft_target = (
+        parsed.soft_target
+        if parsed.soft_target is not None
+        else config.loc_cap.soft_target
+    )
+    baseline_file = parsed.baseline if parsed.baseline else config.loc_cap.baseline_file
+
+    # Run loc-cap checker
+    return run_loc_cap(
+        path=parsed.path,
+        hard_cap=hard_cap,
+        soft_target=soft_target,
+        baseline_file=baseline_file,
+        generate=parsed.generate_baseline,
+    )
+
+
+def main() -> int:
+    """Main CLI entry point."""
+    # Check for loc-cap subcommand (dispatch before argparse)
+    if len(sys.argv) > 1 and sys.argv[1] == "loc-cap":
+        return handle_loc_cap(sys.argv)
+
+    parser = argparse.ArgumentParser(
+        description="AST-based linter for Python DTO discipline and facade-ban enforcement."
+    )
+    parser.add_argument("path", nargs="?", help="Path to file or directory to lint")
+    parser.add_argument(
+        "--config",
+        default="pyproject.toml",
+        help="Path to pyproject.toml config file (default: pyproject.toml)",
+    )
+    parser.add_argument(
+        "--format",
+        choices=["text", "github", "json"],
+        default="text",
+        help="Output format (default: text)",
+    )
+    parser.add_argument(
+        "--generate-baseline",
+        action="store_true",
+        help="Generate baseline JSON from all violations in path and output to stdout",
+    )
+    parser.add_argument(
+        "--baseline",
+        type=Path,
+        help="Path to baseline JSON file; violations in baseline are accepted (ratchet mode)",
+    )
+
+    args = parser.parse_args()
+
+    # Load configuration
+    config_path = Path(args.config)
+    config = Config.from_pyproject(config_path)
+
+    # If generating baseline, require path
+    if args.generate_baseline:
+        if not args.path:
+            print("error: --generate-baseline requires PATH argument", file=sys.stderr)
+            return 1
+
+        target_path = Path(args.path)
+        linter = DtoStrictLinter(config)
+        violations = linter.lint_path(target_path)
+        baseline_data = linter.generate_baseline(violations)
+        print(json.dumps(baseline_data, indent=2))
+        return 0
+
+    # Normal linting mode
+    if not args.path:
+        print(
+            "error: PATH argument required (unless using --generate-baseline)",
+            file=sys.stderr,
+        )
+        return 1
+
+    target_path = Path(args.path)
+
+    # Load baseline if provided
+    baseline = None
+    if args.baseline:
+        baseline = DtoStrictLinter.load_baseline(args.baseline)
+
+    # Lint path
+    linter = DtoStrictLinter(config, baseline=baseline)
+    violations = linter.lint_path(target_path)
+
+    # Output results
+    if violations:
+        output = linter.format_violations(violations, args.format)
+        print(output)
+
+    # Return exit code
+    return linter.get_exit_code(violations)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

strict_module/config/__init__.py

@@ -0,0 +1,6 @@
+"""Configuration module for strict-module."""
+
+from ._config import Config, LocCapConfig
+from ._version import __version__
+
+__all__ = ["Config", "LocCapConfig", "__version__"]

strict_module/config/_config.py

@@ -0,0 +1,97 @@
+"""Configuration loading for strict-module (formerly dto-strict)."""
+
+try:
+    import tomllib  # Python 3.11+ stdlib
+except ModuleNotFoundError:  # Python 3.10
+    import tomli as tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+@dataclass(frozen=True, slots=True)
+class LocCapConfig:
+    """Configuration for LOC cap checker."""
+
+    hard_cap: int = 694
+    soft_target: int = 500
+    baseline_file: str = ".loc-cap-baseline.txt"
+
+
+@dataclass(frozen=True, slots=True)
+class Config:
+    """Configuration for strict-module linter."""
+
+    service_paths: list[str] = field(
+        default_factory=lambda: ["apps/*/services/*.py", "**/services/*.py"]
+    )
+    dto_paths: list[str] = field(default_factory=lambda: ["**/dtos.py", "**/dtos/*.py"])
+    exception_tags: list[str] = field(
+        default_factory=lambda: ["facade — celery schedule", "FRAMEWORK"]
+    )
+    disabled_rules: list[str] = field(default_factory=list)
+    severity_overrides: dict[str, str] = field(default_factory=dict)
+    strict_collections: bool = field(default=False)
+    exception_tag_requires_justification: bool = field(default=False)
+    max_exception_tags_per_file: int | None = field(default=None)
+    r003_mode: str = field(default="canonical")  # "canonical" or "legacy"
+    r006_paths: list[str] = field(
+        default_factory=lambda: ["apps/*/services/*.py", "**/services/*.py"]
+    )
+    min_dict_keys: int = field(default=3)  # NEW: threshold for R002
+    r003_strict_repr: bool = field(
+        default=True
+    )  # NEW: R003 strict mode (flags repr=False)
+    loc_cap: LocCapConfig = field(default_factory=LocCapConfig)
+
+    @classmethod
+    def from_pyproject(cls, path: Path) -> "Config":
+        """Load configuration from pyproject.toml."""
+        if not path.exists():
+            return cls()
+
+        try:
+            with open(path, "rb") as f:
+                data = tomllib.load(f)
+        except Exception:
+            return cls()
+
+        tool_data = data.get("tool", {})
+        config_data = tool_data.get("strict-module") or tool_data.get("dto-strict", {})
+        loc_cap_data = config_data.get("loc-cap", {})
+
+        loc_cap = LocCapConfig(
+            hard_cap=loc_cap_data.get("hard_cap", 694),
+            soft_target=loc_cap_data.get("soft_target", 500),
+            baseline_file=loc_cap_data.get("baseline_file", ".loc-cap-baseline.txt"),
+        )
+
+        return cls(
+            service_paths=config_data.get(
+                "service_paths",
+                ["apps/*/services/*.py", "**/services/*.py"],
+            ),
+            dto_paths=config_data.get("dto_paths", ["**/dtos.py", "**/dtos/*.py"]),
+            exception_tags=config_data.get(
+                "exception_tags",
+                ["facade — celery schedule", "FRAMEWORK"],
+            ),
+            disabled_rules=config_data.get("disabled_rules", []),
+            severity_overrides=config_data.get("severity_overrides", {}),
+            strict_collections=config_data.get("strict_collections", False),
+            exception_tag_requires_justification=config_data.get(
+                "exception_tag_requires_justification", False
+            ),
+            max_exception_tags_per_file=config_data.get("max_exception_tags_per_file"),
+            r003_mode=config_data.get("r003_mode", "canonical"),
+            r006_paths=config_data.get(
+                "r006_paths",
+                ["apps/*/services/*.py", "**/services/*.py"],
+            ),
+            min_dict_keys=config_data.get("min_dict_keys", 3),
+            r003_strict_repr=config_data.get("r003_strict_repr", True),
+            loc_cap=loc_cap,
+        )
+
+    def is_rule_enabled(self, rule_id: str) -> bool:
+        """Check if a rule is enabled."""
+        return rule_id not in self.disabled_rules

strict_module/config/_version.py

@@ -0,0 +1,3 @@
+"""Version single-source for strict-module."""
+
+__version__ = "0.5.0"

strict_module/linter.py

@@ -0,0 +1,212 @@
+"""Main linter implementation."""
+
+import ast
+import hashlib
+import json
+from pathlib import Path
+from dataclasses import dataclass
+
+from .checkers import (
+    R001Checker,
+    R002Checker,
+    R003Checker,
+    R004Checker,
+    R005Checker,
+    R006Checker,
+    R007Checker,
+    R008Checker,
+)
+from .config import Config
+from .rules import RuleSeverity, Violation
+
+
+@dataclass(frozen=True, slots=True)
+class BaselineEntry:
+    """Baseline entry for tracking accepted violations."""
+
+    file: str
+    line: int
+    rule_id: str
+    message_hash: str
+
+
+class DtoStrictLinter:
+    """AST-based linter for DTO discipline."""
+
+    def __init__(
+        self, config: Config, baseline: dict[tuple[str, int, str], str] | None = None
+    ):
+        self.config = config
+        self.violations: list[Violation] = []
+        self.baseline = (
+            baseline or {}
+        )  # Key: (file, line, rule_id), Value: message_hash
+
+    def lint_file(self, file_path: Path) -> list[Violation]:
+        """Lint a single Python file."""
+        if not file_path.suffix == ".py":
+            return []
+
+        try:
+            source = file_path.read_text()
+        except Exception:
+            return []
+
+        try:
+            tree = ast.parse(source)
+        except SyntaxError:
+            return []
+
+        violations = []
+
+        # Run all checkers
+        for checker_cls in [
+            R001Checker,
+            R002Checker,
+            R003Checker,
+            R004Checker,
+            R005Checker,
+            R006Checker,
+            R007Checker,
+            R008Checker,
+        ]:
+            checker = checker_cls(file_path, source, self.config)
+            checker.visit(tree)
+            violations.extend(checker.violations)
+
+        # Filter by enabled rules
+        filtered = []
+        for v in violations:
+            if self.config.is_rule_enabled(v.rule_id):
+                filtered.append(v)
+
+        # Apply baseline filtering if present
+        if self.baseline:
+            filtered = self._filter_by_baseline(filtered)
+
+        return filtered
+
+    def lint_path(self, path: Path) -> list[Violation]:
+        """Lint all Python files in a directory or single file."""
+        all_violations = []
+
+        if path.is_file():
+            all_violations.extend(self.lint_file(path))
+        elif path.is_dir():
+            for py_file in path.rglob("*.py"):
+                all_violations.extend(self.lint_file(py_file))
+
+        # Filter by enabled rules
+        filtered = []
+        for v in all_violations:
+            if self.config.is_rule_enabled(v.rule_id):
+                filtered.append(v)
+
+        # Apply baseline filtering if present
+        if self.baseline:
+            filtered = self._filter_by_baseline(filtered)
+
+        # Apply severity overrides
+        for violation in filtered:
+            if violation.rule_id in self.config.severity_overrides:
+                new_severity = self.config.severity_overrides[violation.rule_id].upper()
+                if new_severity in ["HIGH", "MEDIUM", "LOW"]:
+                    violation = Violation(
+                        rule_id=violation.rule_id,
+                        severity=RuleSeverity[new_severity],
+                        file=violation.file,
+                        line=violation.line,
+                        col=violation.col,
+                        message=violation.message,
+                    )
+
+        return filtered
+
+    def _filter_by_baseline(self, violations: list[Violation]) -> list[Violation]:
+        """Filter violations by baseline, removing accepted violations.
+
+        A violation is considered in baseline if file+line+rule_id match.
+        Message hash comparison adds extra confidence but is not strict
+        (allows for minor message wording changes).
+        """
+        new_violations = []
+        for v in violations:
+            key = (v.file, v.line, v.rule_id)
+            if key not in self.baseline:
+                # New violation not in baseline
+                new_violations.append(v)
+        return new_violations
+
+    @staticmethod
+    def _hash_message(message: str) -> str:
+        """Hash violation message for baseline comparison."""
+        return hashlib.sha256(message.encode()).hexdigest()[:16]
+
+    def generate_baseline(self, violations: list[Violation]) -> list[dict]:
+        """Generate baseline JSON from violations."""
+        baseline_data = []
+        for v in violations:
+            baseline_data.append(
+                {
+                    "file": v.file,
+                    "line": v.line,
+                    "rule_id": v.rule_id,
+                    "message_hash": self._hash_message(v.message),
+                }
+            )
+        return baseline_data
+
+    @staticmethod
+    def load_baseline(baseline_path: Path) -> dict[tuple[str, int, str], str]:
+        """Load baseline JSON file."""
+        try:
+            with open(baseline_path, "r") as f:
+                data = json.load(f)
+            baseline = {}
+            for entry in data:
+                key = (entry["file"], entry["line"], entry["rule_id"])
+                baseline[key] = entry["message_hash"]
+            return baseline
+        except Exception:
+            return {}
+
+    def format_violations(
+        self, violations: list[Violation], format_type: str = "text"
+    ) -> str:
+        """Format violations for output."""
+        if format_type == "github":
+            return "\n".join(v.format_github() for v in violations)
+        elif format_type == "json":
+            import json
+
+            return json.dumps(
+                [
+                    {
+                        "rule_id": v.rule_id,
+                        "severity": v.severity.value,
+                        "file": v.file,
+                        "line": v.line,
+                        "col": v.col,
+                        "message": v.message,
+                    }
+                    for v in violations
+                ],
+                indent=2,
+            )
+        else:  # text
+            return "\n".join(v.format_text() for v in violations)
+
+    def get_exit_code(self, violations: list[Violation]) -> int:
+        """Determine exit code based on violation severities."""
+        if not violations:
+            return 0
+
+        has_high = any(v.severity == RuleSeverity.HIGH for v in violations)
+        has_medium = any(v.severity == RuleSeverity.MEDIUM for v in violations)
+
+        if has_high:
+            return 1
+        elif has_medium:
+            return 2
+        else:
+            return 3

strict_module/loc_cap.py

@@ -0,0 +1,228 @@
+"""LOC cap enforcer for Python codebases.
+
+Reads a baseline file (format: path:loc_count per line) and enforces:
+- Hard cap: configurable (default 694 LOC)
+- Soft target: configurable (default 500 LOC)
+- Ratchet semantics: baselined files cannot grow; improvements are allowed.
+"""
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+from .rules import is_loc_test_file
+
+
+@dataclass(frozen=True, slots=True)
+class LocCapConfig:
+    """Configuration for LOC cap checker."""
+
+    hard_cap: int = 694
+    soft_target: int = 500
+    baseline_file: str = ".loc-cap-baseline.txt"
+    exclude_patterns: tuple[str, ...] = ("migrations", "management/commands")
+
+
+def count_lines(file_path: str) -> int:
+    """Count all lines (matches wc -l semantics for baseline compatibility)."""
+    try:
+        with open(file_path, "r", encoding="utf-8") as f:
+            return sum(1 for _ in f)
+    except (OSError, UnicodeDecodeError):
+        return 0
+
+
+def load_baseline(baseline_file: str) -> dict[str, int]:
+    """Load baseline LOC counts from file (with fallback for backward compatibility)."""
+    baseline = {}
+
+    actual_file = None
+    if os.path.isfile(baseline_file):
+        actual_file = baseline_file
+    elif baseline_file == ".loc-cap-baseline.txt":
+        fallback_names = [".strict-module-baseline.txt", ".dto-strict-baseline.txt"]
+        for fallback in fallback_names:
+            if os.path.isfile(fallback):
+                actual_file = fallback
+                break
+
+    if not actual_file:
+        return baseline
+
+    try:
+        with open(actual_file, "r", encoding="utf-8") as f:
+            for line in f:
+                line = line.strip()
+                if not line:
+                    continue
+                parts = line.rsplit(":", 1)
+                if len(parts) == 2:
+                    path, loc_str = parts
+                    try:
+                        baseline[path.strip()] = int(loc_str.strip())
+                    except ValueError:
+                        continue
+    except OSError:
+        pass
+
+    return baseline
+
+
+def find_python_files(
+    root_path: str,
+    exclude_patterns: tuple[str, ...] = ("migrations", "management/commands"),
+) -> dict[str, int]:
+    """Find all Python files under root_path (excluding specified patterns and test files).
+
+    Test files are exempt from LOC cap enforcement. A file is a test file if:
+    - Its basename is conftest.py
+    - Its basename matches test_*.py
+    - It is under a tests/ directory
+    """
+    current_locs = {}
+    root = Path(root_path).resolve()  # Normalize to absolute path
+
+    if not root.exists():
+        return current_locs
+
+    for file_path in root.rglob("*.py"):
+        # Skip excluded patterns
+        file_str = str(file_path)
+        if any(excl in file_str for excl in exclude_patterns):
+            continue
+
+        # Skip test files (conftest.py, test_*.py, or under tests/)
+        if is_loc_test_file(file_path):
+            continue
+
+        loc = count_lines(file_str)
+        current_locs[file_str] = loc
+
+    return current_locs
+
+
+def generate_baseline(
+    root_path: str,
+    exclude_patterns: tuple[str, ...] = ("migrations", "management/commands"),
+    floor: int = 0,
+) -> str:
+    """Generate baseline output (path:loc format, sorted by LOC descending).
+
+    Args:
+        root_path: Root directory to scan
+        exclude_patterns: Patterns to exclude
+        floor: Only include files with LOC >= floor (default 0 includes all)
+
+    Returns:
+        Baseline text (path:loc per line, sorted by LOC desc)
+    """
+    files = find_python_files(root_path, exclude_patterns)
+
+    # Filter by floor and sort by LOC descending, then by path for stability
+    filtered = [(path, loc) for path, loc in files.items() if loc >= floor]
+    sorted_files = sorted(filtered, key=lambda x: (-x[1], x[0]))
+
+    lines = [f"{path}:{loc}" for path, loc in sorted_files]
+    return "\n".join(lines)
+
+
+def run_loc_cap(
+    path: str,
+    hard_cap: int = 694,
+    soft_target: int = 500,
+    baseline_file: str = ".loc-cap-baseline.txt",
+    exclude_patterns: tuple[str, ...] = ("migrations", "management/commands"),
+    generate: bool = False,
+) -> int:
+    """Run LOC cap checker.
+
+    Args:
+        path: Root directory to scan
+        hard_cap: Hard cap limit (default 694)
+        soft_target: Soft target limit (default 500)
+        baseline_file: Path to baseline file (default .loc-cap-baseline.txt)
+        exclude_patterns: Patterns to exclude (default migrations, management/commands)
+        generate: If True, generate baseline instead of checking
+
+    Returns:
+        Exit code (0 pass, 1 fail)
+    """
+    if generate:
+        # Generate mode: compute LOC for all files and output baseline format
+        baseline_output = generate_baseline(path, exclude_patterns, floor=0)
+        print(baseline_output)
+        return 0
+
+    # Check mode: enforce LOC cap
+    baseline = load_baseline(baseline_file)
+    current = find_python_files(path, exclude_patterns)
+
+    soft_warnings = []
+    hard_violations = []
+    improvements = []
+
+    # Check each current file
+    for path_str, loc in current.items():
+        # Soft target warning (soft_target < loc <= hard_cap)
+        if soft_target < loc <= hard_cap:
+            soft_warnings.append(f"  {loc}  {path_str}")
+
+        # Hard cap violations
+        if loc > hard_cap:
+            if path_str not in baseline:
+                hard_violations.append(f"  {loc}  {path_str} (NEW OFFENDER)")
+            elif loc > baseline[path_str]:
+                delta = loc - baseline[path_str]
+                hard_violations.append(
+                    f"  {loc}  {path_str} (was {baseline[path_str]}, grew by {delta})"
+                )
+
+    # Check for improvements in baseline files
+    for baseline_path, baseline_loc in baseline.items():
+        current_loc = current.get(baseline_path)
+
+        if current_loc is None:
+            improvements.append(f"  {baseline_path} (deleted)")
+        elif current_loc < baseline_loc:
+            if current_loc <= hard_cap:
+                delta = baseline_loc - current_loc
+                improvements.append(
+                    f"  {current_loc}  {baseline_path} (was {baseline_loc}, improved by {delta})"
+                )
+
+    # Output warnings for soft target
+    if soft_warnings:
+        print(
+            f"::warning::Files over soft target ({soft_target} LOC) — consider decomposition:"
+        )
+        print("\n".join(soft_warnings))
+        print()
+
+    # Output improvements
+    if improvements:
+        print(f"::notice::Files improved (under {hard_cap} LOC):")
+        print("\n".join(improvements))
+        print()
+
+    # Fail on hard violations
+    if hard_violations:
+        print(
+            f"::error::Files exceed hard cap of {hard_cap} LOC. Decompose by cohesion:"
+        )
+        print("\n".join(hard_violations))
+        print()
+        print(
+            "See memory/feedback_dto_refactor_autonomous_priority.md for cap rationale."
+        )
+        print(
+            "Tests: cap applies. Decompose by class-under-test; lift fixtures to conftest if needed."
+        )
+        print(
+            "Refactor approach: split by COHESION not line count. E.g., bedrock.py → bedrock/{invoke,embed,dtos}.py"
+        )
+        return 1
+
+    print(
+        f"✓ All Python files within {hard_cap} LOC cap (ratchet: baseline allows improvements)"
+    )
+    return 0