explico 0.12.0 → 0.13.0

package/src/compiler/exports/zip.ts

@@ -0,0 +1,88 @@
+import { Buffer } from 'node:buffer';
+import { crc32, deflateRawSync } from 'node:zlib';
+
+/**
+ * A minimal, deterministic ZIP writer for export downloads: entries sorted by
+ * path, one fixed timestamp (1980-01-01, the format's epoch), UTF-8 names,
+ * deflate where it helps. The same files always give the same bytes, so a
+ * rebuild does not churn the published download.
+ */
+
+export interface ZipEntry {
+  /** Path inside the archive, `/`-separated, no leading slash. */
+  readonly path: string;
+  readonly content: string | Uint8Array;
+}
+
+const DOS_DATE_1980_01_01 = 0x0021;
+const UTF8_NAMES = 0x0800;
+const REGULAR_FILE_644 = 0o100644 << 16;
+
+export function zip(entries: readonly ZipEntry[]): Buffer {
+  const sorted = [...entries].sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+  const seen = new Set<string>();
+  const locals: Buffer[] = [];
+  const centrals: Buffer[] = [];
+  let offset = 0;
+  for (const entry of sorted) {
+    if (!entry.path || entry.path.startsWith('/') || entry.path.split('/').includes('..')) {
+      throw new Error(`Zip entry path ${JSON.stringify(entry.path)} is not a relative path.`);
+    }
+    if (seen.has(entry.path)) throw new Error(`Zip entry ${entry.path} appears twice.`);
+    seen.add(entry.path);
+    const name = Buffer.from(entry.path, 'utf8');
+    const data =
+      typeof entry.content === 'string' ? Buffer.from(entry.content, 'utf8') : Buffer.from(entry.content);
+    const deflated = deflateRawSync(data, { level: 9 });
+    const stored = deflated.length >= data.length;
+    const body = stored ? data : deflated;
+    const checksum = crc32(data) >>> 0;
+
+    const local = Buffer.alloc(30);
+    local.writeUInt32LE(0x04034b50, 0);
+    local.writeUInt16LE(20, 4);
+    local.writeUInt16LE(UTF8_NAMES, 6);
+    local.writeUInt16LE(stored ? 0 : 8, 8);
+    local.writeUInt16LE(0, 10);
+    local.writeUInt16LE(DOS_DATE_1980_01_01, 12);
+    local.writeUInt32LE(checksum, 14);
+    local.writeUInt32LE(body.length, 18);
+    local.writeUInt32LE(data.length, 22);
+    local.writeUInt16LE(name.length, 26);
+    local.writeUInt16LE(0, 28);
+    locals.push(local, name, body);
+
+    const central = Buffer.alloc(46);
+    central.writeUInt32LE(0x02014b50, 0);
+    central.writeUInt16LE((3 << 8) | 20, 4); // made by UNIX, ZIP 2.0
+    central.writeUInt16LE(20, 6);
+    central.writeUInt16LE(UTF8_NAMES, 8);
+    central.writeUInt16LE(stored ? 0 : 8, 10);
+    central.writeUInt16LE(0, 12);
+    central.writeUInt16LE(DOS_DATE_1980_01_01, 14);
+    central.writeUInt32LE(checksum, 16);
+    central.writeUInt32LE(body.length, 20);
+    central.writeUInt32LE(data.length, 24);
+    central.writeUInt16LE(name.length, 28);
+    central.writeUInt16LE(0, 30);
+    central.writeUInt16LE(0, 32);
+    central.writeUInt16LE(0, 34);
+    central.writeUInt16LE(0, 36);
+    central.writeUInt32LE(REGULAR_FILE_644 >>> 0, 38);
+    central.writeUInt32LE(offset, 42);
+    centrals.push(central, name);
+
+    offset += local.length + name.length + body.length;
+  }
+  const directory = Buffer.concat(centrals);
+  const end = Buffer.alloc(22);
+  end.writeUInt32LE(0x06054b50, 0);
+  end.writeUInt16LE(0, 4);
+  end.writeUInt16LE(0, 6);
+  end.writeUInt16LE(sorted.length, 8);
+  end.writeUInt16LE(sorted.length, 10);
+  end.writeUInt32LE(directory.length, 12);
+  end.writeUInt32LE(offset, 16);
+  end.writeUInt16LE(0, 20);
+  return Buffer.concat([...locals, directory, end]);
+}

package/src/compiler/lesson-derivation.ts

@@ -5,7 +5,7 @@
  * layout, the tests) goes through that one loader.
  *
  * Authored per lesson after C2: `title`, `description`, `teaches`, `assumptions`,
- * `editorialStatus`, `notation.local`. Everything below is derived:
+ * `notation.local`. Everything below is derived:
  *
  * - `lessonId`      — the doc slug, `/` → `.` (`foundations/discount-factors`).
  * - `requires`      — direct competency-graph prerequisites of `teaches`, minus
@@ -24,6 +24,8 @@
  * is redundant.
  */
 
+import { citedIds, withoutLinkCitations } from '../reference/citation-format.mjs';
+
 /** `foundations/discount-factors` → `foundations.discount-factors`. */
 export function lessonIdFromSlug(slug: string): string {
   return slug.replace(/\.(md|mdx)$/, '').replace(/\//g, '.');
@@ -39,6 +41,15 @@ export function isLessonSlug(slug: string): boolean {
   return clean.includes('/') && !clean.endsWith('/index');
 }
 
+/**
+ * The docs slugs a Starlight route id can stand for. The glob loader shortens
+ * `<dir>/index.mdx` to the id `<dir>`, and may give the landing page an empty
+ * one, so a manifest entry matches its route either way.
+ */
+export function docsSlugsForRoute(routeSlug: string): readonly string[] {
+  return routeSlug === '' ? ['index'] : [routeSlug, `${routeSlug}/index`];
+}
+
 /**
  * Direct prerequisites of everything the lesson `teaches`, minus the taught
  * competencies themselves, sorted. Editorial "you should also know" extras that
@@ -68,13 +79,7 @@ export function citedSourceIds(body: string): Set<string> {
   const withoutCode = body
     .replace(/```[\s\S]*?```/g, '')
     .replace(/`[^`\n]*`/g, '');
-  const ids = new Set<string>();
-  for (const match of withoutCode.matchAll(
-    /\[@([a-z0-9][a-z0-9.-]*)(?:;[^\]]*)?\]/g,
-  )) {
-    ids.add((match[1] ?? '').trim());
-  }
-  return ids;
+  return citedIds(withoutLinkCitations(withoutCode)) as Set<string>;
 }
 
 /** Cited source ids as a sorted array — the derived frontmatter `sources`. */