@testmo/testmo-link 1.0.0-beta.0

package/dist/linking/annotationScanner.js

@@ -0,0 +1,745 @@
+"use strict";
+/*
+ * Copyright (c) Testmo GmbH (Berlin, Germany)
+ * All rights reserved.
+ * contact@testmo.com - www.testmo.com
+ */
+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.AnnotationScanner = void 0;
+exports.isSafePattern = isSafePattern;
+exports.toJestParamPattern = toJestParamPattern;
+exports.pendingBracketDepth = pendingBracketDepth;
+exports.extractTestName = extractTestName;
+exports.normalizeTestName = normalizeTestName;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const readline = __importStar(require("readline"));
+const glob_1 = require("glob");
+const logger_1 = require("../lib/logger");
+const errors_1 = require("../lib/errors");
+// Default annotation pattern
+const DEFAULT_PATTERNS = ['@TestmoId:(\\d+)'];
+// Warn when a file exceeds this size during streaming scan
+const LARGE_FILE_WARN_BYTES = 10 * 1024 * 1024; // 10MB
+// Lines to scan below an annotation looking for the test name (normal case)
+const NAME_SCAN_LINES = 8;
+// Gherkin structural keywords that do NOT represent individual test scenarios.
+// Scenario / Scenario Outline / Example / i18n equivalents are intentionally absent.
+const GHERKIN_NON_SCENARIO_KEYWORDS = new Set([
+    'feature', 'background', 'examples', 'rule',
+    'given', 'when', 'then', 'and', 'but',
+]);
+// Absolute upper bound — prevents runaway accumulation when inside a very large
+// multi-line decorator argument list or a malformed file
+const MAX_SCAN_LINES = 100;
+/**
+ * Validates that a regex pattern does not contain constructs known to cause
+ * catastrophic backtracking (nested quantifiers).
+ */
+function isSafePattern(pattern) {
+    // Reject patterns with nested quantifiers like (a+)+ or (\w*)*
+    if (/\([^)]*[\+\*\?][^)]*\)[\+\*\{]/.test(pattern)) {
+        return false;
+    }
+    // Reject alternation inside repeated groups like (a|b)+
+    if (/\([^)]*\|[^)]*\)[\+\*\{]/.test(pattern)) {
+        return false;
+    }
+    return true;
+}
+/**
+ * Returns true if the line is a decorator, attribute, blank, or comment line
+ * that should be skipped when extracting the test name after an annotation.
+ */
+function isDecoratorLine(line) {
+    const t = line.trim();
+    return (!t ||
+        t.startsWith('@') || // Python/Java/Kotlin/Go decorators
+        t.startsWith('[') || // C# attributes
+        t.startsWith('//') || // single-line comments (already consumed annotation)
+        t.startsWith('#') || // Python/Ruby comments
+        t.startsWith('*') || // Javadoc continuation
+        t.startsWith('/*') || // block comment open
+        t.startsWith('--') // SQL / Lua comments
+    );
+}
+/**
+ * Convert a Ruby test name containing string interpolation (#{...}) to a RegExp
+ * for loose matching against resolved test names from the runner.
+ * "grants access to #{role}" → /^grants access to .+$/
+ * Returns undefined if the name contains no interpolation.
+ */
+function toInterpolationPattern(name) {
+    if (!name.includes('#{'))
+        return undefined;
+    const parts = name.split(/#\{[^}]*\}/);
+    // Require at least 3 characters of literal text combined to avoid catch-all patterns
+    // e.g. "#{name}" → literal="" → skip; "grants access to #{role}" → literal="grants access to " → ok
+    if (parts.join('').trim().length < 3)
+        return undefined;
+    const escaped = parts.map(p => p.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'));
+    return new RegExp(`^${escaped.join('.+')}$`);
+}
+/**
+ * Convert a Jest test.each name containing placeholders to a RegExp for loose
+ * matching against the generated test names that Jest produces at runtime.
+ *
+ * Handles two placeholder styles:
+ *   - printf-style: %s, %d, %i, %f, %o, %#, %p (inline array form)
+ *     "should grant access to %s role" → /^should grant access to .+ role$/i
+ *   - template-literal $variable style (tagged template form)
+ *     "should add $a + $b = $expected" → /^should add .+ \+ .+ = .+$/i
+ *
+ * Returns undefined if the name contains no placeholders, or if the combined
+ * literal text is too short (< 3 chars) to produce a safe, non-catch-all pattern.
+ */
+function toJestParamPattern(name) {
+    const hasPrintf = /%[sdifo#p]/i.test(name);
+    // Match both $var (tagged template) and ${expression} (inline template literal) styles.
+    // ${expression} covers patterns like `should login as ${user.role} user` produced by
+    // Cypress forEach loops (TMD-2124). The split regex below includes both placeholder
+    // forms so we can build a matching pattern for the resolved runtime test names.
+    const hasTemplate = /\$[A-Za-z_][A-Za-z0-9_]*/.test(name) || /\$\{[^}]+\}/.test(name);
+    if (!hasPrintf && !hasTemplate)
+        return undefined;
+    const parts = name.split(/(?:%[sdifo#p]|\$\{[^}]+\}|\$[A-Za-z_][A-Za-z0-9_]*)/gi);
+    // Require at least 3 chars of literal text to avoid overly broad patterns
+    if (parts.join('').trim().length < 3)
+        return undefined;
+    const escaped = parts.map(p => p.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'));
+    return new RegExp(`^${escaped.join('.+')}$`, 'i');
+}
+/**
+ * Returns the net open bracket depth of the accumulated lookahead lines,
+ * considering only decorator-initiated lines as bracket-tracked context.
+ * A value > 0 means we are still inside a multi-line decorator argument list
+ * and should keep accumulating lines before attempting name extraction.
+ */
+function pendingBracketDepth(lines) {
+    let depth = 0;
+    for (const line of lines) {
+        const t = line.trim();
+        if (depth > 0 || t.startsWith('@') || t.startsWith('[')) {
+            for (const ch of t) {
+                if (ch === '(' || ch === '[')
+                    depth++;
+                else if (ch === ')' || ch === ']')
+                    depth--;
+            }
+        }
+    }
+    return Math.max(0, depth);
+}
+/**
+ * Extract the test name from the lines immediately following an annotation.
+ * Tries language-specific patterns in priority order, then a generic fallback.
+ * Returns the extracted name, or undefined if no pattern matched.
+ */
+function extractTestName(lines) {
+    var _a, _b;
+    let inBlockComment = false;
+    let inRubyBlockComment = false;
+    // Tracks unmatched open brackets inside a decorator's argument list so that
+    // multi-line decorators like @pytest.mark.parametrize("a", [\n  (1,2),\n])
+    // are fully skipped before we attempt to extract the function name (TMD-2044).
+    let decoratorDepth = 0;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const t = line.trim();
+        // Track C#/Java/JS /* ... */ multi-line block comments
+        if (inBlockComment) {
+            if (t.includes('*/'))
+                inBlockComment = false;
+            continue;
+        }
+        if (t.startsWith('/*') && !t.includes('*/')) {
+            inBlockComment = true;
+            // fall through to isDecoratorLine which also skips the opening line
+        }
+        // Track Ruby =begin...=end block comments
+        if (t === '=begin') {
+            inRubyBlockComment = true;
+            continue;
+        }
+        if (inRubyBlockComment) {
+            if (t === '=end')
+                inRubyBlockComment = false;
+            continue;
+        }
+        // If inside a multi-line decorator argument list, keep skipping until brackets balance
+        if (decoratorDepth > 0) {
+            for (const ch of t) {
+                if (ch === '(' || ch === '[')
+                    decoratorDepth++;
+                else if (ch === ')' || ch === ']')
+                    decoratorDepth--;
+            }
+            continue;
+        }
+        if (isDecoratorLine(line)) {
+            // Only count brackets on actual decorator/attribute lines — not on
+            // comments, blank lines, or Javadoc/block-comment lines, which may
+            // contain unmatched brackets (e.g. `# Returns list of (valid, invalid)`)
+            // that would corrupt the depth count and cause real code lines to be skipped.
+            if (t.startsWith('@') || t.startsWith('[')) {
+                for (const ch of t) {
+                    if (ch === '(' || ch === '[')
+                        decoratorDepth++;
+                    else if (ch === ')' || ch === ']')
+                        decoratorDepth--;
+                }
+            }
+            continue;
+        }
+        // JS/TS: it/test/describe with a restricted set of known dot-modifiers (skip, only,
+        // fixme, fail, parallel, serial). Using a closed list instead of (?:\.[a-z]+)? prevents
+        // false positives on non-test helpers like test.step('label', fn) or test.use({...}).
+        // All patterns also require a comma after the name to avoid matching bare fn('string')
+        // calls that happen to follow an annotation.
+        // context() and specify() are Cypress aliases for describe() and it() respectively
+        // (TMD-2124) and are treated identically for name extraction purposes.
+        // Shape A of test.each: test.each(data)('name', fn) — greedy .* skips all data,
+        // then backtracking finds the )( boundary before the test name string.
+        // The fallback's ^ anchor prevents method-chain calls like todoPage.fill('selector')
+        // from matching; only the known test modifiers skip/only/fixme/fail/parallel/serial/concurrent are allowed after the dot.
+        const jsMatch = (_b = (_a = t.match(/\b(?:it|test|describe|context|specify)(?:\.(?:skip|only|fixme|fail|parallel|serial|concurrent))?\s*\(\s*['"`]([^'"`]+)['"`]\s*,/)) !== null && _a !== void 0 ? _a : t.match(/\b(?:it|test)\.each.*\)\s*\(\s*['"`]([^'"`]+)['"`]\s*,/)) !== null && _b !== void 0 ? _b : t.match(/^[A-Za-z_$][A-Za-z0-9_$]*(?:\.(?:skip|only|fixme|fail|concurrent))?\s*\(\s*['"`]([^'"`]+)['"`]\s*,/);
+        if (jsMatch)
+            return jsMatch[1];
+        // JS/TS: test.each / it.each tagged template literal form (Shape B).
+        // The test name is on the closing backtick line several lines below the annotation:
+        //   test.each`          ← first real line after annotation
+        //     a | b
+        //     1 | 2
+        //   `('name', fn)       ← name extracted from here
+        // Comma is required after the name — a bare `('name')` without a callback is not a test.
+        if (/\b(?:it|test)\.each\s*`/.test(t)) {
+            for (let j = i + 1; j < lines.length; j++) {
+                const m = lines[j].trim().match(/^`\s*\(\s*['"`]([^'"`]+)['"`]\s*,/);
+                if (m)
+                    return m[1];
+            }
+            return undefined;
+        }
+        // JS/TS: test.each / it.each Shape A multi-line form — when the data argument
+        // and the test name call are split across lines:
+        //   test.each(['a', 'b'])(       ← first line after annotation (no name yet)
+        //     'test name %s',            ← name is here
+        //     (v) => { ... }
+        // or with multi-line data:
+        //   test.each([                  ← data spans several lines
+        //     ['a', true], ['b', false]
+        //   ])('test name %s', ...)      ← name on the closing-bracket line
+        if (/\b(?:it|test)\.each\b/.test(t) && !t.includes('`')) {
+            let depth = 0;
+            for (const ch of t) {
+                if (ch === '(' || ch === '[')
+                    depth++;
+                else if (ch === ')' || ch === ']')
+                    depth--;
+            }
+            for (let j = i + 1; j < lines.length; j++) {
+                const next = lines[j].trim();
+                if (!next)
+                    continue;
+                // ')(' pattern on a single line: data closes and name call opens
+                const m1 = next.match(/\)\s*\(\s*['"`]([^'"`]+)['"`]\s*,/);
+                if (m1)
+                    return m1[1];
+                // depth 1 means we're inside the name call parens: look for string arg
+                if (depth <= 1) {
+                    const m2 = next.match(/^\(?['"`]([^'"`]+)['"`]\s*,/);
+                    if (m2)
+                        return m2[1];
+                }
+                for (const ch of next) {
+                    if (ch === '(' || ch === '[')
+                        depth++;
+                    else if (ch === ')' || ch === ']')
+                        depth--;
+                }
+                if (depth < 0)
+                    break;
+            }
+            return undefined;
+        }
+        // Ruby: it/fit/xit/pending/example 'name' / describe/fdescribe 'name' / context/specify 'name'
+        const rubyMatch = t.match(/\b(?:it|fit|xit|pending|describe|fdescribe|context|specify|example)\s+['"]([^'"]+)['"]/);
+        if (rubyMatch)
+            return rubyMatch[1];
+        // Python: def name( / async def name(
+        const pythonMatch = t.match(/\bdef\s+(\w+)\s*\(/);
+        if (pythonMatch)
+            return pythonMatch[1];
+        // Kotlin: fun `test description with spaces`()
+        const kotlinBacktick = t.match(/\bfun\s+`([^`]+)`/);
+        if (kotlinBacktick)
+            return kotlinBacktick[1];
+        // Cucumber/Gherkin: Scenario: / Scenario Outline: / Scenario Template: /
+        // Example: (Gherkin 6+) / and i18n equivalents (Scénario:, シナリオ:, etc.)
+        // Matches any "Keyword: name" line; strips trailing inline comment.
+        // Non-scenario structural keywords (Feature, Background, Examples, Rule) are skipped.
+        const gherkinMatch = t.match(/^([\w\s\u00C0-\uFFFF]+?):\s+(.+)$/u);
+        if (gherkinMatch) {
+            const keyword = gherkinMatch[1].trim().toLowerCase();
+            if (!GHERKIN_NON_SCENARIO_KEYWORDS.has(keyword)) {
+                const name = gherkinMatch[2].trim().replace(/\s+#.*$/, '').trim();
+                if (name)
+                    return name;
+            }
+        }
+        // Generic: last identifier before ( — covers Java, C#, Go, PHP, Kotlin, Rust, Swift, etc.
+        // matchAll finds every word( occurrence; we take the last non-keyword one.
+        const allMatches = [...t.matchAll(/\b(\w+)\s*\(/g)];
+        if (allMatches.length > 0) {
+            const skip = new Set([
+                'if', 'for', 'while', 'switch', 'catch', 'return',
+                'new', 'throw', 'import', 'export', 'class', 'interface',
+                'enum', 'struct', 'impl', 'super', 'this', 'typeof', 'instanceof',
+                'function',
+            ]);
+            for (let i = allMatches.length - 1; i >= 0; i--) {
+                const m = allMatches[i];
+                const name = m[1];
+                // Skip names that are attribute/subscript calls, e.g. [Values(1, 2, 3)]
+                const precededByBracket = m.index > 0 && t[m.index - 1] === '[';
+                if (name.length >= 3 && !skip.has(name) && !precededByBracket)
+                    return name;
+            }
+        }
+        break; // stop after the first non-decorator line
+    }
+    return undefined;
+}
+/**
+ * Normalize a test name for matching:
+ * - strips parameterized suffixes: test_login[admin]           → test_login
+ * - strips JUnit 5 typed suffixes: testLogin(String)[1]        → testLogin
+ * - strips TestNG / NUnit row suffixes: login (row 1)          → login
+ * - strips JUnit 5 / Kotlin Surefire empty parens: testLogin() → testLogin
+ * - strips PHPUnit data provider suffixes: test with data set "x" → test
+ * - strips Go subtest paths: TestLogin/admin                   → TestLogin
+ * - lowercases and trims
+ */
+function normalizeTestName(name) {
+    return name
+        .replace(/\(.*?\)\[\d+\]$/, '') // (Type)[N]          — JUnit 5 parameterized
+        .replace(/\[.*?\]$/, '') // [param]            — pytest / JUnit 5
+        .replace(/\s*\(\s*row\s*\d+\s*\)$/i, '') // (row N)            — NUnit / TestNG
+        .replace(/\s*\([^)]*,[^)]*\)$/, '') // (a, b, ...)        — Cucumber Scenario Outline
+        .replace(/([A-Za-z0-9_])\(\s*\)$/, '$1') // ()                 — JUnit 5 / Kotlin Surefire (only after word char, not special chars like &*)
+        .replace(/\s+with data set\s+.*$/i, '') // with data set ...  — PHPUnit data providers
+        .replace(/^(Test\w+)\/.+$/, '$1') // TestFoo/subtest    — Go subtests
+        .trim()
+        .toLowerCase();
+}
+/**
+ * Return the last segment of a describe-prefixed test name.
+ * "Authentication > should login" → "should login"
+ * Returns undefined if no separator is found.
+ */
+function getLastSegment(name) {
+    const separators = [' > ', ' / ', ' :: ', ' — ', ' - '];
+    for (const sep of separators) {
+        const idx = name.lastIndexOf(sep);
+        if (idx >= 0)
+            return name.slice(idx + sep.length).trim();
+    }
+    return undefined;
+}
+/**
+ * Scans source files for @TestmoId annotations, extracts the name of the
+ * test immediately following each annotation, and builds a name-based index
+ * for matching against test results.
+ *
+ * Matching requires only test.name (always present in results). The optional
+ * test.file attribute is used to disambiguate when the same test name appears
+ * in multiple files.
+ */
+class AnnotationScanner {
+    constructor(config) {
+        var _a, _b;
+        this.annotationsByName = new Map();
+        this.annotationsByPattern = [];
+        this.warnedAmbiguous = new Set();
+        this.basePath = path.resolve((_a = config.base_path) !== null && _a !== void 0 ? _a : process.cwd());
+        const rawPatterns = ((_b = config.patterns) === null || _b === void 0 ? void 0 : _b.length) ? config.patterns : DEFAULT_PATTERNS;
+        this.compiledPatterns = [];
+        for (const raw of rawPatterns) {
+            if (!isSafePattern(raw)) {
+                logger_1.logger.warn(`Skipping unsafe annotation pattern (potential ReDoS): ${raw}`);
+                continue;
+            }
+            try {
+                this.compiledPatterns.push(new RegExp(raw, 'g'));
+            }
+            catch (e) {
+                throw new errors_1.PatternError(raw, e.message);
+            }
+        }
+    }
+    /**
+     * Scan all files matching the given glob patterns and extract annotations.
+     */
+    async scan(globPatterns) {
+        if (!globPatterns.length)
+            return;
+        const files = await (0, glob_1.glob)(globPatterns, {
+            cwd: this.basePath,
+            nodir: true,
+            absolute: false,
+        });
+        if (files.length === 0) {
+            logger_1.logger.warn(`No files matched annotation scanning paths: ${globPatterns.join(', ')}`);
+            return;
+        }
+        logger_1.logger.debug(`Scanning ${files.length} file(s) for annotations`);
+        for (const relFile of files) {
+            const absPath = path.join(this.basePath, relFile);
+            await this.parseFile(relFile, absPath);
+        }
+    }
+    /**
+     * Stream a single file line-by-line, extracting annotations and the test
+     * name immediately following each one using a small lookahead window.
+     */
+    async parseFile(relFile, absPath) {
+        var _a;
+        try {
+            const stat = fs.statSync(absPath);
+            if (stat.size > LARGE_FILE_WARN_BYTES) {
+                logger_1.logger.warn(`Large file (${Math.round(stat.size / 1024 / 1024)}MB) during annotation scan: ${relFile}`);
+            }
+        }
+        catch (_b) {
+            return;
+        }
+        const rawAnnotations = [];
+        let lineNum = 0;
+        let pendingAnnotation;
+        let pendingLines = [];
+        // Running bracket depth for the current lookahead window.
+        // Tracks unclosed ( [ from decorator lines so we know whether we are still
+        // inside a multi-line decorator argument list when deciding to flush.
+        let pendingDecoratorDepth = 0;
+        const resolvePending = () => {
+            var _a, _b;
+            if (!pendingAnnotation)
+                return;
+            const extractedName = (_b = (_a = extractTestName(pendingLines)) === null || _a === void 0 ? void 0 : _a.trim().toLowerCase()) !== null && _b !== void 0 ? _b : '';
+            for (const caseId of pendingAnnotation.caseIds) {
+                rawAnnotations.push({ line: pendingAnnotation.line, caseId, extractedName });
+            }
+            pendingAnnotation = undefined;
+            pendingLines = [];
+            pendingDecoratorDepth = 0;
+        };
+        await new Promise((resolve) => {
+            let stream;
+            try {
+                stream = fs.createReadStream(absPath, { encoding: 'utf8' });
+            }
+            catch (_a) {
+                resolve();
+                return;
+            }
+            const rl = readline.createInterface({ input: stream, crlfDelay: Infinity });
+            stream.on('error', () => { rl.close(); resolve(); });
+            rl.on('line', (line) => {
+                lineNum++;
+                // Check for a new annotation on this line first
+                const newCaseIds = [];
+                for (const pattern of this.compiledPatterns) {
+                    pattern.lastIndex = 0;
+                    let match;
+                    while ((match = pattern.exec(line)) !== null) {
+                        const caseId = parseInt(match[1], 10);
+                        if (!isNaN(caseId) && caseId >= 1) {
+                            newCaseIds.push(caseId);
+                            // Also extract comma-separated IDs that follow this match
+                            // e.g. @TestmoId:100,200,300
+                            let pos = match.index + match[0].length;
+                            while (pos < line.length) {
+                                const extra = /^,\s*(\d+)/.exec(line.slice(pos));
+                                if (!extra)
+                                    break;
+                                const extraId = parseInt(extra[1], 10);
+                                if (!isNaN(extraId) && extraId >= 1)
+                                    newCaseIds.push(extraId);
+                                pos += extra[0].length;
+                            }
+                        }
+                    }
+                }
+                if (newCaseIds.length > 0) {
+                    if (pendingAnnotation && pendingLines.length === 0) {
+                        // Consecutive annotation lines before a test — accumulate all case IDs
+                        for (const id of newCaseIds)
+                            pendingAnnotation.caseIds.push(id);
+                    }
+                    else {
+                        // New annotation group: commit any pending and start fresh
+                        resolvePending();
+                        pendingAnnotation = { line: lineNum, caseIds: newCaseIds };
+                        pendingLines = [];
+                        pendingDecoratorDepth = 0;
+                    }
+                }
+                else if (pendingAnnotation) {
+                    // Collect lookahead lines for name extraction.
+                    // Suppress the NAME_SCAN_LINES cap while inside a multi-line
+                    // decorator argument list (e.g. @pytest.mark.parametrize with
+                    // many rows); fall back to MAX_SCAN_LINES as an absolute ceiling.
+                    pendingLines.push(line);
+                    // Maintain running bracket depth for decorator lines so we can
+                    // detect multi-line argument lists without rescanning every time.
+                    const prevDepth = pendingDecoratorDepth;
+                    const t = line.trim();
+                    if (pendingDecoratorDepth > 0 || t.startsWith('@') || t.startsWith('[')) {
+                        for (const ch of t) {
+                            if (ch === '(' || ch === '[')
+                                pendingDecoratorDepth++;
+                            else if (ch === ')' || ch === ']')
+                                pendingDecoratorDepth--;
+                        }
+                        if (pendingDecoratorDepth < 0)
+                            pendingDecoratorDepth = 0;
+                    }
+                    // justClosedDecorator: depth just reached 0 on this line (e.g. the
+                    // "])" closing line). The def is on the NEXT line — defer the flush.
+                    const justClosedDecorator = prevDepth > 0 && pendingDecoratorDepth === 0;
+                    if (pendingLines.length >= MAX_SCAN_LINES ||
+                        (pendingLines.length >= NAME_SCAN_LINES &&
+                            pendingDecoratorDepth === 0 &&
+                            !justClosedDecorator)) {
+                        resolvePending();
+                    }
+                }
+            });
+            rl.on('close', () => {
+                resolvePending();
+                resolve();
+            });
+        });
+        // Index by extracted name
+        const normalized = relFile.replace(/\\/g, '/');
+        for (const ann of rawAnnotations) {
+            if (!ann.extractedName) {
+                logger_1.logger.debug(`No test name found after annotation at ${normalized}:${ann.line} ` +
+                    `(case ${ann.caseId}) — annotation will not be matched`);
+                continue;
+            }
+            const entry = {
+                extractedName: ann.extractedName,
+                file: normalized,
+                caseId: ann.caseId,
+                line: ann.line,
+            };
+            const existing = (_a = this.annotationsByName.get(ann.extractedName)) !== null && _a !== void 0 ? _a : [];
+            existing.push(entry);
+            this.annotationsByName.set(ann.extractedName, existing);
+            // Also index by interpolation pattern for Ruby names like "grants access to #{role}"
+            const interpolationPattern = toInterpolationPattern(ann.extractedName);
+            if (interpolationPattern) {
+                this.annotationsByPattern.push({ pattern: interpolationPattern, annotation: entry });
+            }
+            // Index by Jest printf pattern for names like "should grant access to %s role"
+            const jestParamPattern = toJestParamPattern(ann.extractedName);
+            if (jestParamPattern) {
+                this.annotationsByPattern.push({ pattern: jestParamPattern, annotation: entry });
+            }
+        }
+    }
+    /**
+     * Returns true if the test result's folder string corresponds to the
+     * annotation's source file. Used as a fallback when testFile is absent
+     * or insufficient for disambiguation.
+     *
+     * Strategy: use only the last segment of the folder (e.g. "UserManagementTests"
+     * from "com.example.tests.user.UserManagementTests") and check whether it is
+     * contained in the file's basename (without extension). Using intermediate
+     * segments would cause generic ones like "tests" to match every file.
+     */
+    static folderMatchesFile(folder, filePath) {
+        var _a;
+        if (!folder)
+            return false;
+        const baseName = path.basename(filePath).replace(/\.[^.]+$/, '').toLowerCase();
+        if (baseName.length < 3)
+            return false;
+        // Use only the last segment of the folder (handles FQCN like
+        // "com.example.tests.user.UserManagementTests" → "UserManagementTests").
+        // Using all segments would cause intermediate ones like "tests" to
+        // match every file whose basename ends in "Tests".
+        const parts = folder.split(/[./\\]+/).filter(Boolean);
+        const lastSegment = ((_a = parts[parts.length - 1]) !== null && _a !== void 0 ? _a : '').toLowerCase();
+        if (lastSegment.length < 5)
+            return false;
+        return baseName.includes(lastSegment) || lastSegment.includes(baseName);
+    }
+    /**
+     * Find the repository case ID for a test given its name.
+     *
+     * Matching is performed against the name extracted from the source file
+     * immediately below each annotation. The optional testFile is used to
+     * disambiguate when two files contain annotations with the same name.
+     * When testFile is absent, testFolder is tried as a fallback by matching
+     * folder segments against source file basenames.
+     *
+     * @param testName    Test name from the run result (always present)
+     * @param testFile    Optional source file path (used for disambiguation)
+     * @param testFolder  Optional test suite/class folder (fallback disambiguation)
+     * @returns The matched case ID, or undefined if no unambiguous match found
+     */
+    findCaseId(testName, testFile, testFolder) {
+        const ids = this.findCaseIds(testName, testFile, testFolder);
+        return ids.length > 0 ? ids[0] : undefined;
+    }
+    /**
+     * Returns all repository case IDs linked to a test via annotations.
+     * For multi-case annotations (multiple @TestmoId on one test), returns all IDs.
+     * Returns an empty array when no match is found or when the same test name
+     * appears in multiple files (true ambiguity).
+     */
+    findCaseIds(testName, testFile, testFolder) {
+        const normalized = normalizeTestName(testName);
+        // Try exact name match
+        let results = this.resolveAllByName(normalized, testFile, testFolder);
+        if (results.length > 0)
+            return results;
+        // Try suffix match for describe-prefixed names ("Suite > test name")
+        const segment = getLastSegment(normalized);
+        if (segment) {
+            results = this.resolveAllByName(segment, testFile, testFolder);
+            if (results.length > 0)
+                return results;
+        }
+        // Try interpolation-pattern match for Ruby names like "grants access to #{role}"
+        const patResults = this.resolveAllByPattern(normalized, testFile, testFolder);
+        if (patResults.length > 0)
+            return patResults;
+        if (segment) {
+            const segResults = this.resolveAllByPattern(segment, testFile, testFolder);
+            if (segResults.length > 0)
+                return segResults;
+        }
+        return [];
+    }
+    resolveByPattern(name, testFile, testFolder) {
+        const ids = this.resolveAllByPattern(name, testFile, testFolder);
+        return ids.length > 0 ? ids[0] : undefined;
+    }
+    resolveAllByPattern(name, testFile, testFolder) {
+        const candidates = this.annotationsByPattern
+            .filter(({ pattern }) => pattern.test(name))
+            .map(({ annotation }) => annotation);
+        if (candidates.length === 0)
+            return [];
+        // Narrow by file/folder using the same fallback logic as resolveAllByName
+        let pool = candidates;
+        if (testFile) {
+            const normFile = testFile.replace(/\\/g, '/');
+            const fileMatches = candidates.filter(c => c.file === normFile ||
+                c.file.endsWith('/' + normFile) ||
+                normFile.endsWith('/' + c.file));
+            if (fileMatches.length > 0)
+                pool = fileMatches;
+        }
+        if (pool === candidates && testFolder) {
+            const folderMatches = candidates.filter(c => AnnotationScanner.folderMatchesFile(testFolder, c.file));
+            if (folderMatches.length > 0)
+                pool = folderMatches;
+        }
+        // All from same file → return all case IDs (de-duplicated)
+        const files = new Set(pool.map(c => c.file));
+        if (files.size === 1) {
+            return [...new Set(pool.map(c => c.caseId))];
+        }
+        // Still ambiguous — warn once per name
+        if (!this.warnedAmbiguous.has(name)) {
+            this.warnedAmbiguous.add(name);
+            const detail = pool.map(c => `${c.file}→case ${c.caseId}`).join(', ');
+            logger_1.logger.warn(`Annotation ambiguous for "${name}": multiple interpolation patterns matched ` +
+                `(${detail}). Include the file attribute in test results, or use ` +
+                `config_mappings to resolve.`);
+        }
+        return [];
+    }
+    resolveAllByName(name, testFile, testFolder) {
+        const candidates = this.annotationsByName.get(name);
+        if (!candidates || candidates.length === 0)
+            return [];
+        // Narrow to best-matching file if disambiguation hints are available.
+        // Try testFile first; fall through to testFolder if testFile matched nothing
+        // (preserves the disambiguation behaviour of the prior resolveByName).
+        let pool = candidates;
+        if (testFile) {
+            const normFile = testFile.replace(/\\/g, '/');
+            const fileMatches = candidates.filter(c => c.file === normFile ||
+                c.file.endsWith('/' + normFile) ||
+                normFile.endsWith('/' + c.file));
+            if (fileMatches.length > 0)
+                pool = fileMatches;
+        }
+        if (pool === candidates && testFolder) {
+            const folderMatches = candidates.filter(c => AnnotationScanner.folderMatchesFile(testFolder, c.file));
+            if (folderMatches.length > 0)
+                pool = folderMatches;
+        }
+        // All from same file → unambiguous single or multi-case annotation
+        const files = new Set(pool.map(c => c.file));
+        if (files.size === 1) {
+            // De-duplicate in case the same ID was annotated more than once
+            return [...new Set(pool.map(c => c.caseId))];
+        }
+        // Multiple files — true ambiguity; warn once and return nothing
+        if (!this.warnedAmbiguous.has(name)) {
+            this.warnedAmbiguous.add(name);
+            const detail = pool.map(c => `${c.file}→case ${c.caseId}`).join(', ');
+            logger_1.logger.warn(`Annotation ambiguous for "${name}": same name found in multiple files ` +
+                `(${detail}). Include the file attribute in test results, or use ` +
+                `config_mappings to resolve.`);
+        }
+        return [];
+    }
+    /** Total number of successfully named annotations indexed. */
+    getNamedAnnotationCount() {
+        let count = 0;
+        for (const anns of this.annotationsByName.values())
+            count += anns.length;
+        return count;
+    }
+}
+exports.AnnotationScanner = AnnotationScanner;