@wxxb789/anc 0.0.1

package/scripts/write-snapshot.js

@@ -0,0 +1,136 @@
+/**
+ * Build the public SQLite snapshot from a validated content artifact.
+ *
+ * This is the producer side of `docs/core-design/sqlite-contract.md`. It writes a
+ * fresh file (never copies and deletes from a previous snapshot, which would
+ * leave removed text in free pages), finalizes it, runs the integrity and
+ * foreign-key checks, validates the exact schema, and returns the binding the
+ * rest of the build threads through: the digest-named URL, the full digest, and
+ * the format constants.
+ *
+ * `node:sqlite` is the accepted build-time driver
+ * (`docs/core-design/architecture.md`). Determinism is a contract: fixed page
+ * size, explicit IDs in canonical slug/key order, primary-key insert order, no
+ * timestamps and no counters, so two builds of the same corpus are byte-equal.
+ */
+import { createHash } from 'node:crypto';
+import { mkdirSync, readFileSync, rmSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { DatabaseSync } from "../src/lib/sqlite.js";
+import { tagFacets } from "../src/lib/routes.js";
+import { NAV_LANGUAGE } from "../src/lib/translations.js";
+import { compareSlugs } from "../src/lib/route-path.js";
+import { SNAPSHOT_APPLICATION_ID, SNAPSHOT_PAGE_SIZE, SNAPSHOT_SCHEMA_SQL, SNAPSHOT_USER_VERSION, snapshotRoute, } from "../src/lib/snapshot.js";
+import { assertSnapshotRows } from "../src/lib/snapshot-contract.js";
+/**
+ * Compare slugs in the canonical order IDs are assigned in: Unicode code point
+ * order, which is what SQLite's BINARY collation gives `ORDER BY slug` and the
+ * `slug > ?` cursor. JavaScript `<` (UTF-16 units) disagrees for astral
+ * characters, and would make `ORDER BY id` and `ORDER BY slug` diverge.
+ */
+const bySlug = compareSlugs;
+/**
+ * Fail unless the file carries exactly the accepted schema.
+ *
+ * The contract itself lives in `src/lib/snapshot-contract.ts`, so the native and
+ * browser drivers validate the same rules; this adapts it to a `node:sqlite`
+ * handle. Called after finalization, before the file is hashed or copied.
+ */
+export function assertSnapshotContract(database) {
+    assertSnapshotRows((sql) => database.prepare(sql).all());
+}
+/**
+ * Write the snapshot for one artifact and return its binding.
+ *
+ * @throws if a relation names an unknown or self target, if SQLite rejects a row,
+ *   or if the finalized file fails integrity, foreign keys, or schema shape.
+ */
+export function writeSnapshot(artifact, destination) {
+    const entries = [...artifact.entries].sort((a, b) => bySlug(a.slug, b.slug));
+    const idBySlug = new Map(entries.map((entry, index) => [entry.slug, index + 1]));
+    // `tagFacets` owns the accepted normalization, collision failure, and
+    // representative-label rule; the snapshot must not re-derive it. Facets are
+    // already in canonical key order, so their position is the tag id.
+    const facets = tagFacets(artifact.entries);
+    const tagIdByKey = new Map(facets.map((facet, index) => [facet.key, index + 1]));
+    rmSync(destination, { force: true });
+    mkdirSync(dirname(destination), { recursive: true });
+    const database = new DatabaseSync(destination);
+    try {
+        // Fixed before the first page is allocated, so byte layout is reproducible.
+        database.exec(`PRAGMA page_size = ${SNAPSHOT_PAGE_SIZE}`);
+        database.exec('PRAGMA journal_mode = DELETE');
+        database.exec(SNAPSHOT_SCHEMA_SQL);
+        database.exec('PRAGMA foreign_keys = ON');
+        const enforced = database.prepare('PRAGMA foreign_keys').get();
+        if (enforced?.foreign_keys !== 1)
+            throw new Error('snapshot could not enable foreign-key enforcement');
+        const insertNode = database.prepare('INSERT INTO nodes (id, slug, title, excerpt, language) VALUES (?, ?, ?, ?, ?)');
+        const insertTag = database.prepare('INSERT INTO tags (id, key, label) VALUES (?, ?, ?)');
+        const insertAlias = database.prepare('INSERT INTO aliases (node_id, ordinal, alias) VALUES (?, ?, ?)');
+        const insertEdge = database.prepare('INSERT INTO edges (source_id, target_id) VALUES (?, ?)');
+        const insertMembership = database.prepare('INSERT INTO node_tags (tag_id, node_id) VALUES (?, ?)');
+        database.exec('BEGIN IMMEDIATE');
+        try {
+            for (const entry of entries) {
+                const id = idBySlug.get(entry.slug);
+                insertNode.run(id, entry.slug, entry.title, entry.excerpt, entry.language ?? NAV_LANGUAGE);
+            }
+            for (const [index, facet] of facets.entries())
+                insertTag.run(index + 1, facet.key, facet.label);
+            for (const entry of entries) {
+                const id = idBySlug.get(entry.slug);
+                for (const [ordinal, alias] of (entry.aliases ?? []).entries())
+                    insertAlias.run(id, ordinal, alias);
+            }
+            for (const entry of entries) {
+                const sourceId = idBySlug.get(entry.slug);
+                for (const target of [...entry.outgoing].sort(bySlug)) {
+                    const targetId = idBySlug.get(target);
+                    if (targetId === undefined) {
+                        throw new Error(`snapshot edge from "${entry.slug}" names unpublished target "${target}"`);
+                    }
+                    if (targetId === sourceId) {
+                        throw new Error(`snapshot edge from "${entry.slug}" targets itself`);
+                    }
+                    insertEdge.run(sourceId, targetId);
+                }
+            }
+            for (const facet of facets) {
+                const tagId = tagIdByKey.get(facet.key);
+                const memberIds = facet.entries
+                    .map((entry) => idBySlug.get(entry.slug))
+                    .sort((a, b) => a - b);
+                for (const nodeId of memberIds)
+                    insertMembership.run(tagId, nodeId);
+            }
+            database.exec('COMMIT');
+        }
+        catch (error) {
+            database.exec('ROLLBACK');
+            throw error;
+        }
+        const integrity = database.prepare('PRAGMA integrity_check').all();
+        if (integrity.length !== 1 || integrity[0].integrity_check !== 'ok') {
+            throw new Error(`snapshot integrity_check is not ok: ${JSON.stringify(integrity)}`);
+        }
+        const foreignKeys = database.prepare('PRAGMA foreign_key_check').all();
+        if (foreignKeys.length > 0) {
+            throw new Error(`snapshot foreign_key_check returned ${foreignKeys.length} row(s)`);
+        }
+        assertSnapshotContract(database);
+    }
+    finally {
+        database.close();
+    }
+    const bytes = readFileSync(destination);
+    const digest = createHash('sha256').update(bytes).digest('hex');
+    return {
+        url: snapshotRoute(digest),
+        digest,
+        applicationId: SNAPSHOT_APPLICATION_ID,
+        userVersion: SNAPSHOT_USER_VERSION,
+        path: destination,
+        size: bytes.length,
+    };
+}

package/src/components/CollectionExplorer.astro

@@ -0,0 +1,149 @@
+---
+/**
+ * The collection explorer: the corpus, grouped, as a real `<nav>`.
+ *
+ * Four properties are load-bearing, and each is a decision the parity plan's L5
+ * records against Quartz's explorer:
+ *
+ * 1. **Complete in the server-rendered HTML.** Quartz rebuilds a trie in the
+ *    browser from `contentIndex.json` and renders an empty `<ul>` with
+ *    JavaScript disabled — the whole navigation is gone. Every group and every
+ *    title here is written by the build.
+ * 2. **Collapse costs zero JavaScript.** `<details>`/`<summary>` is the native
+ *    disclosure: keyboard-operable, announced as one, and remembered by the
+ *    browser across a back-navigation. No script is loaded for it, and none
+ *    exists to load.
+ * 3. **The open group is the reader's own.** `collectionNavigation` marks the
+ *    group holding the current page and only that one is `open`, so the rail is
+ *    contextual without a preference to store or a state to sync. Quartz needs
+ *    `localStorage` and a `new Function()` comparator to reach the same place.
+ * 4. **It is chrome, not content.** `data-pagefind-ignore`: it renders on every
+ *    page, so without it every note's search record would carry the title of
+ *    every other note. This is the defect TK-12 fixed for the back link and the
+ *    heading anchors, and a rail is the largest possible instance of it.
+ *
+ * **Every group is listed; a large group's notes are windowed.** The rail used
+ * to render every published note on every page, which is quadratic in the
+ * corpus — `GROUP_WINDOW` in `collection-navigation.ts` carries the measurement
+ * and the reason the bound is what it is. What this component owes the bound is
+ * two things: the count beside a label is `group.total` rather than the size of
+ * the drawn slice, and the collection index link is rendered where a group has
+ * one, because on a windowed group that link is the expansion action.
+ *
+ * The heading is visually hidden rather than absent. A `<nav>` needs an
+ * accessible name — two unnamed navigations on a page are indistinguishable in a
+ * screen reader's landmark list, and this page has four — but a visible "Browse"
+ * heading above a list that already announces itself is chrome restating chrome.
+ */
+import type { ExplorerGroup } from '../lib/collection-navigation.js';
+import { partLanguage, translate } from '../lib/translations.js';
+
+interface Props {
+  groups: readonly ExplorerGroup[];
+  /** The page's own language. The group labels are artifact text and are not. */
+  lang: string;
+}
+
+const { groups, lang } = Astro.props;
+const t = translate(lang);
+---
+
+{/* Nothing to browse is not an empty rail: a corpus with one note in one group
+    would render a disclosure whose only content is the page already open. The
+    threshold is two notes, below which the site map in the footer already says
+    everything this would.
+
+    Summed over `total` rather than over `notes.length`, so the decision is about
+    how many notes the corpus has and not how many this page happens to draw. */}
+{groups.reduce((count, group) => count + group.total, 0) > 1 && (
+  <nav class="explorer" aria-labelledby="explorer-title" data-pagefind-ignore>
+    <h2 id="explorer-title" class="sr-only">{t.explorerHeading}</h2>
+    <ul class="explorer-groups">
+      {groups.map((group) => (
+        <li>
+          {/* `open` on the reader's own group only. A `<details>` carrying the
+              current page must never start closed — that is the one state where
+              the reader would have to open a disclosure to find where they
+              already are. */}
+          <details class="explorer-group" open={group.isCurrent}>
+            <summary>
+              <span class="explorer-label">{group.label}</span>
+              {/* Text, not a badge: nothing here is carried by colour or shape
+                  alone, and the count tells a reader whether opening the group
+                  costs them three lines or thirty.
+
+                  `group.total`, never `group.notes.length`: past
+                  `GROUP_WINDOW` the two differ, and the number a reader needs is
+                  how large the collection is rather than how much of it this
+                  page drew. */}
+              <span class="explorer-count">{group.total}</span>
+            </summary>
+            {/* The collection's own index page, where it has one. The
+                uncollected group has no route — see `ExplorerGroup.route` — and
+                links nothing rather than inventing a page for it.
+
+                The label is interpolated by the locale rather than concatenated
+                here: Chinese puts the modifier before the head noun with `的`,
+                so `All X notes` and `X 的全部笔记` cannot share a template. */}
+            {group.route !== undefined && (
+              <a class="explorer-index" href={group.route}>{t.explorerIndex(group.label)}</a>
+            )}
+            <ul class="explorer-notes">
+              {group.notes.map((note) => (
+                <li>
+                  {/* `aria-current="page"` on the note being read, and the
+                      stylesheet marks it with a weight and a rule as well as a
+                      colour. A reader who cannot see the colour still knows
+                      where they are.
+
+                      The window is what makes that mark *reachable*: past the
+                      rail's own row budget the marker rendered below the fold of
+                      the rail's scroll container, so on a 300-note site 40 of 40
+                      sampled pages showed a wall of titles that never included
+                      the reader's own. `windowAround` centres the slice on them.
+
+                      `lang` on a title whose language differs from the page's.
+                      The rail is still the largest concentration of foreign-
+                      language text on any page on a bilingual site. Every group
+                      of the 32-note fixture corpus is under the bound, so both
+                      directions render whole there — 4 Chinese titles on every
+                      English page and 28 English ones on every Chinese page. */}
+                  <a
+                    href={note.route}
+                    aria-current={note.isCurrent ? 'page' : undefined}
+                    lang={partLanguage(note.language, lang)}
+                  >{note.title}</a>
+                </li>
+              ))}
+            </ul>
+            {/* A windowed group says so, and says how to see the rest.
+                Rendered only where the window actually dropped something, so a
+                group drawing whole does not claim to be partial — the same rule
+                `NoteGraph.astro` applies to its own bound sentence, and the
+                same shown-of-total shape.
+
+                Without this the group is a contradiction a reader has to
+                resolve: a count of 376 beside twelve rows, with nothing saying
+                the twelve are a window. A screen reader hears "Uncollected,
+                376", walks twelve items, and reaches the end of the list.
+
+                The expansion link matters on the uncollected group, which
+                still contains every root-level note because only a first folder
+                produces a collection. The home page lists every published note,
+                so that is where it goes;
+                a group with its own index already links it above and does not
+                need a second route to the same idea. */}
+            {group.total > group.notes.length && (
+              <p class="explorer-bound">
+                <span>{t.explorerBounded(group.notes.length, group.total)}</span>
+                {group.route === undefined && (
+                  <a href="/" aria-label={t.explorerExpandLabel}>{t.explorerExpand}</a>
+                )}
+              </p>
+            )}
+          </details>
+        </li>
+      ))}
+    </ul>
+  </nav>
+)}

package/src/components/FacetIndex.astro

@@ -0,0 +1,45 @@
+---
+/**
+ * A tag or collection index: one link per group, or an honest empty state.
+ *
+ * The empty state is the normal case today, not an edge case. The artifact
+ * carries neither `tags` nor `collection`, and the ticket forbids both a 404
+ * and a fabricated grouping — so the page explains that the projection carries
+ * no such field yet, and lights up on its own as soon as one appears.
+ */
+import type { Facet } from '../lib/routes.js';
+import { translate } from '../lib/translations.js';
+
+interface Props {
+  facets: readonly Facet[];
+  /** Builds the route for one facet key. */
+  route: (key: string) => string;
+  /** Shown in place of the list when the artifact carries no such field. */
+  empty: string;
+  /** The page's own language, which decides the count's grammar. */
+  lang: string;
+}
+
+const { facets, route, empty, lang } = Astro.props;
+const t = translate(lang);
+---
+
+{facets.length === 0 ? (
+  <p class="empty-state">{empty}</p>
+) : (
+  <ul class="facet-list">
+    {facets.map((facet) => (
+      <li>
+        {/* The label is the artifact's own text — a tag reading `security` stays
+            `security` on a Chinese page, and `笔记` stays `笔记` on an English
+            one. Only the count beside it is chrome. */}
+        <a href={route(facet.key)}>{facet.label}</a>
+        {/* The count is text, not a colour or an icon: no information here is
+            carried by colour alone. Both callers count *notes* — a tag row says
+            how many notes carry the tag — so this is `noteCount` rather than a
+            per-facet noun. */}
+        <span class="facet-count">{t.noteCount(facet.entries.length)}</span>
+      </li>
+    ))}
+  </ul>
+)}

package/src/components/LinkedNotes.astro

@@ -0,0 +1,94 @@
+---
+/**
+ * A named list of notes related to this one, or an honest statement that there
+ * are none.
+ *
+ * Three of requirements section 9.2's regions are the same shape — outgoing
+ * links (item 8), backlinks (item 9), and the related-note fallback (item 10) —
+ * so they are one component rendered three times rather than three components
+ * that would drift apart. What differs is the heading, the empty message, and
+ * whether the derivation needs stating; all three are props.
+ *
+ * Two properties are load-bearing:
+ *
+ * 1. **The empty state is rendered, not omitted.** Ticket scope item 6 requires
+ *    it, and the reason is that a missing section and a section with nothing in
+ *    it are indistinguishable to a reader who cannot know the site has such a
+ *    section at all. An orphan note now says it is an orphan.
+ * 2. **No JavaScript, and no fetch.** Requirements section 13.1 states that
+ *    static backlinks need neither script nor a database round trip, and every
+ *    list here is resolved from the validated artifact during the build. This is
+ *    a capability where the site is already at parity with Quartz; moving it
+ *    into a query would give that away for nothing.
+ *
+ * The section is located by its `aria-labelledby` id rather than by a per-
+ * surface class: the three look identical by design, so a class that existed
+ * only to tell them apart would be an unstyled hook.
+ */
+import type { ContentEntry } from '../lib/content.js';
+import { noteRoute } from '../lib/routes.js';
+import { partLanguage, translate } from '../lib/translations.js';
+
+interface Props {
+  /** Identifies the region: the heading takes `<region>-title`, the aside points at it. */
+  region: string;
+  heading: string;
+  entries: readonly ContentEntry[];
+  /** Rendered in place of the list. Never omitted — see above. */
+  empty: string;
+  /** How the list was derived, where the heading does not already say. */
+  derivation?: string;
+  /** The page's own language, which decides the count's grammar. */
+  lang: string;
+}
+
+const { region, heading, entries, empty, derivation, lang } = Astro.props;
+const t = translate(lang);
+const titleId = `${region}-title`;
+---
+
+<aside class="relations" aria-labelledby={titleId}>
+  <div class="relations-heading">
+    <h2 id={titleId}>{heading}</h2>
+    {/* Text, not a badge: nothing here is carried by colour or shape alone. It
+        is also what makes a long list legible before it is read — a reader
+        meeting "Linked from" sees whether it is two notes or forty.
+
+        `noteCount` rather than a count and a noun assembled here: English
+        pluralises and Chinese does not, so the whole phrase is the locale's to
+        form. A shared `n === 1` branch would put an English rule on a language
+        that has none. */}
+    {entries.length > 0 && (
+      <span class="relations-count">{t.noteCount(entries.length)}</span>
+    )}
+  </div>
+
+  {/* Only alongside a list. The empty message already states the operative
+      half of the rule, and printing both makes the empty case read as two
+      sentences saying one thing. */}
+  {derivation !== undefined && entries.length > 0 && (
+    <p class="relations-derivation">{derivation}</p>
+  )}
+
+  {entries.length === 0 ? (
+    <p class="empty-state">{empty}</p>
+  ) : (
+    /*
+     * A grid, which is the whole of the large-list treatment: one column at
+     * 320 px, two or three once there is width, so forty backlinks are a block
+     * a reader takes in rather than a screen of scrolling. It stays one `<ul>`,
+     * so the count and the reading order are unchanged and a screen reader
+     * announces "list, 40 items" either way.
+     */
+    <ul class="relations-list">
+      {entries.map((entry) => (
+        <li>
+          {/* The linked note's own language, when it differs from this page's.
+              A bilingual corpus links across languages — three fixture notes
+              do — and an unmarked foreign title is read in the wrong voice. */}
+          <a href={noteRoute(entry.slug)} lang={partLanguage(entry.language, lang)}>{entry.title}</a>
+        </li>
+      ))}
+    </ul>
+  )}
+</aside>