bubbles-lint 0.1.0__py3-none-any.whl

bubbles_lint/__init__.py

@@ -0,0 +1,3 @@
+"""Bubbles Lint keeps Python modules small, composable, and inspectable."""
+
+__version__ = "0.1.0"

bubbles_lint/cli.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from bubbles_lint.config import load_config
+from bubbles_lint.report import format_human, format_json
+from bubbles_lint.scanner import scan_path
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    if args.command == "scan":
+        target = Path(args.path)
+        config = load_config(target)
+        result = scan_path(target, config=config)
+        output = format_json(result) if args.json else format_human(result)
+        print(output)
+        return 1 if result.has_findings else 0
+
+    parser.print_help()
+    return 2
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="bubbles-lint",
+        description="Architectural linting for small, composable Python code.",
+    )
+    subcommands = parser.add_subparsers(dest="command")
+
+    scan = subcommands.add_parser("scan", help="Scan Python files for architecture findings.")
+    scan.add_argument("path", nargs="?", default=".", help="File or directory to scan.")
+    scan.add_argument("--json", action="store_true", help="Emit machine-readable JSON output.")
+
+    return parser
+
+
+if __name__ == "__main__":
+    sys.exit(main())

bubbles_lint/config.py

@@ -0,0 +1,79 @@
+from __future__ import annotations
+
+import tomllib
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+
+DEFAULT_EXCLUDES = frozenset({
+    ".git",
+    ".venv",
+    "__pycache__",
+    "build",
+    "dist",
+    "venv",
+})
+
+
+@dataclass(frozen=True)
+class Config:
+    max_file_lines: int = 500
+    max_function_lines: int = 50
+    max_class_methods: int = 10
+    max_function_params: int = 5
+    max_imports_per_module: int = 20
+    max_nesting_depth: int = 4
+    max_side_effect_kinds: int = 3
+    max_ai_module_lines: int = 200
+    max_ai_class_dependencies: int = 8
+    allow_private_imports: bool = False
+    excludes: frozenset[str] = DEFAULT_EXCLUDES
+
+
+def load_config(start: Path) -> Config:
+    pyproject = find_pyproject(start)
+    if pyproject is None:
+        return Config()
+
+    try:
+        data = tomllib.loads(pyproject.read_text(encoding="utf-8"))
+    except (OSError, tomllib.TOMLDecodeError):
+        return Config()
+
+    tool_config = data.get("tool", {})
+    if not isinstance(tool_config, dict):
+        return Config()
+
+    values = tool_config.get("bubbles-lint", tool_config.get("bubbles", {}))
+    if not isinstance(values, dict):
+        return Config()
+
+    return build_config(values)
+
+
+def find_pyproject(start: Path) -> Path | None:
+    current = start.resolve()
+    if current.is_file():
+        current = current.parent
+
+    for directory in (current, *current.parents):
+        pyproject = directory / "pyproject.toml"
+        if pyproject.exists():
+            return pyproject
+    return None
+
+
+def build_config(values: dict[str, Any]) -> Config:
+    defaults = Config()
+    kwargs: dict[str, Any] = {}
+    for field_name in defaults.__dataclass_fields__:
+        if field_name not in values:
+            continue
+        value = values[field_name]
+        if field_name == "excludes":
+            if isinstance(value, list) and all(isinstance(item, str) for item in value):
+                kwargs[field_name] = DEFAULT_EXCLUDES | frozenset(value)
+            continue
+        kwargs[field_name] = value
+    return Config(**kwargs)

bubbles_lint/models.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from pathlib import Path
+from typing import Protocol
+
+from bubbles_lint.config import Config
+
+
+class Severity(str, Enum):
+    INFO = "info"
+    WARNING = "warning"
+    ERROR = "error"
+
+
+@dataclass(frozen=True)
+class Finding:
+    rule: str
+    severity: Severity
+    path: Path
+    line: int
+    message: str
+    suggestion: str
+
+    def to_json(self) -> dict[str, object]:
+        return {
+            "rule": self.rule,
+            "severity": self.severity.value,
+            "path": self.path.as_posix(),
+            "line": self.line,
+            "message": self.message,
+            "suggestion": self.suggestion,
+        }
+
+
+@dataclass(frozen=True)
+class ModuleContext:
+    path: Path
+    root: Path
+    source: str
+    tree: object
+    line_count: int
+    config: Config
+
+    @property
+    def relative_path(self) -> Path:
+        try:
+            return self.path.relative_to(self.root)
+        except ValueError:
+            return self.path
+
+
+class Rule(Protocol):
+    id: str
+    title: str
+
+    def check(self, context: ModuleContext) -> list[Finding]:
+        ...
+
+
+@dataclass
+class ScanResult:
+    findings: list[Finding] = field(default_factory=list)
+    files_scanned: int = 0
+
+    @property
+    def has_errors(self) -> bool:
+        return any(finding.severity is Severity.ERROR for finding in self.findings)
+
+    @property
+    def has_findings(self) -> bool:
+        return bool(self.findings)
+
+    def extend(self, findings: list[Finding]) -> None:
+        self.findings.extend(findings)

bubbles_lint/report.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+import json
+from collections import defaultdict
+from types import MappingProxyType
+
+from bubbles_lint.models import Finding, ScanResult
+
+
+RULE_TITLES = MappingProxyType({
+    "ai-smells": "AI Smells",
+    "bubble-boundary": "Bubble Boundary",
+    "bubble-burst": "Bubble Burst",
+    "bubble-leak": "Bubble Leak",
+    "parser": "Parser",
+})
+
+
+def format_json(result: ScanResult) -> str:
+    return json.dumps(
+        {
+            "findings": [finding.to_json() for finding in result.findings],
+            "files_scanned": result.files_scanned,
+        },
+        indent=2,
+    )
+
+
+def format_human(result: ScanResult) -> str:
+    if not result.findings:
+        return f"No bubbles burst. Scanned {result.files_scanned} Python file(s)."
+
+    grouped: dict[str, list[Finding]] = defaultdict(list)
+    for finding in result.findings:
+        grouped[_family(finding.rule)].append(finding)
+
+    chunks: list[str] = []
+    for family in sorted(grouped):
+        chunks.append(f"Bubble: {RULE_TITLES.get(family, family)}")
+        for finding in grouped[family]:
+            chunks.append("")
+            chunks.append(f"{finding.path}:{finding.line}")
+            chunks.append(f"{finding.severity.value}: {finding.message}")
+            chunks.append("")
+            chunks.append("Suggestion:")
+            chunks.append(finding.suggestion)
+
+    return "\n".join(chunks)
+
+
+def _family(rule: str) -> str:
+    return rule.split("/", 1)[0]

bubbles_lint/rules/__init__.py

@@ -0,0 +1 @@
+"""Architecture rules shipped with Bubbles Lint."""

bubbles_lint/rules/ai_smells.py

@@ -0,0 +1,113 @@
+from __future__ import annotations
+
+import ast
+
+from bubbles_lint.models import Finding, ModuleContext, Severity
+from bubbles_lint.rules.imports import imports
+
+
+SMELLY_MODULES = frozenset({"utils.py", "helpers.py", "manager.py", "service.py"})
+SMELLY_CLASS_SUFFIXES = ("Manager", "Service", "Handler")
+BRANCH_NODES = (ast.If, ast.For, ast.AsyncFor, ast.While, ast.With, ast.AsyncWith, ast.Try, ast.Match)
+
+
+class AiSmellRule:
+    id = "ai-smells"
+    title = "AI Smells"
+
+    def check(self, context: ModuleContext) -> list[Finding]:
+        findings: list[Finding] = []
+
+        generic_finding = _generic_module_finding(context)
+        if generic_finding:
+            findings.append(generic_finding)
+
+        for node in ast.walk(context.tree):
+            if isinstance(node, ast.ClassDef) and node.name.endswith(SMELLY_CLASS_SUFFIXES):
+                class_finding = _class_smell_finding(context, node)
+                if class_finding:
+                    findings.append(class_finding)
+
+        max_depth, line = _max_nesting(context.tree)
+        if max_depth > context.config.max_nesting_depth:
+            findings.append(Finding(
+                rule="ai-smells/deep-nesting",
+                severity=Severity.WARNING,
+                path=context.relative_path,
+                line=line,
+                message=(
+                    f"Code nesting depth is {max_depth}; recommended maximum "
+                    f"is {context.config.max_nesting_depth}."
+                ),
+                suggestion="Use guard clauses, smaller functions, or a simple pipeline to flatten control flow.",
+            ))
+
+        return findings
+
+
+def _generic_module_finding(context: ModuleContext) -> Finding | None:
+    if context.path.name not in SMELLY_MODULES:
+        return None
+    module_imports = imports(context.tree)
+    is_large = context.line_count > context.config.max_ai_module_lines
+    has_many_imports = len(module_imports) > context.config.max_imports_per_module
+    if not is_large and not has_many_imports:
+        return None
+    return Finding(
+        rule="ai-smells/generic-module",
+        severity=Severity.WARNING,
+        path=context.relative_path,
+        line=1,
+        message=(
+            f"Generic module '{context.path.name}' has {context.line_count} lines "
+            f"and {len(module_imports)} imports."
+        ),
+        suggestion="Rename around a specific responsibility and split unrelated helpers apart.",
+    )
+
+
+def _class_smell_finding(context: ModuleContext, node: ast.ClassDef) -> Finding | None:
+    methods = [
+        item for item in node.body
+        if isinstance(item, (ast.FunctionDef, ast.AsyncFunctionDef))
+    ]
+    dependencies = _class_dependency_count(node)
+    is_broad = (
+        len(methods) > context.config.max_class_methods
+        or dependencies > context.config.max_ai_class_dependencies
+    )
+    if not is_broad:
+        return None
+    return Finding(
+        rule="ai-smells/god-class-name",
+        severity=Severity.WARNING,
+        path=context.relative_path,
+        line=node.lineno,
+        message=f"Class '{node.name}' looks broad: {len(methods)} methods, {dependencies} dependencies.",
+        suggestion="Replace broad coordinator classes with smaller objects and explicit functions.",
+    )
+
+
+def _class_dependency_count(node: ast.ClassDef) -> int:
+    names: set[str] = set()
+    for item in ast.walk(node):
+        if isinstance(item, ast.Attribute) and isinstance(item.value, ast.Name) and item.value.id == "self":
+            names.add(item.attr)
+    return len(names)
+
+
+def _max_nesting(tree: ast.AST) -> tuple[int, int]:
+    best_depth = 0
+    best_line = 1
+
+    def visit(node: ast.AST, depth: int) -> None:
+        nonlocal best_depth, best_line
+        next_depth = depth + 1 if isinstance(node, BRANCH_NODES) else depth
+        if next_depth > best_depth:
+            best_depth = next_depth
+            best_line = getattr(node, "lineno", best_line)
+        for child in ast.iter_child_nodes(node):
+            visit(child, next_depth)
+
+    visit(tree, 0)
+    return best_depth, best_line

bubbles_lint/rules/boundaries.py

@@ -0,0 +1,94 @@
+from __future__ import annotations
+
+import ast
+from collections import defaultdict
+from pathlib import Path
+
+from bubbles_lint.models import Finding, ModuleContext, Severity
+from bubbles_lint.rules.imports import imports
+
+
+class BoundaryRule:
+    id = "bubble-boundary"
+    title = "Bubble Boundary"
+
+    def __init__(self, import_graph: dict[str, set[str]] | None = None) -> None:
+        self.import_graph = import_graph or {}
+
+    def check(self, context: ModuleContext) -> list[Finding]:
+        findings: list[Finding] = []
+        module_imports = imports(context.tree)
+
+        if len(module_imports) > context.config.max_imports_per_module:
+            findings.append(Finding(
+                rule="bubble-boundary/too-many-imports",
+                severity=Severity.WARNING,
+                path=context.relative_path,
+                line=1,
+                message=(
+                    f"Module imports {len(module_imports)} dependencies; recommended maximum "
+                    f"is {context.config.max_imports_per_module}."
+                ),
+                suggestion="Narrow this module's responsibilities or move integration code to a boundary.",
+            ))
+
+        if not context.config.allow_private_imports:
+            for node in ast.walk(context.tree):
+                if isinstance(node, ast.ImportFrom) and node.module and _has_private_part(node.module):
+                    findings.append(Finding(
+                        rule="bubble-boundary/private-import",
+                        severity=Severity.WARNING,
+                        path=context.relative_path,
+                        line=node.lineno,
+                        message=f"Import reaches into private module '{node.module}'.",
+                        suggestion="Depend on a public interface instead of a private implementation module.",
+                    ))
+
+        module_name = module_name_for_path(context.root, context.path)
+        for target in self.import_graph.get(module_name, set()):
+            if module_name in self.import_graph.get(target, set()):
+                findings.append(Finding(
+                    rule="bubble-boundary/circular-import",
+                    severity=Severity.ERROR,
+                    path=context.relative_path,
+                    line=1,
+                    message=f"Module '{module_name}' and '{target}' import each other.",
+                    suggestion="Extract shared contracts into a smaller third module or invert the dependency.",
+                ))
+
+        return findings
+
+
+def build_import_graph(files: list[Path], root: Path) -> dict[str, set[str]]:
+    modules = {module_name_for_path(root, path): path for path in files}
+    graph: dict[str, set[str]] = defaultdict(set)
+    for module, path in modules.items():
+        try:
+            tree = ast.parse(path.read_text(encoding="utf-8"))
+        except (OSError, SyntaxError, UnicodeDecodeError):
+            continue
+        for imported in imports(tree):
+            candidates = _candidate_modules(imported)
+            for candidate in candidates:
+                if candidate in modules and candidate != module:
+                    graph[module].add(candidate)
+    return graph
+
+
+def module_name_for_path(root: Path, path: Path) -> str:
+    relative = path.relative_to(root).with_suffix("")
+    parts = list(relative.parts)
+    if parts[-1] == "__init__":
+        parts = parts[:-1]
+    return ".".join(parts)
+
+def _candidate_modules(name: str) -> list[str]:
+    parts = name.split(".")
+    return [".".join(parts[:index]) for index in range(len(parts), 0, -1)]
+
+
+def _has_private_part(module: str) -> bool:
+    return any(
+        part.startswith("_") and not (part.startswith("__") and part.endswith("__"))
+        for part in module.split(".")
+    )

bubbles_lint/rules/imports.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+import ast
+
+
+def imports(tree: ast.AST) -> set[str]:
+    names: set[str] = set()
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            for alias in node.names:
+                names.add(alias.name)
+        elif isinstance(node, ast.ImportFrom) and node.module:
+            names.add(node.module)
+    return names

bubbles_lint/rules/leaks.py

@@ -0,0 +1,216 @@
+from __future__ import annotations
+
+import ast
+from collections.abc import Iterable
+
+from bubbles_lint.models import Finding, ModuleContext, Severity
+
+
+MUTABLE_LITERALS = (ast.List, ast.Dict, ast.Set)
+MUTABLE_CALLS = frozenset({"dict", "list", "set", "defaultdict", "Counter"})
+CONFIG_MODULE_NAMES = frozenset({"config", "settings", "environment", "env"})
+SIDE_EFFECT_MODULES = {
+    "filesystem": frozenset({"open", "pathlib", "shutil", "glob", "os.path"}),
+    "network": frozenset({"requests", "httpx", "urllib", "socket", "aiohttp"}),
+    "database": frozenset({"sqlite3", "sqlalchemy", "psycopg2", "pymongo", "redis"}),
+    "subprocess": frozenset({"subprocess"}),
+    "logging": frozenset({"logging"}),
+    "rendering": frozenset({"jinja2", "render", "template", "matplotlib", "PIL"}),
+}
+
+
+class LeakRule:
+    id = "bubble-leak"
+    title = "Bubble Leak"
+
+    def check(self, context: ModuleContext) -> list[Finding]:
+        visitor = _LeakVisitor(context)
+        visitor.visit(context.tree)
+        return visitor.findings
+
+
+class _LeakVisitor(ast.NodeVisitor):
+    def __init__(self, context: ModuleContext) -> None:
+        self.context = context
+        self.findings: list[Finding] = []
+        self.function_depth = 0
+        self.import_aliases = _import_aliases(context.tree)
+
+    def visit_Assign(self, node: ast.Assign) -> None:
+        if self.function_depth == 0 and _is_mutable_value(node.value) and not _all_constants(node.targets):
+            self.findings.append(Finding(
+                rule="bubble-leak/global-mutable-state",
+                severity=Severity.WARNING,
+                path=self.context.relative_path,
+                line=node.lineno,
+                message="Module-level assignment creates mutable global state.",
+                suggestion="Move mutable state behind an explicit object or pass it through function calls.",
+            ))
+        self.generic_visit(node)
+
+    def visit_AnnAssign(self, node: ast.AnnAssign) -> None:
+        is_mutable_global = (
+            self.function_depth == 0
+            and node.value is not None
+            and _is_mutable_value(node.value)
+            and not _all_constants([node.target])
+        )
+        if is_mutable_global:
+            self.findings.append(Finding(
+                rule="bubble-leak/global-mutable-state",
+                severity=Severity.WARNING,
+                path=self.context.relative_path,
+                line=node.lineno,
+                message="Module-level assignment creates mutable global state.",
+                suggestion="Move mutable state behind an explicit object or pass it through function calls.",
+            ))
+        self.generic_visit(node)
+
+    def visit_FunctionDef(self, node: ast.FunctionDef) -> None:
+        self._visit_function(node)
+
+    def visit_AsyncFunctionDef(self, node: ast.AsyncFunctionDef) -> None:
+        self._visit_function(node)
+
+    def _visit_function(self, node: ast.FunctionDef | ast.AsyncFunctionDef) -> None:
+        self.function_depth += 1
+        side_effects = _side_effect_kinds(node, self.import_aliases)
+        if len(side_effects) > self.context.config.max_side_effect_kinds:
+            kinds = ", ".join(sorted(side_effects))
+            self.findings.append(Finding(
+                rule="bubble-leak/mixed-side-effects",
+                severity=Severity.WARNING,
+                path=self.context.relative_path,
+                line=node.lineno,
+                message=f"Function '{node.name}' mixes side effects: {kinds}.",
+                suggestion="Separate orchestration from filesystem, network, database, logging, and rendering work.",
+            ))
+        self.generic_visit(node)
+        self.function_depth -= 1
+
+    def visit_Subscript(self, node: ast.Subscript) -> None:
+        if not _is_config_module(self.context.path) and _is_os_environ_read(node):
+            self.findings.append(Finding(
+                rule="bubble-leak/env-read-outside-config",
+                severity=Severity.WARNING,
+                path=self.context.relative_path,
+                line=node.lineno,
+                message="Environment variable read appears outside a config module.",
+                suggestion="Read environment variables in a config boundary and pass values explicitly.",
+            ))
+        self.generic_visit(node)
+
+    def visit_Call(self, node: ast.Call) -> None:
+        if not _is_config_module(self.context.path) and _is_os_getenv_call(node):
+            self.findings.append(Finding(
+                rule="bubble-leak/env-read-outside-config",
+                severity=Severity.WARNING,
+                path=self.context.relative_path,
+                line=node.lineno,
+                message="Environment variable read appears outside a config module.",
+                suggestion="Read environment variables in a config boundary and pass values explicitly.",
+            ))
+        self.generic_visit(node)
+
+
+def _is_mutable_value(node: ast.AST) -> bool:
+    if isinstance(node, MUTABLE_LITERALS):
+        return True
+    if isinstance(node, ast.Call):
+        name = _call_name(node.func)
+        return name in MUTABLE_CALLS
+    return False
+
+
+def _all_constants(nodes: list[ast.expr]) -> bool:
+    names = [node.id for node in nodes if isinstance(node, ast.Name)]
+    return bool(names) and all(name.isupper() for name in names)
+
+
+def _is_config_module(path) -> bool:
+    stem = path.stem.lower()
+    return stem in CONFIG_MODULE_NAMES or stem.endswith("_config") or stem.endswith("_settings")
+
+
+def _is_os_environ_read(node: ast.Subscript) -> bool:
+    return _dotted_name(node.value) == "os.environ"
+
+
+def _is_os_getenv_call(node: ast.Call) -> bool:
+    return _call_name(node.func) in {"os.getenv", "os.environ.get"}
+
+
+def _side_effect_kinds(function: ast.AST, aliases: dict[str, str]) -> set[str]:
+    kinds: set[str] = set()
+    for node in ast.walk(function):
+        if isinstance(node, ast.Call):
+            kinds.update(_side_effects_for_call(node, aliases))
+        elif isinstance(node, (ast.Import, ast.ImportFrom)):
+            kinds.update(_side_effects_for_import(node))
+    return kinds
+
+
+def _side_effects_for_call(node: ast.Call, aliases: dict[str, str]) -> set[str]:
+    call = _call_name(node.func)
+    kinds: set[str] = set()
+    if call == "open":
+        kinds.add("filesystem")
+    if call == "print":
+        kinds.add("rendering")
+
+    resolved = _resolve_alias(call, aliases)
+    return kinds | _matching_side_effects(resolved)
+
+
+def _side_effects_for_import(node: ast.Import | ast.ImportFrom) -> set[str]:
+    kinds: set[str] = set()
+    for name in _imported_modules(node):
+        kinds.update(_matching_side_effects(name))
+    return kinds
+
+
+def _matching_side_effects(name: str) -> set[str]:
+    return {
+        kind
+        for kind, markers in SIDE_EFFECT_MODULES.items()
+        if any(name == marker or name.startswith(f"{marker}.") for marker in markers)
+    }
+
+
+def _import_aliases(tree: ast.AST) -> dict[str, str]:
+    aliases: dict[str, str] = {}
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            for alias in node.names:
+                aliases[alias.asname or alias.name.split(".")[0]] = alias.name
+        elif isinstance(node, ast.ImportFrom) and node.module:
+            for alias in node.names:
+                aliases[alias.asname or alias.name] = f"{node.module}.{alias.name}"
+    return aliases
+
+
+def _imported_modules(node: ast.Import | ast.ImportFrom) -> Iterable[str]:
+    if isinstance(node, ast.Import):
+        for alias in node.names:
+            yield alias.name
+    elif node.module:
+        yield node.module
+
+
+def _resolve_alias(name: str, aliases: dict[str, str]) -> str:
+    head, _, tail = name.partition(".")
+    resolved = aliases.get(head, head)
+    return f"{resolved}.{tail}" if tail else resolved
+
+
+def _call_name(node: ast.AST) -> str:
+    return _dotted_name(node)
+
+
+def _dotted_name(node: ast.AST) -> str:
+    if isinstance(node, ast.Name):
+        return node.id
+    if isinstance(node, ast.Attribute):
+        parent = _dotted_name(node.value)
+        return f"{parent}.{node.attr}" if parent else node.attr
+    return ""

bubbles_lint/rules/registry.py

@@ -0,0 +1,13 @@
+from bubbles_lint.rules.ai_smells import AiSmellRule
+from bubbles_lint.rules.boundaries import BoundaryRule
+from bubbles_lint.rules.leaks import LeakRule
+from bubbles_lint.rules.size import SizeRule
+
+
+def default_rules():
+    return [
+        SizeRule(),
+        LeakRule(),
+        BoundaryRule(),
+        AiSmellRule(),
+    ]

bubbles_lint/rules/size.py

@@ -0,0 +1,111 @@
+from __future__ import annotations
+
+import ast
+
+from bubbles_lint.models import Finding, ModuleContext, Severity
+
+
+class SizeRule:
+    id = "bubble-burst"
+    title = "Bubble Burst"
+
+    def check(self, context: ModuleContext) -> list[Finding]:
+        findings: list[Finding] = []
+
+        file_finding = _file_size_finding(context)
+        if file_finding:
+            findings.append(file_finding)
+
+        for node in ast.walk(context.tree):
+            if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                findings.extend(_function_findings(context, node))
+
+            if isinstance(node, ast.ClassDef):
+                class_finding = _class_finding(context, node)
+                if class_finding:
+                    findings.append(class_finding)
+
+        return findings
+
+
+def _file_size_finding(context: ModuleContext) -> Finding | None:
+    if context.line_count <= context.config.max_file_lines:
+        return None
+    return Finding(
+        rule="bubble-burst/file-too-large",
+        severity=Severity.WARNING,
+        path=context.relative_path,
+        line=1,
+        message=(
+            f"File has {context.line_count} lines; recommended maximum "
+            f"is {context.config.max_file_lines}."
+        ),
+        suggestion="Split this module into smaller bubbles with one responsibility each.",
+    )
+
+
+def _function_findings(
+    context: ModuleContext,
+    node: ast.FunctionDef | ast.AsyncFunctionDef,
+) -> list[Finding]:
+    findings: list[Finding] = []
+    length = _node_length(node)
+    if length > context.config.max_function_lines:
+        findings.append(Finding(
+            rule="bubble-burst/function-too-large",
+            severity=Severity.WARNING,
+            path=context.relative_path,
+            line=node.lineno,
+            message=(
+                f"Function '{node.name}' has {length} lines; recommended "
+                f"maximum is {context.config.max_function_lines}."
+            ),
+            suggestion="Extract smaller functions with explicit inputs and outputs.",
+        ))
+
+    param_count = _parameter_count(node.args)
+    if param_count > context.config.max_function_params:
+        findings.append(Finding(
+            rule="bubble-burst/too-many-parameters",
+            severity=Severity.WARNING,
+            path=context.relative_path,
+            line=node.lineno,
+            message=(
+                f"Function '{node.name}' has {param_count} parameters; "
+                f"recommended maximum is {context.config.max_function_params}."
+            ),
+            suggestion="Group related data behind a clear interface or split responsibilities.",
+        ))
+    return findings
+
+
+def _class_finding(context: ModuleContext, node: ast.ClassDef) -> Finding | None:
+    methods = [
+        item for item in node.body
+        if isinstance(item, (ast.FunctionDef, ast.AsyncFunctionDef))
+    ]
+    if len(methods) <= context.config.max_class_methods:
+        return None
+    return Finding(
+        rule="bubble-burst/class-too-many-methods",
+        severity=Severity.WARNING,
+        path=context.relative_path,
+        line=node.lineno,
+        message=(
+            f"Class '{node.name}' has {len(methods)} methods; recommended "
+            f"maximum is {context.config.max_class_methods}."
+        ),
+        suggestion="Split the class into smaller collaborators with narrower roles.",
+    )
+
+
+def _node_length(node: ast.AST) -> int:
+    end = getattr(node, "end_lineno", None) or getattr(node, "lineno", 1)
+    return end - getattr(node, "lineno", 1) + 1
+
+
+def _parameter_count(args: ast.arguments) -> int:
+    positional = list(args.posonlyargs) + list(args.args)
+    if positional and positional[0].arg in {"self", "cls"}:
+        positional = positional[1:]
+    return len(positional) + len(args.kwonlyargs) + (1 if args.vararg else 0) + (1 if args.kwarg else 0)

bubbles_lint/scanner.py

@@ -0,0 +1,88 @@
+from __future__ import annotations
+
+import ast
+from pathlib import Path
+from typing import Iterable
+
+from bubbles_lint.config import Config, load_config
+from bubbles_lint.models import Finding, ModuleContext, Rule, ScanResult, Severity
+from bubbles_lint.rules.boundaries import BoundaryRule, build_import_graph
+from bubbles_lint.rules.registry import default_rules
+
+
+def scan_path(path: Path, config: Config | None = None, rules: Iterable[Rule] | None = None) -> ScanResult:
+    root = path.resolve()
+    if root.is_file():
+        root = root.parent
+
+    active_config = config or load_config(root)
+    files = list(iter_python_files(path.resolve(), active_config))
+    active_rules = list(rules) if rules is not None else _rules_for_files(files, root)
+    result = ScanResult(files_scanned=0)
+
+    for file_path in files:
+        result.files_scanned += 1
+        try:
+            source = file_path.read_text(encoding="utf-8")
+            tree = ast.parse(source, filename=str(file_path))
+        except SyntaxError as error:
+            result.findings.append(Finding(
+                rule="parser/syntax-error",
+                severity=Severity.ERROR,
+                path=_relative(file_path, root),
+                line=error.lineno or 1,
+                message=f"Could not parse Python file: {error.msg}.",
+                suggestion="Fix the syntax error before Bubbles Lint can inspect this module's architecture.",
+            ))
+            continue
+        except (OSError, UnicodeDecodeError) as error:
+            result.findings.append(Finding(
+                rule="parser/read-error",
+                severity=Severity.ERROR,
+                path=_relative(file_path, root),
+                line=1,
+                message=f"Could not read Python file: {error}.",
+                suggestion="Ensure the file is readable UTF-8 Python source.",
+            ))
+            continue
+
+        context = ModuleContext(
+            path=file_path,
+            root=root,
+            source=source,
+            tree=tree,
+            line_count=len(source.splitlines()),
+            config=active_config,
+        )
+        for rule in active_rules:
+            result.extend(rule.check(context))
+
+    result.findings.sort(key=lambda item: (item.path.as_posix(), item.line, item.rule))
+    return result
+
+
+def iter_python_files(path: Path, config: Config) -> Iterable[Path]:
+    if path.is_file():
+        if path.suffix == ".py":
+            yield path
+        return
+
+    for item in sorted(path.rglob("*.py")):
+        if any(part in config.excludes for part in item.parts):
+            continue
+        yield item
+
+
+def _rules_for_files(files: list[Path], root: Path) -> list[Rule]:
+    graph = build_import_graph(files, root)
+    return [
+        BoundaryRule(import_graph=graph) if isinstance(rule, BoundaryRule) else rule
+        for rule in default_rules()
+    ]
+
+
+def _relative(path: Path, root: Path) -> Path:
+    try:
+        return path.relative_to(root)
+    except ValueError:
+        return path

bubbles_lint-0.1.0.dist-info/METADATA

@@ -0,0 +1,211 @@
+Metadata-Version: 2.4
+Name: bubbles-lint
+Version: 0.1.0
+Summary: A Python-first architectural linter for small, composable, Unix-like code.
+Author: Bubbles Lint contributors
+License: MIT License
+        
+        Copyright (c) 2026 Syed (Sadat) Nazrul
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: architecture,linter,python,static-analysis,unix-philosophy
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="assets/bubbles-lint-logo.png" alt="Bubbles Lint logo" width="220">
+</p>
+
+Bubbles Lint is an architectural linter for Python code. It is inspired by Unix and Linux software design principles: do one thing well, keep modules small, compose simple parts, and make boundaries easy to inspect.
+
+Think of it as Ruff for architecture. It does not compete with Ruff, Black, Flake8, or Pylint. Bubbles Lint looks for software shape problems: code that is too large, too coupled, too magical, or too monolithic.
+
+## Installation
+
+```bash
+pip install bubbles-lint
+```
+
+For local development from this repository:
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Usage
+
+Scan the current repository:
+
+```bash
+bubbles-lint scan .
+```
+
+Emit JSON for CI systems:
+
+```bash
+bubbles-lint scan . --json
+```
+
+Bubbles Lint exits with status `1` when findings are present and `0` when the scan is clean.
+
+## Philosophy
+
+Bubbles Lint encourages codebases where:
+
+- modules have one clear responsibility
+- functions and classes stay small enough to replace
+- dependencies flow through explicit interfaces
+- configuration is loaded at the edge
+- side effects are isolated from pure logic
+- text and data move through well-defined boundaries
+- components are easy to inspect, test, and swap
+
+The goal is not style enforcement. The goal is software design discipline, especially in Python codebases that have grown quickly with help from AI coding assistants.
+
+## Rules
+
+### Bubble Burst
+
+Flags code that has grown too large:
+
+- files over `max_file_lines`
+- functions over `max_function_lines`
+- classes with more than `max_class_methods`
+- functions with more than `max_function_params`
+
+### Bubble Leak
+
+Flags hidden coupling and mixed side effects:
+
+- global mutable state
+- direct environment variable reads outside config modules
+- functions mixing too many side-effect categories, such as filesystem, network, database, subprocess, logging, and rendering
+
+### Bubble Boundary
+
+Flags dependency boundary problems:
+
+- circular imports where practical
+- modules importing too many dependencies
+- imports from private modules like `from package._internal import thing`
+
+### AI Smells
+
+Flags common broad abstractions produced in rushed or generated code:
+
+- oversized `utils.py`, `helpers.py`, `manager.py`, and `service.py` modules
+- broad classes ending in `Manager`, `Service`, or `Handler`
+- deeply nested control flow
+
+## Configuration
+
+Configure Bubbles Lint in `pyproject.toml`:
+
+```toml
+[tool.bubbles-lint]
+max_file_lines = 500
+max_function_lines = 50
+max_class_methods = 10
+max_function_params = 5
+max_imports_per_module = 20
+max_nesting_depth = 4
+allow_private_imports = false
+```
+
+Additional knobs:
+
+```toml
+[tool.bubbles-lint]
+max_side_effect_kinds = 3
+max_ai_module_lines = 200
+max_ai_class_dependencies = 8
+excludes = ["generated"]
+```
+
+Bubbles Lint always ignores `.venv`, `venv`, `.git`, `__pycache__`, `build`, and `dist`.
+
+Existing `[tool.bubbles]` configs are still read for compatibility, but new projects should use `[tool.bubbles-lint]`.
+
+## Human Output
+
+```text
+Bubble: Bubble Burst
+
+src/payment_service.py:1
+warning: File has 1437 lines; recommended maximum is 500.
+
+Suggestion:
+Split this module into smaller bubbles with one responsibility each.
+```
+
+## JSON Output
+
+```json
+{
+  "findings": [
+    {
+      "rule": "bubble-burst/file-too-large",
+      "severity": "warning",
+      "path": "src/payment_service.py",
+      "line": 1,
+      "message": "File has 1437 lines; recommended maximum is 500.",
+      "suggestion": "Split this module into smaller bubbles with one responsibility each."
+    }
+  ],
+  "files_scanned": 1
+}
+```
+
+## CI
+
+Example GitHub Actions step:
+
+```yaml
+- name: Install Bubbles Lint
+  run: pip install .
+
+- name: Scan architecture
+  run: bubbles-lint scan . --json
+```
+
+## Development
+
+Run tests:
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+The rule engine is intentionally small. New rules implement a `check(context)` method and return `Finding` objects. Parsing, configuration, scanning, reporting, and CLI code are separated so the tool can grow without becoming the kind of monolith it warns about.

bubbles_lint-0.1.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+bubbles_lint/__init__.py,sha256=Czd291KJEuH1LavswVQYGzZN_y-jyyBABVSn9RKH8vM,99
+bubbles_lint/cli.py,sha256=WD0R92wYYKI1HRQOgxdZt_PIcz1pGI1fG3_m2AUbXeA,1290
+bubbles_lint/config.py,sha256=0KMuo89xKRX3xx_0_3Ag74HFOzAQoyJ-8urz6yyRU84,2094
+bubbles_lint/models.py,sha256=8pwjn-q--qIMuha-Wn7mgUQgSQU1fq2dSm2CTvFMEkU,1606
+bubbles_lint/report.py,sha256=GFnSzrA1-a55R7VOGStJ-oWoKDEXBjez1OtG8NEyTSA,1473
+bubbles_lint/scanner.py,sha256=zvcDZKljQkc0l_HuSihVeoAOOgB99TOTqQgDTMBDvQ4,3021
+bubbles_lint/rules/__init__.py,sha256=PQD1t3A7SxjPsLUaplODyU0Pi6kDYtRB7CGfAPy2CA0,52
+bubbles_lint/rules/ai_smells.py,sha256=YysDHErSQ9eHl_5Dt_fNQF1J8iZcENvJBW1nK5v7RLo,4095
+bubbles_lint/rules/boundaries.py,sha256=byl38_TZDS-tzFbxS5gsQBqj22bqRmSXj1CkZ2T5jks,3778
+bubbles_lint/rules/imports.py,sha256=XfRO4zWjBnI0ZWLM9q9_x87jhg3pDqOzF2uiP_PC-Wc,380
+bubbles_lint/rules/leaks.py,sha256=BBE6c94vgn9-Fhq_JJSW0N0esq2P93UTZu34c6Fwkog,8154
+bubbles_lint/rules/registry.py,sha256=kXgG49M2NO6SQpejRSADoGiLo9Zl9nX5f1iauT2Kz8Y,328
+bubbles_lint/rules/size.py,sha256=1Phl5l7RWFRLumEtJbTc_aYCZ7r-GBOuABdMgnwzXvU,3873
+bubbles_lint-0.1.0.dist-info/METADATA,sha256=wCsn1SQI_KR5XU6wmUvN51uxwYgSjlxQeAUsZ8MgWNA,6380
+bubbles_lint-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+bubbles_lint-0.1.0.dist-info/entry_points.txt,sha256=8i6NCvjaxfUeemNfXiKgGmmaU7pi9i4aYmdnWhRJ_uo,55
+bubbles_lint-0.1.0.dist-info/licenses/LICENSE,sha256=ntzBqSx5kLY1uLtYQwpo1nEZURJ7XO78NGIaiNCjaVc,1076
+bubbles_lint-0.1.0.dist-info/RECORD,,

bubbles_lint-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

bubbles_lint-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+bubbles-lint = bubbles_lint.cli:main

bubbles_lint-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Syed (Sadat) Nazrul
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.