@massu/core 1.4.0 → 1.5.1

package/src/detect/adapters/python-flask.ts

@@ -0,0 +1,235 @@
+// Copyright (c) 2026 Massu. All rights reserved.
+// Licensed under BSL 1.1 - see LICENSE file for details.
+
+/**
+ * Plan 3c — Phase 7: Flask AST adapter.
+ *
+ * First Phase 7 framework after Plan 3b's 4 (FastAPI/Django/tRPC/SwiftUI).
+ * Establishes the per-framework deliverable pattern (4 artifacts) all
+ * remaining Phase 7 frameworks follow:
+ *   1. packages/core/templates/python-flask/massu.config.yaml  (variant template)
+ *   2. packages/core/src/detect/adapters/python-flask.ts        (this file — AST adapter)
+ *   3. Adversarial fixtures (inline in the test file via mkdirSync+writeFileSync,
+ *      following the python-fastapi pattern in ast-adapters-adversarial.test.ts)
+ *   4. packages/core/src/__tests__/python-flask.test.ts          (golden-output snapshot)
+ *
+ * Extracts:
+ *   - auth_decorator: name of the auth-gating decorator (`@login_required`,
+ *     `@auth_required`, or other Flask-Login-style decorator on a view).
+ *   - blueprint_url_prefix: first path segment of `Blueprint(name, __name__,
+ *     url_prefix="/api/...")`, mirroring the python-fastapi APIRouter prefix
+ *     extraction.
+ *   - app_factory: name of the Flask app-factory function (`def create_app():`
+ *     or similar). Useful for scaffold-router templates that need to know
+ *     where to register a new Blueprint.
+ *
+ * Confidence rules (mirror python-fastapi):
+ *   - 'high' if exactly ONE auth_decorator is found (clear single convention).
+ *   - 'medium' if blueprint_url_prefix or app_factory found but no auth decorator.
+ *   - 'low' if multiple distinct auth_decorators are found (ambiguous).
+ *   - 'none' if no Flask 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
+// ============================================================
+
+/**
+ * Auth decorator: matches `@login_required`, `@auth_required`,
+ * `@some_auth_required`, etc. on a view function.
+ *
+ * The Tree-sitter Python grammar represents `@some_name` decorators as
+ * a `decorator` node containing an `identifier` (for bare names) OR an
+ * `attribute` (for `@module.name`). We capture both shapes and filter to
+ * names ending in `_required` since that's the Flask-Login convention
+ * and avoids matching unrelated decorators like `@app.route(...)`.
+ */
+const AUTH_DECORATOR_QUERY = `
+(decorator
+  (identifier) @auth_decorator (#match? @auth_decorator "_required$"))
+`;
+
+/**
+ * Blueprint URL prefix: `Blueprint(name, __name__, url_prefix="/api/orders")`.
+ * Captures the keyword-arg string literal so the runner can split off the
+ * base segment.
+ */
+const BLUEPRINT_URL_PREFIX_QUERY = `
+(call
+  function: (identifier) @_callee (#eq? @_callee "Blueprint")
+  arguments: (argument_list
+    (keyword_argument
+      name: (identifier) @_kw (#eq? @_kw "url_prefix")
+      value: (string) @url_prefix)))
+`;
+
+/**
+ * App factory: `def create_app():` (or any function whose name starts with
+ * `create_` and contains `Flask`). The factory pattern is canonical in Flask
+ * (per Flask docs: https://flask.palletsprojects.com/en/2.3.x/patterns/appfactories/).
+ * We capture the function name + assert its body contains `Flask(`.
+ *
+ * The Tree-sitter Python grammar represents `def name():` as a
+ * `function_definition` node with `name: (identifier)` field.
+ */
+const APP_FACTORY_QUERY = `
+(function_definition
+  name: (identifier) @factory_name (#match? @factory_name "^create_")
+  body: (block
+    (expression_statement
+      (assignment
+        right: (call
+          function: (identifier) @_flask_call (#eq? @_flask_call "Flask"))))))
+`;
+
+// ============================================================
+// Adapter
+// ============================================================
+
+export const pythonFlaskAdapter: CodebaseAdapter = {
+  id: 'python-flask',
+  languages: ['python'],
+
+  matches(signals: DetectionSignals): boolean {
+    // Cheap signal-only check. No file IO. Match if:
+    //   1. pyproject.toml mentions flask (raw text contains 'flask'), OR
+    //   2. project has app/ + python files at top level (Flask convention)
+    const pyToml = signals.pyprojectToml as { __raw?: string } | undefined;
+    if (pyToml?.__raw && /\bflask\b/i.test(pyToml.__raw)) return true;
+    if (signals.presentDirs.has('app') && signals.presentFiles.has('app.py')) return true;
+    if (signals.presentDirs.has('app') && signals.presentFiles.has('wsgi.py')) 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('python');
+    } 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 authDecorators = new Map<string, { line: number; file: string }>();
+    const urlPrefixes = new Map<string, { line: number; file: string }>();
+    const appFactories = 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: python-flask 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, AUTH_DECORATOR_QUERY, 'flask-auth-decorator', file.path)) {
+            const name = hit.captures.auth_decorator;
+            if (name && !authDecorators.has(name)) {
+              authDecorators.set(name, { line: hit.line, file: file.path });
+            }
+          }
+          for (const hit of runQuery(parser, file.content, BLUEPRINT_URL_PREFIX_QUERY, 'flask-blueprint-url-prefix', file.path)) {
+            const raw = hit.captures.url_prefix;
+            if (!raw) continue;
+            const literal = raw.replace(/^['"]/, '').replace(/['"]$/, '');
+            const base = extractPrefixBase(literal);
+            if (base && !urlPrefixes.has(base)) {
+              urlPrefixes.set(base, { line: hit.line, file: file.path });
+            }
+          }
+          for (const hit of runQuery(parser, file.content, APP_FACTORY_QUERY, 'flask-app-factory', file.path)) {
+            const name = hit.captures.factory_name;
+            if (name && !appFactories.has(name)) {
+              appFactories.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 */ }
+    }
+
+    // Build result
+    const conventions: Record<string, unknown> = {};
+    const provenance: Provenance[] = [];
+
+    if (authDecorators.size === 1) {
+      const [name, { line, file }] = authDecorators.entries().next().value as [string, { line: number; file: string }];
+      conventions.auth_decorator = name;
+      provenance.push({ field: 'auth_decorator', sourceFile: file, line, query: 'flask-auth-decorator' });
+    } else if (authDecorators.size >= 2) {
+      // Ambiguous — prefer first-seen (stable order from input file list).
+      const [name, { line, file }] = authDecorators.entries().next().value as [string, { line: number; file: string }];
+      conventions.auth_decorator = name;
+      provenance.push({ field: 'auth_decorator', sourceFile: file, line, query: 'flask-auth-decorator' });
+    }
+
+    if (urlPrefixes.size >= 1) {
+      const [base, { line, file }] = urlPrefixes.entries().next().value as [string, { line: number; file: string }];
+      conventions.blueprint_url_prefix = base;
+      provenance.push({ field: 'blueprint_url_prefix', sourceFile: file, line, query: 'flask-blueprint-url-prefix' });
+    }
+
+    if (appFactories.size >= 1) {
+      const [name, { line, file }] = appFactories.entries().next().value as [string, { line: number; file: string }];
+      conventions.app_factory = name;
+      provenance.push({ field: 'app_factory', sourceFile: file, line, query: 'flask-app-factory' });
+    }
+
+    let confidence: AdapterResult['confidence'];
+    if (Object.keys(conventions).length === 0) {
+      confidence = 'none';
+    } else if (authDecorators.size === 1) {
+      confidence = 'high';
+    } else if (authDecorators.size >= 2) {
+      confidence = 'low';
+    } else {
+      confidence = 'medium';
+    }
+
+    return { conventions, provenance, confidence };
+  },
+};
+
+// ============================================================
+// Helpers
+// ============================================================
+
+/**
+ * Extract the first path segment of a Blueprint url_prefix. Mirrors
+ * python-fastapi's extractPrefixBase. Returns null if input doesn't
+ * start with `/`.
+ */
+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/rails.ts

@@ -0,0 +1,279 @@
+// 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;
+}

package/src/detect/adapters/runner.ts

@@ -216,11 +216,43 @@ export function buildDetectionSignals(rootDir: string): DetectionSignals {
     gemfile: tryReadString(join(rootDir, 'Gemfile')),
     cargoToml: tryReadToml(join(rootDir, 'Cargo.toml')),
     goMod: tryReadString(join(rootDir, 'go.mod')),
+    mixExs: tryReadString(join(rootDir, 'mix.exs')),
+    csproj: tryReadFirstCsproj(rootDir, presentFiles),
+    pomXml: tryReadString(join(rootDir, 'pom.xml')),
+    gradleBuild: tryReadGradleBuild(rootDir, presentFiles),
     presentDirs,
     presentFiles,
   };
 }
 
+/**
+ * Find the first `.csproj` file at the project root (sorted alphabetically
+ * for determinism) and return its raw XML content. Returns undefined if
+ * none exist. Multi-project solutions where the root has no top-level
+ * .csproj (the `.sln` lives at root and projects are in subdirs) get
+ * `csproj=undefined` — adapters then degrade per their own logic.
+ */
+function tryReadFirstCsproj(rootDir: string, presentFiles: Set<string>): string | undefined {
+  const csprojNames = [...presentFiles].filter((f) => f.endsWith('.csproj')).sort();
+  if (csprojNames.length === 0) return undefined;
+  return tryReadString(join(rootDir, csprojNames[0]!));
+}
+
+/**
+ * Read `build.gradle.kts` (Kotlin DSL — modern default per Gradle 7+) if
+ * present; otherwise fall back to `build.gradle` (legacy Groovy DSL).
+ * Returns undefined if neither exists.
+ */
+function tryReadGradleBuild(rootDir: string, presentFiles: Set<string>): string | undefined {
+  if (presentFiles.has('build.gradle.kts')) {
+    return tryReadString(join(rootDir, 'build.gradle.kts'));
+  }
+  if (presentFiles.has('build.gradle')) {
+    return tryReadString(join(rootDir, 'build.gradle'));
+  }
+  return undefined;
+}
+
 function tryReadString(path: string): string | undefined {
   if (!existsSync(path)) return undefined;
   try {