@rigour-labs/core 6.3.1 → 6.4.1

package/dist/semantic/project-facts.js

@@ -0,0 +1,104 @@
+/**
+ * What a file's own package declares: its nearest package.json dependencies and
+ * nearest tsconfig compiler options. Ecosystem rules are gated on these, so a
+ * Solid rule only runs where Solid is a dependency, and in a monorepo each
+ * package is judged by its own manifest. Lookups never leave `cwd`, and are
+ * cached for one analysis run.
+ */
+import fs from 'fs';
+import path from 'path';
+import ts from 'typescript';
+const DEPENDENCY_FIELDS = ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies'];
+export class ProjectFacts {
+    cwd;
+    packages = new Map();
+    options = new Map();
+    constructor(cwd) {
+        this.cwd = cwd;
+    }
+    /** Declared dependency names and version ranges of the package that owns `file`. */
+    dependencies(file) {
+        return this.nearestPackage(file)?.dependencies ?? new Map();
+    }
+    /** Directory of the package.json that owns `file`. */
+    packageDir(file) {
+        return this.dirsUp(file).find(dir => this.readPackage(dir));
+    }
+    /** The `name` of the package that owns `file`. */
+    packageName(file) {
+        return this.nearestPackage(file)?.name;
+    }
+    declares(file, ...names) {
+        const deps = this.dependencies(file);
+        return names.some(name => deps.has(name));
+    }
+    /**
+     * Highest major version a declared dependency may run on, across every field
+     * and `||` alternative (`>=18.0.0 || >=19.0.0` -> 19). A package that supports
+     * a major must work on it. Undefined when no range names a version (`catalog:`, `workspace:*`).
+     */
+    majorVersion(file, name) {
+        const majors = (this.nearestPackage(file)?.ranges.get(name) ?? [])
+            .flatMap(range => range.split('||'))
+            .map(alternative => alternative.match(/(\d+)(?:\.[\dx*]+)*/)?.[1])
+            .filter((m) => m !== undefined)
+            .map(Number);
+        return majors.length ? Math.max(...majors) : undefined;
+    }
+    /** Compiler options of the nearest tsconfig.json above `file`, extends resolved. */
+    compilerOptions(file) {
+        const dir = path.dirname(path.resolve(this.cwd, file));
+        const cached = this.options.get(dir);
+        if (cached)
+            return cached;
+        const configPath = this.dirsUp(file).map(d => path.join(d, 'tsconfig.json')).find(p => fs.existsSync(p));
+        let options = {};
+        if (configPath) {
+            const read = ts.readConfigFile(configPath, ts.sys.readFile);
+            if (!read.error)
+                options = ts.parseJsonConfigFileContent(read.config, ts.sys, path.dirname(configPath)).options;
+        }
+        this.options.set(dir, options);
+        return options;
+    }
+    dirsUp(file) {
+        const root = path.resolve(this.cwd);
+        const dirs = [];
+        for (let dir = path.dirname(path.resolve(root, file)); dir.startsWith(root); dir = path.dirname(dir)) {
+            dirs.push(dir);
+            if (dir === root)
+                break;
+        }
+        return dirs;
+    }
+    nearestPackage(file) {
+        for (const dir of this.dirsUp(file)) {
+            const manifest = this.readPackage(dir);
+            if (manifest)
+                return manifest;
+        }
+        return undefined;
+    }
+    readPackage(dir) {
+        if (this.packages.has(dir))
+            return this.packages.get(dir);
+        let manifest = null;
+        try {
+            const json = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8'));
+            const dependencies = new Map();
+            const ranges = new Map();
+            for (const field of DEPENDENCY_FIELDS) {
+                for (const [name, range] of Object.entries(json[field] ?? {})) {
+                    dependencies.set(name, String(range));
+                    ranges.set(name, [...(ranges.get(name) ?? []), String(range)]);
+                }
+            }
+            manifest = { name: typeof json.name === 'string' ? json.name : undefined, dependencies, ranges };
+        }
+        catch {
+            manifest = null;
+        }
+        this.packages.set(dir, manifest);
+        return manifest;
+    }
+}

package/dist/semantic/project-facts.test.d.ts

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

package/dist/semantic/project-facts.test.js

@@ -0,0 +1,45 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { afterEach, describe, expect, it } from 'vitest';
+import { ProjectFacts } from './project-facts.js';
+let root;
+afterEach(() => { if (root)
+    fs.rmSync(root, { recursive: true, force: true }); root = undefined; });
+function write(files) {
+    root = fs.mkdtempSync(path.join(os.tmpdir(), 'project-facts-'));
+    for (const [name, text] of Object.entries(files)) {
+        fs.mkdirSync(path.dirname(path.join(root, name)), { recursive: true });
+        fs.writeFileSync(path.join(root, name), text);
+    }
+    return root;
+}
+describe('ProjectFacts', () => {
+    it('reads the nearest package.json, so each monorepo package is judged by its own', () => {
+        const dir = write({
+            'package.json': JSON.stringify({ name: 'root', devDependencies: { vite: '^5.0.0' } }),
+            'packages/ui/package.json': JSON.stringify({ name: '@x/ui', peerDependencies: { 'solid-js': '^1.8.0' } }),
+            'packages/ui/src/a.tsx': '',
+        });
+        const facts = new ProjectFacts(dir);
+        expect(facts.declares('packages/ui/src/a.tsx', 'solid-js')).toBe(true);
+        expect(facts.declares('packages/ui/src/a.tsx', 'vite')).toBe(false);
+        expect(facts.majorVersion('packages/ui/src/a.tsx', 'solid-js')).toBe(1);
+        expect(facts.packageName('packages/ui/src/a.tsx')).toBe('@x/ui');
+        expect(facts.packageDir('packages/ui/src/a.tsx')).toBe(path.join(dir, 'packages/ui'));
+    });
+    it('never reads a manifest above cwd', () => {
+        const dir = write({ 'package.json': JSON.stringify({ dependencies: { react: '^19.0.0' } }), 'app/src/a.tsx': '' });
+        const facts = new ProjectFacts(path.join(dir, 'app'));
+        expect(facts.dependencies('src/a.tsx').size).toBe(0);
+        expect(facts.packageDir('src/a.tsx')).toBeUndefined();
+    });
+    it('resolves compiler options through tsconfig extends', () => {
+        const dir = write({
+            'tsconfig.base.json': JSON.stringify({ compilerOptions: { stripInternal: true } }),
+            'pkg/tsconfig.json': JSON.stringify({ extends: '../tsconfig.base.json' }),
+            'pkg/src/a.ts': '',
+        });
+        expect(new ProjectFacts(dir).compilerOptions('pkg/src/a.ts').stripInternal).toBe(true);
+    });
+});

package/dist/semantic/rules/ecosystem/deps-codegen-undeclared-import.d.ts

@@ -0,0 +1,2 @@
+import type { SemanticRule } from '../../types.js';
+export declare const depsCodegenUndeclaredImport: SemanticRule;

package/dist/semantic/rules/ecosystem/deps-codegen-undeclared-import.js

@@ -0,0 +1,71 @@
+/**
+ * deps/codegen-undeclared-import: generated code imports a package the
+ * generating package does not declare.
+ *
+ * Plugins and compilers emit source into their users' builds. An emitted
+ * `import … from 'pkg'` resolves in the user's project, so `pkg` must be a
+ * dependency or peer dependency of the plugin; otherwise builds fail wherever
+ * the user has not happened to install it. TanStack's Rsbuild plugin emitted
+ * `react-refresh/runtime` and broke apps without it.
+ *
+ * Only text that is emitted as code counts: a template given to a code builder
+ * (`template.statement\`…\`` or `template.statement(\`…\`)`), the `code` a
+ * bundler hook returns, or text given to a MagicString edit. Strings that merely mention imports (docs, lint rule
+ * data, demos) do not.
+ */
+import { builtinModules } from 'module';
+import ts from 'typescript';
+import { forEachNode, propertyNameText } from '../../ast.js';
+import { finding, packageOf } from './shared.js';
+const EMITTED_IMPORT = /(?:^|[\s;{}])import\s+(?:[\w*{}\s,$]+\s+from\s+)?['"]([^'"]+)['"]/g;
+const BUILTINS = new Set(builtinModules);
+const CODE_TAG = /(?:^|\.)(?:template|statement|statements|expression|smart|program|ast|js|ts|jsx|tsx|code)$/;
+const EMIT_METHODS = new Set(['prepend', 'append', 'appendLeft', 'appendRight', 'prependLeft', 'prependRight', 'overwrite']);
+export const depsCodegenUndeclaredImport = {
+    id: 'deps/codegen-undeclared-import',
+    check(ctx) {
+        const { sourceFile, project } = ctx;
+        const declared = project.dependencies(sourceFile.fileName);
+        if (declared.size === 0)
+            return [];
+        const self = project.packageName(sourceFile.fileName);
+        const findings = [];
+        forEachNode(sourceFile, (node) => {
+            const text = templateText(node);
+            if (!text || !isEmittedCode(node))
+                return;
+            for (const match of text.matchAll(EMITTED_IMPORT)) {
+                const pkg = packageOf(match[1]);
+                if (!pkg || pkg.includes('${') || BUILTINS.has(pkg) || declared.has(pkg) || pkg === self)
+                    continue;
+                findings.push(finding(ctx, 'deps/codegen-undeclared-import', node, 'high', `Generated code imports \`${match[1]}\`, but \`${pkg}\` is not a dependency or peer dependency of this package; builds without it fail.`, `Declare \`${pkg}\` as a (peer) dependency, or emit code that does not import it.`));
+            }
+        });
+        return findings;
+    },
+};
+/** Text of a string or template that is code: it must contain an import statement, not just a path. */
+function templateText(node) {
+    if (ts.isNoSubstitutionTemplateLiteral(node) || ts.isStringLiteral(node))
+        return node.text.includes('import') ? node.text : undefined;
+    if (ts.isTemplateExpression(node)) {
+        const text = [node.head.text, ...node.templateSpans.map(s => s.literal.text)].join('${}');
+        return text.includes('import') ? text : undefined;
+    }
+    return undefined;
+}
+/** The string is emitted as module code, not merely text that mentions an import. */
+function isEmittedCode(node) {
+    const parent = node.parent;
+    if (ts.isTaggedTemplateExpression(parent))
+        return CODE_TAG.test(parent.tag.getText());
+    if (ts.isPropertyAssignment(parent) && propertyNameText(parent.name) === 'code')
+        return true;
+    if (!ts.isCallExpression(parent) || !parent.arguments.includes(node))
+        return false;
+    const callee = parent.expression;
+    // template.statement(`import …`), a code builder called rather than tagged
+    if (CODE_TAG.test(callee.getText()))
+        return true;
+    return ts.isPropertyAccessExpression(callee) && EMIT_METHODS.has(callee.name.text);
+}

package/dist/semantic/rules/ecosystem/deps-internal-symbol.d.ts

@@ -0,0 +1,2 @@
+import type { SemanticRule } from '../../types.js';
+export declare const depsInternalSymbol: SemanticRule;

package/dist/semantic/rules/ecosystem/deps-internal-symbol.js

@@ -0,0 +1,36 @@
+/**
+ * deps/internal-symbol: reading a library's internal `Symbol.for('<lib>.internal…')`
+ * with the type error silenced.
+ *
+ * Internal symbols change without notice between releases, and the
+ * `@ts-expect-error` hides exactly the signal that the value is not public API.
+ * TanStack Start read h3's internal response symbol and replaced it with the
+ * public `event.res`.
+ */
+import ts from 'typescript';
+import { forEachNode } from '../../ast.js';
+import { finding, leadingCommentText } from './shared.js';
+const INTERNAL_KEY = /(?:^|[.:/])(?:internal|private)(?:[.:/]|$)/i;
+const SILENCED = /@ts-(?:expect-error|ignore)/;
+export const depsInternalSymbol = {
+    id: 'deps/internal-symbol',
+    check(ctx) {
+        const findings = [];
+        forEachNode(ctx.sourceFile, (node) => {
+            if (!ts.isCallExpression(node) || !isSymbolFor(node))
+                return;
+            const key = node.arguments[0];
+            if (!key || !ts.isStringLiteralLike(key) || !INTERNAL_KEY.test(key.text))
+                return;
+            if (!SILENCED.test(leadingCommentText(ctx.sourceFile, node)))
+                return;
+            findings.push(finding(ctx, 'deps/internal-symbol', node, 'medium', `\`Symbol.for('${key.text}')\` reads a library internal with the type error silenced; it can break on any release.`, 'Use the library\'s public API for this value, or pin the version and cover it with a test.'));
+        });
+        return findings;
+    },
+};
+function isSymbolFor(call) {
+    const callee = call.expression;
+    return ts.isPropertyAccessExpression(callee) && callee.name.text === 'for'
+        && ts.isIdentifier(callee.expression) && callee.expression.text === 'Symbol';
+}

package/dist/semantic/rules/ecosystem/dom-self-query-in-component.d.ts

@@ -0,0 +1,2 @@
+import type { SemanticRule } from '../../types.js';
+export declare const domSelfQueryInComponent: SemanticRule;

package/dist/semantic/rules/ecosystem/dom-self-query-in-component.js

@@ -0,0 +1,60 @@
+/**
+ * dom/self-query-in-component: a component scans the whole document to find
+ * its own element.
+ *
+ * `document.querySelectorAll(...)` inside a component's mount or effect, looping
+ * to find the node whose attribute equals this instance's id, costs O(n) per
+ * instance and O(n²) per page. A ref gives the element directly. TanStack's
+ * Solid hydration did this for every boundary.
+ */
+import ts from 'typescript';
+import { forEachNode } from '../../ast.js';
+import { finding, isJsxFile } from './shared.js';
+const LIFECYCLE = new Set(['onMount', 'createEffect', 'createRenderEffect', 'useEffect', 'useLayoutEffect', 'onMounted', 'watchEffect']);
+export const domSelfQueryInComponent = {
+    id: 'dom/self-query-in-component',
+    check(ctx) {
+        if (!isJsxFile(ctx.sourceFile) && !ctx.sourceFile.fileName.endsWith('.vue.ts'))
+            return [];
+        const findings = [];
+        forEachNode(ctx.sourceFile, (node) => {
+            if (!ts.isCallExpression(node) || !isDocumentQueryAll(node) || !insideLifecycle(node))
+                return;
+            if (!matchesOwnIdentity(node))
+                return;
+            findings.push(finding(ctx, 'dom/self-query-in-component', node, 'medium', 'Each instance scans the whole document to find its own element: O(n) per instance, O(n²) per page.', 'Attach a ref to the element and use it directly.'));
+        });
+        return findings;
+    },
+};
+function isDocumentQueryAll(call) {
+    const callee = call.expression;
+    return ts.isPropertyAccessExpression(callee) && callee.name.text === 'querySelectorAll'
+        && ts.isIdentifier(callee.expression) && callee.expression.text === 'document';
+}
+function insideLifecycle(node) {
+    for (let current = node.parent; current; current = current.parent) {
+        if (!ts.isCallExpression(current))
+            continue;
+        const callee = current.expression;
+        const name = ts.isIdentifier(callee) ? callee.text : ts.isPropertyAccessExpression(callee) ? callee.name.text : '';
+        if (LIFECYCLE.has(name))
+            return true; // onMount(...) or Solid.onMount(...)
+    }
+    return false;
+}
+/** The query's results are filtered by comparing an attribute to something (the instance's own id). */
+function matchesOwnIdentity(query) {
+    let scope = query;
+    while (scope.parent && !ts.isBlock(scope.parent))
+        scope = scope.parent;
+    const block = scope.parent ?? scope;
+    let matches = false;
+    forEachNode(block, (node) => {
+        if (matches || !ts.isBinaryExpression(node) || node.operatorToken.kind !== ts.SyntaxKind.EqualsEqualsEqualsToken)
+            return;
+        matches = [node.left, node.right].some(side => ts.isCallExpression(side) && ts.isPropertyAccessExpression(side.expression)
+            && side.expression.name.text === 'getAttribute');
+    });
+    return matches;
+}

package/dist/semantic/rules/ecosystem/env-bare-browser-global.d.ts

@@ -0,0 +1,2 @@
+import type { SemanticRule } from '../../types.js';
+export declare const envBareBrowserGlobal: SemanticRule;

package/dist/semantic/rules/ecosystem/env-bare-browser-global.js

@@ -0,0 +1,57 @@
+/**
+ * env/bare-browser-global: a browser global used bare (`addEventListener(...)`,
+ * `history.x`) in a file that knows it may run outside a browser.
+ *
+ * The file qualifies the global as `window.x` elsewhere, compares against
+ * `window`, or checks `isServer` / `typeof window`: it runs where the global is
+ * absent or is not the window (SSR, Node with a jsdom window, workers). A bare
+ * use there throws or reaches the wrong object. TanStack Router's core crashed
+ * router creation under Node + jsdom this way.
+ */
+import ts from 'typescript';
+import { forEachNode } from '../../ast.js';
+import { finding } from './shared.js';
+const BARE_CALLS = new Set(['addEventListener', 'removeEventListener', 'dispatchEvent']);
+const BARE_OBJECTS = new Set(['history', 'location', 'localStorage', 'sessionStorage']);
+/** The file guards for non-browser runtimes: `isServer`, `typeof window`/`document`, or compares against `window`. */
+const ENV_AWARE = /\bisServer\b|typeof\s+(?:window|document)\b|[=!]==?\s*window\b|\bwindow\s*[=!]==?/;
+export const envBareBrowserGlobal = {
+    id: 'env/bare-browser-global',
+    check(ctx) {
+        const { sourceFile, checker } = ctx;
+        const qualified = windowQualified(sourceFile);
+        const aware = qualified.size > 0 || ENV_AWARE.test(sourceFile.text);
+        if (!aware)
+            return [];
+        const findings = [];
+        forEachNode(sourceFile, (node) => {
+            const bare = bareGlobal(node);
+            if (!bare || isLocal(checker, bare))
+                return;
+            findings.push(finding(ctx, 'env/bare-browser-global', node, 'medium', `Bare \`${bare.text}\` in a file that also runs outside the browser; where the global is not the window (SSR, jsdom, workers) it throws or hits the wrong object.`, `Use \`window.${bare.text}\` as the rest of the file does.`));
+        });
+        return findings;
+    },
+};
+/** Names the file reads as `window.<name>`. */
+function windowQualified(sourceFile) {
+    const names = new Set();
+    forEachNode(sourceFile, (node) => {
+        if (ts.isPropertyAccessExpression(node) && ts.isIdentifier(node.expression) && node.expression.text === 'window'
+            && (BARE_CALLS.has(node.name.text) || BARE_OBJECTS.has(node.name.text)))
+            names.add(node.name.text);
+    });
+    return names;
+}
+function bareGlobal(node) {
+    if (ts.isCallExpression(node) && ts.isIdentifier(node.expression) && BARE_CALLS.has(node.expression.text))
+        return node.expression;
+    if (ts.isPropertyAccessExpression(node) && ts.isIdentifier(node.expression) && BARE_OBJECTS.has(node.expression.text))
+        return node.expression;
+    return undefined;
+}
+/** Declared in the project (an import, a parameter, a local): not the browser global. */
+function isLocal(checker, id) {
+    const declarations = checker.getSymbolAtLocation(id)?.declarations ?? [];
+    return declarations.some(d => !d.getSourceFile().isDeclarationFile);
+}

package/dist/semantic/rules/ecosystem/exports-condition-parity.d.ts

@@ -0,0 +1,2 @@
+import type { SemanticRule } from '../../types.js';
+export declare const exportsConditionParity: SemanticRule;

package/dist/semantic/rules/ecosystem/exports-condition-parity.js

@@ -0,0 +1,57 @@
+/**
+ * exports/condition-parity: a conditional entry (`index.react-server.ts`,
+ * `index.rsc.ts`, `index.browser.ts`, …) exports fewer names than the package's
+ * default `index.ts` beside it.
+ *
+ * Bundlers pick the conditional entry for that environment, so every name it
+ * lacks is an import that works in one environment and fails in another.
+ * TanStack Start's `react-server` entry dropped `useServerFn` and broke RSC apps.
+ */
+import fs from 'fs';
+import path from 'path';
+import ts from 'typescript';
+import { finding } from './shared.js';
+const VARIANT = /^index\.([a-z][\w-]*)\.[cm]?[jt]sx?$/i;
+const DECLARATION = /\.d\.[cm]?ts$/i;
+export const exportsConditionParity = {
+    id: 'exports/condition-parity',
+    check(ctx) {
+        const { sourceFile } = ctx;
+        const base = path.basename(sourceFile.fileName);
+        const variant = base.match(VARIANT);
+        if (!variant || DECLARATION.test(base))
+            return [];
+        const defaultEntry = siblingIndex(path.dirname(sourceFile.fileName));
+        if (!defaultEntry)
+            return [];
+        const { checker, entry, variant: own } = entries(ctx, defaultEntry);
+        if (!entry || !own)
+            return [];
+        const ownNames = exportNames(checker, own);
+        const missing = [...exportNames(checker, entry)].filter(name => !ownNames.has(name));
+        if (missing.length === 0)
+            return [];
+        const anchor = sourceFile.statements.find(s => ts.isExportDeclaration(s)) ?? sourceFile.statements[0] ?? sourceFile;
+        const shown = missing.slice(0, 5).map(n => `\`${n}\``).join(', ');
+        return [finding(ctx, 'exports/condition-parity', anchor, 'medium', `The \`${variant[1]}\` entry lacks ${missing.length} export(s) of ${path.basename(defaultEntry)}: ${shown}${missing.length > 5 ? ', …' : ''}. Imports of them fail only in that environment.`, `Re-export them from ${base}, or point the \`${variant[1]}\` condition at the default entry.`)];
+    },
+};
+function siblingIndex(dir) {
+    return ['index.ts', 'index.tsx', 'index.js', 'index.mts'].map(f => path.join(dir, f)).find(f => fs.existsSync(f));
+}
+/**
+ * Both entries in one program: the analysis program when it loaded the default
+ * entry (a full check), otherwise a two-file program (a review of the variant alone).
+ */
+function entries(ctx, defaultEntry) {
+    const entry = ctx.program.getSourceFile(defaultEntry);
+    if (entry)
+        return { checker: ctx.checker, entry, variant: ctx.sourceFile };
+    const options = { ...ctx.project.compilerOptions(ctx.sourceFile.fileName), noEmit: true, skipLibCheck: true, types: [] };
+    const pair = ts.createProgram([defaultEntry, ctx.sourceFile.fileName], options);
+    return { checker: pair.getTypeChecker(), entry: pair.getSourceFile(defaultEntry), variant: pair.getSourceFile(ctx.sourceFile.fileName) };
+}
+function exportNames(checker, sourceFile) {
+    const moduleSymbol = checker.getSymbolAtLocation(sourceFile);
+    return new Set(moduleSymbol ? checker.getExportsOfModule(moduleSymbol).map(s => s.name) : []);
+}

package/dist/semantic/rules/ecosystem/exports-forgotten-type.d.ts

@@ -0,0 +1,2 @@
+import type { SemanticRule } from '../../types.js';
+export declare const exportsForgottenType: SemanticRule;

package/dist/semantic/rules/ecosystem/exports-forgotten-type.js

@@ -0,0 +1,128 @@
+/**
+ * exports/forgotten-type: a package entry exports a function whose signature
+ * names a type the entry does not export (api-extractor's "forgotten export").
+ *
+ * Consumers can call the function but cannot name its parameter or return
+ * types, so they cannot annotate, wrap or store the values. TanStack Start's
+ * RSC entry exported `renderServerComponent` without the Renderable* types it
+ * returns.
+ */
+import fs from 'fs';
+import path from 'path';
+import ts from 'typescript';
+import { finding } from './shared.js';
+const ENTRY = /^index\.[cm]?tsx?$/;
+export const exportsForgottenType = {
+    id: 'exports/forgotten-type',
+    check(ctx) {
+        const { sourceFile, checker } = ctx;
+        if (!ENTRY.test(path.basename(sourceFile.fileName)) || !isPackageEntry(ctx))
+            return [];
+        const moduleSymbol = checker.getSymbolAtLocation(sourceFile);
+        if (!moduleSymbol)
+            return [];
+        const exported = checker.getExportsOfModule(moduleSymbol);
+        const exportedTargets = new Set(exported.map(s => resolve(checker, s)));
+        // One finding per export statement: the engine keeps one finding per line.
+        const missing = new Map();
+        for (const symbol of exported) {
+            for (const declaration of resolve(checker, symbol).declarations ?? []) {
+                const fn = functionOf(declaration);
+                if (!fn)
+                    continue;
+                for (const type of signatureTypes(checker, fn)) {
+                    if (exportedTargets.has(type) || subpathExports(ctx, type))
+                        continue;
+                    const anchor = exportStatementFor(checker, sourceFile, symbol.name) ?? sourceFile.statements[0] ?? sourceFile;
+                    const entry = missing.get(anchor) ?? { names: [], types: new Set() };
+                    if (!entry.names.includes(symbol.name))
+                        entry.names.push(symbol.name);
+                    entry.types.add(type.name);
+                    missing.set(anchor, entry);
+                }
+            }
+        }
+        const findings = [];
+        for (const [anchor, { names, types }] of missing) {
+            const typeList = [...types].map(t => `\`${t}\``).join(', ');
+            findings.push(finding(ctx, 'exports/forgotten-type', anchor, 'medium', `${names.map(n => `\`${n}\``).join(', ')} ${names.length > 1 ? 'are' : 'is'} exported, but ${types.size > 1 ? 'their signatures use' : 'the signature uses'} ${typeList}, which this entry does not export; consumers cannot name ${types.size > 1 ? 'them' : 'it'}.`, `Export ${typeList} (a type-only export is enough) from ${path.basename(sourceFile.fileName)}.`));
+        }
+        return findings;
+    },
+};
+/** The entry of its package: `index.ts` beside package.json or in its `src/`. */
+function isPackageEntry(ctx) {
+    // TypeScript names files with '/', path.resolve with the OS separator: compare resolved paths.
+    const dir = path.resolve(path.dirname(ctx.sourceFile.fileName));
+    const owner = ctx.project.packageDir(ctx.sourceFile.fileName);
+    return !!owner && (dir === owner || dir === path.join(owner, 'src'));
+}
+/**
+ * Exported by a subpath entry instead: an `index` file between the type's
+ * declaration and the package root that exports it (`pkg/sub` entries).
+ */
+function subpathExports(ctx, type) {
+    const owner = ctx.project.packageDir(ctx.sourceFile.fileName);
+    const declared = type.declarations?.[0]?.getSourceFile().fileName;
+    const self = path.resolve(ctx.sourceFile.fileName);
+    if (!owner || !declared)
+        return false;
+    for (let dir = path.resolve(path.dirname(declared)); dir.startsWith(owner) && dir !== owner; dir = path.dirname(dir)) {
+        const index = ['index.ts', 'index.tsx', 'index.mts'].map(f => path.join(dir, f)).find(f => fs.existsSync(f));
+        if (!index || index === self)
+            continue;
+        const loaded = ctx.program.getSourceFile(index);
+        const moduleSymbol = loaded && ctx.checker.getSymbolAtLocation(loaded);
+        if (moduleSymbol ? ctx.checker.getExportsOfModule(moduleSymbol).some(s => s.name === type.name)
+            : new RegExp(`\\b${type.name}\\b|export \\*`).test(fs.readFileSync(index, 'utf8')))
+            return true;
+    }
+    return false;
+}
+function resolve(checker, symbol) {
+    return symbol.flags & ts.SymbolFlags.Alias ? checker.getAliasedSymbol(symbol) : symbol;
+}
+/** `function f()` or `const f = () => …` / `const f = function () {…}`. */
+function functionOf(declaration) {
+    if (ts.isFunctionDeclaration(declaration))
+        return declaration;
+    const init = ts.isVariableDeclaration(declaration) ? declaration.initializer : undefined;
+    return init && (ts.isArrowFunction(init) || ts.isFunctionExpression(init)) ? init : undefined;
+}
+/** Project-declared interfaces, type aliases, classes and enums named in parameter and return annotations. */
+function signatureTypes(checker, fn) {
+    const types = [];
+    const visit = (node) => {
+        if (ts.isTypeReferenceNode(node)) {
+            const symbol = checker.getSymbolAtLocation(node.typeName);
+            const target = symbol && resolve(checker, symbol);
+            if (target && isProjectType(target))
+                types.push(target);
+        }
+        ts.forEachChild(node, visit);
+    };
+    for (const param of fn.parameters)
+        if (param.type)
+            visit(param.type);
+    if (fn.type)
+        visit(fn.type);
+    return types;
+}
+function isProjectType(symbol) {
+    const kinds = ts.SymbolFlags.Interface | ts.SymbolFlags.TypeAlias | ts.SymbolFlags.Class | ts.SymbolFlags.Enum;
+    return (symbol.flags & kinds) !== 0
+        && (symbol.declarations ?? []).some(d => !d.getSourceFile().isDeclarationFile && !d.getSourceFile().fileName.includes('/node_modules/'));
+}
+/** The statement that exports `name`: a named export, or the `export *` whose module provides it. */
+function exportStatementFor(checker, sourceFile, name) {
+    const declarations = sourceFile.statements.filter(ts.isExportDeclaration);
+    const named = declarations.find(s => s.exportClause && ts.isNamedExports(s.exportClause)
+        && s.exportClause.elements.some(e => e.name.text === name));
+    if (named)
+        return named;
+    return declarations.find(s => !s.exportClause && s.moduleSpecifier && providesName(checker, s.moduleSpecifier, name));
+}
+function providesName(checker, specifier, name) {
+    const moduleSymbol = checker.getSymbolAtLocation(specifier);
+    return !!moduleSymbol && checker.getExportsOfModule(moduleSymbol).some(s => s.name === name);
+}

package/dist/semantic/rules/ecosystem/imports-barrel-cycle.d.ts

@@ -0,0 +1,2 @@
+import type { SemanticRule } from '../../types.js';
+export declare const importsBarrelCycle: SemanticRule;