modwire 1.0.0__py3-none-any.whl

modwire/__init__.py

@@ -0,0 +1,15 @@
+from .extraction import CodeMap, extract_code
+from .extractors.loader import normalize_source_id, supported_languages
+from .graph import DependencyGraph, Edge, Node, build_dependency_graph
+
+
+__all__ = [
+    "CodeMap",
+    "DependencyGraph",
+    "Edge",
+    "Node",
+    "build_dependency_graph",
+    "extract_code",
+    "normalize_source_id",
+    "supported_languages",
+]

modwire/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '1.0.0'
+__version_tuple__ = version_tuple = (1, 0, 0)
+
+__commit_id__ = commit_id = None

modwire/architecture/__init__.py

@@ -0,0 +1,10 @@
+from .analyzers import supported_analyzers
+from .policy import ArchitecturePolicyEvaluator
+from .violations import EdgeRuleViolation, FlowViolation
+
+__all__ = [
+    "ArchitecturePolicyEvaluator",
+    "EdgeRuleViolation",
+    "FlowViolation",
+    "supported_analyzers",
+]

modwire/architecture/analyzers.py

@@ -0,0 +1,140 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Callable
+
+from .violations import FlowViolation
+
+
+@dataclass(frozen=True)
+class FlowAnalyzer:
+    name: str
+    title: str
+    run: Callable
+
+
+def supported_analyzers() -> tuple[str, ...]:
+    return tuple(_ANALYZERS)
+
+
+def analyzer_title(name: str) -> str:
+    return _ANALYZERS[name].title
+
+
+def run_analyzer(name: str, graph, tags, config):
+    analyzer = _ANALYZERS[name]
+    return analyzer.run(analyzer.name, graph, tags, config)
+
+
+def _roots(graph):
+    incoming = {node_id: 0 for node_id in graph.node_ids()}
+    for edge in graph.edges:
+        if edge.to_id in incoming:
+            incoming[edge.to_id] += 1
+    roots = [node_id for node_id, count in incoming.items() if count == 0]
+    return tuple(sorted(roots or incoming))
+
+
+def _dedupe(violations):
+    seen = set()
+    unique = []
+    for violation in violations:
+        key = (violation.violation_type, violation.path, violation.violation_index)
+        if key not in seen:
+            seen.add(key)
+            unique.append(violation)
+    return unique
+
+
+def _flow(name, path, index, message):
+    return FlowViolation(name, tuple(path), index, f"analyzer:{name}", message)
+
+
+def _backward_flow(name, graph, tags, config):
+    layers = config.rules.flow.layers
+
+    def layer(node):
+        return next((i for i, layer_name in enumerate(layers) if layer_name in tags.get(node, set())), None)
+
+    violations = []
+    seen = set()
+
+    def walk(node, current_layer, path):
+        if (node, current_layer) in seen:
+            return
+        seen.add((node, current_layer))
+        for edge in graph.outgoing(node):
+            next_layer = layer(edge.to_id)
+            if current_layer is not None and next_layer is not None and next_layer < current_layer:
+                violations.append(_flow(name, [*path, edge.to_id], len(path), "layer order violated"))
+                continue
+            walk(edge.to_id, current_layer if next_layer is None else next_layer, [*path, edge.to_id])
+
+    for root in _roots(graph):
+        walk(root, layer(root), [root])
+    return _dedupe(violations)
+
+
+def _no_reentry(name, graph, tags, config):
+    module_tag = config.rules.flow.module_tag
+    violations = []
+    seen = set()
+
+    def walk(node, state, path):
+        if (node, state) in seen:
+            return
+        seen.add((node, state))
+        for edge in graph.outgoing(node):
+            inside = module_tag in tags.get(edge.to_id, set())
+            next_state = 1 if state == 0 and inside else 2 if state == 1 and not inside else state
+            if state == 2 and inside:
+                violations.append(_flow(name, [*path, edge.to_id], len(path), "module layer re-entered after exit"))
+                continue
+            walk(edge.to_id, next_state, [*path, edge.to_id])
+
+    for root in _roots(graph):
+        walk(root, 1 if module_tag in tags.get(root, set()) else 0, [root])
+    return _dedupe(violations)
+
+
+def _no_cycles(name, graph, tags, config):
+    scoped = {node for node, node_tags in tags.items() if config.rules.flow.module_tag in node_tags}
+    seen, stack, index, emitted, violations = set(), [], {}, set(), []
+
+    def canonical(cycle):
+        ring = list(cycle[:-1])
+        first = min(tuple(ring[i:] + ring[:i]) for i in range(len(ring)))
+        return (*first, first[0])
+
+    def dfs(node):
+        seen.add(node)
+        index[node] = len(stack)
+        stack.append(node)
+        for edge in graph.outgoing(node):
+            if edge.to_id not in scoped:
+                continue
+            if edge.to_id in index:
+                cycle = tuple([*stack[index[edge.to_id] :], edge.to_id])
+                key = canonical(cycle)
+                if key not in emitted:
+                    emitted.add(key)
+                    violations.append(_flow(name, cycle, len(cycle) - 1, "module cycle detected"))
+            elif edge.to_id not in seen:
+                dfs(edge.to_id)
+        stack.pop()
+        index.pop(node, None)
+
+    for node in sorted(scoped):
+        if node not in seen:
+            dfs(node)
+    return violations
+
+
+_ANALYZERS = {
+    analyzer.name: analyzer
+    for analyzer in (
+        FlowAnalyzer("backward-flow", "Backward Flow Violations", _backward_flow),
+        FlowAnalyzer("no-reentry", "No Re-Entry Violations", _no_reentry),
+        FlowAnalyzer("no-cycles", "Cycle Violations", _no_cycles),
+    )
+}

modwire/architecture/matching.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+import re
+from functools import cache
+
+from modwire.extractors.loader import normalize_source_id
+
+
+def match_node(node_id, pattern, config, exclusions, *, scope=True, exclude=()):
+    language = config.language
+    path = normalize_source_id(language, node_id)
+    for ignored in (*exclusions.get(pattern, ()), *exclude):
+        for normalized_ignored in _normalized_patterns(language, ignored, config):
+            if _regex(normalized_ignored, True).match(path):
+                return None
+    for normalized in _normalized_patterns(language, pattern, config):
+        match = _regex(normalized, scope).match(path)
+        if match is not None:
+            return match.group(1), "*" in normalized or "?" in normalized
+    return None
+
+
+def _normalized_patterns(language, pattern, config):
+    normalized = normalize_source_id(language, pattern).strip("/")
+    architecture_root = normalize_source_id(
+        language,
+        getattr(config, "architecture_root", None) or "",
+    ).strip("/")
+    if not architecture_root:
+        return (normalized,)
+
+    root_anchor = architecture_root.split("/", 1)[0]
+    is_full_path = normalized == architecture_root or normalized.startswith(
+        (f"{architecture_root}/", f"{root_anchor}/")
+    )
+    if is_full_path:
+        return (normalized,)
+    return (f"{architecture_root}/{normalized}",)
+
+
+@cache
+def _regex(pattern: str, scope: bool):
+    parts = ["^("]
+    i = 0
+    while i < len(pattern):
+        char = pattern[i]
+        if char == "*":
+            is_deep = i + 1 < len(pattern) and pattern[i + 1] == "*"
+            parts.append("(.*)" if is_deep else "([^/]*)")
+            i += 2 if is_deep else 1
+        elif char == "?":
+            parts.append("([^/])")
+            i += 1
+        else:
+            parts.append(re.escape(char))
+            i += 1
+    parts.append(")(?:/.*)?" if scope else ")")
+    return re.compile("".join(parts) + "$")

modwire/architecture/policy.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+from modwire.graph import DependencyGraph
+
+from .analyzers import run_analyzer
+from .matching import match_node
+from .violations import EdgeRuleViolation, FlowViolation
+
+
+class ArchitecturePolicyEvaluator:
+    def evaluate(self, graph: DependencyGraph, config):
+        tags = _tags(graph.node_ids(), config)
+        violations: list[EdgeRuleViolation | FlowViolation] = _edge_violations(graph, config)
+        for analyzer_name in config.rules.flow.analyzers:
+            violations.extend(run_analyzer(analyzer_name, graph, tags, config))
+        return violations
+
+
+def _edge_violations(graph, config):
+    violations = []
+    exclusions = {rule.match: rule.excluded_patterns for rule in config.rules.tags}
+    for edge in graph.edges:
+        denied: tuple[str, str] | None = None
+        for rule in config.rules.boundaries:
+            source = match_node(edge.from_id, rule.source, config, exclusions)
+            if source is None:
+                continue
+            for target in rule.disallow:
+                target_match = match_node(edge.to_id, target, config, exclusions)
+                same_owner = (
+                    rule.allow_same_match
+                    and source[1]
+                    and target_match is not None
+                    and target_match[1]
+                    and source[0] == target_match[0]
+                )
+                if target_match is not None and not same_owner:
+                    denied = (rule.source, target)
+            for target in rule.allow:
+                if match_node(edge.to_id, target, config, exclusions, scope=target in exclusions):
+                    denied = None
+        if denied:
+            violations.append(
+                EdgeRuleViolation(
+                    edge.from_id,
+                    edge.to_id,
+                    denied[0],
+                    denied[1],
+                    f"boundary:{denied[0]}->{denied[1]}:deny",
+                )
+            )
+    return violations
+
+
+def _tags(node_ids, config):
+    return {
+        node_id: {
+            rule.name
+            for rule in config.rules.tags
+            if match_node(node_id, rule.match, config, {}, exclude=rule.excluded_patterns)
+        }
+        for node_id in node_ids
+    }

modwire/architecture/render.py

@@ -0,0 +1,98 @@
+from __future__ import annotations
+
+import json
+from dataclasses import asdict
+
+from .analyzers import analyzer_title
+from .violations import EDGE_RULE_TYPE, EdgeRuleViolation, FlowViolation
+
+GROUP_TITLES = {
+    EDGE_RULE_TYPE: "Edge Rule Violations",
+}
+
+
+def summary(report) -> str:
+    return "\n".join(
+        (
+            "Boundaries Summary:",
+            f"- Paths found in scope: {report.files_found}",
+            f"- Paths excluded by rules: {report.files_excluded}",
+            f"- Files checked: {report.files_checked}",
+        )
+    )
+
+
+def violations(report) -> str:
+    groups: dict[str, list[str]] = {}
+    for violation in report.violations:
+        violation_type = _type(violation)
+        title = GROUP_TITLES.get(violation_type)
+        if title is None:
+            title = analyzer_title(violation_type)
+        groups.setdefault(title, []).append(compact(violation))
+    return "\n".join(
+        line
+        for title, entries in groups.items()
+        for line in (f"{title}:", *(f"- {entry}" for entry in entries))
+    )
+
+
+def compact(violation: EdgeRuleViolation | FlowViolation) -> str:
+    if isinstance(violation, EdgeRuleViolation):
+        return (
+            f"{violation.source_id} -> [{violation.target_id}] "
+            f"blocked by {violation.source_pattern} -> {violation.target_pattern}"
+        )
+    path = list(violation.path)
+    path[violation.violation_index] = f"[{path[violation.violation_index]}]"
+    return f"{' -> '.join(path)}  {violation.violation_type}"
+
+
+def render_json(report) -> str:
+    return json.dumps(
+        {
+            "project_root": str(report.project_root),
+            "config_path": str(report.config_path),
+            "config_format": report.config_format,
+            "language": report.language,
+            "runtime_command": report.runtime_command,
+            "files_found": report.files_found,
+            "files_excluded": report.files_excluded,
+            "files_checked": report.files_checked,
+            "violations": [_json_violation(v) for v in report.violations],
+        },
+        indent=2,
+        sort_keys=True,
+    )
+
+
+def render_dot(report) -> str:
+    edges = dict.fromkeys(edge for violation in report.violations for edge in _edges(violation))
+    return "\n".join(
+        ("digraph architecture_violations {", "  rankdir=LR;")
+        + tuple(f'  "{source}" -> "{target}";' for source, target in edges)
+        + ("}",)
+    )
+
+
+def _json_violation(violation):
+    payload = asdict(violation)
+    payload["type"] = _type(violation)
+    payload["path"] = (
+        [violation.source_id, violation.target_id]
+        if isinstance(violation, EdgeRuleViolation)
+        else list(violation.path)
+    )
+    if isinstance(violation, EdgeRuleViolation):
+        payload["violation_index"] = 1
+    return payload
+
+
+def _edges(violation):
+    if isinstance(violation, EdgeRuleViolation):
+        return ((violation.source_id, violation.target_id),)
+    return tuple(zip(violation.path, violation.path[1:], strict=False))
+
+
+def _type(violation):
+    return EDGE_RULE_TYPE if isinstance(violation, EdgeRuleViolation) else violation.violation_type

modwire/architecture/violations.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+EDGE_RULE_TYPE = "edge-rule"
+
+
+@dataclass(frozen=True)
+class EdgeRuleViolation:
+    source_id: str
+    target_id: str
+    source_pattern: str
+    target_pattern: str
+    rule_name: str
+
+
+@dataclass(frozen=True)
+class FlowViolation:
+    violation_type: str
+    path: tuple[str, ...]
+    violation_index: int
+    rule_name: str
+    message: str

modwire/definitions.py

@@ -0,0 +1,101 @@
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+
+ImportCrossingType = Literal["module", "symbol"]
+SourceVisibility = Literal["public", "protected", "private"]
+SourceSignatureKind = Literal["call", "construct", "index"]
+
+
+class SourceImport(BaseModel):
+    path: str
+    is_relative: bool
+    normalized_path: str
+    imported_name: str
+    is_aliased: bool
+    crossing_type: ImportCrossingType
+    file_barrier_crossed: bool
+    statement_id: int
+    join_key: str
+    uses_joined_import: bool
+
+
+class SourceFunction(BaseModel):
+    name: str
+    visibility: SourceVisibility
+    visibility_intent: SourceVisibility
+    line_count: int
+    declared_args: int
+    optional_args: int
+
+
+class SourceClassMethod(BaseModel):
+    name: str
+    visibility: SourceVisibility
+    visibility_intent: SourceVisibility
+    line_count: int
+    declared_args: int
+    optional_args: int
+
+
+class SourceClassProperty(BaseModel):
+    name: str
+    is_optional: bool
+
+
+class SourceSignature(BaseModel):
+    kind: SourceSignatureKind
+    line_count: int
+    declared_args: int
+    optional_args: int
+
+
+class SourceClass(BaseModel):
+    name: str
+    visibility: SourceVisibility
+    visibility_intent: SourceVisibility
+    methods: list[SourceClassMethod]
+    properties: list[SourceClassProperty]
+    line_count: int
+
+
+class SourceInterface(BaseModel):
+    name: str
+    visibility: SourceVisibility
+    visibility_intent: SourceVisibility
+    methods: list[SourceClassMethod]
+    properties: list[SourceClassProperty]
+    signatures: list[SourceSignature]
+    line_count: int
+
+
+class SourceType(BaseModel):
+    name: str
+    visibility: SourceVisibility
+    visibility_intent: SourceVisibility
+    properties: list[SourceClassProperty]
+    signatures: list[SourceSignature]
+    line_count: int
+
+
+class SourceAbstractClass(BaseModel):
+    name: str
+    visibility: SourceVisibility
+    visibility_intent: SourceVisibility
+    abstract_methods: list[SourceClassMethod]
+    concrete_methods: list[SourceClassMethod]
+    properties: list[SourceClassProperty]
+    line_count: int
+
+
+class SourceFile(BaseModel):
+    imports: list[SourceImport]
+    classes: list[SourceClass]
+    interfaces: list[SourceInterface] = Field(default_factory=list)
+    types: list[SourceType] = Field(default_factory=list)
+    abstract_classes: list[SourceAbstractClass] = Field(default_factory=list)
+    functions: list[SourceFunction]
+    line_count: int
+    code_line_count: int
+    public_symbol_count: int

modwire/extraction.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from .definitions import SourceFile
+from .extractors import load_extractor
+from .graph import DependencyGraph, build_dependency_graph
+
+
+@dataclass(frozen=True)
+class ExtractionSummary:
+    files_found: int
+    files_checked: int
+    files_excluded: int
+
+
+@dataclass(frozen=True)
+class ExtractionResult:
+    files: dict[str, SourceFile]
+    summary: ExtractionSummary
+
+
+@dataclass(frozen=True)
+class CodeMap:
+    graph: DependencyGraph
+    extraction_result: ExtractionResult
+    runtime_command: str
+
+
+def extract_code(
+    language: str,
+    sources_root: Path,
+    exclusions: tuple[str, ...],
+) -> CodeMap:
+    """ Extracts the code from the given source root and builds a dependency graph.
+
+    Args:
+        language (str): programming language name, supprted are: "python", "javascript", "typescript"
+        sources_root (Path): where to look for source files, usually src or lib folder in your project
+        exclusions (tuple[str, ...]): glob patterns to exclude files from extraction, e.g. ("**/node_modules/**", "**/dist/**"), relative to sources_root (just like gitignore patterns)
+    Returns:
+        CodeMap: graph of the codebase and extraction result, including summary and runtime command used for extraction
+    """
+    assert sources_root.is_dir(), f"Project root {sources_root} is not a directory"
+
+    extractor = load_extractor(language)
+    extraction = extractor.extract_files(sources_root, exclusions)
+    extracted_files = extraction.files
+    dependency_graph = build_dependency_graph(extracted_files)
+    
+    extraction_result = ExtractionResult(
+        files=extracted_files,
+        summary=ExtractionSummary(
+            files_found=extraction.files_found,
+            files_checked=len(extracted_files),
+            files_excluded=extraction.files_excluded,
+        ),
+    )
+
+    return CodeMap(
+        graph=dependency_graph,
+        extraction_result=extraction_result,
+        runtime_command=extractor.command,
+    )
+
+
+__all__ = [
+    "CodeMap",
+    "ExtractionResult",
+    "ExtractionSummary",
+    "extract_code",
+]

modwire/extractors/__init__.py

@@ -0,0 +1,5 @@
+from .base import SourceExtractor
+from .loader import load_extractor
+
+
+__all__ = ["SourceExtractor", "load_extractor"]