@mknrt/autotests-overkill 1.1.2 → 1.1.4

package/dist/src/domain/triageFailedRun.js

@@ -1,4 +1,5 @@
 import fs from 'node:fs';
+import { countDocuments, queryDocuments } from '../knowledge/repositories.js';
 import { evidenceFile, output } from './shared.js';
 export async function triageFailedRun(input, context) {
     const stats = context.ciArtifacts.readStats(input.statsFile);
@@ -11,6 +12,10 @@ export async function triageFailedRun(input, context) {
     const apiCaptures = context.ciArtifacts.listArtifacts(input.apiCaptureRoot, '**/*.json');
     const failedSpecs = stats.failed_specs ?? [];
     const repeatedAttempts = screenshots.filter((filePath) => filePath.includes('attempt 2')).length;
+    const captureSignals = readApiCaptureSignals(apiCaptures);
+    const apiBackendContext = captureSignals.length > 0
+        ? await matchApiCapturesToBackendContext(captureSignals, context)
+        : { interactionHits: [], backendHits: [] };
     const warnings = failedSpecs.length === 0
         ? ['Current stats file reports zero failed specs; using persisted screenshots and artifact residue for triage context.']
         : [];
@@ -19,6 +24,9 @@ export async function triageFailedRun(input, context) {
         failedSpecs.length > 0 ? 'Rerun only the failed specs first.' : 'Start from the specs named in persisted screenshots before broad reruns.',
         repeatedAttempts > 0 ? 'Inspect flaky or environment-sensitive failures because repeated attempts are present.' : 'Inspect first-failure artifacts before assuming flakiness.',
         apiCaptures.length > 0 ? 'Compare API capture payloads for the affected run before editing selectors.' : 'Capture API traffic on the next rerun to reduce ambiguity.',
+        ...(apiBackendContext.interactionHits.length > 0 || apiBackendContext.backendHits.length > 0
+            ? ['Compare the failing API capture with the indexed API interaction flow and backend contract before editing the test flow.']
+            : []),
     ];
     return output(`CI triage summary: stats show ${stats.total ?? 0} tests, ${stats.failed ?? 0} current failures, ${screenshots.length} screenshots, ${videos.length} videos, and ${apiCaptures.length} captured API artifacts.`, [
         evidenceFile('stats report', input.statsFile, JSON.stringify({
@@ -30,6 +38,16 @@ export async function triageFailedRun(input, context) {
         ...failedSpecs.slice(0, 5).map((specPath) => ({ type: 'test', label: 'failed spec', path: specPath })),
         ...screenshots.slice(0, 5).map((filePath) => evidenceFile('failure screenshot', filePath, fs.existsSync(filePath) ? undefined : 'missing')),
         ...videos.slice(0, 3).map((filePath) => evidenceFile('failure video', filePath)),
+        ...captureSignals.slice(0, 5).map((signal) => evidenceFile('matched api capture', signal.sourcePath, `${signal.method ?? 'UNKNOWN'} ${signal.path} -> ${signal.status ?? 'unknown status'}`, {
+            requestPath: signal.path,
+            status: signal.status,
+        })),
+        ...apiBackendContext.interactionHits.map((item) => evidenceFile('api interaction', item.path, item.title, {
+            confidence: parseMetadata(item.metadata_json).confidence,
+        })),
+        ...apiBackendContext.backendHits.map((item) => evidenceFile('backend endpoint', item.path, item.title, {
+            confidence: parseMetadata(item.metadata_json).confidence,
+        })),
         ...(reportPortal.launchLink ? [{
                 type: 'report',
                 label: reportPortal.launchStatus ? `ReportPortal launch (${reportPortal.launchStatus})` : 'ReportPortal launch',
@@ -44,3 +62,82 @@ export async function triageFailedRun(input, context) {
             }] : []),
     ], actions, warnings);
 }
+function readApiCaptureSignals(apiCaptures) {
+    return apiCaptures.flatMap((filePath) => {
+        try {
+            const raw = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+            const entries = Array.isArray(raw) ? raw : [raw];
+            return entries.flatMap((entry) => normalizeCaptureEntry(entry, filePath));
+        }
+        catch {
+            return [];
+        }
+    });
+}
+function normalizeCaptureEntry(entry, sourcePath) {
+    if (!entry || typeof entry !== 'object') {
+        return [];
+    }
+    const record = entry;
+    const pathValue = record.path ?? record.url ?? record.requestUrl;
+    if (typeof pathValue !== 'string') {
+        return [];
+    }
+    return [{
+            sourcePath,
+            method: typeof record.method === 'string' ? record.method : undefined,
+            path: normalizeRequestPath(pathValue),
+            status: typeof record.status === 'number' ? record.status : undefined,
+        }];
+}
+async function matchApiCapturesToBackendContext(captureSignals, context) {
+    if (countDocuments(context.database) === 0) {
+        return { interactionHits: [], backendHits: [] };
+    }
+    const signalQuery = captureSignals.map((signal) => signal.path).join(' ');
+    const interactionHits = queryDocuments(context.database, signalQuery, {
+        repoKind: 'autotests2',
+        sourceKinds: ['api-interaction'],
+        limit: 6,
+    }).filter((item) => {
+        const metadata = parseMetadata(item.metadata_json);
+        return (metadata.confidence ?? 0) >= 0.7
+            && (metadata.normalizedPaths ?? []).some((indexedPath) => captureSignals.some((signal) => pathsOverlap(indexedPath, signal.path)));
+    });
+    const backendHits = interactionHits.length > 0
+        ? queryDocuments(context.database, interactionHits.map((item) => item.title).join(' '), {
+            repoKind: 'fis-platform',
+            sourceKinds: ['backend-endpoint'],
+            limit: 6,
+        }).filter((item) => (parseMetadata(item.metadata_json).confidence ?? 0) >= 0.7)
+        : [];
+    return { interactionHits, backendHits };
+}
+function normalizeRequestPath(value) {
+    try {
+        const parsed = new URL(value);
+        return parsed.pathname;
+    }
+    catch {
+        return value.split('?')[0] ?? value;
+    }
+}
+function pathsOverlap(indexedPath, capturedPath) {
+    return capturedPath.includes(indexedPath)
+        || indexedPath.includes(capturedPath)
+        || normalizeTokens(indexedPath).filter((token) => normalizeTokens(capturedPath).includes(token)).length >= 2;
+}
+function normalizeTokens(value) {
+    return value
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter((token) => token.length > 1 && !/^(platform|rs2|api|rest)$/.test(token));
+}
+function parseMetadata(metadataJson) {
+    try {
+        return JSON.parse(metadataJson);
+    }
+    catch {
+        return {};
+    }
+}

package/dist/src/indexer/extractors/apiDiscoveryExtractor.d.ts

@@ -0,0 +1,23 @@
+export type ApiDiscoveryCatalog = {
+    families: ApiDiscoveryFamily[];
+    generatedAt: string;
+    warnings: string[];
+};
+export type ApiDiscoveryFamily = {
+    family: string;
+    normalizedPaths: string[];
+    consumerSignals: ApiConsumerSignal[];
+    score: number;
+    whySelected: string[];
+};
+export type ApiConsumerSignal = {
+    kind: 'endpoint-constant' | 'request-wrapper' | 'capture-support' | 'spec-reference';
+    path: string;
+    name?: string;
+    snippet: string;
+};
+export declare function buildApiDiscoveryCatalog(input: {
+    root: string;
+    maxSelectedFamilies?: number;
+}): Promise<ApiDiscoveryCatalog>;
+export declare function scoreFamily(signals: ApiConsumerSignal[]): number;

package/dist/src/indexer/extractors/apiDiscoveryExtractor.js

@@ -0,0 +1,183 @@
+import path from 'node:path';
+import { Autotests2Connector } from '../../connectors/autotests2Connector.js';
+import { toPosixPath } from '../../utils/pathUtils.js';
+export async function buildApiDiscoveryCatalog(input) {
+    const connector = new Autotests2Connector(input.root);
+    const sources = await connector.findApiSupportSources();
+    const drafts = new Map();
+    for (const source of sources) {
+        collectEndpointSignals(source, drafts);
+    }
+    for (const source of sources) {
+        collectWrapperSignals(source, drafts);
+        collectCaptureSignals(source, drafts);
+    }
+    const candidates = [...drafts.entries()]
+        .map(([family, draft]) => {
+        const score = scoreFamily(draft.consumerSignals);
+        const signalKinds = new Set(draft.consumerSignals.map((signal) => signal.kind));
+        return {
+            family,
+            normalizedPaths: [...draft.normalizedPaths].sort(),
+            consumerSignals: dedupeSignals(draft.consumerSignals),
+            score,
+            whySelected: [
+                `Selected from ${signalKinds.size} consumer signal kind(s).`,
+                `Deterministic score ${score} from endpoint constants, request wrappers, capture support, and spec references.`,
+            ],
+        };
+    })
+        .filter((family) => family.score > 0 && hasEnoughEvidence(family))
+        .sort((left, right) => {
+        if (right.score !== left.score) {
+            return right.score - left.score;
+        }
+        return left.family.localeCompare(right.family);
+    });
+    const selected = candidates.slice(0, input.maxSelectedFamilies ?? 3);
+    return {
+        families: selected,
+        generatedAt: new Date().toISOString(),
+        warnings: selected.length === 0
+            ? [`No API families with at least two signal kinds were discovered under ${input.root}.`]
+            : [],
+    };
+}
+export function scoreFamily(signals) {
+    const count = (kind) => signals.filter((signal) => signal.kind === kind).length;
+    return count('endpoint-constant') * 4
+        + count('request-wrapper') * 3
+        + count('capture-support') * 2
+        + count('spec-reference');
+}
+function hasEnoughEvidence(family) {
+    return new Set(family.consumerSignals.map((signal) => signal.kind)).size >= 2;
+}
+function collectEndpointSignals(source, drafts) {
+    for (const line of source.body.split(/\r?\n/)) {
+        const endpointMatches = [...line.matchAll(/(?:const|let|var|export\s+const)?\s*([A-Z0-9_]+)?\s*=?\s*['"`]([^'"`]*(?:\/platform\/|\/rs2\/)[^'"`]*)['"`]/gi)];
+        for (const match of endpointMatches) {
+            const rawPath = match[2];
+            if (!rawPath) {
+                continue;
+            }
+            const normalizedPath = normalizeApiPath(rawPath);
+            const family = inferFamily(normalizedPath);
+            if (!family) {
+                continue;
+            }
+            const draft = getDraft(drafts, family);
+            draft.normalizedPaths.add(normalizedPath);
+            draft.consumerSignals.push({
+                kind: 'endpoint-constant',
+                path: source.path,
+                name: match[1],
+                snippet: line.trim(),
+            });
+        }
+    }
+}
+function collectWrapperSignals(source, drafts) {
+    if (!/cy\.request|fetch\(|XMLHttpRequest|\brequest\s*\(/i.test(source.body)) {
+        return;
+    }
+    const commandNames = [...source.body.matchAll(/Cypress\.Commands\.add\((?:'|")([^'"]+)(?:'|")/g)]
+        .map((match) => match[1])
+        .filter((value) => Boolean(value));
+    const families = familiesReferencedBySource(source, drafts);
+    for (const family of families) {
+        getDraft(drafts, family).consumerSignals.push({
+            kind: 'request-wrapper',
+            path: source.path,
+            name: commandNames.join(', ') || path.basename(source.path),
+            snippet: firstMatchingLine(source.body, /cy\.request|fetch\(|XMLHttpRequest|\brequest\s*\(/i),
+        });
+    }
+}
+function collectCaptureSignals(source, drafts) {
+    if (!/apiCapture/i.test(source.body)) {
+        return;
+    }
+    for (const family of familiesReferencedBySource(source, drafts)) {
+        getDraft(drafts, family).consumerSignals.push({
+            kind: 'capture-support',
+            path: source.path,
+            snippet: firstMatchingLine(source.body, /apiCapture/i),
+        });
+    }
+}
+function familiesReferencedBySource(source, drafts) {
+    const directFamilies = new Set();
+    for (const endpoint of extractApiPaths(source.body)) {
+        const family = inferFamily(endpoint);
+        if (family) {
+            directFamilies.add(family);
+        }
+    }
+    if (directFamilies.size > 0) {
+        return [...directFamilies];
+    }
+    const importedNames = [...source.body.matchAll(/\b([A-Z][A-Z0-9_]+_ENDPOINT)\b/g)]
+        .map((match) => match[1])
+        .filter((value) => Boolean(value))
+        .map((value) => value.toLowerCase());
+    return [...drafts.entries()]
+        .filter(([family, draft]) => {
+        const familyToken = family.toLowerCase().replace(/[^a-z0-9]+/g, '_');
+        return importedNames.some((name) => name.includes(familyToken))
+            || [...draft.normalizedPaths].some((endpoint) => source.body.includes(endpoint));
+    })
+        .map(([family]) => family);
+}
+function extractApiPaths(body) {
+    return [...body.matchAll(/['"`]([^'"`]*(?:\/platform\/|\/rs2\/)[^'"`]*)['"`]/gi)]
+        .map((match) => match[1])
+        .filter((value) => Boolean(value))
+        .map((value) => normalizeApiPath(value));
+}
+function normalizeApiPath(value) {
+    const withoutHost = value.replace(/^https?:\/\/[^/]+/i, '');
+    const withoutQuery = withoutHost.split('?')[0] ?? withoutHost;
+    return withoutQuery.startsWith('/') ? withoutQuery : `/${withoutQuery}`;
+}
+function inferFamily(normalizedPath) {
+    const segments = normalizedPath.split('/').filter(Boolean);
+    const rs2Index = segments.findIndex((segment) => segment.toLowerCase() === 'rs2');
+    const rs2Family = segments[rs2Index + 1];
+    if (rs2Index >= 0 && rs2Family) {
+        return rs2Family.toLowerCase();
+    }
+    const platformIndex = segments.findIndex((segment) => segment.toLowerCase() === 'platform');
+    const platformFamily = segments[platformIndex + 1];
+    if (platformIndex >= 0 && platformFamily) {
+        return platformFamily.toLowerCase();
+    }
+    return segments.find((segment) => !/^(api|rest|v\d+)$/i.test(segment))?.toLowerCase();
+}
+function getDraft(drafts, family) {
+    const existing = drafts.get(family);
+    if (existing) {
+        return existing;
+    }
+    const draft = {
+        normalizedPaths: new Set(),
+        consumerSignals: [],
+    };
+    drafts.set(family, draft);
+    return draft;
+}
+function dedupeSignals(signals) {
+    const seen = new Set();
+    const result = [];
+    for (const signal of signals) {
+        const key = `${signal.kind}:${toPosixPath(signal.path)}:${signal.name ?? ''}:${signal.snippet}`;
+        if (!seen.has(key)) {
+            seen.add(key);
+            result.push(signal);
+        }
+    }
+    return result;
+}
+function firstMatchingLine(body, pattern) {
+    return body.split(/\r?\n/).find((line) => pattern.test(line))?.trim() ?? body.slice(0, 160);
+}

package/dist/src/indexer/extractors/apiInteractionExtractor.d.ts

@@ -0,0 +1,23 @@
+import type { ApiDiscoveryCatalog } from './apiDiscoveryExtractor.js';
+export type ApiInteractionRecord = {
+    id: string;
+    title: string;
+    path: string;
+    body: string;
+    sourceKind: 'api-interaction';
+    repoKind: 'autotests2';
+    metadata: {
+        apiFamily: string;
+        normalizedPaths: string[];
+        consumerSignalIds: string[];
+        evidencePaths: string[];
+        confidence: number;
+        whySelected: string[];
+    };
+};
+export declare function extractApiInteractions(input: {
+    catalog: ApiDiscoveryCatalog;
+}): {
+    documents: ApiInteractionRecord[];
+    warnings: string[];
+};

package/dist/src/indexer/extractors/apiInteractionExtractor.js

@@ -0,0 +1,35 @@
+export function extractApiInteractions(input) {
+    const documents = input.catalog.families
+        .map((family) => {
+        const consumerSignalIds = family.consumerSignals.map((signal, index) => `${signal.kind}:${signal.path}:${signal.name ?? index}`);
+        const evidencePaths = [...new Set(family.consumerSignals.map((signal) => signal.path))].sort();
+        const confidence = Math.min(1, family.score / 10);
+        const body = [
+            `API family: ${family.family}`,
+            `Normalized paths: ${family.normalizedPaths.join(', ')}`,
+            `Consumer evidence: ${family.consumerSignals.map((signal) => `${signal.kind} ${signal.name ?? ''} ${signal.snippet}`).join('\n')}`,
+            `Why selected: ${family.whySelected.join('\n')}`,
+        ].join('\n');
+        return {
+            id: `api-interaction:${family.family}`,
+            title: `API interaction: ${family.family}`,
+            path: evidencePaths[0] ?? `api-discovery/${family.family}`,
+            body,
+            sourceKind: 'api-interaction',
+            repoKind: 'autotests2',
+            metadata: {
+                apiFamily: family.family,
+                normalizedPaths: family.normalizedPaths,
+                consumerSignalIds,
+                evidencePaths,
+                confidence,
+                whySelected: family.whySelected,
+            },
+        };
+    })
+        .filter((record) => record.metadata.confidence >= 0.7);
+    return {
+        documents,
+        warnings: documents.length === 0 ? ['No high-confidence API interaction documents were extracted.'] : [],
+    };
+}

package/dist/src/indexer/extractors/backendContractExtractor.d.ts

@@ -0,0 +1,26 @@
+import type { FocusedFisSource } from '../../connectors/fisPlatformConnector.js';
+export type { FocusedFisSource } from '../../connectors/fisPlatformConnector.js';
+export type BackendKnowledgeRecord = {
+    id: string;
+    title: string;
+    path: string;
+    body: string;
+    sourceKind: 'backend-endpoint';
+    repoKind: 'fis-platform';
+    metadata: {
+        httpMethod?: 'GET' | 'POST' | 'PUT' | 'DELETE';
+        endpointPath: string;
+        apiFamily: string;
+        paramNames: string[];
+        ruleHints: string[];
+        evidencePaths: string[];
+        confidence: number;
+        whyMatched: string[];
+    };
+};
+export declare function extractBackendContracts(input: {
+    sources: FocusedFisSource[];
+}): {
+    documents: BackendKnowledgeRecord[];
+    warnings: string[];
+};

package/dist/src/indexer/extractors/backendContractExtractor.js

@@ -0,0 +1,66 @@
+export function extractBackendContracts(input) {
+    const documents = input.sources.flatMap((source) => extractRecordsFromSource(source));
+    return {
+        documents,
+        warnings: documents.length === 0 ? ['No backend endpoint contracts were extracted from focused FIS Platform sources.'] : [],
+    };
+}
+function extractRecordsFromSource(source) {
+    const classPath = firstMatch(source.body, /@Path\(\s*"([^"]+)"\s*\)/);
+    const methodBlocks = [...source.body.matchAll(/@(GET|POST|PUT|DELETE)([\s\S]*?)(?=@(?:GET|POST|PUT|DELETE)|\n\s*}\s*$)/g)];
+    if (methodBlocks.length === 0 && classPath) {
+        return [createRecord(source, undefined, classPath, source.body)];
+    }
+    return methodBlocks.map((match) => {
+        const method = match[1];
+        const block = match[0];
+        const methodPath = firstMatch(block, /@Path\(\s*"([^"]+)"\s*\)/);
+        return createRecord(source, method, joinPaths(classPath, methodPath), block);
+    });
+}
+function createRecord(source, httpMethod, endpointPath, body) {
+    const resolvedEndpointPath = endpointPath ?? firstMatch(source.body, /@Path\(\s*"([^"]+)"\s*\)/) ?? '/';
+    const paramNames = [
+        ...extractMatches(body, /@QueryParam\(\s*"([^"]+)"\s*\)/g),
+        ...extractMatches(body, /@HeaderParam\(\s*"([^"]+)"\s*\)/g),
+    ].filter((value) => Boolean(value));
+    const ruleHints = extractRuleHints(body);
+    return {
+        id: `fis-platform:${source.matchedFamily}:${httpMethod ?? 'RESOURCE'}:${source.path}:${resolvedEndpointPath}`,
+        title: `${httpMethod ? `${httpMethod} ` : ''}${resolvedEndpointPath}`,
+        path: source.path,
+        body,
+        sourceKind: 'backend-endpoint',
+        repoKind: 'fis-platform',
+        metadata: {
+            httpMethod,
+            endpointPath: resolvedEndpointPath,
+            apiFamily: source.matchedFamily,
+            paramNames,
+            ruleHints,
+            evidencePaths: [source.path],
+            confidence: source.confidence,
+            whyMatched: source.whyMatched,
+        },
+    };
+}
+function joinPaths(base, child) {
+    const parts = [base, child]
+        .filter((part) => Boolean(part))
+        .map((part) => part.replace(/^\/+|\/+$/g, ''));
+    return `/${parts.join('/')}`.replace(/\/+/g, '/');
+}
+function firstMatch(body, pattern) {
+    return body.match(pattern)?.[1];
+}
+function extractMatches(body, pattern) {
+    return [...body.matchAll(pattern)].map((match) => match[1]);
+}
+function extractRuleHints(body) {
+    const hints = body
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter((line) => /validate|required|permission|async|task|complete|status|throw|Exception/i.test(line))
+        .slice(0, 8);
+    return hints;
+}

package/dist/src/indexer/refreshPipeline.js

@@ -2,6 +2,9 @@ import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 import { syncDocumentsByRepoKinds } from '../knowledge/repositories.js';
+import { buildApiDiscoveryCatalog } from './extractors/apiDiscoveryExtractor.js';
+import { extractApiInteractions } from './extractors/apiInteractionExtractor.js';
+import { extractBackendContracts } from './extractors/backendContractExtractor.js';
 import { extractFrontendContract } from './extractors/frontendContractExtractor.js';
 import { SnapshotStore } from './snapshotStore.js';
 import { ensureDirectory } from '../utils/fileUtils.js';
@@ -15,6 +18,13 @@ export async function refreshKnowledge(context) {
     if (fs.existsSync(context.config.repos.autotests2)) {
         repoKindsToSync.push('autotests2');
         const docs = context.autotests2.getAreaDocs();
+        const apiCatalog = await buildApiDiscoveryCatalog({
+            root: context.config.repos.autotests2,
+            maxSelectedFamilies: 3,
+        });
+        snapshotStore.write('api-discovery-catalog', apiCatalog);
+        const apiInteractions = extractApiInteractions({ catalog: apiCatalog });
+        snapshotStore.write('api-interactions', apiInteractions);
         const testAssets = {
             specs: await context.autotests2.findSpecs(),
             commands: await context.autotests2.findCommands(),
@@ -83,6 +93,36 @@ export async function refreshKnowledge(context) {
                 }));
             }
         }
+        for (const record of apiInteractions.documents) {
+            documents.push(documentFrom({
+                sourceKind: record.sourceKind,
+                repoKind: record.repoKind,
+                path: record.path,
+                title: record.title,
+                body: record.body,
+                metadata: record.metadata,
+                updatedAt: now,
+            }));
+        }
+        warnings.push(...apiCatalog.warnings, ...apiInteractions.warnings);
+        if (context.fisPlatform && context.config.repos.fisPlatform && fs.existsSync(context.config.repos.fisPlatform)) {
+            repoKindsToSync.push('fis-platform');
+            const backendSources = await context.fisPlatform.listFocusedSources(apiCatalog);
+            const backendContracts = extractBackendContracts({ sources: backendSources });
+            snapshotStore.write('backend-contracts', backendContracts);
+            for (const record of backendContracts.documents) {
+                documents.push(documentFrom({
+                    sourceKind: record.sourceKind,
+                    repoKind: record.repoKind,
+                    path: record.path,
+                    title: record.title,
+                    body: record.body,
+                    metadata: record.metadata,
+                    updatedAt: now,
+                }));
+            }
+            warnings.push(...backendContracts.warnings);
+        }
     }
     else {
         warnings.push(`Skipped autotests2 refresh because '${context.config.repos.autotests2}' is unavailable.`);

package/dist/src/mcp/registerTools.js

@@ -4,6 +4,7 @@ import { analyzeTestGaps } from '../domain/analyzeTestGaps.js';
 import { buildRerunScope } from '../domain/buildRerunScope.js';
 import { buildSetupTeardownPlan } from '../domain/buildSetupTeardownPlan.js';
 import { findExistingTestAssets } from '../domain/findExistingTestAssets.js';
+import { findBackendTestContext } from '../domain/findBackendTestContext.js';
 import { findFrontendContract } from '../domain/findFrontendContract.js';
 import { findFrontendRuntimeLogic } from '../domain/findFrontendRuntimeLogic.js';
 import { findTestAreaContext } from '../domain/findTestAreaContext.js';
@@ -22,6 +23,13 @@ export function buildToolRegistry() {
             outputSchema: toolOutputSchema,
             execute: findExistingTestAssets,
         },
+        {
+            name: 'find_backend_test_context',
+            description: 'Finds autotests2 API interaction flows plus backend endpoint, validation, async-task, and error hints.',
+            inputSchema: z.object({ query: z.string().min(1) }),
+            outputSchema: toolOutputSchema,
+            execute: findBackendTestContext,
+        },
         {
             name: 'find_test_area_context',
             description: 'Returns conventions, init patterns, and area context for constructor or formRunner.',

package/docs/operator-cookbook.md

@@ -5,8 +5,9 @@
 1. Run `find_existing_test_assets` for the target widget or feature.
 2. Run `find_frontend_contract`.
 3. Run `find_frontend_runtime_logic`.
-4. Run `generate_spec_blueprint`.
-5. Review reuse candidates, setup hints, and selector guidance before editing `autotests2`.
+4. For API-heavy flows, run `find_backend_test_context` to inspect `ApiDiscoveryCatalog`, `api-interaction`, and `backend-endpoint` evidence.
+5. Run `generate_spec_blueprint`.
+6. Review reuse candidates, setup hints, selector guidance, backend params, validation hints, and async completion hints before editing `autotests2`.
 
 ## Find coverage gaps
 
@@ -20,7 +21,17 @@
 1. Run `summarize_ci_context`.
 2. Run `triage_failed_run`.
 3. Run `build_rerun_scope`.
-4. If frontend files changed, run `analyze_diff_impact`.
+4. If frontend or backend files changed, run `analyze_diff_impact`.
+5. When API capture files exist, treat triage backend hints as evidence-backed hypotheses only when the capture path matches high-confidence `api-interaction` and `backend-endpoint` records.
+
+## Use backend indexing
+
+1. Set optional `repos.fisPlatform` to `../fis_platform` in `overkill.config.json`.
+2. Run `npm run index`; refresh builds `ApiDiscoveryCatalog` from `autotests2` support code before scanning backend sources.
+3. Review snapshots under `.overkill-cache/snapshots`: `api-discovery-catalog.json`, `api-interactions.json`, and `backend-contracts.json`.
+4. Use backend context for debugging request flows discovered from support code or API capture, generating API-heavy blueprints, triaging failures with API captures, and analyzing backend REST/resource diffs.
+5. Do not treat backend indexing as a hardcoded file allowlist. Discovery uses REST/JAX-RS signals and evidence metadata such as `confidence`, `whySelected`, `whyMatched`, `normalizedPaths`, and `evidencePaths`.
+6. Runtime API captures are on-demand in iteration 1; raw captures are not persisted to the knowledge store.
 
 ## Onboard a new engineer