criteria-review 0.3.2 → 0.3.3

package/bin/criteria-review.js

@@ -848,9 +848,20 @@ async function main() {
   // an instruction to open the review UI. The old fallthrough turned a typo - or a flag a
   // newer version understands - into a server start, which in a pipeline is a hang and on
   // a desk is EADDRINUSE from the server already running.
-  if (cmd !== undefined || args._.some((a) => a.startsWith('-'))) {
-    const what = cmd ?? args._.find((a) => a.startsWith('-'));
-    throw new Error(`unknown command "${what}". Run: criteria-review help`);
+  // `serve` is how a backgrounded server is spawned (see cmdStart), and no args at all is
+  // the foreground UI. Everything else reaching here is unrecognised.
+  //
+  // NAMED EXPLICITLY rather than left to fall through, which is what made the first
+  // version of this guard reject the tool's own subprocess and break `start`, `here` and
+  // `restart` in a published release. A guard that does not know the commands it is
+  // guarding is a guess.
+  if (cmd !== undefined && cmd !== 'serve') {
+    throw new Error(`unknown command "${cmd}". Run: criteria-review help`);
+  }
+  if (args._.some((a) => a.startsWith('-'))) {
+    throw new Error(
+      `unknown option "${args._.find((a) => a.startsWith('-'))}". Run: criteria-review help`
+    );
   }
 
   const cfg = await loadConfig();

package/docs/help/01-getting-started.md

@@ -65,9 +65,15 @@ The keyboard drives it. The bar along the bottom of the page is the whole cheat
 | `n` | write a note on it |
 | `f` | fullscreen the recording |
 | `r` | reload from disk |
+| `t` | switch between the flat queue and the grouped tree |
 | `/` | jump to the filter box |
 | `s` | switch between the queue and this reading tab |
 
+Two ways to read the list, for two different questions. **Flat** is the queue: one ordered run,
+riskiest first, which is what a review pass wants. **Tree** groups by document and feature, which
+is what "where does this live, and what else is near it" wants. Groups collapse, and moving the
+selection into a collapsed group opens it rather than selecting something you cannot see.
+
 **Every action writes straight into the source markdown**, next to the scenario it is about.
 There is no database. Your notes are sourced intent, which is the one thing that cannot be
 reconstructed from the code later, so they belong in git beside what they annotate.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "criteria-review",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "private": false,
   "description": "Review acceptance criteria across projects, and generate the scenario clauses your tests cite.",
   "license": "MIT",

package/public/app.js

@@ -35,6 +35,12 @@ const state = {
   tab: 'review',
   docs: [],
   doc: null,
+  // Flat is the queue: one ordered list, riskiest first, which is what a review PASS
+  // wants. Tree is the map: which document holds what, and which feature inside it,
+  // which is what someone answering "where does this live" wants. Different questions,
+  // so both, rather than a compromise that serves neither.
+  tree: false,
+  collapsed: new Set(),
 };
 
 /**
@@ -67,6 +73,8 @@ function saveViewState() {
         selected: scenarioKey(state.view[state.index]),
         tab: state.tab,
         doc: state.doc,
+        tree: state.tree,
+        collapsed: [...state.collapsed],
       })
     );
   } catch {
@@ -93,6 +101,8 @@ function restoreViewState() {
   // document who refreshes should be back on it, not at the top of the queue.
   state.doc = saved.doc ?? null;
   state.savedTab = saved.tab === 'standard' ? 'standard' : 'review';
+  state.tree = saved.tree === true;
+  state.collapsed = new Set(Array.isArray(saved.collapsed) ? saved.collapsed : []);
 }
 
 /**
@@ -237,26 +247,9 @@ function renderCounts() {
     .join('');
 }
 
-function renderList() {
-  // A header whenever the document changes, so the batch boundary is visible.
-  // Without it the grouping is real but invisible, and a reviewer cannot tell
-  // whether the next item continues the current feature or starts a new one.
-  let lastDoc = null;
-  $('#list').innerHTML = state.view
-    .map((s, i) => {
-      const doc = `${s.project} ${s.source}`;
-      let header = '';
-      if (doc !== lastDoc) {
-        lastDoc = doc;
-        const remaining = state.view.filter((x) => `${x.project} ${x.source}` === doc).length;
-        header = `<div class="doc-head">
-            <span class="doc-name">${escapeHtml(s.source.split('/').slice(-1)[0])}</span>
-            <span class="doc-meta">${escapeHtml(s.project)} · ${remaining}</span>
-          </div>`;
-      }
-      return (
-        header +
-        `<button class="row ${i === state.index ? 'active' : ''} ${
+/** One scenario row. Shared by both views so they cannot drift in how a scenario reads. */
+function scenarioRow(s, i, depth = 0) {
+  return `<button class="row depth-${depth} ${i === state.index ? 'active' : ''} ${
           state.highlight.has(s.id) ? 'highlighted' : ''
         }" data-i="${i}">
           <span class="row-top">${flagged(s) ? '<span class="looknow">LOOK</span>' : ''}${
@@ -271,10 +264,90 @@ function renderList() {
                 }">!</span>`
           }</span>
           <span class="row-title">${escapeHtml(s.title)}</span>
-        </button>`
-      );
+        </button>`;
+}
+
+/** The queue: one ordered list, with a header where the document changes. */
+function renderFlat() {
+  // A header whenever the document changes, so the batch boundary is visible. Without
+  // it the grouping is real but invisible, and a reviewer cannot tell whether the next
+  // item continues the current feature or starts a new one.
+  let lastDoc = null;
+  return state.view
+    .map((s, i) => {
+      const doc = `${s.project} ${s.source}`;
+      let header = '';
+      if (doc !== lastDoc) {
+        lastDoc = doc;
+        const remaining = state.view.filter((x) => `${x.project} ${x.source}` === doc).length;
+        header = `<div class="doc-head">
+            <span class="doc-name">${escapeHtml(s.source.split('/').slice(-1)[0])}</span>
+            <span class="doc-meta">${escapeHtml(s.project)} · ${remaining}</span>
+          </div>`;
+      }
+      return header + scenarioRow(s, i);
     })
     .join('');
+}
+
+/**
+ * The map: project, document, feature, scenario.
+ *
+ * Groups keep the order of FIRST APPEARANCE in the queue rather than sorting
+ * alphabetically, so the riskiest document is still at the top and the two views agree
+ * about what matters most. A tree that reordered the queue would quietly disagree with
+ * every other surface about where to start.
+ */
+function renderTree() {
+  const tree = new Map();
+  state.view.forEach((s, i) => {
+    const docKey = `${s.project}|${s.source}`;
+    if (!tree.has(docKey)) tree.set(docKey, { scenario: s, features: new Map() });
+    const featureKey = s.feature ?? '';
+    const features = tree.get(docKey).features;
+    if (!features.has(featureKey)) features.set(featureKey, []);
+    features.get(featureKey).push([s, i]);
+  });
+
+  const caret = (open) => `<span class="caret">${open ? '▾' : '▸'}</span>`;
+  const out = [];
+
+  for (const [docKey, { scenario, features }] of tree) {
+    const docOpen = !state.collapsed.has(docKey);
+    const count = [...features.values()].reduce((n, list) => n + list.length, 0);
+    out.push(
+      `<div class="doc-head tree-head" data-group="${escapeHtml(docKey)}">
+        ${caret(docOpen)}
+        <span class="doc-name">${escapeHtml(scenario.source.split('/').slice(-1)[0])}</span>
+        <span class="doc-meta">${escapeHtml(scenario.project)} · ${count}</span>
+      </div>`
+    );
+    if (!docOpen) continue;
+
+    for (const [featureKey, list] of features) {
+      const featKey = `${docKey}|${featureKey}`;
+      const featOpen = !state.collapsed.has(featKey);
+      // A document with no Feature headings would otherwise grow a nameless level that
+      // costs a click and says nothing.
+      const named = featureKey !== '';
+      if (named) {
+        out.push(
+          `<div class="feature-head" data-group="${escapeHtml(featKey)}">
+            ${caret(featOpen)}
+            <span>${escapeHtml(featureKey)}</span>
+            <span class="doc-meta">${list.length}</span>
+          </div>`
+        );
+        if (!featOpen) continue;
+      }
+      for (const [s, i] of list) out.push(scenarioRow(s, i, named ? 1 : 0));
+    }
+  }
+  return out.join('');
+}
+
+function renderList() {
+  $('#list').innerHTML = state.tree ? renderTree() : renderFlat();
   const active = $('#list .row.active');
   if (active) active.scrollIntoView({ block: 'nearest' });
 }
@@ -467,9 +540,21 @@ function openNoteEditor(s) {
   };
 }
 
+function revealSelected() {
+  if (!state.tree) return;
+  const s = state.view[state.index];
+  if (!s) return;
+  const docKey = `${s.project}|${s.source}`;
+  state.collapsed.delete(docKey);
+  state.collapsed.delete(`${docKey}|${s.feature ?? ''}`);
+}
+
 function move(delta) {
   if (!state.view.length) return;
   state.index = Math.min(Math.max(state.index + delta, 0), state.view.length - 1);
+  // Before painting, not after: a selection inside a collapsed group would be real and
+  // invisible, and the reviewer would answer whatever they could see instead.
+  revealSelected();
   renderList();
   renderDetail();
   saveViewState();
@@ -601,7 +686,11 @@ async function showTab(tab) {
   $('#review-pane').hidden = tab !== 'review';
   $('#standard-pane').hidden = tab !== 'standard';
   for (const b of document.querySelectorAll('#tabs button')) {
-    b.classList.toggle('active', b.dataset.tab === tab);
+    const on = b.dataset.tab === tab;
+    b.classList.toggle('active', on);
+    // The class is what a sighted reader sees; this is what everything else reads. Setting
+    // one without the other makes the tab strip a lie to half its audience.
+    b.setAttribute('aria-selected', String(on));
   }
   // The queue's filters steer the queue and mean nothing while reading, so they go
   // rather than sit there implying they apply to what is on screen. Same for the
@@ -636,6 +725,17 @@ function moveDoc(delta) {
   openDoc(state.docs[next].name);
 }
 
+function setListMode(tree) {
+  state.tree = tree;
+  $('#view-mode').textContent = tree ? 'flat' : 'tree';
+  $('#view-mode').setAttribute('aria-pressed', String(tree));
+  revealSelected();
+  renderList();
+  saveViewState();
+}
+
+$('#view-mode').addEventListener('click', () => setListMode(!state.tree));
+
 $('#tabs').addEventListener('click', (e) => {
   const b = e.target.closest('button[data-tab]');
   if (b) showTab(b.dataset.tab);
@@ -673,7 +773,8 @@ document.addEventListener('keydown', (e) => {
     return;
   }
 
-  if (e.key === 'j') move(1);
+  if (e.key === 't') setListMode(!state.tree);
+  else if (e.key === 'j') move(1);
   else if (e.key === 'k') move(-1);
   else if (e.key === 'a') act('accepted');
   else if (e.key === 'v') act('verified');
@@ -690,6 +791,15 @@ document.addEventListener('keydown', (e) => {
 });
 
 $('#list').addEventListener('click', (e) => {
+  const group = e.target.closest('[data-group]');
+  if (group) {
+    const key = group.dataset.group;
+    if (state.collapsed.has(key)) state.collapsed.delete(key);
+    else state.collapsed.add(key);
+    renderList();
+    saveViewState();
+    return;
+  }
   const row = e.target.closest('.row');
   if (!row) return;
   state.index = Number(row.dataset.i);
@@ -781,6 +891,7 @@ function listen() {
 }
 
 restoreViewState();
+setListMode(state.tree);
 load()
   .then(listen)
   .then(() => {

package/public/index.html

@@ -9,9 +9,11 @@
   <body>
     <header class="bar">
       <h1>Criteria review</h1>
-      <nav class="tabs" id="tabs">
-        <button data-tab="review" class="active">Review</button>
-        <button data-tab="standard">Standard</button>
+      <nav class="tabs" id="tabs" role="tablist" aria-label="Views">
+        <button id="tab-review" data-tab="review" class="active"
+                role="tab" aria-selected="true" aria-controls="review-pane">Review</button>
+        <button id="tab-standard" data-tab="standard"
+                role="tab" aria-selected="false" aria-controls="standard-pane">Standard</button>
       </nav>
       <div class="counts" id="counts"></div>
       <div class="spacer"></div>
@@ -35,12 +37,14 @@
           <option value="none">no recording</option>
         </select>
         <input id="search" type="search" placeholder="filter text" />
+        <button id="view-mode" type="button" title="Flat queue or grouped tree (t)">tree</button>
       </div>
     </header>
 
     <div id="banner" class="banner" hidden title="click to dismiss"></div>
 
-    <main id="review-pane">
+    <div class="panes">
+      <main id="review-pane" role="tabpanel" aria-labelledby="tab-review">
       <aside id="list" class="list" aria-label="Scenario queue"></aside>
 
       <section id="detail" class="detail">
@@ -53,12 +57,13 @@
       deciding whether a scenario is written correctly should not have to leave the
       page and go find a repository to read the rule.
     -->
-    <main id="standard-pane" hidden>
+      <main id="standard-pane" role="tabpanel" aria-labelledby="tab-standard" hidden>
       <aside id="doc-list" class="list" aria-label="Standard documents"></aside>
       <section id="doc" class="detail md">
         <p class="empty">Select a document.</p>
       </section>
-    </main>
+      </main>
+    </div>
 
     <footer class="help">
       <!--
@@ -73,6 +78,7 @@
         <span><kbd>n</kbd> note</span>
         <span><kbd>f</kbd> fullscreen</span>
         <span><kbd>r</kbd> reload</span>
+        <span><kbd>t</kbd> tree / flat</span>
         <span><kbd>/</kbd> search</span>
       </span>
       <span id="keys-standard" class="keys" hidden>

package/public/styles.css

@@ -25,15 +25,35 @@
 
 * { box-sizing: border-box; }
 
+/*
+ * Flex column, NOT a four-row grid template.
+ *
+ * The grid version assigned rows by POSITION, so it was only correct while every child
+ * was in flow. The banner is `hidden` most of the time, which shifted each remaining
+ * child up a row: the pane took the banner's `auto` row and collapsed to its content,
+ * and the footer took the `1fr` and grew to fill the window. Adding a second view made
+ * it worse again, five children for four rows.
+ *
+ * A flex column has no positional assumption to break: the bars size to content and the
+ * pane area takes the rest, whatever is hidden.
+ */
 body {
   margin: 0;
   height: 100vh;
-  display: grid;
-  grid-template-rows: auto auto 1fr auto;
+  display: flex;
+  flex-direction: column;
   background: var(--bg);
   color: var(--text);
 }
 
+body > header,
+body > footer,
+body > .banner { flex: 0 0 auto; }
+
+/* min-height:0 is load bearing: without it a flex item refuses to shrink below its
+   content, and the scrolling panes push the footer off the bottom of the window. */
+.panes { flex: 1 1 auto; min-height: 0; }
+
 .bar {
   display: flex;
   align-items: center;
@@ -307,6 +327,41 @@ kbd {
 .note-dialog button { background: var(--panel-2); border: 1px solid var(--line); color: var(--text); border-radius: 6px; padding: 6px 14px; font-size: 13px; cursor: pointer; }
 .note-dialog button.primary { border-color: var(--accent); }
 
+/* ---- Tree view ---- */
+
+.tree-head, .feature-head { cursor: pointer; user-select: none; }
+.tree-head:hover, .feature-head:hover { background: var(--panel-2); }
+.caret { display: inline-block; width: 12px; color: var(--muted); font-size: 10px; }
+
+.feature-head {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  padding: 5px 12px 5px 18px;
+  font-size: 12px;
+  color: var(--muted);
+  border-bottom: 1px solid var(--line);
+}
+.feature-head span:nth-child(2) { color: var(--text); }
+.feature-head .doc-meta { margin-left: auto; }
+
+/* Indent nests the row under its feature without moving the status pills, which are
+   what the eye scans down. */
+.row.depth-1 { padding-left: 26px; }
+
+#view-mode {
+  background: var(--panel);
+  border: 1px solid var(--line);
+  color: var(--muted);
+  font: inherit;
+  font-size: 12px;
+  padding: 3px 10px;
+  border-radius: 6px;
+  cursor: pointer;
+}
+#view-mode:hover { color: var(--text); }
+#view-mode[aria-pressed='true'] { color: var(--text); border-color: var(--accent); }
+
 /* ---- Reading tab: the standard and the walkthrough, beside the queue ---- */
 
 .tabs { display: flex; gap: 2px; }
@@ -327,13 +382,23 @@ kbd {
   border-color: var(--line);
 }
 
-/* The two panes share the queue's grid, so switching does not move the furniture. */
+/* Both panes occupy ONE row of the body grid, so adding a second view cannot change the
+   page's row template. Before this they were siblings of header and footer, and the body's
+   four-row template had five children to place. */
+.panes { min-height: 0; display: grid; }
+.panes > main { grid-area: 1 / 1; min-height: 0; }
+
 #standard-pane { display: grid; grid-template-columns: 320px 1fr; min-height: 0; }
 
 /* `display` set on an element or class BEATS the hidden attribute's UA rule, so a
    pane given a display here stays on screen while claiming to be hidden. Both panes
    then render stacked. Needs the same specificity to win, not !important. */
-main[hidden], .filters[hidden], .counts[hidden] { display: none; }
+/* ID + attribute, because `#standard-pane { display: grid }` is an ID selector and beats a
+   plain `main[hidden]`. That mismatch shipped: the pane reported hidden === true while
+   computing display:grid, and rendered under the other one. */
+#review-pane[hidden], #standard-pane[hidden], .filters[hidden], .counts[hidden] {
+  display: none;
+}
 
 /* The two key-hint rows swap; the hidden one must actually go. */
 .keys { display: contents; }