claude-memory-lint 0.1.0

package/lib/collector.js

@@ -0,0 +1,205 @@
+'use strict';
+// Shared collector for the memory archive: a directory of Markdown files plus
+// one index file (default name `MEMORY.md`) that links to them.
+//
+// Every detector in this package needs the SAME input — per file: name,
+// frontmatter, body, `[[wikilink]]` references, and the matching index line —
+// so this module reads it once and hands back plain data. It never judges
+// anything (no pass/fail here); detectors consume this structure and decide.
+//
+// Disk access is confined to `listFiles` and `readCollection`. Everything
+// else is a pure function: text/structure in, structure out.
+const fs = require('fs');
+const path = require('path');
+
+const INDEX_NAME = 'MEMORY.md';
+
+// The index file documents the folder, not a memory itself: it never carries
+// frontmatter and is never a linkable entry, so it stays out of file counts.
+const OUT_OF_SCOPE = new Set([INDEX_NAME, 'README.md']);
+
+// CRLF and a leading BOM both break naive line-counting. Normalizing on the
+// way in is the only defense that doesn't depend on remembering it in every
+// regex downstream.
+function normalize(raw) {
+  let t = String(raw).split('\r\n').join('\n').split('\r').join('\n');
+  if (t.charCodeAt(0) === 0xfeff) t = t.slice(1);
+  return t;
+}
+
+// Minimal YAML, on purpose: a `key: value` line at column 0; an indented line
+// is a continuation of the previous key's value and is kept as raw text
+// inside it. The collector never judges deep structure, only whether the
+// block is made of recognizable pairs. A block with no pair at all returns
+// null and becomes 'malformed' upstream.
+function parseSimpleYaml(block) {
+  const lines = block.split('\n');
+  const data = {};
+  let currentKey = null;
+  let hadAnyPair = false;
+  for (const line of lines) {
+    if (line.trim() === '') continue;
+    if (/^\s/.test(line)) {
+      if (currentKey === null) return null; // indentation with no prior key = malformed
+      data[currentKey] += '\n' + line;
+      continue;
+    }
+    const m = line.match(/^([A-Za-z0-9_.-]+):\s?(.*)$/);
+    if (!m) return null;
+    currentKey = m[1];
+    data[currentKey] = m[2];
+    hadAnyPair = true;
+  }
+  return hadAnyPair ? data : null;
+}
+
+// YAML frontmatter between `---`/`---` at the START of the (already
+// normalized) text. Three states, never blended:
+//   'valid'     : opens and closes `---`, and the block parses into pairs
+//   'malformed' : opens `---` but never closes, OR closes but the block
+//                 doesn't parse into any key: value pair
+//   'absent'    : the text doesn't start with a `---` line
+function parseFrontmatter(txt) {
+  const lines = txt.split('\n');
+  if (lines[0] !== '---') {
+    return { state: 'absent', data: null, raw: null, reason: null, body: txt };
+  }
+  let end = -1;
+  for (let i = 1; i < lines.length; i++) {
+    if (lines[i] === '---') { end = i; break; }
+  }
+  if (end === -1) {
+    return {
+      state: 'malformed',
+      data: null,
+      raw: lines.slice(1).join('\n'),
+      reason: 'opens `---` but never closes',
+      body: '',
+    };
+  }
+  const yamlBlock = lines.slice(1, end).join('\n');
+  const body = lines.slice(end + 1).join('\n').replace(/^\n+/, '');
+  const data = parseSimpleYaml(yamlBlock);
+  if (data === null) {
+    return {
+      state: 'malformed',
+      data: null,
+      raw: yamlBlock,
+      reason: 'block between the `---` markers has no key: value pair',
+      body,
+    };
+  }
+  return { state: 'valid', data, raw: yamlBlock, reason: null, body };
+}
+
+// `[[...]]` links from the body, in order of appearance, de-duplicated.
+function extractLinks(body) {
+  const seen = new Set();
+  const links = [];
+  const re = /\[\[([^\]]+)\]\]/g;
+  let m;
+  while ((m = re.exec(String(body)))) {
+    const name = m[1].trim();
+    if (!seen.has(name)) { seen.add(name); links.push(name); }
+  }
+  return links;
+}
+
+// One index line is `- [Title](file.md)` with an optional suffix afterwards
+// (` — note` or ` - note`; both forms show up in real indexes).
+const RE_INDEX_LINE = /^-\s*\[([^\]]*)\]\(([^)]+)\)(.*)$/;
+
+function parseIndex(txt) {
+  const lines = String(txt).split('\n');
+  const entries = [];
+  for (let i = 0; i < lines.length; i++) {
+    const m = lines[i].match(RE_INDEX_LINE);
+    if (!m) continue;
+    entries.push({
+      line: i + 1,
+      title: m[1].trim(),
+      file: m[2].trim(),
+      suffix: m[3].trim(),
+      raw: lines[i],
+    });
+  }
+  return entries;
+}
+
+// Cross-reference file <-> index in BOTH directions, matched by FILE NAME
+// (the link target), never by title — title is free prose and can repeat or
+// drift from the file name.
+//   - filesWithoutLine : file in the archive with no index entry
+//   - orphanLines      : index entry whose file doesn't exist in the archive
+function correlate(fileNames, entries) {
+  const byFile = new Map();
+  for (const e of entries) {
+    if (!byFile.has(e.file)) byFile.set(e.file, []);
+    byFile.get(e.file).push(e);
+  }
+  const fileSet = new Set(fileNames);
+
+  const lineByFile = new Map();
+  const filesWithoutLine = [];
+  for (const name of fileNames) {
+    const es = byFile.get(name);
+    if (es && es.length) lineByFile.set(name, es[0]);
+    else filesWithoutLine.push(name);
+  }
+
+  const orphanLines = entries.filter((e) => !fileSet.has(e.file));
+
+  return { lineByFile, filesWithoutLine, orphanLines };
+}
+
+// Builds the record for ONE file from its raw content — pure, no disk access.
+function buildFile(name, raw) {
+  const txt = normalize(raw);
+  const frontmatter = parseFrontmatter(txt);
+  const links = extractLinks(frontmatter.body);
+  return { name, frontmatter, body: frontmatter.body, links };
+}
+
+// --- I/O: the only place this module touches fs. ---------------------------
+
+function listFiles(dir) {
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir).filter((f) => f.endsWith('.md') && !OUT_OF_SCOPE.has(f)).sort();
+}
+
+// Reads the whole archive: every `.md` file (except the index) plus the
+// index itself, builds each file's record and cross-references both ways.
+function readCollection(dir) {
+  const names = listFiles(dir);
+  const files = names.map((name) =>
+    buildFile(name, fs.readFileSync(path.join(dir, name), 'utf8'))
+  );
+
+  const indexPath = path.join(dir, INDEX_NAME);
+  const indexRead = fs.existsSync(indexPath);
+  const entries = indexRead ? parseIndex(normalize(fs.readFileSync(indexPath, 'utf8'))) : [];
+
+  const { lineByFile, filesWithoutLine, orphanLines } = correlate(names, entries);
+  const withLine = files.map((f) => ({ ...f, indexLine: lineByFile.get(f.name) || null }));
+
+  // `entries` is exposed as `indexEntries` so a detector can judge the index
+  // file's own text (title + suffix note on each line), not just the notes
+  // it points to. The index is the single file every boot reads in full —
+  // treating it as out-of-scope for content detectors (it is legitimately
+  // out of scope for file COUNTS, see `OUT_OF_SCOPE` above) would leave the
+  // most-read file in the archive unjudged.
+  return { dir, indexRead, indexPath, indexEntries: entries, files: withLine, filesWithoutLine, orphanLines };
+}
+
+module.exports = {
+  INDEX_NAME,
+  normalize,
+  parseSimpleYaml,
+  parseFrontmatter,
+  extractLinks,
+  parseIndex,
+  correlate,
+  buildFile,
+  listFiles,
+  readCollection,
+};

package/lib/config.js

@@ -0,0 +1,73 @@
+'use strict';
+// Loads `memory-lint.config.json` from the current working directory (or a
+// path given by `MEMORY_LINT_CONFIG`), merged over the built-in defaults
+// below. There is no hardcoded ceiling copied from any real archive: the
+// defaults are round placeholder numbers, and the README asks the user to
+// measure their own current file and tighten them — that's the whole point
+// of a closed budget (see detectors/budget.js).
+const fs = require('fs');
+const path = require('path');
+
+const DEFAULTS = {
+  budget: {
+    // Ceiling for MEMORY.md itself. Lines/bytes are a PROXY for the token
+    // cost of loading the file at boot, never a conversion — the bytes-per-
+    // token ratio depends on language and drifts as the file changes.
+    // These starting numbers are placeholders. Run the CLI once to see your
+    // actual size, then set these to that size (closed budget: new content
+    // must merge into or replace existing content, not just add to it).
+    lines: 200,
+    bytes: 20000,
+    // Claude Code (observed, as of this writing) loads at most this many
+    // lines of MEMORY.md at boot and warns about the rest. Configurable
+    // because that ceiling is the host application's behavior, not this
+    // tool's, and may change.
+    readerLineLimit: 200,
+    // Below this many lines, warn that the reader limit is close, before it
+    // silently cuts content off.
+    proximityWarning: 190,
+  },
+  provenance: {
+    // Where the line-baseline (see detectors/provenance.js) is stored,
+    // relative to the config file's directory (or CWD if there is none).
+    baselineFile: 'memory-lint.baseline.json',
+  },
+  perishable: {
+    // Only files touched on/after this date are judged (ISO `YYYY-MM-DD`).
+    // `null` means "judge everything" — set this once, to the date you adopt
+    // the convention, so pre-existing files aren't retroactively flagged.
+    cutoffDate: null,
+  },
+  pii: {
+    // `null` means "use the category list this package ships"
+    // (lib/pii-categories.json). Point this at your own file to add, drop,
+    // or re-tune a category — the detector never merges the two lists, so a
+    // custom file replaces the shipped one entirely.
+    categoriesFile: null,
+  },
+};
+
+function deepMerge(base, extra) {
+  if (!extra || typeof extra !== 'object') return base;
+  const out = { ...base };
+  for (const [k, v] of Object.entries(extra)) {
+    out[k] = v && typeof v === 'object' && !Array.isArray(v) && base[k]
+      ? deepMerge(base[k], v)
+      : v;
+  }
+  return out;
+}
+
+function loadConfig(explicitPath) {
+  const file = explicitPath || process.env.MEMORY_LINT_CONFIG ||
+    path.join(process.cwd(), 'memory-lint.config.json');
+  if (!fs.existsSync(file)) return { config: DEFAULTS, file: null };
+  try {
+    const raw = JSON.parse(fs.readFileSync(file, 'utf8'));
+    return { config: deepMerge(DEFAULTS, raw), file };
+  } catch (e) {
+    return { config: DEFAULTS, file, error: e.message };
+  }
+}
+
+module.exports = { DEFAULTS, deepMerge, loadConfig };

package/lib/detectors/budget.js

@@ -0,0 +1,127 @@
+'use strict';
+// CLOSED BUDGET for the memory index file (`MEMORY.md`).
+//
+// What it measures (effect, not intent): the SIZE of the file that loads at
+// every session boot, against a ceiling from config. Closed budget means the
+// ceiling is frozen at "today's size": new content has to merge into or
+// replace existing content, never just add to it. Without this trip-wire the
+// file only grows, one line per closed session, and every session boot pays
+// for it.
+//
+// Unit: LINES and BYTES, both. They're a PROXY for token cost, never a
+// conversion — a bytes-per-token ratio measured in English underestimates
+// non-English text by a wide margin. Anyone who wants the real token number
+// measures it by ablation (diff two boots with/without the file), not by
+// dividing bytes.
+//
+// Exit code: 0 within budget | 1 over budget | 2 archive not found (unchecked)
+const fs = require('fs');
+const path = require('path');
+
+// Reader line limit is checked SEPARATELY from budget growth: budget bounds
+// growth, this bounds visibility. A ceiling configured above the reader's
+// own cutoff can stay "green" while the newest lines silently never reach
+// context (they land at the end of the index, so they're the first thing to
+// vanish).
+function measureText(buf) {
+  const bytes = Buffer.isBuffer(buf) ? buf.length : Buffer.byteLength(String(buf), 'utf8');
+  const raw = Buffer.isBuffer(buf) ? buf.toString('utf8') : String(buf);
+  const txt = raw.split('\r\n').join('\n').split('\r').join('\n').replace(/^/, '');
+  const withoutTrailingBreak = txt.replace(/\n$/, '');
+  return { bytes, lines: withoutTrailingBreak === '' ? 0 : withoutTrailingBreak.split('\n').length };
+}
+
+function measureArchive(dir, indexName = 'MEMORY.md') {
+  const file = path.join(dir, indexName);
+  if (!fs.existsSync(file)) return null;
+  return { file, ...measureText(fs.readFileSync(file)) };
+}
+
+function verdict(measured, budget) {
+  const exceeded = [];
+  if (measured.lines > budget.lines) exceeded.push('lines');
+  if (measured.bytes > budget.bytes) exceeded.push('bytes');
+  return {
+    withinBudget: exceeded.length === 0,
+    exceeded,
+    headroom: { lines: budget.lines - measured.lines, bytes: budget.bytes - measured.bytes },
+  };
+}
+
+// Verdict on the READER LIMIT, separate from the growth verdict: the two
+// call for different fixes —
+//   (a) file over the limit -> prune the archive (the tail lines are
+//       invisible TODAY, in every session);
+//   (b) configured budget over the limit -> lower the budget (raising it
+//       back up would make the gate green over a file the reader still cuts).
+function readerVerdict(measured, budget, limit = budget.readerLineLimit, warnAt = budget.proximityWarning) {
+  const reasons = [];
+  if (measured.lines > limit) {
+    reasons.push(
+      `file has ${measured.lines} lines, above the reader limit (${limit}): ` +
+      `${measured.lines - limit} line(s) at the END of the index never reach context`
+    );
+  }
+  if (budget.lines > limit) {
+    reasons.push(
+      `configured budget (${budget.lines} lines) is above the reader limit (${limit}): ` +
+      `the budget currently allows growing past what the reader loads`
+    );
+  }
+  const cutOff = Math.max(0, measured.lines - limit);
+  return {
+    withinLimit: reasons.length === 0,
+    reasons,
+    cutOff,
+    limit,
+    warnAt,
+    // Proximity is only worth reporting while nothing has failed yet.
+    close: reasons.length === 0 && measured.lines >= warnAt,
+  };
+}
+
+module.exports = { measureText, measureArchive, verdict, readerVerdict };
+
+// --- CLI ---------------------------------------------------------------
+// Usage: node lib/detectors/budget.js [--json]
+// The archive directory comes from `locateArchive()` — the same resolution
+// order (MEMORY_LINT_DIR -> autoMemoryDirectory -> derived default) the other
+// five detectors use. A caller-supplied positional directory used to bypass
+// that order silently; unifying on `locateArchive()` means `--archive <dir>`
+// at the `memory-lint` CLI level (which sets MEMORY_LINT_DIR) now reaches
+// this detector the same way it reaches every other one.
+if (require.main === module) {
+  const { loadConfig } = require('../config');
+  const { locateArchive } = require('../locate-archive');
+  const json = process.argv.includes('--json');
+  const { dir, source } = locateArchive();
+  const { config } = loadConfig();
+  const budget = config.budget;
+  const measured = measureArchive(dir);
+
+  if (!measured) {
+    const msg = `BUDGET: ARCHIVE NOT FOUND - ${path.join(dir, 'MEMORY.md')} does not exist.`;
+    if (json) console.log(JSON.stringify({ dir, source, state: 'absent', measured: null }, null, 2));
+    else console.log(msg);
+    console.error(msg);
+    process.exit(2);
+  }
+
+  const v = verdict(measured, budget);
+  const r = readerVerdict(measured, budget);
+  const out = { dir, source, budget, measured, ...v, reader: r };
+
+  if (json) {
+    console.log(JSON.stringify(out, null, 2));
+  } else {
+    console.log(`archive: ${measured.file}`);
+    console.log(`lines: ${measured.lines} / budget ${budget.lines}   bytes: ${measured.bytes} / budget ${budget.bytes}`);
+    console.log(
+      `\nBUDGET: ${v.withinBudget ? 'within budget' : 'OVER BUDGET'}` +
+      (v.withinBudget ? '' : ` (${v.exceeded.join(' and ')})`)
+    );
+    if (!r.withinLimit) console.log(`READER LIMIT: exceeded - ${r.reasons.join(' | ')}`);
+    else if (r.close) console.log(`WARNING: ${measured.lines} lines, ${r.limit - measured.lines} away from the reader limit.`);
+  }
+  process.exit(v.withinBudget && r.withinLimit ? 0 : 1);
+}

package/lib/detectors/frontmatter.js

@@ -0,0 +1,96 @@
+'use strict';
+// REQUIRED FRONTMATTER detector.
+//
+// What it judges (not collects — see lib/collector.js): every file in the
+// archive has VALID frontmatter, and inside it a non-empty `description`.
+// Without that, a file is invisible to whatever decides which memory to open
+// — the frontmatter state ('valid' | 'malformed' | 'absent') already comes
+// from `parseFrontmatter`/`readCollection`; this module only holds the
+// VERDICT over that fact, the same collector/judge split used by budget.js.
+//
+// Declared scope: this detector fails on MISSING frontmatter/description. It
+// does not judge whether the description is *well written* — that's a
+// content-quality call, not something detectable by shape.
+const fs = require('fs');
+const { readCollection } = require('../collector');
+const { locateArchive } = require('../locate-archive');
+
+// Judges ONE already-collected file. Pure: struct in, verdict out — no I/O,
+// which is what lets the two-sided test attack this function directly.
+function judgeFile(file) {
+  const fm = file.frontmatter;
+  if (fm.state === 'absent') {
+    return { name: file.name, state: 'no_frontmatter', reason: 'file does not start with `---`' };
+  }
+  if (fm.state === 'malformed') {
+    return { name: file.name, state: 'malformed', reason: fm.reason };
+  }
+  const desc = fm.data && typeof fm.data.description === 'string' ? fm.data.description.trim() : '';
+  if (!desc) {
+    return { name: file.name, state: 'no_description', reason: 'valid frontmatter but `description` missing (or empty)' };
+  }
+  return { name: file.name, state: 'ok', reason: null };
+}
+
+function auditFrontmatter(files) {
+  return files.map(judgeFile);
+}
+
+// Summary built from the SAME list the gate reads, never a second parallel
+// count.
+function summarizeFrontmatter(lines) {
+  const noFrontmatter = lines.filter((l) => l.state === 'no_frontmatter');
+  const malformed = lines.filter((l) => l.state === 'malformed');
+  const noDescription = lines.filter((l) => l.state === 'no_description');
+  const ok = lines.filter((l) => l.state === 'ok');
+  return {
+    total: lines.length,
+    ok: ok.length,
+    noFrontmatter: noFrontmatter.length,
+    malformed: malformed.length,
+    noDescription: noDescription.length,
+    failed: noFrontmatter.length + malformed.length + noDescription.length,
+    namesNoFrontmatter: noFrontmatter.map((l) => l.name),
+    namesMalformed: malformed.map((l) => l.name),
+    namesNoDescription: noDescription.map((l) => l.name),
+  };
+}
+
+module.exports = { judgeFile, auditFrontmatter, summarizeFrontmatter };
+
+// --- CLI ---------------------------------------------------------------
+// Usage: node lib/detectors/frontmatter.js [--json]
+// Exit: 0 nothing failed | 1 something failed | 2 archive not found
+if (require.main === module) {
+  const json = process.argv.includes('--json');
+  const { dir, source } = locateArchive();
+
+  if (!fs.existsSync(dir)) {
+    const msg = `FRONTMATTER: ARCHIVE NOT FOUND - ${dir} (path from ${source}).`;
+    if (json) console.log(JSON.stringify({ dir, source, state: 'absent', lines: null }, null, 2));
+    else console.log(msg);
+    console.error(msg);
+    process.exit(2);
+  }
+
+  const r = readCollection(dir);
+  const lines = auditFrontmatter(r.files);
+  const summary = summarizeFrontmatter(lines);
+  const state = summary.failed > 0 ? 'failed' : 'ok';
+
+  if (json) {
+    console.log(JSON.stringify({ dir, source, state, summary, lines }, null, 2));
+  } else {
+    console.log(`archive: ${dir}  (${source})`);
+    console.log(`total: ${summary.total}  ok: ${summary.ok}  no frontmatter: ${summary.noFrontmatter}  malformed: ${summary.malformed}  no description: ${summary.noDescription}`);
+    if (summary.failed) {
+      console.log(`\nFRONTMATTER: ${summary.failed} failed.`);
+      if (summary.namesNoFrontmatter.length) console.log(`  no frontmatter: ${summary.namesNoFrontmatter.join(', ')}`);
+      if (summary.namesMalformed.length) console.log(`  malformed: ${summary.namesMalformed.join(', ')}`);
+      if (summary.namesNoDescription.length) console.log(`  no description: ${summary.namesNoDescription.join(', ')}`);
+    } else {
+      console.log('\nFRONTMATTER: nothing failed.');
+    }
+  }
+  process.exit(summary.failed > 0 ? 1 : 0);
+}