@dokebi/cli 0.4.2 → 0.4.27

package/dist/check/source-rules.js

@@ -1,7 +1,11 @@
 // 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)
+//                        `on('error', …)` listener, and the same handlers that only give back
+//                        nothing (`() => undefined`, `() => null`, `() => void 0`) (D-0047)
+//   missing-cause        a catch block that throws a new error and never reads the one it
+//                        caught (`catch { throw new X() }`): the original error is lost
+//                        (D-0047, D-0118)
 //   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)
@@ -9,9 +13,27 @@
 //                        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
+// and, when their plugin is installed, the security rules of security-rules.ts (D-0076 §6), and
+// when src/shared/errors.ts declares the app's codes, unknown-error-code (error-rules.ts, D-0077),
+// and in server code background-timer (timer-rules.ts), console-output (console-rules.ts,
+// D-0151) and the structure warnings
+// responsibility-size and memory-filtered-page (structure-rules.ts, D-0105), and
+// module-point-not-installed (module-rules.ts, D-0130).
+// Browser code outside the program (.vue scripts, views/ .js; browser-sources.ts, D-0120) gets
+// only empty-catch, missing-cause and floating-promise, typed by its own program.
 import { relative, sep } from 'node:path';
-import { MARKABLE } from './problems.js';
+import { assetRouteRules } from './asset-rules.js';
+import { consoleRules } from './console-rules.js';
+import { ERRORS_FILE, errorCodeRules, isAppCode, readErrorList, } from './error-rules.js';
+import { mailRules } from './mail-rules.js';
+import { modulePoints } from './module-rules.js';
+import { poolRules } from './pool-rules.js';
+import { BROWSER_RULES, MARKABLE, WARNING_RULES } from './problems.js';
+import { securityRules } from './security-rules.js';
+import { layerOf, structureRules } from './structure-rules.js';
+import { isServerCode, timerRules } from './timer-rules.js';
 import { field, nodes, property, } from './typescript.js';
+import { ownerCapRules, queueRules, waitRules } from './wait-rules.js';
 const LISTEN = new Set([
     'on',
     'once',
@@ -22,7 +44,7 @@ const LISTEN = new Set([
 ]);
 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;
+const MARKER = /dokebi-check:\s*allow\s+([a-z0-9-]+)[ \t]*(?:[:\-—–][ \t]*)?([^\n]*?)[ \t]*(?:\*\/|$)/gm;
 export function readMarkers(text) {
     const markers = [];
     let lineStart = 0;
@@ -43,16 +65,31 @@ export function readMarkers(text) {
     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('/');
+export async function inspectFile(file, kinds, root, imports, 
+/** Installed plugin ids: the security rules run only for the plugin they protect. */
+installed = new Set(), 
+/** The codes of src/shared/errors.ts (D-0077 D); unknown-error-code runs only with them. */
+errorList, 
+/**
+ * D-0120: a virtual browser source — the file problems name, and the only rules that run
+ * (the per-plugin, server and import rules do not apply to browser code).
+ */
+browser) {
+    const path = browser?.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 untypedImports = [];
     const specifiers = [];
+    /** console-output (D-0151): a marker before the first statement covers the whole file. */
+    const firstStatement = nodes(file, 'statements')[0];
+    const headerEnd = firstStatement ? lineOf(firstStatement.getStart()) : Number.POSITIVE_INFINITY;
     /** The problem, or nothing when a marker with a reason sits on or just above its lines. */
     const report = (node, rule, message, fix) => {
+        if (browser && !browser.rules.has(rule))
+            return undefined;
         const first = lineOf(node.getStart());
         const last = lineOf(Math.max(node.getStart(), node.end - 1));
         let note = '';
@@ -60,12 +97,21 @@ export async function inspectFile(file, kinds, root, imports) {
             for (const marker of markers)
                 if (marker.rule === rule &&
                     marker.line <= last &&
-                    (marker.line >= first || (marker.line === first - 1 && marker.ownLine))) {
+                    (marker.line >= first ||
+                        (marker.line === first - 1 && marker.ownLine) ||
+                        (rule === 'console-output' && marker.ownLine && marker.line < headerEnd))) {
                     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 };
+        const problem = {
+            rule,
+            ...(WARNING_RULES.has(rule) ? { severity: 'warning' } : {}),
+            file: path,
+            line: first,
+            message: message + note,
+            fix,
+        };
         return problem;
     };
     const push = (problem) => {
@@ -80,12 +126,57 @@ export async function inspectFile(file, kinds, root, imports) {
         ? 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) => {
+    const unwrap = (node) => {
+        let current = node;
+        while (current?.kind === kinds.ParenthesizedExpression)
+            current = field(current, 'expression');
+        return current;
+    };
+    /**
+     * An expression that does nothing: `undefined`, `null`, or `void` of a name or a literal
+     * (`void 0`, `void error`). A call (`void log(error)`) or any other value is not one: a
+     * fallback value such as `false` is the handler's decision, not a drop.
+     */
+    const nothing = (node) => {
+        const value = unwrap(node);
+        if (!value)
+            return false;
+        if (value.kind === kinds.NullKeyword)
+            return true;
+        if (value.kind === kinds.Identifier)
+            return property(value, 'text') === 'undefined';
+        if (value.kind !== kinds.VoidExpression)
+            return false;
+        const operand = unwrap(field(value, 'expression'));
+        return (operand !== undefined &&
+            (operand.kind === kinds.Identifier ||
+                operand.kind === kinds.NullKeyword ||
+                operand.kind === kinds.TrueKeyword ||
+                operand.kind === kinds.FalseKeyword ||
+                operand.kind === kinds.NumericLiteral ||
+                operand.kind === kinds.StringLiteral ||
+                operand.kind === kinds.NoSubstitutionTemplateLiteral));
+    };
+    /**
+     * An arrow or function expression that drops what it gets (D-0047): an empty block, a block
+     * that only returns nothing (`return;`, `return undefined;`, `return null;`), or an arrow whose
+     * body is nothing (`() => undefined`, `() => null`, `() => void 0`).
+     */
+    const emptyFunction = (argument) => {
+        const node = unwrap(argument);
         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;
+        if (body?.kind !== kinds.Block)
+            return nothing(body);
+        const statements = nodes(body, 'statements');
+        if (statements.length === 0)
+            return true;
+        const only = statements.length === 1 ? statements[0] : undefined;
+        if (only?.kind !== kinds.ReturnStatement)
+            return false;
+        const returned = field(only, 'expression');
+        return returned === undefined || nothing(returned);
     };
     /** The method name of `a.b(...)`, if the callee is a property access. */
     const methodName = (call) => {
@@ -95,12 +186,6 @@ export async function inspectFile(file, kinds, root, imports) {
         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)
@@ -146,26 +231,95 @@ export async function inspectFile(file, kinds, root, imports) {
             current = field(current, 'expression');
         return current?.kind === kinds.Identifier ? String(property(current, 'text')) : undefined;
     };
+    const functionKinds = new Set([
+        kinds.ArrowFunction,
+        kinds.FunctionExpression,
+        kinds.FunctionDeclaration,
+        kinds.MethodDeclaration,
+        kinds.Constructor,
+        kinds.GetAccessor,
+        kinds.SetAccessor,
+        kinds.ClassDeclaration,
+        kinds.ClassExpression,
+    ]);
+    /**
+     * D-0118: a catch block that throws a new error (`throw new X(…)`, or `throw fail(…)` — a call
+     * makes a new error too, AI-M46; outside nested functions) and never reads the error it caught —
+     * no binding, or a plain name that is never used. A destructured binding counts as read.
+     */
+    const losesCause = (clause, block) => {
+        const declaration = field(clause, 'variableDeclaration');
+        const binding = declaration && field(declaration, 'name');
+        if (binding && binding.kind !== kinds.Identifier)
+            return false;
+        const name = binding ? String(property(binding, 'text')) : undefined;
+        let throwsNew = false;
+        let reads = false;
+        const walk = (current, inFunction) => {
+            if (current.kind === kinds.ThrowStatement && !inFunction) {
+                const thrown = unwrap(field(current, 'expression'));
+                if (thrown?.kind === kinds.NewExpression || thrown?.kind === kinds.CallExpression)
+                    throwsNew = true;
+            }
+            if (name !== undefined &&
+                current.kind === kinds.Identifier &&
+                property(current, 'text') === name)
+                reads = true;
+            const nested = inFunction || functionKinds.has(current.kind);
+            current.forEachChild((child) => walk(child, nested));
+            return undefined;
+        };
+        block.forEachChild((child) => walk(child, false));
+        return throwsNew && !reads;
+    };
+    /**
+     * The value names an import binds (not `import type`, not a .vue component: a component is
+     * never called, and a project without a shim types none). Judged after the walk.
+     */
+    const untypedImport = (node, value) => {
+        const clause = field(node, 'importClause');
+        if (!clause || property(clause, 'isTypeOnly') === true)
+            return;
+        if (/\.(?:vue|css|scss|sass|less|svg|png|jpe?g|gif|webp|json)(?:\?.*)?$/.test(value))
+            return;
+        const bindings = field(clause, 'namedBindings');
+        const names = [
+            field(clause, 'name'),
+            bindings?.kind === kinds.NamespaceImport ? field(bindings, 'name') : undefined,
+            ...(bindings && bindings.kind !== kinds.NamespaceImport
+                ? nodes(bindings, 'elements')
+                    .filter((element) => property(element, 'isTypeOnly') !== true)
+                    .map((element) => field(element, 'name'))
+                : []),
+        ].filter((name) => name?.kind === kinds.Identifier);
+        if (!names.length)
+            return;
+        const problem = report(node, 'untyped-browser-import', `'${value}' has no types in the browser program: floating-promise cannot judge the calls of what this file imports from it`, `make its types resolve as the bundler does (the package's types, a declaration file such as src/infra/inertia/page.d.ts, or a relative path that exists); when the module really has no types, write // dokebi-check: allow untyped-browser-import <reason>`);
+        if (problem)
+            untypedImports.push({ names, problem });
+    };
     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 (block && losesCause(node, block))
+                push(report(node, 'missing-cause', 'This catch throws a new error and drops the one it caught: the original message and stack are lost (D-0047)', "name the caught error and pass it on: catch (error) { throw new X(…, { cause: error }) } (or the error class's cause argument); if the original must not travel, log it at debug first, or write // dokebi-check: allow missing-cause <reason>"));
         }
         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>'));
+                push(report(node, 'empty-catch', `${snippet(node)} drops the rejection with a handler that does nothing (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'));
+                push(report(node, 'empty-catch', `${snippet(node)} drops the rejection with an onRejected handler that does nothing (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'));
+                push(report(node, 'empty-catch', `A '${method}('error', …)' listener that does nothing 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)
@@ -183,7 +337,11 @@ export async function inspectFile(file, kinds, root, imports) {
                     (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>)');
+                    const problem = report(node, 'floating-promise', browser
+                        ? `${snippet(expression)} returns a Promise that nothing awaits: its rejection becomes an unhandled rejection in the browser that the page never handles or shows`
+                        : `${snippet(expression)} returns a Promise that nothing awaits: its rejection becomes an unhandled rejection and stops the process`, browser
+                        ? 'await it (or return it to the caller); for deliberate background work end it with .catch(error => <show or report the error>)'
+                        : '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 });
                 }
@@ -231,6 +389,8 @@ export async function inspectFile(file, kinds, root, imports) {
             const value = stringValue(specifier);
             if (value !== undefined && specifier)
                 specifiers.push({ node: specifier, value });
+            if (browser && kind === kinds.ImportDeclaration && value !== undefined)
+                untypedImport(node, value);
         }
         else if (kind === kinds.ImportType) {
             const argument = field(node, 'argument');
@@ -243,31 +403,92 @@ export async function inspectFile(file, kinds, root, imports) {
         return undefined;
     };
     file.forEachChild(visit);
+    if (browser)
+        return { problems, candidates, imports: untypedImports };
+    if (installed.has('dokebi-mail'))
+        mailRules(file, kinds, (node, rule, message, fix) => push(report(node, rule, message, fix)));
+    // D-0105: periodic work on the app's own timers, and files that carry several responsibilities.
+    if (isServerCode(path)) {
+        timerRules(file, kinds, (node, message, fix, rule = 'background-timer') => push(report(node, rule, message, fix)));
+        consoleRules(file, kinds, (node, message, fix) => push(report(node, 'console-output', message, fix)));
+        waitRules(file, kinds, (node, message, fix) => push(report(node, 'wait-count-refusal', message, fix)));
+        queueRules(file, kinds, (node, message, fix) => push(report(node, 'in-process-queue', message, fix)));
+        ownerCapRules(file, kinds, (node, message, fix) => push(report(node, 'fixed-owner-cap', message, fix)));
+        poolRules(file, path, kinds, (node, rule, message, fix) => push(report(node, rule, message, fix)));
+        assetRouteRules(file, kinds, (node, message, fix) => push(report(node, 'asset-route', message, fix)));
+    }
+    const layer = layerOf(path);
+    if (layer)
+        structureRules(file, layer, kinds, (node, rule, message, fix) => push(report(node, rule, message, fix)));
+    const auth = installed.has('dokebi-auth');
+    const csrf = installed.has('dokebi-csrf');
+    if (auth || csrf)
+        securityRules(file, kinds, { auth, csrf }, (node, rule, message, fix) => push(report(node, rule, message, fix)));
+    if (errorList && isAppCode(path))
+        errorCodeRules(file, path, kinds, errorList, (node, message, fix) => push(report(node, 'unknown-error-code', message, fix)));
     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));
     }
+    // D-0130: a module point whose plugin package is present but not installed in the project.
+    for (const point of modulePoints(file, kinds)) {
+        const plugin = await imports.pluginOf(file.fileName, point.specifier);
+        if (!plugin || installed.has(plugin.id))
+            continue;
+        push(report(point.node, 'module-point-not-installed', `Module ${point.module || '(unnamed)'} contributes to ${point.point} of ${plugin.package}, but this project has not installed ${plugin.id}: nothing registers the plugin that collects it, so the app drops the values (warn POINT_NOT_COLLECTED)`, `npx dokebi add ${plugin.package} --dry-run --json, then without --dry-run (read its AI.md first); or remove ${point.point} from contributes. When you register the plugin yourself, write // dokebi-check: allow module-point-not-installed <reason>`));
+    }
     return { problems, candidates };
 }
 /** Every program file: syntactic problems, then one batched checker call for the candidates. */
-export async function sourceProblems(typescript, root, imports, skip) {
+export async function sourceProblems(typescript, root, imports, skip, installed = new Set()) {
     const problems = [];
     const candidates = [];
     let files = 0;
+    const pathOf = (file) => relative(root, file.fileName.split('/').join(sep)).split(sep).join('/');
+    const errorsFile = typescript.files.find((file) => pathOf(file) === ERRORS_FILE);
+    const errorList = errorsFile ? readErrorList(errorsFile, typescript.kinds) : undefined;
     for (const file of typescript.files) {
-        const path = relative(root, file.fileName.split('/').join(sep)).split(sep).join('/');
+        const path = pathOf(file);
         if (skip(path))
             continue;
         files++;
-        const found = await inspectFile(file, typescript.kinds, root, imports);
+        const found = await inspectFile(file, typescript.kinds, root, imports, installed, errorList);
         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);
-    });
+    const browserCandidates = [];
+    const browserImports = [];
+    for (const { file, path } of typescript.browser) {
+        if (skip(path))
+            continue;
+        files++;
+        const found = await inspectFile(file, typescript.kinds, root, imports, installed, undefined, {
+            path,
+            rules: BROWSER_RULES,
+        });
+        problems.push(...found.problems);
+        browserCandidates.push(...found.candidates);
+        browserImports.push(...(found.imports ?? []));
+    }
+    // D-0120 §1.4: an import none of whose names has a type is reported, never passed silently.
+    const untyped = typescript.untyped(browserImports.flatMap((item) => item.names), true);
+    let at = 0;
+    for (const item of browserImports) {
+        const verdicts = untyped.slice(at, at + item.names.length);
+        at += item.names.length;
+        if (verdicts.every(Boolean))
+            problems.push(item.problem);
+    }
+    for (const [list, browser] of [
+        [candidates, false],
+        [browserCandidates, true],
+    ]) {
+        const verdicts = typescript.promises(list.map((candidate) => candidate.expression), browser);
+        list.forEach((candidate, index) => {
+            if (verdicts[index])
+                problems.push(candidate.problem);
+        });
+    }
     return { problems, files };
 }

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

@@ -0,0 +1,23 @@
+import { type Kinds, type TsNode, type TsSourceFile } from './typescript.js';
+export type StructureRule = 'responsibility-size' | 'memory-filtered-page';
+export type Report = (node: TsNode, rule: StructureRule, message: string, fix: string) => void;
+/** D-0105 §3: the smallest measured model that carried several features had 486 code lines. */
+export declare const MODEL_LINES = 400;
+export declare const MODEL_TABLES = 8;
+/**
+ * D-0105 §3: the controllers that took every route of their app had 22–34 handlers (176–467
+ * code lines); every other controller measured had at most 16 handlers and 214 code lines.
+ */
+export declare const CONTROLLER_HANDLERS = 20;
+export declare const CONTROLLER_LINES = 300;
+/** D-0105 §3: services that only forwarded had 10–15 such methods out of 15–21. */
+export declare const SERVICE_FORWARDS = 5;
+export declare const FORWARD_SHARE = 0.6;
+export type Layer = 'model' | 'controller' | 'service';
+/** The layer of an app file by its folder (D-0031, D-0032), or undefined outside them. */
+export declare function layerOf(path: string): Layer | undefined;
+/** Lines with code: comments and blank lines do not count (string contents do, SQL is code). */
+export declare function codeLines(text: string): number;
+/** Table names in one piece of SQL text (EXTRACT(… FROM x) and CTE names excluded). */
+export declare function sqlTables(sql: string, into: Set<string>): void;
+export declare function structureRules(file: TsSourceFile, layer: Layer, kinds: Kinds, report: Report): void;