@dmthepm/commune 0.2.0 → 0.3.0

package/lib/integration.js

@@ -11,7 +11,7 @@
 import { copyFile, writeFile, mkdir } from 'node:fs/promises';
 import { fileURLToPath } from 'node:url';
 import path from 'node:path';
-import { buildGraph, formatDiagnostic, loadContentEntries, toBacklinksJson, toMarkdownPath, } from "./lib/graph.js";
+import { buildGraph, formatDiagnostic, loadContentEntries, summarizeSite, toBacklinksJson, toMarkdownPath, } from "./lib/graph.js";
 function buildBacklinksGraph(entries, logger) {
     const graph = buildGraph(entries);
     logger.info(`📝 Found ${Object.keys(graph.nodes).length} public content entries`);
@@ -24,9 +24,24 @@ function buildBacklinksGraph(entries, logger) {
     }
     return graph;
 }
-async function writeBacklinksFile(filePath, graph) {
+async function writeJsonFile(filePath, value) {
     await mkdir(path.dirname(filePath), { recursive: true });
-    await writeFile(filePath, JSON.stringify(graph, null, 2) + '\n');
+    await writeFile(filePath, JSON.stringify(value, null, 2) + '\n');
+}
+async function writeBacklinksFile(filePath, graph) {
+    await writeJsonFile(filePath, graph);
+}
+/**
+ * The site-wide summary, beside the graph rather than inside it.
+ *
+ * `backlinks.json` is keyed by urlPath and two of its readers walk it with
+ * `Object.entries`, so a top-level `lastUpdated` there would be a malformed
+ * node rather than a new field. It is also committed, and this value changes
+ * on the same commit that changes it — a committed copy is stale exactly when
+ * it matters. So: a sibling file, generated, gitignored.
+ */
+async function writeSiteFile(filePath, summary) {
+    await writeJsonFile(filePath, summary);
 }
 /**
  * Copy every entry's source file next to its rendered page, at `<url>.md`.
@@ -60,6 +75,7 @@ export default function commune(_options = {}) {
     // one process do not overwrite each other's roots.
     let root;
     let publicBacklinks;
+    let publicSite;
     return {
         name: 'commune-backlinks',
         hooks: {
@@ -74,9 +90,12 @@ export default function commune(_options = {}) {
                 // `fileURLToPath` is what Astro's own docs use.
                 root = fileURLToPath(config.root);
                 publicBacklinks = fileURLToPath(new URL('./backlinks.json', config.publicDir));
+                publicSite = fileURLToPath(new URL('./site.json', config.publicDir));
                 try {
-                    const graph = buildBacklinksGraph(await loadContentEntries({ root }), logger);
+                    const entries = await loadContentEntries({ root });
+                    const graph = buildBacklinksGraph(entries, logger);
                     await writeBacklinksFile(publicBacklinks, toBacklinksJson(graph));
+                    await writeSiteFile(publicSite, summarizeSite(entries));
                     logger.info(`✅ Backlinks index written to ${path.relative(root, publicBacklinks)}`);
                     logger.info(summarize(graph));
                 }
@@ -95,10 +114,16 @@ export default function commune(_options = {}) {
                     await writeBacklinksFile(fileURLToPath(new URL('./backlinks.json', dir)), json);
                     // Also written to the public directory, for dev server parity.
                     await writeBacklinksFile(publicBacklinks, json);
+                    const site = summarizeSite(entries);
+                    await writeSiteFile(fileURLToPath(new URL('./site.json', dir)), site);
+                    await writeSiteFile(publicSite, site);
                     const written = await writeMarkdownFiles(entries, root, fileURLToPath(dir));
                     logger.info(`✅ Backlinks index written to /backlinks.json (dist + public)`);
                     logger.info(`📄 ${written} source files written as .md alongside their pages`);
                     logger.info(summarize(graph));
+                    logger.info(site.lastUpdated
+                        ? `🕒 Site last updated ${site.lastUpdated} (${site.lastUpdatedPath}, from ${site.lastUpdatedSource})`
+                        : '🕒 No entry carries a date, so site.json has no lastUpdated');
                 }
                 catch (error) {
                     logger.error('❌ Failed to build backlinks index:');

package/lib/lib/dates.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Where a content entry's dates come from when nobody wrote them down.
+ *
+ * `updated:` in frontmatter is a hand-maintained field, and a hand-maintained
+ * field is only true while somebody remembers to maintain it. The repository
+ * already knows the answer — a file's last commit *is* the day it last
+ * changed — so this module reads it from there and the graph prefers
+ * frontmatter only when frontmatter exists.
+ *
+ * Three rules the rest of the engine depends on:
+ *
+ *   - **One walk, not one process per file.** `git log --name-only` over the
+ *     content directories yields every file's whole history in a single
+ *     child process. A vault has hundreds of notes; spawning `git` for each
+ *     one turns a build into a minute of process creation.
+ *   - **A shallow clone has no dates to give.** `actions/checkout` fetches
+ *     depth 1 by default, and in that tree every file's "first and last
+ *     commit" is the same single commit — the day of the build. That is not a
+ *     worse date, it is a false one, and it would be false on every entry at
+ *     once. So a shallow checkout produces no derived dates at all, and says
+ *     so once on stderr.
+ *   - **Never fatal, and never a guess dressed as a fact.** A tree that is not
+ *     in a repository at all falls back to file mtimes. A tree that *is* in one
+ *     never does: inside a checkout an mtime is the day the files were written
+ *     to disk, which on CI is the day of the build and on a fresh clone is
+ *     today, so it would launder the same falsehood the shallow rule exists to
+ *     refuse.
+ */
+/**
+ * How an entry's `updated` was decided, so a site can show the honest one.
+ *
+ * `frontmatter` is an author's claim, `git` is the repository's record,
+ * `mtime` is the filesystem's guess in a directory with no repository around
+ * it, and `none` means nothing could answer — an uncommitted file, or any file
+ * in a shallow checkout.
+ */
+export type DateSource = 'frontmatter' | 'git' | 'mtime' | 'none';
+/** The first and last commit dates of one file, as `yyyy-mm-dd`. */
+export interface FileHistory {
+    /** Date of the file's most recent commit. */
+    updated: string;
+    /** Date of the file's oldest commit. */
+    created: string;
+}
+/**
+ * What the project's history can and cannot answer.
+ *
+ * Three states, because the two failures are not the same failure and the
+ * graph has to treat them differently. `unversioned` means no repository, and
+ * an mtime is the best honest answer available. `shallow` means a repository
+ * whose history was truncated, where both a commit date and an mtime would say
+ * "today" about every file at once.
+ */
+export type HistoryKind = 'history' | 'shallow' | 'unversioned';
+export interface ContentHistory {
+    kind: HistoryKind;
+    /** Keyed by root-relative file path. Empty unless `kind` is `history`. */
+    files: Map<string, FileHistory>;
+}
+/**
+ * Said once, on stderr, when a build or a query runs in a truncated checkout.
+ *
+ * On stderr rather than in `Graph.diagnostics` because it is not a finding
+ * about anyone's content — it is a fact about the environment the command ran
+ * in, and the person who needs it is reading a build log. stderr also keeps it
+ * out of the way of `--json`, whose stdout carries one document and nothing
+ * else.
+ */
+export declare const SHALLOW_WARNING: string;
+/** Test seam: forget which roots have been warned about. */
+export declare function resetShallowWarnings(): void;
+/** A local calendar day as `yyyy-mm-dd`.
+ *
+ * The one spelling of "what day is it" in the engine. Local rather than UTC on
+ * purpose, and shared rather than reimplemented: `git log --date=short` renders
+ * a commit in its own recorded timezone — the committer's local day — so an
+ * mtime, a `--recent 7d` cutoff and the date a scaffolded update is filed under
+ * all have to be local days too, or the four would disagree for the hours
+ * either side of midnight.
+ */
+export declare function toIsoDay(date: Date): string;
+/**
+ * Every content file's first and last commit date, from one `git log` walk.
+ *
+ * `--relative` (with the child process's cwd set to `root`) is what keeps the
+ * returned paths in the same spelling `ContentEntry.file` uses: a project root
+ * nested inside a larger repository would otherwise get repository-relative
+ * paths back and match nothing. `core.quotePath=false` keeps non-ASCII
+ * filenames literal — notes are named for their titles, and titles have
+ * accents.
+ *
+ * `%D` rides along on each commit line as the second belt: `rev-parse` has
+ * already answered whether the repository is shallow, and a walk that reaches
+ * the grafted boundary anyway says the same thing from the other direction.
+ * Either one means the same commit stands in for every commit before it, so
+ * neither the dates nor a first-commit `created` can be trusted.
+ */
+export declare function readContentHistory(root: string, dirs: string[]): Promise<ContentHistory>;
+/** A file's modification time as a local `yyyy-mm-dd`, or `undefined` if unreadable. */
+export declare function readMtimeDate(root: string, file: string): Promise<string | undefined>;

package/lib/lib/dates.js

@@ -0,0 +1,182 @@
+/**
+ * Where a content entry's dates come from when nobody wrote them down.
+ *
+ * `updated:` in frontmatter is a hand-maintained field, and a hand-maintained
+ * field is only true while somebody remembers to maintain it. The repository
+ * already knows the answer — a file's last commit *is* the day it last
+ * changed — so this module reads it from there and the graph prefers
+ * frontmatter only when frontmatter exists.
+ *
+ * Three rules the rest of the engine depends on:
+ *
+ *   - **One walk, not one process per file.** `git log --name-only` over the
+ *     content directories yields every file's whole history in a single
+ *     child process. A vault has hundreds of notes; spawning `git` for each
+ *     one turns a build into a minute of process creation.
+ *   - **A shallow clone has no dates to give.** `actions/checkout` fetches
+ *     depth 1 by default, and in that tree every file's "first and last
+ *     commit" is the same single commit — the day of the build. That is not a
+ *     worse date, it is a false one, and it would be false on every entry at
+ *     once. So a shallow checkout produces no derived dates at all, and says
+ *     so once on stderr.
+ *   - **Never fatal, and never a guess dressed as a fact.** A tree that is not
+ *     in a repository at all falls back to file mtimes. A tree that *is* in one
+ *     never does: inside a checkout an mtime is the day the files were written
+ *     to disk, which on CI is the day of the build and on a fresh clone is
+ *     today, so it would launder the same falsehood the shallow rule exists to
+ *     refuse.
+ */
+import { execFile } from 'node:child_process';
+import { stat } from 'node:fs/promises';
+import path from 'node:path';
+import { promisify } from 'node:util';
+const run = promisify(execFile);
+/**
+ * Said once, on stderr, when a build or a query runs in a truncated checkout.
+ *
+ * On stderr rather than in `Graph.diagnostics` because it is not a finding
+ * about anyone's content — it is a fact about the environment the command ran
+ * in, and the person who needs it is reading a build log. stderr also keeps it
+ * out of the way of `--json`, whose stdout carries one document and nothing
+ * else.
+ */
+export const SHALLOW_WARNING = 'git history is shallow: dates come from frontmatter only. ' +
+    'Fetch full history (fetch-depth: 0 / unshallow) to derive dates from commits.';
+/** One warning per project root per process, however many times the graph is loaded. */
+const warned = new Set();
+function warnShallow(root) {
+    const key = path.resolve(root);
+    if (warned.has(key))
+        return;
+    warned.add(key);
+    process.stderr.write(`${SHALLOW_WARNING}\n`);
+}
+/** Test seam: forget which roots have been warned about. */
+export function resetShallowWarnings() {
+    warned.clear();
+}
+/** A local calendar day as `yyyy-mm-dd`.
+ *
+ * The one spelling of "what day is it" in the engine. Local rather than UTC on
+ * purpose, and shared rather than reimplemented: `git log --date=short` renders
+ * a commit in its own recorded timezone — the committer's local day — so an
+ * mtime, a `--recent 7d` cutoff and the date a scaffolded update is filed under
+ * all have to be local days too, or the four would disagree for the hours
+ * either side of midnight.
+ */
+export function toIsoDay(date) {
+    const month = String(date.getMonth() + 1).padStart(2, '0');
+    const day = String(date.getDate()).padStart(2, '0');
+    return `${date.getFullYear()}-${month}-${day}`;
+}
+/** Is this root a shallow checkout, a full one, or not a repository at all? */
+async function classify(root) {
+    try {
+        const { stdout } = await run('git', ['rev-parse', '--is-shallow-repository'], { cwd: root });
+        return stdout.trim() === 'true' ? 'shallow' : 'history';
+    }
+    catch {
+        // Not a repository, or no `git` on the PATH. The flag itself is not in
+        // question: it has shipped since git 2.15 (2017).
+        return 'unversioned';
+    }
+}
+/**
+ * Every content file's first and last commit date, from one `git log` walk.
+ *
+ * `--relative` (with the child process's cwd set to `root`) is what keeps the
+ * returned paths in the same spelling `ContentEntry.file` uses: a project root
+ * nested inside a larger repository would otherwise get repository-relative
+ * paths back and match nothing. `core.quotePath=false` keeps non-ASCII
+ * filenames literal — notes are named for their titles, and titles have
+ * accents.
+ *
+ * `%D` rides along on each commit line as the second belt: `rev-parse` has
+ * already answered whether the repository is shallow, and a walk that reaches
+ * the grafted boundary anyway says the same thing from the other direction.
+ * Either one means the same commit stands in for every commit before it, so
+ * neither the dates nor a first-commit `created` can be trusted.
+ */
+export async function readContentHistory(root, dirs) {
+    const kind = await classify(root);
+    if (kind !== 'history') {
+        if (kind === 'shallow')
+            warnShallow(root);
+        return { kind, files: new Map() };
+    }
+    let stdout;
+    try {
+        ({ stdout } = await run('git', [
+            '-c',
+            'core.quotePath=false',
+            'log',
+            // A NUL before each commit, then its date and its decoration: no
+            // line of this can be confused with a filename, whatever a file is
+            // called.
+            '--format=%x00%cd%x09%D',
+            '--date=short',
+            '--name-only',
+            '--relative',
+            '--',
+            ...dirs,
+        ], { cwd: root, maxBuffer: 64 * 1024 * 1024 }));
+    }
+    catch {
+        // A repository the walk cannot read — most often one with no commits yet.
+        // Still a repository, so still not a place to reach for an mtime: it has
+        // nothing to say, and `none` is what "nothing to say" looks like.
+        return { kind: 'history', files: new Map() };
+    }
+    const files = new Map();
+    // `git log` walks newest first, so the first sighting of a file is its last
+    // commit and every later sighting is an older one.
+    for (const commit of stdout.split('\u0000')) {
+        const [header, ...lines] = commit.split('\n');
+        const [date, decoration = ''] = header.split('\t');
+        if (!/^\d{4}-\d{2}-\d{2}$/.test(date))
+            continue;
+        if (decoration.includes('grafted')) {
+            warnShallow(root);
+            return { kind: 'shallow', files: new Map() };
+        }
+        for (const line of lines) {
+            if (!line)
+                continue;
+            const file = unquotePath(line);
+            const seen = files.get(file);
+            if (seen)
+                seen.created = date;
+            else
+                files.set(file, { updated: date, created: date });
+        }
+    }
+    return { kind: 'history', files };
+}
+/**
+ * Undo git's C-style quoting of a path.
+ *
+ * With `core.quotePath=false` only paths containing a quote, a backslash or a
+ * control character are quoted at all, and JSON's escapes cover those. A path
+ * git quoted some other way is returned as git printed it: a filename that odd
+ * is better shown verbatim than silently mangled by a guess.
+ */
+function unquotePath(line) {
+    if (!line.startsWith('"'))
+        return line;
+    try {
+        return JSON.parse(line);
+    }
+    catch {
+        return line;
+    }
+}
+/** A file's modification time as a local `yyyy-mm-dd`, or `undefined` if unreadable. */
+export async function readMtimeDate(root, file) {
+    try {
+        const stats = await stat(path.join(root, file));
+        return toIsoDay(stats.mtime);
+    }
+    catch {
+        return undefined;
+    }
+}

package/lib/lib/graph.d.ts

@@ -8,18 +8,27 @@
  * rules, and three subtly different opinions about trailing slashes.
  *
  * The rules this module owns:
- *   - which collections participate (notes, research, pages)
- *   - visibility (notes opt in with `visibility: public`; research and pages
- *     are always public)
+ *   - which collections participate (notes, research, pages, updates)
+ *   - visibility (notes opt in with `visibility: public`; research, pages and
+ *     updates are always public)
  *   - canonical URLs, always with a trailing slash, matching Astro's
  *     directory build format
  *   - the title/alias lookup used to resolve `[[WikiLinks]]`
  *   - which link forms count as an edge, and how each one resolves
  */
-export type CollectionName = 'notes' | 'research' | 'pages';
+import { type DateSource } from './dates.ts';
+export type { ContentHistory, DateSource, HistoryKind } from './dates.ts';
+export { SHALLOW_WARNING, toIsoDay } from './dates.ts';
+export type CollectionName = 'notes' | 'research' | 'pages' | 'updates';
 /** Where each collection's markdown lives, relative to the project root. */
 export declare const CONTENT_DIRS: Record<CollectionName, string>;
-/** Collection scan order. Stable so derived artifacts are deterministic. */
+/**
+ * Collection scan order. Stable so derived artifacts are deterministic.
+ *
+ * `updates` is last because it was added last, and the order is the order
+ * `backlinks.json` is keyed in: putting it anywhere else would rewrite the
+ * whole committed artifact to say the same thing.
+ */
 export declare const COLLECTIONS: CollectionName[];
 /** One piece of public content, as the graph sees it. */
 export interface ContentEntry {
@@ -33,7 +42,28 @@ export interface ContentEntry {
     tags: string[];
     status: string;
     summary?: string;
+    /**
+     * When this entry last changed, by the best answer available.
+     *
+     * Frontmatter wins when an author wrote one down; otherwise the file's
+     * last commit date, and in a tree with no history its mtime. `updatedSource`
+     * says which of those this is, so a site can decide whether to show it.
+     */
     updated?: string;
+    /** Which of the three answers `updated` is. */
+    updatedSource: DateSource;
+    /** When this entry first appeared, by the same precedence as `updated`. */
+    created?: string;
+    /**
+     * The date of the file's last commit, whatever `updated` ended up being.
+     *
+     * Carried separately so a site can show both — "updated 2026-01-21, last
+     * touched 2026-09-03" is the sentence that catches a stale `updated:` field,
+     * and it cannot be written if the two dates have already been collapsed
+     * into one. Absent when the project is not a git checkout, or when the file
+     * has never been committed.
+     */
+    modifiedInGit?: string;
     /** Markdown body with frontmatter stripped. */
     body: string;
     /** Parsed frontmatter. Kept because links can live in it. */
@@ -93,6 +123,15 @@ export declare function toMarkdownPath(urlPath: string): string;
 export declare function toMarkdownHref(urlPath: string): string;
 /** Coerce a frontmatter date to `yyyy-mm-dd`, so build output has no timestamp drift. */
 export declare function normalizeDate(value: unknown): string | undefined;
+/**
+ * The date an author wrote down, if they wrote one down.
+ *
+ * `updated` first, then `date` — the key the changelog-shaped collections use,
+ * where the entry *is* a dated thing rather than a page that happens to have
+ * been edited. Kept as one function so the graph, `--recent` and the site-wide
+ * last-updated value can never disagree about what an author claimed.
+ */
+export declare function claimedDate(data: Record<string, unknown>): string | undefined;
 /** Where to read content from. */
 export interface GraphOptions {
     /**
@@ -251,6 +290,7 @@ export interface NoteMetadata {
     tags: string[];
     status: string;
     summary?: string;
+    /** The author's claimed date. Not the resolved one — see `buildGraph`. */
     updated?: string;
     isStarred?: boolean;
 }
@@ -311,6 +351,48 @@ export declare function buildGraph(entries: ContentEntry[]): Graph;
  * as it was when the integration formatted it itself.
  */
 export declare function formatDiagnostic(diagnostic: Diagnostic): string;
+/**
+ * What the whole site says about itself, as one small object.
+ *
+ * Written to `site.json` beside `backlinks.json`, and deliberately not *into*
+ * it. Two reasons, and either alone would settle it:
+ *
+ *   - Every top-level key of `backlinks.json` is a urlPath. Two of its readers
+ *     walk it with `Object.entries` and treat what they find as a node, so a
+ *     `lastUpdated` string at the top level is not a new field — it is a
+ *     malformed entry in a runtime contract.
+ *   - `backlinks.json` is committed, and this value moves with history: it
+ *     changes on the commit that changes it, so a committed copy is stale the
+ *     moment it is right. `site.json` is generated and ignored, like `dist/`.
+ */
+export interface SiteSummary {
+    /** The newest `updated` across every public entry. Absent if nothing has a date. */
+    lastUpdated?: string;
+    /** The entry that date belongs to, so a page can link to what changed. */
+    lastUpdatedPath?: string;
+    /** Where that date came from — an author's claim, git, or an mtime. */
+    lastUpdatedSource?: DateSource;
+    /**
+     * The newest commit date across every entry, whatever the entries claim.
+     *
+     * `lastUpdated` obeys frontmatter, because an author who writes a date down
+     * means it. This does not, and the pair is the point: when they disagree,
+     * the wiki changed on a day nobody wrote down, and a site can say so
+     * instead of quietly showing the older number.
+     */
+    lastModifiedInGit?: string;
+    /** How many public entries the site has. */
+    entries: number;
+}
+/**
+ * The newest change across the whole site, and which entry it was.
+ *
+ * "When did this wiki last change" is not the same question as "when did this
+ * page last change", and a home page that answers the second while appearing
+ * to answer the first is the bug this ticket opened on. Ties go to the entry
+ * scanned first, which is stable because the scan is.
+ */
+export declare function summarizeSite(entries: ContentEntry[]): SiteSummary;
 /**
  * The public artifact, exactly as `public/backlinks.json` stores it.
  *