Skip to content

Home

Jump to bottom
Semenov Dmitrii edited this page Feb 18, 2026 · 4 revisions

What is GDShrapt?

GDShrapt is a semantic analysis and safe refactoring platform for GDScript.

It provides project‑wide understanding of:

  • symbols and inheritance
  • types (explicit and inferred)
  • signal connections (code + .tscn)
  • duck‑typed call sites
  • cross‑file data flow

The primary goal is safe, large‑scale refactoring without breaking dynamic code.

Architecture Overview

GDShrapt consists of three user‑facing components:

  1. CLI – automation, CI, batch refactoring, reports
  2. LSP – editor features (find references, rename, diagnostics)
  3. Godot Plugin – in‑editor UX and visual workflows

All three are thin consumers of the same semantic core.

The core provides:

  • parsing and AST
  • semantic model
  • type system
  • provenance tracking
  • confidence scoring
  • refactoring engine

This means:

  • identical results in CLI, LSP, and Plugin
  • deterministic rename safety
  • shared caches and analysis pipeline

The rest of this wiki focuses on the semantic core model, because it defines the behavior of all tools.

Core Concepts

GDShrapt safety is based on three pillars:

Semantic Types

Project‑wide type model built from:

  • annotations
  • inference
  • control‑flow narrowing
  • scene metadata
  • signals
  • collision filtering

Provenance

Every reference carries:

  • where it came from
  • how it was inferred
  • which paths prove it

This enables explainable refactoring.

Confidence Levels

Each edit is classified as:

  • Strict – provably correct, safe to apply
  • Potential – likely correct, preview only
  • NameMatch – heuristic, preview only
  • Contract strings – string APIs, explicit opt‑in

Recommended Reading Order

If you are new:

  1. Rename Safety Model – mental model and workflow
  2. CLI Output Legend – how to read reports
  3. Confidence Levels – what gets applied and why

If you want to understand why something is Strict:

  1. Provenance – evidence and promotion rules
  2. Semantic Types – how types are inferred

If you want CI automation:

  1. CI Usage Guide

Quick Workflow

Typical safe rename:

gdshrapt rename old_name new_name --diff
gdshrapt rename old_name new_name --apply

Only Strict edits are applied by default.

To include contract strings:

gdshrapt rename old_name new_name --diff --include-contract-strings

Key Commands

  • rename – safe project‑wide rename
  • find-refs – semantic reference search
  • analyze – full diagnostics
  • check – CI exit codes
  • dead-code – unused symbols
  • type-coverage – annotation coverage

All commands use the same semantic model.

Why GDShrapt Is Different

Godot’s built‑in tools are syntax‑based.

GDShrapt is semantic and explainable:

  • understands inheritance across files
  • resolves signals in .tscn
  • tracks duck‑typed flows
  • filters by collision layers
  • separates unrelated same‑name symbols
  • shows proof for every edit

This enables safe refactoring in dynamic GDScript projects.

Next Steps

Start with:

➡ Rename Safety Model

Clone this wiki locally