draftgo-cli 1.0.4

package/src/worklog.js

@@ -0,0 +1,276 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const { dgDir } = require('./paths');
+
+const STATUS = Object.freeze({ pending: '', active: '●', waiting: '?', completed: '√' });
+const LOCK_WAIT_ARRAY = new Int32Array(new SharedArrayBuffer(4));
+
+function formatLocalDate(value = new Date()) {
+  if (!(value instanceof Date) || Number.isNaN(value.getTime())) throw new TypeError('A valid Date is required.');
+  const year = String(value.getFullYear()).padStart(4, '0');
+  const month = String(value.getMonth() + 1).padStart(2, '0');
+  const day = String(value.getDate()).padStart(2, '0');
+  return `${year}-${month}-${day}`;
+}
+
+function worklogPath(projectDir) {
+  return path.join(dgDir(projectDir), 'worklog.md');
+}
+
+function invalid(detail) {
+  const error = new Error(`Invalid .draftgo/worklog.md: ${detail}`);
+  error.code = 'INVALID_WORKLOG';
+  return error;
+}
+
+function normalizeText(value, name = 'Worklog text') {
+  const text = value == null ? '' : String(value).trim();
+  if (!text) throw new TypeError(`${name} must not be empty.`);
+  if (/[\r\n\u2028\u2029]/.test(text)) throw new TypeError(`${name} must be a single line.`);
+  return text;
+}
+
+function normalizeDate(value, now = new Date()) {
+  const date = value == null || value === '' ? formatLocalDate(now) : String(value).trim();
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(date)) throw new TypeError('Worklog date must use YYYY-MM-DD.');
+  const [year, month, day] = date.split('-').map(Number);
+  const parsed = new Date(year, month - 1, day);
+  if (parsed.getFullYear() !== year || parsed.getMonth() !== month - 1 || parsed.getDate() !== day) {
+    throw new TypeError(`Invalid worklog date: ${date}.`);
+  }
+  return date;
+}
+
+function parseStatus(marker) {
+  if (marker === '●') return 'active';
+  if (marker === '√') return 'completed';
+  if (marker === '?') return 'waiting';
+  if (marker === '') return 'pending';
+  throw invalid(`unsupported status marker ${JSON.stringify(marker)}.`);
+}
+
+function parseWorklog(source) {
+  if (typeof source !== 'string') throw new TypeError('Worklog source must be a string.');
+  if (!source) return [];
+  if (/\r(?!\n)/.test(source)) throw invalid('unsupported line ending.');
+  const normalized = source.replace(/\r\n/g, '\n');
+  const body = normalized.endsWith('\n') ? normalized.slice(0, -1) : normalized;
+  if (!body) return [];
+  const lines = body.split('\n');
+  const blocks = [];
+  let cursor = 0;
+
+  while (cursor < lines.length) {
+    const header = /^\[\s*(\d{4}-\d{2}-\d{2})\s*\]$/.exec(lines[cursor]);
+    if (!header) throw invalid(`expected a [ YYYY-MM-DD ] header at line ${cursor + 1}.`);
+    const date = normalizeDate(header[1]);
+    if (blocks.length && date <= blocks[blocks.length - 1].date) {
+      throw invalid(`date blocks must be strictly chronological (line ${cursor + 1}).`);
+    }
+    cursor += 1;
+    const entries = [];
+    while (cursor < lines.length && lines[cursor] !== '') {
+      const itemMatch = /^([1-9]\d*)\.\s+\[\s*(●|√|\?)?\s*\]\s+(.+)$/.exec(lines[cursor]);
+      if (!itemMatch) throw invalid(`invalid item at line ${cursor + 1}.`);
+      const number = Number(itemMatch[1]);
+      if (!Number.isSafeInteger(number) || number !== entries.length + 1) {
+        throw invalid(`items must be consecutively numbered from 1 (line ${cursor + 1}).`);
+      }
+      const title = normalizeText(itemMatch[3], 'Worklog item');
+      const status = parseStatus(itemMatch[2] || '');
+      cursor += 1;
+      const notes = [];
+      while (cursor < lines.length && lines[cursor].startsWith('//')) {
+        const note = lines[cursor].slice(2).trim();
+        if (note) notes.push(note);
+        cursor += 1;
+      }
+      entries.push({ number, title, status, notes });
+    }
+    if (!entries.length) throw invalid(`date block ${date} has no items.`);
+    blocks.push({ date, entries });
+    if (cursor >= lines.length) break;
+    cursor += 1;
+    if (cursor >= lines.length || lines[cursor] === '') {
+      throw invalid(`date blocks must be separated by one blank line (line ${cursor + 1}).`);
+    }
+  }
+  return blocks;
+}
+
+function renderStatus(status) {
+  const marker = STATUS[status];
+  if (marker === undefined) throw new TypeError(`Unknown worklog status: ${status}.`);
+  return marker ? `[ ${marker} ]` : '[ ]';
+}
+
+function renderWorklog(blocks) {
+  if (!Array.isArray(blocks)) throw new TypeError('Worklog blocks must be an array.');
+  if (!blocks.length) return '';
+  return `${blocks.map((block) => [
+    `[ ${block.date} ]`,
+    ...block.entries.flatMap((entry) => [
+      `${entry.number}. ${renderStatus(entry.status)} ${entry.title}`,
+      ...(entry.notes || []).map((note) => `// ${note}`),
+    ]),
+  ].join('\n')).join('\n\n')}\n`;
+}
+
+function cloneBlocks(blocks) {
+  return blocks.map((block) => ({
+    ...block,
+    entries: block.entries.map((entry) => ({ ...entry, notes: [...entry.notes] })),
+  }));
+}
+
+function appendItem(blocks, title, status = 'pending', notes = [], date = normalizeDate()) {
+  const next = cloneBlocks(blocks);
+  const last = next[next.length - 1];
+  if (last && date < last.date) throw new Error(`Cannot append ${date}; the latest worklog date is ${last.date}.`);
+  if (last && last.date === date) {
+    last.entries.push({ number: last.entries.length + 1, title, status, notes: [...notes] });
+  } else {
+    next.push({ date, entries: [{ number: 1, title, status, notes: [...notes] }] });
+  }
+  return next;
+}
+
+function resolveReference(blocks, reference) {
+  const value = String(reference || '').trim();
+  const match = /^(?:([^#]+)#)?([1-9]\d*)$/.exec(value);
+  if (!match) throw new Error('Worklog item reference must be a number or YYYY-MM-DD#number.');
+  const date = match[1];
+  const number = Number(match[2]);
+  const block = date ? blocks.find((entry) => entry.date === normalizeDate(date)) : blocks[blocks.length - 1];
+  if (!block) throw new Error(`No worklog entries exist for ${date || 'the latest date'}.`);
+  const entry = block.entries.find((item) => item.number === number);
+  if (!entry) throw new Error(`Worklog item ${value} was not found.`);
+  return { block, entry };
+}
+
+function updateItem(blocks, reference, status, note) {
+  const next = cloneBlocks(blocks);
+  const resolved = resolveReference(next, reference);
+  resolved.entry.status = status;
+  if (note) resolved.entry.notes.push(note);
+  return next;
+}
+
+function temporaryPath(destination) {
+  return path.join(path.dirname(destination), `.${path.basename(destination)}.${process.pid}.${crypto.randomBytes(8).toString('hex')}.tmp`);
+}
+
+function writeTextAtomic(destination, content) {
+  fs.mkdirSync(path.dirname(destination), { recursive: true });
+  const temporary = temporaryPath(destination);
+  let descriptor;
+  try {
+    descriptor = fs.openSync(temporary, 'wx', 0o666);
+    fs.writeFileSync(descriptor, content, 'utf8');
+    fs.fsyncSync(descriptor);
+    fs.closeSync(descriptor);
+    descriptor = undefined;
+    fs.renameSync(temporary, destination);
+  } finally {
+    if (descriptor !== undefined) {
+      try { fs.closeSync(descriptor); } catch { /* Preserve the original failure. */ }
+    }
+    try { fs.rmSync(temporary, { force: true }); } catch { /* Best-effort cleanup. */ }
+  }
+}
+
+function removeStaleLock(lockPath, staleMs) {
+  try {
+    if (Date.now() - fs.lstatSync(lockPath).mtimeMs < staleMs) return false;
+    fs.rmSync(lockPath, { force: true });
+    return true;
+  } catch (error) {
+    if (error && error.code === 'ENOENT') return true;
+    throw error;
+  }
+}
+
+function acquireLock(destination, options = {}) {
+  fs.mkdirSync(path.dirname(destination), { recursive: true });
+  const lockPath = `${destination}.lock`;
+  const timeoutMs = Number(options.lockTimeoutMs ?? 10_000);
+  const staleMs = Number(options.lockStaleMs ?? 60_000);
+  const retryMs = Number(options.lockRetryMs ?? 10);
+  if (![timeoutMs, staleMs, retryMs].every(Number.isSafeInteger) || timeoutMs < 0 || staleMs < 1 || retryMs < 1) {
+    throw new TypeError('Invalid worklog lock timing options.');
+  }
+  const token = `${process.pid}:${crypto.randomBytes(16).toString('hex')}`;
+  const started = Date.now();
+  while (true) {
+    let descriptor;
+    try {
+      descriptor = fs.openSync(lockPath, 'wx', 0o600);
+      fs.writeFileSync(descriptor, `${token}\n`, 'utf8');
+      fs.fsyncSync(descriptor);
+      fs.closeSync(descriptor);
+      return { path: lockPath, token };
+    } catch (error) {
+      if (descriptor !== undefined) {
+        try { fs.closeSync(descriptor); } catch { /* Preserve the original failure. */ }
+      }
+      const retryable = error && ['EEXIST', 'EPERM', 'EACCES', 'EBUSY'].includes(error.code);
+      if (!retryable) throw error;
+    }
+    if (removeStaleLock(lockPath, staleMs)) continue;
+    const elapsed = Date.now() - started;
+    if (elapsed >= timeoutMs) {
+      const error = new Error('Timed out waiting for .draftgo/worklog.md.lock.');
+      error.code = 'WORKLOG_LOCK_TIMEOUT';
+      throw error;
+    }
+    Atomics.wait(LOCK_WAIT_ARRAY, 0, 0, Math.min(retryMs, timeoutMs - elapsed));
+  }
+}
+
+function releaseLock(lock) {
+  try {
+    if (fs.readFileSync(lock.path, 'utf8').trim() === lock.token) fs.rmSync(lock.path, { force: true });
+  } catch (error) {
+    if (!error || error.code !== 'ENOENT') throw error;
+  }
+}
+
+function mutateWorklog(projectDir, mutate, options = {}) {
+  const file = worklogPath(projectDir);
+  const lock = acquireLock(file, options);
+  try {
+    const source = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '';
+    const blocks = parseWorklog(source);
+    const result = mutate(blocks);
+    const next = result && result.blocks ? result.blocks : result;
+    writeTextAtomic(file, renderWorklog(next));
+    return { ...(result && result.blocks ? result : { blocks: next }), path: file };
+  } finally {
+    releaseLock(lock);
+  }
+}
+
+function readWorklog(projectDir) {
+  const file = worklogPath(projectDir);
+  return parseWorklog(fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '');
+}
+
+module.exports = {
+  STATUS,
+  formatLocalDate,
+  worklogPath,
+  normalizeDate,
+  parseWorklog,
+  renderWorklog,
+  appendItem,
+  resolveReference,
+  updateItem,
+  mutateWorklog,
+  readWorklog,
+  acquireLock,
+  releaseLock,
+  writeTextAtomic,
+};