@chrisdudek/yg 5.2.6 → 5.4.0

package/dist/templates/portal/js/export.js

@@ -0,0 +1,151 @@
+/*
+ * Audit export — turn the honest ledger into a portable artifact (CSV + JSON).
+ *
+ * The compliance deliverable is a real file, not a screenshot (§0b.5): the suppression
+ * inventory, the no-rule residue (nodes that own source but carry no effective rule), and the
+ * coverage summary are serialized to CSV and JSON and handed to the browser as a download. The
+ * download is built entirely in the page from a Blob / data-URI — NO network, so the offline
+ * static export can still produce the artifact. Pure string builders (buildSuppressionsCsv /
+ * buildResidueCsv / buildCoverageCsv / buildExportJson) are separated from the trigger so they
+ * are directly testable and round-trip back to the same rows; nothing here invents a state or a
+ * green — it serializes exactly what the honest PortalData already carries.
+ *
+ * Browser globals only — reads the already-resolved PortalData; no Node.
+ */
+(function () {
+  'use strict';
+
+  var Yg = (window.YgPortal = window.YgPortal || {});
+
+  /** Quote one CSV field: wrap in double-quotes and double any embedded quote (RFC 4180). */
+  function csvField(value) {
+    var s = value === null || value === undefined ? '' : String(value);
+    return '"' + s.replace(/"/g, '""') + '"';
+  }
+
+  /** Join an array of row-arrays into a CRLF-terminated CSV string (header row first). */
+  function csvRows(rows) {
+    return rows
+      .map(function (cols) {
+        return cols.map(csvField).join(',');
+      })
+      .join('\r\n');
+  }
+
+  /** CSV of the suppression inventory: every active waiver with its resolved risk flag. */
+  function buildSuppressionsCsv(data) {
+    var rows = [['file', 'line', 'aspect', 'risk', 'reason']];
+    var sups = (data.suppressions || []).slice();
+    for (var i = 0; i < sups.length; i += 1) {
+      var s = sups[i];
+      rows.push([s.file, s.line, s.aspectId, s.risk || 'none', s.reason || '']);
+    }
+    return csvRows(rows);
+  }
+
+  /** CSV of the no-rule residue: nodes that own source but carry no effective rule. */
+  function buildResidueCsv(data) {
+    var rows = [['node', 'kind']];
+    var res = (data.residue || { noRuleNodes: [], uncoveredFiles: [] });
+    (res.noRuleNodes || []).forEach(function (p) {
+      rows.push([p, 'no-rule-node']);
+    });
+    (res.uncoveredFiles || []).forEach(function (f) {
+      rows.push([f, 'uncovered-file']);
+    });
+    return csvRows(rows);
+  }
+
+  /** CSV of the coverage summary: each count from the honest ledger, one metric per row. */
+  function buildCoverageCsv(data) {
+    var c = data.meta.counts;
+    var rows = [['metric', 'value']];
+    var keys = [
+      'nodes', 'aspects', 'flows', 'pairsTotal', 'pairsLLM', 'pairsDet',
+      'verified', 'refused', 'advisoryRefused', 'unverified', 'noRule', 'draft', 'notApplicable',
+      'suppressed', 'coveredFiles', 'uncoveredFiles', 'totalFiles', 'errors', 'warnings',
+    ];
+    for (var i = 0; i < keys.length; i += 1) rows.push([keys[i], c[keys[i]]]);
+    return rows.length ? csvRows(rows) : '';
+  }
+
+  /**
+   * The combined JSON export object: provenance (project, generation time, lock hash, commit
+   * ref) + the three audit tables. Round-trips back to the same rows; never collapses a state.
+   */
+  function buildExportJson(data) {
+    var c = data.meta.counts;
+    return {
+      provenance: {
+        project: data.meta.projectName,
+        generatedAt: data.meta.generatedAt,
+        lockHash: data.meta.lockHash,
+        commitRef: data.meta.commitRef,
+        schemaSupported: data.meta.schemaSupported,
+      },
+      coverage: c,
+      suppressions: (data.suppressions || []).slice(),
+      residue: data.residue || { noRuleNodes: [], uncoveredFiles: [] },
+    };
+  }
+
+  /**
+   * Hand `content` to the browser as a download named `filename`, type `mime`. Built from a
+   * Blob + object URL when available, else a data: URI — both are in-page, NO network, so the
+   * offline static export still produces the artifact. Degrades silently when neither the
+   * anchor download nor URL APIs exist (a constrained sandbox); returns true on a real trigger.
+   */
+  function download(filename, content, mime) {
+    try {
+      var doc = window.document;
+      var a = doc.createElement('a');
+      if (typeof a.click !== 'function' && !('download' in a)) return false;
+      var href = null;
+      if (window.URL && typeof window.URL.createObjectURL === 'function' && typeof window.Blob === 'function') {
+        href = window.URL.createObjectURL(new window.Blob([content], { type: mime }));
+      } else {
+        href = 'data:' + mime + ';charset=utf-8,' + encodeURIComponent(content);
+      }
+      a.setAttribute('href', href);
+      a.setAttribute('download', filename);
+      // Append so a real browser fires the navigation; removed straight after.
+      if (doc.body && typeof doc.body.appendChild === 'function') doc.body.appendChild(a);
+      a.click();
+      if (doc.body && typeof doc.body.removeChild === 'function') doc.body.removeChild(a);
+      if (href && href.indexOf('blob:') === 0 && window.URL.revokeObjectURL) {
+        window.URL.revokeObjectURL(href);
+      }
+      return true;
+    } catch (_e) {
+      return false;
+    }
+  }
+
+  Yg.exporter = {
+    buildSuppressionsCsv: buildSuppressionsCsv,
+    buildResidueCsv: buildResidueCsv,
+    buildCoverageCsv: buildCoverageCsv,
+    buildExportJson: buildExportJson,
+    download: download,
+    // Convenience triggers used by the views (suppressions / coverage). Each builds the content
+    // and offers the download; honest filenames carry the project name when present.
+    exportSuppressionsCsv: function (data) {
+      return download(slug(data) + '-suppressions.csv', buildSuppressionsCsv(data), 'text/csv');
+    },
+    exportResidueCsv: function (data) {
+      return download(slug(data) + '-residue.csv', buildResidueCsv(data), 'text/csv');
+    },
+    exportCoverageCsv: function (data) {
+      return download(slug(data) + '-coverage.csv', buildCoverageCsv(data), 'text/csv');
+    },
+    exportJson: function (data) {
+      return download(slug(data) + '-audit.json', JSON.stringify(buildExportJson(data), null, 2), 'application/json');
+    },
+  };
+
+  /** A filesystem-safe slug from the project name (fallback 'portal'). */
+  function slug(data) {
+    var name = (data.meta && data.meta.projectName) || 'portal';
+    return String(name).toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '') || 'portal';
+  }
+})();

package/dist/templates/portal/js/glossary.js

@@ -0,0 +1,72 @@
+/*
+ * Plain-language glossary — the engine words said simply.
+ *
+ * The portal must be legible to a human who does not speak the engine's vocabulary, so
+ * every internal term (aspect, pair, deterministic vs LLM, relation, flow, reviewer /
+ * tier / consensus, no-rule, draft, when-filtered, waived) carries a plain definition
+ * that appears as a tooltip wherever the term is shown. The wording here is the same
+ * text as the glossary-key reference card, so the in-app tooltip and the key never drift.
+ *
+ * Browser globals only — the tooltip is a hover/focus popover built from page DOM; no
+ * network, no Node.
+ */
+(function () {
+  'use strict';
+
+  var Yg = (window.YgPortal = window.YgPortal || {});
+
+  // term id -> plain definition. Keyed by a stable lowercase id, not display text.
+  var TERMS = {
+    aspect: 'A rule the code must satisfy — e.g. “UI must not import the database”.',
+    deterministic:
+      'A rule is checked either by a free local script (mechanical, repeatable) or by an AI reviewer reading it (judgment, may cost).',
+    llm: 'An AI reviewer reads the rule and judges the code against it — judgment, and it may cost.',
+    pair: 'One rule checked against one thing — the unit a verdict is recorded for.',
+    relation:
+      "A declared dependency between two components (calls / uses / …). The code's real dependencies must match what's declared.",
+    flow: 'A business process that spans several components — “place an order”.',
+    reviewer:
+      'Which model judged a rule, and how many times it voted — so you can weigh how much a green is worth.',
+    tier: 'The named reviewer setting an aspect uses — which model judges it, and how strictly.',
+    consensus: 'How many times the reviewer voted on a rule — more votes, more confidence in the verdict.',
+    'no-rule': 'Nothing is checking this part. Not broken — just unguarded. Absence of red is not a pass.',
+    draft: 'A rule parked as not-ready — it is removed from the expected set and verifies nothing.',
+    'when-filtered': 'A rule was deliberately filtered out here — it does not apply to this node.',
+    waived: 'Someone told the reviewer to skip a rule here, on purpose, with a reason. Not the same as verified.',
+    unverified: "The code changed, so no reviewer has confirmed it yet. Not a pass — just “we don’t know”.",
+    suppressed: 'A waiver tells the reviewer to skip a rule on specific lines, with a reason. Waived is not verified.',
+    cost: 'A free local script costs nothing; an AI reviewer may cost a paid API call each time it judges.',
+    // Where a rule comes from — its provenance / attach channel onto this component.
+    own: 'This rule is set directly on this component.',
+    ancestor: 'This rule is inherited from a parent component.',
+    'own-type': 'This rule applies to every component of this type.',
+    'ancestor-type': "Inherited from a parent component's type.",
+    port: 'This rule crosses in from a named contract this component consumes.',
+    implied: 'Pulled in by another rule that includes this one.',
+  };
+
+  /** The plain definition for a term id, or null when the term is unknown. */
+  function lookup(termId) {
+    var key = String(termId || '').toLowerCase();
+    return Object.prototype.hasOwnProperty.call(TERMS, key) ? TERMS[key] : null;
+  }
+
+  /**
+   * Wrap a piece of text as a glossary term: a <span class="term"> carrying the plain
+   * definition both as a native title and as an aria-label, so the meaning is reachable on
+   * hover AND by a screen reader. Falls back to plain text when the term is unknown.
+   */
+  function term(termId, displayText) {
+    var def = lookup(termId);
+    var text = displayText === undefined ? String(termId) : displayText;
+    if (!def) return Yg.dom.el('span', null, text);
+    var node = Yg.dom.el('span', 'term', text);
+    node.setAttribute('tabindex', '0');
+    node.setAttribute('title', def);
+    node.setAttribute('aria-label', text + ': ' + def);
+    node.setAttribute('data-term', String(termId).toLowerCase());
+    return node;
+  }
+
+  Yg.glossary = { lookup: lookup, term: term, _terms: TERMS };
+})();

package/dist/templates/portal/js/namespace.js

@@ -0,0 +1,60 @@
+/*
+ * Portal namespace + small DOM/util helpers.
+ *
+ * Every portal browser module attaches to ONE global, `window.YgPortal`, so the
+ * inlined static page (a sequence of plain <script> blocks, no module system) can
+ * share code without `import`/`require` — neither exists in a single-file offline
+ * page. This is the only place the global is created; later modules extend it.
+ *
+ * Browser globals only: no Node, no network, no secrets. The portal frontend runs
+ * inside a browser tab from a self-contained file or a same-origin loopback page.
+ */
+(function () {
+  'use strict';
+
+  /** The shared namespace — created once, extended by every later module. */
+  var Yg = (window.YgPortal = window.YgPortal || {});
+
+  /** Create an element with an optional class and text/child content. */
+  function el(tag, cls, content) {
+    var node = document.createElement(tag);
+    if (cls) node.className = cls;
+    if (content === undefined || content === null) return node;
+    if (typeof content === 'string' || typeof content === 'number') {
+      node.textContent = String(content);
+    } else if (content.nodeType) {
+      node.appendChild(content);
+    } else if (Array.isArray(content)) {
+      for (var i = 0; i < content.length; i += 1) {
+        var c = content[i];
+        if (c == null) continue;
+        node.appendChild(typeof c === 'string' ? document.createTextNode(c) : c);
+      }
+    }
+    return node;
+  }
+
+  /** Set several attributes at once (skips null/undefined values). */
+  function attrs(node, map) {
+    for (var k in map) {
+      if (!Object.prototype.hasOwnProperty.call(map, k)) continue;
+      var v = map[k];
+      if (v === null || v === undefined) continue;
+      node.setAttribute(k, String(v));
+    }
+    return node;
+  }
+
+  /** Remove every child of an element (cheap, allocation-free clear). */
+  function clear(node) {
+    while (node.firstChild) node.removeChild(node.firstChild);
+    return node;
+  }
+
+  /** First element matching a selector within `root` (defaults to document). */
+  function find(selector, root) {
+    return (root || document).querySelector(selector);
+  }
+
+  Yg.dom = { el: el, attrs: attrs, clear: clear, find: find };
+})();

package/dist/templates/portal/js/palette-overlay.js

@@ -0,0 +1,176 @@
+/*
+ * Command palette overlay — the ⌘K modal DOM, driven by the pure matcher.
+ *
+ * Builds the search index from PortalData once, then renders a keyboard-first modal:
+ * an input, a results list (arrow keys move the active row, Enter routes to it), and a
+ * footer of shortcuts. Open with ⌘K / Ctrl-K or the top-bar trigger; close with Esc.
+ * Selecting a result hands its route to the router — one navigation code path. The
+ * ranking logic lives in palette.js (pure, tested); this file is only the overlay.
+ *
+ * Browser globals only — no network, no Node.
+ */
+(function () {
+  'use strict';
+
+  var Yg = (window.YgPortal = window.YgPortal || {});
+  var dom = Yg.dom;
+
+  /** Create a palette controller bound to a router and a PortalData index. */
+  function create(data, router) {
+    var index = Yg.paletteSearch.buildIndex(data);
+    var overlay = null;
+    var input = null;
+    var listEl = null;
+    var rows = [];
+    var active = 0;
+
+    function isOpen() {
+      return overlay !== null;
+    }
+
+    function renderResults() {
+      var query = input ? input.value : '';
+      var results = Yg.paletteSearch.search(index, query, 50);
+      dom.clear(listEl);
+      rows = [];
+      active = 0;
+      if (results.length === 0) {
+        listEl.appendChild(dom.el('div', 'palette-empty', 'No matches.'));
+        return;
+      }
+      for (var i = 0; i < results.length; i += 1) {
+        rows.push(appendRow(results[i], i === 0));
+      }
+    }
+
+    function appendRow(item, isActive) {
+      var row = dom.el('div', 'palette-row' + (isActive ? ' on' : ''));
+      row.setAttribute('role', 'option');
+      row.setAttribute('aria-selected', isActive ? 'true' : 'false');
+      var ic = dom.el('span', 'palette-ic', kindGlyph(item));
+      var nm = dom.el('span', 'palette-nm', item.label);
+      var sub = dom.el('span', 'palette-sub', item.sub || '');
+      var kind = dom.el('span', 'palette-kind', item.kind);
+      row.appendChild(ic);
+      row.appendChild(nm);
+      row.appendChild(sub);
+      row.appendChild(kind);
+      row.addEventListener('mouseenter', function () {
+        setActiveRow(rows.indexOf(row));
+      });
+      row.addEventListener('click', function () {
+        choose(item);
+      });
+      row._item = item;
+      listEl.appendChild(row);
+      return row;
+    }
+
+    function kindGlyph(item) {
+      if (item.kind === 'node') return Yg.states.glyph(item.state || 'no-rule');
+      if (item.kind === 'aspect') return '▤';
+      if (item.kind === 'flow') return '⤳';
+      return '◧';
+    }
+
+    function setActiveRow(i) {
+      if (i < 0 || i >= rows.length) return;
+      if (rows[active]) {
+        rows[active].className = 'palette-row';
+        rows[active].setAttribute('aria-selected', 'false');
+      }
+      active = i;
+      rows[active].className = 'palette-row on';
+      rows[active].setAttribute('aria-selected', 'true');
+      rows[active].scrollIntoView({ block: 'nearest' });
+    }
+
+    function choose(item) {
+      close();
+      router.go(item.route);
+    }
+
+    function onKey(e) {
+      if (e.key === 'Escape') {
+        close();
+        e.preventDefault();
+        return;
+      }
+      if (e.key === 'ArrowDown') {
+        setActiveRow(Math.min(active + 1, rows.length - 1));
+        e.preventDefault();
+        return;
+      }
+      if (e.key === 'ArrowUp') {
+        setActiveRow(Math.max(active - 1, 0));
+        e.preventDefault();
+        return;
+      }
+      if (e.key === 'Enter') {
+        if (rows[active] && rows[active]._item) choose(rows[active]._item);
+        e.preventDefault();
+      }
+    }
+
+    function open() {
+      if (isOpen()) return;
+      overlay = dom.el('div', 'palette-backdrop');
+      overlay.setAttribute('role', 'dialog');
+      overlay.setAttribute('aria-label', 'Command palette');
+      var box = dom.el('div', 'palette-box');
+      var inputWrap = dom.el('div', 'palette-input');
+      inputWrap.appendChild(dom.el('span', 'palette-search-ic', '⌕'));
+      input = document.createElement('input');
+      input.type = 'text';
+      input.className = 'palette-field';
+      input.setAttribute('aria-label', 'Search nodes, aspects, flows, and views');
+      input.placeholder = 'Search nodes, aspects, flows…';
+      inputWrap.appendChild(input);
+      listEl = dom.el('div', 'palette-results');
+      listEl.setAttribute('role', 'listbox');
+      var foot = dom.el('div', 'palette-foot');
+      foot.appendChild(dom.el('span', null, '↑↓ navigate'));
+      foot.appendChild(dom.el('span', null, '↵ open'));
+      foot.appendChild(dom.el('span', null, 'esc close'));
+      box.appendChild(inputWrap);
+      box.appendChild(listEl);
+      box.appendChild(foot);
+      overlay.appendChild(box);
+
+      overlay.addEventListener('click', function (e) {
+        if (e.target === overlay) close();
+      });
+      input.addEventListener('input', renderResults);
+      input.addEventListener('keydown', onKey);
+
+      document.body.appendChild(overlay);
+      renderResults();
+      input.focus();
+    }
+
+    function close() {
+      if (overlay && overlay.parentNode) overlay.parentNode.removeChild(overlay);
+      overlay = null;
+      input = null;
+      listEl = null;
+      rows = [];
+    }
+
+    function toggle() {
+      if (isOpen()) close();
+      else open();
+    }
+
+    // Global ⌘K / Ctrl-K binding.
+    document.addEventListener('keydown', function (e) {
+      if ((e.metaKey || e.ctrlKey) && (e.key === 'k' || e.key === 'K')) {
+        toggle();
+        e.preventDefault();
+      }
+    });
+
+    return { open: open, close: close, toggle: toggle, isOpen: isOpen };
+  }
+
+  Yg.palette = { create: create };
+})();

package/dist/templates/portal/js/palette.js

@@ -0,0 +1,133 @@
+/*
+ * Command palette (⌘K) — fuzzy jump to any node / aspect / flow or view action.
+ *
+ * One keyboard-first overlay over the whole graph: type a few characters and the palette
+ * fuzzy-matches every node, aspect, flow, and view action, ranked; Enter routes to the
+ * selection (a node opens its panel, an aspect/flow its detail, an action runs). It is
+ * never empty — with no query it shows view actions and a few entities so the door is
+ * always open.
+ *
+ * The index builder and the fuzzy matcher are PURE functions over plain data (no DOM), so
+ * the ranking is unit-testable directly; the overlay below is the thin DOM layer. Browser
+ * globals only — no network, no Node.
+ */
+(function () {
+  'use strict';
+
+  var Yg = (window.YgPortal = window.YgPortal || {});
+
+  /**
+   * Build the flat searchable index from a PortalData object. Each entry is
+   * { id, label, sub, kind, route } — `route` is a router route the selection navigates to.
+   * View actions come first so an empty query always has somewhere to go.
+   */
+  function buildIndex(data) {
+    var items = [];
+
+    // View actions — always present, even on an empty/blank graph.
+    var VIEW_ACTIONS = [
+      { id: 'view:overview', label: 'Overview', sub: 'the landing', kind: 'view', route: { view: 'overview' } },
+      { id: 'view:coverage', label: 'Coverage & audit', sub: 'the full ledger', kind: 'view', route: { view: 'coverage' } },
+      { id: 'view:tree', label: 'Structure (tree)', sub: 'the hierarchy', kind: 'view', route: { view: 'tree' } },
+      { id: 'view:relations', label: 'Relations & boundaries', sub: 'matrix · hubs · boundary', kind: 'view', route: { view: 'relations' } },
+      { id: 'view:rulebook', label: 'Rulebook', sub: "what's enforced", kind: 'view', route: { view: 'rulebook' } },
+      { id: 'view:types', label: 'Type model', sub: "what's possible", kind: 'view', route: { view: 'types' } },
+      { id: 'view:flows', label: 'Flows', sub: 'what the system does', kind: 'view', route: { view: 'flows' } },
+      { id: 'view:suppressions', label: 'Suppressions', sub: 'waiver inventory', kind: 'view', route: { view: 'suppressions' } },
+      { id: 'view:start', label: 'Start here', sub: 'the on-ramp', kind: 'view', route: { view: 'start' } },
+    ];
+    for (var a = 0; a < VIEW_ACTIONS.length; a += 1) items.push(VIEW_ACTIONS[a]);
+
+    var nodes = (data && data.nodes) || [];
+    for (var n = 0; n < nodes.length; n += 1) {
+      var node = nodes[n];
+      items.push({
+        id: 'node:' + node.path,
+        label: node.name || node.path,
+        sub: node.path + ' · ' + (node.type || ''),
+        kind: 'node',
+        state: node.state,
+        route: { view: 'tree', node: node.path },
+      });
+    }
+
+    var aspects = (data && data.aspects) || [];
+    for (var s = 0; s < aspects.length; s += 1) {
+      var asp = aspects[s];
+      items.push({
+        id: 'aspect:' + asp.id,
+        label: asp.id,
+        sub: 'aspect · ' + (asp.kind || '') + ' · ' + (asp.status || ''),
+        kind: 'aspect',
+        route: { view: 'rulebook', aspect: asp.id },
+      });
+    }
+
+    var flows = (data && data.flows) || [];
+    for (var f = 0; f < flows.length; f += 1) {
+      var flow = flows[f];
+      items.push({
+        id: 'flow:' + flow.name,
+        label: flow.name,
+        sub: 'flow · ' + ((flow.participants && flow.participants.length) || 0) + ' participants',
+        kind: 'flow',
+        route: { view: 'flows', flow: flow.name },
+      });
+    }
+
+    return items;
+  }
+
+  /**
+   * Subsequence fuzzy score of `query` against `text`. Returns a number (higher = better)
+   * or -1 when the query is not a subsequence. Rewards contiguous runs and a match at a word
+   * boundary, so "fill" ranks "cli/core/fill" above an incidental scatter of those letters.
+   */
+  function fuzzyScore(query, text) {
+    var q = query.toLowerCase();
+    var t = text.toLowerCase();
+    if (q.length === 0) return 0;
+    var score = 0;
+    var ti = 0;
+    var prevMatch = -2;
+    for (var qi = 0; qi < q.length; qi += 1) {
+      var ch = q.charAt(qi);
+      var found = t.indexOf(ch, ti);
+      if (found === -1) return -1;
+      score += 1;
+      if (found === prevMatch + 1) score += 3; // contiguous run
+      if (found === 0 || /[\/\-_. ]/.test(t.charAt(found - 1))) score += 2; // word boundary
+      prevMatch = found;
+      ti = found + 1;
+    }
+    // Prefer shorter targets (a tighter match) and an exact-substring hit.
+    if (t.indexOf(q) !== -1) score += 4;
+    score -= t.length * 0.01;
+    return score;
+  }
+
+  /**
+   * Rank index `items` against `query`. An empty query returns the first `limit` items in
+   * index order (view actions first — never an empty palette). A non-empty query keeps only
+   * subsequence matches, ranked by score, capped at `limit`.
+   */
+  function search(items, query, limit) {
+    var cap = limit || 50;
+    var q = String(query || '').trim();
+    if (q.length === 0) return items.slice(0, cap);
+    var scored = [];
+    for (var i = 0; i < items.length; i += 1) {
+      var item = items[i];
+      var best = Math.max(fuzzyScore(q, item.label), fuzzyScore(q, item.sub || '') - 1);
+      if (best >= 0) scored.push({ item: item, score: best });
+    }
+    scored.sort(function (a, b) {
+      return b.score - a.score;
+    });
+    return scored.slice(0, cap).map(function (s) {
+      return s.item;
+    });
+  }
+
+  Yg.paletteSearch = { buildIndex: buildIndex, fuzzyScore: fuzzyScore, search: search };
+})();