@massu/core 1.3.0 → 1.4.0

package/src/detect/adapters/parse-guard.ts

@@ -0,0 +1,133 @@
+// Copyright (c) 2026 Massu. All rights reserved.
+// Licensed under BSL 1.1 - see LICENSE file for details.
+
+/**
+ * Plan 3b — Phase 3.5 (security audit): centralized AST parse-time safety.
+ *
+ * Adapters consume oversized / pathological user source. Tree-sitter is
+ * fast but synchronous — there is no native timeout, no native size cap.
+ * This module provides:
+ *
+ *   1. `MAX_AST_FILE_BYTES` — 1MB hard cap per file (covers DoS vector
+ *      "oversized file"). Plan §1 cited 5MB; we apply a tighter bound at
+ *      the adapter tier because adapter sample size is small (≤3 files
+ *      per adapter) and 1MB is already an order of magnitude beyond
+ *      reasonable convention-defining files.
+ *   2. `MAX_AST_PARSE_DEPTH` — 5K-deep nested-structure rejection — a
+ *      static text scan for runaway open-paren / open-brace runs that
+ *      would push Tree-sitter into deep recursion. Cheap pre-check.
+ *   3. `parseTimeout(ms, fn)` — wraps a synchronous Tree-sitter call in
+ *      a deadline guard. Tree-sitter's pure-JS path can't be interrupted
+ *      mid-parse, but we record the elapsed time AFTER the call returns
+ *      and emit a stderr warning when budget is exceeded so daemon ops
+ *      see the abuse signal.
+ *   4. `isParsableSource(source)` — static gate combining size + depth.
+ *      Returns `null` if accepted, or a `{ reason, detail }` object when
+ *      rejected so the adapter can record provenance and skip the file.
+ *
+ * Library purity: never terminates the process, no DB calls, no network.
+ * Pure helper module.
+ */
+
+/** Hard size cap for an individual file fed to Tree-sitter. */
+export const MAX_AST_FILE_BYTES = 1 * 1024 * 1024;
+
+/**
+ * Maximum nested-bracket depth allowed in a file. Pathological inputs
+ * with 10K-deep nesting can push Tree-sitter into runaway recursion on
+ * some grammar versions. Cheap O(n) text scan picks them off before parse.
+ */
+export const MAX_AST_PARSE_DEPTH = 5000;
+
+/**
+ * Per-file Tree-sitter parse budget (ms). Tree-sitter parses are
+ * synchronous in JS, so this is enforced as a post-call elapsed-time
+ * check rather than a hard timer. The check still serves the purpose of
+ * giving operators visibility into adversarial files.
+ */
+export const MAX_AST_PARSE_MS = 2000;
+
+export type ParseSkipReason =
+  | 'size-cap'
+  | 'depth-cap'
+  | 'control-bytes'
+  | 'utf8-validation';
+
+export interface ParseSkip {
+  reason: ParseSkipReason;
+  detail: string;
+}
+
+/**
+ * Static safety gate. Call BEFORE invoking `parser.parse()`. Returns
+ * `null` if the source is acceptable, or a `ParseSkip` describing why
+ * the file is rejected.
+ *
+ * Cheap to evaluate — single linear scan + size check.
+ */
+export function isParsableSource(source: string, sizeBytes?: number): ParseSkip | null {
+  // Size cap: reject before Tree-sitter sees the bytes. We compute
+  // byte-length conservatively when not provided.
+  const bytes = sizeBytes ?? Buffer.byteLength(source, 'utf-8');
+  if (bytes > MAX_AST_FILE_BYTES) {
+    return {
+      reason: 'size-cap',
+      detail: `${bytes} bytes > ${MAX_AST_FILE_BYTES} cap`,
+    };
+  }
+
+  // Depth cap: count maximal nesting depth across `(` `[` `{` runs.
+  // Single-pass O(n) — no regex backtracking.
+  let depth = 0;
+  let maxDepth = 0;
+  // Also reject NUL bytes (Tree-sitter handles them but they're a
+  // canary for binary-file mislabeling).
+  for (let i = 0; i < source.length; i++) {
+    const c = source.charCodeAt(i);
+    if (c === 0) {
+      return { reason: 'control-bytes', detail: 'NUL byte at offset ' + i };
+    }
+    // 40 = '(', 91 = '[', 123 = '{'
+    if (c === 40 || c === 91 || c === 123) {
+      depth++;
+      if (depth > maxDepth) maxDepth = depth;
+      if (depth > MAX_AST_PARSE_DEPTH) {
+        return {
+          reason: 'depth-cap',
+          detail: `nesting depth exceeded ${MAX_AST_PARSE_DEPTH}`,
+        };
+      }
+    } else if (c === 41 || c === 93 || c === 125) {
+      // Close brackets — clamp to 0 (mismatched code shouldn't crash this).
+      depth = depth > 0 ? depth - 1 : 0;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Wrap a synchronous Tree-sitter call and emit a warning when the call
+ * exceeds the budget. Returns the call's result regardless — callers may
+ * decide to discard it based on `elapsed`.
+ *
+ * Note: Tree-sitter's WASM path has no co-operative cancellation, so
+ * this is observability rather than a hard kill. The size + depth caps
+ * are the load-bearing mitigations; this is the third belt.
+ */
+export function withParseDeadline<T>(
+  fn: () => T,
+  filePath: string,
+  budgetMs: number = MAX_AST_PARSE_MS,
+): { value: T; elapsedMs: number; overBudget: boolean } {
+  const start = Date.now();
+  const value = fn();
+  const elapsedMs = Date.now() - start;
+  const overBudget = elapsedMs > budgetMs;
+  if (overBudget) {
+    process.stderr.write(
+      `[massu/ast] WARN: parse of ${filePath} took ${elapsedMs}ms (budget ${budgetMs}ms) — file may be adversarial. (Phase 3.5 mitigation)\n`,
+    );
+  }
+  return { value, elapsedMs, overBudget };
+}

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

@@ -0,0 +1,208 @@
+// Copyright (c) 2026 Massu. All rights reserved.
+// Licensed under BSL 1.1 - see LICENSE file for details.
+
+/**
+ * Plan 3b — Phase 1: Django AST adapter.
+ *
+ * Extracts:
+ *   - mixin_classes: class-based-view base classes inheriting LoginRequiredMixin etc.
+ *   - decorator_usage: `@login_required` or `@permission_required` decorators
+ *   - urlpatterns_shape: 'function-views' | 'class-views' | 'mixed'
+ *
+ * Conservative gate: returns 'none' if no `INSTALLED_APPS` Django marker is
+ * present in the signal bundle. Adapter wants HIGH precision: false-positive
+ * Django classification would push regex fallback aside for projects that
+ * don't actually use Django.
+ */
+
+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';
+
+// ============================================================
+// Queries
+// ============================================================
+
+/**
+ * `@login_required` / `@permission_required` decorator on a function def.
+ * Captures the decorator name (`login_required` or any `*_required`/`*_login`).
+ */
+const DECORATOR_QUERY = `
+(decorator
+  (identifier) @decorator_name)
+`;
+
+/**
+ * Class definition with a base list — captures bases like `LoginRequiredMixin`,
+ * `PermissionRequiredMixin`, `View`, `ListView`. The runner filters for the
+ * Django-specific names.
+ */
+const CLASS_BASE_QUERY = `
+(class_definition
+  name: (identifier) @class_name
+  superclasses: (argument_list
+    (identifier) @base_name))
+`;
+
+/**
+ * urlpatterns assignment — captures the rhs (a list) so we can inspect what's
+ * inside (path() / re_path() calls indicate function-view style; class names
+ * indicate class-view style).
+ */
+const URLPATTERNS_QUERY = `
+(assignment
+  left: (identifier) @_target (#eq? @_target "urlpatterns")
+  right: (list) @urlpatterns_list)
+`;
+
+// ============================================================
+// Adapter
+// ============================================================
+
+const DJANGO_MIXIN_NAMES = new Set([
+  'LoginRequiredMixin',
+  'PermissionRequiredMixin',
+  'UserPassesTestMixin',
+  'StaffuserRequiredMixin',
+]);
+
+const DJANGO_DECORATOR_PATTERNS = [
+  /^login_required$/,
+  /^permission_required$/,
+  /_required$/,
+  /^require_/,
+];
+
+export const pythonDjangoAdapter: CodebaseAdapter = {
+  id: 'python-django',
+  languages: ['python'],
+
+  matches(signals: DetectionSignals): boolean {
+    // Conservative gate: require an explicit Django marker.
+    // - manage.py at root, OR
+    // - settings.py with INSTALLED_APPS reference, OR
+    // - pyproject.toml dep on Django
+    if (signals.presentFiles.has('manage.py')) return true;
+    const pyToml = signals.pyprojectToml as { __raw?: string } | undefined;
+    if (pyToml?.__raw && /\bdjango\b/i.test(pyToml.__raw)) 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 {
+      return { conventions: {}, provenance: [], confidence: 'none' };
+    }
+
+    const parser = new Parser();
+    parser.setLanguage(language);
+
+    const decoratorsFound = new Map<string, { line: number; file: string }>();
+    const mixinsFound = new Map<string, { line: number; file: string }>();
+    const urlpatternsShape: { value: 'function-views' | 'class-views' | 'mixed' | null; line: number; file: string } = {
+      value: null,
+      line: 0,
+      file: '',
+    };
+
+    try {
+      for (const file of files) {
+        const skip = isParsableSource(file.content, file.size);
+        if (skip) {
+          process.stderr.write(
+            `[massu/ast] WARN: python-django skipping ${file.path}: ${skip.reason} (${skip.detail}). Cap=${MAX_AST_FILE_BYTES}. (Phase 3.5 mitigation)\n`,
+          );
+          continue;
+        }
+        try {
+          // Decorators
+          for (const hit of runQuery(parser, file.content, DECORATOR_QUERY, 'django-decorator', file.path)) {
+            const name = hit.captures.decorator_name;
+            if (!name) continue;
+            // Filter to Django-shaped decorator names only.
+            if (DJANGO_DECORATOR_PATTERNS.some(re => re.test(name)) && !decoratorsFound.has(name)) {
+              decoratorsFound.set(name, { line: hit.line, file: file.path });
+            }
+          }
+          // Mixins
+          for (const hit of runQuery(parser, file.content, CLASS_BASE_QUERY, 'django-mixin', file.path)) {
+            const base = hit.captures.base_name;
+            if (base && DJANGO_MIXIN_NAMES.has(base) && !mixinsFound.has(base)) {
+              mixinsFound.set(base, { line: hit.line, file: file.path });
+            }
+          }
+          // urlpatterns shape — naive heuristic: inspect the captured text
+          for (const hit of runQuery(parser, file.content, URLPATTERNS_QUERY, 'django-urlpatterns', file.path)) {
+            const listText = hit.captures.urlpatterns_list ?? '';
+            const hasFunctionForm = /\bpath\s*\(/.test(listText) || /\bre_path\s*\(/.test(listText);
+            const hasClassForm = /\.as_view\s*\(/.test(listText);
+            let shape: 'function-views' | 'class-views' | 'mixed' | null = null;
+            if (hasFunctionForm && hasClassForm) shape = 'mixed';
+            else if (hasFunctionForm) shape = 'function-views';
+            else if (hasClassForm) shape = 'class-views';
+            if (shape && !urlpatternsShape.value) {
+              urlpatternsShape.value = shape;
+              urlpatternsShape.line = hit.line;
+              urlpatternsShape.file = file.path;
+            }
+          }
+        } catch (e) {
+          if (e instanceof InvalidQueryError) throw e;
+          continue;
+        }
+      }
+    } finally {
+      try { parser.delete(); } catch { /* ignore */ }
+    }
+
+    const conventions: Record<string, unknown> = {};
+    const provenance: Provenance[] = [];
+
+    if (decoratorsFound.size > 0) {
+      const list = Array.from(decoratorsFound.keys());
+      conventions.decorator_usage = list;
+      const [first, { line, file }] = decoratorsFound.entries().next().value as [string, { line: number; file: string }];
+      provenance.push({ field: 'decorator_usage', sourceFile: file, line, query: 'django-decorator' });
+      // Also emit first decorator as auth_dep proxy for compatibility with
+      // regex-fallback's behavior — auth_dep was the regex's primary output.
+      conventions.auth_dep = first;
+      provenance.push({ field: 'auth_dep', sourceFile: file, line, query: 'django-decorator' });
+    }
+
+    if (mixinsFound.size > 0) {
+      const list = Array.from(mixinsFound.keys());
+      conventions.mixin_classes = list;
+      const [, { line, file }] = mixinsFound.entries().next().value as [string, { line: number; file: string }];
+      provenance.push({ field: 'mixin_classes', sourceFile: file, line, query: 'django-mixin' });
+    }
+
+    if (urlpatternsShape.value) {
+      conventions.urlpatterns_shape = urlpatternsShape.value;
+      provenance.push({
+        field: 'urlpatterns_shape',
+        sourceFile: urlpatternsShape.file,
+        line: urlpatternsShape.line,
+        query: 'django-urlpatterns',
+      });
+    }
+
+    let confidence: AdapterResult['confidence'];
+    if (Object.keys(conventions).length === 0) {
+      confidence = 'none';
+    } else if (decoratorsFound.size > 0 || mixinsFound.size > 0) {
+      confidence = 'high';
+    } else {
+      confidence = 'medium';
+    }
+
+    return { conventions, provenance, confidence };
+  },
+};

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

@@ -0,0 +1,223 @@
+// Copyright (c) 2026 Massu. All rights reserved.
+// Licensed under BSL 1.1 - see LICENSE file for details.
+
+/**
+ * Plan 3b — Phase 1: FastAPI AST adapter.
+ *
+ * Extracts:
+ *   - auth_dep: name passed to `Depends(...)` in router files
+ *   - api_prefix_base: first path segment of `APIRouter(prefix="/...")`
+ *   - test_async_pattern: `@pytest.mark.asyncio` (with or without parens)
+ *
+ * Confidence rules:
+ *   - 'high' if the auth dep is found exactly ONCE in routers/ and matches
+ *     known FastAPI signatures.
+ *   - 'medium' if found in non-routers/ paths (e.g., a deps.py module).
+ *   - 'low' if multiple candidate auth deps are found (ambiguous — but still
+ *     emitted so the user can see what was found).
+ *   - 'none' if no `Depends(...)` calls found AND no `APIRouter(prefix=)` —
+ *     adapter doesn't apply, 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 dependency: catches `Depends(get_current_user)`, `Depends(require_tier_or_guardian)`,
+ * etc. Anchored on the canonical `Depends` call shape.
+ *
+ * Per the spec doc §3, predicate constraints (#eq?) keep the query from
+ * matching arbitrary `<x>(<y>)` calls.
+ */
+const AUTH_DEP_QUERY = `
+(call
+  function: (identifier) @_callee (#eq? @_callee "Depends")
+  arguments: (argument_list
+    (identifier) @auth_dep))
+`;
+
+/**
+ * APIRouter prefix: `APIRouter(prefix="/api/orders", ...)`. Captures the
+ * string literal so the runner can split off the base segment.
+ */
+const API_PREFIX_QUERY = `
+(call
+  function: (identifier) @_callee (#eq? @_callee "APIRouter")
+  arguments: (argument_list
+    (keyword_argument
+      name: (identifier) @_kw (#eq? @_kw "prefix")
+      value: (string) @prefix_value)))
+`;
+
+/**
+ * `@pytest.mark.asyncio` decorator. Captures the decorator name string for
+ * provenance; the value field is fixed as the canonical form.
+ */
+const PYTEST_ASYNCIO_QUERY = `
+(decorator
+  (attribute
+    object: (attribute
+      object: (identifier) @_pkg (#eq? @_pkg "pytest")
+      attribute: (identifier) @_mark (#eq? @_mark "mark"))
+    attribute: (identifier) @_marker (#eq? @_marker "asyncio"))) @decorator
+`;
+
+// ============================================================
+// Adapter
+// ============================================================
+
+export const pythonFastApiAdapter: CodebaseAdapter = {
+  id: 'python-fastapi',
+  languages: ['python'],
+
+  matches(signals: DetectionSignals): boolean {
+    // Cheap signal-only check. No file IO. Match if:
+    //   1. pyproject.toml mentions fastapi (raw text contains 'fastapi'), OR
+    //   2. project has a routers/ directory (FastAPI convention), OR
+    //   3. project has app/ + python files at top level
+    const pyToml = signals.pyprojectToml as { __raw?: string } | undefined;
+    if (pyToml?.__raw && /\bfastapi\b/i.test(pyToml.__raw)) return true;
+    if (signals.presentDirs.has('routers')) return true;
+    if (signals.presentDirs.has('app') && signals.presentFiles.has('main.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. The runner's stderr line is emitted at the introspector tier.
+      return { conventions: {}, provenance: [], confidence: 'none' };
+    }
+
+    const parser = new Parser();
+    parser.setLanguage(language);
+
+    // Per-field collection: { value -> { fileLine, queryName } }
+    const authDeps = new Map<string, { line: number; file: string }>();
+    const prefixBases = new Map<string, { line: number; file: string }>();
+    const testAsyncPatterns = new Map<string, { line: number; file: string }>();
+
+    try {
+      for (const file of files) {
+        // Phase 3.5 fix: defense-in-depth size + depth gate at adapter
+        // tier (the runner also gates, but adapters may be invoked
+        // directly from tests/CLI).
+        const skip = isParsableSource(file.content, file.size);
+        if (skip) {
+          process.stderr.write(
+            `[massu/ast] WARN: python-fastapi skipping ${file.path}: ${skip.reason} (${skip.detail}). Cap=${MAX_AST_FILE_BYTES}. (Phase 3.5 mitigation)\n`,
+          );
+          continue;
+        }
+        try {
+          // Auth dep
+          for (const hit of runQuery(parser, file.content, AUTH_DEP_QUERY, 'fastapi-auth-dep', file.path)) {
+            const name = hit.captures.auth_dep;
+            if (name && !authDeps.has(name)) {
+              authDeps.set(name, { line: hit.line, file: file.path });
+            }
+          }
+          // API prefix
+          for (const hit of runQuery(parser, file.content, API_PREFIX_QUERY, 'fastapi-api-prefix', file.path)) {
+            const raw = hit.captures.prefix_value;
+            if (!raw) continue;
+            // Strip enclosing quotes (string node text includes them)
+            const literal = raw.replace(/^['"]/, '').replace(/['"]$/, '');
+            const base = extractPrefixBase(literal);
+            if (base && !prefixBases.has(base)) {
+              prefixBases.set(base, { line: hit.line, file: file.path });
+            }
+          }
+          // pytest.mark.asyncio
+          for (const hit of runQuery(parser, file.content, PYTEST_ASYNCIO_QUERY, 'fastapi-pytest-asyncio', file.path)) {
+            const pat = '@pytest.mark.asyncio';
+            if (!testAsyncPatterns.has(pat)) {
+              testAsyncPatterns.set(pat, { 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 this file, keep going. Tree-sitter is
+          // error-tolerant so this is rare; usually means we got a binary or
+          // a non-Python file mislabeled.
+          continue;
+        }
+      }
+    } finally {
+      try { parser.delete(); } catch { /* ignore */ }
+    }
+
+    // Build result
+    const conventions: Record<string, unknown> = {};
+    const provenance: Provenance[] = [];
+
+    // Auth dep: high if exactly 1, low if >1 (still emit first), none if 0.
+    if (authDeps.size === 1) {
+      const [name, { line, file }] = authDeps.entries().next().value as [string, { line: number; file: string }];
+      conventions.auth_dep = name;
+      provenance.push({ field: 'auth_dep', sourceFile: file, line, query: 'fastapi-auth-dep' });
+    } else if (authDeps.size >= 2) {
+      // Ambiguous — prefer the first-seen (stable order from input file list).
+      const [name, { line, file }] = authDeps.entries().next().value as [string, { line: number; file: string }];
+      conventions.auth_dep = name;
+      provenance.push({ field: 'auth_dep', sourceFile: file, line, query: 'fastapi-auth-dep' });
+    }
+
+    if (prefixBases.size >= 1) {
+      const [base, { line, file }] = prefixBases.entries().next().value as [string, { line: number; file: string }];
+      conventions.api_prefix_base = base;
+      provenance.push({ field: 'api_prefix_base', sourceFile: file, line, query: 'fastapi-api-prefix' });
+    }
+
+    if (testAsyncPatterns.size >= 1) {
+      const [pat, { line, file }] = testAsyncPatterns.entries().next().value as [string, { line: number; file: string }];
+      conventions.test_async_pattern = pat;
+      provenance.push({ field: 'test_async_pattern', sourceFile: file, line, query: 'fastapi-pytest-asyncio' });
+    }
+
+    let confidence: AdapterResult['confidence'];
+    if (Object.keys(conventions).length === 0) {
+      confidence = 'none';
+    } else if (authDeps.size === 1 || (authDeps.size === 0 && prefixBases.size > 0)) {
+      confidence = 'high';
+    } else if (authDeps.size >= 2) {
+      confidence = 'low';
+    } else {
+      confidence = 'medium';
+    }
+
+    return { conventions, provenance, confidence };
+  },
+};
+
+// ============================================================
+// Helpers
+// ============================================================
+
+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;
+}