@brandon_m_behring/book-scaffold-astro 3.0.0-alpha.0 → 3.0.0-alpha.2

package/dist/index.mjs

@@ -152,12 +152,12 @@ var ALWAYS_ON_STYLES = [
 ];
 var TOOLS_ONLY_STYLES = ["convergence.css", "tool-filter.css"];
 var DEFAULT_ROUTES_ALL = [
-  { pattern: "/chapters", file: "chapters.astro" },
   { pattern: "/references", file: "references.astro" },
   { pattern: "/print", file: "print.astro" },
   { pattern: "/search", file: "search.astro" }
 ];
 var DEFAULT_ROUTES_TOOLS = [
+  { pattern: "/chapters", file: "chapters.astro" },
   { pattern: "/convergence", file: "convergence.astro" }
 ];
 function resolvePage(file) {

package/dist/schemas.d.ts

@@ -6,12 +6,7 @@ import 'astro';
  * consumer extends via object spread and Zod `.extend()` (see PACKAGE_DESIGN.md §5).
  */
 declare function defineBookSchemas(opts?: BookSchemasOptions): {
-    collections: {
-        chapters: unknown;
-        sources: unknown;
-        changelog: unknown;
-        patterns: unknown;
-    };
+    collections: Record<string, unknown>;
 };
 
 export { defineBookSchemas };

package/dist/schemas.mjs

@@ -1,4 +1,5 @@
 // src/schemas-entry.ts
+import { existsSync } from "fs";
 import { defineCollection } from "astro:content";
 import { glob, file } from "astro/loaders";
 
@@ -139,21 +140,28 @@ function defineBookSchemas(opts = {}) {
     }),
     schema: profile === "academic" ? academicChapterSchema : toolsChapterSchema
   });
-  const sources = defineCollection({
-    loader: file("sources/manifest.yaml"),
-    schema: sourcesSchema
-  });
-  const changelog = defineCollection({
-    loader: glob({ pattern: "*.yaml", base: "./changelog/tools" }),
-    schema: changelogSchema
-  });
-  const patterns = defineCollection({
-    loader: file("changelog/patterns.yaml"),
-    schema: patternsSchema
-  });
-  return {
-    collections: { chapters, sources, changelog, patterns }
+  const collections = {
+    chapters
   };
+  if (existsSync("./sources/manifest.yaml")) {
+    collections.sources = defineCollection({
+      loader: file("sources/manifest.yaml"),
+      schema: sourcesSchema
+    });
+  }
+  if (existsSync("./changelog/tools")) {
+    collections.changelog = defineCollection({
+      loader: glob({ pattern: "*.yaml", base: "./changelog/tools" }),
+      schema: changelogSchema
+    });
+  }
+  if (existsSync("./changelog/patterns.yaml")) {
+    collections.patterns = defineCollection({
+      loader: file("changelog/patterns.yaml"),
+      schema: patternsSchema
+    });
+  }
+  return { collections };
 }
 export {
   defineBookSchemas

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@brandon_m_behring/book-scaffold-astro",
   "description": "Astro 6 + MDX toolkit for long-form technical books. Profile-aware (academic / tools / minimal); ships Tufte typography, KaTeX, BibTeX citations, Pagefind, Cloudflare Workers deploy. See PACKAGE_DESIGN.md for the API contract.",
-  "version": "3.0.0-alpha.0",
+  "version": "3.0.0-alpha.2",
   "type": "module",
   "license": "MIT",
   "author": "Brandon Behring",
@@ -95,6 +95,7 @@
   },
   "files": [
     "dist",
+    "src/lib",
     "components",
     "styles",
     "layouts",

package/src/lib/chapters.ts

@@ -0,0 +1,37 @@
+/**
+ * src/lib/chapters.ts — ordering + nav helpers for the chapters collection.
+ *
+ * Centralizes the sort key (part × 100 + chapter) and draft filtering so
+ * components and static-path generation use the same logic.
+ */
+import { getCollection, type CollectionEntry } from 'astro:content';
+
+export type Chapter = CollectionEntry<'chapters'>;
+
+/** Numeric sort key; chapters within a part come before a higher part. */
+export function sortKey(c: Chapter): number {
+  return c.data.part * 1000 + c.data.chapter;
+}
+
+/** All non-draft chapters, ordered by part+chapter ascending. */
+export async function getAllChapters(): Promise<Chapter[]> {
+  const all = await getCollection('chapters', (entry) => !entry.data.draft);
+  return all.sort((a, b) => sortKey(a) - sortKey(b));
+}
+
+/**
+ * Given a chapter id, return its ordered neighbors.
+ * Either may be null at the edges of the book.
+ */
+export async function getNeighbors(id: string): Promise<{
+  prev: Chapter | null;
+  next: Chapter | null;
+}> {
+  const all = await getAllChapters();
+  const idx = all.findIndex((c) => c.id === id);
+  if (idx === -1) return { prev: null, next: null };
+  return {
+    prev: idx > 0 ? all[idx - 1] : null,
+    next: idx < all.length - 1 ? all[idx + 1] : null,
+  };
+}

package/src/lib/freshness.ts

@@ -0,0 +1,84 @@
+/**
+ * src/lib/freshness.ts — volatility-aware staleness computation.
+ *
+ * Each chapter carries a `last_verified` date and a `volatility` class.
+ * This module maps those to a freshness status the reader can trust.
+ *
+ * Thresholds chosen to align with Ch 15's source-tier audit cadences:
+ *   stable-principle      → 365 days (principles drift annually at most)
+ *   architectural-pattern → 180 days (between annual and quarterly; "on
+ *                                     major release" isn't derivable from
+ *                                     frontmatter)
+ *   feature-surface       → 90 days  (quarterly)
+ *
+ * Status bands (fraction of threshold):
+ *   fresh       (<75%)   — green dot, unobtrusive
+ *   verify-soon (75-100%) — yellow, mild warning
+ *   stale       (>100%)  — amber/red, "verify before trusting"
+ *
+ * Example assertions (verified by visual inspection during Stage 3.1):
+ *   getFreshness(today, 'feature-surface').status     === 'fresh'
+ *   getFreshness(today-70d, 'feature-surface').status === 'verify-soon'
+ *   getFreshness(today-100d, 'feature-surface').status === 'stale'
+ *   getFreshness(today-200d, 'stable-principle').status === 'fresh'
+ *   getFreshness(today-300d, 'stable-principle').status === 'verify-soon'
+ */
+import type { volatilityLevels } from '../schemas.js';
+
+export type VolatilityLevel = (typeof volatilityLevels)[number];
+
+export type FreshnessStatus = 'fresh' | 'verify-soon' | 'stale';
+
+export interface Freshness {
+  status: FreshnessStatus;
+  daysOld: number;
+  thresholdDays: number;
+  /** Days until stale; negative when already stale. */
+  daysUntil: number;
+}
+
+const THRESHOLDS: Record<VolatilityLevel, number> = {
+  'stable-principle': 365,
+  'architectural-pattern': 180,
+  'feature-surface': 90,
+};
+
+const MS_PER_DAY = 1000 * 60 * 60 * 24;
+
+/**
+ * Compute freshness for a chapter given its last_verified date + volatility.
+ *
+ * Pure function; caller supplies `now` only in tests. Production callers omit.
+ */
+export function getFreshness(
+  lastVerified: Date,
+  volatility: VolatilityLevel,
+  now: Date = new Date(),
+): Freshness {
+  const thresholdDays = THRESHOLDS[volatility];
+  const daysOld = Math.floor((now.getTime() - lastVerified.getTime()) / MS_PER_DAY);
+  const daysUntil = thresholdDays - daysOld;
+
+  let status: FreshnessStatus;
+  if (daysOld < thresholdDays * 0.75) {
+    status = 'fresh';
+  } else if (daysOld < thresholdDays) {
+    status = 'verify-soon';
+  } else {
+    status = 'stale';
+  }
+
+  return { status, daysOld, thresholdDays, daysUntil };
+}
+
+/** Human-readable label for each status; used for ARIA + tooltips. */
+export function freshnessLabel(f: Freshness): string {
+  switch (f.status) {
+    case 'fresh':
+      return `Fresh (${f.daysOld}d old; verify within ${f.daysUntil}d)`;
+    case 'verify-soon':
+      return `Verify soon (${f.daysOld}d old; ${f.daysUntil}d until stale)`;
+    case 'stale':
+      return `Stale (${f.daysOld}d old; ${Math.abs(f.daysUntil)}d past threshold)`;
+  }
+}

package/src/lib/katex-macros.ts

@@ -0,0 +1,110 @@
+/**
+ * src/lib/katex-macros.ts — KaTeX macro definitions ported from the LaTeX guide.
+ *
+ * Source files in the LaTeX tree:
+ *   - guides/shared/ssm-notation.tex   (20 SSM-specific macros)
+ *   - guides/shared/ssm-guide-preamble.sty:387-413  (16 general math macros)
+ *
+ * Wired into astro.config.mjs via:
+ *   rehypeKatex({ strict: 'error', macros: ssmMacros, trust: true })
+ *
+ * KaTeX-specific adaptations:
+ *   - \bm is not part of KaTeX; aliased to \boldsymbol (visually identical
+ *     in stix-two / Computer Modern math fonts).
+ *   - \DeclareMathOperator and \DeclareMathOperator* are translated to
+ *     \operatorname / \operatorname* respectively.
+ *   - \psmallmatrix is an environment in amsmath, not a macro. KaTeX
+ *     macros operate at command level; substitution happens in the
+ *     converter script (latex-to-mdx.mjs in Phase 2.7) — search for
+ *     \begin{psmallmatrix} and replace with \begin{pmatrix}.
+ *
+ * Equation numbering is handled by a separate remark plugin (deferred to
+ * a follow-up session per plan Phase 2.1 Task #9).
+ */
+
+export const ssmMacros: Record<string, string> = {
+  // -----------------------------------------------------------------
+  // Compatibility alias: \bm{x} -> \boldsymbol{x}
+  // KaTeX does not ship \bm. The LaTeX source uses \bm extensively in
+  // ssm-notation.tex for vectors and matrices.
+  // -----------------------------------------------------------------
+  '\\bm': '\\boldsymbol{#1}',
+
+  // -----------------------------------------------------------------
+  // SSM state space variables (ssm-notation.tex:5-13)
+  // -----------------------------------------------------------------
+  '\\statevec': '\\boldsymbol{h}', // state vector h_t
+  '\\statemat': '\\boldsymbol{A}', // dynamics matrix A
+  '\\inputmat': '\\boldsymbol{B}', // input matrix B
+  '\\outputmat': '\\boldsymbol{C}', // output matrix C
+  '\\feedmat': '\\boldsymbol{D}', // feedthrough matrix D
+  '\\stepsize': '\\Delta', // discretization step
+  '\\discA': '\\bar{\\boldsymbol{A}}', // discretized A
+  '\\discB': '\\bar{\\boldsymbol{B}}', // discretized B
+
+  // -----------------------------------------------------------------
+  // Dimensions (ssm-notation.tex:16-18)
+  // -----------------------------------------------------------------
+  '\\seqlen': 'L', // sequence length
+  '\\statedim': 'N', // state dimension
+  '\\inputdim': 'D', // input / model dimension
+
+  // -----------------------------------------------------------------
+  // Scan operator (ssm-notation.tex:23-24)
+  // -----------------------------------------------------------------
+  '\\scanop': '\\oplus', // associative binary operator for diagonal SSMs
+  '\\elemwise': '\\odot', // element-wise product
+
+  // -----------------------------------------------------------------
+  // Dynamical systems (ssm-notation.tex:27-30)
+  // -----------------------------------------------------------------
+  '\\monodromy': '\\boldsymbol{Z}', // monodromy matrix Z(T)
+  '\\floquet': '\\mu', // Floquet multiplier
+  '\\lyapexp': '\\lambda', // Lyapunov exponent
+  '\\jacobian': '\\boldsymbol{J}', // Jacobian matrix
+
+  // -----------------------------------------------------------------
+  // Calculus shortcuts (ssm-notation.tex:33-35)
+  // -----------------------------------------------------------------
+  '\\ddt': '\\frac{d}{dt}',
+  '\\pderiv': '\\frac{\\partial #1}{\\partial #2}', // 2 args
+  '\\spectralradius': '\\rho',
+
+  // -----------------------------------------------------------------
+  // Common sets (preamble:390-393)
+  // -----------------------------------------------------------------
+  '\\R': '\\mathbb{R}',
+  '\\C': '\\mathbb{C}',
+  '\\N': '\\mathbb{N}',
+  '\\Z': '\\mathbb{Z}',
+
+  // -----------------------------------------------------------------
+  // Probability / statistics (preamble:396-397)
+  // -----------------------------------------------------------------
+  '\\E': '\\mathbb{E}',
+  '\\Prob': '\\mathbb{P}',
+
+  // -----------------------------------------------------------------
+  // Norms and inner products (preamble:400-402)
+  // -----------------------------------------------------------------
+  '\\norm': '\\lVert #1 \\rVert',
+  '\\ip': '\\langle #1, #2 \\rangle',
+  '\\abs': '\\lvert #1 \\rvert',
+
+  // -----------------------------------------------------------------
+  // Operators (preamble:405-410)
+  // \DeclareMathOperator* -> \operatorname* (with limits below in display)
+  // \DeclareMathOperator  -> \operatorname
+  // -----------------------------------------------------------------
+  '\\argmax': '\\operatorname*{arg\\,max}',
+  '\\argmin': '\\operatorname*{arg\\,min}',
+  '\\diag': '\\operatorname{diag}',
+  '\\tr': '\\operatorname{tr}',
+  '\\spec': '\\operatorname{spec}',
+  '\\rank': '\\operatorname{rank}',
+
+  // -----------------------------------------------------------------
+  // Complexity (preamble:413)
+  // -----------------------------------------------------------------
+  '\\bigO': '\\mathcal{O}(#1)',
+};

package/src/lib/patterns.ts

@@ -0,0 +1,127 @@
+/**
+ * src/lib/patterns.ts — helpers for the convergence dashboard.
+ *
+ * Joins the patterns collection (registry of agentic-coding patterns)
+ * with the changelog collection (per-tool version timelines) to answer
+ * the two questions the dashboard surfaces:
+ *
+ *   1. For a given pattern, which tools adopted it and when?
+ *   2. What is the set of tracked patterns, in a stable display order?
+ *
+ * Neither file format stores the join directly; these helpers compute
+ * it lazily at build time so new tool/version rows require no code
+ * changes.
+ */
+import { getCollection, type CollectionEntry } from 'astro:content';
+import {
+  toolSlugs,
+  patternCategories,
+  changeKinds,
+} from '../content.config';
+
+export type PatternEntry = CollectionEntry<'patterns'>;
+export type ToolSlug = (typeof toolSlugs)[number];
+export type PatternCategory = (typeof patternCategories)[number];
+export type ChangeKind = (typeof changeKinds)[number];
+
+export interface TimelineEntry {
+  tool: ToolSlug;
+  version: string;
+  date: Date;
+  kind: ChangeKind;
+  note: string;
+  sourceKey?: string;
+}
+
+/**
+ * Per-pattern timeline: every (tool, version, change) triple where
+ * change.pattern === slug, sorted by date ascending. A pattern that no
+ * tool has adopted yet returns an empty array.
+ */
+export async function getPatternTimeline(slug: string): Promise<TimelineEntry[]> {
+  const tools = await getCollection('changelog');
+  const out: TimelineEntry[] = [];
+  for (const entry of tools) {
+    const tool = entry.data.tool;
+    for (const v of entry.data.versions) {
+      for (const change of v.changes) {
+        if (change.pattern !== slug) continue;
+        out.push({
+          tool,
+          version: v.version,
+          date: v.date,
+          kind: change.kind,
+          note: change.note,
+          sourceKey: change.source_key,
+        });
+      }
+    }
+  }
+  out.sort((a, b) => a.date.getTime() - b.date.getTime());
+  return out;
+}
+
+/**
+ * All patterns in stable display order: converged patterns first (by
+ * convergence_date ascending — oldest convergence first), then
+ * unconverged patterns (by slug). Within each bucket, preserves
+ * manifest order.
+ */
+export async function getAllPatterns(): Promise<PatternEntry[]> {
+  const all = await getCollection('patterns');
+  return all.sort((a, b) => {
+    const aDate = a.data.convergence_date?.getTime();
+    const bDate = b.data.convergence_date?.getTime();
+    if (aDate != null && bDate != null) return aDate - bDate;
+    if (aDate != null) return -1;
+    if (bDate != null) return 1;
+    return a.id.localeCompare(b.id);
+  });
+}
+
+/**
+ * Patterns grouped by category; categories that have no patterns are
+ * still emitted with an empty array so the dashboard can render
+ * honest "no patterns yet" placeholders without checking undefined.
+ */
+export async function getPatternsByCategory(): Promise<
+  Record<PatternCategory, PatternEntry[]>
+> {
+  const all = await getAllPatterns();
+  const grouped = Object.fromEntries(
+    patternCategories.map((c) => [c, [] as PatternEntry[]]),
+  ) as Record<PatternCategory, PatternEntry[]>;
+  for (const p of all) {
+    const cat = p.data.category ?? 'other';
+    grouped[cat].push(p);
+  }
+  return grouped;
+}
+
+/** Human-readable labels per category. */
+export const CATEGORY_LABELS: Record<PatternCategory, string> = {
+  safety: 'Safety',
+  scale: 'Scale',
+  context: 'Context',
+  interaction: 'Interaction',
+  extension: 'Extension',
+  other: 'Other',
+};
+
+/**
+ * Which tools have adopted a given pattern (deduplicated). Helpful
+ * for computing "adopted by N of 3 tools" summary counts.
+ */
+export function toolsInTimeline(timeline: TimelineEntry[]): ToolSlug[] {
+  const seen = new Set<ToolSlug>();
+  for (const e of timeline) seen.add(e.tool);
+  return Array.from(seen);
+}
+
+/** Fixed display order for tool rows on the timeline. 'cross-tool' is
+ * excluded because a pattern is something tools adopt individually. */
+export const TIMELINE_TOOL_ORDER: ToolSlug[] = [
+  'claude-code',
+  'gemini-cli',
+  'codex-cli',
+];

package/src/lib/repo-url.ts

@@ -0,0 +1,32 @@
+/**
+ * Repository URL constants used by CodeRef and CodeBlock components.
+ *
+ * Centralized here so renaming the repo or moving branches is a one-file
+ * change rather than a hunt across components.
+ *
+ * If the repo is later mirrored to a different host, update GITHUB_BASE
+ * accordingly; the components do not assume GitHub-specific anchor syntax
+ * beyond #L<N>-L<M>, which all major hosts (GitHub, GitLab, Codeberg)
+ * support.
+ */
+export const GITHUB_REPO = 'brandon-behring/post_transformers';
+export const GITHUB_BRANCH = 'main';
+export const GITHUB_BASE = `https://github.com/${GITHUB_REPO}/blob/${GITHUB_BRANCH}`;
+
+/**
+ * Build a GitHub line-anchor URL.
+ *   buildGithubUrl('experiments/jax/week04/s4.py', 42)        -> .../s4.py#L42
+ *   buildGithubUrl('experiments/jax/week04/s4.py', 42, 58)    -> .../s4.py#L42-L58
+ *   buildGithubUrl('experiments/jax/week04/s4.py')            -> .../s4.py
+ */
+export function buildGithubUrl(path: string, line?: number, lineEnd?: number): string {
+  const cleanPath = path.replace(/^\/+/, '');
+  let url = `${GITHUB_BASE}/${cleanPath}`;
+  if (line !== undefined) {
+    url += `#L${line}`;
+    if (lineEnd !== undefined && lineEnd !== line) {
+      url += `-L${lineEnd}`;
+    }
+  }
+  return url;
+}

package/src/lib/sources.ts

@@ -0,0 +1,62 @@
+/**
+ * src/lib/sources.ts — helpers for the sources collection.
+ *
+ * `sources/manifest.yaml` drives every citation in the book. This
+ * module centralizes tier grouping + ordering so the SourceArchive
+ * component and any future dashboards share a single source of truth.
+ */
+import { getCollection, type CollectionEntry } from 'astro:content';
+import { sourceTiers } from '../content.config';
+
+export type SourceEntry = CollectionEntry<'sources'>;
+export type SourceTier = (typeof sourceTiers)[number];
+
+/**
+ * Grouped source entries keyed by tier, in descending authority
+ * (T1-official → T4-conjecture). Empty tiers map to an empty array
+ * so callers can render "no sources yet" placeholders without
+ * checking for undefined.
+ *
+ * Within each tier, entries sort by publish_date descending (newest
+ * first); entries without a publish_date sort after those with one.
+ */
+export async function getSourcesByTier(): Promise<Record<SourceTier, SourceEntry[]>> {
+  const all = await getCollection('sources');
+  const grouped: Record<SourceTier, SourceEntry[]> = {
+    'T1-official': [],
+    'T2-release-notes': [],
+    'T3-practitioner': [],
+    'T4-conjecture': [],
+  };
+  for (const entry of all) {
+    grouped[entry.data.tier].push(entry);
+  }
+  for (const tier of sourceTiers) {
+    grouped[tier].sort((a, b) => {
+      const ad = a.data.publish_date?.getTime() ?? -Infinity;
+      const bd = b.data.publish_date?.getTime() ?? -Infinity;
+      return bd - ad;
+    });
+  }
+  return grouped;
+}
+
+/** Human-readable description for each tier (used as empty-state label). */
+export const TIER_LABELS: Record<SourceTier, string> = {
+  'T1-official': 'T1 · Official',
+  'T2-release-notes': 'T2 · Release notes',
+  'T3-practitioner': 'T3 · Practitioner',
+  'T4-conjecture': 'T4 · Conjecture',
+};
+
+/** One-line explanation per tier (shown under the heading). */
+export const TIER_DESCRIPTIONS: Record<SourceTier, string> = {
+  'T1-official':
+    'Vendor-official documentation or release notes. Highest trust for factual claims about the vendor\u2019s own tool.',
+  'T2-release-notes':
+    'Release blog posts, changelogs, conference talks. Trustworthy for intent and availability claims.',
+  'T3-practitioner':
+    'Respected community writing with a durable argument the author has defended over time.',
+  'T4-conjecture':
+    'Blog posts, tweets, or unverified claims. Pointers to investigate, not authorities.',
+};