reslop 0.2.7 → 0.3.1

package/lib/review/format.js

@@ -0,0 +1,420 @@
+'use strict';
+
+const path = require('node:path');
+const files = require('../common/files.js');
+const { TASKS_FILE, TASK_KINDS, taskKind, taskTitle } = files;
+const { captureBaseline } = require('./merge.js');
+const { toInt, resource } = require('../common/utilities.js');
+const storePart = require('./store.js');
+const { flatTaskText, toNote, feedbackKey } = storePart;
+const { ReviewStore } = storePart;
+
+const REVIEW_STATUSES = ['editing', 'partial', 'done'];
+
+const EDITING_ALIASES = ['pending', 'ready'];
+
+const FEED_HEAD = /^### Feedback `([^`]+)` \+(\d+) \((.*)\)\s*$/;
+
+const FEED_BLOCK = /^(.*), block (\d+)$/;
+
+const FEED_BLOCK_ONLY = /^block (\d+)$/;
+
+const FEED_META = /^<!-- reslop:(.*) -->\s*$/;
+
+const FEED_SUFFIX = /^(.*) - (.+):(\d+):(\d+):(\d+)$/;
+
+const CHECK_ITEM = /^- \[([ xX])\] (.*)$/;
+
+const CODE_HEAD = /^- \[([ xX])\] code `([^`]+)`\s*$/;
+
+const FENCE_LINE = /^(`{3,})\s*$/;
+
+const FILE_QUOTE = /^> (.+)$/;
+
+const STATUS_LINE = /^status:\s*(\S+)\s*$/;
+
+const GIT_ORIGINS = ['unstaged', 'staged', 'untracked', 'commit', 'pr'];
+
+const SECTION_LINE = {
+  '### Todo': 'todo',
+  '### Feedback': 'feedback',
+};
+
+const BACKLOG_HEAD = 'Backlog';
+
+const LEGACY_BACKLOG = 'TODOs';
+
+const TASK_TITLES = Object.fromEntries([
+  [BACKLOG_HEAD, 'debt'],
+  [LEGACY_BACKLOG, 'debt'],
+  ['Issues', 'debt'],
+  ['Bug Reports', 'bugs'],
+  ['Bug reports', 'bugs'],
+  ['Feature Requests', 'features'],
+  ['Feature requests', 'features'],
+  ['Technical debt', 'debt'],
+  ['Research', 'research'],
+  ['Security', 'security'],
+  ...TASK_KINDS.map((kind) => [kind.title, kind.id]),
+]);
+
+const AGENT_INSTRUCTIONS = resource(__dirname, 'agent-instructions.md').trim();
+
+const canonicalStatus = (raw) => {
+  const name = EDITING_ALIASES.includes(raw) ? 'editing' : raw;
+  return REVIEW_STATUSES.includes(name) ? name : '';
+};
+
+const frontmatterStatus = (text) => {
+  const body = `${text ?? ''}`;
+  if (!body.startsWith('---')) return '';
+  const nl = body.indexOf('\n');
+  if (nl < 0) return '';
+  const rest = body.slice(nl + 1);
+  const end = rest.indexOf('\n---');
+  if (end < 0) return '';
+  for (const line of rest.slice(0, end).split('\n')) {
+    const match = STATUS_LINE.exec(line);
+    if (match) return match[1];
+  }
+  return '';
+};
+
+const parseFrontmatterStatus = (text) =>
+  canonicalStatus(frontmatterStatus(text));
+
+const isDoneMark = (mark) => mark === 'x' || mark === 'X';
+
+const checkboxLine = (text, done) => {
+  const mark = done ? 'x' : ' ';
+  return `- [${mark}] ${flatTaskText(text)}`;
+};
+
+const storeNote = (notes, note, key) => {
+  const next = toNote(note);
+  notes.set(key || feedbackKey(next), next);
+};
+
+const feedbackLine = (note) => {
+  const loc = feedbackKey(note);
+  return `${checkboxLine(note.text, note.done)} - ${loc}`;
+};
+
+const parseLoc = (raw) => {
+  const parts = raw.split(':');
+  const n = parts.length;
+  if (n < 4) return null;
+  const blockId = toInt(parts[n - 1]);
+  const newStart = toInt(parts[n - 2]);
+  const oldStart = toInt(parts[n - 3]);
+  if (!Number.isFinite(blockId + newStart + oldStart)) return null;
+  let fileParts = parts.slice(0, n - 3);
+  let origin = '';
+  if (fileParts.length > 1 && GIT_ORIGINS.includes(fileParts[0])) {
+    origin = fileParts[0];
+    fileParts = fileParts.slice(1);
+  }
+  if (!fileParts.length) return null;
+  const file = fileParts.join(':');
+  return { origin, file, oldStart, newStart, blockId };
+};
+
+const parseFeedSuffix = (textItem) => {
+  const match = FEED_SUFFIX.exec(textItem);
+  if (!match) return null;
+  const text = match[1];
+  const file = match[2];
+  const oldStart = toInt(match[3]);
+  const newStart = toInt(match[4]);
+  const blockId = toInt(match[5]);
+  return { text, file, oldStart, newStart, blockId };
+};
+
+const fileGroup = (groups, file) => {
+  let group = groups.get(file);
+  if (!group) {
+    group = { tasks: [], feedback: [], code: [] };
+    groups.set(file, group);
+  }
+  return group;
+};
+
+const TASK_SECTION = 'task:';
+
+const taskSection = (id) => `${TASK_SECTION}${id}`;
+
+const groupReviewNotes = (notes) => {
+  const groups = new Map();
+  for (const kind of TASK_KINDS) {
+    for (const todo of notes.tasks) {
+      if (!todo.text.trim() || taskKind(todo) !== kind.id) continue;
+      fileGroup(groups, taskSection(kind.id)).tasks.push(todo);
+    }
+  }
+  for (const key of notes.feedback.keys()) {
+    const note = notes.feedback.get(key);
+    if (!note.text.trim()) continue;
+    fileGroup(groups, note.file).feedback.push({ key, note });
+  }
+  for (const key of notes.code.keys()) {
+    const note = notes.code.get(key);
+    fileGroup(groups, note.file).code.push({ key, note });
+  }
+  return groups;
+};
+
+const reviewHeader = (notes) => {
+  const name = path.basename(notes.reviewPath, '.md');
+  const status = canonicalStatus(notes.status) || 'editing';
+  return [
+    '---',
+    `status: ${status}`,
+    '---',
+    '',
+    `# reslop review ${name}`,
+    '',
+    '## Agent instructions',
+    '',
+    AGENT_INSTRUCTIONS,
+    '',
+  ];
+};
+
+const fenceFor = (text) => {
+  let n = 3;
+  for (const line of text.split('\n')) {
+    const match = /^(`{3,})/.exec(line);
+    if (!match) continue;
+    if (match[1].length >= n) n = match[1].length + 1;
+  }
+  return '`'.repeat(n);
+};
+
+const emitCodeItem = (lines, note) => {
+  const loc = feedbackKey(note);
+  const mark = note.done ? 'x' : ' ';
+  const fence = fenceFor(note.text);
+  lines.push(`- [${mark}] code \`${loc}\``);
+  lines.push(fence);
+  if (note.text !== '') lines.push(note.text);
+  lines.push(fence);
+};
+
+const sectionTitle = (file) => {
+  if (!file.startsWith(TASK_SECTION)) return file;
+  return taskTitle(file.slice(TASK_SECTION.length));
+};
+
+const backlogFile = (name) => {
+  if (name === BACKLOG_HEAD || name === LEGACY_BACKLOG) return TASKS_FILE;
+  return name;
+};
+
+const emitReviewGroups = (lines, groups) => {
+  for (const file of groups.keys()) {
+    const group = groups.get(file);
+    lines.push(`## ${sectionTitle(file)}`);
+    lines.push('');
+    for (const todo of group.tasks) {
+      lines.push(checkboxLine(todo.text, todo.done));
+    }
+    for (const item of group.feedback) {
+      lines.push(feedbackLine(item.note));
+    }
+    for (const item of group.code) {
+      emitCodeItem(lines, item.note);
+    }
+    lines.push('');
+  }
+};
+
+const serializeReview = (notes) => {
+  const lines = reviewHeader(notes);
+  emitReviewGroups(lines, groupReviewNotes(notes));
+  return `${lines.join('\n')}\n`;
+};
+
+const parseFeedbackHeading = (line) => {
+  const match = FEED_HEAD.exec(line);
+  if (!match) return null;
+  const file = match[1];
+  const newStart = toInt(match[2]);
+  const rest = match[3];
+  const only = FEED_BLOCK_ONLY.exec(rest);
+  if (only) {
+    return { file, newStart, header: '', blockId: toInt(only[1]) };
+  }
+  const withHead = FEED_BLOCK.exec(rest);
+  if (!withHead) {
+    return { file, newStart, header: rest, blockId: 0 };
+  }
+  const header = withHead[1];
+  const blockId = toInt(withHead[2]);
+  return { file, newStart, header, blockId };
+};
+
+const headingFile = (line) => {
+  const quoted = FILE_QUOTE.exec(line);
+  if (quoted) return backlogFile(quoted[1]);
+  if (line.startsWith('## ') && line !== '## Agent instructions') {
+    const name = line.slice(3);
+    const kind = TASK_TITLES[name];
+    if (kind) return taskSection(kind);
+    return name;
+  }
+  return null;
+};
+
+const startFeedbackPending = (heading, file) => ({
+  file: heading.file || file,
+  newStart: heading.newStart,
+  header: heading.header,
+  blockId: heading.blockId,
+  oldStart: heading.newStart,
+  origin: '',
+  key: '',
+  text: '',
+});
+
+const applyFeedMeta = (pending, raw) => {
+  const loc = parseLoc(raw);
+  if (!loc) return pending;
+  return Object.assign(pending, loc, { key: feedbackKey(loc) });
+};
+
+const startCodePending = (line) => {
+  const match = CODE_HEAD.exec(line);
+  if (!match) return null;
+  const loc = parseLoc(match[2]);
+  if (!loc) return null;
+  return { done: isDoneMark(match[1]), ...loc, open: '', lines: [] };
+};
+
+class ReviewParser {
+  constructor(store) {
+    this.store = store;
+    this.file = '';
+    this.section = '';
+    this.pending = null;
+    this.code = null;
+  }
+
+  flushFeedback() {
+    const pending = this.pending;
+    this.pending = null;
+    if (!pending || !(pending.text ?? '').trim()) return;
+    storeNote(this.store.feedback, pending, pending.key);
+  }
+
+  closeCode(text) {
+    storeNote(this.store.code, { ...this.code, text });
+    this.code = null;
+  }
+
+  takeCheckItem(text, done) {
+    const { store, file, section, pending } = this;
+    if (file.startsWith(TASK_SECTION)) {
+      const kind = file.slice(TASK_SECTION.length);
+      store.addTask(TASKS_FILE, text, done, kind);
+      return;
+    }
+    if (section === 'todo' && file) {
+      store.addTask(file, text, done, 'backlog');
+      return;
+    }
+    const parsed = parseFeedSuffix(text);
+    if (parsed) {
+      this.flushFeedback();
+      storeNote(store.feedback, { ...parsed, file: parsed.file || file, done });
+      return;
+    }
+    if (pending) {
+      pending.text = text;
+      pending.done = done;
+      this.flushFeedback();
+      return;
+    }
+    if (file && section !== 'feedback') {
+      store.addTask(file, text, done, 'backlog');
+    }
+  }
+
+  takeReviewLine(line) {
+    const nextFile = headingFile(line);
+    if (nextFile !== null) {
+      this.flushFeedback();
+      this.file = nextFile;
+      this.section = '';
+      return;
+    }
+    const nextSection = SECTION_LINE[line];
+    if (nextSection) {
+      this.flushFeedback();
+      this.section = nextSection;
+      return;
+    }
+    const heading = parseFeedbackHeading(line);
+    if (heading) {
+      this.flushFeedback();
+      this.pending = startFeedbackPending(heading, this.file);
+      this.section = 'feedback';
+      return;
+    }
+    const meta = FEED_META.exec(line);
+    if (meta && this.pending) {
+      applyFeedMeta(this.pending, meta[1]);
+      return;
+    }
+    const item = CHECK_ITEM.exec(line);
+    if (item) this.takeCheckItem(item[2], isDoneMark(item[1]));
+  }
+
+  takeCodeLine(line) {
+    const code = this.code;
+    const fence = FENCE_LINE.exec(line);
+    if (!code.open) {
+      if (fence) code.open = fence[1];
+      else if (line.trim()) this.closeCode('');
+      return this.code !== null;
+    }
+    const closes = fence && fence[1].length >= code.open.length;
+    if (closes) this.closeCode(code.lines.join('\n'));
+    else code.lines.push(line);
+    return true;
+  }
+
+  takeLine(line) {
+    if (this.code && this.takeCodeLine(line)) return;
+    const started = startCodePending(line);
+    if (started) {
+      this.flushFeedback();
+      this.code = started;
+      return;
+    }
+    this.takeReviewLine(line);
+  }
+
+  finish() {
+    const code = this.code;
+    if (code) this.closeCode(code.open ? code.lines.join('\n') : '');
+    this.flushFeedback();
+  }
+}
+
+const parseReview = (text, reviewPath, templates = []) => {
+  const store = new ReviewStore(reviewPath, templates);
+  const parser = new ReviewParser(store);
+  for (const line of text.split('\n')) parser.takeLine(line);
+  parser.finish();
+  store.status = parseFrontmatterStatus(text) || 'editing';
+  store.dirty = false;
+  captureBaseline(store);
+  return store;
+};
+
+module.exports = {
+  frontmatterStatus,
+  parseFrontmatterStatus,
+  serializeReview,
+  parseReview,
+};

package/lib/{review-merge.js → review/merge.js}

@@ -1,13 +1,11 @@
 'use strict';
 
-const files = require('./files.js');
-const { TASKS_FILE, taskKind } = files;
-
-const flatText = (text) => `${text ?? ''}`.trim().replace(/\n/g, ' ');
+const { TASKS_FILE, taskKind } = require('../common/files.js');
+const { flatTaskText } = require('./store.js');
 
 const snapTodo = (todo) => ({
   file: todo.file ?? '',
-  text: flatText(todo.text),
+  text: flatTaskText(todo.text),
   done: todo.done === true,
   kind: taskKind(todo),
 });
@@ -53,7 +51,7 @@ const withDone = (todo, done) => {
   return { ...todo, done };
 };
 
-const liveText = (todo) => flatText(todo.text);
+const liveText = (todo) => flatTaskText(todo.text);
 
 const snapText = (snap) => snap.text;
 
@@ -182,8 +180,11 @@ class TodoMerge {
   }
 }
 
-const sameNote = (left, right) =>
-  left.text === right.text && !!left.done === !!right.done;
+const sameNote = (left, right) => {
+  const sameText = left.text === right.text;
+  const sameDone = !!left.done === !!right.done;
+  return sameText && sameDone;
+};
 
 const cloneNote = (note, done) => {
   if (!!note.done === done) return note;

package/lib/review/review.js

@@ -0,0 +1,190 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const files = require('../common/files.js');
+const { REVIEW_DIR, taskKind } = files;
+const { captureBaseline, mergeReview } = require('./merge.js');
+const {
+  pad2,
+  dateStamp,
+  toInt,
+  readText,
+  writeJson,
+  listDir,
+} = require('../common/utilities.js');
+const formatPart = require('./format.js');
+const { parseFrontmatterStatus, parseReview, serializeReview } = formatPart;
+const { frontmatterStatus } = formatPart;
+const storePart = require('./store.js');
+const { hasNotes, ReviewStore, noteCounts, reviewProgress } = storePart;
+const { checkLabel, feedbackKey } = storePart;
+const templatesPart = require('./templates.js');
+const { TEMPLATES_FILE, LEGACY_TEMPLATES, TEMPLATE_SHOW, rankedTemplates } =
+  templatesPart;
+const { prefixTemplates, upsertTemplate, loadTemplates } = templatesPart;
+
+const AUTOSAVE_MS = 3000;
+
+const REVIEW_NAME = /^(\d{4}-\d{2}-\d{2})-(\d+)\.md$/;
+
+const allocateReviewPath = (dir, date, existingNames) => {
+  const stamp = dateStamp(date);
+  let max = -1;
+  for (const name of existingNames) {
+    const match = REVIEW_NAME.exec(name);
+    if (!match) continue;
+    if (match[1] !== stamp) continue;
+    const n = toInt(match[2]);
+    if (n > max) max = n;
+  }
+  const next = max + 1;
+  return path.join(dir, REVIEW_DIR, `${stamp}-${pad2(next)}.md`);
+};
+
+const listReviewNames = (dir) => listDir(path.join(dir, REVIEW_DIR));
+
+const compareReviewNames = (left, right) => {
+  const a = REVIEW_NAME.exec(left);
+  const b = REVIEW_NAME.exec(right);
+  if (!a && !b) return 0;
+  if (!a) return -1;
+  if (!b) return 1;
+  if (a[1] < b[1]) return -1;
+  if (a[1] > b[1]) return 1;
+  return toInt(a[2]) - toInt(b[2]);
+};
+
+const latestReviewName = (names) => {
+  let best = '';
+  for (const name of names) {
+    if (!REVIEW_NAME.test(name)) continue;
+    if (!best || compareReviewNames(name, best) > 0) best = name;
+  }
+  return best;
+};
+
+const readEntries = (folder) => {
+  try {
+    return fs.readdirSync(folder, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+};
+
+const planFiles = (dir) => {
+  const reviews = [];
+  const notes = [];
+  for (const entry of readEntries(path.join(dir, REVIEW_DIR))) {
+    const name = entry.name;
+    if (!entry.isFile() || !name.endsWith('.md')) continue;
+    if (REVIEW_NAME.test(name)) reviews.push(name);
+    else notes.push(name);
+  }
+  return { reviews, notes };
+};
+
+const planFileNames = (dir) => {
+  const { reviews, notes } = planFiles(dir);
+  reviews.sort((left, right) => compareReviewNames(right, left));
+  return reviews.concat(notes.sort());
+};
+
+const orderedPlanNames = (dir) => {
+  const { reviews, notes } = planFiles(dir);
+  reviews.sort(compareReviewNames);
+  notes.sort();
+  return notes.concat(reviews);
+};
+
+const readReviewStatus = (reviewPath) =>
+  parseFrontmatterStatus(readText(reviewPath));
+
+const resolveReviewPath = (dir, date, existingNames, extra = {}) => {
+  if (!extra.forceNew) {
+    const latest = latestReviewName(existingNames);
+    if (latest) {
+      const reviewPath = path.join(dir, REVIEW_DIR, latest);
+      if (readReviewStatus(reviewPath) === 'editing') {
+        return { reviewPath, resume: true };
+      }
+    }
+  }
+  return {
+    reviewPath: allocateReviewPath(dir, date, existingNames),
+    resume: false,
+  };
+};
+
+const loadReview = (reviewPath, templates) => {
+  const raw = fs.readFileSync(reviewPath, 'utf8');
+  return parseReview(raw, reviewPath, templates);
+};
+
+const readReviewText = (reviewPath) => {
+  try {
+    return fs.readFileSync(reviewPath, 'utf8');
+  } catch (error) {
+    if (error.code === 'ENOENT') return '';
+    throw error;
+  }
+};
+
+const mergeDiskReview = (notes) => {
+  const text = readReviewText(notes.reviewPath);
+  if (!text.startsWith('---')) return;
+  const disk = parseReview(text, notes.reviewPath, notes.templates);
+  mergeReview(notes, disk);
+};
+
+const flushReview = (notes, force = false) => {
+  if (!notes || !notes.dirty) return false;
+  mergeDiskReview(notes);
+  if (!hasNotes(notes) && !force) {
+    notes.dirty = false;
+    return false;
+  }
+  const folder = path.dirname(notes.reviewPath);
+  fs.mkdirSync(folder, { recursive: true });
+  fs.writeFileSync(notes.reviewPath, serializeReview(notes), 'utf8');
+  const top = path.dirname(folder);
+  const templatesFile = path.join(top, REVIEW_DIR, TEMPLATES_FILE);
+  writeJson(templatesFile, notes.templates);
+  const legacyFile = path.join(top, REVIEW_DIR, LEGACY_TEMPLATES);
+  try {
+    fs.rmSync(legacyFile);
+  } catch {
+    // ignore when the old templates file is already gone
+  }
+  captureBaseline(notes);
+  notes.dirty = false;
+  return true;
+};
+
+module.exports = {
+  TEMPLATE_SHOW,
+  AUTOSAVE_MS,
+  allocateReviewPath,
+  listReviewNames,
+  latestReviewName,
+  planFileNames,
+  orderedPlanNames,
+  parseFrontmatterStatus,
+  resolveReviewPath,
+  rankedTemplates,
+  prefixTemplates,
+  upsertTemplate,
+  ReviewStore,
+  noteCounts,
+  reviewProgress,
+  frontmatterStatus,
+  hasNotes,
+  taskKind,
+  checkLabel,
+  feedbackKey,
+  serializeReview,
+  parseReview,
+  loadReview,
+  loadTemplates,
+  flushReview,
+};