@jskit-ai/jskit-catalog 0.2.30 → 0.2.32

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/jskit-catalog",
-  "version": "0.2.30",
+  "version": "0.2.32",
   "description": "Published metadata catalog for JSKIT package metadata.",
   "type": "module",
   "files": [
@@ -14,13 +14,14 @@
     ".": "./catalog/packages.json",
     "./packages": "./catalog/packages.json",
     "./project-packages": "./scripts/project-packages.mjs",
+    "./test-budget": "./scripts/test-budget.mjs",
     "./package.json": "./package.json"
   },
   "scripts": {
     "catalog:build": "node ./scripts/build-catalog.mjs",
     "jskit:check": "node ./scripts/jskit.mjs check",
     "verify:packages": "node ./scripts/verify-packages.mjs",
-    "test": "node --test --test-concurrency=1"
+    "test": "jskit test"
   },
   "engines": {
     "node": "^22.13.0 || ^24.0.0 || ^26.0.0"

package/scripts/jskit.mjs

@@ -13,6 +13,8 @@ import {
 } from "./i18n.mjs";
 import { checkMaterial3, formatMaterial3Report, formatNavigationReport } from "./material3.mjs";
 import { checkProject, updateProject } from "./project-packages.mjs";
+import { runTests } from "./test-command.mjs";
+import { checkTestRuns, formatTestRunsReport } from "./test-runs.mjs";
 
 const SCRIPT_PATH = fileURLToPath(import.meta.url);
 const PACKAGE_ROOT = path.resolve(path.dirname(SCRIPT_PATH), "..");
@@ -30,13 +32,17 @@ function usage() {
     "  jskit check m3 [<path> ...] [--root <path>]",
     "  jskit i18n export <locale> [--root <path>]",
     "  jskit i18n check <locale> [--root <path>]",
+    "  jskit test [node options] [files or globs]",
     "",
     "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.",
+    "               page without a declared parent, or a main-navigation page that declares one. 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.",
     "  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.",
@@ -44,6 +50,10 @@ function usage() {
     "               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,",
     "               invalid messages or placeholder mismatches, and list extra keys and untranslated messages.",
+    "  test         Run node --test with these arguments, test files in parallel within the machine's test budget:",
+    "               V64_TEST_CONCURRENCY when it is a positive whole number, otherwise half of the machine's CPUs",
+    "               (at least 1). A file whose first line is `// jskit-test: alone - <reason>` runs after the others,",
+    "               on its own.",
     "",
     "<locale> is a BCP 47 language tag, such as fr or pt-BR."
   ].join("\n");
@@ -55,6 +65,9 @@ function parseArgs(argv = []) {
   const command = commandArgument === "--help" || commandArgument === "-h"
     ? "help"
     : commandArgument;
+  if (command === "test") {
+    return { command, args };
+  }
   const options = {
     command,
     projectRoot: process.cwd(),
@@ -200,6 +213,10 @@ async function main(argv = process.argv.slice(2)) {
     await runMaterial3(options);
     return;
   }
+  if (options.command === "test") {
+    process.exitCode = await runTests(options.args);
+    return;
+  }
 
   const catalog = await readCatalog();
   if (options.command === "update") {
@@ -230,14 +247,16 @@ async function main(argv = process.argv.slice(2)) {
     catalog
   });
   const ui = await checkMaterial3({ projectRoot: options.projectRoot, navigationOnly: !MATERIAL3_GATE });
+  const tests = await checkTestRuns({ projectRoot: options.projectRoot, manifests: result.manifests });
   const reports = [
     result.ok
       ? `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)
+    MATERIAL3_GATE ? formatMaterial3Report(ui) : formatNavigationReport(ui),
+    formatTestRunsReport(tests)
   ];
-  if (!result.ok || !ui.ok) {
+  if (!result.ok || !ui.ok || !tests.ok) {
     throw new Error(reports.join("\n"));
   }
   process.stdout.write(`${reports.join("\n")}\n`);

package/scripts/material3-source.mjs

@@ -2,6 +2,8 @@
 // so these read Vue, JavaScript and CSS just far enough for the Material 3 rules: blocks, tags with attributes,
 // declarations, and comments blanked to spaces so every offset still maps to its original line and column.
 
+import path from "node:path";
+
 const HEX_DIGITS = "[0-9a-fA-F]";
 // #rgb, #rgba, #rrggbb and #rrggbbaa, not followed by another word character.
 const HEX_COLOUR = `#(?:${HEX_DIGITS}{8}|${HEX_DIGITS}{6}|${HEX_DIGITS}{3,4})(?![\\w-])`;
@@ -121,6 +123,10 @@ function splitVue(source) {
 
 const ATTRIBUTE = /([^\s"'<>/=]+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>]+)))?/gu;
 const TAG = /<([A-Za-z][\w.-]*)((?:\s+[^\s"'<>/=]+(?:\s*=\s*(?:"[^"]*"|'[^']*'|[^\s>]+))?)*)\s*(\/?)>/gu;
+// An opening or closing tag in a template, with its attributes; HTML void elements never close.
+const TEMPLATE_TAG = /<(\/?)([A-Za-z][\w.-]*)((?:\s+[^\s"'<>/=]+(?:\s*=\s*(?:"[^"]*"|'[^']*'|[^\s>]+))?)*)\s*(\/?)>/gu;
+const VOID_TAGS = new Set(["area", "base", "br", "col", "embed", "hr", "img", "input", "link", "meta", "source", "track", "wbr"]);
+const CONDITIONAL = /(?:^|\s)v-(if|else-if|else)(?=[\s=]|$)/u;
 
 function kebab(name) {
   return name.replace(/([a-z0-9])([A-Z])/gu, "$1-$2").toLowerCase();
@@ -172,6 +178,39 @@ function readTags(template) {
   return tags;
 }
 
+// The v-if chains each element of a template (comments already blanked) renders under, by its offset: a list of
+// [chain, branch] pairs, outermost first. A v-if starts a chain among its siblings, each v-else-if or v-else right
+// after it is the chain's next branch, so two elements on different branches of one chain never render together.
+function readConditionalBranches(template) {
+  const branches = new Map();
+  const open = [{ name: "", path: [], chain: null }];
+  let chains = 0;
+  for (const match of template.text.matchAll(TEMPLATE_TAG)) {
+    const [, closing, rawName, attributes, selfClosing] = match;
+    const name = kebab(rawName);
+    if (closing) {
+      const index = open.findLastIndex((entry) => entry.name === name);
+      if (index > 0) open.length = index;
+      continue;
+    }
+    const parent = open.at(-1);
+    const directive = CONDITIONAL.exec(attributes)?.[1];
+    if (directive === "if") parent.chain = { id: (chains += 1), branch: 0 };
+    else if (directive && parent.chain) parent.chain.branch += 1;
+    else parent.chain = null;
+    const path = parent.chain ? [...parent.path, [parent.chain.id, parent.chain.branch]] : parent.path;
+    if (directive === "else") parent.chain = null;
+    branches.set(template.offset + match.index, path);
+    if (!selfClosing && !VOID_TAGS.has(name)) open.push({ name, path, chain: null });
+  }
+  return branches;
+}
+
+// Whether two elements sit on different branches of one v-if chain, so at most one of them renders.
+function exclusiveBranches(left, right) {
+  return left.some(([chain, branch]) => right.some(([other, otherBranch]) => other === chain && otherBranch !== branch));
+}
+
 // CSS declarations with the selectors that enclose them, for flat CSS, nested SCSS and at-rule blocks.
 function readDeclarations(css, offset) {
   const declarations = [];
@@ -207,13 +246,57 @@ function readInlineDeclarations(text, offset) {
   return readDeclarations(`x{${text}}`, offset - 2);
 }
 
+// A default import: `import Name from "specifier"`, its name and specifier.
+const DEFAULT_IMPORT = /\bimport\s+([A-Za-z_$][\w$]*)\s+from\s*["']([^"']+)["']/gu;
+
+// The value of the first balanced { ... } or [ ... ] starting at or after `start`.
+function balancedFrom(text, start, open = "{", close = "}") {
+  const first = text.indexOf(open, start);
+  if (first < 0) return null;
+  let depth = 0;
+  for (let index = first; index < text.length; index += 1) {
+    if (text[index] === open) depth += 1;
+    else if (text[index] === close && --depth === 0) return { start: first, end: index + 1, text: text.slice(first, index + 1) };
+  }
+  return null;
+}
+
+// The object literal that encloses `offset`, as { start, end, text }, or null.
+function enclosingObject(text, offset) {
+  let depth = 0;
+  for (let index = offset; index >= 0; index -= 1) {
+    if (text[index] === "}") depth += 1;
+    else if (text[index] === "{") {
+      if (depth === 0) return balancedFrom(text, index);
+      depth -= 1;
+    }
+  }
+  return null;
+}
+
+// The app's .vue file an import names: "@/components/Bar.vue" is src/components/Bar.vue; "./Bar" is beside the file.
+function localComponent(file, specifier, known) {
+  const base = specifier.startsWith("@/")
+    ? path.posix.join("src", specifier.slice(2))
+    : path.posix.join(path.posix.dirname(file), specifier);
+  return [base, `${base}.vue`].find((candidate) => candidate.endsWith(".vue") && known.has(candidate)) || null;
+}
+
 export {
+  DEFAULT_IMPORT,
+  TEMPLATE_TAG,
+  VOID_TAGS,
   HEX_COLOUR,
+  balancedFrom,
   blankCssComments,
   blankHtmlComments,
   blankJsComments,
+  enclosingObject,
+  exclusiveBranches,
   kebab,
   lineIndex,
+  localComponent,
+  readConditionalBranches,
   readDeclarations,
   readExceptions,
   readInlineDeclarations,

package/scripts/material3.mjs

@@ -7,14 +7,17 @@ import {
   checkLinkAttribute,
   checkNavigationCode,
   checkPageParents,
-  checkScriptBackNames
+  checkScriptBackNames,
+  readTitledFiles
 } from "./navigation.mjs";
 import {
   HEX_COLOUR,
   blankCssComments,
   blankHtmlComments,
   blankJsComments,
+  exclusiveBranches,
   lineIndex,
+  readConditionalBranches,
   readDeclarations,
   readExceptions,
   readInlineDeclarations,
@@ -50,12 +53,27 @@ const SKIPPED_DIRECTORIES = new Set([
   "fixtures", "server", "migrations"
 ]);
 const SKIPPED_FILE = /\.(?:test|spec)\.[cm]?[jt]s$|\.d\.ts$/u;
+// In JSKIT's own repository, packages/ holds the framework, which implements the navigation, Up and reloads the rules
+// send an app to (ShellUpButton, reloadAppPage(), leaveApp(), the system Back button). A whole-app run reads only the
+// app code a JSKIT package carries, its patterns and templates; an app's own packages are read in full.
+const FRAMEWORK_SCOPE = "@jskit-ai/";
+const FRAMEWORK_APP_CODE = new Set(["patterns", "templates"]);
 // The generated colour scheme is the one home of hex values.
 const THEME_DIRECTORY = "theme";
+// Colours that are content, not UI, keep one value in both schemes, so they are not theme colours (which are toned per
+// scheme): they are named hex exports of src/theme/palettes.js, which this check, like all of src/theme/, reads as
+// the place for hex values.
+const CONTENT_COLOUR = "A content colour (an identity palette, artwork, a brand mark, a chart series) is a named export of src/theme/palettes.js, used as it is.";
 const WHOLE_APP_ROOTS = Object.freeze(["src", "packages"]);
 
 const hexPattern = () => new RegExp(HEX_COLOUR, "gu");
 const exactHex = new RegExp(`^${HEX_COLOUR}$`, "u");
+// A colour written as channels, as a hand-made shadow is: rgba(0, 0, 0, 0.15), rgb(0 0 0 / 20%), hsl(...). One that
+// reads a theme role, rgba(var(--v-theme-shadow), 0.2), is not.
+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).";
 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;
@@ -67,6 +85,7 @@ const GENERATED_SCHEMES = /\bcreateMaterialVuetifyOptions\s*\(/u;
 const PINNED_LIGHT = /\bdefaultTheme\s*:\s*["']light["']/u;
 const SHELL_PACKAGE = "@jskit-ai/shell-web";
 const isNavigationRule = (rule) => rule.startsWith("nav/");
+const SMALLER_BUTTON = "A smaller button is size=\"small\" or \"x-small\", which keeps the touch target.";
 
 function isSkippedDirectory(name) {
   return SKIPPED_DIRECTORIES.has(name);
@@ -77,7 +96,18 @@ function isSourceFile(relativePath) {
   return !relativePath.split("/").slice(0, -1).some(isSkippedDirectory);
 }
 
-async function walk(projectRoot, directory, files) {
+async function isFrameworkPackage(projectRoot, directory) {
+  if (!/^packages\/[^/]+$/u.test(directory)) return false;
+  try {
+    const manifest = JSON.parse(await readFile(path.join(projectRoot, directory, "package.json"), "utf8"));
+    return String(manifest?.name || "").startsWith(FRAMEWORK_SCOPE);
+  } catch (error) {
+    if (error?.code === "ENOENT") return false;
+    throw error;
+  }
+}
+
+async function walk(projectRoot, directory, files, wholeApp = false) {
   let entries;
   try {
     entries = await readdir(path.join(projectRoot, directory), { withFileTypes: true });
@@ -85,10 +115,12 @@ async function walk(projectRoot, directory, files) {
     if (error?.code === "ENOENT") return;
     throw error;
   }
+  const framework = wholeApp && await isFrameworkPackage(projectRoot, directory);
   for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
     const relative = directory ? `${directory}/${entry.name}` : entry.name;
+    if (framework && !(entry.isDirectory() && FRAMEWORK_APP_CODE.has(entry.name))) continue;
     if (entry.isDirectory()) {
-      if (!isSkippedDirectory(entry.name)) await walk(projectRoot, relative, files);
+      if (!isSkippedDirectory(entry.name)) await walk(projectRoot, relative, files, wholeApp);
     } else if (entry.isFile() && isSourceFile(relative)) {
       files.add(relative);
     }
@@ -114,7 +146,7 @@ async function collectFiles(projectRoot, paths) {
       if (paths.length > 0) missing.push(target);
       continue;
     }
-    if (info.isDirectory()) await walk(projectRoot, relative === "" ? "" : relative, files);
+    if (info.isDirectory()) await walk(projectRoot, relative === "" ? "" : relative, files, paths.length === 0);
     else if (isSourceFile(relative)) files.add(relative);
   }
   return { files: [...files].sort(), missing };
@@ -156,7 +188,10 @@ function createReporter(file, source, { navigationOnly = false } = {}) {
 function checkCode(code, offset, { report, themed }) {
   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; hex values live only in the generated scheme under src/theme/.`);
+      report("m3/raw-hex", offset + match.index, `Raw colour ${match[2]}. Use a theme colour role. ${CONTENT_COLOUR}`);
+    }
+    for (const match of code.matchAll(channelColour())) {
+      report("m3/raw-hex", offset + match.index, `Raw colour ${match[0]}. ${CHANNEL_FIX} ${CONTENT_COLOUR}`);
     }
   }
   checkNavigationCode(code, offset, report);
@@ -190,12 +225,15 @@ function checkDeclaration(declaration, context) {
   const { report, themed } = context;
   if (!themed) {
     for (const match of declaration.value.matchAll(hexPattern())) {
-      report("m3/raw-hex", declaration.valueOffset + match.index, `Raw colour ${match[0]}. Use rgb(var(--v-theme-<role>)); hex values live only in the generated scheme under src/theme/.`);
+      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())) {
+      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));
   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.`);
+    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}`);
   }
 }
 
@@ -209,7 +247,9 @@ function checkTemplate(template, context) {
   for (const match of template.text.matchAll(MDI_STRING)) {
     report("m3/mdi-icon", template.offset + match.index, `MDI icon "${match[0]}". Use a Material Symbols alias such as "$add" from the app's Vuetify icon aliases.`);
   }
-  let headings = 0;
+  // The branches each h1 renders under: h1s on different branches of one v-if chain never show together.
+  const branches = readConditionalBranches(template);
+  const headings = [];
   for (const tag of tags) {
     for (const entry of tag.attributes) {
       checkAttribute(tag, entry, context);
@@ -218,9 +258,10 @@ function checkTemplate(template, context) {
     if (tag.name === "v-btn") checkButtonSize(tag, report);
     checkBackControl(tag, report, context.script);
     if (tag.name === "h1") {
-      headings += 1;
-      if (headings > 1) report("m3/duplicate-h1", tag.offset, "A second h1 in one template. A page has one title, carried by the top app bar.");
-      else if (context.shell) report("m3/duplicate-h1", tag.offset, "An in-page h1. The top app bar carries the page title; use a title role (text-title-large) for a section title.");
+      const branch = branches.get(tag.offset) || [];
+      if (headings.some((other) => !exclusiveBranches(other, branch))) report("m3/duplicate-h1", tag.offset, "A second h1 in one template. A page has one title, carried by the top app bar.");
+      else if (context.titled) report("m3/duplicate-h1", tag.offset, "An in-page h1 under the top app bar, which carries the page title; use a title role (text-title-large) for a section title.");
+      headings.push(branch);
     }
   }
 }
@@ -233,8 +274,8 @@ 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())) {
-    report("m3/raw-hex", entry.valueOffset, `Raw colour ${entry.value.trim()}. Use a theme colour role such as color="primary".`);
+  } else if (!themed && (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);
 }
@@ -253,7 +294,7 @@ function checkSurface(tag, report) {
 function checkButtonSize(tag, report) {
   for (const name of ["height", "min-height"]) {
     const entry = attribute(tag, name);
-    if (entry) report("m3/fixed-button-height", entry.offset, `A fixed ${name} on v-btn. JSKIT ships the 40dp button with its 48dp touch target; remove it.`);
+    if (entry) report("m3/fixed-button-height", entry.offset, `A fixed ${name} on v-btn. JSKIT ships the 40dp button with its 48dp touch target; remove it. ${SMALLER_BUTTON}`);
   }
 }
 
@@ -320,11 +361,15 @@ async function checkMaterial3({ projectRoot = process.cwd(), paths = [], navigat
   const root = path.resolve(projectRoot);
   const { files, missing } = await collectFiles(root, paths);
   const appFiles = paths.length === 0 ? files : (await collectFiles(root, [])).files;
-  const context = { shell: usesShell(await readProjectManifest(root)), navigationOnly };
+  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 findings = [];
   const exceptions = [];
   for (const file of files) {
-    const checked = checkFile(file, await readFile(path.join(root, file), "utf8"), context);
+    const checked = checkFile(file, await readFile(path.join(root, file), "utf8"), { ...context, titled: titledFiles.has(file) });
     findings.push(...checked.findings);
     exceptions.push(...checked.exceptions);
   }