claude-memory-lint 0.1.0

package/lib/detectors/honesty.js

@@ -0,0 +1,351 @@
+'use strict';
+// HONESTY GUARDRAIL, JUDGED BY EFFECT — no memory in the archive may contain
+// an instruction that, IF FOLLOWED, would make a real problem stop being
+// raised. A person who tells their agent "you can disagree and push back" one
+// day, then writes a memory born of one frustrated afternoon ("stop
+// questioning my numbers", "no more pushback") the next, silently overturns
+// the first instruction in every future session — nobody notices until an
+// error that should have been flagged wasn't.
+//
+// THE CRITERION IS THE EFFECT, NOT THE WORDING. An instruction stays caught
+// even when it arrives softened ("only flag it if it's really bad"), scoped
+// to one topic ("don't question me about the budget numbers"), justified
+// ("skip the caveats, we're in a hurry") or dressed up as a preference about
+// format, tone, pacing, or efficiency ("to save time, skip the risk
+// warnings"). So this detector never looks for one forbidden sentence: it
+// looks for the STRUCTURE suppressor + honesty act, in any of the families
+// below.
+//
+// WHAT PASSES (the declared boundary, and the half that matters): a
+// legitimate preference about FORM — length ("keep it short"), tone ("blunt,
+// no pleasantries"), how direct to be ("skip the preamble", "get to the
+// point"), and how much of a draft to touch ("only change the part I asked
+// about"). None of these make a problem stop being raised, and none of them
+// trip this detector.
+//
+// MENTION IS NOT USE: text inside a backtick span or a fenced code block is a
+// literal quotation and is out of judgment — a memory that explains this
+// detector needs to be able to show the phrase it catches. Quotation marks
+// are deliberately NOT exempted the same way: a real instruction fits inside
+// quotes just as well, and exempting them would only move the false positive,
+// not remove it. See `maskCode` (shared with the other detectors here).
+//
+// A NOTE ON REMEDIATION (for whoever reads the verdict, not for this code): a
+// finding here is not fixed by writing a softer version of the same memory.
+// Needing a softer version IS the signal that the line shouldn't be recorded
+// at all — and editing someone else's already-recorded memory is their call,
+// not this tool's.
+//
+// This module does not parse files itself: frontmatter, body, CRLF and BOM
+// handling all come from the shared collector (lib/collector.js). Only the
+// VERDICT lives here.
+//
+// Exit: 0 nothing found | 1 a suppression instruction found | 2 archive not
+// found (not checked)
+
+const fs = require('fs');
+const { readCollection } = require('../collector');
+const { locateArchive } = require('../locate-archive');
+const { maskCode } = require('../mask-code');
+
+// --- vocabulary of the criterion --------------------------------------------
+// Not a list of forbidden phrases (a forbidden phrase is defeated by swapping
+// one word for a synonym): it's the pair suppressor x honesty act.
+
+// Suppressor: what cancels the act. Includes the softened forms ("avoid",
+// "quit") and the scoped one ("no more"), because the criterion is the effect.
+const NEG = '(?:not|never|don\'t|do not|dont|stop|quit|forget|skip|avoid|no more|please don\'t)';
+const RE_NEG = new RegExp('\\b' + NEG + '\\b', 'g');
+
+// FORM OF INSTRUCTION ONLY, never descriptive prose. An earlier version of
+// this class of detector matched any inflection of the verb and flagged
+// sentences that DEFEND honesty ("the criticism was fair", "the failure
+// wasn't hidden") — a defect in the detector, not a real hit. Only the
+// address-the-agent forms (imperative, "please + verb") enter below;
+// descriptive third-person and noun forms are left out on purpose.
+
+// A direct honesty act, complete on its own.
+const RE_ACT_DIRECT =
+  /\b(?:disagree|question|challenge|criticize|object|contradict|correct me|push back|pushback|call it out)\b/g;
+
+// An honesty act that only counts with an object: signal/flag/raise/mention
+// WHAT. "let me know when it's done" is not honesty; "flag the risk" is.
+const RE_ACT_SIGNAL = /\b(?:warn|flag|raise|mention|bring up|point out|report|surface|note)\b/g;
+const RE_OBJECT =
+  /\b(?:risks?|problems?|errors?|issues?|flaws?|mistakes?|findings?|concerns?|objections?|criticism|bugs?|downsides?|caveats?|red flags?)\b/;
+
+// A cut straight to the noun ("no more pushback", "zero criticism") — the
+// construction already IS the order; it needs no verb.
+const RE_CUT_NOUN =
+  /\b(?:no more|zero|none of the)\s+(?:pushback|criticism|objections?|caveats?|questions?|risk warnings?|red flags?)\b/g;
+
+// A silencing verb in address-the-agent form: already carries the
+// suppression, needs no negator. The bare infinitive does NOT enter here:
+// "or suppress a finding" inside a list of things not to do is prose, not an
+// order.
+const RE_SILENCE =
+  /\b(?:hide|suppress|bury|omit|ignore|downplay|soften|sugarcoat|swallow|mute|gloss over|brush aside|sweep .{0,20} under the rug)\b/g;
+
+// When a silencing verb is the SUBJECT of a requirement ("suppressing a
+// finding requires an owner and a ticket"), the sentence is a rule AGAINST
+// suppression, not an order to suppress. Without this inversion the detector
+// would flag exactly the memories that defend honesty.
+const RE_REQUIREMENT =
+  /\b(?:requires?|needs?|takes?|depends on|only with|isn't enough|is not enough)\b/;
+
+// Forced agreement: the suppression stated from the other direction ("just
+// comply", "accept without question"). Some already fall under NEG+ACT;
+// these are the ones that don't.
+const RE_FORCED =
+  /\b(?:just execute|just comply|just agree|always agree|accept without question|follow without question|never contradict me|just say yes|only agree|just approve)\b/g;
+
+// Family E: SEVERITY THRESHOLD. Here the honesty act isn't negated — it's
+// RESTRICTED to a level: "only warn me if it's really serious", "only push
+// back if you're absolutely certain", "skip the caveats unless it's
+// critical". The effect is the same as the other families, and it blocks the
+// same way: the next time there's a REAL problem BELOW the threshold,
+// following the line to the letter means not raising it.
+const SEVERITY =
+  '(?:seri\\w*|critical\\w*|urgent\\w*|catastrophic\\w*|disastr\\w*|irreversib\\w*|absolut\\w*|certain|major|huge|blocking|really|truly|genuinely)';
+// "actually" is deliberately left OUT — it also matches phrasing that DEFENDS
+// a gate ("only valid if the check actually runs"), the opposite of
+// suppression.
+
+// "only/just ... if/when ... <severity>". The restrictor can come before the
+// act ("Only warn me if it's serious") or after ("Warn me only when it's
+// really serious"): this family judges the whole SENTENCE, not a left-hand
+// window like the families above. The negated punctuation classes stop the
+// construction from crossing a period/semicolon and matching pieces of two
+// different sentences.
+const RE_THRESHOLD_ONLY = new RegExp(
+  '\\b(?:only|just|solely)\\b[^.;:!?]{0,60}?\\b(?:if|when|unless)\\b[^.;:!?]{0,45}?' + SEVERITY,
+  'g'
+);
+
+// "unless / except when ... <severity>" — the same restriction stated from
+// the exception side.
+const RE_THRESHOLD_UNLESS = new RegExp(
+  '\\b(?:unless|except if|except when|save for|other than when)\\b[^.;:!?]{0,45}?' + SEVERITY,
+  'g'
+);
+
+const WINDOW_NEG = 45; // "not", "avoid", "no more" further away than this is a different clause
+const WINDOW_OBJ = 40; // "flag the risk" / "raise the problem"
+const WINDOW_REQ = 70; // "suppressing a finding requires an owner"
+const WINDOW_THRESHOLD = 50; // "only ... if it's serious" far from the act is a different topic
+
+function findAll(re, line) {
+  const out = [];
+  re.lastIndex = 0;
+  let m;
+  while ((m = re.exec(line))) out.push({ text: m[0], start: m.index, end: m.index + m[0].length });
+  return out;
+}
+
+// `RegExp.test` with the /g flag carries `lastIndex` between calls — a
+// classic bug that makes a detector start lying after its first hit. Always
+// zero it before and after.
+function testWindow(re, snippet) {
+  re.lastIndex = 0;
+  const r = re.test(snippet);
+  re.lastIndex = 0;
+  return r;
+}
+
+// Slices a line into sentences on strong punctuation, keeping each one's
+// offset. The threshold family must judge WITHIN one sentence — otherwise
+// "only publish if it's big. flag the risk" would match by proximity, which
+// is exactly the defect this split exists to prevent: the sentence has to
+// block on its own, without another sentence's suppressor carrying the verdict.
+function sentences(line) {
+  const out = [];
+  let start = 0;
+  for (let i = 0; i <= line.length; i++) {
+    if (i === line.length || '.;:!?'.includes(line[i])) {
+      const text = line.slice(start, i);
+      if (text.trim()) out.push({ text, start, end: i });
+      start = i + 1;
+    }
+  }
+  return out;
+}
+
+// Judges ONE already-masked line. Returns the list of hits (family + excerpt),
+// never just a boolean — the reader needs to know WHICH structure matched to
+// know what to fix.
+function findSuppression(maskedLine, rawLine) {
+  const line = maskedLine.toLowerCase();
+  const found = [];
+
+  const mark = (family, start, end, reason) => {
+    found.push({
+      family,
+      reason,
+      excerpt: rawLine.slice(Math.max(0, start - 20), Math.min(rawLine.length, end + 20)).trim(),
+    });
+  };
+
+  // Family A: negator + direct honesty act.
+  for (const a of findAll(RE_ACT_DIRECT, line)) {
+    const before = line.slice(Math.max(0, a.start - WINDOW_NEG), a.start);
+    if (testWindow(RE_NEG, before)) {
+      mark('negated_act', a.start, a.end, `honesty act "${a.text}" under a negator`);
+    }
+  }
+
+  // Family B: negator + flag/warn/raise WITH an honesty object.
+  for (const a of findAll(RE_ACT_SIGNAL, line)) {
+    const before = line.slice(Math.max(0, a.start - WINDOW_NEG), a.start);
+    if (!testWindow(RE_NEG, before)) continue;
+    const near = line.slice(a.end, a.end + WINDOW_OBJ);
+    if (!testWindow(RE_OBJECT, near)) continue;
+    mark('negated_signal', a.start, a.end + WINDOW_OBJ, `"${a.text}" a problem/risk under a negator`);
+  }
+
+  // Family C: silencing verb + honesty object, NOT negated and NOT the
+  // subject of a requirement.
+  for (const s of findAll(RE_SILENCE, line)) {
+    const before = line.slice(Math.max(0, s.start - WINDOW_NEG), s.start);
+    if (testWindow(RE_NEG, before)) continue; // "never hide the risk" = a requirement of honesty
+    const near = line.slice(s.end, s.end + WINDOW_OBJ);
+    if (!testWindow(RE_OBJECT, near)) continue;
+    const after = line.slice(s.end, s.end + WINDOW_REQ);
+    if (testWindow(RE_REQUIREMENT, after)) continue; // "suppressing a finding requires an owner"
+    mark('silencing', s.start, s.end + WINDOW_OBJ, `"${s.text}" with a problem/risk object`);
+  }
+
+  // Family C2: a direct cut of the noun ("no more pushback"). The
+  // construction is already the order; no verb needed.
+  for (const c of findAll(RE_CUT_NOUN, line)) {
+    mark('noun_cut', c.start, c.end, `"${c.text}"`);
+  }
+
+  // Family E: honesty act restricted by a severity threshold. The act can be
+  // directed ("push back", "flag it") or an object ("the criticism", "the
+  // caveats"); what blocks is the threshold's company in the SAME sentence.
+  for (const sent of sentences(line)) {
+    const thresholds = findAll(RE_THRESHOLD_ONLY, sent.text).concat(findAll(RE_THRESHOLD_UNLESS, sent.text));
+    for (const t of thresholds) {
+      // The act has to be NEAR the threshold, not just in the same sentence:
+      // without this window, a long sentence defending the gate ("only valid
+      // if CI actually runs..., not the absence of an error") would match on
+      // "error" at the far end — the same class of false positive that broke
+      // an earlier version of this detector.
+      const near = sent.text.slice(Math.max(0, t.start - WINDOW_THRESHOLD), t.end + WINDOW_THRESHOLD);
+      const hasAct =
+        testWindow(RE_ACT_DIRECT, near) || testWindow(RE_ACT_SIGNAL, near) || testWindow(RE_OBJECT, near);
+      if (!hasAct) continue;
+      mark('severity_threshold', sent.start + t.start, sent.start + t.end, 'honesty act restricted to a severity threshold');
+      break; // one hit per sentence is enough for the verdict
+    }
+  }
+
+  // Family D: forced agreement.
+  for (const f of findAll(RE_FORCED, line)) {
+    mark('forced_agreement', f.start, f.end, `"${f.text}"`);
+  }
+
+  return found;
+}
+
+// Text under judgment = frontmatter `description` + body. A suppression fits
+// in the description as much as the body, and the description is what loads
+// at boot.
+function judgeableText(file) {
+  const desc =
+    file.frontmatter && file.frontmatter.data && typeof file.frontmatter.data.description === 'string'
+      ? file.frontmatter.data.description
+      : '';
+  return (desc ? desc + '\n' : '') + String(file.body || '');
+}
+
+// Judges ONE already-collected file. Pure: struct in, verdict out.
+function judgeFile(file) {
+  const text = judgeableText(file);
+  const rawLines = text.split('\n');
+  // Mask the WHOLE text before slicing into lines: a code span that opens on
+  // one line and closes on the next only shows up correctly with the whole
+  // document in hand.
+  const maskedLines = maskCode(text).split('\n');
+  const occurrences = [];
+  for (let i = 0; i < rawLines.length; i++) {
+    for (const a of findSuppression(maskedLines[i], rawLines[i])) {
+      occurrences.push({ line: i + 1, ...a });
+    }
+  }
+  if (occurrences.length) return { name: file.name, state: 'suppression', occurrences };
+  return { name: file.name, state: 'ok', occurrences: [] };
+}
+
+function auditHonesty(files) {
+  return files.map(judgeFile);
+}
+
+// Summary from the SAME list the gate reads, never a second parallel count.
+function summarizeHonesty(lines) {
+  const suppressions = lines.filter((l) => l.state === 'suppression');
+  return {
+    total: lines.length,
+    ok: lines.length - suppressions.length,
+    suppressions: suppressions.length,
+    failed: suppressions.length,
+    namesSuppression: suppressions.map((l) => l.name),
+    occurrences: suppressions.reduce((n, l) => n + l.occurrences.length, 0),
+  };
+}
+
+module.exports = {
+  findSuppression,
+  judgeableText,
+  judgeFile,
+  auditHonesty,
+  summarizeHonesty,
+};
+
+// --- CLI ---------------------------------------------------------------
+// Usage: node lib/detectors/honesty.js [--json]
+// Exit: 0 nothing found | 1 a suppression instruction found | 2 archive not
+// found (not checked).
+if (require.main === module) {
+  const json = process.argv.includes('--json');
+  const { dir, source } = locateArchive();
+
+  if (!fs.existsSync(dir)) {
+    const msg = `HONESTY: NOT CHECKED - ${dir} not found (path from ${source}).`;
+    if (json) console.log(JSON.stringify({ dir, source, state: 'absent', summary: null, lines: null }, null, 2));
+    else console.log(msg);
+    console.error(msg);
+    process.exit(2);
+  }
+
+  const r = readCollection(dir);
+  const lines = auditHonesty(r.files);
+  const summary = summarizeHonesty(lines);
+  const state = summary.failed > 0 ? 'failed' : 'ok';
+
+  if (json) {
+    console.log(
+      JSON.stringify(
+        { dir, source, state, summary, lines: lines.filter((l) => l.state === 'suppression') },
+        null,
+        2
+      )
+    );
+  } else {
+    console.log(`archive: ${dir}  (${source})`);
+    console.log(`total: ${summary.total}  ok: ${summary.ok}  suppression found: ${summary.suppressions}`);
+    if (summary.failed) {
+      console.log(`\nHONESTY: ${summary.failed} file(s) with a suppression instruction.`);
+      for (const l of lines.filter((x) => x.state === 'suppression')) {
+        for (const o of l.occurrences) {
+          console.log(`  ${l.name}:${o.line}  [${o.family}]  ${o.reason}`);
+          console.log(`     ... ${o.excerpt} ...`);
+        }
+      }
+      console.log('\nThis is a FINDING to report, not something this tool edits on its own.');
+    } else {
+      console.log('\nHONESTY: nothing found.');
+    }
+  }
+  process.exit(summary.failed > 0 ? 1 : 0);
+}