@chrisdudek/yg 5.2.6 → 5.4.0

package/dist/templates/portal/js/views/start-view.js

@@ -0,0 +1,287 @@
+/*
+ * V9 Start here — the new-joiner on-ramp.
+ *
+ * A short scripted walk assembled live from the committed graph (§3a V9), so it is rot-proof:
+ * every word is derived from the resolved PortalData, never hardcoded. Five plain-language
+ * steps: (1) what this system is, (2) the big areas of the codebase, (3) one business process
+ * end to end, (4) one component explained, (5) reading the colours (the honest key). The front
+ * door of the pro-adoption rebalance.
+ *
+ * The step is in-view state with no hash grammar of its own, so the wizard re-renders its own
+ * stage in place on Next/Back — it never round-trips through the router for the step (the steps
+ * that OPEN a real surface — the structure tree, a flow, a node's panel — route normally). Every
+ * state treatment (the area dots, the colour key) is read from the one shared honest-state model.
+ *
+ * Browser globals only — reads the already-resolved PortalData; no network, no Node.
+ */
+(function () {
+  'use strict';
+
+  var Yg = (window.YgPortal = window.YgPortal || {});
+  var dom = Yg.dom;
+  Yg.views = Yg.views || {};
+
+  var STEP_TITLES = [
+    'What this system is',
+    'The big areas of this system',
+    'One process, end to end',
+    'One component, explained',
+    'Reading the colours',
+  ];
+
+  /** Top-level component nodes (the "big areas") — derived from the graph, never hardcoded. */
+  function bigAreas(data) {
+    var nodes = data.nodes || [];
+    var top = nodes.filter(function (n) {
+      return !n.parent;
+    });
+    // If there is a single synthetic root, descend one level to the real areas.
+    if (top.length === 1) {
+      var rootPath = top[0].path;
+      top = nodes.filter(function (n) {
+        return n.parent === rootPath;
+      });
+    }
+    return top.slice(0, 9);
+  }
+
+  /**
+   * The honest area state — an area is a container, so its badge is the bottom-up
+   * rollupState (the worst REAL state anywhere in its subtree). rollupState is already
+   * honest for an empty container: with nothing verdict-bearing under it, the rollup is
+   * no-rule (unguarded, never green); a refused/unverified descendant bubbles up. We must
+   * NOT gate on the node's own `checked` here — that would suppress a real subtree state
+   * on a source-less container area (the exact green-over-empty defect).
+   */
+  function areaState(node) {
+    return node.rollupState;
+  }
+
+  /** A representative node to explain in step 4: the first checked node with relations, else any. */
+  function representativeNode(data) {
+    var nodes = data.nodes || [];
+    var withRules = nodes.filter(function (n) {
+      return n.checked && (n.effectiveAspects || []).length > 0;
+    });
+    return withRules[0] || nodes.filter(function (n) { return n.sourceFileCount > 0; })[0] || nodes[0] || null;
+  }
+
+  function stepRail(step) {
+    var rail = dom.el('div', 'st-steps');
+    for (var i = 0; i < 5; i += 1) {
+      var seg = dom.el('div', 'st-step' + (i < step ? ' st-step-done' : i === step ? ' st-step-now' : ''));
+      rail.appendChild(seg);
+    }
+    return rail;
+  }
+
+  function roadmapChips(step) {
+    var box = dom.el('div', 'st-roadmap');
+    for (var i = 0; i < 5; i += 1) {
+      var chip = dom.el('span', 'st-chip' + (i === step ? ' st-chip-now' : ''), (i + 1) + ' · ' + STEP_TITLES[i]);
+      box.appendChild(chip);
+    }
+    return box;
+  }
+
+  // ── Per-step bodies (each derived from live PortalData) ──────────────────────
+
+  function stepWhatIs(data) {
+    var c = data.meta.counts;
+    var body = dom.el('div');
+    body.appendChild(
+      dom.el(
+        'p',
+        'st-lead',
+        'This project is guarded by continuous architecture checks. A set of rules describes how the code should be built; a reviewer checks the real code against them and records a verdict. Green means a reviewer actually checked something and it passed — nothing else is green.',
+      ),
+    );
+    var stats = dom.el('div', 'st-areas');
+    stats.appendChild(factCard(String(c.nodes), 'components mapped'));
+    stats.appendChild(factCard(String(c.aspects), 'rules in the book'));
+    stats.appendChild(factCard(String(c.flows), 'business processes'));
+    body.appendChild(stats);
+    body.appendChild(
+      dom.el('p', 'st-lead st-lead-sm', 'Right now ' + c.verified + ' of ' + c.pairsTotal + ' expected checks are verified. The rest are not failures by default — some are simply unchecked or unguarded. You will learn to read that difference by the end of this walk.'),
+    );
+    return body;
+  }
+
+  function factCard(big, label) {
+    var card = dom.el('div', 'st-area');
+    card.appendChild(dom.el('b', 'st-fact', big));
+    card.appendChild(dom.el('span', null, label));
+    return card;
+  }
+
+  function stepBigAreas(data, nav) {
+    var body = dom.el('div');
+    body.appendChild(dom.el('p', 'st-lead', 'This codebase is organized into a handful of areas. Each groups the files that do a related job — and each carries its own rules. Here is the map you will be working in.'));
+    var areas = bigAreas(data);
+    var grid = dom.el('div', 'st-areas');
+    for (var i = 0; i < areas.length; i += 1) {
+      grid.appendChild(areaCard(areas[i], nav));
+    }
+    body.appendChild(grid);
+    body.appendChild(
+      dom.el('p', 'st-lead st-lead-sm', 'The badge on each area is its state. Green means a reviewer checked it and it passed; the grey "no rule" badge means nothing checks it yet — not broken, just unguarded. You will learn the rest of the colours in the last step.'),
+    );
+    return body;
+  }
+
+  function areaCard(node, nav) {
+    var state = areaState(node);
+    var card = dom.el('button', 'st-area st-area-link');
+    card.type = 'button';
+    var top = dom.el('div', 'st-area-top');
+    top.appendChild(Yg.states.badge(state));
+    top.appendChild(dom.el('b', 'mono', node.name || node.path));
+    card.appendChild(top);
+    card.appendChild(dom.el('span', null, node.description ? shorten(node.description) : node.type));
+    card.addEventListener('click', function () {
+      nav({ view: 'tree', node: node.path });
+    });
+    return card;
+  }
+
+  function stepOneFlow(data, nav) {
+    var body = dom.el('div');
+    var flows = data.flows || [];
+    var flow = flows[0];
+    if (!flow) {
+      body.appendChild(dom.el('p', 'st-lead', 'No business processes are defined yet. When they are, this step walks one end to end.'));
+      return body;
+    }
+    body.appendChild(dom.el('p', 'st-lead', 'A "flow" is a real-world process that crosses several components. Here is one, named in plain business language, with the components it touches.'));
+    var card = dom.el('div', 'st-flowcard');
+    card.appendChild(dom.el('b', null, flow.name));
+    if (flow.description) card.appendChild(dom.el('p', 'st-flow-d', flow.description));
+    card.appendChild(dom.el('div', 'st-flow-meta', flow.participants.length + ' components take part. A flow is never just green: if nothing checks its components it reads "nothing-checked", and any unverified component makes the whole process need attention.'));
+    var open = dom.el('button', 'st-inline-link');
+    open.type = 'button';
+    open.textContent = 'See this process in full →';
+    open.addEventListener('click', function () {
+      nav({ view: 'flows', flow: flow.name });
+    });
+    card.appendChild(open);
+    body.appendChild(card);
+    return body;
+  }
+
+  function stepOneNode(data, nav) {
+    var body = dom.el('div');
+    var node = representativeNode(data);
+    if (!node) {
+      body.appendChild(dom.el('p', 'st-lead', 'No components are mapped yet. When they are, this step explains one in full.'));
+      return body;
+    }
+    body.appendChild(dom.el('p', 'st-lead', 'Each component has an identity, the rules in force on it, and what it depends on. Open one and you can read exactly what a reviewer checked — and what is still unguarded.'));
+    var card = dom.el('div', 'st-flowcard');
+    var top = dom.el('div', 'st-area-top');
+    // node.state is already the honest own state — a node with no real verdict-bearing
+    // pair is no-rule, never green (the backend `checked` gate handles that), so we render
+    // it directly rather than re-gating on `checked`.
+    top.appendChild(Yg.states.badge(node.state));
+    top.appendChild(dom.el('b', 'mono', node.name || node.path));
+    card.appendChild(top);
+    if (node.description) card.appendChild(dom.el('p', 'st-flow-d', shorten(node.description)));
+    var ruleCount = (node.effectiveAspects || []).length;
+    card.appendChild(dom.el('div', 'st-flow-meta', ruleCount > 0 ? ruleCount + ' rule(s) are in force here. Each carries its own honest verdict — verified, refused, or simply not-yet-checked.' : 'No rule is in force here yet — it is unguarded, not approved.'));
+    var open = dom.el('button', 'st-inline-link');
+    open.type = 'button';
+    open.textContent = 'Open this component →';
+    open.addEventListener('click', function () {
+      nav({ view: 'tree', node: node.path });
+    });
+    card.appendChild(open);
+    body.appendChild(card);
+    return body;
+  }
+
+  function stepColours() {
+    var body = dom.el('div');
+    body.appendChild(dom.el('p', 'st-lead', 'This is the whole key. Every colour means exactly one thing, and only one of them is green. Absence of red is not a pass — an unchecked or unguarded surface is its own distinct colour, never green.'));
+    var grid = dom.el('div', 'st-key');
+    for (var i = 0; i < Yg.states.ORDER.length; i += 1) {
+      var state = Yg.states.ORDER[i];
+      var item = dom.el('div', 'st-key-item ' + Yg.states.cssClass(state));
+      item.appendChild(Yg.states.badge(state));
+      var t = dom.el('div', 'st-key-text');
+      t.appendChild(dom.el('b', null, Yg.states.label(state)));
+      t.appendChild(dom.el('span', null, Yg.states.plain(state)));
+      item.appendChild(t);
+      grid.appendChild(item);
+    }
+    body.appendChild(grid);
+    return body;
+  }
+
+  function shorten(text) {
+    var t = String(text).replace(/\s+/g, ' ').trim();
+    return t.length > 90 ? t.slice(0, 87) + '…' : t;
+  }
+
+  function renderStep(stage, data, nav, step, setStep) {
+    dom.clear(stage);
+
+    stage.appendChild(stepRail(step));
+    stage.appendChild(dom.el('div', 'st-stepno mono', 'Step ' + (step + 1) + ' of 5'));
+
+    var card = dom.el('div', 'st-card');
+    card.appendChild(dom.el('h1', 'st-h1', STEP_TITLES[step]));
+
+    var bodies = [stepWhatIs(data), stepBigAreas(data, nav), stepOneFlow(data, nav), stepOneNode(data, nav), stepColours()];
+    card.appendChild(bodies[step]);
+
+    card.appendChild(roadmapChips(step));
+
+    var navRow = dom.el('div', 'st-nav');
+    var back = dom.el('button', 'st-btn');
+    back.type = 'button';
+    back.textContent = '← Back';
+    back.disabled = step === 0;
+    back.addEventListener('click', function () {
+      if (step > 0) setStep(step - 1);
+    });
+    navRow.appendChild(back);
+
+    var next = dom.el('button', 'st-btn st-btn-primary');
+    next.type = 'button';
+    if (step < 4) {
+      next.textContent = 'Next: ' + STEP_TITLES[step + 1].toLowerCase() + ' →';
+      next.addEventListener('click', function () {
+        setStep(step + 1);
+      });
+    } else {
+      next.textContent = 'Done — go to the overview';
+      next.addEventListener('click', function () {
+        nav({ view: 'overview' });
+      });
+    }
+    navRow.appendChild(next);
+
+    var skip = dom.el('button', 'st-skip');
+    skip.type = 'button';
+    skip.textContent = 'Skip the tour';
+    skip.addEventListener('click', function () {
+      nav({ view: 'overview' });
+    });
+    navRow.appendChild(skip);
+
+    card.appendChild(navRow);
+    stage.appendChild(card);
+  }
+
+  Yg.views.start = function (stage, route, data, ctx) {
+    var nav = ctx && ctx.navigate ? ctx.navigate : function () {};
+    var frame = dom.el('div', 'st-frame');
+    stage.appendChild(frame);
+
+    var step = 0;
+    function setStep(s) {
+      step = s;
+      renderStep(frame, data, nav, step, setStep);
+    }
+    renderStep(frame, data, nav, step, setStep);
+  };
+})();

package/dist/templates/portal/js/views/suppressions-view.js

@@ -0,0 +1,187 @@
+/*
+ * V8 Suppressions — the risk-first waiver inventory.
+ *
+ * Suppressed is NOT verified (§3.6, §3a V8): the permanent, surfaced ledger of every deliberate
+ * hole and which are dangerous. Every active waiver marker on mapped source as a table —
+ * file:line, the waived aspect, the reason text, and a RISK flag resolved by the CLI's own
+ * suppress-range resolver (not ad-hoc regex): wildcard (`*`, all aspects off), unbounded (runs
+ * to end of file / a long range), inert (the aspect is draft, so the waiver is a no-op), or typo
+ * (the aspect-id matches no known aspect). Sorted risk-first; a standing banner if any marker is
+ * wildcard or unbounded. A waiver NEVER hides the real verdict.
+ *
+ * The waived state is read from the one shared honest-state model (the `suppressed` treatment),
+ * so a waiver can never read as a green pass.
+ *
+ * Transitions (§3a V8): a marker's location → its node's attestation panel (SHELL-panel); the
+ * waived aspect → V5 (the rulebook). Browser globals only; reads the resolved PortalData; no Node.
+ */
+(function () {
+  'use strict';
+
+  var Yg = (window.YgPortal = window.YgPortal || {});
+  var dom = Yg.dom;
+  Yg.views = Yg.views || {};
+
+  // Risk → severity rank (lower = more dangerous, sorted first) + a plain label.
+  var RISK_RANK = { wildcard: 0, unbounded: 1, inert: 2, typo: 3 };
+  var RISK_LABEL = {
+    wildcard: 'WILDCARD — all aspects off',
+    unbounded: 'RANGE — runs unbounded',
+    inert: 'INERT — aspect is draft, waiver is a no-op',
+    typo: 'TYPO — aspect-id matches no known rule',
+  };
+
+  function riskRank(s) {
+    return s.risk && Object.prototype.hasOwnProperty.call(RISK_RANK, s.risk) ? RISK_RANK[s.risk] : 9;
+  }
+
+  /** A keyboard-operable export trigger (a native <button>, focusable + Enter/Space-activatable). */
+  function exportBtn(label, aria, onClick) {
+    var b = dom.el('button', 'exp-btn', label);
+    b.type = 'button';
+    b.setAttribute('aria-label', aria);
+    b.addEventListener('click', onClick);
+    return b;
+  }
+
+  /** Map the node owning a source file path, for the location → SHELL-panel transition. */
+  function nodeForFile(data, file) {
+    var nodes = data.nodes || [];
+    var best = null;
+    for (var i = 0; i < nodes.length; i += 1) {
+      var globs = nodes[i].mapping || [];
+      for (var g = 0; g < globs.length; g += 1) {
+        // A cheap, dependency-free containment: the node's mapping prefix (before any glob char)
+        // is a path prefix of the file. The exact owner is authoritative in the panel itself.
+        var prefix = String(globs[g]).split(/[*?[]/)[0];
+        if (prefix && file.indexOf(prefix) === 0) {
+          if (!best || prefix.length > best.prefix) best = { path: nodes[i].path, prefix: prefix.length };
+        }
+      }
+    }
+    return best ? best.path : null;
+  }
+
+  function riskCell(sup) {
+    if (!sup.risk) {
+      var ok = dom.el('span', 'sup-flag sup-flag-ok', 'bounded · single rule');
+      return ok;
+    }
+    var cls = sup.risk === 'wildcard' ? 'sup-flag-wild' : sup.risk === 'unbounded' ? 'sup-flag-unb' : 'sup-flag-other';
+    return dom.el('span', 'sup-flag ' + cls, RISK_LABEL[sup.risk] || sup.risk);
+  }
+
+  function markerRow(sup, data, nav) {
+    var tr = dom.el('tr', 'sup-row');
+
+    // Location — the waived state badge + file:line, routing to the owning node's panel.
+    var locCell = dom.el('td', 'sup-loc');
+    var locBtn = dom.el('button', 'sup-locbtn');
+    locBtn.type = 'button';
+    locBtn.appendChild(Yg.states.badge('suppressed'));
+    locBtn.appendChild(dom.el('span', 'mono sup-locpath', sup.file + ':' + sup.line));
+    var owner = nodeForFile(data, sup.file);
+    locBtn.addEventListener('click', function () {
+      if (owner) nav({ view: 'tree', node: owner });
+    });
+    if (!owner) locBtn.disabled = true;
+    locCell.appendChild(locBtn);
+    tr.appendChild(locCell);
+
+    // The waived aspect — routes to its detail in the rulebook.
+    var aspCell = dom.el('td');
+    var aspBtn = dom.el('button', 'sup-asp mono');
+    aspBtn.type = 'button';
+    aspBtn.textContent = sup.aspectId;
+    aspBtn.addEventListener('click', function () {
+      nav({ view: 'rulebook', aspect: sup.aspectId });
+    });
+    aspCell.appendChild(aspBtn);
+    tr.appendChild(aspCell);
+
+    tr.appendChild(dom.el('td', null, riskCell(sup)));
+
+    var reasonCell = dom.el('td', 'sup-reason');
+    reasonCell.textContent = '"' + (sup.reason || '') + '" — a waiver, not a pass.';
+    tr.appendChild(reasonCell);
+
+    return tr;
+  }
+
+  function banner(suppressions) {
+    var dangerous = suppressions.filter(function (s) {
+      return s.risk === 'wildcard' || s.risk === 'unbounded';
+    });
+    if (!dangerous.length) return null;
+    var wild = dangerous.filter(function (s) {
+      return s.risk === 'wildcard';
+    }).length;
+    var unb = dangerous.length - wild;
+    var msg = '';
+    if (wild) msg += wild + ' wildcard marker' + (wild === 1 ? '' : 's') + ' (waives every rule on that line) ';
+    if (unb) msg += (msg ? '· ' : '') + unb + ' unbounded range' + (unb === 1 ? '' : 's') + ' ';
+    var box = dom.el('div', 'sup-banner');
+    box.appendChild(Yg.states.badge('suppressed'));
+    box.appendChild(dom.el('span', null, msg + '— review whether each is intended.'));
+    return box;
+  }
+
+  function summary(suppressions) {
+    var files = {};
+    for (var i = 0; i < suppressions.length; i += 1) files[suppressions[i].file] = true;
+    var fileCount = Object.keys(files).length;
+    return suppressions.length + ' active waiver' + (suppressions.length === 1 ? '' : 's') + ' across ' + fileCount + ' file' + (fileCount === 1 ? '' : 's') + ' — a suppressed line is NOT verified; the reviewer was told to skip it. Sorted risk-first.';
+  }
+
+  Yg.views.suppressions = function (stage, route, data, ctx) {
+    var nav = ctx && ctx.navigate ? ctx.navigate : function () {};
+    var suppressions = (data.suppressions || []).slice().sort(function (a, b) {
+      var r = riskRank(a) - riskRank(b);
+      if (r !== 0) return r;
+      return (a.file + ':' + a.line).localeCompare(b.file + ':' + b.line, 'en');
+    });
+
+    stage.appendChild(dom.el('p', 'view-lead', 'Every deliberate waiver, risk-first. A waived line is not verified — someone told the reviewer to skip a rule there, on purpose, with a reason. A waiver never hides the real verdict; it is a documented hole, not a pass.'));
+
+    // Export the inventory as a portable audit artifact (CSV / JSON) — built in-page, no network.
+    if (Yg.exporter) {
+      var bar = dom.el('div', 'exp-bar');
+      bar.appendChild(exportBtn('Export CSV', 'Download the suppression inventory as CSV', function () {
+        Yg.exporter.exportSuppressionsCsv(data);
+      }));
+      bar.appendChild(exportBtn('Export JSON', 'Download the full audit bundle (suppressions, residue, coverage) as JSON', function () {
+        Yg.exporter.exportJson(data);
+      }));
+      stage.appendChild(bar);
+    }
+
+    if (!suppressions.length) {
+      var empty = dom.el('div', 'sup-empty');
+      empty.appendChild(Yg.states.badge('suppressed'));
+      empty.appendChild(dom.el('b', null, 'No active waivers.'));
+      empty.appendChild(dom.el('p', null, 'Nothing is being skipped on current inputs. That is the honest empty state — not a green, just an empty ledger.'));
+      stage.appendChild(empty);
+      return;
+    }
+
+    stage.appendChild(dom.el('div', 'rb-sub', summary(suppressions)));
+    var b = banner(suppressions);
+    if (b) stage.appendChild(b);
+
+    var table = dom.el('table', 'sup-table');
+    var thead = dom.el('thead');
+    var htr = dom.el('tr');
+    ['location', 'waived rule', 'risk', 'reason'].forEach(function (h) {
+      htr.appendChild(dom.el('td', null, h));
+    });
+    thead.appendChild(htr);
+    table.appendChild(thead);
+
+    var tbody = dom.el('tbody');
+    for (var i = 0; i < suppressions.length; i += 1) {
+      tbody.appendChild(markerRow(suppressions[i], data, nav));
+    }
+    table.appendChild(tbody);
+    stage.appendChild(table);
+  };
+})();

package/dist/templates/portal/js/views/tree-view.js

@@ -0,0 +1,68 @@
+/*
+ * V3 Structure — the node tree view.
+ *
+ * The where-does-X-live spine (§3a V3). It reuses the shared DOM-virtualized node tree
+ * (Yg.tree) so the hierarchy stays responsive at 300–1000+ nodes, colors each row by its
+ * own honest state (read from the one shared honest-state model — never an invented green),
+ * and routes a row click to that node's attestation panel via the §3a "tree row → SHELL-panel"
+ * transition. A short honest preface states what the coloring means so the absence of red is
+ * never mistaken for a pass.
+ *
+ * Browser globals only — reads the already-resolved PortalData; no network, no Node.
+ */
+(function () {
+  'use strict';
+
+  var Yg = (window.YgPortal = window.YgPortal || {});
+  var dom = Yg.dom;
+  Yg.views = Yg.views || {};
+
+  /**
+   * Render the structure tree into `stage`. `ctx.onSelect(path)` routes a row to the node's
+   * attestation panel (§3a: tree row → SHELL-panel). The shared count header + honest legend
+   * are rendered by the dispatcher around this body.
+   */
+  Yg.views.tree = function (stage, route, data, ctx) {
+    var intro = dom.el('p', 'view-lead');
+    intro.appendChild(
+      document.createTextNode('The component hierarchy. Each row carries its '),
+    );
+    var ownState = Yg.glossary ? Yg.glossary.term('verified', 'own state') : dom.el('span', null, 'own state');
+    intro.appendChild(ownState);
+    intro.appendChild(
+      document.createTextNode(
+        ' — kept separate from a roll-up over its children, so one refused leaf never falsely reddens an ancestor. Click a row to open it.',
+      ),
+    );
+    stage.appendChild(intro);
+
+    // In-tree filter: at hundreds of nodes, "where does X live" needs a filter that prunes the
+    // hierarchy to matches (plus their ancestors) in place — the ⌘K palette only jumps to a panel.
+    var filterWrap = dom.el('div', 'tree-filter');
+    var filterInput = dom.el('input', 'tree-filter-input');
+    filterInput.type = 'search';
+    filterInput.placeholder = 'Filter components by name or path…';
+    filterInput.setAttribute('aria-label', 'Filter the structure tree by component name or path');
+    filterWrap.appendChild(filterInput);
+    stage.appendChild(filterWrap);
+
+    var mount = dom.el('section', 'tree-mount');
+    stage.appendChild(mount);
+    var controller = Yg.tree.render(mount, data, function (path) {
+      if (ctx && ctx.onSelect) ctx.onSelect(path);
+    });
+
+    var debounce;
+    filterInput.addEventListener('input', function () {
+      var v = filterInput.value;
+      if (debounce) clearTimeout(debounce);
+      debounce = setTimeout(function () {
+        if (controller && controller.filter) controller.filter(v);
+      }, 120);
+    });
+
+    // Reveal-on-select: a palette pick or a deep-link to a node scrolls the tree to it and marks
+    // it, so the user lands ON the node in the hierarchy, not only in the side panel.
+    if (route && route.node && controller && controller.reveal) controller.reveal(route.node);
+  };
+})();