@maintainabilityai/research-runner 0.1.1

package/dist/runner/nodes/analyze-architecture.js

@@ -0,0 +1,447 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ANALYZER_VERSION = void 0;
+exports.analyzeArchitecture = analyzeArchitecture;
+/**
+ * analyze_architecture — pure node (archaeology path), file-based variant.
+ *
+ * Phase 3a — no tree-sitter. Extracts:
+ *   - RepositoryProfile (languages, frameworks, manifests, totals)
+ *   - Modules (top-level src/ subdirectories or root dirs not in SKIP_DIRS),
+ *     each tagged with an inferred layer (api / web / data / worker / shared)
+ *   - Endpoints (regex-detected route handlers across the four most common
+ *     frameworks: Express, FastAPI, Flask, Spring)
+ *   - Dependencies (parsed from package.json, pyproject.toml requirements
+ *     section, Cargo.toml [dependencies], go.mod require block)
+ *
+ * Heuristic, not authoritative. Tree-sitter integration (phase 3b) will
+ * give us symbol-level accuracy; for now the synthesis prompt knows this
+ * is a file-based pass and the audit log records `analyzer_version` so
+ * an auditor can re-run with a deeper analyzer later.
+ */
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+exports.ANALYZER_VERSION = 'file-based-v1';
+const LAYER_HINTS = [
+    { layer: 'api', patterns: [/^api$/i, /^server$/i, /^backend$/i, /^routes$/i, /^controllers$/i, /^handlers$/i, /^endpoints$/i] },
+    { layer: 'web', patterns: [/^web$/i, /^frontend$/i, /^client$/i, /^ui$/i, /^app$/i, /^components$/i, /^pages$/i, /^views$/i] },
+    { layer: 'data', patterns: [/^db$/i, /^database$/i, /^models$/i, /^entities$/i, /^migrations$/i, /^prisma$/i, /^schemas?$/i] },
+    { layer: 'worker', patterns: [/^workers?$/i, /^jobs$/i, /^cron$/i, /^queue$/i, /^tasks?$/i, /^consumers?$/i] },
+    { layer: 'shared', patterns: [/^lib$/i, /^libs$/i, /^common$/i, /^shared$/i, /^utils?$/i, /^helpers$/i, /^core$/i, /^types$/i] },
+];
+const ENDPOINT_FILE_EXTS = new Set(['.ts', '.tsx', '.js', '.jsx', '.mjs', '.py', '.java', '.kt']);
+/** Walked-source file cap for endpoint scanning — keep audit cheap. */
+const MAX_ENDPOINT_SCAN_FILES = 200;
+/** Cap on returned endpoints (very chatty Express files can blow up). */
+const MAX_ENDPOINTS = 80;
+function analyzeArchitecture(opts) {
+    const { cloneDir, targetRepo, cloneSha, inventory } = opts;
+    const languages = detectLanguages(inventory);
+    const { frameworks, dependencies } = readManifests(cloneDir, inventory.rootManifests);
+    const modules = detectModules(cloneDir, inventory);
+    const endpoints = scanEndpoints(cloneDir);
+    // Attribute endpoints back to their module (best-effort: longest matching prefix)
+    const endpointsByModule = new Map();
+    for (const ep of endpoints) {
+        const owner = modules
+            .map(m => m.name)
+            .filter(n => ep.file === n || ep.file.startsWith(`${n}/`) || ep.file.startsWith(`src/${n}/`))
+            .sort((a, b) => b.length - a.length)[0];
+        if (owner) {
+            endpointsByModule.set(owner, (endpointsByModule.get(owner) ?? 0) + 1);
+        }
+    }
+    for (const m of modules) {
+        m.endpointCount = endpointsByModule.get(m.name) ?? 0;
+    }
+    const profile = {
+        slug: targetRepo,
+        cloneSha,
+        totalFiles: inventory.totalFiles,
+        totalBytes: inventory.totalBytes,
+        byExtension: inventory.byExtension,
+        languages,
+        frameworks,
+        manifests: inventory.rootManifests,
+    };
+    return { profile, modules, endpoints, dependencies, deviations: [] };
+}
+// ============================================================================
+// Language + framework detection
+// ============================================================================
+function detectLanguages(inventory) {
+    const langs = new Set();
+    const counts = inventory.byExtension;
+    if ((counts['.ts'] ?? 0) + (counts['.tsx'] ?? 0) > 0) {
+        langs.add('TypeScript');
+    }
+    if ((counts['.js'] ?? 0) + (counts['.jsx'] ?? 0) + (counts['.mjs'] ?? 0) + (counts['.cjs'] ?? 0) > 0) {
+        langs.add('JavaScript');
+    }
+    if ((counts['.py'] ?? 0) > 0) {
+        langs.add('Python');
+    }
+    if ((counts['.java'] ?? 0) > 0) {
+        langs.add('Java');
+    }
+    if ((counts['.kt'] ?? 0) + (counts['.kts'] ?? 0) > 0) {
+        langs.add('Kotlin');
+    }
+    if ((counts['.go'] ?? 0) > 0) {
+        langs.add('Go');
+    }
+    if ((counts['.rs'] ?? 0) > 0) {
+        langs.add('Rust');
+    }
+    if ((counts['.rb'] ?? 0) > 0) {
+        langs.add('Ruby');
+    }
+    if ((counts['.php'] ?? 0) > 0) {
+        langs.add('PHP');
+    }
+    if ((counts['.cs'] ?? 0) > 0) {
+        langs.add('C#');
+    }
+    if ((counts['.swift'] ?? 0) > 0) {
+        langs.add('Swift');
+    }
+    if ((counts['.ex'] ?? 0) + (counts['.exs'] ?? 0) > 0) {
+        langs.add('Elixir');
+    }
+    return [...langs].sort();
+}
+function readManifests(cloneDir, manifestNames) {
+    const frameworks = new Set();
+    const dependencies = new Set();
+    for (const name of manifestNames) {
+        const full = path.join(cloneDir, name);
+        let raw;
+        try {
+            raw = fs.readFileSync(full, 'utf8');
+        }
+        catch {
+            continue;
+        }
+        if (/^package\.json$/i.test(name)) {
+            parsePackageJson(raw, frameworks, dependencies);
+        }
+        else if (/^pyproject\.toml$/i.test(name)) {
+            parsePyproject(raw, frameworks, dependencies);
+        }
+        else if (/^requirements\.txt$/i.test(name)) {
+            parseRequirementsTxt(raw, frameworks, dependencies);
+        }
+        else if (/^cargo\.toml$/i.test(name)) {
+            parseCargoToml(raw, frameworks, dependencies);
+        }
+        else if (/^go\.mod$/i.test(name)) {
+            parseGoMod(raw, frameworks, dependencies);
+        }
+        else if (/^pom\.xml$/i.test(name)) {
+            parsePomXml(raw, frameworks, dependencies);
+        }
+        else if (/^gemfile$/i.test(name)) {
+            parseGemfile(raw, frameworks, dependencies);
+        }
+    }
+    return {
+        frameworks: [...frameworks].sort().slice(0, 30),
+        dependencies: [...dependencies].sort().slice(0, 60),
+    };
+}
+const KNOWN_FRAMEWORK_PACKAGES = {
+    // JS/TS
+    express: 'express', '@nestjs/core': 'nestjs', fastify: 'fastify',
+    next: 'next.js', react: 'react', vue: 'vue', '@angular/core': 'angular',
+    svelte: 'svelte', remix: 'remix', '@remix-run/server-runtime': 'remix',
+    koa: 'koa', hapi: 'hapi',
+    // Python
+    fastapi: 'fastapi', flask: 'flask', django: 'django', starlette: 'starlette',
+    // Java/Kotlin
+    'spring-boot-starter-web': 'spring-boot', 'spring-web': 'spring',
+    // Go
+    'github.com/gin-gonic/gin': 'gin', 'github.com/labstack/echo': 'echo',
+    'github.com/gofiber/fiber': 'fiber',
+    // Rust
+    actix: 'actix-web', 'actix-web': 'actix-web', axum: 'axum', rocket: 'rocket',
+    // Ruby
+    rails: 'rails', sinatra: 'sinatra',
+};
+function classifyDep(dep, frameworks) {
+    const hit = KNOWN_FRAMEWORK_PACKAGES[dep.toLowerCase()];
+    if (hit) {
+        frameworks.add(hit);
+    }
+}
+function parsePackageJson(raw, frameworks, deps) {
+    try {
+        const obj = JSON.parse(raw);
+        const dependencies = obj.dependencies ?? {};
+        for (const name of Object.keys(dependencies)) {
+            deps.add(name);
+            classifyDep(name, frameworks);
+        }
+    }
+    catch { /* malformed package.json — skip */ }
+}
+function parsePyproject(raw, frameworks, deps) {
+    // Lightweight: pick up `dependencies = ["fastapi >=0.100", …]` AND
+    // `[tool.poetry.dependencies]` keys.
+    const arrayMatch = raw.match(/dependencies\s*=\s*\[([\s\S]*?)\]/);
+    if (arrayMatch) {
+        for (const m of arrayMatch[1].matchAll(/"\s*([a-zA-Z0-9_.-]+)/g)) {
+            deps.add(m[1].toLowerCase());
+            classifyDep(m[1].toLowerCase(), frameworks);
+        }
+    }
+    const poetrySection = raw.match(/\[tool\.poetry\.dependencies\]([\s\S]*?)(?:\n\[|$)/);
+    if (poetrySection) {
+        for (const m of poetrySection[1].matchAll(/^([a-zA-Z0-9_.-]+)\s*=/gm)) {
+            const name = m[1].toLowerCase();
+            if (name === 'python') {
+                continue;
+            }
+            deps.add(name);
+            classifyDep(name, frameworks);
+        }
+    }
+}
+function parseRequirementsTxt(raw, frameworks, deps) {
+    for (const line of raw.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith('#') || trimmed.startsWith('-')) {
+            continue;
+        }
+        const m = trimmed.match(/^([a-zA-Z0-9_.-]+)/);
+        if (m) {
+            const name = m[1].toLowerCase();
+            deps.add(name);
+            classifyDep(name, frameworks);
+        }
+    }
+}
+function parseCargoToml(raw, frameworks, deps) {
+    const section = raw.match(/\[dependencies\]([\s\S]*?)(?:\n\[|$)/);
+    if (!section) {
+        return;
+    }
+    for (const m of section[1].matchAll(/^([a-zA-Z0-9_.-]+)\s*=/gm)) {
+        const name = m[1].toLowerCase();
+        deps.add(name);
+        classifyDep(name, frameworks);
+    }
+}
+function parseGoMod(raw, frameworks, deps) {
+    const requireBlock = raw.match(/require\s*\(([\s\S]*?)\)/);
+    const body = requireBlock ? requireBlock[1] : raw;
+    for (const m of body.matchAll(/^\s*([\w./-]+)\s+v[\d.+\-a-z]+/gm)) {
+        const name = m[1].toLowerCase();
+        deps.add(name);
+        classifyDep(name, frameworks);
+    }
+}
+function parsePomXml(raw, frameworks, deps) {
+    for (const m of raw.matchAll(/<artifactId>([\w.-]+)<\/artifactId>/gi)) {
+        const name = m[1].toLowerCase();
+        deps.add(name);
+        classifyDep(name, frameworks);
+    }
+}
+function parseGemfile(raw, frameworks, deps) {
+    for (const m of raw.matchAll(/gem\s+["']([a-zA-Z0-9_.-]+)/g)) {
+        const name = m[1].toLowerCase();
+        deps.add(name);
+        classifyDep(name, frameworks);
+    }
+}
+// ============================================================================
+// Module / layer detection
+// ============================================================================
+function detectModules(cloneDir, inventory) {
+    const candidateDirs = new Set();
+    // Top-level directories (skipped already filtered by clone-and-index)
+    for (const entry of inventory.topLevelEntries) {
+        const full = path.join(cloneDir, entry);
+        try {
+            if (fs.statSync(full).isDirectory()) {
+                candidateDirs.add(entry);
+            }
+        }
+        catch { /* skip */ }
+    }
+    // Also walk src/* — many JS/TS repos hide structure there
+    const srcDir = path.join(cloneDir, 'src');
+    if (fs.existsSync(srcDir) && fs.statSync(srcDir).isDirectory()) {
+        try {
+            for (const entry of fs.readdirSync(srcDir, { withFileTypes: true })) {
+                if (entry.isDirectory()) {
+                    candidateDirs.add(`src/${entry.name}`);
+                }
+            }
+        }
+        catch { /* skip */ }
+    }
+    const modules = [];
+    for (const name of candidateDirs) {
+        const full = path.join(cloneDir, name);
+        const fileCount = countFiles(full);
+        if (fileCount === 0) {
+            continue;
+        }
+        modules.push({
+            name,
+            layer: classifyLayer(name),
+            fileCount,
+            endpointCount: 0, // populated after endpoint scan
+        });
+    }
+    return modules.sort((a, b) => b.fileCount - a.fileCount);
+}
+function classifyLayer(modulePath) {
+    const leaf = modulePath.split('/').pop().toLowerCase();
+    for (const hint of LAYER_HINTS) {
+        if (hint.patterns.some(re => re.test(leaf))) {
+            return hint.layer;
+        }
+    }
+    return 'unknown';
+}
+function countFiles(dir) {
+    let count = 0;
+    function walk(d) {
+        let entries;
+        try {
+            entries = fs.readdirSync(d, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const ent of entries) {
+            if (ent.isDirectory()) {
+                walk(path.join(d, ent.name));
+            }
+            else if (ent.isFile()) {
+                count += 1;
+            }
+        }
+    }
+    walk(dir);
+    return count;
+}
+const ENDPOINT_PATTERNS = [
+    // Express / Koa / Fastify shape: `app.get('/users/:id', ...)`
+    { framework: 'express', re: /\b(?:app|router|fastify|server)\.(get|post|put|patch|delete|options|head)\s*\(\s*['"`]([^'"`]+)/gi },
+    // FastAPI / Flask: `@app.get("/users/{id}")` / `@app.route("/x")`
+    { framework: 'fastapi', re: /@\w+\.(get|post|put|patch|delete)\s*\(\s*['"]([^'"]+)/gi },
+    { framework: 'flask', re: /@\w+\.route\s*\(\s*['"]([^'"]+)/gi, methodFromDecoratorPos: -1 },
+    // Spring (Java/Kotlin): `@GetMapping("/users")` / `@RequestMapping(method=…, value="/x")`
+    { framework: 'spring', re: /@(Get|Post|Put|Patch|Delete)Mapping\s*\(\s*['"]([^'"]+)/g },
+];
+function scanEndpoints(cloneDir) {
+    const found = [];
+    let scanned = 0;
+    function walk(dir) {
+        if (found.length >= MAX_ENDPOINTS) {
+            return;
+        }
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const ent of entries) {
+            if (found.length >= MAX_ENDPOINTS) {
+                return;
+            }
+            const full = path.join(dir, ent.name);
+            if (ent.isDirectory()) {
+                if (ent.name === '.git' || ent.name === 'node_modules' || ent.name === 'dist' || ent.name === 'build') {
+                    continue;
+                }
+                walk(full);
+                continue;
+            }
+            if (!ent.isFile()) {
+                continue;
+            }
+            if (!ENDPOINT_FILE_EXTS.has(path.extname(ent.name).toLowerCase())) {
+                continue;
+            }
+            if (scanned >= MAX_ENDPOINT_SCAN_FILES) {
+                continue;
+            }
+            scanned += 1;
+            let content;
+            try {
+                content = fs.readFileSync(full, 'utf8');
+            }
+            catch {
+                continue;
+            }
+            const relFile = path.relative(cloneDir, full);
+            for (const pat of ENDPOINT_PATTERNS) {
+                // matchAll needs a global regex; reset lastIndex isn't an issue with matchAll
+                for (const m of content.matchAll(pat.re)) {
+                    let method;
+                    let routePath;
+                    if (pat.methodFromDecoratorPos === -1) {
+                        // Flask: `@app.route("/x")` — method defaults to GET unless `methods=` is set
+                        method = 'GET';
+                        routePath = m[1];
+                    }
+                    else {
+                        method = (m[1] || '').toUpperCase();
+                        routePath = m[2];
+                    }
+                    if (!routePath) {
+                        continue;
+                    }
+                    found.push({ method, path: routePath, file: relFile, framework: pat.framework });
+                    if (found.length >= MAX_ENDPOINTS) {
+                        break;
+                    }
+                }
+                if (found.length >= MAX_ENDPOINTS) {
+                    break;
+                }
+            }
+        }
+    }
+    walk(cloneDir);
+    return found;
+}

package/dist/runner/nodes/arxiv-search.d.ts

@@ -0,0 +1,12 @@
+import type { ProviderResult } from '../../search/provider-result';
+import type { QueryEnvelope } from './tavily-search';
+export interface ArxivSearchNodeOpts {
+    queries: string[];
+    maxResultsPerQuery?: number;
+    fetchImpl?: typeof fetch;
+}
+export interface ArxivSearchNodeResult {
+    envelopes: QueryEnvelope[];
+    results: ProviderResult[];
+}
+export declare function runArxivSearch(opts: ArxivSearchNodeOpts): Promise<ArxivSearchNodeResult>;

package/dist/runner/nodes/arxiv-search.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runArxivSearch = runArxivSearch;
+/**
+ * arxiv_search — pure_api node.
+ *
+ * Runs each arxiv query against export.arxiv.org in parallel. arXiv's
+ * Atom API doesn't return a relevance score; we synthesise one from
+ * result position (top result → 0.9 → linear decay to 0.5).
+ */
+const arxiv_client_1 = require("../../search/arxiv-client");
+async function runArxivSearch(opts) {
+    const settled = await Promise.allSettled(opts.queries.map(query => (0, arxiv_client_1.arxivSearch)({
+        query,
+        maxResults: opts.maxResultsPerQuery ?? 5,
+        fetchImpl: opts.fetchImpl,
+    })));
+    const envelopes = [];
+    const results = [];
+    for (let i = 0; i < opts.queries.length; i++) {
+        const query = opts.queries[i];
+        const outcome = settled[i];
+        if (outcome.status === 'fulfilled') {
+            const ok = outcome.value;
+            envelopes.push({
+                query,
+                httpStatus: ok.httpStatus,
+                responseBytes: ok.responseBytes,
+                resultCount: ok.results.length,
+            });
+            for (let j = 0; j < ok.results.length; j++) {
+                const r = ok.results[j];
+                results.push({
+                    provider: 'arxiv',
+                    fromQuery: query,
+                    title: r.title,
+                    url: r.abstractUrl,
+                    content: r.summary.slice(0, 500),
+                    // Position-derived score: arXiv returns by relevance, decay 0.9 → 0.5.
+                    score: Math.max(0.5, 0.9 - j * 0.1),
+                    publishedDate: r.published || undefined,
+                    authors: r.authors,
+                });
+            }
+        }
+        else {
+            const err = outcome.reason instanceof Error ? outcome.reason.message : String(outcome.reason);
+            envelopes.push({ query, httpStatus: 0, responseBytes: 0, resultCount: 0, error: err });
+        }
+    }
+    return { envelopes, results };
+}

package/dist/runner/nodes/clone-and-index.d.ts

@@ -0,0 +1,32 @@
+export interface CloneAndIndexOpts {
+    /** owner/repo (used for both the URL and the `slug` in RepositoryProfile). */
+    targetRepo: string;
+    /** Override the parent dir for tests. Defaults to os.tmpdir(). */
+    parentDir?: string;
+    /** Branch / tag / SHA to check out after clone. Default: repo default branch. */
+    ref?: string;
+    /**
+     * Test injection: override the clone source URL (e.g. a `file://` path
+     * pointing at a local repo). When set, replaces the default
+     * `https://github.com/<targetRepo>.git`.
+     */
+    originUrl?: string;
+}
+export interface FileInventory {
+    totalFiles: number;
+    totalBytes: number;
+    byExtension: Record<string, number>;
+    /** Manifest filenames present at repo root (lowercased). */
+    rootManifests: string[];
+    /** Top-level entries (directories + files at depth 1). */
+    topLevelEntries: string[];
+    /** Lightly-walked list of source files (cap-applied — we don't enumerate everything). */
+    sourceFiles: string[];
+}
+export interface CloneAndIndexResult {
+    /** Absolute path to the cloned repo on disk. Caller is responsible for cleanup. */
+    cloneDir: string;
+    cloneSha: string;
+    inventory: FileInventory;
+}
+export declare function cloneAndIndex(opts: CloneAndIndexOpts): CloneAndIndexResult;