gdcruiser 1.1.0__tar.gz

gdcruiser-1.1.0/PKG-INFO

@@ -0,0 +1,207 @@
+Metadata-Version: 2.3
+Name: gdcruiser
+Version: 1.1.0
+Summary: Dependency analyzer for Godot/GDScript projects
+Author: LeTuR
+Author-email: LeTuR <magicletur@protonmail.com>
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+
+# gdcruiser
+
+A dependency analyzer for Godot/GDScript projects. Scans your project to build a dependency graph, detect circular dependencies, and export visualizations.
+
+## Features
+
+- Analyzes `.gd` (GDScript) and `.tscn` (scene) files
+- Detects circular dependencies
+- Resolves `class_name` declarations to map symbolic inheritance
+- Multiple output formats: human-readable text, JSON, and GraphViz DOT
+- Returns non-zero exit code when cycles are detected (CI-friendly)
+
+## Installation
+
+Requires Python 3.13+.
+
+```bash
+pip install gdcruiser
+```
+
+Or with [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv tool install gdcruiser
+```
+
+## Usage
+
+```
+gdcruiser [-h] [-f {text,json,dot}] [-o FILE] [--no-cycles] [-v] [path]
+```
+
+| Option | Description |
+|--------|-------------|
+| `path` | Godot project path (default: current directory) |
+| `-f, --format` | Output format: `text` (default), `json`, or `dot` |
+| `-o, --output` | Write output to file instead of stdout |
+| `--no-cycles` | Skip cycle detection |
+| `-v, --verbose` | Verbose output |
+
+### Examples
+
+Analyze the current directory:
+
+```bash
+gdcruiser .
+```
+
+Analyze a specific project and output JSON:
+
+```bash
+gdcruiser /path/to/godot/project -f json
+```
+
+Generate a GraphViz DOT file:
+
+```bash
+gdcruiser . -f dot -o deps.dot
+dot -Tpng deps.dot -o deps.png
+```
+
+## Output Formats
+
+### Text (default)
+
+```
+============================================================
+GDScript Dependency Analysis
+============================================================
+
+Modules: 9
+Dependencies: 8
+
+----------------------------------------
+CIRCULAR DEPENDENCIES (1 found)
+----------------------------------------
+
+Cycle 1:
+  -> res://cycle_b.gd
+  -> res://cycle_a.gd
+  -> res://cycle_b.gd (back to start)
+
+----------------------------------------
+MODULE DEPENDENCIES
+----------------------------------------
+
+res://player.gd
+  class_name: Player
+  extends_class: res://base_entity.gd:2
+  preload: res://inventory.gd:5
+```
+
+### JSON
+
+```json
+{
+  "graph": {
+    "modules": {
+      "res://player.gd": {
+        "path": "res://player.gd",
+        "class_name": "Player",
+        "dependencies": [
+          {
+            "target": "res://base_entity.gd",
+            "type": "extends_class",
+            "line": 2,
+            "resolved": true
+          }
+        ]
+      }
+    },
+    "stats": {
+      "module_count": 9,
+      "dependency_count": 8
+    }
+  },
+  "cycles": [],
+  "symbols": {
+    "Player": "res://player.gd"
+  },
+  "errors": []
+}
+```
+
+### GraphViz DOT
+
+```dot
+digraph dependencies {
+    rankdir=LR;
+    node [shape=box, fontname="monospace"];
+
+    "res://player.gd" [label="Player\nplayer.gd"];
+    "res://base_entity.gd" [label="BaseEntity\nbase_entity.gd"];
+
+    "res://player.gd" -> "res://base_entity.gd" [label="extends"];
+}
+```
+
+Nodes involved in cycles are highlighted in red.
+
+## Supported Dependency Patterns
+
+gdcruiser detects the following GDScript patterns:
+
+| Pattern | Example |
+|---------|---------|
+| `extends` (path) | `extends "res://path/to/script.gd"` |
+| `extends` (class) | `extends ClassName` |
+| `class_name` | `class_name MyClass` |
+| `preload()` | `preload("res://path/to/file.gd")` |
+| `load()` | `load("res://path/to/file.gd")` |
+
+For `.tscn` files, it detects scripts attached to nodes via `[ext_resource]`.
+
+## Development
+
+Install dependencies:
+
+```bash
+uv sync
+```
+
+Set up pre-commit hooks:
+
+```bash
+uv run pre-commit install
+```
+
+This installs hooks for `pre-commit`, `commit-msg`, and `post-checkout` stages. On every commit the hooks will:
+
+- Fix trailing whitespace and line endings
+- Lint and format with [Ruff](https://docs.astral.sh/ruff/)
+- Run the test suite with pytest
+- Enforce [Conventional Commits](https://www.conventionalcommits.org/) for commit messages
+
+Run the CLI:
+
+```bash
+uv run gdcruiser
+```
+
+Run tests:
+
+```bash
+uv run pytest
+```
+
+Run linter:
+
+```bash
+uv run ruff check .
+```
+
+Format code:
+
+```bash
+uv run ruff format .
+```

gdcruiser-1.1.0/README.md

@@ -0,0 +1,198 @@
+# gdcruiser
+
+A dependency analyzer for Godot/GDScript projects. Scans your project to build a dependency graph, detect circular dependencies, and export visualizations.
+
+## Features
+
+- Analyzes `.gd` (GDScript) and `.tscn` (scene) files
+- Detects circular dependencies
+- Resolves `class_name` declarations to map symbolic inheritance
+- Multiple output formats: human-readable text, JSON, and GraphViz DOT
+- Returns non-zero exit code when cycles are detected (CI-friendly)
+
+## Installation
+
+Requires Python 3.13+.
+
+```bash
+pip install gdcruiser
+```
+
+Or with [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv tool install gdcruiser
+```
+
+## Usage
+
+```
+gdcruiser [-h] [-f {text,json,dot}] [-o FILE] [--no-cycles] [-v] [path]
+```
+
+| Option | Description |
+|--------|-------------|
+| `path` | Godot project path (default: current directory) |
+| `-f, --format` | Output format: `text` (default), `json`, or `dot` |
+| `-o, --output` | Write output to file instead of stdout |
+| `--no-cycles` | Skip cycle detection |
+| `-v, --verbose` | Verbose output |
+
+### Examples
+
+Analyze the current directory:
+
+```bash
+gdcruiser .
+```
+
+Analyze a specific project and output JSON:
+
+```bash
+gdcruiser /path/to/godot/project -f json
+```
+
+Generate a GraphViz DOT file:
+
+```bash
+gdcruiser . -f dot -o deps.dot
+dot -Tpng deps.dot -o deps.png
+```
+
+## Output Formats
+
+### Text (default)
+
+```
+============================================================
+GDScript Dependency Analysis
+============================================================
+
+Modules: 9
+Dependencies: 8
+
+----------------------------------------
+CIRCULAR DEPENDENCIES (1 found)
+----------------------------------------
+
+Cycle 1:
+  -> res://cycle_b.gd
+  -> res://cycle_a.gd
+  -> res://cycle_b.gd (back to start)
+
+----------------------------------------
+MODULE DEPENDENCIES
+----------------------------------------
+
+res://player.gd
+  class_name: Player
+  extends_class: res://base_entity.gd:2
+  preload: res://inventory.gd:5
+```
+
+### JSON
+
+```json
+{
+  "graph": {
+    "modules": {
+      "res://player.gd": {
+        "path": "res://player.gd",
+        "class_name": "Player",
+        "dependencies": [
+          {
+            "target": "res://base_entity.gd",
+            "type": "extends_class",
+            "line": 2,
+            "resolved": true
+          }
+        ]
+      }
+    },
+    "stats": {
+      "module_count": 9,
+      "dependency_count": 8
+    }
+  },
+  "cycles": [],
+  "symbols": {
+    "Player": "res://player.gd"
+  },
+  "errors": []
+}
+```
+
+### GraphViz DOT
+
+```dot
+digraph dependencies {
+    rankdir=LR;
+    node [shape=box, fontname="monospace"];
+
+    "res://player.gd" [label="Player\nplayer.gd"];
+    "res://base_entity.gd" [label="BaseEntity\nbase_entity.gd"];
+
+    "res://player.gd" -> "res://base_entity.gd" [label="extends"];
+}
+```
+
+Nodes involved in cycles are highlighted in red.
+
+## Supported Dependency Patterns
+
+gdcruiser detects the following GDScript patterns:
+
+| Pattern | Example |
+|---------|---------|
+| `extends` (path) | `extends "res://path/to/script.gd"` |
+| `extends` (class) | `extends ClassName` |
+| `class_name` | `class_name MyClass` |
+| `preload()` | `preload("res://path/to/file.gd")` |
+| `load()` | `load("res://path/to/file.gd")` |
+
+For `.tscn` files, it detects scripts attached to nodes via `[ext_resource]`.
+
+## Development
+
+Install dependencies:
+
+```bash
+uv sync
+```
+
+Set up pre-commit hooks:
+
+```bash
+uv run pre-commit install
+```
+
+This installs hooks for `pre-commit`, `commit-msg`, and `post-checkout` stages. On every commit the hooks will:
+
+- Fix trailing whitespace and line endings
+- Lint and format with [Ruff](https://docs.astral.sh/ruff/)
+- Run the test suite with pytest
+- Enforce [Conventional Commits](https://www.conventionalcommits.org/) for commit messages
+
+Run the CLI:
+
+```bash
+uv run gdcruiser
+```
+
+Run tests:
+
+```bash
+uv run pytest
+```
+
+Run linter:
+
+```bash
+uv run ruff check .
+```
+
+Format code:
+
+```bash
+uv run ruff format .
+```

gdcruiser-1.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[project]
+name = "gdcruiser"
+version = "1.1.0"
+description = "Dependency analyzer for Godot/GDScript projects"
+readme = "README.md"
+authors = [
+    { name = "LeTuR", email = "magicletur@protonmail.com" }
+]
+requires-python = ">=3.13"
+dependencies = []
+
+[project.scripts]
+gdcruiser = "gdcruiser:main"
+
+[build-system]
+requires = ["uv_build>=0.9.13,<0.10.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.2",
+    "ruff>=0.15.0",
+]
+
+[tool.semantic_release]
+version_toml = []
+branch = "main"
+tag_format = "v{version}"
+commit_message = ""
+
+[tool.semantic_release.commit_parser_options]
+allowed_tags = ["build", "chore", "ci", "docs", "feat", "fix", "perf", "refactor", "style", "test"]
+minor_tags = ["feat"]
+patch_tags = ["fix", "perf"]
+
+[tool.semantic_release.remote]
+type = "github"

gdcruiser-1.1.0/src/gdcruiser/__init__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+__all__ = ["main"]

gdcruiser-1.1.0/src/gdcruiser/analyzer.py

@@ -0,0 +1,86 @@
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from .scanner import Scanner
+from .parser.gdscript import GDScriptParser
+from .parser.tscn import TscnParser
+from .graph.dependency import DependencyGraph
+from .graph.cycles import CycleDetector
+from .symbols.table import SymbolTable
+
+
+@dataclass
+class AnalysisResult:
+    """Result of analyzing a Godot project."""
+
+    graph: DependencyGraph
+    cycles: list[list[str]] = field(default_factory=list)
+    symbol_table: SymbolTable = field(default_factory=SymbolTable)
+    errors: list[str] = field(default_factory=list)
+
+    def to_dict(self) -> dict:
+        return {
+            "graph": self.graph.to_dict(),
+            "cycles": self.cycles,
+            "symbols": self.symbol_table.all_classes(),
+            "errors": self.errors,
+        }
+
+
+class Analyzer:
+    """Orchestrates parsing and graph building for a Godot project."""
+
+    def __init__(self, project_path: Path, verbose: bool = False) -> None:
+        self._scanner = Scanner(project_path)
+        self._symbol_table = SymbolTable()
+        self._gd_parser = GDScriptParser(self._symbol_table)
+        self._tscn_parser = TscnParser()
+        self._graph = DependencyGraph()
+        self._verbose = verbose
+        self._errors: list[str] = []
+
+    def analyze(self, detect_cycles: bool = True) -> AnalysisResult:
+        """Analyze the project and return results."""
+        gd_files, tscn_files = self._scanner.find_all_files()
+        root = self._scanner.root
+
+        if self._verbose:
+            print(f"Found {len(gd_files)} GDScript files")
+            print(f"Found {len(tscn_files)} scene files")
+
+        # First pass: parse all GDScript files to build symbol table
+        modules = []
+        for gd_file in gd_files:
+            try:
+                module = self._gd_parser.parse(gd_file, root)
+                modules.append(module)
+                self._graph.add_module(module)
+            except Exception as e:
+                self._errors.append(f"Error parsing {gd_file}: {e}")
+
+        # Second pass: resolve class name dependencies
+        for module in modules:
+            self._gd_parser.resolve_class_dependencies(module)
+
+        # Parse scene files
+        for tscn_file in tscn_files:
+            try:
+                module = self._tscn_parser.parse(tscn_file, root)
+                self._graph.add_module(module)
+            except Exception as e:
+                self._errors.append(f"Error parsing {tscn_file}: {e}")
+
+        # Detect cycles
+        cycles: list[list[str]] = []
+        if detect_cycles:
+            detector = CycleDetector(self._graph)
+            cycles = detector.find_cycles()
+            if self._verbose:
+                print(f"Found {len(cycles)} cycles")
+
+        return AnalysisResult(
+            graph=self._graph,
+            cycles=cycles,
+            symbol_table=self._symbol_table,
+            errors=self._errors,
+        )

gdcruiser-1.1.0/src/gdcruiser/cli.py

@@ -0,0 +1,186 @@
+import argparse
+import sys
+from pathlib import Path
+
+from .analyzer import Analyzer
+from .config import ConfigError, ConfigLoader, ConfigValidator
+from .output.dot import DotFormatter
+from .output.json import JsonFormatter
+from .output.text import TextFormatter
+from .rules import RuleEngine
+
+
+def create_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="gdcruiser",
+        description="Dependency analyzer for Godot/GDScript projects",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  gdcruiser .                    Analyze current directory
+  gdcruiser /path/to/project     Analyze specific project
+  gdcruiser . -f json            Output as JSON
+  gdcruiser . -f dot -o deps.dot Output DOT file for GraphViz
+  gdcruiser . --no-cycles        Skip cycle detection
+  gdcruiser . --config rules.json Use custom config file
+  gdcruiser . --validate-config  Validate config without analyzing
+""",
+    )
+
+    parser.add_argument(
+        "path",
+        nargs="?",
+        default=".",
+        help="Godot project path (default: current directory)",
+    )
+
+    parser.add_argument(
+        "-f",
+        "--format",
+        choices=["text", "json", "dot"],
+        default="text",
+        help="Output format (default: text)",
+    )
+
+    parser.add_argument(
+        "-o",
+        "--output",
+        metavar="FILE",
+        help="Output file (default: stdout)",
+    )
+
+    parser.add_argument(
+        "--no-cycles",
+        action="store_true",
+        help="Skip cycle detection",
+    )
+
+    parser.add_argument(
+        "-v",
+        "--verbose",
+        action="store_true",
+        help="Verbose output",
+    )
+
+    parser.add_argument(
+        "--config",
+        metavar="FILE",
+        help="Path to config file (.gdcruiser.json or pyproject.toml)",
+    )
+
+    parser.add_argument(
+        "--validate-config",
+        action="store_true",
+        help="Validate config file and exit",
+    )
+
+    parser.add_argument(
+        "--ignore-rules",
+        action="store_true",
+        help="Skip rule evaluation",
+    )
+
+    return parser
+
+
+def run(args: argparse.Namespace) -> int:
+    project_path = Path(args.path).resolve()
+
+    if not project_path.exists():
+        print(f"Error: Path does not exist: {project_path}", file=sys.stderr)
+        return 1
+
+    if not project_path.is_dir():
+        print(f"Error: Path is not a directory: {project_path}", file=sys.stderr)
+        return 1
+
+    # Load configuration
+    config_path = Path(args.config) if args.config else None
+    loader = ConfigLoader(project_path)
+
+    try:
+        config = loader.load(config_path)
+    except ConfigError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        return 1
+
+    # Validate config
+    if config.has_rules() or args.validate_config:
+        validator = ConfigValidator()
+        validation = validator.validate(config)
+
+        if args.verbose or args.validate_config:
+            if validation.warnings:
+                for w in validation.warnings:
+                    print(f"Warning: {w.path}: {w.message}", file=sys.stderr)
+
+        if not validation.is_valid():
+            for e in validation.errors:
+                print(f"Error: {e.path}: {e.message}", file=sys.stderr)
+            return 1
+
+        if args.validate_config:
+            config_file = config_path or loader.discover()
+            if config_file:
+                print(f"Config valid: {config_file}")
+                print(f"  Forbidden rules: {len(config.forbidden)}")
+                print(f"  Allowed rules: {len(config.allowed)}")
+                print(f"  Required rules: {len(config.required)}")
+            else:
+                print("No config file found")
+            return 0
+
+    if args.verbose:
+        print(f"Analyzing: {project_path}")
+        if config.has_rules():
+            print(f"Rules loaded: {len(config.all_rules())}")
+
+    analyzer = Analyzer(project_path, verbose=args.verbose)
+    result = analyzer.analyze(detect_cycles=not args.no_cycles)
+
+    # Evaluate rules
+    rule_result = None
+    if config.has_rules() and not args.ignore_rules:
+        engine = RuleEngine(config, result.graph)
+        rule_result = engine.check_all(cycles=result.cycles)
+
+        if args.verbose:
+            print(
+                f"Rule violations: {rule_result.error_count()} errors, "
+                f"{rule_result.warning_count()} warnings"
+            )
+
+    # Format output
+    if args.format == "json":
+        formatter = JsonFormatter()
+        output = formatter.format(result, rule_result)
+    elif args.format == "dot":
+        formatter = DotFormatter()
+        output = formatter.format(result)
+    else:
+        formatter = TextFormatter()
+        output = formatter.format(result, rule_result)
+
+    # Write output
+    if args.output:
+        output_path = Path(args.output)
+        output_path.write_text(output, encoding="utf-8")
+        if args.verbose:
+            print(f"Output written to: {output_path}")
+    else:
+        print(output)
+
+    # Return non-zero if rule errors or cycles found
+    if rule_result and rule_result.has_errors():
+        return 1
+
+    if result.cycles and not args.no_cycles:
+        return 1
+
+    return 0
+
+
+def main() -> int:
+    parser = create_parser()
+    args = parser.parse_args()
+    return run(args)