svelte-docsmith 0.10.0 → 0.12.0

package/bin/svelte-docsmith.mjs

@@ -1,161 +1,16 @@
 #!/usr/bin/env node
-// The svelte-docsmith maintenance CLI. Currently one command: `archive-version`,
-// which freezes today's docs into an archived version folder so they stay live
-// after a breaking release.
-//
-// The current version is served unprefixed from the docs root and is the folder
-// you keep editing; archives are copies under their own prefix. See
-// docs/adr/0001-unprefixed-current-docs.md. The text transforms live in
-// `src/lib/buildtime/archive.ts` so they are typechecked and unit-tested; this
-// file is the filesystem wrapper around them.
-import fs from 'node:fs';
-import path from 'node:path';
-import { execFileSync } from 'node:child_process';
-import {
-	rewriteDocsLinks,
-	freezeLastUpdated,
-	isInheritedRouteFile
-} from '../dist/buildtime/archive.js';
-
-const HELP = `svelte-docsmith — docs maintenance CLI
-
-Usage:
-  svelte-docsmith archive-version <id> [options]
-
-Freeze the current docs into an archived version folder. The archive keeps
-serving the release it documents while you go on editing the docs root.
-
-Options:
-  --label <label>  switcher label for the archive (default: the id)
-  --content <dir>  docs content directory (default: src/routes/docs)
-  --routes <dir>   SvelteKit routes directory (default: src/routes)
-`;
-
-// Written into every archive this command creates, so later runs know which
-// directories are already archives and must not be copied into the new one.
-const MARKER = '.docsmith-archive';
-
-const [command, ...rest] = process.argv.slice(2);
-
-if (command !== 'archive-version') {
-	console.log(HELP);
-	process.exit(command ? 1 : 0);
-}
-
-const opts = { content: 'src/routes/docs', routes: 'src/routes', label: undefined };
-let id;
-for (let i = 0; i < rest.length; i++) {
-	const arg = rest[i];
-	if (arg === '--label') opts.label = rest[++i];
-	else if (arg === '--content') opts.content = rest[++i];
-	else if (arg === '--routes') opts.routes = rest[++i];
-	else if (!arg.startsWith('--') && !id) id = arg;
-}
-
-const fail = (message) => {
-	console.error(`svelte-docsmith archive-version: ${message}`);
-	process.exit(1);
-};
-
-if (!id) fail('missing <id>. e.g. `svelte-docsmith archive-version v1`');
-// Must start alphanumeric: the id is both a directory name and a URL segment, so
-// `.`, `..` and dotfiles would escape the docs root or make a hidden, dead route.
-if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(id)) {
-	fail(`invalid id: ${id}. Start with a letter or digit; it is used as a URL segment.`);
-}
-
-const contentDir = path.resolve(opts.content);
-const routesDir = path.resolve(opts.routes);
-const toDir = path.join(contentDir, id);
-const rel = (p) => path.relative(process.cwd(), p);
-
-if (!fs.existsSync(contentDir)) fail(`content directory not found: ${rel(contentDir)}`);
-if (fs.existsSync(toDir)) fail(`target already exists: ${rel(toDir)}`);
-
-// The docs URL base (e.g. `/docs`), derived exactly as the vite plugin does.
-const docsBase = '/' + path.relative(routesDir, contentDir).split(path.sep).join('/');
-
-/** Directories directly under the docs root that are already archives. */
-const archivedIds = new Set(
-	fs
-		.readdirSync(contentDir, { withFileTypes: true })
-		.filter((e) => e.isDirectory() && fs.existsSync(path.join(contentDir, e.name, MARKER)))
-		.map((e) => e.name)
-);
-
-const isPage = (name) => name.endsWith('+page.md') || name.endsWith('+page.svx');
-
-/** Copy the docs root into the archive, skipping what the archive shouldn't hold. */
-function copyCurrent(from, to) {
-	fs.mkdirSync(to, { recursive: true });
-	for (const entry of fs.readdirSync(from, { withFileTypes: true })) {
-		const src = path.join(from, entry.name);
-		const dest = path.join(to, entry.name);
-		if (entry.isDirectory()) {
-			// Never descend into the archive being written (it lives inside the docs
-			// root) or into an archive written by an earlier run.
-			if (src === toDir) continue;
-			if (from === contentDir && archivedIds.has(entry.name)) continue;
-			copyCurrent(src, dest);
-		} else {
-			// The root layout and error page already apply to the archive, which is
-			// nested inside them; copying them would nest a second DocsShell.
-			if (from === contentDir && isInheritedRouteFile(entry.name)) continue;
-			fs.copyFileSync(src, dest);
-		}
-	}
-}
-
-/** Every file in the archive, paired with the source file it was copied from. */
-function* eachCopiedFile(dir = toDir) {
-	for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
-		const file = path.join(dir, entry.name);
-		if (entry.isDirectory()) yield* eachCopiedFile(file);
-		else yield { file, source: path.join(contentDir, path.relative(toDir, file)) };
+// Process boundary only. The command itself lives in
+// `src/lib/buildtime/cli/`, where it is typechecked and unit-tested; this file
+// exists so `svelte-docsmith` is a runnable bin entry.
+import { run, CliError } from '../dist/buildtime/cli/run.js';
+
+try {
+	run(process.argv.slice(2));
+} catch (error) {
+	if (error instanceof CliError) {
+		// A mistake the user can fix. The message says how; a stack would not help.
+		console.error(`svelte-docsmith: ${error.message}`);
+		process.exit(1);
 	}
+	throw error;
 }
-
-/** The date a page last really changed, so the archive doesn't claim today. */
-function lastCommitDate(file) {
-	try {
-		const out = execFileSync('git', ['log', '-1', '--format=%cs', '--', file], {
-			cwd: path.dirname(file),
-			encoding: 'utf-8',
-			stdio: ['ignore', 'pipe', 'ignore']
-		}).trim();
-		return out || undefined;
-	} catch {
-		return undefined;
-	}
-}
-
-copyCurrent(contentDir, toDir);
-fs.writeFileSync(
-	path.join(toDir, MARKER),
-	`Archived docs for ${id}, created by \`svelte-docsmith archive-version\`.\n` +
-		`This folder is frozen: edit the docs root instead.\n`
-);
-
-let pages = 0;
-for (const { file, source } of eachCopiedFile()) {
-	if (!isPage(path.basename(file))) continue;
-	pages++;
-	const text = fs.readFileSync(file, 'utf-8');
-	fs.writeFileSync(
-		file,
-		freezeLastUpdated(
-			rewriteDocsLinks(text, { docsBase, versionId: id, archivedIds }),
-			lastCommitDate(source)
-		)
-	);
-}
-
-const label = opts.label ?? id;
-console.log(`\n✓ Archived the current docs into ${rel(toDir)} (${pages} pages)\n`);
-console.log('Links were rewritten to stay inside the archive, and each page kept');
-console.log('its real last-updated date. Review the diff, then update');
-console.log('docsmith({ versions }) so the archive is served:\n');
-console.log('  versions: {');
-console.log("    current: { id: '<new release>', label: '<new release>' },");
-console.log(`    archived: [{ id: '${id}', label: '${label}' }${archivedIds.size ? ', …' : ''}]`);
-console.log('  }\n');

package/dist/buildtime/archive.js

@@ -7,6 +7,7 @@
  * Kept here rather than in `bin/` so they are typechecked and unit-tested; the
  * CLI is a thin wrapper over them. See `docs/adr/0002-archives-are-rewritten-source-copies.md`.
  */
+import { atBoundary, firstSegmentUnder } from '../utils/url.js';
 import { outsideCodeFences, withFrontmatter } from './markdown-source.js';
 /** Route files at the docs root that an archive nested inside it already inherits. */
 export function isInheritedRouteFile(name) {
@@ -28,10 +29,11 @@ export function rewriteDocsLinks(text, options) {
     const skip = new Set([...(options.archivedIds ?? []), versionId]);
     const pattern = new RegExp(`(\\]\\(|href="|href='|\\]:[ \\t]+)(${escapeRe(docsBase)})([^)"'\\s]*)`, 'g');
     return outsideCodeFences(text, (chunk) => chunk.replace(pattern, (match, prefix, base, rest) => {
-        // Guard the segment boundary: `/docsmith` must not become `/docs/v1mith`.
-        if (rest && !/^[/#?]/.test(rest))
+        // The regex has already matched the base, so guard the boundary on what
+        // follows it: `/docsmith` must not become `/docs/v1mith`.
+        if (!atBoundary(rest))
             return match;
-        const firstSegment = rest.startsWith('/') ? rest.slice(1).split(/[/#?]/)[0] : '';
+        const firstSegment = firstSegmentUnder(rest, '');
         if (firstSegment && skip.has(firstSegment))
             return match;
         return `${prefix}${base}/${versionId}${rest}`;

package/dist/buildtime/archives.d.ts

@@ -0,0 +1,18 @@
+import type { ArchivesOnDisk } from '../core/version.js';
+/**
+ * Written into every archive `archive-version` creates. Not a convenience for
+ * the command: this file is what makes a directory an archived version rather
+ * than an ordinary section of the current docs, and the build reads it. The two
+ * are otherwise indistinguishable, since a page is assigned to a version by its
+ * first directory segment. See
+ * `docs/adr/0003-the-archive-marker-defines-an-archive.md`.
+ */
+export declare const ARCHIVE_MARKER = ".docsmith-archive";
+/** The text written into a new archive's marker file. */
+export declare function markerContents(id: string): string;
+/**
+ * The directories directly under `contentDir`, and which of them are archives.
+ * An absent docs root reads as empty rather than throwing: the collectors
+ * already report that case, and the command has its own message for it.
+ */
+export declare function discoverArchives(contentDir: string): ArchivesOnDisk;

package/dist/buildtime/archives.js

@@ -0,0 +1,43 @@
+/**
+ * What the docs root says about itself: which directories under it are archived
+ * versions. The scan is deliberately thin, so the reconciliation it feeds
+ * (`checkVersions`) stays pure and testable without a filesystem.
+ *
+ * Both callers cross this seam. The vite plugin scans before resolving versions;
+ * `archive-version` scans so it knows which directories not to copy into the
+ * archive it is writing.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+/**
+ * Written into every archive `archive-version` creates. Not a convenience for
+ * the command: this file is what makes a directory an archived version rather
+ * than an ordinary section of the current docs, and the build reads it. The two
+ * are otherwise indistinguishable, since a page is assigned to a version by its
+ * first directory segment. See
+ * `docs/adr/0003-the-archive-marker-defines-an-archive.md`.
+ */
+export const ARCHIVE_MARKER = '.docsmith-archive';
+/** The text written into a new archive's marker file. */
+export function markerContents(id) {
+    return (`Archived docs for ${id}, created by \`svelte-docsmith archive-version\`.\n` +
+        `This folder is frozen: edit the docs root instead.\n` +
+        `Removing this file makes the build treat it as current-version content.\n`);
+}
+/**
+ * The directories directly under `contentDir`, and which of them are archives.
+ * An absent docs root reads as empty rather than throwing: the collectors
+ * already report that case, and the command has its own message for it.
+ */
+export function discoverArchives(contentDir) {
+    if (!fs.existsSync(contentDir))
+        return { marked: [], directories: [] };
+    const directories = fs
+        .readdirSync(contentDir, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => entry.name);
+    return {
+        directories,
+        marked: directories.filter((name) => fs.existsSync(path.join(contentDir, name, ARCHIVE_MARKER)))
+    };
+}

package/dist/buildtime/cli/archive-version.d.ts

@@ -0,0 +1,18 @@
+export type ArchiveVersionOptions = {
+    /** Id of the archive to create. Becomes its directory name and URL segment. */
+    id: string;
+    /** Switcher label for the archive. Defaults to the id. */
+    label?: string;
+    /** Docs content directory, resolved against `cwd`. */
+    content?: string;
+    /** SvelteKit routes directory, resolved against `cwd`. */
+    routes?: string;
+    /** Working directory the relative options resolve against. */
+    cwd?: string;
+};
+/**
+ * Copy the docs root into `<content>/<id>/`, mark it as an archive, and rewrite
+ * each copied page so it stays inside the archive and keeps its real
+ * last-updated date. Returns the number of pages archived.
+ */
+export declare function archiveVersion(options: ArchiveVersionOptions, log: (line: string) => void): number;

package/dist/buildtime/cli/archive-version.js

@@ -0,0 +1,104 @@
+/**
+ * `svelte-docsmith archive-version <id>`: freeze the current docs into an
+ * archived version folder so they keep serving the release they document while
+ * the docs root goes on being edited.
+ *
+ * The pure text transforms live in `../archive.js`; this is the filesystem work
+ * around them. It takes its working directory and its output sink rather than
+ * reading `process.cwd()` and calling `console.log`, so the whole command runs
+ * in-process under test. See `docs/adr/0002-archives-are-rewritten-source-copies.md`.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { assertValidVersionId } from '../../core/version.js';
+import { freezeLastUpdated, isInheritedRouteFile, rewriteDocsLinks } from '../archive.js';
+import { ARCHIVE_MARKER, discoverArchives, markerContents } from '../archives.js';
+import { lastCommitDate } from '../git.js';
+import { docsBaseFrom } from '../paths.js';
+import { isPageFile } from '../vite/pages.js';
+import { CliError } from './error.js';
+/**
+ * Copy the docs root into `<content>/<id>/`, mark it as an archive, and rewrite
+ * each copied page so it stays inside the archive and keeps its real
+ * last-updated date. Returns the number of pages archived.
+ */
+export function archiveVersion(options, log) {
+    const cwd = options.cwd ?? process.cwd();
+    const { id, label = options.id } = options;
+    try {
+        assertValidVersionId(id);
+    }
+    catch (error) {
+        throw new CliError(error.message);
+    }
+    const contentDir = path.resolve(cwd, options.content ?? 'src/routes/docs');
+    const routesDir = path.resolve(cwd, options.routes ?? 'src/routes');
+    const toDir = path.join(contentDir, id);
+    const rel = (p) => path.relative(cwd, p);
+    if (!fs.existsSync(contentDir)) {
+        throw new CliError(`content directory not found: ${rel(contentDir)}`);
+    }
+    if (fs.existsSync(toDir)) {
+        throw new CliError(`target already exists: ${rel(toDir)}`);
+    }
+    const docsBase = docsBaseFrom(routesDir, contentDir);
+    // Archives already on disk, so this run neither copies them into the new
+    // archive nor rewrites links that already point into one of them.
+    const archivedIds = new Set(discoverArchives(contentDir).marked);
+    /** Copy the docs root into the archive, skipping what the archive shouldn't hold. */
+    function copyCurrent(from, to) {
+        fs.mkdirSync(to, { recursive: true });
+        for (const entry of fs.readdirSync(from, { withFileTypes: true })) {
+            const src = path.join(from, entry.name);
+            const dest = path.join(to, entry.name);
+            if (entry.isDirectory()) {
+                // Never descend into the archive being written (it lives inside the docs
+                // root) or into an archive written by an earlier run.
+                if (src === toDir)
+                    continue;
+                if (from === contentDir && archivedIds.has(entry.name))
+                    continue;
+                copyCurrent(src, dest);
+            }
+            else {
+                // The root layout and error page already apply to the archive, which is
+                // nested inside them; copying them would nest a second DocsShell.
+                if (from === contentDir && isInheritedRouteFile(entry.name))
+                    continue;
+                fs.copyFileSync(src, dest);
+            }
+        }
+    }
+    /** Every file in the archive, paired with the source file it was copied from. */
+    function* eachCopiedFile(dir = toDir) {
+        for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+            const file = path.join(dir, entry.name);
+            if (entry.isDirectory())
+                yield* eachCopiedFile(file);
+            else
+                yield { file, source: path.join(contentDir, path.relative(toDir, file)) };
+        }
+    }
+    copyCurrent(contentDir, toDir);
+    fs.writeFileSync(path.join(toDir, ARCHIVE_MARKER), markerContents(id));
+    let pages = 0;
+    for (const { file, source } of eachCopiedFile()) {
+        if (!isPageFile(path.basename(file)))
+            continue;
+        pages++;
+        const text = fs.readFileSync(file, 'utf-8');
+        fs.writeFileSync(file, freezeLastUpdated(rewriteDocsLinks(text, { docsBase, versionId: id, archivedIds }), lastCommitDate(source)));
+    }
+    log(`\n✓ Archived the current docs into ${rel(toDir)} (${pages} pages)\n`);
+    log('Links were rewritten to stay inside the archive, and each page kept');
+    log('its real last-updated date. Review the diff, then update');
+    log('docsmith({ versions }) so the archive is served:\n');
+    log('  versions: {');
+    log("    current: { id: '<new release>', label: '<new release>' },");
+    log(`    archived: [{ id: '${id}', label: '${label}' }${archivedIds.size ? ', …' : ''}]`);
+    log('  }\n');
+    // Until that paste lands the build fails, by design: the archive is on disk
+    // and undeclared. See docs/adr/0003-the-archive-marker-defines-an-archive.md.
+    log('Until then the build will fail, reporting this archive as undeclared.\n');
+    return pages;
+}

package/dist/buildtime/cli/error.d.ts

@@ -0,0 +1,9 @@
+/**
+ * A failure the user caused and can fix: a missing argument, a bad id, a target
+ * that already exists. The `bin/` shim prints its message and exits 1, without
+ * a stack, because a stack is noise for these. Anything else thrown out of the
+ * command is a bug and keeps its stack.
+ */
+export declare class CliError extends Error {
+    readonly name = "CliError";
+}

package/dist/buildtime/cli/error.js

@@ -0,0 +1,9 @@
+/**
+ * A failure the user caused and can fix: a missing argument, a bad id, a target
+ * that already exists. The `bin/` shim prints its message and exits 1, without
+ * a stack, because a stack is noise for these. Anything else thrown out of the
+ * command is a bug and keeps its stack.
+ */
+export class CliError extends Error {
+    name = 'CliError';
+}

package/dist/buildtime/cli/run.d.ts

@@ -0,0 +1,13 @@
+export { CliError } from './error.js';
+export { archiveVersion } from './archive-version.js';
+export declare const HELP = "svelte-docsmith \u2014 docs maintenance CLI\n\nUsage:\n  svelte-docsmith archive-version <id> [options]\n\nFreeze the current docs into an archived version folder. The archive keeps\nserving the release it documents while you go on editing the docs root.\n\nOptions:\n  --label <label>  switcher label for the archive (default: the id)\n  --content <dir>  docs content directory (default: src/routes/docs)\n  --routes <dir>   SvelteKit routes directory (default: src/routes)\n";
+/** Where the command writes, and what it resolves relative paths against. */
+export type CliIo = {
+    cwd?: string;
+    log?: (line: string) => void;
+};
+/**
+ * Run the CLI over `argv` (everything after the node binary and script). Throws
+ * {@link CliError} for anything the user can fix; the caller owns the exit code.
+ */
+export declare function run(argv: string[], io?: CliIo): void;

package/dist/buildtime/cli/run.js

@@ -0,0 +1,62 @@
+/**
+ * The `svelte-docsmith` maintenance CLI. Currently one command:
+ * `archive-version`.
+ *
+ * This is the whole command, not a helper for it: `bin/svelte-docsmith.mjs` is a
+ * shim that hands over `process.argv` and turns a thrown {@link CliError} into a
+ * message and an exit code. Keeping the process boundary out here means the
+ * command is typechecked, and testable in-process against a temporary directory
+ * rather than by spawning node and parsing stdout.
+ */
+import { archiveVersion } from './archive-version.js';
+import { CliError } from './error.js';
+export { CliError } from './error.js';
+export { archiveVersion } from './archive-version.js';
+export const HELP = `svelte-docsmith — docs maintenance CLI
+
+Usage:
+  svelte-docsmith archive-version <id> [options]
+
+Freeze the current docs into an archived version folder. The archive keeps
+serving the release it documents while you go on editing the docs root.
+
+Options:
+  --label <label>  switcher label for the archive (default: the id)
+  --content <dir>  docs content directory (default: src/routes/docs)
+  --routes <dir>   SvelteKit routes directory (default: src/routes)
+`;
+/** Parse `archive-version`'s flags and its one positional id. */
+function parseArchiveArgs(rest) {
+    const options = {};
+    for (let i = 0; i < rest.length; i++) {
+        const arg = rest[i];
+        if (arg === '--label')
+            options.label = rest[++i];
+        else if (arg === '--content')
+            options.content = rest[++i];
+        else if (arg === '--routes')
+            options.routes = rest[++i];
+        else if (!arg.startsWith('--') && !options.id)
+            options.id = arg;
+    }
+    if (!options.id) {
+        throw new CliError('missing <id>. e.g. `svelte-docsmith archive-version v1`');
+    }
+    return options;
+}
+/**
+ * Run the CLI over `argv` (everything after the node binary and script). Throws
+ * {@link CliError} for anything the user can fix; the caller owns the exit code.
+ */
+export function run(argv, io = {}) {
+    const log = io.log ?? ((line) => console.log(line));
+    const [command, ...rest] = argv;
+    if (!command) {
+        log(HELP);
+        return;
+    }
+    if (command !== 'archive-version') {
+        throw new CliError(`unknown command: ${command}\n\n${HELP}`);
+    }
+    archiveVersion({ ...parseArchiveArgs(rest), cwd: io.cwd }, log);
+}

package/dist/buildtime/{vite/git.d.ts → git.d.ts}

@@ -1,4 +1,4 @@
-/** Last git commit date (strict ISO) for a file, or undefined outside a repo. */
+/** Commit day (`YYYY-MM-DD`) a file last changed, or undefined outside a repo. */
 export declare function lastCommitDate(file: string): string | undefined;
 /**
  * Release dates keyed by version, read from the commit that introduced each

package/dist/buildtime/{vite/git.js → git.js}

@@ -1,8 +1,20 @@
+/**
+ * The git queries the build makes: when a page last changed, and when each
+ * release landed. Used by both the vite plugin and the `archive-version`
+ * command, which is why it sits here rather than under `vite/`.
+ *
+ * Every date here is `%cs`, the commit's calendar day (`YYYY-MM-DD`), never a
+ * timestamp. Dates from this module are rendered as a day and nothing more, and
+ * a date-only string parses to UTC midnight, so pinning the formatter to UTC
+ * renders the committer's own day identically for every reader and identically
+ * on the server and the client. A full timestamp buys precision no consumer
+ * uses and reintroduces the day-boundary drift.
+ */
 import { spawnSync } from 'node:child_process';
 import path from 'node:path';
-/** Last git commit date (strict ISO) for a file, or undefined outside a repo. */
+/** Commit day (`YYYY-MM-DD`) a file last changed, or undefined outside a repo. */
 export function lastCommitDate(file) {
-    const res = spawnSync('git', ['log', '-1', '--format=%cI', '--', file], {
+    const res = spawnSync('git', ['log', '-1', '--format=%cs', '--', file], {
         cwd: path.dirname(file),
         encoding: 'utf-8'
     });
@@ -19,7 +31,7 @@ export function changelogDates(file) {
     const dates = new Map();
     // `-L` would be per-line; instead walk the file's commits newest-first and
     // record the first commit in which each version heading appears.
-    const log = spawnSync('git', ['log', '--format=%H %cI', '--reverse', '--follow', '--', path.basename(file)], { cwd: path.dirname(file), encoding: 'utf-8' });
+    const log = spawnSync('git', ['log', '--format=%H %cs', '--reverse', '--follow', '--', path.basename(file)], { cwd: path.dirname(file), encoding: 'utf-8' });
     if (log.status !== 0)
         return dates;
     for (const line of log.stdout.trim().split('\n').filter(Boolean)) {

package/dist/buildtime/paths.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The URL a directory under the routes root is served at: `<routes>/docs/intro`
+ * becomes `/docs/intro`. The routes root itself becomes `/`.
+ */
+export declare function urlFor(routesDir: string, dir: string): string;
+/**
+ * The docs URL base, e.g. `/docs`, from the content directory's location under
+ * the routes directory. The same mapping a page's own directory goes through, so
+ * a page at `<routes>/docs/intro/+page.md` is served at `/docs/intro` under a
+ * base of `/docs`.
+ */
+export declare function docsBaseFrom(routesDir: string, contentDir: string): string;

package/dist/buildtime/paths.js

@@ -0,0 +1,23 @@
+/**
+ * Build-time path derivations shared by the vite plugin and the maintenance CLI.
+ * Both have to agree on where the docs live in URL space, and each deriving it
+ * separately is how they drift.
+ */
+import path from 'node:path';
+/**
+ * The URL a directory under the routes root is served at: `<routes>/docs/intro`
+ * becomes `/docs/intro`. The routes root itself becomes `/`.
+ */
+export function urlFor(routesDir, dir) {
+    const rel = path.relative(routesDir, dir).split(path.sep).join('/');
+    return '/' + rel;
+}
+/**
+ * The docs URL base, e.g. `/docs`, from the content directory's location under
+ * the routes directory. The same mapping a page's own directory goes through, so
+ * a page at `<routes>/docs/intro/+page.md` is served at `/docs/intro` under a
+ * base of `/docs`.
+ */
+export function docsBaseFrom(routesDir, contentDir) {
+    return urlFor(routesDir, contentDir);
+}

package/dist/buildtime/vite/collect.d.ts

@@ -1,24 +1,33 @@
 import type { DocsContentItem, LlmsDoc, SearchDoc } from '../../core/content.js';
 import type { DocsVersions } from '../../core/version.js';
+import { type SourcePage } from './pages.js';
+/** Where the pages sit, which is what turns a page's file into a URL and a version. */
+export type IndexOptions = {
+    /** The docs root the pages were read from. */
+    contentDir: string;
+    /** Routes root, so `<routes>/docs/intro/+page.md` becomes `/docs/intro`. */
+    routesDir: string;
+    /** Declared versions, when the site has them. */
+    versions?: DocsVersions;
+};
 /**
- * Scan `contentDir` for `+page.md`/`+page.svx` files and read the frontmatter
- * fields the sidebar needs (plus the heading list for a server-rendered TOC and
- * an estimated reading time), deriving each page's URL from its directory
- * relative to `routesDir`. Pure and synchronous so it can be unit-tested.
+ * The sidebar's index: the frontmatter fields navigation needs, plus the heading
+ * list for a server-rendered TOC and an estimated reading time. Served as the
+ * eagerly-imported `svelte-docsmith/content` virtual module.
+ *
+ * `lastUpdated` is read off the page rather than looked up here, so pass pages
+ * that have been through `withCommitDates` or the column comes out blank.
  */
-export declare function collectDocs(contentDir: string, routesDir: string, versions?: DocsVersions): DocsContentItem[];
+export declare function contentIndex(pages: SourcePage[], options: IndexOptions): DocsContentItem[];
 /**
- * Build the search records for every page under `contentDir`: title, section,
- * description, heading list, and plain-text body. Served as the lazy-loaded
- * `svelte-docsmith/search` virtual module so search can index bodies without
- * bloating the eagerly-imported nav index. The missing-directory case is
- * already reported by {@link collectDocs}, so this stays quiet.
+ * The search index: title, section, description, heading list, and plain-text
+ * body. Served as the lazy-loaded `svelte-docsmith/search` virtual module so
+ * search can index bodies without bloating the eagerly-imported content index.
  */
-export declare function collectSearchDocs(contentDir: string, routesDir: string, versions?: DocsVersions): SearchDoc[];
+export declare function searchIndex(pages: SourcePage[], options: IndexOptions): SearchDoc[];
 /**
- * Build the LLM records for every page: title, section, description, and the
- * full markdown content. Served as the `svelte-docsmith/llms` virtual module and
- * consumed server-side by `llms.txt` / `llms-full.txt` routes, so it never ships
- * to the client.
+ * The LLM index: title, section, description, and the full markdown content.
+ * Served as the `svelte-docsmith/llms` virtual module and consumed server-side
+ * by `llms.txt` / `llms-full.txt` routes, so it never ships to the client.
  */
-export declare function collectLlmsDocs(contentDir: string, routesDir: string, versions?: DocsVersions): LlmsDoc[];
+export declare function llmsIndex(pages: SourcePage[], options: IndexOptions): LlmsDoc[];