tosijs-ui 1.7.3 → 1.8.0

package/CHANGELOG.md

@@ -1,5 +1,94 @@
 # 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
+  left of the site title, instead of always inheriting the tosijs-ui logo. Accepts the name of a
+  known icon (from `tosijs-ui`'s `icons`, e.g. `'tosiUi'`), an image URL / path / `data:` URI
+  (rendered as an `<img>`), or a raw inline `<svg>…</svg>` string. Threaded through
+  `SiteConfig.logo` (`tosijs-ui/site`), `createDocBrowser({ logo })`, and an embedded
+  `<tosi-doc-system config='{"logo":"…"}'>`. Omit it to keep the prior behavior: the tosijs-ui
+  logo when `projectLinks.tosijs` is set, otherwise no mark. Previously the header logo was
+  hard-wired to the tosijs-ui mark — the one branding element `SiteConfig` couldn't override.
+
 ## 1.7.3
 
 - **New `<tosi-pocket-bar>` component.** A "pocket buttonbar": a single translucent icon at

package/dist/doc-browser.d.ts

@@ -61,6 +61,17 @@ export interface DocBrowserOptions {
     context?: Record<string, any>;
     projectName?: string;
     projectLinks?: ProjectLinks;
+    /**
+     * The brand mark shown left of the site title in the header. One of:
+     * - the name of a known icon (from `icons`), e.g. `'tosiUi'`
+     * - 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. 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;
     minSize?: number;
     routing?: DocRoutingMode;

package/dist/doc-browser.js

@@ -163,7 +163,7 @@ import { tosiLocalized } from './localize';
 import { popMenu } from './menu';
 import { codeEditor } from './code-editor';
 import { tosiDiff } from './diff';
-const { div, span, a, header, button, template, input, h2, details, summary, ul, li, } = elements;
+const { div, span, a, header, button, template, input, h2, img, details, summary, ul, li, } = elements;
 // Test colors
 const testColor = {
     pass: varDefault.testColorPass('#0a0'),
@@ -254,11 +254,69 @@ const testIndicatorStyleSpec = {
         borderRadius: vars.roundedRadius,
     },
 };
+// 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. 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:
+// URI renders as an <img>, and anything else is treated as an icon(-composition)
+// name.
+function looksLikeImageUrl(s) {
+    return (/^(https?:)?\/\//.test(s) ||
+        s.startsWith('data:') ||
+        s.startsWith('/') ||
+        s.startsWith('./') ||
+        s.startsWith('../') ||
+        /\.(png|jpe?g|gif|webp|avif|svg|ico)(\?.*)?$/i.test(s));
+}
+function logoMark(logo, projectLinks) {
+    let mark = null;
+    if (logo) {
+        if (logo.trimStart().startsWith('<')) {
+            // 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;
+        }
+        else if (looksLikeImageUrl(logo)) {
+            mark = img({ src: logo, alt: '' });
+        }
+        else {
+            mark = icons[logo]();
+        }
+    }
+    else if (projectLinks.tosijs) {
+        mark = icons.tosiUi();
+    }
+    // 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;
 export function createDocBrowser(options) {
-    const { docs, context = {}, projectName = '', projectLinks = {}, navSize = 200, minSize = 600, routing = 'query', initialRoute, onRouteChange, navbarLinks, contentElement, } = options;
+    const { docs, context = {}, projectName = '', projectLinks = {}, logo, navSize = 200, minSize = 600, routing = 'query', initialRoute, onRouteChange, navbarLinks, contentElement, } = options;
     // Memory routing is fully self-contained: it never reads or writes
     // window.history/location, so an embedded or nested browser can't hijack the
     // host page's URL (or recurse into it).
@@ -522,11 +580,7 @@ export function createDocBrowser(options) {
                 alignItems: 'center',
                 borderBottom: 'none',
             },
-        }, projectLinks.tosijs
-            ? icons.tosiUi({
-                style: { _xinIconSize: 40, marginRight: 10 },
-            })
-            : span(), h2(projectName)));
+        }, logoMark(logo, projectLinks), h2(projectName)));
     }
     headerContent.push(span({ class: 'elastic' }));
     // A header link renders as an icon (if `icon` names a known icon) or its label.
@@ -1147,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/doc-system.js

@@ -409,6 +409,7 @@ export class TosiDocSystem extends Component {
             },
             projectName: config.projectName,
             projectLinks: config.projectLinks,
+            logo: config.logo,
             navbarLinks: navbarLinks.length ? navbarLinks : undefined,
             contentElement,
         });

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;