@jskit-ai/jskit-catalog 0.2.42 → 0.2.44

package/package.json

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

package/scripts/data-access-files.mjs

@@ -0,0 +1,140 @@
+import { readdir, 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";
+
+// The files `jskit check`'s data part (data-access.mjs) reads: the app's own source, but what its ESLint config ignores
+// outside server source (SERVER_FILE), which no lint reads either; and the source of its installed @jskit-ai packages.
+// With them, each app file's ESLint config, which data/lint-config judges, and the paths it skipped, which it lists.
+
+// 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)/[^/]+/)?`;
+// Server source, which the app's ESLint config may not ignore, as @jskit-ai/config-eslint's base.js and dataAccess.js
+// lint it: at a root (ROOT), its files (a root server.js) and its src/ (an app's whole src/, src/jobs/ and its server
+// code with it; a package's src/server and src/shared), server/, scripts/, bin/ and config/. Anything else the config
+// ignores, a vendored copy of old code or generated output, is not data-access code.
+const SERVER_FILE = new RegExp(`^${ROOT}(?:[^/]+$|(?:src|server|scripts|bin|config)/)`, "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, 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 PACKAGE_DIRECTORY = /^(?:packages|tooling)\/[^/]+\/(.+)$/u;
+const skipsDirectory = (name) => path.posix.basename(name) === "node_modules" ||
+  SKIPPED_ROOT_DIRECTORIES.has(PACKAGE_DIRECTORY.exec(name)?.[1] ?? name);
+
+async function walk(root, directory, files) {
+  let entries;
+  try {
+    entries = await readdir(path.join(root, directory), { withFileTypes: true });
+  } catch (error) {
+    if (error?.code === "ENOENT" || error?.code === "ENOTDIR") return;
+    throw error;
+  }
+  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(".") && !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);
+    }
+  }
+}
+
+// The installed @jskit-ai packages outside the app's own tree (a workspace's linked packages are read as app source),
+// each as { directory, real }: where the app sees it and where it is.
+async function frameworkPackages(root) {
+  let entries;
+  try {
+    entries = await readdir(path.join(root, FRAMEWORK_DIRECTORY), { withFileTypes: true });
+  } catch (error) {
+    if (error?.code === "ENOENT") return [];
+    throw error;
+  }
+  const packages = [];
+  for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
+    const directory = path.join(FRAMEWORK_DIRECTORY, entry.name);
+    const real = await realpath(path.join(root, directory)).catch(() => "");
+    const inside = path.relative(root, real);
+    const appSource = real && !inside.startsWith("..") && !path.isAbsolute(inside) && !inside.split(path.sep).includes("node_modules");
+    if (real && !appSource) packages.push({ directory, real });
+  }
+  return packages;
+}
+
+// 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;
+}
+
+// The ESLint config of each app file that one governs, read as `eslint` reads it: each { file, governed, config },
+// `governed` the file's path from that config's directory and `config` undefined when the config ignores the file; and the
+// first error reading one, after which no more are read. None when the app has no ESLint config (appEslint).
+async function lintConfigs(root, files) {
+  const configs = [];
+  const eslint = await appEslint(root);
+  for (const file of eslint ? files : []) {
+    const absolute = path.join(root, file);
+    try {
+      const configFile = await eslint.findConfigFile(absolute);
+      if (!configFile) continue;
+      const governed = toPosixPath(path.relative(path.dirname(configFile), absolute));
+      configs.push({ file, governed, config: await eslint.calculateConfigForFile(absolute) });
+    } catch (error) {
+      return { configs, error: { file, message: String(error?.message || error).split("\n")[0] } };
+    }
+  }
+  return { configs };
+}
+
+// Code the app's ESLint config ignores that is not server source: no lint reads it, so neither does this check.
+const lintIgnores = ({ governed, config }) => !config && !SERVER_FILE.test(governed);
+
+// The fewest paths that name the app files skipped: for each, the highest directory holding no file that is read, written
+// with a trailing "/", or else the file itself.
+function skippedPaths(files, skipped) {
+  const directories = (file) => file.split("/").slice(0, -1).map((_, index, parts) => parts.slice(0, index + 1).join("/"));
+  const read = new Set(files.filter((file) => !skipped.has(file)).flatMap(directories));
+  return [...new Set([...skipped].map((file) => {
+    const directory = directories(file).find((name) => !read.has(name));
+    return directory ? `${directory}/` : file;
+  }))].sort();
+}
+
+// The app's source files but those its ESLint config ignores outside server source (lintIgnores), and those of its
+// installed @jskit-ai packages (framework: true), each { file, absolute, framework }; with each app file's ESLint config
+// (lintConfigs) and the paths of the files skipped (skippedPaths).
+async function sourceFiles(root) {
+  const appFiles = [];
+  await walk(root, "", appFiles);
+  const names = appFiles.map(toPosixPath);
+  const lint = await lintConfigs(root, names);
+  const skipped = new Set(lint.configs.filter(lintIgnores).map(({ file }) => file));
+  const sources = names.filter((file) => !skipped.has(file)).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, lint, skipped: skippedPaths(names, skipped) };
+}
+
+export { ROOT, lintIgnores, sourceFiles };

package/scripts/data-access.mjs

@@ -1,7 +1,6 @@
-import { readdir, readFile, realpath } from "node:fs/promises";
-import { createRequire } from "node:module";
+import { readFile } from "node:fs/promises";
 import path from "node:path";
-import { fileURLToPath, pathToFileURL } from "node:url";
+import { ROOT, lintIgnores, sourceFiles } from "./data-access-files.mjs";
 import { toPosixPath } from "./files.mjs";
 import { blankJsComments, lineIndex } from "./material3-source.mjs";
 
@@ -15,8 +14,9 @@ import { blankJsComments, lineIndex } from "./material3-source.mjs";
 // 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.
+// error, or ignores though it is server code. Whatever else that config ignores, no lint reads, so neither does this
+// check: it lists what it skipped. 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({
@@ -70,9 +70,6 @@ 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");
@@ -81,20 +78,6 @@ const CLIENT_FILE = new RegExp(`^${ROOT}src/client/`, "u");
 // 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, 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 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;
@@ -441,43 +424,14 @@ function readRuntimeCapabilities(file, { code, masked, position }) {
 // 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;
+function checkLintConfig({ configs, error }, baseline, report) {
+  if (error) report({ file: error.file, line: 1 }, "data/lint-config", `ESLint cannot read the app's config for this file: ${error.message}`);
+  for (const { file, governed, config } of configs) {
+    if (LINT_EXEMPT.test(governed) || lintIgnores({ governed, config })) 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;
@@ -541,45 +495,6 @@ function checkBaseline(baseline, excuses, scopes, report) {
   }
 }
 
-async function walk(root, directory, files) {
-  let entries;
-  try {
-    entries = await readdir(path.join(root, directory), { withFileTypes: true });
-  } catch (error) {
-    if (error?.code === "ENOENT" || error?.code === "ENOTDIR") return;
-    throw error;
-  }
-  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(".") && !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);
-    }
-  }
-}
-
-// The installed @jskit-ai packages outside the app's own tree (a workspace's linked packages are read as app source),
-// each as { directory, real }: where the app sees it and where it is.
-async function frameworkPackages(root) {
-  let entries;
-  try {
-    entries = await readdir(path.join(root, FRAMEWORK_DIRECTORY), { withFileTypes: true });
-  } catch (error) {
-    if (error?.code === "ENOENT") return [];
-    throw error;
-  }
-  const packages = [];
-  for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
-    const directory = path.join(FRAMEWORK_DIRECTORY, entry.name);
-    const real = await realpath(path.join(root, directory)).catch(() => "");
-    const inside = path.relative(root, real);
-    const appSource = real && !inside.startsWith("..") && !path.isAbsolute(inside) && !inside.split(path.sep).includes("node_modules");
-    if (real && !appSource) packages.push({ directory, real });
-  }
-  return packages;
-}
-
 // Every table resource of a table, and of a name, that another one shares: each one is reported, naming the others.
 function checkTables(resources, report) {
   const where = (resource) => `${resource.file}:${resource.line}`;
@@ -622,19 +537,6 @@ function checkSystemScopes(scopes, report) {
   }
 }
 
-// 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);
-  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
@@ -643,7 +545,7 @@ async function sourceFiles(root) {
  */
 async function readTableResourceSources({ projectRoot = process.cwd() } = {}) {
   const resources = [];
-  for (const { file, absolute, framework } of await sourceFiles(path.resolve(projectRoot))) {
+  for (const { file, absolute, framework } of (await sourceFiles(path.resolve(projectRoot))).sources) {
     const source = await readFile(absolute, "utf8");
     if (!TABLE_RESOURCE_MARKER.test(source)) continue;
     const read = readSourceFile(source);
@@ -660,7 +562,7 @@ async function readTableResourceSources({ projectRoot = process.cwd() } = {}) {
  */
 async function checkDataAccess({ projectRoot = process.cwd() } = {}) {
   const root = path.resolve(projectRoot);
-  const sources = await sourceFiles(root);
+  const { sources, lint, skipped } = await sourceFiles(root);
   const resources = [];
   const contracts = [];
   const scopes = [];
@@ -692,8 +594,7 @@ async function checkDataAccess({ projectRoot = process.cwd() } = {}) {
   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);
+  checkLintConfig(lint, baseline, report);
   findings.sort((left, right) => left.file.localeCompare(right.file) || left.line - right.line);
   return {
     ok: findings.length < 1,
@@ -702,7 +603,8 @@ async function checkDataAccess({ projectRoot = process.cwd() } = {}) {
     resources: resources.length,
     systemScopes: scopes.filter((scope) => scope.reason !== null),
     excuses,
-    unnamedFields: unnamedFields(resources, contracts)
+    unnamedFields: unnamedFields(resources, contracts),
+    skipped
   };
 }
 
@@ -728,6 +630,10 @@ function formatDataAccessReport(result) {
       `name one in a contract's fields to offer it (data/unnamed-fields; ${GUIDE}#${SECTIONS["data/unnamed-fields"]}):`);
     for (const { file, line, name, fields } of result.unnamedFields) lines.push(`  ${file}:${line}  ${name}: ${fields.join(", ")}`);
   }
+  if (result.skipped.length > 0) {
+    lines.push(`Skipped, as the app's ESLint config ignores them and they hold no server code (${result.skipped.length}):`);
+    for (const skipped of result.skipped) lines.push(`  ${skipped}`);
+  }
   const listed = `${result.systemScopes.length} system scope(s) and ${result.excuses.length} infrastructure exception(s) listed for review`;
   lines.push(result.ok
     ? `JSKIT data access: ${result.resources} table resource(s), each table and name defined once; ${listed}.`

package/scripts/jskit.mjs

@@ -12,7 +12,7 @@ import {
   formatExportSummary
 } from "./i18n.mjs";
 import { checkDataAccess, formatDataAccessReport } from "./data-access.mjs";
-import { checkMaterial3, formatMaterial3Report, formatNavigationReport } from "./material3.mjs";
+import { checkMaterial3, formatMaterial3Report } from "./material3.mjs";
 import { checkProject, updateProject } from "./project-packages.mjs";
 import { runTests } from "./test-command.mjs";
 import { checkTestRuns, formatTestRunsReport } from "./test-runs.mjs";
@@ -21,9 +21,6 @@ const SCRIPT_PATH = fileURLToPath(import.meta.url);
 const PACKAGE_ROOT = path.resolve(path.dirname(SCRIPT_PATH), "..");
 const CATALOG_PATH = path.join(PACKAGE_ROOT, "catalog", "packages.json");
 const I18N_SUBCOMMANDS = new Set(["export", "check"]);
-// #241: plain `jskit check` fails on every nav/* rule. The JSKIT release that ships once every app has
-// been converted sets this to true, so plain `jskit check` (and every app's verify) fails on every m3/* finding too.
-const MATERIAL3_GATE = false;
 
 function usage() {
   return [
@@ -38,9 +35,12 @@ function usage() {
     "Commands:",
     "  update       Align root and workspace @jskit-ai/* declarations to this published catalog, then run npm install.",
     "  check        Fail when manifests or package-lock.json contain stale, mixed, or private singleton JSKIT stacks,",
-    "               or when application source breaks a JSKIT navigation rule (nav/*): history or window.location",
-    "               navigation, a hand-built in-app path, a back control other than the shell's Up arrow, an inner",
-    "               page without a declared parent, or a main-navigation page that declares one. It also fails when",
+    "               or when application source breaks a rule of the JSKIT Material 3 guide: a navigation rule (nav/*),",
+    "               such as history or window.location navigation, a hand-built in-app path, a back control other than",
+    "               the shell's Up arrow, an inner page without a declared parent or a main-navigation page that",
+    "               declares one, a visual rule (m3/*), such as a raw colour, an MDI icon, an outlined card or a",
+    "               fixed button height, or a rule for using components (ui/*), such as a prop a JSKIT component",
+    "               no longer has. It also fails when",
     "               a package script runs tests outside the machine's test budget (test/*): node --test instead of",
     "               jskit test, a fixed test concurrency or worker count, or a Playwright or Vitest config whose",
     "               workers do not come from testConcurrency() of @jskit-ai/jskit-catalog/test-budget. A Playwright",
@@ -51,9 +51,9 @@ function usage() {
     "               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.",
+    "  check m3     Check application UI source against the JSKIT Material 3 guide alone, with each finding's guide",
+    "               section and every exception: the whole app, or only the given files and directories (a section,",
+    "               or a task's changed files). Plain jskit check applies the same rules to the whole app.",
     "  i18n export  Write the English messages of the installed JSKIT packages to src/locales/<locale>/jskit.json",
     "               for translators, keeping existing translations and extra keys.",
     "  i18n check   Compare src/locales/<locale>/jskit.json with the installed packages' English; fail on missing keys,",
@@ -269,7 +269,7 @@ async function main(argv = process.argv.slice(2)) {
     checkInstalled: true,
     catalog
   });
-  const ui = await checkMaterial3({ projectRoot: options.projectRoot, navigationOnly: !MATERIAL3_GATE });
+  const ui = await checkMaterial3({ projectRoot: options.projectRoot });
   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.
@@ -279,7 +279,7 @@ async function main(argv = process.argv.slice(2)) {
       ? `JSKIT project graph is coordinated across ${result.manifests.length} manifest(s) and ` +
         `${result.installations.length} resolved package installation(s).`
       : `JSKIT project graph is inconsistent:\n- ${result.issues.join("\n- ")}`,
-    MATERIAL3_GATE ? formatMaterial3Report(ui) : formatNavigationReport(ui),
+    formatMaterial3Report(ui),
     formatTestRunsReport(tests)
   ];
   if (!result.ok || !ui.ok || !tests.ok || !data.ok) {

package/scripts/material3.mjs

@@ -24,12 +24,14 @@ import {
   readTags,
   splitVue
 } from "./material3-source.mjs";
+import { checkRemovedProps, checkVuetifyByNameAttribute, checkVuetifyByNameCode, readRemovedProps, readVuetifyComponents } from "./ui-components.mjs";
 
-// `jskit check m3 [path ...]`: the conformance check of the JSKIT Material 3 guide. It reads application source,
-// never runs it. With no paths it checks the whole app; paths narrow it to a section or a task's changed files. The
-// navigation rules (nav/*) are also part of plain `jskit check`, which fails on them for every JSKIT app (#241); the
-// visual rules (m3/*) join them there once every app has been converted. Nothing turns the check off for an app, a
-// folder or a file: the only exception is one line's `m3-check: allow <m3 rule> - <reason>`.
+// The conformance check of the JSKIT Material 3 guide, its navigation rules (nav/*), its visual rules (m3/*) and its
+// rules for using components (ui/*, ui-components.mjs). It
+// reads application source, never runs it. Plain `jskit check` runs it over the whole app and fails on any finding, in
+// every JSKIT app's verify (#241); `jskit check m3 [path ...]` runs it alone, narrowed to a section or a task's changed
+// files. Nothing turns the check off for an app, a folder or a file: the only exception is one line's
+// `m3-check: allow <m3 rule> - <reason>`.
 
 const GUIDE = "https://mobily-enterprises.github.io/jskit-ai/guide/framework/material-3";
 const RULES = Object.freeze({
@@ -40,6 +42,8 @@ const RULES = Object.freeze({
   "m3/outlined-card": "colour",
   "m3/mdi-icon": "foundation",
   "m3/fixed-button-height": "exact-sizes",
+  "ui/removed-prop": "foundation",
+  "ui/vuetify-by-name": "foundation",
   "m3/allow-reason": "exceptions",
   "m3/allow-rule": "exceptions",
   "nav/allow": "exceptions"
@@ -74,6 +78,13 @@ const CHANNEL_COLOUR = String.raw`\b(?:rgba?|hsla?)\(\s*[\d.][^()]*\)`;
 const channelColour = () => new RegExp(CHANNEL_COLOUR, "giu");
 const exactChannelColour = new RegExp(`^${CHANNEL_COLOUR}$`, "iu");
 const CHANNEL_FIX = "Use rgb(var(--v-theme-<role>)), with an alpha for a shadow or scrim: rgba(var(--v-theme-shadow), 0.2).";
+// An attribute that takes a colour as a plain value: a Vuetify colour prop (color, bg-color, baseColor) or SVG paint.
+// Any other attribute's "#add" is a fragment or text.
+const COLOUR_ATTRIBUTE = /(?:colou?r|^fill|^stroke)$/iu;
+// A url(...) in CSS, whose "#fade" names an SVG element, not a colour.
+const CSS_URL = /url\([^)]*\)/giu;
+// A border attribute that draws none: a bound false, 0, null or undefined, or "0" (Vuetify's border-0).
+const NO_BORDER = /^(?:false|0|null|undefined)$/u;
 const quotedHex = () => new RegExp(`(["'\`])(${HEX_COLOUR})\\1`, "gu");
 const MDI_STRING = /\bmdi-[a-z][a-z0-9-]*/gu;
 const MDI_IMPORT = /(?:from\s*|import\s*|require\(\s*)["'](@mdi\/(?:js|font)[^"']*)["']/gu;
@@ -154,7 +165,7 @@ async function collectFiles(projectRoot, paths) {
 
 // One line's `m3-check: allow <m3 rule> - <reason>` excuses that rule on its own line and the next. Any other
 // m3-check comment is itself a finding: one naming a nav/* rule (nothing excuses those), an unknown rule, or no reason.
-function createReporter(file, source, { navigationOnly = false } = {}) {
+function createReporter(file, source) {
   const position = lineIndex(source);
   const findings = [];
   const exceptions = [];
@@ -163,8 +174,6 @@ function createReporter(file, source, { navigationOnly = false } = {}) {
     const at = { file, line, column: 1 };
     if (isNavigationRule(rule)) {
       findings.push({ rule: "nav/allow", ...at, message: `Nothing excuses a navigation rule (${rule}). Delete the comment and fix the line.` });
-    } else if (navigationOnly) {
-      continue;
     } else if (!EXCUSABLE_RULES.has(rule)) {
       const what = rule ? `${rule} is not a Material 3 rule` : "The comment is not \"m3-check: allow <rule> - <reason>\"";
       findings.push({ rule: "m3/allow-rule", ...at, message: `${what}, so it excuses nothing.` });
@@ -176,7 +185,6 @@ function createReporter(file, source, { navigationOnly = false } = {}) {
     }
   }
   function report(rule, offset, message) {
-    if (navigationOnly && !isNavigationRule(rule)) return;
     const at = position(offset);
     if (excused.get(at.line)?.includes(rule)) return;
     findings.push({ rule, file, line: at.line, column: at.column, message });
@@ -185,7 +193,8 @@ function createReporter(file, source, { navigationOnly = false } = {}) {
 }
 
 // Hex colours and navigation in any JavaScript: a script block, a module, or a bound or event attribute's expression.
-function checkCode(code, offset, { report, themed }) {
+function checkCode(code, offset, context) {
+  const { report, themed } = context;
   if (!themed) {
     for (const match of code.matchAll(quotedHex())) {
       report("m3/raw-hex", offset + match.index, `Raw colour ${match[2]}. Use a theme colour role. ${CONTENT_COLOUR}`);
@@ -195,6 +204,7 @@ function checkCode(code, offset, { report, themed }) {
     }
   }
   checkNavigationCode(code, offset, report);
+  checkVuetifyByNameCode(code, offset, context);
 }
 
 function checkScript(code, offset, context) {
@@ -224,14 +234,16 @@ function checkCss(css, offset, context) {
 function checkDeclaration(declaration, context) {
   const { report, themed } = context;
   if (!themed) {
-    for (const match of declaration.value.matchAll(hexPattern())) {
+    const value = declaration.value.replace(CSS_URL, (url) => " ".repeat(url.length));
+    for (const match of value.matchAll(hexPattern())) {
       report("m3/raw-hex", declaration.valueOffset + match.index, `Raw colour ${match[0]}. Use rgb(var(--v-theme-<role>)). ${CONTENT_COLOUR}`);
     }
-    for (const match of declaration.value.matchAll(channelColour())) {
+    for (const match of value.matchAll(channelColour())) {
       report("m3/raw-hex", declaration.valueOffset + match.index, `Raw colour ${match[0]}. ${CHANNEL_FIX} ${CONTENT_COLOUR}`);
     }
   }
-  const buttonRule = declaration.selectors.some((selector) => /\.v-btn\b/u.test(selector));
+  // .v-btn and its modifiers (.v-btn--size-large), not .v-btn-group or .v-btn-toggle.
+  const buttonRule = declaration.selectors.some((selector) => /\.v-btn(?:--[\w-]+)?(?![\w-])/u.test(selector));
   if (buttonRule && ["height", "min-height", "--v-btn-height"].includes(declaration.property)) {
     report("m3/fixed-button-height", declaration.offset, `A fixed ${declaration.property} on buttons. JSKIT ships the 40dp button with its 48dp touch target; remove it. ${SMALLER_BUTTON}`);
   }
@@ -249,6 +261,7 @@ function checkTemplate(template, context) {
   }
   // The branches each h1 renders under: h1s on different branches of one v-if chain never show together.
   const branches = readConditionalBranches(template);
+  checkRemovedProps(tags, context.script, context.removedProps, report);
   const headings = [];
   for (const tag of tags) {
     for (const entry of tag.attributes) {
@@ -274,10 +287,12 @@ function checkAttribute(tag, entry, context) {
     for (const declaration of readInlineDeclarations(entry.value, entry.valueOffset)) {
       checkDeclaration({ ...declaration, selectors: tag.name === "v-btn" ? [".v-btn"] : [] }, context);
     }
-  } else if (!themed && (exactHex.test(entry.value.trim()) || exactChannelColour.test(entry.value.trim()))) {
+  } else if (!themed && COLOUR_ATTRIBUTE.test(entry.name) &&
+    (exactHex.test(entry.value.trim()) || exactChannelColour.test(entry.value.trim()))) {
     report("m3/raw-hex", entry.valueOffset, `Raw colour ${entry.value.trim()}. Use a theme colour role such as color="primary". ${CONTENT_COLOUR}`);
   }
   checkLinkAttribute(tag, entry, context.report);
+  checkVuetifyByNameAttribute(tag, entry, context);
 }
 
 function checkSurface(tag, report) {
@@ -286,7 +301,7 @@ function checkSurface(tag, report) {
     report("m3/outlined-card", variant.offset, `${tag.name} with variant="outlined". Material 3 separates surfaces by tone: use the flat default or a surface-container colour.`);
   }
   const border = attribute(tag, "border");
-  if (border) {
+  if (border && !(border.bound ? NO_BORDER.test(border.value.trim()) : border.value.trim() === "0")) {
     report("m3/outlined-card", border.offset, `${tag.name} with a border. Material 3 separates surfaces by tone: use the flat default or a surface-container colour.`);
   }
 }
@@ -299,7 +314,7 @@ function checkButtonSize(tag, report) {
 }
 
 function checkFile(file, source, context) {
-  const { report, findings, exceptions } = createReporter(file, source, context);
+  const { report, findings, exceptions } = createReporter(file, source);
   const fileContext = { ...context, report, file, themed: file.split("/").slice(0, -1).includes(THEME_DIRECTORY) };
   const extension = path.extname(file);
   if (extension === ".vue") {
@@ -354,30 +369,30 @@ async function checkDarkScheme(projectRoot, checkedFiles, wholeApp) {
 
 /**
  * Checks application source against the Material 3 guide.
- * @param {{ projectRoot?: string, paths?: string[], navigationOnly?: boolean }} options paths are files or directories
- * relative to the root; navigationOnly keeps only the nav/* rules, as plain jskit check does for the whole app
+ * @param {{ projectRoot?: string, paths?: string[] }} options paths are files or directories relative to the root
  */
-async function checkMaterial3({ projectRoot = process.cwd(), paths = [], navigationOnly = false } = {}) {
+async function checkMaterial3({ projectRoot = process.cwd(), paths = [] } = {}) {
   const root = path.resolve(projectRoot);
   const { files, missing } = await collectFiles(root, paths);
   const appFiles = paths.length === 0 ? files : (await collectFiles(root, [])).files;
-  const context = { navigationOnly };
   // Only a page under the shell's top app bar has its title there; one without a bar has its own h1.
   const titledFiles = usesShell(await readProjectManifest(root))
     ? await readTitledFiles({ root, appFiles: [...new Set([...appFiles, ...files])] })
     : new Set();
+  const removedProps = await readRemovedProps(root);
+  const vuetifyComponents = await readVuetifyComponents(root);
   const findings = [];
   const exceptions = [];
   for (const file of files) {
-    const checked = checkFile(file, await readFile(path.join(root, file), "utf8"), { ...context, titled: titledFiles.has(file) });
+    const context = { titled: titledFiles.has(file), removedProps, vuetifyComponents };
+    const checked = checkFile(file, await readFile(path.join(root, file), "utf8"), context);
     findings.push(...checked.findings);
     exceptions.push(...checked.exceptions);
   }
   const pages = await checkPageParents({ root, appFiles, pageFiles: files, report: (finding) => findings.push(finding) });
-  if (!navigationOnly) findings.push(...await checkDarkScheme(root, files, paths.length === 0));
+  findings.push(...await checkDarkScheme(root, files, paths.length === 0));
   findings.sort((left, right) => left.file.localeCompare(right.file) || left.line - right.line || left.column - right.column);
-  const errors = findings.filter((finding) => isNavigationRule(finding.rule)).length;
-  return { projectRoot: root, wholeApp: paths.length === 0, navigationOnly, files, missing, pages, findings, exceptions, errors, ok: findings.length === 0 };
+  return { projectRoot: root, wholeApp: paths.length === 0, files, missing, pages, findings, exceptions, ok: findings.length === 0 };
 }
 
 function formatFindings(result) {
@@ -395,24 +410,13 @@ function formatMaterial3Report(result) {
   const scope = result.wholeApp ? "the whole app" : "the given paths";
   const fileCount = `${result.files.length} file(s)`;
   const withFindings = new Set(result.findings.map((finding) => finding.file)).size;
-  const errors = result.errors > 0 ? ` ${result.errors} of them nav/* rules, which plain jskit check fails on.` : "";
   if (result.exceptions.length > 0) lines.push(`Exceptions (${result.exceptions.length}):`);
   for (const { file, line, rule, reason } of result.exceptions) lines.push(`${file}:${line}  ${rule}  ${reason}`);
   const exceptions = ` Exceptions: ${result.exceptions.length}.`;
   lines.push(result.ok
     ? `Material 3 check: no findings in ${fileCount} of ${scope}.${exceptions}`
-    : `Material 3 check: ${result.findings.length} finding(s) in ${withFindings} of ${fileCount} of ${scope}.${errors}${exceptions}`);
-  return lines.join("\n");
-}
-
-// The navigation part of plain jskit check: errors, with no exemptions.
-function formatNavigationReport(result) {
-  const lines = result.ok ? [] : formatFindings(result);
-  const pages = `${result.pages.length} shell page(s)`;
-  lines.push(result.ok
-    ? `JSKIT navigation rules pass in ${result.files.length} file(s) and ${pages}.`
-    : `JSKIT navigation rules: ${result.findings.length} error(s) in ${result.files.length} file(s) and ${pages}. Fix each one; no comment excuses a navigation rule.`);
+    : `Material 3 check: ${result.findings.length} finding(s) in ${withFindings} of ${fileCount} of ${scope}.${exceptions}`);
   return lines.join("\n");
 }
 
-export { RULES as MATERIAL3_RULES, checkMaterial3, formatMaterial3Report, formatNavigationReport };
+export { RULES as MATERIAL3_RULES, checkMaterial3, formatMaterial3Report };