@massu/core 1.3.0 → 1.4.0-soak.0

package/src/detect/adapters/query-helpers.ts

@@ -0,0 +1,170 @@
+// Copyright (c) 2026 Massu. All rights reserved.
+// Licensed under BSL 1.1 - see LICENSE file for details.
+
+/**
+ * Plan 3b — Phase 1: Tree-sitter query wrapper.
+ *
+ * Adapters consume the helpers in this file — never the raw `web-tree-sitter`
+ * API. This keeps the surface area minimal and testable.
+ *
+ * Design:
+ *   - `compileQuery` caches compiled `Query` instances per (language, source)
+ *     tuple. Compiling an S-expression is non-trivial; cache hit-rate is
+ *     critical when the same query runs across N sampled files.
+ *   - `runQuery` returns the captures as `{captures, file, line}` records so
+ *     adapters never need to touch raw `Node` objects.
+ *   - `InvalidQueryError` is the typed error thrown when an S-expression is
+ *     malformed; never let a raw `Error` reach the adapter (per audit-iter-5
+ *     fix HH test (b)).
+ */
+
+import { Query, type Language, type Node, type Parser, type QueryMatch } from 'web-tree-sitter';
+
+/**
+ * Thrown when an S-expression query string fails to compile against the
+ * supplied grammar. Carries the original message and the offending source
+ * so adapter authors can debug.
+ */
+export class InvalidQueryError extends Error {
+  public readonly queryName: string;
+  public readonly querySource: string;
+  public readonly cause?: unknown;
+  constructor(queryName: string, querySource: string, cause: unknown) {
+    const causeMsg = cause instanceof Error ? cause.message : String(cause);
+    super(
+      `[query-helpers] Invalid Tree-sitter query "${queryName}": ${causeMsg}\n` +
+        `Query source:\n${querySource}`,
+    );
+    this.name = 'InvalidQueryError';
+    this.queryName = queryName;
+    this.querySource = querySource;
+    this.cause = cause;
+  }
+}
+
+// ============================================================
+// Query compile cache
+// ============================================================
+
+// We key by Language identity (not by name) AND by source string. The Query
+// type from web-tree-sitter is opaque; we store it directly.
+const queryCache = new WeakMap<Language, Map<string, Query>>();
+
+/**
+ * Compile (and cache) an S-expression query against `language`.
+ *
+ * Throws `InvalidQueryError` (NOT raw Error) on malformed S-expressions —
+ * adapters can catch this without losing the typed boundary.
+ *
+ * Cache lookup is O(1) on the (Language, source) tuple via WeakMap+Map.
+ */
+export function compileQuery(
+  language: Language,
+  source: string,
+  queryName: string,
+): Query {
+  let perLang = queryCache.get(language);
+  if (!perLang) {
+    perLang = new Map();
+    queryCache.set(language, perLang);
+  }
+  const cached = perLang.get(source);
+  if (cached) return cached;
+
+  let q: Query;
+  try {
+    q = new Query(language, source);
+  } catch (e) {
+    throw new InvalidQueryError(queryName, source, e);
+  }
+
+  perLang.set(source, q);
+  return q;
+}
+
+// ============================================================
+// Capture extraction
+// ============================================================
+
+export interface RunQueryHit {
+  /**
+   * Capture name → captured text. If the same capture name appears multiple
+   * times in a single match, the LAST occurrence wins (callers usually want
+   * the most-specific one).
+   */
+  captures: Record<string, string>;
+  /** Absolute path to the file being parsed. */
+  file: string;
+  /** 1-based line number of the FIRST capture in the match. */
+  line: number;
+  /** Name of the query (used for provenance). */
+  queryName: string;
+}
+
+/**
+ * Run a compiled query against a parsed tree. Returns a flat list of hits.
+ *
+ * Each match becomes one `RunQueryHit`. The `line` is computed from the
+ * earliest-starting capture in the match (1-based). Note that this helper is
+ * intentionally narrow — it is NOT a general node-walker. Adapters that need
+ * tree traversal should compose multiple queries instead.
+ */
+export function runQuery(
+  parser: Parser,
+  source: string,
+  queryText: string,
+  queryName: string,
+  filePath: string,
+): RunQueryHit[] {
+  const language = parser.language;
+  if (!language) {
+    throw new InvalidQueryError(
+      queryName,
+      queryText,
+      new Error('Parser has no language assigned'),
+    );
+  }
+  const query = compileQuery(language, queryText, queryName);
+
+  const tree = parser.parse(source);
+  if (!tree) return [];
+
+  let matches: QueryMatch[];
+  try {
+    matches = query.matches(tree.rootNode);
+  } catch (e) {
+    // Match-time errors are unusual (compile-time catches most), but we still
+    // wrap to keep the typed-error contract.
+    throw new InvalidQueryError(queryName, queryText, e);
+  }
+
+  const out: RunQueryHit[] = [];
+  for (const match of matches) {
+    if (!match.captures || match.captures.length === 0) continue;
+    const captures: Record<string, string> = {};
+    let earliestLine = Number.POSITIVE_INFINITY;
+    for (const cap of match.captures) {
+      const node: Node = cap.node;
+      captures[cap.name] = node.text;
+      if (node.startPosition.row + 1 < earliestLine) {
+        earliestLine = node.startPosition.row + 1;
+      }
+    }
+    out.push({
+      captures,
+      file: filePath,
+      line: Number.isFinite(earliestLine) ? earliestLine : 1,
+      queryName,
+    });
+  }
+
+  // Per Tree-sitter docs: trees should be deleted to free WASM memory.
+  // Adapters call runQuery once per file so this cleanup is local.
+  try {
+    tree.delete();
+  } catch {
+    /* deletion is best-effort — some test mocks don't implement delete */
+  }
+
+  return out;
+}

package/src/detect/adapters/runner.ts

@@ -0,0 +1,252 @@
+// Copyright (c) 2026 Massu. All rights reserved.
+// Licensed under BSL 1.1 - see LICENSE file for details.
+
+/**
+ * Plan 3b — Phase 1: AST adapter runner.
+ *
+ * Orchestrates: filter adapters via `matches()`, run them, isolate failures
+ * via per-adapter try/catch (audit-iter-5 fix HH test (d)), and merge their
+ * results.
+ *
+ * Confidence merge rule (spec §5):
+ *   - 'high' / 'medium' / 'low' → field is written, with per-field provenance.
+ *   - 'none' → field DROPPED (introspect's regex fallback may then emit it).
+ *
+ * AST-wins rule:
+ *   - When the same conventions key appears in two adapters that BOTH return
+ *     non-'none', the FIRST adapter (by source-list order) wins. This is
+ *     deterministic — adapters are listed in `runner.ts`'s static array,
+ *     never user-provided.
+ */
+
+import { basename, relative } from 'path';
+import type {
+  AdapterResolved,
+  CodebaseAdapter,
+  DetectionSignals,
+  MergedAdapterOutput,
+  Provenance,
+  SourceFile,
+} from './types.ts';
+import { isParsableSource, MAX_AST_FILE_BYTES } from './parse-guard.ts';
+
+export interface RunAdaptersOptions {
+  /**
+   * Optional file sampler — given an adapter and the project root, returns
+   * the SourceFile[] the adapter should consume. If omitted, the runner
+   * passes an empty file list (useful in unit tests where the caller has
+   * already constructed adapters that don't need files).
+   */
+  sampleFiles?: (adapter: CodebaseAdapter, rootDir: string) => Promise<SourceFile[]> | SourceFile[];
+}
+
+/**
+ * Run a static list of adapters against a project root.
+ *
+ * Per-adapter try/catch isolation: a single adapter throwing MUST NOT crash
+ * the runner. The error is captured in `errored[]` and the runner continues.
+ *
+ * @param adapters - Static list of first-party adapters (no user-authored
+ *   adapters at v1 — Plan 3c will add discovery).
+ * @param rootDir - Absolute project root.
+ * @param signals - Pre-built `DetectionSignals` (manifest reads, present
+ *   dirs/files). Adapters consume these read-only.
+ * @param options - Hooks for testing.
+ */
+export async function runAdapters(
+  adapters: CodebaseAdapter[],
+  rootDir: string,
+  signals: DetectionSignals,
+  options: RunAdaptersOptions = {},
+): Promise<MergedAdapterOutput> {
+  const out: MergedAdapterOutput = {
+    byAdapter: {},
+    skipped: [],
+    errored: [],
+  };
+
+  // AST-wins / per-adapter merge:
+  // Each adapter writes to its own `detected.<adapter.id>` namespace, so
+  // global field collisions across adapters can't happen at the conventions
+  // level. The "AST-wins" rule in the spec applies at the introspector tier
+  // (regex fallback only fills fields the adapter returned 'none' for).
+  // Within a single adapter, if `conventions` repeats a key (shouldn't, but
+  // defensively), the first occurrence wins. For multiple adapters with the
+  // same id (shouldn't, but defensively), the first wins.
+
+  for (const adapter of adapters) {
+    if (out.byAdapter[adapter.id] || out.skipped.includes(adapter.id)) {
+      // Duplicate adapter id → skip the second one to preserve first-wins.
+      continue;
+    }
+    let matches: boolean;
+    try {
+      matches = adapter.matches(signals);
+    } catch (e) {
+      out.errored.push({
+        adapterId: adapter.id,
+        error: `matches() threw: ${e instanceof Error ? e.message : String(e)}`,
+      });
+      continue;
+    }
+    if (!matches) {
+      out.skipped.push(adapter.id);
+      continue;
+    }
+
+    let files: SourceFile[];
+    try {
+      files = options.sampleFiles
+        ? await options.sampleFiles(adapter, rootDir)
+        : [];
+    } catch (e) {
+      out.errored.push({
+        adapterId: adapter.id,
+        error: `sampleFiles threw: ${e instanceof Error ? e.message : String(e)}`,
+      });
+      continue;
+    }
+
+    // Phase 3.5 fix: size + depth + control-byte gate. Drop adversarial
+    // inputs BEFORE the adapter sees them — adapters trust this layer.
+    // Files dropped here are logged once per drop so operators see the
+    // signal; the adapter then runs against the surviving subset.
+    const safeFiles: SourceFile[] = [];
+    for (const f of files) {
+      const skip = isParsableSource(f.content, f.size);
+      if (skip) {
+        process.stderr.write(
+          `[massu/ast] WARN: skipping ${f.path} for adapter ${adapter.id}: ${skip.reason} (${skip.detail}). Cap=${MAX_AST_FILE_BYTES} bytes. (Phase 3.5 mitigation)\n`,
+        );
+        continue;
+      }
+      safeFiles.push(f);
+    }
+    files = safeFiles;
+
+    let result;
+    try {
+      result = await adapter.introspect(files, rootDir);
+    } catch (e) {
+      out.errored.push({
+        adapterId: adapter.id,
+        error: `introspect() threw: ${e instanceof Error ? e.message : String(e)}`,
+      });
+      continue;
+    }
+
+    // 'none' confidence drops the entire adapter result. The runner records
+    // that the adapter was attempted (in `byAdapter`) so callers can see it
+    // ran, but with empty conventions. introspect()'s regex fallback then
+    // takes over for the field.
+    if (result.confidence === 'none') {
+      out.byAdapter[adapter.id] = {
+        conventions: {},
+        _provenance: {},
+        confidence: 'none',
+      };
+      continue;
+    }
+
+    // Merge: keep first occurrence of each field (defensive against an
+    // adapter accidentally writing the same field twice).
+    const conventions: Record<string, unknown> = {};
+    const provenanceMap: Record<string, string> = {};
+    for (const [field, value] of Object.entries(result.conventions)) {
+      if (value === null || value === undefined) continue;
+      if (field in conventions) continue;
+      conventions[field] = value;
+    }
+    for (const p of result.provenance) {
+      if (p.field in provenanceMap) continue;
+      provenanceMap[p.field] = formatProvenance(p, rootDir);
+    }
+
+    const resolved: AdapterResolved = {
+      conventions,
+      _provenance: provenanceMap,
+      confidence: result.confidence,
+    };
+    out.byAdapter[adapter.id] = resolved;
+  }
+
+  return out;
+}
+
+function formatProvenance(p: Provenance, rootDir: string): string {
+  const rel = p.sourceFile.startsWith(rootDir + '/')
+    ? relative(rootDir, p.sourceFile)
+    : basename(p.sourceFile);
+  return `${rel}:${p.line} :: ${p.query}`;
+}
+
+// ============================================================
+// Signal builder — used by codebase-introspector to feed the runner
+// ============================================================
+
+import { existsSync, readdirSync, readFileSync, statSync } from 'fs';
+import { join } from 'path';
+
+/**
+ * Build a `DetectionSignals` bundle by reading manifest files at the project
+ * root. Cheap (one-level dir scan + a handful of file reads). Failures
+ * degrade gracefully — a missing manifest just means that field is undefined.
+ */
+export function buildDetectionSignals(rootDir: string): DetectionSignals {
+  const presentDirs = new Set<string>();
+  const presentFiles = new Set<string>();
+  try {
+    for (const entry of readdirSync(rootDir)) {
+      if (entry.startsWith('.')) continue;
+      try {
+        const st = statSync(join(rootDir, entry));
+        if (st.isDirectory()) presentDirs.add(entry);
+        else if (st.isFile()) presentFiles.add(entry);
+      } catch {
+        /* ignore */
+      }
+    }
+  } catch {
+    /* unreadable root → empty signals */
+  }
+
+  return {
+    packageJson: tryReadJson(join(rootDir, 'package.json')),
+    pyprojectToml: tryReadToml(join(rootDir, 'pyproject.toml')),
+    gemfile: tryReadString(join(rootDir, 'Gemfile')),
+    cargoToml: tryReadToml(join(rootDir, 'Cargo.toml')),
+    goMod: tryReadString(join(rootDir, 'go.mod')),
+    presentDirs,
+    presentFiles,
+  };
+}
+
+function tryReadString(path: string): string | undefined {
+  if (!existsSync(path)) return undefined;
+  try {
+    return readFileSync(path, 'utf-8');
+  } catch {
+    return undefined;
+  }
+}
+
+function tryReadJson(path: string): Record<string, unknown> | undefined {
+  const txt = tryReadString(path);
+  if (!txt) return undefined;
+  try {
+    const parsed = JSON.parse(txt);
+    return typeof parsed === 'object' && parsed !== null ? (parsed as Record<string, unknown>) : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function tryReadToml(path: string): Record<string, unknown> | undefined {
+  const txt = tryReadString(path);
+  if (!txt) return undefined;
+  // Cheap signal-only parse: we just need top-level table presence + keys.
+  // Avoid pulling the full toml parser for this; check `[project]`/`[tool.x]`
+  // headers and treat `tool.poetry.dependencies` etc. as opaque text-search.
+  // Adapters that need structured data can grep `txt` themselves.
+  return { __raw: txt };
+}

package/src/detect/adapters/swift-swiftui.ts

@@ -0,0 +1,171 @@
+// Copyright (c) 2026 Massu. All rights reserved.
+// Licensed under BSL 1.1 - see LICENSE file for details.
+
+/**
+ * Plan 3b — Phase 1: SwiftUI AST adapter.
+ *
+ * Extracts:
+ *   - api_client_class: identifier ending in `API` (e.g. `HedgeAPI`)
+ *   - biometric_policy: `LAPolicy.deviceOwnerAuthenticationWithBiometrics` etc.
+ *   - navigation_pattern: 'NavigationStack' | 'NavigationView' | null
+ *
+ * Tree-sitter Swift grammar quirks: the `tree-sitter-swift` grammar names some
+ * nodes differently from python/typescript. We use simpler, more permissive
+ * S-expressions that fall back to capture-text matching where needed.
+ */
+
+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
+// ============================================================
+
+/**
+ * Identifier that looks like an API client class. Captures any uppercase-led
+ * identifier ending in `API`. Predicate filtering is done in JS — Swift's
+ * grammar doesn't surface a clean class-instantiation pattern uniformly.
+ */
+const API_CLASS_QUERY = `
+(simple_identifier) @ident
+`;
+
+/**
+ * `.deviceOwnerAuthentication` / `.deviceOwnerAuthenticationWithBiometrics`
+ * member access. Captures the property name.
+ */
+const POLICY_QUERY = `
+(navigation_expression
+  suffix: (navigation_suffix
+    (simple_identifier) @policy_name))
+`;
+
+/**
+ * NavigationStack / NavigationView usage. Captures any reference to either
+ * symbol.
+ */
+const NAV_QUERY = `
+(simple_identifier) @nav_ident
+`;
+
+// ============================================================
+// Adapter
+// ============================================================
+
+const POLICY_NAMES = new Set([
+  'deviceOwnerAuthentication',
+  'deviceOwnerAuthenticationWithBiometrics',
+]);
+
+export const swiftSwiftUiAdapter: CodebaseAdapter = {
+  id: 'swift-swiftui',
+  languages: ['swift'],
+
+  matches(signals: DetectionSignals): boolean {
+    // Swift signal: presence of Package.swift, *.xcodeproj, or Sources/ dir
+    if (signals.presentFiles.has('Package.swift')) return true;
+    for (const dir of signals.presentDirs) {
+      if (dir.endsWith('.xcodeproj') || dir.endsWith('.xcworkspace')) return true;
+      if (dir === 'Sources') return true;
+    }
+    for (const file of signals.presentFiles) {
+      if (file.endsWith('.swift')) 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('swift');
+    } catch {
+      return { conventions: {}, provenance: [], confidence: 'none' };
+    }
+
+    const parser = new Parser();
+    parser.setLanguage(language);
+
+    const apiClasses = new Map<string, { line: number; file: string }>();
+    const policies = new Map<string, { line: number; file: string }>();
+    const navs = new Map<string, { line: number; file: string }>();
+
+    try {
+      for (const file of files) {
+        const skip = isParsableSource(file.content, file.size);
+        if (skip) {
+          process.stderr.write(
+            `[massu/ast] WARN: swift-swiftui skipping ${file.path}: ${skip.reason} (${skip.detail}). Cap=${MAX_AST_FILE_BYTES}. (Phase 3.5 mitigation)\n`,
+          );
+          continue;
+        }
+        try {
+          // API class names: filter via JS regex on the captured identifier
+          for (const hit of runQuery(parser, file.content, API_CLASS_QUERY, 'swift-api-class', file.path)) {
+            const ident = hit.captures.ident;
+            if (ident && /^[A-Z][A-Za-z0-9_]*API$/.test(ident) && !apiClasses.has(ident)) {
+              apiClasses.set(ident, { line: hit.line, file: file.path });
+            }
+          }
+          // Biometric policy
+          for (const hit of runQuery(parser, file.content, POLICY_QUERY, 'swift-biometric-policy', file.path)) {
+            const name = hit.captures.policy_name;
+            if (name && POLICY_NAMES.has(name) && !policies.has(name)) {
+              policies.set(name, { line: hit.line, file: file.path });
+            }
+          }
+          // Navigation
+          for (const hit of runQuery(parser, file.content, NAV_QUERY, 'swift-navigation', file.path)) {
+            const ident = hit.captures.nav_ident;
+            if ((ident === 'NavigationStack' || ident === 'NavigationView') && !navs.has(ident)) {
+              navs.set(ident, { line: hit.line, 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 (apiClasses.size > 0) {
+      const [name, { line, file }] = apiClasses.entries().next().value as [string, { line: number; file: string }];
+      conventions.api_client_class = name;
+      provenance.push({ field: 'api_client_class', sourceFile: file, line, query: 'swift-api-class' });
+    }
+    if (policies.size > 0) {
+      const [name, { line, file }] = policies.entries().next().value as [string, { line: number; file: string }];
+      conventions.biometric_policy = name;
+      provenance.push({ field: 'biometric_policy', sourceFile: file, line, query: 'swift-biometric-policy' });
+    }
+    if (navs.size > 0) {
+      const [name, { line, file }] = navs.entries().next().value as [string, { line: number; file: string }];
+      conventions.navigation_pattern = name;
+      provenance.push({ field: 'navigation_pattern', sourceFile: file, line, query: 'swift-navigation' });
+    }
+
+    let confidence: AdapterResult['confidence'];
+    if (Object.keys(conventions).length === 0) {
+      confidence = 'none';
+    } else if (apiClasses.size === 1 && policies.size <= 1) {
+      confidence = 'high';
+    } else if (apiClasses.size > 1) {
+      confidence = 'low';
+    } else {
+      confidence = 'medium';
+    }
+
+    return { conventions, provenance, confidence };
+  },
+};