Code structure

Guide for navigating the rgctl workspace: how crates are segmented, how they connect, and where to put new functionality so it is not duplicated elsewhere.

1. Crate segmentation (overview)

flowchart TB
    subgraph entry["Entry & CLI"]
        RB["rgctl<br/>(binary + src/cli)"]
    end

    subgraph facade["Facade"]
        CORE["rgctl-core<br/>re-exports workspace API"]
    end

    subgraph orchestration["Orchestration"]
        PIPE["rgctl-pipeline<br/>discover / index repo"]
        INC["rgctl-incremental<br/>file tracker, deltas"]
    end

    subgraph extraction_layer["Extraction"]
        EXT["rgctl-extraction<br/>discover files, build graph"]
    end

    subgraph plugins["Plugin system"]
        API["rgctl-plugin-api<br/>LanguagePlugin trait"]
        HELP["rgctl-plugin-helpers<br/>tree-sitter helpers"]
        RUNTIME["rgctl-lang-runtime<br/>generic TS/regex plugins"]
        CFG["rgctl-config-formats<br/>yaml/json/toml/properties"]
        REG["rgctl-registry<br/>LanguageRegistry"]
        LANGS["rgctl-languages<br/>all Tier 1 plugins"]
        LANG["rgctl-lang-*<br/>(language implementations)"]
    end

    subgraph storage["Graph storage"]
        GRAPH["rgctl-graph<br/>CodeGraph, schema, snapshots"]
    end

    subgraph analytics["Graph analytics"]
        ANALYSIS["rgctl-analysis<br/>blast-radius, CFG/PDG, taint, …"]
    end

    subgraph query_export["Query & output"]
        GQL["rgctl-gql<br/>Cypher-like graph queries"]
        EXPORT["rgctl-export<br/>HTML, Mermaid, GraphML, DOT"]
    end

    subgraph cross_cutting["Cross-cutting"]
        SEM["rgctl-semantic<br/>signatures, IDL, types"]
        RULES["rgctl-rules<br/>labeling rule engine"]
        SEC["rgctl-security<br/>CVE / vulnerability patterns"]
        PROJ["rgctl-project-config<br/>.rgctl config, secrets, drift"]
        ERR["rgctl-error<br/>shared Error type"]
        MACROS["rgctl-macros<br/>plugin derive macros"]
    end

    RB --> CORE
    RB --> PIPE
    RB --> ANALYSIS
    RB --> GQL
    RB --> EXPORT

    CORE --> GRAPH
    CORE --> ANALYSIS
    CORE --> PIPE
    CORE --> EXT
    CORE --> GQL
    CORE --> EXPORT
    CORE --> INC
    CORE --> REG
    CORE --> SEM
    CORE --> RULES
    CORE --> SEC
    CORE --> PROJ

    PIPE --> EXT
    PIPE --> GRAPH
    PIPE --> REG

    EXT --> GRAPH
    EXT --> API

    REG --> API
    REG --> CFG
    LANGS --> REG
    LANGS --> LANG
    LANG --> API
    LANG --> HELP
    LANG --> RUNTIME

    ANALYSIS --> GRAPH
    ANALYSIS --> ERR

    GQL --> GRAPH
    GQL --> ANALYSIS

    EXPORT --> GRAPH

    INC --> GRAPH

    SEM --> API
    RULES --> GRAPH
    SEC --> GRAPH
    PROJ --> EXT

    GRAPH --> ERR
    PIPE --> ERR
    EXT --> ERR
    GQL --> ERR

    MACROS -.-> LANG

Reading the diagram: Data generally flows down and left-to-right during discover: registry → extraction → graph → analysis → persisted .rgctl/ artifacts. Query commands (blast-radius, gql, inspect) read the graph and analysis layers without re-parsing source unless slicing or CFG is required.

2. Segmented design (details)

Design principles

Layer responsibilities

Entry (rgctl root crate)

• src/main.rs — process entry, dispatches to CLI.
• src/cli/ — subcommands: discover, blast-radius, serve, gql, slice, inspect, metrics, semantic, communities, cpg, check, export.
• src/cli/http_serve.rs — serve: dashboard + POST /api/query (foreground HTTP for one repo).
• src/cli/migrate_cache.rs — migrate-cache: copy legacy ~/.rgctl/cache/ into in-repo .rgctl/.
• src/cli/*_output.rs — typed JSON serializers (blast_radius_output, discover_output, gql_output, …). Commands assemble domain results from workspace crates and serialize here; do not embed algorithm logic in output modules.
• src/languages/ — wires the active language bundle into a LanguageRegistry at runtime.
• Re-exports rgctl-core for library users (use rgctl::analysis, etc.).

Put new user-facing commands here; implement behavior in the appropriate workspace crate.

Facade (rgctl-core)

Stable “library surface” for embedders: re-exports graph, analysis, pipeline, export, gql, incremental, registry, rules, semantic, security, project-config. Also hosts memory monitoring helpers used during discover.

If you add a new workspace crate that external tools should use, export it through rgctl-core (and optionally the root rgctl crate).

Plugin system

Language crates (rgctl-lang-*): One crate per language or config dialect (e.g. rgctl-lang-java, rgctl-lang-github-actions). Each registers a plugin with the registry. Do not add parsing logic for an existing language in another language crate — extend the relevant rgctl-lang-* plugin instead. For Tier 1 / full analysis parity, see tier-1-language-support.md.

Ingestion pipeline

Discover flow: CLI discover → discover_impl → ProcessingPipeline → plugins → CodeGraph → analysis passes → write .rgctl/.

Graph storage (rgctl-graph)

• CodeGraph — high-level API over the backend.
• backend/ — MemoryBackend, indexes, batch insert, query.
• schema/ — Node, Edge, NodeType, EdgeType.
• snapshot/ — columnar v2 mmap snapshots (graph.snapshot.bin, 64B node / 40B edge rows + string pool); v1 bincode still readable. SnapshotNodeStore, ColumnarGraphMmap.
• export/ / import_json — JSON serialization (legacy graph.db).
• query/ — simple string queries over the backend.

All persistent graph topology belongs here. Analysis results that attach to nodes may use rgctl-analysis::results columnar tables, not new graph backends.

Graph analytics (rgctl-analysis)

Single home for graph algorithms and semantic analysis:

Do not reimplement SCC blast radius, PageRank, community detection, or CFG building outside this crate.

Query & export

Cross-cutting

Where CLI commands map

On-disk artifacts (.rgctl/)

Understanding files helps avoid duplicating cache layers:

3. Crate reference (non-language)

Alphabetical list of workspace crates excluding individual rgctl-lang-* plugins.

Language implementations (rgctl-lang-*)

There are many crates named rgctl-lang-<language> (and a few for CI/config dialects). Each implements LanguagePlugin (or a config plugin) for one language or format. They are registered through rgctl-registry and rgctl-languages — not linked directly from analysis or graph code.

When adding or fixing language support:

1. Change or add a rgctl-lang-* crate.
2. Register it in rgctl-languages.
3. Do not add language-specific parsing to rgctl-analysis or src/cli/.

Quick “where do I put this?” table

Related docs: user-guide.md, json-api.md, dashboard-design.md, cli-io-sanity-qe.md, graph-storage-architecture.md, CLI_STRUCTURE.txt.