MageContext

              & &&&&  &&&&&        && &       &&&&&  &&&& &                       
         &&& &&&&& &&&&  &&&  && &&&&&&  &&&  &&&& &&&&& &&                     
         & &&     &&&& &&&&&&&& &&&&& &&&&&&&& &&&&     && &                    
         &   &  & &&& &&&&&&&&&& &&& &&&&&&&&&& &&& &  &   &                    
          &      &  &&&&&&&&&&& &&&&& &&&&&&&&&&&  &      &                     
      &    &&  & && &&&&&&&&&& &&&&&&& &&&&&&&&&  && &  &&    &&                
        &&         &    &&&&&  &&&&&&&  &&&&&    &         &&&                  
          &&        &    &  &&&&&&&&&&&&&  &    &        &&                     
     &&&&&    &&     & &   &&&&&&&&&&&&&&&   & &      &     &&&&                
     &&&&&&&   &&&   &&  &&&&&&&&&&&&&&&&&&&  &&   &&&   &&&&&&&                
            &  & &     & &&&&&&&&&&&&&&&&&&& &     & &                          
      &&&&&     &&     &    &&&&&&&&&&&&&    &     &&   & &&&&&                 
         &&&  &  &&&   &&     &&&&&&&&&     &&   &&&  &  &&&                    
       & &  && &&&      &&&  & &&&&&&& &  &&&      &&& &&  &&&                  
       &   &  &   &&      &&&&& &&&&& &&&&&      &&   &  &   &                  
        &  &&  &&          & &&&&&&&&&&& &          &&  &&  &&                  
            &&            & & &&&&&&&&& & &            &&                       
                         && & &&&&&&&&& & &&                                    
                        &&&   &       &   & &                                   
                        & &  &&&&   &&&& &&&                                    
                        &  &&   &        &&&                                    
                          &&&&& &&&&&  & &&&                                    
                          &&&&  &     & &&                                      
                           &   &&&& & & &&                                      
                            && &&&&&&&& &                                       
                              &  &&&&&                                          
                                  &&

A CLI tool that indexes a Magento 2 repository — structure, configuration, and runtime behavior — and outputs an AI-ready context bundle. Structured, queryable, deterministic, and immediately usable by AI coding tools like Windsurf, Cursor, or Claude.

Problem

AI agents fail on enterprise Magento codebases not because the models are weak, but because the context is opaque. Deep XML config, implicit behavior via DI/plugins/observers, layers of overrides, and runtime settings scattered across env.php, config.php, queue topology, and payment gateway configs make it impossible for an AI to reason about the system without help.

Solution

MageContext runs 29 extractors across your repo and produces a self-describing context bundle:

Module graph — modules, themes, composer packages, and their dependency edges
Typed dependency graph — structural, code, and runtime coupling with split metrics
DI resolution map — per-area preference chains with confidence scores
Plugin/interceptor chains — per-method interception with sort order and evidence
Event/observer graph — cross-module event flow with risk scoring
Execution paths — reconstructed controller/cron/CLI flows through DI, plugins, observers
Route map, cron map, CLI commands, API surface — all entry points indexed
Layout handles, UI components, DB schema — frontend and data layer structure
Layer classification — files classified into architectural layers with violation detection
Symbol index — class→file→module O(1) lookup for every PHP symbol
File index — file→module→layer O(1) lookup for every file in scope
Reverse indexes — "given X, find all facts about X" for classes, modules, events, routes
Allocation view — which modules are active in which Magento areas
Scenario bundles — self-contained slices per entry point with risk assessment
Quality metrics — modifiability risk, architectural debt, performance indicators, deviation detection
Hotspot ranking — modules ranked by combined git churn and dependency centrality
Service contracts — Api/*Interface method signatures with DI bindings and webapi exposure
Repository patterns — repository interfaces, CRUD completeness, SearchCriteria usage guide
Entity relationships — entity→table mappings, foreign keys, domain invariants, EAV detection
Call graph — delegation chains from REST/GraphQL/CLI entry points through DI to concrete executors
Plugin seam timing — per-method plugin execution order, side-effect warnings, hook-type recommendations
Safe API matrix — method stability tiers (api_interface → deprecated) with replacement guidance
DTO data interfaces — Api/Data/*Interface getter/setter signatures, field inventory, nullability
Implementation patterns — concrete class constructor dependencies, design patterns, interface deviations
Runtime config — MSI module status, stock capability inference, declared queue topology & DLQ gaps, DB connection hints & engine intentions, payment method defaults & declared capabilities, order state/status customizations & state mutator detection. Every section carries a machine-readable _meta.confidence enum (see Truth Model)
JSON schemas — every output file has a machine-readable schema

Installation

Requirements: PHP 8.2+ (see composer.json).

Install via Composer:

composer global require infinri/mage-context

Or install in a dedicated directory (recommended if you have other global Composer tools that use different PHP/Symfony versions):

mkdir ~/.magecontext
cd ~/.magecontext
composer init
composer require infinri/mage-context

Run the compiler (from anywhere):

~/.magecontext/vendor/bin/magecontext

Or from inside ~/.magecontext: vendor/bin/magecontext.

To update later (from ~/.magecontext):

cd ~/.magecontext && composer update infinri/mage-context

Alternative: clone and run from source

git clone https://github.com/infinri/MageContext.git
cd MageContext
composer install

Quick Start

# Basic compile (auto-detects Magento, outputs to .ai-context/)
bin/magecontext compile --repo /path/to/magento

# Custom output directory
bin/magecontext compile --repo /path/to/magento --out /tmp/my-context

# Custom scopes (default: app/code,app/design)
bin/magecontext compile --repo /path/to/magento --scope app/code,vendor

# Faster local dev (skip determinism check, shorter churn window)
bin/magecontext compile --repo /path/to/magento --skip-determinism-check --churn-window 30

# Disable churn entirely (fastest)
bin/magecontext compile --repo /path/to/magento --churn-window 0

CLI Commands

`compile`

The primary command. Runs all extractors and produces the full context bundle.

Option	Default	Description
`--repo`, `-r`	`.`	Path to the repository root
`--target`, `-t`	`auto`	Target platform: `magento`, `generic`, or `auto`
`--scope`, `-s`	target default	Comma-separated directories to scan
`--out`, `-o`	`.ai-context`	Output directory for the context bundle
`--format`, `-f`	`json`	Output format: `json` or `jsonl`
`--churn-window`	`365`	Git churn analysis window in days (0 = disable)
`--skip-determinism-check`	off	Skip determinism verification (dev machines only)
`--ci`	off	CI mode: write `ci_summary.json`, exit non-zero on threshold violations
`--max-violations`	unlimited	CI threshold: max layer violations
`--max-cycles`	unlimited	CI threshold: max circular dependencies
`--max-deviations`	unlimited	CI threshold: max deviations
`--max-risk`	unlimited	CI threshold: max average modifiability risk (0.0–1.0)

`diff`

Compare two compiled context bundles and detect architectural regressions.

bin/magecontext diff /path/to/old/.ai-context /path/to/new/.ai-context

Option	Default	Description
`--format`, `-f`	`text`	Output format: `text`, `json`, or `markdown`
`--out`, `-o`	stdout	Output file path

Exits non-zero if regressions are detected (new cycles, increased violations, rising risk scores, etc.).

`pack`

Extract minimum relevant context from a compiled bundle for a specific issue or stack trace.

bin/magecontext pack --issue "Checkout fails when coupon applied" --context-dir .ai-context
bin/magecontext pack --issue "500 error" --trace /path/to/stacktrace.log
bin/magecontext pack --keywords "SalesRule,Quote,Plugin" --context-dir .ai-context

Option	Default	Description
`--issue`, `-i`	—	Issue description or bug summary
`--trace`, `-t`	—	Path to a stack trace or log file
`--keywords`, `-k`	—	Comma-separated additional keywords to search for
`--context-dir`, `-c`	`.ai-context`	Path to the compiled context directory
`--out`, `-o`	stdout	Output path (JSON file or directory)
`--format`, `-f`	`both`	Output format: `json`, `markdown`, or `both`

`guide`

Generate development guidance for a task within specific Magento areas.

bin/magecontext guide --task "Add free shipping rule" --area salesrule,checkout

Option	Default	Description
`--task`, `-t`	—	Description of the development task
`--area`, `-a`	—	Comma-separated Magento areas or module keywords
`--context-dir`, `-c`	`.ai-context`	Path to the compiled context directory
`--out`, `-o`	stdout	Output file path
`--format`, `-f`	`markdown`	Output format: `json`, `markdown`, or `both`

Output Structure

.ai-context/
├── manifest.json                        # Build metadata, extractor results, validation
├── ai_digest.md                         # AI entry point — read this first
├── repo_map.json                        # Directory tree structure
│
├── schemas/                             # JSON Schema for every output file
│   ├── manifest.schema.json
│   ├── symbol_index.schema.json
│   ├── reverse_index.schema.json
│   └── ... (17 total)
│
├── indexes/                             # O(1) lookup indexes
│   ├── symbol_index.json                # class→file→module mapping
│   └── file_index.json                  # file→module→layer mapping
│
├── reverse_index/
│   └── reverse_index.json               # by_class, by_module, by_event, by_route
│
├── module_view/                         # Structural analysis
│   ├── modules.json                     # Module graph with dependency edges
│   ├── dependencies.json                # Typed dependency graph + coupling metrics
│   ├── layer_classification.json        # File layer classification + violations
│   ├── layout_handles.json              # Layout XML structure
│   ├── ui_components.json               # UI component definitions
│   ├── db_schema_patches.json           # Declarative schema + patches
│   ├── api_surface.json                 # REST + GraphQL endpoints
│   ├── entity_relationships.json        # Entity→table maps, foreign keys, invariants
│   └── dto_data_interfaces.json         # Api/Data/*Interface getter/setter signatures
│
├── runtime_view/                        # Behavioral analysis
│   ├── execution_paths.json             # Reconstructed entry→exit flows
│   ├── plugin_chains.json               # Plugin interception chains
│   ├── event_graph.json                 # Event/observer graph
│   ├── di_resolution_map.json           # DI preference resolution
│   ├── route_map.json                   # Route declarations
│   ├── cron_map.json                    # Cron job declarations
│   ├── cli_commands.json                # CLI command declarations
│   ├── call_graph.json                  # Delegation chains through DI
│   ├── service_contracts.json           # Api/*Interface signatures + DI + webapi
│   ├── repository_patterns.json         # Repository CRUD + SearchCriteria
│   ├── plugin_seam_timing.json          # Plugin execution order + side effects
│   ├── safe_api_matrix.json             # Method stability tiers
│   ├── implementation_patterns.json     # Concrete class deps + patterns
│   └── runtime_config.json              # MSI, stock, queues, DB hints, payments, state machine + _meta tiering
│
├── allocation_view/
│   └── areas.json                       # Per-area module allocation
│
├── quality_metrics/
│   ├── modifiability.json               # Per-module modifiability risk
│   ├── hotspot_ranking.json             # Churn + centrality ranking
│   ├── architectural_debt.json          # Cycles, god modules, multi-overrides
│   ├── performance.json                 # Performance risk indicators
│   ├── custom_deviations.json           # Deviations from best practices
│   ├── custom_deviations.md             # Human-readable deviation report
│   └── git_churn_hotspots.json          # Raw churn data
│
└── scenarios/                           # Per-entry-point scenario bundles
    ├── scenario_coverage.json           # Seed matching report
    ├── frontend.controller.*.json       # One bundle per execution path
    ├── crontab.cron.*.json
    └── cli.console.*.json

Key Concepts

AI Digest (`ai_digest.md`)

The entry point for AI consumers. Read this file first — it summarizes the system, highlights top risks, and includes a Quick Lookup Guide showing how to query the indexes.

Reverse Index

The most powerful artifact for AI agents. Instead of scanning 20+ JSON files to answer "what do I need to know about class X?", query reverse_index.json:

by_class[class_id]  → file, module, plugins, DI resolutions, events observed
by_module[module_id] → files, classes, plugins, events, routes, crons, CLI, debt
by_event[event_id]  → observers, cross-module count, risk score
by_route[route_id]  → area, controller, module, plugins on controller

Scenario Bundles

Each scenario bundle is a self-contained slice for one entry point (controller, cron job, CLI command). It includes the execution chain, affected modules, risk assessment, and QA concerns. Use these when working on a specific feature.

Truth Model (`runtime_config.json`)

RuntimeConfigExtractor operates in static mode (repository-only analysis). It does not inspect live database state or broker runtime unless explicitly extended.

Every section in runtime_config.json includes a _meta block with machine-readable confidence classification:

{
  "_meta": {
    "confidence": "authoritative_static",
    "source_type": "repo_file",
    "sources": ["app/etc/config.php"],
    "runtime_required": false,
    "limitations": "..."
  }
}

Confidence uses a strict enum — not free-text:

Confidence value	Meaning
`authoritative_static`	Directly declared in repo files; deterministic and authoritative
`inferred_static`	Derived from structural configuration (DI preferences, schema presence)
`declared_config`	Explicit configuration values from `env.php` or `config.xml`; environment-specific
`best_effort_detection`	Pattern-based mutation detection (e.g. plugins on `Order::setState`)
`requires_runtime_introspection`	Needs DB/broker access; not available in static mode

Per-section classification:

Section	Confidence	What MageContext extracts	What it does NOT capture
MSI modules	`authoritative_static`	Module enabled/disabled from `config.php`	Whether MSI is fully configured with sources/stocks
Stock infrastructure	`inferred_static`	DI resolver preferences, schema table presence	Live `inventory_stock_sales_channel` rows (requires DB)
Queue topology	`authoritative_static`	Declared topics, exchanges, bindings, DLQ arguments, consumers	Broker-level policies, deployment overrides, consumer runner config
DB config	`declared_config`	Connection hints from `env.php`, declared table engines from `db_schema.xml`	Live table engine drift, session-level isolation overrides
Payment config	`declared_config`	Defaults from `config.xml`: model, payment_action, active flag, declared capabilities	Admin config overrides (`core_config_data`), dynamic providers, vault layers
State machine: custom_statuses	`authoritative_static`	Declared statuses, state mappings	Dynamic state changes from payment integrations or custom workflows
State machine: state_mutators	`best_effort_detection`	Plugins on `Order::setState`, observers on state events	Indirect mutation via services, payment internals, repository saves, async consumers

Design notes:

Confidence applies per output section, not per collector. state_machine_overrides uses subsection-level _meta because it emits mixed truth types (authoritative declarations + best-effort mutation detection).
actual_mapping_known: false in stock infrastructure explicitly encodes that this is capability inference only — not actual website→stock assignment data.
Each state_mutator item carries its own confidence, detection_method, and limitations for full epistemic transparency.

Static-only guarantee: The runtime_required field in _meta is documentation metadata only — it tells consumers which findings would benefit from database access. MageContext never connects to a database or broker in its current mode. If runtime introspection is added in the future, it will be a separate explicit mode (e.g. --runtime-introspection) with its own security disclaimers, never a silent upgrade.

Determinism

All output is deterministic — same input always produces byte-identical output. This is enforced by:

Recursive key sorting on all JSON objects
Explicit sort keys for arrays
A post-compile determinism check (re-load → re-normalize → compare)

Configuration

Place a .magecontext.json in your repo root to customize behavior.

Key settings:

{
    "scopes": ["app/code", "app/design"],
    "include_vendor": false,
    "churn": {
        "enabled": true,
        "window_days": 365,
        "cache": true
    },
    "max_evidence_per_edge": 5,
    "max_reverse_index_size_mb": 10,
    "edge_weights": {
        "plugin_intercept": 1.2,
        "event_observe": 1.1,
        "di_preference": 1.0
    }
}

CLI options override config file values. Config file overrides defaults.

CI Integration

bin/magecontext compile \
  --repo . \
  --ci \
  --max-violations 0 \
  --max-cycles 5 \
  --max-deviations 50 \
  --max-risk 0.7

Exits non-zero if any threshold is exceeded. Writes ci_summary.json with pass/fail details.

Requirements

PHP >= 8.2
Git (for churn analysis)
A Magento 2 repository to analyze (or any PHP project in generic mode)

Architecture

CLI (symfony/console)
  → CompileCommand
    → CompilerConfig (.magecontext.json + CLI overrides)
    → TargetRegistry (auto-detect Magento vs generic)
    → ExtractorRegistry
      → 29 Magento extractors (XML, DI, plugins, events, routes, service contracts, call graph, runtime config, ...)
      → 4 Universal extractors (repo map, git churn, symbol index, file index)
    → OutputWriter (deterministic JSON + Markdown)
    → IndexBuilder (reverse indexes from extractor data)
    → ScenarioBundleGenerator (per-entry-point slices)
    → SchemaGenerator (17 JSON schemas)
    → AiDigestGenerator (ai_digest.md)
    → BundleValidator (determinism, evidence, cross-checks, size guardrails)
  → DiffCommand (compare two bundles, detect regressions)
  → PackCommand (extract issue-specific context via ContextResolver)
  → GuideCommand (generate dev guidance via GuideResolver)

Extractors are modular — each handles a single concern, outputs structured data with evidence arrays, and declares its output view directory. The registry composes them, and post-processors (IndexBuilder, ScenarioBundleGenerator) cross-reference their output.

Testing

# Run all tests
vendor/bin/phpunit

# Hardening tests only (determinism, corruption, edge weights, etc.)
vendor/bin/phpunit tests/Hardening/

# Acceptance tests only (canonical queries, config wiring)
vendor/bin/phpunit tests/Acceptance/

Test suite covering:

5 canonical AI queries (controller→plugins, interface→impl, event→listeners, module→dependents, hotspot→touchpoints)
9 extractor acceptance tests (service contracts, DTOs, repositories, call graph, entities, plugin seams, API matrix, implementation patterns, runtime config)
Determinism invariants (including cross-run determinism for new extractors)
Corruption detection
Edge weight consistency
Integrity degradation formulas
Percentile normalization
Scenario seed resolver
Scenario bug regressions
Churn cache behavior
Config wiring (defaults, file overrides, CLI overrides)

Performance

Tested on an enterprise Magento repo (148 modules, 67,000+ files):

Metric	Value
Compile time	~174s full Magento vendor scan, ~6s warm cache on app/code
Peak memory	974 MB
Extractors	33 (29 Magento + 4 universal)
Schemas	17
Scenario bundles	2,079 (full Magento vendor)

License

MIT — see LICENSE file.

Name		Name	Last commit message	Last commit date
Latest commit History 17 Commits
bin		bin
src		src
tests		tests
.gitignore		.gitignore
.magecontext.example.json		.magecontext.example.json
LICENSE		LICENSE
README.md		README.md
composer.json		composer.json
phpunit.xml		phpunit.xml

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

MageContext

Problem

Solution

Installation

Quick Start

CLI Commands

`compile`

`diff`

`pack`

`guide`

Output Structure

Key Concepts

AI Digest (`ai_digest.md`)

Reverse Index

Scenario Bundles

Truth Model (`runtime_config.json`)

Determinism

Configuration

CI Integration

Requirements

Architecture

Testing

Performance

License

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

MageContext

Problem

Solution

Installation

Quick Start

CLI Commands

compile

diff

pack

guide

Output Structure

Key Concepts

AI Digest (ai_digest.md)

Reverse Index

Scenario Bundles

Truth Model (runtime_config.json)

Determinism

Configuration

CI Integration

Requirements

Architecture

Testing

Performance

License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`compile`

`diff`

`pack`

`guide`

AI Digest (`ai_digest.md`)

Truth Model (`runtime_config.json`)

Packages