bubbles-lint 0.1.0__tar.gz

bubbles_lint-0.1.0/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.

bubbles_lint-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,166 @@
+<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/bubbles_lint/__init__.py

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

bubbles_lint-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-0.1.0/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-0.1.0/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-0.1.0/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-0.1.0/bubbles_lint/rules/__init__.py

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