config-audit/scanners/optimize-lens-cli.mjs

#!/usr/bin/env node

/**
 * optimize-lens CLI — feeds the v5.7 optimization lens (CA-OPT) `/config-audit
 * optimize` command. It produces the two halves of the hybrid motor as one JSON
 * payload:
 *
 *   1. `deterministic` — the OPT scanner's high-precision findings (CA-OPT-001:
 *      a long numbered procedure in CLAUDE.md → skill). Already part of the
 *      orchestrated audit; surfaced here so /optimize is a complete view.
 *   2. `candidates` — recall-oriented prose-judgment candidates from the
 *      lens-prefilter (lifecycle → hook, unscoped path-specific → rule, "never"
 *      → permission), each stamped with the CONFIRMED register entry it might fit
 *      (claim / recommendation / source / severity). The opus
 *      optimization-lens-agent is the precision gate over these.
 *
 * Only CONFIRMED register entries are attached (Verifiseringsplikt); a candidate
 * whose register rule is missing or unconfirmed is dropped, so the agent never
 * sees an unverifiable recommendation.
 *
 * Usage:
 *   node optimize-lens-cli.mjs [path] [--output-file <path>] [--global]
 *                              [--subtract [--for-model <name>]]
 *
 * `--for-model <name>` annotates the subtraction candidates a named model
 * documents as redundant (BP-PROMPT-001). It never widens the candidate set,
 * and there is deliberately no auto-detection: a CLAUDE.md has no frontmatter
 * and no statically-resolvable target model, so the model must be named.
 *
 * Exit codes: 0=ok, 3=unrecoverable error. Zero external dependencies.
 */

import { resolve, sep } from 'node:path';
import { readFile, stat } from 'node:fs/promises';
import { writeOutputFile } from './lib/write-output.mjs';
import { discoverConfigFiles } from './lib/file-discovery.mjs';
import { parseFrontmatter } from './lib/yaml-parser.mjs';
import { loadRegister, getEntry } from './lib/best-practices-register.mjs';
import { prefilterClaudeMd, LENS_DETECTORS } from './lib/lens-prefilter.mjs';
import { subtractionCandidates, SUBTRACT_DETECTORS } from './lib/subtraction-prefilter.mjs';
import { matchModelScope, normalizeModel } from './lib/prompting-model-scope.mjs';
import { scan as optScan } from './optimization-lens-scanner.mjs';
import { requireValidArgs } from './lib/cli-args.mjs';

/** Flag surface, measured 2026-08-09. Anything else is exit 3. */
const ARG_SPEC = {
  boolean: ['--global', '--subtract'],
  // `--for-model` is a VALUE flag, so a bare `--for-model` is reported as
  // "needs a value" rather than "unknown flag" — the two are different failures
  // and reporting the wrong one hides which mistake the caller made.
  value: ['--output-file', '--for-model'],
};

// Files under `.claude/plugins/` are shipped by an installed plugin — vendored
// CLAUDE.md plus its bundled tests/fixtures and examples. They are not the user's
// authored config, so a mechanism-fit suggestion against them is not actionable
// (the user can't edit a file the plugin overwrites on update). Excluded from the
// lens regardless of active/stale version. (M-BUG-11; mirrors the M-BUG-2 rule
// that keeps plugin-bundled config out of the conflict detector.)
const PLUGIN_TREE_MARKER = `.claude${sep}plugins${sep}`;
const isPluginBundled = (file) => (file.absPath || '').includes(PLUGIN_TREE_MARKER);

/** Confirmed register entry for `id`, or null. */
function confirmedEntry(register, id) {
  const e = getEntry(register, id);
  return e && e.confidence === 'confirmed' ? e : null;
}

async function main() {
  const args = process.argv.slice(2);
  if (!requireValidArgs(args, ARG_SPEC)) return;
  let targetPath = '.';
  let outputFile = null;
  let includeGlobal = false;
  let subtract = false;
  let targetModel = null;

  for (let i = 0; i < args.length; i++) {
    if (args[i] === '--global') includeGlobal = true;
    else if (args[i] === '--subtract') subtract = true;
    else if (args[i] === '--output-file' && args[i + 1]) outputFile = args[++i];
    else if (args[i] === '--for-model' && args[i + 1]) targetModel = args[++i];
    else if (!args[i].startsWith('-')) targetPath = args[i];
  }

  const absPath = resolve(targetPath);
  try {
    const s = await stat(absPath);
    if (!s.isDirectory()) {
      process.stderr.write(`Error: ${absPath} is not a directory\n`);
      process.exitCode = 3;
      return;
    }
  } catch {
    process.stderr.write(`Error: path does not exist: ${absPath}\n`);
    process.exitCode = 3;
    return;
  }

  // Load the register once; tolerate its absence (deterministic half still runs).
  let register = null;
  try {
    register = loadRegister();
  } catch {
    register = null;
  }

  const rawDiscovery = await discoverConfigFiles(absPath, { includeGlobal });
  // Scope the lens to the user's authored config: drop plugin-bundled files for
  // BOTH halves of the motor (the OPT scanner reads discovery.files directly).
  const discovery = {
    ...rawDiscovery,
    files: (rawDiscovery.files || []).filter((f) => !isPluginBundled(f)),
  };

  // ── Deterministic half: the OPT scanner (CA-OPT-001) ──
  const opt = await optScan(absPath, discovery);

  // ── Recall half: prose-judgment candidates from the pre-filter ──
  const claudeMdFiles = (discovery.files || []).filter((f) => f.type === 'claude-md');
  const candidates = [];
  // Opt-in only: the subtraction axis asks a different question and must not
  // fire on a plain `/config-audit optimize` run (brief §7 q3).
  const subtractCands = [];
  const subtractEntry = subtract && register ? confirmedEntry(register, 'BP-SUB-001') : null;
  // Model-scoped annotation entries (BP-PROMPT-001 and any later sibling). These
  // never produce candidates of their own — they only tag candidates the
  // BP-SUB-001 detector above already surfaced.
  const promptEntries =
    subtract && register
      ? (register.entries || []).filter(
          (e) => e.category === 'prompting-fit' && e.confidence === 'confirmed',
        )
      : [];
  // `recognized` is reported separately from the match count so a typo'd model
  // name is distinguishable from a config that genuinely carries nothing.
  const modelRecognized =
    !!targetModel &&
    promptEntries.some((e) =>
      (e.modelScope || []).some((m) => normalizeModel(m) === normalizeModel(targetModel)),
    );
  let modelMatchedCount = 0;

  for (const file of claudeMdFiles) {
    let content;
    try {
      content = await readFile(file.absPath, 'utf-8');
    } catch {
      continue;
    }
    const parsed = parseFrontmatter(content);
    const body = parsed.body || content;
    const bodyStartLine = parsed.bodyStartLine || 1;

    if (subtractEntry) {
      for (const cand of subtractionCandidates(body)) {
        const modelScope = matchModelScope(cand.text, targetModel, promptEntries);
        if (modelScope) modelMatchedCount++;
        subtractCands.push({
          file: file.absPath,
          line: bodyStartLine - 1 + cand.startLine,
          endLine: bodyStartLine - 1 + cand.endLine,
          lineCount: cand.lineCount,
          lensCheck: cand.lensCheck,
          mechanism: cand.mechanism,
          signalText: cand.text,
          register: {
            id: subtractEntry.id,
            claim: subtractEntry.claim,
            recommendation: subtractEntry.recommendation || null,
            severity: subtractEntry.severity || 'low',
            source: subtractEntry.source,
          },
          // Spread only when matched: a run without --for-model must not grow
          // even a key set to undefined.
          ...(modelScope ? { modelScope } : {}),
        });
      }
    }

    for (const cand of prefilterClaudeMd(body)) {
      const entry = register ? confirmedEntry(register, cand.registerId) : null;
      if (!entry) continue; // never surface an unverifiable recommendation
      candidates.push({
        // Absolute path: unique + readable. relPath collides across scopes
        // (a repo-root `CLAUDE.md` and the user-global `~/.claude/CLAUDE.md`
        // both relPath to `CLAUDE.md`), which would send the agent's Read() to
        // the wrong file. (M-BUG-11)
        file: file.absPath,
        line: bodyStartLine - 1 + cand.line,
        lensCheck: cand.lensCheck,
        mechanism: cand.mechanism,
        signalText: cand.text,
        register: {
          id: entry.id,
          claim: entry.claim,
          recommendation: entry.recommendation || null,
          severity: entry.severity || 'low',
          source: entry.source,
        },
      });
    }
  }

  // The CONFIRMED prose-judgment entries, so the agent has full provenance even
  // for a detector class that produced no candidates this run.
  const registerEntries = register
    ? LENS_DETECTORS.map((d) => confirmedEntry(register, d.registerId))
        .filter(Boolean)
        .map((e) => ({
          id: e.id,
          lensCheck: e.lensCheck,
          claim: e.claim,
          recommendation: e.recommendation || null,
          mechanism: e.mechanism || null,
          severity: e.severity || 'low',
          source: e.source,
        }))
    : [];

  const payload = {
    status: 'ok',
    target: absPath,
    deterministic: opt.findings || [],
    candidates,
    register: registerEntries,
    counts: {
      deterministic: (opt.findings || []).length,
      candidates: candidates.length,
      byLensCheck: candidates.reduce((acc, c) => {
        acc[c.lensCheck] = (acc[c.lensCheck] || 0) + 1;
        return acc;
      }, {}),
    },
  };

  // Additive ONLY under --subtract: a plain run's payload must stay byte-identical.
  if (subtract) {
    payload.subtract = {
      enabled: true,
      candidates: subtractCands,
      register: subtractEntry
        ? [
            {
              id: subtractEntry.id,
              lensCheck: subtractEntry.lensCheck,
              claim: subtractEntry.claim,
              recommendation: subtractEntry.recommendation || null,
              mechanism: subtractEntry.mechanism || null,
              severity: subtractEntry.severity || 'low',
              source: subtractEntry.source,
            },
          ]
        : [],
      detectors: SUBTRACT_DETECTORS.map((d) => ({ ...d })),
    };
    // Present ONLY when a model was named — a plain --subtract run stays
    // byte-identical to the pre-flag payload.
    if (targetModel) {
      payload.subtract.forModel = {
        requested: targetModel,
        recognized: modelRecognized,
        matchedCount: modelMatchedCount,
      };
    }
    payload.counts.subtractCandidates = subtractCands.length;
  }

  const json = JSON.stringify(payload, null, 2);
  if (outputFile) {
    await writeOutputFile(outputFile, json, 'utf-8');
  }
  if (!outputFile) {
    process.stdout.write(json + '\n');
  }
}

const isDirectRun = process.argv[1] && resolve(process.argv[1]) === resolve(new URL(import.meta.url).pathname);
if (isDirectRun) {
  main().catch((err) => {
    process.stderr.write(`Fatal: ${err.message}\n`);
    process.exitCode = 3;
  });
}