@dokebi/cli 0.4.2 → 0.4.27

package/dist/check/wait-rules.js

@@ -0,0 +1,337 @@
+// The wait-count rule of `dokebi check` (@dokebi/db AI.md §1.2 and §6.4, AI-M34), over the
+// TypeScript AST:
+//   wait-count-refusal  (warning) server code under src/ (not views/, not tests/) that compares
+//                       how many callers wait for a database connection with a number: pg's
+//                       `pool.waitingCount`, mariadb's `pool.taskQueueSize()`, the MongoDB
+//                       driver's `waitQueueSize` and mysql2's `pool._connectionQueue.length`.
+//                       The number of waiters says nothing about overload (a pool of 10 serving
+//                       5 ms statements clears 100 waiters in about 50 ms), so refusing work on
+//                       it refuses work the database can still do (M34: 60% of 200 concurrent
+//                       requests refused by an idle app). Bound the wait by its deadline instead
+//                       (waitTimeoutMs, then 503 with Retry-After) and shed per tenant on time.
+//   in-process-queue    (warning) server code that parks callers in its own queue: the resolve
+//                       of a `new Promise` executor pushed into a collection (`.push`,
+//                       `.unshift`, `.set`, `.add`) to be called later. @dokebi/db AI.md says
+//                       never build in-process queues or mutexes around database writes: such a
+//                       queue has no bound or deadline (M35: requests waited up to 63 s, no 503),
+//                       is per worker, and drops its place on a restart. Let the pool's wait
+//                       deadline bound the wait and shed one tenant by time instead.
+//   fixed-owner-cap     (warning) a per-owner count of requests in progress (a Map entry that goes
+//                       up and down by one) compared with a fixed limit before a refusal, without
+//                       asking whether a connection is free: it refuses work while the database is
+//                       idle (M37: a cap of 12 refused up to 1.6 % of a burst at 9 % database CPU).
+//                       Refuse an owner only while the pool is full (@dokebi/db AI.md 6.4).
+// A `// dokebi-check: allow wait-count-refusal <reason>` (or `in-process-queue`) comment keeps a
+// deliberate one (a metric or a log line that only reports the number; a queue of a library
+// adapter written in the app).
+import { field } from './typescript.js';
+/** Properties (or methods) that count the callers waiting for a pool connection. */
+const WAIT_COUNTS = new Set(['waitingCount', 'taskQueueSize', 'waitQueueSize']);
+export const WAIT_FIX = 'bound the wait for a connection by its deadline instead (the pool option waitTimeoutMs: past it the caller gets 503 DB_UNAVAILABLE with Retry-After) and shed one tenant by the time its requests already hold, never by how many callers wait; a metric or log line that only reports the number takes // dokebi-check: allow wait-count-refusal <reason>';
+export const QUEUE_FIX = 'do not hold callers in a queue of your own: send the database work at once and let the pool bound the wait (waitTimeoutMs, then 503 DB_UNAVAILABLE with Retry-After), shedding one tenant by time it already holds; ordered background work goes to @dokebi/outbox. A deliberate one takes // dokebi-check: allow in-process-queue <reason>';
+/** Callers parked in a collection: the resolve of a `new Promise` executor stored to call later. */
+export function queueRules(file, kinds, report) {
+    if (!/\bnew\s+Promise\b/.test(file.text))
+        return;
+    const STORE = new Set(['push', 'unshift', 'set', 'add']);
+    const text = (node) => file.text.slice(node.getStart(), node.end);
+    const functional = (node) => node !== undefined &&
+        (node.kind === kinds.ArrowFunction || node.kind === kinds.FunctionExpression);
+    const uses = (node, name) => {
+        let found = false;
+        const walk = (child) => {
+            if (child.kind === kinds.Identifier && text(child) === name)
+                found = true;
+            if (!found)
+                child.forEachChild(walk);
+            return undefined;
+        };
+        walk(node);
+        return found;
+    };
+    const visit = (node) => {
+        if (node.kind === kinds.NewExpression &&
+            text(field(node, 'expression')) === 'Promise') {
+            const executor = node.arguments?.[0];
+            const first = functional(executor)
+                ? executor.parameters[0]
+                : undefined;
+            const resolve = first ? field(first, 'name') : undefined;
+            if (executor && resolve?.kind === kinds.Identifier) {
+                const name = text(resolve);
+                // Names that hold the resolve (`const pending = { input, resolve }`, `const fresh =
+                // [pending]`), followed until nothing new: a store of any of them parks the caller (M36).
+                const held = new Set([name]);
+                const holds = (node) => [...held].some((item) => uses(node, item));
+                for (let grew = true; grew;) {
+                    grew = false;
+                    const scan = (child) => {
+                        if (child.kind === kinds.VariableDeclaration) {
+                            const own = field(child, 'name');
+                            const value = field(child, 'initializer');
+                            if (own?.kind === kinds.Identifier && value && !held.has(text(own)) && holds(value)) {
+                                held.add(text(own));
+                                grew = true;
+                            }
+                        }
+                        child.forEachChild(scan);
+                        return undefined;
+                    };
+                    scan(executor);
+                }
+                const walk = (child) => {
+                    if (child.kind === kinds.CallExpression) {
+                        const callee = field(child, 'expression');
+                        const method = callee?.kind === kinds.PropertyAccessExpression ? field(callee, 'name') : undefined;
+                        const args = child.arguments ?? [];
+                        if (method && STORE.has(text(method)) && args.some((arg) => holds(arg))) {
+                            report(child, `the resolve of a new Promise is stored with ${text(method)}() to be called later: callers wait in a queue of this worker, without a bound or a deadline, and lose their place on a restart (@dokebi/db AI.md: no in-process queues around database writes; M35)`, QUEUE_FIX);
+                            return undefined;
+                        }
+                    }
+                    child.forEachChild(walk);
+                    return undefined;
+                };
+                walk(executor);
+            }
+        }
+        node.forEachChild(visit);
+        return undefined;
+    };
+    file.forEachChild(visit);
+}
+export function waitRules(file, kinds, report) {
+    // Most files never look at a pool's queue: skip the walk.
+    if (!/\b(?:waitingCount|taskQueueSize|waitQueueSize|_connectionQueue)\b/.test(file.text))
+        return;
+    const COMPARISONS = new Set([
+        kinds.GreaterThanToken,
+        kinds.GreaterThanEqualsToken,
+        kinds.LessThanToken,
+        kinds.LessThanEqualsToken,
+    ]);
+    const name = (node) => node && (node.kind === kinds.Identifier || node.kind === kinds.PrivateIdentifier)
+        ? file.text.slice(node.getStart(), node.end)
+        : undefined;
+    const unwrap = (node) => {
+        let current = node;
+        while (current?.kind === kinds.ParenthesizedExpression)
+            current = field(current, 'expression');
+        return current;
+    };
+    /** The waiting count this side reads, or undefined. */
+    const waitCount = (side) => {
+        let value = unwrap(side);
+        // `pool.taskQueueSize()`: the method of mariadb.
+        if (value?.kind === kinds.CallExpression)
+            value = field(value, 'expression');
+        if (value?.kind !== kinds.PropertyAccessExpression)
+            return undefined;
+        const member = name(field(value, 'name'));
+        if (member && WAIT_COUNTS.has(member))
+            return member;
+        // mysql2: `pool._connectionQueue.length`.
+        const inner = field(value, 'expression');
+        if (member === 'length' &&
+            inner?.kind === kinds.PropertyAccessExpression &&
+            name(field(inner, 'name')) === '_connectionQueue')
+            return '_connectionQueue.length';
+        return undefined;
+    };
+    const visit = (node) => {
+        if (node.kind === kinds.BinaryExpression) {
+            const operator = field(node, 'operatorToken');
+            if (operator && COMPARISONS.has(operator.kind)) {
+                const counted = waitCount(field(node, 'left')) ?? waitCount(field(node, 'right'));
+                if (counted)
+                    report(node, `${counted} compared with a number: the count of callers waiting for a connection is not overload, so a decision on it refuses work the database can still do (@dokebi/db AI.md 1.2 and 6.4)`, WAIT_FIX);
+            }
+        }
+        node.forEachChild(visit);
+        return undefined;
+    };
+    file.forEachChild(visit);
+}
+export const OWNER_CAP_FIX = "use the owner share of @dokebi/db instead of a count of your own: const release = context.getDependency(db).share(main).enter(owner) before the database work, release() after it; it refuses only while the pool is full (D-0156). By hand: refuse an owner only while the pool is full: admit every request while a connection is free (pg: max - pool.totalCount + pool.idleCount > 0) or the pool became full less than a connect time ago (connections being opened count as open), and when it is full refuse with 503 and Retry-After only an owner that already holds an equal share (max divided by the owners with requests in progress) (@dokebi/db AI.md 6.4, an owner's share). A budget that bounds something other than connections (the report CPU budget of @dokebi/db AI.md 6.9, a plan's quota) takes // dokebi-check: allow fixed-owner-cap <reason>";
+/**
+ * A per-owner count of requests in progress compared with a fixed limit (AI-M37): a Map whose
+ * entries go up by one and down by one in the same file, read into a variable that an `if`
+ * compares with `>=` or `>` before a throw or a return, with no free or idle connection in the
+ * condition. It refuses work while the database is idle.
+ */
+export function ownerCapRules(file, kinds, report) {
+    // Most files keep no counters in a Map: skip the walks.
+    if (!/\.get\([^)]*\)/.test(file.text) || !/[-+]\s*1\b/.test(file.text))
+        return;
+    const text = (node) => file.text.slice(node.getStart(), node.end);
+    const operator = (node) => {
+        const token = field(node, 'operatorToken');
+        return token ? text(token) : '';
+    };
+    // Maps read with `.get(`: the ones some `+ 1` and some `- 1` expression reads or writes.
+    const up = new Set();
+    const down = new Set();
+    const mapOf = (node) => {
+        if (node.kind !== kinds.CallExpression)
+            return undefined;
+        const callee = field(node, 'expression');
+        if (callee?.kind !== kinds.PropertyAccessExpression)
+            return undefined;
+        const method = field(callee, 'name');
+        const object = field(callee, 'expression');
+        return method && object && text(method) === 'get' ? text(object) : undefined;
+    };
+    const mapsIn = (node) => {
+        const found = [];
+        const walk = (child) => {
+            const map = mapOf(child);
+            if (map)
+                found.push(map);
+            child.forEachChild(walk);
+            return undefined;
+        };
+        walk(node);
+        return found;
+    };
+    // Variables holding `map.get(key)` (with `?? 0` or `|| 0`).
+    const counters = new Map();
+    const scan = (node) => {
+        if (node.kind === kinds.BinaryExpression) {
+            const right = field(node, 'right');
+            const left = field(node, 'left');
+            const op = operator(node);
+            if ((op === '+' || op === '-') && right && /^1$/.test(text(right)) && left) {
+                for (const map of mapsIn(left))
+                    (op === '+' ? up : down).add(map);
+                // `current + 1` where current holds map.get(key): counted below, once counters are known.
+                if (left.kind === kinds.Identifier)
+                    (op === '+' ? up : down).add(`#var:${text(left)}`);
+            }
+        }
+        else if (node.kind === kinds.VariableDeclaration) {
+            const name = field(node, 'name');
+            const value = field(node, 'initializer');
+            if (name?.kind === kinds.Identifier && value) {
+                const [map] = mapsIn(value);
+                if (map &&
+                    /^\(?\s*[\w.#]+\.get\([^)]*\)\s*(?:(?:\?\?|\|\|)\s*\d+)?\s*\)?(?:\s*\+\s*1)?$/.test(text(value)))
+                    counters.set(text(name), map);
+            }
+        }
+        node.forEachChild(scan);
+        return undefined;
+    };
+    file.forEachChild(scan);
+    for (const [name, map] of counters) {
+        if (up.has(`#var:${name}`))
+            up.add(map);
+        if (down.has(`#var:${name}`))
+            down.add(map);
+    }
+    const inFlight = (name) => {
+        const map = counters.get(name);
+        return map !== undefined && up.has(map) && down.has(map);
+    };
+    const exits = (node) => {
+        if (!node)
+            return false;
+        let found = false;
+        const walk = (child) => {
+            if (child.kind === kinds.ThrowStatement || child.kind === kinds.ReturnStatement)
+                found = true;
+            if (!found)
+                child.forEachChild(walk);
+            return undefined;
+        };
+        walk(node);
+        return found;
+    };
+    // Conditions about the pool's free connections, directly or through a variable made from them
+    // (`const free = max - pool.totalCount + pool.idleCount; const full = free <= 0`).
+    const POOL = /idle|free|totalCount|totalConnections/i;
+    const poolNames = new Set();
+    for (let grew = true; grew;) {
+        grew = false;
+        const collect = (node) => {
+            if (node.kind === kinds.VariableDeclaration) {
+                const name = field(node, 'name');
+                const value = field(node, 'initializer');
+                if (name?.kind === kinds.Identifier &&
+                    value &&
+                    !poolNames.has(text(name)) &&
+                    aboutPool(value)) {
+                    poolNames.add(text(name));
+                    grew = true;
+                }
+            }
+            node.forEachChild(collect);
+            return undefined;
+        };
+        file.forEachChild(collect);
+    }
+    function aboutPool(node) {
+        if (POOL.test(text(node)))
+            return true;
+        let found = false;
+        const walk = (child) => {
+            if (child.kind === kinds.Identifier && poolNames.has(text(child)))
+                found = true;
+            if (!found)
+                child.forEachChild(walk);
+            return undefined;
+        };
+        walk(node);
+        return found;
+    }
+    /** The comparison of an in-flight count with a limit in this condition, if any. */
+    const comparedIn = (condition) => {
+        let compared;
+        const walk = (child) => {
+            if (child.kind === kinds.BinaryExpression) {
+                const op = operator(child);
+                const left = field(child, 'left');
+                const right = field(child, 'right');
+                if ((op === '>=' || op === '>') && left?.kind === kinds.Identifier && inFlight(text(left)))
+                    compared = text(left);
+                if ((op === '<=' || op === '<') &&
+                    right?.kind === kinds.Identifier &&
+                    inFlight(text(right)))
+                    compared = text(right);
+            }
+            if (!compared)
+                child.forEachChild(walk);
+            return undefined;
+        };
+        walk(condition);
+        return compared;
+    };
+    // `guarded`: the code runs only when a condition about free connections decided it — inside
+    // either branch of such an `if`, or after one whose branch leaves the function (M38: the
+    // comparison nested in `if (free <= 0) { … }` is the guidance's own pattern).
+    const visit = (node, guarded) => {
+        if (node.kind === kinds.IfStatement) {
+            const condition = field(node, 'expression');
+            const pool = condition !== undefined && aboutPool(condition);
+            const compared = condition && !pool && !guarded ? comparedIn(condition) : undefined;
+            if (compared && exits(field(node, 'thenStatement')))
+                report(node, `${compared} counts one owner's requests in progress and is compared with a fixed limit: it refuses requests while connections are free and the database is idle (@dokebi/db AI.md 6.4, an owner's share; M37)`, OWNER_CAP_FIX);
+            node.forEachChild((child) => visit(child, guarded || pool));
+            return undefined;
+        }
+        const statements = node.statements;
+        if (node.kind !== file.kind && Array.isArray(statements)) {
+            let after = guarded;
+            for (const statement of statements) {
+                visit(statement, after);
+                if (statement.kind === kinds.IfStatement &&
+                    aboutPool(field(statement, 'expression')) &&
+                    exits(field(statement, 'thenStatement')))
+                    after = true;
+            }
+            return undefined;
+        }
+        node.forEachChild((child) => visit(child, guarded));
+        return undefined;
+    };
+    file.forEachChild((child) => visit(child, false));
+}

package/dist/commands.d.ts

@@ -11,6 +11,13 @@ export interface CommandHelp {
 export declare const COMMANDS: readonly CommandHelp[];
 /** True when the usage line of `dokebi <command>` names `flag` (absent `no-flag:` rules). */
 export declare function commandHasFlag(command: string, flag: string): boolean;
+/**
+ * The commands whose usage line takes --dry-run, in table order (AI-M04 F8: `--help` said only
+ * "changing commands", and an agent tried `start --dry-run`). Derived, so it cannot drift.
+ */
+export declare const DRY_RUN_COMMANDS: readonly string[];
+/** DRY_RUN_COMMANDS on one line, subcommands grouped: `app add/remove/link/unlink`. */
+export declare function dryRunList(): string;
 /** `dokebi <command> --help`: what each flag does, and one example (D-0065, AI-M01). */
 export declare const COMMAND_DETAILS: Readonly<Record<string, {
     readonly flags: readonly (readonly [string, string])[];