@chrisdudek/yg 5.3.0 → 5.4.0

package/dist/templates/portal/js/router.js

@@ -0,0 +1,169 @@
+/*
+ * URL-hash router — the deep-link grammar for every view and entity.
+ *
+ * The portal is a single page, but EVERY view and EVERY entity (node / aspect / flow,
+ * down to a per-verdict node→aspect→file-unit) is deep-linkable: a hash routes straight
+ * to it, and reloading the page reopens exactly what the hash names (an entity reopens
+ * its panel). The grammar:
+ *
+ *   (empty)                                  -> { view: 'overview' }            (default)
+ *   #/view/<viewId>                          -> { view: <viewId> }
+ *   #/node/<path>                            -> { view: 'tree',  node: <path> }
+ *   #/node/<path>/<aspectId>/<file-unit>     -> { ..., aspect, file }          (per-verdict)
+ *   #/aspect/<id>                            -> { view: 'rulebook', aspect: <id> }
+ *   #/flow/<name>                            -> { view: 'flows', flow: <name> }
+ *
+ * Each path segment is percent-encoded, so a node path with slashes, or a file unit with
+ * its own slashes, round-trips losslessly. parse() and serialize() are PURE string
+ * functions (no DOM, no window) so they are testable directly; start() wires them to the
+ * live `hashchange` event. Browser globals only — no network, no Node.
+ */
+(function () {
+  'use strict';
+
+  var Yg = (window.YgPortal = window.YgPortal || {});
+
+  // The known full-view ids. An unknown view id falls back to the overview so a stale or
+  // hand-typed hash never lands on a blank page.
+  var VIEWS = [
+    'overview',
+    'coverage',
+    'tree',
+    'relations',
+    'rulebook',
+    'types',
+    'flows',
+    'suppressions',
+    'start',
+  ];
+
+  // Which view an entity kind opens into (the entity's natural home surface).
+  var ENTITY_VIEW = { node: 'tree', aspect: 'rulebook', flow: 'flows' };
+
+  function isKnownView(id) {
+    return VIEWS.indexOf(id) !== -1;
+  }
+
+  /** Split a hash into clean, decoded segments (drops the leading '#', '/' and empties). */
+  function segments(hash) {
+    var raw = String(hash || '');
+    if (raw.charAt(0) === '#') raw = raw.slice(1);
+    if (raw.charAt(0) === '/') raw = raw.slice(1);
+    if (raw.length === 0) return [];
+    return raw.split('/').map(decodeSegment);
+  }
+
+  function decodeSegment(seg) {
+    try {
+      return decodeURIComponent(seg);
+    } catch (_e) {
+      return seg;
+    }
+  }
+
+  /**
+   * Parse a hash string into a normalized route object. Always returns a valid route — an
+   * empty or malformed hash resolves to the default overview, never null. The route always
+   * carries a `view`; entity fields (node / aspect / flow / file) are present only when the
+   * hash names them.
+   */
+  function parse(hash) {
+    var segs = segments(hash);
+    if (segs.length === 0) return { view: 'overview' };
+
+    var kind = segs[0];
+
+    if (kind === 'view') {
+      var id = segs[1];
+      if (isKnownView(id)) return { view: id };
+      return { view: 'overview', notFound: id || '(none)' };
+    }
+
+    if (kind === 'node' && segs[1]) {
+      var route = { view: ENTITY_VIEW.node, node: segs[1] };
+      // Per-verdict file unit: node / aspectId / file-unit (file may itself contain '/').
+      if (segs.length >= 4) {
+        route.aspect = segs[2];
+        route.file = segs.slice(3).join('/');
+      }
+      return route;
+    }
+
+    if (kind === 'aspect' && segs[1]) {
+      return { view: ENTITY_VIEW.aspect, aspect: segs[1] };
+    }
+
+    if (kind === 'flow' && segs[1]) {
+      return { view: ENTITY_VIEW.flow, flow: segs[1] };
+    }
+
+    // Bare `#/view-id` shorthand (no `view/` prefix) — accept a known view id directly.
+    if (isKnownView(kind)) return { view: kind };
+
+    // An unrecognized hash — degrade to overview but carry the requested token so the page can
+    // say "nothing here" honestly, instead of silently presenting overview as if it resolved.
+    return { view: 'overview', notFound: segs.join('/') };
+  }
+
+  function enc(seg) {
+    return encodeURIComponent(String(seg));
+  }
+
+  /**
+   * Serialize a route object back into a canonical hash string. The inverse of parse for
+   * any route parse() produces, so a round-trip is lossless. A node route with a per-verdict
+   * file unit encodes node / aspect / file as separate segments (the file's own slashes are
+   * percent-encoded inside its single segment).
+   */
+  function serialize(route) {
+    if (!route || !route.view) return '#/view/overview';
+
+    if (route.node) {
+      var parts = ['#', 'node', enc(route.node)];
+      if (route.aspect && route.file) {
+        parts.push(enc(route.aspect));
+        parts.push(enc(route.file));
+      }
+      return parts.join('/');
+    }
+    if (route.aspect) return '#/aspect/' + enc(route.aspect);
+    if (route.flow) return '#/flow/' + enc(route.flow);
+    return '#/view/' + enc(route.view);
+  }
+
+  /**
+   * Create a router bound to the live location. `onRoute(route)` fires on every hash change
+   * and once at start with the current route. `go(route)` updates the hash (which triggers
+   * onRoute via the hashchange listener — one code path, no double render). Returns a small
+   * controller; `current()` reads the live route without navigating.
+   */
+  function create(onRoute) {
+    function emit() {
+      onRoute(parse(window.location.hash));
+    }
+    function go(route) {
+      var next = serialize(route);
+      if (window.location.hash === next) {
+        emit(); // same hash — re-emit so a repeat selection still re-renders
+      } else {
+        window.location.hash = next;
+      }
+    }
+    function current() {
+      return parse(window.location.hash);
+    }
+    function start() {
+      window.addEventListener('hashchange', emit);
+      emit();
+    }
+    return { go: go, current: current, start: start };
+  }
+
+  Yg.router = {
+    VIEWS: VIEWS,
+    parse: parse,
+    serialize: serialize,
+    create: create,
+    isKnownView: isKnownView,
+  };
+})();

package/dist/templates/portal/js/shell.js

@@ -0,0 +1,264 @@
+/*
+ * Shell — the persistent three-region chrome rendered on every view.
+ *
+ * Builds and owns the frame the whole portal lives in:
+ *   - LEFT nav rail: brand (-> overview), a ⌘K trigger, and the grouped view links
+ *     ("Get oriented" / "Inspect & audit"), the active one highlighted.
+ *   - TOP bar: a live-status pill + Refresh + Approve control cluster, a breadcrumb, the
+ *     ⌘K search trigger, a write/view-only indicator, and the theme toggle.
+ *   - RIGHT panel slot: an empty mount the Node Attestation panel slides into on selection.
+ *   - CENTER stage: the mount the view dispatcher renders the current view into.
+ *
+ * The shell is built ONCE; navigation only swaps the center stage and updates the rail
+ * highlight + breadcrumb, so the chrome is stable. Browser globals only — Refresh/Approve
+ * are wired by the boot to the server (or disabled on a static page); no network here.
+ */
+(function () {
+  'use strict';
+
+  var Yg = (window.YgPortal = window.YgPortal || {});
+  var dom = Yg.dom;
+
+  // Nav rail groups -> view ids, mirroring §3a primary navigation.
+  var NAV_GROUPS = [
+    {
+      title: 'Get oriented',
+      items: [
+        { view: 'overview', glyph: '◧', label: 'Overview' },
+        { view: 'start', glyph: '◆', label: 'Start here' },
+        { view: 'flows', glyph: '⤳', label: 'Flows' },
+        { view: 'rulebook', glyph: '▤', label: 'Rulebook' },
+        { view: 'types', glyph: '◇', label: 'Type model' },
+      ],
+    },
+    {
+      title: 'Inspect & audit',
+      items: [
+        { view: 'coverage', glyph: '▦', label: 'Coverage & audit' },
+        { view: 'tree', glyph: '⌗', label: 'Structure' },
+        { view: 'relations', glyph: '↔', label: 'Relations & boundaries' },
+        { view: 'suppressions', glyph: '⛉', label: 'Suppressions' },
+      ],
+    },
+  ];
+
+  /**
+   * Build the shell into `root` for a given PortalData. `handlers` carries the user actions
+   * the chrome triggers: { onNavigate(view), onSearch(), onRefresh(), onApprove(), onTheme() }.
+   * Returns a controller exposing the live region mounts and the per-navigation updaters.
+   */
+  function build(root, data, handlers) {
+    dom.clear(root);
+    var app = dom.el('div', 'app-grid');
+
+    var rail = buildRail(data, handlers);
+    var main = dom.el('main', 'app-main');
+    var topbar = buildTopbar(data, handlers);
+    var stage = dom.el('div', 'app-stage');
+    main.appendChild(topbar.el);
+    main.appendChild(stage);
+
+    var panel = dom.el('aside', 'app-panel');
+    panel.setAttribute('aria-label', 'Node attestation panel');
+
+    app.appendChild(rail.el);
+    app.appendChild(main);
+    app.appendChild(panel);
+
+    // The honest key as ONE pinned, collapsible bottom bar — built once here, never inside a
+    // view's scrolling stage, so it can be pinned and the stage clears it via its bottom padding.
+    if (Yg.dispatch && typeof Yg.dispatch.buildLegendBar === 'function') {
+      app.appendChild(Yg.dispatch.buildLegendBar());
+    }
+
+    root.appendChild(app);
+
+    return {
+      stage: stage,
+      panel: panel,
+      setActive: function (view) {
+        rail.setActive(view);
+      },
+      setBreadcrumb: function (route) {
+        topbar.setBreadcrumb(route);
+      },
+      setFreshness: function (text, tone) {
+        topbar.setFreshness(text, tone);
+      },
+    };
+  }
+
+  function buildRail(data, handlers) {
+    var rail = dom.el('aside', 'app-rail');
+    rail.setAttribute('aria-label', 'Primary navigation');
+
+    var brand = dom.el('button', 'rail-brand');
+    brand.type = 'button';
+    // The brand mark: reuse the inline data: URI the serializer injected into the favicon
+    // link (single source, no network). Guarded so the non-DOM test sandbox (no querySelector)
+    // and any environment lacking the link simply omit the mark rather than break. The mark is
+    // decorative (alt=''), as the adjacent text already names the product.
+    var favicon = document.querySelector && document.querySelector('link[rel~="icon"]');
+    if (favicon && favicon.getAttribute('href')) {
+      var logo = dom.el('img', 'rail-logo');
+      logo.src = favicon.getAttribute('href');
+      logo.alt = '';
+      brand.appendChild(logo);
+    }
+    brand.appendChild(dom.el('b', null, 'Yggdrasil'));
+    // A static export is a frozen snapshot (no server), not a live view — say so honestly.
+    var brandSub = !Yg.consumer.isServed() ? 'snapshot' : data.meta.writeEnabled ? 'live view' : 'view-only';
+    brand.appendChild(dom.el('span', 'rail-brand-sub', brandSub));
+    brand.addEventListener('click', function () {
+      handlers.onNavigate('overview');
+    });
+    rail.appendChild(brand);
+
+    var cmdk = dom.el('button', 'rail-cmdk');
+    cmdk.type = 'button';
+    cmdk.appendChild(dom.el('span', null, '⌕ Search…'));
+    cmdk.appendChild(dom.el('kbd', null, '⌘K'));
+    cmdk.addEventListener('click', function () {
+      handlers.onSearch();
+    });
+    rail.appendChild(cmdk);
+
+    var links = {};
+    for (var g = 0; g < NAV_GROUPS.length; g += 1) {
+      var grp = NAV_GROUPS[g];
+      rail.appendChild(dom.el('div', 'rail-h', grp.title));
+      var nav = dom.el('nav', 'rail-nav');
+      for (var i = 0; i < grp.items.length; i += 1) {
+        nav.appendChild(buildLink(grp.items[i], handlers, links));
+      }
+      rail.appendChild(nav);
+    }
+
+    return {
+      el: rail,
+      setActive: function (view) {
+        for (var key in links) {
+          if (!Object.prototype.hasOwnProperty.call(links, key)) continue;
+          if (key === view) links[key].classList.add('on');
+          else links[key].classList.remove('on');
+        }
+      },
+    };
+  }
+
+  function buildLink(item, handlers, links) {
+    var a = dom.el('button', 'rail-link');
+    a.type = 'button';
+    a.appendChild(dom.el('span', 'rail-glyph', item.glyph));
+    a.appendChild(dom.el('span', null, item.label));
+    a.addEventListener('click', function () {
+      handlers.onNavigate(item.view);
+    });
+    links[item.view] = a;
+    return a;
+  }
+
+  function buildTopbar(data, handlers) {
+    var bar = dom.el('div', 'app-topbar');
+
+    var live = dom.el('span', 'topbar-live');
+    var dot = dom.el('span', 'topbar-dot');
+    live.appendChild(dot);
+    var liveText = dom.el(
+      'span',
+      null,
+      !Yg.consumer.isServed()
+        ? 'Exported snapshot — re-run yg portal for a live view'
+        : data.meta.writeEnabled
+          ? 'Live · re-checks free on refresh'
+          : 'View-only',
+    );
+    live.appendChild(liveText);
+    bar.appendChild(live);
+
+    var crumb = dom.el('span', 'topbar-crumb', '');
+    bar.appendChild(crumb);
+
+    var spacer = dom.el('span', 'topbar-spacer');
+    bar.appendChild(spacer);
+
+    // Refresh and Approve are live ONLY when the page is served by `yg portal`. On a static
+    // export they cannot reach the server, so they are disabled UP FRONT with a plain reason
+    // (never click-to-discover), and the page never presents a write it cannot perform.
+    var served = Yg.consumer.isServed();
+    var staticReason = 'Available only when the portal is served by `yg portal` — this is a read-only export.';
+
+    var refresh = dom.el('button', 'btn topbar-refresh');
+    refresh.type = 'button';
+    refresh.appendChild(dom.el('span', null, '↻ Refresh'));
+    refresh.appendChild(dom.el('span', 'btn-free', 'free'));
+    refresh.addEventListener('click', function () {
+      handlers.onRefresh();
+    });
+    if (!served) {
+      refresh.disabled = true;
+      refresh.title = staticReason;
+      refresh.setAttribute('aria-label', 'Refresh — ' + staticReason);
+    }
+    bar.appendChild(refresh);
+
+    var approve = dom.el('button', 'btn primary topbar-approve', '✓ Approve');
+    approve.type = 'button';
+    approve.disabled = !data.meta.writeEnabled || !served;
+    if (approve.disabled) {
+      var approveReason = !served ? staticReason : 'View-only mode (--no-write) — approving is disabled.';
+      approve.title = approveReason;
+      approve.setAttribute('aria-label', '✓ Approve — ' + approveReason);
+    }
+    approve.addEventListener('click', function () {
+      handlers.onApprove();
+    });
+    bar.appendChild(approve);
+
+    var search = dom.el('button', 'btn topbar-search', '⌕');
+    search.type = 'button';
+    search.setAttribute('aria-label', 'Open command palette');
+    search.addEventListener('click', function () {
+      handlers.onSearch();
+    });
+    bar.appendChild(search);
+
+    var theme = dom.el('button', 'btn topbar-theme', '◐');
+    theme.type = 'button';
+    theme.setAttribute('aria-label', 'Toggle light / dark theme');
+    theme.addEventListener('click', function () {
+      handlers.onTheme();
+    });
+    bar.appendChild(theme);
+
+    return {
+      el: bar,
+      setBreadcrumb: function (route) {
+        crumb.textContent = breadcrumbText(route);
+      },
+      setFreshness: function (text, tone) {
+        liveText.textContent = text;
+        dot.className = 'topbar-dot' + (tone ? ' ' + tone : '');
+      },
+    };
+  }
+
+  function breadcrumbText(route) {
+    if (!route) return '';
+    if (route.node) return 'Structure / ' + route.node;
+    if (route.aspect) return 'Rulebook / ' + route.aspect;
+    if (route.flow) return 'Flows / ' + route.flow;
+    return labelForView(route.view);
+  }
+
+  function labelForView(view) {
+    for (var g = 0; g < NAV_GROUPS.length; g += 1) {
+      for (var i = 0; i < NAV_GROUPS[g].items.length; i += 1) {
+        if (NAV_GROUPS[g].items[i].view === view) return NAV_GROUPS[g].items[i].label;
+      }
+    }
+    return view || '';
+  }
+
+  Yg.shell = { build: build, NAV_GROUPS: NAV_GROUPS, _labelForView: labelForView };
+})();

package/dist/templates/portal/js/state-model.js

@@ -0,0 +1,142 @@
+/*
+ * The honest-state taxonomy — the spine of the whole portal.
+ *
+ * Eight distinct render states, each carried by color + GLYPH + label + border-style
+ * (never color alone — accessibility), exactly as the visual-foundations reference
+ * defines them. "verified" is the ONLY green: a reviewer ran, approved, AND the stored
+ * hash still matches the current inputs. The others are deliberately, visibly distinct
+ * and must NEVER be collapsed into one "green". This module is the single source of
+ * truth a renderer reads — no view re-invents a glyph or a color.
+ *
+ * Five of these (verified / refused / unverified / no-rule / warning) are the
+ * PortalNode.state values the contract enumerates; the remaining three
+ * (not-applicable / suppressed / draft) are pair/aspect-level honest states, plus
+ * "boundary" for a live undeclared-dependency violation. All eight render here so the
+ * legend, the panels, and the cells share one honest vocabulary.
+ */
+(function () {
+  'use strict';
+
+  var Yg = (window.YgPortal = window.YgPortal || {});
+
+  // Glyph + border + plain-language label for every honest state. The plain text is the
+  // same wording as the glossary key card, so a tooltip and the legend never diverge.
+  var STATE_META = {
+    verified: {
+      glyph: '✓', // check
+      label: 'verified',
+      border: 'solid',
+      plain: 'A reviewer actually checked this against the current code and it passed. The only green.',
+    },
+    refused: {
+      glyph: '✕', // cross
+      label: 'refused',
+      border: 'solid',
+      plain: 'A reviewer checked it and it broke a rule — with a reason you can read.',
+    },
+    unverified: {
+      glyph: '◌', // dashed circle
+      label: 'unverified',
+      border: 'dashed',
+      plain: "The code changed, so no reviewer has confirmed it yet. Not a pass — just “we don’t know”.",
+    },
+    'no-rule': {
+      glyph: '⊖', // minus-circle
+      label: 'no rule',
+      border: 'dotted',
+      plain: 'Nothing is checking this part. Not broken — just unguarded. Absence of red is not a pass.',
+    },
+    warning: {
+      glyph: '▲', // triangle (advisory)
+      label: 'warning',
+      border: 'dashed',
+      plain: 'An advisory rule flagged this. It does not block — it is signal worth a look, not a failure.',
+    },
+    'not-applicable': {
+      glyph: '–', // en-dash
+      label: 'not applicable',
+      border: 'none',
+      plain: 'A rule was filtered out here on purpose — an empty cell, distinct from unverified.',
+    },
+    suppressed: {
+      glyph: '⛉', // shield-like waiver mark
+      label: 'waived',
+      border: 'dashed',
+      plain: 'Someone told the reviewer to skip a rule here, on purpose, with a reason. Not the same as verified.',
+    },
+    draft: {
+      glyph: '‖', // double bar (paused)
+      label: 'draft',
+      border: 'dotted',
+      plain: 'Parked — removed from the expected set. It verifies nothing while it is a draft.',
+    },
+    boundary: {
+      glyph: '⚡', // zap
+      label: 'live boundary',
+      border: 'hazard',
+      plain: 'An undeclared code dependency, recomputed live right now — never read from the stored lock.',
+    },
+  };
+
+  // The canonical order the legend renders in (mirrors the foundations reference).
+  var STATE_ORDER = [
+    'verified',
+    'refused',
+    'unverified',
+    'no-rule',
+    'warning',
+    'not-applicable',
+    'suppressed',
+    'draft',
+    'boundary',
+  ];
+
+  /** Metadata for a state, falling back to no-rule for an unknown value (never throws). */
+  function meta(state) {
+    return STATE_META[state] || STATE_META['no-rule'];
+  }
+
+  /** The glyph for a state (color is carried by the CSS class, never alone). */
+  function glyph(state) {
+    return meta(state).glyph;
+  }
+
+  /** The plain-language label for a state. */
+  function label(state) {
+    return meta(state).label;
+  }
+
+  /** The plain-language one-line explanation (tooltip text) for a state. */
+  function plain(state) {
+    return meta(state).plain;
+  }
+
+  /** The CSS state class a renderer attaches so color + border come from one place. */
+  function cssClass(state) {
+    return 'state-' + (STATE_META[state] ? state : 'no-rule');
+  }
+
+  /**
+   * Build an accessible state badge: a glyph element carrying the state color/border (from
+   * the CSS class) plus an aria-label of the plain wording, so the state is conveyed by
+   * shape AND text, never color alone. Returns a <span> ready to insert.
+   */
+  function badge(state) {
+    var m = meta(state);
+    var node = Yg.dom.el('span', 'state-glyph ' + cssClass(state), m.glyph);
+    node.setAttribute('role', 'img');
+    node.setAttribute('aria-label', m.label);
+    node.setAttribute('title', m.plain);
+    return node;
+  }
+
+  Yg.states = {
+    ORDER: STATE_ORDER,
+    meta: meta,
+    glyph: glyph,
+    label: label,
+    plain: plain,
+    cssClass: cssClass,
+    badge: badge,
+  };
+})();