starchainx

Extract business knowledge from Java Spring Boot source code into a queryable SQLite index.

Automatically discovers state machines, method contracts, business rules, cross-module data flows, API contracts, and more — from code structure, not from comments or documentation.

Quick Start

# Requires Node.js >= 22.5
npx starchainx init --path /path/to/java/project
npx starchainx query entity PurchaseOrder

What It Extracts

| Dimension | Description | |-----------|-------------| | Entity Profiles | Service classes, their repositories, domain classes, controllers | | State Machines | States, transitions with from/to, trigger methods, terminal states | | Method Contracts | Preconditions, postconditions, invariants per method | | Business Rules | Guard checks with conditions, error messages, rule types | | Data Flows | Cross-module client calls with success/failure handlers | | API Contracts | HTTP endpoints with request/response types, preconditions, side effects | | Impact Chains | Cross-module effect propagation paths | | Glossary | Status enum values, business exceptions, domain entities | | Table Ownership | Which modules write to which tables |

Commands

starchainx init [--path <dir>]                    # Detect project, create config, full scan
starchainx scan [--path <dir>]                    # Re-run full pipeline

starchainx query entity <name> [--explain] [--json]  # Entity profile + state machine + methods
starchainx query api [path] [--module <name>]        # API contracts
starchainx query flow <entity> [--target <module>]   # Cross-module data flows
starchainx query impact <method>                     # Impact chains
starchainx query glossary [--module <name>]          # Business glossary
starchainx query table [name] [--module <name>]      # Table ownership

starchainx rules explain --method <Class.method>     # Why a pattern was matched
starchainx review semantics                          # Low-confidence detections
starchainx profile show                              # Inferred project profile

Architecture

Java source code
  |
  v
Layer 1: Raw Fact Extractor        tree-sitter AST -> 4 fact types (invocation, conditional, field access, object creation)
  |
  v
Layer 1.5: Project Profiler        Auto-infer modules, roles, status fields, terminal values
  |
  v
Layer 2: Semantic Rule Engine      Declarative YAML rules (preset + profile + user override)
  |
  v
Layer 3: Pattern Store + Links     Patterns with confidence + declarative link rules
  |
  v
Layer 4: Semantic Assemblers       9 dimensions of business knowledge

Configuration

Zero-config by default. The built-in spring-boot-default preset covers standard Spring Boot / MyBatis projects.

To customize, create .starchainx/rules.yaml in your project:

roles:
  repository:
    type_suffix: [Repository, Mapper, Dao, Store]
  app_service:
    type_suffix: [AppService, UseCase, Handler]

domain:
  status_field_names: [status, state, orderStatus]
  terminal_status_names: [CANCELLED, COMPLETED, CLOSED, DELETED]

patterns:
  - id: my-custom-rule
    emits: STATUS_UPDATE
    role: update
    from: RAW_INVOCATION
    when:
      all:
        - receiver_role: repository
        - method_name_regex: "^transition[A-Z]"
    extract:
      normalized_value: method_name_suffix_upper_snake
    confidence: 0.85

Requirements

• Node.js >= 22.5 (uses node:sqlite)
• Java source code (analyzed via tree-sitter, no compilation needed)

License

MIT