@dokebi/cli 0.4.2 → 0.4.27

package/dist/check/structure-rules.js

@@ -0,0 +1,502 @@
+// Structure rules of `dokebi check` (D-0105 §2–§3), warnings over the TypeScript AST of the
+// app's models, controllers and services (src/**/models|controllers|services/**):
+//   responsibility-size  one file that carries several responsibilities, measured on the AI
+//                        consumer rounds AI-M22..M24 (D-0105 §3 has the numbers):
+//                        - a model with at least MODEL_LINES code lines that reaches at least
+//                          MODEL_TABLES tables or collections (names after FROM, JOIN, INTO,
+//                          UPDATE in SQL text, CTE names excluded; Mongo `.collection('x')` and
+//                          a local helper that wraps it; Kysely selectFrom/insertInto/…),
+//                        - a controller with at least CONTROLLER_HANDLERS route handlers
+//                          (public methods and function-valued fields) or CONTROLLER_LINES code
+//                          lines,
+//                        - a service class whose methods mostly forward their parameters to one
+//                          call on a field (`return this.model.list(user, filter)`): at least
+//                          SERVICE_FORWARDS such methods and FORWARD_SHARE of all its methods.
+//   memory-filtered-page rows an awaited query returned that are filtered in code by an input of
+//                        the function and then cut to a page: `rows.filter((row) => row.x ===
+//                        input.x).slice(…)`, or a `for (const row of rows)` loop that skips rows
+//                        with `if (row.x !== input.x) continue` and stops with `break` once a
+//                        `.length` reaches a size. The filter belongs in the query (§6.2). A
+//                        search that checks its other terms on a capped candidate set (§6.10)
+//                        compares with term sets, not inputs, and is not matched.
+// Code lines are lines with something besides whitespace and comments. Files that say they are
+// generated (`@generated`, `generated by`, `do not edit` in their first lines) are not read.
+import { field, nodes, property, } from './typescript.js';
+/** D-0105 §3: the smallest measured model that carried several features had 486 code lines. */
+export const MODEL_LINES = 400;
+export 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 const CONTROLLER_HANDLERS = 20;
+export const CONTROLLER_LINES = 300;
+/** D-0105 §3: services that only forwarded had 10–15 such methods out of 15–21. */
+export const SERVICE_FORWARDS = 5;
+export const FORWARD_SHARE = 0.6;
+/** The layer of an app file by its folder (D-0031, D-0032), or undefined outside them. */
+export function layerOf(path) {
+    if (!path.startsWith('src/') || /(^|\/)(views|public)\//.test(path))
+        return undefined;
+    if (/\/models\//.test(path))
+        return 'model';
+    if (/\/controllers\//.test(path))
+        return 'controller';
+    if (/\/services\//.test(path))
+        return 'service';
+    return undefined;
+}
+/** Lines with code: comments and blank lines do not count (string contents do, SQL is code). */
+export function codeLines(text) {
+    let count = 0;
+    let code = false;
+    let index = 0;
+    const length = text.length;
+    while (index < length) {
+        const char = text[index];
+        const next = text[index + 1];
+        if (char === '\n') {
+            if (code)
+                count++;
+            code = false;
+            index++;
+        }
+        else if (char === '/' && next === '/') {
+            const end = text.indexOf('\n', index);
+            index = end === -1 ? length : end;
+        }
+        else if (char === '/' && next === '*') {
+            const end = text.indexOf('*/', index + 2);
+            const stop = end === -1 ? length : end + 2;
+            // Newlines inside the comment end lines that may already hold code.
+            for (let at = index; at < stop; at++)
+                if (text[at] === '\n') {
+                    if (code)
+                        count++;
+                    code = false;
+                }
+            index = stop;
+        }
+        else if (char === "'" || char === '"' || char === '`') {
+            code = true;
+            let at = index + 1;
+            while (at < length && text[at] !== char) {
+                if (text[at] === '\\')
+                    at++;
+                else if (text[at] === '\n') {
+                    if (char !== '`')
+                        break;
+                    count++;
+                }
+                at++;
+            }
+            index = at + 1;
+        }
+        else {
+            if (char !== ' ' && char !== '\t' && char !== '\r')
+                code = true;
+            index++;
+        }
+    }
+    if (code)
+        count++;
+    return count;
+}
+const GENERATED = /@generated|generated by|do not edit/i;
+const SQL = /\bselect\b[\s\S]*\bfrom\b|\binsert\s+into\b|\bupdate\s+[\w."`]+\s+set\b|\bdelete\s+from\b/i;
+const TABLE = /\b(from|join|into|update)\s+(?:only\s+)?([`"]?)([A-Za-z_]\w*)\2(?:\.([`"]?)([A-Za-z_]\w*)\4)?(\s*\()?/gi;
+const CTE = /(?:\bwith\s+(?:recursive\s+)?|,\s*)([A-Za-z_]\w*)\s+as\s+(?:(?:not\s+)?materialized\s+)?\(/gi;
+/** Words after FROM/JOIN/INTO/UPDATE that are SQL, not a table. */
+const NOT_TABLES = new Set([
+    'select',
+    'set',
+    'lateral',
+    'skip',
+    'nowait',
+    'of',
+    'only',
+    'dual',
+    'values',
+    'the',
+    'a',
+    'an',
+]);
+const BUILDER_METHODS = new Set([
+    'collection',
+    'selectFrom',
+    'insertInto',
+    'updateTable',
+    'deleteFrom',
+    'replaceInto',
+    'mergeInto',
+]);
+/** Table names in one piece of SQL text (EXTRACT(… FROM x) and CTE names excluded). */
+export function sqlTables(sql, into) {
+    if (!SQL.test(sql))
+        return;
+    const source = sql
+        .replace(/\b(?:extract|substring|trim|position|overlay)\s*\([^()]*\)/gi, ' ')
+        // An upsert's UPDATE names columns: ON DUPLICATE KEY UPDATE x = …, ON CONFLICT … DO UPDATE SET.
+        .replace(/\b(?:duplicate\s+key|do)\s+update\b/gi, ' ');
+    const ctes = new Set();
+    for (const match of source.matchAll(CTE))
+        ctes.add(match[1].toLowerCase());
+    for (const match of source.matchAll(TABLE)) {
+        // FROM unnest(…), JOIN generate_series(…) read a function; INTO t(a, b) names columns.
+        if (match[6] && !/^into$/i.test(match[1]))
+            continue;
+        const table = (match[5] ?? match[3] ?? '').toLowerCase();
+        if (!table || NOT_TABLES.has(table) || ctes.has(table))
+            continue;
+        into.add(table);
+    }
+}
+export function structureRules(file, layer, kinds, report) {
+    const text = file.text;
+    if (GENERATED.test(text.split('\n', 3).join('\n')))
+        return;
+    const name = (node) => node && (node.kind === kinds.Identifier || node.kind === kinds.PrivateIdentifier)
+        ? String(property(node, 'text'))
+        : undefined;
+    const literal = (node) => node && (node.kind === kinds.StringLiteral || node.kind === kinds.NoSubstitutionTemplateLiteral)
+        ? String(property(node, 'text'))
+        : undefined;
+    const unwrap = (node) => {
+        let current = node;
+        while (current &&
+            (current.kind === kinds.ParenthesizedExpression ||
+                current.kind === kinds.AwaitExpression ||
+                current.kind === kinds.AsExpression ||
+                current.kind === kinds.NonNullExpression))
+            current = field(current, 'expression');
+        return current;
+    };
+    const methodOf = (call) => {
+        const callee = field(call, 'expression');
+        return callee?.kind === kinds.PropertyAccessExpression
+            ? name(field(callee, 'name'))
+            : undefined;
+    };
+    const functional = (node) => node.kind === kinds.ArrowFunction ||
+        node.kind === kinds.FunctionExpression ||
+        node.kind === kinds.FunctionDeclaration ||
+        node.kind === kinds.MethodDeclaration;
+    const lines = layer === 'service' ? 0 : codeLines(text);
+    const first = nodes(file, 'statements')[0] ?? file;
+    if (layer === 'model' && lines >= MODEL_LINES) {
+        const tables = new Set();
+        // Local helpers that wrap `.collection(name)`: `c('tickets')` names a collection too.
+        const helpers = new Set();
+        const findHelpers = (node) => {
+            if (functional(node)) {
+                let wraps = false;
+                const look = (inner) => {
+                    if (inner.kind === kinds.CallExpression &&
+                        methodOf(inner) === 'collection' &&
+                        !literal(nodes(inner, 'arguments')[0]))
+                        wraps = true;
+                    if (!wraps)
+                        inner.forEachChild(look);
+                    return undefined;
+                };
+                node.forEachChild(look);
+                const own = name(field(node, 'name')) ??
+                    (node.parent?.kind === kinds.VariableDeclaration ||
+                        node.parent?.kind === kinds.PropertyDeclaration
+                        ? name(field(node.parent, 'name'))
+                        : undefined);
+                if (wraps && own)
+                    helpers.add(own);
+            }
+            node.forEachChild(findHelpers);
+            return undefined;
+        };
+        findHelpers(file);
+        const walk = (node) => {
+            const kind = node.kind;
+            if (kind === kinds.StringLiteral || kind === kinds.NoSubstitutionTemplateLiteral)
+                sqlTables(String(property(node, 'text')), tables);
+            else if (kind === kinds.TemplateExpression) {
+                const head = field(node, 'head');
+                const parts = [head ? String(property(head, 'text')) : ''];
+                for (const span of nodes(node, 'templateSpans')) {
+                    const piece = field(span, 'literal');
+                    parts.push(piece ? String(property(piece, 'text')) : '');
+                }
+                sqlTables(parts.join(' ? '), tables);
+            }
+            else if (kind === kinds.CallExpression) {
+                const callee = field(node, 'expression');
+                const method = callee?.kind === kinds.PropertyAccessExpression
+                    ? name(field(callee, 'name'))
+                    : name(callee);
+                const argument = literal(nodes(node, 'arguments')[0]);
+                if (argument && method && (BUILDER_METHODS.has(method) || helpers.has(method)))
+                    tables.add(argument.toLowerCase());
+            }
+            node.forEachChild(walk);
+            return undefined;
+        };
+        walk(file);
+        if (tables.size >= MODEL_TABLES)
+            report(first, 'responsibility-size', `This model has ${lines} code lines over ${tables.size} tables or collections (${[...tables].sort().slice(0, 12).join(', ')}${tables.size > 12 ? ', …' : ''}): one file carries several features, and every change touches all of them`, 'split it by feature, one model per table group (src/apps/<app>/models/<feature>.ts or src/shared/modules/<feature>/models/), each with its own queries; the service that runs one use case passes its transaction to each model');
+    }
+    if (layer === 'controller') {
+        // Route handlers: public methods and function-valued fields of the controller classes.
+        let handlers = 0;
+        const countHandlers = (node) => {
+            if (node.kind === kinds.ClassDeclaration || node.kind === kinds.ClassExpression)
+                for (const member of nodes(node, 'members')) {
+                    if (member.kind === kinds.PrivateIdentifier ||
+                        field(member, 'name')?.kind === kinds.PrivateIdentifier)
+                        continue;
+                    if (nodes(member, 'modifiers').some((modifier) => modifier.kind === kinds.PrivateKeyword ||
+                        modifier.kind === kinds.ProtectedKeyword ||
+                        modifier.kind === kinds.StaticKeyword))
+                        continue;
+                    const initializer = unwrap(field(member, 'initializer'));
+                    if (member.kind === kinds.MethodDeclaration ||
+                        (member.kind === kinds.PropertyDeclaration &&
+                            initializer !== undefined &&
+                            functional(initializer)))
+                        handlers++;
+                }
+            node.forEachChild(countHandlers);
+            return undefined;
+        };
+        countHandlers(file);
+        if (handlers >= CONTROLLER_HANDLERS || lines >= CONTROLLER_LINES)
+            report(first, 'responsibility-size', `This controller has ${handlers} handlers in ${lines} code lines: one controller that takes most routes of the app mixes the HTTP handling of unrelated features`, 'split it by feature or resource (one controller per resource in controllers/, or a feature module with npx dokebi module add <feature>); a handler reads the request, calls one service method and shapes the reply');
+    }
+    if (layer === 'service') {
+        const visitClass = (node) => {
+            if (node.kind === kinds.ClassDeclaration || node.kind === kinds.ClassExpression) {
+                let methods = 0;
+                let forwarding = 0;
+                for (const member of nodes(node, 'members')) {
+                    if (member.kind !== kinds.MethodDeclaration)
+                        continue;
+                    if (nodes(member, 'modifiers').some((modifier) => modifier.kind === kinds.StaticKeyword))
+                        continue;
+                    methods++;
+                    if (forwards(member))
+                        forwarding++;
+                }
+                if (forwarding >= SERVICE_FORWARDS && forwarding / methods >= FORWARD_SHARE)
+                    report(node, 'responsibility-size', `${forwarding} of the ${methods} methods of ${name(field(node, 'name')) ?? 'this service'} only pass their arguments on to a model: the service adds a layer without owning the use case, so the work lands in the controller or the model`, 'give the service the use case (validation of the inputs it takes, the transaction across models, the DTO it returns); call a model directly from another service only, never from a controller');
+            }
+            node.forEachChild(visitClass);
+            return undefined;
+        };
+        /** A method whose one statement returns `this.<field>.<method>(…its own parameters…)`. */
+        const forwards = (method) => {
+            const body = field(method, 'body');
+            const statements = body ? nodes(body, 'statements') : [];
+            if (statements.length !== 1)
+                return false;
+            const only = statements[0];
+            if (only.kind !== kinds.ReturnStatement && only.kind !== kinds.ExpressionStatement)
+                return false;
+            const call = unwrap(field(only, 'expression'));
+            if (call?.kind !== kinds.CallExpression)
+                return false;
+            const callee = field(call, 'expression');
+            const holder = callee?.kind === kinds.PropertyAccessExpression ? field(callee, 'expression') : undefined;
+            if (holder?.kind !== kinds.PropertyAccessExpression ||
+                field(holder, 'expression')?.kind !== kinds.ThisKeyword)
+                return false;
+            const parameters = new Set(nodes(method, 'parameters').flatMap((parameter) => name(field(parameter, 'name')) ?? []));
+            const rootOf = (node) => {
+                let current = node;
+                while (current?.kind === kinds.PropertyAccessExpression)
+                    current = field(current, 'expression');
+                return current;
+            };
+            return nodes(call, 'arguments').every((argument) => {
+                const value = argument.kind === kinds.SpreadElement ? field(argument, 'expression') : argument;
+                const root = rootOf(value);
+                if (root?.kind === kinds.ThisKeyword)
+                    return true; // a setting of the service
+                return root?.kind === kinds.Identifier && parameters.has(name(root));
+            });
+        };
+        visitClass(file);
+    }
+    if (layer === 'model' || layer === 'service')
+        memoryPages(file, kinds, report, { name, unwrap, methodOf, functional });
+}
+/**
+ * memory-filtered-page: rows from an awaited query, skipped in code by comparing a field of the
+ * row with an input of the function (`t.status !== f.status`), then cut to a page.
+ */
+function memoryPages(file, kinds, report, help) {
+    const { name, unwrap, methodOf, functional } = help;
+    const message = 'Rows the query returned are filtered here by an input of the function and then cut to a page: the database read a fixed window, so a page comes back short or empty while matches remain, and a rare filter value pages through hundreds of empty pages';
+    const fix = 'put the filter in the query (WHERE … with an index that starts with the equality filters and ends with the sort key) and LIMIT the page size + 1 (@dokebi/db AI.md 6.2); a capped candidate check of the other terms of a search (6.10) gets // dokebi-check: allow memory-filtered-page <reason>';
+    const COMPARE = new Set([
+        kinds.EqualsEqualsEqualsToken,
+        kinds.ExclamationEqualsEqualsToken,
+        kinds.EqualsEqualsToken,
+        kinds.ExclamationEqualsToken,
+        kinds.LessThanToken,
+        kinds.GreaterThanToken,
+        kinds.LessThanEqualsToken,
+        kinds.GreaterThanEqualsToken,
+    ]);
+    /** The identifier a chain of calls and property reads starts from (`pages` of `pages.flat()`). */
+    const chainRoot = (node) => {
+        let current = unwrap(node);
+        while (current &&
+            (current.kind === kinds.CallExpression || current.kind === kinds.PropertyAccessExpression))
+            current = unwrap(field(current, 'expression'));
+        return current;
+    };
+    const rootName = (node) => {
+        const root = chainRoot(node);
+        return root?.kind === kinds.Identifier ? name(root) : undefined;
+    };
+    /** Names bound by a declaration name or a parameter (destructuring included). */
+    const bound = (target, into) => {
+        if (!target)
+            return;
+        const own = name(target);
+        if (own)
+            into.add(own);
+        else
+            for (const element of nodes(target, 'elements'))
+                bound(field(element, 'name'), into);
+    };
+    /** Code under `node` that runs in the same function (nested functions are their own). */
+    const within = (node, check) => {
+        check(node);
+        node.forEachChild((child) => {
+            if (!functional(child))
+                within(child, check);
+            return undefined;
+        });
+    };
+    /** A comparison of a field of a row (`row.x`) with an input of the function (`input.y`). */
+    const comparesInput = (condition, row, inputs) => {
+        let found = false;
+        const look = (node) => {
+            if (found)
+                return undefined;
+            if (node.kind === kinds.BinaryExpression &&
+                COMPARE.has(field(node, 'operatorToken')?.kind ?? -1)) {
+                const left = field(node, 'left');
+                const right = field(node, 'right');
+                const sides = [left, right].map((side) => ({
+                    root: rootName(side),
+                    read: unwrap(side)?.kind === kinds.PropertyAccessExpression,
+                }));
+                const [a, b] = sides;
+                const rowField = (side) => side.read && side.root !== undefined && row.has(side.root);
+                const input = (side) => side.root !== undefined && inputs.has(side.root);
+                if ((rowField(a) && input(b)) || (rowField(b) && input(a)))
+                    found = true;
+            }
+            node.forEachChild(look);
+            return undefined;
+        };
+        look(condition);
+        return found;
+    };
+    const visitFunction = (fn) => {
+        const inputs = new Set();
+        for (const parameter of nodes(fn, 'parameters'))
+            bound(field(parameter, 'name'), inputs);
+        if (!inputs.size)
+            return;
+        const rows = new Set();
+        const fromRows = (value) => {
+            if (!value)
+                return false;
+            if (value.kind === kinds.AwaitExpression || unwrap(value)?.kind === kinds.AwaitExpression)
+                return true;
+            const root = rootName(value);
+            return root !== undefined && rows.has(root);
+        };
+        within(fn, (node) => {
+            if (node.kind === kinds.VariableDeclaration && fromRows(field(node, 'initializer')))
+                bound(field(node, 'name'), rows);
+            else if (node.kind === kinds.BinaryExpression &&
+                field(node, 'operatorToken')?.kind === kinds.EqualsToken &&
+                fromRows(field(node, 'right')))
+                bound(field(node, 'left'), rows);
+        });
+        if (!rows.size)
+            return;
+        const isRows = (node) => {
+            const root = rootName(node);
+            return root !== undefined && rows.has(root);
+        };
+        within(fn, (node) => {
+            if (node.kind === kinds.CallExpression && methodOf(node) === 'slice') {
+                // rows.filter((row) => row.status === input.status).slice(0, size)
+                const receiver = unwrap(field(field(node, 'expression'), 'expression'));
+                if (receiver?.kind !== kinds.CallExpression || methodOf(receiver) !== 'filter')
+                    return;
+                if (!isRows(field(field(receiver, 'expression'), 'expression')))
+                    return;
+                const callback = unwrap(nodes(receiver, 'arguments')[0]);
+                if (!callback || !functional(callback))
+                    return;
+                const row = new Set();
+                for (const parameter of nodes(callback, 'parameters'))
+                    bound(field(parameter, 'name'), row);
+                const body = field(callback, 'body');
+                if (row.size && body && comparesInput(body, row, inputs))
+                    report(node, 'memory-filtered-page', message, fix);
+            }
+            else if (node.kind === kinds.ForOfStatement && isRows(field(node, 'expression'))) {
+                // for (const row of rows) { if (row.status !== input.status) continue; …; if (page.length === size) break; }
+                const row = new Set();
+                const declared = field(node, 'initializer');
+                for (const declaration of declared
+                    ? nodes(field(declared, 'declarationList') ?? declared, 'declarations')
+                    : [])
+                    bound(field(declaration, 'name'), row);
+                let skips = false;
+                let stops = false;
+                const body = field(node, 'statement');
+                const exits = (statement, kind) => statement?.kind === kind ||
+                    (statement?.kind === kinds.Block &&
+                        nodes(statement, 'statements').some((inner) => inner.kind === kind));
+                const look = (child) => {
+                    if (functional(child) ||
+                        child.kind === kinds.ForOfStatement ||
+                        child.kind === kinds.ForStatement ||
+                        child.kind === kinds.ForInStatement ||
+                        child.kind === kinds.WhileStatement ||
+                        child.kind === kinds.DoStatement)
+                        return undefined;
+                    if (child.kind === kinds.IfStatement) {
+                        const condition = field(child, 'expression');
+                        const consequent = field(child, 'thenStatement');
+                        if (condition &&
+                            exits(consequent, kinds.ContinueStatement) &&
+                            comparesInput(condition, row, inputs))
+                            skips = true;
+                        if (condition &&
+                            exits(consequent, kinds.BreakStatement) &&
+                            /\.length\b/.test(file.text.slice(condition.getStart(), condition.end)))
+                            stops = true;
+                    }
+                    child.forEachChild(look);
+                    return undefined;
+                };
+                if (body && row.size)
+                    look(body);
+                if (skips && stops)
+                    report(node, 'memory-filtered-page', message, fix);
+            }
+        });
+    };
+    const visit = (node) => {
+        if (functional(node))
+            visitFunction(node);
+        node.forEachChild(visit);
+        return undefined;
+    };
+    visit(file);
+}

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

@@ -0,0 +1,7 @@
+import { type Kinds, type TsNode, type TsSourceFile } from './typescript.js';
+export type Report = (node: TsNode, message: string, fix: string, rule?: 'background-timer' | 'polling-loop') => void;
+/** Paths the rule reads: server code under src/, without views (browser code) and tests. */
+export declare function isServerCode(path: string): boolean;
+export declare const TIMER_FIX = "run periodic work as a job: register the handler in the setup of the module that owns it (context.getDependency(job).queue(<queue>).handle(<type>, async (payload, { signal }) => \u2026), src/shared/modules/<module>/module.ts) and add its entry to options.dokebi-scheduler.schedules in dokebi.yaml (npx dokebi add @dokebi/job, then @dokebi/scheduler); inside one job use await setTimeout(ms, undefined, { signal }) from node:timers/promises between bounded batches. Per-process upkeep of in-memory state that no job can reach: // dokebi-check: allow background-timer <reason>";
+export declare const POLLING_FIX = "move the loop to background work the framework runs: an @dokebi/outbox handler (one coalesced item per owner and window with a dedupeKey, its handler doing one bounded batch through context.db and enqueuing the next while work remains) or a @dokebi/job handler with an options.dokebi-scheduler.schedules entry; a dokebi-check marker does not silence this rule";
+export declare function timerRules(file: TsSourceFile, kinds: Kinds, report: Report): void;