svelte-docsmith 0.12.0 → 0.12.1

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

@@ -13,7 +13,7 @@ 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 { commitDates } from '../git.js';
 import { docsBaseFrom } from '../paths.js';
 import { isPageFile } from '../vite/pages.js';
 import { CliError } from './error.js';
@@ -79,6 +79,14 @@ export function archiveVersion(options, log) {
                 yield { file, source: path.join(contentDir, path.relative(toDir, file)) };
         }
     }
+    // Read the dates before copying, so the walk sees the docs root as it was
+    // rather than a tree half full of untracked copies. Say so if they could not
+    // be read: an archive is written once and never edited again, so a page that
+    // misses its date here keeps the wrong one for good.
+    const dates = commitDates(contentDir, (reason) => {
+        log(`\n! Could not read commit dates: ${reason}`);
+        log('  Archived pages will keep no last-updated date.\n');
+    });
     copyCurrent(contentDir, toDir);
     fs.writeFileSync(path.join(toDir, ARCHIVE_MARKER), markerContents(id));
     let pages = 0;
@@ -87,12 +95,15 @@ export function archiveVersion(options, log) {
             continue;
         pages++;
         const text = fs.readFileSync(file, 'utf-8');
-        fs.writeFileSync(file, freezeLastUpdated(rewriteDocsLinks(text, { docsBase, versionId: id, archivedIds }), lastCommitDate(source)));
+        fs.writeFileSync(file, freezeLastUpdated(rewriteDocsLinks(text, { docsBase, versionId: id, archivedIds }), dates.get(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('Links were rewritten to stay inside the archive.');
+    // Only claim the dates were kept when the walk actually produced some.
+    if (dates.size)
+        log('Each page kept its real last-updated date.');
+    log('Review the diff, then update docsmith({ versions }) so the archive');
+    log('is served:\n');
     log('  versions: {');
     log("    current: { id: '<new release>', label: '<new release>' },");
     log(`    archived: [{ id: '${id}', label: '${label}' }${archivedIds.size ? ', …' : ''}]`);

package/dist/buildtime/git.d.ts

@@ -1,5 +1,33 @@
-/** Commit day (`YYYY-MM-DD`) a file last changed, or undefined outside a repo. */
-export declare function lastCommitDate(file: string): string | undefined;
+/**
+ * Commit day (`YYYY-MM-DD`) every tracked file under `dir` last changed, keyed by
+ * absolute path. One history walk rather than a `git log` per file: the per-file
+ * form costs a process each, which is the build's largest single expense once a
+ * site has more than a handful of pages.
+ *
+ * `--relative` makes git print paths relative to `dir`, so they join straight
+ * back onto it with no second call to find the repository root. `--no-renames`
+ * makes a rename list both of its paths, which keeps the answer identical to
+ * asking about one file at a time.
+ *
+ * An empty map for a directory outside a repository, or one git could not read.
+ * That is the same "no date" every caller already handles, and it is deliberately
+ * all-or-nothing: a truncated read would date some pages and not others, which
+ * looks like real data and is not.
+ *
+ * Only a truncated read calls `onFail`, because it is the one failure that would
+ * otherwise date some pages and not others. A directory outside a repository, a
+ * missing directory, or a machine without git all yield no dates, which every
+ * caller already handles and which the plugin already reports where it matters.
+ * Reporting is the caller's to do, which is why this takes a callback rather
+ * than writing to the console itself.
+ */
+export declare function commitDates(dir: string, onFail?: (reason: string) => void, 
+/**
+ * Cap on the walk's output. The default is far above any real docs root; it is
+ * a parameter so the truncation path can be exercised without a repository
+ * large enough to produce 256 MB of history.
+ */
+maxBuffer?: number): Map<string, string>;
 /**
  * Release dates keyed by version, read from the commit that introduced each
  * `## <version>` heading in a changelog. Changesets does not write dates, and a

package/dist/buildtime/git.js

@@ -12,14 +12,64 @@
  */
 import { spawnSync } from 'node:child_process';
 import path from 'node:path';
-/** 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=%cs', '--', file], {
-        cwd: path.dirname(file),
-        encoding: 'utf-8'
-    });
-    const date = res.status === 0 ? res.stdout.trim() : '';
-    return date || undefined;
+/**
+ * Commit day (`YYYY-MM-DD`) every tracked file under `dir` last changed, keyed by
+ * absolute path. One history walk rather than a `git log` per file: the per-file
+ * form costs a process each, which is the build's largest single expense once a
+ * site has more than a handful of pages.
+ *
+ * `--relative` makes git print paths relative to `dir`, so they join straight
+ * back onto it with no second call to find the repository root. `--no-renames`
+ * makes a rename list both of its paths, which keeps the answer identical to
+ * asking about one file at a time.
+ *
+ * An empty map for a directory outside a repository, or one git could not read.
+ * That is the same "no date" every caller already handles, and it is deliberately
+ * all-or-nothing: a truncated read would date some pages and not others, which
+ * looks like real data and is not.
+ *
+ * Only a truncated read calls `onFail`, because it is the one failure that would
+ * otherwise date some pages and not others. A directory outside a repository, a
+ * missing directory, or a machine without git all yield no dates, which every
+ * caller already handles and which the plugin already reports where it matters.
+ * Reporting is the caller's to do, which is why this takes a callback rather
+ * than writing to the console itself.
+ */
+export function commitDates(dir, onFail, 
+/**
+ * Cap on the walk's output. The default is far above any real docs root; it is
+ * a parameter so the truncation path can be exercised without a repository
+ * large enough to produce 256 MB of history.
+ */
+maxBuffer = 256 * 1024 * 1024) {
+    const dates = new Map();
+    const res = spawnSync('git', ['log', '--format=%cs', '--name-only', '--relative', '--no-renames', '--', '.'], 
+    // The 1 MB default would truncate rather than throw on a large history,
+    // which is why the cap is raised and the result checked below.
+    { cwd: dir, encoding: 'utf-8', maxBuffer });
+    // `ENOBUFS` is the output outgrowing maxBuffer, which truncates rather than
+    // throws and is the only failure that could leave a half-filled map. `ENOENT`
+    // (no such directory, or no git installed) and a non-zero status ("not a
+    // repository") both mean no dates at all, which is a state callers expect.
+    if (res.error?.code === 'ENOBUFS') {
+        onFail?.(res.error.message);
+    }
+    if (res.error || res.status !== 0)
+        return dates;
+    let date;
+    for (const line of res.stdout.split('\n')) {
+        if (!line)
+            continue;
+        if (/^\d{4}-\d{2}-\d{2}$/.test(line)) {
+            date = line;
+            continue;
+        }
+        // Newest commit first, so the first date a file appears under is its latest.
+        const file = path.resolve(dir, line);
+        if (date && !dates.has(file))
+            dates.set(file, date);
+    }
+    return dates;
 }
 /**
  * Release dates keyed by version, read from the commit that introduced each

package/dist/buildtime/vite/index.js

@@ -26,6 +26,7 @@ import { docsBaseFrom } from '../paths.js';
 import { isPageFile, readSourcePages, withCommitDates } from './pages.js';
 import { contentIndex, llmsIndex, searchIndex } from './collect.js';
 import { collectReleases } from './releases.js';
+import { commitDates } from '../git.js';
 /**
  * The svelte-docsmith Vite plugin. Add it to `plugins` in `vite.config.ts`:
  *
@@ -70,6 +71,17 @@ function contentIndexPlugin(options) {
     const changelogRoute = options.changelogPath ?? '/changelog';
     const changelogOverrides = path.join(routesDir, changelogRoute);
     const indexOptions = { contentDir, routesDir, versions };
+    // One history walk, reused for the life of the plugin. A build loads this
+    // module once, so it is always fresh there; `dev` reloads it on every page
+    // save, and re-walking each time would cost git a process for dates that
+    // cannot have changed without a commit. The trade is that committing during
+    // `dev` leaves the dates as they were until the server restarts.
+    let dates;
+    const trackedDates = () => (dates ??= commitDates(contentDir, (reason) => {
+        console.warn(`[svelte-docsmith] could not read commit dates under ${contentDir}\n` +
+            `  ${reason}\n` +
+            `  Pages will render without a last-updated date, and sitemap entries without \`lastmod\`.`);
+    }));
     return {
         name: 'docsmith-content',
         enforce: 'pre',
@@ -101,7 +113,7 @@ function contentIndexPlugin(options) {
                 const { pages, exists } = readSourcePages(contentDir);
                 watch(pages);
                 // Only this index has a date field, so only this one pays for git.
-                const docs = contentIndex(withCommitDates(pages), indexOptions);
+                const docs = contentIndex(withCommitDates(pages, trackedDates()), indexOptions);
                 warnAboutDocsRoot(contentDir, exists, docs.length);
                 const resolved = resolveVersions(versions, docsBase, docs);
                 return (`export const docs = ${JSON.stringify(docs, null, 2)};\n` +

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

@@ -39,18 +39,18 @@ export declare function readSourcePages(contentDir: string): {
  */
 export declare function titleOf(page: SourcePage): string | undefined;
 /**
- * Date each page from the commit that last touched it, skipping the lookup for
- * pages that carry their own `lastUpdated`. Archiving copies every page in one
- * commit, so an archive's pages are written with the date they last really
- * changed and must keep it.
+ * Date each page from `dates`, keyed by absolute path, unless it carries its own
+ * frontmatter `lastUpdated`. Archiving copies every page in one commit, so an
+ * archive's pages are written with the date they last really changed and must
+ * keep it.
  *
- * Deliberately a second pass rather than part of {@link readSourcePages}: it
- * spawns a git process per page, and only the content index has a date field.
- * Folding it into the read would make the search and llms indexes pay for a
- * value neither of them has anywhere to put. For the same reason it skips
- * untitled pages, which no index carries.
+ * Pure: the caller walks git once with {@link commitDates} and hands the result
+ * in. Asking per page cost a process each and was the build's largest single
+ * expense, and doing the walk here would put it behind a function the search and
+ * llms indexes also call, making them pay for a date neither has anywhere to put.
+ * For the same reason this skips untitled pages, which no index carries.
  */
-export declare function withCommitDates(pages: SourcePage[]): SourcePage[];
+export declare function withCommitDates(pages: SourcePage[], dates: Map<string, string>): SourcePage[];
 /**
  * List the absolute paths of every `+page.md`/`+page.svx` under `contentDir`.
  */

package/dist/buildtime/vite/pages.js

@@ -7,7 +7,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { parseFrontmatter } from './frontmatter.js';
-import { lastCommitDate } from '../git.js';
 const PAGE_NAMES = ['+page.md', '+page.svx'];
 /** Whether a filename is a doc page the plugin should index. */
 export function isPageFile(file) {
@@ -40,18 +39,18 @@ export function titleOf(page) {
     return typeof page.frontmatter.title === 'string' ? page.frontmatter.title : undefined;
 }
 /**
- * Date each page from the commit that last touched it, skipping the lookup for
- * pages that carry their own `lastUpdated`. Archiving copies every page in one
- * commit, so an archive's pages are written with the date they last really
- * changed and must keep it.
+ * Date each page from `dates`, keyed by absolute path, unless it carries its own
+ * frontmatter `lastUpdated`. Archiving copies every page in one commit, so an
+ * archive's pages are written with the date they last really changed and must
+ * keep it.
  *
- * Deliberately a second pass rather than part of {@link readSourcePages}: it
- * spawns a git process per page, and only the content index has a date field.
- * Folding it into the read would make the search and llms indexes pay for a
- * value neither of them has anywhere to put. For the same reason it skips
- * untitled pages, which no index carries.
+ * Pure: the caller walks git once with {@link commitDates} and hands the result
+ * in. Asking per page cost a process each and was the build's largest single
+ * expense, and doing the walk here would put it behind a function the search and
+ * llms indexes also call, making them pay for a date neither has anywhere to put.
+ * For the same reason this skips untitled pages, which no index carries.
  */
-export function withCommitDates(pages) {
+export function withCommitDates(pages, dates) {
     return pages.map((page) => {
         if (titleOf(page) === undefined)
             return page;
@@ -59,7 +58,7 @@ export function withCommitDates(pages) {
             ...page,
             lastUpdated: typeof page.frontmatter.lastUpdated === 'string'
                 ? page.frontmatter.lastUpdated
-                : lastCommitDate(page.file)
+                : dates.get(page.file)
         };
     });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "svelte-docsmith",
-  "version": "0.12.0",
+  "version": "0.12.1",
   "description": "A framework for building beautiful documentation sites with Svelte.",
   "author": {
     "name": "George Daskalakis",