v0.8.1: Hardened Error-Decode, Regression Selftest & AI Subtools

LocalGrep v0.8.1: Hardened Diagnostics, Regression Suite & Agent Subtools

This release resolves all findings from the multi-round adversarial review (§1–§14), permanently eliminating core failure modes and delivering four gap-closing subtools:

1. Hardened Error Decoder (lg error-decode)

• Zero Anti-Pattern Guard: Honest rejection of non-error inputs; zero synthetic placeholder cards.
• Log Content Disambiguation: Deterministic differentiation between raw log entries with slashes and missing file paths.
• Multi-Format Stack Traces: Full support for PSR-3 multi-line, single-line JSON exceptions, #0 file:line, and Python tracebacks.
• Innermost App Frame Extraction: Pinpoints deep application frames behind 100+ vendor frames with local source code snippets.

2. Four New Agent Subtools

• lg selftest [--json]: Built-in 12-test adversarial regression suite verifying core commands in under 2 seconds.
• lg factory <Model> [--json]: Offline Laravel factory inspector extracting default definition attributes and custom state modifiers with fuzzy suggestions.
• lg importgraph <file> [--json]: Bidirectional AST import/export dependency and consumer graph resolver.
• lg diff-context [--staged] [--file <f>]: Contextual git diff generator providing enclosing function/class headers for every modified hunk.

3. Core Engine Polish

• Dead-Weight Removal: Eliminated legacy 91MB model.onnx and dropped onnxruntime/transformers dependencies; engine runs pure AST & lexical analysis at sub-millisecond latencies.
• Language-Scoped Audit: Restrained lg audit-diff exit/die checks to PHP/Blade, preventing false alarms on Python sys.exit().
• 74/74 Unit Tests Passing across all modules and subtools.

v0.8.0: High-Leverage AI Agent Acceleration Tools & AST Pruning

LocalGrep v0.8.0: The Complete Autonomous Agent Accelerator

This release delivers the high-leverage agent tools and AST pruning fixes detailed in the architecture roadmap, cutting agent token consumption by up to 92% and providing instant deterministic file navigation:

New Commands & Capabilities:

• lg slice <file> '<symbol>' [--json]: Skeletonized file context collapsing non-target methods for 85%+ token reduction during edits.
• lg lint-fast <file> [--json]: Sub-20ms pre-flight linter for PHP, Vue SFC tag balancing, and Python syntax.
• lg test-map <file> [--run] [--json]: Targeted Pest and PHPUnit test selector and runner with distilled output.
• lg sample <Model|table> [--json]: Zero-query database peek from PostgreSQL socket, SQLite, and MySQL with credential redaction.
• lg impact <symbol|file> [--json]: Downstream blast radius engine mapping frontend/backend callers, routes, and affected tests.
• lg error-decode [log|stdin] [--json]: Intelligent stack-trace distiller stripping framework vendor noise and inlining SQL query bindings.
• lg env-audit [--json]: Configuration and environment validator checking live schema, disabled services, and credentials.
• lg state-map <component.vue> [--json]: Frontend reactive dependency DAG tracing props, computeds, watchers, and emits.
• lg api-shape <route|controller@method> [--json]: Full-stack contract synthesizer unifying Route, FormRequest, Resource, and Inertia components.
• Exact AST Symbol Short-Circuiting in lg prune: Fixes cross-encoder length penalty on concise methods (score = 1000.0).

Test Coverage:

• 40/40 unit tests passing in <0.2s.

v0.7.0: Zero Cold-Start Daemon & Multi-Tier AST Extraction

Highlights in v0.7.0

• Multi-Tier AST Extraction (lg contract <file> [--full]): Eliminates over-pruning by providing full visibility into component and model internals without reading entire 400+ line files.
  • Vue 3: Extracts defineExpose, internal reactive state (ref, reactive, computed), lifecycle hooks (onMounted, onUnmounted, etc.) with called function summaries, and balanced multi-target watchers (watch([a, b], ...)).
  • PHP: Extracts traits used inside classes (use HasFactory, SoftDeletes;), protected properties ($casts, $fillable, $table), and protected methods (booted(), casts()).
  • TS/JS: Extracts internal interfaces and types.
• Zero Cold-Start Architecture via Linux User Service (systemd --user):
  • Automatically manages daemon lifecycle with memory limits and instant recovery (Restart=always).
  • Warm ONNX runtime in memory delivers sub-5ms semantic queries and AST pruning.
• MCP Server & CLI:
  • Added full: bool = False to localgrep_contract MCP tool.
  • Added --full and --hooks flags to lg contract CLI.

v0.6.1 - Frontend Inertia & Blade Page Route Resolution

Added

• Frontend Inertia & Blade Route Resolution in lg route: Inspects controller action methods for Inertia::render('Component', ...) and view('name', ...), linking routes directly to frontend Vue SFC files (resources/js/Pages/*.vue). Supports searching routes directly by Vue component names or page URLs.

v0.6.0 - Phase 3: Patch Verification, Git Diff Audit & Test Isolation

Added

• lg verify-patch <file> [target] [--json]: Pre-validation of edit blocks for code replacement tools (replace_file_content). Checks uniqueness, resolves exact 1-indexed StartLine and EndLine, detects indentation/whitespace discrepancies (tabs vs spaces), auto-resolves actual file indentation, and outputs drop-in tool arguments.
• lg audit-diff [--staged] [--file <f>] [--json]: Pre-commit code sanity auditor. Scans git diff for leftover debug calls (dd, dump, ray, var_dump, console.log, debugger), temporary markers (TODO: remove), potential secrets/tokens, and runs PHP syntax validation.
• lg test-isolate <command...> [--json]: Test failure noise isolator for Pest, PHPUnit, and Python unittest. Strips 95% of framework and vendor stack traces to distill test failures into failure description, exact test location, failure assertion message, application stack frame, and snippet.
• MCP Server Expansion: Added localgrep_verify_patch, localgrep_audit_diff, and localgrep_test_isolate tools to mcp_server.py.
• Unit Test Suite: Added tests/test_phase3.py with 100% test coverage across patch verification, whitespace correction, and test isolation.

v0.5.1 - Upward Project Root Discovery in Topology

Fixed

• Upward Project Root Discovery in lg topo: Added parent directory traversal to detect composer.json or .git when lg topo is executed from deep subfolders (e.g. resources/js/Pages or app/Http), ensuring consistent and accurate topology resolution regardless of the active working directory.

v0.5.0 - Phase 2: Callers Tracking, Event Architecture Map & Offline Schema Extractor

• Added lg callers <Method|Class>: Deterministic call-site and reference tracker across PHP and Vue/TS/JS with caller context
• Added lg event-map [<filter>]: Laravel Event -> Listener -> Queue -> Job dependency graph mapper across modular packages
• Added lg schema <Model>: Offline database schema, columns, casts, fillables, and Eloquent relationships extractor
• Added full --json machine-readable mode across all new commands
• Added MCP server tools: localgrep_callers, localgrep_event_map, localgrep_schema
• 25 automated unit tests passing in 0.040s

v0.4.1 - Enhanced Route Disambiguation, Resource Expansion & Machine JSON Mode

• Added --json flag support across all LocalGrep commands for automated agent tooling
• Enhanced lg route with multi-line route definition parsing and chained method calls
• Implemented module-affinity and namespace-aware controller disambiguation resolving colliding controller names
• Added automatic Route::resource and Route::apiResource expansion into standard actions (index, create, store, show, edit, update, destroy) with ->only() and ->except() filtering
• Track nested route group prefixes and route names via curly brace depth stack
• Fixed Vue SFC withDefaults parenthesis parsing in lg contract without leaking component lifecycle code

v0.4.0: Contract Extractor, Route Mapper, and Project Topology

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog,
and this project adheres to Semantic Versioning.

[0.4.0] - 2026-09-30

Added

• lg contract <file|component>: AST contract extractor for Vue SFCs (defineProps, defineEmits, defineModel, slots), PHP classes/interfaces (namespace, public properties, constructor promoted properties, and public method signatures), and TypeScript modules. Slashes file-reading token burn by up to 90% (<10ms execution).
• lg route '<query>': Fast route-to-controller mapper. Scans Laravel routes/*.php and modular packages (vendor/bina/*/routes/), resolving route methods, URIs, route names, and exact controller target file line numbers in <30ms.
• lg topo: Zero-token project topology card. Generates an ultra-dense, 150-token executive summary of framework stack (Laravel, PHP), active frontend dependencies (Vue, Inertia, Tailwind, Vite), database/queue drivers, modular monorepo packages, and entry points (<15ms).
• MCP Server Expansion: Added localgrep_contract, localgrep_route, and localgrep_topo tools to mcp_server.py.
• Automated test suite in tests/test_phase1.py covering contract, route, and topology extraction.

---

[0.3.3] - 2026-09-30

Added

• Tier 1 Fast-Path Query Routing (<15ms): Automatically detects symbol, component, identifier, and PascalCase/camelCase queries. When high-confidence file or symbol declaration matches exist, bypasses the neural Cross-Encoder entirely, slashing query latency from >5000ms to sub-100ms.
• Hybrid Path + Content Discovery: Decoupled path-based file discovery from content search constraints. rg --files runs concurrently with dedicated dynamic path scoring (compute_file_path_score), guaranteeing component declarations (e.g. BinaTextEditor.vue for BinaEditor) outrank incidental callers.
• Noise Dampening for Localization & Dictionaries: Automatically excludes **/lang/** and **/locales/** from default code search scope (unless explicitly requested) and applies negative score penalties to eliminate dictionary saturation.
• Fully Offline Tokenizer Initialization: Enforced local_files_only=True on Hugging Face tokenizer loading with automatic fallback, preventing network round-trips and cold-start latency.

Changed

• Bounded neural Cross-Encoder candidate evaluation to the top 12 pre-ranked candidates with max sequence length 256, capping conceptual query execution time under 250ms.

---

[0.3.2] - 2026-09-29

Added

• Algorithmic Morphological Stemmer (stem_word): In-memory rule-based inflection analysis for prefixes (re-, un-), participles (-ed, -ing), and plural/verb suffixes (-s, -es, -ies), with grammatical sibilant exclusions (status, wherehas, alias).
• Software Engineering Action Taxonomy (PROGRAMMING_SYNONYMS): Zero-index lexical-semantic mapping covering 40+ common lifecycle verbs, framework relations, and domain entities (recalculate ↔ calculate/recalc/compute/update, variation ↔ variant/option/sku, bug ↔ issue/fix/wherehas/orwherehas).
• Compound Identifier Preservation: Preserves raw camelCase and snake_case symbols (such as orWhereHas) alongside tokenized components during search term extraction.
• Dynamic Modular Monorepo Discovery: Automatically inspects config/modules.php (paths.modules) to register custom module directories (e.g. vendor/bina/, Modules/) without hardcoding proprietary vendor names.
• Configurable Search Overrides (LOCALGREP_DIRS): Added environment variable support to scan arbitrary non-standard monorepo directories.
• Term Density Pre-scoring: Candidate ripgrep blocks are sorted and prioritized by query term density and source code weights prior to neural cross-encoder re-ranking.

Changed

• Decreased default cross-encoder sequence length to 256 and batch size to 16 to reduce peak working set memory footprint.
• Added meta-programming stop words (function, method, class, variable, trait, interface) to prevent candidate pollution.
• Excluded internal prompt directories (!**/prompts/**) from default source code search scope.

---

[0.3.1] - 2026-09-29

Added

• lg stop subcommand for graceful daemon shutdown with signal handling.
• Process-level locking using fcntl.flock on the daemon PID file to prevent startup race conditions.
• Automatic non-Latin query detection and user guidance message.
• Explicit non-TTY stream detection via stat.S_ISFIFO and stat.S_ISREG for seamless shell piping (cat file | lg "q").

Fixed

• Daemon Boot on Clean Install: Automatically downloads missing model.onnx from Hugging Face Hub during first run without crashing.
• Linear Memory Leak: Disabled ONNX Runtime CPU memory arena (enable_cpu_mem_arena = False) and pattern memory allocator, keeping daemon RSS constant across long-running query cycles.
• Header Snippet Extraction: Candidate path snippets now anchor on AST declaration keywords rather than generic namespace/license file headers.

Security

• Hardened daemon socket permissions from 0o777 in /tmp to 0o600 inside ~/.local/localgrep/ (mode 0o700), restricting socket communication strictly to the owning user.
• Added 30-second socket timeout and 10MB payload size limit on incoming connections to defend against socket starvation and buffer exhaustion.

---

[0.3.0] - 2026-09-28

Added

• lg skill "<task>" CLI command for instant (<25ms) dynamic recommendation of AI agent skills.
• Native Model Context Protocol (MCP) tool localgrep_skill for JIT skill resolution in Claude Code, Antigravity, and Cursor.
• Recursive skill discovery covering .claude/skills, .agents/skills, .gemini/skills, and builtin/skills.

---

[0.2.0] - 2026-09-28

Added

• Tree-sitter AST context pruner: lg prune <file> "<query>".
• Grammar parsers for PHP, JavaScript, TypeScript, Python, and Vue Single File Components (SFC).
• Model Context Protocol (MCP) server support (localgrep_search, localgrep_prune).
• ONNX Runtime cross-encoder backend with automatic fallback to PyTorch.

---

[0.1.0] - 2026-09-28

Added

• Initial release of LocalGrep (lg).
• Zero-index local semantic search combining ripgrep candidate extraction with cross-encoder re-ranking.
• Unix domain socket daemon architecture for sub-100ms response times.
• Stream distilling utility for large CLI command outputs (<command> | lg "<query>").

v0.3.3: Fast-Path Query Routing & Hybrid Candidate Discovery

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog,
and this project adheres to Semantic Versioning.

[0.3.3] - 2026-09-30

Added

• Tier 1 Fast-Path Query Routing (<15ms): Automatically detects symbol, component, identifier, and PascalCase/camelCase queries. When high-confidence file or symbol declaration matches exist, bypasses the neural Cross-Encoder entirely, slashing query latency from >5000ms to sub-100ms.
• Hybrid Path + Content Discovery: Decoupled path-based file discovery from content search constraints. rg --files runs concurrently with dedicated dynamic path scoring (compute_file_path_score), guaranteeing component declarations (e.g. BinaTextEditor.vue for BinaEditor) outrank incidental callers.
• Noise Dampening for Localization & Dictionaries: Automatically excludes **/lang/** and **/locales/** from default code search scope (unless explicitly requested) and applies negative score penalties to eliminate dictionary saturation.
• Fully Offline Tokenizer Initialization: Enforced local_files_only=True on Hugging Face tokenizer loading with automatic fallback, preventing network round-trips and cold-start latency.

Changed

• Bounded neural Cross-Encoder candidate evaluation to the top 12 pre-ranked candidates with max sequence length 256, capping conceptual query execution time under 250ms.

---

[0.3.2] - 2026-09-29

Added

• Algorithmic Morphological Stemmer (stem_word): In-memory rule-based inflection analysis for prefixes (re-, un-), participles (-ed, -ing), and plural/verb suffixes (-s, -es, -ies), with grammatical sibilant exclusions (status, wherehas, alias).
• Software Engineering Action Taxonomy (PROGRAMMING_SYNONYMS): Zero-index lexical-semantic mapping covering 40+ common lifecycle verbs, framework relations, and domain entities (recalculate ↔ calculate/recalc/compute/update, variation ↔ variant/option/sku, bug ↔ issue/fix/wherehas/orwherehas).
• Compound Identifier Preservation: Preserves raw camelCase and snake_case symbols (such as orWhereHas) alongside tokenized components during search term extraction.
• Dynamic Modular Monorepo Discovery: Automatically inspects config/modules.php (paths.modules) to register custom module directories (e.g. vendor/bina/, Modules/) without hardcoding proprietary vendor names.
• Configurable Search Overrides (LOCALGREP_DIRS): Added environment variable support to scan arbitrary non-standard monorepo directories.
• Term Density Pre-scoring: Candidate ripgrep blocks are sorted and prioritized by query term density and source code weights prior to neural cross-encoder re-ranking.

Changed

• Decreased default cross-encoder sequence length to 256 and batch size to 16 to reduce peak working set memory footprint.
• Added meta-programming stop words (function, method, class, variable, trait, interface) to prevent candidate pollution.
• Excluded internal prompt directories (!**/prompts/**) from default source code search scope.

---

[0.3.1] - 2026-09-29

Added

• lg stop subcommand for graceful daemon shutdown with signal handling.
• Process-level locking using fcntl.flock on the daemon PID file to prevent startup race conditions.
• Automatic non-Latin query detection and user guidance message.
• Explicit non-TTY stream detection via stat.S_ISFIFO and stat.S_ISREG for seamless shell piping (cat file | lg "q").

Fixed

• Daemon Boot on Clean Install: Automatically downloads missing model.onnx from Hugging Face Hub during first run without crashing.
• Linear Memory Leak: Disabled ONNX Runtime CPU memory arena (enable_cpu_mem_arena = False) and pattern memory allocator, keeping daemon RSS constant across long-running query cycles.
• Header Snippet Extraction: Candidate path snippets now anchor on AST declaration keywords rather than generic namespace/license file headers.

Security

• Hardened daemon socket permissions from 0o777 in /tmp to 0o600 inside ~/.local/localgrep/ (mode 0o700), restricting socket communication strictly to the owning user.
• Added 30-second socket timeout and 10MB payload size limit on incoming connections to defend against socket starvation and buffer exhaustion.

---

[0.3.0] - 2026-09-28

Added

• lg skill "<task>" CLI command for instant (<25ms) dynamic recommendation of AI agent skills.
• Native Model Context Protocol (MCP) tool localgrep_skill for JIT skill resolution in Claude Code, Antigravity, and Cursor.
• Recursive skill discovery covering .claude/skills, .agents/skills, .gemini/skills, and builtin/skills.

---

[0.2.0] - 2026-09-28

Added

• Tree-sitter AST context pruner: lg prune <file> "<query>".
• Grammar parsers for PHP, JavaScript, TypeScript, Python, and Vue Single File Components (SFC).
• Model Context Protocol (MCP) server support (localgrep_search, localgrep_prune).
• ONNX Runtime cross-encoder backend with automatic fallback to PyTorch.

---

[0.1.0] - 2026-09-28

Added

• Initial release of LocalGrep (lg).
• Zero-index local semantic search combining ripgrep candidate extraction with cross-encoder re-ranking.
• Unix domain socket daemon architecture for sub-100ms response times.
• Stream distilling utility for large CLI command outputs (<command> | lg "<query>").