@jskit-ai/jskit-catalog 0.2.35 → 0.2.36

package/scripts/jskit.mjs

@@ -11,6 +11,7 @@ import {
   formatCheckReport,
   formatExportSummary
 } from "./i18n.mjs";
+import { checkDataAccess, formatDataAccessReport } from "./data-access.mjs";
 import { checkMaterial3, formatMaterial3Report, formatNavigationReport } from "./material3.mjs";
 import { checkProject, updateProject } from "./project-packages.mjs";
 import { runTests } from "./test-command.mjs";
@@ -45,7 +46,11 @@ function usage() {
     "               workers do not come from testConcurrency() of @jskit-ai/jskit-catalog/test-budget. A Playwright",
     "               config with a webServer uses browserTestConfig() of @jskit-ai/jskit-catalog/browser-tests (one",
     "               production-build server and database per worker), never a development server, and every one",
-    "               has a globalTimeout.",
+    "               has a globalTimeout. It fails when two table resources (defineTableResource) of the app and its",
+    "               installed JSKIT packages share a table or a name (data/one-resource-per-table), or when a system",
+    "               scope (a feature's systemScope, a systemContext() call) gives no literal reason (data/system-scope),",
+    "               and it lists every system scope and every file the infrastructure exception lifts past the",
+    "               data-access lint rules for review.",
     "  check m3     List application UI source that departs from the JSKIT Material 3 guide, each finding with its",
     "               guide section: the whole app, or only the given files and directories (a section, or a task's",
     "               changed files). Its visual rules (m3/*) are a report; its nav/* rules are plain jskit check's.",
@@ -231,6 +236,9 @@ async function main(argv = process.argv.slice(2)) {
       additionalManifests: options.additionalManifests,
       install: options.install
     });
+    for (const { packageId, replacedBy } of result.retiredPackages) {
+      process.stdout.write(`Removed ${packageId}, which this release retired: ${replacedBy} replaced it.\n`);
+    }
     if (result.changedFiles.length < 1) {
       process.stdout.write(`JSKIT manifests already match catalog ${result.catalogVersion}.\n`);
     } else {
@@ -253,7 +261,10 @@ async function main(argv = process.argv.slice(2)) {
   });
   const ui = await checkMaterial3({ projectRoot: options.projectRoot, navigationOnly: !MATERIAL3_GATE });
   const tests = await checkTestRuns({ projectRoot: options.projectRoot, manifests: result.manifests });
+  const data = await checkDataAccess({ projectRoot: options.projectRoot });
+  // The data rules first: a graph that fails on many pin versions would otherwise bury them.
   const reports = [
+    formatDataAccessReport(data),
     result.ok
       ? `JSKIT project graph is coordinated across ${result.manifests.length} manifest(s) and ` +
         `${result.installations.length} resolved package installation(s).`
@@ -261,7 +272,7 @@ async function main(argv = process.argv.slice(2)) {
     MATERIAL3_GATE ? formatMaterial3Report(ui) : formatNavigationReport(ui),
     formatTestRunsReport(tests)
   ];
-  if (!result.ok || !ui.ok || !tests.ok) {
+  if (!result.ok || !ui.ok || !tests.ok || !data.ok) {
     throw new Error(reports.join("\n"));
   }
   process.stdout.write(`${reports.join("\n")}\n`);

package/scripts/project-packages.mjs

@@ -1,4 +1,4 @@
-import { realpath, rename, rm, writeFile } from "node:fs/promises";
+import { readdir, readFile, realpath, rename, rm, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { fileExists, toPosixPath } from "./files.mjs";
 import { readOptionalFile, restoreProjectFiles, runNpmInstall, writeManifestUpdates } from "./project-install.mjs";
@@ -13,6 +13,16 @@ const DEPENDENCY_FIELDS = Object.freeze([
   "optionalDependencies"
 ]);
 const UPDATE_SCRIPT = "npx --yes @jskit-ai/jskit-catalog@latest update";
+// JSKIT packages a release retired, each with what replaced it. The updater removes their declarations itself, and
+// refuses while the application's own code still imports one, naming the import to use instead.
+const RETIRED_PACKAGES = Object.freeze({
+  "@jskit-ai/json-rest-api-core": Object.freeze({
+    packageId: "@jskit-ai/resource-runtime",
+    importFrom: "@jskit-ai/resource-runtime/server (its types from @jskit-ai/resource-runtime/server/types)"
+  })
+});
+const SOURCE_FILE_PATTERN = /\.(?:[cm]?[jt]s|vue)$/u;
+const SKIPPED_DIRECTORIES = new Set(["node_modules", "dist", "build", "coverage"]);
 const CHECK_SCRIPT = "jskit check";
 
 function normalizeCatalog(catalog = {}) {
@@ -395,6 +405,39 @@ async function preparePackageLockForInstall(projectRoot, manifests, packageLockP
   }
 }
 
+/**
+ * The application's files, outside node_modules and build output, that import one of the packages.
+ * @param {string} root
+ * @param {string[]} packageIds
+ * @returns {Promise<Map<string, string[]>>} The importing files, relative to root, by package.
+ */
+async function findImports(root, packageIds) {
+  const imports = new Map();
+  const patterns = packageIds.map((packageId) => {
+    const name = packageId.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+    return [packageId, new RegExp(`["']${name}(?:/[^"']*)?["']`, "u")];
+  });
+  const visit = async (directory) => {
+    for (const entry of await readdir(directory, { withFileTypes: true })) {
+      const absolutePath = path.join(directory, entry.name);
+      if (entry.isDirectory()) {
+        if (!entry.name.startsWith(".") && !SKIPPED_DIRECTORIES.has(entry.name)) {
+          await visit(absolutePath);
+        }
+      } else if (entry.isFile() && SOURCE_FILE_PATTERN.test(entry.name)) {
+        const source = await readFile(absolutePath, "utf8");
+        for (const [packageId, pattern] of patterns) {
+          if (pattern.test(source)) {
+            imports.set(packageId, [...(imports.get(packageId) || []), toPosixPath(path.relative(root, absolutePath))]);
+          }
+        }
+      }
+    }
+  };
+  await visit(root);
+  return imports;
+}
+
 /**
  * Pins a project's JSKIT dependencies to the catalog and installs them; a
  * failed install or check restores the manifests, lockfile and node_modules.
@@ -414,10 +457,20 @@ async function updateProject({
   const localPackageNames = collectLocalPackageNames(manifests);
   const declarations = collectManifestDeclarations(manifests, root)
     .filter((entry) => !localPackageNames.has(entry.packageId));
+  const retiredPackageIds = [...new Set(
+    declarations.map((entry) => entry.packageId).filter((packageId) => Object.hasOwn(RETIRED_PACKAGES, packageId))
+  )].sort();
+  const retiredImports = retiredPackageIds.length > 0 ? await findImports(root, retiredPackageIds) : new Map();
+  if (retiredImports.size > 0) {
+    throw new Error(`Cannot update while the application imports retired JSKIT packages:\n${[...retiredImports]
+      .map(([packageId, files]) => `- ${packageId} (in ${files.sort().join(", ")}): ${RETIRED_PACKAGES[packageId].packageId} ` +
+        `replaced it; import from ${RETIRED_PACKAGES[packageId].importFrom} instead.`)
+      .join("\n")}`);
+  }
   const unknownPackageIds = [...new Set(
     declarations
       .map((entry) => entry.packageId)
-      .filter((packageId) => !normalizedCatalog.versions.has(packageId))
+      .filter((packageId) => !normalizedCatalog.versions.has(packageId) && !retiredPackageIds.includes(packageId))
   )].sort();
   if (unknownPackageIds.length > 0) {
     throw new Error(`Cannot update JSKIT packages missing from the coordinated catalog: ${unknownPackageIds.join(", ")}.`);
@@ -449,6 +502,11 @@ async function updateProject({
         if (!packageId.startsWith(JSKIT_SCOPE_PREFIX) || localPackageNames.has(packageId)) {
           continue;
         }
+        if (retiredPackageIds.includes(packageId)) {
+          delete next[field][packageId];
+          changed = true;
+          continue;
+        }
         const expectedVersion = normalizedCatalog.versions.get(packageId);
         if (next[field][packageId] !== expectedVersion) {
           next[field][packageId] = expectedVersion;
@@ -527,7 +585,11 @@ async function updateProject({
     changedFiles: Object.freeze(
       updates.map((update) => toPosixPath(path.relative(root, update.manifest.absolutePath)))
     ),
-    catalogVersion
+    catalogVersion,
+    retiredPackages: Object.freeze(retiredPackageIds.map((packageId) => Object.freeze({
+      packageId,
+      replacedBy: RETIRED_PACKAGES[packageId].packageId
+    })))
   });
 }
 

package/scripts/verify-packages.mjs

@@ -249,6 +249,17 @@ async function validateMigrationDirectory(packageName, absoluteDirectory, relati
   return entries;
 }
 
+// Each apiSummary surface names an entrypoint the package exports, or a group of them ("./server" for its "./server/..."
+// subpaths), so the catalog never describes an import that fails.
+function validateApiSummarySurfaces(packageJson) {
+  const exported = packageJson.exports && typeof packageJson.exports === "object" ? Object.keys(packageJson.exports) : [];
+  for (const { subpath } of packageJson.jskit?.metadata?.apiSummary?.surfaces || []) {
+    if (!exported.some((entry) => entry === subpath || entry.startsWith(`${subpath}/`))) {
+      throw new Error(`${packageJson.name}#jskit.metadata.apiSummary describes ${subpath}, which the package does not export.`);
+    }
+  }
+}
+
 async function validatePackage(packageRecord, localVersions, migrationOwners) {
   const { packageJson, packageRoot, manifestPath } = packageRecord;
   const packageId = String(packageJson.name || "").trim();
@@ -282,6 +293,7 @@ async function validatePackage(packageRecord, localVersions, migrationOwners) {
     throw new Error(`${packageId} cannot both provide and require the same capability.`);
   }
 
+  validateApiSummarySurfaces(packageJson);
   const serverProviderCount = await validateProviderList(packageRecord, "server");
   await validateProviderList(packageRecord, "client");
   await validateMigrations(packageRecord, migrationOwners);
@@ -337,12 +349,22 @@ function validateCapabilityClosure(packages, { builtinCapabilities = BUILTIN_CAP
   }
 }
 
+// The application's one table runtime: a package that takes it as a dependency can install a second copy of it beside
+// the application's, with its own tables, transactions and error classes. Every package takes it as a peer.
+const TABLE_RUNTIME_PACKAGE_IDS = Object.freeze(["@jskit-ai/database-runtime", "@jskit-ai/resource-runtime"]);
+
 function validateSingletonPeerDependencies(packages) {
   const singletonPackageIds = new Set(collectSingletonPackageIds(packages.map(({ packageJson }) => packageJson)));
 
   for (const { packageJson } of packages) {
     for (const section of ["dependencies", "optionalDependencies"]) {
       for (const dependencyId of Object.keys(packageJson[section] || {})) {
+        if (TABLE_RUNTIME_PACKAGE_IDS.includes(dependencyId)) {
+          throw new Error(
+            `${packageJson.name}#${section}.${dependencyId} must be declared in peerDependencies because ` +
+            `${dependencyId} is the application's one table runtime.`
+          );
+        }
         if (!singletonPackageIds.has(dependencyId)) {
           continue;
         }
@@ -400,6 +422,7 @@ if (process.argv[1] && path.resolve(process.argv[1]) === SCRIPT_PATH) {
 
 export {
   main,
+  validateApiSummarySurfaces,
   validateCapabilityClosure,
   validateMigrations,
   validateProviderExport,