@zyaiting/keelson 0.4.0

package/src/lib/health.js

@@ -0,0 +1,113 @@
+import path from 'node:path';
+import fs from 'node:fs';
+import { exists, read, readOr, listDirs, walk } from './fs.js';
+import { parseRulesIndex } from './rules.js';
+import { parseSpec } from './markdown.js';
+import { loadAllChanges } from './changes.js';
+import { capabilityPhysicalDocs, readCapabilitySpec } from './specs.js';
+
+const lines = (t) => String(t ?? '').split('\n').length;
+export const HARD_BUDGET_MULTIPLIER = 2;
+
+export function budgetStatus(text, budget, { hard = true } = {}) {
+  const count = lines(text);
+  const soft = Number(budget) || 0;
+  const hardLimit = hard && soft ? soft * HARD_BUDGET_MULTIPLIER : null;
+  if (!soft) return { state: 'unbounded', lines: count, budget: null, hardLimit: null };
+  if (hardLimit && count > hardLimit) return { state: 'hard', lines: count, budget: soft, hardLimit };
+  if (count > soft) return { state: 'compact', lines: count, budget: soft, hardLimit };
+  return { state: 'ok', lines: count, budget: soft, hardLimit };
+}
+// Narrative markers: dated change sentences and "we later/then changed" phrasing. Words like "no longer" are legitimate present tense and are not flagged.
+const HISTORY_NARRATIVE = /\b(used to be|was changed to|has been replaced by|we (then|later|subsequently) (moved|switched|changed|replaced)|as of (20\d\d|[A-Z][a-z]+ 20\d\d))\b|\b(20\d\d)[-/](0?[1-9]|1[0-2])\b[^\n]*\b(changed|moved|switched|replaced)\b/i;
+const ORDINAL_UPDATE = /^#{2,4}\s+(update|changelog|history|migration notes)\b/im;
+
+/**
+ * Knowledge-health findings for a project. Pure over the file system; never edits.
+ * Each finding: { level: 'error'|'warn'|'info', kind, text, fix }.
+ * Durable truth has a hard ceiling at 2x its soft budget; temporary change/handoff
+ * artifacts only receive compaction warnings because they disappear after landing.
+ */
+export function knowledgeHealth(root, cfg, p) {
+  const out = [];
+  const b = cfg.budgets ?? {};
+  const over = (label, file, budget, { kind = 'budget', hard = true } = {}) => {
+    if (!exists(file) || !budget) return;
+    const pressure = budgetStatus(read(file), budget, { hard });
+    if (pressure.state === 'hard') {
+      out.push({ level: 'error', kind: 'budget-hard', text: `${label} is ${pressure.lines} lines (hard limit ${pressure.hardLimit}, budget ${pressure.budget})`, fix: 'compact before adding more durable truth: rewrite current state, split by capability/scope, delete history kept by git, and automate checkable rules' });
+    } else if (pressure.state === 'compact') {
+      out.push({ level: 'warn', kind, text: `${label} is ${pressure.lines} lines (budget ${pressure.budget})`, fix: 'compact: rewrite the current truth, split by capability or scope, delete history that git already keeps, move automatable rules into checks' });
+    }
+  };
+  over('INTENT.md', p.intent, b.INTENT);
+  over('ROADMAP.md', p.roadmap, b.ROADMAP);
+  over('NOW.md', p.now, b.NOW);
+  over('GLOSSARY.md', p.glossary, b.GLOSSARY);
+
+  // always-on rules budget
+  const idx = parseRulesIndex(readOr(p.rulesIndex));
+  let alwaysOn = 0;
+  for (const e of idx) if (e.glob === '**' || e.glob === '*') alwaysOn += lines(readOr(path.join(p.rules, e.file)));
+  if (b['always-on']) {
+    const pressure = budgetStatus('\n'.repeat(Math.max(0, alwaysOn - 1)), b['always-on']);
+    if (pressure.state === 'hard') out.push({ level: 'error', kind: 'budget-hard', text: `always-on rules total ${alwaysOn} lines (hard limit ${pressure.hardLimit}, budget ${pressure.budget}); every session pays for them`, fix: 'scope rules to paths, split broad rules, or move checkable invariants into `check:` before adding more always-on prose' });
+    else if (pressure.state === 'compact') out.push({ level: 'warn', kind: 'budget', text: `always-on rules total ${alwaysOn} lines (budget ${pressure.budget}); every session pays for them`, fix: 'scope rules to paths, or move checkable rules into `check:`' });
+  }
+  for (const e of idx) over(`rules/${e.file}`, path.join(p.rules, e.file), b.rule);
+
+  // specs: budget, history narrative, duplicates across capabilities
+  const reqIndex = new Map();
+  for (const cap of listDirs(p.specs)) {
+    const f = path.join(p.specs, cap, 'spec.md');
+    if (!exists(f)) continue;
+    for (const doc of capabilityPhysicalDocs(p.specs, cap)) {
+      over(`${p.specsRel}/${cap}/${doc.rel}`, doc.file, b.spec);
+    }
+    const txt = readCapabilitySpec(p.specs, cap);
+    const parsed = parseSpec(txt);
+    const bodies = parsed.requirements.map((r) => r.body).join('\n');
+    if (HISTORY_NARRATIVE.test(bodies) || ORDINAL_UPDATE.test(txt)) out.push({ level: 'warn', kind: 'narrative', text: `${p.specsRel}/${cap} reads like history in places`, fix: 'current truth is present tense; reasons go to Decisions, the sequence of changes stays in git' });
+    for (const r of parsed.requirements) {
+      const key = r.name.toLowerCase();
+      if (reqIndex.has(key)) out.push({ level: 'warn', kind: 'duplicate', text: `requirement "${r.name}" appears in both ${reqIndex.get(key)} and ${cap}`, fix: 'one capability owns a requirement; the other links to it' });
+      else reqIndex.set(key, cap);
+    }
+  }
+
+  // changes: budget, idle, oversized
+  const now = Date.now();
+  for (const c of loadAllChanges(p.changes)) {
+    over(`changes/${c.name}/change.md`, path.join(c.dir, 'change.md'), b.change, { hard: false });
+    if (exists(path.join(c.dir, 'handoff.md'))) over(`changes/${c.name}/handoff.md`, path.join(c.dir, 'handoff.md'), b.handoff, { hard: false });
+    if (c.tasks.length > 25) out.push({ level: 'warn', kind: 'oversized', text: `changes/${c.name} has ${c.tasks.length} tasks`, fix: 'split into changes that can be accepted on their own; `depends:` links them' });
+    const stamp = fs.statSync(path.join(c.dir, 'change.md')).mtimeMs;
+    const newest = Math.max(stamp, ...['tasks.md', 'ledger.md', 'handoff.md'].map((f) => (exists(path.join(c.dir, f)) ? fs.statSync(path.join(c.dir, f)).mtimeMs : 0)));
+    const days = Math.floor((now - newest) / 86400000);
+    if (days >= 14) out.push({ level: 'warn', kind: 'idle', text: `changes/${c.name} has not been touched for ${days} days (work: ${c.work})`, fix: 'finish it, `keelson handoff` it with a next step, or `keelson cancel` it with a reason' });
+  }
+
+  // generated docs older than the code they describe
+  const gen = path.join(root, 'docs', 'generated');
+  if (exists(gen)) {
+    const srcNewest = newestMtime(path.join(root, 'src')) ?? newestMtime(root);
+    for (const f of walk(gen)) {
+      const m = fs.statSync(path.join(gen, f)).mtimeMs;
+      if (srcNewest && m + 86400000 < srcNewest) out.push({ level: 'info', kind: 'stale-generated', text: `docs/generated/${f} is older than the source tree`, fix: 'regenerate it from the code, or delete it if nothing reads it' });
+    }
+  }
+
+  // refs pointing at missing files are caught by validate; here: specs that name no scenario are caught by validate too.
+  return out;
+}
+
+function newestMtime(dir) {
+  if (!exists(dir)) return null;
+  let m = 0;
+  for (const f of walk(dir, { ignore: ['node_modules', '.git', '.keelson', 'dist', 'build', 'docs'] })) {
+    try {
+      m = Math.max(m, fs.statSync(path.join(dir, f)).mtimeMs);
+    } catch {}
+  }
+  return m || null;
+}

package/src/lib/lifecycle.js

@@ -0,0 +1,120 @@
+/**
+ * One lifecycle engine for status, context, check, doctor, and land.
+ *
+ * Work lifecycle is derived from durable outcome gates and fresh evidence.
+ * Session focus and tasks.md are advisory runtime/planning state only.
+ */
+
+export function verificationStatus(change, fingerprint) {
+  const v = change.evidence;
+  if (!v) return { state: 'not-run', detail: 'no structured evidence; run `keelson check --record`' };
+  if (v.state !== 'passed') return { state: v.state, detail: v.detail };
+  if (!fingerprint || v.tree !== fingerprint) {
+    return { state: 'stale', detail: `verified at tree ${v.tree}, worktree is ${fingerprint}` };
+  }
+  return { state: 'passed', detail: v.detail };
+}
+
+const gate = (code, pass, detail) => ({ code, pass, detail });
+
+/**
+ * Evaluate the durable work lifecycle without touching the filesystem.
+ *
+ * activeNames: names of other active changes, used to enforce depends:.
+ * confirmAssumptions: land-only owner confirmation; status/check leave this false.
+ */
+export function evaluateLifecycle(change, fingerprint, {
+  activeNames = [],
+  confirmAssumptions = false,
+  contractDrift = [],
+  acceptDrift = false,
+} = {}) {
+  const active = activeNames instanceof Set ? activeNames : new Set(activeNames);
+  const verification = verificationStatus(change, fingerprint);
+  const blockedBy = change.depends.filter((name) => active.has(name) && name !== change.name);
+  const acceptanceComplete = change.acceptance.length
+    ? change.acceptanceProgress.done === change.acceptanceProgress.total
+    : change.tier === 'quick';
+  const contractComplete = change.tier === 'quick' || change.acceptance.length > 0;
+  const rolloutReady = !change.breaking || change.hasRollout;
+
+  const pendingDecisions = (change.decisionRecords ?? []).filter((d) => d.state === 'open' || d.state === 'assumed');
+  const gates = [
+    gate('decisions', pendingDecisions.length === 0, `${pendingDecisions.length} unresolved decision(s): ${pendingDecisions.map((d) => d.id).join(', ')}; use keelson ask frontier`),
+    gate(
+      'contract',
+      contractComplete,
+      'spec tier without an "## Acceptance" list'
+    ),
+    gate(
+      'acceptance',
+      acceptanceComplete,
+      `${Math.max(0, change.acceptance.length - change.acceptanceProgress.done)} acceptance item(s) unchecked`
+    ),
+    gate(
+      'questions',
+      change.open.length === 0,
+      `${change.open.length} open question(s): ${change.open.map((o) => o.text).join('; ')}`
+    ),
+    gate(
+      'dependencies',
+      blockedBy.length === 0,
+      `depends on active change(s): ${blockedBy.join(', ')}`
+    ),
+    gate(
+      'drift',
+      acceptDrift || contractDrift.length === 0,
+      contractDrift.map((d) => d.detail ?? String(d)).join('; ')
+    ),
+    gate(
+      'assumptions',
+      change.assumed.length === 0 || confirmAssumptions,
+      `${change.assumed.length} assumed decision(s) would be folded as confirmed; pass --confirm-assumptions once the owner agrees`
+    ),
+    gate(
+      'rollout',
+      rolloutReady,
+      'change is marked **BREAKING** but has no "## Rollout" section (compatibility, migration, rollback)'
+    ),
+    gate(
+      'verification',
+      verification.state === 'passed',
+      `verification ${verification.state} (${verification.detail})`
+    ),
+  ];
+
+  if (change.storedWork === 'blocked') {
+    gates.unshift(gate('explicit-block', false, 'change status is blocked'));
+  }
+
+  // A missing acceptance list on a quick change is intentionally allowed; do not
+  // emit a synthetic "0 acceptance unchecked" blocker.
+  const blockers = gates
+    .filter((g) => !g.pass)
+    .filter((g) => !(g.code === 'acceptance' && !change.acceptance.length));
+
+  const explicit = change.storedWork;
+  let work;
+  if (['integrated', 'cancelled'].includes(explicit)) work = explicit;
+  else if (explicit === 'blocked') work = 'blocked';
+  else if (blockers.length === 0) work = 'ready';
+  else if (explicit === 'clarifying' && change.progress.done === 0 && verification.state === 'not-run') work = 'clarifying';
+  else work = 'in-progress';
+
+  const uncheckedTasks = change.progress.total
+    ? Math.max(0, change.progress.total - change.progress.done)
+    : 0;
+  const warnings = uncheckedTasks
+    ? [`${uncheckedTasks} task(s) remain unchecked; tasks are planning notes, not lifecycle gates`]
+    : [];
+
+  return {
+    work,
+    verification,
+    gates,
+    blockers: blockers.map((g) => g.detail),
+    blockedBy,
+    contractDrift,
+    warnings,
+  };
+}

package/src/lib/maintenance.js

@@ -0,0 +1,66 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { exists, listFiles, rmrf, walk } from './fs.js';
+import { runtimeDir } from './runtime-path.js';
+
+const DAY = 24 * 60 * 60 * 1000;
+
+function safeMtime(file) {
+  try {
+    return fs.statSync(file).mtimeMs;
+  } catch {
+    return 0;
+  }
+}
+
+/**
+ * Runtime state is a cache, not durable project truth. Prune it opportunistically
+ * from normal Keelson commands so users never need a maintenance command.
+ */
+export function maintainRuntime(root, {
+  now = Date.now(),
+  sessionMaxAgeDays = 30,
+  evidenceMaxAgeDays = 14,
+  maxEvidenceFiles = 200,
+} = {}) {
+  const runtime = runtimeDir(root);
+  const sessions = path.join(runtime, 'sessions');
+  const evidence = path.join(runtime, 'evidence');
+  const result = { sessionsRemoved: 0, evidenceRemoved: 0 };
+
+  if (exists(sessions)) {
+    const cutoff = now - sessionMaxAgeDays * DAY;
+    for (const name of listFiles(sessions)) {
+      const file = path.join(sessions, name);
+      if (safeMtime(file) && safeMtime(file) < cutoff) {
+        rmrf(file);
+        result.sessionsRemoved += 1;
+      }
+    }
+  }
+
+  if (exists(evidence)) {
+    const cutoff = now - evidenceMaxAgeDays * DAY;
+    const files = walk(evidence).map((rel) => ({
+      rel,
+      file: path.join(evidence, rel),
+      mtime: safeMtime(path.join(evidence, rel)),
+    }));
+
+    for (const item of files) {
+      if (item.mtime && item.mtime < cutoff) {
+        rmrf(item.file);
+        item.removed = true;
+        result.evidenceRemoved += 1;
+      }
+    }
+
+    const remaining = files.filter((x) => !x.removed).sort((a, b) => b.mtime - a.mtime);
+    for (const item of remaining.slice(maxEvidenceFiles)) {
+      rmrf(item.file);
+      result.evidenceRemoved += 1;
+    }
+  }
+
+  return result;
+}