ratchet agent 规则遵循检查器

 24function emptySession(sessionId, mode, root) {
 25  return {
 26    sessionId: sessionId || 'default',
 27    mode,
 28    root: root || '',
 29    startedAt: Date.now(),
 30    addedLines: 0,
 31    removedLines: 0,
 32    newFiles: [],
 33    touchedFiles: [],
 34    deps: [],
 35    findings: [],
 36    reported: [],
 37  };
 38}

 84async function main() {
 85  const payload = await readStdin();
 86  if (!EDIT_TOOLS.has(payload.tool_name)) return;
 87  if (payload.tool_response && payload.tool_response.error) return;
 88
 89  const root = repoRoot(payload.cwd || process.cwd());
 90  useRoot(root);
 91  const stored = readSession(payload.session_id);
 92  const mode = (stored && normalizeMode(stored.mode)) || resolveMode(root);
 93  if (mode === 'off') return;
 94
 95  const budget = resolveBudget(mode, root);
 96  const session = stored || emptySession(payload.session_id, mode, root);
 97  session.mode = mode;
 98  session.removedLines = session.removedLines || 0;
 99
100  const changes = changesFrom(payload, root);
101  if (!changes.length) return;
102
103  const context = {
104    root,
105    symbols: buildIndex(root),
106    countImplementations: (name) => countImplementations(root, name),
107  };
108  const accepted = baseline.read(root);
109  const fresh = [];
110
111  for (const change of changes) {
112    const relative = relativePosix(root, change.path);
113    if (relative.startsWith('..') || isTestPath(relative)) continue;
114    if (isNewFile(root, change.path, session)) session.newFiles.push(relative);
115    if (!session.touchedFiles.includes(relative)) session.touchedFiles.push(relative);
116
117    const result = inspect(change, context);
118    session.addedLines += result.added.length;
119    session.removedLines += result.removed.length;
120
121    const surviving = baseline.filter(result.findings, accepted, () => relative);
122    for (const finding of surviving) {
123      if (finding.dep && !session.deps.includes(finding.dep)) session.deps.push(finding.dep);
124      const key = fingerprint(finding, relative);
125      if (session.reported.includes(key)) continue;
126      session.reported.push(key);
127      finding.path = relative;
128      session.findings.push(finding);
129      fresh.push(finding);
130    }
131  }
132
133  const overruns = budget.enforce === 'silent' ? [] : budgetFindings(session, budget);
134  writeSession(session);
135
136  const shown = [...fresh, ...overruns].slice(0, MAX_REPORTED);
137  if (!shown.length) return;
138
139  const hidden = fresh.length + overruns.length - shown.length;
140  const body =
141    headline(session, budget, mode) +
142    '\n\n' +
143    alignedFindings(shown) +
144    (hidden > 0 ? '\n\n' + hidden + ' more not shown' : '');
145
146  const blocking =
147    budget.enforce === 'block' &&
148    (overruns.length > 0 || fresh.some((finding) => finding.confidence === CERTAIN));
149
150  if (blocking) {
151    block('PostToolUse', body + '\n\nStrict mode. Revert or shrink this change, or ask the user to raise the budget.');
152    return;
153  }
154
155  emit(
156    'PostToolUse',
157    body + '\n\nFix what applies, then continue. Wrong call? say so, or mark the line with: ratchet-ignore: reason'
158  );

279function inspect(change, context = {}) {
280  const added = addedLines(change.before, change.after);
281  const removed = addedLines(change.after, change.before);
282  if (!added.length && !isManifest(change.path)) return { added: [], removed, findings: [] };
283
284  const suppressed = suppressedLines(change.after);
285  const findings = [
286    ...scanManifest(change),
287    ...scanPatterns(change, added),
288    ...scanWrappers(change, added),
289    ...scanAbstractions(change, added, context),
290    ...scanDuplicates(change, added, context),
291  ].filter((finding) => !suppressed.has(finding.line));
292
293  const unique = new Map();
294  for (const finding of findings) {
295    const key = finding.tag + '|' + finding.what;
296    const previous = unique.get(key);
297    if (!previous || RANK[finding.confidence] < RANK[previous.confidence]) unique.set(key, finding);
298  }
299
300  const ordered = [...unique.values()].sort(
301    (a, b) => RANK[a.confidence] - RANK[b.confidence] || a.line - b.line
302  );
303  return { added, removed, findings: ordered };
304}
305
306function budgetFindings(session, budget) {
307  if (!budget) return [];
308  const findings = [];
309  const net = session.addedLines - (session.removedLines || 0);
310
311  if (session.newFiles.length > budget.newFiles) {
312    findings.push({
313      tag: 'budget', confidence: CERTAIN, path: '', line: 0,
314      what: session.newFiles.length + ' new files, budget is ' + budget.newFiles,
315      fix: 'fold the extras into files that already exist',
316    });
317  }
318  if (session.deps.length > budget.newDeps) {
319    findings.push({
320      tag: 'budget', confidence: CERTAIN, path: '', line: 0,
321      what: session.deps.length + ' new dependencies, budget is ' + budget.newDeps,
322      fix: 'drop ' + session.deps.slice(budget.newDeps).join(', '),
323    });
324  }
325  if (net > budget.addedLines) {
326    findings.push({
327      tag: 'budget', confidence: CERTAIN, path: '', line: 0,
328      what: net + ' net added lines, budget is ' + budget.addedLines,
329      fix: 'stop adding and start deleting, or raise the budget explicitly',
330    });
331  }
332  return findings;
333}
334
335function format(finding) {
336  const where = finding.path ? finding.path + ':' + finding.line + ' ' : '';
337  return where + finding.tag + ': ' + finding.what + '. ' + finding.fix + '.';
338}
339
340module.exports = {
341  CERTAIN, HEURISTIC, LIKELY, PATTERNS, RANK,
342  budgetFindings, fingerprint, format, inspect, splitLines, suppressedLines,
343};

586function doctor() {
587  const root = projectRoot();
588  let failed = false;
589
590  say(heading('environment'));
591  say('');
592  const major = Number(process.versions.node.split('.')[0]);
593  line('node', process.versions.node, major >= 20 ? 'good' : 'bad');
594  if (major < 20) failed = true;
595  const hasGit = which('git');
596  line('git', hasGit ? 'found' : 'missing, the measurement half will not run', hasGit ? 'good' : 'warn');
597
598  const projectSettings = path.join(root, '.claude', 'settings.json');
599  const globalSettings = path.join(claudeDir(), 'settings.json');
600  const installedHere = (readJsonStrict(projectSettings, null) || {}).hooks;
601  const installedGlobally = (readJsonStrict(globalSettings, null) || {}).hooks;
602  const scope = JSON.stringify(installedHere || {}).includes('ratchet-')
603    ? 'project  ' + projectSettings
604    : JSON.stringify(installedGlobally || {}).includes('ratchet-')
605      ? 'global  ' + globalSettings
606      : '';
607  line('install', scope || 'not installed here, run: ratchet', scope ? 'good' : 'warn');
608
609  say('');
610  say(heading('the loop, driven with real payloads'));
611  say('');
612
613  const scratch = fs.mkdtempSync(path.join(os.tmpdir(), 'ratchet-doctor-'));
614  const home = path.join(scratch, 'home');
615  const env = { CLAUDE_CONFIG_DIR: home, RATCHET_MODE: 'guard' };
616
617  try {
618    fs.mkdirSync(path.join(scratch, 'src'), { recursive: true });
619    fs.mkdirSync(path.join(scratch, '.ratchet'), { recursive: true });
620    fs.writeFileSync(path.join(scratch, 'package.json'), '{"name":"scratch","dependencies":{}}');
621    fs.writeFileSync(
622      path.join(scratch, 'src', 'time.js'),
623      'export function formatDuration(ms) {\n  return ms + "ms";\n}\n'
624    );
625
626    if (hasGit) {
627      const git = (...args) => execFileSync('git', args, { cwd: scratch, stdio: 'ignore' });
628      git('init', '-q');
629      git('config', 'user.email', 'doctor@ratchet');
630      git('config', 'user.name', 'doctor');
631      git('add', '-A');
632      git('commit', '-qm', 'init');
633    }
634
635    const session = driveHook('ratchet-session.js', { session_id: 'doctor', cwd: scratch, source: 'startup' }, env);
636    const ruleset = session.includes('RATCHET ACTIVE') && session.includes('first rung');
637    line('session hook', ruleset ? 'injected the ruleset and the budget' : 'no ruleset came back', ruleset ? 'good' : 'bad');
638    if (!ruleset) failed = true;
639
640    const planted = [
641      "import moment from 'moment';",
642      '',
643      'export function format_duration(ms) {',
644      "  return ms + 'ms';",
645      '}',
646      '',
647      'const snapshot = JSON.parse(JSON.stringify(state));',
648      '',
649    ].join('\n');
650    fs.writeFileSync(path.join(scratch, 'src', 'report.js'), planted);
651
652    const guard = driveHook('ratchet-guard.js', {
653      session_id: 'doctor',
654      cwd: scratch,
655      tool_name: 'Write',
656      tool_input: { file_path: path.join(scratch, 'src', 'report.js'), content: planted },
657    }, env);
658    const tags = ['dep', 'native', 'exists'].filter((tag) => guard.includes(tag + ' '));
659    line('guard hook', tags.length ? 'caught ' + tags.join(', ') + ' in a planted file' : 'caught nothing', tags.length >= 2 ? 'good' : 'bad');
660    if (tags.length < 2) failed = true;
661
662    const report = driveHook('ratchet-report.js', { session_id: 'doctor', cwd: scratch }, env);
663    const ledger = fs.existsSync(path.join(scratch, '.ratchet', 'ledger.jsonl'));
664    line('report hook', report.includes('ratchet guard session') ? (ledger ? 'summarised and wrote a ledger row' : 'summarised, no ledger') : 'silent', report ? 'good' : 'bad');