tosijs-ui 1.7.4 → 1.8.0

package/CHANGELOG.md

@@ -1,5 +1,83 @@
 # Changelog
 
+## 1.8.0
+
+> **Read this first if you use `tosijs-ui/site`.** This release adds a **dependency-audit
+> gate that is ON BY DEFAULT and can fail your build** — on advisories in _your_ dependency
+> tree, not ours. That is deliberate, and there are three ways out (below). Minor, not patch,
+> precisely because `bun run build` can now exit 1 where it previously didn't.
+
+- **New: dependency-audit gate** (`src/doc-system/site/audit-guard.ts`, exported from
+  `tosijs-ui/site`). `bun audit` knows the registry advisory database; nothing in a normal
+  build ever asked it, so a high-severity advisory in a transitive dep stayed invisible until
+  someone ran it by hand. Now it's asked at the point a human is looking.
+  - **Runs synchronously in every mode** — inside `buildSite` for `bun run build` / `--test`,
+    and in `devServer` **just before it binds the port** (it throws, so the server never comes
+    up). Sub-second in practice; a gate you wait for can't be raced. **Watch rebuilds never
+    audit** — that would put a network call in your edit loop and break offline dev.
+  - **What blocks:** any advisory at or above `level` (default `high`) that isn't gated.
+    Consumer-facing and developer-facing advisories block **alike** — a dev-only dependency
+    still runs on your machine, and the escape hatch makes over-blocking cheap.
+  - **Three ways out:** `audit: { allow: [{ advisory, reason, expires }] }` to accept a risk
+    **on a deadline** (an expired or malformed gate stops suppressing, so it comes back for
+    review instead of living in an allowlist nobody re-reads); `audit: { mode: 'warn' }` to
+    report without failing; `audit: false` or `TOSIJS_AUDIT=off` to disable.
+  - **Fails open, never closed, when it can't check** — offline, registry down, `bun` too old,
+    or past its 20s timeout: it warns and proceeds. It fails **closed** only on a real finding.
+  - **Not downgraded in CI.** Unlike the machine-health preflight (a heuristic about someone's
+    local box), an advisory is deterministic and environment-independent.
+  - **Findings are grouped, sorted worst-first, and annotated** with the _nature_ of the risk
+    (`LEAK/ALTER` / `DoS-only` / `DoS?+ESCALATABLE` / `UNCLASSIFIED`), parsed from the CVSS
+    vector (3.x and 4.0) plus CWEs. Annotation only — it never changes what blocks, and it
+    fails **closed**: ~20% of real advisories carry no CVSS vector at all, and those skew
+    severe. Sub-threshold advisories are listed compactly (previously collected and never
+    shown), plus an **advisories-per-package tally** — a dependency that keeps producing them
+    is a code smell worth replacing rather than patching.
+- **Fix (issue #24, reported by a consumer): nav `order` now sorts numerically.** Section nav
+  and the generated `<!-- toc -->` built a zero-padded *string* key and compared it lexically,
+  so a fractional order silently sorted to the **end** of its section — `order: 1.5` landed
+  after `2`, `3`, … because `"01.5" > "0002"` as text. "Insert a page at N.5" reads like a
+  supported idiom and did the opposite with no warning. The same padding capped `order` at 4
+  digits (10000+ overflowed the width) and mis-sorted negatives. `pinnedSort` is now a
+  multi-key comparator (pin bucket → numeric order → title → filename), which fixes all three.
+  **Removed `navSortKey`** (the string-key builder) — it was never in a public index, but was
+  reachable via the `./*` subpath, so: technically breaking. A string key cannot express this
+  ordering, so there is no corrected version of it.
+- **`src/doc-system/nav-tree.ts` was a binary file.** The old sort key joined title and
+  filename with a raw NUL byte, which makes macOS `grep` silently match **nothing** in that
+  file (exit 1, no message) — so searching it for any symbol came back empty and the sort bug
+  above was effectively unfindable. The comparator needs no delimiter; the NUL is gone.
+- **New: `openBrowser`** site-config option — opens the doc site on dev-server start, reusing
+  an existing tab on macOS rather than piling up new ones.
+- **New: `DEV_NO_WATCH=1`** serves the built site without watching. The E2E lane used to run
+  `bun start`, so a file watcher stayed live for the whole suite and could `rm -rf docs/` and
+  regenerate underneath a test mid-navigation — the lane flaked against its own build system,
+  which presents as a product bug.
+- **New public API on `tosijs-ui/site`:** `auditDependencies`, `reportAudit`,
+  `resolveAuditMode`, `classifyRisk`, `groupAdvisories`, `openBrowser`, plus their types.
+  `buildSite` takes an optional second argument (`{ skipAudit }`).
+- **Fix: `bun run test-browser` no longer reports success on a failed build.** It computed the
+  build result and launched the test run regardless, so a failing build (or a blocking
+  advisory) still went green. One-shot modes now exit 1.
+- **Fix: the E2E lane can register ServiceWorkers over the dev cert.** `ignoreHTTPSErrors` is a
+  browser-_context_ option and never covered a ServiceWorker's own script fetch, so the
+  import-resolver worker failed to register and `hydration.pw.ts` caught it as a console error.
+  Chromium now launches with `--ignore-certificate-errors`.
+- **Dependency pins:** `overrides` for `flatted` (`>=3.4.2`) and `brace-expansion` (`>=5.0.8`)
+  clear live high-severity advisories. Added `.github/dependabot.yml` so advisories published
+  later against an unchanged lockfile still surface.
+- Includes the unpublished 1.7.5 (header-logo sizing) — npm goes 1.7.4 → 1.8.0.
+
+## 1.7.5
+
+- **Header logo size/spacing are now CSS-tunable** (follow-up to 1.7.4). The brand mark no
+  longer hard-wires a pixel height inline; it carries a `.logo-mark` class driven by two
+  variables — `--tosi-logo-mark-size` (default **32px**, was a fixed 40px) and
+  `--tosi-logo-mark-gap` (default 10px) — for icon, `<img>`, and inline-`<svg>` logos alike.
+  (Icon `<svg>`s take their height from `--tosi-icon-size`, set inline by `makeIcon()`, so the
+  class points that knob at the same variable rather than fighting the inline height.) Retune a
+  logo from CSS instead of editing the build.
+
 ## 1.7.4
 
 - **Configurable header logo.** A new `logo` option lets a doc site set the brand mark shown

package/dist/doc-browser.d.ts

@@ -67,7 +67,9 @@ export interface DocBrowserOptions {
      * - an image URL / path / data: URI (rendered as an `<img>`)
      * - a raw inline `<svg …>…</svg>` string
      * Omit to fall back to the tosijs-ui logo when `projectLinks.tosijs` is set,
-     * or to no mark at all otherwise.
+     * or to no mark at all otherwise. Size and spacing are CSS-tunable via
+     * `--tosi-logo-mark-size` (default 32px) and `--tosi-logo-mark-gap` (default
+     * 10px) on the `.logo-mark` element.
      */
     logo?: string;
     navSize?: number;

package/dist/doc-browser.js

@@ -257,9 +257,9 @@ const testIndicatorStyleSpec = {
 // The brand mark shown left of the site title. `logo` (from config) may name a
 // known icon, be an inline `<svg>` string, or be an image URL; when absent we
 // keep the legacy behavior — the tosijs-ui logo iff this is a tosijs project,
-// else nothing. Sized to match the header height so hydration doesn't reflow.
-const LOGO_SIZE = 40;
-const LOGO_GAP = 10;
+// else nothing. Size and spacing are class-driven (`.logo-mark`, see
+// logoMarkStyleSpec) so a consumer retunes them with one CSS variable each,
+// rather than a hard-wired pixel value.
 // `icons` is a Proxy that returns a factory for ANY string (unknown names get a
 // placeholder glyph), so we can't ask it whether a name is real — we route by the
 // shape of the string instead: an inline `<svg>` renders as-is, a URL/path/data:
@@ -274,33 +274,44 @@ function looksLikeImageUrl(s) {
         /\.(png|jpe?g|gif|webp|avif|svg|ico)(\?.*)?$/i.test(s));
 }
 function logoMark(logo, projectLinks) {
+    let mark = null;
     if (logo) {
         if (logo.trimStart().startsWith('<')) {
-            const holder = span({
-                style: {
-                    display: 'inline-flex',
-                    height: `${LOGO_SIZE}px`,
-                    marginRight: `${LOGO_GAP}px`,
-                },
-            });
-            holder.innerHTML = logo;
-            return holder;
+            // Inline <svg>: wrap in a flex holder so `.logo-mark`'s height sizes it.
+            mark = span({ style: { display: 'inline-flex', alignItems: 'center' } });
+            mark.innerHTML = logo;
         }
-        if (looksLikeImageUrl(logo)) {
-            return img({
-                src: logo,
-                alt: '',
-                style: { height: `${LOGO_SIZE}px`, marginRight: `${LOGO_GAP}px` },
-            });
+        else if (looksLikeImageUrl(logo)) {
+            mark = img({ src: logo, alt: '' });
         }
-        return icons[logo]({
-            style: { _xinIconSize: LOGO_SIZE, marginRight: LOGO_GAP },
-        });
+        else {
+            mark = icons[logo]();
+        }
+    }
+    else if (projectLinks.tosijs) {
+        mark = icons.tosiUi();
     }
-    return projectLinks.tosijs
-        ? icons.tosiUi({ style: { _xinIconSize: LOGO_SIZE, marginRight: LOGO_GAP } })
-        : span();
+    // No mark → an empty span with NO class, so it carries no margin (the title
+    // stays flush; a flex `gap` on the header link couldn't do that).
+    if (!mark)
+        return span();
+    mark.classList.add('logo-mark');
+    return mark;
 }
+const logoMarkStyleSpec = {
+    '.logo-mark': {
+        height: 'var(--tosi-logo-mark-size, 32px)',
+        // An icon <svg> takes its height from --tosi-icon-size, set INLINE on the svg
+        // by makeIcon() — which beats a class `height` rule. Point that knob at the
+        // same variable so one --tosi-logo-mark-size drives an icon, an <img>, or an
+        // inline <svg> alike.
+        _tosiIconSize: 'var(--tosi-logo-mark-size, 32px)',
+        marginRight: 'var(--tosi-logo-mark-gap, 10px)',
+        flexShrink: '0',
+    },
+    // Inline-<svg> logos are wrapped in a flex holder; scale the embedded svg to it.
+    '.logo-mark > svg': { height: '100%', width: 'auto' },
+};
 // Monotonic per-page counter so each createDocBrowser() call gets a distinct
 // tosi() registry key (see stateKey below) and two browsers can't share state.
 let docBrowserSeq = 0;
@@ -1190,6 +1201,8 @@ export function createDocBrowser(options) {
     showDoc(currentDoc);
     // Inject test indicator styles
     StyleSheet('test-indicators', testIndicatorStyleSpec);
+    // Header brand-mark sizing (icon / <img> / inline-<svg>), one CSS var each.
+    StyleSheet('doc-logo-mark', logoMarkStyleSpec);
     // Floating widget for test status
     const testWidget = button({
         class: 'test-widget',

package/dist/doc-system/nav-tree.d.ts

@@ -14,12 +14,31 @@ export interface NavNode<T extends NavDoc = NavDoc> {
     depth: number;
 }
 /**
- * Total-order sort key: pin bucket (top<none<bottom), then `order` (default
- * 500), then title, then filename. The filename tiebreak guarantees a stable
- * total order even for equal titles — required so the generated TOC blocks are
- * idempotent (no build-to-build churn).
+ * Total order: pin bucket (top<none<bottom), then `order` (NUMERIC, default 500),
+ * then title, then filename. The filename tiebreak guarantees a stable total order
+ * even for equal titles — required so the generated TOC blocks are idempotent (no
+ * build-to-build churn).
+ *
+ * This is a multi-key COMPARATOR, not a concatenated string key, and that is the
+ * whole point (issue #24, reported by a consumer). The old version built
+ * `bucket + String(order).padStart(4,'0') + title + filename` and compared it
+ * lexically, so `order` sorted as TEXT:
+ *
+ *   order 1   -> "0001"
+ *   order 2   -> "0002"
+ *   order 1.5 -> String(1.5) = "1.5" -> padStart(4,'0') = "01.5"
+ *
+ * and lexically "01.5" > "0002" (at index 1, '1' > '0'), so a doc at 1.5 sorted
+ * AFTER 2, 3, ... — last in its section. "Insert a page at N.5" reads like a
+ * supported idiom and silently did the opposite, with no warning. The same padding
+ * also capped `order` at 4 digits (10000+ overflowed the width) and mis-sorted
+ * negatives. Comparing numbers as numbers fixes all three.
+ *
+ * The old key also joined title and filename with a raw NUL byte, which made this
+ * file BINARY: macOS grep then silently matches nothing in it (exit 1, no message),
+ * so searching this file for any symbol came back empty and the padStart bug was
+ * effectively unfindable. A comparator needs no delimiter, so the NUL is gone.
  */
-export declare function navSortKey(doc: NavDoc): string;
 export declare function pinnedSort(a: NavDoc, b: NavDoc): number;
 /**
  * Build the forest of top-level nav nodes. Children are grouped under their

package/dist/doc-system/site/audit-guard.d.ts

@@ -0,0 +1,124 @@
+export type AuditSeverity = 'info' | 'low' | 'moderate' | 'high' | 'critical';
+export type AuditMode = 'fail' | 'warn' | 'off';
+/** One advisory as `bun audit --json` reports it, flattened with its package. */
+export interface AuditAdvisory {
+    package: string;
+    id: number;
+    url: string;
+    title: string;
+    severity: AuditSeverity;
+    vulnerableVersions?: string;
+    /** GHSA id parsed from `url`, e.g. 'GHSA-25h7-pfq9-p65f' (if present) */
+    ghsa?: string;
+    /** what KIND of harm this is — annotation only, never changes whether it blocks */
+    risk?: Classification;
+}
+export type RiskNature = 
+/** C or I impact — can leak or alter data / execute code */
+'compromise'
+/** availability-only — resource exhaustion, hang, crash */
+ | 'dos'
+/** no or unparseable vector, or an escalatable CWE — assume the worst */
+ | 'unknown';
+export interface Classification {
+    nature: RiskNature;
+    /** short label for the report line */
+    label: string;
+    /** what drove the call, so the reader can second-guess it */
+    basis: string;
+}
+/** Classify one advisory's nature from its CVSS vector + CWEs. Fails CLOSED. */
+export declare function classifyRisk(raw: {
+    cvss?: {
+        vectorString?: string;
+    } | null;
+    cwe?: string[] | null;
+}): Classification;
+/**
+ * A time-boxed exception. A gate suppresses a matching advisory ONLY while it is
+ * valid and unexpired — after `expires` it stops suppressing and the build fails
+ * again, which is the point: an accepted risk gets re-evaluated on a deadline
+ * rather than living forever in an allowlist nobody re-reads.
+ */
+export interface AuditGate {
+    /** GHSA id, the numeric advisory id, or a package name (package match is broad) */
+    advisory: string;
+    /** why this is temporarily allowed — required, non-empty */
+    reason: string;
+    /** YYYY-MM-DD; on/after this date the gate no longer suppresses — required */
+    expires: string;
+}
+export interface AuditConfig {
+    /** 'fail' (default) blocks the build; 'warn' reports and proceeds; 'off' skips it */
+    mode?: AuditMode;
+    /** minimum severity that blocks, default 'high' */
+    level?: AuditSeverity;
+    /** time-boxed exceptions */
+    allow?: AuditGate[];
+}
+export interface GatedFinding {
+    advisory: AuditAdvisory;
+    reason: string;
+    /** whole days until the gate expires (active gate) */
+    daysLeft?: number;
+    /** whole days since the gate expired (expired gate) */
+    daysAgo?: number;
+}
+export interface AuditResult {
+    /** did the audit actually run and parse? false => fail-open, treated as pass */
+    ran: boolean;
+    /** no blocking findings (or couldn't run) */
+    ok: boolean;
+    mode: AuditMode;
+    level: AuditSeverity;
+    /** at/above threshold and NOT suppressed — these fail the build */
+    blocking: AuditAdvisory[];
+    /** suppressed by a valid, unexpired gate */
+    gated: GatedFinding[];
+    /** matched a gate whose expiry has passed — NOT suppressed (also in `blocking`) */
+    expired: GatedFinding[];
+    /** gates that are structurally invalid (missing reason/expires) — ignored */
+    invalid: Array<{
+        gate: AuditGate;
+        problem: string;
+    }>;
+    /** valid gates that matched no current advisory — safe to delete */
+    stale: AuditGate[];
+    /** findings below the blocking threshold (reported, never blocking) */
+    belowThreshold: AuditAdvisory[];
+}
+/** Injectable subprocess seam for tests. */
+export type AuditRunner = () => Promise<string>;
+export declare const AUDIT_TIMEOUT_MS = 20000;
+/**
+ * Parse `bun audit --json` output — `{ "<pkg>": [advisory, …] }` — into a flat
+ * advisory list. Returns null when the text is not a JSON object (offline, an
+ * error dump, an incompatible bun): the caller reads null as "couldn't check".
+ */
+export declare function parseAuditJson(text: string): AuditAdvisory[] | null;
+/** Resolve the effective mode from config + the TOSIJS_AUDIT env override. */
+export declare function resolveAuditMode(config: boolean | AuditConfig | undefined): AuditMode;
+/** Test-only: forget the per-process audit memo. */
+export declare function resetAuditMemo(): void;
+/**
+ * Run `bun audit`, classify findings against the configured threshold and the
+ * time-boxed allowlist, and return a structured verdict. Never exits.
+ *
+ * Memoized per process (see above) unless `opts.runAudit` is injected.
+ */
+export declare function auditDependencies(config: boolean | AuditConfig | undefined, opts?: {
+    now?: Date;
+    runAudit?: AuditRunner;
+}): Promise<AuditResult>;
+export interface GroupedAdvisory {
+    advisory: AuditAdvisory;
+    /** every vulnerable range this advisory matched for this package */
+    ranges: string[];
+}
+export declare function groupAdvisories(advisories: AuditAdvisory[]): GroupedAdvisory[];
+/**
+ * Print the verdict. Blocking findings first (why the build is failing), then
+ * active gates, expired/invalid gates, stale gates, and — when blocking — the
+ * due-diligence footer. Returns nothing; the caller decides what to do with `ok`.
+ */
+export declare function reportAudit(result: AuditResult, label?: string): void;