@dokebi/cli 0.4.2 → 0.4.26

package/dist/check/typescript.js

@@ -4,6 +4,7 @@
 // TypeScript; it loads the copy the project installed, so the AST and the types are exactly what
 // `npm run typecheck` sees. The API is marked unstable, so only the few calls below are used and
 // a missing or changed API is a coded failure (TYPESCRIPT_UNAVAILABLE), never a silent pass.
+import { existsSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { join, sep } from 'node:path';
 import { pathToFileURL } from 'node:url';
@@ -25,42 +26,122 @@ export function property(node, name) {
 }
 /** SyntaxKind names the rules use; each must exist in the loaded TypeScript. */
 const KIND_NAMES = [
+    'ArrayLiteralExpression',
     'ArrowFunction',
+    'AsExpression',
+    'AwaitExpression',
+    'BarBarEqualsToken',
+    'BarBarToken',
+    'BinaryExpression',
+    'BindingElement',
     'Block',
+    'BreakStatement',
     'CallExpression',
     'CatchClause',
+    'ClassDeclaration',
+    'ClassExpression',
+    'ConditionalExpression',
     'Constructor',
-    'Decorator',
+    'ContinueStatement',
     'DeclareKeyword',
+    'Decorator',
+    'DoStatement',
+    'ElementAccessExpression',
     'EnumDeclaration',
+    'EqualsEqualsEqualsToken',
+    'EqualsEqualsToken',
+    'EqualsToken',
+    'ExclamationEqualsEqualsToken',
+    'ExclamationEqualsToken',
     'ExportAssignment',
     'ExportDeclaration',
+    'ExportKeyword',
     'ExpressionStatement',
     'ExternalModuleReference',
+    'FalseKeyword',
+    'ForInStatement',
+    'ForOfStatement',
+    'ForStatement',
+    'FunctionDeclaration',
     'FunctionExpression',
+    'GetAccessor',
+    'GreaterThanEqualsToken',
+    'GreaterThanToken',
     'Identifier',
+    'IfStatement',
     'ImportDeclaration',
     'ImportEqualsDeclaration',
     'ImportKeyword',
     'ImportType',
     'InterfaceDeclaration',
+    'LessThanEqualsToken',
+    'LessThanToken',
     'LiteralType',
+    'MethodDeclaration',
     'ModuleBlock',
     'ModuleDeclaration',
+    'NamedImports',
+    'NamespaceImport',
     'NewExpression',
     'NoSubstitutionTemplateLiteral',
+    'NonNullExpression',
+    'NullKeyword',
+    'NumericLiteral',
+    'ObjectBindingPattern',
+    'ObjectLiteralExpression',
     'OverrideKeyword',
     'Parameter',
     'ParenthesizedExpression',
+    'PrivateIdentifier',
     'PrivateKeyword',
     'PropertyAccessExpression',
+    'PropertyAssignment',
+    'PropertyDeclaration',
     'ProtectedKeyword',
     'PublicKeyword',
+    'QuestionQuestionEqualsToken',
+    'QuestionQuestionToken',
     'ReadonlyKeyword',
+    'ReturnStatement',
+    'SetAccessor',
+    'ShorthandPropertyAssignment',
+    'SpreadElement',
+    'StaticKeyword',
     'StringLiteral',
+    'TemplateExpression',
+    'ThisKeyword',
+    'ThrowStatement',
+    'TrueKeyword',
     'TypeAliasDeclaration',
     'TypeAssertionExpression',
+    'TypeOfExpression',
+    'VariableDeclaration',
+    'VariableStatement',
+    'VoidExpression',
+    'WhileStatement',
 ];
+/** The virtual tsconfig of the browser program; never written to disk. */
+export const BROWSER_TSCONFIG = 'tsconfig.dokebi-check.json';
+/**
+ * How the browser program resolves and what it knows, over the project's tsconfig: browser code is
+ * bundled by Vite, so imports resolve as a bundler does (the project's own tsconfig.vue.json says
+ * the same), and the DOM exists. Under the server's NodeNext a package whose type files import
+ * `./app` without an extension (@inertiajs/vue3 3.x) resolves to nothing, and every call of it was
+ * untyped, so a floating `createInertiaApp(…)` passed (D-0120 §1.4).
+ */
+const BROWSER_OPTIONS = {
+    module: 'esnext',
+    moduleResolution: 'bundler',
+    lib: ['esnext', 'dom', 'dom.iterable'],
+};
+/** Compiler options of a browser program without a project tsconfig (the framework's gate). */
+const STANDALONE_OPTIONS = {
+    target: 'esnext',
+    strict: true,
+    skipLibCheck: true,
+    types: [],
+};
+const slashes = (path) => path.split(sep).join('/');
 function unavailable(root, message, cause) {
     return new CliError('TYPESCRIPT_UNAVAILABLE', message, {
         ...(cause === undefined ? {} : { cause }),
@@ -75,7 +156,14 @@ function unavailable(root, message, cause) {
  * closes it. Throws TYPESCRIPT_UNAVAILABLE (TypeScript missing, older than 7, or its API changed)
  * and TSCONFIG_INVALID (the program cannot be loaded).
  */
-export async function openTypeScript(root) {
+export async function openTypeScript(root, 
+/**
+ * The tsconfig file in `root` (the framework's check:catch gate also reads its other
+ * programs); null: no project program, only the browser sources (with standalone options).
+ */
+tsconfig = 'tsconfig.json', 
+/** D-0120: files outside the program read in a second program that extends `tsconfig`. */
+browser = []) {
     const began = performance.now();
     const require = createRequire(join(root, 'package.json'));
     let sync;
@@ -99,48 +187,96 @@ export async function openTypeScript(root) {
     const anyFlags = (sync.TypeFlags?.Any ?? 0) | (sync.TypeFlags?.Unknown ?? 0);
     if (typeof sync.API !== 'function' || !anyFlags)
         throw unavailable(root, `TypeScript ${version} has no usable unstable/sync API`);
-    const config = join(root, 'tsconfig.json');
+    const config = tsconfig === null ? undefined : join(root, tsconfig);
+    // The browser program (D-0120): a virtual tsconfig that extends the project's and lists only
+    // the virtual sources, so the project program stays exactly what npm run typecheck sees.
+    const browserConfig = browser.length ? slashes(join(root, BROWSER_TSCONFIG)) : undefined;
+    const virtual = new Map();
+    if (browserConfig) {
+        for (const source of browser)
+            virtual.set(slashes(source.fileName), source.text);
+        virtual.set(browserConfig, JSON.stringify({
+            ...(config && existsSync(config) ? { extends: `./${tsconfig}` } : {}),
+            compilerOptions: {
+                ...(config && existsSync(config) ? {} : STANDALONE_OPTIONS),
+                ...BROWSER_OPTIONS,
+                allowJs: true,
+                checkJs: false,
+                noEmit: true,
+            },
+            files: [...virtual.keys()],
+            include: [],
+        }));
+    }
     let api;
     try {
-        api = new sync.API({ cwd: root });
+        api = new sync.API({
+            cwd: root,
+            // Only with browser sources: every file read then makes a round trip through this callback.
+            ...(virtual.size
+                ? {
+                    fs: {
+                        readFile: (name) => virtual.get(slashes(name)),
+                        fileExists: (name) => (virtual.has(slashes(name)) ? true : undefined),
+                    },
+                }
+                : {}),
+        });
     }
     catch (cause) {
         throw unavailable(root, 'Cannot start the TypeScript API (tsgo)', cause);
     }
+    const opened = [config, browserConfig].filter((item) => item !== undefined);
     let project;
+    let browserProject;
     try {
-        project = api.updateSnapshot({ openProject: config }).getProject(config);
+        const snapshot = api.updateSnapshot({ openProjects: opened });
+        project = config ? snapshot.getProject(config) : undefined;
+        browserProject = browserConfig ? snapshot.getProject(browserConfig) : undefined;
     }
     catch (cause) {
         api.close();
-        throw new CliError('TSCONFIG_INVALID', `TypeScript cannot load ${config}`, {
+        throw new CliError('TSCONFIG_INVALID', `TypeScript cannot load ${opened.join(', ')}`, {
             cause,
-            details: { tsconfig: config },
+            details: { tsconfig: config ?? browserConfig },
         });
     }
-    if (!project) {
+    if ((config && !project) || (browserConfig && !browserProject)) {
         api.close();
-        throw new CliError('TSCONFIG_INVALID', `TypeScript has no project for ${config}`, {
-            details: { tsconfig: config },
+        const missing = config && !project ? config : browserConfig;
+        throw new CliError('TSCONFIG_INVALID', `TypeScript has no project for ${missing}`, {
+            details: { tsconfig: missing },
         });
     }
     const prefix = root.endsWith(sep) ? root : root + sep;
     const modules = `${prefix}node_modules${sep}`;
     const files = [];
-    for (const name of project.program.getSourceFileNames()) {
+    for (const name of project?.program.getSourceFileNames() ?? []) {
         const native = name.split('/').join(sep);
         if (!native.startsWith(prefix) || native.startsWith(modules))
             continue;
         if (!/\.(c|m)?tsx?$/.test(native) || /\.d\.(c|m)?ts$/.test(native))
             continue;
-        const file = project.program.getSourceFile(name);
+        const file = project?.program.getSourceFile(name);
         if (file)
             files.push(file);
     }
+    const browserFiles = [];
+    for (const source of browser) {
+        const file = browserProject?.program.getSourceFile(slashes(source.fileName));
+        if (file)
+            browserFiles.push({ file, path: source.path });
+        else
+            debug('check: TypeScript did not load a browser source', { path: source.path });
+    }
     // The program loads lazily on the first file request, so the load ends here.
     const loadMs = Math.round(performance.now() - began);
-    debug('check: TypeScript program loaded', { version, files: files.length, loadMs });
-    const checker = project.checker;
+    debug('check: TypeScript program loaded', {
+        version,
+        files: files.length,
+        browser: browserFiles.length,
+        loadMs,
+    });
     // A Promise (or PromiseLike) — not any object with a `then`: Fastify's reply and query
     // builders are thenables whose methods return themselves, and leaving those alone is fine.
     const promiseType = (type, depth) => {
@@ -156,11 +292,21 @@ export async function openTypeScript(root) {
         kinds,
         files,
         loadMs,
-        promises(expressions) {
-            if (!expressions.length)
-                return [];
+        browser: browserFiles,
+        promises(expressions, inBrowser = false) {
+            const checker = (inBrowser ? browserProject : project)?.checker;
+            if (!expressions.length || !checker)
+                return expressions.map(() => false);
             return checker.getTypeAtLocation(expressions).map((type) => promiseType(type, 0));
         },
+        untyped(nodes, inBrowser = false) {
+            const checker = (inBrowser ? browserProject : project)?.checker;
+            if (!nodes.length || !checker)
+                return nodes.map(() => true);
+            return checker
+                .getTypeAtLocation(nodes)
+                .map((type) => type === undefined || (type.flags & anyFlags) !== 0);
+        },
         close() {
             api.close();
         },

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

@@ -0,0 +1,2 @@
+import type { Problem } from './problems.js';
+export declare function viteConfigProblems(root: string, installed: ReadonlySet<string>): Promise<Problem[]>;

package/dist/check/vite-rules.js

@@ -0,0 +1,136 @@
+import { readdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { debug, isMissing } from '../diagnostics.js';
+import { CliError } from '../errors.js';
+import { maskCode } from './form-rules.js';
+import { readMarkers } from './source-rules.js';
+const RULE = 'vite-dev-files';
+const CONFIGS = ['vite.config.ts', 'vite.config.mts', 'vite.config.js', 'vite.config.mjs'];
+/** Allow entries that widen the dev server to the root or to server code. */
+const WIDE_ALLOW = /^\s*(?:(['"`])(?:\.|\.\/|\/|src|\.\/src|src\/apps|tests?|\.\/tests?|scripts|tools|\.\.|\.\.\/)\/?\1|process\.cwd\(\)|__dirname|import\.meta\.dirname|searchForWorkspaceRoot\([^)]*\))\s*$/;
+/** Whether the project has an Inertia app (`src/apps/<app>/views/app.js`). */
+async function hasInertiaApp(root) {
+    let entries;
+    try {
+        entries = await readdir(join(root, 'src/apps'), { withFileTypes: true });
+    }
+    catch (error) {
+        if (isMissing(error))
+            return false;
+        throw new CliError('READ_FAILED', 'Cannot read src/apps', { cause: error });
+    }
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        try {
+            await readFile(join(root, 'src/apps', entry.name, 'views/app.js'));
+            return true;
+        }
+        catch (error) {
+            if (!isMissing(error))
+                throw new CliError('READ_FAILED', `Cannot read src/apps/${entry.name}/views/app.js`, {
+                    cause: error,
+                });
+        }
+    }
+    return false;
+}
+/** `[open, close]` of the `{ … }` that starts at `open` in masked code, or undefined. */
+function block(code, open) {
+    let depth = 0;
+    for (let index = open; index < code.length; index++) {
+        const char = code[index];
+        if (char === '{' || char === '[' || char === '(')
+            depth++;
+        else if (char === '}' || char === ']' || char === ')') {
+            depth--;
+            if (depth === 0)
+                return [open, index];
+        }
+    }
+    return undefined;
+}
+/** The comma-separated items of the `[ … ]` at `open` (original text), with their offsets. */
+function items(text, code, open) {
+    const range = block(code, open);
+    if (!range)
+        return [];
+    const found = [];
+    let depth = 0;
+    let start = open + 1;
+    for (let index = open; index <= range[1]; index++) {
+        const char = code[index];
+        if (char === '{' || char === '[' || char === '(')
+            depth++;
+        else if (char === '}' || char === ']' || char === ')')
+            depth--;
+        if ((char === ',' && depth === 1) || index === range[1]) {
+            const item = text.slice(start, index);
+            if (item.trim())
+                found.push([start, item]);
+            start = index + 1;
+        }
+    }
+    return found;
+}
+export async function viteConfigProblems(root, installed) {
+    if (!installed.has('dokebi-template-inertia') && !(await hasInertiaApp(root)))
+        return [];
+    let file;
+    let text = '';
+    for (const name of CONFIGS) {
+        try {
+            text = await readFile(join(root, name), 'utf8');
+            file = name;
+            break;
+        }
+        catch (error) {
+            if (!isMissing(error))
+                throw new CliError('READ_FAILED', `Cannot read ${name}`, { cause: error });
+        }
+    }
+    // No config: Vite runs with its defaults and the Vite host of dokebi dev adds the policy.
+    if (file === undefined)
+        return [];
+    const code = maskCode(text);
+    const lineAt = (offset) => text.slice(0, offset).split('\n').length;
+    const markers = readMarkers(text).filter((marker) => marker.rule === RULE);
+    const problems = [];
+    const report = (offset, message, fix) => {
+        const line = offset < 0 ? 0 : lineAt(offset);
+        const marker = markers.find((item) => item.line === line || item.line === line - 1);
+        if (line && marker?.reason)
+            return;
+        problems.push({
+            rule: RULE,
+            severity: 'warning',
+            file,
+            line,
+            message: `${message}${line && marker ? ' (the dokebi-check marker has no reason, so it does not count)' : ''}`,
+            fix,
+        });
+    };
+    if (!/\bdokebiInertia\s*\(/.test(code))
+        report(-1, `${file} does not use dokebiInertia() of @dokebi/template-inertia: a plain vite dev server then serves the whole project root (dokebi.yaml, .env, the server code), and pages bundle their own copy of the seal client. dokebi dev adds the file policy itself, other ways of running Vite do not`, "import { dokebiInertia } from '@dokebi/template-inertia/vite' and add it to plugins: [vue(), dokebiInertia()]");
+    for (const match of code.matchAll(/\bfs\s*:\s*\{/g)) {
+        const open = (match.index ?? 0) + match[0].length - 1;
+        const range = block(code, open);
+        if (!range)
+            continue;
+        const inner = code.slice(open, range[1]);
+        const strict = /\bstrict\s*:\s*false\b/.exec(inner);
+        if (strict)
+            report(open + strict.index, 'server.fs.strict: false asks the dev server to serve files outside its allow list (dokebiInertia() turns it on again and warns)', 'remove server.fs.strict; to serve another browser folder use dokebiInertia({ allow: [...] })');
+        const deny = /\bdeny\s*:/.exec(inner);
+        if (deny)
+            report(open + deny.index, "server.fs.deny of the config replaces Vite's default deny list (.env, keys, .git) wherever the framework's policy does not run; dokebiInertia() keeps dokebi.yaml, .env, .dokebi/, keys and compose files denied in any case", 'remove server.fs.deny and add your entries with dokebiInertia({ deny: [...] })');
+    }
+    for (const match of code.matchAll(/\ballow\s*:\s*\[/g)) {
+        const open = (match.index ?? 0) + match[0].length - 1;
+        for (const [offset, item] of items(text, code, open))
+            if (WIDE_ALLOW.test(item))
+                report(offset, `allow: [${item.trim()}] lets the dev server serve the project root or server code (src/ outside views/, tests/, scripts/); through a devHosts tunnel that is public`, 'allow only the folders the browser loads (the views folders are allowed already), for example dokebiInertia({ allow: ["src/shared/browser"] })');
+    }
+    debug('check: vite config read for the dev file rule', { file, problems: problems.length });
+    return problems;
+}

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

@@ -0,0 +1,16 @@
+import { type Kinds, type TsNode, type TsSourceFile } from './typescript.js';
+export type Report = (node: TsNode, message: string, fix: string) => void;
+export declare 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 declare 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>";
+export type QueueReport = (node: TsNode, message: string, fix: string) => void;
+/** Callers parked in a collection: the resolve of a `new Promise` executor stored to call later. */
+export declare function queueRules(file: TsSourceFile, kinds: Kinds, report: QueueReport): void;
+export declare function waitRules(file: TsSourceFile, kinds: Kinds, report: Report): void;
+export declare 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 declare function ownerCapRules(file: TsSourceFile, kinds: Kinds, report: Report): void;