@rigour-labs/core 6.2.5 → 6.3.1

package/dist/semantic/ast.js

@@ -0,0 +1,122 @@
+/**
+ * Small, checker-aware AST helpers shared by the semantic rules.
+ */
+import path from 'path';
+import ts from 'typescript';
+export function isFunctionLike(node) {
+    return ts.isFunctionDeclaration(node) || ts.isFunctionExpression(node)
+        || ts.isArrowFunction(node) || ts.isMethodDeclaration(node);
+}
+/** Drop parentheses, type assertions, non-null and `await` around an expression. */
+export function unwrap(expr) {
+    let current = expr;
+    for (;;) {
+        if (ts.isParenthesizedExpression(current) || ts.isAsExpression(current) || ts.isNonNullExpression(current)
+            || ts.isTypeAssertionExpression(current) || ts.isSatisfiesExpression(current) || ts.isAwaitExpression(current)) {
+            current = current.expression;
+        }
+        else {
+            return current;
+        }
+    }
+}
+/**
+ * Symbol for a node, following import aliases to the declaration. For the
+ * name in a shorthand property (`{ headers }`) this is the variable it reads,
+ * not the property it creates.
+ */
+export function symbolOf(checker, node) {
+    const symbol = ts.isShorthandPropertyAssignment(node.parent) && node.parent.name === node
+        ? checker.getShorthandAssignmentValueSymbol(node.parent)
+        : checker.getSymbolAtLocation(node);
+    if (symbol && symbol.flags & ts.SymbolFlags.Alias)
+        return checker.getAliasedSymbol(symbol);
+    return symbol;
+}
+/** The function a call invokes, when it resolves to one declared in source. */
+export function calledFunction(checker, call) {
+    const symbol = symbolOf(checker, call.expression);
+    for (const decl of symbol?.declarations ?? []) {
+        if (isFunctionLike(decl) && decl.body)
+            return decl;
+        if ((ts.isVariableDeclaration(decl) || ts.isPropertyAssignment(decl)) && decl.initializer) {
+            const init = unwrap(decl.initializer);
+            if (isFunctionLike(init) && init.body)
+                return init;
+        }
+    }
+    return undefined;
+}
+/** `fetch` in `fetch(...)`, `deps.fetch(...)`, `this.fetch(...)`. */
+export function calleeName(call) {
+    const callee = unwrap(call.expression);
+    if (ts.isIdentifier(callee))
+        return callee.text;
+    if (ts.isPropertyAccessExpression(callee))
+        return callee.name.text;
+    return undefined;
+}
+export function enclosingFunction(node) {
+    for (let current = node.parent; current; current = current.parent) {
+        if (isFunctionLike(current))
+            return current;
+    }
+    return undefined;
+}
+/** Visit every descendant of `root` that belongs to `root` itself, not to a nested function. */
+export function forEachOwnNode(root, visit) {
+    const walk = (node) => {
+        visit(node);
+        if (node !== root && isFunctionLike(node))
+            return;
+        ts.forEachChild(node, walk);
+    };
+    ts.forEachChild(root, walk);
+}
+export function forEachNode(root, visit) {
+    const walk = (node) => {
+        visit(node);
+        ts.forEachChild(node, walk);
+    };
+    ts.forEachChild(root, walk);
+}
+/** Text of a property name (`a`, `'a'`, `"x-token"`), or undefined for computed names. */
+export function propertyNameText(name) {
+    if (!name)
+        return undefined;
+    if (ts.isIdentifier(name) || ts.isStringLiteral(name) || ts.isNumericLiteral(name))
+        return name.text;
+    if (ts.isNoSubstitutionTemplateLiteral(name))
+        return name.text;
+    return undefined;
+}
+export function lineOf(node) {
+    const sf = node.getSourceFile();
+    return sf.getLineAndCharacterOfPosition(node.getStart(sf)).line + 1;
+}
+/** "http.ts:51" style location for evidence, relative to cwd. */
+export function locationOf(cwd, node) {
+    return `${relativeFile(cwd, node.getSourceFile())}:${lineOf(node)}`;
+}
+export function relativeFile(cwd, sf) {
+    return path.relative(cwd, sf.fileName).replace(/\\/g, '/');
+}
+/** Short, single-line source text for messages. */
+export function snippet(node, max = 60) {
+    const text = node.getText(node.getSourceFile()).replace(/\s+/g, ' ');
+    return text.length > max ? `${text.slice(0, max - 1)}…` : text;
+}
+/** True when any identifier inside `expr` resolves to `target`. */
+export function mentionsSymbol(checker, expr, target) {
+    let found = false;
+    const walk = (node) => {
+        if (found)
+            return;
+        if (ts.isIdentifier(node) && symbolOf(checker, node) === target)
+            found = true;
+        else
+            ts.forEachChild(node, walk);
+    };
+    walk(expr);
+    return found;
+}

package/dist/semantic/benchmark.d.ts

@@ -0,0 +1,16 @@
+export interface BenchmarkCase {
+    name: string;
+    rule: string | null;
+    file: string | null;
+    line: number | null;
+    note: string;
+}
+export interface CaseResult {
+    case: BenchmarkCase;
+    /** Expected finding reported on `before/` (true for negatives). */
+    caught: boolean;
+    /** Findings on `after/` plus unexpected findings on `before/`. */
+    falsePositives: string[];
+}
+export declare function loadCases(root: string): BenchmarkCase[];
+export declare function runCase(root: string, bench: BenchmarkCase): CaseResult;

package/dist/semantic/benchmark.js

@@ -0,0 +1,31 @@
+/**
+ * Semantic benchmark: synthetic before/after cases per bug class.
+ *
+ * `before/` must produce the expected finding (recall); `after/` and cases
+ * with `rule: null` must produce none (false positives).
+ */
+import fs from 'fs';
+import path from 'path';
+import { analyzeFiles } from './engine.js';
+export function loadCases(root) {
+    return fs.readdirSync(root, { withFileTypes: true })
+        .filter(entry => entry.isDirectory() && fs.existsSync(path.join(root, entry.name, 'case.json')))
+        .map(entry => ({ name: entry.name, ...JSON.parse(fs.readFileSync(path.join(root, entry.name, 'case.json'), 'utf8')) }))
+        .sort((a, b) => a.name.localeCompare(b.name));
+}
+export function runCase(root, bench) {
+    const before = findingsIn(path.join(root, bench.name, 'before'));
+    const after = findingsIn(path.join(root, bench.name, 'after'));
+    const isExpected = (f) => bench.rule !== null && f === `${bench.rule} ${bench.file}:${bench.line}`;
+    return {
+        case: bench,
+        caught: bench.rule === null || before.some(isExpected),
+        falsePositives: [...before.filter(f => !isExpected(f)).map(f => `before: ${f}`), ...after.map(f => `after: ${f}`)],
+    };
+}
+function findingsIn(dir) {
+    if (!fs.existsSync(dir))
+        return [];
+    const files = fs.readdirSync(dir).filter(f => /\.[cm]?[jt]sx?$/.test(f));
+    return analyzeFiles(dir, files).map(f => `${f.rule} ${f.file}:${f.line}`);
+}

package/dist/semantic/benchmark.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/semantic/benchmark.test.js

@@ -0,0 +1,18 @@
+import path from 'path';
+import { describe, expect, it } from 'vitest';
+import { loadCases, runCase } from './benchmark.js';
+const ROOT = path.resolve(__dirname, '../../../../benchmarks/semantic');
+describe('semantic benchmark', () => {
+    const cases = loadCases(ROOT);
+    it('has cases for every built-in rule, including negatives', () => {
+        const rules = new Set(cases.map(c => c.rule));
+        expect(rules).toEqual(new Set(['in-memory-aggregation', 'credential-redirect', 'degraded-response-cached', null]));
+    });
+    for (const bench of cases) {
+        it(`${bench.name}: ${bench.note}`, () => {
+            const result = runCase(ROOT, bench);
+            expect(result.falsePositives).toEqual([]);
+            expect(result.caught).toBe(true);
+        });
+    }
+});

package/dist/semantic/engine.d.ts

@@ -0,0 +1,8 @@
+import type { SemanticFinding, SemanticRule } from './types.js';
+export declare const BUILT_IN_RULES: SemanticRule[];
+export interface EngineOptions {
+    rules?: SemanticRule[];
+    batchSize?: number;
+}
+/** Analyze `files` (cwd-relative or absolute). Declaration files are skipped. */
+export declare function analyzeFiles(cwd: string, files: string[], opts?: EngineOptions): SemanticFinding[];

package/dist/semantic/engine.js

@@ -0,0 +1,45 @@
+/**
+ * Runs semantic rules over a set of JS/TS files.
+ */
+import path from 'path';
+import { loadProjectConfig, programBatches } from './program.js';
+import { Summaries } from './summaries.js';
+import { inMemoryAggregation } from './rules/in-memory-aggregation.js';
+import { credentialRedirect } from './rules/credential-redirect.js';
+import { degradedResponseCached } from './rules/degraded-response-cached.js';
+export const BUILT_IN_RULES = [inMemoryAggregation, credentialRedirect, degradedResponseCached];
+/** Analyze `files` (cwd-relative or absolute). Declaration files are skipped. */
+export function analyzeFiles(cwd, files, opts = {}) {
+    const rules = opts.rules ?? BUILT_IN_RULES;
+    const roots = files
+        .filter(f => /\.(?:[cm]?[jt]s|[jt]sx)$/i.test(f) && !/\.d\.[cm]?ts$/i.test(f))
+        .map(f => path.resolve(cwd, f));
+    if (roots.length === 0 || rules.length === 0)
+        return [];
+    const { options } = loadProjectConfig(cwd);
+    const rootSet = new Set(roots.map(r => path.normalize(r)));
+    const findings = [];
+    for (const program of programBatches(roots, options, opts.batchSize)) {
+        const checker = program.getTypeChecker();
+        const summaries = new Summaries(checker);
+        for (const sourceFile of program.getSourceFiles()) {
+            if (!rootSet.has(path.normalize(sourceFile.fileName)))
+                continue;
+            for (const rule of rules) {
+                findings.push(...rule.check({ cwd, checker, sourceFile, summaries }));
+            }
+            rootSet.delete(path.normalize(sourceFile.fileName));
+        }
+    }
+    return dedupe(findings);
+}
+function dedupe(findings) {
+    const seen = new Set();
+    return findings.filter(f => {
+        const key = `${f.rule}:${f.file}:${f.line}`;
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+}

package/dist/semantic/intent/benchmark.d.ts

@@ -0,0 +1,31 @@
+import { type ReadVerdict, type YesNoModel } from './intent-check.js';
+export interface IntentCase {
+    name: string;
+    note: string;
+    labels: Record<string, 'optional' | 'required'>;
+    expectFinding: boolean;
+    /** False when the finder must skip the site (no model call). */
+    expectSite?: boolean;
+}
+export interface IntentCaseResult {
+    case: IntentCase;
+    siteFound: boolean;
+    verdicts: ReadVerdict[];
+    findings: number;
+}
+export interface IntentScore {
+    /** Individual answers matching the label (question 1 expects yes for optional, question 2 no). */
+    rawCorrect: number;
+    rawTotal: number;
+    /** Reads whose flipped answers agreed, and how many of those were right. */
+    consistent: number;
+    consistentCorrect: number;
+    reads: number;
+    truePositives: number;
+    falseNegatives: number;
+    falsePositives: number;
+    finderErrors: string[];
+}
+export declare function loadIntentCases(root: string): IntentCase[];
+export declare function runIntentCase(root: string, bench: IntentCase, model: YesNoModel): Promise<IntentCaseResult>;
+export declare function scoreIntent(results: IntentCaseResult[]): IntentScore;

package/dist/semantic/intent/benchmark.js

@@ -0,0 +1,74 @@
+/**
+ * Intent benchmark: labelled `Promise.all` sites for optional-read-no-fallback.
+ *
+ * Each case is one file (`code.ts`) whose reads are labelled optional or
+ * required, and whether a finding is expected. Scoring separates the raw
+ * answers from the verdicts that survive the flipped-question filter, so
+ * the filter's effect (accuracy gained, answers discarded) is measured.
+ */
+import fs from 'fs';
+import path from 'path';
+import { programBatches, loadProjectConfig } from '../program.js';
+import { classifyReads, findingsFor } from './intent-check.js';
+import { findParallelReads } from './parallel-reads.js';
+export function loadIntentCases(root) {
+    return fs.readdirSync(root, { withFileTypes: true })
+        .filter(entry => entry.isDirectory() && fs.existsSync(path.join(root, entry.name, 'case.json')))
+        .map(entry => ({ name: entry.name, ...readCase(path.join(root, entry.name, 'case.json')) }))
+        .sort((a, b) => a.name.localeCompare(b.name));
+}
+function readCase(file) {
+    try {
+        return JSON.parse(fs.readFileSync(file, 'utf8'));
+    }
+    catch (error) {
+        throw new Error(`Invalid intent benchmark case ${file}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+export async function runIntentCase(root, bench, model) {
+    const dir = path.join(root, bench.name);
+    const file = path.join(dir, 'code.ts');
+    const [program] = [...programBatches([file], loadProjectConfig(dir).options)];
+    const [site] = findParallelReads(dir, program.getTypeChecker(), program.getSourceFile(file));
+    if (!site)
+        return { case: bench, siteFound: false, verdicts: [], findings: 0 };
+    const verdicts = await classifyReads(model, site);
+    return { case: bench, siteFound: true, verdicts, findings: findingsFor(site, verdicts).length };
+}
+export function scoreIntent(results) {
+    const score = {
+        rawCorrect: 0, rawTotal: 0, consistent: 0, consistentCorrect: 0, reads: 0,
+        truePositives: 0, falseNegatives: 0, falsePositives: 0, finderErrors: [],
+    };
+    for (const result of results) {
+        if (result.siteFound !== (result.case.expectSite ?? true))
+            score.finderErrors.push(result.case.name);
+        for (const verdict of result.verdicts)
+            scoreRead(score, verdict, result.case.labels[verdict.read.label]);
+        scoreSite(score, result);
+    }
+    return score;
+}
+function scoreRead(score, { verdict, answers }, label) {
+    if (!label)
+        return;
+    const optional = label === 'optional';
+    score.reads += 1;
+    score.rawTotal += 2;
+    score.rawCorrect += Number(answers[0] === (optional ? 'yes' : 'no')) + Number(answers[1] === (optional ? 'no' : 'yes'));
+    if (verdict === 'unknown')
+        return;
+    score.consistent += 1;
+    score.consistentCorrect += Number(verdict === label);
+}
+function scoreSite(score, result) {
+    if (result.case.expectFinding) {
+        if (result.findings > 0)
+            score.truePositives += 1;
+        else
+            score.falseNegatives += 1;
+    }
+    else if (result.findings > 0) {
+        score.falsePositives += 1;
+    }
+}

package/dist/semantic/intent/intent-check.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Asks the local model the one thing code cannot say: is a read optional?
+ *
+ * Flipped-question protocol: each read gets two questions of opposite
+ * polarity ("should it still return if X fails?" / "is X required?"). An
+ * answer counts only when both agree (yes/no = optional, no/yes = required);
+ * anything else is unknown, and unknown never becomes a finding. A finding
+ * needs one read judged optional and another judged required at the same
+ * site: then the optional read's failure takes down the required one.
+ */
+import type { InferenceProvider } from '../../inference/types.js';
+import type { SemanticFinding } from '../types.js';
+import type { ParallelRead, ParallelReadSite } from './parallel-reads.js';
+export type Answer = 'yes' | 'no' | null;
+export type Verdict = 'optional' | 'required' | 'unknown';
+export interface YesNoModel {
+    ask(prompt: string): Promise<Answer>;
+}
+export interface ReadVerdict {
+    read: ParallelRead;
+    verdict: Verdict;
+    answers: [Answer, Answer];
+}
+export declare const RULE_ID = "optional-read-no-fallback";
+export declare const YES_NO_SCHEMA: {
+    type: string;
+    properties: {
+        answer: {
+            type: string;
+            enum: string[];
+        };
+    };
+    required: string[];
+    additionalProperties: boolean;
+};
+/** A local provider as a yes/no oracle: schema-constrained, temperature 0. */
+export declare function yesNoModel(provider: InferenceProvider): YesNoModel;
+export declare function verdictOf([ifFails, required]: [Answer, Answer]): Verdict;
+export declare function questionsFor(site: ParallelReadSite, read: ParallelRead): [string, string];
+export declare function promptFor(site: ParallelReadSite, question: string): string;
+export declare function classifyReads(model: YesNoModel, site: ParallelReadSite): Promise<ReadVerdict[]>;
+/** Findings for a site: every read judged optional, when another read is judged required. */
+export declare function findingsFor(site: ParallelReadSite, verdicts: ReadVerdict[]): SemanticFinding[];

package/dist/semantic/intent/intent-check.js

@@ -0,0 +1,72 @@
+import { lineOf } from '../ast.js';
+export const RULE_ID = 'optional-read-no-fallback';
+const MAX_SOURCE_LINES = 80;
+export const YES_NO_SCHEMA = {
+    type: 'object',
+    properties: { answer: { type: 'string', enum: ['yes', 'no'] } },
+    required: ['answer'],
+    additionalProperties: false,
+};
+/** A local provider as a yes/no oracle: schema-constrained, temperature 0. */
+export function yesNoModel(provider) {
+    return {
+        async ask(prompt) {
+            const text = await provider.analyze(prompt, { jsonSchema: YES_NO_SCHEMA, temperature: 0, maxTokens: 16 });
+            try {
+                const answer = JSON.parse(text)?.answer;
+                return answer === 'yes' || answer === 'no' ? answer : null;
+            }
+            catch {
+                return null;
+            }
+        },
+    };
+}
+export function verdictOf([ifFails, required]) {
+    if (ifFails === 'yes' && required === 'no')
+        return 'optional';
+    if (ifFails === 'no' && required === 'yes')
+        return 'required';
+    return 'unknown';
+}
+export function questionsFor(site, read) {
+    return [
+        `If \`${read.label}\` throws, should \`${site.fnName}\` still return a result built from the other calls?`,
+        `Is the result of \`${read.label}\` required for \`${site.fnName}\` to return anything useful?`,
+    ];
+}
+export function promptFor(site, question) {
+    const source = site.fn.getText(site.fn.getSourceFile()).split('\n').slice(0, MAX_SOURCE_LINES).join('\n');
+    return [
+        'You are reviewing a TypeScript function.',
+        '```ts', source, '```',
+        `The calls ${site.reads.map(r => `\`${r.label}\``).join(', ')} run together in \`await Promise.all([...])\`. If any of them throws, the whole Promise.all rejects.`,
+        `Question: ${question}`,
+        'Answer with JSON: {"answer": "yes"} or {"answer": "no"}.',
+    ].join('\n');
+}
+export async function classifyReads(model, site) {
+    const verdicts = [];
+    for (const read of site.reads) {
+        const [ifFails, required] = questionsFor(site, read);
+        const answers = [await model.ask(promptFor(site, ifFails)), await model.ask(promptFor(site, required))];
+        verdicts.push({ read, verdict: verdictOf(answers), answers });
+    }
+    return verdicts;
+}
+/** Findings for a site: every read judged optional, when another read is judged required. */
+export function findingsFor(site, verdicts) {
+    const required = verdicts.filter(v => v.verdict === 'required').map(v => `\`${v.read.label}\``);
+    if (required.length === 0)
+        return [];
+    return verdicts.filter(v => v.verdict === 'optional').map(({ read }) => ({
+        rule: RULE_ID,
+        severity: 'medium',
+        provenance: 'deep-analysis',
+        file: site.file,
+        line: lineOf(read.call),
+        message: `\`${read.label}\` looks optional to \`${site.fnName}\`, but it runs in Promise.all with ${required.join(', ')}, so its failure also discards ${required.length > 1 ? 'them' : 'that result'}.`,
+        hint: 'Give the optional read its own catch that returns a fallback (and tell the caller the result is partial), or confirm it is required.',
+        evidence: [`${site.file}:${site.line} Promise.all`, 'Intent from the local model: two flipped questions answered consistently.'],
+    }));
+}

package/dist/semantic/intent/intent.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/semantic/intent/intent.test.js

@@ -0,0 +1,46 @@
+import path from 'path';
+import { describe, expect, it } from 'vitest';
+import { loadIntentCases, runIntentCase, scoreIntent } from './benchmark.js';
+import { verdictOf } from './intent-check.js';
+const ROOT = path.resolve(__dirname, '../../../../../benchmarks/intent');
+/** Answers from the labels: an oracle, optionally contradicting itself on one read. */
+function labelledModel(labels, contradict) {
+    return {
+        async ask(prompt) {
+            const label = Object.keys(labels).find(name => prompt.includes(`Question: If \`${name}\``) || prompt.includes(`result of \`${name}\``));
+            if (!label)
+                return null;
+            const optional = labels[label] === 'optional';
+            const firstQuestion = prompt.includes('Question: If');
+            if (label === contradict)
+                return 'yes';
+            return firstQuestion === optional ? 'yes' : 'no';
+        },
+    };
+}
+describe('verdictOf', () => {
+    it('counts only consistent flipped answers', () => {
+        expect(verdictOf(['yes', 'no'])).toBe('optional');
+        expect(verdictOf(['no', 'yes'])).toBe('required');
+        expect(verdictOf(['yes', 'yes'])).toBe('unknown');
+        expect(verdictOf(['no', 'no'])).toBe('unknown');
+        expect(verdictOf([null, 'no'])).toBe('unknown');
+    });
+});
+describe('intent benchmark with a labelled oracle', () => {
+    const cases = loadIntentCases(ROOT);
+    it('finds every labelled site, skips the fixed one, and scores the oracle perfectly', async () => {
+        const results = await Promise.all(cases.map(bench => runIntentCase(ROOT, bench, labelledModel(bench.labels))));
+        const score = scoreIntent(results);
+        expect(score.finderErrors).toEqual([]);
+        expect(score.falsePositives).toBe(0);
+        expect(score.falseNegatives).toBe(0);
+        expect(score.rawCorrect).toBe(score.rawTotal);
+    });
+    it('drops a read whose answers contradict each other instead of guessing', async () => {
+        const bench = cases.find(c => c.name === 'dashboard');
+        const result = await runIntentCase(ROOT, bench, labelledModel(bench.labels, 'getRecommendedCourses'));
+        expect(result.verdicts.find(v => v.read.label === 'getRecommendedCourses')?.verdict).toBe('unknown');
+        expect(result.findings).toBe(0);
+    });
+});

package/dist/semantic/intent/parallel-reads.d.ts

@@ -0,0 +1,23 @@
+/**
+ * `await Promise.all([...])` sites where one read failing loses them all.
+ *
+ * This part is deterministic: two or more calls run together with no
+ * handling of their own, and nothing in the function catches the rejection.
+ * Whether that is a bug depends on intent (is one of the reads optional?),
+ * which the code cannot say; see intent-check.ts.
+ */
+import ts from 'typescript';
+import { type FunctionLike } from '../ast.js';
+export interface ParallelRead {
+    call: ts.CallExpression;
+    /** Callee text, e.g. `fetchStepEngagement`. */
+    label: string;
+}
+export interface ParallelReadSite {
+    file: string;
+    line: number;
+    fnName: string;
+    fn: FunctionLike;
+    reads: ParallelRead[];
+}
+export declare function findParallelReads(cwd: string, checker: ts.TypeChecker, sourceFile: ts.SourceFile): ParallelReadSite[];

package/dist/semantic/intent/parallel-reads.js

@@ -0,0 +1,59 @@
+/**
+ * `await Promise.all([...])` sites where one read failing loses them all.
+ *
+ * This part is deterministic: two or more calls run together with no
+ * handling of their own, and nothing in the function catches the rejection.
+ * Whether that is a bug depends on intent (is one of the reads optional?),
+ * which the code cannot say; see intent-check.ts.
+ */
+import ts from 'typescript';
+import { calledFunction, enclosingFunction, forEachNode, lineOf, relativeFile, unwrap } from '../ast.js';
+import { promiseAllItems } from '../origins.js';
+import { functionKeyOf } from '../learn/identity.js';
+export function findParallelReads(cwd, checker, sourceFile) {
+    const sites = [];
+    forEachNode(sourceFile, (node) => {
+        if (!ts.isCallExpression(node) || !isPromiseAll(node))
+            return;
+        const fn = enclosingFunction(node);
+        if (!fn || isInsideTry(node, fn))
+            return;
+        const reads = (promiseAllItems(node) ?? [])
+            .map(item => unwrap(item))
+            .filter((item) => ts.isCallExpression(item) && !handlesOwnFailure(checker, item))
+            .map(call => ({ call, label: call.expression.getText(sourceFile).replace(/\s+/g, '') }));
+        if (reads.length < 2)
+            return;
+        sites.push({ file: relativeFile(cwd, sourceFile), line: lineOf(node), fnName: functionKeyOf(node), fn, reads });
+    });
+    return sites;
+}
+function isPromiseAll(call) {
+    const callee = call.expression;
+    return ts.isPropertyAccessExpression(callee) && callee.name.text === 'all'
+        && ts.isIdentifier(callee.expression) && callee.expression.text === 'Promise';
+}
+/** Inside a `try` (with a catch) of the same function: the rejection is handled there. */
+function isInsideTry(node, fn) {
+    for (let child = node, parent = node.parent; parent && parent !== fn; child = parent, parent = parent.parent) {
+        if (ts.isTryStatement(parent) && parent.tryBlock === child && parent.catchClause)
+            return true;
+    }
+    return false;
+}
+/** `x().catch(...)`, `x().then(ok, fail)`, or a callee whose body catches and returns. */
+function handlesOwnFailure(checker, call) {
+    const callee = call.expression;
+    if (ts.isPropertyAccessExpression(callee)) {
+        if (callee.name.text === 'catch' || callee.name.text === 'finally')
+            return true;
+        if (callee.name.text === 'then' && call.arguments.length >= 2)
+            return true;
+    }
+    const target = calledFunction(checker, call);
+    const body = target?.body;
+    return !!body && ts.isBlock(body) && body.statements.some(s => ts.isTryStatement(s) && !!s.catchClause && catchReturns(s.catchClause));
+}
+function catchReturns(clause) {
+    return clause.block.statements.some(s => ts.isReturnStatement(s));
+}

package/dist/semantic/learn/benchmark.d.ts

@@ -0,0 +1,20 @@
+import { type LearnReport } from './learn.js';
+export interface LearnCase {
+    name: string;
+    note: string;
+    expect: {
+        template: string;
+        property: string;
+        guard?: string;
+        scoped: boolean;
+    } | null;
+    variants?: string[];
+    unsupported?: string[];
+}
+export interface LearnCaseResult {
+    case: LearnCase;
+    report: LearnReport;
+    problems: string[];
+}
+export declare function loadLearnCases(root: string): LearnCase[];
+export declare function runLearnCase(root: string, bench: LearnCase): Promise<LearnCaseResult>;