purecontext-mcp 1.2.0 → 1.5.0

package/docs/dev/phase-35-coverage-audit.md

@@ -0,0 +1,469 @@
+# Phase 35 — PHP Coverage Gap Audit
+
+**Date**: 2026-05-15  
+**Benchmark project**: ntropy-client (CodeIgniter PHP app) at `D:/private/archive/ntropy/source/ntropy-client/src`  
+**PureContext repo ID**: `1dad4925caceee44`  
+**jCodeMunch index**: `local-src-6d0e6b5b`
+
+---
+
+## Task 206 — Apples-to-Apples Baseline
+
+### Setup
+
+Both tools were re-indexed fresh on the same project path before this audit.
+
+| Tool | Files Indexed | Total Symbols |
+|------|--------------|---------------|
+| PureContext | 2,865 | 9,011 |
+| jCodeMunch | — | 23,387 |
+
+### The Original 5× Gap Was a Measurement Artifact
+
+The benchmark (Phase 34) reported: **JC 21,984 symbols vs PC 4,291 symbols** — a 5× gap. This audit finds the gap is almost entirely explained by two measurement problems:
+
+#### Problem 1: JC counts CSS class selectors as "class" symbols
+
+jCodeMunch indexes CSS files and maps every CSS rule (`.selector { }`) to the `class` kind. On the ntropy-client project, this inflates JC's count by **14,027 CSS symbols** (60% of its total):
+
+| JC kind | PHP | CSS | JS/other | Total |
+|---------|-----|-----|----------|-------|
+| class   | 929 | 13,345 | 208 | 14,482 |
+| method  | 7,662 | 0 | 0 | 7,662 |
+| function | 267 | 0 | 354 | 621 |
+| type    | 68 | 0 | 413 | 481 |
+| constant | 0 | 0 | 141 | 141 |
+| **Total** | **8,926** | **13,345** | **1,116** | **23,387** |
+
+PureContext does not index CSS files, so its count is PHP/JS/TS only.
+
+#### Problem 2: The old PC benchmark used an early index
+
+The old benchmark compared JC's `local-eu-za-tebe-bd0ab334` index (21,984 symbols) against a PC count of 4,291. The current fresh PC index of the same codebase yields 9,011 symbols — more than 2× the old count. The old count came from an earlier version of PureContext with a smaller file limit or an older state of the code.
+
+### Apples-to-Apples Comparison: PHP Only
+
+| Metric | jCodeMunch | PureContext |
+|--------|-----------|-------------|
+| PHP symbol count | **8,926** | **8,781** |
+| PHP files with symbols | 1,016 | 991 |
+| PHP/PHP gap ratio | — | **1.02× (near parity)** |
+
+**The adjusted coverage ratio is 1.02×, not 5×.** The original benchmark finding was a measurement artifact from CSS contamination and an outdated PC index.
+
+### PHP Kind Breakdown: Where the 145-Symbol Difference Lives
+
+| Kind | jCodeMunch | PureContext | Delta |
+|------|-----------|-------------|-------|
+| method | 7,662 | 7,326 | JC +336 |
+| class | 929 | 929 | = |
+| function | 267 | 85 | JC +182 |
+| const | 0 | 373 | PC +373 |
+| interface | 0 | 68 | PC +68 |
+| type | 68 | 0 | JC +68 |
+| **Total** | **8,926** | **8,781** | JC +145 |
+
+Key observations:
+- **methods**: JC extracts 336 more methods. Likely cause: PureContext skips `private` methods (`isPrivateMethod` filter in `extractMembers`); jCodeMunch does not filter by visibility.
+- **functions**: JC extracts 182 more top-level PHP functions. Cause to investigate in Task 208.
+- **const**: PC extracts 373 constants (class `const` declarations and top-level `const`) that JC does not. JC's PHP_SPEC lists `const_declaration` in `constant_patterns` but uses kind `constant` — yet the DB shows 0 PHP constant entries. Likely extraction failure similar to the property issue (see below).
+- **interface**: PC maps `trait_declaration` to `interface` kind (68 entries); JC maps it to `type`. After normalising kinds, these are the same symbols.
+
+---
+
+### CIR_Model.php Side-by-Side
+
+File: `application/core/CIR_Model.php`  
+Content: 280 lines, 1 class (`CIR_Model extends CI_Model`), 1 property (`$table`), 16 methods.
+
+#### jCodeMunch output (18 expected, 17 extracted)
+
+| Line | Kind | Name |
+|------|------|------|
+| 20 | class | CIR_Model |
+| 24 | method | CIR_Model.__construct |
+| 31 | method | CIR_Model.get_by_id |
+| 39 | method | CIR_Model.get_by_slug |
+| 50 | method | CIR_Model.insert |
+| 63 | method | CIR_Model.insert_batch |
+| 73 | method | CIR_Model.update |
+| 90 | method | CIR_Model.delete |
+| 112 | method | CIR_Model.get_all |
+| 138 | method | CIR_Model.get_rid_of_serbian_letters |
+| 144 | method | CIR_Model.create_excerpt |
+| 152 | method | CIR_Model.process_dates |
+| 162 | method | CIR_Model.generate_slug |
+| 184 | method | CIR_Model.generate_uid |
+| 198 | method | CIR_Model.get_admin_type |
+| 208 | method | CIR_Model.go_up |
+| 241 | method | CIR_Model.go_down |
+
+Not extracted: `$table` (property_declaration) — see "property extraction failure" below.
+
+#### PureContext output (18 expected, 17 extracted)
+
+| Line | Kind | Name | Notes |
+|------|------|------|-------|
+| 20 | class | CIR_Model | ✓ |
+| 24 | method | CIR_Model::__construct | ✓ |
+| 31 | method | CIR_Model::get_by_id | ✓ |
+| 39 | method | CIR_Model::get_by_slug | ✓ |
+| 50 | method | CIR_Model::insert | ✓ |
+| 63 | method | CIR_Model::insert_batch | ✓ |
+| 73 | method | CIR_Model::update | ✓ |
+| 90 | method | CIR_Model::delete | ✓ |
+| 112 | method | CIR_Model::get_all | ✓ |
+| 138 | method | CIR_Model::get_rid_of_serbian_letters | ✓ |
+| 144 | method | `CIR_Model:: function crea` | **BROKEN NAME** — should be `create_excerpt` |
+| 152 | method | `CIR_Model:: function pro` | **BROKEN NAME** — should be `process_dates` |
+| 162 | method | `CIR_Model:: function gen` | **BROKEN NAME** — should be `generate_slug` |
+| 184 | method | CIR_Model::generate_uid | ✓ |
+| 198 | method | CIR_Model::get_admin_type | ✓ |
+| 208 | method | CIR_Model::go_up | ✓ |
+| 241 | method | CIR_Model::go_down | ✓ |
+
+Not extracted: `$table` (property_declaration).
+
+#### Classification
+
+| Entity | JC | PC | Classification |
+|--------|----|----|----------------|
+| CIR_Model (class) | ✓ | ✓ | (a) Also found by PureContext |
+| `__construct` | ✓ | ✓ | (a) Also found |
+| `get_by_id` | ✓ | ✓ | (a) Also found |
+| `get_by_slug` | ✓ | ✓ | (a) Also found |
+| `insert` | ✓ | ✓ | (a) Also found |
+| `insert_batch` | ✓ | ✓ | (a) Also found |
+| `update` | ✓ | ✓ | (a) Also found |
+| `delete` | ✓ | ✓ | (a) Also found |
+| `get_all` | ✓ | ✓ | (a) Also found |
+| `get_rid_of_serbian_letters` | ✓ | ✓ | (a) Also found |
+| `create_excerpt` | ✓ | ✗ (broken name) | (b) Same concept, broken name in PC |
+| `process_dates` | ✓ | ✗ (broken name) | (b) Same concept, broken name in PC |
+| `generate_slug` | ✓ | ✗ (broken name) | (b) Same concept, broken name in PC |
+| `generate_uid` | ✓ | ✓ | (a) Also found |
+| `get_admin_type` | ✓ | ✓ | (a) Also found |
+| `go_up` | ✓ | ✓ | (a) Also found |
+| `go_down` | ✓ | ✓ | (a) Also found |
+| `$table` (property) | ✗ | ✗ | (c) Genuinely absent from both |
+
+**Summary for CIR_Model.php**: Both tools miss the `$table` property. PC extracts the same 17 symbols as JC, but 3 method names are corrupted by a UTF-8 byte/char offset bug.
+
+---
+
+### Property Extraction Failure (Both Tools)
+
+`CIR_Model.php` has `public $table = '';` — a `property_declaration` node in the PHP grammar.
+
+**jCodeMunch**: Despite listing `"property_declaration": "property"` in `PHP_SPEC.symbol_node_types`, JC extracts 0 PHP property symbols across the entire project. Root cause: the PHP tree-sitter grammar does not expose a `name` field on `property_declaration` nodes — it uses `property_element` → `variable_name`. `_extract_name()` falls back to `node.child_by_field_name("name")` which returns None, so the symbol is silently dropped.
+
+**PureContext**: Does not attempt `property_declaration` extraction at all — it is not in the handler's node type list.
+
+**Net effect**: Neither tool captures class property declarations. This is a genuine gap in both implementations, not a competitive disadvantage for PureContext alone.
+
+---
+
+### PC Name Extraction Bug (UTF-8 Offset)
+
+Three methods in CIR_Model.php have broken names after `get_rid_of_serbian_letters`:
+- `CIR_Model:: function crea` (should be `create_excerpt`)  
+- `CIR_Model:: function pro` (should be `process_dates`)
+- `CIR_Model:: function gen` (should be `generate_slug`)
+
+The signatures for these methods start with `}` (the closing brace of the previous method), and the names contain ` function crea` as raw source text. This is a **byte vs character offset bug**: the method body of `get_rid_of_serbian_letters` contains multibyte UTF-8 characters (Serbian letters: `š`, `đ`, `ž`, `č`, `ć`, `Š`, `Đ`, `Ž`, `Č`, `Ć`), each taking 2 bytes. After this method, web-tree-sitter's `startIndex` values are byte-based, but the source buffer slicing uses them as character offsets — causing a negative shift for all subsequent method nodes.
+
+This is the same bug documented in `feedback_handler_text_extraction.md`. It was fixed in the TypeScript handler but not yet in the PHP handler for all code paths. The `buildSignature` function correctly uses `source.toString('utf8', byteOffset, endByte)` — but `getNameText` relies on `nameNode?.text` which, in web-tree-sitter, may use character-based string slicing internally when the source contains multibyte UTF-8.
+
+**Impact**: Any PHP file containing multibyte UTF-8 characters in method bodies will produce broken names for all subsequent methods. This is a data quality bug, not a coverage gap.
+
+---
+
+### Answers to the Key Questions
+
+1. **Does jCodeMunch count PHP files themselves as symbols?** No. The PHP_SPEC has no file-level entry and the DB confirms no such symbols.
+
+2. **Does jCodeMunch count import-kind entries?** No. PHP `use` statements are not in JC's symbol kinds.
+
+3. **What is the adjusted coverage ratio after correcting?**
+   - Remove CSS symbols from JC: 23,387 − 14,027 = **9,360 non-CSS JC symbols**
+   - PHP-only JC: **8,926** vs PHP-only PC: **8,781**
+   - **Adjusted ratio: 1.02× (JC has 1.6% more PHP symbols)**
+
+The original 5× gap was:
+- ~2× from comparing different versions of the PC index (old, smaller PC count)
+- ~2.5× from CSS contamination in JC's total count
+- After both corrections: **no meaningful coverage gap**
+
+---
+
+## Task 207 — jCodeMunch PHP Extractor Source Audit
+
+### Sources Examined
+
+- `reference/jcodemunch-mcp/src/jcodemunch_mcp/parser/languages.py` — `PHP_SPEC` (line 468)
+- `reference/jcodemunch-mcp/src/jcodemunch_mcp/parser/extractor.py` — `_walk_tree`, `_extract_symbol`, `_extract_name`, `_extract_constant`
+- `src/handlers/php.ts` — PureContext PHP handler
+
+### Node Type Comparison Table
+
+| PHP construct | tree-sitter node type | JC extracts? | PC extracts? | Notes |
+|---|---|---|---|---|
+| Top-level function | `function_definition` | ✓ function | ✓ function | Both |
+| Class declaration | `class_declaration` | ✓ class | ✓ class | Both |
+| Method declaration | `method_declaration` | ✓ method (all) | ✓ method (non-private) | JC includes private; PC skips them |
+| Interface | `interface_declaration` | ✓ type | ✓ interface | Same content, different kind label |
+| Trait | `trait_declaration` | ✓ type | ✓ interface | Same content, different kind label |
+| Enum | `enum_declaration` | ✓ type | ✓ enum | Same content, different kind label |
+| Class property | `property_declaration` | ✗ (spec lists it; extraction fails) | ✗ (not in handler) | Gap in both |
+| Class constant | `const_declaration` (inside class) | ✗ (extraction fails) | ✓ const | PC advantage |
+| Top-level constant | `const_declaration` (top-level) | ✗ (extraction fails) | ✓ const | PC advantage |
+
+### Why JC's `property_declaration` Extraction Fails
+
+JC's `PHP_SPEC` lists:
+```python
+symbol_node_types={"property_declaration": "property"},
+name_fields={"property_declaration": "name"},
+```
+
+But the PHP tree-sitter grammar does **not** expose a `name` field on `property_declaration` nodes. The actual grammar structure is:
+
+```
+property_declaration
+  visibility_modifier: "public"
+  property_element
+    variable_name: "$table"   ← no `name` field; requires child traversal
+```
+
+In `_extract_name()`, `node.child_by_field_name("name")` returns None, so the function returns None, and the symbol is silently dropped. **Zero PHP property symbols exist in JC's index** despite the spec listing them.
+
+### Why JC's `const_declaration` Extraction Fails
+
+JC's `PHP_SPEC` lists `const_declaration` in `constant_patterns`. In `_walk_tree()`:
+```python
+if node.type in spec.constant_patterns and parent_symbol is None:
+    const_symbol = _extract_constant(node, ...)
+```
+
+Two problems:
+1. **`parent_symbol is None` check** — class-level `const` declarations have the class as parent, so they are never even attempted.
+2. **`_extract_constant` has no PHP handler** — the function handles Python `assignment`, C `preproc_def`, GDScript `const_statement`, Perl `use_statement`, and Swift `property_declaration`. There is no branch for PHP `const_declaration`. All PHP `const` nodes fall through and return `None`.
+
+Result: JC extracts **0 PHP constant symbols** from this project. PC extracts **373** (372 class-level, 1 top-level) across 72 files.
+
+### Visibility Filter Difference
+
+PC's `extractMembers()` explicitly skips private methods:
+```typescript
+if (isPrivateMethod(child)) continue;
+```
+
+JC's `_walk_tree()` has no visibility filter — all method declarations are extracted regardless of `private`/`protected`/`public`. This accounts for the 336-method delta between JC and PC across the project (JC: 7,662 PHP methods; PC: 7,326).
+
+### File Coverage Difference (Top-Level Functions)
+
+JC extracts 267 PHP top-level functions; PC extracts 85. The 182-function gap is driven by CodeIgniter system helper files (`form_helper.php`, `url_helper.php`, `date_helper.php`, etc.) that JC indexes but PC does not include in its extraction results. These files appear to be present in `system/` subdirectories which may be outside PC's default extraction scope. This is a file-coverage difference, not a node-type extraction gap.
+
+### Summary: Node Type Diff Table
+
+**JC extracts that PC does not (in theory):**
+- `property_declaration` → "property" — but **extraction fails in practice** (wrong name field); effectively 0 symbols extracted
+
+**PC extracts that JC does not (in practice):**
+- `const_declaration` (class-level + top-level) → "const" — **PC: 373 symbols; JC: 0**
+
+**Kind label differences (same symbols, different names):**
+- `interface_declaration` / `trait_declaration`: JC → "type", PC → "interface"
+- `enum_declaration`: JC → "type", PC → "enum"
+
+---
+
+## Task 208 — Three-File Symbol Audit
+
+File 3 (`application/modules/bridge/models/Homepage_model.php`) does not exist in this project. Substituted with `application/libraries/Flexi_auth_lite.php` — a library class with a broad method signature variety and no property declarations, providing a clean method-parity check.
+
+---
+
+### File 1: `application/core/CIR_Model.php`
+
+*(Full analysis in Task 206 — summary only here)*
+
+| Entity | JC | PC | Notes |
+|--------|----|----|-------|
+| CIR_Model (class) | ✓ | ✓ | — |
+| 16 methods | ✓ | ✓ (3 broken names) | UTF-8 offset bug in PC |
+| `$table` (property) | ✗ | ✗ | Neither tool extracts |
+| **Total** | **17** | **17** | Equal count; PC has data quality issue |
+
+Absent from both: 1 property (`$table = ''`).
+
+---
+
+### File 2: `application/libraries/Twig.php`
+
+File: 226 lines. Contains: 1 class, 1 class constant (`TWIG_CONFIG_FILE`), 5 properties (`$module`, `$template_dir`, `$cache_dir`, `$_ci`, `$_twig_env`), 8 methods.
+
+| Line | Entity | Kind in file | JC | PC |
+|------|--------|-------------|----|----|
+| 26 | `Twig` | class | ✓ class | ✓ class |
+| 27 | `TWIG_CONFIG_FILE` | class constant | ✗ | ✓ const |
+| 35 | `$module` | public property | ✗ | ✗ |
+| 42 | `$template_dir` | protected property | ✗ | ✗ |
+| 49 | `$cache_dir` | protected property | ✗ | ✗ |
+| 56 | `$_ci` | private property | ✗ | ✗ |
+| 63 | `$_twig_env` | private property | ✗ | ✗ |
+| 68 | `__construct` | method | ✓ | ✓ |
+| 118 | `setPaths` | method | ✓ | ✓ |
+| 133 | `render` | method | ✓ | ✓ |
+| 161 | `display` | method | ✓ | ✓ |
+| 183 | `register_function` | method | ✓ | ✓ |
+| 188 | `add_filter` | method | ✓ | ✓ |
+| 202 | `addGlobal` | method | ✓ | ✓ |
+| 211 | `ci_function_init` | method | ✓ | ✓ |
+| **Total** | | | **9** | **10** |
+
+**Gaps:**
+- `TWIG_CONFIG_FILE` (class constant): (c) genuinely absent from JC; PC extracts it correctly.
+- 5 properties: (c) genuinely absent from both.
+
+JC classification: 1 class + 8 methods = 9 symbols (missing 1 constant + 5 properties).  
+PC classification: 1 class + 1 const + 8 methods = 10 symbols (missing 5 properties).
+
+---
+
+### File 3 (Substitute): `application/libraries/Flexi_auth_lite.php`
+
+File: ~700 lines. Contains: 1 class, 0 class constants, 0 explicit property declarations, 44 methods (all public).
+
+| Entity | JC | PC | Notes |
+|--------|----|----|-------|
+| `Flexi_auth_lite` (class) | ✓ | ✓ | — |
+| 44 methods | ✓ (all 44) | ✓ (all 44) | Perfect parity |
+| **Total** | **45** | **45** | Equal |
+
+No properties declared at class level (only `$this->CI` assigned in constructor). No constants. This file confirms that method extraction is at parity when no multibyte UTF-8 chars are present and no private methods exist.
+
+---
+
+### Three-File Summary
+
+| File | JC count | PC count | JC-only | PC-only | Missing from both |
+|------|----------|----------|---------|---------|-------------------|
+| CIR_Model.php | 17 | 17 | 0 | 0 (3 broken) | 1 property |
+| Twig.php | 9 | 10 | 0 | 1 const | 5 properties |
+| Flexi_auth_lite.php | 45 | 45 | 0 | 0 | 0 |
+
+**Pattern across all three files:**
+- PC extracts class constants; JC does not.
+- Neither tool extracts class properties.
+- Method extraction is at parity (no private methods in these files).
+- PC has a data quality bug (broken names for 3 methods in CIR_Model.php).
+
+### Ranked Extraction Gaps by Estimated Impact
+
+Across the full project (991 PHP files with symbols):
+
+| Gap | Who is affected | Frequency estimate | Searchability |
+|-----|----------------|-------------------|---------------|
+| Class property declarations | Both tools | ~1–3 per class → est. 500–1500 total | Medium-High |
+| Class constants (PC already has; JC doesn't) | JC only | 372 found by PC across 72 files | Medium |
+| Private methods (JC has; PC skips) | PC only | 336 delta across project | Low (private = implementation detail) |
+| Top-level helper functions in system/ | PC only | ~178 across helper files | Medium |
+
+---
+
+## Task 209 — Implementation Recommendations for Phase 36
+
+### Gap: Class Property Declarations
+
+**PHP construct**: `property_declaration`  
+**Example**: `public $table = '';` → symbol `CIR_Model::$table` (kind: property)  
+**Frequency estimate**: ~1,000–1,500 occurrences project-wide (based on Twig having 5, CIR_Model having 1; average ~1.5 per class across 929 classes). Confirmed: 72 files have class constants (a subset); properties are more prevalent.  
+**Search value**: **High** — `$db`, `$config`, `$table`, `$_ci` are meaningful names that appear in NL queries like "what's the database connection field?" or "find the config property". Public and protected properties are especially valuable; private ones are lower value.  
+**Implementation effort**: **Medium** — the property node in the PHP grammar has structure `property_element → variable_name`. Requires custom extraction logic (not just `childForFieldName('name')`): must find the `property_element` child, then get the `variable_name` child's text and strip the leading `$`.  
+**Recommended**: **Yes** — highest impact gap, affects both tools equally, medium effort.
+
+```typescript
+// Sketch in extractMembers():
+} else if (child.type === 'property_declaration') {
+  // skip private properties
+  if (isPrivateVisibility(child)) continue;
+  for (const pe of child.children) {
+    if (pe.type !== 'property_element') continue;
+    const varNode = pe.children.find(c => c.type === 'variable_name');
+    if (!varNode) continue;
+    const name = `${className}::${varNode.text}`; // e.g. CIR_Model::$table
+    symbols.push({ kind: 'const', name, ... });
+  }
+}
+```
+
+---
+
+### Gap: UTF-8 Broken Name Bug
+
+**PHP construct**: method names after UTF-8 multibyte characters in method bodies  
+**Example**: `create_excerpt`, `process_dates`, `generate_slug` in `CIR_Model.php` become `CIR_Model:: function crea` etc.  
+**Frequency estimate**: Any PHP file with non-ASCII characters (Serbian, French, Spanish, etc.) in method bodies will produce broken names for all subsequent methods. Conservatively affects ~50–100 files in localised projects.  
+**Search value**: **Critical** — broken names make affected symbols completely unsearchable.  
+**Implementation effort**: **Low** — the fix is to use `source.slice(node.startIndex, nameNode.endIndex).toString('utf8')` → `nameNode.text` via buffer bytes, not JS string. The pattern is already fixed in the TS handler; apply the same fix to PHP's `getNameText`.  
+**Recommended**: **Yes, P0** — this is a data quality bug, not a feature gap. Should be fixed in Phase 36 alongside the property extraction.
+
+---
+
+### Gap: `define()` Constants
+
+**PHP construct**: `function_call_expression` where function name is `define`  
+**Example**: `define('MAX_RETRIES', 3);` → symbol `MAX_RETRIES` (kind: const)  
+**Frequency estimate**: **Low** — `define()` is a PHP 4/5 pattern; modern PHP uses `const`. A grep across the project finds minimal usage in this codebase.  
+**Search value**: **Medium** — named constants are searchable, but `define()` is rare in modern CodeIgniter projects.  
+**Implementation effort**: **Medium** — requires a custom call-expression check in the extraction loop.  
+**Recommended**: **Deferred** — low frequency in this project; implement in Phase 36 only if grep confirms significant usage.
+
+---
+
+### Gap: Anonymous Functions / Closures
+
+**PHP construct**: `anonymous_function_creation_expression` or `arrow_function` assigned to variables  
+**Example**: `$validator = function($x) { return $x > 0; };` → symbol `$validator` (kind: function)  
+**Frequency estimate**: **Low** — closures in this CodeIgniter project are rare; most logic is in named methods.  
+**Search value**: **Low** — closure variable names (`$validator`, `$callback`) are rarely searched for directly.  
+**Implementation effort**: **High** — requires scanning expression_statement nodes for variable assignments whose RHS is an anonymous function.  
+**Recommended**: **Skip** — low frequency + low searchability + high effort. Not worth Phase 36.
+
+---
+
+### Gap: Class Constants (PC already has this)
+
+**PHP construct**: `const_declaration` inside a class  
+**Status**: Already implemented in PC (`extractMembers` handles `const_declaration`). PC has 372 class-level PHP constants; JC has 0.  
+**Recommended**: **No action needed for PC**. (Noted for completeness — JC has this bug; PC does not.)
+
+---
+
+### Gap: Private Methods (JC includes; PC skips)
+
+**Status**: PC deliberately skips `private` methods. JC extracts all methods regardless of visibility.  
+**Search value**: **Low** — private methods are implementation details not intended for external consumers.  
+**Recommended**: **Keep PC behavior** (skip private methods). This is the correct choice for an index aimed at AI navigation.
+
+---
+
+### Ranked Recommendation Summary for Phase 36
+
+| Priority | Gap | Kind | Effort | Action |
+|----------|-----|------|--------|--------|
+| **P0** | UTF-8 broken name bug | bug fix | Low | Fix `getNameText` in `php.ts` to use buffer byte slicing |
+| **P1** | Class property declarations | new extraction | Medium | Add `property_declaration` to `extractMembers()` |
+| **P2** | `define()` constants | new extraction | Medium | Only if grep confirms ≥20 occurrences project-wide |
+| **Skip** | Anonymous function closures | new extraction | High | Frequency + value too low |
+| **Keep** | Private method skipping | behavior | — | PC is correct; JC's inclusion is a disadvantage |
+
+### Expected Impact of P0+P1
+
+- **P0 (UTF-8 fix)**: Restores correct names for all methods in PHP files with non-ASCII chars. Zero symbol count change; critical data quality improvement.
+- **P1 (property extraction)**: Adds ~1,000–1,500 new PHP property symbols (~10–17% increase in PHP symbol count). Enables queries like "find the database connection field", "what properties does CIR_Model have?".
+
+---
+
+*Phase 35 complete. Proceed to Phase 36 implementation starting with the UTF-8 bug fix (P0) and property extraction (P1).*

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "purecontext-mcp",
-  "version": "1.2.0",
+  "version": "1.5.0",
   "description": "Token-efficient source code navigation MCP server for AI agents",
   "type": "module",
   "license": "MIT",
@@ -34,6 +34,7 @@
     "README.md",
     "AGENT_INSTRUCTIONS.md",
     "AGENT_INSTRUCTIONS_SHORT.md",
+    "AGENT_REFERENCE.md",
     "AI-SUMMARIES.md",
     "AST-SEARCH.md",
     "CHANGELOG.md",
@@ -41,8 +42,10 @@
     "CODE-HISTORY.md",
     "CODE-INTELLIGENCE.md",
     "FINDING-CODE.md",
+    "FRAMEWORK-ADAPTERS.md",
     "FULL-INSTALLATAION-GUIDE.md",
     "HEALTH-DASHBOARDS.md",
+    "LANGUAGE-SUPPORT.md",
     "LICENSE",
     "NAVIGATING-NEW-CODE.md",
     "REFACTORING-SAFELY.md",