@kirchdev/duxt 0.3.4 → 0.3.5-dev-main.44-5337cc1

package/app/utils/search-display.ts

@@ -0,0 +1,248 @@
+import { asText } from './duxt-text';
+
+/**
+ * How a search hit says where it came from.
+ *
+ * The search used to label a hit `[repo, version].join(' ') || prefix || '/'`,
+ * which is a URL segment doing a name's job: the site's own documentation sits
+ * at the root and therefore showed a bare `/`, and a source whose segment is an
+ * abbreviation showed the abbreviation. Neither tells a reader which project
+ * they are about to open.
+ *
+ * So provenance is resolved to a NAME here, once, off the same manifest the
+ * rest of the theme reads — and `sources[].name` lets a consumer state the one
+ * thing no rule can derive.
+ */
+
+/** Where one hit came from, as the dialog says it. */
+export interface DuxtSearchProvenance {
+  /** The source's display name — see `sourceDisplayNames`. */
+  name: string;
+  /** The generated artefact's own label, where the hit came out of one. */
+  artefact?: string;
+  /** The edition, where the site publishes more than one. */
+  version?: string;
+}
+
+/** One search result, and whether it opens a run of shared provenance. */
+export interface DuxtSearchRow<T> {
+  hit: T;
+  /**
+   * Drawn above this hit, once per run. Decorative: the same text reaches a
+   * screen reader through `provenance` on every row, so the visible caption is
+   * `aria-hidden` and never read twice.
+   */
+  caption?: string;
+  /** This hit's own provenance, whether or not it drew the caption. */
+  provenance?: string;
+}
+
+/** `Demo · Demo API · v3.x` — source, artefact, edition, in that order. */
+export const provenanceLabel = (source: DuxtSearchProvenance) =>
+  [source.name, source.artefact, source.version].filter(Boolean).join(' · ');
+
+/**
+ * Results, with the repeated source label lifted off them.
+ *
+ * A badge on every row spelled the same source name five times down a list of
+ * five hits from one repository — the noise this issue is about. A caption at
+ * the head of each RUN says it once.
+ *
+ * A run is CONTIGUOUS, which is the whole constraint. Gathering every hit of
+ * one source under a single heading would re-sort the list, and the ranking is
+ * the thing the merge across sources exists to produce — see `useDuxtSearch`.
+ * So provenance that comes back changes nothing about order: it simply opens a
+ * second run.
+ */
+export function searchRows<T extends { source?: DuxtSearchProvenance }>(
+  hits: T[]
+): DuxtSearchRow<T>[] {
+  let previous: string | undefined;
+
+  return hits.map((hit) => {
+    const provenance = hit.source ? provenanceLabel(hit.source) : undefined;
+    const caption =
+      provenance && provenance !== previous ? provenance : undefined;
+    previous = provenance;
+
+    return { hit, caption, provenance };
+  });
+}
+
+/** How much of a section's text a preview may show. */
+const EXCERPT_LENGTH = 160;
+
+/**
+ * A plain-text preview of the section a hit sits in.
+ *
+ * A title and a breadcrumb say where a result IS; they do not say whether it
+ * answers the question, and that is the judgement a reader makes before opening
+ * a page. So each hit carries a line or two of its own text.
+ *
+ * Whitespace is collapsed because Content's index stores a section as it was
+ * written — newlines, indentation and all — and an excerpt taken raw would
+ * spend half its budget on layout the reader cannot see.
+ *
+ * PLAIN TEXT, and it stays that way. What comes back is the section's
+ * characters, `<` and `&` included; the component renders it through
+ * interpolation, never `v-html`, so a document that happens to contain markup
+ * shows markup rather than running it.
+ */
+export function searchExcerpt(
+  content: string | undefined,
+  term: string,
+  max = EXCERPT_LENGTH
+): string {
+  const text = (content ?? '').replace(/\s+/g, ' ').trim();
+  if (!text) return '';
+  if (text.length <= max) return text;
+
+  // The window is anchored on the LITERAL term where the text carries it: a
+  // preview whose match is off the end is a preview of the wrong sentence. FTS
+  // and Fuse both match things a literal search does not, so this often finds
+  // nothing — and the opening of a section is a good second answer, because a
+  // section's first sentence is usually what it is about.
+  const found = term.trim()
+    ? text.toLowerCase().indexOf(term.trim().toLowerCase())
+    : -1;
+
+  if (found < 0) return `${cut(text, 0, max)}…`;
+
+  // A third of the window ahead of the match, so the reader sees what leads
+  // into it as well as what follows.
+  const lead = Math.floor(max / 3);
+  const start = Math.max(0, found - lead);
+  const end = Math.min(text.length, start + max);
+
+  return [
+    start > 0 ? '…' : '',
+    text.slice(start > 0 ? boundary(text, start) : 0, end).trim(),
+    end < text.length ? '…' : ''
+  ].join('');
+}
+
+/** Forward to the next word start, so a window never opens mid-word. */
+function boundary(text: string, index: number) {
+  const space = text.indexOf(' ', index);
+  return space < 0 || space > index + 20 ? index : space + 1;
+}
+
+/** Back to the last whole word that fits, so a cut never splits one. */
+function cut(text: string, start: number, max: number) {
+  const slice = text.slice(start, start + max);
+  const space = slice.lastIndexOf(' ');
+  return (space > max / 2 ? slice.slice(0, space) : slice).trim();
+}
+
+/** As much of a resolved source as naming it needs. */
+export interface DuxtSearchSourceInput {
+  collection: string;
+  /** The display name a consumer configured, already resolved for the locale. */
+  name?: DuxtText;
+  /** The source's own URL segment — its identity, where it has one. */
+  repo?: string;
+  /** `owner/name` of the repository behind it, where there is one. */
+  repository?: string;
+  /** Folder inside that repository holding the Markdown. */
+  path: string;
+}
+
+/**
+ * A slug as a reader would write it: `client-sdk` → `Client Sdk`.
+ *
+ * Deliberately not a title-caser — `of`, `and` and the rest are left capitalised
+ * rather than guessed at per language, because this runs over a URL segment and
+ * a wrong small word reads worse than a consistent one. A consumer who wants
+ * the real spelling writes `name`.
+ */
+export const humanizeSlug = (value: string) =>
+  value
+    .split(/[-_.\s]+/)
+    .filter(Boolean)
+    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+    .join(' ');
+
+/**
+ * The name each collection shows, by collection.
+ *
+ * The ladder, in order, and every rung is a fallback for the one before it:
+ *
+ *  1. `sources[].name` — display only, and the only rung a consumer controls.
+ *  2. The source's own SEGMENT, humanized. Usually this IS the repository's
+ *     name: `repoSlug` derives the segment from it unless the source claimed a
+ *     `slug`, and where a source did claim one, the claim is the deliberate
+ *     spelling and the better name.
+ *  3. The site's name — the answer for a source with no segment at all, which
+ *     is the site's own root documentation. Unset, `duxt.title` is already the
+ *     localized "Documentation" label, so that is the bottom rung and it needs
+ *     no second string to translate.
+ *
+ * The REPOSITORY deliberately names nothing. Several sources may be read out of
+ * one repository — this site's own demo tree and its documentation are — so a
+ * repository identifies a source only sometimes, and a rule that is right only
+ * sometimes attributes one section to another. It qualifies a collision below,
+ * where it has a second name beside it to be read against, and nothing else.
+ *
+ * A collection never falls through to its own identifier or to `/`: both are
+ * addresses, and this is the one place that must not show one.
+ *
+ * Two DIFFERENT sources landing on one name are then qualified — see
+ * `qualified`. Two editions of the SAME source landing on one name are the
+ * point of the exercise and left alone: a version and a translation are the
+ * same project, and the version caption already tells them apart.
+ */
+export function sourceDisplayNames(
+  sources: DuxtSearchSourceInput[],
+  siteName: string
+): Map<string, string> {
+  const named = sources.map((source) => ({
+    source,
+    // The source's identity, not the collection's: every version and every
+    // language of one source shares it, which is what keeps them one name.
+    identity: source.repo ?? '',
+    name:
+      asText(source.name) ||
+      (source.repo && humanizeSlug(source.repo)) ||
+      siteName
+  }));
+
+  const identities = new Map<string, Set<string>>();
+  for (const { name, identity } of named) {
+    const claimed = identities.get(name) ?? new Set<string>();
+    claimed.add(identity);
+    identities.set(name, claimed);
+  }
+
+  return new Map(
+    named.map(({ source, name }) => [
+      source.collection,
+      identities.get(name)!.size > 1 ? qualified(name, source, named) : name
+    ])
+  );
+}
+
+/**
+ * One colliding name, told apart.
+ *
+ * The repository first, because "Reference (acme/api)" answers the reader's
+ * actual question — which project is this. A monorepo publishing two sections
+ * out of one repository cannot be told apart that way, so the folder is the
+ * second rung: it is the only thing left that differs, and it is readable.
+ */
+function qualified(
+  name: string,
+  source: DuxtSearchSourceInput,
+  named: { source: DuxtSearchSourceInput; identity: string; name: string }[]
+) {
+  const colliding = named.filter((entry) => entry.name === name);
+  const repositories = new Set(
+    colliding.map((entry) => entry.source.repository ?? '')
+  );
+
+  const qualifier =
+    repositories.size > 1 && source.repository
+      ? source.repository
+      : source.path;
+
+  return qualifier ? `${name} (${qualifier})` : name;
+}

package/app/utils/section-scope.ts

@@ -50,15 +50,65 @@ function documentationFor(source: Area | undefined, sources: Area[]) {
   )[0];
 }
 
-/** The version-neutral root of a documentation area. */
+/**
+ * The version-neutral root of a documentation area.
+ *
+ * A tree published INSIDE another area's root belongs to that area: a provider
+ * reference at `/demo/terraform` is a part of `/demo` in the same way the
+ * generated reference beside it is, and treating it as an area of its own
+ * would empty the row on its pages and hide its entry on every other one. The
+ * root area `''` never adopts anything, or every source would be one area.
+ */
 function areaRoot(source: Area | undefined, sources: Area[]): string {
+  const own = treeRoot(source, sources);
+  if (!own) return own;
+
+  const enclosing = sources
+    .filter((other) => !other.generated)
+    .map((other) => treeRoot(other, sources))
+    .filter((root) => root && root !== own && isInside(own, root))
+    .sort((a, b) => a.length - b.length)[0];
+
+  return enclosing ?? own;
+}
+
+/**
+ * The prefix a source WITHOUT a slug has before its version segment.
+ *
+ * Such a source carries no identity to group its editions by, so they used to
+ * keep their own prefixes: `/v0.2.0` was an area apart from the root, and on a
+ * site with a second area every section was filtered off the page — the row
+ * vanished on every non-default edition of the documentation it belongs to.
+ * The version segment is the one thing the editions of one source add to the
+ * same base, so it is taken off again — but only where an edition without it
+ * actually exists, so a prefix that merely ends like a version stays its own.
+ */
+function unversioned(source: Area, sources: Area[]): string {
+  const segment = source.version ? `/${source.version}` : '';
+  if (!segment || !source.prefix.endsWith(segment)) return source.prefix;
+
+  const base = source.prefix.slice(0, -segment.length);
+
+  return sources.some(
+    (other) =>
+      !other.generated &&
+      !other.repo &&
+      other.prefix === base &&
+      other.version !== source.version
+  )
+    ? base
+    : source.prefix;
+}
+
+/** The root of the one documentation tree a source belongs to. */
+function treeRoot(source: Area | undefined, sources: Area[]): string {
   const documentation = documentationFor(source, sources);
   if (!documentation) return '';
 
   // A slug is the source identity and survives the version segment. All
   // versions of `/demo` are therefore one area, whose shallowest prefix is
-  // the default edition. Sources without an identity retain their own prefix.
-  if (!documentation.repo) return documentation.prefix;
+  // the default edition.
+  if (!documentation.repo) return unversioned(documentation, sources);
 
   return sources
     .filter((other) => !other.generated && other.repo === documentation.repo)
@@ -96,6 +146,17 @@ export function areaForPath(path: string, sources: Area[]): string {
   return areaRoot(sourceForPath(path, sources), sources);
 }
 
+/**
+ * Whether two sources are editions of one documentation tree: the same slug
+ * where they carry one, the same unversioned root where they do not. Two
+ * slug-less sources are NOT one tree merely for both lacking a slug.
+ */
+function sameTree(a: Area, b: Area, sources: Area[]): boolean {
+  if (a.repo || b.repo) return a.repo === b.repo;
+
+  return unversioned(a, sources) === unversioned(b, sources);
+}
+
 /**
  * The entries of one area, in the order the site declared them.
  *
@@ -134,7 +195,7 @@ export function sectionsForPath<T extends { to?: string }>(
     if (
       target &&
       !target.generated &&
-      target.repo === reader.repo &&
+      sameTree(target, reader, sources) &&
       target.version !== reader.version
     ) {
       return {

package/app/utils/stored-json.ts

@@ -0,0 +1,31 @@
+/**
+ * A JSON value kept in `localStorage`, read and written without ever throwing.
+ *
+ * Storage is the one browser API that fails for reasons the page cannot see: a
+ * private window, a blocked site, a full quota, or a value some other script
+ * wrote under the same key. Every reader here wants the same answer to all of
+ * those — "nothing stored" — and every writer the same shrug, because what is
+ * kept is a convenience and never worth an error the reader has to read.
+ *
+ * `unknown` on the way out, deliberately: the stored value crossed a boundary
+ * the type system cannot follow, so the caller checks its shape rather than
+ * trusting a cast.
+ */
+export function readStoredJson(key: string): unknown {
+  try {
+    const stored = window.localStorage.getItem(key);
+    return stored ? (JSON.parse(stored) as unknown) : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Whether the value was kept. A failure is not reported further than that. */
+export function writeStoredJson(key: string, value: unknown): boolean {
+  try {
+    window.localStorage.setItem(key, JSON.stringify(value));
+    return true;
+  } catch {
+    return false;
+  }
+}

package/app/utils/version-choices.ts

@@ -65,20 +65,13 @@ export function versionChoices(
   current: DuxtResolvedSource | undefined,
   configured: DuxtLink[] | undefined
 ): DuxtLink[] {
-  // A global generated section has no version of its own, but its reader still
-  // needs the documentation context of the source that owns it. Start from
-  // that source's default edition: its choices lead to the version overviews,
-  // never to non-existent versioned copies of the generated section.
-  const global = current?.generated?.versioning === 'global';
+  // A GLOBAL generated section has no version of its own and serves one URL,
+  // so every entry would move the reader off it. A per-version one — the API
+  // reference, the changelog — is scoped below like any other artefact, which
+  // is what keeps a reader in it when they change versions.
+  if (current?.generated?.versioning === 'global') return [];
 
-  if (global && current?.generated?.type !== 'changelog') return [];
-
-  const context = global
-    ? sources.find(
-        (source) =>
-          source.repo === current.repo && source.isDefault && !source.generated
-      )
-    : current;
+  const context = current;
 
   if (!context) return [];
 

package/app/utils/version-paths.ts

@@ -57,6 +57,27 @@ export function versionPath(
   return `${target}${rest}` || '/';
 }
 
+/**
+ * Where the switcher sends a reader who picks another version.
+ *
+ * The same page in that version, as `versionPath` answers — unless that page is
+ * one the target never published. A release page is the case this exists for:
+ * every version publishes its own changelog, and an older one has no page for
+ * a release cut after it. `missing` holds the target paths known not to exist,
+ * and such a pick lands at the target's own root — the changelog overview of
+ * that version — rather than at a 404.
+ */
+export function versionSwitchPath(
+  path: string,
+  from: string | undefined,
+  to: string,
+  missing: ReadonlySet<string>
+): string {
+  const target = versionPath(path, from, to);
+
+  return missing.has(target) ? to || '/' : target;
+}
+
 /**
  * Re-exported so the app can auto-import it.
  *

package/bin/duxt-cache-key.mjs

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+import { createJiti } from 'jiti';
+
+/**
+ * The cache key for a site's remote sources, as a command.
+ *
+ * PLAIN JAVASCRIPT for the reason `duxt.mjs` states: Node refuses to strip
+ * types from a file under `node_modules`, so a TypeScript entry point dies on
+ * the first real install with `ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING`.
+ *
+ * Everything it decides is in `sources-cache.ts`, where it is typed and tested.
+ * This file exists to have no logic in it.
+ *
+ * Written for a CI step that caches `.data/content` between runs:
+ *
+ *   duxt-cache-key --github >> "$GITHUB_OUTPUT"
+ *
+ * and readable without one, which is what makes "why did my cache miss" a
+ * question with an answer.
+ */
+// `node:sqlite` is not reached on this path, but the config is loaded through
+// the same modules the report loads it through — and an experimental-feature
+// warning in the middle of a `$GITHUB_OUTPUT` capture is a corrupt step output,
+// not merely noise.
+process.removeAllListeners('warning');
+
+const guide = 'https://duxt.app/guides/cache-build-work';
+const argv = process.argv.slice(2);
+
+if (argv.includes('--help') || argv.includes('-h')) {
+  console.log(`Usage: duxt-cache-key [--root <site>] [--github]
+
+Print the cache key and paths for remote Content sources.
+Documentation: ${guide}`);
+  process.exit(0);
+}
+
+const jiti = createJiti(import.meta.url, { interopDefault: true });
+
+const { duxtSourcesCache, runDuxtSourcesCacheCli } =
+  await jiti.import('../sources-cache');
+
+try {
+  const rootIndex = argv.indexOf('--root');
+  const rootDir = rootIndex === -1 ? undefined : argv[rootIndex + 1];
+
+  const { output, exitCode } = runDuxtSourcesCacheCli(
+    argv,
+    duxtSourcesCache({ rootDir })
+  );
+
+  console.log(output);
+  process.exitCode = exitCode;
+} catch (error) {
+  // The message, not the stack: everything thrown on this path is a statement
+  // about the SITE's own source list, written to be read by whoever wrote it.
+  console.error(
+    `${error instanceof Error ? error.message : String(error)}\nDocumentation: ${guide}`
+  );
+  process.exitCode = 1;
+}

package/bin/duxt-og-cache.mjs

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+import { createJiti } from 'jiti';
+
+/**
+ * The rendered-OG-image cache, as a command.
+ *
+ * PLAIN JAVASCRIPT for the reason `duxt.mjs` states: Node refuses to strip
+ * types from a file under `node_modules`, so a TypeScript entry point dies on
+ * the first real install with `ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING`.
+ *
+ * Everything it decides is in `og-image-cache.ts`, where it is typed and
+ * tested. This file exists to have no logic in it.
+ *
+ * Written for a deploy that caches the rendered images between runs — once
+ * before the build, to say what to restore and under which key:
+ *
+ *   duxt-og-cache --root www --run "$GITHUB_SHA" --github >> "$GITHUB_OUTPUT"
+ *
+ * and once after it, to say what that was worth:
+ *
+ *   duxt-og-cache --root www --report --since "$STARTED" --log build.log
+ *
+ * Both are readable without a workflow, which is what makes "why did my cache
+ * miss" and "did it help" questions with answers.
+ */
+// An experimental-feature warning in the middle of a `$GITHUB_OUTPUT` capture
+// is a corrupt step output, not merely noise.
+process.removeAllListeners('warning');
+
+const guide = 'https://duxt.app/guides/cache-build-work';
+const argv = process.argv.slice(2);
+
+if (argv.includes('--help') || argv.includes('-h')) {
+  console.log(`Usage: duxt-og-cache [--root <site>] [--run <id>] [--github]
+       duxt-og-cache --report [--root <site>] [--since <ms>] [--log <file>]
+
+Print a rendered-OG cache key or report reuse after a build.
+Documentation: ${guide}`);
+  process.exit(0);
+}
+
+const jiti = createJiti(import.meta.url, { interopDefault: true });
+
+const { duxtOgImageCacheCommand } = await jiti.import('../og-image-cache');
+
+try {
+  const { output, exitCode } = duxtOgImageCacheCommand(argv);
+
+  console.log(output);
+  process.exitCode = exitCode;
+} catch (error) {
+  // The message, not the stack: everything thrown on this path is a statement
+  // about the SITE, written to be read by whoever built it.
+  console.error(
+    `${error instanceof Error ? error.message : String(error)}\nDocumentation: ${guide}`
+  );
+  process.exitCode = 1;
+}

package/bin/{duxt-report.mjs → duxt.mjs}

@@ -2,7 +2,7 @@
 import { createJiti } from 'jiti';
 
 /**
- * The report, as a command.
+ * The `duxt` command.
  *
  * PLAIN JAVASCRIPT, and it has to be: Node refuses to strip types from a file
  * under `node_modules`, so a TypeScript entry point runs in this repository —
@@ -14,8 +14,9 @@ import { createJiti } from 'jiti';
  * `duxt-app-config.ts` already reads a site's config, so the rest of the layer
  * needs no build step to be reachable from here.
  *
- * Everything the command decides is in `report.ts`, where it is typed and
- * tested. This file exists to have no logic in it.
+ * Everything the command decides is in `cli.ts`, where it is typed and tested.
+ * This file exists to have no logic in it: it hands over the arguments, prints
+ * the two streams and sets the exit code.
  */
 // Content's cache is read through `node:sqlite`, which announces itself as
 // experimental on every run. True, and not this command's news to break to
@@ -25,15 +26,20 @@ process.removeAllListeners('warning');
 
 const jiti = createJiti(import.meta.url, { interopDefault: true });
 
-const { duxtReport, runDuxtReportCli } = await jiti.import('../report');
+const { runDuxtCli } = await jiti.import('../cli');
+const { duxtReport } = await jiti.import('../report');
 
 try {
-  const { output, exitCode } = runDuxtReportCli(
+  // `duxtReport` is passed rather than called: usage has to answer on a site
+  // that has never been built, so nothing may read a config or a parse cache
+  // until the arguments have been read and found to ask for a report.
+  const { stdout, stderr, exitCode } = await runDuxtCli(
     process.argv.slice(2),
-    duxtReport()
+    duxtReport
   );
 
-  console.log(output);
+  if (stdout) console.log(stdout);
+  if (stderr) console.error(stderr);
   process.exitCode = exitCode;
 } catch (error) {
   // The message, not the stack. Everything thrown on this path is a statement