Godot GDScript Architecture Guard

godot-gdscript-architecture-guard checks whether GDScript files still follow a small architecture policy. It is aimed at projects where autoloads, shared scripts, and feature modules can quietly become tangled during refactors.

It does not run the Godot editor. It scans .gd files and reports dependency direction, autoload access, unresolved res:// script/resource references, module owner summaries, high fan-in/fan-out from visible script references, and possible unused scripts/resources.

Install

python -m pip install godot-gdscript-architecture-guard

From a source checkout:

python -m pip install -e .\godot-gdscript-architecture-guard

Quick Start

godot-architecture-guard examples\tiny-architecture-project --config architecture-guard.toml

Write SARIF for code scanning:

godot-architecture-guard . --config architecture-guard.toml --format sarif --output reports\architecture.sarif

Write a Markdown refactor note:

godot-architecture-guard . --config architecture-guard.toml --format markdown --output reports\architecture.md --fail-on none

Markdown reports include owner summaries, dependency hotspots, possible unused files, and a Mermaid module dependency graph when configured modules reference each other. Use --format mermaid when you only want the graph.

Policy Example

[modules.ui]
paths = ["scripts/ui/**"]
may_depend_on = ["shared"]
allowed_autoloads = ["Settings"]

[modules.gameplay]
paths = ["scripts/gameplay/**"]
may_depend_on = ["shared"]
allowed_autoloads = ["GameState"]

[modules.shared]
paths = ["scripts/shared/**"]
may_depend_on = []
allowed_autoloads = []

[autoloads]
names = ["GameState", "Settings"]

[ignore]
paths = ["addons/generated/**", "scripts/generated/**"]

If scripts/ui/menu.gd preloads res://scripts/gameplay/inventory.gd, the tool reports a module boundary violation unless ui may depend on gameplay.

If a configured module path matches no scripts, the tool reports that stale policy path as a warning. JSON, text, and Markdown reports also include advisory sections for module ownership, files with many visible script references, and scripts or resources that do not appear in visible res:// references. Script checks also treat class_name declarations as public entry points. Use [ignore] paths for generated, vendor, or imported helper folders that would otherwise dominate owner summaries, hotspots, and possible-unused advice. Patterns are matched against project-relative paths with forward slashes.

Outputs

• text: local terminal report.
• json: CI and scripts.
• markdown: PR comments and review notes.
• sarif: GitHub code scanning.
• mermaid: dependency graph.

JSON reports include metadata, rule_help, and per-finding suggestions so CI jobs and small review scripts can explain the issue without hard-coding rule text. They also include owner_summaries, hotspots, and possible_unused_scripts / possible_unused_resources arrays for refactor review. Markdown reports embed the same module graph that --format mermaid writes as a standalone artifact. SARIF output carries rule descriptions for code scanning tools.