@iyulab/canopy-page 0.14.0 → 0.15.0

package/CHANGELOG.md

@@ -7,6 +7,17 @@ Notable changes to canopy-page. The format follows
 The `settings.json` contract is what consuming projects plan their upgrades around, so changes
 to it — its fields, its validation, and what the checks reject — are what this file is about.
 
+## [0.15.0] — 2026-09-17
+
+### Added
+
+- **`sitemap.xml` entries now carry `<lastmod>`.** A page's own frontmatter `updated:` date wins
+  when it names one; otherwise it is the last git commit date of that page's source markdown.
+  A page with no source file (canopy's synthetic root `index.html`) or with an untracked source
+  is written without the element rather than with a guessed date. On a shallow clone — where an
+  untouched page would falsely report the clone's boundary date, indistinguishable from every
+  other untouched page — `<lastmod>` is withheld from the whole sitemap, and the build warns why.
+
 ## [0.14.0] — 2026-09-17
 
 ### Added

package/dist/build.js

@@ -4,6 +4,7 @@ import path from "node:path";
 import { assembleScript, assembleTokensCss } from "./assets-bundle.js";
 import { runCanopy } from "./canopy.js";
 import { siteFindings } from "./check.js";
+import { resolveLastmods } from "./lastmod.js";
 import { listHtmlFiles, robotsTxt, sitemapXml } from "./sitemap.js";
 import { loadSite, reportFindings } from "./site.js";
 /**
@@ -96,10 +97,16 @@ export async function buildSite({ dir, out }) {
         if (code === 0 && site.settings.siteUrl !== undefined) {
             const outDir = path.resolve(out);
             const pages = await listHtmlFiles(outDir);
+            const { byPath: lastmodByPath, shallowClone } = await resolveLastmods(site.root, pages);
+            if (shallowClone) {
+                console.warn("warning: this checkout is a shallow git clone, so a page's last commit date cannot " +
+                    "be trusted (every untouched page would report the same boundary date); " +
+                    "sitemap.xml is written without <lastmod>");
+            }
             await writeFile(path.join(outDir, "sitemap.xml"), sitemapXml(site.settings.siteUrl, pages, {
                 ...(site.settings.lang === undefined ? {} : { lang: site.settings.lang }),
                 ...(site.settings.alternates === undefined ? {} : { alternates: site.settings.alternates }),
-            }), "utf8");
+            }, lastmodByPath), "utf8");
             await writeFile(path.join(outDir, "robots.txt"), robotsTxt(site.settings.siteUrl), "utf8");
             console.log(`canopy-page: sitemap.xml with ${pages.length} page(s)`);
         }

package/dist/lastmod.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Whether the repository containing `cwd` is a shallow clone.
+ *
+ * A shallow clone's history stops at an arbitrary boundary commit. A page last
+ * touched before that boundary reports the boundary commit's date instead of
+ * its own — so every such page would carry the same `<lastmod>`, which reads
+ * to a crawler as "all of these changed together" when in fact none of them
+ * did. That false agreement is worse than publishing nothing.
+ */
+export declare function isShallowClone(cwd: string): Promise<boolean>;
+/** Every page a `<lastmod>` could be found for, and whether it was suppressed for being unsafe to trust. */
+export interface Lastmods {
+    /** htmlPath → date, for pages a date was found for. */
+    byPath: Record<string, string>;
+    /** True when dates were withheld entirely because the clone is shallow. */
+    shallowClone: boolean;
+}
+/**
+ * Resolve `<lastmod>` for each published page.
+ *
+ * `htmlPaths` are site paths as `listHtmlFiles` returns them; each is mapped
+ * back to the source markdown `toSitePath` produced it from
+ * (`toSitePath`'s only transform is `.md` → `.html`, so the inverse is exact).
+ * A path with no such source — canopy's synthetic root `index.html` when a
+ * site has none of its own — is left out rather than guessed at.
+ */
+export declare function resolveLastmods(siteRoot: string, htmlPaths: readonly string[]): Promise<Lastmods>;

package/dist/lastmod.js

@@ -0,0 +1,98 @@
+import { execFile } from "node:child_process";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { promisify } from "node:util";
+import { parseFrontmatter } from "@iyulab/canopy";
+const execFileAsync = promisify(execFile);
+/**
+ * Resolving each page's `<lastmod>`.
+ *
+ * A sitemap's `<lastmod>` is a claim about when a page actually changed, and a
+ * wrong claim is worse than none: a crawler that trusts a stale or fabricated
+ * date has no reason to revisit a page that did change. The only two sources
+ * honest enough to publish are a page's own frontmatter, when the author named
+ * a date, and its source markdown's last git commit otherwise. Anything else —
+ * a file's mtime, the build's own clock — describes the filesystem or the
+ * build, not the page.
+ */
+/** A YAML scalar that plausibly names a calendar date, in either form the `yaml` parser hands back. */
+function asDateString(value) {
+    if (value instanceof Date)
+        return value.toISOString().slice(0, 10);
+    if (typeof value === "string" && /^\d{4}-\d{2}-\d{2}/.test(value))
+        return value.slice(0, 10);
+    return undefined;
+}
+/** A page's own `updated:` frontmatter date, when it names one. */
+async function frontmatterUpdated(absPath) {
+    let raw;
+    try {
+        raw = await readFile(absPath, "utf8");
+    }
+    catch {
+        // No source file at this path — canopy's synthetic root index.html, or a
+        // page whose source moved. Nothing to read frontmatter from.
+        return undefined;
+    }
+    return asDateString(parseFrontmatter(raw).data.updated);
+}
+/** The date (YYYY-MM-DD) git last recorded a change to `file`, or undefined when it has none. */
+async function lastCommitDate(file, cwd) {
+    try {
+        const { stdout } = await execFileAsync("git", ["log", "-1", "--format=%cs", "--", file], {
+            cwd,
+        });
+        const date = stdout.trim();
+        return date === "" ? undefined : date;
+    }
+    catch {
+        // Not a git repository, or the file is untracked — indistinguishable from
+        // here, and both mean the same thing: no date to publish.
+        return undefined;
+    }
+}
+/**
+ * Whether the repository containing `cwd` is a shallow clone.
+ *
+ * A shallow clone's history stops at an arbitrary boundary commit. A page last
+ * touched before that boundary reports the boundary commit's date instead of
+ * its own — so every such page would carry the same `<lastmod>`, which reads
+ * to a crawler as "all of these changed together" when in fact none of them
+ * did. That false agreement is worse than publishing nothing.
+ */
+export async function isShallowClone(cwd) {
+    try {
+        const { stdout } = await execFileAsync("git", ["rev-parse", "--is-shallow-repository"], {
+            cwd,
+        });
+        return stdout.trim() === "true";
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Resolve `<lastmod>` for each published page.
+ *
+ * `htmlPaths` are site paths as `listHtmlFiles` returns them; each is mapped
+ * back to the source markdown `toSitePath` produced it from
+ * (`toSitePath`'s only transform is `.md` → `.html`, so the inverse is exact).
+ * A path with no such source — canopy's synthetic root `index.html` when a
+ * site has none of its own — is left out rather than guessed at.
+ */
+export async function resolveLastmods(siteRoot, htmlPaths) {
+    if (await isShallowClone(siteRoot)) {
+        return { byPath: {}, shallowClone: true };
+    }
+    const byPath = {};
+    for (const htmlPath of htmlPaths) {
+        if (!htmlPath.toLowerCase().endsWith(".html"))
+            continue;
+        const mdPath = htmlPath.replace(/\.html$/i, ".md");
+        const fromFrontmatter = await frontmatterUpdated(path.join(siteRoot, mdPath));
+        const date = fromFrontmatter ?? (await lastCommitDate(mdPath, siteRoot));
+        if (date !== undefined)
+            byPath[htmlPath] = date;
+    }
+    return { byPath, shallowClone: false };
+}

package/dist/sitemap.d.ts

@@ -12,8 +12,13 @@ export interface SitemapEditions {
  * edition, this one included — the sitemap form of the `hreflang` links the
  * pages themselves carry, and the same rule: this edition leads unless the map
  * already places its language explicitly.
+ *
+ * `lastmodByPath` supplies each page's `<lastmod>` by its own htmlPath
+ * (`resolveLastmods` builds this map); a page missing from it — no source
+ * file, or one git has no record of — is written without the element rather
+ * than with a guessed date.
  */
-export declare function sitemapXml(siteUrl: string, htmlPaths: readonly string[], editions?: SitemapEditions): string;
+export declare function sitemapXml(siteUrl: string, htmlPaths: readonly string[], editions?: SitemapEditions, lastmodByPath?: Readonly<Record<string, string>>): string;
 /**
  * A robots file whose only job is to point at the sitemap.
  *

package/dist/sitemap.js

@@ -37,8 +37,13 @@ function escapeXml(value) {
  * edition, this one included — the sitemap form of the `hreflang` links the
  * pages themselves carry, and the same rule: this edition leads unless the map
  * already places its language explicitly.
+ *
+ * `lastmodByPath` supplies each page's `<lastmod>` by its own htmlPath
+ * (`resolveLastmods` builds this map); a page missing from it — no source
+ * file, or one git has no record of — is written without the element rather
+ * than with a guessed date.
  */
-export function sitemapXml(siteUrl, htmlPaths, editions = {}) {
+export function sitemapXml(siteUrl, htmlPaths, editions = {}, lastmodByPath = {}) {
     const editionList = [];
     if (editions.alternates !== undefined) {
         const lang = editions.lang ?? "en";
@@ -49,10 +54,12 @@ export function sitemapXml(siteUrl, htmlPaths, editions = {}) {
     const entries = [...htmlPaths]
         .sort()
         .map((htmlPath) => {
+        const lastmod = lastmodByPath[htmlPath];
+        const lastmodTag = lastmod === undefined ? "" : `<lastmod>${escapeXml(lastmod)}</lastmod>`;
         const alternates = editionList
             .map(([hreflang, base]) => `<xhtml:link rel="alternate" hreflang="${escapeXml(hreflang)}" href="${escapeXml(pageUrl(base, htmlPath))}"/>`)
             .join("");
-        return `  <url><loc>${escapeXml(pageUrl(siteUrl, htmlPath))}</loc>${alternates}</url>`;
+        return `  <url><loc>${escapeXml(pageUrl(siteUrl, htmlPath))}</loc>${lastmodTag}${alternates}</url>`;
     })
         .join("\n");
     const xhtmlNamespace = editionList.length > 0 ? ' xmlns:xhtml="http://www.w3.org/1999/xhtml"' : "";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iyulab/canopy-page",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "Authoring pipeline for documentation sites: one settings file, integrity checks, and a build.",
   "type": "module",
   "license": "MIT",