@dokebi/cli 0.4.1 → 0.4.26

package/dist/check/i18n-rules.js

@@ -0,0 +1,353 @@
+// The translation rules of `dokebi check` (warnings; only with @dokebi/i18n and its catalogs).
+// The catalogs have three layers (D-0181): an app's (src/apps/<app>/locales/), the modules'
+// (src/shared/modules/<module>/locales/) and the shared ones (src/shared/locales/); within one
+// language an app's key wins over a module's, a module's over a shared one.
+//   i18n-missing-key       a fixed key a page or server code asks for (`t('ns.a.b')`, `$t(…)`,
+//                          `request.i18n.t(…)`) that the default locale of its scope lacks (code
+//                          under src/apps/<app>/ reads that app's layer, the modules and the shared
+//                          catalogs; other code the modules and the shared ones, community A2).
+//                          @dokebi/i18n throws MISSING_MESSAGE for it everywhere but under
+//                          `npx dokebi dev` (missing: auto).
+//   i18n-layer-override    one key in one language in two layers: an app over a module or the
+//                          shared catalogs, a module over the shared ones, or two modules. An
+//                          intended override is listed in the overriding file's top-level
+//                          `"$overrides": ["key", …]`; a listed key that overrides nothing is
+//                          reported too. Two modules are always reported (their name order decides).
+//   i18n-layer-missing     a layer has a key in one language and not in another language of the
+//                          project: users of that language see a lower layer's or another
+//                          language's text. One problem per layer, language and namespace.
+// Only literal keys whose first part is a namespace of the catalogs are read (`t('auth.login')`
+// with an auth.json); a key built at run time, one with an explicit default (`t('k', 'Text')`)
+// and lines in a comment are not.
+import { readdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { CONFIG_FILE, parseProjectConfig } from '../configuration.js';
+import { debug } from '../diagnostics.js';
+import { sources } from './form-rules.js';
+import { readMarkers } from './source-rules.js';
+const RULE = 'i18n-missing-key';
+const OVERRIDE = 'i18n-layer-override';
+const MISSING = 'i18n-layer-missing';
+const LOCALES = 'src/shared/locales';
+const FILES = /\.(?:vue|ts|mts|js|mjs|ejs)$/;
+/** Files larger than this are not read (generated bundles, data). */
+const MAX_BYTES = 1024 * 1024;
+const CATEGORIES = new Set(['zero', 'one', 'two', 'few', 'many', 'other']);
+/** `t(` or `$t(` (also `.t(`, `i18n.t(`) with a quoted key, then `,` or `)`. */
+const CALL = /(^|[^\w$])\$?t\(\s*(['"`])([A-Za-z][\w-]*(?:\.[\w-]+)+)\2\s*([,)])/g;
+/** Keys a missing-layer problem names before "and N more". */
+const NAMED = 5;
+/** @dokebi/i18n's rule (catalogs.ts): `other` and only plural categories with strings. */
+function pluralMessage(value) {
+    if (value === null || typeof value !== 'object' || !Object.hasOwn(value, 'other'))
+        return false;
+    return Object.entries(value).every(([key, branch]) => CATEGORIES.has(key) && typeof branch === 'string');
+}
+function flatten(value, prefix, keys, top = true) {
+    if (typeof value === 'string' || pluralMessage(value)) {
+        keys.add(prefix);
+        return;
+    }
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return;
+    for (const [key, child] of Object.entries(value)) {
+        if (top && key === '$overrides')
+            continue;
+        flatten(child, `${prefix}.${key}`, keys, false);
+    }
+}
+/** The files of one locales folder (`<locale>/<namespace>.json`); unreadable JSON is reported. */
+async function readLayer(root, kind, name, folder, broken) {
+    let locales;
+    try {
+        locales = await readdir(join(root, folder), { withFileTypes: true });
+    }
+    catch (error) {
+        // No catalogs folder: this layer has nothing.
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+    const files = new Map();
+    for (const locale of locales) {
+        if (!locale.isDirectory())
+            continue;
+        const byNamespace = new Map();
+        for (const file of await readdir(join(root, folder, locale.name), { withFileTypes: true })) {
+            if (!file.isFile() || !file.name.endsWith('.json'))
+                continue;
+            const path = `${folder}/${locale.name}/${file.name}`;
+            const text = await readFile(join(root, path), 'utf8');
+            let parsed;
+            try {
+                parsed = JSON.parse(text);
+            }
+            catch (error) {
+                // Reported, not compared: the app's start fails with INVALID_CATALOG and this cause.
+                broken.push({
+                    rule: RULE,
+                    severity: 'warning',
+                    file: path,
+                    line: 1,
+                    message: `${path} is not JSON (${error.message}): its keys are not compared, and @dokebi/i18n refuses it at start (INVALID_CATALOG)`,
+                    fix: 'correct the JSON of the file',
+                });
+                continue;
+            }
+            const namespace = file.name.slice(0, -5);
+            const keys = new Set();
+            flatten(parsed, namespace, keys);
+            const listed = parsed?.$overrides;
+            const overrides = new Set(Array.isArray(listed)
+                ? listed
+                    .filter((key) => typeof key === 'string')
+                    .map((key) => `${namespace}.${key}`)
+                : []);
+            byNamespace.set(namespace, { path, text, keys, overrides });
+        }
+        files.set(locale.name, byNamespace);
+    }
+    return files.size ? { kind, name, folder, files } : undefined;
+}
+/** The named folders of `parent` that have a locales folder, as layers in name order. */
+async function namedLayers(root, parent, kind, broken) {
+    let entries;
+    try {
+        entries = await readdir(join(root, parent), { withFileTypes: true });
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return [];
+        throw error;
+    }
+    const out = [];
+    for (const entry of entries
+        .filter((item) => item.isDirectory())
+        .sort((a, b) => (a.name < b.name ? -1 : 1))) {
+        const layer = await readLayer(root, kind, entry.name, `${parent}/${entry.name}/locales`, broken);
+        if (layer)
+            out.push(layer);
+    }
+    return out;
+}
+/** The keys of a locale of a layer. */
+function keysOf(layer, locale) {
+    const out = new Set();
+    for (const file of layer.files.get(locale)?.values() ?? [])
+        for (const key of file.keys)
+            out.add(key);
+    return out;
+}
+/** The keys of each locale of a scope (its layers together), for i18n-missing-key. */
+function scopeKeys(layers, locales) {
+    const out = new Map();
+    for (const locale of locales) {
+        const keys = new Set();
+        for (const layer of layers)
+            for (const key of keysOf(layer, locale))
+                keys.add(key);
+        out.set(locale, keys);
+    }
+    return out;
+}
+/** The line of `"<last part of key>":` in a catalog file, else 1. */
+function lineOf(text, key) {
+    const name = key.slice(key.lastIndexOf('.') + 1);
+    const at = text.indexOf(`"${name}"`);
+    return at < 0 ? 1 : text.slice(0, at).split('\n').length;
+}
+const label = (layer) => layer.kind === 'shared' ? 'the shared catalogs' : `the ${layer.kind} ${layer.name}`;
+/** i18n-layer-override: a key of one language in two layers, unless the overriding file lists it. */
+export function overrideProblems(shared, modules, apps) {
+    const problems = [];
+    const below = (layers, locale, key) => layers.filter((layer) => keysOf(layer, locale).has(key));
+    const judge = (layer, lower) => {
+        for (const [locale, files] of layer.files)
+            for (const file of files.values()) {
+                for (const key of file.keys) {
+                    const under = below(lower, locale, key);
+                    if (!under.length || file.overrides.has(key))
+                        continue;
+                    problems.push({
+                        rule: OVERRIDE,
+                        severity: 'warning',
+                        file: file.path,
+                        line: lineOf(file.text, key),
+                        message: `${file.path} gives ${key}, which ${under.map(label).join(' and ')} also give${under.length > 1 ? '' : 's'} in ${locale}: ${label(layer)} wins, so their text is not shown where ${label(layer)} applies`,
+                        fix: `if the override is intended, add "${key.slice(key.indexOf('.') + 1)}" to the "$overrides" list at the top of ${file.path}; otherwise rename the key or remove it from one layer`,
+                    });
+                }
+                for (const key of file.overrides) {
+                    if (file.keys.has(key) && below(lower, locale, key).length)
+                        continue;
+                    problems.push({
+                        rule: OVERRIDE,
+                        severity: 'warning',
+                        file: file.path,
+                        line: lineOf(file.text, '$overrides'),
+                        message: `${file.path} lists ${key} in $overrides, but ${file.keys.has(key) ? `no lower layer gives it in ${locale}` : 'the file does not give it'}: the entry overrides nothing`,
+                        fix: `remove "${key.slice(key.indexOf('.') + 1)}" from the "$overrides" list of ${file.path}`,
+                    });
+                }
+            }
+    };
+    const base = shared ? [shared] : [];
+    for (const app of apps)
+        judge(app, [...modules, ...base]);
+    for (const module of modules)
+        judge(module, base);
+    // Two modules with one key: the first by name gives it, by chance; never silenced.
+    for (const [index, module] of modules.entries())
+        for (const [locale, files] of module.files)
+            for (const file of files.values())
+                for (const key of file.keys) {
+                    const earlier = modules.slice(0, index).filter((other) => keysOf(other, locale).has(key));
+                    if (!earlier.length)
+                        continue;
+                    problems.push({
+                        rule: OVERRIDE,
+                        severity: 'warning',
+                        file: file.path,
+                        line: lineOf(file.text, key),
+                        message: `${file.path} gives ${key}, which ${earlier.map(label).join(' and ')} also give${earlier.length > 1 ? '' : 's'} in ${locale}: between modules the first by name wins, so this text is never shown`,
+                        fix: `give each module its own keys (its own namespace), or move the shared wording to ${LOCALES}`,
+                    });
+                }
+    return problems;
+}
+/** i18n-layer-missing: keys a layer gives in one language and lacks in another of the project. */
+export function layerMissingProblems(layers, locales) {
+    const problems = [];
+    for (const layer of layers) {
+        // Every key of the layer, by namespace, in any of its languages.
+        const all = new Map();
+        for (const files of layer.files.values())
+            for (const [namespace, file] of files) {
+                const keys = all.get(namespace) ?? new Set();
+                for (const key of file.keys)
+                    keys.add(key);
+                all.set(namespace, keys);
+            }
+        for (const locale of locales)
+            for (const [namespace, keys] of all) {
+                const has = layer.files.get(locale)?.get(namespace)?.keys ?? new Set();
+                const missing = [...keys].filter((key) => !has.has(key)).sort();
+                if (!missing.length)
+                    continue;
+                const path = `${layer.folder}/${locale}/${namespace}.json`;
+                const named = missing.slice(0, NAMED).join(', ');
+                problems.push({
+                    rule: MISSING,
+                    severity: 'warning',
+                    file: path,
+                    line: 1,
+                    message: `${label(layer)} lacks ${missing.length} key${missing.length > 1 ? 's' : ''} of ${namespace} in ${locale} that it gives in another language (${named}${missing.length > NAMED ? ` and ${missing.length - NAMED} more` : ''}): ${locale} users see a lower layer's or another language's text there`,
+                    fix: `add the keys to ${path}, or remove them from the other languages of ${label(layer)}`,
+                });
+            }
+    }
+    return problems;
+}
+/** The problems of one file's text against the catalogs (the path is project-relative). */
+export function missingKeyProblems(path, text, catalogs, 
+/** dokebi-i18n defaultLocale: the end of every fallback chain. */
+defaultLocale = 'en') {
+    // A key the default locale has never throws (every lookup chain ends there); one it lacks
+    // throws in every locale that lacks it too.
+    const fallback = catalogs.get(defaultLocale);
+    const namespaces = new Set();
+    for (const keys of catalogs.values())
+        for (const key of keys)
+            namespaces.add(key.slice(0, key.indexOf('.')));
+    const markers = readMarkers(text).filter((marker) => marker.rule === RULE);
+    const problems = [];
+    for (const [index, content] of text.split('\n').entries()) {
+        if (/^\s*(?:\/\/|\*|\/\*|<%#|<!--)/.test(content))
+            continue;
+        for (const match of content.matchAll(CALL)) {
+            const key = match[3];
+            if (!namespaces.has(key.slice(0, key.indexOf('.'))))
+                continue;
+            // An explicit default (`t('k', 'Text')`) is shown when the key is missing.
+            const after = content.slice((match.index ?? 0) + match[0].length);
+            if (match[4] === ',' && /^\s*['"`]/.test(after))
+                continue;
+            if (fallback?.has(key))
+                continue;
+            const having = [...catalogs].filter(([, keys]) => keys.has(key)).map(([locale]) => locale);
+            const line = index + 1;
+            const marker = markers.find((item) => item.line === line || item.line === line - 1);
+            if (marker?.reason.replace(/\s*[-_%]*>\s*$/, '').trim())
+                continue;
+            const namespace = key.slice(0, key.indexOf('.'));
+            problems.push({
+                rule: RULE,
+                severity: 'warning',
+                file: path,
+                line,
+                message: `${path} asks for the translation ${key}, which ${having.length ? `only the ${having.join(', ')} catalog${having.length > 1 ? 's have' : ' has'}, not the default locale ${defaultLocale}` : 'no catalog has'}: @dokebi/i18n throws MISSING_MESSAGE for it${having.length ? ' in the other locales' : ''} (under npx dokebi dev the page shows the key)${marker ? ' (the dokebi-check marker has no reason, so it does not count)' : ''}`,
+                fix: `add ${key.slice(namespace.length + 1)} to ${LOCALES}/${defaultLocale}/${namespace}.json (the fallback of every locale; or to the locales folder of its app or module), or correct the key`,
+            });
+        }
+    }
+    return problems;
+}
+/** dokebi-i18n defaultLocale of dokebi.yaml (`en` when absent or unreadable: doctor reports that). */
+async function defaultLocaleOf(root) {
+    let source;
+    try {
+        source = await readFile(join(root, CONFIG_FILE), 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return 'en';
+        throw error;
+    }
+    try {
+        const options = parseProjectConfig(source).options;
+        const section = options['dokebi-i18n'];
+        return typeof section?.defaultLocale === 'string' ? section.defaultLocale : 'en';
+    }
+    catch (error) {
+        debug('check: i18n default locale not read, en assumed', { error: error.message });
+        return 'en';
+    }
+}
+/** The translation rules over the catalogs and the files under `src/` (only with @dokebi/i18n). */
+export async function missingKeysProblems(root, skip) {
+    const problems = [];
+    const shared = await readLayer(root, 'shared', 'shared', LOCALES, problems);
+    const modules = await namedLayers(root, 'src/shared/modules', 'module', problems);
+    const apps = await namedLayers(root, 'src/apps', 'app', problems);
+    const all = [...apps, ...modules, ...(shared ? [shared] : [])];
+    if (!all.length)
+        return problems;
+    const locales = [...new Set(all.flatMap((layer) => [...layer.files.keys()]))].sort();
+    problems.push(...overrideProblems(shared, modules, apps));
+    problems.push(...layerMissingProblems(all, locales));
+    const fallback = await defaultLocaleOf(root);
+    const base = [...modules, ...(shared ? [shared] : [])];
+    const scoped = new Map([['', scopeKeys(base, locales)]]);
+    for (const app of apps)
+        scoped.set(app.name, scopeKeys([app, ...base], locales));
+    let files = 0;
+    for (const path of await sources(root, 'src', FILES)) {
+        if (skip(path) || /(?:^|\/)locales\//.test(path))
+            continue;
+        const text = await readFile(join(root, path), 'utf8');
+        if (text.length > MAX_BYTES)
+            continue;
+        files++;
+        const app = /^src\/apps\/([^/]+)\//.exec(path)?.[1];
+        const catalogs = (app !== undefined && scoped.get(app)) || scoped.get('');
+        problems.push(...missingKeyProblems(path, text, catalogs, fallback));
+    }
+    debug('check: translation keys', {
+        files,
+        locales: locales.length,
+        modules: modules.length,
+        apps: apps.length,
+        problems: problems.length,
+    });
+    return problems;
+}

package/dist/check/index.d.ts

@@ -1,10 +1,22 @@
 import { type Inspection } from '../project-inspector.js';
 import { type Problem } from './problems.js';
 export { type Problem, RULES, type RuleName } from './problems.js';
+/** A `// dokebi-check: allow <rule> <reason>` marker with a reason: a problem silenced on purpose. */
+export interface AllowedMarker {
+    readonly rule: string;
+    readonly file: string;
+    readonly line: number;
+    readonly reason: string;
+}
 export interface CheckResult {
     readonly ok: boolean;
     readonly problems: Problem[];
-    /** Source files the rules read (the tsconfig program under the root). */
+    /**
+     * Every marker with a reason under src/ (M34: a database polling loop passed under one): what
+     * the project chose to silence, listed so a reader judges each reason, not only the problems.
+     */
+    readonly allowed: readonly AllowedMarker[];
+    /** Source files the rules read (the tsconfig program under the root, and browser code). */
     readonly files: number;
     readonly rules: readonly string[];
     readonly typescript: string;
@@ -19,5 +31,7 @@ export interface CheckOptions {
     readonly inspection?: Inspection;
 }
 export declare function check(directory: string, options?: CheckOptions): Promise<CheckResult>;
+/** The markers with a reason in the source files under src/ (generated files left out). */
+export declare function allowedMarkers(root: string, skip: (path: string) => boolean): Promise<AllowedMarker[]>;
 /** The human output: one block per problem, then a summary line. */
 export declare function checkText(result: CheckResult): string;

package/dist/check/index.js

@@ -1,19 +1,32 @@
 // `dokebi check` (D-0072): the user-code convention gate of a project made by `dokebi init`.
-// Seven error rules (problems.ts), each matching only code that is wrong, with a fix per problem,
-// and one warning (inertia-form-only, D-0074) that reports without failing.
+// Error rules (problems.ts), each matching only code that is wrong, with a fix per problem, and
+// warnings (inertia-form-only D-0074; form-without-csrf, csrf-exempt-unverified D-0076 §6;
+// responsibility-size, memory-filtered-page D-0105; vite-dev-files D-0129; formatter-migrations D-0145; console-output
+// D-0151; background-timer is
+// an error) that report without failing. The security rules run only when the plugin they protect is installed.
 // Project rules reuse doctor's inspection (one source for CLI-owned files and plugin checks);
 // source rules walk the AST of the project's own TypeScript 7 program (typescript.ts); the form
-// rule reads the text of src/ (Vue files are not in the program, form-rules.ts).
-import { realpath } from 'node:fs/promises';
+// rule reads the text of src/ (Vue files are not in the program, form-rules.ts). The .vue scripts
+// and the .js under views/ go to a second program of the same tsgo (browser-sources.ts, D-0120)
+// for empty-catch, missing-cause and floating-promise.
+import { readdir, readFile, realpath } from 'node:fs/promises';
+import { extname, join } from 'node:path';
 import { loadCatalog } from '../catalog.js';
 import { debug } from '../diagnostics.js';
 import { ProjectInspector } from '../project-inspector.js';
-import { formProblems } from './form-rules.js';
+import { assetProblems } from './asset-rules.js';
+import { browserSources } from './browser-sources.js';
+import { csrfFormsProblems, formProblems } from './form-rules.js';
+import { formatterProblems } from './formatter-rules.js';
+import { missingKeysProblems } from './i18n-rules.js';
 import { DokebiImports } from './packages.js';
-import { byPlace, RULES } from './problems.js';
+import { byPlace, MARKABLE, RULES } from './problems.js';
 import { projectProblems } from './project-rules.js';
-import { sourceProblems } from './source-rules.js';
+import { sealHeadsProblems } from './seal-rules.js';
+import { sharedStateProblems } from './shared-state-rules.js';
+import { readMarkers, sourceProblems } from './source-rules.js';
 import { openTypeScript } from './typescript.js';
+import { viteConfigProblems } from './vite-rules.js';
 export { RULES } from './problems.js';
 /** CLI-generated TypeScript: judged by doctor (generated-file), not by the source rules. */
 const GENERATED_SOURCES = new Set(['src/dokebi.generated.ts']);
@@ -22,18 +35,31 @@ export async function check(directory, options = {}) {
     const root = await realpath(directory);
     const inspection = options.inspection ?? (await new ProjectInspector().inspect(root, { runChecks: true }));
     const problems = await projectProblems(root, inspection);
-    const typescript = await openTypeScript(root);
+    const installed = new Set(inspection.plugins.flatMap((item) => item.installed?.id ?? []));
+    const skip = (path) => GENERATED_SOURCES.has(path);
+    const typescript = await openTypeScript(root, 'tsconfig.json', await browserSources(root, skip));
     let files = 0;
     try {
-        const found = await sourceProblems(typescript, root, new DokebiImports(await loadCatalog()), (path) => GENERATED_SOURCES.has(path));
+        const found = await sourceProblems(typescript, root, new DokebiImports(await loadCatalog()), skip, installed);
         problems.push(...found.problems);
         files = found.files;
     }
     finally {
         typescript.close();
     }
-    problems.push(...(await formProblems(root, (path) => GENERATED_SOURCES.has(path))).problems);
+    problems.push(...(await formProblems(root, skip)).problems);
+    if (installed.has('dokebi-csrf'))
+        problems.push(...(await csrfFormsProblems(root)).problems);
+    problems.push(...(await viteConfigProblems(root, installed)));
+    problems.push(...(await formatterProblems(root)));
+    problems.push(...(await sharedStateProblems(root, installed)));
+    problems.push(...(await assetProblems(root)));
+    if (installed.has('dokebi-app'))
+        problems.push(...(await sealHeadsProblems(root, skip)));
+    if (installed.has('dokebi-i18n'))
+        problems.push(...(await missingKeysProblems(root, skip)));
     problems.sort(byPlace);
+    const allowed = await allowedMarkers(root, skip);
     const ms = {
         total: Math.round(performance.now() - began),
         typescript: typescript.loadMs,
@@ -42,23 +68,75 @@ export async function check(directory, options = {}) {
     debug('check: finished', {
         root,
         problems: problems.length,
+        allowed: allowed.length,
         warnings: problems.length - errors,
         files,
         ...ms,
     });
     return {
-        // Warnings (inertia-form-only) are reported but never fail check or verify.
+        // Warnings (inertia-form-only, the CSRF ones) are reported but never fail check or verify.
         ok: errors === 0,
         problems,
+        allowed,
         files,
         rules: RULES,
         typescript: typescript.version,
         ms,
     };
 }
+const MARKED_SOURCES = new Set([
+    '.ts',
+    '.mts',
+    '.cts',
+    '.js',
+    '.mjs',
+    '.cjs',
+    '.vue',
+    '.ejs',
+    '.html',
+]);
+/** The markers with a reason in the source files under src/ (generated files left out). */
+export async function allowedMarkers(root, skip) {
+    let entries;
+    try {
+        entries = await readdir(join(root, 'src'), { recursive: true });
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return [];
+        throw error;
+    }
+    const found = [];
+    for (const entry of entries.sort()) {
+        const file = `src/${entry.split('\\').join('/')}`;
+        if (!MARKED_SOURCES.has(extname(file)) || skip(file) || /(^|\/)node_modules\//.test(file))
+            continue;
+        let text;
+        try {
+            text = await readFile(join(root, file), 'utf8');
+        }
+        catch (error) {
+            // A folder named like a source file, or a file removed meanwhile: nothing to list.
+            const code = error.code;
+            if (code === 'EISDIR' || code === 'ENOENT')
+                continue;
+            throw error;
+        }
+        if (!text.includes('dokebi-check:'))
+            continue;
+        for (const marker of readMarkers(text)) {
+            const reason = marker.reason.replace(/\s*(\*\/|-->|%>)\s*$/, '').trim();
+            if (reason && MARKABLE.has(marker.rule))
+                found.push({ rule: marker.rule, file, line: marker.line, reason });
+        }
+    }
+    return found;
+}
 /** The human output: one block per problem, then a summary line. */
 export function checkText(result) {
     const lines = result.problems.map((problem) => `${problem.file}${problem.line ? `:${problem.line}` : ''}  ${problem.rule}${problem.severity === 'warning' ? ' (warning)' : ''}  ${problem.message}\n    fix: ${problem.fix}`);
+    for (const marker of result.allowed)
+        lines.push(`${marker.file}:${marker.line}  allowed ${marker.rule}  ${marker.reason}`);
     const timing = `${result.files} files, ${result.ms.total} ms (TypeScript ${result.typescript} load ${result.ms.typescript} ms)`;
     const warnings = result.problems.filter((problem) => problem.severity === 'warning').length;
     const errors = result.problems.length - warnings;

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

@@ -0,0 +1,4 @@
+import { type Kinds, type TsNode, type TsSourceFile } from './typescript.js';
+type Rule = 'mail-send-in-request' | 'mail-secret-in-data';
+export declare function mailRules(file: TsSourceFile, kinds: Kinds, report: (node: TsNode, rule: Rule, message: string, fix: string) => void): void;
+export {};

package/dist/check/mail-rules.js

@@ -0,0 +1,72 @@
+// D-0078 MP4: conservative source heuristics, only with @dokebi/mail installed.
+import { nameWords } from './security-rules.js';
+import { field, nodes, property, } from './typescript.js';
+const SECRETS = new Set(['token', 'password', 'passwd', 'secret', 'url', 'link']);
+const METHODS = new Set(['get', 'post', 'put', 'patch', 'delete', 'head', 'options', 'route']);
+export function mailRules(file, kinds, report) {
+    const name = (node) => {
+        if (!node)
+            return '';
+        const key = field(node, 'name');
+        return String(property(key ?? node, 'text') ?? '');
+    };
+    const routeHandlers = new Set();
+    const collect = (node) => {
+        if (node.kind === kinds.CallExpression && METHODS.has(name(field(node, 'expression'))))
+            for (const arg of nodes(node, 'arguments'))
+                if (arg.kind === kinds.Identifier)
+                    routeHandlers.add(name(arg));
+        node.forEachChild(collect);
+        return undefined;
+    };
+    collect(file);
+    const walk = (node, inRequest = false) => {
+        const functional = node.kind === kinds.ArrowFunction ||
+            node.kind === kinds.FunctionExpression ||
+            node.kind === kinds.FunctionDeclaration;
+        const request = inRequest ||
+            (functional &&
+                (routeHandlers.has(name(node)) ||
+                    nodes(node, 'parameters').some((p) => /^(request|req)$/.test(name(p)))));
+        if (node.kind === kinds.CallExpression) {
+            const callee = field(node, 'expression');
+            const method = name(callee);
+            const receiver = callee && field(callee, 'expression');
+            // mail, app.mail, this.mail and notificationMailer; no unrelated socket.send calls.
+            const isMail = nameWords(name(receiver).replace(/^#/, '')).some((word) => word === 'mail' || word === 'mailer');
+            if (isMail && (method === 'send' || method === 'queue')) {
+                if (request && method === 'send')
+                    report(node, 'mail-send-in-request', 'Mail delivery blocks this request on the transport.', 'Use await mail.queue(message) with a provisioned @dokebi/job queue.');
+                const message = nodes(node, 'arguments')[0];
+                if (message?.kind === kinds.ObjectLiteralExpression) {
+                    const data = nodes(message, 'properties').find((item) => name(item) === 'data');
+                    const value = data && field(data, 'initializer');
+                    const secrets = (value) => {
+                        if (value.kind === kinds.ObjectLiteralExpression)
+                            for (const item of nodes(value, 'properties')) {
+                                if (nameWords(name(item)).some((word) => SECRETS.has(word)))
+                                    report(item, 'mail-secret-in-data', 'A token, password or link-like field is in unsealed mail data.', 'Move sensitive values to sealed; templates read them from data after decryption.');
+                                const nested = field(item, 'initializer');
+                                if (nested)
+                                    secrets(nested);
+                            }
+                        return undefined;
+                    };
+                    if (value)
+                        secrets(value);
+                }
+            }
+            // Inline handlers without named request parameters are still request handlers.
+            const route = METHODS.has(method) && receiver !== undefined;
+            // The callee too: in `mail.send(m).then(…)` the send is the receiver of `then`.
+            if (callee)
+                walk(callee, request);
+            for (const child of nodes(node, 'arguments'))
+                walk(child, request || route);
+            return undefined;
+        }
+        node.forEachChild((child) => walk(child, request));
+        return undefined;
+    };
+    walk(file);
+}

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

@@ -0,0 +1,13 @@
+import { type Kinds, type TsNode, type TsSourceFile } from './typescript.js';
+/** One point listed in a `contributes` array, with the module specifier it was imported from. */
+export interface ModulePoint {
+    readonly node: TsNode;
+    readonly module: string;
+    readonly point: string;
+    readonly specifier: string;
+}
+/**
+ * The points of every `defineModule({ contributes: [...] })` of the file whose `defineModule`
+ * comes from @dokebi/module, when the point is a name (or `ns.name`) imported from a package.
+ */
+export declare function modulePoints(file: TsSourceFile, kinds: Kinds): ModulePoint[];