@kirchdev/duxt 0.1.0

package/app/utils/section-scope.ts

@@ -0,0 +1,97 @@
+/**
+ * Which section-row entries belong to the part of the site the reader is in.
+ *
+ * `duxt.sections` is one flat list, and on a site with one source that is the
+ * whole truth: every entry is a top-level part of the documentation. A site
+ * with a SECOND source has two sets of top-level parts, and rendering the list
+ * whole showed both everywhere — the demo API's own entries in the row above a
+ * getting-started page, and the documentation's six above the demo API.
+ *
+ * So an entry belongs to the source whose prefix it lies under, and the row
+ * shows the entries of the source the reader is in. A site that declares one
+ * source has one area, every entry is inside it, and nothing changes.
+ *
+ * Pure, and beside the resolver's other prefix arithmetic for the same reason
+ * that lives there: prefix work done inline in a component can only be checked
+ * by clicking.
+ */
+import { isInside, sourceForPath } from './version-paths';
+
+/** The minimum a source has to carry to place a path or an entry. */
+interface Area {
+  prefix: string;
+  generated?: unknown;
+}
+
+/**
+ * The AREAS a site has — one per documentation tree, never per generated
+ * section.
+ *
+ * A reference at `/demo/api` is not a part of the site beside `/demo`; it is
+ * something published under it, and its own entry is what the row offers. Were
+ * its prefix an area of its own, an operation page would look like a third part
+ * of the site and the row would empty out on it.
+ */
+const areas = (sources: Area[]): string[] => [
+  ...new Set(sources.filter((source) => !source.generated).map((s) => s.prefix))
+];
+
+/**
+ * The area a path is in — the longest documentation prefix it sits under.
+ *
+ * `''` for a site whose sources are all unprefixed, which is every site that
+ * never asked for any of this.
+ */
+export function areaForPath(path: string, sources: Area[]): string {
+  return (
+    sourceForPath(
+      path,
+      areas(sources).map((prefix) => ({ prefix }))
+    )?.prefix ?? ''
+  );
+}
+
+/**
+ * The entries of one area, in the order the site declared them.
+ *
+ * An entry with no `to` cannot be placed and is kept in every area: it is a
+ * link the consumer wrote for a reason the layer cannot read, and dropping it
+ * would make it disappear from a site that gained a second source.
+ */
+export function sectionsForPath<T extends { to?: string }>(
+  sections: T[],
+  sources: Area[],
+  path: string
+): T[] {
+  const area = areaForPath(path, sources);
+  const all = areas(sources);
+
+  // Only when the site HAS two areas: with one, every entry is in it, and the
+  // filter is a walk over the list for an answer that cannot change.
+  if (all.length < 2) return sections;
+
+  return sections.filter(
+    (section) => !section.to || areaForPath(section.to, sources) === area
+  );
+}
+
+/**
+ * WHICH ONE of an area's entries is the one being read.
+ *
+ * A row of siblings answers this by itself — `/guides` and `/reference` cannot
+ * both prefix a path. An area whose parts nest can: `/demo/api` is inside
+ * `/demo`, so marking every entry that prefixes the path lit two chips at once
+ * and told the reader they were in both places.
+ *
+ * The longest match wins, which is the rule `sourceForPath` and `useDuxtSection`
+ * already follow — the deepest thing that claims the page is the thing the page
+ * is in.
+ */
+export function currentSection<T extends { to?: string }>(
+  sections: T[],
+  path: string
+): T | undefined {
+  return sections
+    .filter((section) => section.to && isInside(path, section.to))
+    .sort((a, b) => (b.to?.length ?? 0) - (a.to?.length ?? 0))[0];
+}

package/app/utils/sheet-navigation.ts

@@ -0,0 +1,100 @@
+/**
+ * The mobile sheet's navigation, with the sections hung where they belong.
+ *
+ * The desktop header shows two rows: the navbar links up top and the sections
+ * below. The sheet has no rows, and listing the two as sibling blocks made the
+ * documentation look like a peer of its own parts — "Docs" in one list and
+ * "Guides", "ADR", "API" in another, with nothing saying the second is what the
+ * first opens.
+ *
+ * It already is, everywhere else. A navbar entry with no `to` means "the
+ * documentation" (see `DuxtHeader.linkTarget`), and `entryActive` lights it
+ * wherever ANY section is. This gives that entry the children it has always
+ * implied, so the sheet can render one tree instead of two lists.
+ *
+ * Pure and here rather than inline in the component, because the interesting
+ * part is what happens when there is nothing to hang them on — and a section
+ * that silently reaches no list at all is unreachable on a phone.
+ */
+import { areaForPath } from './section-scope';
+
+/** The navbar with the sections adopted, plus whatever nobody adopted. */
+export interface DuxtSheetNavigation {
+  entries: DuxtLink[];
+  /**
+   * Sections left over.
+   *
+   * Empty on the ordinary site, where an entry took them. A consumer who
+   * replaces `navigation` wholesale — `mergeDuxtConfig` REPLACES an array — may
+   * leave no entry that qualifies, and the sheet then renders these as their own
+   * block. Dropping them instead would take the whole documentation off the
+   * phone.
+   */
+  sections: DuxtSection[];
+}
+
+/**
+ * Which entry may adopt the sections: the first with neither a `to` nor
+ * children of its own.
+ *
+ * Both halves matter. An entry WITH a `to` names one page — a consumer wrote a
+ * destination and meant it, and appending eight children under it would
+ * repurpose their link. An entry that already has children carries a menu the
+ * consumer authored, and the sections are not more of it.
+ */
+function adopts(entry: DuxtLink) {
+  return !entry.to && !entry.children?.length;
+}
+
+/**
+ * And which entry adopts ANOTHER AREA's sections: the one pointing at that
+ * area's own root.
+ *
+ * The desktop row scopes itself to the area the reader is in — see
+ * `sectionsForPath` — and the sheet has no rows to scope. So a site with a
+ * second source hangs that source's parts under the navbar entry that opens it,
+ * which is the same relationship the to-less entry has with the documentation,
+ * stated with a `to` because this one has somewhere to point.
+ */
+const adoptsArea = (entry: DuxtLink, area: string) =>
+  Boolean(area) && entry.to === area && !entry.children?.length;
+
+export function buildSheetNavigation(
+  navigation: DuxtLink[] | undefined,
+  sections: DuxtSection[] | undefined,
+  sources: { prefix: string; generated?: unknown }[] = []
+): DuxtSheetNavigation {
+  const entries = navigation ?? [];
+  const list = sections ?? [];
+
+  if (!list.length) return { entries, sections: [] };
+
+  // One bucket per area, in the order the site declared the sections.
+  const byArea = new Map<string, DuxtSection[]>();
+  for (const section of list) {
+    const area = section.to ? areaForPath(section.to, sources) : '';
+    byArea.set(area, [...(byArea.get(area) ?? []), section]);
+  }
+
+  const adopted = entries.map((entry) => ({
+    entry,
+    taken: [] as DuxtSection[]
+  }));
+  const orphans: DuxtSection[] = [];
+
+  for (const [area, group] of byArea) {
+    const host = adopted.find(({ entry }) =>
+      area ? adoptsArea(entry, area) : adopts(entry)
+    );
+
+    if (host) host.taken = group;
+    else orphans.push(...group);
+  }
+
+  return {
+    entries: adopted.map(({ entry, taken }) =>
+      taken.length ? { ...entry, children: taken } : entry
+    ),
+    sections: orphans
+  };
+}

package/app/utils/source-file.ts

@@ -0,0 +1,84 @@
+/**
+ * From a page back to the file it was written in.
+ *
+ * "Edit this page" is the visible half; the same two functions answer "which
+ * file is this" for anything else that needs it. Pure, because every part of
+ * this is string arithmetic over a scheme with three moving pieces — the URL
+ * prefix, the numbered folder names and the source's own docs folder — and the
+ * only way that stays right is a test rather than a click.
+ */
+
+/**
+ * The file's path inside its repository.
+ *
+ * `stem` is Content's own: the file path with the extension gone and the URL
+ * prefix in front, and — unlike `path` — with the numbered folder names still
+ * on it. `1.guides/2.add-a-body` renders at `/guides/add-a-body`, so the URL
+ * cannot be turned back into a file name; the stem can.
+ */
+export function sourceFilePath(
+  stem: string,
+  prefix: string,
+  folder: string
+): string {
+  const lead = prefix.replace(/^\//, '');
+  const relative =
+    lead && stem.startsWith(`${lead}/`) ? stem.slice(lead.length + 1) : stem;
+
+  return [folder.replace(/\/+$/, ''), `${relative}.md`]
+    .filter(Boolean)
+    .join('/');
+}
+
+/**
+ * The link back to a file: an edit form where one is possible, a view where it
+ * is not.
+ *
+ * A TAG CANNOT BE EDITED. GitHub's web editor commits to a branch, so
+ * `/edit/v0.8.0/…` is a 404 for anyone signed in — and a version served from a
+ * tag is exactly the case this layer creates. Sending that reader to the
+ * default branch instead would be worse than the 404: they would be editing
+ * today's documentation while believing they were fixing the version they were
+ * reading.
+ *
+ * So a tag gets the source, not a form. The caller draws the label the kind
+ * asks for.
+ *
+ * GitHub and GitLab spell both forms differently and every other host is left
+ * alone — a wrong link is worse than none, so no button is drawn at all.
+ */
+export interface SourceLink {
+  url: string;
+  /** `edit` opens a form; `view` opens the file as it stands. */
+  kind: 'edit' | 'view';
+}
+
+export function sourceLink(
+  repositoryUrl: string | undefined,
+  ref: string | undefined,
+  refKind: 'branch' | 'tag' | undefined,
+  file: string
+): SourceLink | undefined {
+  if (!repositoryUrl) return undefined;
+
+  const base = repositoryUrl.replace(/\.git$/, '').replace(/\/+$/, '');
+
+  // Without a ref there is nothing to open a form against either: `HEAD` is a
+  // symbolic name the editor does not accept, though it reads fine.
+  const editable = refKind !== 'tag' && Boolean(ref);
+  const at = ref || 'HEAD';
+  const kind = editable ? 'edit' : 'view';
+
+  if (base.includes('gitlab')) {
+    return {
+      url: `${base}/-/${editable ? 'edit' : 'blob'}/${at}/${file}`,
+      kind
+    };
+  }
+
+  if (base.includes('github')) {
+    return { url: `${base}/${editable ? 'edit' : 'blob'}/${at}/${file}`, kind };
+  }
+
+  return undefined;
+}

package/app/utils/version-choices.ts

@@ -0,0 +1,68 @@
+/**
+ * Which versions the switcher may offer.
+ *
+ * Lifted out of `DuxtVersion` because two components need the answer and only
+ * one of them draws the control: the mobile sheet renders a full-width select
+ * where there is something to choose and a plain badge beside the brand where
+ * there is not, and it has to know which before it decides where the version
+ * goes at all.
+ *
+ * Pure, and beside the resolver's other path arithmetic for the same reason the
+ * rest of it is: every version bug this layer has had came from prefix work
+ * done inline in a component, where it could only be checked by clicking.
+ */
+
+/**
+ * Are these two collections versions of the SAME thing?
+ *
+ * A documentation tree and an API reference are both published per version, and
+ * neither is a version of the other — so a switcher that compared only the
+ * repository offered `v2 → /` and `v2 → /api` side by side, twice each label,
+ * and a canonical URL on a reference page pointed at the documentation's root.
+ *
+ * Compared by DECLARATION, which is the identity `resolveGeneratedSections`
+ * records for exactly this question. Two documentation trees answer `undefined`
+ * on both sides and are the same artefact, which is what keeps a site without a
+ * single generated section reading exactly as it did.
+ */
+export const sameArtefact = (
+  a: DuxtResolvedSource | undefined,
+  b: DuxtResolvedSource | undefined
+) => a?.generated?.declaration === b?.generated?.declaration;
+
+export function versionChoices(
+  sources: DuxtResolvedSource[],
+  current: DuxtResolvedSource | undefined,
+  configured: DuxtLink[] | undefined
+): DuxtLink[] {
+  // A version-neutral generated section suppresses the control entirely, and
+  // that is the point of the policy rather than a tidy-up: a changelog is one
+  // global history, so every entry the switcher could offer would move the
+  // reader to a URL that section does not serve.
+  if (current?.generated?.versioning === 'global') return [];
+
+  // `versions` in the config still wins where a label needs to read differently
+  // from the URL segment.
+  if (configured?.length) return configured;
+
+  return sources
+    .filter(
+      (source) =>
+        source.version &&
+        source.repo === current?.repo &&
+        sameArtefact(source, current)
+    )
+    .map((source) => ({
+      label: source.version!,
+      to: source.prefix || '/',
+      // The lifecycle, not just "is this the default": a list where three
+      // entries look alike says nothing about which of them is still safe to
+      // read. `current` needs no word — it is what the reader assumes.
+      description:
+        source.status && source.status !== 'current'
+          ? `duxt.version.status.${source.status}`
+          : source.isDefault
+            ? 'default'
+            : undefined
+    }));
+}

package/app/utils/version-paths.ts

@@ -0,0 +1,65 @@
+/**
+ * Which source serves a path, and how to move a path between versions.
+ *
+ * Pure functions, deliberately: every version bug this layer has had came from
+ * prefix arithmetic done inline in a component, where it could only be checked
+ * by clicking. `/workflows/v0.7.0` starts with `/workflows` as well, so taking
+ * the *first* matching prefix said "main" while reading the tag — and swapping
+ * versions then appended instead of replacing, turning /workflows/v0.7.0 into
+ * /workflows/v0.7.0/v0.7.0 on every click.
+ */
+
+/** The source whose prefix the path is inside. Longest prefix wins. */
+export function sourceForPath<T extends { prefix: string }>(
+  path: string,
+  sources: T[]
+): T | undefined {
+  return (
+    [...sources]
+      .sort((a, b) => b.prefix.length - a.prefix.length)
+      .find((source) => !source.prefix || isInside(path, source.prefix)) ??
+    sources.find((source) => !source.prefix)
+  );
+}
+
+/**
+ * Is `path` inside `prefix`?
+ *
+ * Segment-aware: `/workflows-old` is not inside `/workflows`, though it starts
+ * with it.
+ */
+export function isInside(path: string, prefix: string): boolean {
+  if (!prefix) return true;
+
+  return path === prefix || path.startsWith(`${prefix}/`);
+}
+
+/**
+ * The same page in another version.
+ *
+ * Strips the current version's prefix and applies the target's, so a page keeps
+ * its place instead of dropping the reader at the version's root.
+ */
+export function versionPath(
+  path: string,
+  from: string | undefined,
+  to: string
+): string {
+  const rest =
+    from && from !== '/' && isInside(path, from)
+      ? path.slice(from.length)
+      : path;
+  const target = to === '/' ? '' : to;
+
+  return `${target}${rest}` || '/';
+}
+
+/**
+ * Re-exported so the app can auto-import it.
+ *
+ * The function itself lives beside the resolver, because that is where the
+ * semver comparison it uses lives and where its tests are. `app/utils` is what
+ * Nuxt scans for auto-imports, and `sources-resolve.ts` is plain logic with no
+ * Node imports — the same property that lets `app.config.ts` read it.
+ */
+export { versionRelation } from '../../sources-resolve';

package/bin/duxt-report.mjs

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+import { createJiti } from 'jiti';
+
+/**
+ * The report, as a 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 —
+ * where the package is a symlink — and dies on the first real install with
+ * `ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING`. That was measured against a
+ * packed tarball, not assumed.
+ *
+ * jiti is what loads the TypeScript behind it, the same way
+ * `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.
+ */
+// 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
+// anybody: the report is a thing you pipe into a file or paste into a chat, and
+// a warning about somebody else's implementation detail is noise in both.
+process.removeAllListeners('warning');
+
+const jiti = createJiti(import.meta.url, { interopDefault: true });
+
+const { duxtReport, runDuxtReportCli } = await jiti.import('../report');
+
+try {
+  const { output, exitCode } = runDuxtReportCli(
+    process.argv.slice(2),
+    duxtReport()
+  );
+
+  console.log(output);
+  process.exitCode = exitCode;
+} catch (error) {
+  // The message, not the stack. Everything thrown on this path is a statement
+  // about the SITE — an artefact that is not where the config says, a section
+  // option nobody knows — written to be read by whoever wrote that config, and
+  // a trace through jiti's loader helps none of them.
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exitCode = 1;
+}

package/components.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "https://shadcn-vue.com/schema.json",
+  "style": "new-york",
+  "typescript": true,
+  "tailwind": {
+    "config": "",
+    "css": "app/assets/css/duxt.css",
+    "baseColor": "neutral",
+    "cssVariables": true
+  },
+  "aliases": {
+    "components": "@duxt/components",
+    "composables": "@duxt/composables",
+    "utils": "@duxt/lib/utils",
+    "ui": "@duxt/components/ui",
+    "lib": "@duxt/lib"
+  },
+  "iconLibrary": "lucide"
+}

package/content-cache.ts

@@ -0,0 +1,193 @@
+import { existsSync, mkdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+import type { Nuxt } from '@nuxt/schema';
+
+/**
+ * Every parsed page, out of Content's own cache.
+ *
+ * The one place the build can see what Content actually produced. NOT the
+ * `content:file:afterParse` hook, which was the obvious choice and is the wrong
+ * one: Content skips the parse for every file whose checksum is unchanged, so
+ * on the second build that hook fires for nothing and a validator built on it
+ * reports an empty site. The cache holds the parsed document either way, remote
+ * sources included — Content downloads a repository into `.data/content/` and
+ * nothing else on disk describes what came back.
+ *
+ * Returns undefined rather than an empty list when there is no cache to read.
+ * A `nuxt prepare` run parses nothing, and "no pages" there is not a finding.
+ */
+export interface CachedPage {
+  collection: string;
+  path: string;
+  file: string;
+  content: Record<string, unknown>;
+}
+
+/**
+ * Where Content keeps its parse cache.
+ *
+ * Read from the runtime config where Content has already put it there, and
+ * from Content's own default where it has not — which is the case for anything
+ * running before Content's setup, `enableWriteAheadLog` included.
+ */
+function cacheFile(nuxt: Nuxt): string {
+  const configured = (
+    nuxt.options.runtimeConfig as {
+      content?: { localDatabase?: { filename?: string } };
+    }
+  ).content?.localDatabase?.filename;
+
+  return configured && existsSync(configured)
+    ? configured
+    : join(nuxt.options.rootDir, '.data/content/contents.sqlite');
+}
+
+export function readContentCache(
+  nuxt: Nuxt,
+  collections: Iterable<string>
+): CachedPage[] | undefined {
+  return readContentCacheAt(cacheFile(nuxt), collections);
+}
+
+/** Content's default location for that cache, for a reader with no Nuxt. */
+export const contentCacheFile = (rootDir: string) =>
+  join(rootDir, '.data/content/contents.sqlite');
+
+/**
+ * The same read, addressed by FILE rather than by a Nuxt instance.
+ *
+ * Split out for `report.ts`, which runs as a command beside the build rather
+ * than inside it and has no `nuxt` to be handed. Everything below was already
+ * a function of the path alone; only the path was not reachable.
+ */
+export function readContentCacheAt(
+  file: string,
+  collections: Iterable<string>
+): CachedPage[] | undefined {
+  if (!existsSync(file)) return undefined;
+
+  const names = new Set(collections);
+  const pages: CachedPage[] = [];
+
+  /**
+   * WAIT for Content rather than failing next to it.
+   *
+   * SQLite's default journal mode locks the whole FILE while a writer holds it,
+   * so a reader gets SQLITE_BUSY immediately — `readOnly` does not help, it is
+   * the writer that excludes us. Content writes its parse cache from a
+   * `Promise.all` over the collections, and the build's own hooks read that
+   * cache; with a handful of files the write is over before anyone reads, and
+   * at six hundred it is not. The result was `database is locked` from
+   * whichever module read first, on a site whose only sin was having enough
+   * pages.
+   *
+   * A busy timeout turns the race into a wait: the reader retries internally
+   * until the writer commits. Fifteen seconds is far longer than a parse pass
+   * needs and still fails loudly if something genuinely holds the file — a
+   * stray dev server, say.
+   */
+  const database = new DatabaseSync(file, {
+    readOnly: true,
+    timeout: 15_000
+  });
+
+  try {
+    const rows = database
+      .prepare('SELECT id, value FROM _development_cache')
+      .all() as { id: string; value: string }[];
+
+    for (const row of rows) {
+      const collection = row.id.split('/')[0] ?? '';
+      // The cache carries a version marker and, after a config change, rows of
+      // collections that no longer exist.
+      if (!names.has(collection)) continue;
+
+      let content: Record<string, unknown>;
+      try {
+        content = JSON.parse(row.value) as Record<string, unknown>;
+      } catch {
+        continue;
+      }
+
+      const path = typeof content.path === 'string' ? content.path : undefined;
+      if (!path) continue;
+
+      pages.push({
+        collection,
+        path,
+        file: typeof content.id === 'string' ? content.id : row.id,
+        content
+      });
+    }
+  } finally {
+    database.close();
+  }
+
+  return pages;
+}
+
+/**
+ * Put Content's cache database into WAL mode, before Content opens it.
+ *
+ * The failure this removes: a `nuxt build` the kernel or a Ctrl-C left behind
+ * keeps `contents.sqlite` open, and every following build then fails with
+ * `database is locked` — a message naming neither the process nor the file.
+ * The busy timeout above covers the layer's own reader; Content's cache WRITER
+ * has no such patience, and a build cannot ask it for any.
+ *
+ * SQLite's default rollback journal locks the whole FILE while a writer holds
+ * it, so any reader is excluded outright. Write-ahead logging lets readers and
+ * one writer coexist, which is the actual shape of a build: Content writing the
+ * parse cache while this layer's modules read it. Measured on this repo's own
+ * site while translating — 237 lock errors went to zero.
+ *
+ * The mode lives in the FILE HEADER, not in a connection, so setting it once
+ * holds for every process that opens the file afterwards — Content's included,
+ * which is why this can be done from a module and does not need a patch.
+ *
+ * Creates the file when it is not there yet, so a first build gets WAL too.
+ * Safe: Content opens the path either way and probes for its cache table with
+ * a `SELECT` in a try/catch, so an empty database is the same to it as no file.
+ *
+ * Best-effort throughout. A database that cannot be opened, a filesystem that
+ * does not support WAL (a network mount is the usual one) and a read-only
+ * checkout each leave the build exactly as it was before this ran.
+ */
+export function enableWriteAheadLog(nuxt: Nuxt): 'wal' | 'skipped' {
+  const file = cacheFile(nuxt);
+
+  /**
+   * NEVER CREATE THE FILE. `new DatabaseSync` on a missing path writes an empty
+   * 4 kB database, and Content then finds a file where it expected none and
+   * never creates its schema — every query afterwards dies with `no such table:
+   * _development_cache`.
+   *
+   * Invisible on any machine that has built once, because the file is there by
+   * then; it only bites a FRESH checkout, which is to say CI and every new
+   * contributor. Skipping here costs the first build its WAL and nothing else:
+   * that build has no cache to read anyway, and the second one finds the file
+   * and switches it over.
+   */
+  if (!existsSync(file)) return 'skipped';
+
+  try {
+    mkdirSync(dirname(file), { recursive: true });
+
+    const database = new DatabaseSync(file, { timeout: 15_000 });
+
+    try {
+      const [row] = database.prepare('PRAGMA journal_mode = WAL').all() as {
+        journal_mode?: string;
+      }[];
+
+      return row?.journal_mode?.toLowerCase() === 'wal' ? 'wal' : 'skipped';
+    } finally {
+      database.close();
+    }
+  } catch {
+    // Nothing here is worth failing a build over: the busy timeout on the
+    // reader is what this improves upon, not what it replaces.
+    return 'skipped';
+  }
+}