@massu/core 1.4.0-soak.0 → 1.5.0

package/src/detect/adapters/go-chi.ts

@@ -0,0 +1,261 @@
+// Copyright (c) 2026 Massu. All rights reserved.
+// Licensed under BSL 1.1 - see LICENSE file for details.
+
+/**
+ * Plan 3c — Phase 7: go-chi AST adapter.
+ *
+ * First Phase 7 framework that introduces a NEW Tree-sitter grammar
+ * (`go`) — added to GRAMMAR_MANIFEST in the preceding Commit 1
+ * (plan-3c-phase7-grammar-infra). End-to-end proof that the grammar
+ * load + parse + query path works for non-Python/JS/Swift languages.
+ *
+ * Establishes the per-framework deliverable pattern (4 artifacts) for
+ * the remaining registry-verified frameworks (rails / aspnet / spring /
+ * phoenix) and the bundled Go adapters (gin / echo / fiber / net-http):
+ *   1. packages/core/templates/go-chi/massu.config.yaml      (variant template)
+ *   2. packages/core/src/detect/adapters/go-chi.ts           (this file — AST adapter)
+ *   3. Adversarial fixtures (inline in the test file via mkdirSync+writeFileSync)
+ *   4. packages/core/src/__tests__/go-chi.test.ts            (golden-output test)
+ *
+ * Extracts:
+ *   - route_method: most-common HTTP method registered via `r.<Method>(...)`
+ *     (one of Get/Post/Put/Delete/Patch/Head/Options/Connect/Trace).
+ *     Useful for scaffold-router templates that need to know which verb
+ *     style the project uses.
+ *   - mount_prefix_base: first path segment of `r.Mount("/api/...", ...)`
+ *     mirroring python-fastapi's APIRouter prefix extraction. The chi
+ *     `Mount` call is the canonical way to attach a sub-router under
+ *     a path prefix (per chi docs: https://go-chi.io/#/pages/routing).
+ *   - middleware_name: first chi middleware registered via
+ *     `r.Use(middleware.<Name>)` (e.g., "Logger", "Recoverer", "RequestID").
+ *     Captured from the canonical chi `middleware.*` package qualifier.
+ *
+ * Confidence rules (mirror python-fastapi/python-flask):
+ *   - 'high' if exactly ONE distinct route_method seen (clear convention).
+ *   - 'medium' if mount_prefix_base or middleware_name found but no route_method.
+ *   - 'low' if multiple distinct route_methods seen (mixed convention).
+ *   - 'none' if no chi signals at all (regex fallback takes over).
+ *
+ * Does NOT use regex on file content — only Tree-sitter S-expression queries
+ * compiled via query-helpers.ts. Regex would be the regex-fallback path.
+ */
+
+import { Parser } from 'web-tree-sitter';
+import type { CodebaseAdapter, AdapterResult, DetectionSignals, Provenance, SourceFile } from './types.ts';
+import { runQuery, InvalidQueryError } from './query-helpers.ts';
+import { loadGrammar } from './tree-sitter-loader.ts';
+import { isParsableSource, MAX_AST_FILE_BYTES } from './parse-guard.ts';
+
+// ============================================================
+// Tree-sitter S-expression queries (Go grammar)
+// ============================================================
+
+/**
+ * HTTP method route registration: matches `r.Get("/path", handler)`,
+ * `r.Post(...)`, etc. Anchored on the chi-canonical method names; we
+ * deliberately do NOT match arbitrary `r.<Anything>(...)` calls because
+ * Go's selector_expression shape is shared by every method call.
+ *
+ * The Tree-sitter Go grammar represents `r.Get(...)` as:
+ *   call_expression {
+ *     function: selector_expression {
+ *       operand: identifier   (e.g. "r")
+ *       field:   field_identifier  (e.g. "Get")
+ *     }
+ *     arguments: argument_list { ... }
+ *   }
+ *
+ * The #match? predicate constrains @method to chi's HTTP verb set.
+ */
+const ROUTE_METHOD_QUERY = `
+(call_expression
+  function: (selector_expression
+    field: (field_identifier) @method (#match? @method "^(Get|Post|Put|Delete|Patch|Head|Options|Connect|Trace)$"))
+  arguments: (argument_list
+    .
+    (interpreted_string_literal) @route_path))
+`;
+
+/**
+ * Subrouter mount: `r.Mount("/api/v1", apiRouter)`. Captures the path
+ * literal so we can split off the base segment, mirroring python-fastapi's
+ * APIRouter prefix extraction.
+ *
+ * Per chi docs (https://go-chi.io/#/pages/routing#mounting):
+ *   "Mount attaches another http.Handler along ./pattern/*"
+ */
+const MOUNT_PREFIX_QUERY = `
+(call_expression
+  function: (selector_expression
+    field: (field_identifier) @_field (#eq? @_field "Mount"))
+  arguments: (argument_list
+    .
+    (interpreted_string_literal) @mount_path))
+`;
+
+/**
+ * chi middleware registration: `r.Use(middleware.Logger)`,
+ * `r.Use(middleware.Recoverer)`, etc. We require the canonical
+ * `middleware.<Name>` qualifier to avoid matching user-defined
+ * middleware (which we couldn't classify by name alone).
+ *
+ * The selector_expression inside the argument captures the package
+ * qualifier (`middleware`) and the function name (`Logger`/etc).
+ */
+const MIDDLEWARE_USE_QUERY = `
+(call_expression
+  function: (selector_expression
+    field: (field_identifier) @_use (#eq? @_use "Use"))
+  arguments: (argument_list
+    .
+    (selector_expression
+      operand: (identifier) @_pkg (#eq? @_pkg "middleware")
+      field: (field_identifier) @middleware_name)))
+`;
+
+// ============================================================
+// Adapter
+// ============================================================
+
+export const goChiAdapter: CodebaseAdapter = {
+  id: 'go-chi',
+  languages: ['go'],
+
+  matches(signals: DetectionSignals): boolean {
+    // Cheap signal-only check. No file IO. Match if:
+    //   1. go.mod text mentions github.com/go-chi/chi (canonical require), OR
+    //   2. project has cmd/ + internal/ AND go.mod is present (Go layout) — but
+    //      only when go.mod ALSO mentions chi (avoids matching every Go project).
+    if (!signals.goMod) return false;
+    if (/github\.com\/go-chi\/chi/i.test(signals.goMod)) return true;
+    return false;
+  },
+
+  async introspect(files: SourceFile[], _rootDir: string): Promise<AdapterResult> {
+    if (files.length === 0) {
+      return { conventions: {}, provenance: [], confidence: 'none' };
+    }
+
+    let language;
+    try {
+      language = await loadGrammar('go');
+    } catch (e) {
+      // Grammar unavailable → adapter returns 'none' so regex fallback takes over.
+      return { conventions: {}, provenance: [], confidence: 'none' };
+    }
+
+    const parser = new Parser();
+    parser.setLanguage(language);
+
+    const routeMethods = new Map<string, { line: number; file: string }>();
+    const mountBases = new Map<string, { line: number; file: string }>();
+    const middlewareNames = new Map<string, { line: number; file: string }>();
+
+    try {
+      for (const file of files) {
+        // Phase 3.5 defense-in-depth size + depth gate at adapter tier.
+        const skip = isParsableSource(file.content, file.size);
+        if (skip) {
+          process.stderr.write(
+            `[massu/ast] WARN: go-chi skipping ${file.path}: ${skip.reason} (${skip.detail}). Cap=${MAX_AST_FILE_BYTES}. (Phase 3.5 mitigation)\n`,
+          );
+          continue;
+        }
+        try {
+          for (const hit of runQuery(parser, file.content, ROUTE_METHOD_QUERY, 'chi-route-method', file.path)) {
+            const method = hit.captures.method;
+            if (method && !routeMethods.has(method)) {
+              routeMethods.set(method, { line: hit.line, file: file.path });
+            }
+          }
+          for (const hit of runQuery(parser, file.content, MOUNT_PREFIX_QUERY, 'chi-mount-prefix', file.path)) {
+            const raw = hit.captures.mount_path;
+            if (!raw) continue;
+            const literal = raw.replace(/^["`]/, '').replace(/["`]$/, '');
+            const base = extractPrefixBase(literal);
+            if (base && !mountBases.has(base)) {
+              mountBases.set(base, { line: hit.line, file: file.path });
+            }
+          }
+          for (const hit of runQuery(parser, file.content, MIDDLEWARE_USE_QUERY, 'chi-middleware-use', file.path)) {
+            const name = hit.captures.middleware_name;
+            if (name && !middlewareNames.has(name)) {
+              middlewareNames.set(name, { line: hit.line, file: file.path });
+            }
+          }
+        } catch (e) {
+          if (e instanceof InvalidQueryError) {
+            // Compile-time failure of OUR query is a developer bug — surface it.
+            throw e;
+          }
+          // Per-file parse error: skip + keep going.
+          continue;
+        }
+      }
+    } finally {
+      try { parser.delete(); } catch { /* ignore */ }
+    }
+
+    const conventions: Record<string, unknown> = {};
+    const provenance: Provenance[] = [];
+
+    if (routeMethods.size === 1) {
+      const [name, { line, file }] = routeMethods.entries().next().value as [string, { line: number; file: string }];
+      conventions.route_method = name;
+      provenance.push({ field: 'route_method', sourceFile: file, line, query: 'chi-route-method' });
+    } else if (routeMethods.size >= 2) {
+      // Mixed convention — emit first-seen for visibility.
+      const [name, { line, file }] = routeMethods.entries().next().value as [string, { line: number; file: string }];
+      conventions.route_method = name;
+      provenance.push({ field: 'route_method', sourceFile: file, line, query: 'chi-route-method' });
+    }
+
+    if (mountBases.size >= 1) {
+      const [base, { line, file }] = mountBases.entries().next().value as [string, { line: number; file: string }];
+      conventions.mount_prefix_base = base;
+      provenance.push({ field: 'mount_prefix_base', sourceFile: file, line, query: 'chi-mount-prefix' });
+    }
+
+    if (middlewareNames.size >= 1) {
+      const [name, { line, file }] = middlewareNames.entries().next().value as [string, { line: number; file: string }];
+      conventions.middleware_name = name;
+      provenance.push({ field: 'middleware_name', sourceFile: file, line, query: 'chi-middleware-use' });
+    }
+
+    let confidence: AdapterResult['confidence'];
+    if (Object.keys(conventions).length === 0) {
+      confidence = 'none';
+    } else if (routeMethods.size === 1) {
+      confidence = 'high';
+    } else if (routeMethods.size >= 2) {
+      confidence = 'low';
+    } else {
+      confidence = 'medium';
+    }
+
+    return { conventions, provenance, confidence };
+  },
+};
+
+// ============================================================
+// Helpers
+// ============================================================
+
+/**
+ * Extract the first path segment of a chi mount path. Mirrors
+ * python-fastapi/python-flask's extractPrefixBase. Returns null if input
+ * doesn't start with `/`.
+ *
+ * NOTE: future refactor opportunity once a third adapter needs identical
+ * logic — extracting a shared helper module. The Phase 7 Flask commit
+ * deliberately copied this from python-fastapi rather than premature
+ * extraction (per its self-attest #3); the same reasoning applies here
+ * until a fourth consumer appears.
+ */
+function extractPrefixBase(prefix: string): string | null {
+  if (!prefix.startsWith('/')) return null;
+  const stripped = prefix.replace(/^\/+/, '');
+  const firstSeg = stripped.split('/')[0];
+  if (!firstSeg) return null;
+  return '/' + firstSeg;
+}

package/src/detect/adapters/index.ts

@@ -0,0 +1,49 @@
+/**
+ * CORE-BUNDLED adapter id source of truth.
+ *
+ * Plan 3c Phase 5 5H + 5I deliverable. The CLI's `adapters list` consumes
+ * this set to know which ids should be classified as CORE-BUNDLED via the
+ * three-class trust model (security/adapter-origin.ts:getAdapterOrigin).
+ *
+ * CR-46 / Rule 0 drift-prevention: a static set is the wrong shape (it
+ * inevitably drifts as Plan 3b/Phase 7 adds adapters). Instead the set
+ * is paired with a drift-guard test
+ * (__tests__/core-bundled-ids-drift.test.ts) that asserts CORE_BUNDLED_IDS
+ * matches the actual filesystem state of `detect/adapters/*.ts` minus the
+ * support modules (types, runner, query-helpers, parse-guard, tree-sitter-
+ * loader, index, discover). A new adapter file added to the directory
+ * without updating this set fails the drift-guard test → cannot merge.
+ *
+ * Plan 3b shipped 4 (next, fastapi, django, swiftui); Phase 7 ships 31
+ * more for 35 total. Each Phase 7 commit MUST update this set in lockstep
+ * with the new adapter file under detect/adapters/.
+ */
+
+export const CORE_BUNDLED_IDS: ReadonlySet<string> = new Set([
+  'aspnet',
+  'go-chi',
+  'nextjs-trpc',
+  'phoenix',
+  'python-django',
+  'python-fastapi',
+  'python-flask',
+  'rails',
+  'spring',
+  'swift-swiftui',
+]);
+
+/**
+ * Filenames in `detect/adapters/` that are NOT first-party adapters but
+ * support modules (the adapter contract types, the runner, helpers).
+ * The drift-guard test uses this list to subtract support files from the
+ * filesystem scan before asserting equality with CORE_BUNDLED_IDS.
+ */
+export const ADAPTER_SUPPORT_FILES: ReadonlySet<string> = new Set([
+  'types.ts',
+  'runner.ts',
+  'query-helpers.ts',
+  'parse-guard.ts',
+  'tree-sitter-loader.ts',
+  'index.ts',
+  'discover.ts',
+]);

package/src/detect/adapters/phoenix.ts

@@ -0,0 +1,277 @@
+// Copyright (c) 2026 Massu. All rights reserved.
+// Licensed under BSL 1.1 - see LICENSE file for details.
+
+/**
+ * Plan 3c — Phase 7: Phoenix AST adapter.
+ *
+ * Fourth Phase 7 framework after go-chi + Flask + Rails. First to consume
+ * the `elixir` Tree-sitter grammar entry from GRAMMAR_MANIFEST (commit
+ * fbb8aa9). Together with the @massu/adapter-phoenix workspace stub from
+ * Stage 2 P1-004 (commit ebf2983), completes the per-framework deliverable
+ * pattern (4 artifacts):
+ *   1. packages/core/templates/phoenix/massu.config.yaml   (variant template)
+ *   2. packages/core/src/detect/adapters/phoenix.ts        (this file — AST adapter)
+ *   3. Adversarial fixtures (inline in the test file via mkdirSync+writeFileSync)
+ *   4. packages/core/src/__tests__/phoenix.test.ts         (golden-output test)
+ *      + adapter-grammar-strict.test.ts entry (structural gate)
+ *
+ * Phoenix routes live in `lib/<app>_web/router.ex` using Elixir DSL macros
+ * (per Phoenix routing guide: https://hexdocs.pm/phoenix/routing.html).
+ * The adapter walks the router DSL invocations directly rather than scanning
+ * controller/live directories, mirroring the rails approach against
+ * routes.rb.
+ *
+ * Extracts:
+ *   - route_method: most-common explicit HTTP verb macro (`get`, `post`,
+ *     `put`, `patch`, `delete`, `head`, `options`) used at the router scope
+ *     level with a string-literal path argument. Mirrors python-fastapi/
+ *     python-flask/go-chi/rails route_method semantics. Excludes the
+ *     Phoenix-specific `live` and `live_session` macros (those are
+ *     LiveView-specific and not interchangeable with HTTP verbs), and
+ *     excludes `resources "/users", UserController` (RESTful sugar — same
+ *     reasoning as rails resources :users).
+ *   - scope_prefix_base: first path segment of the first `scope "/api", …
+ *     do …` block, normalized to a leading-slash path. Mirrors rails
+ *     api_namespace / python-flask blueprint_url_prefix / go-chi
+ *     mount_prefix_base. Per Phoenix routing guide §Scoped routes:
+ *     https://hexdocs.pm/phoenix/routing.html#scoped-routes
+ *   - router_module: full module name from `defmodule MyAppWeb.Router do`,
+ *     restricted to modules ending in `Router` (canonical Phoenix naming).
+ *     Useful for scaffold-router templates that need to know the project's
+ *     Web module convention.
+ *
+ * Confidence rules (mirror rails / go-chi):
+ *   - 'high'   if exactly ONE distinct route_method seen (clear convention).
+ *   - 'low'    if multiple distinct route_methods seen (mixed convention).
+ *   - 'medium' if scope_prefix_base or router_module found but no
+ *              route_method.
+ *   - 'none'   if no Phoenix DSL signals at all (regex fallback takes over).
+ *
+ * Tree-sitter-elixir grammar shape (verified via AST probe 2026-05-07):
+ *   - Macro invocations parse as `(call target: (identifier) (arguments ...))`
+ *     OR `(call (identifier) (arguments ...))` — both forms accepted; we use
+ *     the positional shape (no `target:` field) so queries also match the
+ *     parens-ful invocation `get(...)`.
+ *   - Module names are `(alias)` (full dotted chain as one node).
+ *   - String literals are `(string (quoted_content))`; node.text returns
+ *     the quotes intact.
+ *   - `do … end` blocks are `(do_block ...)` siblings of `(arguments)`.
+ *   - Atoms (`:foo`) are `(atom)` — NOT used in any phoenix query (we
+ *     exclude atom-arg DSL forms by anchoring on `(string)` first arg).
+ *
+ * Does NOT use regex on file content — only Tree-sitter S-expression queries
+ * compiled via query-helpers.ts. Regex would be the regex-fallback path.
+ */
+
+import { Parser } from 'web-tree-sitter';
+import type { CodebaseAdapter, AdapterResult, DetectionSignals, Provenance, SourceFile } from './types.ts';
+import { runQuery, InvalidQueryError } from './query-helpers.ts';
+import { loadGrammar } from './tree-sitter-loader.ts';
+import { isParsableSource, MAX_AST_FILE_BYTES } from './parse-guard.ts';
+
+// ============================================================
+// Tree-sitter S-expression queries (Elixir grammar)
+// ============================================================
+
+/**
+ * HTTP method route registration with a STRING-LITERAL first argument:
+ * `get "/health", HealthController, :show`,
+ * `post "/login", SessionController, :create`.
+ *
+ * Anchored (`.`) on the first argument so we ONLY match string-literal
+ * paths. The `#match?` predicate restricts to canonical HTTP verbs,
+ * excluding Phoenix-specific `live` / `live_session` / `forward` /
+ * `resources` macros (those have different semantics).
+ *
+ * Per Phoenix routing guide §HTTP Methods:
+ * https://hexdocs.pm/phoenix/routing.html#http-methods
+ */
+const ROUTE_METHOD_QUERY = `
+(call
+  (identifier) @method (#match? @method "^(get|post|put|patch|delete|options|head)$")
+  (arguments
+    .
+    (string) @route_path))
+`;
+
+/**
+ * Scope block: `scope "/api", MyAppWeb do … end` or `scope "/admin" do …
+ * end`. Captures the FIRST positional argument as a string. The shape
+ * `scope MyAppWeb do … end` (alias-only, no path) deliberately doesn't
+ * match because the first arg is `(alias)` not `(string)` — verified
+ * negative case in AST probe.
+ *
+ * The presence of a `do_block` is required — `scope "/api", MyAppWeb` (no
+ * do/end) wouldn't be a valid Phoenix router scope anyway, but anchoring
+ * on the do_block makes the query semantically tighter.
+ */
+const SCOPE_PATH_QUERY = `
+(call
+  (identifier) @_method (#eq? @_method "scope")
+  (arguments
+    .
+    (string) @scope_path)
+  (do_block))
+`;
+
+/**
+ * Router module definition: `defmodule MyAppWeb.Router do …`. We restrict
+ * to module names ending in `Router` to avoid capturing every `defmodule`
+ * in the project (Phoenix apps have many modules, only one is THE router).
+ *
+ * The tree-sitter-elixir grammar represents `MyAppWeb.Router` as a single
+ * `(alias)` node — the dotted chain is part of the alias node's text, not
+ * a sub-tree of nested aliases. Verified via AST probe 2026-05-07.
+ */
+const ROUTER_MODULE_QUERY = `
+(call
+  (identifier) @_method (#eq? @_method "defmodule")
+  (arguments
+    .
+    (alias) @module_name (#match? @module_name "Router$"))
+  (do_block))
+`;
+
+// ============================================================
+// Adapter
+// ============================================================
+
+export const phoenixAdapter: CodebaseAdapter = {
+  id: 'phoenix',
+  languages: ['elixir'],
+
+  matches(signals: DetectionSignals): boolean {
+    // Cheap signal-only check. No file IO. The canonical Phoenix
+    // declaration in mix.exs is `{:phoenix, "~> 1.7.10"}` (per Phoenix
+    // install guide: https://hexdocs.pm/phoenix/installation.html). The
+    // negative-lookahead `(?!_)` after `:phoenix\b` rejects
+    // `:phoenix_live_view` (a sibling dep that Phoenix-LiveView-only
+    // projects pull in without Phoenix itself in some Plug-based stacks).
+    if (!signals.mixExs) return false;
+    return /\{\s*:phoenix\b(?!_)/.test(signals.mixExs);
+  },
+
+  async introspect(files: SourceFile[], _rootDir: string): Promise<AdapterResult> {
+    if (files.length === 0) {
+      return { conventions: {}, provenance: [], confidence: 'none' };
+    }
+
+    let language;
+    try {
+      language = await loadGrammar('elixir');
+    } catch (e) {
+      // Grammar unavailable → adapter returns 'none' so regex fallback takes over.
+      return { conventions: {}, provenance: [], confidence: 'none' };
+    }
+
+    const parser = new Parser();
+    parser.setLanguage(language);
+
+    const routeMethods = new Map<string, { line: number; file: string }>();
+    const scopePaths = new Map<string, { line: number; file: string }>();
+    const routerModules = new Map<string, { line: number; file: string }>();
+
+    try {
+      for (const file of files) {
+        // Phase 3.5 defense-in-depth size + depth gate at adapter tier.
+        const skip = isParsableSource(file.content, file.size);
+        if (skip) {
+          process.stderr.write(
+            `[massu/ast] WARN: phoenix skipping ${file.path}: ${skip.reason} (${skip.detail}). Cap=${MAX_AST_FILE_BYTES}. (Phase 3.5 mitigation)\n`,
+          );
+          continue;
+        }
+        try {
+          for (const hit of runQuery(parser, file.content, ROUTE_METHOD_QUERY, 'phoenix-route-method', file.path)) {
+            const method = hit.captures.method;
+            if (method && !routeMethods.has(method)) {
+              routeMethods.set(method, { line: hit.line, file: file.path });
+            }
+          }
+          for (const hit of runQuery(parser, file.content, SCOPE_PATH_QUERY, 'phoenix-scope-path', file.path)) {
+            const raw = hit.captures.scope_path;
+            if (!raw) continue;
+            const literal = raw.replace(/^["']/, '').replace(/["']$/, '');
+            const base = extractPrefixBase(literal);
+            if (base && !scopePaths.has(base)) {
+              scopePaths.set(base, { line: hit.line, file: file.path });
+            }
+          }
+          for (const hit of runQuery(parser, file.content, ROUTER_MODULE_QUERY, 'phoenix-router-module', file.path)) {
+            const name = hit.captures.module_name;
+            if (name && !routerModules.has(name)) {
+              routerModules.set(name, { line: hit.line, file: file.path });
+            }
+          }
+        } catch (e) {
+          if (e instanceof InvalidQueryError) {
+            // Compile-time failure of OUR query is a developer bug — surface it.
+            throw e;
+          }
+          // Per-file parse error: skip + keep going.
+          continue;
+        }
+      }
+    } finally {
+      try { parser.delete(); } catch { /* ignore */ }
+    }
+
+    const conventions: Record<string, unknown> = {};
+    const provenance: Provenance[] = [];
+
+    if (routeMethods.size === 1) {
+      const [name, { line, file }] = routeMethods.entries().next().value as [string, { line: number; file: string }];
+      conventions.route_method = name;
+      provenance.push({ field: 'route_method', sourceFile: file, line, query: 'phoenix-route-method' });
+    } else if (routeMethods.size >= 2) {
+      // Mixed convention — emit first-seen for visibility.
+      const [name, { line, file }] = routeMethods.entries().next().value as [string, { line: number; file: string }];
+      conventions.route_method = name;
+      provenance.push({ field: 'route_method', sourceFile: file, line, query: 'phoenix-route-method' });
+    }
+
+    if (scopePaths.size >= 1) {
+      const [base, { line, file }] = scopePaths.entries().next().value as [string, { line: number; file: string }];
+      conventions.scope_prefix_base = base;
+      provenance.push({ field: 'scope_prefix_base', sourceFile: file, line, query: 'phoenix-scope-path' });
+    }
+
+    if (routerModules.size >= 1) {
+      const [name, { line, file }] = routerModules.entries().next().value as [string, { line: number; file: string }];
+      conventions.router_module = name;
+      provenance.push({ field: 'router_module', sourceFile: file, line, query: 'phoenix-router-module' });
+    }
+
+    let confidence: AdapterResult['confidence'];
+    if (Object.keys(conventions).length === 0) {
+      confidence = 'none';
+    } else if (routeMethods.size === 1) {
+      confidence = 'high';
+    } else if (routeMethods.size >= 2) {
+      confidence = 'low';
+    } else {
+      confidence = 'medium';
+    }
+
+    return { conventions, provenance, confidence };
+  },
+};
+
+// ============================================================
+// Helpers
+// ============================================================
+
+/**
+ * Extract the first path segment of a Phoenix scope path. Mirrors
+ * python-fastapi/python-flask/go-chi/rails prefix-base extractors.
+ * Returns null if input doesn't start with `/`.
+ *
+ * "/api/v1/users" → "/api"; "/" → null (root scope is uninformative).
+ */
+function extractPrefixBase(prefix: string): string | null {
+  if (!prefix.startsWith('/')) return null;
+  const stripped = prefix.replace(/^\/+/, '');
+  const firstSeg = stripped.split('/')[0];
+  if (!firstSeg) return null;
+  return '/' + firstSeg;
+}