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.
Files changed (43) hide show
  1. wingbox-0.1.1/.gitignore +11 -0
  2. wingbox-0.1.1/CHANGELOG.md +135 -0
  3. wingbox-0.1.1/LICENSE +21 -0
  4. wingbox-0.1.1/PKG-INFO +366 -0
  5. wingbox-0.1.1/README.md +336 -0
  6. wingbox-0.1.1/pyproject.toml +62 -0
  7. wingbox-0.1.1/scripts/build_code_graph.py +2943 -0
  8. wingbox-0.1.1/scripts/build_infra_topology.py +854 -0
  9. wingbox-0.1.1/scripts/code_graph_search.py +2782 -0
  10. wingbox-0.1.1/scripts/git_descendants.py +124 -0
  11. wingbox-0.1.1/scripts/git_ignore.py +178 -0
  12. wingbox-0.1.1/scripts/lang/__init__.py +74 -0
  13. wingbox-0.1.1/scripts/lang/csharp/__init__.py +87 -0
  14. wingbox-0.1.1/scripts/lang/csharp/imports.py +54 -0
  15. wingbox-0.1.1/scripts/lang/csharp/parser.py +277 -0
  16. wingbox-0.1.1/scripts/lang/discovery.py +41 -0
  17. wingbox-0.1.1/scripts/lang/go/__init__.py +90 -0
  18. wingbox-0.1.1/scripts/lang/go/imports.py +117 -0
  19. wingbox-0.1.1/scripts/lang/go/parser.py +186 -0
  20. wingbox-0.1.1/scripts/lang/interface.py +199 -0
  21. wingbox-0.1.1/scripts/lang/java/__init__.py +91 -0
  22. wingbox-0.1.1/scripts/lang/java/imports.py +54 -0
  23. wingbox-0.1.1/scripts/lang/java/parser.py +245 -0
  24. wingbox-0.1.1/scripts/lang/pascal/__init__.py +73 -0
  25. wingbox-0.1.1/scripts/lang/pascal/imports.py +162 -0
  26. wingbox-0.1.1/scripts/lang/pascal/parser.py +519 -0
  27. wingbox-0.1.1/scripts/lang/purpose.py +488 -0
  28. wingbox-0.1.1/scripts/lang/python/__init__.py +76 -0
  29. wingbox-0.1.1/scripts/lang/python/imports.py +81 -0
  30. wingbox-0.1.1/scripts/lang/python/parser.py +159 -0
  31. wingbox-0.1.1/scripts/lang/ruby/__init__.py +95 -0
  32. wingbox-0.1.1/scripts/lang/ruby/imports.py +366 -0
  33. wingbox-0.1.1/scripts/lang/ruby/parser.py +456 -0
  34. wingbox-0.1.1/scripts/lang/rust/__init__.py +89 -0
  35. wingbox-0.1.1/scripts/lang/rust/imports.py +244 -0
  36. wingbox-0.1.1/scripts/lang/rust/parser.py +280 -0
  37. wingbox-0.1.1/scripts/lang/source.py +44 -0
  38. wingbox-0.1.1/scripts/lang/treesitter.py +27 -0
  39. wingbox-0.1.1/scripts/lang/typescript/__init__.py +102 -0
  40. wingbox-0.1.1/scripts/lang/typescript/imports.py +330 -0
  41. wingbox-0.1.1/scripts/lang/typescript/parser.py +409 -0
  42. wingbox-0.1.1/src/wingbox/__init__.py +1 -0
  43. wingbox-0.1.1/src/wingbox/cli.py +104 -0
@@ -0,0 +1,11 @@
1
+ # macOS
2
+ .DS_Store
3
+
4
+ # Python
5
+ __pycache__/
6
+ *.py[cod]
7
+ .ruff_cache/
8
+
9
+ # Generated code-graph artifacts (produced by scripts/build_code_graph.py)
10
+ .code_graph.sexp
11
+ .code_graph_cache.json
@@ -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
+ ![Wingbox: the code graph of a repository drawn as the structure of an aircraft wing, with the blast radius of one change highlighted](https://raw.githubusercontent.com/aileron-tech/wingbox/main/docs/assets/wingbox-social-preview.png)
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