@jskit-ai/jskit-catalog 0.2.31 → 0.2.32

package/scripts/navigation.mjs

@@ -1,6 +1,19 @@
 import { readFile } from "node:fs/promises";
 import path from "node:path";
-import { blankJsComments, lineIndex, splitVue } from "./material3-source.mjs";
+import {
+  DEFAULT_IMPORT,
+  TEMPLATE_TAG,
+  VOID_TAGS,
+  balancedFrom,
+  blankHtmlComments,
+  blankJsComments,
+  enclosingObject,
+  kebab,
+  lineIndex,
+  localComponent,
+  splitVue
+} from "./material3-source.mjs";
+import { readPackageRoutes } from "./package-routes.mjs";
 
 // The navigation rules of the JSKIT Material 3 guide (#241). The shell owns Up and the per-tab trail;
 // an app declares each inner page's parent and links through JSKIT navigation, nothing more. Plain `jskit check`
@@ -15,7 +28,8 @@ const RULES = Object.freeze({
   "nav/missing-parent": "what-an-app-declares",
   "nav/top-level-parent": "what-an-app-declares",
   "nav/placement-data": "what-an-app-declares",
-  "nav/missing-shell-layout": "what-an-app-declares"
+  "nav/missing-shell-layout": "what-an-app-declares",
+  "nav/surface-parent": "what-an-app-declares"
 });
 
 const HISTORY_CALL = /(?<![\w$.])(?:(?:window|globalThis)\s*\.\s*)?history\s*\.\s*(?:back|go|forward|pushState|replaceState)\s*\(/gu;
@@ -104,12 +118,17 @@ function isPlacementLink(code, offset) {
   return Boolean(placement) && /\btarget\s*:\s*["'`][\w.-]+["'`]/u.test(placement.text) && /\bkind\s*:/u.test(placement.text);
 }
 
-// A back-named function that navigates the app; a variable, an import or an in-component step is not back logic.
+// A back-named function that navigates the app, and the import of a back component (ContextBackButton); a variable,
+// a composable's import or an in-component step is not back logic.
 function checkScriptBackNames(code, offset, report) {
   for (const match of code.matchAll(BACK_DEFINITION)) {
     if (!navigatesApp(definitionOf(code, match[1]), code)) continue;
     report("nav/back-control", offset + match.index, `${match[1]} navigates back in the app. ${UP_OWNER}; delete it and declare the page's parent.`);
   }
+  for (const match of code.matchAll(DEFAULT_IMPORT)) {
+    if (!/^[A-Z]/u.test(match[1]) || !isBackComponentName(match[1])) continue;
+    report("nav/back-control", offset + match.index, `${match[1]} is a back component. ${UP_OWNER}; remove it and declare the page's parent.`);
+  }
 }
 
 // The text of a local function's definition: function name(...) { ... }, or const name = ... to its end.
@@ -174,9 +193,13 @@ function visibleText(inner) {
   return inner.replace(/<[^>]*>/gu, " ").replace(/\{\{[\s\S]*?\}\}/gu, " ").replace(/\s+/gu, " ").trim();
 }
 
-function isBackTag(tag) {
-  const segments = tag.name.split("-");
-  return segments.includes("back") && !tag.name.startsWith("v-");
+// A back component, in either case (tags are read in kebab case): ContextBackButton, <page-back-link>, GoBack,
+// BackToList. Not Vuetify's own tags, a back office, or a back-to-top control, which scrolls the page.
+const BACK_COMPONENT = /(?:^|-)back(?:$|-(?:action|arrow|btn|button|chevron|control|icon|link|nav|navigation)(?:-|$)|-to-(?!top(?:-|$)))/u;
+
+function isBackComponentName(name) {
+  const tag = kebab(name);
+  return !tag.startsWith("v-") && BACK_COMPONENT.test(tag);
 }
 
 function looksLikeBack(tag) {
@@ -200,11 +223,12 @@ function checkBackControl(tag, report, script = "") {
     report("nav/back-control", tag.offset, "Breadcrumbs navigate back up the hierarchy. The shell's Up arrow does that; the app bar title says where the person is.");
     return;
   }
-  if (!navigatesFromControl(tag, script)) return;
-  if (isBackTag(tag)) {
+  // A back component navigates by itself, so its tag needs no link or handler to be one.
+  if (isBackComponentName(tag.name)) {
     report("nav/back-control", tag.offset, `<${tag.name}> is a back control. ${UP_OWNER}; remove it and declare the page's parent.`);
     return;
   }
+  if (!navigatesFromControl(tag, script)) return;
   const handler = tag.attributes.find((entry) => entry.event && BACK_IDENTIFIER.test(entry.value));
   if (handler) {
     report("nav/back-control", handler.offset, `${handler.raw}="${handler.value.trim()}" is a back handler. ${UP_OWNER}; remove the control and declare the page's parent.`);
@@ -223,37 +247,13 @@ function checkLinkAttribute(tag, entry, report) {
   }
 }
 
-// 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;
-}
-
 const stringValue = (text, key) => new RegExp(`\\b${key}\\s*:\\s*(["'\\u0060])([^"'\\u0060]*)\\1`, "u").exec(text)?.[2];
 
-// Main-navigation destinations, by surface: every main-navigation placement's suffixes. A link that names its
-// surface (props.surface) leads to that surface's page wherever it shows, so it is a destination of that surface only;
-// one that names none leads to the page on each surface it shows on. A placement is literal data; one whose suffixes or
-// surface are computed (built by a helper, spread or interpolated) can't be read, and is returned as unreadable.
+// Main-navigation destinations, by surface: every main-navigation placement's suffixes, and its address when it has
+// one (`to`). A link that names its surface (props.surface) leads to that surface's page wherever it shows, so it is a
+// destination of that surface only; one that names none leads to the page on each surface it shows on. A placement is
+// literal data; one whose suffixes, address or surface are computed (built by a helper, spread or interpolated) can't
+// be read, and is returned as unreadable.
 function readMainNavigation(sources) {
   const destinations = [];
   const unreadable = [];
@@ -272,6 +272,9 @@ function readMainNavigation(sources) {
         const suffix = stringValue(placement, key);
         if (suffix !== undefined) destinations.push({ suffix: normalisePath(suffix.split(/[?#]/u)[0]), surfaces });
       }
+      // A link with an address of its own (`to: "/account"`, a package's global route) leads to that path.
+      const to = stringValue(placement, "to");
+      if (to?.startsWith("/")) destinations.push({ to: normalisePath(to.split(/[?#]/u)[0]), surfaces });
     }
   }
   return { destinations, unreadable };
@@ -357,7 +360,7 @@ function readPage(file, source) {
     redirect: REDIRECT_KEY.test(meta),
     parent: declarations.find(({ text }) => PARENT_KEY.test(text)),
     surfaceRoot: SURFACE_KEY.test(meta.replace(PARENT_OBJECT, "")),
-    shell: false
+    shell: "none"
   };
 }
 
@@ -383,11 +386,66 @@ function createShellBarReader(appFiles, read, tag = SHELL_UP_TAG) {
   return drawsShellBar;
 }
 
+const SHELL_LAYOUT_SPECIFIER = /^(?:@\/components\/ShellLayout|@jskit-ai\/shell-web\/client\/components\/ShellLayout)(?:\.vue)?$/u;
+
+/**
+ * Where a layout renders its pages: "all" under the shell's top app bar (every <RouterView /> inside ShellLayout or
+ * an app component that draws the bar, or a bar drawn beside them: ShellUpButton, or such a component around no
+ * RouterView), "some" when a branch renders them without it (a shop device's sign-in in a v-if beside the
+ * ShellLayout), or "none".
+ * @param {string} file
+ * @param {string} source
+ * @param {(file: string) => Promise<boolean>} drawsShellBar
+ * @param {Set<string>} known The app's files.
+ * @param {RegExp} [barTag] The shell-web piece that marks a bar of the layout's own: Up, or, for the page title,
+ *   ShellPageTitle (with drawsShellBar then reading the title too).
+ */
+async function shellPlacement(file, source, drawsShellBar, known, barTag = SHELL_UP_TAG) {
+  const { template, scripts } = splitVue(source);
+  const text = blankHtmlComments(template?.text || "");
+  if (barTag.test(text)) return "all";
+  const shellTags = new Set();
+  for (const block of scripts) {
+    for (const [, name, specifier] of blankJsComments(block.text).matchAll(DEFAULT_IMPORT)) {
+      const imported = localComponent(file, specifier, known);
+      if (SHELL_LAYOUT_SPECIFIER.test(specifier) || (imported && await drawsShellBar(imported))) shellTags.add(kebab(name));
+    }
+  }
+  const open = [];
+  let inside = 0;
+  let outside = 0;
+  let barBeside = false;
+  for (const [, closing, rawName, , selfClosing] of text.matchAll(TEMPLATE_TAG)) {
+    const name = kebab(rawName);
+    if (closing) {
+      const index = open.findLastIndex((entry) => entry.name === name);
+      if (index < 0) continue;
+      barBeside ||= open.slice(index).some((entry) => entry.shell && !entry.view);
+      open.length = index;
+      continue;
+    }
+    const shell = shellTags.has(name);
+    if (name === "router-view") {
+      const around = open.filter((entry) => entry.shell);
+      for (const entry of around) entry.view = true;
+      if (around.length > 0) inside += 1;
+      else outside += 1;
+    }
+    if (selfClosing || VOID_TAGS.has(name)) barBeside ||= shell;
+    else open.push({ name, shell, view: false });
+  }
+  if (barBeside) return "all";
+  if (inside === 0) return "none";
+  return outside === 0 ? "all" : "some";
+}
+
 /**
  * The app's .vue files that render under the shell's page title, where an in-page h1 would be a second one: a file
- * that shows the title (ShellLayout's bar, or ShellPageTitle in a bar of its own), a page a layout showing it renders,
- * and a component such a file imports. A component no .vue file imports (routed or placed from JavaScript) counts
- * too, as where it renders can't be read; App.vue counts only when it shows the title itself.
+ * that shows the title (ShellLayout's bar, or ShellPageTitle in a bar of its own), a page a layout always renders
+ * under it, and a component such a file imports. A component no .vue file imports (routed or placed from JavaScript) counts
+ * too, as where it renders can't be read, unless JavaScript hands it to the shell to render outside every layout (the
+ * router's notFoundComponent or fallbackRoute, the app's rootComponent) or it is a package route's page, which the
+ * kernel adds at the top level: that one counts only as App.vue does, which counts only when it shows the title itself.
  * @param {{ root: string, appFiles: string[] }} options
  */
 async function readTitledFiles({ root, appFiles }) {
@@ -406,6 +464,18 @@ async function readTitledFiles({ root, appFiles }) {
       if (imported) importers.set(imported, [...(importers.get(imported) || []), file]);
     }
   }
+  // Whether each component JavaScript imports is handed to the shell only to render outside every layout.
+  const outsideLayouts = new Map();
+  for (const file of appFiles.filter((entry) => /\.(?:[cm]?[jt]s)$/u.test(entry))) {
+    const code = blankJsComments(await read(file));
+    for (const [, name, specifier] of code.matchAll(DEFAULT_IMPORT)) {
+      const imported = localComponent(file, specifier, known);
+      if (!imported) continue;
+      const outside = rendersOutsideLayouts(code, name);
+      outsideLayouts.set(imported, (outsideLayouts.get(imported) ?? true) && outside);
+    }
+  }
+  const packagePages = new Set((await readPackageRoutes(root, known)).map((route) => route.file));
   const verdicts = new Map();
   async function titled(file) {
     if (verdicts.has(file)) return verdicts.get(file);
@@ -416,13 +486,18 @@ async function readTitledFiles({ root, appFiles }) {
       const segments = pageKey(file).split("/");
       for (let length = segments.length - 1; length > 0 && !verdict; length -= 1) {
         const layout = `src/pages/${segments.slice(0, length).join("/")}.vue`;
+        // A layout that renders its pages without the title on one branch (a shop device's sign-in in a bare v-main
+        // beside the ShellLayout) leaves them unjudged, as which branch shows a page is decided at runtime.
         if (known.has(layout) && ROUTER_VIEW_TAG.test(splitVue(await read(layout)).template?.text || "")) {
-          verdict = await showsTitle(layout);
+          verdict = await shellPlacement(layout, await read(layout), showsTitle, known, SHELL_TITLE_TAG) === "all";
         }
       }
     } else if (!verdict && path.posix.basename(file) !== "App.vue") {
       const users = importers.get(file) || [];
       verdict = users.length === 0;
+      if (verdict && (outsideLayouts.get(file) === true || packagePages.has(file))) {
+        verdict = known.has("src/App.vue") && await showsTitle("src/App.vue");
+      }
       for (const user of users) {
         if (verdict) break;
         verdict = await titled(user);
@@ -436,12 +511,17 @@ async function readTitledFiles({ root, appFiles }) {
   return result;
 }
 
-// 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;
+// A component JavaScript gives the shell to render outside every layout: the router's notFoundComponent or
+// fallbackRoute component, or the app's rootComponent.
+function rendersOutsideLayouts(code, name) {
+  const escaped = name.replaceAll("$", "\\$");
+  const named = String.raw`(?<![\w$.])${escaped}(?![\w$])`;
+  const handed = new RegExp(String.raw`\b(?:notFoundComponent|rootComponent)\s*:\s*${named}|\bcreateFallbackNotFoundRoute\s*\(\s*${named}|\bfallbackRoute\s*:\s*\{[^{}]*\bcomponent\s*:\s*${named}`, "gu");
+  // Every use after the import (whose specifier may spell the name too) is a hand-over, or it may render anywhere.
+  const body = code.replace(new RegExp(String.raw`\bimport\s+${escaped}\s+from\s*["'][^"']+["']`, "gu"), "");
+  const uses = [...body.matchAll(new RegExp(named, "gu"))].length;
+  const handovers = [...body.matchAll(handed)].length;
+  return handovers > 0 && handovers === uses;
 }
 
 /**
@@ -461,8 +541,9 @@ async function checkPageParents({ root, appFiles, pageFiles, report }) {
   const pages = new Map();
   for (const file of appFiles.filter(isPageFile)) pages.set(pageKey(file), readPage(file, await read(file)));
   const drawsShellBar = createShellBarReader(appFiles, read);
+  const known = new Set(appFiles);
   for (const page of pages.values()) {
-    if (page.layout) page.shell = await drawsShellBar(page.file);
+    if (page.layout) page.shell = await shellPlacement(page.file, page.source, drawsShellBar, known);
   }
   const surfaces = readSurfaces(configSource, [...pages.values()].map(({ file }) => routeOf(file)));
   const scripts = appFiles.filter((file) => /\.(?:[cm]?[jt]s|vue)$/u.test(file));
@@ -472,8 +553,14 @@ async function checkPageParents({ root, appFiles, pageFiles, report }) {
     report({ rule: "nav/placement-data", file, ...lineIndex(source)(offset), message: `A main-navigation placement that isn't literal data: ${computed}. Declare each placement literally, with plain string suffixes and surface, so its destination can be read; until then no page is judged for nav/missing-parent.` });
   }
   const surfacePath = (file, surface) => normalisePath(routePattern(routeOf(file).slice(surface.pagesRoot.length)));
-  const isDestination = (relative, surface) => navigation.destinations.some(({ suffix, surfaces: owners }) =>
-    suffix === relative && (owners.length === 0 || owners.includes(surface.id) || owners.includes("*")));
+  const addressOf = (relative, surface) => normalisePath(routePattern(`${surface.pagesRoot}${relative}`));
+  const shownOn = (owners, surface) => owners.length === 0 || owners.includes(surface.id) || owners.includes("*");
+  // A destination by its suffix on the surface, or by its address (`to`).
+  const isDestination = (relative, surface) => navigation.destinations.some(({ suffix, to, surfaces: owners }) =>
+    to === undefined ? suffix === relative && shownOn(owners, surface) : to === addressOf(relative, surface));
+  // A global route's address is a destination when a link's `to` names it, or a suffix leads there on a surface.
+  const isAddress = (address) => navigation.destinations.some(({ suffix, to, surfaces: owners }) =>
+    to === undefined ? surfaces.some((surface) => shownOn(owners, surface) && addressOf(suffix, surface) === address) : to === address);
   // An App.vue that wraps every page in the shell's bar leaves no page outside it.
   const appShell = appFiles.includes("src/App.vue") && await drawsShellBar("src/App.vue");
   const judged = [];
@@ -481,6 +568,12 @@ async function checkPageParents({ root, appFiles, pageFiles, report }) {
     const page = pages.get(pageKey(file));
     const surface = surfaceOf(routeOf(file), surfaces);
     if (!surface || page.redirect) continue;
+    // The record that carries jskit.surface is the surface root, where Up stops, so a parent beside it is never read.
+    if (page.surfaceRoot && page.parent) {
+      const at = lineIndex(page.source)(page.parent.offset + PARENT_KEY.exec(page.parent.text).index);
+      const fix = page.layout ? "move jskit.parent to the page this layout renders" : "remove jskit.surface and keep jskit.parent";
+      report({ rule: "nav/surface-parent", file, ...at, message: `${path.posix.basename(file)} declares jskit.parent beside jskit.surface, so the shell never reads it and the page shows no Up: the record with the surface is the surface root, where Up stops. Declare the surface only on the surface's layout page (ShellLayout around <RouterView />) and the parent on the page it renders; here, ${fix}.` });
+    }
     // The layouts that render this page, nearest first: src/pages/home/settings.vue renders home/settings/*.
     const segments = pageKey(file).split("/");
     const layouts = segments.slice(1).map((_, index) => pages.get(segments.slice(0, segments.length - 1 - index).join("/")))
@@ -489,7 +582,7 @@ async function checkPageParents({ root, appFiles, pageFiles, report }) {
     const position = lineIndex(page.source);
     // Up lives in the shell's top app bar, so only pages a shell layout renders have one. A page that declares a
     // parent expects that bar, with its title, Up and page actions; under no shell layout it shows none of them.
-    if (!layouts.some((entry) => entry.shell)) {
+    if (!layouts.some((entry) => entry.shell !== "none")) {
       if (page.parent && !appShell && !await drawsShellBar(file)) {
         const at = position(page.parent.offset + PARENT_KEY.exec(page.parent.text).index);
         const layout = surface.pagesRoot ? `, src/pages/${surface.pagesRoot}.vue` : "";
@@ -512,14 +605,63 @@ async function checkPageParents({ root, appFiles, pageFiles, report }) {
     const inherited = chain.find((entry) => entry.parent);
     const topLevel = destination || relative === "/" || chain.some((entry) => isDestination(surfacePath(entry.file, surface), surface));
     judged.push({ file, route: relative, surface: surface.id, topLevel, parent: page.parent ? "own" : inherited ? "inherited" : null });
-    if (!topLevel && !page.parent && !inherited && navigation.unreadable.length === 0) {
+    // A layout that also renders its pages without the shell (a shop device's sign-in) leaves which of them show Up
+    // unreadable, so only a page that always renders under the bar needs a parent.
+    const alwaysInShell = layouts.some((entry) => entry.shell === "all");
+    if (!topLevel && !page.parent && !inherited && alwaysInShell && navigation.unreadable.length === 0) {
       const at = position(page.declarations[0]?.offset ?? 0);
       report({ rule: "nav/missing-parent", file, ...at, message: `Inner page ${relative} of ${surface.id} has no parent. Declare it once in the page's route meta (or its layout's, for tabs), so Up works after a direct entry.` });
     }
   }
+  for (const route of await readPackageRoutes(root, known)) {
+    if (!pageFiles.includes(route.file) && !pageFiles.includes(route.manifest)) continue;
+    const verdict = await judgePackageRoute(route, { surfaces, appShell, drawsShellBar, isDestination, isAddress, readable: navigation.unreadable.length === 0, report });
+    if (verdict) judged.push(verdict);
+  }
   return judged;
 }
 
+/**
+ * The page rules for a package's route, which the kernel adds at the top level: under the shell's bar only when its
+ * component (or App.vue) draws it, with the parent its package.json declares in meta.jskit.parent. Findings point at
+ * the route's entry in package.json.
+ */
+async function judgePackageRoute(route, { surfaces, appShell, drawsShellBar, isDestination, isAddress, readable, report }) {
+  const position = lineIndex(route.source);
+  const at = (offset) => ({ file: route.manifest, ...position(offset) });
+  const address = normalisePath(route.path);
+  const name = `${address} (route "${route.id}" of ${route.manifest})`;
+  // A surface route's path starts at its surface's base: /app/manage/:view is /manage/:view of app.
+  let surface = { id: "", pagesRoot: "" };
+  let relative = address;
+  if (route.scope === "surface") {
+    surface = surfaces.find(({ id }) => id === route.surface);
+    if (!surface) return null;
+    const base = normalisePath(routePattern(surface.pagesRoot));
+    if (base !== "/" && address !== base && !address.startsWith(`${base}/`)) return null;
+    relative = normalisePath(address.slice(base === "/" ? 0 : base.length));
+  }
+  const where = surface.id ? ` of ${surface.id}` : "";
+  if (route.surfaceRoot && route.parent) {
+    report({ rule: "nav/surface-parent", ...at(route.parentOffset), message: `${name} declares jskit.parent beside jskit.surface, so the shell never reads it and the page shows no Up: the record with the surface is the surface root, where Up stops. Remove meta.jskit.surface; the route's own "surface" chooses where it is served.` });
+  }
+  if (!appShell && !await drawsShellBar(route.file)) {
+    if (route.parent) {
+      report({ rule: "nav/missing-shell-layout", ...at(route.parentOffset), message: `${name} declares a parent, but its component, ${route.file}, doesn't draw the shell's top app bar, so its title, Up and page actions never show. A package's route renders at the top level, under no layout: render ShellLayout around the page.` });
+    }
+    return null;
+  }
+  const destination = route.scope === "surface" ? isDestination(relative, surface) : isAddress(address);
+  if (destination && route.parent) {
+    report({ rule: "nav/top-level-parent", ...at(route.parentOffset), message: `${name} is a main-navigation destination${where}, so it declares no parent: choosing it starts a fresh trail.` });
+  }
+  const topLevel = destination || relative === "/";
+  if (!topLevel && !route.parent && readable) {
+    report({ rule: "nav/missing-parent", ...at(route.offset), message: `Inner page ${name}${where} has no parent. Declare it in the route's meta, "meta": { "jskit": { "parent": ... } }, so Up works after a direct entry.` });
+  }
+  return { file: route.file, route: relative, surface: surface.id || "global", topLevel, parent: route.parent ? "own" : null };
+}
+
 // src/pages/home/suppliers.vue is home/suppliers and src/pages/home/suppliers/index.vue is home/suppliers/index.
 function pageKey(file) {
   return file.replace(/^src\/pages\//u, "").replace(/\.vue$/u, "");

package/scripts/package-routes.mjs

@@ -0,0 +1,93 @@
+// The pages an app's own packages give the router, for the navigation rules: each package.json route in
+// jskit.metadata.ui.routes with the component its client entry's routeComponents names.
+import { readdir, readFile } from "node:fs/promises";
+import path from "node:path";
+import { DEFAULT_IMPORT, balancedFrom, blankJsComments, enclosingObject, localComponent } from "./material3-source.mjs";
+
+const isRecord = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value);
+const ROUTE_COMPONENTS = /\brouteComponents\s*=\s*(?:Object\s*\.\s*freeze\s*\(\s*)?(?=\{)/u;
+// One routeComponents entry: `key: () => import("./page.vue")` or `"key": ImportedPage`.
+const ROUTE_COMPONENT = /(?<=[{,]\s*)(?:(["'])([^"']+)\1|([A-Za-z_$][\w$]*))\s*:\s*(?:\(\s*\)\s*=>\s*import\s*\(\s*(["'])([^"']+)\4\s*\)|([A-Za-z_$][\w$]*))(?=\s*[,}])/gu;
+
+// The file a package's "./client" export names, relative to the app: packages/shelves/src/client/index.js.
+function clientEntryOf(manifest, directory) {
+  const target = manifest?.exports?.["./client"];
+  const entry = typeof target === "string" ? target : target?.import || target?.default;
+  return typeof entry === "string" ? path.posix.join(directory, entry) : "";
+}
+
+// The app's .vue file of each routeComponents key in a client entry, from its literal map: an entry another module
+// builds, or one naming a file outside the app, has none.
+function readRouteComponents(entry, code, known) {
+  const components = new Map();
+  const start = ROUTE_COMPONENTS.exec(code);
+  const map = start ? balancedFrom(code, start.index + start[0].length)?.text || "" : "";
+  const imports = new Map([...code.matchAll(DEFAULT_IMPORT)].map(([, name, specifier]) => [name, specifier]));
+  for (const match of map.matchAll(ROUTE_COMPONENT)) {
+    const specifier = match[5] ?? imports.get(match[6]);
+    const file = specifier ? localComponent(entry, specifier, known) : null;
+    if (file) components.set(match[2] ?? match[3], file);
+  }
+  return components;
+}
+
+/**
+ * The pages an app's own packages give the router: each packages/<name>/package.json's jskit.metadata.ui.routes entry
+ * the kernel registers (not autoRegister: false), with the component its client entry's literal routeComponents map
+ * names for componentKey. The kernel adds each at the top level, so no layout renders it: it is under the shell's top
+ * app bar only when its component (or App.vue) draws the bar. Its parent and surface are its meta.jskit, as declared.
+ * @param {string} root
+ * @param {Set<string>} known The app's files; a package whose client entry or component is not among them is skipped.
+ */
+async function readPackageRoutes(root, known) {
+  let directories = [];
+  try {
+    directories = (await readdir(path.join(root, "packages"), { withFileTypes: true })).filter((entry) => entry.isDirectory());
+  } catch (error) {
+    if (error?.code !== "ENOENT") throw error;
+  }
+  const pages = [];
+  for (const directory of directories.map((entry) => `packages/${entry.name}`).sort()) {
+    const manifestFile = `${directory}/package.json`;
+    let manifestSource;
+    let manifest;
+    try {
+      manifestSource = await readFile(path.join(root, manifestFile), "utf8");
+      manifest = JSON.parse(manifestSource);
+    } catch (error) {
+      if (error?.code === "ENOENT" || error instanceof SyntaxError) continue;
+      throw error;
+    }
+    const routes = manifest?.jskit?.metadata?.ui?.routes;
+    const entry = clientEntryOf(manifest, directory);
+    if (!Array.isArray(routes) || !known.has(entry)) continue;
+    const components = readRouteComponents(entry, blankJsComments(await readFile(path.join(root, entry), "utf8")), known);
+    for (const route of routes) {
+      const file = isRecord(route) && route.autoRegister !== false ? components.get(String(route.componentKey || "").trim()) : null;
+      if (!file) continue;
+      const id = String(route.id || "").trim();
+      const jskit = isRecord(route.meta?.jskit) ? route.meta.jskit : {};
+      const parent = typeof jskit.parent === "string" ? jskit.parent.trim() : isRecord(jskit.parent) ? jskit.parent : "";
+      // Where package.json declares the route, and its parent, for findings.
+      const declared = new RegExp(String.raw`"id"\s*:\s*${JSON.stringify(id).replace(/[.*+?^${}()|[\]\\]/gu, "\\$&")}`, "u").exec(manifestSource);
+      const object = declared ? enclosingObject(manifestSource, declared.index) : null;
+      const parentKey = object ? /"parent"\s*:/u.exec(object.text) : null;
+      pages.push({
+        file,
+        manifest: manifestFile,
+        source: manifestSource,
+        id,
+        path: String(route.path || "").trim(),
+        scope: String(route.scope || "surface").trim().toLowerCase() === "global" ? "global" : "surface",
+        surface: String(route.surface || "").trim().toLowerCase(),
+        parent,
+        surfaceRoot: Boolean(jskit.surface),
+        offset: declared?.index ?? 0,
+        parentOffset: parentKey ? object.start + parentKey.index : declared?.index ?? 0
+      });
+    }
+  }
+  return pages;
+}
+
+export { readPackageRoutes };

package/scripts/test-budget.mjs

@@ -0,0 +1,19 @@
+import os from "node:os";
+import process from "node:process";
+
+// The machine's test budget: how many test files (node --test), Playwright workers or Vitest workers a run may use at
+// once. A test runner that hands out slots exports V64_TEST_CONCURRENCY for each run; anywhere else a run takes half
+// of the machine, so a test suite neither runs one file at a time nor overwhelms the machine (a 2-vCPU VPS stays at 1).
+const BUDGET_VARIABLE = "V64_TEST_CONCURRENCY";
+
+/**
+ * @param {{ env?: Record<string, string | undefined>, parallelism?: number }} [options]
+ * @returns {number} a whole number of at least 1
+ */
+function testConcurrency({ env = process.env, parallelism = os.availableParallelism() } = {}) {
+  const configured = String(env[BUDGET_VARIABLE] ?? "").trim();
+  if (/^[1-9]\d*$/u.test(configured)) return Number(configured);
+  return Math.max(1, Math.floor(parallelism / 2));
+}
+
+export { BUDGET_VARIABLE, testConcurrency };

package/scripts/test-command.mjs

@@ -0,0 +1,116 @@
+import { spawn } from "node:child_process";
+import { globSync, readFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import process from "node:process";
+import { toPosixPath } from "./files.mjs";
+import { BUDGET_VARIABLE, testConcurrency } from "./test-budget.mjs";
+
+// `jskit test [node options] [files or globs]`: node --test, running test files in parallel within the machine's test
+// budget (test-budget.mjs). Its arguments go to node --test unchanged. A file that truly must run alone says why on its
+// first line, `// jskit-test: alone - <reason>`, and runs after the others, one such file at a time.
+
+// node --test's own default (Node 26) when it is given no files.
+const DEFAULT_PATTERN = "**/{test,test/**/*,test-*,*[._-]test}.{js,mjs,cjs,ts,mts,cts}";
+const MARKER = /^\s*\/\/\s*jskit-test:(.*)$/u;
+const ALONE = /^\s*alone\s+-\s+(\S.*)$/u;
+
+function findTestFiles(patterns, cwd) {
+  const entries = globSync(patterns, { cwd, withFileTypes: true, exclude: (entry) => entry.name === "node_modules" });
+  const files = entries
+    .filter((entry) => entry.isFile() || entry.isSymbolicLink())
+    .map((entry) => toPosixPath(path.relative(cwd, path.join(entry.parentPath, entry.name))));
+  return [...new Set(files)].sort();
+}
+
+/**
+ * The files of a run that must run alone, from their first line. A marker that is malformed or not on the first line
+ * (after a shebang) is an error, so a file never runs in parallel because its marker was missed.
+ * @returns {{ alone: Array<{ file: string, reason: string }>, problems: string[] }}
+ */
+function readAloneFiles(files, cwd) {
+  const alone = [];
+  const problems = [];
+  for (const file of files) {
+    const lines = readFileSync(path.resolve(cwd, file), "utf8").split("\n");
+    const top = lines[0]?.startsWith("#!") ? 1 : 0;
+    lines.forEach((line, index) => {
+      const marker = MARKER.exec(line);
+      if (!marker) return;
+      const reason = ALONE.exec(marker[1])?.[1]?.trim();
+      if (index !== top) problems.push(`${file}:${index + 1}: a jskit-test marker belongs on the file's first line.`);
+      else if (!reason) problems.push(`${file}:${index + 1}: write it as \`// jskit-test: alone - <why this file cannot run beside others>\`.`);
+      else alone.push({ file, reason });
+    });
+  }
+  return { alone, problems };
+}
+
+/**
+ * The node --test runs for these arguments: one in parallel within the budget, then the files that must run alone.
+ * @param {string[]} args the arguments after `jskit test`
+ * @param {{ cwd?: string, concurrency?: number }} [options]
+ */
+function planTestRuns(args, { cwd = process.cwd(), concurrency = testConcurrency() } = {}) {
+  if (args.some((argument) => /^--test-concurrency(?:=|$)/u.test(argument))) {
+    throw new Error("jskit test takes the test concurrency from the machine's budget; remove --test-concurrency.");
+  }
+  const candidates = args.filter((argument) => !argument.startsWith("-"));
+  // An argument that matches no file is an option's value (--test-reporter spec) or a typo node reports itself.
+  const matched = new Map(candidates.map((candidate) => [candidate, findTestFiles([candidate], cwd)]));
+  const files = candidates.length > 0
+    ? [...new Set([...matched.values()].flat())].sort()
+    : findTestFiles([DEFAULT_PATTERN], cwd);
+  const { alone, problems } = readAloneFiles(files, cwd);
+  if (problems.length > 0) throw new Error(`jskit test:\n- ${problems.join("\n- ")}`);
+  const parallel = ["--test", `--test-concurrency=${concurrency}`];
+  if (alone.length < 1) return { concurrency, alone, runs: [[...parallel, ...args]] };
+
+  const options = args.filter((argument) => !(matched.get(argument)?.length > 0));
+  const aloneFiles = new Set(alone.map((entry) => entry.file));
+  const others = files.filter((file) => !aloneFiles.has(file));
+  return {
+    concurrency,
+    alone,
+    runs: [
+      ...(others.length > 0 ? [[...parallel, ...options, ...others]] : []),
+      ["--test", "--test-concurrency=1", ...options, ...aloneFiles]
+    ]
+  };
+}
+
+function runNode(args) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(process.execPath, args, { stdio: "inherit" });
+    const forward = (signal) => child.kill(signal);
+    process.on("SIGINT", forward);
+    process.on("SIGTERM", forward);
+    child.once("error", reject);
+    child.once("exit", (code, signal) => {
+      process.off("SIGINT", forward);
+      process.off("SIGTERM", forward);
+      resolve({ code: code ?? 128 + (os.constants.signals[signal] ?? 0), signal });
+    });
+  });
+}
+
+/**
+ * Runs `jskit test` and resolves to its exit code: the first failing run's, or 0.
+ * @param {string[]} args
+ */
+async function runTests(args) {
+  const plan = planTestRuns(args);
+  const source = process.env[BUDGET_VARIABLE] ? BUDGET_VARIABLE : "half of this machine";
+  process.stderr.write(`jskit test: ${plan.concurrency} test file(s) at a time (${source}).\n`);
+  for (const { file, reason } of plan.alone) process.stderr.write(`jskit test: ${file} runs alone: ${reason}\n`);
+  let exitCode = 0;
+  for (const run of plan.runs) {
+    const { code, signal } = await runNode(run);
+    if (exitCode === 0) exitCode = code;
+    // An interrupted run ends the whole command.
+    if (signal) break;
+  }
+  return exitCode;
+}
+
+export { planTestRuns, runTests };