@facilis.dev/analyze 0.0.0-stage → 0.1.1

package/dist/passes/clients.js

@@ -0,0 +1,167 @@
+/**
+ * Client consumers -> PageFacts and page→route edges (§3.4 of the AST DSL contract).
+ *
+ * Exactly one transport is sanctioned (`api()` from `src/lib/api.ts` by default): the
+ * transport export is resolved through imports (aliases and namespace imports included) and
+ * every other network call in `src/**` is a `client-transport` error. The transport module
+ * itself is the only place allowed to call `fetch`, so it is not scanned as a consumer.
+ */
+import { callArguments, identifierName, memberName, unwrapExpression, } from "../ast/node.js";
+import { walk } from "../ast/walk.js";
+import { error, warning } from "../diagnostics.js";
+import { extractPathExpression, matchRouteIds } from "./path-expression.js";
+import { projectPath, readStaticObject, relativePath, refOf, sortDiagnostics, } from "./static-read.js";
+const SRC_DIR = "src/";
+const HTTP_METHODS = new Set([
+    "GET",
+    "POST",
+    "PUT",
+    "PATCH",
+    "DELETE",
+    "HEAD",
+    "OPTIONS",
+    "TRACE",
+    "CONNECT",
+]);
+const NETWORK_CALLEES = new Set(["fetch", "axios", "ky", "got"]);
+function transportBindings(graph, file, transportPath, exportName) {
+    const names = new Set();
+    const namespaces = new Set();
+    for (const imported of file.module.imports) {
+        if (graph.resolve(file.path, imported.specifier) !== transportPath)
+            continue;
+        if (imported.kind === "namespace")
+            namespaces.add(imported.local);
+        else if ((imported.imported ?? "default") === exportName)
+            names.add(imported.local);
+    }
+    return { names, namespaces };
+}
+function isTransportCall(call, bindings, exportName) {
+    const callee = unwrapExpression(call.callee);
+    const direct = identifierName(callee);
+    if (direct !== undefined)
+        return bindings.names.has(direct);
+    if (callee?.type !== "MemberExpression")
+        return false;
+    const objectName = identifierName(unwrapExpression(callee.object));
+    return (objectName !== undefined &&
+        bindings.namespaces.has(objectName) &&
+        memberName(callee) === exportName);
+}
+/** Name of a network call that is not the transport, or null when the node is not one. */
+function networkCallName(node) {
+    if (node.type === "NewExpression") {
+        return identifierName(unwrapExpression(node.callee)) === "XMLHttpRequest"
+            ? "XMLHttpRequest"
+            : null;
+    }
+    if (node.type !== "CallExpression")
+        return null;
+    const callee = unwrapExpression(node.callee);
+    const direct = identifierName(callee);
+    if (direct !== undefined && NETWORK_CALLEES.has(direct))
+        return direct;
+    if (callee?.type !== "MemberExpression")
+        return null;
+    const objectName = identifierName(unwrapExpression(callee.object));
+    return objectName !== undefined && NETWORK_CALLEES.has(objectName) ? objectName : null;
+}
+/** The request method comes from the second argument's static `method`, else GET. */
+function requestMethod(init, context, callRef) {
+    if (init === undefined)
+        return { method: "GET", unknown: null };
+    const object = readStaticObject(init, context, { code: "page-path-static", report: false });
+    const field = object.fields.get("method");
+    if (field !== undefined && field.ok && typeof field.value === "string") {
+        const method = field.value.toUpperCase();
+        if (HTTP_METHODS.has(method))
+            return { method: method, unknown: null };
+    }
+    // An unreadable options object hides the method; defaulting silently could produce a wrong
+    // page→route edge, so the assumption is recorded as unknown.
+    const unknown = field === undefined && object.unknown.length === 0
+        ? null
+        : {
+            code: "page-path-static",
+            reason: "the request method cannot be read statically; assuming GET",
+            source: callRef,
+        };
+    return { method: "GET", unknown };
+}
+function pageKind(relative) {
+    if (relative.startsWith("src/pages/"))
+        return "page";
+    if (relative.startsWith("src/components/"))
+        return "component";
+    if (relative.startsWith("src/lib/"))
+        return "lib";
+    return "other";
+}
+function scanPage(graph, file, routes, transportPath, exportName) {
+    const context = { graph, file: file.path };
+    const bindings = transportBindings(graph, file, transportPath, exportName);
+    const calls = [];
+    const diagnostics = [];
+    walk(file.program, (node) => {
+        if (node.type !== "CallExpression" && node.type !== "NewExpression")
+            return;
+        const transport = node.type === "CallExpression" && isTransportCall(node, bindings, exportName);
+        const network = transport ? null : networkCallName(node);
+        if (!transport && network === null)
+            return;
+        const callRef = refOf(context, node);
+        const args = node.type === "CallExpression" ? callArguments(node) : [];
+        const extracted = extractPathExpression(args[0], context, node, "page-path-static");
+        const method = requestMethod(args[1], context, callRef);
+        const unknown = [...extracted.unknown];
+        if (method.unknown !== null)
+            unknown.push(method.unknown);
+        if (transport && extracted.path === null && extracted.staticPrefix === null) {
+            diagnostics.push(warning("page-path-static", "the API path cannot be resolved statically", callRef));
+        }
+        if (!transport && network !== null) {
+            const reason = network + " outside the sanctioned transport module is not allowed";
+            unknown.push({ code: "client-transport", reason, source: callRef });
+            diagnostics.push(error("client-transport", reason, callRef));
+        }
+        calls.push({
+            expression: extracted.expression,
+            kind: extracted.kind,
+            staticPrefix: extracted.staticPrefix,
+            matchedRouteIds: matchRouteIds(routes, extracted.path, extracted.staticPrefix, method.method),
+            source: callRef,
+            unknown,
+        });
+    });
+    const page = {
+        path: file.path,
+        kind: pageKind(relativePath(graph.root, file.path)),
+        calls,
+        source: { file: file.path, line: 1 },
+        unknown: [],
+    };
+    return { page, diagnostics };
+}
+/** Map client files to the routes they call. */
+export function buildPageFacts(graph, routes, transport) {
+    const transportPath = projectPath(graph.root, transport.module);
+    const files = [...graph.files.values()]
+        .filter((file) => {
+        const relative = relativePath(graph.root, file.path);
+        if (!relative.startsWith(SRC_DIR))
+            return false;
+        if (relative.includes(".test."))
+            return false;
+        return file.path !== transportPath;
+    })
+        .toSorted((left, right) => left.path.localeCompare(right.path));
+    const pages = [];
+    const diagnostics = [];
+    for (const file of files) {
+        const scanned = scanPage(graph, file, routes, transportPath, transport.exportName);
+        pages.push(scanned.page);
+        diagnostics.push(...scanned.diagnostics);
+    }
+    return { pages, diagnostics: sortDiagnostics(diagnostics) };
+}

package/dist/passes/config.d.ts

@@ -0,0 +1,16 @@
+/**
+ * `facilis.config.ts` -> ConfigFacts (docs/findings/ast-dsl-contract.md §3.2).
+ *
+ * The config is the project's security contract, so a value outside the static subset is an
+ * explicit unknown plus a diagnostic, never a silent default. Defaults mirror
+ * packages/core/src/config.ts exactly: the runtime and the analyzer must agree on what
+ * "absent" means, and only the analyzer may report a wrong value instead of throwing.
+ */
+import type { ModuleGraph } from "../module-graph.js";
+import type { ConfigFacts, Diagnostic } from "../types.js";
+export interface ConfigResult {
+    readonly facts: ConfigFacts;
+    readonly diagnostics: readonly Diagnostic[];
+}
+export declare function emptyConfigFacts(): ConfigFacts;
+export declare function buildConfigFacts(graph: ModuleGraph): ConfigResult;

package/dist/passes/config.js

@@ -0,0 +1,229 @@
+/**
+ * `facilis.config.ts` -> ConfigFacts (docs/findings/ast-dsl-contract.md §3.2).
+ *
+ * The config is the project's security contract, so a value outside the static subset is an
+ * explicit unknown plus a diagnostic, never a silent default. Defaults mirror
+ * packages/core/src/config.ts exactly: the runtime and the analyzer must agree on what
+ * "absent" means, and only the analyzer may report a wrong value instead of throwing.
+ */
+import { callArguments, identifierName, unwrapExpression } from "../ast/node.js";
+import { error } from "../diagnostics.js";
+import { defaultExportDeclaration } from "../module-info.js";
+import { sourceRef } from "../source.js";
+import { defaultExportExpression, isLocallyDeclared, isRecord, projectPath, readStaticObject, refOf, sortDiagnostics, } from "./static-read.js";
+const CONFIG_FILE = "facilis.config.ts";
+const CORE_SPECIFIER = "@facilis.dev/core";
+// Mirrors packages/core/src/config.ts. The analyzer is browser-safe and must not import the
+// server package, so the defaults are restated here and covered by a test.
+const DEFAULT_MIGRATIONS_DIR = "./drizzle";
+const DEFAULT_TENANT_COLUMNS = ["tenantId"];
+const DEFAULT_OWNER_COLUMNS = ["ownerId"];
+const DEFAULT_LOCALE = "en";
+const DEFAULT_LOCALES = ["en"];
+function configDefaults() {
+    return {
+        parsed: false,
+        source: null,
+        permissions: [],
+        roles: {},
+        defaultRole: null,
+        defaultLocale: DEFAULT_LOCALE,
+        locales: [...DEFAULT_LOCALES],
+        migrationsDir: DEFAULT_MIGRATIONS_DIR,
+        tenantColumns: [...DEFAULT_TENANT_COLUMNS],
+        ownerColumns: [...DEFAULT_OWNER_COLUMNS],
+        unknown: [],
+    };
+}
+export function emptyConfigFacts() {
+    return configDefaults();
+}
+function stringField(section, key, fallback, unknown, at) {
+    if (!Object.hasOwn(section, key))
+        return fallback;
+    if (typeof section[key] === "string")
+        return section[key];
+    unknown.push({ code: "config-static", reason: key + " must be a string", source: at });
+    return fallback;
+}
+function stringArrayField(section, key, fallback, unknown, at) {
+    if (!Object.hasOwn(section, key))
+        return fallback;
+    const value = section[key];
+    if (Array.isArray(value) && value.every((item) => typeof item === "string")) {
+        return [...value];
+    }
+    unknown.push({ code: "config-static", reason: key + " must be a string[]", source: at });
+    return fallback;
+}
+function rolesField(section, unknown, at) {
+    if (!Object.hasOwn(section, "roles"))
+        return {};
+    const value = section.roles;
+    if (!isRecord(value)) {
+        unknown.push({ code: "config-static", reason: "roles must be an object", source: at });
+        return {};
+    }
+    const roles = {};
+    for (const [role, permissions] of Object.entries(value)) {
+        if (Array.isArray(permissions) && permissions.every((item) => typeof item === "string")) {
+            roles[role] = [...permissions];
+        }
+        else {
+            unknown.push({
+                code: "config-static",
+                reason: 'roles["' + role + '"] must be a string[]',
+                source: at,
+            });
+        }
+    }
+    return roles;
+}
+function readSection(root, name, context, unknown) {
+    const field = root.fields.get(name);
+    if (field === undefined)
+        return null;
+    if (field.ok && isRecord(field.value))
+        return field.value;
+    const nested = readStaticObject(field.node, context, { code: "config-static", report: true });
+    unknown.push(...nested.unknown);
+    if (field.ok && nested.fields.size === 0) {
+        unknown.push({
+            code: "config-static",
+            reason: name + " must be an object",
+            source: refOf(context, field.node),
+        });
+    }
+    const out = {};
+    for (const [key, value] of nested.fields)
+        if (value.ok)
+            out[key] = value.value;
+    return out;
+}
+/** The default export must be a `defineConfig(...)` call of the @facilis.dev/core named import. */
+function resolveDefineConfig(file) {
+    const expression = defaultExportExpression(file);
+    if (expression === undefined) {
+        return { call: null, reason: "facilis.config.ts has no default export" };
+    }
+    if (expression.type !== "CallExpression") {
+        return { call: null, reason: "the default export is not a defineConfig() call" };
+    }
+    const callee = unwrapExpression(expression.callee);
+    const name = callee?.type === "Identifier" ? identifierName(callee) : undefined;
+    if (name === undefined)
+        return { call: null, reason: "defineConfig must be called by name" };
+    if (isLocallyDeclared(file, name)) {
+        return { call: null, reason: 'defineConfig "' + name + '" is shadowed by a local declaration' };
+    }
+    const imported = file.module.imports.find((entry) => entry.local === name);
+    if (imported === undefined) {
+        return { call: null, reason: "defineConfig is not imported from @facilis.dev/core" };
+    }
+    if (imported.specifier !== CORE_SPECIFIER || imported.imported !== "defineConfig") {
+        return { call: null, reason: "defineConfig must be the named import from @facilis.dev/core" };
+    }
+    return { call: expression, reason: null };
+}
+function validationIssues(facts, authMissing) {
+    const auth = [];
+    if (authMissing)
+        auth.push("auth is required in facilis.config.ts");
+    if (facts.permissions.includes("*"))
+        auth.push('"*" is only valid inside auth.roles');
+    const seenPermissions = new Set();
+    for (const permission of facts.permissions) {
+        if (seenPermissions.has(permission))
+            auth.push('duplicate permission "' + permission + '"');
+        seenPermissions.add(permission);
+    }
+    for (const [role, permissions] of Object.entries(facts.roles)) {
+        const seen = new Set();
+        for (const permission of permissions) {
+            if (permission !== "*" && !seenPermissions.has(permission)) {
+                auth.push('role "' + role + '" references undeclared permission "' + permission + '"');
+            }
+            if (seen.has(permission))
+                auth.push('role "' + role + '" repeats "' + permission + '"');
+            seen.add(permission);
+        }
+    }
+    if (facts.defaultRole === null) {
+        if (!authMissing)
+            auth.push("auth.defaultRole is required");
+    }
+    else if (!Object.hasOwn(facts.roles, facts.defaultRole)) {
+        auth.push('defaultRole "' + facts.defaultRole + '" is not a key of auth.roles');
+    }
+    const i18n = [];
+    if (!facts.locales.includes(facts.defaultLocale ?? "")) {
+        i18n.push('defaultLocale "' + (facts.defaultLocale ?? "") + '" must be listed in i18n.locales');
+    }
+    return { auth, i18n };
+}
+export function buildConfigFacts(graph) {
+    const file = graph.file(projectPath(graph.root, CONFIG_FILE));
+    if (file === undefined) {
+        return {
+            facts: emptyConfigFacts(),
+            diagnostics: [
+                error("config-missing", CONFIG_FILE + " was not found; the project config is required", null),
+            ],
+        };
+    }
+    const context = { graph, file: file.path };
+    const at = sourceRef(file.path, file.source, defaultExportDeclaration(file.program)?.start ?? 0);
+    const resolved = resolveDefineConfig(file);
+    if (resolved.call === null) {
+        const reason = resolved.reason ?? "defineConfig() could not be resolved";
+        return {
+            facts: {
+                ...configDefaults(),
+                source: at,
+                unknown: [{ code: "config-static", reason, source: at }],
+            },
+            diagnostics: [error("config-static", reason, at)],
+        };
+    }
+    const root = readStaticObject(callArguments(resolved.call)[0], context, {
+        code: "config-static",
+        report: false,
+    });
+    const unknown = [...root.unknown];
+    const auth = readSection(root, "auth", context, unknown);
+    const i18n = readSection(root, "i18n", context, unknown);
+    const db = readSection(root, "db", context, unknown);
+    const authRef = refOf(context, root.fields.get("auth")?.node);
+    const i18nRef = refOf(context, root.fields.get("i18n")?.node);
+    const base = configDefaults();
+    const facts = {
+        parsed: true,
+        source: at,
+        permissions: auth === null ? [] : stringArrayField(auth, "permissions", [], unknown, authRef),
+        roles: auth === null ? {} : rolesField(auth, unknown, authRef),
+        defaultRole: auth === null ? null : stringField(auth, "defaultRole", null, unknown, authRef),
+        defaultLocale: i18n === null
+            ? base.defaultLocale
+            : stringField(i18n, "defaultLocale", base.defaultLocale, unknown, i18nRef),
+        locales: i18n === null
+            ? base.locales
+            : stringArrayField(i18n, "locales", base.locales, unknown, i18nRef),
+        migrationsDir: db === null
+            ? base.migrationsDir
+            : (stringField(db, "migrationsDir", base.migrationsDir, unknown, at) ?? base.migrationsDir),
+        tenantColumns: db === null
+            ? base.tenantColumns
+            : stringArrayField(db, "tenantColumns", base.tenantColumns, unknown, at),
+        ownerColumns: db === null
+            ? base.ownerColumns
+            : stringArrayField(db, "ownerColumns", base.ownerColumns, unknown, at),
+        unknown,
+    };
+    const issues = validationIssues(facts, auth === null);
+    const diagnostics = [
+        ...unknown.map((fact) => error(fact.code, fact.reason, fact.source)),
+        ...issues.auth.map((message) => error("config-invalid", message, authRef)),
+        ...issues.i18n.map((message) => error("config-invalid", message, i18nRef)),
+    ];
+    return { facts, diagnostics: sortDiagnostics(diagnostics) };
+}

package/dist/passes/file-facts.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Per-file module facts: imports, re-exports, dynamic imports/requires and literal `t()`
+ * keys (docs/findings/ast-dsl-contract.md §3.6).
+ *
+ * These are the AST replacement for the patch validator's tolerant text scans: the rules
+ * need the module graph edges and the translation keys of a source file, and they must be
+ * readable without executing the project. The parser produced the structure; this pass only
+ * reads it, so a construct outside the static subset is simply absent rather than guessed.
+ */
+import type { ModuleGraph } from "../module-graph.js";
+import type { FileFacts } from "../types.js";
+/** Read the module facts of every parsed source file, in path order. */
+export declare function buildFileFacts(graph: ModuleGraph): readonly FileFacts[];

package/dist/passes/file-facts.js

@@ -0,0 +1,130 @@
+/**
+ * Per-file module facts: imports, re-exports, dynamic imports/requires and literal `t()`
+ * keys (docs/findings/ast-dsl-contract.md §3.6).
+ *
+ * These are the AST replacement for the patch validator's tolerant text scans: the rules
+ * need the module graph edges and the translation keys of a source file, and they must be
+ * readable without executing the project. The parser produced the structure; this pass only
+ * reads it, so a construct outside the static subset is simply absent rather than guessed.
+ */
+import { identifierName, literalString, nodeArray } from "../ast/node.js";
+import { walk } from "../ast/walk.js";
+import { sourceRef } from "../source.js";
+function refOf(file, node) {
+    const offset = typeof node.start === "number" ? node.start : 0;
+    return sourceRef(file.path, file.source, offset);
+}
+function push(imports, specifier, kind, local, imported, source) {
+    imports.push({ specifier, kind, local, imported, source });
+}
+function declarationImports(file) {
+    const imports = [];
+    for (const statement of nodeArray(file.program, "body")) {
+        if (statement.type === "ImportDeclaration") {
+            const specifier = literalString(statement.source);
+            if (specifier === undefined)
+                continue;
+            const source = refOf(file, statement);
+            const specifiers = nodeArray(statement, "specifiers");
+            if (specifiers.length === 0) {
+                push(imports, specifier, "side-effect", null, null, source);
+                continue;
+            }
+            for (const item of specifiers) {
+                const local = identifierName(item.local);
+                if (local === undefined)
+                    continue;
+                if (item.type === "ImportDefaultSpecifier") {
+                    push(imports, specifier, "default", local, "default", source);
+                }
+                else if (item.type === "ImportNamespaceSpecifier") {
+                    push(imports, specifier, "namespace", local, null, source);
+                }
+                else if (item.type === "ImportSpecifier") {
+                    const imported = identifierName(item.imported) ?? literalString(item.imported);
+                    if (imported !== undefined)
+                        push(imports, specifier, "named", local, imported, source);
+                }
+            }
+            continue;
+        }
+        if (statement.type === "ExportAllDeclaration" ||
+            (statement.type === "ExportNamedDeclaration" && statement.source !== null)) {
+            const specifier = literalString(statement.source);
+            if (specifier !== undefined) {
+                push(imports, specifier, "export-from", null, null, refOf(file, statement));
+            }
+        }
+    }
+    return imports;
+}
+function expressionImports(file) {
+    const imports = [];
+    walk(file.program, (node) => {
+        if (node.type === "ImportExpression") {
+            const specifier = literalString(node.source);
+            if (specifier !== undefined)
+                push(imports, specifier, "dynamic", null, null, refOf(file, node));
+            return;
+        }
+        if (node.type === "CallExpression" && identifierName(node.callee) === "require") {
+            const specifier = literalString(nodeArray(node, "arguments")[0]);
+            if (specifier !== undefined)
+                push(imports, specifier, "require", null, null, refOf(file, node));
+        }
+    });
+    return imports;
+}
+function templateString(node) {
+    if (node === undefined || node.type !== "TemplateLiteral")
+        return undefined;
+    const quasis = nodeArray(node, "quasis");
+    if (quasis.length !== 1)
+        return undefined;
+    const value = quasis[0]?.value;
+    if (typeof value !== "object" || value === null)
+        return undefined;
+    const cooked = value.cooked;
+    if (typeof cooked === "string")
+        return cooked;
+    const raw = value.raw;
+    return typeof raw === "string" ? raw : undefined;
+}
+function translationCalls(file) {
+    const calls = [];
+    walk(file.program, (node) => {
+        if (node.type !== "CallExpression" || identifierName(node.callee) !== "t")
+            return;
+        const argument = nodeArray(node, "arguments")[0];
+        const key = literalString(argument) ?? templateString(argument);
+        if (key !== undefined)
+            calls.push({ key, source: refOf(file, node) });
+    });
+    return calls;
+}
+function bareCalls(file) {
+    const calls = [];
+    walk(file.program, (node) => {
+        if (node.type !== "CallExpression")
+            return;
+        const name = identifierName(node.callee);
+        if (name !== undefined)
+            calls.push({ name, source: refOf(file, node) });
+    });
+    return calls;
+}
+function byPosition(left, right) {
+    return (left.source.line - right.source.line ||
+        left.specifier.localeCompare(right.specifier) ||
+        left.kind.localeCompare(right.kind));
+}
+/** Read the module facts of every parsed source file, in path order. */
+export function buildFileFacts(graph) {
+    const files = [...graph.files.values()].toSorted((left, right) => left.path.localeCompare(right.path));
+    return files.map((file) => ({
+        path: file.path,
+        imports: [...declarationImports(file), ...expressionImports(file)].toSorted(byPosition),
+        translationCalls: translationCalls(file),
+        calls: bareCalls(file),
+    }));
+}

package/dist/passes/i18n.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Locale catalogs: every `locales/*.json` in the file map (docs/findings/ast-dsl-contract.md
+ * §3.5). A missing `locales/` directory is fine (catalogs are optional); malformed JSON is a
+ * warning and the catalog is skipped, because i18n completeness is a gate concern but a broken
+ * file must never stop the rest of the analysis.
+ */
+import type { ModuleGraph } from "../module-graph.js";
+import type { Diagnostic, LocaleCatalogs } from "../types.js";
+export interface LocaleResult {
+    readonly locales: LocaleCatalogs;
+    readonly diagnostics: readonly Diagnostic[];
+}
+/** Read the locale JSON files from the project file map. */
+export declare function readLocaleCatalogs(graph: ModuleGraph): LocaleResult;

package/dist/passes/i18n.js

@@ -0,0 +1,55 @@
+/**
+ * Locale catalogs: every `locales/*.json` in the file map (docs/findings/ast-dsl-contract.md
+ * §3.5). A missing `locales/` directory is fine (catalogs are optional); malformed JSON is a
+ * warning and the catalog is skipped, because i18n completeness is a gate concern but a broken
+ * file must never stop the rest of the analysis.
+ */
+import { warning } from "../diagnostics.js";
+import { isRecord, relativePath, sortDiagnostics } from "./static-read.js";
+const LOCALES_DIR = "locales/";
+const JSON_EXTENSION = ".json";
+function parseCatalog(source) {
+    let parsed;
+    try {
+        parsed = JSON.parse(source);
+    }
+    catch {
+        return null;
+    }
+    if (!isRecord(parsed))
+        return null;
+    const catalog = {};
+    for (const [key, value] of Object.entries(parsed)) {
+        if (typeof value === "string")
+            catalog[key] = value;
+    }
+    return catalog;
+}
+/** Read the locale JSON files from the project file map. */
+export function readLocaleCatalogs(graph) {
+    const files = [...graph.allFiles.entries()]
+        .filter(([path]) => {
+        const relative = relativePath(graph.root, path);
+        if (!relative.startsWith(LOCALES_DIR))
+            return false;
+        const name = relative.slice(LOCALES_DIR.length);
+        return (!name.includes("/") && name.endsWith(JSON_EXTENSION) && name.length > JSON_EXTENSION.length);
+    })
+        .toSorted(([left], [right]) => left.localeCompare(right));
+    const locales = {};
+    const diagnostics = [];
+    for (const [path, source] of files) {
+        const relative = relativePath(graph.root, path);
+        const name = relative.slice(LOCALES_DIR.length, -JSON_EXTENSION.length);
+        const catalog = parseCatalog(source);
+        if (catalog === null) {
+            diagnostics.push(warning("i18n-catalog", "locale catalog " + relative + " is not a JSON object", {
+                file: path,
+                line: 1,
+            }));
+            continue;
+        }
+        locales[name] = catalog;
+    }
+    return { locales, diagnostics: sortDiagnostics(diagnostics) };
+}

package/dist/passes/job-relations-diagnostics.d.ts

@@ -0,0 +1,9 @@
+/**
+ * D-157 diagnostics for a job's static db usage. The rules mirror the route ones
+ * (`route-relations-diagnostics.ts`) with job codes; jobs have no elevation dimension, so the
+ * only suppression of the unused warning is an opaque helper or an allowed `db.execute`.
+ */
+import type { Diagnostic } from "../types.js";
+import type { JobFact, JobRelationsFact } from "../types-jobs.js";
+/** Every diagnostic the relation pass derives from one job's usage fact. */
+export declare function jobRelationDiagnostics(job: JobFact, usage: JobRelationsFact): Diagnostic[];

package/dist/passes/job-relations-diagnostics.js

@@ -0,0 +1,38 @@
+/**
+ * D-157 diagnostics for a job's static db usage. The rules mirror the route ones
+ * (`route-relations-diagnostics.ts`) with job codes; jobs have no elevation dimension, so the
+ * only suppression of the unused warning is an opaque helper or an allowed `db.execute`.
+ */
+import { error, warning } from "../diagnostics.js";
+function unusedSuppressed(usage) {
+    return usage.opaque || usage.rawSql.length > 0;
+}
+/** Every diagnostic the relation pass derives from one job's usage fact. */
+export function jobRelationDiagnostics(job, usage) {
+    const diagnostics = [];
+    const declared = job.dbTables === null ? null : new Set(job.dbTables);
+    if (declared !== null) {
+        for (const use of usage.used) {
+            if (declared.has(use.name))
+                continue;
+            diagnostics.push(error("job-table-undeclared", 'relation "' + use.name + '" is used through the job db but not declared in dbTables', use.source));
+        }
+    }
+    for (const source of usage.unresolved) {
+        diagnostics.push(error("job-table-unresolved", "a relation used through the job db cannot be resolved statically", source));
+    }
+    for (const source of usage.rawSql) {
+        if (job.rawSql === true)
+            continue;
+        diagnostics.push(error("job-raw-sql", "db.execute() requires rawSql: true on the job definition", source));
+    }
+    if (declared !== null && !unusedSuppressed(usage)) {
+        const used = new Set(usage.used.map((use) => use.name));
+        for (const name of job.dbTables ?? []) {
+            if (used.has(name))
+                continue;
+            diagnostics.push(warning("job-table-unused", 'dbTables declares "' + name + '" but the job never uses it', job.source));
+        }
+    }
+    return diagnostics;
+}