graphify-sfcc

graphify-sfcc 🚀

💡 Quick Setup Guide: For step-by-step setup instructions across Claude Code, Claude Desktop, Cursor, Gemini, Windsurf, and VS Code, see the dedicated INSTALLATION.md guide.

An ultra-fast, Demandware-aware code-graph engine and Model Context Protocol (MCP) server for Salesforce Commerce Cloud (SFCC / SFRA) codebases.

graphify-sfcc lets AI coding assistants answer "how is this wired?" questions in one deterministic tool call (~200 tokens) instead of a slow, context-bloating chain of grep and file reads.

⚡ Why graphify-sfcc?

When an AI assistant investigates SFCC architecture — which copy of Checkout.js wins on the cartridge path? where is this helper used? what does HookMgr.callHook dispatch to? — raw text search fails:

• Context Bloat: Traditional grep requires multiple grep → read → grep round-trips. Each read dumps whole source files into context, consuming thousands of tokens.
• Incorrect Precedence: Raw text search cannot resolve cartridge path precedence (app_custom vs app_storefront_base). It cannot tell which of five Checkout.js files actually executes or resolve ~/cartridge/... requires.

📊 Benchmark: graphify-sfcc vs. Raw Grep

Head-to-head benchmark on 10 real-world SFCC architecture queries (evaluated against ground truth):

Metric	Traditional Grep	graphify-sfcc	Improvement
Tool Calls / Query (Avg)	~6.6 calls	~2.1 calls	⚡ 3× Faster
Tokens / Query	5,000+ tokens	~200 tokens	💰 95% Token Savings
Cartridge Precedence	Guesses / Fails	Exact (Leftmost-Wins)	🎯 100% Accuracy
Symbol Call-Site Recall	Incomplete	1.00 (Exact File:Line)	🔍 Complete Precision

🎯 What it Models

graphify-sfcc indexes your entire repository into a high-performance Graphology network graph, capturing:

• 🗂️ Cartridge Path Resolution: require('*/cartridge/...') leftmost-wins precedence, app_storefront_base/..., base/..., relative ./, and dw/* platform externals.
• 🔄 Overlay & SuperModule Chains: module.superModule override chains and shadowed modules across cartridges.
• ⚡ SFRA server.* Route Wiring: prepend, append, replace, get, post, use, and extend middleware bindings.
• 🪝 hooks.json Dispatch: Dynamic HookMgr.callHook() and hooksHelper() execution linked to script handlers.
• 📄 ISML & Controller Graph: Controller res.render('template') calls, ISML <isinclude template="...">, and URLUtils.url(...) routes.
• 🛠️ Forms & Metadata: server.forms.getForm('name') mapped to forms/**/*.xml definitions and field IDs.
• ⚠️ Site Preference Silent-Null Auditor: getCustomPreferenceValue('id') reads joined against customPreferences.js and system metadata XML to catch unconfigured preference bugs.
• 🌐 Platform Globals: Ambient session, request, customer, response, pdict, slotcontent, and dw.order.OrderMgr.

🏗️ Architecture Pipeline

graph TD
    A[SFCC / SFRA Repository] --> B[Cartridge Path Resolver]
    A --> C[AST & XML Parsers]
    B --> D[Graphology Network Engine]
    C --> D
    D --> E[MCP Server stdio]
    D --> F[Interactive HTML Visualizer]
    E --> G[Claude / Cursor / Gemini / Windsurf / VS Code]

🚀 Quick Start

1. Installation

Install graphify-sfcc globally via npm:

npm install -g graphify-sfcc

Verify installation:

graphify-sfcc --version
# Output: 0.1.0

2. CLI Commands

Command	Description
graphify-sfcc (or serve)	Start the stdio MCP server for AI assistants.
graphify-sfcc build	Build/refresh graph index and output node/edge stats.
graphify-sfcc visualize	Generate an interactive HTML graph visualization and open it in browser.
graphify-sfcc install	Install the Claude skill (.claude/skills/sfcc-graph/SKILL.md) into your workspace.

3. AI Assistant Integration

Configure graphify-sfcc in your AI coding assistant. Standard stdio config block:

{
  "mcpServers": {
    "graphify-sfcc": {
      "command": "graphify-sfcc",
      "args": ["serve"],
      "env": {
        "SFCC_GRAPH_ROOT": "/absolute/path/to/your/sfcc-storefront-repo"
      }
    }
  }
}

Client Configuration Locations:

• Claude Code CLI: Run claude mcp add graphify-sfcc -- graphify-sfcc serve
• Claude Desktop: %APPDATA%\Claude\claude_desktop_config.json (Win) or ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
• Cursor: .cursor/mcp.json
• Windsurf: ~/.codeium/windsurf/mcp_config.json
• Gemini CLI / Antigravity: ~/.gemini/config/mcp_config.json or workspace .mcp.json

(See INSTALLATION.md for detailed client setup guides).

🛠️ MCP Tool Reference

graphify-sfcc exposes 18 deterministic MCP tools to your AI agent:

Tool	Purpose
build_index	Build or refresh graph index for target repository.
stats	Return total counts for cartridges, modules, routes, templates, and symbols.
resolve_module	Resolve exact target file path given a require specifier and caller context.
who_overrides	List override chain (module.superModule) and lower-precedence shadows.
dependencies_of	List all outbound require modules and imported scripts for a file.
callers_of	Find all inbound caller modules that require a given file.
defines_symbols	List top-level functions defined in a module with line numbers.
symbol_usages	Find exact file:line call sites of a function across the codebase.
route_info	Inspect controller route handlers (prepend, append, replace, get, post).
hook_handler	Find script handlers bound to a hooks.json hook extension point.
template_graph	Inspect ISML template includes (<isinclude>) and outbound route links.
pref_usage	Inspect site preference reads (getCustomPreferenceValue) vs metadata declarations.
uses_global	Find dw ambient global accesses (session, request, customer, pdict) in a file.
global_usages	Find all files accessing a specific dw ambient global.
unresolved	Audit dead require links, missing ISML templates, and orphan site preferences.
search_nodes	Search graph nodes by substring, cartridge name, or node kind.
explain	Return full attributes, incoming edges, and outgoing edges for any node.
shortest_path	Compute shortest dependency path between two files or symbols in the graph.

🎨 Interactive Graph Visualizer

Generate an interactive, standalone HTML network visualization of your codebase architecture:

graphify-sfcc visualize

This creates .sfcc-graph-cache/visualize.html and automatically opens it in your default web browser.

💻 Programmatic SDK Usage

You can also use graphify-sfcc as a Node.js library in custom tooling:

import { Index, CartridgeResolver } from 'graphify-sfcc';

// Build or load graph index for repository
const index = Index.build({ root: '/path/to/sfcc-storefront' });

// Query exact function call sites
const usages = index.symbolUsages('Handle');
console.log(usages);

// Resolve cartridge path precedence
const resolver = new CartridgeResolver('/path/to/sfcc-storefront');
const resolved = resolver.resolveRequire('*/cartridge/scripts/checkout/checkoutHelpers', 'app_custom');
console.log(resolved);

🧪 Testing & Quality Assurance

graphify-sfcc maintains 85.2% unit test coverage across 60 test suites:

npm run build      # Compile TypeScript (tsc)
npm test           # Run 60 unit tests with LCOV path mapping
npm run smoke      # Execute graph integration smoke test

⚙️ Environment Variables

• SFCC_GRAPH_ROOT: Target SFCC repository root path.
• SFCC_GRAPH_CARTRIDGE_PATH: Override cartridge resolution path (e.g. app_custom:app_storefront_base).
• SFCC_GRAPH_CACHE: Override disk cache folder (default <repo-root>/.sfcc-graph-cache/).

📄 License

Distributed under the MIT License. Created by nabhat.