@dokebi/cli 0.2.5 → 0.4.0

package/dist/check/packages.js

@@ -0,0 +1,161 @@
+// `@dokebi/*` import specifiers in user code (D-0072 rules private-import and missing-package).
+// A specifier is checked against the installed package's package.json `exports` the way Node
+// resolves it (nearest node_modules upward from the importing file), and a package that is not
+// installed is looked up in the CLI catalog: a Dokebi package to add, something Dokebi lacks
+// (absent.yaml, with its `instead`), or a name that does not exist.
+import { readFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { findPackage, searchCatalog } from '../catalog.js';
+import { debug, isMissing } from '../diagnostics.js';
+import { CliError } from '../errors.js';
+const SCOPE = '@dokebi/';
+const PACKAGE = /^@dokebi\/([a-z0-9][a-z0-9._-]*)(\/.*)?$/;
+/** Whether `subpath` (`.` or `./x`) is a public path of an `exports` value (Node rules). */
+export function isExported(exports, subpath) {
+    if (exports === undefined)
+        return true; // no exports: Node lets every file be imported
+    if (exports === null)
+        return false;
+    if (typeof exports === 'string' || Array.isArray(exports))
+        return subpath === '.';
+    if (typeof exports !== 'object')
+        return false;
+    const map = exports;
+    const keys = Object.keys(map);
+    if (!keys.some((key) => key.startsWith('.')))
+        return subpath === '.'; // conditions only
+    if (Object.hasOwn(map, subpath))
+        return map[subpath] !== null;
+    let best;
+    for (const key of keys) {
+        const star = key.indexOf('*');
+        if (star === -1)
+            continue;
+        const before = key.slice(0, star);
+        const after = key.slice(star + 1);
+        if (subpath.length >= before.length + after.length &&
+            subpath.startsWith(before) &&
+            subpath.endsWith(after) &&
+            (!best || before.length > best.prefix))
+            best = { prefix: before.length, value: map[key] };
+    }
+    return best !== undefined && best.value !== null;
+}
+/** The public specifiers of a package (for the fix text). */
+export function publicPaths(name, exports) {
+    if (exports === undefined || typeof exports !== 'object' || exports === null)
+        return [name];
+    if (Array.isArray(exports))
+        return [name];
+    const keys = Object.keys(exports).filter((key) => key.startsWith('.') && exports[key] !== null);
+    if (!keys.length)
+        return [name];
+    return keys.filter((key) => key !== './package.json').map((key) => name + key.slice(1));
+}
+export class DokebiImports {
+    #catalog;
+    /** `<directory>\0<package>` → installed package (or null when no node_modules has it). */
+    #found = new Map();
+    constructor(catalog) {
+        this.#catalog = catalog;
+    }
+    async #manifest(path) {
+        let text;
+        try {
+            text = await readFile(path, 'utf8');
+        }
+        catch (error) {
+            if (isMissing(error))
+                return null;
+            throw new CliError('READ_FAILED', `Cannot read ${path}`, { cause: error });
+        }
+        try {
+            return JSON.parse(text);
+        }
+        catch (cause) {
+            throw new CliError('INVALID_PACKAGE', `${path} is not JSON`, { cause });
+        }
+    }
+    /** Nearest `node_modules/<name>` from the importing file's folder upward (Node resolution). */
+    async #installed(from, name) {
+        const visited = [];
+        let directory = dirname(from);
+        let result = null;
+        for (;;) {
+            const key = `${directory}\0${name}`;
+            const cached = this.#found.get(key);
+            if (cached !== undefined) {
+                result = cached;
+                break;
+            }
+            visited.push(key);
+            const candidate = join(directory, 'node_modules', name);
+            const manifest = await this.#manifest(join(candidate, 'package.json'));
+            if (manifest) {
+                result = { directory: candidate, exports: manifest.exports };
+                break;
+            }
+            const parent = dirname(directory);
+            if (parent === directory)
+                break;
+            directory = parent;
+        }
+        for (const key of visited)
+            this.#found.set(key, result);
+        return result;
+    }
+    /** The problem with one module specifier of `file`, if any. */
+    async verdict(file, specifier) {
+        const viaPath = /(^|\/)node_modules\/(@dokebi\/[^/]+)/.exec(specifier);
+        if (viaPath && !specifier.startsWith(SCOPE))
+            return {
+                rule: 'private-import',
+                message: `"${specifier}" reaches ${viaPath[2]} through node_modules by path; the package boundary (its exports) is skipped`,
+                fix: `import "${viaPath[2]}" (or one of its exported subpaths) by package name`,
+            };
+        const match = PACKAGE.exec(specifier);
+        if (!match)
+            return undefined;
+        const name = `${SCOPE}${match[1]}`;
+        const subpath = `.${match[2] ?? ''}`;
+        const installed = await this.#installed(file, name);
+        if (installed) {
+            if (isExported(installed.exports, subpath))
+                return undefined;
+            const internal = /^\.\/(dist|src|lib|build)(\/|$)/.test(subpath);
+            return {
+                rule: 'private-import',
+                message: `"${specifier}" is not an exported path of ${name}${internal ? ' (it reaches into the build output)' : ''}: Node refuses it (ERR_PACKAGE_PATH_NOT_EXPORTED) and it can change in any release`,
+                fix: `import from ${publicPaths(name, installed.exports).join(' or ')}`,
+            };
+        }
+        const known = this.#catalog.packages.find((item) => item.package === name);
+        if (known)
+            return {
+                rule: 'missing-package',
+                message: `${name} is a Dokebi package this project has not installed`,
+                fix: `npx dokebi add ${name} --dry-run --json, then without --dry-run (read its AI.md first)`,
+            };
+        const wanted = match[1].replace(/[._]/g, '-');
+        const search = searchCatalog(this.#catalog, wanted);
+        debug('check: unknown Dokebi package', { name, status: search.status });
+        const absent = search.absent[0];
+        if (absent)
+            return {
+                rule: 'missing-package',
+                message: `${name} does not exist: ${absent.summary} (Dokebi has no ${absent.capability}; do not invent a package or API for it)`,
+                fix: absent.instead,
+            };
+        const similar = search.matches
+            .map((item) => item.package)
+            .concat(findPackage(this.#catalog, wanted)?.package ?? [])
+            .filter((value, index, list) => list.indexOf(value) === index);
+        return {
+            rule: 'missing-package',
+            message: `${name} is not a Dokebi package`,
+            fix: similar.length
+                ? `use ${similar.slice(0, 3).join(' or ')} (npx dokebi plugins info <id> --json)`
+                : `npx dokebi plugins search ${wanted} --json; if nothing matches, write it in app code`,
+        };
+    }
+}

package/dist/check/problems.d.ts

@@ -0,0 +1,19 @@
+export declare const RULES: readonly ['empty-catch', 'floating-promise', 'non-erasable-syntax', 'private-import', 'generated-file', 'secret-in-config', 'missing-package', 'inertia-form-only'];
+export type RuleName = (typeof RULES)[number];
+/** Rules a `// dokebi-check: allow <rule> <reason>` comment may silence (D-0072 §4, markers). */
+export declare const MARKABLE: ReadonlySet<RuleName>;
+/** Rules that warn: reported with `severity: 'warning'`, they do not fail check or verify. */
+export declare const WARNING_RULES: ReadonlySet<RuleName>;
+export interface Problem {
+    readonly rule: RuleName;
+    /** `warning` for a rule of WARNING_RULES (absent: an error that fails check). */
+    readonly severity?: 'warning';
+    /** Project-relative path with `/`. */
+    readonly file: string;
+    /** 1-based; 0 when the problem is about the whole file. */
+    readonly line: number;
+    readonly message: string;
+    /** What to do instead, one line. */
+    readonly fix: string;
+}
+export declare function byPlace(a: Problem, b: Problem): number;

package/dist/check/problems.js

@@ -0,0 +1,22 @@
+// `dokebi check` problem shape and rule names (D-0072; inertia-form-only D-0074).
+export const RULES = [
+    'empty-catch',
+    'floating-promise',
+    'non-erasable-syntax',
+    'private-import',
+    'generated-file',
+    'secret-in-config',
+    'missing-package',
+    'inertia-form-only',
+];
+/** Rules a `// dokebi-check: allow <rule> <reason>` comment may silence (D-0072 §4, markers). */
+export const MARKABLE = new Set([
+    'empty-catch',
+    'floating-promise',
+    'inertia-form-only',
+]);
+/** Rules that warn: reported with `severity: 'warning'`, they do not fail check or verify. */
+export const WARNING_RULES = new Set(['inertia-form-only']);
+export function byPlace(a, b) {
+    return a.file.localeCompare(b.file) || a.line - b.line || a.rule.localeCompare(b.rule);
+}

package/dist/check/project-rules.d.ts

@@ -0,0 +1,10 @@
+import type { Inspection } from '../project-inspector.js';
+import type { Problem } from './problems.js';
+/**
+ * Whether dokebi.yaml can end up in version control: git tracks it, or git does not ignore it.
+ * Without git (or outside a repository) the project's .gitignore must list it.
+ */
+export declare function configReachesGit(root: string): Promise<boolean>;
+/** 1-based line of `options.<plugin>.<path…>` in dokebi.yaml: its deepest existing key (0: none). */
+export declare function optionLine(source: string, path: readonly string[]): number;
+export declare function projectProblems(root: string, inspection: Inspection): Promise<Problem[]>;

package/dist/check/project-rules.js

@@ -0,0 +1,142 @@
+// Project rules of `dokebi check` (D-0072): they read doctor's inspection instead of judging
+// files again, so doctor stays the one source for CLI-owned files and plugin checks.
+//   generated-file    doctor MODIFIED_REGISTRATION (src/dokebi.generated.ts),
+//                     GUIDE_BLOCK_MODIFIED (the AGENTS.md installed list between its markers) and
+//                     MODIFIED_TEMPLATE (a plugin file declared `owner: 'cli'`, D-0065 §11).
+//                     Files scaffolded for the developer (`owner: 'user'`) are never reported.
+//   secret-in-config  a plugin check's SECRET_IN_CONFIG (doctor PLUGIN_CHECK) when dokebi.yaml
+//                     can reach version control (tracked, or not ignored by git)
+import { execFile } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { isMap, isScalar, parseDocument } from 'yaml';
+import { CONFIG_FILE, CONFIG_IGNORES } from '../configuration.js';
+import { debug, describeError, isMissing } from '../diagnostics.js';
+import { CliError } from '../errors.js';
+import { AGENTS_FILE, INSTALLED_START } from '../project-guide.js';
+/** git's answer for one path: 0/1 exit codes, or undefined when git or the repository is absent. */
+function git(root, args) {
+    return new Promise((resolve) => {
+        execFile('git', args, { cwd: root, timeout: 10_000 }, (error) => {
+            if (!error)
+                return resolve(0);
+            const code = error.code;
+            if (code === 1)
+                return resolve(1);
+            // 128: not a repository; ENOENT: no git. Both mean "ask .gitignore instead".
+            debug('check: git gave no answer', { args, error: describeError(error) });
+            resolve(undefined);
+        });
+    });
+}
+/**
+ * Whether dokebi.yaml can end up in version control: git tracks it, or git does not ignore it.
+ * Without git (or outside a repository) the project's .gitignore must list it.
+ */
+export async function configReachesGit(root) {
+    const tracked = await git(root, ['ls-files', '--error-unmatch', '--', CONFIG_FILE]);
+    if (tracked === 0)
+        return true;
+    const ignored = await git(root, ['check-ignore', '-q', '--', CONFIG_FILE]);
+    if (ignored !== undefined)
+        return ignored !== 0;
+    let text = '';
+    try {
+        text = await readFile(join(root, '.gitignore'), 'utf8');
+    }
+    catch (error) {
+        if (!isMissing(error))
+            throw new CliError('READ_FAILED', 'Cannot read .gitignore', { cause: error });
+    }
+    const entry = CONFIG_IGNORES[0];
+    return !text
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .some((line) => line === entry || line === `/${entry}`);
+}
+/** 1-based line of `options.<plugin>.<path…>` in dokebi.yaml: its deepest existing key (0: none). */
+export function optionLine(source, path) {
+    const document = parseDocument(source, { version: '1.2' });
+    let node = document.contents;
+    let offset;
+    for (const key of path) {
+        if (!isMap(node))
+            break;
+        const pair = node.items.find((item) => isScalar(item.key) && String(item.key.value) === key);
+        if (!pair)
+            break;
+        offset = isScalar(pair.key) ? pair.key.range?.[0] : undefined;
+        node = pair.value;
+    }
+    if (offset === undefined)
+        return 0;
+    let line = 1;
+    for (let index = 0; index < offset; index++)
+        if (source.charCodeAt(index) === 10)
+            line++;
+    return line;
+}
+function lineOf(text, needle) {
+    const index = text.indexOf(needle);
+    return index === -1 ? 0 : text.slice(0, index).split('\n').length;
+}
+export async function projectProblems(root, inspection) {
+    const problems = [];
+    const codes = (code) => inspection.diagnostics.filter((item) => item.code === code);
+    for (const item of codes('MODIFIED_REGISTRATION'))
+        problems.push({
+            rule: 'generated-file',
+            file: item.path,
+            line: 1,
+            message: `${item.path} is generated by the CLI and was edited (doctor MODIFIED_REGISTRATION); add, upgrade and remove refuse to run until it is restored`,
+            fix: 'undo the edit (for example git checkout -- src/dokebi.generated.ts); change plugins with npx dokebi add/remove/app/module and options in dokebi.yaml',
+        });
+    for (const item of codes('MODIFIED_TEMPLATE'))
+        problems.push({
+            rule: 'generated-file',
+            file: item.path,
+            line: 0,
+            message: `${item.path} is a CLI-owned plugin file (owner: cli) and was edited (doctor MODIFIED_TEMPLATE); an upgrade of ${item.plugin ?? 'its plugin'} keeps the edit but no longer updates the file`,
+            fix: item.hint ?? 'restore the file and keep your changes in a user-owned file',
+        });
+    for (const item of codes('GUIDE_BLOCK_MODIFIED')) {
+        let text = '';
+        try {
+            text = await readFile(join(root, AGENTS_FILE), 'utf8');
+        }
+        catch (error) {
+            if (!isMissing(error))
+                throw new CliError('READ_FAILED', `Cannot read ${AGENTS_FILE}`, { cause: error });
+        }
+        problems.push({
+            rule: 'generated-file',
+            file: item.path,
+            line: lineOf(text, INSTALLED_START),
+            message: `The installed list between the dokebi:installed markers of ${item.path} was edited (doctor GUIDE_BLOCK_MODIFIED); the next add, upgrade or remove rewrites it and drops the edit`,
+            fix: item.hint ?? 'move your notes outside the markers',
+        });
+    }
+    const secrets = inspection.diagnostics.filter((item) => item.code === 'PLUGIN_CHECK' &&
+        item.details?.code === 'SECRET_IN_CONFIG');
+    if (secrets.length && (await configReachesGit(root))) {
+        let source = '';
+        try {
+            source = await readFile(join(root, CONFIG_FILE), 'utf8');
+        }
+        catch (error) {
+            if (!isMissing(error))
+                throw new CliError('READ_FAILED', `Cannot read ${CONFIG_FILE}`, { cause: error });
+        }
+        for (const item of secrets) {
+            const path = ['options', item.plugin ?? '', ...(item.details.optionPath ?? [])];
+            problems.push({
+                rule: 'secret-in-config',
+                file: CONFIG_FILE,
+                line: optionLine(source, path),
+                message: `${path.slice(1).join('.')} holds a secret (doctor PLUGIN_CHECK SECRET_IN_CONFIG) and ${CONFIG_FILE} can reach version control (git tracks it or does not ignore it)`,
+                fix: `${item.hint ? `${item.hint}; or ` : ''}keep ${CONFIG_FILE} out of git: list it in .gitignore (dokebi init does) and git rm --cached ${CONFIG_FILE}`,
+            });
+        }
+    }
+    return problems;
+}

package/dist/check/source-rules.d.ts

@@ -0,0 +1,28 @@
+import type { DokebiImports } from './packages.js';
+import { type Problem } from './problems.js';
+import { type Kinds, type TsNode, type TsSourceFile, type TypeScriptProject } from './typescript.js';
+interface Marker {
+    readonly line: number;
+    readonly rule: string;
+    readonly reason: string;
+    /** Nothing but the comment on its line: then it also covers the line below. */
+    readonly ownLine: boolean;
+}
+export declare function readMarkers(text: string): Marker[];
+/** A candidate statement whose expression's type decides the floating-promise rule. */
+export interface FloatingCandidate {
+    readonly expression: TsNode;
+    readonly problem: Problem;
+}
+export interface FileFindings {
+    readonly problems: Problem[];
+    readonly candidates: FloatingCandidate[];
+}
+/** Walks one file: all syntactic problems, and the statements the checker must judge. */
+export declare function inspectFile(file: TsSourceFile, kinds: Kinds, root: string, imports: DokebiImports): Promise<FileFindings>;
+/** Every program file: syntactic problems, then one batched checker call for the candidates. */
+export declare function sourceProblems(typescript: TypeScriptProject, root: string, imports: DokebiImports, skip: (path: string) => boolean): Promise<{
+    problems: Problem[];
+    files: number;
+}>;
+export {};

package/dist/check/source-rules.js

@@ -0,0 +1,273 @@
+// Source rules of `dokebi check` (D-0072): one walk over each file's TypeScript 7 AST. Each rule
+// matches only shapes that are wrong whatever the surrounding code is (no heuristics on names):
+//   empty-catch          `catch {}`, `.catch(() => {})`, `.then(ok, () => {})`, an empty
+//                        `on('error', …)` listener (D-0047)
+//   floating-promise     an expression statement whose call returns a Promise (the checker's
+//                        type) that is neither awaited, returned, `void`ed nor `.catch`ed;
+//                        node:test's test()/describe() are exempt (their promise never rejects)
+//   non-erasable-syntax  what Node's type stripping refuses or cannot run: enum, namespace with
+//                        values, parameter properties, decorators, `import x =`, `export =`, `<T>x`
+//   private-import       an `@dokebi/*` path outside the package exports (packages.ts)
+//   missing-package      an `@dokebi/*` package that is not installed, absent or unknown
+import { relative, sep } from 'node:path';
+import { MARKABLE } from './problems.js';
+import { field, nodes, property, } from './typescript.js';
+const LISTEN = new Set([
+    'on',
+    'once',
+    'addListener',
+    'prependListener',
+    'prependOnceListener',
+    'addEventListener',
+]);
+const SNIPPET = 60;
+/** `// dokebi-check: allow <rule> <reason>` (also inside a block comment). */
+const MARKER = /dokebi-check:\s*allow\s+([a-z-]+)[ \t]*(?:[:\-—–][ \t]*)?([^\n]*?)[ \t]*(?:\*\/|$)/gm;
+export function readMarkers(text) {
+    const markers = [];
+    let lineStart = 0;
+    let line = 1;
+    for (const match of text.matchAll(MARKER)) {
+        const index = match.index ?? 0;
+        for (; lineStart < index; lineStart++)
+            if (text.charCodeAt(lineStart) === 10)
+                line++;
+        const before = text.slice(text.lastIndexOf('\n', index) + 1, index);
+        markers.push({
+            line,
+            rule: match[1],
+            reason: (match[2] ?? '').replace(/^[\s:\-—–]+/, '').trim(),
+            ownLine: /^\s*(\/\/|\/\*+|\*)?\s*$/.test(before),
+        });
+    }
+    return markers;
+}
+/** Walks one file: all syntactic problems, and the statements the checker must judge. */
+export async function inspectFile(file, kinds, root, imports) {
+    const path = relative(root, file.fileName.split('/').join(sep)).split(sep).join('/');
+    const text = file.text;
+    const markers = readMarkers(text);
+    const lineOf = (position) => file.getLineAndCharacterOfPosition(position).line + 1;
+    const problems = [];
+    const candidates = [];
+    const specifiers = [];
+    /** The problem, or nothing when a marker with a reason sits on or just above its lines. */
+    const report = (node, rule, message, fix) => {
+        const first = lineOf(node.getStart());
+        const last = lineOf(Math.max(node.getStart(), node.end - 1));
+        let note = '';
+        if (MARKABLE.has(rule))
+            for (const marker of markers)
+                if (marker.rule === rule &&
+                    marker.line <= last &&
+                    (marker.line >= first || (marker.line === first - 1 && marker.ownLine))) {
+                    if (marker.reason)
+                        return undefined;
+                    note = ' (the dokebi-check marker has no reason, so it does not count)';
+                }
+        const problem = { rule, file: path, line: first, message: message + note, fix };
+        return problem;
+    };
+    const push = (problem) => {
+        if (problem)
+            problems.push(problem);
+    };
+    const snippet = (node) => {
+        const source = text.slice(node.getStart(), node.end).replace(/\s+/g, ' ');
+        return source.length > SNIPPET ? `${source.slice(0, SNIPPET - 1)}…` : source;
+    };
+    const stringValue = (node) => node && (node.kind === kinds.StringLiteral || node.kind === kinds.NoSubstitutionTemplateLiteral)
+        ? String(property(node, 'text'))
+        : undefined;
+    const hasModifier = (node, kind) => nodes(node, 'modifiers').some((modifier) => modifier.kind === kind);
+    /** An arrow or function expression whose body is a block without statements. */
+    const emptyFunction = (node) => {
+        if (!node || (node.kind !== kinds.ArrowFunction && node.kind !== kinds.FunctionExpression))
+            return false;
+        const body = field(node, 'body');
+        return body?.kind === kinds.Block && nodes(body, 'statements').length === 0;
+    };
+    /** The method name of `a.b(...)`, if the callee is a property access. */
+    const methodName = (call) => {
+        const callee = field(call, 'expression');
+        if (callee?.kind !== kinds.PropertyAccessExpression)
+            return undefined;
+        const name = field(callee, 'name');
+        return name?.kind === kinds.Identifier ? String(property(name, 'text')) : undefined;
+    };
+    const unwrap = (node) => {
+        let current = node;
+        while (current?.kind === kinds.ParenthesizedExpression)
+            current = field(current, 'expression');
+        return current;
+    };
+    /** Namespaces with only types (or `declare`) are erased; anything else makes a value. */
+    const instantiated = (body) => {
+        if (!body)
+            return false;
+        if (body.kind === kinds.ModuleDeclaration)
+            return !hasModifier(body, kinds.DeclareKeyword) && instantiated(field(body, 'body'));
+        return nodes(body, 'statements').some((statement) => statement.kind !== kinds.InterfaceDeclaration &&
+            statement.kind !== kinds.TypeAliasDeclaration &&
+            !hasModifier(statement, kinds.DeclareKeyword) &&
+            (statement.kind !== kinds.ModuleDeclaration || instantiated(field(statement, 'body'))));
+    };
+    const parameterModifiers = new Set([
+        kinds.PublicKeyword,
+        kinds.PrivateKeyword,
+        kinds.ProtectedKeyword,
+        kinds.ReadonlyKeyword,
+        kinds.OverrideKeyword,
+    ]);
+    const unsupported = (node, what, fix) => push(report(node, 'non-erasable-syntax', `${what} is TypeScript that Node's type stripping refuses (ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX): the app does not start`, fix));
+    // node:test's test(), it(), describe(), suite() return promises that never reject (a failed
+    // test is reported, not thrown), and calling them without await is the documented form.
+    const testNames = new Set();
+    for (const statement of nodes(file, 'statements')) {
+        if (statement.kind !== kinds.ImportDeclaration)
+            continue;
+        const from = stringValue(field(statement, 'moduleSpecifier'));
+        if (from !== 'node:test' && from !== 'test')
+            continue;
+        const clause = field(statement, 'importClause');
+        const bindings = clause && field(clause, 'namedBindings');
+        for (const name of [
+            clause && field(clause, 'name'),
+            bindings && field(bindings, 'name'),
+            ...(bindings ? nodes(bindings, 'elements').map((element) => field(element, 'name')) : []),
+        ])
+            if (name?.kind === kinds.Identifier)
+                testNames.add(String(property(name, 'text')));
+    }
+    /** The identifier a call chain starts from: `test` of `test.skip(…)`. */
+    const calleeRoot = (call) => {
+        let current = field(call, 'expression');
+        while (current?.kind === kinds.PropertyAccessExpression)
+            current = field(current, 'expression');
+        return current?.kind === kinds.Identifier ? String(property(current, 'text')) : undefined;
+    };
+    const visit = (node) => {
+        const kind = node.kind;
+        if (kind === kinds.CatchClause) {
+            const block = field(node, 'block');
+            if (block && nodes(block, 'statements').length === 0)
+                push(report(node, 'empty-catch', 'An empty catch block hides the error (D-0047: no silent catch)', 'rethrow it, turn it into a coded error for the caller, or log it at error level (fixed message, code, error); if ignoring is really right, write // dokebi-check: allow empty-catch <reason> in the block'));
+        }
+        else if (kind === kinds.CallExpression) {
+            const args = nodes(node, 'arguments');
+            const method = methodName(node);
+            const callee = field(node, 'expression');
+            if (method === 'catch' && emptyFunction(args[0]))
+                push(report(node, 'empty-catch', `${snippet(node)} drops the rejection with an empty handler (D-0047)`, 'handle or log the error in the handler (error level, code, error); to keep only an unhandled-rejection guard on a promise you also return, write // dokebi-check: allow empty-catch <reason>'));
+            else if (method === 'then' && emptyFunction(args[1]))
+                push(report(node, 'empty-catch', `${snippet(node)} drops the rejection with an empty onRejected handler (D-0047)`, 'handle or log the error in the second handler, or remove it and let the caller see the rejection'));
+            else if (method &&
+                LISTEN.has(method) &&
+                stringValue(args[0]) === 'error' &&
+                emptyFunction(args[1]))
+                push(report(node, 'empty-catch', `An empty '${method}('error', …)' listener hides every error of that emitter (D-0047)`, 'log the error (error level, code, error) and close or replace the resource; write // dokebi-check: allow empty-catch <reason> only for a deliberate drop'));
+            if (callee?.kind === kinds.ImportKeyword) {
+                const value = stringValue(args[0]);
+                if (value !== undefined)
+                    specifiers.push({ node: args[0], value });
+            }
+        }
+        else if (kind === kinds.ExpressionStatement) {
+            const expression = unwrap(field(node, 'expression'));
+            if (expression &&
+                (expression.kind === kinds.CallExpression || expression.kind === kinds.NewExpression)) {
+                const method = expression.kind === kinds.CallExpression ? methodName(expression) : undefined;
+                const args = nodes(expression, 'arguments');
+                // `.catch(handler)` and `.then(ok, onRejected)` handle the rejection themselves.
+                const handled = (method === 'catch' && args.length >= 1) ||
+                    (method === 'then' && args.length >= 2) ||
+                    (expression.kind === kinds.CallExpression && testNames.has(calleeRoot(expression) ?? ''));
+                if (!handled) {
+                    const problem = report(node, 'floating-promise', `${snippet(expression)} returns a Promise that nothing awaits: its rejection becomes an unhandled rejection and stops the process`, 'await it (or return it to the caller); for deliberate background work end it with .catch(error => <log at error level>)');
+                    if (problem)
+                        candidates.push({ expression, problem });
+                }
+            }
+        }
+        else if (kind === kinds.EnumDeclaration) {
+            if (!hasModifier(node, kinds.DeclareKeyword))
+                unsupported(node, `enum ${snippet(field(node, 'name') ?? node)}`, "use a const object and a union type: export const Color = { Red: 'red' } as const; export type Color = (typeof Color)[keyof typeof Color];");
+        }
+        else if (kind === kinds.ModuleDeclaration) {
+            const name = field(node, 'name');
+            if (name?.kind === kinds.Identifier &&
+                !hasModifier(node, kinds.DeclareKeyword) &&
+                node.parent?.kind !== kinds.ModuleDeclaration &&
+                instantiated(field(node, 'body')))
+                unsupported(node, `namespace ${String(property(name, 'text'))} with values`, 'use an ES module (its own file) or a plain object; namespaces with only types are fine');
+        }
+        else if (kind === kinds.Parameter) {
+            if (node.parent?.kind === kinds.Constructor &&
+                nodes(node, 'modifiers').some((modifier) => parameterModifiers.has(modifier.kind)))
+                unsupported(node, `The parameter property "${snippet(node)}"`, 'declare the field in the class and assign it in the constructor: readonly name: T; constructor(name: T) { this.name = name; }');
+        }
+        else if (kind === kinds.Decorator) {
+            push(report(node, 'non-erasable-syntax', `The decorator ${snippet(node)} cannot run: Node has no decorators (SyntaxError at start)`, 'call the function yourself (wrap the class or method, or register it explicitly)'));
+        }
+        else if (kind === kinds.ImportEqualsDeclaration) {
+            if (property(node, 'isTypeOnly') !== true)
+                unsupported(node, `"${snippet(node)}"`, "use import x from '…' (or createRequire from node:module for CommonJS)");
+            const reference = field(node, 'moduleReference');
+            const value = reference?.kind === kinds.ExternalModuleReference
+                ? stringValue(field(reference, 'expression'))
+                : undefined;
+            if (value !== undefined && reference)
+                specifiers.push({ node: reference, value });
+        }
+        else if (kind === kinds.ExportAssignment) {
+            if (property(node, 'isExportEquals') === true)
+                unsupported(node, '"export ="', 'use export default …');
+        }
+        else if (kind === kinds.TypeAssertionExpression) {
+            unsupported(node, `The type assertion ${snippet(node)}`, 'write value as T');
+        }
+        else if (kind === kinds.ImportDeclaration || kind === kinds.ExportDeclaration) {
+            const specifier = field(node, 'moduleSpecifier');
+            const value = stringValue(specifier);
+            if (value !== undefined && specifier)
+                specifiers.push({ node: specifier, value });
+        }
+        else if (kind === kinds.ImportType) {
+            const argument = field(node, 'argument');
+            const literal = argument?.kind === kinds.LiteralType ? field(argument, 'literal') : undefined;
+            const value = stringValue(literal);
+            if (value !== undefined && literal)
+                specifiers.push({ node: literal, value });
+        }
+        node.forEachChild(visit);
+        return undefined;
+    };
+    file.forEachChild(visit);
+    for (const { node, value } of specifiers) {
+        const verdict = await imports.verdict(file.fileName, value);
+        if (verdict)
+            push(report(node, verdict.rule, verdict.message, verdict.fix));
+    }
+    return { problems, candidates };
+}
+/** Every program file: syntactic problems, then one batched checker call for the candidates. */
+export async function sourceProblems(typescript, root, imports, skip) {
+    const problems = [];
+    const candidates = [];
+    let files = 0;
+    for (const file of typescript.files) {
+        const path = relative(root, file.fileName.split('/').join(sep)).split(sep).join('/');
+        if (skip(path))
+            continue;
+        files++;
+        const found = await inspectFile(file, typescript.kinds, root, imports);
+        problems.push(...found.problems);
+        candidates.push(...found.candidates);
+    }
+    const verdicts = typescript.promises(candidates.map((candidate) => candidate.expression));
+    candidates.forEach((candidate, index) => {
+        if (verdicts[index])
+            problems.push(candidate.problem);
+    });
+    return { problems, files };
+}