Tier 1 language support — contributor requirements

This document defines what fully supported means for a programming language in rgBuilder, and the concrete steps to add or promote a language to that level.

Audience: contributors adding a new Tier 1 language or bringing a language to parity with the current bar (Java-shaped Layer F + Layers A–E).

Related docs: Code_structure.md (crate layout), dashboard-design.md (dashboard bundle), user-guide.md (discover / serve), hybrid-cpg-plan.md (CPG).

1. Language tiers (quick reference)

rgBuilder uses a hybrid tiering model:

Tier 1 custom plugins today: Rust, Python, TypeScript, JavaScript, Go, Java, C#, C, C++ — see languages.toml (handler = "custom").

Fully supported means the language passes all of Layers A–F with automated tests. Layer F (hybrid CPG: fields, constructors, typed params, field-write mutations) is not optional for Tier 1 — Java is the reference implementation, not a special case.

Honesty limits still apply (no full points-to, no reflection, dynamic languages may emit more Unresolved receivers) — but plugins must ship the same shapes and golden mutation fixture as Java.

2. Capability checklist — “fully supported”

A language is fully supported when all rows are ✅ and backed by automated tests.

Layer A — Graph plugin (indexing)

Layer B — Analysis profile (CFG pipeline)

Layer C — Security & interprocedural

Layer D — Dashboard & UX

Layer E — Tests (required for merge)

Layer F — CPG readiness (hybrid CPG) — required for Tier 1

Required for high-quality cpg mutations / typed field writes. Reference: Java (rgbuilder-lang-java) + field_write golden tests. See hybrid-cpg-plan.md.

Graph extract must populate Symbol.fields on type symbols (F1). Graph materialization of those fields as Variable nodes under the owning type (Contains) happens only when discover runs with --with-cfg (CPG path) — default discover keeps fields on symbols without emitting per-field graph nodes (rgbuilder-extraction graph builder). Empty fields on the symbol is not enough for Tier 1 plugins.

Non-negotiable: a new Tier 1 language that skips Layer F is not mergeable as Tier 1. Ship it as Tier 2 until F1–F6 land.

Layer F language notes (honesty)

Java extract honesty (java-extract-gaps + java-grammar-remainder + java-gql-remainder-gates):

• Annotation types are :Annotation nodes (not :Interface). Usages emit AnnotatedWith; no classpath/FQN resolution beyond imports/package best-effort.
• Records are Class with metadata.is_record; compact ctors and <clinit> / <initblock>N are CFG entry points.
• Annotation elements are Functions with is_annotation_element; interface constant_declaration becomes fields.
• Generics/throws are symbol metadata (type_params, throws); not TypeParameter nodes. GQL JSON projects allowlisted properties (type_params, throws, is_lambda, is_external_stub, …).
• Lambdas are synthetic Functions ($lambda$N, is_lambda); direct CFG $lambda$N lookup is file-global (prefer enclosing-method CFG).
• Anonymous classes use synthetic Outer.$AnonymousN owners.
• Expression refs: field reads → References; array new → Instantiates; .class → References. No full points-to.
• Type-use annotations (annotated_type) and declaration-site parameter annotations attach to the owning method/constructor (parameter encodings are not graph nodes). Field type-use attaches to the field symbol.
• Unresolved Instantiates / DependsOn / Uses / AnnotatedWith / References / Calls targets become deduplicated external stub nodes (is_external_stub, file <external>) so GQL edges survive; stubs are placeholders, not a JDK model.
• Pattern-matching (record_pattern / type_pattern) not first-class symbols.
• No full reflection / retention-policy analysis.
• GQL gates: cargo test --test java_langfeatures (fixture tests/fixtures/java/langfeatures).

3. Repository layout

languages.toml                          # Metadata source of truth (handler, extensions, kinds)
crates/
  rgbuilder-plugin-api/                  # LanguagePlugin trait, Symbol, Relation, call_extraction
  rgbuilder-lang-runtime/                # Generic Tier 2 TreeSitterLanguagePlugin
  rgbuilder-lang-{id}/                   # One crate per language (YOU ADD THIS)
    Cargo.toml
    src/
      lib.rs                            # pub fn register(registry: &mut LanguageRegistry)
      plugin.rs                         # Tier 1: custom LanguagePlugin impl
      config.rs                         # Tier 2 only: static LanguageConfig
  rgbuilder-analysis/
    src/
      language_profile.rs               # CFG/taint gating registry
      cfg_builder.rs                    # Per-language CFG visitors
      def_use.rs                        # Per-language def/use AST cases
      field_write.rs                    # Mutation index (Layer F)
      field_write_locals.rs             # Per-language local/param type recovery (F5)
      taint.rs                          # Per-language taint patterns
  rgbuilder-languages/                   # Wire register() into default binary
tests/
  {lang}_cfg_analysis.rs                # Fixture CFG tests
  {lang}_taint.rs                     # Taint + calls integration
  dashboard_{fixture}.rs                # discover --with-cfg --with-security --with-taint dashboard gate

Crate naming rules

• Directory: crates/rgbuilder-lang-{id}/
• language_id(): lowercase, no spaces ("go", "csharp", "javascript")
• Tree-sitter dep: tree-sitter-{grammar} (version pin in crate Cargo.toml)

4. Step-by-step: add a new Tier 1 language

Use Kotlin → Tier 1 or C# → Tier 1 as a mental template; use Java / Go as code references.

Step 1 — Scaffold the plugin crate

1. Copy an existing custom plugin crate (e.g. rgbuilder-lang-go or rgbuilder-lang-java).
2. Rename to crates/rgbuilder-lang-{id}/.
3. Update Cargo.toml:

[package]
name = "rgbuilder-lang-{id}"
description = "rgBuilder language plugin: {id}"

[dependencies]
rgbuilder-plugin-api = { workspace = true }
rgbuilder-registry = { workspace = true }
rgbuilder-plugin-helpers = { workspace = true }
tree-sitter = { workspace = true }
tree-sitter-{grammar} = "0.xx"
serde_json = "1"

4. Implement lib.rs:

pub fn register(registry: &mut LanguageRegistry) {
    registry.register_language_plugin(Arc::new(MyPlugin::new().expect("init MyPlugin")));
}

5. Add to workspace root Cargo.toml:
   • members list
   • [workspace.dependencies] rgbuilder-lang-{id} = { path = "...", version = "0.1.0" }
6. Register in crates/rgbuilder-languages/src/lib.rs.

Step 2 — languages.toml

Add a [languages.{id}] section:

[languages.{id}]
handler = "custom"
plugin = "MyPlugin"
module = "crate::languages::builtin::{id}"   # legacy doc path; crate is standalone
crate = "tree-sitter-{grammar}"
extensions = ["ext"]
aliases = ["alias"]
function_kinds = ["function_declaration"]      # must match tree-sitter
class_kinds = ["class_declaration"]
import_kinds = ["import_declaration"]
enable_complexity = true
enable_type_inference = false                  # true only if plugin infers param types

Run scripts/generate_lang_configs.py if you maintain Tier 2 config.rs files in parallel (not needed for pure custom Tier 1).

Step 3 — Implement LanguagePlugin

Required methods — see crates/rgbuilder-plugin-api/src/lib.rs:

Calls extraction: prefer shared helper:

use rgbuilder_plugin_api::{walk_calls, GO_CALL_KINDS}; // or define LANG_CALL_KINDS

walk_calls(tree.root_node(), source, file_path, symbols, CALL_KINDS, "mylang", &mut relations);

Add language-specific call node kinds to call_extraction.rs if needed (e.g. method_invocation for Java uses a custom walker today).

Reference implementations:

Step 4 — Wire the analysis profile

Edit crates/rgbuilder-analysis/src/language_profile.rs:

LanguageAnalysisProfile {
    id: "mylang",
    aliases: &["ml"],
    extensions: &["ml"],
    function_kinds: &["function_declaration"],
    cfg_enabled: true,
    taint_enabled: true,
},

Add grammar loader in grammar_for():

"mylang" => Ok(tree_sitter_mylang::LANGUAGE.into()),

Add tree-sitter-mylang to crates/rgbuilder-analysis/Cargo.toml.

Export new helpers from crates/rgbuilder-analysis/src/lib.rs if public API additions are needed.

Step 5 — CFG builder

In cfg_builder.rs:

1. Confirm build_cfg_for_function parses via language_profile::parse_source.
2. Add visit_* handlers for language-specific statement node kinds.
3. Add is_block_like() kinds if the grammar uses nonstandard block nodes (Go uses statement_list).
4. Add unit tests test_{lang}_if_cfg, test_{lang}_loop_has_cycle, plus switch/try if applicable.

Tip: Dump the AST with a small tree_sitter script or cfg_builder test when mapping kinds — do not guess field names (body vs consequence).

Step 6 — Def-use and PDG

In def_use.rs, add match arms for the language’s assignment/declaration node kinds (see Go short_var_declaration, range_clause).

PDG construction is shared; no separate file unless control-dependency edge cases need work.

Step 7 — Taint patterns

In taint.rs:

1. Add detect_mylang_patterns(&mut self).
2. Register in detect_patterns via canonical_language_id match arm.
3. Cover at minimum: HTTP/input sources, SQL/shell sinks, common sanitizers for that ecosystem.

Keep patterns statement-text based for now (consistent with existing code); type-aware taint is optional (with_type_inference).

Step 8 — Tests

Minimum test matrix:

crates/rgbuilder-lang-{id}/src/plugin.rs   # unit: symbols, calls
crates/rgbuilder-analysis/src/cfg_builder.rs # unit: CFG shape
crates/rgbuilder-analysis/src/language_profile.rs # unit: path → id
tests/{id}_cfg_analysis.rs                # integration: real fixture file
tests/{id}_taint.rs                     # taint + calls smoke
tests/dashboard_{fixture}.rs              # discover --with-cfg --with-security --with-taint + manifest/cfg_index

Reuse tests/dashboard_harness.rs helpers (run_discover_all, assert_dashboard_bundle_all_analysis).

Provide a small fixture repo under rgbuilder-tests/ or document RGBUILDER_{LANG}_REPO env override.

Step 9 — Manual validation

cargo build --release
./scripts/build-dashboard.sh && cargo build --release   # if dashboard dist changed

rg-build discover --with-cfg --with-security --with-taint -r /path/to/fixture-repo -l {id} -v
rg-build serve -r /path/to/fixture-repo --host 127.0.0.1 --port 8080
# Open http://127.0.0.1:8080 — check Graph, CFG, Dataflow, Taint, Blast Radius tabs

Confirm manifest.json shows calls_count > 0 and cfg_index.json has "available": true.

5. Promoting Tier 2 → Tier 1

Many languages exist as generic tree-sitter plugins (TreeSitterLanguagePlugin::from_config). To promote:

1. Replace generic plugin with custom plugin.rs (copy from Go/Java).
2. Change languages.toml handler from "tree_sitter" to "custom".
3. Implement extract_relations (at least Calls).
4. Complete Layers B–F checklist (including Layer F).
5. Keep config.rs only if scripts still generate it; otherwise delete to avoid dual sources of truth.

Do not add CFG support only in cfg_builder.rs without a language_profile entry — discover will skip the language.

6. What not to do

7. PR submission checklist

Copy into your PR description:

• crates/rgbuilder-lang-{id}/ with LanguagePlugin + tests
• languages.toml updated (handler = "custom")
• Workspace Cargo.toml + bundle registration
• language_profile.rs entry (cfg_enabled, taint_enabled, grammar)
• cfg_builder.rs + tests for control-flow constructs
• def_use.rs cases for declarations/assignments including field-access LHS
• Layer F: fields[], is_constructor + .<init>/::<init>, typed params
• Layer F: merge_local_types arm in field_write_locals.rs (or documented N/A)
• Layer F: golden {id}_cfg_captures_field_write_and_query in field_write tests
• taint.rs detect_{id}_patterns
• extract_relations emits Calls (and inheritance if applicable)
• Integration test + dashboard gate (or documented fixture path)
• discover --with-cfg --with-security --with-taint smoke on fixture repo documented in test
• No new CDN / online-only dashboard dependencies

8. Current parity snapshot (2026-07)

Layer F golden coverage lives in crates/rgbuilder-analysis/src/field_write.rs (*_cfg_captures_field_write_and_query). Update this table when promoting a language or when F tests regress.

9. Getting help

• Open a Language Support Request issue before large work.
• Point questions at rgbuilder-plugin-api::LanguagePlugin and the reference crates above.
• For dashboard contract details, see tests/dashboard_harness.rs and docs/dashboard-design.md.