claude-memory-lint 0.1.0

package/lib/detectors/perishable.js

@@ -0,0 +1,356 @@
+'use strict';
+// STABLE RESIDUE vs. PERISHABLE STATE in the memory archive.
+//
+// The failure mode this exists to catch: a status note records that some
+// external system was broken/blocked on a given day. The note was correct
+// that day. Days later the same system works fine, but nothing in the
+// archive says so, and by then someone has built a costly workaround around
+// a restriction that no longer exists. The sibling failure: a cited fact
+// that was true when written and has quietly gone stale since.
+//
+// The split to make:
+//
+//   STABLE RESIDUE     -- the area exists, the decision was made, the rule
+//                         holds. Write it down. It ages well.
+//   PERISHABLE STATE   -- "paused at step 5 of 9", "the block is active",
+//                         "the spec is in section 2". This is a measurement
+//                         of a moment. Let it expire, or if it must stay on
+//                         record, carry a MEASUREMENT DATE and a RECHECK
+//                         ROUTE — perishable by construction.
+//
+// -- THE BOUNDARY (which file is a "state card") LIVES IN ONE PLACE ---------
+//
+// `isStateCard` is that place. The signal comes from a command, not from
+// reading prose: `metadata.type: project` in frontmatter, or an explicit
+// `measuredOn:`/`recheck:` field. Judging the BODY by keyword ("paused",
+// "live", "active") was considered and rejected for the same reason: it
+// can't tell an actual state claim from prose describing someone else's
+// state, and produces false positives in both directions.
+//
+// -- MENTION IS NOT USE -------------------------------------------------------
+//
+// Backticks and fenced blocks are quotation. A measurement date written
+// INSIDE backticks (an example of the convention in a doc note) doesn't
+// count as a real measurement. Masking is shared, not reimplemented.
+//
+// -- CUT: ONLY NEW CARDS ------------------------------------------------------
+//
+// Same decision as the provenance detector, for the same reason: a detector
+// that debuts by flagging every pre-existing file leaves the gate red
+// forever, and a gate that's permanently red stops being a signal. A card
+// enters judgment if it declares `measuredOn:`/`recheck:` in frontmatter, OR
+// its `metadata.modified` is on/after the configured cutoff date. The
+// backlog doesn't disappear: it's counted separately and surfaced as a
+// warning.
+//
+// -- KNOWN LIMITS, DECLARED RATHER THAN HIDDEN --------------------------------
+//
+// (a) A file with no `metadata` block at all escapes the signal entirely.
+//     Closing this would need a second trigger on prose, which is the exact
+//     failure mode this design avoids. The gap is pinned by a test and the
+//     declarative door (`measuredOn:`/`recheck:`) is the way in for anyone
+//     who writes a state card without a `type`.
+// (b) The cut is BY FILE, not by line: `metadata.modified` belongs to the
+//     file, so appending one new note to an old state card drags the WHOLE
+//     file into the cut. Same class of defect the line-level cut in
+//     provenance.js fixes; not fixed here on purpose because the fix
+//     changes the unit of judgment, which is a design decision, not a
+//     detail.
+// (c) The measurement date is validated against the calendar and rejected if
+//     it's in the future: an accepted-but-invalid marker would leave the
+//     card LOOKING measured, which is worse than a red gate.
+//
+// Exit: 0 ok | 1 failed | 2 archive not found (not checked)
+
+const fs = require('fs');
+const { readCollection } = require('../collector');
+const { locateArchive } = require('../locate-archive');
+const { maskCode } = require('../mask-code');
+
+const STATE_TYPE = 'project';
+
+// --- reading frontmatter (fact, not judgment) ------------------------------
+
+// `metadata` arrives from the collector as a raw YAML block: the level-0 key
+// with its indented lines glued underneath. The `(?:^|\n)\s*` anchor is
+// required — without it, a key like `node_type: memory` could match before
+// `type: project` and misclassify the whole file.
+const RE_TYPE = /(?:^|\n)\s*type:\s*(\S+)/;
+const RE_MODIFIED = /(?:^|\n)\s*modified:\s*(\S+)/;
+
+function frontmatterField(file, key) {
+  const data = (file && file.frontmatter && file.frontmatter.data) || {};
+  const v = data[key];
+  return typeof v === 'string' && v.trim() ? v.trim() : null;
+}
+
+function metadataBlock(file) {
+  const data = (file && file.frontmatter && file.frontmatter.data) || {};
+  return typeof data.metadata === 'string' ? data.metadata : '';
+}
+
+function declaredType(file) {
+  const m = RE_TYPE.exec(metadataBlock(file));
+  if (m) return m[1];
+  return frontmatterField(file, 'type');
+}
+
+function modifiedDate(file) {
+  const m = RE_MODIFIED.exec(metadataBlock(file));
+  return m ? m[1] : null;
+}
+
+// --- the boundary: which file is a state card -------------------------------
+
+// Returns `{ isCard, via }`. `via` names the signal that decided, so both the
+// gate's message and the test assertion say which rule fired.
+function isStateCard(file) {
+  if (frontmatterField(file, 'measuredOn') || frontmatterField(file, 'recheck')) {
+    return { isCard: true, via: 'declared field (measuredOn/recheck)' };
+  }
+  const type = declaredType(file);
+  if (type === STATE_TYPE) return { isCard: true, via: `metadata.type: ${STATE_TYPE}` };
+  return { isCard: false, via: type ? `metadata.type: ${type}` : 'no type declared' };
+}
+
+// --- the two markers a state card carries ----------------------------------
+
+const RE_DATE = /\b(\d{4}-\d{2}-\d{2}|\d{1,2}\/\d{1,2}\/\d{2,4})\b/;
+// `measured on <date>` in the body. Accepts a couple of verb forms so a
+// reasonable phrasing isn't rejected on a technicality.
+const RE_MEASURED_ON = /\bmeasured\s+on\s*:?\s*(\d{4}-\d{2}-\d{2}|\d{1,2}\/\d{1,2}\/\d{2,4})\b/i;
+// `recheck: <how to reconfirm>` — needs an actual route, not just the word.
+const RE_RECHECK = /\brecheck\s*:\s*(\S.{2,})/i;
+
+// -- THE DATE HAS TO BE AN ACTUAL DATE, AND IN THE PAST ----------------------
+//
+// `\d{4}-\d{2}-\d{2}` matches `2026-13-45`, and the slash form matches
+// `32/01/2026`: without calendar validation the gate goes GREEN on a wrong
+// marker, which is worse than red — the card ends up LOOKING measured. A
+// future date is the same defect through a different door: a measurement is
+// of the past by construction, and a future date is either a typo or a
+// marker planted just to quiet the gate. The rejection names the reason
+// instead of returning a bare null.
+function todayLocal(d) {
+  const t = d || new Date();
+  const p = (n) => String(n).padStart(2, '0');
+  return `${t.getFullYear()}-${p(t.getMonth() + 1)}-${p(t.getDate())}`;
+}
+
+// Returns the date in ISO form, or null if the calendar doesn't allow it.
+function normalizeDate(txt) {
+  let y;
+  let mo;
+  let d;
+  const iso = /^(\d{4})-(\d{2})-(\d{2})$/.exec(String(txt));
+  if (iso) {
+    [, y, mo, d] = iso;
+  } else {
+    const br = /^(\d{1,2})\/(\d{1,2})\/(\d{2,4})$/.exec(String(txt));
+    if (!br) return null;
+    d = br[1];
+    mo = br[2];
+    y = br[3].length === 2 ? `20${br[3]}` : br[3];
+  }
+  const Y = Number(y);
+  const M = Number(mo);
+  const D = Number(d);
+  const dt = new Date(Date.UTC(Y, M - 1, D));
+  if (dt.getUTCFullYear() !== Y || dt.getUTCMonth() !== M - 1 || dt.getUTCDate() !== D) return null;
+  const p = (n) => String(n).padStart(2, '0');
+  return `${String(Y).padStart(4, '0')}-${p(M)}-${p(D)}`;
+}
+
+function validateMeasurementDate(txt, today) {
+  const iso = normalizeDate(txt);
+  if (!iso) return { ok: false, reason: 'impossible date' };
+  // Inclusive: measuring TODAY is the normal case.
+  if (iso > String(today)) return { ok: false, reason: 'date in the future' };
+  return { ok: true, reason: null };
+}
+
+// Each candidate (declared field, then body) goes through calendar
+// validation; the first VALID one wins, and if none wins the reported reason
+// is the first rejection's — the gate says what was actually written, not
+// just that something's missing.
+function findMeasurementDate(file, opts) {
+  const today = (opts && opts.today) || todayLocal();
+  const candidates = [];
+  const field = frontmatterField(file, 'measuredOn');
+  if (field) {
+    const mc = RE_DATE.exec(field);
+    if (mc) candidates.push({ txt: mc[1], via: 'frontmatter measuredOn' });
+  }
+  const body = maskCode(String((file && file.body) || ''));
+  const m = RE_MEASURED_ON.exec(body);
+  if (m) candidates.push({ txt: m[1], via: 'body "measured on <date>"' });
+
+  let reason = null;
+  for (const c of candidates) {
+    const v = validateMeasurementDate(c.txt, today);
+    if (v.ok) return { date: c.txt, via: c.via, reason: null };
+    if (!reason) reason = v.reason;
+  }
+  if (!reason && field) reason = 'measuredOn field has no readable date';
+  return { date: null, via: null, reason };
+}
+
+// Route to recheck: the command, call or step that reconfirms the state.
+function findRecheckRoute(file) {
+  const field = frontmatterField(file, 'recheck');
+  if (field && field.length >= 3) return { route: field, via: 'frontmatter recheck' };
+  const body = maskCode(String((file && file.body) || ''));
+  const m = RE_RECHECK.exec(body);
+  if (m) return { route: m[1].trim(), via: 'body "recheck: …"' };
+  return { route: null, via: null };
+}
+
+// --- cut: who enters judgment -----------------------------------------------
+
+function isInCutoff(file, cutoff) {
+  if (!cutoff) return { inCutoff: true, via: 'no cutoff configured' };
+  if (frontmatterField(file, 'measuredOn') || frontmatterField(file, 'recheck')) {
+    return { inCutoff: true, via: 'declared field (measuredOn/recheck)' };
+  }
+  const mod = modifiedDate(file);
+  if (mod && String(mod) >= String(cutoff)) return { inCutoff: true, via: `modified ${mod}` };
+  return { inCutoff: false, via: mod ? `modified ${mod}` : 'no date' };
+}
+
+// --- judgment ----------------------------------------------------------------
+
+// Judges ONE already-collected file. Pure: struct in, verdict out.
+//
+// Three end states, never blended:
+//   'not_a_card'  : stable residue, out of this gate's scope
+//   'out_of_cutoff': state card predating the convention (declared backlog)
+//   'ok'/'unmarked': new state card, judged
+function judgeFile(file, opts) {
+  const o = opts || {};
+  const cutoff = o.cutoff || null;
+  const scope = isStateCard(file);
+  if (!scope.isCard) {
+    return { name: file.name, state: 'not_a_card', via: scope.via, missing: [] };
+  }
+
+  const window = isInCutoff(file, cutoff);
+  const measurement = findMeasurementDate(file, { today: o.today || todayLocal() });
+  const route = findRecheckRoute(file);
+  const missing = [];
+  if (!measurement.date) missing.push('measurement_date');
+  if (!route.route) missing.push('recheck_route');
+
+  const base = {
+    name: file.name,
+    signal: scope.via,
+    via: window.via,
+    measurementDate: measurement.date,
+    measurementVia: measurement.via,
+    measurementReason: measurement.reason || null,
+    route: route.route,
+    routeVia: route.via,
+    missing,
+  };
+
+  if (!window.inCutoff) return { ...base, state: 'out_of_cutoff' };
+  if (missing.length) return { ...base, state: 'unmarked' };
+  return { ...base, state: 'ok' };
+}
+
+function auditPerishable(files, opts) {
+  return files.map((f) => judgeFile(f, opts));
+}
+
+// Summary from the SAME list the gate reads, never a second parallel count.
+function summarizePerishable(lines) {
+  const cards = lines.filter((l) => l.state !== 'not_a_card');
+  const outside = cards.filter((l) => l.state === 'out_of_cutoff');
+  const inside = cards.filter((l) => l.state !== 'out_of_cutoff');
+  const unmarked = inside.filter((l) => l.state === 'unmarked');
+  const outsideNoDate = outside.filter((l) => l.missing.includes('measurement_date'));
+  const outsideNoRoute = outside.filter((l) => l.missing.includes('recheck_route'));
+  return {
+    total: lines.length,
+    cards: cards.length,
+    notCards: lines.length - cards.length,
+    outOfCutoff: outside.length,
+    outOfCutoffNoDate: outsideNoDate.length,
+    outOfCutoffNoRoute: outsideNoRoute.length,
+    inCutoff: inside.length,
+    ok: inside.length - unmarked.length,
+    unmarked: unmarked.length,
+    failed: unmarked.length,
+    namesUnmarked: unmarked.map((l) => l.name),
+    missingInCutoff: unmarked.reduce((n, l) => n + l.missing.length, 0),
+  };
+}
+
+module.exports = {
+  STATE_TYPE,
+  frontmatterField,
+  declaredType,
+  modifiedDate,
+  isStateCard,
+  todayLocal,
+  normalizeDate,
+  validateMeasurementDate,
+  findMeasurementDate,
+  findRecheckRoute,
+  isInCutoff,
+  judgeFile,
+  auditPerishable,
+  summarizePerishable,
+};
+
+// --- CLI ---------------------------------------------------------------
+// Usage: node lib/detectors/perishable.js [--json]
+// Exit: 0 nothing failed | 1 new state card missing a measurement date or a
+// recheck route | 2 archive not found (not checked).
+if (require.main === module) {
+  const { loadConfig } = require('../config');
+  const json = process.argv.includes('--json');
+  const { config } = loadConfig();
+  const cutoff = process.env.MEMORY_LINT_PERISHABLE_CUTOFF || config.perishable.cutoffDate;
+  const { dir, source } = locateArchive();
+
+  if (!fs.existsSync(dir)) {
+    const msg = `PERISHABLE: ARCHIVE NOT CHECKED - ${dir} not found (path from ${source}).`;
+    if (json) console.log(JSON.stringify({ dir, source, cutoff, state: 'absent', summary: null, lines: null }, null, 2));
+    else console.log(msg);
+    console.error(msg);
+    process.exit(2);
+  }
+
+  const r = readCollection(dir);
+  const lines = auditPerishable(r.files, { cutoff });
+  const summary = summarizePerishable(lines);
+  const state = summary.failed > 0 ? 'failed' : 'ok';
+
+  if (json) {
+    console.log(JSON.stringify({ dir, source, cutoff, state, summary, lines: lines.filter((l) => l.state === 'unmarked') }, null, 2));
+  } else {
+    console.log(`archive: ${dir}  (${source})`);
+    console.log(`cutoff: ${cutoff || '(none, everything judged)'}`);
+    console.log(`signal for a state card: metadata.type: ${STATE_TYPE}, or a declared field`);
+    console.log(`total: ${summary.total}  state cards: ${summary.cards}  stable residue (out of scope): ${summary.notCards}`);
+    console.log(`cards in cutoff: ${summary.inCutoff}  out of cutoff: ${summary.outOfCutoff}`);
+    console.log(`in cutoff: ok ${summary.ok}  unmarked ${summary.unmarked}  (missing: ${summary.missingInCutoff})`);
+    if (summary.failed) {
+      console.log(`\nPERISHABLE: ${summary.failed} failed.`);
+      for (const l of lines.filter((x) => x.state === 'unmarked')) {
+        const reason = l.measurementReason ? `  date rejected: ${l.measurementReason}` : '';
+        console.log(`  ${l.name}  [${l.missing.join('+')}]  (${l.signal})${reason}`);
+      }
+      console.log('\nA recorded perishable state carries both markers: `measured on <date>` and `recheck: <how to reconfirm>`.');
+    } else {
+      console.log('\nPERISHABLE: nothing failed.');
+    }
+    if (summary.outOfCutoff) {
+      console.log(
+        `\nDECLARED BACKLOG: ${summary.outOfCutoff} state card(s) predating the cutoff are not judged here ` +
+        `(${summary.outOfCutoffNoDate} missing a measurement date, ${summary.outOfCutoffNoRoute} missing a recheck route).`
+      );
+    }
+  }
+  process.exit(summary.failed > 0 ? 1 : 0);
+}