@yasserkhanorg/impact-gate 2.0.0

package/dist/esm/knowledge/api_surface.js

@@ -0,0 +1,408 @@
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+import { existsSync, readFileSync, readdirSync, writeFileSync } from 'fs';
+import { join, extname } from 'path';
+import ts from 'typescript';
+// ── TypeScript AST-based extraction ────────────────────────
+function extractMethodsFromAST(sourceFile, checker) {
+    const surfaces = [];
+    ts.forEachChild(sourceFile, (node) => {
+        if (!ts.isClassDeclaration(node) || !node.name) {
+            return;
+        }
+        const className = node.name.text;
+        const methods = [];
+        const seen = new Set();
+        // Get base class name if extends
+        let extendsName;
+        if (node.heritageClauses) {
+            for (const clause of node.heritageClauses) {
+                if (clause.token === ts.SyntaxKind.ExtendsKeyword && clause.types.length > 0) {
+                    const expr = clause.types[0].expression;
+                    if (ts.isIdentifier(expr)) {
+                        extendsName = expr.text;
+                    }
+                }
+            }
+        }
+        for (const member of node.members) {
+            // Skip constructor
+            if (ts.isConstructorDeclaration(member)) {
+                continue;
+            }
+            // Skip private/protected members
+            const modifiers = ts.canHaveModifiers(member) ? ts.getModifiers(member) : undefined;
+            if (modifiers?.some((m) => m.kind === ts.SyntaxKind.PrivateKeyword || m.kind === ts.SyntaxKind.ProtectedKeyword)) {
+                continue;
+            }
+            const name = member.name && ts.isIdentifier(member.name) ? member.name.text : null;
+            if (!name || name.startsWith('_') || seen.has(name)) {
+                continue;
+            }
+            seen.add(name);
+            if (ts.isMethodDeclaration(member)) {
+                const isAsync = modifiers?.some((m) => m.kind === ts.SyntaxKind.AsyncKeyword) ?? false;
+                const params = extractParams(member.parameters, checker);
+                const returnType = extractReturnType(member, checker);
+                methods.push({
+                    name,
+                    kind: 'method',
+                    async: isAsync ? true : undefined,
+                    params: params.length > 0 ? params : undefined,
+                    returnType: returnType || undefined,
+                });
+            }
+            else if (ts.isGetAccessorDeclaration(member)) {
+                methods.push({ name, kind: 'getter' });
+            }
+            else if (ts.isPropertyDeclaration(member)) {
+                // Check if it's an arrow function property (e.g., name = async () => {})
+                if (member.initializer && (ts.isArrowFunction(member.initializer) || ts.isFunctionExpression(member.initializer))) {
+                    const fn = member.initializer;
+                    const fnModifiers = ts.canHaveModifiers(fn) ? ts.getModifiers(fn) : undefined;
+                    const isAsync = fnModifiers?.some((m) => m.kind === ts.SyntaxKind.AsyncKeyword) ?? false;
+                    const params = extractParams(fn.parameters, checker);
+                    methods.push({
+                        name,
+                        kind: 'method',
+                        async: isAsync ? true : undefined,
+                        params: params.length > 0 ? params : undefined,
+                    });
+                }
+                else {
+                    methods.push({ name, kind: 'property' });
+                }
+            }
+        }
+        if (methods.length > 0) {
+            surfaces.push({
+                className,
+                file: sourceFile.fileName,
+                methods,
+                extends: extendsName,
+            });
+        }
+    });
+    return surfaces;
+}
+function extractParams(params, checker) {
+    return params.map((p) => {
+        const name = ts.isIdentifier(p.name) ? p.name.text : p.name.getText();
+        const optional = p.questionToken !== undefined || p.initializer !== undefined;
+        let type;
+        if (p.type) {
+            type = p.type.getText();
+        }
+        else if (checker) {
+            try {
+                const symbol = checker.getSymbolAtLocation(p.name);
+                if (symbol) {
+                    const t = checker.getTypeOfSymbolAtLocation(symbol, p);
+                    type = checker.typeToString(t);
+                }
+            }
+            catch {
+                // Type inference failure is non-fatal
+            }
+        }
+        return { name, type, optional: optional || undefined };
+    });
+}
+function extractReturnType(method, checker) {
+    if (method.type) {
+        return method.type.getText();
+    }
+    if (checker) {
+        try {
+            const signature = checker.getSignatureFromDeclaration(method);
+            if (signature) {
+                const returnType = checker.getReturnTypeOfSignature(signature);
+                const typeStr = checker.typeToString(returnType);
+                // Skip overly verbose inferred types
+                if (typeStr.length < 100) {
+                    return typeStr;
+                }
+            }
+        }
+        catch {
+            // Type inference failure is non-fatal
+        }
+    }
+    return null;
+}
+/**
+ * Extract page objects using the TypeScript Compiler API.
+ * Falls back to regex if compilation fails.
+ */
+function extractWithAST(files) {
+    if (files.length === 0) {
+        return [];
+    }
+    // Find the nearest tsconfig.json
+    const firstDir = join(files[0], '..');
+    const tsconfigPath = ts.findConfigFile(firstDir, ts.sys.fileExists, 'tsconfig.json');
+    let program;
+    if (tsconfigPath) {
+        const configFile = ts.readConfigFile(tsconfigPath, ts.sys.readFile);
+        const parsedConfig = ts.parseJsonConfigFileContent(configFile.config, ts.sys, join(tsconfigPath, '..'));
+        // Only compile the files we care about, using the config's compiler options
+        program = ts.createProgram(files, parsedConfig.options);
+    }
+    else {
+        program = ts.createProgram(files, {
+            target: ts.ScriptTarget.ES2022,
+            module: ts.ModuleKind.ESNext,
+            moduleResolution: ts.ModuleResolutionKind.Bundler,
+            strict: true,
+            allowJs: false,
+            noEmit: true,
+        });
+    }
+    const checker = program.getTypeChecker();
+    const surfaces = [];
+    for (const filePath of files) {
+        const sourceFile = program.getSourceFile(filePath);
+        if (!sourceFile) {
+            continue;
+        }
+        surfaces.push(...extractMethodsFromAST(sourceFile, checker));
+    }
+    // Resolve inherited methods: if class extends another class in the catalog,
+    // merge parent methods that the child doesn't override
+    resolveInheritance(surfaces);
+    return surfaces;
+}
+/**
+ * Merge parent class methods into child classes that extend them.
+ */
+function resolveInheritance(surfaces) {
+    const byName = new Map(surfaces.map((s) => [s.className, s]));
+    for (const surface of surfaces) {
+        if (!surface.extends) {
+            continue;
+        }
+        const parent = byName.get(surface.extends);
+        if (!parent) {
+            continue;
+        }
+        const childMethodNames = new Set(surface.methods.map((m) => m.name));
+        for (const parentMethod of parent.methods) {
+            if (!childMethodNames.has(parentMethod.name)) {
+                surface.methods.push({ ...parentMethod });
+            }
+        }
+    }
+}
+// ── Regex-based extraction (fallback) ──────────────────────
+const RESERVED_WORDS = new Set([
+    'private', 'protected', 'static', 'abstract', 'override',
+    'if', 'for', 'while', 'switch', 'return',
+    'const', 'let', 'var', 'import', 'export',
+    'class', 'type', 'interface', 'constructor',
+]);
+function extractMethodsFromRegex(content) {
+    const methods = [];
+    const seen = new Set();
+    const asyncMethodRe = /(?:async\s+)([a-zA-Z_]\w*)\s*\(/g;
+    let match;
+    while ((match = asyncMethodRe.exec(content)) !== null) {
+        const name = match[1];
+        if (!RESERVED_WORDS.has(name) && !seen.has(name)) {
+            seen.add(name);
+            methods.push({ name, kind: 'method', async: true });
+        }
+    }
+    const methodRe = /^\s+(?:readonly\s+)?([a-zA-Z_]\w*)\s*(?:\(|=\s*(?:async\s*)?\()/gm;
+    while ((match = methodRe.exec(content)) !== null) {
+        const name = match[1];
+        if (!RESERVED_WORDS.has(name) && !seen.has(name)) {
+            seen.add(name);
+            const isAsync = match[0].includes('async');
+            methods.push({ name, kind: 'method', async: isAsync ? true : undefined });
+        }
+    }
+    const arrowRe = /^\s+([a-zA-Z_]\w*)\s*=\s*(async\s+)?(?:\([^)]*\)|[a-zA-Z_]\w*)\s*=>/gm;
+    while ((match = arrowRe.exec(content)) !== null) {
+        const name = match[1];
+        if (!RESERVED_WORDS.has(name) && !seen.has(name)) {
+            seen.add(name);
+            methods.push({ name, kind: 'method', async: match[2] ? true : undefined });
+        }
+    }
+    const getterRe = /\bget\s+([a-zA-Z_]\w*)\s*\(\)/g;
+    while ((match = getterRe.exec(content)) !== null) {
+        const name = match[1];
+        if (!seen.has(name)) {
+            seen.add(name);
+            methods.push({ name, kind: 'getter' });
+        }
+    }
+    const propRe = /^\s+(?:readonly\s+)?([a-zA-Z_]\w*)\s*[:=]/gm;
+    while ((match = propRe.exec(content)) !== null) {
+        const name = match[1];
+        if (!RESERVED_WORDS.has(name) && !seen.has(name)) {
+            seen.add(name);
+            methods.push({ name, kind: 'property' });
+        }
+    }
+    return methods;
+}
+function extractClassName(content) {
+    const match = content.match(/(?:export\s+)?class\s+(\w+)/);
+    return match ? match[1] : null;
+}
+// ── Directory scanning ─────────────────────────────────────
+function collectTypeScriptFiles(dir) {
+    const files = [];
+    if (!existsSync(dir)) {
+        return files;
+    }
+    const entries = readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+        const fullPath = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            files.push(...collectTypeScriptFiles(fullPath));
+            continue;
+        }
+        const ext = extname(entry.name);
+        if (ext === '.ts' || ext === '.tsx') {
+            files.push(fullPath);
+        }
+    }
+    return files;
+}
+function scanDirectoryWithRegex(dir) {
+    const surfaces = [];
+    if (!existsSync(dir)) {
+        return surfaces;
+    }
+    const entries = readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+        const fullPath = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            surfaces.push(...scanDirectoryWithRegex(fullPath));
+            continue;
+        }
+        const ext = extname(entry.name);
+        if (ext !== '.ts' && ext !== '.tsx') {
+            continue;
+        }
+        try {
+            const content = readFileSync(fullPath, 'utf-8');
+            const className = extractClassName(content);
+            if (!className) {
+                continue;
+            }
+            const extractedMethods = extractMethodsFromRegex(content);
+            if (extractedMethods.length > 0) {
+                surfaces.push({ className, file: fullPath, methods: extractedMethods });
+            }
+        }
+        catch {
+            continue;
+        }
+    }
+    return surfaces;
+}
+// ── Public API ──────────────────────────────────────────────
+export function buildApiSurface(testsRoot, config) {
+    const pageObjectsDir = config?.pageObjectsDir
+        ? join(testsRoot, config.pageObjectsDir)
+        : join(testsRoot, 'lib', 'src', 'ui', 'pages');
+    const componentsDir = config?.componentsDir
+        ? join(testsRoot, config.componentsDir)
+        : join(testsRoot, 'lib', 'src', 'ui', 'components');
+    let pageObjects;
+    if (config?.useRegexFallback) {
+        pageObjects = [
+            ...scanDirectoryWithRegex(pageObjectsDir),
+            ...scanDirectoryWithRegex(componentsDir),
+        ];
+    }
+    else {
+        // Use TypeScript AST — full type info, inheritance, params
+        const allFiles = [
+            ...collectTypeScriptFiles(pageObjectsDir),
+            ...collectTypeScriptFiles(componentsDir),
+        ];
+        try {
+            pageObjects = extractWithAST(allFiles);
+        }
+        catch {
+            // Fall back to regex if AST extraction fails
+            pageObjects = [
+                ...scanDirectoryWithRegex(pageObjectsDir),
+                ...scanDirectoryWithRegex(componentsDir),
+            ];
+        }
+    }
+    return {
+        pageObjects,
+        generatedAt: new Date().toISOString(),
+    };
+}
+export function loadOrBuildApiSurface(testsRoot, config) {
+    if (!config?.enabled) {
+        return { pageObjects: [], generatedAt: new Date().toISOString() };
+    }
+    const cachePath = config.cachePath
+        ? join(testsRoot, config.cachePath)
+        : join(testsRoot, '.e2e-ai-agents', 'api-surface.json');
+    if (existsSync(cachePath)) {
+        try {
+            const cached = JSON.parse(readFileSync(cachePath, 'utf-8'));
+            if (cached.pageObjects && Array.isArray(cached.pageObjects)) {
+                return cached;
+            }
+        }
+        catch {
+            // Rebuild if cache is corrupt
+        }
+    }
+    const catalog = buildApiSurface(testsRoot, config);
+    try {
+        const dir = join(cachePath, '..');
+        if (existsSync(dir)) {
+            writeFileSync(cachePath, JSON.stringify(catalog, null, 2), 'utf-8');
+        }
+    }
+    catch {
+        // Cache write failure is non-fatal
+    }
+    return catalog;
+}
+export function getMethodsForPageObject(catalog, className) {
+    const surface = catalog.pageObjects.find((po) => po.className === className);
+    return surface?.methods || [];
+}
+export function validateMethodCall(catalog, className, methodName) {
+    const methods = getMethodsForPageObject(catalog, className);
+    return methods.some((m) => m.name === methodName);
+}
+export function formatApiSurfaceForPrompt(catalog, classNames) {
+    const sections = [];
+    for (const name of classNames) {
+        const surface = catalog.pageObjects.find((po) => po.className === name);
+        if (!surface) {
+            continue;
+        }
+        const methodList = surface.methods
+            .map((m) => {
+            if (m.kind === 'property') {
+                return `  ${m.name} (property)`;
+            }
+            if (m.kind === 'getter') {
+                return `  get ${m.name}()`;
+            }
+            const prefix = m.async ? 'async ' : '';
+            const paramStr = m.params
+                ? m.params.map((p) => `${p.name}${p.optional ? '?' : ''}${p.type ? `: ${p.type}` : ''}`).join(', ')
+                : '';
+            const retStr = m.returnType ? `: ${m.returnType}` : '';
+            return `  ${prefix}${m.name}(${paramStr})${retStr}`;
+        })
+            .join('\n');
+        sections.push(`${name}:\n${methodList}`);
+    }
+    return sections.join('\n\n');
+}

package/dist/esm/knowledge/cluster_utils.js

@@ -0,0 +1,60 @@
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+/**
+ * Shared cluster ID derivation for knowledge graph processing.
+ * Used by both kg_bridge.ts and kg_scanner.ts.
+ */
+/** Default directories to skip when deriving cluster IDs from file paths. */
+const DEFAULT_SKIP_DIRS = new Set([
+    'src', 'app', 'lib', 'packages', 'server', 'api', 'pages',
+    'components', 'features', 'modules',
+]);
+/** Extended skip set that also excludes test directories. */
+const SKIP_DIRS_WITH_TESTS = new Set([
+    ...DEFAULT_SKIP_DIRS,
+    'test', 'tests', 'e2e', 'spec', 'specs',
+]);
+/**
+ * Normalize a name to a snake_case cluster ID.
+ * Handles camelCase conversion, then strips non-alphanumeric characters.
+ */
+export function normalizeToClusterId(name) {
+    return name
+        .replace(/[A-Z]/g, (c, idx) => (idx > 0 ? `_${c.toLowerCase()}` : c.toLowerCase()))
+        .replace(/[^a-z0-9_]/g, '_')
+        .replace(/_+/g, '_')
+        .replace(/^_|_$/g, '');
+}
+/**
+ * Derive a cluster ID from a node that has an optional filePath and name.
+ * Prefers file path grouping for consistency.
+ */
+export function deriveClusterId(node, skipDirs) {
+    if (node.filePath) {
+        return deriveClusterIdFromPath(node.filePath, skipDirs);
+    }
+    const name = normalizeToClusterId(node.name);
+    return name && name.length > 1 ? name : null;
+}
+/**
+ * Derive a cluster ID from a file path by finding the first meaningful
+ * directory segment after skipping common structural prefixes.
+ */
+export function deriveClusterIdFromPath(filePath, skipDirs = DEFAULT_SKIP_DIRS) {
+    const parts = filePath.replace(/\\/g, '/').split('/').filter(Boolean);
+    for (const part of parts) {
+        if (skipDirs.has(part))
+            continue;
+        if (part.includes('.'))
+            continue; // skip files
+        const normalized = part.toLowerCase()
+            .replace(/[^a-z0-9_]/g, '_')
+            .replace(/_+/g, '_')
+            .replace(/^_|_$/g, '');
+        if (normalized && normalized.length > 1) {
+            return normalized;
+        }
+    }
+    return null;
+}
+export { DEFAULT_SKIP_DIRS, SKIP_DIRS_WITH_TESTS };

package/dist/esm/knowledge/context_loader.js

@@ -0,0 +1,85 @@
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+const MAX_CHARS_PER_DOC = 15000;
+const MAX_TOTAL_CHARS = 40000;
+const DEFAULT_CONTEXT_FILES = [
+    'CLAUDE.OPTIONAL.md',
+    '.claude/CLAUDE.OPTIONAL.md',
+    'README.md',
+];
+export function loadContextDocuments(testsRoot, appRoot, additionalFiles) {
+    const warnings = [];
+    const documents = [];
+    let totalChars = 0;
+    const files = [...DEFAULT_CONTEXT_FILES, ...(additionalFiles || [])];
+    const seen = new Set();
+    for (const file of files) {
+        if (totalChars >= MAX_TOTAL_CHARS) {
+            break;
+        }
+        const candidates = [
+            join(testsRoot, file),
+            ...(appRoot && appRoot !== testsRoot ? [join(appRoot, file)] : []),
+        ];
+        let found = false;
+        for (const candidate of candidates) {
+            const normalized = candidate.replace(/\\/g, '/');
+            if (seen.has(normalized)) {
+                continue;
+            }
+            seen.add(normalized);
+            if (!existsSync(candidate)) {
+                continue;
+            }
+            try {
+                const raw = readFileSync(candidate, 'utf-8').trim();
+                if (!raw) {
+                    continue;
+                }
+                const remaining = MAX_TOTAL_CHARS - totalChars;
+                const content = raw.slice(0, Math.min(MAX_CHARS_PER_DOC, remaining));
+                documents.push({
+                    name: file,
+                    path: normalized,
+                    content,
+                });
+                totalChars += content.length;
+                found = true;
+                break;
+            }
+            catch {
+                continue;
+            }
+        }
+        if (!found && DEFAULT_CONTEXT_FILES.includes(file)) {
+            // Only warn for default files, not user-provided ones
+        }
+    }
+    if (documents.length === 0) {
+        warnings.push('No context documents found (CLAUDE.OPTIONAL.md, README.md). AI agents will have reduced context.');
+    }
+    return { documents, warnings };
+}
+export function formatContextForPrompt(context) {
+    if (context.documents.length === 0) {
+        return 'No repository context documents available.';
+    }
+    return context.documents
+        .map((doc) => `### Context: ${doc.name}\n${doc.content}`)
+        .join('\n\n');
+}
+export function loadSpecFileContent(testsRoot, relativePath, maxChars = 20000) {
+    const fullPath = join(testsRoot, relativePath);
+    if (!existsSync(fullPath)) {
+        return null;
+    }
+    try {
+        const content = readFileSync(fullPath, 'utf-8');
+        return content.slice(0, maxChars);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/esm/knowledge/failure_history.js

@@ -0,0 +1,121 @@
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+/**
+ * Tracks historical test failure correlations: which tests fail when certain files change.
+ * Used to boost confidence in impact analysis — if a file change historically breaks a test,
+ * future changes to that file should prioritize that test.
+ *
+ * Data is stored as a JSON file at .e2e-ai-agents/failure-history.json.
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { join, dirname } from 'path';
+const DEFAULT_HISTORY = {
+    correlations: [],
+    totalRuns: 0,
+    updatedAt: new Date().toISOString(),
+};
+export function loadFailureHistory(testsRoot) {
+    const historyPath = join(testsRoot, '.e2e-ai-agents', 'failure-history.json');
+    if (!existsSync(historyPath)) {
+        return { ...DEFAULT_HISTORY };
+    }
+    try {
+        const raw = JSON.parse(readFileSync(historyPath, 'utf-8'));
+        if (!Array.isArray(raw.correlations)) {
+            return { ...DEFAULT_HISTORY };
+        }
+        return raw;
+    }
+    catch {
+        return { ...DEFAULT_HISTORY };
+    }
+}
+export function saveFailureHistory(testsRoot, history) {
+    const historyPath = join(testsRoot, '.e2e-ai-agents', 'failure-history.json');
+    try {
+        const dir = dirname(historyPath);
+        if (!existsSync(dir)) {
+            mkdirSync(dir, { recursive: true });
+        }
+        history.updatedAt = new Date().toISOString();
+        writeFileSync(historyPath, JSON.stringify(history, null, 2), 'utf-8');
+    }
+    catch {
+        // Non-fatal — history is advisory, not required
+    }
+}
+/**
+ * Record that a set of changed files caused a set of spec failures.
+ * Call this after a test run where failures were observed.
+ */
+export function recordFailures(history, changedFiles, failedSpecs) {
+    const now = new Date().toISOString();
+    const updated = { ...history, totalRuns: history.totalRuns + 1, correlations: [...history.correlations] };
+    for (const changedFile of changedFiles) {
+        for (const specFile of failedSpecs) {
+            const existing = updated.correlations.find((c) => c.changedFile === changedFile && c.specFile === specFile);
+            if (existing) {
+                existing.count++;
+                existing.lastSeen = now;
+            }
+            else {
+                updated.correlations.push({
+                    changedFile,
+                    specFile,
+                    count: 1,
+                    lastSeen: now,
+                });
+            }
+        }
+    }
+    // Prune stale correlations (not seen in 90 days)
+    const cutoff = new Date();
+    cutoff.setDate(cutoff.getDate() - 90);
+    const cutoffStr = cutoff.toISOString();
+    updated.correlations = updated.correlations.filter((c) => c.lastSeen >= cutoffStr);
+    return updated;
+}
+/**
+ * Get a confidence boost (0-20) for a file based on historical failure patterns.
+ * A file that historically causes test failures gets a higher confidence boost
+ * when detected as impacted, meaning the system is more confident it needs testing.
+ */
+export function getConfidenceBoost(history, changedFile) {
+    const correlations = history.correlations.filter((c) => c.changedFile === changedFile);
+    if (correlations.length === 0) {
+        return 0;
+    }
+    // More correlations and higher counts = more confidence
+    const totalCount = correlations.reduce((sum, c) => sum + c.count, 0);
+    const uniqueSpecs = correlations.length;
+    // Scale: 1 correlation = +5, 3+ = +10, 5+ with high counts = +15, max +20
+    if (totalCount >= 10 && uniqueSpecs >= 5)
+        return 20;
+    if (totalCount >= 5 && uniqueSpecs >= 3)
+        return 15;
+    if (totalCount >= 3)
+        return 10;
+    return 5;
+}
+/**
+ * Get the most likely failing specs for a set of changed files, based on history.
+ * Returns specs sorted by correlation strength (count * recency).
+ */
+export function getPredictedFailures(history, changedFiles, limit = 10) {
+    const specScores = new Map();
+    for (const changedFile of changedFiles) {
+        for (const c of history.correlations) {
+            if (c.changedFile !== changedFile)
+                continue;
+            // Score: count weighted by recency (days since last seen)
+            const daysSince = (Date.now() - new Date(c.lastSeen).getTime()) / (1000 * 60 * 60 * 24);
+            const recencyWeight = Math.max(0.1, 1 - daysSince / 90);
+            const score = c.count * recencyWeight;
+            specScores.set(c.specFile, (specScores.get(c.specFile) || 0) + score);
+        }
+    }
+    return Array.from(specScores.entries())
+        .map(([specFile, score]) => ({ specFile, score }))
+        .sort((a, b) => b.score - a.score)
+        .slice(0, limit);
+}