@massu/core 1.5.7 → 1.6.0

package/src/detect/adapters/phoenix.ts

@@ -1,277 +1,4 @@
-// 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;
-}
+// Plan 3c Phase 9b P-A-005: re-export shim. Source-of-truth lives at
+// `packages/adapter-phoenix/src/index.ts` (workspace package). This shim
+// preserves the legacy import path used by codebase-introspector + tests.
+export { phoenixAdapter } from '@massu/adapter-phoenix';

package/src/detect/adapters/rails.ts

@@ -1,279 +1,4 @@
-// Copyright (c) 2026 Massu. All rights reserved.
-// Licensed under BSL 1.1 - see LICENSE file for details.
-
-/**
- * Plan 3c — Phase 7: Rails AST adapter.
- *
- * Second Phase 7 framework after go-chi; first to consume the new `ruby`
- * Tree-sitter grammar entry from GRAMMAR_MANIFEST (commit fbb8aa9). Together
- * with the @massu/adapter-rails workspace stub created in Stage 2 P1-004
- * (commit ebf2983), this completes the per-framework deliverable pattern
- * established by Phase 7 commits 1–3:
- *   1. packages/core/templates/rails/massu.config.yaml      (variant template)
- *   2. packages/core/src/detect/adapters/rails.ts           (this file — AST adapter)
- *   3. Adversarial fixtures (inline in the test file via mkdirSync+writeFileSync)
- *   4. packages/core/src/__tests__/rails.test.ts            (golden-output test)
- *
- * Rails uses a DSL-heavy `config/routes.rb` (per Rails routing guide:
- * https://guides.rubyonrails.org/routing.html). The adapter walks the
- * routes.rb DSL invocations directly rather than scanning controller
- * directories, mirroring the go-chi approach against router.go files.
- *
- * Extracts:
- *   - route_method: most-common explicit HTTP verb (`get`, `post`, `put`,
- *     `patch`, `delete`, `head`, `options`) used at TOP LEVEL with a
- *     string-literal path argument. Mirrors python-fastapi/python-flask/
- *     go-chi route_method semantics. Distinct from `resources :users`
- *     RESTful blocks — those imply all seven verbs in one declaration and
- *     should NOT pin the project to one verb. The string-literal anchor
- *     also excludes member/collection block calls like `get :preview`
- *     (where the arg is a symbol, not a string).
- *   - api_namespace: first segment of the first `namespace :foo do …` or
- *     `namespace 'foo' do …` block, normalized to a leading-slash path
- *     (mirrors python-fastapi/flask's blueprint_url_prefix and go-chi's
- *     mount_prefix_base). Per Rails routing guide §3:
- *     https://guides.rubyonrails.org/routing.html#controller-namespaces-and-routing
- *   - root_controller: controller name from `root 'pages#home'` or
- *     `root to: 'pages#home'`. The `Foo#bar` syntax canonically denotes
- *     `FooController#bar`. Useful for scaffold-router/scaffold-page
- *     templates that need to know the project's home route convention.
- *
- * Confidence rules (mirror go-chi):
- *   - 'high'   if exactly ONE distinct route_method seen (clear convention).
- *   - 'low'    if multiple distinct route_methods seen (mixed convention).
- *   - 'medium' if api_namespace or root_controller found but no route_method.
- *   - 'none'   if no Rails DSL 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 (Ruby grammar)
-// ============================================================
-
-/**
- * HTTP method route registration with a STRING-LITERAL first argument:
- * `get '/health', to: 'health#show'`, `post "/login", to: 'sessions#create'`.
- *
- * Anchored (`.`) on the first argument so that we ONLY match string-literal
- * paths — symbol arguments (`get :preview` inside a member block) are
- * deliberately excluded because those are nested action declarations, NOT
- * top-level routes.
- *
- * tree-sitter-ruby (v0.20.1, pinned by tree-sitter-wasms@0.1.13) emits
- * `(call method: (identifier) arguments: (argument_list ...))` for the
- * parens-less DSL form `get '/x', ...` AND for the parens-ful `get('/x', ...)`
- * form. Verified by AST probe (2026-05-07): there is NO separate `method_call`
- * node in this grammar — historical web sources mentioning `method_call`
- * refer to a different/older grammar fork.
- */
-const ROUTE_METHOD_QUERY = `
-(call
-  method: (identifier) @method (#match? @method "^(get|post|put|patch|delete|options|head)$")
-  arguments: (argument_list
-    .
-    (string) @route_path))
-`;
-
-/**
- * Namespace block: `namespace :api do ... end` or `namespace 'api' do ... end`.
- * Captures the first symbol-or-string argument so we can normalize to a
- * leading-slash path.
- *
- * Rails accepts both `namespace :api` (symbol — canonical) and the rarer
- * `namespace 'api'` (string). Both forms produce a `namespace` identifier
- * call; the first arg differs only in node type.
- */
-const NAMESPACE_QUERY = `
-(call
-  method: (identifier) @_method (#eq? @_method "namespace")
-  arguments: (argument_list
-    .
-    [
-      (simple_symbol) @namespace_symbol
-      (string) @namespace_string
-    ]))
-`;
-
-/**
- * Root route: `root 'pages#home'`, `root "pages#home"`, or
- * `root to: 'pages#home'`. We capture the string literal in either the
- * positional or `to:` keyword position; the controller is whatever
- * precedes the `#`.
- *
- * Rails routing guide §2.6:
- * https://guides.rubyonrails.org/routing.html#using-root
- */
-const ROOT_ROUTE_QUERY = `
-(call
-  method: (identifier) @_method (#eq? @_method "root")
-  arguments: (argument_list
-    .
-    (string) @root_target))
-
-(call
-  method: (identifier) @_method (#eq? @_method "root")
-  arguments: (argument_list
-    (pair
-      key: (hash_key_symbol) @_key (#eq? @_key "to")
-      value: (string) @root_target)))
-`;
-
-// ============================================================
-// Adapter
-// ============================================================
-
-export const railsAdapter: CodebaseAdapter = {
-  id: 'rails',
-  languages: ['ruby'],
-
-  matches(signals: DetectionSignals): boolean {
-    // Cheap signal-only check. No file IO. The canonical Rails declaration
-    // is `gem 'rails'` in Gemfile (per Rails install guide:
-    // https://guides.rubyonrails.org/getting_started.html). The strict
-    // `gem ['"]rails['"]` regex deliberately rejects `gem 'rails-api'`,
-    // `gem 'rails_admin'`, etc. — those are Rails-adjacent gems that may
-    // appear in non-Rails Ruby projects.
-    if (!signals.gemfile) return false;
-    return /^\s*gem\s+['"]rails['"]/im.test(signals.gemfile);
-  },
-
-  async introspect(files: SourceFile[], _rootDir: string): Promise<AdapterResult> {
-    if (files.length === 0) {
-      return { conventions: {}, provenance: [], confidence: 'none' };
-    }
-
-    let language;
-    try {
-      language = await loadGrammar('ruby');
-    } 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 namespaces = new Map<string, { line: number; file: string }>();
-    const rootControllers = 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: rails 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, 'rails-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, NAMESPACE_QUERY, 'rails-namespace', file.path)) {
-            const symbolRaw = hit.captures.namespace_symbol;
-            const stringRaw = hit.captures.namespace_string;
-            const name = symbolRaw
-              ? symbolRaw.replace(/^:/, '')
-              : stringRaw
-                ? stringRaw.replace(/^['"]/, '').replace(/['"]$/, '')
-                : null;
-            if (!name) continue;
-            const path = '/' + name;
-            if (!namespaces.has(path)) {
-              namespaces.set(path, { line: hit.line, file: file.path });
-            }
-          }
-          for (const hit of runQuery(parser, file.content, ROOT_ROUTE_QUERY, 'rails-root', file.path)) {
-            const raw = hit.captures.root_target;
-            if (!raw) continue;
-            const literal = raw.replace(/^['"]/, '').replace(/['"]$/, '');
-            const controller = extractRootController(literal);
-            if (controller && !rootControllers.has(controller)) {
-              rootControllers.set(controller, { 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: 'rails-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: 'rails-route-method' });
-    }
-
-    if (namespaces.size >= 1) {
-      const [path, { line, file }] = namespaces.entries().next().value as [string, { line: number; file: string }];
-      conventions.api_namespace = path;
-      provenance.push({ field: 'api_namespace', sourceFile: file, line, query: 'rails-namespace' });
-    }
-
-    if (rootControllers.size >= 1) {
-      const [name, { line, file }] = rootControllers.entries().next().value as [string, { line: number; file: string }];
-      conventions.root_controller = name;
-      provenance.push({ field: 'root_controller', sourceFile: file, line, query: 'rails-root' });
-    }
-
-    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 controller name from a Rails `controller#action` string.
- * `'pages#home'` → `'pages'`; `'admin/dashboard#index'` → `'admin/dashboard'`.
- * Returns null for malformed input (no `#` separator).
- *
- * Per Rails routing guide §2.6: the string before `#` is the controller
- * (with optional namespace prefix), the part after is the action.
- */
-function extractRootController(target: string): string | null {
-  const idx = target.indexOf('#');
-  if (idx <= 0) return null;
-  const controller = target.slice(0, idx).trim();
-  return controller || null;
-}
+// Plan 3c Phase 9b P-A-005: re-export shim. Source-of-truth lives at
+// `packages/adapter-rails/src/index.ts` (workspace package). This shim
+// preserves the legacy import path used by codebase-introspector + tests.
+export { railsAdapter } from '@massu/adapter-rails';