purecontext-mcp 1.1.1 → 1.1.2

package/docs/dev/PHASE6_TASKS.md

@@ -1,347 +0,0 @@
-# Phase 6 — Task Breakdown
-
-**Goal**: Expand language coverage to C++, Lua, and Dart, and deliver the Flutter framework adapter. This phase completes the systems-language tier (C++ extends the C foundation from Phase 5), adds Lua for the game scripting and embedded scripting community, and adds Dart/Flutter for the mobile and cross-platform development community.
-
-**Scope rationale**: Phase 5 delivered PHP, Ruby, Kotlin, C, and all Python/Go framework adapters. The three remaining languages with good grammar availability and strong demand are C++ (official grammar, extends C), Lua (community grammar, widely used via Neovim and game engines), and Dart (community grammar, driven by Flutter adoption). C++ is the most complex handler in this phase due to namespace context tracking and template unwrapping. Lua and Dart are lower complexity. Flutter is Dart's dominant framework and a straightforward adapter once the Dart handler exists.
-
-**Approach**: Tasks are sequenced so each one builds on the previous. C++ should be done first (it builds conceptually on the C handler from Phase 5). Lua and Dart are independent of each other and of C++. Flutter follows Dart. Complete tasks in order within each language group; language groups can be parallelised if desired.
-
----
-
-## Task 61: Extend SymbolKind for Phase 6
-
-Add two new `SymbolKind` values required by C++ and Flutter before those handlers compile.
-
-**Deliverables:**
-- Update `src/core/types.ts` — extend the `SymbolKind` union:
-  ```typescript
-  export type SymbolKind =
-    // Existing (Phase 1–5, unchanged)
-    | 'function' | 'class' | 'method' | 'const' | 'type'
-    | 'interface' | 'enum' | 'component' | 'composable'
-    | 'hook' | 'route' | 'decorator' | 'middleware'
-    | 'model' | 'view' | 'struct' | 'macro' | 'signal'
-    // Phase 6 additions
-    | 'namespace'  // C++ named namespace; PHP namespace (retroactive enrichment); Kotlin package object
-    | 'widget';    // Flutter StatelessWidget / StatefulWidget subclasses
-  ```
-
-**Rationale:**
-- `namespace`: C++ namespaces are first-class navigational units — agents frequently ask "what's in namespace Foo?". Using `type` or `class` loses this distinction. Also applicable retroactively to PHP namespace declarations (the Phase 5 PHP handler tracks namespaces as prefixes but does not emit them as symbols — emitting them as `namespace` kind is opt-in and additive).
-- `widget`: Flutter's defining pattern is a class extending `StatelessWidget` or `StatefulWidget` with a `build()` method. A dedicated kind lets agents query "find all widgets" meaningfully, distinct from plain `class` symbols.
-
-**Backward-compatibility:** Both additions are appended to the union. No migrations required.
-
-**Verify:** `npm run build` succeeds. All Phase 1–5 tests still pass.
-
-**Tests:** Type-level assertion that new kinds are valid `SymbolKind` values.
-
----
-
-## Task 62: C++ Language Handler
-
-Add C++ as the most complex language handler in Phase 6. C++ extends C with classes, namespaces, templates, and inheritance — requiring a namespace context stack and template unwrapping during AST traversal.
-
-**Deliverables:**
-- Download and bundle `grammars/tree-sitter-cpp.wasm`
-  - Source: `tree-sitter-cpp` npm package (official tree-sitter grammar, extends C grammar)
-  - Build: `npx tree-sitter build-wasm node_modules/tree-sitter-cpp`
-- `src/handlers/cpp.ts` — implements `LanguageHandler`
-  - `extensions()`: `['.cpp', '.cxx', '.cc', '.c++', '.hpp', '.hxx', '.hh', '.h++']`
-  - `grammarPath()`: path to `tree-sitter-cpp.wasm`
-  - `extractSymbols(tree, source)`:
-    - Use a recursive `walkNode(node, context: { nsStack: string[], className: string | null, accessLevel: 'public' | 'private' | 'protected' })` helper
-    - **Namespace context stack**: when entering `namespace_definition`, push the namespace name (or `<anonymous>` for unnamed namespaces) onto `nsStack`; pop on exit. Qualify all emitted symbol names with `nsStack.join('::')`.
-    - **Top-level and namespace-scoped declarations**:
-      - `function_definition` → kind `'function'`, name qualified with namespace stack
-      - `class_specifier` or `struct_specifier` as the type in a `type_definition` or directly at namespace scope → kind `'class'` (for `class`) or `'struct'` (for `struct`)
-      - `enum_specifier` → kind `'enum'`
-      - `alias_declaration` (`using Foo = Bar`) → kind `'type'`
-      - `namespace_definition` → kind `'namespace'`, name from `name` child; recurse into body
-      - `template_declaration` wrapping any of the above → unwrap (see below) and emit the inner symbol
-    - **Class body** (inside `class_specifier` or `struct_specifier` body `field_declaration_list`):
-      - Track current access level: default is `private` for `class`, `public` for `struct`
-      - `access_specifier` node (`public:`, `private:`, `protected:`) → update context `accessLevel`
-      - Skip nodes where `accessLevel` is `'private'`
-      - `function_definition` inside class body → kind `'method'`, name = `Namespace::ClassName::methodName`
-      - `constructor_definition` → kind `'method'`, name = `ClassName::ClassName`
-      - `destructor_name` function → kind `'method'`, name = `ClassName::~ClassName`
-      - Nested `class_specifier` or `struct_specifier` → recurse with updated className context
-    - **Template unwrapping**:
-      - `template_declaration` has a `template_parameters` child and a declaration child
-      - Find the first child that is a `function_definition`, `class_specifier`, `struct_specifier`, or `alias_declaration`
-      - Extract the template parameter list string (`template<...>`) and prepend it to the symbol signature
-      - Emit the inner symbol normally; skip explicit template specializations (they have `<` immediately after the name)
-    - **Preprocessor macros** (same as C handler):
-      - `preproc_def` → kind `'macro'`; skip `preproc_function_def` and guard macros
-  - `extractImports(tree, source)`:
-    - `preproc_include` nodes — same as C handler
-    - `using_declaration` (`using std::vector`) — record as an import with specifier = qualified name
-    - `using_directive` (`using namespace std`) — record with specifier = namespace name, `importedNames: []`
-  - `extractDocstring(node)`:
-    - Same as C handler: walk `previousNamedSibling` for `comment` nodes; handle `//` and `/* */`
-    - Also handle Doxygen `///` prefix lines
-- Update `src/handlers/handler-registry.ts` — add entry for C++ extensions
-- Update `src/index.ts` — register C++ handler in bootstrap
-
-**Signature building:**
-- Functions: `[template<T>] returnType qualifiedName(params)`
-- Classes: `[template<T>] class Namespace::Name [: public Base]`
-- Structs: `[template<T>] struct Namespace::Name`
-- Namespaces: `namespace Name` (signature is just the declaration line)
-- Methods: `[virtual] [static] returnType ClassName::methodName(params) [const] [override]`
-- Destructors: `~ClassName()`
-- Type aliases: `using Name = Type`
-- Macros: `#define NAME value`
-- Keep signatures under 120 chars
-
-**Key technical notes:**
-- **Namespace stack is critical**: without it, symbols from `namespace Foo { namespace Bar { class Baz {}}}` would emit as just `Baz` instead of `Foo::Bar::Baz`
-- **Anonymous namespaces** (`namespace { ... }`): symbols inside have internal linkage — skip or emit with `<anonymous>::Name` prefix. In Phase 6, skip anonymous namespace symbols entirely (implementation details).
-- **Template specialisation detection**: `template<>` (empty template parameters) indicates a full specialisation — skip these, they are implementation details of the primary template.
-- **Operator overloads**: `operator==`, `operator<<` — the name child will be an `operator_name` node; emit as `'method'` with name `ClassName::operator==`
-- **`inline` and `constexpr`**: modifiers in `declaration_specifiers` — include in signature but do not affect extraction logic
-- **Forward declarations**: `class Foo;` at namespace scope — skip (no body means no symbols to extract)
-- The C++ handler reuses the name-unwrapping helper from the C handler for pointer declarators
-
-**Verify:** Index `test/fixtures/cpp-project/`. Verify namespace-qualified names (`Foo::Bar::method`), template class extraction, struct vs class distinction, access specifier filtering (private methods skipped), destructor extraction.
-
-**Tests:** Named namespace qualifying names, nested namespaces (`::` separator), top-level function, class with public/private methods (private skipped), struct with public fields, `template<T>` class, template function, `using Foo = Bar` type alias, `#define` macro, `#include`, destructor, constructor, operator overload name.
-
----
-
-## Task 63: Lua Language Handler
-
-Add Lua as a lightweight scripting language handler. Lua's grammar is well-maintained by the community (used by Neovim's tree-sitter integration) and its function definition patterns, while idiomatic, are well-defined.
-
-**Deliverables:**
-- Download and bundle `grammars/tree-sitter-lua.wasm`
-  - Source: `tree-sitter-lua` npm package (MunifTanjim/tree-sitter-lua, used by Neovim)
-  - Build: `npx tree-sitter build-wasm node_modules/tree-sitter-lua`
-- `src/handlers/lua.ts` — implements `LanguageHandler`
-  - `extensions()`: `['.lua']`
-  - `grammarPath()`: path to `tree-sitter-lua.wasm`
-  - `extractSymbols(tree, source)`:
-    - Lua has multiple function definition patterns — all must be detected:
-
-    **1. Named function declaration** (`function foo() ... end`):
-    - `function_declaration` node → kind `'function'`
-    - Name from `dot_index_expression` or `method_index_expression` child (module methods) or plain `identifier`
-    - `method_index_expression` (`Module:method`) → kind `'method'`, name = `Module:method`
-
-    **2. Local function** (`local function foo() ... end`):
-    - `local_function` node → kind `'function'`
-
-    **3. Variable assignment to function literal** (`foo = function() ... end`):
-    - `assignment_statement` where the RHS is a `function_definition` node
-    - LHS is a `variable_list` with one `identifier` → kind `'function'`
-    - LHS is a `dot_index_expression` (`Module.foo = function()`) → kind `'method'`, name = `Module.foo`
-
-    **4. Local variable assignment to function literal** (`local foo = function() ... end`):
-    - `local_variable_declaration` where the `expression_list` contains a `function_definition`
-    - Kind `'function'`
-
-    **Module table constants** (top-level `assignment_statement` where RHS is a `table_constructor` and LHS is an uppercase or PascalCase identifier):
-    - Emit kind `'const'` — Lua module tables are the nearest equivalent to constants
-
-    **Skip**: nested function definitions (inside other functions), `do ... end` blocks at non-top-level
-
-  - `extractImports(tree, source)`:
-    - Scan for `assignment_statement` nodes where the RHS is a `call_expression` whose function name is `require`
-    - Specifier: the first argument string to `require` (e.g. `"socket"`, `"mymodule.utils"`)
-    - `resolvedPath`: convert dot-separated module path to file path (`"mymodule.utils"` → `mymodule/utils.lua`); return `null` if path cannot be resolved
-    - `importedNames`: the LHS variable name(s) (what the require result is assigned to)
-    - `isTypeOnly`: `false`
-  - `extractDocstring(node)`:
-    - Walk `previousNamedSibling` chain for consecutive `comment` nodes (`--` prefix)
-    - Also handle block comments (`--[[ ... ]]`) immediately preceding a declaration
-    - Strip `-- ` prefix, concatenate, return first paragraph
-
-**Signature building:**
-- Functions: `function name(params)` or `local function name(params)`
-- Methods (dot-index): `function Module.name(params)`
-- Methods (colon-index): `function Module:name(params)`
-- Constants (module tables): `local Module = { ... }` (truncate body)
-- Keep signatures under 120 chars
-
-**Key technical notes:**
-- Lua has no class system — OOP is simulated via metatables and module patterns. The handler only extracts function definitions and module-level constants; metatable wiring is not parsed.
-- The colon syntax `Module:method(params)` desugars to `Module.method(self, params)` — emit with the colon notation preserved in the name for clarity
-- Lua files often begin with `local M = {}` then populate `M` then `return M` — only emit symbols that are clearly exported (accessible via the returned table). In Phase 6, emit all top-level and module-level function assignments without trying to determine if they are in the returned table.
-- `pcall`, `require`, `ipairs`, `pairs` are standard library calls — they will not match function definition patterns and should not be extracted
-
-**Verify:** Index `test/fixtures/lua-project/`. Verify `function foo()` is kind `'function'`, `function M.bar()` is kind `'method'` with name `M.bar`, `function M:baz()` is kind `'method'` with name `M:baz`, `local function helper()` is kind `'function'`.
-
-**Tests:** `function foo()`, `local function helper()`, `M.bar = function()`, `function M:baz()`, `local M = {}` table constant, `require("socket")` import, `--` comment docstring.
-
----
-
-## Task 64: Dart Language Handler
-
-Add Dart as the language handler required by the Flutter adapter. Dart's community grammar is actively maintained and used by several editor plugins.
-
-**Deliverables:**
-- Download and bundle `grammars/tree-sitter-dart.wasm`
-  - Source: `tree-sitter-dart` npm package (UserNobody14/tree-sitter-dart)
-  - Build: `npx tree-sitter build-wasm node_modules/tree-sitter-dart`
-- `src/handlers/dart.ts` — implements `LanguageHandler`
-  - `extensions()`: `['.dart']`
-  - `grammarPath()`: path to `tree-sitter-dart.wasm`
-  - `extractSymbols(tree, source)`:
-    - `class_definition` → kind `'class'`
-    - `mixin_declaration` → kind `'class'` with `frameworkMeta.dart_mixin: true`
-    - `extension_declaration` → kind `'class'` with `frameworkMeta.dart_extension: true`; name = `Extension:ExtendedType` if named, `<anonymous extension>` if not
-    - `enum_declaration` → kind `'enum'`
-    - `type_alias` (`typedef`) → kind `'type'`
-    - Top-level `function_signature` followed by `function_body` → kind `'function'`
-    - Top-level `getter_signature` / `setter_signature` → kind `'function'` (getters/setters at top level are function-like)
-    - `method_signature` inside `class_body` → kind `'method'`, name = `ClassName.methodName`
-    - `constructor_signature` → kind `'method'`, name = `ClassName.ClassName` (or `ClassName.namedConstructor`)
-    - Top-level `initialized_variable_definition` with `const` or `final` keyword → kind `'const'`
-    - Visibility: Dart uses `_` prefix for private names — skip symbols whose name starts with `_`
-  - `extractImports(tree, source)`:
-    - `import_or_export` nodes containing `import_specification`
-    - `specifier`: the URI string (e.g. `'dart:core'`, `'package:http/http.dart'`, `'../utils.dart'`)
-    - `importedNames`: symbols from `show` clause if present; `[]` otherwise
-    - `resolvedPath`: for `'../relative/path.dart'` style — resolve relative to file; for `'package:...'` and `'dart:...'` — `null`
-    - `isTypeOnly`: `false` (Dart has no type-only imports)
-  - `extractDocstring(node)`:
-    - Dart doc comments use `///` (triple-slash) lines or `/** */` block comments
-    - Walk `previousNamedSibling` for `documentation_comment` or `comment` nodes
-    - Strip `/// ` prefix, concatenate, return first paragraph
-
-**Signature building:**
-- Classes: `class Name [extends Base] [implements Interface, ...] [with Mixin, ...]`
-- Mixins: `mixin Name [on ConstraintType]`
-- Functions: `[async] returnType name(params)`
-- Methods: `[static] [async] returnType name(params)` (including class context in name)
-- Constructors: `ClassName([params])` or `ClassName.namedConstructor([params])`
-- Constants: `const Type name = value`
-- Enums: `enum Name { value1, value2, ... }` (show first 3 values)
-- Keep signatures under 120 chars
-
-**Key technical notes:**
-- Dart's `async`, `async*`, `sync*` function modifiers appear in the function signature — include them
-- Named constructors (`User.fromJson(...)`) have a `.constructorName` suffix in the node — emit as `ClassName.constructorName`
-- `factory` constructors are `constructor_signature` nodes with a `factory` modifier — extract normally
-- Class body includes `operator` method declarations — emit as `'method'` with name `ClassName.operator==` etc.
-- Dart null safety annotations (`?`, `!`, `required`) appear in type annotations — preserve in signatures
-
-**Verify:** Index `test/fixtures/dart-project/`. Verify class, mixin, enum, top-level function, and class method extraction. Verify private `_names` are skipped. Verify `///` doc comments are captured.
-
-**Tests:** `class`, `mixin`, `extension`, `enum`, top-level function, class method, named constructor, `typedef`, `const` top-level, `import` with `show` clause, `_private` name (skipped), `///` doc comment.
-
----
-
-## Task 65: Flutter Adapter
-
-Extract Flutter widget symbols from Dart projects. Flutter's defining pattern is classes extending `StatelessWidget` or `StatefulWidget` — the adapter reclassifies these from `'class'` to `'widget'`.
-
-**Deliverables:**
-- `src/adapters/flutter.ts` — implements `FrameworkAdapter`
-  - `name`: `'flutter'`
-  - `extensions()`: `[]` — `.dart` files are handled by the Dart handler
-  - `detect(projectRoot)`:
-    - Read `pubspec.yaml` — check for `sdk: flutter` under the `flutter:` key, or `flutter` in `dependencies`
-    - As a fallback: check if `pubspec.yaml` exists and contains the string `flutter` anywhere (broad but reliable for Flutter projects)
-  - `fileFilter(filePath)`: `.dart` files only
-  - `extractFrameworkSymbols(tree, source, filePath)`:
-    - Scan for `class_definition` nodes whose superclass chain includes `StatelessWidget`, `StatefulWidget`, `State`, `InheritedWidget`, or `RenderObject`
-      - Detection: check the `extends_clause` child of `class_definition` for these type names
-      - Emit kind `'widget'`
-      - `frameworkMeta.flutter_widget_type`: `'stateless'` | `'stateful'` | `'state'` | `'inherited'` | `'render'`
-      - `frameworkMeta.flutter_widget: true`
-    - For `StatefulWidget` subclasses: also scan for the associated `State<T>` class and link them via `frameworkMeta.state_class` (name of the State class)
-    - Scan for `@immutable` annotated classes (common Flutter pattern for data classes) → emit kind `'class'` with `frameworkMeta.flutter_immutable: true`
-    - Scan for `ChangeNotifier` / `Listenable` subclasses → emit kind `'class'` with `frameworkMeta.flutter_notifier: true`
-  - `enrichMetadata(symbol)`:
-    - For kind `'class'` symbols in Flutter files: if the class name ends in `Widget` and the Dart handler didn't find an `extends` clause (e.g. due to truncation) → leave as `'class'`, do not guess
-    - Do not downgrade `'widget'` symbols set by `extractFrameworkSymbols`
-  - Register via `registerAdapter(flutterAdapter)` at module level
-
-**Key technical notes:**
-- `StatefulWidget` and its `State<T>` subclass are always declared in the same file — the adapter can link them by scanning the file for both
-- Flutter's provider pattern (`ChangeNotifier`, `ValueNotifier`) is widely used for state management — the `frameworkMeta.flutter_notifier` flag helps agents distinguish state from UI
-- Flutter test files (`*_test.dart`) contain `testWidgets(...)` calls — the adapter should not emit route or widget symbols from test files (apply path filter `!filePath.endsWith('_test.dart')`)
-- `BuildContext` parameter in `build()` method is a Flutter-specific type — its presence in method signatures is a strong signal but the class inheritance check is more reliable
-
-**Verify:** Index `test/fixtures/flutter-project/`. Verify `class MyWidget extends StatelessWidget` produces kind `'widget'` with `flutter_widget_type: 'stateless'`. Verify `class MyWidgetState extends State<MyWidget>` produces kind `'widget'` with `flutter_widget_type: 'state'`. Verify a plain Dart class does not produce kind `'widget'`.
-
-**Tests:** `StatelessWidget` subclass, `StatefulWidget` + linked `State` class, `InheritedWidget`, `ChangeNotifier` subclass, plain class (stays `'class'`), test file widget (not extracted as widget).
-
----
-
-## Task 66: Phase 6 Test Fixtures and Integration Tests
-
-Validate the full Phase 6 pipeline end-to-end across all new handlers and adapters.
-
-**Deliverables:**
-
-- `test/fixtures/cpp-project/` — representative C++ project:
-  - `include/auth.hpp` — namespace `Auth`, class `AuthService` with public/private methods, template class
-  - `src/auth.cpp` — `Auth::AuthService` method implementations
-  - `include/models.hpp` — nested namespace `App::Models`, structs, enums
-  - `src/utils.cpp` — free functions in namespace, `#define` macros, `using` type aliases
-  - `CMakeLists.txt` (presence marker, not parsed)
-
-- `test/fixtures/lua-project/` — representative Lua project:
-  - `src/auth.lua` — `local M = {}`, `M.login = function()`, `M:logout()`, module return
-  - `src/utils.lua` — top-level `function format(...)`, `local function helper()`, `require` calls
-  - `src/config.lua` — top-level constant table
-
-- `test/fixtures/dart-project/` — representative Dart project:
-  - `lib/src/auth_service.dart` — class with methods, named constructor, `///` doc comments
-  - `lib/src/models/user.dart` — class with `const` constructor, `final` fields
-  - `lib/src/utils.dart` — top-level functions, `typedef`
-  - `test/auth_service_test.dart` — test file (lower priority)
-
-- `test/fixtures/flutter-project/` — minimal Flutter application:
-  - `pubspec.yaml` with `sdk: flutter`
-  - `lib/widgets/my_button.dart` — `class MyButton extends StatelessWidget` with `build()`
-  - `lib/screens/home_screen.dart` — `class HomeScreen extends StatefulWidget` + `class _HomeScreenState extends State<HomeScreen>`
-  - `lib/providers/auth_provider.dart` — `class AuthProvider extends ChangeNotifier`
-  - `lib/models/user.dart` — plain Dart class (not a widget)
-
-- Integration tests `test/integration/phase6.test.ts`:
-  1. C++: `namespace Auth { class AuthService { ... } }` → symbol name is `Auth::AuthService`
-  2. C++: nested namespace → `App::Models::User`
-  3. C++: `template<T> class Cache` → kind `'class'` with template prefix in signature
-  4. C++: private method → not extracted; public method → extracted
-  5. C++: `struct Point` → kind `'struct'` (not `'class'`)
-  6. C++: `namespace Auth` declaration → kind `'namespace'`
-  7. Lua: `function M.login()` → kind `'method'` with name `M.login`
-  8. Lua: `function M:logout()` → kind `'method'` with name `M:logout`
-  9. Lua: top-level `function format()` → kind `'function'`
-  10. Dart: class with public methods → extracted; `_private` method → skipped
-  11. Dart: named constructor → kind `'method'` with name `ClassName.namedConstructor`
-  12. Dart: `///` doc comment captured
-  13. Flutter: `StatelessWidget` subclass → kind `'widget'` with `flutter_widget_type: 'stateless'`
-  14. Flutter: `StatefulWidget` + linked `State` class → both emitted as `'widget'`
-  15. Flutter: `ChangeNotifier` subclass → kind `'class'` with `flutter_notifier: true`
-  16. Flutter: plain Dart class → kind `'class'`, not `'widget'`
-  17. `search-symbols` with `kind: 'widget'` returns only Flutter widgets
-  18. `search-symbols` with `kind: 'namespace'` returns only C++ namespaces
-  19. Full suite regression: all Phase 1–5 tests still green
-
-- **Performance benchmark** `test/benchmarks/phase6.bench.ts`:
-  - Index each language fixture, record time and symbol count
-  - C++ fixture specifically: verify namespace-qualified name generation does not degrade indexing performance vs. C fixture
-
-**Verify:** `npm run test` passes entirely — all Phase 1–6 tests green. No regressions.
-
----
-
-## Order of Execution
-
-```
-Task 61: Extend SymbolKind                 ██░░░░░░░░ Foundation
-Task 62: C++ language handler              ████░░░░░░ C++
-Task 63: Lua language handler              ██████░░░░ Lua
-Task 64: Dart language handler             ████████░░ Dart
-Task 65: Flutter adapter                   █████████░ Dart/Flutter
-Task 66: Fixtures + integration tests      ██████████ Polish
-```
-
-Task 61 must come first. Task 62 (C++) is independent of Tasks 63–65 (Lua/Dart/Flutter). Task 65 (Flutter) depends on Task 64 (Dart handler). Otherwise Tasks 62, 63, and 64 can be developed in parallel.
-
-**After Phase 6 is complete**, move to Phase 7: Swift language handler and Vapor server-side Swift adapter.

package/docs/dev/PHASE7_TASKS.md

@@ -1,257 +0,0 @@
-# Phase 7 — Task Breakdown
-
-**Goal**: Add Swift as the final language handler and deliver the Vapor server-side Swift framework adapter. This phase closes the language expansion roadmap started in Phase 5, bringing PureContext to full language parity with jCodeMunch across all targeted languages.
-
-**Scope rationale**: Phase 6 completed C++, Lua, Dart, and Flutter. Swift is the last language in the expansion plan and the most complex grammar of the entire set. It was deliberately deferred to a standalone phase because (1) the Swift tree-sitter grammar is large and the most complex of all targeted languages (actors, result builders, property wrappers, async/await, opaque types), (2) Vapor's server-side Swift market is smaller than other targets, so the ROI is lower and rushing the implementation risks quality, and (3) by Phase 7 the grammar-loading and WASM pipeline is battle-tested, making the infrastructure risk minimal. The integration test task in Phase 7 is expanded to include a full benchmark comparison against jCodeMunch across all shared languages.
-
-**Approach**: Tasks are sequenced linearly: Swift handler → Vapor adapter → integration tests and competitive benchmark. Each task must be complete before the next begins.
-
----
-
-## Task 67: Swift Language Handler
-
-Add Swift as the final new language handler. Swift's grammar is the most complex in the entire PureContext handler set, requiring careful handling of access control, extensions, actors, and optional chaining in type signatures.
-
-**Deliverables:**
-- Download and bundle `grammars/tree-sitter-swift.wasm`
-  - Source: `tree-sitter-swift` npm package (alex-pinkus/tree-sitter-swift, community-maintained and widely adopted)
-  - Build: `npx tree-sitter build-wasm node_modules/tree-sitter-swift`
-  - Note: the Swift WASM file is significantly larger than other grammars (~3–5 MB vs. ~0.5–1 MB). Verify the grammar loads and parses correctly before proceeding to handler implementation.
-- `src/handlers/swift.ts` — implements `LanguageHandler`
-  - `extensions()`: `['.swift']`
-  - `grammarPath()`: path to `tree-sitter-swift.wasm`
-  - `extractSymbols(tree, source)`:
-    - Use a recursive `walkNode(node, context: { typeName: string | null, accessLevel: string | null })` helper
-    - **Access control filter**: only extract symbols with `public`, `open`, or no explicit modifier (Swift's default is `internal`, which is package-visible and useful for navigation). Skip `private` and `fileprivate` symbols.
-    - Extract `visibility_modifier` from the `modifiers` sequence preceding declarations.
-
-    **Top-level declarations:**
-    - `function_declaration` → kind `'function'`
-    - `class_declaration` → kind `'class'`
-    - `struct_declaration` → kind `'class'` (Swift structs are value-type equivalents of classes)
-    - `enum_declaration` → kind `'enum'`
-    - `protocol_declaration` → kind `'interface'`
-    - `actor_declaration` (Swift 5.5+) → kind `'class'` with `frameworkMeta.swift_actor: true`
-    - `extension_declaration` → kind `'class'` with `frameworkMeta.swift_extension: true`; name derived from extended type (e.g. `String+MyExtensions` or just the extended type name)
-    - `typealias_declaration` → kind `'type'`
-    - `let_declaration` / `var_declaration` at top level with `let` and uppercase or PascalCase name → kind `'const'`
-
-    **Type body declarations** (inside `class`, `struct`, `actor`, `extension`, `enum` body):
-    - `function_declaration` → kind `'method'`, name = `TypeName.methodName`
-    - `init_declaration` → kind `'method'`, name = `TypeName.init`; failable init (`init?`) → name = `TypeName.init?`
-    - `deinit_declaration` → kind `'method'`, name = `TypeName.deinit`
-    - `subscript_declaration` → kind `'method'`, name = `TypeName.subscript`
-    - `computed_property` (`var name: Type { get { ... } }`) → kind `'const'` (properties as named access points)
-    - Nested type declarations → recurse with updated `typeName` context
-
-    **Protocol body declarations**:
-    - `protocol_function_declaration` (requirement stubs) → kind `'method'`
-    - `protocol_property_declaration` → kind `'const'`
-
-  - `extractImports(tree, source)`:
-    - `import_declaration` nodes → specifier = module name (e.g. `Foundation`, `UIKit`, `Vapor`)
-    - `resolvedPath`: `null` for all (Swift Package Manager handles resolution)
-    - `importedNames`: `[]` (Swift `import` brings the whole module into scope)
-    - `isTypeOnly`: `false`
-  - `extractDocstring(node)`:
-    - Swift uses `///` triple-slash doc comments (DocC format)
-    - Walk `previousNamedSibling` for consecutive `comment` nodes with `///` prefix
-    - Also handle `/** */` block comments
-    - Strip `/// ` prefix and DocC markup (e.g. `- Parameter x:` → include in docstring, strip formatting)
-    - Return first paragraph (up to first blank line or 200 chars)
-- Update `src/handlers/handler-registry.ts` — add entry for Swift extensions
-- Update `src/index.ts` — register Swift handler in bootstrap
-
-**Signature building:**
-- Functions: `[public/open] [static/class] func name(params) [async] [throws] -> ReturnType`
-- Classes: `[public] class Name[: SuperClass[, Protocol, ...]]`
-- Structs: `[public] struct Name[: Protocol, ...]`
-- Protocols: `[public] protocol Name[: BaseProtocol]`
-- Actors: `[public] actor Name`
-- Extensions: `extension TypeName[: Protocol]`
-- Methods: same as functions but omitting `func` keyword in method context
-- Init: `init([params]) [throws]` or `init?([params])`
-- Type aliases: `typealias Name = Type`
-- Constants: `let Name: Type = value` or `var Name: Type { get }`
-- Include `async` and `throws` in signatures where present
-- Keep signatures under 120 chars; truncate parameter lists with `...` if needed
-
-**Key technical notes:**
-- **Property wrappers** (`@State`, `@Binding`, `@Published`, `@AppStorage`, etc.) appear as `attribute` nodes inside the `modifiers` list — include the first attribute in the signature but do not emit them as separate symbols
-- **Result builders** (`@ViewBuilder`, `@ResultBuilder`): function bodies with result builder syntax look like normal function bodies in the AST — no special handling needed
-- **`some` and `any` opaque types** in return positions — preserve in signature as text
-- **`async` functions** (`async throws`): `async_modifier` and `throws_modifier` appear in `function_modifiers` — include both in signature
-- **Extension named types**: `extension String { ... }` — emit as kind `'class'` with name `String` and `frameworkMeta.swift_extension: true`. When the extension has a protocol conformance (`extension String: Encodable { ... }`), include `": Encodable"` in the signature.
-- **Generic constraints** (`where T: Equatable`): very common in Swift — truncate after `where` clause if the signature exceeds 120 chars
-- **`@objc` and `@objcMembers`**: include in signature as annotation prefix, do not affect extraction logic
-
-**Verify:** Index `test/fixtures/swift-project/`. Verify class, struct, protocol, actor, extension, and top-level function extraction. Verify `private` and `fileprivate` symbols are skipped. Verify `///` doc comments are captured. Verify `extension String` produces a symbol named `String` with extension metadata.
-
-**Tests:** `public class`, `struct`, `protocol`, `actor`, `extension` (named type), `extension` with protocol conformance, top-level `func`, class method, `init` and `init?`, `deinit`, `typealias`, `import`, `///` doc comment, `private func` (skipped), `fileprivate class` (skipped), `@State` property (attribute in signature), `async throws` function.
-
----
-
-## Task 68: Vapor Adapter
-
-Extract route and middleware symbols from Vapor server-side Swift applications. Vapor's routing API uses a method-call DSL on a `RoutesBuilder`.
-
-**Deliverables:**
-- `src/adapters/vapor.ts` — implements `FrameworkAdapter`
-  - `name`: `'vapor'`
-  - `extensions()`: `[]` — `.swift` files handled by the Swift handler
-  - `detect(projectRoot)`:
-    - Read `Package.swift` — check for `.package(url:` containing `vapor/vapor` (case-insensitive)
-    - Regex: `/\.package\s*\(.*["']https:\/\/github\.com\/vapor\/vapor/i`
-  - `fileFilter(filePath)`: `.swift` files only
-  - `extractFrameworkSymbols(tree, source, filePath)`:
-    - Scan for `call_expression` nodes matching Vapor's routing API:
-      - `app.get(...)`, `app.post(...)`, `app.put(...)`, `app.delete(...)`, `app.patch(...)`, `app.webSocket(...)` → kind `'route'`
-      - `routes.get(...)`, `router.get(...)`, etc. — same pattern with alternate variable names
-    - For each matched call:
-      - Extract the path components from the arguments (Vapor uses variadic path components: `app.get("users", ":id", use: handler)`)
-      - Join path components with `/` to form the route path string (e.g. `"users", ":id"` → `/users/:id`)
-      - Skip path components that are not string literals (e.g. `PathComponent.catchall`)
-      - Emit kind `'route'`
-      - `frameworkMeta.http_method`: uppercase method name
-      - `frameworkMeta.route_path`: constructed path string
-      - `frameworkMeta.vapor_route: true`
-    - Scan for classes or structs conforming to `RouteCollection` → emit kind `'class'` with `frameworkMeta.vapor_route_collection: true`
-    - Scan for `app.middleware.use(...)` calls → emit kind `'middleware'` with `frameworkMeta.vapor_middleware: true`
-  - `enrichMetadata(symbol)`: no-op
-  - Register via `registerAdapter(vaporAdapter)` at module level
-
-**Key technical notes:**
-- Vapor path components use string literals for static segments and `:paramName` for dynamic segments — both appear as string arguments to the route method
-- Vapor's `PathComponent` enum (`.parameter("id")`, `.catchall`) is the typed equivalent — out of scope for Phase 7; skip non-string-literal path components
-- `RouteCollection` protocol: classes/structs conforming to it define routes in a `boot(routes:)` method — the adapter emits the `RouteCollection` conformance as metadata but does not parse the `boot` method body (that would require data-flow analysis)
-- Vapor middleware: `app.middleware.use(CORSMiddleware())` — extract the middleware type name as the symbol name
-
-**Verify:** Index `test/fixtures/vapor-project/`. Verify `app.get("users", ":id", use: handler)` produces a route with path `/users/:id`. Verify `app.post("users", use: create)` produces a POST route. Verify `RouteCollection` conforming struct produces class symbol with metadata.
-
-**Tests:** `app.get` single segment, `app.post` multi-segment path, dynamic path component (`:id`), `app.webSocket`, `RouteCollection` conformance, `app.middleware.use`, non-route call (not extracted).
-
----
-
-## Task 69: Phase 7 Test Fixtures, Integration Tests, and Competitive Benchmark
-
-Validate Phase 7 end-to-end and deliver a formal competitive benchmark comparing PureContext against jCodeMunch across all shared languages.
-
-**Deliverables:**
-
-- `test/fixtures/swift-project/` — representative Swift project:
-  - `Sources/Auth/AuthService.swift` — `public class AuthService`, methods, `///` doc comments
-  - `Sources/Models/User.swift` — `public struct User`, protocol conformances
-  - `Sources/Models/Role.swift` — `public enum Role`
-  - `Sources/Protocols/Authenticatable.swift` — `public protocol Authenticatable`
-  - `Sources/Extensions/String+Validation.swift` — `extension String` with methods
-  - `Sources/Actors/TokenStore.swift` — `public actor TokenStore`
-  - `Package.swift` — minimal package manifest (no Vapor dependency — that is in the Vapor fixture)
-
-- `test/fixtures/vapor-project/` — minimal Vapor application:
-  - `Package.swift` — with `vapor/vapor` dependency
-  - `Sources/App/routes.swift` — `app.get`, `app.post`, route group
-  - `Sources/App/Controllers/UserController.swift` — `struct UserController: RouteCollection`
-  - `Sources/App/Middleware/AuthMiddleware.swift` — `app.middleware.use`
-
-- Integration tests `test/integration/phase7.test.ts`:
-  1. Swift: `public class AuthService` extracted, `private func helper()` skipped
-  2. Swift: `public struct User: Encodable` → kind `'class'` with struct in signature
-  3. Swift: `public protocol Authenticatable` → kind `'interface'`
-  4. Swift: `public actor TokenStore` → kind `'class'` with `swift_actor: true`
-  5. Swift: `extension String` → kind `'class'` with `swift_extension: true`
-  6. Swift: `///` triple-slash doc comment captured
-  7. Swift: `async throws` included in function signature
-  8. Vapor: `app.get("users", ":id", use: handler)` → route with path `/users/:id`
-  9. Vapor: `app.post("users", use: create)` → route with http_method `POST`
-  10. Vapor: `RouteCollection` conformance → class with `vapor_route_collection: true`
-  11. Full suite regression: all Phase 1–6 tests still green
-
-- **Competitive benchmark** `test/benchmarks/competitive.bench.ts`:
-
-  This benchmark measures PureContext token efficiency against jCodeMunch using the same corpus defined in `reference/jcodemunch-mcp/benchmarks/tasks.json`.
-
-  **Benchmark methodology** (identical to jCodeMunch's published approach):
-  - Baseline: concatenate all indexed source files for each repo, count tokens using `tiktoken cl100k_base` encoding
-  - PureContext workflow per query: `search-symbols` (max 5 results) + `get-symbol-source` for top 3 hits
-  - Token counting: sum all tool response JSON bytes / 4 (cl100k_base approximation)
-  - Reduction formula: `(1 - purecontext_tokens / baseline_tokens) * 100`
-
-  **Repos** (from `tasks.json`):
-  - `expressjs/express` — JavaScript/TypeScript (both tools index this fully)
-  - `nestjs/nest` — TypeScript with NestJS (PureContext has advantage via NestJS adapter)
-  - `gin-gonic/gin` — Go (both tools index this; add Gin adapter routes)
-  - `fastapi/fastapi` — Python (both tools index this; add FastAPI adapter routes)
-  - `rails/rails` — Ruby (Phase 5 added Ruby handler and Rails adapter)
-
-  **Queries** (from `tasks.json`, applied to all repos):
-  1. `router route handler`
-  2. `middleware`
-  3. `error exception`
-  4. `request response`
-  5. `context bind`
-
-  **Output format** (matches jCodeMunch's `results.md` table format for easy side-by-side comparison):
-  ```
-  | Repo              | Files | Baseline tokens | PureContext tokens | Reduction |
-  |-------------------|------:|----------------:|----------------:|----------:|
-  | expressjs/express |    34 |          73,838 |           3,124 |    **95.8%** |
-  | ...               |       |                 |                 |           |
-  | Grand total       |     — |       1,865,210 |               — |        —% |
-  ```
-
-  **Run command:**
-  ```bash
-  npm run benchmark:competitive
-  ```
-
-  **Notes:**
-  - The benchmark requires the `index-repo` tool (Task 40) to clone and index the test repos
-  - Results are written to `benchmarks/results.md`
-  - jCodeMunch's canonical results are in `reference/jcodemunch-mcp/benchmarks/results.md` for direct comparison
-  - The benchmark is run once on demand, not as part of `npm run test` (it requires network access and disk space)
-
-**Verify:** All Phase 7 tests pass. Benchmark produces a results table with token reduction percentages for each repo/query combination. `npm run test` green (1000+ tests, no regressions).
-
----
-
-## Order of Execution
-
-```
-Task 67: Swift language handler            ████░░░░░░ Swift
-Task 68: Vapor adapter                     ████████░░ Swift/Vapor
-Task 69: Fixtures + integration + bench    ██████████ Polish
-```
-
-Tasks proceed strictly in order: the Swift handler (67) must be complete before the Vapor adapter (68), which must be complete before the integration tests and benchmark (69).
-
----
-
-## Post-Phase 7: What Comes Next
-
-With Phase 7 complete, PureContext will support the following languages and frameworks:
-
-| Language | Handler | Framework Adapters |
-|---|---|---|
-| TypeScript / JavaScript | Phase 1 | Vue, Nuxt, React, Next.js, Angular, NestJS, Express, Fastify |
-| Python | Phase 3 | Flask, FastAPI, Django |
-| Go | Phase 3 | Gin, Echo, Fiber |
-| Rust | Phase 4 | — |
-| Java | Phase 4 | — |
-| C# | Phase 4 | — |
-| PHP | Phase 5 | Laravel, Symfony |
-| Ruby | Phase 5 | Rails, Sinatra |
-| Kotlin | Phase 5 | Ktor, Spring |
-| C | Phase 5 | — |
-| C++ | Phase 6 | — |
-| Lua | Phase 6 | — |
-| Dart | Phase 6 | Flutter |
-| Swift | Phase 7 | Vapor |
-
-**Potential future work after Phase 7:**
-- Approximate nearest-neighbour semantic search (HNSW) for repos with > 50k symbols (Phase 41 item from PRD)
-- Rate limiting and multi-tenant auth for hosted deployments
-- Web UI for exploring the symbol graph visually
-- Additional language handlers: Elixir, Haskell, Scala, R
-- Additional framework adapters: Spring (Java), Hibernate, SQLAlchemy, Django ORM enrichment
-- Rust framework adapters: Axum, Actix-web, Rocket
-- Java framework adapters: Spring Boot (Java), Micronaut, Quarkus