@marcomigozzi/trailhead 0.16.1 → 0.18.0

package/plugins/trailhead/templates/trailhead-issue-body.js

@@ -8,7 +8,8 @@
 //
 // CLI:
 //   node trailhead-issue-body.js <append|replace|remove> --issue <n> [--repo <owner/name>]
-//        --section "<name>" (--line "<text>" | --file <path> | --match "<text>") [--dry-run]
+//        --section "<name>" (--line "<text>" | --file <path> | --match "<text>")
+//        [--stamp <sha>] [--dry-run]
 //   append   adds --line as the last line of the section (a `_none yet_`-style
 //            placeholder that is the section's only content is dropped)
 //   replace  swaps the section content for the text of --file
@@ -17,6 +18,12 @@
 // <name> matches a `## ` heading with its leading emoji/punctuation stripped
 // (`Decisions so far` matches `## ✅ Decisions so far`); `:preamble` is the text
 // before the first `## ` (the conventions header).
+// --stamp <sha> (7 to 40 lowercase hex) sets the section's `_as of <sha>_` line, the
+// commit a codebase facet was written or last patched against: the first content
+// line of the section, then a blank line. Applied only when given (map and
+// conventions patches omit it) and written in the same single guarded write as the
+// patch. Without it an existing stamp is kept; a no-op `remove` writes nothing and
+// does not stamp. Not valid on `:preamble`. #360.
 // --dry-run reads and computes (secret scan included) but writes nothing and
 // prints the old and new byte sizes.
 //
@@ -40,6 +47,7 @@ const fs = require('fs');
 const os = require('os');
 const path = require('path');
 const { spawnSync } = require('child_process');
+const { gitEnv } = require('./trailhead-git-env.js');
 
 const PREAMBLE = ':preamble';
 const DEGENERATE_MAX = 20; // a body with fewer non-space characters is degenerate
@@ -116,20 +124,80 @@ function bodyLines(text) {
   return t === '' ? [] : t.split('\n');
 }
 
-// A list entry: a top-level `- ` line plus the indented lines that follow it.
+// A list entry: a top-level bullet (`- `, `* `, `+ `) or ordered item (`1. `, `1) `)
+// plus the indented lines that follow it (a continuation paragraph may follow blank
+// lines; the entry's end excludes trailing blanks). Ordered entries carry their number and
+// delimiter (null for a bullet); an indented `1.` is a continuation, not an entry.
 function listEntries(lines, sec) {
   const entries = [];
   const end = contentEnd(lines, sec);
   for (let i = sec.from; i < end; i++) {
-    if (!/^[-*+][ \t]/.test(lines[i])) continue;
+    const m = /^(?:[-*+]|(\d+)([.)]))[ \t]/.exec(lines[i]);
+    if (!m) continue;
     let j = i + 1;
-    while (j < end && /^[ \t]+\S/.test(lines[j])) j++;
-    entries.push({ start: i, end: j, text: lines.slice(i, j).join('\n') });
+    for (;;) {
+      // Blank lines belong to the entry only when an indented line follows them.
+      let k = j;
+      while (k < end && isBlank(lines[k])) k++;
+      if (k >= end || !/^[ \t]+\S/.test(lines[k])) break;
+      j = k + 1;
+    }
+    entries.push({
+      start: i,
+      end: j,
+      text: lines.slice(i, j).join('\n'),
+      num: m[1] === undefined ? null : Number(m[1]),
+      numText: m[1] === undefined ? '' : m[1],
+      delim: m[2] || null,
+    });
     i = j - 1;
   }
   return entries;
 }
 
+// After removing entry `h`, the following ordered entries with the same delimiter are
+// renumbered from h's own number. Entries separated only by blank lines (a loose list)
+// stay in the run; a paragraph, a bullet or another delimiter ends it. A list that
+// repeats one number (`1. 1. 1.`) is left alone, and zero padding is kept.
+// Returns a new lines array.
+function renumberAfter(lines, entries, h) {
+  if (h.num === null) return lines;
+  const run = [];
+  let prev = h;
+  for (const e of entries.filter((x) => x.start > h.start)) {
+    const gap = lines.slice(prev.end, e.start);
+    if (e.num === null || e.delim !== h.delim || !gap.every(isBlank)) break;
+    run.push(e);
+    prev = e;
+  }
+  if ([h, ...run].every((e) => e.num === h.num)) return lines;
+  const padded = (t) => /^0\d/.test(t);
+  const fixed = new Map(run.map((e, k) => {
+    const width = Math.max(...[h, e].filter((x) => padded(x.numText)).map((x) => x.numText.length), 0);
+    const num = String(h.num + k).padStart(width, '0');
+    return [e.start, `${num}${h.delim}${lines[e.start].replace(/^\d+[.)]/, '')}`];
+  }));
+  return lines.map((l, i) => (fixed.has(i) ? fixed.get(i) : l));
+}
+
+// The line range [from, to) to drop for entry `h`: the entry plus, in a loose list, one
+// adjoining run of blank lines so no double blank or stray leading blank is left.
+function removalRange(lines, entries, h, sec) {
+  const k = entries.indexOf(h);
+  const prev = entries[k - 1];
+  const next = entries[k + 1];
+  const blankGap = (from, to) => to > from && lines.slice(from, to).every(isBlank);
+  const blankAfter = next && blankGap(h.end, next.start);
+  const blankBefore = prev && blankGap(prev.end, h.start);
+  const tightBefore = prev && prev.end === h.start;
+  if (blankAfter && !tightBefore) return [h.start, next.start];
+  if (blankBefore && !next) return [prev.end, h.end];
+  // Sole entry of a spaced section before a heading: drop one trailing blank too.
+  const soleSpaced = !prev && !next && h.start > sec.from && isBlank(lines[h.start - 1]) && h.end < sec.to && isBlank(lines[h.end]);
+  if (soleSpaced && sec.to < lines.length) return [h.start, h.end + 1];
+  return [h.start, h.end];
+}
+
 // The non-blank content lines of a section, or null when the section is missing.
 function readSection(body, name) {
   const { lines } = splitBody(String(body));
@@ -137,9 +205,83 @@ function readSection(body, name) {
   return sec ? lines.slice(sec.from, sec.to).filter((l) => !isBlank(l)) : null;
 }
 
-// op: { kind: 'append'|'replace'|'remove', section, line|text|match }.
+// --- facet stamp -------------------------------------------------------------
+
+const STAMP_RE = /^_as of ([0-9a-f]{7,40})_$/;
+const STAMP_VALUE_RE = /^[0-9a-f]{7,40}$/;
+const stampLine = (sha) => `_as of ${sha}_`;
+
+// The first non-blank line of lines[from..to) when it is a stamp: { at, sha }, else null.
+function stampIn(lines, from, to) {
+  for (let i = from; i < to; i++) {
+    if (isBlank(lines[i])) continue;
+    const m = STAMP_RE.exec(lines[i].trim());
+    return m ? { at: i, sha: m[1] } : null;
+  }
+  return null;
+}
+
+// `## ` sections of a body as { name, sha, text }: sha is the stamp or null, text
+// the section content. Fence-aware (headingIndexes), so a fenced `## ` is no facet.
+function facetsOf(body) {
+  const { lines } = splitBody(String(body));
+  const heads = headingIndexes(lines);
+  return heads.map((h, k) => {
+    const to = k + 1 < heads.length ? heads[k + 1] : lines.length;
+    const stamp = stampIn(lines, h + 1, to);
+    return { name: headingName(lines[h]), sha: stamp ? stamp.sha : null, text: lines.slice(h + 1, to).join('\n') };
+  });
+}
+
+// Runs the op with the stamp set aside, then writes the supplied stamp (else the
+// old one, else the file's own for a replace) back as the section's first content.
+function applyStamped(body, op) {
+  if (op.stamp !== undefined && !STAMP_VALUE_RE.test(op.stamp)) return { error: 'stamp must be 7 to 40 lowercase hex characters' };
+  if (op.section === PREAMBLE) return op.stamp === undefined ? applyCore(body, op) : { error: 'a stamp does not apply to the preamble' };
+  const parts = splitBody(String(body));
+  const sec = findSection(parts.lines, op.section);
+  if (!sec) return { error: `section not found: ${op.section}` };
+  const old = stampIn(parts.lines, sec.from, sec.to);
+  let text = op.text;
+  let own = null;
+  if (op.kind === 'replace') {
+    const tl = bodyLines(text);
+    const t = stampIn(tl, 0, tl.length);
+    if (t) {
+      own = t.sha;
+      tl.splice(t.at, t.at + 1 < tl.length && isBlank(tl[t.at + 1]) ? 2 : 1);
+      text = tl.join('\n');
+    }
+  }
+  const sha = op.stamp !== undefined ? op.stamp : old ? old.sha : own;
+  if (!old && sha === null) return applyCore(body, { ...op, text });
+  // Strip the old stamp line and the one blank line after it.
+  let stripped = parts;
+  if (old) {
+    const drop = old.at + 1 < sec.to && isBlank(parts.lines[old.at + 1]) ? 2 : 1;
+    stripped = { ...parts, lines: [...parts.lines.slice(0, old.at), ...parts.lines.slice(old.at + drop)] };
+  }
+  const r = applyCore(joinBody(stripped), { ...op, text });
+  if (r.error) return r;
+  if (!r.changed) return { ...r, body: String(body) };
+  const out = splitBody(r.body);
+  const ns = findSection(out.lines, op.section);
+  let at = ns.from;
+  while (at < ns.to && isBlank(out.lines[at])) at++;
+  if (at === ns.to) at = ns.from;
+  const add = [stampLine(sha)];
+  if (at >= out.lines.length || !isBlank(out.lines[at])) add.push('');
+  const lines = [...out.lines.slice(0, at), ...add, ...out.lines.slice(at)];
+  return { ...r, body: joinBody({ ...out, lines }) };
+}
+
+// op: { kind: 'append'|'replace'|'remove', section, line|text|match, stamp? }.
 // Returns { body, changed, summary } or { error }.
 function applyOp(body, op) {
+  return applyStamped(body, op);
+}
+
+function applyCore(body, op) {
   const parts = splitBody(String(body));
   const { lines } = parts;
   const sec = findSection(lines, op.section);
@@ -179,13 +321,16 @@ function applyOp(body, op) {
   }
 
   if (op.kind === 'remove') {
-    const hits = listEntries(lines, sec).filter((e) => e.text.includes(op.match));
+    const entries = listEntries(lines, sec);
+    const hits = entries.filter((e) => e.text.includes(op.match));
     if (hits.length === 0) {
       return { body: String(body), changed: false, summary: `no entry matching "${op.match}" in ${label}, nothing written` };
     }
     if (hits.length > 1) return { error: `ambiguous: ${hits.length} entries in ${label} contain "${op.match}"` };
     const h = hits[0];
-    const next = [...lines.slice(0, h.start), ...lines.slice(h.end)];
+    const renumbered = renumberAfter(lines, entries, h);
+    const [from, to] = removalRange(lines, entries, h, sec);
+    const next = [...renumbered.slice(0, from), ...renumbered.slice(to)];
     return { body: joinBody({ ...parts, lines: next }), changed: true, summary: `removed 1 entry from ${label}` };
   }
 
@@ -228,7 +373,7 @@ function secretProblem(text, guard) {
 // --- gh boundary -------------------------------------------------------------
 
 function defaultGh(args) {
-  const r = spawnSync('gh', args, { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
+  const r = spawnSync('gh', args, { encoding: 'utf8', env: gitEnv(), maxBuffer: 64 * 1024 * 1024 });
   return { status: r.status === null ? 1 : r.status, stdout: r.stdout || '', stderr: r.stderr || (r.error ? String(r.error.message) : '') };
 }
 
@@ -382,7 +527,7 @@ function parseArgs(argv) {
   for (let i = 1; i < argv.length; i++) {
     const flag = argv[i];
     if (flag === '--dry-run') { o.dryRun = true; continue; }
-    if (!['--issue', '--repo', '--section', '--line', '--file', '--match'].includes(flag)) return { error: `usage: unknown argument: ${flag}` };
+    if (!['--issue', '--repo', '--section', '--line', '--file', '--match', '--stamp'].includes(flag)) return { error: `usage: unknown argument: ${flag}` };
     i++;
     if (i >= argv.length) return { error: `usage: ${flag} requires a value` };
     const v = argv[i];
@@ -396,6 +541,10 @@ function parseArgs(argv) {
   }
   if (o.issue === undefined) return { error: 'usage: --issue is required' };
   if (!o.section) return { error: 'usage: --section is required' };
+  if (o.stamp !== undefined) {
+    if (!STAMP_VALUE_RE.test(o.stamp)) return { error: `usage: --stamp must be 7 to 40 lowercase hex characters, got: ${o.stamp}` };
+    if (o.section === PREAMBLE) return { error: 'usage: --stamp does not apply to :preamble' };
+  }
   const given = ['line', 'file', 'match'].filter((k) => o[k] !== undefined);
   const want = { append: 'line', replace: 'file', remove: 'match' }[kind];
   if (given.length !== 1 || given[0] !== want) return { error: `usage: ${kind} needs exactly --${want}` };
@@ -412,7 +561,7 @@ function main(argv, { gh, stdout, stderr, guard, tmpdir, firstEditDelta2 } = {})
   if (o.kind === 'replace') {
     try { text = fs.readFileSync(o.file, 'utf8'); } catch (e) { err.write(`usage: cannot read --file ${o.file}: ${e.message}\n`); return 2; }
   }
-  const op = { kind: o.kind, section: o.section, line: o.line, text, match: o.match };
+  const op = { kind: o.kind, section: o.section, line: o.line, text, match: o.match, stamp: o.stamp };
   const prefix = `issue #${o.issue}`;
   let summary = '';
   let unchanged = false;
@@ -452,7 +601,7 @@ function noopFirst(o, compute, wasUnchanged, opts) {
   return !(r && r.error) && wasUnchanged();
 }
 
-module.exports = { applyOp, readSection, defaultGh, PLACEHOLDER_RE, guardedWrite, loadGuard, main, parseArgs, readIssue, editCount, secretProblem, PREAMBLE, HISTORY_FULL_NOTE };
+module.exports = { applyOp, facetsOf, readSection, defaultGh, PLACEHOLDER_RE, guardedWrite, loadGuard, main, parseArgs, readIssue, editCount, secretProblem, PREAMBLE, HISTORY_FULL_NOTE };
 
 if (require.main === module) {
   process.exit(main(process.argv.slice(2), {}));

package/plugins/trailhead/templates/trailhead-merge-ticket.js

@@ -40,6 +40,7 @@ const fs = require('fs');
 const os = require('os');
 const path = require('path');
 const { spawnSync } = require('child_process');
+const { gitEnv } = require('./trailhead-git-env.js');
 const { guardedWrite, loadGuard, secretProblem } = require('./trailhead-issue-body.js');
 
 const MAX_PAGES = 100; // 100 pages x 100 issues
@@ -52,7 +53,7 @@ const NEEDS_YOU_DESC = 'Needs you: an autonomous run parked it for the human';
 const TITLE_PREFIX = 'Merge the branches left unmerged: ';
 
 function defaultGh(args) {
-  const r = spawnSync('gh', args, { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
+  const r = spawnSync('gh', args, { encoding: 'utf8', env: gitEnv(), maxBuffer: 64 * 1024 * 1024 });
   return { status: r.status === null ? 1 : r.status, stdout: r.stdout || '', stderr: r.stderr || (r.error ? String(r.error.message) : '') };
 }
 

package/plugins/trailhead/templates/trailhead-needs-you.js

@@ -7,6 +7,7 @@
 // CLI:
 //   node trailhead-needs-you.js park  --issue <n> --reason <text> --repo <owner/name>
 //   node trailhead-needs-you.js clear --issue <n> --repo <owner/name>
+//   node trailhead-needs-you.js sweep --repo <owner/name>
 //
 // park, in this order (so any partial failure leaves the ticket visible: a label is
 // never set on a ticket still claimed by the run):
@@ -21,15 +22,19 @@
 //   5. unassign `@me` when the ticket is assigned;
 //   6. add the label last.
 // clear: when the ticket carries the label, remove it; otherwise a no-op.
+// sweep: remove the label from every CLOSED issue that still carries it, however it was
+//   closed (a Resolve, a hand close, the web UI): a closed ticket never waits on the human.
 //
 // Prints exactly one JSON line on stdout:
 //   park:  {"status":"ok","issue":n,"commented":bool,"unassigned":bool,"labelled":bool}
 //   clear: {"status":"ok","issue":n,"cleared":bool}
+//   sweep: {"status":"ok","cleared":[n,...]}  (an error also carries the cleared list)
 //   error: {"status":"error","reason":"..."}
 // Exit 0 on ok, 1 on an error (any failed or unparseable gh step), 2 on a usage error
 // (stderr).
 
 const { spawnSync } = require('child_process');
+const { gitEnv } = require('./trailhead-git-env.js');
 const fs = require('fs');
 const path = require('path');
 
@@ -37,9 +42,10 @@ const LABEL = 'trailhead:needs-you';
 const LABEL_COLOR = 'D93F0B';
 const LABEL_DESC = 'Needs you: an autonomous run parked it for the human';
 const MARKER = 'NEEDS YOU';
+const SWEEP_LIMIT = 1000;
 
 function defaultGh(args) {
-  const r = spawnSync('gh', args, { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
+  const r = spawnSync('gh', args, { encoding: 'utf8', env: gitEnv(), maxBuffer: 64 * 1024 * 1024 });
   return { status: r.status === null ? 1 : r.status, stdout: r.stdout || '', stderr: r.stderr || (r.error ? String(r.error.message) : '') };
 }
 
@@ -82,8 +88,8 @@ function secretProblem(text, guard) {
 
 function parseArgs(argv) {
   const cmd = argv[0];
-  if (cmd !== 'park' && cmd !== 'clear') return { error: `usage: expected park or clear, got: ${cmd === undefined ? '(nothing)' : cmd}` };
-  const allowed = cmd === 'park' ? ['--issue', '--reason', '--repo'] : ['--issue', '--repo'];
+  if (!['park', 'clear', 'sweep'].includes(cmd)) return { error: `usage: expected park, clear or sweep, got: ${cmd === undefined ? '(nothing)' : cmd}` };
+  const allowed = { park: ['--issue', '--reason', '--repo'], clear: ['--issue', '--repo'], sweep: ['--repo'] }[cmd];
   const o = { cmd, issue: null, reason: null, repo: null };
   for (let i = 1; i < argv.length; i++) {
     const flag = argv[i];
@@ -102,7 +108,7 @@ function parseArgs(argv) {
     }
   }
   if (!o.repo) return { error: `usage: ${cmd} requires --repo` };
-  if (!o.issue) return { error: `usage: ${cmd} requires --issue` };
+  if (cmd !== 'sweep' && !o.issue) return { error: `usage: ${cmd} requires --issue` };
   if (cmd === 'park' && (o.reason === null || !o.reason.trim())) return { error: 'usage: park requires a non-empty --reason' };
   return o;
 }
@@ -124,6 +130,32 @@ function readIssue(run, o) {
   };
 }
 
+// Numeri delle issue chiuse che portano ancora la label, ordinati; oppure { error }.
+function listClosedLabelled(run, repo) {
+  const r = run(['issue', 'list', '--state', 'closed', '--label', LABEL, '--json', 'number', '--limit', String(SWEEP_LIMIT), '-R', repo]);
+  if (r.status !== 0) return { error: `gh issue list failed: ${firstLine(r.stderr) || 'exit ' + r.status}` };
+  let j;
+  try { j = JSON.parse(r.stdout); } catch { return { error: 'gh issue list returned unparseable JSON' }; }
+  if (!Array.isArray(j)) return { error: 'gh issue list returned unexpected JSON' };
+  return { numbers: j.map((i) => i && i.number).filter((n) => Number.isInteger(n)).sort((a, b) => a - b) };
+}
+
+// Toglie la label da ogni issue chiusa; continua dopo un errore e lo riporta alla fine.
+function sweep(run, repo, emit) {
+  const list = listClosedLabelled(run, repo);
+  if (list.error) { emit({ status: 'error', reason: list.error, cleared: [] }); return 1; }
+  const results = list.numbers.map((n) => ({ n, r: run(['issue', 'edit', String(n), '--remove-label', LABEL, '-R', repo]) }));
+  const cleared = results.filter((x) => x.r.status === 0).map((x) => x.n);
+  const failed = results.filter((x) => x.r.status !== 0);
+  if (failed.length) {
+    const reason = failed.map((x) => `#${x.n}: ${firstLine(x.r.stderr) || 'exit ' + x.r.status}`).join('; ');
+    emit({ status: 'error', reason: `gh issue edit (remove label) failed for ${reason}`, cleared });
+    return 1;
+  }
+  emit({ status: 'ok', cleared });
+  return 0;
+}
+
 // True when the latest NEEDS YOU comment already carries this reason.
 function alreadyCommented(comments, reason) {
   const mine = comments.filter((b) => String(b).replace(/\r/g, '').split('\n')[0] === MARKER);
@@ -143,6 +175,8 @@ function main(argv, { gh, guard, stdout, stderr } = {}) {
   const R = ['-R', o.repo];
   const n = String(o.issue);
 
+  if (o.cmd === 'sweep') return sweep(run, o.repo, emit);
+
   if (o.cmd === 'clear') {
     const cur = readIssue(run, o);
     if (cur.error) return fail(cur.error);