pluvy 0.0.1__py3-none-any.whl

pluvy/__init__.py

@@ -0,0 +1 @@
+"""Parser-backed policy checks with concrete findings and immutable configuration."""

pluvy/__main__.py

@@ -0,0 +1,5 @@
+"""Run the installed architecture gate as a module."""
+
+from pluvy.cli import main
+
+raise SystemExit(main())

pluvy/analysis/__init__.py

@@ -0,0 +1 @@
+"""Language analyzer contracts and execution."""

pluvy/analysis/analyzer.py

@@ -0,0 +1,115 @@
+"""Language-independent execution over a parser's concrete context contract."""
+
+import logging
+from dataclasses import dataclass, field
+
+from pluvy.analysis.context import TreeContext
+from pluvy.analysis.contracts import Analyzer, ContextParser
+from pluvy.analysis.scopes import AffectedScopes, ScopeSyntax
+from pluvy.analysis.session import AnalysisSession, SemanticBinding
+from pluvy.diagnostics import AnalysisError, Finding, SyntaxFailure
+from pluvy.plugins.bundles import BundleRegistry
+from pluvy.plugins.profiles import AnalysisProfile
+from pluvy.policy.models import Policy
+from pluvy.semantics.model import SemanticSyntax
+from pluvy.source import LanguageDefinition, Source
+from pluvy.suppressions import CommentSuppressions, DirectiveSyntax, ParsedSuppressions
+
+
+@dataclass(frozen=True, slots=True)
+class TypedAnalyzer(Analyzer):
+    """Compose one context parser and its compatible registered rule objects."""
+
+    name: str = field()
+    definition: LanguageDefinition = field()
+    parser: ContextParser
+    bundles: BundleRegistry
+    profile: AnalysisProfile = field()
+    semantics: SemanticSyntax | None = None
+    api_version: int = 2
+    scopes: ScopeSyntax | None = None
+    directives: DirectiveSyntax | None = None
+
+    def __post_init__(self) -> None:
+        self.validate()
+
+    def validate(self) -> None:
+        """Validate late bundle additions independently of checker enable flags."""
+        self.profile.validate(self.rule_ids)
+        if self.bundles.requires_semantics and self.semantics is None:
+            raise AnalysisError("Required semantic capability is unavailable")
+
+    def needs_semantics(self, policy: Policy) -> bool:
+        """Select evidence work using enabled consumer requirements."""
+        return self.bundles.needs_semantics(policy.checkers.disabled_rules())
+
+    @property
+    def semantic_binding(self) -> SemanticBinding | None:
+        if self.semantics is None:
+            return None
+        return SemanticBinding(self.parser, self.semantics)
+
+    @property
+    def rule_ids(self) -> tuple[str, ...]:
+        return self.bundles.rule_ids
+
+    def analyze(
+        self, source: Source, policy: Policy, session: AnalysisSession | None = None
+    ) -> tuple[Finding, ...]:
+        self.validate()
+        if session is not None and session.policy != policy:
+            raise AnalysisError("Analysis session policy does not match this execution")
+        if source.language != self.definition.language:
+            raise AnalysisError(f"{self.name} cannot analyze {source.language}")
+        if self.profile.optional_unavailable:
+            logging.getLogger(__name__).warning(
+                "Optional analyses unavailable for %r: %s",
+                source.path,
+                ", ".join(self.profile.optional_unavailable),
+            )
+        disabled = policy.checkers.disabled_rules()
+        if all(rule in disabled for rule in self.rule_ids):
+            return ()
+        try:
+            context = self._context(source, policy, session)
+        except SyntaxFailure:
+            return ()
+        return self._findings(context, disabled)
+
+    def _findings(self, context: TreeContext, disabled: frozenset[str]) -> tuple[Finding, ...]:
+        findings = self.bundles.run(context, disabled)
+        suppressions = (
+            CommentSuppressions(self.directives, self.rule_ids).parse(context)
+            if self.directives is not None
+            else ParsedSuppressions()
+        )
+        lines: frozenset[int] | None = None
+        if context.source.changed_lines is not None:
+            if self.scopes is None:
+                raise AnalysisError(f"Affected-scope capability unavailable for {self.name}")
+            scopes = AffectedScopes(self.scopes)
+            lines = scopes.lines(context, suppressions.target_lines(context.source.changed_lines))
+            findings = tuple(finding for finding in findings if scopes.includes(finding, lines))
+        findings = suppressions.apply(findings, lines)
+        return tuple(
+            sorted(
+                (finding for finding in findings if finding.rule not in disabled), key=_finding_key
+            )
+        )
+
+    def _context(
+        self, source: Source, policy: Policy, session: AnalysisSession | None
+    ) -> TreeContext:
+        active = session or AnalysisSession(policy)
+        if session is None and self.semantics is not None and self.needs_semantics(policy):
+            active.prepare(
+                (source,), {source.language: SemanticBinding(self.parser, self.semantics)}
+            )
+        return active.context(source, self.parser)
+
+
+def _finding_key(finding: Finding) -> tuple[str, int, int, str, str]:
+    return finding.path, finding.line, finding.column, finding.rule, finding.message
+
+
+__all__ = ["SyntaxFailure", "TypedAnalyzer"]

pluvy/analysis/context.py

@@ -0,0 +1,51 @@
+"""One tree-backed context and its session-owned semantic evidence."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from tree_sitter import Node, Tree
+
+from pluvy.diagnostics import AnalysisError
+from pluvy.policy.models import Policy
+from pluvy.source import Source
+
+if TYPE_CHECKING:
+    from pluvy.semantics.boundaries import BoundaryEvidence
+    from pluvy.semantics.index import SemanticIndex
+    from pluvy.semantics.model import UsageEvidence
+
+
+@dataclass
+class TreeContext:
+    """Retain an exact source tree and evidence prepared before rule execution."""
+
+    source: Source
+    tree: Tree
+    policy: Policy
+    semantic_index: SemanticIndex | None = None
+    boundary_evidence: BoundaryEvidence | None = None
+    usage_evidence: UsageEvidence | None = None
+
+    @property
+    def root(self) -> Node:
+        return self.tree.root_node
+
+    def require_index(self) -> SemanticIndex:
+        """Reject rule composition without the required semantic capability."""
+        if self.semantic_index is None:
+            raise AnalysisError("Semantic evidence was not prepared for this rule")
+        return self.semantic_index
+
+    def require_boundary(self) -> BoundaryEvidence:
+        """Expose boundary evidence after its session-owned resolution phase."""
+        if self.boundary_evidence is None:
+            raise AnalysisError("Boundary evidence was not prepared for this rule")
+        return self.boundary_evidence
+
+    def require_usage(self) -> UsageEvidence:
+        """Expose prepared project-wide usage evidence to registered usage rules."""
+        if self.usage_evidence is None:
+            raise AnalysisError("Usage evidence was not prepared for this rule")
+        return self.usage_evidence

pluvy/analysis/contracts.py

@@ -0,0 +1,69 @@
+"""Narrow tree-backed execution protocols independent of language identities."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Protocol
+
+from pluvy.analysis.context import TreeContext
+from pluvy.analysis.requirements import RuleRequirements
+from pluvy.diagnostics import Finding
+from pluvy.plugins.profiles import AnalysisProfile
+from pluvy.policy.models import Policy
+from pluvy.source import LanguageDefinition, Source
+
+if TYPE_CHECKING:
+    from pluvy.analysis.session import AnalysisSession, SemanticBinding
+
+
+class Analyzer(Protocol):
+    """Analyze one registered grammar using application-owned requirements."""
+
+    @property
+    def name(self) -> str: ...
+
+    @property
+    def definition(self) -> LanguageDefinition: ...
+
+    @property
+    def profile(self) -> AnalysisProfile: ...
+
+    @property
+    def api_version(self) -> int: ...
+
+    @property
+    def rule_ids(self) -> tuple[str, ...]: ...
+
+    @property
+    def semantic_binding(self) -> SemanticBinding | None: ...
+
+    def needs_semantics(self, policy: Policy) -> bool: ...
+
+    def validate(self) -> None: ...
+
+    def analyze(
+        self, source: Source, policy: Policy, session: AnalysisSession | None = None
+    ) -> tuple[Finding, ...]: ...
+
+
+class RuleBundle(Protocol):
+    """Own diagnostic identities and consume the same concrete syntax context."""
+
+    @property
+    def name(self) -> str: ...
+
+    @property
+    def api_version(self) -> int: ...
+
+    @property
+    def rule_ids(self) -> tuple[str, ...]: ...
+
+    @property
+    def requirements(self) -> RuleRequirements: ...
+
+    def check(self, context: TreeContext) -> tuple[Finding, ...]: ...
+
+
+class ContextParser(Protocol):
+    """Own tree-sitter parsing, recovery and warning emission."""
+
+    def parse(self, source: Source, policy: Policy) -> TreeContext: ...

pluvy/analysis/requirements.py

@@ -0,0 +1,10 @@
+"""Concrete capability requirements owned by rule execution."""
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class RuleRequirements:
+    """Declare whether a rule consumes resolved semantic and boundary evidence."""
+
+    semantic_evidence: bool = False

pluvy/analysis/scopes.py

@@ -0,0 +1,53 @@
+"""Filter diagnostics by affected definitions without narrowing analysis evidence."""
+
+from dataclasses import dataclass
+from typing import Protocol
+
+from tree_sitter import Node
+
+from pluvy.analysis.context import TreeContext
+from pluvy.diagnostics import Finding
+from pluvy.parsing.treesitter import walk
+
+
+class ScopeSyntax(Protocol):
+    """Identify definition spans and the header of a class-like container."""
+
+    def definition(self, node: Node) -> bool: ...
+    def extent(self, node: Node) -> Node: ...
+    def header_end(self, node: Node) -> int | None: ...
+
+
+@dataclass(frozen=True)
+class AffectedScopes:
+    """Expand edited lines using grammar-owned definitions and module statements."""
+
+    syntax: ScopeSyntax
+
+    def lines(
+        self, context: TreeContext, additional: frozenset[int] = frozenset()
+    ) -> frozenset[int]:
+        touched = context.source.changed_lines
+        if touched is None:
+            return frozenset(range(1, context.root.end_point.row + 2))
+        touched = touched | additional
+        selected = set(touched)
+        for node in walk(context.root):
+            if self._affected(node, touched, context.root):
+                extent = self.syntax.extent(node)
+                selected.update(range(extent.start_point.row + 1, extent.end_point.row + 2))
+        return frozenset(selected)
+
+    def includes(self, finding: Finding, lines: frozenset[int]) -> bool:
+        """File placement and ownership remain obligations for every changed file."""
+        return finding.scope == "file" or finding.line in lines
+
+    def _affected(self, node: Node, touched: frozenset[int], root: Node) -> bool:
+        extent = self.syntax.extent(node)
+        start, end = extent.start_point.row + 1, extent.end_point.row + 1
+        header = self.syntax.header_end(node)
+        if header is not None:
+            end = header
+        elif not self.syntax.definition(node) and node.parent != root:
+            return False
+        return any(start <= line <= end for line in touched)

pluvy/analysis/session.py

@@ -0,0 +1,88 @@
+"""Own exact snapshot trees and the single mutable semantic resolution phase."""
+
+from dataclasses import dataclass
+
+from pluvy.analysis.context import TreeContext
+from pluvy.analysis.contracts import ContextParser
+from pluvy.diagnostics import AnalysisError, SyntaxFailure
+from pluvy.policy.models import Policy
+from pluvy.semantics.boundaries import BoundaryEvidence
+from pluvy.semantics.index import SemanticIndex
+from pluvy.semantics.model import SemanticSyntax
+from pluvy.semantics.project import ProjectUsage
+from pluvy.source import Language, Source
+
+
+@dataclass(frozen=True)
+class SemanticBinding:
+    """Bind a concrete parser and syntax capability at composition."""
+
+    parser: ContextParser
+    syntax: SemanticSyntax
+
+
+class AnalysisSession:
+    """Scope parse caches and mutable evidence to one immutable policy execution."""
+
+    def __init__(self, policy: Policy) -> None:
+        self.policy = policy
+        self._contexts: dict[tuple[Source, int], TreeContext] = {}
+        self._project: ProjectUsage | None = None
+        self._rejected: dict[tuple[Source, int], SyntaxFailure] = {}
+
+    def context(self, source: Source, parser: ContextParser) -> TreeContext:
+        """Include parser identity and exact bytes so grammar or content cannot alias."""
+        key = source, id(parser)
+        if key in self._rejected:
+            raise self._rejected[key]
+        if key not in self._contexts:
+            self._contexts[key] = self._parse(source, parser)
+        return self._contexts[key]
+
+    def _parse(self, source: Source, parser: ContextParser) -> TreeContext:
+        try:
+            return parser.parse(source, self.policy)
+        except SyntaxFailure as error:
+            self._rejected[source, id(parser)] = error
+            for warning in error.warnings:
+                warning.emit()
+            raise
+        except AnalysisError:
+            raise
+        except Exception as error:
+            raise AnalysisError(f"Parser failed for {source.path}: {error}") from error
+
+    def prepare(
+        self, sources: tuple[Source, ...], bindings: dict[Language, SemanticBinding]
+    ) -> None:
+        """Resolve the complete snapshot set before exposing evidence to any rule."""
+        try:
+            self._prepare(sources, bindings)
+        except AnalysisError:
+            raise
+        except Exception as error:
+            raise AnalysisError(f"Semantic preparation failed: {error}") from error
+
+    def _prepare(
+        self, sources: tuple[Source, ...], bindings: dict[Language, SemanticBinding]
+    ) -> None:
+        indexes: list[SemanticIndex] = []
+        for source in dict.fromkeys(sources):
+            binding = bindings.get(source.language)
+            if binding is None:
+                continue
+            try:
+                context = self.context(source, binding.parser)
+            except SyntaxFailure:
+                continue
+            if context.semantic_index is None:
+                context.semantic_index = SemanticIndex(context, binding.syntax)
+            indexes.append(context.semantic_index)
+        complete = tuple(index for index in indexes if not index.context.root.has_error)
+        self._project = ProjectUsage(complete)
+        self._project.prepare()
+        for index in indexes:
+            index.context.boundary_evidence = BoundaryEvidence(index)
+        usage = self._project.evidence()
+        for index in indexes:
+            index.context.usage_evidence = usage

pluvy/architecture/__init__.py

@@ -0,0 +1,17 @@
+"""Architecture contracts and dependency checks."""
+
+from typing import TYPE_CHECKING
+
+__all__ = ["ArchitectureRule"]
+
+if TYPE_CHECKING:
+    from pluvy.architecture.rules import ArchitectureRule
+
+
+def __getattr__(name: str) -> type["ArchitectureRule"]:
+    """Load the public rule class without coupling option imports to execution."""
+    if name != "ArchitectureRule":
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    from pluvy.architecture.rules import ArchitectureRule
+
+    return ArchitectureRule

pluvy/architecture/design.py

@@ -0,0 +1,68 @@
+"""Mechanical evidence for class-based extension ownership and polymorphic dispatch."""
+
+from dataclasses import dataclass
+
+from tree_sitter import Node
+
+from pluvy.analysis.context import TreeContext
+from pluvy.analysis.requirements import RuleRequirements
+from pluvy.architecture.design_contracts import DesignSyntax
+from pluvy.architecture.options import DISPATCH, OBJECT_MODEL
+from pluvy.diagnostics import Finding
+from pluvy.parsing.treesitter import spelling, walk
+from pluvy.policy.paths import matches
+from pluvy.source import Source
+
+
+@dataclass(frozen=True)
+class ObjectDesignRule:
+    """Reject identity switches and public procedural entry points in configured modules."""
+
+    syntax: DesignSyntax
+    name: str = "builtin.object_design"
+    api_version: int = 2
+    requirements: RuleRequirements = RuleRequirements()
+    rule_ids: tuple[str, ...] = (DISPATCH.name, OBJECT_MODEL.name)
+
+    def check(self, context: TreeContext) -> tuple[Finding, ...]:
+        findings: list[Finding] = []
+        options = context.policy.checkers
+        for node in walk(context.root):
+            if options.architecture_dispatch.enabled and self.syntax.dispatch(node, context.source):
+                findings.append(
+                    self._finding(
+                        context.source,
+                        node,
+                        DISPATCH.name,
+                        "Use a registered interface implementation instead of identity dispatch",
+                    )
+                )
+        if options.architecture_object_model.enabled and matches(
+            context.source.path, options.architecture_object_model.paths
+        ):
+            findings.extend(self._procedural(context))
+        return tuple(findings)
+
+    def _procedural(self, context: TreeContext) -> tuple[Finding, ...]:
+        findings: list[Finding] = []
+        for function in self.syntax.module_functions(context.root):
+            name = self.syntax.function_name(function)
+            if name is not None and not spelling(name, context.source).startswith("_"):
+                findings.append(
+                    self._finding(
+                        context.source,
+                        function,
+                        OBJECT_MODEL.name,
+                        "Own extension behavior in a class implementing a narrow interface",
+                    )
+                )
+        return tuple(findings)
+
+    def _finding(self, source: Source, node: Node, rule: str, message: str) -> Finding:
+        return Finding(
+            path=source.path,
+            line=node.start_point.row + 1,
+            column=node.start_point.column + 1,
+            rule=rule,
+            message=message,
+        )

pluvy/architecture/design_contracts.py

@@ -0,0 +1,15 @@
+"""Consumer-owned syntax evidence for architectural object-design checks."""
+
+from typing import Protocol
+
+from tree_sitter import Node
+
+from pluvy.source import Source
+
+
+class DesignSyntax(Protocol):
+    """Interpret selectors and public module functions without evaluating policy."""
+
+    def dispatch(self, node: Node, source: Source) -> bool: ...
+    def module_functions(self, root: Node) -> tuple[Node, ...]: ...
+    def function_name(self, node: Node) -> Node | None: ...

pluvy/architecture/imports.py

@@ -0,0 +1,27 @@
+"""Canonical extraction contracts and module identity resolution."""
+
+from typing import Protocol
+
+from pluvy.analysis.context import TreeContext
+from pluvy.architecture.models import Import
+from pluvy.source import Source
+
+
+class ImportResolver(Protocol):
+    """Map a literal dependency to the names its language considers equivalent."""
+
+    def names(self, dependency: Import, source: Source) -> tuple[str, ...]: ...
+
+
+class LiteralImportResolver(ImportResolver):
+    """Python and Go import specifiers are already module identities."""
+
+    def names(self, dependency: Import, source: Source) -> tuple[str, ...]:
+        """Keep the resolver signature; literal identities need no source path."""
+        return (dependency.module,)
+
+
+class ImportExtractor(Protocol):
+    """Extract dependency evidence from one concrete parser context."""
+
+    def extract(self, context: TreeContext) -> tuple[Import, ...]: ...

pluvy/architecture/models.py

@@ -0,0 +1,12 @@
+"""Syntactically visible dependency contracts."""
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Import:
+    """A visible dependency at its source location."""
+
+    module: str
+    line: int
+    column: int

pluvy/architecture/options.py

@@ -0,0 +1,109 @@
+"""Architecture checker contracts, options and registrations."""
+
+from pydantic import Field
+
+from pluvy.policy.contracts import (
+    CheckerConfiguration,
+    CheckerDefinition,
+    CheckerOptions,
+    CheckerState,
+    Contract,
+)
+
+
+class Boundary(Contract):
+    """Forbid literal or normalized imports from matching source paths."""
+
+    name: str = Field(min_length=1)
+    sources: tuple[str, ...] = Field(min_length=1)
+    forbidden_imports: tuple[str, ...] = Field(min_length=1)
+
+
+class Owner(Contract):
+    """Assign a named responsibility to repository-relative paths."""
+
+    name: str = Field(min_length=1)
+    paths: tuple[str, ...] = Field(min_length=1)
+
+
+class SourcePlacement(Contract):
+    """Keep explicitly selected source modules within their owning locations."""
+
+    name: str = Field(min_length=1)
+    paths: tuple[str, ...] = Field(min_length=1)
+    allowed_paths: tuple[str, ...] = Field(min_length=1)
+
+
+class StructureOptions(CheckerOptions):
+    """Configure source placement independently of ownership and dependencies."""
+
+    placements: tuple[SourcePlacement, ...] = ()
+
+
+class OwnershipOptions(CheckerOptions):
+    """Configure responsibility matching only for architecture.owner."""
+
+    owners: tuple[Owner, ...] = ()
+
+
+class ImportOptions(CheckerOptions):
+    """Configure forbidden dependencies only for architecture.import."""
+
+    boundaries: tuple[Boundary, ...] = ()
+
+
+class ObjectModelOptions(CheckerOptions):
+    """Select modules whose public extension behavior must belong to objects."""
+
+    paths: tuple[str, ...] = ()
+
+
+OWNERSHIP = CheckerDefinition("architecture.owner")
+
+STRUCTURE = CheckerDefinition("architecture.structure")
+
+IMPORTS = CheckerDefinition("architecture.import")
+
+DISPATCH = CheckerDefinition("architecture.dispatch")
+
+OBJECT_MODEL = CheckerDefinition("architecture.object_model")
+
+
+class ArchitectureCheckers(CheckerConfiguration):
+    """Register owned checker fields and project their execution switches."""
+
+    architecture_owner: OwnershipOptions = Field(
+        default=OwnershipOptions(),
+        validation_alias=OWNERSHIP.name,
+        serialization_alias=OWNERSHIP.name,
+    )
+    architecture_structure: StructureOptions = Field(
+        default=StructureOptions(),
+        validation_alias=STRUCTURE.name,
+        serialization_alias=STRUCTURE.name,
+    )
+    architecture_import: ImportOptions = Field(
+        default=ImportOptions(),
+        validation_alias=IMPORTS.name,
+        serialization_alias=IMPORTS.name,
+    )
+    architecture_dispatch: CheckerOptions = Field(
+        default=CheckerOptions(),
+        validation_alias=DISPATCH.name,
+        serialization_alias=DISPATCH.name,
+    )
+    architecture_object_model: ObjectModelOptions = Field(
+        default=ObjectModelOptions(),
+        validation_alias=OBJECT_MODEL.name,
+        serialization_alias=OBJECT_MODEL.name,
+    )
+
+    def checker_states(self) -> tuple[CheckerState, ...]:
+        return (
+            *super().checker_states(),
+            OWNERSHIP.configure(self.architecture_owner.enabled),
+            STRUCTURE.configure(self.architecture_structure.enabled),
+            IMPORTS.configure(self.architecture_import.enabled),
+            DISPATCH.configure(self.architecture_dispatch.enabled),
+            OBJECT_MODEL.configure(self.architecture_object_model.enabled),
+        )