explico 0.6.0 → 0.7.0

package/src/compiler/cli.ts

@@ -18,6 +18,9 @@
  *     source metadata + locators, the section's domain signatures, and the
  *     lesson's current diagnostics — and reports token counts against the doc
  *     set + corpus so the size win is visible.
+ *   - `content diagnostics [severity]` flattens every diagnostic category at
+ *     or above a threshold into one stable, source-aware list for editors.
+ *   - `content warnings` is the warning-only compatibility view.
  *   - `content check` compiles the lesson MDX → remark → KaTeX → HTML and fails
  *     on any renderability error (unparseable MDX, KaTeX error, unresolved
  *     notation, unknown `[[key]]`, unknown citation), on top of the manifest's
@@ -45,6 +48,7 @@ import remarkNotation, {
   createRemarkNotationOptions,
 } from '../reference/remark-notation.mjs';
 import remarkShortNote from '../reference/remark-short-note.mjs';
+import type { DiagnosticSeverity } from '../reference/types';
 import type { Manifest, ManifestLesson } from './manifest';
 import { isLessonSlug, lessonIdFromSlug } from './lesson-derivation';
 
@@ -81,10 +85,15 @@ export class ContentCliError extends Error {
 /** One normalized diagnostic. `code` is `<source>:<kind>` and always stable. */
 export interface CliDiagnostic {
   readonly code: string;
-  readonly severity: 'error' | 'warning';
+  readonly severity: DiagnosticSeverity;
   readonly message: string;
   readonly file?: string;
   readonly line?: number;
+  readonly column?: number;
+}
+
+function diagnosticSeverity(value: unknown): DiagnosticSeverity {
+  return value === 'info' || value === 'warning' ? value : 'error';
 }
 
 function mentions(message: string, lessonId: string, file: string): boolean {
@@ -115,7 +124,7 @@ export function lessonDiagnostics(
     if (!mentions(issue.message, id, file)) continue;
     out.push({
       code: `curriculum:${issue.kind}`,
-      severity: issue.severity === 'warning' ? 'warning' : 'error',
+      severity: diagnosticSeverity(issue.severity),
       message: issue.message,
     });
   }
@@ -135,7 +144,7 @@ export function lessonDiagnostics(
     }
     out.push({
       code: `${group}:${entry.code}`,
-      severity: entry.severity === 'warning' ? 'warning' : 'error',
+      severity: diagnosticSeverity(entry.severity),
       message: entry.message,
       ...withFile(entryFile),
     });
@@ -150,11 +159,12 @@ export function lessonDiagnostics(
         ));
     if (!forLesson) continue;
     out.push({
-      code: `math:${diagnostic.context}`,
+      code: `math:${diagnostic.code ?? diagnostic.context}`,
       severity: diagnostic.severity,
       message: diagnostic.message,
       file: diagnostic.file,
       ...(diagnostic.line === undefined ? {} : { line: diagnostic.line }),
+      ...(diagnostic.column === undefined ? {} : { column: diagnostic.column }),
     });
   }
 
@@ -168,7 +178,7 @@ export function lessonDiagnostics(
     }
     out.push({
       code: `equations:${diagnostic.code}`,
-      severity: diagnostic.severity === 'warning' ? 'warning' : 'error',
+      severity: diagnosticSeverity(diagnostic.severity),
       message: diagnostic.message,
       ...withFile(diagnostic.file),
     });
@@ -190,7 +200,7 @@ export function lessonDiagnostics(
     }
     out.push({
       code: diagnostic.code,
-      severity: diagnostic.severity === 'warning' ? 'warning' : 'error',
+      severity: diagnosticSeverity(diagnostic.severity),
       message: diagnostic.message,
       ...withFile(diagnostic.file),
     });
@@ -200,7 +210,7 @@ export function lessonDiagnostics(
     if (diagnostic.file !== file && diagnostic.lessonId !== id) continue;
     out.push({
       code: `consistency:${diagnostic.code}`,
-      severity: 'warning',
+      severity: diagnostic.severity,
       message: diagnostic.message,
       ...withFile(diagnostic.file),
     });
@@ -500,6 +510,7 @@ export interface StatusReport {
   readonly diagnostics: {
     readonly errors: number;
     readonly warnings: number;
+    readonly infos: number;
   };
 }
 
@@ -517,10 +528,7 @@ export function contentStatus(manifest: Manifest): StatusReport {
     .filter((diagnostic) => diagnostic.code === 'unused-definition')
     .map((diagnostic) => ({
       code: `notation:${diagnostic.code}`,
-      severity:
-        diagnostic.severity === 'warning'
-          ? ('warning' as const)
-          : ('error' as const),
+      severity: diagnosticSeverity(diagnostic.severity),
       message: diagnostic.message,
       ...(diagnostic.source?.file === undefined
         ? {}
@@ -539,7 +547,7 @@ export function contentStatus(manifest: Manifest): StatusReport {
     ...manifest.diagnostics.diagrams.map((d) => d.severity),
     ...manifest.diagnostics.checks.map((d) => d.severity),
     ...manifest.diagnostics.rawFloats.map((d) => d.severity),
-    ...manifest.diagnostics.consistency.map(() => 'warning' as const),
+    ...manifest.diagnostics.consistency.map((d) => d.severity),
     ...manifest.diagnostics.knowledge.map((d) => d.severity),
   ];
 
@@ -583,10 +591,134 @@ export function contentStatus(manifest: Manifest): StatusReport {
       errors: allDiagnostics.filter((severity) => severity === 'error').length,
       warnings: allDiagnostics.filter((severity) => severity === 'warning')
         .length,
+      infos: allDiagnostics.filter((severity) => severity === 'info').length,
     },
   };
 }
 
+// --- content diagnostics -------------------------------------------------
+
+export type DiagnosticThreshold = DiagnosticSeverity;
+
+export interface DiagnosticsReport {
+  readonly minimumSeverity: DiagnosticThreshold;
+  readonly count: number;
+  readonly diagnostics: readonly CliDiagnostic[];
+}
+
+export interface WarningsReport {
+  readonly count: number;
+  readonly warnings: readonly CliDiagnostic[];
+}
+
+type DiagnosticRecord = Record<string, unknown> & {
+  readonly code?: unknown;
+  readonly kind?: unknown;
+  readonly severity?: unknown;
+  readonly message?: unknown;
+  readonly file?: unknown;
+  readonly lessonId?: unknown;
+  readonly line?: unknown;
+  readonly column?: unknown;
+  readonly source?: unknown;
+};
+
+function numericLocation(value: unknown): number | undefined {
+  return typeof value === 'number' && Number.isInteger(value) && value > 0
+    ? value
+    : undefined;
+}
+
+const SEVERITY_RANK: Readonly<Record<DiagnosticSeverity, number>> = {
+  info: 0,
+  warning: 1,
+  error: 2,
+};
+
+/** Manifest diagnostics at or above a severity, normalized for tooling. */
+export function contentDiagnostics(
+  manifest: Manifest,
+  minimumSeverity: DiagnosticThreshold = 'info',
+): DiagnosticsReport {
+  const lessonFileByHint = new Map<string, string>();
+  for (const lesson of manifest.lessons) {
+    lessonFileByHint.set(lesson.id, lesson.file);
+    lessonFileByHint.set(lesson.slug, lesson.file);
+    lessonFileByHint.set(lesson.file, lesson.file);
+  }
+
+  const groups = Object.entries(manifest.diagnostics) as readonly [
+    string,
+    readonly unknown[],
+  ][];
+  const diagnostics: CliDiagnostic[] = [];
+  for (const [group, values] of groups) {
+    for (const value of values) {
+      const diagnostic = value as DiagnosticRecord;
+      const severity = diagnosticSeverity(diagnostic.severity);
+      if (SEVERITY_RANK[severity] < SEVERITY_RANK[minimumSeverity]) continue;
+      const source =
+        diagnostic.source !== null && typeof diagnostic.source === 'object'
+          ? (diagnostic.source as Record<string, unknown>)
+          : undefined;
+      const rawFile =
+        typeof diagnostic.file === 'string'
+          ? diagnostic.file
+          : typeof source?.file === 'string'
+            ? source.file
+            : undefined;
+      const lessonId =
+        typeof diagnostic.lessonId === 'string'
+          ? diagnostic.lessonId
+          : undefined;
+      const file =
+        (rawFile === undefined ? undefined : lessonFileByHint.get(rawFile)) ??
+        (lessonId === undefined ? undefined : lessonFileByHint.get(lessonId)) ??
+        rawFile;
+      const line =
+        numericLocation(diagnostic.line) ?? numericLocation(source?.line);
+      const column =
+        numericLocation(diagnostic.column) ?? numericLocation(source?.column);
+      const detail =
+        typeof diagnostic.code === 'string'
+          ? diagnostic.code
+          : typeof diagnostic.kind === 'string'
+            ? diagnostic.kind
+            : 'diagnostic';
+      diagnostics.push({
+        code: `${group}:${detail}`,
+        severity,
+        message: String(diagnostic.message ?? detail),
+        ...(file === undefined ? {} : { file }),
+        ...(line === undefined ? {} : { line }),
+        ...(column === undefined ? {} : { column }),
+      });
+    }
+  }
+
+  diagnostics.sort(
+    (left, right) =>
+      (left.file ?? '').localeCompare(right.file ?? '') ||
+      (left.line ?? 0) - (right.line ?? 0) ||
+      (left.column ?? 0) - (right.column ?? 0) ||
+      left.code.localeCompare(right.code) ||
+      left.message.localeCompare(right.message),
+  );
+  return {
+    minimumSeverity,
+    count: diagnostics.length,
+    diagnostics,
+  };
+}
+
+/** Every warning exactly; errors and informational advice are excluded. */
+export function contentWarnings(manifest: Manifest): WarningsReport {
+  const warnings = contentDiagnostics(manifest, 'warning').diagnostics.filter(
+    (diagnostic) => diagnostic.severity === 'warning',
+  );
+  return { count: warnings.length, warnings };
+}
+
 // --- content context ---------------------------------------------------
 
 export interface ContextReport {

package/src/compiler/exports/standalone-html.ts

@@ -722,6 +722,20 @@ async function inlineResourceAttribute(
   setAttribute(node, name, await assetDataUrl(path, context));
 }
 
+const INLINEABLE_LINK_RELS: ReadonlySet<string> = new Set([
+  'stylesheet',
+  'icon',
+  'shortcut icon',
+  'apple-touch-icon',
+  'apple-touch-icon-precomposed',
+  'mask-icon',
+]);
+
+function isInlineableLinkRel(node: HtmlElement): boolean {
+  const rel = attribute(node, 'rel');
+  return rel !== undefined && INLINEABLE_LINK_RELS.has(rel.trim().toLowerCase());
+}
+
 function parseSourceSet(value: string): readonly { url: string; descriptor: string }[] {
   const candidates = value.match(/(?:[^\s,]+)(?:\s+(?:\d+w|\d+(?:\.\d+)?x))?/gu) ?? [];
   return candidates.map((candidate) => {
@@ -748,6 +762,7 @@ async function inlineMedia(document: HtmlNode, context: ExportContext): Promise<
         'Standalone HTML does not support an iframe src; use self-contained semantic DOM instead.',
       );
     }
+    if (node.tagName === 'link' && !isInlineableLinkRel(node)) continue;
     const names = resources[node.tagName] ?? [];
     for (const name of names) await inlineResourceAttribute(node, name, context);
     if (node.tagName === 'use' || node.tagName === 'image') {

package/src/compiler/logging.ts

@@ -0,0 +1,248 @@
+/**
+ * Run logs for `pnpm validate:content`, in Python's `logging` format.
+ *
+ * The terminal keeps the compact `[code] message` lines it has always shown.
+ * This module is the second handler over the same records: it writes them to
+ * `build/logs/<timestamp>/` in the format Python's `logging` emits, so a run
+ * can be grepped by level and by subsystem long after the terminal scrolled
+ * away.
+ *
+ *     %(asctime)s %(levelname)s %(name)s: %(message)s
+ *
+ *     2026-09-18 03:22:47,482 WARNING explico.notation: [undefined-reference] …
+ *
+ * Three files per run, each a superset of the one above it, so you open the
+ * narrowest one that still answers the question:
+ *
+ *     build/logs/2026-09-18T03-22-47/
+ *       error.log     errors only
+ *       warning.log   errors + warnings
+ *       info.log      errors + warnings + info
+ *
+ * Nothing is pruned — `build/` is git-ignored, so old runs are yours to clean
+ * up — and `build/logs/latest` points at the newest run.
+ *
+ * Levels carry their Python meaning. `error` is a blocking diagnostic (the
+ * caller still throws; this module only records), `warning` is a non-blocking
+ * finding, and `info` is the run summary plus the severity-`info` diagnostics
+ * the engine has always produced but never printed.
+ *
+ * Each level method **returns its message**, so a call site can log and print
+ * in one expression without the two drifting apart:
+ *
+ *     console.warn(log.warning('notation', `[${d.code}] ${d.message}`));
+ */
+
+import {
+  appendFileSync,
+  existsSync,
+  mkdirSync,
+  rmSync,
+  symlinkSync,
+  writeFileSync,
+} from 'node:fs';
+import { join, relative } from 'node:path';
+
+const REPOSITORY_ROOT = process.cwd();
+/** Sits beside `build/manifest.json` and `build/resolution/` (Phase F). */
+export const LOGS_DIR = join(REPOSITORY_ROOT, 'build', 'logs');
+
+/** Python's levels, narrowed to the three the engine actually emits. */
+export type LogLevel = 'ERROR' | 'WARNING' | 'INFO';
+
+/** Ordered most severe first; a file at index `i` takes levels `0..i`. */
+const LEVELS: readonly LogLevel[] = ['ERROR', 'WARNING', 'INFO'];
+
+/** `error.log` holds `ERROR`, `warning.log` also `WARNING`, and so on. */
+const FILES: readonly { readonly name: string; readonly level: LogLevel }[] = [
+  { name: 'error.log', level: 'ERROR' },
+  { name: 'warning.log', level: 'WARNING' },
+  { name: 'info.log', level: 'INFO' },
+];
+
+/** `true` when a record at `record` belongs in a file whose floor is `file`. */
+function includes(file: LogLevel, record: LogLevel): boolean {
+  return LEVELS.indexOf(record) <= LEVELS.indexOf(file);
+}
+
+function pad(value: number, width = 2): string {
+  return String(value).padStart(width, '0');
+}
+
+/**
+ * Python's `%(asctime)s` — local time, with the comma before the milliseconds
+ * that `logging.Formatter` writes by default.
+ */
+export function formatTimestamp(date: Date): string {
+  return (
+    `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())} ` +
+    `${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}` +
+    `,${pad(date.getMilliseconds(), 3)}`
+  );
+}
+
+/** A filesystem-safe local-time stamp for the run directory's name. */
+export function formatRunStamp(date: Date): string {
+  return (
+    `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}T` +
+    `${pad(date.getHours())}-${pad(date.getMinutes())}-${pad(date.getSeconds())}`
+  );
+}
+
+/**
+ * `explico.<source>` — the logger name is the diagnostic's subsystem, so
+ * filtering by name is filtering by subsystem. `rawFloats` becomes
+ * `explico.raw-floats`; anything already lowercase passes through.
+ */
+export function loggerName(source: string): string {
+  const normalized = source
+    .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+    .toLowerCase();
+  return normalized.startsWith('explico.')
+    ? normalized
+    : `explico.${normalized}`;
+}
+
+/** One formatted line, without its trailing newline. */
+export function formatRecord(
+  level: LogLevel,
+  source: string,
+  message: string,
+  date: Date,
+): string {
+  return `${formatTimestamp(date)} ${level} ${loggerName(source)}: ${message}`;
+}
+
+export interface RunLogSummary {
+  /** Absolute path of this run's directory. */
+  readonly directory: string;
+  /** Repo-relative form, for printing. */
+  readonly relativeDirectory: string;
+  readonly counts: Readonly<Record<LogLevel, number>>;
+}
+
+/** One diagnostic, across every category's slightly different shape. */
+export interface AnyDiagnostic {
+  readonly severity?: string;
+  readonly message: string;
+  readonly code?: string;
+  readonly kind?: string;
+  readonly file?: string;
+  readonly line?: number;
+  readonly column?: number;
+}
+
+/** `manifest.diagnostics`, structurally — one array per subsystem. */
+export type DiagnosticGroups = Readonly<
+  Record<string, readonly AnyDiagnostic[]>
+>;
+
+export interface RunLog {
+  /** Absolute path of this run's directory. */
+  readonly directory: string;
+  /** Records at `ERROR` and returns `message`. */
+  error(source: string, message: string): string;
+  /** Records at `WARNING` and returns `message`. */
+  warning(source: string, message: string): string;
+  /** Records at `INFO` and returns `message`. */
+  info(source: string, message: string): string;
+  /**
+   * Sweeps every severity-`info` diagnostic in a manifest's `diagnostics` into
+   * `info.log`. Errors and warnings are deliberately **not** taken from here:
+   * they are recorded at the call site that also prints the console line, so
+   * the two can never drift.
+   */
+  infoDiagnostics(diagnostics: DiagnosticGroups): number;
+  /** Refreshes `latest` and reports what the run recorded. */
+  close(): RunLogSummary;
+}
+
+/** `[code] message`, matching what the console has always printed. */
+export function diagnosticLine(diagnostic: AnyDiagnostic): string {
+  const code = diagnostic.code ?? diagnostic.kind;
+  const at = [diagnostic.file, diagnostic.line, diagnostic.column]
+    .filter((part) => part !== undefined)
+    .join(':');
+  const prefix = code === undefined ? '' : `[${code}] `;
+  return at === ''
+    ? `${prefix}${diagnostic.message}`
+    : `${prefix}${at}: ${diagnostic.message}`;
+}
+
+export interface RunLogOptions {
+  /** Overridden in tests; defaults to `build/logs` under the repository root. */
+  readonly root?: string;
+  /** Overridden in tests so the directory name is deterministic. */
+  readonly now?: Date;
+  /** Set `false` to skip the `latest` symlink. */
+  readonly latest?: boolean;
+}
+
+/**
+ * Opens a run directory and returns its log. The directory and its three files
+ * are created up front, so a run that crashes before {@link RunLog.close} still
+ * leaves everything recorded up to that point on disk.
+ */
+export function createRunLog(options: RunLogOptions = {}): RunLog {
+  const root = options.root ?? LOGS_DIR;
+  const started = options.now ?? new Date();
+  const stamp = formatRunStamp(started);
+
+  // Two runs inside the same second get `…-2`, `…-3`, rather than collide.
+  let directory = join(root, stamp);
+  for (let suffix = 2; existsSync(directory); suffix += 1) {
+    directory = join(root, `${stamp}-${suffix}`);
+  }
+  mkdirSync(directory, { recursive: true });
+  for (const file of FILES) writeFileSync(join(directory, file.name), '');
+
+  const counts: Record<LogLevel, number> = { ERROR: 0, WARNING: 0, INFO: 0 };
+
+  const record = (level: LogLevel, source: string, message: string): string => {
+    counts[level] += 1;
+    const line = `${formatRecord(level, source, message, new Date())}\n`;
+    for (const file of FILES) {
+      if (includes(file.level, level)) {
+        appendFileSync(join(directory, file.name), line);
+      }
+    }
+    return message;
+  };
+
+  return {
+    directory,
+    error: (source, message) => record('ERROR', source, message),
+    warning: (source, message) => record('WARNING', source, message),
+    info: (source, message) => record('INFO', source, message),
+    infoDiagnostics(diagnostics) {
+      let written = 0;
+      for (const [source, group] of Object.entries(diagnostics)) {
+        if (!Array.isArray(group)) continue;
+        for (const diagnostic of group) {
+          if (diagnostic.severity !== 'info') continue;
+          record('INFO', source, diagnosticLine(diagnostic));
+          written += 1;
+        }
+      }
+      return written;
+    },
+    close() {
+      if (options.latest !== false) {
+        // Convenience only — a filesystem that refuses symlinks must not fail
+        // a content build that otherwise passed.
+        const link = join(root, 'latest');
+        try {
+          rmSync(link, { force: true });
+          symlinkSync(directory, link, 'dir');
+        } catch {
+          /* a missing `latest` is not worth failing a run over */
+        }
+      }
+      return {
+        directory,
+        relativeDirectory: relative(REPOSITORY_ROOT, directory),
+        counts: { ...counts },
+      };
+    },
+  };
+}

package/src/compiler/manifest.ts

@@ -186,8 +186,12 @@ import {
  * engine-authored sections, not written by a lesson, so they get their own
  * default independent of a course's `##` heading default; closed unless the
  * course sets one.
+ * v15 (diagnostic severity): public diagnostic severity unions add `info` for
+ * optional advice. Unused keys/definitions and restructuring candidates move
+ * from `warning` to `info`; their diagnostic codes and container fields stay
+ * unchanged.
  */
-export const MANIFEST_SCHEMA_VERSION = 14;
+export const MANIFEST_SCHEMA_VERSION = 15;
 
 const REPOSITORY_ROOT = process.cwd();
 // Content is the top-level `content/` folder; the build output is `build/`
@@ -453,11 +457,11 @@ export interface Manifest {
     readonly notation: readonly NotationDiagnostic[];
     readonly alignment: readonly NotationDiagnostic[];
     readonly math: readonly MathGateDiagnostic[];
-    /** Tier-3 corpus consistency checks (D6). Warnings only. */
+    /** Tier-3 corpus consistency checks (D6). Warnings and optional info. */
     readonly consistency: readonly ConsistencyDiagnostic[];
     /** Knowledge-version checks (C3): `about.version` vs `content/CHANGELOG.md`. Warnings only. */
     readonly knowledge: readonly KnowledgeVersionDiagnostic[];
-    /** Equation-identity checks (D7): `eq-duplicate-key`, `eq-ref-resolves` (error); `eq-key-unused` (warning). */
+    /** Equation identity: broken identities are errors; unused keys are info. */
     readonly equations: readonly EquationDiagnostic[];
     /** `<Table>` identity checks (F-tables-figures) — same codes, `tab-` prefixed. */
     readonly tables: readonly TableDiagnostic[];

package/src/components/memo/Memo.astro

@@ -239,8 +239,8 @@ if (!number || !anchorId) {
 <script>
   import { attachHoverPeek, closeHoverPeek } from '../disclosure/hover-preview';
   import { wirePersistedDetails } from '../disclosure/persisted-disclosure';
+  import { animatedScrollIntoView } from '../scroll-animation';
 
-  const reduceMotion = window.matchMedia('(prefers-reduced-motion: reduce)');
   let memoPreviewSerial = 0;
 
   function cloneMemoBody(body: HTMLElement): HTMLElement {
@@ -442,10 +442,7 @@ if (!number || !anchorId) {
             history.pushState(null, '', `#${details.id}`);
           }
           requestAnimationFrame(() => {
-            details.scrollIntoView({
-              behavior: reduceMotion.matches ? 'auto' : 'smooth',
-              block: 'start',
-            });
+            animatedScrollIntoView(details, { block: 'start' });
           });
         });
       }

package/src/components/memo/ShortNote.astro

@@ -116,7 +116,7 @@ if (!anchorId) {
 </style>
 
 <script>
-  const reduceMotion = window.matchMedia('(prefers-reduced-motion: reduce)');
+  import { animatedScrollIntoView } from '../scroll-animation';
 
   document
     .querySelectorAll<HTMLElement>('.short-note:not([data-short-note-wired])')
@@ -185,10 +185,7 @@ if (!anchorId) {
           history.pushState(null, '', `#${note.id}`);
         }
         requestAnimationFrame(() => {
-          note.scrollIntoView({
-            behavior: reduceMotion.matches ? 'auto' : 'smooth',
-            block: 'nearest',
-          });
+          animatedScrollIntoView(note, { block: 'nearest' });
         });
       };