DEV Community: Shaaf Syed

Enforcing Architecture with rgctl Policy Checks

Shaaf Syed — Wed, 09 Sep 2026 14:37:39 +0000

Enforcing Architecture with rgctl Policy Checks

rgctl (Reachability Graph Control) indexes a codebase into a compact knowledge graph -- functions, classes, calls, inheritance, communities -- and serves deterministic, structured answers to questions about architecture, impact, and data flow. You run rgctl discover . once, and every subsequent query (blast-radius, metrics, gql) returns sub-millisecond results from the persisted graph. Agents and humans get the same exact facts. No re-reading source files, no confident guesses, no context window gymnastics.

This post is not about querying the graph. It is about using it to enforce rules -- automatically, in CI, on every pull request. We will use a real Java EE monolith as the worked example: the CoolStore WebLogic application.

The example project: CoolStore WebLogic

CoolStore is a Java EE e-commerce monolith originally built for WebLogic. It has a REST layer (CartEndpoint, OrderEndpoint, ProductEndpoint), a service layer (ShoppingCartService, CatalogService, PromoService, OrderService, ShippingService), JPA model classes, and a JavaScript frontend with bundled vendor libraries (lodash, d3, jQuery DataTables, Angular). It is small enough to follow along, but structurally interesting -- the vendor JavaScript creates deep call graphs that dwarf the Java application code.

Clone it and index:

git clone https://github.com/sshaaf/coolstore-weblogic.git
cd coolstore-weblogic
rgctl discover .

[>] rgctl discover
==> Analyzing: coolstore-weblogic
[✓] Loaded 1227 files from snapshot -> 17417 nodes, 52920 edges (0.0s)
[✓] Analyzed 7526 functions (avg complexity: 1.0, 0 high, 0 medium)
[✓] Detected 13565 communities (modularity: 0.29)
[*] Top hotspot: replace (PageRank: 0.0502)
[!] Found 186 circular dependencies
[✓] Analysis complete
[✓] Saved to .rgctl/ (2.9 MB total)
[✓] Completed in 0.6s

17,417 nodes, 52,920 edges, indexed in under a second. The graph is now on disk at .rgctl/ and ready for policy checks.

The problem: architecture rules that live in people's heads

Every team has architectural constraints. "The payments module must not depend on legacy." "No single function should affect more than 50 downstream consumers." "High-centrality bridge functions need extra review." These rules exist as tribal knowledge, communicated in onboarding docs and code review comments. They are enforced manually, inconsistently, and after the fact.

Manual enforcement has three failure modes:

Drift. The rule is forgotten. A new dependency slips in. Nobody notices until it causes a production incident three months later.
Ambiguity. "Too much coupling" means different things to different reviewers. Without a number, every review is a negotiation.
Scale. On a codebase with 7,500 functions, no human can evaluate the blast radius of every changed function in a pull request.

rgctl's check command solves this by turning architecture rules into a JSON policy file that a CI pipeline can evaluate automatically.

Policy file format

A policy file is a JSON object with up to four fields:

{
  "max_impact_nodes": 50,
  "centrality_alert_threshold": 0.8,
  "forbidden_crossings": [["legacy", "payments"]],
  "node_domains": {
    "550e8400-e29b-41d4-a716-446655440000": "legacy",
    "6ba7b810-9dad-11d1-80b4-00c04fd430c8": "payments"
  }
}

Every field is optional. Omitted fields default to unlimited (no constraint).

Field	Type	Default	What it checks
`max_impact_nodes`	integer	unlimited	Fails if any function's blast-radius impact zone exceeds this count
`centrality_alert_threshold`	float	unlimited	Fails if any reached node has betweenness centrality above this value
`forbidden_crossings`	`[[string, string], ...]`	`[]`	Fails if a blast-radius path crosses between the named domain pair
`node_domains`	`{ "uuid": "domain" }`	`{}`	Maps node UUIDs to domain labels used by `forbidden_crossings`

The simplest possible policy is one field:

{"max_impact_nodes": 25}

This says: no function in the codebase may have a blast radius larger than 25 nodes. If any function exceeds that threshold, the check fails.

Violation types

When a policy rule is broken, rgctl reports a structured violation. There are four types:

ScaleFailure

Triggered when a function's impact zone exceeds max_impact_nodes.

scale failure: impact zone size 648 exceeds max 15

This is the most common violation. It catches functions that are deeply embedded in the call graph -- utility functions like indexOf or baseIsEqual that fan out to hundreds of downstream consumers. A change to these functions has outsized blast radius, and the policy forces the team to acknowledge that.

CascadeHazard

Triggered when a node in the blast-radius impact zone has betweenness centrality above centrality_alert_threshold.

cascade hazard: node 6ba7b810... betweenness 0.8523 exceeds threshold 0.8000

Betweenness centrality measures how often a node sits on the shortest path between other nodes. High-betweenness nodes are bridge functions -- they connect otherwise separate parts of the graph. Changing a function that reaches a bridge node means the blast radius crosses architectural boundaries. The CascadeHazard violation flags this.

DomainIsolation

Triggered when a blast-radius path crosses a forbidden_crossings boundary.

domain isolation failure: path from 'legacy' to 'payments' via node 550e8400...

This requires setting up node_domains to assign graph nodes to logical domains, and forbidden_crossings to declare which domain pairs must not be connected. The crossing check is bidirectional -- ["legacy", "payments"] blocks both legacy -> payments and payments -> legacy paths.

SanitizationBypass

Triggered by the CPG (Code Property Graph) analysis when a sanitizer on a taint path does not dominate the sink block in the control-flow graph.

sanitization bypass: sanitizer 550e8400... does not dominate sink at line 42 (path len 3)

This is the most advanced violation type. It requires discover --with-cfg to build the control-flow graph and PDG (Program Dependence Graph), and catches cases where a security sanitizer exists on a data-flow path but can be bypassed through an alternate control-flow route.

Running the first policy check on CoolStore

Create a policy file. We will start with max_impact_nodes: 15 and centrality_alert_threshold: 0.8:

{"max_impact_nodes": 15, "centrality_alert_threshold": 0.8}

Save this as policy.json in the repository root and run:

rgctl -f json check --policy-file policy.json

Output (truncated):

{
  "schema_version": 1,
  "policy": "policy.json",
  "passed": false,
  "violations": [
    {
      "error": "Graph error: scale failure: impact zone size 114 exceeds max 15",
      "symbol": "baseIsEqual"
    },
    {
      "error": "Graph error: scale failure: impact zone size 649 exceeds max 15",
      "symbol": "baseIndexOf"
    },
    {
      "error": "Graph error: scale failure: impact zone size 78 exceeds max 15",
      "symbol": "merge"
    },
    {
      "error": "Graph error: scale failure: impact zone size 818 exceeds max 15",
      "symbol": "isIterateeCall"
    },
    {
      "error": "Graph error: scale failure: impact zone size 900 exceeds max 15",
      "symbol": "isLength"
    },
    {
      "error": "Graph error: scale failure: impact zone size 648 exceeds max 15",
      "symbol": "indexOf"
    },
    {
      "error": "Graph error: scale failure: impact zone size 899 exceeds max 15",
      "symbol": "replace"
    },
    {
      "error": "Graph error: scale failure: impact zone size 18 exceeds max 15",
      "symbol": "getInventory"
    },
    {
      "error": "Graph error: scale failure: impact zone size 16 exceeds max 15",
      "symbol": "_fnInitComplete"
    }
  ]
}

The check exits with code 1. The full output lists over 100 violations, but the pattern is clear: the worst offenders are lodash and jQuery DataTables internals (isLength at 900, replace at 899, isIterateeCall at 818, indexOf at 648). The Java application function getInventory appears too -- it has a blast radius of 18 nodes because of its callers in CatalogService and the downstream CatalogItemEntity model.

Check the exit code

rgctl check --policy-file policy.json
echo "Exit code: $?"

Policy violations: 113
Exit code: 1

Exit code 1 means the policy failed. Any CI system can use this directly as a gate.

Per-function blast radius with policy

The check command evaluates every function in the graph. When you want to inspect a specific function, use blast-radius --policy-file instead.

A function that passes

priceShoppingCart is the core pricing method in ShoppingCartService. Let's check it:

rgctl -f json blast-radius priceShoppingCart --policy-file policy.json

{
  "gatekeeping": {
    "policy_status": "PASS",
    "violations": []
  },
  "metrics": {
    "direct_callers_count": 5,
    "impact_zone_size": 7,
    "score": 40.35
  },
  "target": {
    "symbol": "priceShoppingCart",
    "canonical_fqn": "ShoppingCartService::priceShoppingCart",
    "file_path": "src/main/java/com/redhat/coolstore/service/ShoppingCartService.java",
    "language": "java",
    "signature": "public void priceShoppingCart(ShoppingCart sc) {"
  },
  "topology": {
    "direct_callers": [
      {"fqn": "com.redhat.coolstore.rest.CartEndpoint.add"},
      {"fqn": "com.redhat.coolstore.rest.CartEndpoint.dedupeCartItems"},
      {"fqn": "com.redhat.coolstore.rest.CartEndpoint.set"},
      {"fqn": "com.redhat.coolstore.service.ShoppingCartService.checkOutShoppingCart"},
      {"fqn": "com.redhat.coolstore.rest.CartEndpoint.delete"}
    ],
    "impact_zone": [
      {"fqn": "com.redhat.coolstore.rest.CartEndpoint.add"},
      {"fqn": "com.redhat.coolstore.rest.CartEndpoint.dedupeCartItems"},
      {"fqn": "com.redhat.coolstore.rest.CartEndpoint.delete"},
      {"fqn": "com.redhat.coolstore.rest.CartEndpoint.set"},
      {"fqn": "com.redhat.coolstore.service.ShoppingCartService.checkOutShoppingCart"},
      {"fqn": "com.redhat.coolstore.rest.CartEndpoint.checkout"},
      {"fqn": "anonymous"}
    ]
  }
}

policy_status: "PASS". The impact zone is 7 nodes -- well under the 15-node limit. Five direct callers, all in CartEndpoint and ShoppingCartService itself. Changing priceShoppingCart affects a contained, well-defined set of functions. This is what healthy coupling looks like.

A function that violates

Now check indexOf from the bundled lodash:

rgctl -f json blast-radius indexOf --policy-file policy.json

{
  "gatekeeping": {
    "policy_status": "VIOLATED",
    "violations": [
      {
        "kind": "scale_failure",
        "count": 648,
        "max": 15
      }
    ]
  },
  "metrics": {
    "direct_callers_count": 232,
    "impact_zone_size": 648,
    "score": 72.4
  },
  "target": {
    "symbol": "indexOf",
    "file_path": "src/main/webapp/bower_components/lodash/lodash.js"
  }
}

policy_status: "VIOLATED". 232 direct callers, 648 nodes in the impact zone. Changing indexOf could affect 648 functions across the entire application. The policy rightfully flags this -- nobody should modify a vendored lodash function without understanding that scope.

Tight policy on Java service code

Let's use a tighter policy (max_impact_nodes: 8) and check getShoppingCart:

rgctl -f json blast-radius getShoppingCart \
  --policy-file policy-tight.json

{
  "gatekeeping": {
    "policy_status": "VIOLATED",
    "violations": [
      {
        "kind": "scale_failure",
        "count": 10,
        "max": 8
      }
    ]
  },
  "metrics": {
    "direct_callers_count": 6,
    "impact_zone_size": 10,
    "score": 40.5
  },
  "target": {
    "symbol": "getShoppingCart",
    "canonical_fqn": "ShoppingCartService::getShoppingCart"
  }
}

With a limit of 8, getShoppingCart violates -- its impact zone is 10. Six direct callers (CartEndpoint.add, CartEndpoint.set, CartEndpoint.delete, CartEndpoint.dedupeCartItems, CartEndpoint.getCart, ShoppingCartService.checkOutShoppingCart) plus their downstream consumers push it over. Raise the threshold to 10 and it passes. This is the kind of tuning that policy files are designed for.

Java application violations at moderate thresholds

With max_impact_nodes: 10, the Java application code starts surfacing alongside the vendor JavaScript:

Symbol	Impact zone	File
`getShoppingCartItemList`	12	`ShoppingCart.java`
`getProductByItemId`	11	`ProductService.java`
`toProduct`	14	`Transformers.java`
`getCartItemTotal`	11	`ShoppingCart.java`
`getShippingTotal`	11	`ShoppingCart.java`
`getInventory`	18	`CatalogItemEntity.java`
`getCatalogItemById`	15	`CatalogService.java`

These are the Java functions that fan out the most. getInventory has the largest blast radius at 18 nodes -- it is used by CatalogItemEntity which feeds into CatalogService, ProductService, and ultimately the REST endpoints. During a migration from WebLogic to, say, Quarkus, these are the functions you would want to refactor first -- they touch the most downstream code.

Permissive vs strict policies

Permissive: baseline for a monolith

Start with a high threshold to establish the pipeline and see what you are dealing with:

{"max_impact_nodes": 500, "centrality_alert_threshold": 0.95}

rgctl -f json check --policy-file policy-permissive.json

{
  "schema_version": 1,
  "policy": "policy-permissive.json",
  "passed": false,
  "violations": [
    {"symbol": "baseIndexOf", "error": "Graph error: scale failure: impact zone size 649 exceeds max 500"},
    {"symbol": "binaryIndex", "error": "Graph error: scale failure: impact zone size 659 exceeds max 500"},
    {"symbol": "isIterateeCall", "error": "Graph error: scale failure: impact zone size 818 exceeds max 500"},
    {"symbol": "join", "error": "Graph error: scale failure: impact zone size 607 exceeds max 500"},
    {"symbol": "isLength", "error": "Graph error: scale failure: impact zone size 900 exceeds max 500"},
    {"symbol": "slice", "error": "Graph error: scale failure: impact zone size 697 exceeds max 500"},
    {"symbol": "isIndex", "error": "Graph error: scale failure: impact zone size 856 exceeds max 500"},
    {"symbol": "replace", "error": "Graph error: scale failure: impact zone size 899 exceeds max 500"},
    {"symbol": "baseSlice", "error": "Graph error: scale failure: impact zone size 883 exceeds max 500"},
    {"symbol": "indexOf", "error": "Graph error: scale failure: impact zone size 648 exceeds max 500"},
    {"symbol": "indexOfNaN", "error": "Graph error: scale failure: impact zone size 659 exceeds max 500"},
    {"symbol": "binaryIndexBy", "error": "Graph error: scale failure: impact zone size 660 exceeds max 500"},
    {"symbol": "isObjectLike", "error": "Graph error: scale failure: impact zone size 745 exceeds max 500"}
  ]
}

Even at 500, 13 functions still violate. All of them are lodash internals. The Java application code passes entirely. This tells you the vendor JavaScript is the structural risk, not the Java services.

Strict: zero tolerance

{"max_impact_nodes": 0}

A max_impact_nodes of 0 means any function with any downstream consumer triggers a failure. Useful for smoke-testing the pipeline or for isolated modules where every function is expected to be a leaf.

Domain isolation

You are migrating CoolStore from WebLogic. The REST layer and the service layer must not grow new cross-layer dependencies. You want CI to catch any function whose blast radius crosses from service into rest (or vice versa).

Step 1: Find the node UUIDs for functions in each layer:

rgctl -f json gql \
  "MATCH (n:Function) WHERE n.file_path CONTAINS 'service/' RETURN n"

Each node in the response includes an id field (UUID). Collect the UUIDs for the service-layer functions and the REST-layer functions.

Step 2: Build the policy:

{
  "max_impact_nodes": 50,
  "forbidden_crossings": [["service", "rest"]],
  "node_domains": {
    "60a84e0c-7366-4e65-8c41-98b4411c7d36": "service",
    "26135ad3-6fa3-4fab-bca6-32607ddbff72": "service",
    "b311845f-2bb1-43c5-99b5-90d2e7d6f60b": "service",
    "fd95d5e1-a959-4d7c-92d4-bd20de91dc45": "rest",
    "004895d9-7ebd-46ed-b92f-84ca01ccfed2": "rest",
    "73fb42ed-45dd-46af-86e9-f1306995916c": "rest"
  }
}

Step 3: Run the check. Any blast-radius path that crosses from a service node to a rest node (or vice versa) triggers a DomainIsolation violation.

The crossing check is bidirectional. Declaring ["service", "rest"] blocks both directions.

Git-aware scoping (local development)

The check command has a local optimization: it runs git diff --name-only HEAD to detect uncommitted changes in the working tree. If you have modified files that are not yet committed, check evaluates only the functions defined in those files instead of the full graph. This makes the feedback loop fast during local development -- edit a file, run the check, see if your change introduces a policy violation.

If the diff is empty (no uncommitted changes) or git is unavailable, the check falls back to evaluating every function in the graph. This is what happens in CI: a GitHub Actions checkout produces a clean working tree with no uncommitted changes, so git diff --name-only HEAD returns nothing and the full graph is evaluated. For CoolStore's 7,500 functions this is still fast (sub-second), but on very large codebases you may want to be aware of this.

GitHub Actions integration

Here is a complete GitHub Actions workflow that runs rgctl policy checks on every pull request:

name: Architecture Policy Check

on:
  pull_request:
    branches: [main]

jobs:
  policy-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install rgctl
        run: |
          curl -fsSL https://github.com/sshaaf/rgctl/releases/latest/download/rgctl-linux-x86_64.tar.gz \
            | tar xz -C /usr/local/bin

      - name: Discover codebase
        run: rgctl discover .

      - name: Run policy check
        run: rgctl -f json check --policy-file policy.json

Update 09-09-2026: Today, rgctl does not checkout full git history. evaluation is on a clean tree. This means that check evaluates every function in the graph, not just the ones modified in the PR. Temporal updates and diffs are planned for a future release.

The workflow does three things:

Checks out the PR branch. The checkout is a clean tree, so check evaluates every function in the graph (the git-aware local optimization does not apply in CI -- see above).
Discovers the codebase to build the knowledge graph. This step runs once and persists the graph to .rgctl/.
Runs the policy check against policy.json at the repository root. If any violation is found, the step fails with exit code 1 and the pull request is blocked.

Adding violation details to PR comments

For better developer experience, pipe the JSON output into a PR comment:

      - name: Run policy check
        id: policy
        continue-on-error: true
        run: |
          rgctl -f json check --policy-file policy.json > policy-result.json
          echo "passed=$(jq -r .passed policy-result.json)" >> "$GITHUB_OUTPUT"

      - name: Comment on PR
        if: steps.policy.outputs.passed == 'false'
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');
            const result = JSON.parse(fs.readFileSync('policy-result.json', 'utf8'));
            const violations = result.violations
              .map(v => `- **${v.symbol}**: ${v.error || v.violation}`)
              .join('\n');
            const body = `## Policy Check Failed\n\n${result.violations.length} violation(s) found:\n\n${violations}`;
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body
            });

      - name: Fail if violations
        if: steps.policy.outputs.passed == 'false'
        run: exit 1

This posts a formatted comment listing every violation, so the developer can see exactly which functions broke the policy without digging into the CI logs.

Caching the graph

For large repositories, the discover step can take minutes. Cache the .rgctl/ directory to skip re-indexing when the source has not changed:

      - name: Cache rgctl graph
        uses: actions/cache@v4
        with:
          path: .rgctl
          key: rgctl-${{ hashFiles('**/*.java', '**/*.ts', '**/*.py') }}
          restore-keys: rgctl-

      - name: Discover codebase
        run: rgctl discover .

When the cache hits, discover detects the existing graph and skips the indexing step.

Tightening policies over time

A practical adoption path for CoolStore (or any monolith):

Week 1: Deploy with a permissive policy (max_impact_nodes: 500). On CoolStore, this catches 13 lodash internals and lets all Java application code pass. This is your baseline.
Week 2-4: Lower the threshold (max_impact_nodes: 50). The vendor JavaScript dominates the violations. Consider excluding bower_components/ from indexing if vendor code is not your concern.
Month 2: Add centrality_alert_threshold: 0.8. Start catching bridge functions that connect otherwise separate subsystems.
Month 3+: Tighten to max_impact_nodes: 15. Now Java application functions like getInventory (18 nodes) and getCatalogItemById (15 nodes) start appearing. These are your refactoring targets.
Ongoing: Add forbidden_crossings for module boundaries you want to enforce. Assign node_domains to the key functions in each domain.

Each step produces measurable progress. The violation count in CI is your metric.

Summary

What	How
Define rules	Write a `policy.json` with thresholds and domain boundaries
Check locally	`rgctl -f json check --policy-file policy.json`
Check one function	`rgctl -f json blast-radius priceShoppingCart --policy-file policy.json`
CI gate	Add to GitHub Actions; exit code 1 blocks the PR
Start permissive	`{"max_impact_nodes": 500}` -- catches only the worst offenders
Get strict	`{"max_impact_nodes": 15, "centrality_alert_threshold": 0.8}`
Enforce boundaries	Add `forbidden_crossings` and `node_domains`

Architecture rules should not live in people's heads. They should live in a JSON file, evaluated on every pull request, with a clear pass/fail signal. That is what rgctl policy checks give you.

The CoolStore WebLogic source is at github.com/sshaaf/coolstore-weblogic. Clone it, run rgctl discover ., write a policy.json, and see what breaks.

I Created a Code Graph of Magento 2 for AI Agents

Shaaf Syed — Mon, 07 Sep 2026 15:54:44 +0000

I Created a Code Graph of Magento 2 for AI Agents

Reachability Graph Control (rgctl) indexes a repository once into a compact graph — functions, classes, calls, inheritance, communities — then serves deterministic JSON queries. Agents get structural facts without loading 25,000 PHP files into context.

I wanted to know whether rgctl could give a coding agent the same kind of map I wish I had on day one of a Magento engagement: where modules live, what calls what, which neighborhoods cluster together, and what breaks if I touch a service class — without pretending the framework's dependency injection container is fully visible to static analysis.

This post is use-case driven. If you pair with Cursor, Claude Code, or a custom agent on large PHP monoliths (Magento, Symfony, Laravel at scale), the workflow below is what I actually run. Under the hood I'll cover the new PHP Tier 1 plugin (tree-sitter, not regex), shallow vs deep extraction, and where the graph is honest about what it cannot see.

The corpus is upstream Magento Open Source — cloned locally, indexed with rgctl v0.4.10, not a toy fixture.

Why Magento, why agents

Magento 2 is a stress test for static tooling:

~25,000 PHP files in app/, lib/, and setup/ (excluding vendor/ and generated/)
PSR-4 namespaces, traits, interfaces, generated code paths
Symfony-style DI — constructor injection, di.xml preferences, ObjectManager at the edges
Module boundaries that do not match folder names in your head

A human opens module.xml, greps for preference, reads di.xml, and builds intuition over weeks. An agent has a context window and grep. On a tree this size, "find all usages of OrderRepository" often means either reading the wrong ten files or stopping at the first plausible hit.

rgctl's bet is the same one that worked on Kubernetes and Java monoliths in earlier posts: index once, query many times, return small JSON facts the agent can chain across turns.

Phase 1: Shallow discover — the structural map

Fetch the corpus (optional — rgctl ships a fetch script for profile repos):

./scripts/fetch-profile-repos.sh
# → example/magento2/

Cold discover on maintainer hardware (release build, empty .rgctl/):

export REPO="$(pwd)/example/magento2"
cd "$REPO"
rm -rf .rgctl
rgctl discover app lib setup -l php -e vendor,generated -v

Reference numbers from v0.4.10:

Metric	Value
Wall time	~12 s
PHP files	25,499
Graph nodes	~266k
Functions	~100k
Peak RSS	~2 GB

That is the shallow pass: symbols, relations, communities, blast-radius indexes — no CFG, no taint. For an agent's first turn ("what does this codebase look like?"), this is usually enough.

Artifacts land in {repo}/.rgctl/ — especially graph.snapshot.bin and dashboard manifests. Agents should treat that directory as read-only cache; add .rgctl/ to .gitignore.

Under the hood: tree-sitter, not regex

PHP is Tier 1 in rgctl — the same class as Java, Go, and Rust. That means a custom LanguagePlugin in crates/rgctl-lang-php/, backed by tree-sitter-php, not the generic Tier 2 regex indexer.

Why that matters for Magento:

Approach	What you get on `namespace`, traits, `match`, attributes
Regex / line parsers	Fragile; misses nested structures
Tree-sitter AST	Grammar-accurate nodes; same pipeline as other Tier 1 languages

The plugin walks the AST and emits symbols (classes, interfaces, traits, enums, methods, functions, arrow functions) and relations:

Relation	Example in Magento-style code
`Calls`	`$this->orderRepository->save($order)`
`Extends` / `Implements`	`class OrderRepository implements OrderRepositoryInterface`
`Uses`	`use HasDataChanges;` (trait composition)
`Import`	`use Magento\Sales\Api\OrderRepositoryInterface;`
`Instantiates`	`new OrderFactory()`

Import-aware static calls: OrderRepositoryInterface::class and SomeService::getInstance() get to_qualified_hint from the file's use map — so resolution can tie a call site to a namespaced target when the name is unique in the index.

Modern PHP surface (relevant to extensions and newer core code):

Attributes stored in metadata.attributes
Anonymous classes as $Anonymous{line}
Promoted constructor properties on fields[] (DI-style private readonly OrderRepositoryInterface $orderRepository)
metadata.unresolved on dynamic calls ($this->$method(), variable callees) — the graph keeps the edge but flags that the target is not statically known

Optional: RGCTL_PHP_ONLY=1 switches to the PHP-only tree-sitter grammar (no inline HTML) for pure .php trees.

What shallow extraction does not claim

rgctl is not a PHPStan or Psalm competitor. There is no full type checker inside the plugin — only bound resolution from declarations, parameters, fields, and imports. That design choice is intentional: stay fast on whole-repo discover, stay honest when types are interfaces wired at runtime.

On Magento, the symptom is a sparse call graph: many SCCs, lots of interface-typed receivers, factory and ObjectManager indirection. The graph still tells you that a method invokes something; it often cannot name the single concrete callee. More on that in Honest limits.

Phase 2: Deep discover — CFG, taint, field mutations

When an agent needs control flow, data-flow-ish facts, or security patterns, run deep discover:

rgctl discover app lib setup -l php -e vendor,generated \
  --with-cfg --with-security --with-taint -v

Reference cold numbers (same hardware):

Metric	Value
Wall time	~33 s
CFG functions	~100k
Field writes indexed	~58k
Peak RSS	~5.7 GB

Deep pass adds:

Layer	Agent use
CFG / PDG	`inspect`, `slice`, `cpg flows` — "what happens between line 40 and the `save()` call?"
Taint	Discover-time patterns: `$_FILES`, `filter_input`, PDO `prepare` / SQL sinks
Field mutations	`cpg mutations --type Order` — cart/DTO safety, state change neighborhoods
Security scan	Config-like files when `--with-security` is on

On Magento's core, taint hit count was very low (two flows in our cold run) — framework wrappers and indirection mean discover-time heuristics miss most real sinks. That is a finding, not a failure: agents should not treat "zero taint" as "safe"; they should treat it as "pattern library did not match this framework."

Warm re-run on the same tree dropped to ~12 s wall — cache reuse in .rgctl/ is real for iterative agent sessions.

Honest limits: DI and sparse calls

Magento's DI is the elephant in the room. Constructor injection through interfaces is correct at runtime and invisible to naive static resolution:

public function __construct(
    private readonly OrderRepositoryInterface $orderRepository,
) {}

rgctl records the parameter type on the constructor and the field on the class. A call like $this->orderRepository->get($id) may not resolve to a unique Calls edge to Magento\Sales\Model\OrderRepository::get — because the declared type is the interface, and the binding lives in etc/di.xml.

We track follow-up work in issue #75: CHA-lite candidate edges, config parsers for di.xml, and metadata.candidates on unresolved calls.

For agents today: combine structural queries with module artifacts you already trust:

# Graph: who implements this interface in-repo?
rgctl -f json gql \
  "MATCH (c:Class)-[:IMPLEMENTS]->(i:Interface)
   WHERE i.qualified_name CONTAINS 'OrderRepository'
   RETURN c.qualified_name LIMIT 20"

# Source: preferences in DI config (agent reads file or rgrep)
rgrep 'OrderRepositoryInterface' app/code/**/etc/di.xml

The graph narrows the search space; it does not replace reading di.xml.

Agent workflow: copy-paste recipes

Install the agent skill once per machine (writes AGENTS.md recipes into Cursor / Claude config):

rgctl install --skill --force

Standard session:

export REPO=/path/to/magento2
rgctl -r "$REPO" discover app lib setup -l php -e vendor,generated

All queries below assume -f json and parse schema_version + payload from stdout — never scrape stderr.

1. Inventory before editing

# How many service classes in a module path?
rgctl -f json gql \
  "MATCH (n:Class) WHERE n.file_path CONTAINS 'Magento/Sales'
   RETURN n.qualified_name LIMIT 50"

# Functions named like plugins (Magento convention)
rgctl -f json gql \
  "MATCH (f:Function) WHERE f.name LIKE '*Plugin*'
   RETURN f.name, f.file_path LIMIT 30"

2. Blast radius before a refactor

rgctl -r "$REPO" -f json blast-radius save --class OrderRepository

If the symbol is ambiguous, rgctl returns remediation text — agents must retry with --class or path/to/file.php::method, not pick a random row.

Use gatekeeping.policy_status with a policy file when you want a hard stop:

{ "max_impact_nodes": 80 }

3. Community = module neighborhood

Community detection clusters functions that call each other densely — often aligned with module boundaries:

rgctl -f json gql --macro-name all_communities unused
rgctl -f json gql \
  "MATCH (f:Function) WHERE f.community_id = '42' RETURN f LIMIT 30"

An agent planning "extract this feature to a microservice" can ask for the community around a REST entrypoint instead of listing every file under Controller/.

4. Deep slice on a suspicious method

After --with-cfg:

rgctl -f json cpg slice --function execute --file app/code/Magento/Sales/Model/OrderRepository.php
rgctl -f json cpg flows app/code/.../OrderRepository.php --line 120 --variable $order --function save

5. Semantic search (optional second index)

rgctl semantic index --embedder hash
rgctl -f json semantic query "cancel order workflow" --limit 10

Semantic complements the graph; it does not replace Calls edges.

Agent rules that actually help

Rule	Why
Run `discover` once per branch / after large pulls	Stale graph → wrong blast radius
Prefer `gql` / `blast-radius` over reading random `Model/` files	Token budget
Treat `metadata.unresolved` calls as "unknown callee"	Do not invent targets
On DI-heavy classes, follow `IMPLEMENTS` + `di.xml`	Graph + config, not graph alone
Use `-f json` only	Stable machine output

See agent-recipes.md and AGENTS.md for the full command matrix.

When the graph is enough vs when to use the IDE

Task	Start with
"What module neighborhood is this controller in?"	`gql` + communities
"If I change `save()`, what breaks?"	`blast-radius`
"Does this file call `curl_exec` anywhere?"	`cpg` / `slice` after `--with-cfg`
"What is the runtime DI binding?"	`di.xml`, `setup:di:compile` output, debugger
"Will this PHPStan level pass?"	PHPStan — different tool

Try it

Release: rgctl v0.4.10 — PHP Tier 1 in the default binary
Small fixture: rgctl-tests/ecommerce-php/ — MVC + taint + field-write golden
Large fixture: ./scripts/fetch-profile-repos.sh → example/magento2
Docs: languages, tier-1 PHP parity

rgctl discover . -l php --with-cfg --with-taint
rgctl install --skill --force

If you are building agent playbooks for commerce migrations (Magento → something else, or major version jumps), the combination of fast whole-repo index, honest unresolved edges, and JSON query recipes is the piece I wanted documented — not a fake complete call graph that would lie about DI.

Next up on the graph side: DI-aware call resolution — di.xml preferences and interface fan-out without inventing unique targets. Until then, agents that know the limits are more trustworthy than agents that guess.

Blast Radius for Agent-Assisted Development on Kubernetes

Shaaf Syed — Wed, 02 Sep 2026 20:52:38 +0000

Blast Radius for Agent-Assisted Development on Kubernetes

Reachability Graph Control (rgctl) - AI coding agents default to reading files sequentially. That burns context, misses structure, and produces confident wrong answers about impact and dependencies. rgctl indexes the whole repository once into a rich graph with pre-computed reachability, then serves compact, deterministic query results — so agents (and humans) get the right slice of the codebase without loading it into the prompt.

If you refactor RESTClientFor in Kubernetes by hand, you probably do not open a
call-graph tool first. not that I am suggesting you should.. but lets take it as a good example when it comes to impact on the codebase, its dependencies etc. Usually you have an IDE find-references, a mental map of
client-go, teammates who have been burned before, and CI that will catch what
you missed. For most edits, that workflow is fine.

The landscape changes when you decide to hand the same task to a coding agent. The agent
has a context window, grep, and no tenure on the team and importantly the LLM has its own limits, depending on which one you use.
On a tree with 181,000 functions, asking it to "refactor newPodWorkers safely" often
produces one of three outcomes: it reads the wrong files, stops at direct
callers and misses transitive impact, or burns most of the turn budget
exploring pkg/kubelet/ without ever reaching cmd/kubelet/main.

This post is for brave souls who work or plan to work with agents on large codebases. It
explains why rgctl blast radius belongs in
that workflow, what you should expect from the output, and where your existing
tools are still the right choice. The examples use the upstream
kubernetes/kubernetes repository —
cloned locally and indexed with rgctl, not a trimmed or synthetic corpus.

How blast radius is calculated in rgctl

Blast radius answers one question: if I change this function, what upstream
code could be affected? It walks the call graph backwards along CALLS
edges — from callee to caller, caller's caller, and so on — and returns three
things:

Output	Meaning
Direct callers	Functions that call the target directly
Impact zone	Full transitive closure of upstream callers
Score (0–100)	A capped impact rating derived from both counts

The score is not PageRank (even though rgctl can also calculate it) and its not guestaming it either. rgctl combines two components:

Component	Formula	Cap
Direct callers	`direct_count × 25`	40 points
Transitive impact	`impact_count × 0.05`	60 points

score = min(direct_component + transitive_component, 100)

A symbol with no upstream callers in the static graph scores 0. A shared
helper with dozens of direct callers and a large impact zone lands in the
40–50 range; scores above 50 flag architectural hotspots where both
fan-in dimensions are high.

Why agents get sub-second answers on Kubernetes

Lets take a look at how this is made possible, or as my agent friends always say "lets delve into it.."
Agents work in multi-turn sessions. A live breadth-first search over 1.7M
edges on every "who calls X?" would make that unusable. rgctl does the expensive
work once, at discover time, and serves lookups from pre-built snapshots.

Step 1 — Build the call graph: discover parses source, extracts function
nodes and CALLS edges, and writes graph.snapshot.bin plus a dedicated
blast_engine.snapshot.bin.

Step 2 — Collapse cycles: Mutual recursion is common in real codebases
(7,097 circular call dependencies in Kubernetes). rgctl runs Kosaraju's
algorithm on the CALLS subgraph and condenses each strongly connected
component (SCC) into a single node, producing a directed acyclic graph (DAG).
Cycles no longer break reachability analysis.

Step 3 — Precompute reverse reachability. On the condensed DAG, rgctl
propagates reachability in reverse topological order, storing the result as
dense bitsets — one per SCC. A query becomes a bitset read: O(1) lookup
on the condensed graph, not a per-request graph walk.

Step 4 — Serve through tiers: At query time, rgctl tries the fastest path
first:

T0 — macro call lookup cache hit (macro_call_index.db)
T1 — mmap blast engine with precomputed SCC reachability
T3 — full graph hydrate (only when you need --with-slices or --policy-file)

On Kubernetes that means a ~13 s one-time index, then ~1 s per symbol
query — no daemon, no remote service. Re-run discover after large merges so
the graph stays current. The full breakdown is in the
design doc.

The gap agents cannot close on their own

A typical agent turn looks like this:

You:   "Change how newPodWorkers handles static pods — keep behavior, improve readability."
Agent: [reads pod_workers.go] [greps "newPodWorkers"] [edits file] [maybe runs tests]

Before any line changes, the agent has to answer a structural question: who
depends on this symbol, transitively? The usual approaches all fall short at
Kubernetes scale:

What the agent tries	What it gets	What it misses
Read one file	Local implementation	Callers in other packages
`grep newPodWorkers`	Text matches	Upstream paths two or three hops away
Rely on training data	Plausible Kubernetes architecture	This checkout's actual call graph
Read 20 caller files	More context, fewer tokens left for the edit	No guaranteed closure; easy to stop early

How many times we have seen an agent confidently edit
a helper and skip the integration test package that actually exercises it. Blast radius closes that gap with a single subprocess (point rgctl -r at your
local clone of kubernetes/kubernetes):

rgctl -r /path/to/kubernetes -f json blast-radius <Symbol>

The response is a few hundred tokens of structured JSON instead of tens of
thousands of lines of source the agent would otherwise have to read and still
fail to synthesize correctly. You can run the same command yourself in a
terminal — the point is not to replace your IDE, but to give the agent (and
you, when reviewing its plan) a shared, verifiable fact base.

The loop that actually works

rgctl is built around a loop that matches how Cursor, Claude Code, and similar
tools operate today:

1. Your prompt        →  natural language ("what breaks if I change X?")
2. Subprocess         →  rgctl -f json blast-radius <Symbol>
3. Structured facts   →  parse schema_version + payload
4. Reasoning          →  risk summary, test plan, edit scope
5. Edit / check       →  re-query if the graph may be stale

The contract lives in AGENTS.md
and installs as a project skill via rgctl install --skill. Agents parse
stdout JSON only — not stderr, not the dashboard unless you ask for a UI.

When you review an agent's plan, ask whether it grounded impact analysis in
something like step 2, or whether it inferred callers from grep and memory.
That distinction is usually visible in the quality of the proposed test plan.

Why Kubernetes is a good stress test

All numbers below come from indexing a fresh clone of
kubernetes/kubernetes — the same
tree you get from GitHub, not a fixture or subset. When working inside the
rgctl repo, ./scripts/fetch-profile-repos.sh clones it to example/kubernetes;
otherwise clone it anywhere and pass that path to -r.

Metric	Value
Source files indexed	26,141
Functions analyzed	181,680
Graph edges	1,789,412
Functions named `Run`	513
Cold `discover` time	~13 s
Typical `blast-radius` query	~1 s

No one should have to read 26k Go files to answer "what is the upstream impact of this symbol?".
IMHO it just doesnt make sense, whether a programmer or the helper agent.
Index once:

$ git clone https://github.com/kubernetes/kubernetes.git
$ rgctl -r kubernetes discover .
[✓] Loaded 26141 files -> 740986 nodes, 1789412 edges
[✓] Analyzed 181680 functions
[✓] Completed in 13.3s

discover writes artifacts to kubernetes/.rgctl/ (or wherever you cloned),
including blast_engine.snapshot.bin and a macro call lookup cache. Queries
are mmap lookups, not live graph walks over 1.7M edges.

Example: changing `RESTClientFor`

Suppose you ask your agent to add a default timeout to RESTClientFor in
client-go/rest/config.go.

Without blast radius, a competent agent will open the file, grep for
RESTClientFor(, find a handful of call sites, edit, and suggest:

go test ./staging/src/k8s.io/client-go/rest/...

That is not wrong. It is incomplete.

With blast radius, one query returns the full upstream picture:

$ rgctl -r kubernetes -f json blast-radius RESTClientFor

{
  "schema_version": 2,
  "target": {
    "canonical_fqn": "RESTClientFor",
    "file_path": "kubernetes/staging/src/k8s.io/client-go/rest/config.go",
    "signature": "func RESTClientFor(config *Config) (*RESTClient, error) {"
  },
  "metrics": {
    "direct_callers_count": 38,
    "impact_zone_size": 95,
    "score": 44.75
  },
  "topology": {
    "direct_callers": [
      { "fqn": "factoryImpl.RESTClient" },
      { "fqn": "NewForConfig" },
      { "fqn": "Framework.BeforeEach" }
    ],
    "impact_zone": [
      { "fqn": "NewKubectlCommand" },
      { "fqn": "main", "file_path": ".../cmd/kubectl/kubectl.go" }
    ]
  }
}

From this you — and the agent — can derive a concrete plan:

Score 44.8 — not a leaf function; treat as a shared infrastructure change.
38 direct callers — client factories, kubectl wiring, integration and e2e setup.
Impact zone reaches cmd/kubectl/main — unit tests under rest/ are necessary but not sufficient.

You might reach the same conclusion with IDE find-references and ten minutes of
clicking. The agent will not do that reliably unless you give it a tool that
returns the closure in one shot.

Context cost

This matters if you care about agent turn quality, not just correctness:

Approach	Approx. context cost	Caller coverage
Read `config.go` + five caller files	15k–40k tokens	Partial
`rgctl -f json blast-radius RESTClientFor`	0.5k–2k tokens	Full static closure

The agent keeps context for the actual edit and for reasoning about risk, rather
than spending it reconstructing a call graph from grep output.

Example: refactoring `newPodWorkers`

A subtler case. You ask the agent to extract pod worker configuration into a
struct in pkg/kubelet/pod_workers.go.

Grep finds four direct call sites. That sounds low-risk.

$ rgctl -r kubernetes blast-radius newPodWorkers \
    --file pkg/kubelet/pod_workers.go
Blast radius for 'newPodWorkers'
  Score: 41.5/100
  Direct callers: 4
  Impact zone: 30
  Callers: TestFakePodWorkers, createPodWorkersWithLogger, NewMainKubelet,
           TestVolumeAttachLimitExceededCleanup
  Impact: ... NewMainKubelet, createAndInitKubelet, RunKubelet, startKubelet,
          Run, run, NewKubeletCommand, main

Four direct callers, but 30 in the impact zone — the chain runs through
kubelet construction all the way to cmd/kubelet/main.

An agent that stops at grep will under-scope the test plan. One that reads blast
radius should propose pkg/kubelet tests and the cmd/kubelet startup path,
and mention RunKubelet in the change summary.

You might get there by tracing callers in your IDE or by running
make test WHAT=pkg/kubelet and seeing what breaks. Blast radius is how you
front-load that knowledge before the agent edits, not after CI fails.

Use `--depth` to control noise

Kubernetes impact zones include a lot of test harness symbols. When you want a
local picture rather than the full release surface:

$ rgctl -r kubernetes blast-radius newPodWorkers \
    --file pkg/kubelet/pod_workers.go --depth 2
  Impact zone: 8   # down from 30

Full closure for "what could this break in production?" Bounded depth for
"what is immediately upstream?" Same command, one flag.

Example: the score-zero trap

You ask: "Kubelet.Run looks unused — can we remove it?"

$ rgctl -r kubernetes blast-radius Kubelet::Run \
    --file pkg/kubelet/kubelet.go
  Score: 0.0/100
  Direct callers: 0
  Impact zone: 0

A score of zero here does not mean safe to delete. Kubelet.Run is the
kubelet's main loop; it is started from cmd/kubelet. For this symbol the gap
is primarily interface dispatch — fast static analysis (without heavy
pointer analysis) struggles to link a caller that holds an interface type to the
concrete Kubelet implementation. Goroutine spawns can produce the same blind
spot: the graph may not record them as CALLS edges either.

You would not delete it. An agent might, if it treats the score as ground truth.

This is the most important caveat when relying on blast radius in agent
workflows: the output is a risk signal for reasoning, not permission to
merge. When score is zero on a symbol you know is hot, disambiguate with
--class or --file, then grep for call sites the graph cannot see. The
rgctl skill
encodes this failure mode so agents do not treat "no static callers" as "unused."

What you get in the JSON

Whether you or your agent runs the query, these are the fields worth paying
attention to:

Field	Why it matters
`target.canonical_fqn`	Disambiguated symbol — not just a name that matches 513 `Run` functions
`target.file_path`	Anchor for edits and citations
`metrics.score`	Quick risk tier: 0 / ~25–50 / 50+
`metrics.direct_callers_count`	Immediate fan-in
`metrics.impact_zone_size`	Transitive fan-in
`topology.direct_callers[]`	First-hop checklist for tests and review
`topology.impact_zone[]`	Full upstream checklist
`topology.scc_component_id`	Hint when the symbol sits in a cycle-heavy neighborhood
`gatekeeping.policy_status`	`VIOLATED` when a policy file rejects the change

Text output is fine for a quick terminal check. Agent workflows and CI gates
should use -f json per the JSON API.

Disambiguation on a real tree

Kubernetes has 513 functions named Run. A bare symbol query fails loudly:

$ rgctl -r kubernetes blast-radius Run
Error: Symbol 'Run' is ambiguous. Found 513 matches.
Remediation: rgctl blast-radius "ClassName::Run"
              rgctl blast-radius "path/to/file.go::Run"

You click the right reference in your IDE. An agent needs the remediation path
in the error output — and a rule that says never pick a random row from the
disambiguation table. In practice: retry with ClassName::symbol, --file, or
--class before editing.

If you are setting up agent rules or reviewing agent output, check whether
disambiguation happened before the blast-radius numbers were quoted.

Policy gates in agent-driven PRs

You can wire blast radius into automated guardrails:

{ "max_impact_nodes": 50 }

$ rgctl -r kubernetes -f json blast-radius RESTClientFor \
    --policy-file policy.json
# gatekeeping.policy_status: "VIOLATED", exit code 1

For an agent proposing a large refactor, VIOLATED should mean stop and report
— not silently proceed. The check command runs the same rules across all
touched symbols in one pass, which fits agent-opened PRs where you want a hard
ceiling on impact zone size.

You might override that judgment on a case-by-case basis. Agents should not
override it unless you explicitly say so.

When your IDE is still the better tool

Blast radius is not the right first move for every task — even in agent-assisted
work:

Your question	Often better
What calls this in the file I have open?	IDE find references
Will CI pass?	Run the tests
Is this a public API?	Module boundaries, docs, review
Who owns this package?	CODEOWNERS, team knowledge
What changed in this branch?	`git diff`

Blast radius earns its place when you need transitive upstream impact as a
bounded fact — before an agent edits a shared helper, before you approve its
test plan, or before a high-fan-in change lands in a PR. For local edits where
you already know the blast zone, skip it.

Static analysis limits (both of you should know these)

Go interface dispatch — methods like SyncPod may show zero callers; the graph does not always resolve interface-typed receivers
Reflection and plugins — invisible to static analysis
Test-heavy impact zones — Kubernetes lists many Test* symbols; use --depth or path filters when you care about production paths only
Agents inventing callers — if a caller is not in topology, it was not in the query result; treat that as a hallucination risk

Getting started

Get the tool: Grab rgctl from GitHub.
Test it on your own codebase: Navigate to your project root and run rgctl discover . --export-migration-hints to index your application.

export REPO="$(pwd)/kubernetes"
rgctl -r "$REPO" discover .
rgctl -r "$REPO" -f json blast-radius RESTClientFor
rgctl -r "$REPO" -f json blast-radius newPodWorkers --file pkg/kubelet/pod_workers.go

If you are already in the rgctl repo, ./scripts/fetch-profile-repos.sh clones
kubernetes/kubernetes into example/kubernetes — use that path for -r instead.

A useful sanity-check prompt for your agent:

Use rgctl to find the blast radius of RESTClientFor, and tell me what tests
we should run before changing it based on the upstream callers.

The explicit tool invocation matters — agents sometimes skip subprocesses unless
the prompt names them. A good answer runs rgctl -f json blast-radius and cites
metrics and topology. A weak one greps the tree and guesses.

Decomposing a Monolith into Microservices with Call Graph Analysis

Shaaf Syed — Wed, 02 Sep 2026 20:52:35 +0000

Decomposing a Monolith into Microservices with Call Graph Analysis

Splitting a monolith into microservices is a problem of finding boundaries. The
wrong boundaries produce distributed monoliths -- microservices that cannot be
deployed independently because they call each other synchronously for every
operation. The right boundaries follow natural seams in the code: clusters of
functions that are tightly coupled internally but loosely connected to the rest
of the system. This post picks up the CoolStore monolith from
migrating it to Quarkus with rgctl
and applies the same graph analysis to the next question: where to cut it into
services.

This post walks through a concrete decomposition of a Java EE monolith using
static call-graph analysis. I use rgctl
to build the function-level call graph, detect community structure, measure
coupling with blast radius, and identify the cuts that produce viable
microservice boundaries. The goal is not to argue that you should decompose
every monolith -- it is to show how graph analysis replaces intuition with
structural evidence when you decide to.

before we move forward, yes you can use the same functionality in tandem with an code agent as well. This is possible by using the skill provided by rgctl. The following guide explains how the skill works and how to install it.

The Monolith

The CoolStore is a Java EE 7 e-commerce application originally deployed on
WebLogic. It has 25 classes across 5 packages:

The application handles four distinct business operations:

Catalog browsing -- list products, look up inventory
Shopping cart -- add/remove items, price calculation, shipping, promotions
Order processing -- checkout publishes to JMS, MDBs persist the order
Inventory management -- deduct stock on order, low-stock alerts

In the monolith, these operations share a single database, a single JMS topic,
and freely inject each other's EJBs. The question is: which of these can become
independent services, and where are the coupling points that make that hard?

Step 1: Build the Call Graph

All commands below assume the rgctl repository root, with the CoolStore example
at example/coolstore-weblogic.

$ rgctl -r example/coolstore-weblogic discover . \
    --with-cfg \
    --with-harmonic \
    --with-security \
    --export-migration-hints

[>] rgctl discover
[!] Deep analysis enabled (--with-cfg / --with-taint).
[✓] Loaded 1227 files from snapshot -> 17417 nodes, 52920 edges
[✓] Analyzed 7526 functions (avg complexity: 1.0)
[✓] Detected 13565 communities (modularity: 0.29)
[!] Found 186 circular dependencies

✓ Security analysis:
  Potential secrets found: 5

✓ Control flow analysis:
  Field writes indexed: 3299
  CFG/PDG/Dominance: 6585 functions analyzed
  Skipped: 941 functions (unsupported language or parse error)

[✓] rgctl discover finished in 16.4s

186 circular dependencies. In a monolith, this is typical -- EJBs inject each
other, services call back into the REST layer, model objects are passed across
every boundary. But for microservice decomposition, every circular dependency
is a potential distributed coupling problem. I need to find which cycles can
be broken and which are load-bearing.

Step 2: Detect Community Structure

rgctl uses label-propagation community detection on the call graph. This
algorithm finds clusters of functions that call each other densely but have
sparse connections to the outside. These clusters are candidates for
microservice boundaries.

$ rgctl -r example/coolstore-weblogic -f json gql --macro-name all_communities unused

Filtering to communities with 2+ members that contain Java application code
(community IDs are assigned at discover time; labels are the stable handle
when comparing runs on the same snapshot):

Community	Members	Label	Dominant Classes
8064	30	`coolstore.model::` `APPLICATION_JSON`	CartEndpoint, ShoppingCartService, ShoppingCart, ShippingService, PromoService
4266	30	`coolstore.model::` `getCartItemTotal`	ShoppingCartService, ShippingService, PromoService, Transformers
11973	18	`coolstore.model::` `getProductByItemId`	ProductEndpoint, ProductService, Transformers, Product, CatalogItemEntity
11250	7	`coolstore.service::` `CatalogItemEntity`	CatalogService, InventoryEntity
4058	4	`coolstore.service::` `getPercentOff`	PromoService, Promotion
14643	5	`coolstore.rest::Order`	OrderEndpoint, OrderService

Let's look at what the community detection is telling me by examining the
members of each cluster.

Community 8064 (30 members): Cart Operations

$ rgctl -r example/coolstore-weblogic -f json gql \
    "MATCH (f:Function) WHERE f.community_id = '8064' RETURN f LIMIT 50"

CartEndpoint.add             CartEndpoint.delete
CartEndpoint.set             CartEndpoint.dedupeCartItems
CartEndpoint.getCart         CartEndpoint.checkout
ShoppingCartService.getShoppingCart   ShoppingCartService.getProduct
ShoppingCart.addShoppingCartItem      ShoppingCart.removeShoppingCartItem
ShoppingCart.getShoppingCartItemList  ShoppingCart.setShoppingCartItemList
ShoppingCartItem.setQuantity         ShoppingCartItem.setPrice
ShoppingCartItem.setProduct          ShoppingCartItem.getQuantity
ShoppingCartItem.toOrderItem         Product.getPrice

This is the cart CRUD cluster -- adding, removing, and listing items. The
algorithm grouped the REST endpoint, the service, and the relevant model
methods into one community because they form a tight call cycle.

Pricing and Shipping (community 4266)

ShoppingCartService.priceShoppingCart   ShoppingCartService.initShoppingCartForPricing
ShoppingCartService.lookupShippingServiceRemote
ShippingService.calculateShipping      ShippingService.calculateShippingInsurance
ShippingService.getPercentOfTotal
PromoService.applyShippingPromotions
ShoppingCart.getCartItemTotal          ShoppingCart.setCartItemTotal
ShoppingCart.setShippingTotal          ShoppingCart.getShippingTotal
ShoppingCart.setCartTotal              ShoppingCart.setCartItemPromoSavings
ShoppingCartItem.getPromoSavings
ShoppingCart.setShippingPromoSavings

This is the pricing engine -- computing totals, shipping costs, and
applying shipping promotions. It pulls in ShippingService and
PromoService.applyShippingPromotions because priceShoppingCart calls both
directly.

Cart Serialization and Item Promotions

ShoppingCartOrderProcessor.process
Transformers.shoppingCartToJson        Transformers.$lambda$0
Transformers.$lambda$1
PromoService.applyCartItemPromotions   PromoService.getPromotions
Promotion.getPercentOff                Promotion.getItemId
ShoppingCartItem.setPromoSavings
ShoppingCart.getCartItemPromoSavings    ShoppingCart.getCartTotal
ShoppingCart.getShippingPromoSavings

This cluster links cart serialization (for JMS publishing) with item-level
promotions. The connection is through ShoppingCartOrderProcessor.process,
which serializes the cart, and PromoService.applyCartItemPromotions, which
reads and writes cart item prices.

Order Fulfillment and Inventory (community 11250 + order MDB cluster)

OrderServiceMDB.onMessage             OrderServiceMDB.$lambda$0
InventoryNotificationMDB.onMessage    InventoryNotificationMDB.$lambda$0
OrderService.save
CatalogService.getCatalogItemById     CatalogService.updateInventoryItems
CatalogItemEntity.getInventory
InventoryEntity.getQuantity           InventoryEntity.setQuantity
Order.getItemList                     OrderItem.getProductId

This is the order fulfillment pipeline -- the two MDBs that listen on the JMS
topic, persist the order, and update inventory. CatalogService appears here
because both MDBs use it: OrderServiceMDB calls updateInventoryItems and
InventoryNotificationMDB calls getCatalogItemById to check stock levels.

Product Catalog (community 11973)

ProductEndpoint.listAll               ProductEndpoint.getProduct
ProductService.getProducts            ProductService.getProductByItemId
ProductService.$lambda$0
CatalogService.getCatalogItems
Transformers.toProduct
Product.setItemId  Product.setPrice  Product.setLocation
Product.setQuantity  Product.setLink  Product.setDesc  Product.setName

Product listing and lookup. CatalogService.getCatalogItems provides the JPA
query, Transformers.toProduct maps entities to DTOs, and ProductEndpoint
exposes the REST API.

Order Queries (community 14643)

OrderEndpoint.listAll      OrderEndpoint.getOrder
OrderService.getOrders     OrderService.getOrderById

Simple read path for orders. Just an endpoint and a service with JPA queries.

Step 3: Map the Proposed Microservice Boundaries

The communities suggest four natural services, but with complications. Let me
map them out and then use blast radius to quantify the coupling at each boundary.

Proposed services

Based on the community structure:

The communities group naturally into three services. But look at the problems:

CatalogService appears in two communities -- it is called by the
product listing path (community 11973) and by the order fulfillment path
(community 11250 -- MDBs call CatalogService for inventory operations).
Transformers is split across three services -- toProduct belongs
with catalog, shoppingCartToJson with cart, jsonToOrder with orders.
PromoService spans two communities -- applyCartItemPromotions
is in community 4058 (item promotions) and applyShippingPromotions is
in community 4266 (pricing and shipping).
ShoppingCartService.getProduct calls ProductService.getProductByItemId
-- a synchronous cross-service call.

These are not trivial issues. They are the structural coupling that makes
monolith decomposition hard. Let's use blast radius to quantify them.

Step 4: Quantify Coupling with Blast Radius

Blast radius tells you: if I change this function, how many upstream callers
break? For microservice decomposition, I care specifically about functions that
are called across the proposed service boundaries -- these become the API
contracts between services.

Cross-boundary calls

Query the call graph for edges between Java classes:

$ rgctl -r example/coolstore-weblogic -f json gql \
    "MATCH (a:Function)-[:CALLS]->(b:Function) RETURN a,b LIMIT 5000"

Filtering to cross-class calls between Java files, the significant
inter-service edges are:

Source (proposed service)	Target (proposed service)	Call
Cart	Catalog	`ShoppingCartService.getProduct` → `ProductService.getProductByItemId`
Cart	Catalog	`ShoppingCartOrderProcessor.process` → `Transformers.shoppingCartToJson` (shared)
Order	Catalog	`OrderServiceMDB.onMessage` → `CatalogService.updateInventoryItems`
Order	Catalog	`InventoryNotificationMDB.onMessage` → `CatalogService.getCatalogItemById`
Order	Cart	`Transformers.jsonToOrder` (shared code, both need it)

Blast radius at the boundaries

Now let's check the impact of the key boundary functions:

$ rgctl -r example/coolstore-weblogic -f json blast-radius getShoppingCart
$ rgctl -r example/coolstore-weblogic -f json blast-radius priceShoppingCart
$ rgctl -r example/coolstore-weblogic -f json blast-radius getCatalogItems
$ rgctl -r example/coolstore-weblogic -f json blast-radius getProducts
$ rgctl -r example/coolstore-weblogic -f json blast-radius toProduct
$ rgctl -r example/coolstore-weblogic -f json blast-radius save --class OrderService
$ rgctl -r example/coolstore-weblogic -f json blast-radius onMessage --class OrderServiceMDB
$ rgctl -r example/coolstore-weblogic -f json blast-radius calculateShipping --file ShippingService.java

Function	Score	Direct Callers	Impact Zone	Proposed Service
`ShoppingCartService::` `getShoppingCart`	40.5	6	10	Cart
`ShoppingCartService::` `priceShoppingCart`	40.4	5	7	Cart
`ProductService::` `getProducts`	40.1	2	2	Catalog
`Transformers::` `toProduct`	40.7	2	14	Catalog
`Transformers::` `jsonToOrder`	40.1	2	2	Order
`Transformers::` `shoppingCartToJson`	25.2	1	4	Cart
`PromoService::` `applyCartItemPromotions`	25.4	1	8	Cart
`CatalogService::` `getCatalogItems`	25.1	1	3	Catalog
`CatalogService::` `updateInventoryItems`	25.1	1	1	Catalog
`OrderService::save`	25.1	1	1	Order
`OrderServiceMDB::` `onMessage`	0.0	0	0	Order
`ShippingService::` `calculateShipping`	0.0	0	0	Cart

Transformers::toProduct has the highest blast radius at 40.7 with 14 nodes in
the impact zone. This is a utility function that maps JPA entities to DTOs. It
is called by both ProductService.getProducts (catalog browsing) and
ProductService.getProductByItemId (called from the cart service). If you
change this function, 14 upstream functions are affected -- across two proposed
service boundaries.

What the ShoppingCart mutations tell me

I can also use CPG field mutation analysis to understand the data coupling:

$ rgctl -r example/coolstore-weblogic -f json cpg mutations --type ShoppingCart --exclude-ctors

{
  "mutations": [
    {"function": "setShoppingCartItemList", "member": "shoppingCartItemList", "kind": "ThisField"},
    {"function": "setCartItemTotal",        "member": "cartItemTotal",        "kind": "ThisField"},
    {"function": "setShippingTotal",        "member": "shippingTotal",        "kind": "ThisField"},
    {"function": "setCartTotal",            "member": "cartTotal",            "kind": "ThisField"},
    {"function": "setCartItemPromoSavings",  "member": "cartItemPromoSavings",  "kind": "ThisField"},
    {"function": "setShippingPromoSavings",  "member": "shippingPromoSavings",  "kind": "ThisField"}
  ]
}

Six fields are mutated on ShoppingCart by functions spread across community
8064 (cart CRUD) and community 4266 (pricing and shipping) and community 4058 (item promotions). The cart object
is a shared mutable structure that both ShoppingCartService, PromoService,
and ShippingService write to. In a monolith, this works because they all
operate on the same in-memory object. In microservices, you need to decide who
owns this state.

Step 5: Make the Cuts

With the structural data in hand, here are the decomposition decisions and the
reasoning behind each.

Service 1: Catalog Service

Scope: Product listing, inventory queries, entity-to-DTO mapping.

Classes:

ProductEndpoint (REST API)
ProductService (business logic)
CatalogService (JPA queries) -- but only the read path: getCatalogItems, getCatalogItemById
CatalogItemEntity, InventoryEntity (JPA entities)
Product (DTO)
Transformers.toProduct (mapping logic -- inlined into this service)

Why these boundaries work: Communities 11973 and 11250 form a clean cluster
with only one outbound dependency: ProductService is called by
ShoppingCartService.getProduct in the cart service.

API contract: Expose a REST endpoint that the cart service calls instead of
injecting ProductService directly:

// Catalog Service: src/main/java/com/redhat/coolstore/catalog/ProductResource.java
@Path("/api/products")
@ApplicationScoped
public class ProductResource {

    @Inject
    ProductService productService;

    @GET
    @Produces(MediaType.APPLICATION_JSON)
    public List<Product> listAll() {
        return productService.getProducts();
    }

    @GET
    @Path("/{itemId}")
    @Produces(MediaType.APPLICATION_JSON)
    public Product getByItemId(@PathParam("itemId") String itemId) {
        return productService.getProductByItemId(itemId);
    }
}

Blast radius validation: getCatalogItems has a score of 25.1 with only 1
direct caller (ProductService.getProducts). This call stays within the
service. The cross-service call from ShoppingCartService.getProduct ->
ProductService.getProductByItemId becomes a REST client call, which is a clean
boundary.

Service 2: Cart Service

Scope: Shopping cart lifecycle, pricing, shipping, promotions, checkout
trigger.

Classes:

CartEndpoint (REST API)
ShoppingCartService (cart operations + pricing)
ShippingService (shipping cost calculation)
PromoService (promotion rules)
ShoppingCartOrderProcessor (publishes checkout event)
ShoppingCart, ShoppingCartItem, Promotion (model objects)

Why these boundaries work: Communities 8064 and 4266 (plus community 4058 for item
promotions) forms the cart operations cluster. Despite label-propagation
sometimes splitting cart, pricing, and promotions into adjacent communities,
they share a tight internal coupling: priceShoppingCart calls both
ShippingService and PromoService, and checkOutShoppingCart calls
ShoppingCartOrderProcessor. These are all synchronous, performance-sensitive
calls that belong together.

The CatalogService coupling: ShoppingCartService.getProduct calls
ProductService.getProductByItemId, which calls
CatalogService.getCatalogItemById. This is the only synchronous cross-service
dependency from cart to catalog. Replace the EJB injection with a REST client:

// Cart Service: replaces the direct ProductService injection
@ApplicationScoped
public class CatalogClient {

    @Inject
    @RestClient
    CatalogApi catalogApi;

    public Product getProduct(String itemId) {
        return catalogApi.getByItemId(itemId);
    }
}

@RegisterRestClient(configKey = "catalog-api")
@Path("/api/products")
public interface CatalogApi {

    @GET
    @Path("/{itemId}")
    Product getByItemId(@PathParam("itemId") String itemId);
}

# application.properties
quarkus.rest-client.catalog-api.url=http://catalog-service:8080

Checkout becomes an event: ShoppingCartOrderProcessor.process currently
publishes to a JMS topic. In the microservices version, this becomes a message
to a shared broker (Kafka or AMQP). The cart service is the producer; the order
service is the consumer. This is already an asynchronous boundary in the
monolith -- JMS was doing the right thing.

// Cart Service: checkout event publisher
@ApplicationScoped
public class ShoppingCartOrderProcessor {

    @Inject
    @Channel("orders-out")
    Emitter<String> ordersEmitter;

    public void process(ShoppingCart cart) {
        ordersEmitter.send(Transformers.shoppingCartToJson(cart));
    }
}

Blast radius validation: getShoppingCart has a score of 40.5, but all 6
direct callers are within the cart service (CartEndpoint.add, .delete,
.set, .getCart, .dedupeCartItems, and ShoppingCartService.checkOutShoppingCart).
The blast radius stays internal. The only outbound edge is the checkout event,
which is asynchronous.

Service 3: Order Service

Scope: Order persistence, order queries, inventory deduction, low-stock
alerts.

Classes:

OrderEndpoint (REST API for order queries)
OrderService (JPA persistence for orders)
OrderServiceMDB -> becomes OrderEventConsumer (consumes checkout events)
InventoryNotificationMDB -> becomes InventoryAlertConsumer
Order, OrderItem (JPA entities)

Why these boundaries work: The order MDB cluster and communities 11250 and 14643 form the
order processing cluster. The MDBs have blast radius 0.0 -- they are pure
consumers with no upstream callers. This makes them ideal microservice entry
points: they receive events and operate independently.

The CatalogService coupling problem: This is the hardest cut.
OrderServiceMDB.onMessage calls CatalogService.updateInventoryItems, and
InventoryNotificationMDB.onMessage calls CatalogService.getCatalogItemById.
Both need access to inventory data that lives in the catalog service's
database.

There are two options:

Option A: REST call to catalog service (simple, synchronous)

@ApplicationScoped
public class OrderEventConsumer {

    @Inject
    OrderService orderService;

    @Inject
    @RestClient
    CatalogApi catalogApi;

    @Incoming("orders-in")
    public void onMessage(String orderStr) {
        Order order = Transformers.jsonToOrder(orderStr);
        orderService.save(order);
        order.getItemList().forEach(item ->
            catalogApi.updateInventory(item.getProductId(), item.getQuantity())
        );
    }
}

Option B: Publish inventory events (asynchronous, better decoupling)

@ApplicationScoped
public class OrderEventConsumer {

    @Inject
    OrderService orderService;

    @Inject
    @Channel("inventory-updates")
    Emitter<String> inventoryEmitter;

    @Incoming("orders-in")
    public void onMessage(String orderStr) {
        Order order = Transformers.jsonToOrder(orderStr);
        orderService.save(order);
        // Emit inventory deduction events instead of direct call
        order.getItemList().forEach(item ->
            inventoryEmitter.send(Json.createObjectBuilder()
                .add("productId", item.getProductId())
                .add("quantity", item.getQuantity())
                .build().toString())
        );
    }
}

With Option B, the catalog service would consume inventory-updates and handle
deductions internally. This eliminates the synchronous dependency entirely.

Blast radius confirms this is safe: OrderServiceMDB::onMessage and
InventoryNotificationMDB::onMessage both have scores of 0.0. Changing their
implementation (from JMS to Reactive Messaging, from direct call to event) has
zero impact on upstream callers.

The Shared Code Problem: Transformers

Transformers is the class that appears in all three services. It has three
static methods:

Method	Blast Radius	Used By
`toProduct`	40.7	Catalog (entity-to-DTO mapping)
`shoppingCartToJson`	25.2	Cart (checkout serialization)
`jsonToOrder`	40.1	Order (event deserialization)

These are pure functions with no state and no injected dependencies. The correct
decomposition is to split them:

toProduct moves into the catalog service. It depends on CatalogItemEntity and Product, both of which are catalog-owned models.
shoppingCartToJson moves into the cart service. It depends on ShoppingCart and ShoppingCartItem.
jsonToOrder moves into the order service. It depends on Order and OrderItem.

Each method only references model classes owned by its target service. The blast
radius scores confirm this is the right split: each method's callers are entirely
within its target service.

The Shared Model Problem

In the monolith, ShoppingCart, Order, Product, and their related classes
are all in one model package. In the decomposed version, each service owns its
domain model:

Service	Owned Models
Catalog	`CatalogItemEntity`, `InventoryEntity`, `Product`
Cart	`ShoppingCart`, `ShoppingCartItem`, `Promotion`
Order	`Order`, `OrderItem`

The boundary is clean except for one thing: Product is used by both the
catalog service (as a DTO returned by the API) and the cart service (as the
product embedded in a ShoppingCartItem). The solution is standard: the catalog
service defines and owns the Product type. The cart service either depends on
a shared catalog-api module or defines its own ProductRef DTO with only the
fields it needs (itemId, name, price).

Step 6: The Resulting Architecture

Synchronous dependencies

Only one: Cart -> Catalog for product lookups. This is a single REST call
(GET /api/products/{itemId}) used in ShoppingCartService.getProduct when
adding items to the cart. It can be cached.

Asynchronous dependencies

Cart -> Order: checkout event (orders-out -> orders-in)
Order -> Catalog: inventory deduction event (inventory-updates)

Both are fire-and-forget with eventual consistency.

Database ownership

Each service owns its schema:

Service	Tables	Former JPA entities
Catalog	`CATALOG_ITEM_ENTITY`, `INVENTORY`	`CatalogItemEntity`, `InventoryEntity`
Cart	(in-memory or Redis)	`ShoppingCart`, `ShoppingCartItem`
Order	`ORDERS`, `ORDER_ITEM`	`Order`, `OrderItem`

Step 7: CI Guardrails for Boundary Enforcement

After the decomposition, enforce the boundaries with a policy file:

{
  "forbidden_crossings": [
    ["cart", "catalog-internals"],
    ["order", "catalog-internals"],
    ["order", "cart-internals"]
  ],
  "max_impact_nodes": 20,
  "centrality_alert_threshold": 0.8
}

$ rgctl -r example/coolstore-weblogic -f json check --policy-file policy.json

This prevents re-introduction of direct cross-service calls. If a developer
adds a direct import of CatalogService in the order service, the policy check
fails in CI.

What the Graph Told Me That Intuition Would Not

A developer familiar with the CoolStore would likely suggest similar service
boundaries based on domain knowledge. The graph analysis adds three things that
intuition cannot:

1. It quantifies the cuts. Transformers::toProduct has a blast radius of
40.7 with 14 nodes in the impact zone spanning two proposed services. That is
a number you can use in a design review. "This function affects 14 callers
across 2 services" is more actionable than "Transformers is used in a lot of
places."

2. It finds hidden coupling. The order fulfillment cluster groups OrderServiceMDB,
InventoryNotificationMDB, and OrderService.save by call density. Community
11250 groups the CatalogService inventory methods they call. This is
not obvious from the package structure -- CatalogService is in the service
package alongside cart-related EJBs, but functionally it is tightly coupled to
the order fulfillment pipeline through inventory operations. The community
detection surfaced this relationship from the call graph, not from naming
conventions.

3. It validates the cuts are safe. Both MDBs have blast radius 0.0. This
means converting them from JMS @MessageDriven beans to Reactive Messaging
@Incoming consumers has zero static impact on the rest of the codebase. The
graph proves the refactoring is isolated, which is exactly what you want for a
high-risk change like switching messaging infrastructure.

When Not to Decompose

The analysis also tells you when decomposition is a bad idea. The ShoppingCart
mutations analysis showed 6 fields mutated by functions spread across 3
communities. If you tried to split PromoService and ShippingService into
separate services from the cart, every pricing operation would require
synchronous round-trips to apply promotions, calculate shipping, and update
totals. The graph coupling is too dense.

This is why communities 8064 and 4266 -- despite being separate label-propagation
clusters -- end up in one cart service. The community detection correctly
identifies distinct functional clusters at finer resolution, but the shared
mutable state (the ShoppingCart object) makes them inseparable at deployment
time.

Try it out

Stop migrating by spreadsheet and tribal knowledge. If you are staring down a monolith and wondering where the hidden dependencies are, let the call graph tell you.

Get the tool: Grab rgctl from GitHub.
Test it on your own codebase: Navigate to your project root and run rgctl discover . --export-migration-hints to index your application.
Stop guessing: Run rgctl blast-radius on your most heavily-used service and see exactly what you will break before you write a single line of code.

If rgctl saves you from a broken build or a doomed migration sprint, star the repository. Drop into the GitHub Discussions to share your custom agent recipes—or just to show off your most horrifying circular dependency graph.

Commands Reference

# Build the graph with full analysis (from the rgctl repo root)
rgctl -r example/coolstore-weblogic discover . --with-cfg --with-harmonic --export-migration-hints

# List communities (natural code clusters)
rgctl -r example/coolstore-weblogic -f json gql --macro-name all_communities unused

# Inspect community members
rgctl -r example/coolstore-weblogic -f json gql \
    "MATCH (f:Function) WHERE f.community_id = '<id>' RETURN f LIMIT 25"

# Map call edges between functions
rgctl -r example/coolstore-weblogic -f json gql \
    "MATCH (a:Function)-[:CALLS]->(b:Function) RETURN a,b LIMIT 5000"

# Check blast radius at a boundary
rgctl -r example/coolstore-weblogic -f json blast-radius <method>
rgctl -r example/coolstore-weblogic -f json blast-radius <method> --class <ClassName>
rgctl -r example/coolstore-weblogic -f json blast-radius <method> --file <ClassName>.java
rgctl -r example/coolstore-weblogic blast-radius <method>  # human-readable output

# Analyze field mutations for shared-state coupling
rgctl -r example/coolstore-weblogic -f json cpg mutations --type <ClassName> --exclude-ctors

# Enforce service boundaries in CI
rgctl -r example/coolstore-weblogic -f json check --policy-file policy.json

Application Migration using A Graph-Driven Approach with rgctl

Shaaf Syed — Mon, 31 Aug 2026 19:23:30 +0000

Application Migration using A Graph-Driven Approach with rgctl

Migrating an application takes a lot of time and energy, which itself is on a collision course
with complexity in codebases. Leaving aside the discussion on people and process. In this blog post
I would like to highlight the journey of migration and using a tool like Reachability Graph Control - rgctl which understands the codebase. Although I have taken an example of Java, the tool supports multiple languages like C, C#, Go, Node etc.

By taking this approach I am able to mine the code details via Call graphs, dependenices, data flow in code, slicing, blast radius, harmonic centrality, betweeness, semantic search and a little more of those things 😎.
rgctl takes one more step forward, using centraility, cfg etc, it creates migration hints. So one can choose the different ways to migrate and application.

A common question in application modernization is where do I start? You have a
monolith with dozens of tightly-coupled EJBs, JMS resources, JNDI lookups, and
vendor-specific descriptors. You need to get it onto Quarkus. The traditional
answer is a spreadsheet, tribal knowledge, and hope. This post walks through a
different approach: using static call-graph analysis to make migration decisions
based on structural data rather than guesswork.

I'll use rgctl to analyze a real
Java EE 7 application -- the CoolStore monolith -- and walk through the entire
migration from WebLogic to Quarkus, step by step, with actual tool output at
each stage.

The Application: CoolStore on WebLogic

The CoolStore is a Java EE 7 e-commerce application packaged as a WAR and
deployed on Oracle WebLogic Server 12.2.1.4. It has 25 Java classes across 5
packages:

com.redhat.coolstore/
  model/          8 classes   JPA entities and DTOs
  service/        9 classes   EJB business logic + MDBs
  rest/           4 classes   JAX-RS endpoints
  persistence/    1 class     CDI EntityManager producer
  utils/          3 classes   Logger producer, startup hook, transformers

The architecture follows a standard Java EE layered pattern:

Browser -> AngularJS SPA
             |
        JAX-RS /services/*
             |
    CartEndpoint    ProductEndpoint    OrderEndpoint
    @SessionScoped  @RequestScoped     @RequestScoped
             |              |               |
    ShoppingCart-    ProductService    OrderService
    Service         @Stateless        @Stateless
    @Stateful            |
         |          CatalogService
         |          @Stateless
         |               |
         +---> ShippingService @Remote (JNDI lookup)
         |
         +---> PromoService @ApplicationScoped
         |
         +---> ShoppingCartOrderProcessor @Stateless
                       |
                  JMS Topic (jms/topic/orders)
                       |
              +--------+--------+
              |                 |
        OrderServiceMDB    InventoryNotificationMDB
        (persist order)    (low-stock alerts)

The Java EE APIs in use that need migration work:

EJB: 5 @Stateless, 1 @Stateful, 1 @Singleton, 2 @MessageDriven
JMS: ConnectionFactory + Topic via @Resource(lookup=...), 2 MDB consumers
JNDI: InitialContext.lookup("ejb/ShippingService") for @Remote EJB
JPA: EclipseLink provider, @PersistenceContext, 4 entity classes
JAX-RS: 3 resource endpoints + @ApplicationPath activator
WebLogic-specific: weblogic.xml, weblogic-ejb-jar.xml, WLST scripts

Phase 1: Build the Call Graph

The first step is to index the codebase. rgctl's discover command parses
source files, builds the function-level call graph, computes centrality metrics,
detects communities, and pre-computes blast radius for every function:

$ rgctl discover example/coolstore-weblogic \
    --with-cfg \
    --with-harmonic \
    --with-security \
    --export-migration-hints \
    --migration-preset risk_mitigation

[>] rgctl discover
[!] Deep analysis enabled (--with-cfg / --with-taint).
[✓] Indexed 1226 files -> 14760 nodes, 50082 edges
Skipped files due to errors: 1
[✓] Analyzed 7526 functions (avg complexity: 1.0)
[✓] Detected 10870 communities (modularity: 0.30)
[!] Found 186 circular dependencies

✓ Security analysis:
  Potential secrets found: 5

✓ Control flow analysis:
  Field writes indexed: 3299
  CFG/PDG/Dominance: 6585 functions analyzed
  Skipped: 941 functions (unsupported language or parse error)

[✓] Migration plan (Risk Mitigation): 152 steps
[✓] rgctl discover finished in 22.7s

A few things to note:

186 circular dependencies -- this is normal for a Java EE monolith where EJBs freely inject each other. It is exactly the kind of coupling that makes migration ordering hard without tooling.
5 potential secrets -- the security scan flagged hardcoded values. In a real migration, you would rotate these before they end up in a Quarkus application.properties.
6585 functions analyzed -- the project includes bower_components (the AngularJS frontend), so the graph covers both Java and JavaScript. For migration purposes, I focus on the Java side, but the cross-language call edges (REST endpoint -> JS controller) are real and show up in blast radius.

The result is a .rgctl/ directory with the graph snapshot, blast engine
index, and a migration_plan.json.

Phase 2: Inventory the Codebase

Before planning, I need to understand what I have. Query the graph for all
Java classes:

$ rgctl -f json gql "MATCH (c:Class) RETURN c" 2>/dev/null \
  | python3 -c "
import json, sys
data = json.load(sys.stdin)
for row in data['rows']:
    for item in row:
        if '.java' in item.get('file',''):
            print(f'{item[\"node\"]:40s} {item[\"qualified_name\"]}')" \
  | sort

CartEndpoint                             com.redhat.coolstore.rest.CartEndpoint
CatalogItemEntity                        com.redhat.coolstore.model.CatalogItemEntity
CatalogService                           com.redhat.coolstore.service.CatalogService
InventoryEntity                          com.redhat.coolstore.model.InventoryEntity
InventoryNotificationMDB                 com.redhat.coolstore.service.InventoryNotificationMDB
Order                                    com.redhat.coolstore.model.Order
OrderEndpoint                            com.redhat.coolstore.rest.OrderEndpoint
OrderItem                                com.redhat.coolstore.model.OrderItem
OrderService                             com.redhat.coolstore.service.OrderService
OrderServiceMDB                          com.redhat.coolstore.service.OrderServiceMDB
Producers                                com.redhat.coolstore.utils.Producers
Product                                  com.redhat.coolstore.model.Product
ProductEndpoint                          com.redhat.coolstore.rest.ProductEndpoint
ProductService                           com.redhat.coolstore.service.ProductService
Promotion                                com.redhat.coolstore.model.Promotion
PromoService                             com.redhat.coolstore.service.PromoService
Resources                                com.redhat.coolstore.persistence.Resources
RestApplication                          com.redhat.coolstore.rest.RestApplication
ShippingService                          com.redhat.coolstore.service.ShippingService
ShoppingCart                             com.redhat.coolstore.model.ShoppingCart
ShoppingCartItem                         com.redhat.coolstore.model.ShoppingCartItem
ShoppingCartOrderProcessor               com.redhat.coolstore.service.ShoppingCartOrderProcessor
ShoppingCartService                      com.redhat.coolstore.service.ShoppingCartService
StartupListener                          com.redhat.coolstore.utils.StartupListener
Transformers                             com.redhat.coolstore.utils.Transformers

25 classes. Every one I need to touch is here.

Phase 3: Understand Risk with Blast Radius

Blast radius answers a specific question: "if I change this function, what
breaks upstream?" It uses pre-computed SCC (Strongly Connected Component)
decomposition of the call graph to identify all transitive callers of a given
symbol. The result is an impact score from 0 to 100, the list of direct callers,
and the full impact zone.

This is the most operationally useful tool for migration ordering. Let's run it
on the riskiest-looking class first -- ShoppingCartService:

$ rgctl -r example/coolstore-weblogic blast-radius getShoppingCart

Blast radius for 'getShoppingCart'
  Score: 40.5/100
  Direct callers: 6
  Impact zone: 10
  Callers: ShoppingCartService.checkOutShoppingCart,
           CartEndpoint.add,
           CartEndpoint.dedupeCartItems,
           CartEndpoint.delete,
           CartEndpoint.getCart,
           CartEndpoint.set
  Impact:  CartEndpoint.getCart,
           CartEndpoint.add,
           CartEndpoint.set,
           CartEndpoint.delete,
           CartEndpoint.dedupeCartItems,
           CartEndpoint.checkout,
           ShoppingCartService.checkOutShoppingCart,
           reset (controllers.js),
           performAction (controllers.js),
           anonymous (controllers.js)

A score of 40.5 with 10 nodes in the impact zone. Change getShoppingCart and
you potentially affect 6 Java methods plus 3 JavaScript controller functions.
That is a lot of surface area -- this is not where you want to start your
migration.

Now look at the JSON output for more detail:

$ rgctl -r example/coolstore-weblogic -f json blast-radius getShoppingCart

{
  "schema_version": 2,
  "target": {
    "canonical_fqn": "ShoppingCartService::getShoppingCart",
    "class_context": "ShoppingCartService",
    "file_path": ".../service/ShoppingCartService.java",
    "language": "java",
    "signature": "public ShoppingCart getShoppingCart(String cartId) {"
  },
  "metrics": {
    "score": 40.5,
    "direct_callers_count": 6,
    "impact_zone_size": 10
  },
  "topology": {
    "scc_component_id": 580,
    "direct_callers": [
      {"fqn": "com.redhat.coolstore.service.ShoppingCartService.checkOutShoppingCart"},
      {"fqn": "com.redhat.coolstore.rest.CartEndpoint.add"},
      {"fqn": "com.redhat.coolstore.rest.CartEndpoint.dedupeCartItems"},
      {"fqn": "com.redhat.coolstore.rest.CartEndpoint.delete"},
      {"fqn": "com.redhat.coolstore.rest.CartEndpoint.getCart"},
      {"fqn": "com.redhat.coolstore.rest.CartEndpoint.set"}
    ],
    "impact_zone": ["...10 entries..."]
  },
  "gatekeeping": {
    "policy_status": "SKIPPED"
  }
}

The scc_component_id: 580 tells me this function is part of a strongly
connected component in the call graph -- there are cycles (which matches the 186
circular dependencies the discover phase reported).

Let's compare with a simpler function:

$ rgctl -r example/coolstore-weblogic -f json blast-radius calculateShipping \
    --file ShippingService.java

{
  "target": {
    "canonical_fqn": "ShippingService::calculateShipping",
    "class_context": "ShippingService"
  },
  "metrics": {
    "score": 0.0,
    "direct_callers_count": 0,
    "impact_zone_size": 0
  }
}

Score of 0.0. Zero direct callers in the static graph. ShippingService is
called via JNDI lookup (InitialContext.lookup("ejb/ShippingService")), which
is a runtime dispatch that static analysis cannot resolve. This is actually
useful information: it tells me this class is structurally isolated. I can
migrate it safely without breaking any statically-visible call paths.

A few more blast radius checks to build the full picture:

Symbol	Score	Direct Callers	Impact Zone
`ShoppingCartService::` `getShoppingCart`	40.5	6	10
`ShoppingCartService::` `priceShoppingCart`	40.4	5	7
`ShoppingCartService::` `checkOutShoppingCart`	25.1	1	2
`ProductService::` `getProducts`	40.1	2	2
`PromoService::` `applyCartItemPromotions`	25.4	1	8
`CatalogService::` `getCatalogItems`	25.1	1	3
`OrderService::` `getOrders`	25.1	1	1
`CartEndpoint::` `checkout`	25.1	1	1
`OrderServiceMDB::` `onMessage`	0.0	0	0
`ShippingService::` `calculateShipping`	0.0	0	0

The pattern is clear: the ShoppingCartService methods have the highest blast
radius because everything flows through the cart. The MDBs and
ShippingService have zero because they are invoked through JMS and JNDI
respectively -- runtime dispatch, not static calls.

Phase 4: Read the Migration Plan

The --export-migration-hints flag during discover produced a
migration_plan.json. This is a package-level roadmap that combines three
signals into a priority score:

PageRank (alpha) -- how central the package is in the call graph
Harmonic centrality (beta) -- how reachable the package is from all others
Max blast radius (gamma) -- the worst-case impact of changing anything in the package

The priority formula:

Priority(p) = alpha * norm(pagerank) + beta * norm(harmonic) - gamma * norm(max_blast)

I used --migration-preset risk_mitigation, which sets gamma = 0.70 --
heavily penalizing high-blast packages. This means the plan orders safe,
low-impact packages first.

$ cat .rgctl/migration_plan.json | python3 -c "
import json, sys
data = json.load(sys.stdin)
for s in data['steps']:
    if 'redhat' in s['label']:
        print(f'Step {s[\"step\"]:3d} | schedule:{s[\"schedule_step\"]:3d} '
              f'| rank:{s[\"priority_rank\"]:3d} '
              f'| score:{s[\"priority_score\"]:+.4f} | {s[\"label\"]}')"

Step   2 | schedule:  2 | rank: 72 | score:-0.3424 | com.redhat.coolstore.model
Step  49 | schedule: 49 | rank:127 | score:-0.3500 | com.redhat.coolstore.persistence
Step  76 | schedule: 76 | rank:  2 | score:-0.1801 | com.redhat.coolstore.rest
Step  84 | schedule: 84 | rank: 10 | score:-0.2695 | com.redhat.coolstore.utils
Step  87 | schedule: 87 | rank: 13 | score:-0.2791 | com.redhat.coolstore.service

The schedule_step column is a dependency-aware topological sort (Kahn's
algorithm on the package call graph): packages that are called by others come
first. The priority_rank column is pure score ranking.

Reading this:

com.redhat.coolstore.model (step 2) -- migrate first. These are JPA entities and POJOs. They sit at the bottom of the dependency chain and nothing else breaks when you change them.
com.redhat.coolstore.persistence (step 49) -- the Resources CDI producer for EntityManager. Small, isolated.
com.redhat.coolstore.rest (step 76) -- the REST endpoints. They sit at the top of the call chain (rank 2 by priority, meaning high harmonic centrality) but depend on everything below.
com.redhat.coolstore.utils (step 84) -- utility classes.
com.redhat.coolstore.service (step 87) -- the EJB layer. Migrated last because it has the most complexity (stateful beans, JMS, JNDI) and the highest aggregate blast radius.

This ordering matches engineering intuition, but it was derived from the graph
structure, not from guessing.

Phase 5: Execute the Migration

With the analysis done, I migrate package by package following the plan. Below
is the concrete work for each phase.

Step 1: Entities and DTOs (`com.redhat.coolstore.model`)

The model classes need three changes:

Namespace: javax.persistence.* -> jakarta.persistence.*
Drop JAXB: Remove @XmlRootElement from InventoryEntity (Quarkus uses Jackson by default)
JPA provider: Switch from EclipseLink to Hibernate ORM (Quarkus default)

Before (CatalogItemEntity.java):

import javax.persistence.Entity;
import javax.persistence.Table;
// ...

After:

import jakarta.persistence.Entity;
import jakarta.persistence.Table;
// ...

The ShoppingCart class is annotated @Dependent (CDI). In Quarkus, this
continues to work as-is after the namespace change.

Delete persistence.xml entirely. Replace with application.properties:

quarkus.datasource.db-kind=h2
quarkus.datasource.jdbc.url=jdbc:h2:mem:coolstore;DB_CLOSE_DELAY=-1
quarkus.hibernate-orm.database.generation=drop-and-create
quarkus.hibernate-orm.sql-load-script=import.sql

This is safe. Blast radius for the model classes is low -- they are callees, not
callers.

Step 2: Persistence Producer (`com.redhat.coolstore.persistence`)

The Resources class produces an EntityManager via @PersistenceContext:

// Before
@PersistenceContext
@Produces
private EntityManager em;

In Quarkus, you do not need a CDI producer for EntityManager. Quarkus injects
it directly. Remove the Resources class entirely and inject EntityManager
where needed:

// After (in service classes)
@Inject
EntityManager em;

Step 3: Utilities (`com.redhat.coolstore.utils`)

Producers.java -- The Logger CDI producer works in Quarkus after
javax -> jakarta namespace changes. Alternatively, Quarkus provides built-in
logging via @Inject Logger or the jboss-logging API.

StartupListener.java -- This is an EJB @Singleton + @Startup:

// Before
@Singleton
@Startup
public class StartupListener {
    @PostConstruct
    public void onStartup() {
        log.info("CoolStore Application Started");
    }
}

Replace with Quarkus CDI lifecycle event:

// After
@ApplicationScoped
public class StartupListener {
    void onStartup(@Observes StartupEvent event) {
        Log.info("CoolStore Application Started");
    }
}

Transformers.java -- Uses javax.json.* (JSON-P) for manual JSON
building. In Quarkus, replace with Jackson ObjectMapper or keep JSON-P with
the quarkus-jsonp extension. Either works; Jackson is the path of least
resistance since Quarkus RESTEasy uses it by default.

Step 4: ShippingService (low-risk EJB extraction)

Blast radius: 0.0. This is the ideal first EJB to migrate.

Before:

@Stateless
@Remote
public class ShippingService implements ShippingServiceRemote {
    @Override
    public double calculateShipping(ShoppingCart sc) {
        // price-based shipping tiers
    }
}

After:

@ApplicationScoped
public class ShippingService {
    public double calculateShipping(ShoppingCart sc) {
        // same logic, no EJB, no @Remote
    }
}

Remove the ShippingServiceRemote interface entirely. Remove the JNDI lookup
in ShoppingCartService:

// Before (ShoppingCartService.java line 114-122)
private static ShippingServiceRemote lookupShippingServiceRemote() {
    try {
        final Context context = new InitialContext();
        return (ShippingServiceRemote) context.lookup("ejb/ShippingService");
    } catch (NamingException e) {
        throw new RuntimeException(e);
    }
}

Replace with CDI injection:

// After
@Inject
ShippingService shippingService;

// In priceShoppingCart(), replace:
//   lookupShippingServiceRemote().calculateShipping(sc)
// with:
//   shippingService.calculateShipping(sc)

This eliminates the JNDI dependency, the @Remote interface, and the
weblogic.xml JNDI binding for ejb/ShippingService.

Step 5: Stateless EJBs (CatalogService, OrderService, ProductService, PromoService)

These all follow the same pattern. Take CatalogService:

Before:

@Stateless
public class CatalogService {
    @Inject
    private EntityManager em;

    public List<CatalogItemEntity> getCatalogItems() {
        CriteriaBuilder cb = em.getCriteriaBuilder();
        CriteriaQuery<CatalogItemEntity> criteria = cb.createQuery(CatalogItemEntity.class);
        Root<CatalogItemEntity> member = criteria.from(CatalogItemEntity.class);
        criteria.select(member);
        return em.createQuery(criteria).getResultList();
    }
}

After:

@ApplicationScoped
@Transactional
public class CatalogService {
    @Inject
    EntityManager em;

    public List<CatalogItemEntity> getCatalogItems() {
        // Same JPA logic -- works identically on Hibernate
    }
}

The change: @Stateless -> @ApplicationScoped + @Transactional. The JPA
code remains the same. Quarkus's Hibernate ORM handles the EntityManager
lifecycle.

Blast radius for CatalogService::getCatalogItems is 25.1 (1 direct caller:
ProductService.getProducts, which propagates to ProductEndpoint.listAll).
Moderate risk, but manageable because the callers are simple pass-through methods.

Apply the same pattern to OrderService, ProductService, and PromoService.

Step 6: ShoppingCartOrderProcessor (JMS producer)

This is the most involved single-class change. The original uses WebLogic JMS
resources injected via JNDI:

@Stateless
public class ShoppingCartOrderProcessor {
    @Resource(lookup = "weblogic.jms.ConnectionFactory")
    private ConnectionFactory connectionFactory;

    @Resource(lookup = "jms/topic/orders")
    private Topic ordersTopic;

    public void process(ShoppingCart cart) {
        try (JMSContext context = connectionFactory.createContext()) {
            context.createProducer().send(ordersTopic,
                Transformers.shoppingCartToJson(cart));
        }
    }
}

Two options for Quarkus:

Option A: SmallRye Reactive Messaging (recommended)

@ApplicationScoped
public class ShoppingCartOrderProcessor {
    @Inject
    @Channel("orders")
    Emitter<String> ordersEmitter;

    public void process(ShoppingCart cart) {
        ordersEmitter.send(Transformers.shoppingCartToJson(cart));
    }
}

With application.properties:

mp.messaging.outgoing.orders.connector=smallrye-in-memory
# or for Kafka: smallrye-kafka
# or for AMQP: smallrye-amqp

Option B: Quarkus Artemis JMS (if you want to keep JMS semantics):

@ApplicationScoped
public class ShoppingCartOrderProcessor {
    @Inject
    ConnectionFactory connectionFactory;

    public void process(ShoppingCart cart) {
        try (JMSContext context = connectionFactory.createContext()) {
            context.createProducer().send(
                context.createTopic("orders"),
                Transformers.shoppingCartToJson(cart));
        }
    }
}

Step 7: Message-Driven Beans (OrderServiceMDB, InventoryNotificationMDB)

Both MDBs have blast radius of 0.0 (they are entry points, invoked by the
messaging runtime, not by application code). But they depend on services
migrated in earlier steps, so they must come after.

OrderServiceMDB -- before:

@MessageDriven(name = "OrderServiceMDB", activationConfig = {
    @ActivationConfigProperty(propertyName = "destinationLookup",
                              propertyValue = "topic/orders"),
    @ActivationConfigProperty(propertyName = "destinationType",
                              propertyValue = "javax.jms.Topic"),
    @ActivationConfigProperty(propertyName = "acknowledgeMode",
                              propertyValue = "Auto-acknowledge")})
public class OrderServiceMDB implements MessageListener {
    @Inject OrderService orderService;
    @Inject CatalogService catalogService;

    @Override
    public void onMessage(Message rcvMessage) {
        TextMessage msg = (TextMessage) rcvMessage;
        String orderStr = msg.getBody(String.class);
        Order order = Transformers.jsonToOrder(orderStr);
        orderService.save(order);
        order.getItemList().forEach(orderItem -> {
            catalogService.updateInventoryItems(
                orderItem.getProductId(), orderItem.getQuantity());
        });
    }
}

After (SmallRye Reactive Messaging):

@ApplicationScoped
public class OrderServiceMDB {
    @Inject OrderService orderService;
    @Inject CatalogService catalogService;

    @Incoming("orders")
    public void onMessage(String orderStr) {
        Order order = Transformers.jsonToOrder(orderStr);
        orderService.save(order);
        order.getItemList().forEach(orderItem -> {
            catalogService.updateInventoryItems(
                orderItem.getProductId(), orderItem.getQuantity());
        });
    }
}

The @MessageDriven annotation, MessageListener interface,
ActivationConfigProperty array, and JMS Message unwrapping are all gone.
The method now takes a String directly from the channel.

Apply the same pattern to InventoryNotificationMDB.

Step 8: ShoppingCartService (the hard one)

This is the highest-risk class: blast radius of 40.5 for getShoppingCart,
40.4 for priceShoppingCart. It has three problems:

@Stateful EJB -- holds a ShoppingCart instance in memory per session
JNDI lookup -- InitialContext.lookup("ejb/ShippingService")
Injects other EJBs -- ProductService, PromoService, ShoppingCartOrderProcessor

The JNDI lookup was already eliminated in Step 4. The other EJBs were migrated
to CDI beans in Steps 5-6. What remains is the stateful nature.

Before:

@Stateful
public class ShoppingCartService {
    private ShoppingCart cart = new ShoppingCart();

    public ShoppingCart getShoppingCart(String cartId) {
        return cart;
    }
    // ...
}

Quarkus has no EJB container, so @Stateful does not exist. The cart state
needs to go somewhere. For a monolith migration, the simplest option is
@ApplicationScoped with a ConcurrentHashMap:

@ApplicationScoped
public class ShoppingCartService {
    private final ConcurrentHashMap<String, ShoppingCart> carts = new ConcurrentHashMap<>();

    public ShoppingCart getShoppingCart(String cartId) {
        return carts.computeIfAbsent(cartId, k -> new ShoppingCart());
    }
    // ...
}

For production use, back this with Redis or a database. But for a migration
that preserves behavior, the in-memory map is functionally equivalent.

Step 9: REST Endpoints

The JAX-RS endpoints need:

javax.ws.rs.* -> jakarta.ws.rs.*
Remove RestApplication.java (Quarkus auto-discovers JAX-RS resources)
Fix CartEndpoint's @SessionScoped -- Quarkus does not support @SessionScoped for REST endpoints by default

CartEndpoint before:

@SessionScoped
@Path("/cart")
public class CartEndpoint implements Serializable {
    @Inject
    private ShoppingCartService shoppingCartService;
    // ...
}

After:

@RequestScoped
@Path("/cart")
public class CartEndpoint {
    @Inject
    ShoppingCartService shoppingCartService;
    // ...
}

Since ShoppingCartService now manages cart state by ID (the ConcurrentHashMap
approach), the endpoint no longer needs to be @SessionScoped.

Step 10: WebLogic Descriptors

Delete:

WEB-INF/weblogic.xml -- JNDI mappings, session replication config, classloader preferences. None apply to Quarkus.
WEB-INF/weblogic-ejb-jar.xml -- EJB pool sizes, stateful cache/clustering, MDB destination bindings. None apply.
weblogic-config/*.py -- WLST domain creation scripts.
docker-compose.yml -- WebLogic container definition.

Replace persistence.xml with application.properties (done in Step 1).

Step 11: Frontend

The JSP files (index.jsp, health.jsp) do not work in Quarkus. Move the
AngularJS SPA to src/main/resources/META-INF/resources/ and serve as static
files. Replace health.jsp with the Quarkus SmallRye Health extension:

# pom.xml dependency
quarkus-smallrye-health
# exposes /q/health automatically

Phase 6: CI Guardrails

After the migration, set up policy checks to prevent regressions. Write a
policy.json:

{
  "max_impact_nodes": 15,
  "centrality_alert_threshold": 0.8
}

Gate PRs in CI:

$ rgctl discover . --with-cfg --with-harmonic --export-migration-hints
$ rgctl -f json check --policy-file policy.json

If any changed function has a blast radius exceeding 15 impact nodes, or if the
impact zone crosses a high-betweenness bridge node, the check exits with code 1
and the PR fails. This is useful during the migration itself to catch accidental
scope creep -- changing a "safe" class that inadvertently pulls in a high-blast
dependency.

Summary

The migration order derived from the call graph analysis:

Step	Package/Class	Blast Radius	Change
1	`model/*` (entities, DTOs)	Low	`javax` -> `jakarta` namespace
2	`persistence/Resources`	0.0	Delete (Quarkus injects EntityManager)
3	`utils/*`	Low	`@Singleton @Startup` -> `@Observes StartupEvent`
4	`ShippingService`	0.0	Drop `@Remote`, `@Stateless` -> `@ApplicationScoped`, delete JNDI lookup
5	`CatalogService`, `OrderService`, `ProductService`, `PromoService`	25.1	`@Stateless` -> `@ApplicationScoped @Transactional`
6	`ShoppingCartOrderProcessor`	Moderate	JMS `@Resource` -> SmallRye Reactive Messaging `@Channel`
7	`OrderServiceMDB`, `InventoryNotificationMDB`	0.0	`@MessageDriven` -> `@Incoming`
8	`ShoppingCartService`	40.5	`@Stateful` -> `@ApplicationScoped` + external state
9	REST endpoints	25.1	`@SessionScoped` -> `@RequestScoped`, remove `RestApplication`
10	WebLogic descriptors	--	Delete `weblogic.xml`, `weblogic-ejb-jar.xml`
11	Frontend	--	JSP -> static files, add SmallRye Health

The key insight is not that this ordering is surprising -- an experienced Java
EE developer would likely arrive at a similar sequence. The point is that the
call graph provides structural evidence for migration decisions. When you are
working on a codebase you do not know well, or one with 500 classes instead of
25, the blast radius numbers replace guesswork with data. A score of 40.5 means
something concrete: 6 direct callers and 10 transitive dependents. That is the
scope of what needs testing after you touch that method.

The migration plan's topological sort also catches dependency ordering mistakes
that are easy to make manually. You cannot migrate ShoppingCartService before
ShippingService because the JNDI lookup replacement requires ShippingService
to already be a CDI bean. The plan encodes this constraint automatically.

For larger codebases -- hundreds of EJBs, nested module dependencies, shared
libraries -- this kind of structural analysis scales where spreadsheets do not.

Try it out

Stop migrating by spreadsheet and tribal knowledge. If you are staring down a monolith and wondering where the hidden dependencies are, let the call graph tell you.

Get the tool: Grab rgctl from GitHub.
Test it on your own codebase: Navigate to your project root and run rgctl discover . --export-migration-hints to index your application.
Stop guessing: Run rgctl blast-radius on your most heavily-used service and see exactly what you will break before you write a single line of code.

Lessons from Building My First Claude Skill - a code tutorial generator

Shaaf Syed — Thu, 07 May 2026 07:49:57 +0000

About a year ago, I kicked off (Waver), a project designed to analyze codebases and build developer friendly, readable tutorials. The goal was to generate clean Markdown and Mermaid diagrams so onboarding becomes frictionless and the docs can slide right into existing project pipelines.

I chose Langchain4J for the LLM integration. And in a classic "engineers-quest", I actually ended up building JGraphlet as well, which came to life while I was trying to squeeze better performance out of the LLM communication.

Working in pure Java offers clear benefits, specifically regarding granular control and performance optimization. However, these implementations often become highly opinionated. In contrast, while SKILLS maintains a degree of opinionated design, its actual application depends entirely on the coding agent. Both methods have advantages, and I’m using this post to process what I’ve learned while writing my first SKILL. Here is a code example from my Java project.

package dev.shaaf.waver.cli;

import dev.langchain4j.model.chat.ChatModel;
import dev.shaaf.jgraphlet.TaskPipeline;
import dev.shaaf.waver.llm.config.AppConfig;
import dev.shaaf.waver.llm.config.ModelProviderFactory;
import dev.shaaf.waver.llm.tutorial.task.*;

import java.nio.file.Path;
import java.nio.file.Paths;
import java.util.logging.Logger;

public class TutorialGenerator {

    private static final Logger logger = Logger.getLogger(TutorialGenerator.class.getName());


    public static void generate(AppConfig appConfig) {

        ChatModel chatModel = ModelProviderFactory.buildChatModel(appConfig.llmProvider(), appConfig.apiKey());
        Path outputDir = Paths.get(appConfig.absoluteOutputPath() + "/" + appConfig.projectName());

        logger.info("🚀 Starting Tutorial Generation for: " + appConfig.inputPath());
        try (TaskPipeline tasksPipeLine = new TaskPipeline()) {
            tasksPipeLine.add("Code-crawler", new CodeCrawlerTask())
                    .then("Identify-abstraction", new IdentifyAbstractionsTask(chatModel, appConfig.projectName()))
                    .then("Identify-relationships", new IdentifyRelationshipsTask(chatModel, appConfig.projectName()))
                    .then("Chapter-organizer", new ChapterOrganizerTask(chatModel))
                    .then("Technical-writer", new TechnicalWriterTask(chatModel, outputDir))
                    .then("Meta-info", new MetaInfoTask(chatModel, outputDir, appConfig.projectName(), appConfig.inputPath()));
            tasksPipeLine.run(appConfig.inputPath()).join();
            logger.info("\n✅ Tutorial generation complete! Output located at: " + outputDir);
        }

    }
}

All of these Tasks in the TaskPipeline above are backed by a prompt. So basically its prompt chaining. There wasnt much about SKILLS.md back then. Fast track to today. I have tried to take all the prompts and put them in a Skill instead. And atleast from the intial tests I am looking at its looking pretty good. For example here is a mermaid drawing generated from one of Scribe's code base (an MCP server)

graph TD
    KantraTool[KantraTool<br/>MCP Server Entry Point] -->|queries availability| CommandRegistry[CommandRegistry<br/>Plugin System]
    KantraTool -->|invokes execute| KantraCommand[KantraCommand<br/>Command Interface]
    KantraTool -->|accepts as parameter| KantraOperation[KantraOperation<br/>Operation Catalog]

    CommandRegistry -->|discovers via CDI| KantraCommand
    CommandRegistry -->|uses as map key| KantraOperation
    CommandRegistry -->|applies filtering| CommandConfig[Configuration System]

    KantraCommand -->|declares operation| KantraOperation

    ConcreteCommands[Concrete Command<br/>Implementations] -->|extends| AbstractCommand[AbstractCommand<br/>Command Base Class]
    ConcreteCommands -->|constructs| Rule[Rule<br/>Domain Model]
    ConcreteCommands -->|creates instances| Condition[Condition<br/>Polymorphic Detection]

    AbstractCommand -->|delegates serialization| RuleValidator[RuleValidator<br/>Validation Service]
    AbstractCommand -->|converts to enums| DomainEnums[Domain Enumerations<br/>JavaLocation, Category]
    AbstractCommand -->|constructs| SupportingModels[Supporting Model Classes<br/>Link, CustomVariable]

    Rule -->|contains when field| Condition
    Rule -->|uses category| DomainEnums
    Rule -->|composes| SupportingModels

    Condition -->|references| DomainEnums
    Condition -->|contains| SupportingModels

    RuleValidator -->|validates & serializes| Rule
    RuleValidator -->|validates recursively| Condition

    style KantraTool fill:#e1f5ff,stroke:#0066cc,stroke-width:3px
    style Rule fill:#fff4e1,stroke:#ff9900,stroke-width:2px
    style Condition fill:#fff4e1,stroke:#ff9900,stroke-width:2px
    style CommandRegistry fill:#e8f5e9,stroke:#4caf50,stroke-width:2px
    style RuleValidator fill:#e8f5e9,stroke:#4caf50,stroke-width:2px

Building the SKILLS.md

Lets take a look at the basic file structure when creating a skill.

File Structure

SKILL.md - Main skill definition and instructions
package.json - NPM package configuration
installer.js - Installation script
bin/ - Executable commands
tests/ - Test files, in my case these are test projects in multiple languages so I can compare whats generated.

The Skills file is quite large (100+ lines), here is a little snippet from the code discover phase during anaylsis.

1. Determine project details:
   - If user provided path in command (e.g., `/tutorial analyze ./src`), use that
   - Otherwise ask: "What directory should I analyze?"
   - Auto-detect primary language from file extensions
   - Ask if they want to focus on specific areas (optional)

2. Find source files using Glob:
   - **Java**: `**/*.java` (exclude `**/test/**`, `**/target/**`)
   - **Python**: `**/*.py` (exclude `**/test/**`, `**/__pycache__/**`, `**/venv/**`)
   - **JavaScript/TypeScript**: `**/*.{js,ts,jsx,tsx}` (exclude `**/node_modules/**`, `**/dist/**`, `**/build/**`)
   - **Go**: `**/*.go` (exclude `**/*_test.go`, `**/vendor/**`)
   - **C#**: `**/*.cs` (exclude `**/bin/**`, `**/obj/**`)
   - **Ruby**: `**/*.rb` (exclude `**/spec/**`, `**/test/**`)
   - **Rust**: `**/*.rs` (exclude `**/target/**`)
   - **PHP**: `**/*.php` (exclude `**/vendor/**`, `**/tests/**`)

3. Handle large codebases:
   - If >50 files found, ask: "Found {N} files. Analyze all or focus on specific subdirectory?"
   - Suggest core directories: `src/main`, `lib`, `app`, etc.

4. Read discovered files with Read tool
5. Report: "Found {N} files totaling {LOC} lines of code"

Quick start

npx @sshaaf/tutorial-skill install

# reload the coding agent. e.g. claude.

/tutorial build

#You can preview the files in markdown on disk. for example preview in VSCode. 
#However if you want to preview in html then use the following command.

/tutorial preview

Skill Modes

Currently the Skill is built into two modes. This is exactly what Waver also did, analyze the code base and then generte a contextual tutorial. Here I have broken down that process, so if users just want very basic documentation like the mermaid diagram above with some markdown of the analysis they can do that. Else building tutorial which is the second mode has more steps, to make in consumable and nice 😎

/tutorial analyze - Analyze Mode

3-stage pipeline for quick codebase understanding
Generates architecture diagrams with Mermaid
NEW: Option to save diagrams to disk
Time: 2-5 minutes

/tutorial build - Build Mode

6-stage pipeline for comprehensive tutorial generation
Creates multi-chapter Markdown tutorials
Time: 10-30 minutes

More Commands

While the above commands publish markdown onto disk, it can also be useful to preview them or even push them into github pages. Following will allow previewing locally and checking that it all works.

/tutorial preview

Local tutorial preview with HonKit
Time: 5-30 seconds to start
Output: Local docs site (usually http://localhost:4000)
Use for: Reviewing generated docs before publishing

/tutorial doctor

Diagnostics for local preview/runtime + docs scaffolding
Time: ~10-30 seconds
Output: Pass/fail checklist
Use for: Verifying HonKit runtime + book.json before publishing

The markdown can also be pushed into github pages. Here is a nice example from @Kim Borup

How to use it: Tutorial Generator & Analyzer

# Quick analysis
/tutorial analyze .

# With path
/tutorial analyze ./src/main/java

# Full tutorial
/tutorial build .

# With output directory
/tutorial build --output ./docs/tutorial

# Preview generated tutorial in Claude mode
/tutorial preview ./docs/tutorial

# Diagnose local preview/runtime/docs scaffolding
/tutorial doctor ./docs/tutorial

# Initialize docs files for HonKit
npx @sshaaf/tutorial-skill docs init --dir ./docs/tutorial

# Preview locally with HonKit
npx @sshaaf/tutorial-skill docs preview --dir ./docs/tutorial

# Build static site with HonKit
npx @sshaaf/tutorial-skill docs build --dir ./docs/tutorial

# Diagnose runtime/plugin setup
npx @sshaaf/tutorial-skill docs doctor --dir ./docs/tutorial

The difference

SKILL works directly within Claude Code CLI - no separate tools needed, integrates into the developer workflow. No setup or installation and is pretty aware of the context.
Waver on the other hand complete control on which models are being used, can run parallel and join tasks with its use of JGraphlet, can easily integarte into CI and batch modes for multiple projects etc.

What happens if I edit some files and regenerate? Well how Gen-AI is, it might not chosse the same chapter names or order again. So making a diff is perhaps not useful. Context at that point would mismatch.
So the real use is that the skill and prompt has nailed what it gets out of it. For me I think generating the first time is a good starting point, to start editing. I probably wont use Gen-AI over and over again for the same generation if I am happy with the first one. At its core, it gives a good structure to start with.

Furthermore in the prompt you can ask the agent to do some checks and verifications after the tutorial is generated. However evals could be done as well, likely with other skills or mcp tools etc. This is important incase of hallucinations.

I am not entirely sure if there is an either or an or here, I would still prefer waver just because its a simplified CLI approach, which is pretty solid for multiple cases, however as soon as we speak about developer workflow a Skill makes a lot more sense when one is using Claude or OpenCode etc. I think there is another bit of optmization here that can be investigated where I can take the waver project and integrate it within the skill, so the skill can handover some of the work. A back an forth to take the best of the two.

I have to admit; defining constraints in plain English and letting a coding agent determine the implementation is quite daunting. It requires a significant mindset shift, and I’m eager to see how this scales and where the true limitations lie.

The skill is live, and the journey from a standalone cli to an NPM-distributable skill is complete. Now, the real testing begins 😎😊

May 10 update: NPM package has been updated with some command deperecated (analyze, preveiw, doctor) and new features added e.g. asciidoc.

View the project: github.com/sshaaf/tutorial-skill

Try it out: npx @sshaaf/tutorial-skill

Rendering powerpoint to png files with JBang

Shaaf Syed — Wed, 29 Apr 2026 13:18:33 +0000

Part of my daily work is to create instructions for workshops, and labs. One of the things in that entire content creation process, is to take screenshots and matching instructions and inorder to do that sometimes I need to add arrows, boxes, etc.. Using something like Google docs is pretty easy at that point, drag the screen shot create the overlay items. This time around I ended up having tons of such slides (a little over exaggeration). The next problem, download them as PNG files to add to the instructions. Out of all the nice usability tricks Google docs does not allow me to optimize on this. So I have to download one slide image at a time. yes really!! Well that was some rant, but hey now we have a JBang script that will do the rest. :)

This post demonstrates how to leverage JBang and Apache POI to build a zero-ceremony script that renders PPTX slides to high-DPI PNGs.

JBang: For utility scripts, the overhead of a Maven/Gradle project is a deterrent. JBang eliminates this by allowing "script-style" Java execution. It handles dependency resolution, compilation, and caching in the background, making Java a viable alternative to Python or Bash for system automation.

Okay so here is the solution that uses Apache POI's Common SL (SlideShow) API to parse the OOXML structure and Java 2D (Graphics2D) for the rasterization.

1. Dependency Management

Using JBang's //DEPS directives, we pull in the necessary POI components.

///usr/bin/env jbang "$0" "$@" ; exit $?
//DEPS org.apache.poi:poi:5.2.5
//DEPS org.apache.poi:poi-ooxml:5.2.5
//DEPS org.apache.poi:poi-scratchpad:5.2.5
//DEPS org.apache.logging.log4j:log4j-core:2.20.0

Note: poi-ooxml is required for .pptx (XML-based) files, while poi-scratchpad provides support for the older .ppt (OLE2) format if needed.

2. Initializing the SlideShow

We use Try-with-Resources to ensure the FileInputStream and XMLSlideShow containers are disposed of correctly, preventing memory leaks during batch processing.

try (FileInputStream fis = new FileInputStream(pptxFile);
     XMLSlideShow ppt = new XMLSlideShow(fis)) {

    Dimension pgsize = ppt.getPageSize(); // The logical slide dimensions
    List<XSLFSlide> slides = ppt.getSlides();
    // ... iteration logic
}

3. Scaling and Precision Math

PowerPoint defines slide dimensions in points (where 1 point = 1/72 inch). To produce high-resolution output (e.g., 300 DPI), we must calculate a scale factor relative to this 72 DPI baseline.

double scale = targetDpi / 72.0;
int width = (int) Math.ceil(pgsize.width * scale);
int height = (int) Math.ceil(pgsize.height * scale);

4. Configuring the Graphics Context

To avoid pixelation and "aliased" text, we must explicitly configure the Graphics2D rendering pipeline.

Hint Key	Value	Purpose
`KEY_ANTIALIASING`	`VALUE_ANTIALIAS_ON`	Smooths vector edges and shapes.
`KEY_TEXT_ANTIALIASING`	`VALUE_TEXT_ANTIALIAS_ON`	Ensures readable, sharp typography.
`KEY_INTERPOLATION`	`VALUE_INTERPOLATION_BICUBIC`	High-quality image downsampling/upsampling.
`KEY_RENDERING`	`VALUE_RENDER_QUALITY`	General preference for fidelity over speed.

BufferedImage img = new BufferedImage(width, height, BufferedImage.TYPE_INT_ARGB);
Graphics2D graphics = img.createGraphics();

graphics.setRenderingHints(Map.of(
    RenderingHints.KEY_ANTIALIASING, RenderingHints.VALUE_ANTIALIAS_ON,
    RenderingHints.KEY_INTERPOLATION, RenderingHints.VALUE_INTERPOLATION_BICUBIC,
    RenderingHints.KEY_TEXT_ANTIALIASING, RenderingHints.VALUE_TEXT_ANTIALIAS_ON
));

graphics.scale(scale, scale); // Map logical points to pixel coordinates

5. Execution and Output

The slide.draw(graphics) call is where the heavy lifting happens. Apache POI iterates through the slide's visual tree (shapes, text boxes, images) and issues the corresponding draw commands to our scaled graphics context.

slide.draw(graphics);
ImageIO.write(img, "PNG", new File(outputName));
graphics.dispose();

Running the Script

Once saved as pptx2png.java, make the script executable and run it directly. JBang will fetch the JARs on the first run and cache them at ~/.jbang.

chmod +x pptx2png.java
./pptx2png.java my_deck.pptx out_prefix 300

Well that made life a step easier. ;)
Scritpt source available [here].(https://github.com/sshaaf/jbang-catalog/blob/main/src/pptx2png.java)

Modernizing Legacy Code with Konveyor AI: From EJB to Kubernetes

Shaaf Syed — Wed, 15 Apr 2026 11:06:09 +0000

I always enjoy participating in KubeCon. This time it was at the RAI center in Amsterdam. I have been to many conferences and the ones that are the best IMHO are the ones that are very community focused. For example DevNexus for Java, GeeCon for Geeks ;), and obviously KubeCon for everything Kubernetes. And obvsiouly making new friends and connections is a great way of learning from all the cool stuff thats going on. Thats probably enough name dropping for a wednesday ;)

I had the opportunity to represent the Konveyor Community project update.

Modernizing Legacy Code with Konveyor AI: From EJB to Kubernetes

"We want to have a meaningful result out of generative AI, not just chatting around... we can context engineer that code, send it into the LLM, and get results integrated back into the codebase." — Shaaf Syed

Application modernization is a daunting task, especially when dealing with legacy codebases that are decades old. In my recent CNCF Project Lightning Talk, I introduced how the Konveyor community is leveraging AI and static analysis to automate this process for almost any programming language. While there are multiple ways of solving the migration and modernization challenges, Konveyor community takes a unique approach to it.

For example many enterprises still rely on 30-year-old Enterprise Java Beans (EJB) or legacy protocols like RMI/IIOP. When leadership asks to move these applications to Kubernetes, developers face a nightmare of serialization issues, stubs, and complex clustering logic that simply doesn't fit a modern cloud-native environment. It like you just encountered the "Legacy Wall!". Nothing can get passed that point. True, but hardly anymore IMHO. Why not use the traditional static code anaylsis to enahnce the responses of an LLM.

During the talk, I demonstrated a live example of an outdated EJB, i.e. being transformed into a modern REST service. What would normally take hours of manual refactoring was reduced to a generated Git patch that the developer could simply review and apply.

Konveyor solves this by combining deep static code analysis with the power of Large Language Models (LLMs). The core workflow involves:

Static Code Analysis: The engine analyzes source code (Java, Go, Python, NodeJS, etc.) to identify "incidents"—specific lines of code that won't run on Kubernetes.
Context Engineering: By understanding the code paths via the Language Server Protocol (LSP), Konveyor provides the necessary context to an LLM.
Automated Remediation: Instead of just chatting, the AI generates meaningful code fixes, such as replacing legacy protocols with REST endpoints or suggesting the use of Kubernetes Secrets and ConfigMaps.

Beyond Chat: Agents and Memory

What makes Konveyor AI particularly powerful is its move toward Agentic AI and Distributed Memory:

1. Agentic Validation

When AI fixes one part of the code, it often breaks another. Konveyor’s agents handle:

Compilation: Ensuring the new code actually builds.
Validation Testing: Running tests to verify functionality.
Sanitization: Cleaning up the output before it reaches the developer.

2. Organizational Memory

If a developer modifies an AI-generated fix (e.g., changing how exceptions are handled), Konveyor can "remember" that preference. This memory is shared across the organization, so future migrations automatically follow the team's specific coding standards.

Get Involved

Konveyor is an open-source community project. You can find them at their CNCF kiosk or join the community to help build the future of automated application modernization.

Nano Agent, Mega Senses: Adding LSP to the 260-Line Coding Agent

Shaaf Syed — Fri, 10 Apr 2026 05:19:09 +0000

Learn, learn, and learn more—that’s the name of the game. Coding agents are innovating fast; things are getting bigger and, quite often, bloated. To understand what an agent is actually doing, I’ve found it’s best to go back to the basics. It takes a bit more time, but the expertise you gain along the way sets you up for the long haul." So here I read Max's post and thought, how about add some more things to this. Fetching ideas... done.. Lets add LSP support.

The original nanocode idea is easy to lose in the hype: a coding agent is mostly a loop. You send prompt plus tool definitions to the model; the model answers with text or tool calls; you execute tools, feed results back, and repeat. The heavy lifting is the model; your code is hands (write, edit, shell) and eyes (read, glob, grep).

That pattern is how “real” agents are structured too — usually with more polish, safety rails, and often richer senses than plain text search.

This fork keeps that loop and the same six core tools. It adds an optional extra sense for Java workspaces: a language server, so the model can ask project-aware questions instead of inferring everything from raw files.

Does LSP fits the same architecture?

grep and read are universal and powerful. They are also syntax-blind. A symbol might be a field, a local, an import alias, or a string that happens to match. For Java — especially with Maven or Gradle classpaths — the compiler’s view of the project is not the same as “all lines containing this word.”

The Language Server Protocol is the boring industry answer: one process holds the classpath, incremental errors, types, and navigation graph; the client sends small questions (go to definition, hover, publishDiagnostics) and gets structured answers.

nanocode is a thin client in that sense: it forwards requests and prints results. Wiring Eclipse JDT Language Server (the same engine behind most Java editor extensions) is not a different kind of product — it is narrower, deeper vision for one language, and stays optional so a “single-file story” remains when you do not need Java semantics.

What this fork adds (in practice)

Detection — If the workspace contains .java files, nanocode can offer to turn Java support on.
Local install — On consent (or via an environment flag), it downloads JDT LS once into your user cache (~/.cache/nanocode or $XDG_CACHE_HOME/nanocode), not into the repo.
Process + protocol — A small LSP4J client drives the server; documents are synced before semantic queries so answers match what is on disk.
Three extra tools the model sees only when LSP is enabled:
- java_definition — Where is this name bound? (1-based line/column, like many editors.)
- java_hover — Tooltip-grade material: Javadoc, type hints, etc.
- java_diagnostics — Compiler and analysis diagnostics for one file, or a roll-up across files the server has published.

The main script grew; supporting code lives alongside it so newcomers can still read the core agent in one place.

  /**
   * Dispatch tool calls to their respective implementations.
   *
   * Routes tool execution based on the tool name. Basic tools (read, write, edit, glob, grep, bash)
   * are always available. Java LSP tools (java_definition, java_hover, java_diagnostics) require
   * the javaLsp flag to be enabled.
   *
   * @param name The name of the tool to execute
   * @param args JSON arguments for the tool
   * @param javaLsp Whether Java LSP tools are enabled
   * @return Tool execution result, or error message prefixed with ERROR_PREFIX
   */
  static String runTool(String name, JsonNode args, boolean javaLsp) {
      try {
          return switch (name) {
              // Basic file and search tools
              case "read" -> toolRead(args);
              case "write" -> toolWrite(args);
              case "edit" -> toolEdit(args);
              case "glob" -> toolGlob(args);
              case "grep" -> toolGrep(args);
              case "bash" -> toolBash(args);

              // Java LSP tools - require javaLsp flag
              case "java_definition" -> {
                  if (!javaLsp)
                      yield ERROR_PREFIX + "Java LSP not enabled";
                  yield toolJavaDefinition(args);
              }
              case "java_hover" -> {
                  if (!javaLsp)
                      yield ERROR_PREFIX + "Java LSP not enabled";
                  yield toolJavaHover(args);
              }
              case "java_diagnostics" -> {
                  if (!javaLsp)
                      yield ERROR_PREFIX + "Java LSP not enabled";
                  yield toolJavaDiagnostics(args);
              }

              default -> ERROR_PREFIX + "unknown tool " + name;
          };
      } catch (Exception e) {
          // Catch all exceptions and return as error message
          return ERROR_PREFIX + e.getMessage();
      }
  }

  /**
   * Java LSP tool: Go to the definition of a symbol at the specified location.
   *
   * @param args JSON with path (required), line (default 1), column (default 1)
   * @return Location information for the symbol's definition
   */
  static String toolJavaDefinition(JsonNode args) throws Exception {
      return JavaLspSupport.definition(args.get("path").asText(), args.path("line").asInt(1),
              args.path("column").asInt(1));
  }

  /**
   * Java LSP tool: Get type information, signature, and documentation for a symbol at cursor.
   *
   * @param args JSON with path (required), line (default 1), column (default 1)
   * @return Type info, Javadoc, and signature details for the symbol
   */
  static String toolJavaHover(JsonNode args) throws Exception {
      return JavaLspSupport.hover(args.get("path").asText(), args.path("line").asInt(1),
              args.path("column").asInt(1));
  }

  /**
   * Java LSP tool: Get compiler errors and warnings for a file or all cached files.
   *
   * @param args JSON with optional path (empty string = all cached diagnostics)
   * @return List of compiler/LSP diagnostics
   */
  static String toolJavaDiagnostics(JsonNode args) throws Exception {
      return JavaLspSupport.diagnostics(args.path("path").asText(""));
  }

Examples (prompts that now “make sense”)

These are the sorts of tasks where text tools alone are brittle, but JDT + the loop line up nicely.

Navigate instead of guessing

“In src/main/java/.../OrderService.java, around line 48, what type is discount? Use java_hover at that position, then java_definition if it is a field.”

The model no longer has to re-derive the type from imports and local inference across half a dozen files unless it wants to double-check.

Errors with a real classpath

“Run java_diagnostics on PaymentMapper.java and fix whatever JDT reports; then run mvn -q test in bash.”

Diagnostics are tied to how the project is built, not to “did my regex find the word error in the log.”

Onboarding a module

“I’m new to this package. Summarize the main entry points: use glob for *Application.java, read those files, and for the class that implements Runnable or hosts main, show java_hover on the superclass or key API types.”

Read + LSP combine the way humans use an IDE: skim files, drill into symbols.

Guardrails before a large edit

“Before we rename this method, list java_diagnostics for the whole workspace (no path) and tell me if anything is already red.”

You still do not get a one-click rename refactor in this fork — but you get honest compiler state, which is often enough to avoid stepping on a broken build.

────────────────────────────────────────────────────────────────────────────────
❯ What does `GET_USERS` mean in `KeycloakOperation`?
────────────────────────────────────────────────────────────────────────────────

⏺ Java_hover(src/main/java/dev/shaaf/keycloak/mcp/server/KeycloakOperation.java)
  ⎿  dev ... +1 lines

⏺ Glob(**/KeycloakOperation.java)
  ⎿  ./src/main/java/dev/shaaf/keycloak/mcp/server/KeycloakOperat...

⏺ Read(src/main/java/dev/shaaf/keycloak/mcp/server/KeycloakOperation.java)
  ⎿     1| package dev.shaaf.keycloak.mcp.server; ... +67 lines

⏺ `GET_USERS` in the `KeycloakOperation` enum is a constant that represents an operation related to retrieving a list of users from the Keycloak server. This operation is part of a group of user operations defined in the enum, which allows users of the `KeycloakTool` to easily reference and execute actions related to user management, such as creating, updating, deleting users, and retrieving user details.

To ground this in something non-trivial, the same Java LSP stack was exercised against keycloak-mcp-server: a Quarkus-based MCP server on Java 21, Maven BOM, and many command classes under dev.shaaf.keycloak.mcp.server. Typical results: clean diagnostics on command base classes, classpath-backed hover on ObjectMapper (Jackson JAR version matching the build), and definition jumping to the real KeycloakCommand source — the sort of answers grep alone cannot guarantee.

Trying JDT without an LLM API key: the fork ships LspProbe.java (JBang), a tiny harness that calls the same JavaLspSupport as nanocode’s java_* tools. From the nanocode repo:

jbang run LspProbe.java /path/to/your-maven-project

(optional: LSP_PROBE_SYNC_SEC to tune wait for Maven sync.) First run may download JDT (~50 MB) into ~/.cache/nanocode/; after that you can confirm hover, definition, and diagnostics on disk before wiring up ANTHROPIC_API_KEY, OPENROUTER_API_KEY, or OPENAI_API_KEY.

Trade-offs worth saying out loud

Weight — JDT LS is not a toy; it is a real JVM product. The agent stays teachable; the server is the same class of dependency serious Java tooling already uses.
Tokens — A richer tool list and longer system text cost a little each request; targeted LSP results can replace huge file reads. Net savings are not guaranteed.
Trust — bash remains full power. LSP does not sandbox anything; it mainly reduces wrong guesses.
Nano -- Nano but at about 4x more code from the original port.

Read it, run it, break it, extend it. It’s a great way to understand how tools like Claude Code, Cursor, and Co Pilot work under the hood. -- Max

Java + LLMs: A hands-on guide to building LLM Apps in Java with Jakarta

Shaaf Syed — Sat, 08 Feb 2025 08:12:51 +0000

Java is an amazing language to work with. Millions of developers use it for daily work routines, and many mission-critical applications run on Java today. Whether we talk about banks, stock exchanges, or space, Java is prevalent and a language of choice.

With the advent of Large Language Models(LLM), new opportunities are at play. While Python has been the dominating language runtime for apparent reasons, there is a misconception that creating applications, agents, or other components for LLMs should also be done in Python. Most of the integration in LLMs is achieved by using REST API. Java is not short on anything in that space. System integration has been pretty awesome in Java, with many tools in that space. So why not Java?

LangChain4J! The amazing developers and contributors have provided many goodies for us to infuse LLMs into our apps. Use LangChain4J if you haven't done so yet.

I had the opportunity to speak with A N M Bazlur about this topic at the JChampionsConf last week.

The source code and step-by-step guide is available here on github.
And the speakerdeck.

Embracing the Future of Application Modernization with KAI

Shaaf Syed — Mon, 29 Jul 2024 16:16:20 +0000

Konveyor’s main strength lies in its comprehensive approach to migration and modernization. At the core of Konveyor’s functionality is its powerful analysis engine. This engine performs static source code analysis, identifying anti-patterns and issues that might hinder the application’s operation on a target platform. Utilizing community standards like the Language Server Protocol, Konveyor's analysis engine uses rules designed to aid in various migration scenarios. Users can also create custom rules to address specific migration needs, enhancing Konveyor's flexibility and adaptability.

Enter Konveyor AI - "KAI"

Konveyor AI, the latest advancement under the Konveyor umbrella, leverages generative AI to further streamline application modernization. The primary goal of Konveyor AI (or Kai) is to automate source code changes, thereby improving the economics of migration and modernization efforts.

Our approach is to use static code analysis to find the areas in source code that need to be transformed. 'kai' will iterate through analysis information and work with LLMs to generate code changes to resolve incidents identified from analysis. This approach does not require fine-tuning of LLMs, we augment a LLMs knowledge via the prompt, similar to approaches with RAG by leveraging external data from inside of Konveyor and from Analysis Rules to aid the LLM in constructing better results. For example, analyzer-lsp Rules such as these (Java EE to Quarkus rulesets) are leveraged to aid guiding a LLM to update a legacy Java EE application to Quarkus

There is an awesome blog post by John Matthews one of the Lead engineers in the project explaining "Kai" in depth.

BYO Large Language Model

One of the standout features of Kai is its model-agnostic approach. Unlike other solutions, Kai doesn’t bundle any specific large language model (LLM). Instead, it extends Konveyor to interact with various LLMs, providing the flexibility to use the best-suited model for each specific migration context. This approach ensures that organizations can optimize their migration strategies without being locked into a single technology.

Practical usecase: From Java EE to Quarkus

The short demonstration shows how Konveyor AI facilitates migrations from legacy frameworks like Java EE to modern solutions like Quarkus. The process begins with a static code analysis using the Konveyor CLI, which identifies migration issues within the codebase. Once the analysis is complete, Konveyor AI steps in to generate patches for the identified issues, leveraging LLMs to suggest precise code changes.

For instance, outdated Java EE annotations are seamlessly replaced with their modern Jakarta EE counterparts, and JMS-based message-driven beans were converted to JakartaEE annotations, and legacy technology like EJBs turned into REST end points. These changes can be validated by a developer within an integrated development environment (IDE), showcasing how Konveyor AI integrates into existing developer workflows. Konveyor AI does this by using KAI extension.

For a detailed demo and presentation watch this episode of OpenShift commons where Ramón and I go through the details.

Why should I use Konveyor AI's or how? the power of "Kai" lies in its ability to automate repetitive migration tasks, leveraging accumulated knowledge from previous migrations. By focusing on code transformation rather than architectural changes, Kai provides a robust tool for modernizing applications efficiently. It empowers developers to make informed decisions, enabling smoother transitions to modern frameworks and cloud-native environments.

To give the latest build a try head out the to instructions here.

Get involved in the Konveyor community through their mailing lists, Slack channels, and regular meetings.

Java monitoring: Exploring Cryostat 2.4 features on OpenShift

Shaaf Syed — Mon, 18 Dec 2023 21:38:37 +0000

Orignally posted at Red Hat Developers

Red Hat's latest build of Cryostat 2.4, designed specifically for the Red Hat OpenShift Container Platform, brings a wealth of features and enhancements that cater to various monitoring needs for Java applications.

At its core, Cryostat 2.4 excels in comprehensive Java Flight Recorder (JFR) data management. Users can effortlessly start, stop, retrieve, archive, import, and export JFR data, all through an intuitive web console or an accessible HTTP API. This enhances the ease with which developers can handle JVM performance data. Moreover, Cryostat 2.4 provides flexibility in terms of data storage and analysis. Users can store and analyze JFR data directly on their Red Hat OpenShift or export it to external monitoring applications for a deeper dive into the data.

ARM (aarch64)

A significant enhancement in Cryostat 2.4 is its support for Red Hat OpenShift Container Platform 4.11 and later versions, particularly for the ARM64 (aarch64) architecture. This broadens its applicability across various platforms, making it a versatile tool in diverse environments, e.g., edge deployments.

Smart triggering and HTTP API

Another notable feature is the introduction of dynamic JFR recording with MBean custom triggers. The Cryostat agent is equipped with smart triggers that continuously monitor MBean counter values such as runtime, memory, thread, and operating system metrics. Users are able to set custom trigger conditions, thereby adding a layer of precision to JVM monitoring.

Further enhancing its functionality, Cryostat 2.4 introduces an improved HTTP API provided by the Cryostat agent. This serves as an alternative to an application’s JMX port, allowing users to fully utilize Cryostat's features without the need for JMX port exposure in target applications. This is particularly beneficial for enhancing security and simplifying configurations.

JAR distribution

Cryostat 2.4 also offers flexibility in agent deployment. It provides two types of agent JAR file distributions—an all-in-one "shaded" JAR file that includes all dependencies, and a standard JAR file containing only the agent code. This choice caters to different user requirements and helps manage potential dependency conflicts more effectively.

Topology dashboard view

Additionally, Cryostat 2.4 brings new features and fixes to enhance user experience. The Topology and Dashboard views in the Cryostat web console now display additional information about target JVMs, such as operating system name, memory statistics, class path, library paths, input arguments, and system properties. The introduction of a parameter to restart flight recordings offers more control over recording management, addressing a common user pain point.

Significant issues from previous versions have also been addressed. Automated rule-triggering issues in discovered JVM targets have been resolved, with Cryostat performing regular rechecks and reattempts at rule triggering. This ensures a more reliable connection with JVMs, improving consistency and predictability. The agent registration protocol has also seen improvements, resolving issues related to agent registration with the Cryostat server and ensuring a smoother, more reliable process.

Cryostat 2.4 is a testament to Red Hat's commitment to providing robust and innovative solutions for modern containerized applications. With its enhanced features, improved user experience, and greater flexibility, Cryostat 2.4 is poised to be a pivotal tool in JVM monitoring, offering a sophisticated and user-friendly approach to performance monitoring in containerized environments.

How to use Cryostat for your Java workloads

You can install the Red Hat build of Cryostat using our OpenShift operator, available in Red Hat OpenShift's Operator Hub.
For non-production usage, you can also try our Helm chart, included as part of OpenShift’s Helm chart repository.
You can also try Red Hat build of Cryostat here.

Get support for Java

Support for Cryostat, OpenJDK, and Eclipse Temurin is available to Red Hat customers through a subscription to Red Hat Runtimes, Red Hat Enterprise Linux, and Red Hat OpenShift. Contact your local Red Hat representative or Red Hat sales for more details. You can expect support for Java and other runtimes as described under the Red Hat Product Update and Support Lifecycle.

DEV Community: Shaaf Syed

Enforcing Architecture with rgctl Policy Checks

Enforcing Architecture with rgctl Policy Checks

The example project: CoolStore WebLogic

The problem: architecture rules that live in people's heads

Policy file format

Violation types

ScaleFailure

CascadeHazard

DomainIsolation

SanitizationBypass

Running the first policy check on CoolStore

Check the exit code

Per-function blast radius with policy

A function that passes

A function that violates

Tight policy on Java service code

Java application violations at moderate thresholds

Permissive vs strict policies

Permissive: baseline for a monolith

Strict: zero tolerance

Domain isolation

Git-aware scoping (local development)

GitHub Actions integration

Adding violation details to PR comments

Caching the graph

Tightening policies over time

Summary

I Created a Code Graph of Magento 2 for AI Agents

I Created a Code Graph of Magento 2 for AI Agents

Why Magento, why agents

Phase 1: Shallow discover — the structural map

Under the hood: tree-sitter, not regex

What shallow extraction does not claim

Phase 2: Deep discover — CFG, taint, field mutations

Honest limits: DI and sparse calls

Agent workflow: copy-paste recipes

1. Inventory before editing

2. Blast radius before a refactor

3. Community = module neighborhood

4. Deep slice on a suspicious method

5. Semantic search (optional second index)

Agent rules that actually help

When the graph is enough vs when to use the IDE

Try it

Blast Radius for Agent-Assisted Development on Kubernetes

Blast Radius for Agent-Assisted Development on Kubernetes

How blast radius is calculated in rgctl

Why agents get sub-second answers on Kubernetes

The gap agents cannot close on their own

The loop that actually works

Why Kubernetes is a good stress test

Example: changing RESTClientFor

Context cost

Example: refactoring newPodWorkers

Use --depth to control noise

Example: the score-zero trap

What you get in the JSON

Disambiguation on a real tree

Policy gates in agent-driven PRs

When your IDE is still the better tool

Static analysis limits (both of you should know these)

Getting started

Further reading

Decomposing a Monolith into Microservices with Call Graph Analysis

Decomposing a Monolith into Microservices with Call Graph Analysis

The Monolith

Step 1: Build the Call Graph

Step 2: Detect Community Structure

Community 8064 (30 members): Cart Operations

Pricing and Shipping (community 4266)

Cart Serialization and Item Promotions

Order Fulfillment and Inventory (community 11250 + order MDB cluster)

Product Catalog (community 11973)

Order Queries (community 14643)

Step 3: Map the Proposed Microservice Boundaries

Proposed services

Step 4: Quantify Coupling with Blast Radius

Cross-boundary calls

Blast radius at the boundaries

Example: changing `RESTClientFor`

Example: refactoring `newPodWorkers`

Use `--depth` to control noise

Step 1: Entities and DTOs (`com.redhat.coolstore.model`)

Step 2: Persistence Producer (`com.redhat.coolstore.persistence`)

Step 3: Utilities (`com.redhat.coolstore.utils`)