@jskit-ai/jskit-catalog 0.2.36 → 0.2.38

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/jskit-catalog",
-  "version": "0.2.36",
+  "version": "0.2.38",
   "description": "Published metadata catalog for JSKIT package metadata.",
   "type": "module",
   "files": [

package/scripts/data-access.mjs

@@ -1,5 +1,7 @@
 import { readdir, readFile, realpath } from "node:fs/promises";
+import { createRequire } from "node:module";
 import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
 import { toPosixPath } from "./files.mjs";
 import { blankJsComments, lineIndex } from "./material3-source.mjs";
 
@@ -10,9 +12,11 @@ import { blankJsComments, lineIndex } from "./material3-source.mjs";
 // without a literal reason fails; and every file the infrastructure exception lifts past the data-access lint rules is
 // listed for review. In the app's own code, which no lint directive can hide from it, a feature's system scope and an
 // infrastructure exception fail until the checked-in BASELINE_FILE lists them, so each new one is reviewed; a module
-// that requires runtime.database or runtime.resources fails unless it is declared infrastructure; and an eslint-disable
-// that names a data-access rule, or no rule at all, fails in any file but the client's. As information, it lists the
-// fields of each app table resource that its CRUD contracts never name, which no API shows or accepts.
+// that requires a capability handing out power past the owners (CROSS_OWNER_CAPABILITIES) fails until it is reviewed
+// too; an eslint-disable or inline eslint config that turns off a data-access rule, or every rule, fails in any file
+// but the client's; and so does an app file the app's own ESLint config lints without every data-access rule as an
+// error, or ignores though it is server code. As information, it lists the fields of each app table resource that its CRUD contracts never name,
+// which no API shows or accepts.
 
 const GUIDE = "https://mobily-enterprises.github.io/jskit-ai/guide/framework/data-access";
 const SECTIONS = Object.freeze({
@@ -22,6 +26,7 @@ const SECTIONS = Object.freeze({
   "data/baseline": "hard-rules",
   "data/runtime-capability": "the-resource-is-the-only-door",
   "data/lint-disabled": "hard-rules",
+  "data/lint-config": "hard-rules",
   "data/unnamed-fields": "layer-2-the-crud-surface"
 });
 // What each rule asks, said once above its findings in the report.
@@ -30,33 +35,69 @@ const RULE_EXPLANATIONS = Object.freeze({
   "data/system-scope": "every system scope and systemContext() call gives its reason as a string literal.",
   "data/baseline": "each infrastructure exception and feature system scope of the app is reviewed, then listed in the checked-in " +
     "jskit-data-access.json; review each one below, then add the entry it shows.",
-  "data/runtime-capability": "a module that requires runtime.database or runtime.resources reaches tables past the features that " +
-    "own them. A feature owns its tables with owns and gets their handles; only a module whose job is data access itself, " +
-    "declared with the infrastructure exception, takes them.",
-  "data/lint-disabled": "eslint-disable cannot turn off a data-access rule, and one that names no rule turns them all off. Change the " +
-    "code, or name the rules the directive turns off."
+  "data/runtime-capability": "a module that requires a capability handing out power past the owners reaches rows past the " +
+    "features that own them. A feature owns its tables with owns and gets their handles; only a module whose job is data " +
+    "access itself, declared with the infrastructure exception, takes runtime.database or runtime.resources, and a module " +
+    "takes any other one once the baseline's systemScopes lists it with its reason.",
+  "data/lint-disabled": "neither eslint-disable nor an inline eslint config comment can turn off a data-access rule, and a " +
+    "disable that names no rule turns them all off. Change the code, or name the rules the directive turns off.",
+  "data/lint-config": "the app's ESLint config makes every data-access rule an error in each server file, and ignores no " +
+    "server code; a config that turns one off, lowers it or ignores the file hides that code from it. Put the rule back, or, " +
+    "once the module's whole job is data access, list { \"file\", \"rule\" } in the baseline's \"infrastructure\"."
 });
 // The reviewed list of the app's infrastructure exceptions and feature system scopes, at the app's root.
 const BASELINE_FILE = "jskit-data-access.json";
 const DATA_ACCESS_RULES = Object.freeze(["no-direct-knex", "no-transaction-reader", "sql-literal", "no-hand-scope", "no-hand-context", "knex-reason"]);
 // An eslint-disable directive and the rules it names, before any "--" description.
 const LINT_DISABLE = /\/[/*]\s*eslint-disable(?:-next-line|-line)?(?![\w-])([^\n]*)/gu;
-// A module that takes the database, or every table, past the features that own them.
-const RUNTIME_CAPABILITY = /(["'`])(runtime\.(?:database|resources))\1/gu;
-// An app's client code, which the data-access rules leave alone: its own src/ but src/server and src/shared, and every
-// package's src/client.
-const CLIENT_FILE = /^src\/(?!server\/|shared\/)|(?:^|\/)src\/client\//u;
+// An inline config comment's text, `eslint jskit/no-direct-knex: "off"`, and the rules it sets.
+const LINT_CONFIG = /^\s*eslint\s([\s\S]*)$/u;
+// The capabilities that hand a module power past the features owning the rows, with what each gives: one list. Requiring
+// runtime.database or runtime.resources is for a module declared infrastructure only; requiring any other one passes
+// once the baseline's systemScopes lists it, with its reason: { "file", "capability", "systemScope": "<reason>" }.
+const CROSS_OWNER_CAPABILITIES = Object.freeze({
+  "runtime.database": { gives: "the database, past every owner", infrastructureOnly: true },
+  "runtime.resources": { gives: "every table resource's handle", infrastructureOnly: true },
+  "realtime.audience-scope": { gives: "contexts for any workspace and user (forWorkspace, forUser, forWorkspaceUser)" },
+  "auth.local.accounts": { gives: "every local sign-in account, read and written in local auth's system context" },
+  "auth.local.sessions": { gives: "every sign-in session, read and written in local auth's system context" },
+  "auth.local.recovery": { gives: "every recovery token, read and written in local auth's system context" },
+  "connectors.store": { gives: "every owner's connections, with their credentials decrypted" },
+  "assistant.repositories": { gives: "every actor's and workspace's assistant conversations, messages and settings" },
+  "payments.store": { gives: "every merchant's payment accounts, customers and catalogues" }
+});
+const escapeRegExp = (text) => text.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+// A capability id written as a string, compared as the kernel resolves it: trimmed and in any case.
+const CAPABILITY_NAMES = Object.keys(CROSS_OWNER_CAPABILITIES).map(escapeRegExp).join("|");
+const CROSS_OWNER_CAPABILITY = new RegExp(`(["'\`])\\s*(${CAPABILITY_NAMES})\\s*\\1`, "giu");
+// The root of the app or of one of its packages, where a folder's name says what the whole tree is: a migrations/ or
+// test/ folder deeper in server code is server code (as in @jskit-ai/config-eslint's dataAccess.js).
+const ROOT = String.raw`(?:(?:packages|tooling)/[^/]+/)?`;
+// Client code, which the data-access rules leave alone: a package's src/client. An app's own src/ is linted whole, since
+// server code sits there too.
+const CLIENT_FILE = new RegExp(`^${ROOT}src/client/`, "u");
+// What the data-access lint leaves alone (NOT_DATA_ACCESS_SOURCE in @jskit-ai/config-eslint's dataAccess.js), for a path
+// from the directory of the ESLint config that governs the file, a nested application's own included: client code,
+// tests, migrations, seeds and build output at a root, seed scripts, and test files.
+const LINT_EXEMPT = new RegExp(`^${ROOT}(?:(?:src/client|src/test|test|tests|__tests__|e2e|test-support|migrations|seeds?|` +
+  "dist|build|coverage)/|(?:(?:scripts|bin)/)?seed[^/]*\\.[cm]?js$)|\\.(?:test|spec|vitest)\\.[^/]*$", "u");
+// Server code, which the app's ESLint config may not ignore: a package's src/server or src/shared, or the app's server/.
+const SERVER_FILE = new RegExp(`^(?:${ROOT}src/(?:server|shared)/|server/)`, "u");
 const FRAMEWORK_DIRECTORY = path.join("node_modules", "@jskit-ai");
 const SOURCE_FILE = /\.[cm]?js$/u;
 const SKIPPED_FILE = /\.(?:test|spec|vitest)\.[cm]?js$/u;
-// Code that defines no table resource or system scope an app runs: dependencies, build output, tests and fixtures,
-// migrations and seeds, and the examples, templates and documentation JSKIT packages carry.
-const SKIPPED_DIRECTORIES = new Set([
-  "node_modules", "dist", "build", "coverage", "test", "tests", "__tests__", "e2e", "fixtures", "test-results",
-  "migrations", "seeds", "templates", "patterns", "examples", "docs", "site", "skills", "test-support"
+// Code that defines no table resource or system scope an app runs: dependencies, anywhere; and, at a root (ROOT), build
+// output, tests and fixtures, migrations and seeds, and the examples, templates and documentation JSKIT packages carry.
+const SKIPPED_ROOT_DIRECTORIES = new Set([
+  "dist", "build", "coverage", "test", "tests", "__tests__", "e2e", "fixtures", "test-results", "migrations", "seed",
+  "seeds", "templates", "patterns", "examples", "docs", "site", "skills", "test-support", "src/test"
 ]);
-const MARKERS = /defineTableResource|defineCrudContract|systemScope|systemContext|readable-check: allow|eslint-disable|runtime\.(?:database|resources)/u;
+const PACKAGE_DIRECTORY = /^(?:packages|tooling)\/[^/]+\/(.+)$/u;
+const skipsDirectory = (name) => path.posix.basename(name) === "node_modules" ||
+  SKIPPED_ROOT_DIRECTORIES.has(PACKAGE_DIRECTORY.exec(name)?.[1] ?? name);
+const MARKERS = new RegExp(`defineTableResource|defineCrudContract|systemScope|systemContext|readable-check: allow|eslint|${CAPABILITY_NAMES}`, "iu");
 const TABLE_RESOURCE_CALL = /\bdefineTableResource\s*\(/gu;
+const TABLE_RESOURCE_MARKER = /\bdefineTableResource\s*\(/u;
 // A CRUD contract on a table resource named by its variable: `defineCrudContract(receivalResource, { ... })`.
 const CRUD_CONTRACT_CALL = /\bdefineCrudContract\s*\(\s*([A-Za-z_$][\w$]*)\s*,\s*/gu;
 // The fields an ownership kind keeps for itself: json-rest-api fills them from the context.
@@ -225,7 +266,7 @@ function readTableResources(file, { code, masked, position }) {
   for (const match of masked.matchAll(TABLE_RESOURCE_CALL)) {
     const object = objectArgument(masked, match.index, match[0].length);
     if (!object) continue;
-    const keys = topLevelKeys(masked, object.start, object.end, ["name", "tableName", "ownership", "schema"]);
+    const keys = topLevelKeys(masked, object.start, object.end, ["name", "tableName", "ownership", "schema", "foreignKeys"]);
     const ownership = keyValue(code, masked, keys, "ownership")?.text ?? null;
     resources.push({
       file,
@@ -233,7 +274,8 @@ function readTableResources(file, { code, masked, position }) {
       name: keyValue(code, masked, keys, "name")?.text ?? null,
       tableName: keyValue(code, masked, keys, "tableName")?.text ?? null,
       variable: /(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*$/u.exec(masked.slice(Math.max(0, match.index - 120), match.index))?.[1] ?? null,
-      fields: readSchemaFields(code, masked, keys, ownership)
+      fields: readSchemaFields(code, masked, keys, ownership),
+      foreignKeys: keys.has("foreignKeys")
     });
   }
   return resources;
@@ -328,30 +370,138 @@ function readInfrastructureExcuses(file, source) {
   });
 }
 
+const isDataAccessRule = (rule) => DATA_ACCESS_RULES.includes(rule.replace(/^jskit\//u, ""));
+
+// The block comments of a file, each { index, value }, read as blankJsComments reads comments: text in a string or a line
+// comment is no comment. ESLint reads inline config only from block comments.
+function blockComments(source) {
+  const comments = [];
+  let index = 0;
+  while (index < source.length) {
+    const opening = source.slice(index, index + 2);
+    if (opening === "//" || opening === "/*") {
+      const end = source.indexOf(opening === "//" ? "\n" : "*/", index + 2);
+      const stop = end < 0 ? source.length : end;
+      if (opening === "/*") comments.push({ index, value: source.slice(index + 2, stop) });
+      index = opening === "/*" ? stop + 2 : stop;
+    } else if ("\"'`".includes(source[index])) {
+      const quote = source[index];
+      index += 1;
+      while (index < source.length && source[index] !== quote && (quote === "`" || source[index] !== "\n")) {
+        index += source[index] === "\\" ? 2 : 1;
+      }
+      index += 1;
+    } else {
+      index += 1;
+    }
+  }
+  return comments;
+}
+
 // Every eslint-disable in a file that turns off a data-access rule: one that names one, or one that names no rule and so
-// turns off every rule.
+// turns off every rule; and every inline config comment that sets a data-access rule, which can only weaken it.
 function readLintDisables(file, source, position) {
   const disables = [];
   for (const match of source.matchAll(LINT_DISABLE)) {
     const named = match[1].replace(/\*\/.*$/u, "").split(/\s--\s|\s--$/u)[0].split(",").map((rule) => rule.trim()).filter(Boolean);
-    const rules = named.filter((rule) => DATA_ACCESS_RULES.includes(rule.replace(/^jskit\//u, "")));
+    const rules = named.filter(isDataAccessRule);
     if (named.length < 1 || rules.length > 0) {
-      disables.push({ file, line: position(match.index).line, rules });
+      disables.push({ file, line: position(match.index).line, kind: "disable", rules });
+    }
+  }
+  for (const comment of blockComments(source)) {
+    const settings = LINT_CONFIG.exec(comment.value)?.[1].split(/\s--\s/u)[0] || "";
+    const rules = [...settings.matchAll(/(?:^|[\s,{])["']?((?:jskit\/)?[a-z][\w-]*)["']?\s*:/gu)].map((rule) => rule[1]).filter(isDataAccessRule);
+    if (rules.length > 0) {
+      disables.push({ file, line: position(comment.index).line, kind: "config", rules });
     }
   }
   return disables;
 }
 
-// Every place a file's code takes runtime.database or runtime.resources: each time it names one outside a provides
-// object, the module that provides it.
+// Every place a file's code takes a cross-owner capability: each time it names one outside a provides object (the module
+// that provides it), and other than as the id of a feature that provides it in the same file.
 function readRuntimeCapabilities(file, { code, masked, position }) {
   const provides = [...masked.matchAll(/\bprovides\s*:\s*\{/gu)].map((match) => {
     const start = match.index + match[0].length - 1;
     return { start, end: closingOffset(masked, start) };
   });
-  return [...code.matchAll(RUNTIME_CAPABILITY)]
-    .filter((match) => !provides.some(({ start, end }) => match.index > start && match.index < end))
-    .map((match) => ({ file, line: position(match.index).line, capability: match[2] }));
+  const names = [...code.matchAll(CROSS_OWNER_CAPABILITY)].map((match) => ({
+    match,
+    capability: match[2].toLowerCase(),
+    provided: provides.some(({ start, end }) => match.index > start && match.index < end)
+  }));
+  const provided = new Set(names.filter((name) => name.provided).map(({ capability }) => capability));
+  const ownId = ({ match, capability }) => provided.has(capability) &&
+    /\bid\s*:\s*$/u.test(masked.slice(Math.max(0, match.index - 12), match.index));
+  return names.filter((name) => !name.provided && !ownId(name))
+    .map(({ match, capability }) => ({ file, line: position(match.index).line, capability }));
+}
+
+// Whether a rule's setting in a computed config is "error", which ESLint gives as 2 or [2, ...options].
+const isError = (setting) => [2, "error"].includes(Array.isArray(setting) ? setting[0] : setting);
+
+// The app's ESLint, from the app or else beside this check, set to find each file's config as `eslint` does; null when
+// neither has one, or the app has no config: then the lint itself cannot run, which fails on its own.
+async function appEslint(root) {
+  for (const base of [path.join(root, "package.json"), fileURLToPath(import.meta.url)]) {
+    let resolved;
+    try {
+      resolved = createRequire(base).resolve("eslint");
+    } catch {
+      continue;
+    }
+    const api = await import(pathToFileURL(resolved).href);
+    const eslint = new (api.ESLint || api.default.ESLint)({ cwd: root });
+    return await eslint.findConfigFile(path.join(root, "package.json")) ? eslint : null;
+  }
+  return null;
+}
+
+// Fails each app file its ESLint config lints without every data-access rule as an error, and each server file it
+// ignores, unless the baseline's infrastructure lists { file, rule } for each rule that is not on. Each file is judged by
+// the config that governs it, as `eslint` does, and what the rules leave alone (LINT_EXEMPT) is told from that config's
+// directory: a nested application's client code is its own.
+async function checkLintConfig(root, files, baseline, report) {
+  const eslint = await appEslint(root);
+  if (!eslint) return;
+  for (const file of files) {
+    const absolute = path.join(root, file);
+    let configFile;
+    let config;
+    try {
+      configFile = await eslint.findConfigFile(absolute);
+      config = configFile ? await eslint.calculateConfigForFile(absolute) : undefined;
+    } catch (error) {
+      report({ file, line: 1 }, "data/lint-config", `ESLint cannot read the app's config for this file: ${String(error?.message || error).split("\n")[0]}`);
+      return;
+    }
+    const governed = configFile ? toPosixPath(path.relative(path.dirname(configFile), absolute)) : "";
+    if (!configFile || LINT_EXEMPT.test(governed) || (!config && !SERVER_FILE.test(governed))) continue;
+    const off = DATA_ACCESS_RULES.filter((rule) => !isError(config?.rules?.[`jskit/${rule}`]) &&
+      !baseline.infrastructure.some((item) => item?.file === file && item?.rule === rule));
+    if (off.length < 1) continue;
+    report({ file, line: 1 }, "data/lint-config", config
+      ? `the ESLint config does not make ${off.map((rule) => `jskit/${rule}`).join(", ")} an error here`
+      : "the ESLint config ignores this server file, so no data-access rule checks it");
+  }
+}
+
+// Fails each cross-owner capability a module requires that is not reviewed: runtime.database and runtime.resources
+// outside a module declared infrastructure, and any other one the baseline's systemScopes does not list with a reason.
+function checkCapabilities(baseline, uses, report) {
+  for (const { file, line, capability, infrastructure } of uses) {
+    const { gives, infrastructureOnly } = CROSS_OWNER_CAPABILITIES[capability];
+    if (infrastructureOnly) {
+      if (!infrastructure) report({ file, line }, "data/runtime-capability", `requires ${capability}`);
+      continue;
+    }
+    const entry = baseline.systemScopes.find((item) => item?.file === file && item?.capability === capability);
+    if (typeof entry?.systemScope !== "string" || !entry.systemScope.trim()) {
+      report({ file, line }, "data/runtime-capability", `requires ${capability}, which gives ${gives}: once the module must, add ` +
+        `${JSON.stringify({ file, capability, systemScope: "<why it needs this>" })} to "systemScopes".`);
+    }
+  }
 }
 
 // The app's reviewed baseline, or empty lists when it has none; a file that is not that JSON is a finding.
@@ -370,7 +520,7 @@ async function readBaseline(root, report) {
       systemScopes: Array.isArray(baseline.systemScopes) ? baseline.systemScopes : []
     };
   } catch {
-    report({ file: BASELINE_FILE, line: 1 }, "data/baseline", `${BASELINE_FILE} is not JSON; it lists { "infrastructure": [{ "file", "rule" }], "systemScopes": [{ "feature", "systemScope" }] }.`);
+    report({ file: BASELINE_FILE, line: 1 }, "data/baseline", `${BASELINE_FILE} is not JSON; it lists { "infrastructure": [{ "file", "rule" }], "systemScopes": [{ "feature", "systemScope" }, { "file", "capability", "systemScope" }] }.`);
     return { infrastructure: [], systemScopes: [] };
   }
 }
@@ -402,7 +552,7 @@ async function walk(root, directory, files) {
   for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
     const relative = directory ? path.join(directory, entry.name) : entry.name;
     if (entry.isDirectory()) {
-      if (!entry.name.startsWith(".") && !SKIPPED_DIRECTORIES.has(entry.name)) await walk(root, relative, files);
+      if (!entry.name.startsWith(".") && !skipsDirectory(toPosixPath(relative))) await walk(root, relative, files);
     } else if (entry.isFile() && SOURCE_FILE.test(entry.name) && !SKIPPED_FILE.test(entry.name)) {
       files.push(relative);
     }
@@ -472,26 +622,50 @@ function checkSystemScopes(scopes, report) {
   }
 }
 
-/**
- * Reads the app's source and its installed @jskit-ai packages for table resources, system scopes and infrastructure
- * exceptions.
- * @param {{ projectRoot?: string }} options
- */
-async function checkDataAccess({ projectRoot = process.cwd() } = {}) {
-  const root = path.resolve(projectRoot);
-  const sources = [];
+// The app's source files and those of its installed @jskit-ai packages (framework: true), each { file, absolute }.
+async function sourceFiles(root) {
   const appFiles = [];
   await walk(root, "", appFiles);
-  sources.push(...appFiles.map((file) => ({ file, absolute: path.join(root, file), framework: false })));
+  const sources = appFiles.map((file) => ({ file, absolute: path.join(root, file), framework: false }));
   for (const { directory, real } of await frameworkPackages(root)) {
     const files = [];
     await walk(real, "", files);
     sources.push(...files.map((file) => ({ file: path.join(directory, file), absolute: path.join(real, file), framework: true })));
   }
+  return sources;
+}
+
+/**
+ * The table resources the app and its installed @jskit-ai packages define, read from source as checkDataAccess reads
+ * them: each { file, absolute, framework, name, tableName, foreignKeys }, `foreignKeys` true when the definition
+ * declares them. `jskit test --databases` checks the declared keys against the database.
+ * @param {{ projectRoot?: string }} options
+ */
+async function readTableResourceSources({ projectRoot = process.cwd() } = {}) {
+  const resources = [];
+  for (const { file, absolute, framework } of await sourceFiles(path.resolve(projectRoot))) {
+    const source = await readFile(absolute, "utf8");
+    if (!TABLE_RESOURCE_MARKER.test(source)) continue;
+    const read = readSourceFile(source);
+    resources.push(...readTableResources(toPosixPath(file), read).map(({ file: name, line, name: resourceName, tableName, foreignKeys }) =>
+      ({ file: name, line, absolute, framework, name: resourceName, tableName, foreignKeys })));
+  }
+  return resources;
+}
+
+/**
+ * Reads the app's source and its installed @jskit-ai packages for table resources, system scopes and infrastructure
+ * exceptions.
+ * @param {{ projectRoot?: string }} options
+ */
+async function checkDataAccess({ projectRoot = process.cwd() } = {}) {
+  const root = path.resolve(projectRoot);
+  const sources = await sourceFiles(root);
   const resources = [];
   const contracts = [];
   const scopes = [];
   const excuses = [];
+  const capabilities = [];
   const findings = [];
   const report = ({ file, line }, rule, message) => findings.push({ file, line, rule, message });
   for (const { file, absolute, framework } of sources) {
@@ -505,21 +679,21 @@ async function checkDataAccess({ projectRoot = process.cwd() } = {}) {
     contracts.push(...readCrudContracts(read));
     const fileExcuses = readInfrastructureExcuses(name, source);
     excuses.push(...fileExcuses);
-    if (fileExcuses.length < 1) {
-      for (const use of readRuntimeCapabilities(name, read)) {
-        report(use, "data/runtime-capability", `requires ${use.capability}`);
-      }
-    }
+    capabilities.push(...readRuntimeCapabilities(name, read).map((use) => ({ ...use, infrastructure: fileExcuses.length > 0 })));
     if (CLIENT_FILE.test(name)) continue;
     for (const disable of readLintDisables(name, source, read.position)) {
-      report(disable, "data/lint-disabled", disable.rules.length > 0
-        ? `eslint-disable turns off ${disable.rules.join(", ")}`
-        : "eslint-disable names no rule");
+      report(disable, "data/lint-disabled", disable.kind === "config"
+        ? `an inline eslint config sets ${disable.rules.join(", ")}`
+        : disable.rules.length > 0 ? `eslint-disable turns off ${disable.rules.join(", ")}` : "eslint-disable names no rule");
     }
   }
   checkTables(resources, report);
   checkSystemScopes(scopes, report);
-  checkBaseline(await readBaseline(root, report), excuses, scopes, report);
+  const baseline = await readBaseline(root, report);
+  checkBaseline(baseline, excuses, scopes, report);
+  checkCapabilities(baseline, capabilities, report);
+  const appFiles = sources.filter((source) => !source.framework).map((source) => toPosixPath(source.file));
+  await checkLintConfig(root, appFiles, baseline, report);
   findings.sort((left, right) => left.file.localeCompare(right.file) || left.line - right.line);
   return {
     ok: findings.length < 1,
@@ -561,4 +735,4 @@ function formatDataAccessReport(result) {
   return lines.join("\n");
 }
 
-export { checkDataAccess, formatDataAccessReport };
+export { checkDataAccess, formatDataAccessReport, readTableResourceSources };

package/scripts/jskit.mjs

@@ -247,8 +247,18 @@ async function main(argv = process.argv.slice(2)) {
         `${result.changedFiles.map((file) => `- ${file}`).join("\n")}\n`
       );
     }
+    if (result.addedMigrations.length > 0) {
+      process.stdout.write(
+        `The update installed ${result.addedMigrations.length} new package migration(s); run npm run db:migrate before ` +
+        `the app serves requests, since the new packages read what they create:\n` +
+        `${result.addedMigrations.map((entry) => `- ${entry}`).join("\n")}\n`
+      );
+    }
     if (!options.install) {
-      process.stdout.write("Skipped npm install; run it before jskit check.\n");
+      process.stdout.write(
+        "Skipped npm install; run it before jskit check. If it installs new package migrations, run npm run db:migrate " +
+        "before the app serves requests.\n"
+      );
     }
     return;
   }

package/scripts/project-packages.mjs

@@ -438,6 +438,32 @@ async function findImports(root, packageIds) {
   return imports;
 }
 
+// The migration files the installed @jskit-ai packages ship (jskit.migrations.directories and their constraints/),
+// each "<package>: <path in the package>", as the app's migrations read them from node_modules.
+async function installedPackageMigrations(root) {
+  const scope = path.join(root, "node_modules", JSKIT_SCOPE_PREFIX);
+  const names = await readdir(scope).catch((error) => {
+    if (error?.code === "ENOENT") return [];
+    throw error;
+  });
+  const migrations = new Set();
+  for (const name of names) {
+    const packageRoot = path.join(scope, name);
+    const manifestPath = path.join(packageRoot, "package.json");
+    if (!(await fileExists(manifestPath))) continue;
+    const directories = (await readJsonRecord(manifestPath)).value.jskit?.migrations?.directories;
+    for (const directory of Array.isArray(directories) ? directories : []) {
+      for (const folder of [directory, path.join(directory, "constraints")]) {
+        const files = await readdir(path.join(packageRoot, folder)).catch(() => []);
+        for (const file of files.filter((entry) => entry.endsWith(".cjs"))) {
+          migrations.add(`${JSKIT_SCOPE_PREFIX}${name}: ${toPosixPath(path.join(folder, file))}`);
+        }
+      }
+    }
+  }
+  return migrations;
+}
+
 /**
  * Pins a project's JSKIT dependencies to the catalog and installs them; a
  * failed install or check restores the manifests, lockfile and node_modules.
@@ -544,8 +570,11 @@ async function updateProject({
 
   const packageLockPath = path.join(root, "package-lock.json");
   const packageLockSnapshot = install ? await readOptionalFile(packageLockPath) : null;
+  // npm install replaces node_modules, so the migrations the packages shipped are read before it.
+  const migrationsBefore = install ? await installedPackageMigrations(root) : new Set();
   await writeManifestUpdates(updates);
   let installTransaction = null;
+  let addedMigrations = [];
   try {
     if (install) {
       const updatedManifests = await discoverProjectManifests(root, additionalManifests);
@@ -555,6 +584,7 @@ async function updateProject({
       if (!result.ok) {
         throw new Error(`JSKIT graph remains inconsistent after npm install:\n- ${result.issues.join("\n- ")}`);
       }
+      addedMigrations = [...await installedPackageMigrations(root)].filter((entry) => !migrationsBefore.has(entry)).sort();
       await installTransaction.commit();
     }
   } catch (error) {
@@ -586,6 +616,7 @@ async function updateProject({
       updates.map((update) => toPosixPath(path.relative(root, update.manifest.absolutePath)))
     ),
     catalogVersion,
+    addedMigrations: Object.freeze(addedMigrations),
     retiredPackages: Object.freeze(retiredPackageIds.map((packageId) => Object.freeze({
       packageId,
       replacedBy: RETIRED_PACKAGES[packageId].packageId

package/scripts/test-databases.mjs

@@ -3,6 +3,7 @@ import { createRequire } from "node:module";
 import path from "node:path";
 import process from "node:process";
 import { pathToFileURL } from "node:url";
+import { readTableResourceSources } from "./data-access.mjs";
 
 // `jskit test --databases`: each test file running at once gets a database of its own, a copy of TEST_DB_NAME restored
 // from a schema snapshot, from the application's installed @jskit-ai/database-runtime and its knexfile.js, which loads
@@ -13,6 +14,9 @@ import { pathToFileURL } from "node:url";
 const OPTION = "--databases";
 const KNEXFILES = Object.freeze(["knexfile.js", "knexfile.mjs", "knexfile.cjs"]);
 const TEST_DATABASES = "@jskit-ai/database-runtime/server/testDatabases";
+const RESOURCE_RUNTIME = "@jskit-ai/resource-runtime/server";
+const TABLE_RESOURCES = "@jskit-ai/resource-core/shared/tableResource";
+const GUIDE = "https://mobily-enterprises.github.io/jskit-ai/guide/framework/data-access#layer-1-the-table-resource";
 
 /** Runs `load` and puts process.env back as it was, returning what `load` returned and the environment it saw. */
 async function withOwnEnvironment(load) {
@@ -26,6 +30,76 @@ async function withOwnEnvironment(load) {
   }
 }
 
+// A module's exported table resources: each export, or each item of an exported list or object.
+function exportedTableResources(namespace, isTableResource) {
+  return Object.values(namespace).flatMap((value) => {
+    if (isTableResource(value)) return [value];
+    const items = Array.isArray(value) ? value : value && typeof value === "object" ? Object.values(value) : [];
+    return items.filter((item) => isTableResource(item));
+  });
+}
+
+const keyText = ({ tableName, columns, referencedTableName, referencedColumns }) =>
+  `${tableName} (${columns.join(", ")}) -> ${referencedTableName} (${referencedColumns.join(", ")})`;
+
+/**
+ * Compares the foreignKeys the app's table resources and its @jskit-ai packages' declare with the keys TEST_DB_NAME
+ * holds, once a run's databases are ready: json-rest-api relies on a declaration to skip work, so a declared key the
+ * database lacks fails the run. A package's table that the database does not have is left out: node_modules can hold
+ * a package whose migrations the app never runs (one only a devDependency brings, or one left behind), and the app
+ * never reads that table. The app's own tables are always checked. A key of one of the app's own tables that nothing
+ * declares is reported, as work json-rest-api could skip. It imports only the modules that declare foreignKeys; an app
+ * without the resource runtime has nothing to check.
+ * @param {string} cwd
+ * @returns {(knex: object) => Promise<string>}
+ */
+function foreignKeyCheckFor(cwd) {
+  return async (knex) => {
+    const appRequire = createRequire(path.join(cwd, "package.json"));
+    let runtime;
+    let tableResources;
+    try {
+      [runtime, tableResources] = [appRequire.resolve(RESOURCE_RUNTIME), appRequire.resolve(TABLE_RESOURCES)];
+    } catch {
+      return "";
+    }
+    const sources = await readTableResourceSources({ projectRoot: cwd });
+    const tables = sources.filter((source) => !source.framework && source.tableName).map((source) => source.tableName);
+    const declaringFiles = [...new Set(sources.filter((source) => source.foreignKeys).map((source) => source.absolute))];
+    if (tables.length < 1 && declaringFiles.length < 1) return "";
+    const { isTableResource } = await import(pathToFileURL(tableResources).href);
+    const resources = [];
+    const absentPackageTables = new Set();
+    for (const file of declaringFiles) {
+      const declaring = sources.filter((entry) => entry.absolute === file && entry.foreignKeys);
+      const exported = exportedTableResources(await import(pathToFileURL(file).href), isTableResource);
+      for (const source of declaring) {
+        if (!exported.some((resource) => resource.foreignKeys && resource.name === source.name)) {
+          throw new Error(`${source.file}:${source.line} declares foreignKeys on a table resource the module does not export, so ` +
+            `jskit test ${OPTION} cannot check them against the database: export the resource.`);
+        }
+      }
+      for (const resource of exported.filter((entry) => entry.foreignKeys)) {
+        if (declaring[0].framework && !(await knex.schema.hasTable(resource.tableName))) absentPackageTables.add(resource.tableName);
+        else resources.push(resource);
+      }
+    }
+    const { checkForeignKeys } = await import(pathToFileURL(runtime).href);
+    const { missing, undeclared } = await checkForeignKeys({ knex, resources: [...new Set(resources)], tables });
+    if (missing.length > 0) {
+      throw new Error(`jskit test ${OPTION}: ${missing.length} declared foreign key(s) the test database does not hold. ` +
+        `json-rest-api relies on a declared key, so a wrong one changes results: fix the declaration or add the key ` +
+        `with a migration (${GUIDE}).\n` + missing.map((key) => `  ${key.resource}: ${keyText(key)}`).join("\n"));
+    }
+    const declared = [...new Set(resources)].reduce((count, resource) => count + resource.foreignKeys.length, 0);
+    const checked = `foreign keys: ${declared} declared, all in the database` + (absentPackageTables.size < 1 ? "" :
+      ` (${absentPackageTables.size} JSKIT package table(s) the database does not have are not checked)`);
+    if (undeclared.length < 1) return checked;
+    return `${checked}; ${undeclared.length} database key(s) on the app's tables are not declared, so json-rest-api cannot ` +
+      `skip the work they would save (declare each on its table resource's foreignKeys): ${undeclared.map(keyText).join("; ")}`;
+  };
+}
+
 /**
  * The run's databases for `count` files at once, or one file at a time on the connected database.
  * @param {number} count at most the run's test budget, and no more than its test files
@@ -44,7 +118,7 @@ async function testDatabaseRunFor(count, cwd = process.cwd()) {
   const { result: { default: knexConfig, testDatabaseSchema: schema }, environment } = await withOwnEnvironment(async () =>
     import(pathToFileURL(knexfile).href));
   const { testDatabaseRun } = await import(pathToFileURL(testDatabases).href);
-  return testDatabaseRun({ knexConfig, environment, count, schema, appRoot: cwd });
+  return testDatabaseRun({ knexConfig, environment, count, schema, appRoot: cwd, checkDatabase: foreignKeyCheckFor(cwd) });
 }
 
-export { OPTION as DATABASES_OPTION, testDatabaseRunFor };
+export { OPTION as DATABASES_OPTION, foreignKeyCheckFor, testDatabaseRunFor };