wingbox 0.1.1__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- wingbox-0.1.1/.gitignore +11 -0
- wingbox-0.1.1/CHANGELOG.md +135 -0
- wingbox-0.1.1/LICENSE +21 -0
- wingbox-0.1.1/PKG-INFO +366 -0
- wingbox-0.1.1/README.md +336 -0
- wingbox-0.1.1/pyproject.toml +62 -0
- wingbox-0.1.1/scripts/build_code_graph.py +2943 -0
- wingbox-0.1.1/scripts/build_infra_topology.py +854 -0
- wingbox-0.1.1/scripts/code_graph_search.py +2782 -0
- wingbox-0.1.1/scripts/git_descendants.py +124 -0
- wingbox-0.1.1/scripts/git_ignore.py +178 -0
- wingbox-0.1.1/scripts/lang/__init__.py +74 -0
- wingbox-0.1.1/scripts/lang/csharp/__init__.py +87 -0
- wingbox-0.1.1/scripts/lang/csharp/imports.py +54 -0
- wingbox-0.1.1/scripts/lang/csharp/parser.py +277 -0
- wingbox-0.1.1/scripts/lang/discovery.py +41 -0
- wingbox-0.1.1/scripts/lang/go/__init__.py +90 -0
- wingbox-0.1.1/scripts/lang/go/imports.py +117 -0
- wingbox-0.1.1/scripts/lang/go/parser.py +186 -0
- wingbox-0.1.1/scripts/lang/interface.py +199 -0
- wingbox-0.1.1/scripts/lang/java/__init__.py +91 -0
- wingbox-0.1.1/scripts/lang/java/imports.py +54 -0
- wingbox-0.1.1/scripts/lang/java/parser.py +245 -0
- wingbox-0.1.1/scripts/lang/pascal/__init__.py +73 -0
- wingbox-0.1.1/scripts/lang/pascal/imports.py +162 -0
- wingbox-0.1.1/scripts/lang/pascal/parser.py +519 -0
- wingbox-0.1.1/scripts/lang/purpose.py +488 -0
- wingbox-0.1.1/scripts/lang/python/__init__.py +76 -0
- wingbox-0.1.1/scripts/lang/python/imports.py +81 -0
- wingbox-0.1.1/scripts/lang/python/parser.py +159 -0
- wingbox-0.1.1/scripts/lang/ruby/__init__.py +95 -0
- wingbox-0.1.1/scripts/lang/ruby/imports.py +366 -0
- wingbox-0.1.1/scripts/lang/ruby/parser.py +456 -0
- wingbox-0.1.1/scripts/lang/rust/__init__.py +89 -0
- wingbox-0.1.1/scripts/lang/rust/imports.py +244 -0
- wingbox-0.1.1/scripts/lang/rust/parser.py +280 -0
- wingbox-0.1.1/scripts/lang/source.py +44 -0
- wingbox-0.1.1/scripts/lang/treesitter.py +27 -0
- wingbox-0.1.1/scripts/lang/typescript/__init__.py +102 -0
- wingbox-0.1.1/scripts/lang/typescript/imports.py +330 -0
- wingbox-0.1.1/scripts/lang/typescript/parser.py +409 -0
- wingbox-0.1.1/src/wingbox/__init__.py +1 -0
- wingbox-0.1.1/src/wingbox/cli.py +104 -0
wingbox-0.1.1/.gitignore
ADDED
|
@@ -0,0 +1,135 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## 2026-11-15
|
|
4
|
+
|
|
5
|
+
### Changes
|
|
6
|
+
|
|
7
|
+
- Added the `wingbox` command and the Python package metadata (version 0.1.1):
|
|
8
|
+
`wingbox build [PATH]` builds the code graph and every query command runs as
|
|
9
|
+
`wingbox <command>`, for example `wingbox impact path/to/file.py`. Install it
|
|
10
|
+
with `pipx install git+https://github.com/aileron-tech/wingbox`.
|
|
11
|
+
- Added the `impact <file|id> [depth] [--sexp]` command: the modules that
|
|
12
|
+
depend on a file, grouped by shortest distance, and the files to read first.
|
|
13
|
+
It accepts an ordinary file path, prints readable text by default and
|
|
14
|
+
compact S-expression facts with `--sexp`.
|
|
15
|
+
- Renamed the project and the skill from `codespaces` to `wingbox`; the
|
|
16
|
+
repository is now `aileron-tech/wingbox`.
|
|
17
|
+
- Replaced the term "belief map" with "code graph" in the documentation, the
|
|
18
|
+
scripts and the generated files: `scripts/build_belief_map.py` is now
|
|
19
|
+
`scripts/build_code_graph.py`, `scripts/belief_search.py` is now
|
|
20
|
+
`scripts/code_graph_search.py`, `.belief_map.sexp` is now `.code_graph.sexp`
|
|
21
|
+
and `.belief_map_cache.json` is now `.code_graph_cache.json`. The header of
|
|
22
|
+
the generated S-expression file is now `code-graph`.
|
|
23
|
+
- Existing maps are not read under the old names: rebuild the code graph once,
|
|
24
|
+
delete the old generated files, and update agent instructions and ignore
|
|
25
|
+
rules that mention the old script or file names.
|
|
26
|
+
|
|
27
|
+
## 2026-08-11
|
|
28
|
+
|
|
29
|
+
### Changes
|
|
30
|
+
|
|
31
|
+
- Added dependency-free Free Pascal and Lazarus indexing for units, programs,
|
|
32
|
+
imports, includes, types, inheritance, methods, and routines.
|
|
33
|
+
- Applied repository Git ignore rules to source, language configuration,
|
|
34
|
+
package, and LSP project discovery, including tracked paths matched by
|
|
35
|
+
`.gitignore`.
|
|
36
|
+
|
|
37
|
+
### Fixes
|
|
38
|
+
|
|
39
|
+
- Resolved Rust module IDs to physical `.rs` or nested `mod.rs` files in
|
|
40
|
+
source-aware search output.
|
|
41
|
+
- Preserved conservative dependency edges from bare `use super::*` imports to
|
|
42
|
+
their parent module, including crate-root parents.
|
|
43
|
+
- Rejected path-shaped `--exclude-dir` values consistently across POSIX and
|
|
44
|
+
Windows syntax.
|
|
45
|
+
- Applied caller exclusions to TypeScript alias discovery instead of retaining
|
|
46
|
+
a separate internal directory list.
|
|
47
|
+
|
|
48
|
+
## 2026-08-09
|
|
49
|
+
|
|
50
|
+
### Changes
|
|
51
|
+
|
|
52
|
+
- Added repeatable `--exclude-dir NAME` options so callers can omit tracked
|
|
53
|
+
source snapshots, generated fixtures, and similar non-product trees from
|
|
54
|
+
source, package, project, and LSP discovery.
|
|
55
|
+
- Included caller-provided directory exclusions in cache provenance so changing
|
|
56
|
+
the active exclusion set forces a safe rebuild.
|
|
57
|
+
|
|
58
|
+
## 2026-08-08
|
|
59
|
+
|
|
60
|
+
### Changes
|
|
61
|
+
|
|
62
|
+
- Corrected the README and GitHub description to present AI coding agents as
|
|
63
|
+
the audience rather than another supported language.
|
|
64
|
+
- Added dynamically loaded Ruby and Ruby on Rails indexing for `.rb` and
|
|
65
|
+
`.rake` files, including classes, modules, instance and singleton methods,
|
|
66
|
+
inheritance, explicit requires, and Ruby LSP metadata.
|
|
67
|
+
- Added conservative Rails/Zeitwerk dependency resolution for application and
|
|
68
|
+
custom autoload roots, project acronyms, concerns, associations, callbacks,
|
|
69
|
+
jobs, mailers, and impacted specs.
|
|
70
|
+
- Added official Tree-sitter support for C#, Java, and Go source discovery,
|
|
71
|
+
entity extraction, local dependency resolution, project recognition, and LSP
|
|
72
|
+
metadata.
|
|
73
|
+
- Made Tree-sitter grammars optional and language-scoped: the builder loads only
|
|
74
|
+
detected languages and reports exact per-language install commands when a
|
|
75
|
+
required parser is absent or incompatible.
|
|
76
|
+
- Added a language-neutral adapter contract so source discovery, parsing,
|
|
77
|
+
module identity, dependency resolution, output, and LSP metadata can be
|
|
78
|
+
extended without adding language branches to graph orchestration.
|
|
79
|
+
- Added Rust source discovery, Tree-sitter entity extraction, Cargo workspace
|
|
80
|
+
import resolution, and rust-analyzer metadata.
|
|
81
|
+
- Reworked the README around natural code-search questions, a shorter quick
|
|
82
|
+
start, supported languages, common impact-analysis workflows, and honest
|
|
83
|
+
accuracy limits.
|
|
84
|
+
- Expanded the skill and repository descriptions with architecture-aware code
|
|
85
|
+
search, dependency graph, Rust, monorepo, and AI coding-agent discovery terms.
|
|
86
|
+
|
|
87
|
+
### Fixes
|
|
88
|
+
|
|
89
|
+
- Prevented ambiguous or reopened Ruby constants, polymorphic associations, and
|
|
90
|
+
RSpec `include` matchers from creating guessed Rails dependency edges.
|
|
91
|
+
- Resolved inherited Ruby constants and `through` associations with explicit
|
|
92
|
+
`source` models, and preserved Rails relation types in map facts.
|
|
93
|
+
- Excluded standard .NET `bin`/`obj` outputs and Go `vendor` dependencies from
|
|
94
|
+
source discovery.
|
|
95
|
+
- Prevented unused C# namespace and Java wildcard imports from creating guessed
|
|
96
|
+
dependency edges based only on package cardinality.
|
|
97
|
+
- Prevented unused C#, Java, Go, Rust, or TypeScript grammars from blocking
|
|
98
|
+
Python-only and other single-language map builds.
|
|
99
|
+
- Rust files, local Cargo modules, workspace crate dependencies, and imported
|
|
100
|
+
Rust entity references are now represented in generated architecture maps.
|
|
101
|
+
|
|
102
|
+
## 2026-07-30
|
|
103
|
+
|
|
104
|
+
### Changes
|
|
105
|
+
|
|
106
|
+
- Required an explicit absolute project root for map builds and added custom
|
|
107
|
+
output/map-root query options.
|
|
108
|
+
- Added pinned Python dependencies and documented the supported TypeScript and
|
|
109
|
+
safe search-pattern contracts.
|
|
110
|
+
|
|
111
|
+
### Fixes
|
|
112
|
+
|
|
113
|
+
- Made `CALLS_API` resolution deterministic by following explicit imports and
|
|
114
|
+
failing closed on ambiguous unqualified providers.
|
|
115
|
+
- Rejected colliding module IDs before publication instead of silently
|
|
116
|
+
discarding source files.
|
|
117
|
+
- Versioned incremental caches by schema and builder provenance.
|
|
118
|
+
- Published cache and map files atomically under a per-project writer lock.
|
|
119
|
+
- Rejected malformed maps, unsafe search patterns, and invalid query depths
|
|
120
|
+
with structured diagnostics.
|
|
121
|
+
- Preserved source paths containing spaces and recognized TypeScript
|
|
122
|
+
`import = require()` plus literal template imports.
|
|
123
|
+
|
|
124
|
+
## 2026-07-14
|
|
125
|
+
|
|
126
|
+
### Changes
|
|
127
|
+
|
|
128
|
+
- Added dependency discovery for TypeScript re-exports, literal dynamic imports, and literal CommonJS requires.
|
|
129
|
+
- Added project-scoped TypeScript path aliases and exact package self-import resolution.
|
|
130
|
+
|
|
131
|
+
### Fixes
|
|
132
|
+
|
|
133
|
+
- Fixed missing dependency edges from TSX files.
|
|
134
|
+
- Fixed path aliases with the same name resolving through an unrelated monorepo package.
|
|
135
|
+
- Fixed exact path aliases and package self-imports being omitted from architecture maps.
|
wingbox-0.1.1/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 AILERON TECHNOLOGIES
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
wingbox-0.1.1/PKG-INFO
ADDED
|
@@ -0,0 +1,366 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: wingbox
|
|
3
|
+
Version: 0.1.1
|
|
4
|
+
Summary: Code graph and blast radius analysis for AI coding agents
|
|
5
|
+
Project-URL: Homepage, https://github.com/aileron-tech/wingbox
|
|
6
|
+
Project-URL: Repository, https://github.com/aileron-tech/wingbox
|
|
7
|
+
Project-URL: Changelog, https://github.com/aileron-tech/wingbox/blob/main/CHANGELOG.md
|
|
8
|
+
Project-URL: Issues, https://github.com/aileron-tech/wingbox/issues
|
|
9
|
+
Author: Aileron Technologies
|
|
10
|
+
License-Expression: MIT
|
|
11
|
+
License-File: LICENSE
|
|
12
|
+
Keywords: ai-coding-agents,blast-radius,claude-code,code-graph,code-search,codex,dependency-graph,impact-analysis,static-analysis,tree-sitter
|
|
13
|
+
Classifier: Development Status :: 4 - Beta
|
|
14
|
+
Classifier: Environment :: Console
|
|
15
|
+
Classifier: Intended Audience :: Developers
|
|
16
|
+
Classifier: Operating System :: MacOS
|
|
17
|
+
Classifier: Operating System :: POSIX :: Linux
|
|
18
|
+
Classifier: Programming Language :: Python :: 3
|
|
19
|
+
Classifier: Topic :: Software Development :: Quality Assurance
|
|
20
|
+
Requires-Python: >=3.11
|
|
21
|
+
Requires-Dist: pyyaml==6.0.3
|
|
22
|
+
Requires-Dist: tree-sitter-c-sharp==0.23.5
|
|
23
|
+
Requires-Dist: tree-sitter-go==0.25.0
|
|
24
|
+
Requires-Dist: tree-sitter-java==0.23.5
|
|
25
|
+
Requires-Dist: tree-sitter-ruby==0.23.1
|
|
26
|
+
Requires-Dist: tree-sitter-rust==0.24.2
|
|
27
|
+
Requires-Dist: tree-sitter-typescript==0.23.2
|
|
28
|
+
Requires-Dist: tree-sitter==0.25.2
|
|
29
|
+
Description-Content-Type: text/markdown
|
|
30
|
+
|
|
31
|
+
# Wingbox: Code Graph and Blast Radius Analysis for AI Coding Agents
|
|
32
|
+
|
|
33
|
+

|
|
34
|
+
|
|
35
|
+
> Wingbox builds a local **code graph** of your repository so that AI coding
|
|
36
|
+
> agents and developers can see dependencies, call flows, architecture
|
|
37
|
+
> boundaries and the **blast radius** of a change before editing code.
|
|
38
|
+
> It works as an agent skill in Claude Code and Codex and supports Python,
|
|
39
|
+
> TypeScript, Rust, C#, Java, Go, Ruby, Rails, Free Pascal, and Lazarus.
|
|
40
|
+
>
|
|
41
|
+
> **Install the agent skill:** `npx skills add aileron-tech/wingbox` | [skills.sh](https://skills.sh)
|
|
42
|
+
>
|
|
43
|
+
> **Install the command:** `pipx install git+https://github.com/aileron-tech/wingbox`
|
|
44
|
+
>
|
|
45
|
+
> **Release notes:** [Changelog](CHANGELOG.md)
|
|
46
|
+
>
|
|
47
|
+
> **Note:** Wingbox was formerly published as `codespaces`. The skill, the
|
|
48
|
+
> scripts and the generated files were renamed on 2026-11-15; see the
|
|
49
|
+
> [Changelog](CHANGELOG.md) for the old and new names.
|
|
50
|
+
|
|
51
|
+
Understand a large codebase before you change it. Wingbox is an
|
|
52
|
+
architecture-aware code search and impact analysis tool for Python, TypeScript, TSX, Rust, C#,
|
|
53
|
+
Java, Go, Ruby, Ruby on Rails, Free Pascal, and Lazarus repositories. It helps
|
|
54
|
+
developers and AI coding agents find the right module, trace dependencies,
|
|
55
|
+
measure change impact, and read only the source files that matter.
|
|
56
|
+
|
|
57
|
+
Use it for codebase architecture discovery, dependency graph search, blast-radius
|
|
58
|
+
analysis, call-flow tracing, monorepo navigation, and safer AI-assisted coding.
|
|
59
|
+
|
|
60
|
+
Everything runs on your machine. The code graph is built by deterministic
|
|
61
|
+
static parsing: no LLM call, no embeddings, no vector database, and no network
|
|
62
|
+
access to build or query it.
|
|
63
|
+
|
|
64
|
+
## What can Wingbox answer?
|
|
65
|
+
|
|
66
|
+
- Where is authentication, billing, upload, or another feature implemented?
|
|
67
|
+
- Which modules depend on this service, class, function, or type?
|
|
68
|
+
- What could break if I change this file?
|
|
69
|
+
- Which two or three files should I read before fixing a bug?
|
|
70
|
+
- How does a request or data value move through the system?
|
|
71
|
+
- Does this dependency cross an architecture boundary?
|
|
72
|
+
- Which Rails models, services, jobs, mailers, concerns, and specs are affected?
|
|
73
|
+
- Can you draw a call-flow, data-flow, or sequence diagram from the code?
|
|
74
|
+
|
|
75
|
+
Instead of searching a repository one text match at a time, Wingbox turns code
|
|
76
|
+
into a queryable code graph of modules, entities, imports, references, call
|
|
77
|
+
relationships, architecture layers, and infrastructure connections.
|
|
78
|
+
|
|
79
|
+
## What is a code graph?
|
|
80
|
+
|
|
81
|
+
A code graph describes a codebase as facts instead of text. Modules, classes,
|
|
82
|
+
functions and types are nodes; imports, references, data flows, calls and
|
|
83
|
+
architecture layers are edges. Wingbox writes the graph to `.code_graph.sexp`
|
|
84
|
+
as plain S-expression facts, so the bundled query tool and ordinary text search
|
|
85
|
+
can both read it.
|
|
86
|
+
|
|
87
|
+
## What is blast radius analysis?
|
|
88
|
+
|
|
89
|
+
The blast radius of a change is everything that depends, directly or
|
|
90
|
+
transitively, on the code you are about to edit. Wingbox computes it from the
|
|
91
|
+
reverse dependencies in the code graph. `impact path/to/file` prints the
|
|
92
|
+
dependents by depth and the files to read first; `rdeps` and `boundary` give
|
|
93
|
+
the same facts as a tree and as a change boundary.
|
|
94
|
+
|
|
95
|
+
```text
|
|
96
|
+
$ python3 scripts/code_graph_search.py impact scripts/lang/treesitter.py
|
|
97
|
+
|
|
98
|
+
Impact of changing scripts/lang/treesitter.py
|
|
99
|
+
direct dependents 4
|
|
100
|
+
within 2 hops 11
|
|
101
|
+
|
|
102
|
+
Depth 1
|
|
103
|
+
scripts/lang/csharp/parser.py imports
|
|
104
|
+
scripts/lang/go/parser.py imports
|
|
105
|
+
scripts/lang/java/parser.py imports
|
|
106
|
+
scripts/lang/ruby/parser.py imports
|
|
107
|
+
...
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
The text form is for people. Agents add `--sexp` to get the same facts as
|
|
111
|
+
compact S-expressions.
|
|
112
|
+
|
|
113
|
+
## Quick start for AI coding agents
|
|
114
|
+
|
|
115
|
+
Install the skill:
|
|
116
|
+
|
|
117
|
+
```bash
|
|
118
|
+
npx skills add aileron-tech/wingbox
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
Then ask your agent a natural question:
|
|
122
|
+
|
|
123
|
+
```text
|
|
124
|
+
Use the Wingbox skill before reading source.
|
|
125
|
+
Find where file uploads are handled, analyze that module, show its dependencies
|
|
126
|
+
and blast radius, then list only the boundary files needed for the change.
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
Wingbox works with Codex, Claude Code, and other clients that support Agent
|
|
130
|
+
Skills.
|
|
131
|
+
|
|
132
|
+
## Quick start from the command line
|
|
133
|
+
|
|
134
|
+
Install the `wingbox` command (Python 3.11 or newer, macOS or Linux):
|
|
135
|
+
|
|
136
|
+
```bash
|
|
137
|
+
pipx install git+https://github.com/aileron-tech/wingbox
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
Or run it without installing:
|
|
141
|
+
|
|
142
|
+
```bash
|
|
143
|
+
uvx --from git+https://github.com/aileron-tech/wingbox wingbox --help
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
Build the code graph of a project, then ask what a change will break:
|
|
147
|
+
|
|
148
|
+
```bash
|
|
149
|
+
cd /path/to/project
|
|
150
|
+
wingbox build .
|
|
151
|
+
wingbox impact path/to/file.py
|
|
152
|
+
wingbox quick "file upload"
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
`wingbox build [PATH]` accepts the builder options described below, and every
|
|
156
|
+
query command in [Common code searches](#common-code-searches) is available as
|
|
157
|
+
`wingbox <command>`. The command installs the parsers for all supported
|
|
158
|
+
languages and finds `.code_graph.sexp` in the current directory or its parents.
|
|
159
|
+
|
|
160
|
+
### Running the scripts from a clone
|
|
161
|
+
|
|
162
|
+
Clone the repository:
|
|
163
|
+
|
|
164
|
+
```bash
|
|
165
|
+
git clone https://github.com/aileron-tech/wingbox.git
|
|
166
|
+
cd wingbox
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
Build the code graph for an explicit project directory:
|
|
170
|
+
|
|
171
|
+
```bash
|
|
172
|
+
python3 scripts/build_code_graph.py --root /absolute/path/to/project
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
Exclude tracked source snapshots or generated fixture trees by directory name.
|
|
176
|
+
The option is repeatable and applies at any depth:
|
|
177
|
+
|
|
178
|
+
```bash
|
|
179
|
+
python3 scripts/build_code_graph.py \
|
|
180
|
+
--root /absolute/path/to/project \
|
|
181
|
+
--exclude-dir review-bundles \
|
|
182
|
+
--exclude-dir generated-fixtures
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
When the target is inside a Git worktree, the builder also honors repository
|
|
186
|
+
ignore rules through Git itself. This applies to source files and language
|
|
187
|
+
configuration such as `tsconfig.json`, `package.json`, `Cargo.toml`, `go.mod`,
|
|
188
|
+
and LSP project discovery. Tracked snapshot paths that still match
|
|
189
|
+
`.gitignore` are excluded as well.
|
|
190
|
+
|
|
191
|
+
Parser packages are loaded only for languages found in that project. Python
|
|
192
|
+
needs no extra parser package. If another detected language is not installed,
|
|
193
|
+
the builder stops before publishing and prints its exact install command, for
|
|
194
|
+
example:
|
|
195
|
+
|
|
196
|
+
```bash
|
|
197
|
+
python3 -m pip install -r requirements/typescript.txt
|
|
198
|
+
python3 -m pip install -r requirements/csharp.txt
|
|
199
|
+
python3 -m pip install -r requirements/ruby.txt
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
Install only the files for languages you use, then run the same build command
|
|
203
|
+
again. `requirements.txt` contains the separate infrastructure-topology
|
|
204
|
+
dependency.
|
|
205
|
+
|
|
206
|
+
Run a relevant search and get the first matching module with its full context:
|
|
207
|
+
|
|
208
|
+
```bash
|
|
209
|
+
python3 scripts/code_graph_search.py \
|
|
210
|
+
--map /absolute/path/to/project/.code_graph.sexp \
|
|
211
|
+
--root /absolute/path/to/project \
|
|
212
|
+
quick "file upload"
|
|
213
|
+
```
|
|
214
|
+
|
|
215
|
+
The code graph is written to `.code_graph.sexp`. Wingbox does not modify the
|
|
216
|
+
source files it analyzes.
|
|
217
|
+
|
|
218
|
+
## Common code searches
|
|
219
|
+
|
|
220
|
+
| Goal | Command |
|
|
221
|
+
|---|---|
|
|
222
|
+
| Find and analyze a feature | `quick "payments"` |
|
|
223
|
+
| Search for a module | `search "payment.*service"` |
|
|
224
|
+
| See full module context | `analyze path/to/module` |
|
|
225
|
+
| Find files needed for a change | `boundary path/to/module --files-only` |
|
|
226
|
+
| Trace dependencies | `deps path/to/module 2` |
|
|
227
|
+
| See what a change will break | `impact path/to/file.py` |
|
|
228
|
+
| Measure blast radius as a tree | `rdeps path/to/module 2` |
|
|
229
|
+
| Find a class, module, interface, enum, or type | `find_type OrderService` |
|
|
230
|
+
| Find a function or method | `find_function createOrder` |
|
|
231
|
+
| Find callers | `find_callers createOrder 2` |
|
|
232
|
+
| Trace a call path | `find_callchain handleRequest createOrder 5` |
|
|
233
|
+
| Search inside function bodies | `grep_functions "validate.*input"` |
|
|
234
|
+
| Check architecture boundaries | `boundaries all` |
|
|
235
|
+
| Check naming conventions | `invariants all` |
|
|
236
|
+
| Inspect changed functions | `diff_functions HEAD~1` |
|
|
237
|
+
|
|
238
|
+
Pass the same `--map` and `--root` options shown in the quick start when the map
|
|
239
|
+
is outside the current directory.
|
|
240
|
+
|
|
241
|
+
## Supported languages and projects
|
|
242
|
+
|
|
243
|
+
| Language | What is indexed |
|
|
244
|
+
|---|---|
|
|
245
|
+
| Python | Modules, imports, classes, functions, methods, inheritance, and references |
|
|
246
|
+
| TypeScript and TSX | Imports, re-exports, classes, interfaces, functions, types, decorators, aliases, and references |
|
|
247
|
+
| Rust | Cargo crates, modules, `use` dependencies, structs, traits, enums, functions, implementations, and methods |
|
|
248
|
+
| C# | Namespaces, types, interfaces, records, enums, methods, attributes, inheritance, and local type dependencies |
|
|
249
|
+
| Java | Packages, imports, classes, interfaces, records, enums, methods, annotations, inheritance, and local type dependencies |
|
|
250
|
+
| Go | Modules, packages, imports, structs, interfaces, functions, constants, variables, receiver methods, and local package dependencies |
|
|
251
|
+
| Ruby and Rails | Ruby classes, modules, instance and singleton methods, inheritance, requires, Zeitwerk constants, concerns, associations, callbacks, jobs, mailers, and impacted specs |
|
|
252
|
+
| Free Pascal and Lazarus | Units, programs, uses/includes, classes, records, interfaces, inheritance, methods, and routines |
|
|
253
|
+
|
|
254
|
+
Wingbox is designed for single repositories and monorepos. It understands
|
|
255
|
+
Python project roots, TypeScript configuration and package aliases, Cargo package
|
|
256
|
+
names and local Rust crate dependencies, .NET solutions and projects, Maven and
|
|
257
|
+
Gradle projects, Go modules and workspaces, and Rails application/autoload
|
|
258
|
+
roots with project acronyms.
|
|
259
|
+
|
|
260
|
+
Pascal dependencies resolve by case-insensitive unit identity and explicit
|
|
261
|
+
`UnitName in 'path.pas'` paths, then by a unique same-directory unit. Other
|
|
262
|
+
ambiguous unit names remain unlinked, compiler conditionals are indexed
|
|
263
|
+
conservatively, and Pascal does not use LSP enrichment. Automatic Pascal copies
|
|
264
|
+
under Lazarus `backup/` directories are excluded without excluding other
|
|
265
|
+
supported languages stored under the same path.
|
|
266
|
+
|
|
267
|
+
It can also map infrastructure relationships from Kustomize, Helm, and Terraform.
|
|
268
|
+
|
|
269
|
+
## Ruby and Rails dependency search
|
|
270
|
+
|
|
271
|
+
Rails code often depends on constants without an explicit `require`. Wingbox
|
|
272
|
+
builds a project-local constant index and follows conservative Zeitwerk naming
|
|
273
|
+
rules, so changing a shared model, concern, service, job, or mailer can reveal
|
|
274
|
+
its likely callers and affected specs.
|
|
275
|
+
|
|
276
|
+
The default Ruby map does not boot Rails. Ambiguous reopened constants remain
|
|
277
|
+
unlinked, polymorphic associations stay open, and external or dynamic Ruby
|
|
278
|
+
calls are not guessed. This keeps blast-radius results useful without executing
|
|
279
|
+
application code.
|
|
280
|
+
|
|
281
|
+
## A simple workflow
|
|
282
|
+
|
|
283
|
+
1. Build the map for the exact repository you want to understand.
|
|
284
|
+
2. Search for a feature, type, function, or module instead of guessing a path.
|
|
285
|
+
3. Analyze the returned module to see dependencies, reverse dependencies, layers,
|
|
286
|
+
references, and the minimal boundary files.
|
|
287
|
+
4. Read only those files and make the change.
|
|
288
|
+
5. Rebuild the map after structural changes and check boundaries again.
|
|
289
|
+
|
|
290
|
+
This keeps code exploration focused and gives AI coding agents less irrelevant
|
|
291
|
+
context, clearer ownership, and better evidence for implementation decisions.
|
|
292
|
+
|
|
293
|
+
## Call graphs and diagrams
|
|
294
|
+
|
|
295
|
+
The default static analysis builds import, reference, data-flow, and architecture
|
|
296
|
+
edges. Add `--lsp` when supported language servers are installed to enrich the map
|
|
297
|
+
with precise call-site information:
|
|
298
|
+
|
|
299
|
+
```bash
|
|
300
|
+
python3 scripts/build_code_graph.py \
|
|
301
|
+
--root /absolute/path/to/project \
|
|
302
|
+
--lsp
|
|
303
|
+
```
|
|
304
|
+
|
|
305
|
+
You can then ask an agent to render Mermaid diagrams from the graph:
|
|
306
|
+
|
|
307
|
+
```text
|
|
308
|
+
Use Wingbox to trace the file upload flow and render a Mermaid sequence diagram.
|
|
309
|
+
Base every participant and edge on the code-graph facts.
|
|
310
|
+
```
|
|
311
|
+
|
|
312
|
+
## Accuracy and limits
|
|
313
|
+
|
|
314
|
+
Wingbox is an architecture and impact-analysis tool, not a compiler replacement.
|
|
315
|
+
The default map comes from deterministic static parsing. Optional LSP enrichment
|
|
316
|
+
adds call hierarchy and reference detail when the relevant language server is
|
|
317
|
+
available.
|
|
318
|
+
|
|
319
|
+
For generated imports, runtime dependency injection, reflection, or framework
|
|
320
|
+
behavior that is not explicit in source, verify the result against the running
|
|
321
|
+
application or the owning framework.
|
|
322
|
+
|
|
323
|
+
## FAQ
|
|
324
|
+
|
|
325
|
+
### Does Wingbox send my code anywhere?
|
|
326
|
+
|
|
327
|
+
No. The code graph is built and queried locally by deterministic static
|
|
328
|
+
parsing. Building and querying need no LLM, no embeddings, no vector database
|
|
329
|
+
and no network access.
|
|
330
|
+
|
|
331
|
+
### Which AI coding agents does Wingbox work with?
|
|
332
|
+
|
|
333
|
+
Codex, Claude Code, and other clients that support Agent Skills. The scripts
|
|
334
|
+
can also be run directly from the command line.
|
|
335
|
+
|
|
336
|
+
### How is a code graph different from text search with grep or ripgrep?
|
|
337
|
+
|
|
338
|
+
Text search finds lines that match a pattern. A code graph answers structural
|
|
339
|
+
questions: which modules depend on this one, what a change can break, which
|
|
340
|
+
architecture boundary a dependency crosses, and which few files are worth
|
|
341
|
+
reading first.
|
|
342
|
+
|
|
343
|
+
### Does Wingbox replace a compiler or a language server?
|
|
344
|
+
|
|
345
|
+
No. It is an architecture and impact-analysis tool. Optional LSP enrichment
|
|
346
|
+
adds call hierarchy and reference detail; behavior that is not explicit in
|
|
347
|
+
source, such as generated imports, runtime dependency injection or reflection,
|
|
348
|
+
must be verified against the running application.
|
|
349
|
+
|
|
350
|
+
### Which languages are supported?
|
|
351
|
+
|
|
352
|
+
Python, TypeScript and TSX, Rust, C#, Java, Go, Ruby and Ruby on Rails, Free
|
|
353
|
+
Pascal and Lazarus, plus infrastructure relationships from Kustomize, Helm and
|
|
354
|
+
Terraform.
|
|
355
|
+
|
|
356
|
+
## Project resources
|
|
357
|
+
|
|
358
|
+
- [Skill workflow and complete command reference](SKILL.md)
|
|
359
|
+
- [S-expression map format](references/sexp-notation.md)
|
|
360
|
+
- [Composable query language](references/scheme-queries.md)
|
|
361
|
+
- [Changelog](CHANGELOG.md)
|
|
362
|
+
- [Completion log](LOG.md)
|
|
363
|
+
|
|
364
|
+
## License
|
|
365
|
+
|
|
366
|
+
MIT
|