@dmthepm/commune 0.1.1 → 0.3.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.1.1",
+  "version": "0.3.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": [
@@ -85,15 +85,12 @@
     "unist-util-visit": "^5.1.0"
   },
   "devDependencies": {
-    "@astrojs/check": "^0.9.10",
     "@astrojs/markdown-remark": "^7.3.0",
     "@astrojs/sitemap": "^3.7.4",
-    "@tailwindcss/typography": "^0.5.20",
     "@types/hast": "^3.0.5",
     "@types/mdast": "^4.0.4",
     "@types/node": "^22.20.1",
     "astro": "^7.2.10",
-    "autoprefixer": "^10.5.4",
     "tailwindcss": "^3.4.0",
     "typescript": "^5.6.0"
   }

package/src/components/Backlinks.astro

@@ -2,7 +2,11 @@
 export interface Props { slug: string; title?: string; hideCount?: boolean; }
 const { slug, hideCount = false } = Astro.props;
 ---
-<aside class="backlinks" data-backlinks-for={slug} data-hide-count={hideCount ? 'true' : undefined}>
+<!-- Starts hidden: the list is filled from `/backlinks.json` at runtime, so
+     without JavaScript, or on a note nothing links to, the heading would
+     otherwise stand over an empty list. `BacklinksScript` reveals it once it
+     has links to show. -->
+<aside class="backlinks hidden" data-backlinks-for={slug} data-hide-count={hideCount ? 'true' : undefined}>
   <h4>Links to this note</h4>
   <ul class="backlinks-list"></ul>
 </aside>

package/src/components/BacklinksScript.astro

@@ -5,6 +5,16 @@
 (function() {
   let backlinksData = null;
 
+  // Note titles are the vault author's prose and go into markup below; a stray
+  // <, & or " in one should read as that character rather than break the list
+  // open.
+  const escapeHtml = (value) => String(value ?? '')
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+
   async function initializeBacklinks(scope = document) {
     try {
       // Fetch backlinks data if not already loaded
@@ -57,7 +67,7 @@
         };
 
         // Render links and then add stars as separate clickable elements
-        list.innerHTML = items.map(s => `<li><a href="${s}">${titleFor(s)}</a></li>`).join('');
+        list.innerHTML = items.map(s => `<li><a href="${escapeHtml(s)}">${escapeHtml(titleFor(s))}</a></li>`).join('');
 
         // Add stars to starred notes
         list.querySelectorAll('li').forEach((li, index) => {

package/src/components/Header.astro

@@ -1,5 +1,11 @@
 ---
 ---
+<!-- First thing in the tab order on every page: reading pages put the whole
+     note between the header and the footer, and a keyboard reader should not
+     have to walk the header on each one. #main is on the page's <main>, or on
+     the first pane's scroll container where <main> is the pane container. -->
+<a class="skip-link" href="#main">Skip to content</a>
+
 <header class="commune-header">
   <div class="wrap">
     <a href="/" class="brand-section">
@@ -21,6 +27,30 @@
 </header>
 
 <style>
+  .skip-link{
+    /* Fixed, not absolute: the reader may be scrolled anywhere in a long note
+       when they reach for Tab, and the link has to be on screen to be useful. */
+    position:fixed;
+    left:0.5rem;
+    top:0.5rem;
+    z-index:calc(var(--z-modal) + 1);
+    padding:0.6rem 0.9rem;
+    border:1.5px solid var(--c-accent);
+    border-radius:var(--c-radius-md);
+    background:var(--c-bg);
+    color:var(--c-accent);
+    font-size:0.9rem;
+    font-weight:600;
+    box-shadow:var(--c-shadow-md);
+    transform:translateY(calc(-100% - 1rem));
+    transition:transform 0.15s ease;
+  }
+  .skip-link:focus{
+    transform:translateY(0);
+  }
+  @media print{
+    .skip-link{display:none}
+  }
   .commune-header{
     position:sticky;
     top:0;
@@ -193,6 +223,16 @@
     border-radius:var(--c-radius-sm);
   }
 
+  /* A hover state whose whole content is movement loses the movement. The
+     rule lives here rather than in `design-system.css` because Astro scopes
+     this block's selectors, and a global `.theme-btn:hover` would lose the
+     specificity contest to the scoped rule above. */
+  @media (prefers-reduced-motion: reduce) {
+    .theme-btn:hover {
+      transform: none;
+    }
+  }
+
   /* Mobile: hide Command-K text and search text, show only icon */
   @media (max-width: 768px) {
     .search-btn kbd,
@@ -239,9 +279,44 @@
     });
   })();
 
+  // Publish the header's real height. The pane container positions itself
+  // against --header-height, and the fallback in the stylesheet is a
+  // hand-counted number the header has outgrown — it measures 73px at the
+  // default font size and more once the text is zoomed. Measuring keeps the
+  // pane's top gap equal to its bottom gap at any zoom level or font size,
+  // and means no consumer has to re-count the number after restyling the
+  // header.
+  (function trackHeaderHeight(){
+    const header = document.querySelector('.commune-header');
+    if (!header) return;
+    const publish = () => {
+      const height = Math.round(header.getBoundingClientRect().height);
+      if (height > 0) document.documentElement.style.setProperty('--header-height', height + 'px');
+    };
+    publish();
+    if ('ResizeObserver' in window) new ResizeObserver(publish).observe(header);
+    else addEventListener('resize', publish);
+  })();
+
+  // One platform check, shared with the search modal's own handler, so the
+  // printed shortcut and the key that actually works cannot drift apart.
+  // navigator.platform is deprecated but still the only thing every browser
+  // answers; userAgentData.platform is preferred where it exists.
+  window.CommuneIsMac = () => /mac/i.test(
+    (navigator.userAgentData && navigator.userAgentData.platform) || navigator.platform || ''
+  );
+
+  // The button printed ⌘K to everyone. On Windows and Linux the shortcut is
+  // Ctrl+K, so the label named a key combination that did nothing.
+  (function labelSearchShortcut(){
+    if (window.CommuneIsMac()) return;
+    document.querySelectorAll('.search-btn kbd').forEach((el) => { el.textContent = 'Ctrl K'; });
+    document.querySelectorAll('.search-btn').forEach((el) => { el.setAttribute('aria-label', 'Search (Ctrl K)'); });
+  })();
+
   // cmd/ctrl-k opens modal
   addEventListener('keydown', (e) => {
-    const mac = navigator.platform.toUpperCase().includes('MAC');
+    const mac = window.CommuneIsMac();
     if ((mac ? e.metaKey : e.ctrlKey) && e.key.toLowerCase() === 'k') {
       e.preventDefault();
       dispatchEvent(new CustomEvent('commune:openSearch'));

package/src/components/HeaderStarScript.astro

@@ -5,13 +5,24 @@
 (function() {
   let backlinksData = null;
 
+  // Focus belongs to the dialog while it is open, and goes back to the star
+  // that opened it on close — otherwise a keyboard reader who opens the modal
+  // is dropped at the top of the document with no way back to where they were.
+  let starModalOpener = null;
+
+  const starModalFocusables = (modal) => Array.from(
+    modal.querySelectorAll('a[href], button, [tabindex]:not([tabindex="-1"])')
+  ).filter((el) => !el.hasAttribute('disabled'));
+
   // Show the star modal
   function showStarModal() {
     const modal = document.getElementById('star-modal');
     if (modal) {
+      starModalOpener = document.activeElement;
       modal.style.display = 'flex';
       // Prevent body scroll when modal is open
       document.body.style.overflow = 'hidden';
+      starModalFocusables(modal)[0]?.focus();
     }
   }
 
@@ -21,6 +32,10 @@
     if (modal) {
       modal.style.display = 'none';
       document.body.style.overflow = '';
+      if (starModalOpener instanceof HTMLElement && document.contains(starModalOpener)) {
+        starModalOpener.focus({ preventScroll: true });
+      }
+      starModalOpener = null;
     }
   }
 
@@ -31,6 +46,9 @@
     const modal = document.createElement('div');
     modal.id = 'star-modal';
     modal.className = 'star-modal';
+    modal.setAttribute('role', 'dialog');
+    modal.setAttribute('aria-modal', 'true');
+    modal.setAttribute('aria-label', 'Top 5%');
     modal.innerHTML = `
       <div class="star-modal-backdrop"></div>
       <div class="star-modal-content">
@@ -60,10 +78,25 @@
       hideStarModal();
     });
 
-    // Close on Escape key
+    // Close on Escape, and keep Tab inside the dialog while it is open.
     document.addEventListener('keydown', (e) => {
-      if (e.key === 'Escape' && modal.style.display === 'flex') {
+      if (modal.style.display !== 'flex') return;
+      if (e.key === 'Escape') {
         hideStarModal();
+        return;
+      }
+      if (e.key !== 'Tab') return;
+      const items = starModalFocusables(modal);
+      if (!items.length) { e.preventDefault(); return; }
+      const first = items[0];
+      const last = items[items.length - 1];
+      const active = document.activeElement;
+      if (e.shiftKey && (active === first || !modal.contains(active))) {
+        e.preventDefault();
+        last.focus();
+      } else if (!e.shiftKey && (active === last || !modal.contains(active))) {
+        e.preventDefault();
+        first.focus();
       }
     });
   }
@@ -110,9 +143,13 @@
             star.setAttribute('role', 'button');
             star.setAttribute('tabindex', '0');
 
-            // Click handler to open modal
+            // Click handler to open modal. stopPropagation matters: the pane
+            // container's delegated click handler treats any click that is not
+            // on a link or a real button as "focus this pane", and would pull
+            // focus straight back out of the modal we just opened.
             star.addEventListener('click', (e) => {
               e.preventDefault();
+              e.stopPropagation();
               showStarModal();
             });
 
@@ -120,6 +157,7 @@
             star.addEventListener('keydown', (e) => {
               if (e.key === 'Enter' || e.key === ' ') {
                 e.preventDefault();
+                e.stopPropagation();
                 showStarModal();
               }
             });