@dmthepm/commune 0.2.0 → 0.4.0

package/lib/lib/graph.js

@@ -8,9 +8,9 @@
  * 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]]`
@@ -21,14 +21,23 @@ import { slug as githubSlug } from 'github-slugger';
 import matter from 'gray-matter';
 import { readFile } from 'node:fs/promises';
 import path from 'node:path';
+import { readContentHistory, readMtimeDate, } from "./dates.js";
+export { SHALLOW_WARNING, toIsoDay } from "./dates.js";
 /** Where each collection's markdown lives, relative to the project root. */
 export const CONTENT_DIRS = {
     notes: 'src/content/notes',
     research: 'src/content/research',
     pages: 'src/content/pages',
+    updates: 'src/content/updates',
 };
-/** Collection scan order. Stable so derived artifacts are deterministic. */
-export const COLLECTIONS = ['notes', 'research', 'pages'];
+/**
+ * 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 const COLLECTIONS = ['notes', 'research', 'pages', 'updates'];
 /**
  * Convert a content file path to its collection-relative slug and canonical URL.
  *
@@ -117,7 +126,64 @@ export function normalizeDate(value) {
         return value.split('T')[0];
     return undefined;
 }
-/** Is this entry publicly visible? Notes opt in; research and pages are always public. */
+/**
+ * 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 function claimedDate(data) {
+    return normalizeDate(data.updated) ?? normalizeDate(data.date);
+}
+/**
+ * Decide an entry's dates, and say where the answer came from.
+ *
+ * Precedence, for both `created` and `updated`: what the author wrote, then
+ * what the repository records, then — only outside a repository — the file's
+ * mtime. The first is a claim and can be years stale; the second is a fact
+ * about the file and is what the ticket asked for; the third exists so a
+ * developer's unversioned folder produces dates instead of blanks.
+ *
+ * What is deliberately *not* here is a fourth fallback. Inside a shallow
+ * checkout there is no honest date to be had — every file's only commit is the
+ * one the CI runner fetched, and every file's mtime is the moment it was
+ * written to disk — so both are refused and `updatedSource` says `none`. A
+ * missing date a site can decline to render; a wrong one it renders
+ * confidently. The same goes for a file that has never been committed.
+ *
+ * `updatedSource` is reported and `createdSource` is not, deliberately: the
+ * date a site displays and a reader judges is `updated`, and one honest label
+ * beside it is worth more than two labels nobody reads. `created` follows the
+ * same precedence, and `modifiedInGit` is carried whenever git knew the file,
+ * so anything that needs to audit the pair has both halves.
+ */
+async function resolveDates(root, file, data, history) {
+    const claimed = claimedDate(data);
+    const createdClaim = normalizeDate(data.created);
+    const committed = history.files.get(file);
+    // Read once, and only where an mtime is an answer at all: a versioned tree
+    // never stats a file, and a complete vault outside one never stats twice.
+    let mtime;
+    const fileMtime = async () => history.kind === 'unversioned' ? (mtime ??= await readMtimeDate(root, file)) : undefined;
+    const updated = claimed ?? committed?.updated ?? (await fileMtime());
+    const created = createdClaim ?? committed?.created ?? (await fileMtime());
+    const updatedSource = claimed
+        ? 'frontmatter'
+        : committed
+            ? 'git'
+            : updated
+                ? 'mtime'
+                : 'none';
+    return {
+        ...(updated ? { updated } : {}),
+        updatedSource,
+        ...(created ? { created } : {}),
+        ...(committed ? { modifiedInGit: committed.updated } : {}),
+    };
+}
+/** Is this entry publicly visible? Notes opt in; every other collection is public. */
 function isPublic(collection, data) {
     if (collection !== 'notes')
         return true;
@@ -136,6 +202,9 @@ function isPublic(collection, data) {
 export async function loadContentEntries(options = {}) {
     const root = options.root ?? process.cwd();
     const entries = [];
+    // One walk for the whole vault, before the scan rather than inside it: the
+    // alternative is a `git log` per file, which is a child process per note.
+    const history = await readContentHistory(root, Object.values(CONTENT_DIRS));
     for (const collection of COLLECTIONS) {
         // `cwd` keeps globby's results root-relative, which is exactly the
         // spelling `ContentEntry.file` promises; only the read needs the join.
@@ -148,7 +217,7 @@ export async function loadContentEntries(options = {}) {
                 continue;
             const { slug, urlPath } = toUrlPath(file, collection, data);
             const summary = typeof data.summary === 'string' ? data.summary : undefined;
-            const updated = normalizeDate(data.updated);
+            const dates = await resolveDates(root, file, data, history);
             entries.push({
                 slug,
                 urlPath,
@@ -158,7 +227,7 @@ export async function loadContentEntries(options = {}) {
                 tags: data.tags || [],
                 status: data.status || 'seed',
                 ...(summary ? { summary } : {}),
-                ...(updated ? { updated } : {}),
+                ...dates,
                 body: content,
                 frontmatter: data,
                 file,
@@ -298,6 +367,17 @@ export function stripCode(content) {
 }
 /** Frontmatter keys whose values are vocabulary, not links. */
 const NON_LINK_KEYS = new Set(['aliases', 'tags']);
+/**
+ * Frontmatter keys whose strings are link targets in their own right.
+ *
+ * Everywhere else in frontmatter a link has to be spelled `[[like this]]`,
+ * because a bare string is usually prose and guessing otherwise would turn a
+ * page's own `url:` into a self-edge. Under `links:` the guess is the whole
+ * point: an update declares the pages it rolls up, and writing them as
+ * `[[double brackets]]` inside a YAML list is ceremony for a field that means
+ * nothing else.
+ */
+const LINK_KEYS = new Set(['links']);
 /**
  * Extract every outbound link target from a markdown body and its frontmatter.
  *
@@ -333,27 +413,34 @@ export function extractLinks(content, frontmatter = {}) {
  */
 function extractFrontmatterLinks(frontmatter) {
     const links = [];
-    const walk = (value) => {
+    const walk = (value, bare) => {
         if (typeof value === 'string') {
             for (const match of value.matchAll(WIKILINK)) {
                 const target = stripSubpath(match[1]);
                 if (target)
                     links.push({ kind: 'name', target });
             }
+            // A string that already spelled its link is not also a bare target.
+            if (bare && !value.includes('[[')) {
+                const link = classifyFrontmatterTarget(value);
+                if (link)
+                    links.push(link);
+            }
         }
         else if (Array.isArray(value)) {
-            value.forEach(walk);
+            for (const nested of value)
+                walk(nested, bare);
         }
         else if (value && typeof value === 'object') {
             for (const [key, nested] of Object.entries(value)) {
                 if (!NON_LINK_KEYS.has(key))
-                    walk(nested);
+                    walk(nested, bare || LINK_KEYS.has(key));
             }
         }
     };
     for (const [key, value] of Object.entries(frontmatter)) {
         if (!NON_LINK_KEYS.has(key))
-            walk(value);
+            walk(value, LINK_KEYS.has(key));
     }
     return links;
 }
@@ -376,6 +463,26 @@ const MARKDOWN_LINK = /!?\[[^\]]*\]\(\s*(<[^>]*>|[^()\s]+)(?:\s+"[^"]*")?\s*\)/g
  * handed to the title lookup, where it only ever resolved by the coincidence of
  * a note listing its own slug as an alias.
  */
+/**
+ * Classify one bare string from a `links:` list.
+ *
+ * A site path is a `url` link, a filename is the file's title, and anything
+ * else is read as a title — the same two namespaces every other edge resolves
+ * through, so `check` reports an unresolvable entry here exactly as it reports
+ * a broken `[[WikiLink]]`. External URLs are not edges, as everywhere else.
+ */
+function classifyFrontmatterTarget(raw) {
+    const value = raw.trim();
+    if (!value)
+        return null;
+    if (/^[a-z][a-z0-9+.-]*:/i.test(value) || value.startsWith('//'))
+        return null;
+    const classified = classifyMarkdownTarget(value);
+    if (classified)
+        return classified;
+    const title = stripSubpath(value);
+    return title ? { kind: 'name', target: title } : null;
+}
 function classifyMarkdownTarget(raw) {
     const destination = raw.replace(/^<|>$/g, '').trim();
     // Anything with a scheme, and protocol-relative `//host`, leaves the site.
@@ -454,8 +561,10 @@ export const STAR_CONFIG = {
  */
 export function calculateStars(notes) {
     const starredSlugs = new Set();
-    // Standalone pages belong in search and WikiLinks, not note rankings.
-    const notesArray = Array.from(notes.values()).filter((note) => note.collection !== 'pages');
+    // Standalone pages and changelog updates belong in search and WikiLinks, not
+    // note rankings. An update links to everything it rolled up, so ranking it
+    // alongside notes would let the changelog crowd out the writing it describes.
+    const notesArray = Array.from(notes.values()).filter((note) => note.collection !== 'pages' && note.collection !== 'updates');
     // Skip if too few notes
     if (notesArray.length < STAR_CONFIG.minNotesForStars) {
         return starredSlugs;
@@ -540,6 +649,14 @@ export function buildGraph(entries) {
     for (const entry of entries) {
         extracted.set(entry.urlPath, extractLinks(entry.body, entry.frontmatter));
         files.set(entry.urlPath, entry.file);
+        // `updated` here is the author's claim, not the resolved date on the
+        // entry, and it stays that way on purpose. `backlinks.json` is committed,
+        // and a git-derived date cannot be committed alongside the commit that
+        // changes it: the file's new date does not exist until that commit does,
+        // so every content commit would land with the artifact already stale.
+        // The resolved date is on `ContentEntry`, in `graph query --json`, and in
+        // the build-time `site.json` — all of which are computed, not stored.
+        const claimed = claimedDate(entry.frontmatter);
         notes.set(entry.urlPath, {
             slug: entry.urlPath,
             title: entry.title,
@@ -550,7 +667,7 @@ export function buildGraph(entries) {
             tags: entry.tags,
             status: entry.status,
             ...(entry.summary ? { summary: entry.summary } : {}),
-            ...(entry.updated ? { updated: entry.updated } : {}),
+            ...(claimed ? { updated: claimed } : {}),
         });
     }
     const diagnostics = [];
@@ -579,7 +696,14 @@ export function buildGraph(entries) {
                 }
             }
             if (resolved && notes.has(resolved)) {
-                resolvedOutbound.push(resolved);
+                // One edge per target, not one per spelling. `[[World]]` in the body
+                // and `/notes/world/` under `links:` are the same edge written two
+                // ways, and an update names both — the prose says it and the
+                // frontmatter lists it. `inbound` has always been deduplicated;
+                // `outbound` reaching the same page twice was the same fact
+                // counted twice.
+                if (!resolvedOutbound.includes(resolved))
+                    resolvedOutbound.push(resolved);
                 const target = notes.get(resolved);
                 if (!target.inbound.includes(fromUrl)) {
                     target.inbound.push(fromUrl);
@@ -635,6 +759,36 @@ export function formatDiagnostic(diagnostic) {
     }
     return `⚠️  ${diagnostic.rule} in ${diagnostic.file}: ${diagnostic.message}`;
 }
+/**
+ * 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 function summarizeSite(entries) {
+    let newest;
+    let newestInGit;
+    for (const entry of entries) {
+        if (entry.updated && (!newest || entry.updated > newest.updated))
+            newest = entry;
+        if (entry.modifiedInGit && (!newestInGit || entry.modifiedInGit > newestInGit)) {
+            newestInGit = entry.modifiedInGit;
+        }
+    }
+    return {
+        ...(newest
+            ? {
+                lastUpdated: newest.updated,
+                lastUpdatedPath: newest.urlPath,
+                lastUpdatedSource: newest.updatedSource,
+            }
+            : {}),
+        ...(newestInGit ? { lastModifiedInGit: newestInGit } : {}),
+        entries: entries.length,
+    };
+}
 /**
  * The public artifact, exactly as `public/backlinks.json` stores it.
  *

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@dmthepm/commune",
   "type": "module",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "An Astro wiki engine with WikiLinks, sliding panes, backlinks and static search, plus a commune CLI that queries the content graph and checks links",
   "license": "MIT",
   "keywords": [

package/src/components/Updates.astro

@@ -0,0 +1,114 @@
+---
+/**
+ * The newest entries from the `updates` collection, as a card.
+ *
+ * A wiki's front door has to answer "what changed" before it answers anything
+ * else, and the answer is content the site already has: one dated entry per
+ * batch of work, in `src/content/updates/`. This renders the newest few.
+ *
+ * Everything happens at build time. There is no `fetch` here and no client
+ * script — unlike `Backlinks.astro`, which reads `/backlinks.json` in the
+ * browser because a note's inbound links depend on which note you are on. A
+ * changelog does not, so it is markup by the time the page is served, and it
+ * is in the HTML for a reader with no JavaScript and for anything that reads
+ * the page as a document.
+ *
+ * The collection has to be registered in the consumer's `src/content.config.ts`
+ * for `getCollection` to see it — the same requirement `notes` has. The schema
+ * this expects is in the README.
+ */
+
+import { getCollection } from 'astro:content';
+
+interface Props {
+	/** How many entries to show. */
+	limit?: number;
+	/** The card's heading. Passed rather than fixed, because a card that says
+	 *  "Recent updates" on the home page often wants to say nothing at all on
+	 *  the updates index itself. An empty string renders no heading. */
+	heading?: string;
+}
+
+const { limit = 5, heading = 'Recent updates' } = Astro.props;
+
+// `date` is the update's subject — the day the work happened — not a fact
+// about the file, so entries sort by it and not by their history. Descending,
+// and by id as the tiebreak so two updates dated the same day have a stable
+// order rather than the filesystem's.
+const updates = (await getCollection('updates'))
+	.sort((a, b) => b.data.date.localeCompare(a.data.date) || b.id.localeCompare(a.id))
+	.slice(0, limit);
+---
+
+<section class="commune-updates">
+	{heading && <h2 class="commune-updates-title">{heading}</h2>}
+
+	{updates.length === 0 ? (
+		<p class="commune-updates-empty">No updates yet.</p>
+	) : (
+		<ul class="commune-updates-list">
+			{updates.map((update) => (
+				<li class="commune-updates-item">
+					<a href={`/updates/${update.id}/`} class="commune-updates-link">
+						{update.data.title}
+					</a>
+					<time class="commune-updates-date" datetime={update.data.date}>
+						{update.data.date}
+					</time>
+					{update.data.summary && (
+						<p class="commune-updates-summary">{update.data.summary}</p>
+					)}
+				</li>
+			))}
+		</ul>
+	)}
+</section>
+
+<style>
+	.commune-updates-title {
+		font-size: 1.1rem;
+		font-weight: 600;
+		margin: 0 0 1rem 0;
+	}
+
+	.commune-updates-list {
+		list-style: none;
+		padding: 0;
+		margin: 0;
+	}
+
+	.commune-updates-item {
+		margin-bottom: 1rem;
+	}
+
+	.commune-updates-item:last-child {
+		margin-bottom: 0;
+	}
+
+	.commune-updates-link {
+		font-weight: 500;
+		text-decoration: none;
+	}
+
+	.commune-updates-link:hover {
+		text-decoration: underline;
+	}
+
+	.commune-updates-date {
+		display: block;
+		font-size: 0.8rem;
+		opacity: 0.7;
+	}
+
+	.commune-updates-summary {
+		margin: 0.25rem 0 0 0;
+		font-size: 0.9rem;
+		line-height: 1.5;
+	}
+
+	.commune-updates-empty {
+		margin: 0;
+		font-style: italic;
+		opacity: 0.7;
+	}
+</style>