Output Files
This page describes every file that eulix_parser writes, what it contains, and which tools read it.
Crate / path:
eulix-parser/src/output.rs,eulix-parser/src/views.rs
Language: Rust
Status: stable
Last verified against:ad744e9
Overview
A normal run writes eight JSON files, plus a checksum file and a cache directory. They are all written into the directory that contains your --output path, and the seven secondary files are named after the main file’s stem. With --output .eulix/kb.json, the files are .eulix/kb.json, .eulix/kb_index.json, .eulix/kb_call_graph.json, and so on. With the default knowledge_base.json, they are knowledge_base_index.json and so on.
The files are split by purpose, so that a tool needing only one kind of information can read only that file. A retrieval engine, for example, can load the call graph without loading every function’s signature.
Why It Exists
One giant file would force every consumer to load everything, and for a large repository that can be gigabytes. Splitting the data lets each consumer load what it needs, and lets the parser write each piece in a streaming way, straight from borrowed views of the in-memory data, without building a second copy.
How It Works
Phase 4 of the pipeline writes the files in this order: the knowledge base, then the index, summary, call graph, metrics, entry points, external dependencies and patterns. kb.json is assembled from the spill file. The others are serialized directly with serde_json, some pretty-printed and some compact.
Main Components
File (with default stem kb) |
Format | Contents |
|---|---|---|
kb.json |
compact | metadata and structure: for every file, its language, line count, functions (id, name, signature, parameters, return type, docstring, line range), classes (with methods, attributes, bases, decorators) and TODOs. |
kb_index.json |
compact | Lookup indices: functions by name (path:line), the callers of each callee, functions by tag, types by name, and files by category. |
kb_call_graph.json |
compact | Call-graph nodes and edges, plus a tags map (node id to tags) and a file_categories map (file to category). Each map is left out when empty. |
kb_summary.json |
pretty | Project name, file and line totals, languages, files grouped by category, key features from docstrings, entry points, dependencies split into standard library and third party, and detected patterns. |
kb_metrics.json |
pretty | The metadata and the 20 most complex functions, each with complexity, importance score and line range. |
kb_entry_points.json |
pretty | main-style functions, HTTP routes and CLI commands. |
kb_external_deps.json |
compact | Each external package, its source (stdlib or external), the files that import it, and the import count. |
kb_patterns.json |
pretty | Naming convention, structure type and architecture style. |
checksum.json.zst |
zstd-compressed JSON | Per-file size and modification time, and the project hash. Written during file discovery. |
parse_cache/ |
binary and zstd | The incremental cache. Private to the parser. |
With --no-analyze, only kb.json, checksum.json.zst and parse_cache/ are written.
Data In, Data Out
The shapes of the nodes, edges and other records are the types described in Knowledge Base Schema. The one important difference is kb.json: it is not a full dump of those types.
Key Algorithms
Why kb.json is smaller than the in-memory data
The problem. The full per-file structures include control flow, exception details, variables, call arguments and more. That data multiplies the file size, and most consumers never read it.
The approach. kb.json is written through FileDataSimpleView, FunctionSimpleView and ClassSimpleView. These are borrowed views that serialize only a chosen set of fields. Calls, called_by, control flow, exceptions, variables, tags, complexity, importance, imports and most language-specific data are left out. Call relationships are available in kb_call_graph.json instead, and tags in the call graph’s tags map.
Why this way. In version 0.7.7 this cut kb.json for the Linux kernel from about 2.06 GB to about 0.67 GB, and the README reports about 353 MB for v0.8.1. The analysis itself still uses the full relationships in memory, so nothing is lost for the call graph.
What to remember. Any consumer that used to read calls, called_by, control_flow, exceptions, is_async or tags from kb.json must read kb_call_graph.json or other artifacts instead.
Configuration
| Setting | Where | Default | What it does and when to change it |
|---|---|---|---|
--output |
command line | knowledge_base.json |
Sets the main file path, and therefore the directory and the stem of every other file. |
--no-analyze |
command line | off | Writes only kb.json. |
Usage Examples
eulix_parser -r ./proj -p 2 -o .eulix/kb.json
ls .eulix
Expected result: kb.json, kb_call_graph.json, kb_entry_points.json, kb_external_deps.json, kb_index.json, kb_metrics.json, kb_patterns.json, kb_summary.json, checksum.json.zst and the parse_cache directory.
Reading just the call graph:
jq '.edges | length' .eulix/kb_call_graph.json
Performance Notes
For the Linux kernel at v0.8.1, the README lists these sizes: kb.json about 353 MB, kb_index.json about 380 MB, kb_call_graph.json about 364 MB, kb_external_deps.json about 12 MB, kb_summary.json about 3 MB, and the rest under 50 KB each. Output generation took about 4 seconds. These are single-machine measurements, not guarantees.
Limitations
| Limitation | Why it happens | Workaround |
|---|---|---|
| Output paths are not separately configurable. | Everything derives from --output. |
Pick the output path with the directory you want. |
The seven secondary artifacts do not exist after --no-analyze. |
They come from the analysis phase. | Run without --no-analyze. |
kb.json has no imports. |
FileDataSimpleView omits them. |
Use kb_external_deps.json for external imports. |
The external-dependency version is always null. |
Versions live in manifests that are not read. | Read manifests separately. |
dependency_graph is not written anywhere. |
It is never populated. | None. |
Related Docs
- Parsing Pipeline: where each file is produced.
- Knowledge Base Schema: the underlying types.
- Spill to Disk: how
kb.jsonis assembled.