codeburn/tests/optimize-apply.test.ts
Resham Joshi 5c162600e8
fix(optimize): stop archiving used commands, match MCP servers the way Claude Code names them, count each saving once (#1898)
* fix(optimize): count slash commands named with their leading slash as used

A slash command shows up in the transcript as <command-name>/review</command-name>.
commandNames kept the slash, so "/review" never matched the defined command
"review": every command the user actually ran was reported unused and the apply
plan archived it. The leading slash is now stripped.

commandNames produces stored facts, so FACTS_VERSION goes to 2 and the
optimize facts store rebuilds once on the next run.

* fix(optimize): name MCP servers the way Claude Code namespaces their tools

Claude Code turns every character outside letters, digits, "_" and "-" into
"_" when it builds tool names, so a server "docs.local" is called as
mcp__docs_local__*. Config names were only mapped ":" -> "_", so such a server
was reported as never called and offered for removal, counted twice by the
deferral check, and shown with 0 calls by the alwaysLoad check. One helper,
mcpNamespace, now applies the full rule in the config loader, the local server
names and the remove plan's key lookup.

* fix(optimize): charge a never-called MCP server's schema once

A configured server that was never called is in unused-mcp, and the same
schema was charged again by mcp-deferral-off (unpinned) or
mcp-alwaysload-hygiene (pinned), so potential savings and the share of spend
summed it twice. The servers unused-mcp reports are now passed to both checks
and left out there.

* fix(act): recommend a default model only for Claude Code projects

The model-default plan writes "model" into <project>/.claude/settings.json,
which only Claude Code reads. A Codex project got a gpt model recommended and
apply-model wrote it there, so Claude Code in that project started on a model
it does not know. recommendModelDefault now returns nothing for a non-Claude
provider.

* fix(optimize): read the bash output cap from the settings env block first

Claude Code takes BASH_MAX_OUTPUT_LENGTH from the env block of its settings
files. The check only read shell profiles (lines with export) and the process
env, so a cap of 10000 set in settings.json still reported the 30K default and
the apply plan appended an export to ~/.zshrc that the settings value
overrides. The check now uses the same lookup as the deferral checks: settings
env from the most specific scope, then shell profiles.

* fix(act): plan each optimize fix right before applying it

optimize --apply built every plan up front, each carrying the hash of the
config file as first read. When two fixes edit the same file (remove one MCP
server and unpin another in .mcp.json, or two edits to ~/.claude.json), the
first apply changed the file and the second was refused as "changed since the
plan was built", exit code 1. Each plan is now rebuilt from the file on disk
just before it runs; the baseline captured for it is kept, and the stale-plan
check still guards edits made while the plan is being applied.

* fix(optimize): fast mode on background agents saves dollars, not tokens

Switching subagent calls from fast to standard speed bills the same tokens at
a lower rate. The finding claimed every output token of those calls as tokens
saved, which inflated the token headline and pushed it up the urgency ranking.
tokensSaved is now 0; the dollar figure is unchanged and still carries it.

* fix(optimize): charge an unused MCP server only to Claude sessions

unused-mcp reads servers from Claude Code config, but multiplied their schema
by every session of every provider in the period, so under --provider all a
handful of Claude sessions next to hundreds of Codex or Cursor sessions
produced a large token and dollar figure. It now counts and prices only Claude
sessions, as the deferral checks already do.

* fix(optimize): stop reading MCP servers from ~/.claude/settings.json

Claude Code reads MCP servers from ~/.claude.json and .mcp.json, not from the
mcpServers key of ~/.claude/settings.json or settings.local.json. The MCP
checks read both user settings files, while the remove plan never edits them,
so a server listed only there showed as an unused server with savings under
"Fix now" and apply skipped it as "not found in editable config". The loader
now leaves those two files out; its home directory parameter, and the one on
the alwaysLoad check that only fed it, go with them.

* fix(act): match MCP servers in the report by their namespace

The report's baseline keeps config names such as "docs.local", while sessions
name the server as Claude Code does in tool names ("docs_local"). A removed
server that came back never matched, so act report counted savings instead of
reading it as reverted. sessionLoadsAny now compares through mcpNamespace.

* fix(optimize): keep every config name that maps to one MCP namespace

Claude Code turns "a.b" and "a:b" into the same tool namespace "a_b", so the
MCP config loader keyed both under one entry and kept only the newest name.
unused-mcp then named one of them, and the remove plan left the other config
entry in place. The entry now keeps every config name; unused-mcp and the
alwaysLoad check pass each one to their plans.

* fix(act): read a "__" server name whole from report inventory entries

Inventory entries are mcp__<server>__<tool>, and the report took the server
as the second "__" segment, so a server named "a__b" was read as "a" and a
re-added "a__b" never showed as reverted. The tool is now cut off from the
right, leaving the full server name.

* fix(act): resolve MCP namespaces against the known servers

mcp__a__b__c can be server "a__b" with tool "c" or server "a" with tool
"b__c", and both fixed rules (first segment, or cut from the right) pick the
wrong server for some names. A tool name is now split at the longest server
namespace found in the MCP config (plus the servers being measured in act
report), falling back to the first segment only when none matches. This
applies to act report's inventory reads and to the call names unused-mcp and
mcp-deferral-off count.

* fix(act): replan only for files an earlier fix in this run changed

Rebuilding every plan right before it ran took a fresh hash of the current
file, so under --apply --yes a config file edited outside codeburn between
selection and apply was rewritten anyway, where the stale-plan guard used to
refuse it. The run now records the hash of every file it writes. A plan is
rebuilt only when one of its files differs from the plan solely because an
earlier fix in this run wrote it; any other change keeps the original plan,
and runAction rejects it with "changed since the plan was built".

* docs(optimize): note why an MCP tool name with two known prefixes is ambiguous
2026-11-06 09:27:46 +01:00

1027 lines
46 KiB
TypeScript
Raw Permalink Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

import { afterAll, describe, expect, it } from 'vitest'
import { mkdtemp, mkdir, readFile, readdir, rm, writeFile } from 'node:fs/promises'
import { existsSync } from 'node:fs'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
import { createHash } from 'node:crypto'
import { PassThrough, Writable } from 'node:stream'
import stripAnsi from 'strip-ansi'
import { planFor, planFindings, type PlanContext } from '../src/act/plans.js'
import { renderApplyList, runOptimizeApply, type ApplyOptions } from '../src/act/optimize-apply.js'
import { runAction } from '../src/act/apply.js'
import { undoAction } from '../src/act/undo.js'
import { readRecords, shortId } from '../src/act/journal.js'
import {
FINDING_BASIS,
FINDING_CLASS,
findingClass,
detectBloatedClaudeMd,
detectDuplicateReads,
detectJunkReads,
detectLowReadEditRatio,
detectMcpToolCoverage,
} from '../src/optimize.js'
import type {
FindingApply,
FindingId,
McpServerCoverage,
ToolCall,
WasteAction,
WasteFinding,
} from '../src/optimize.js'
const roots: string[] = []
type Fixture = { root: string; home: string; project: string; actionsDir: string }
async function makeFixture(): Promise<Fixture> {
const root = await mkdtemp(join(tmpdir(), 'codeburn-optimize-apply-'))
roots.push(root)
const home = join(root, 'home')
const project = join(root, 'project')
await mkdir(home, { recursive: true })
await mkdir(project, { recursive: true })
return { root, home, project, actionsDir: join(root, 'actions') }
}
afterAll(async () => {
for (const root of roots) await rm(root, { recursive: true, force: true })
})
function makeFinding(id: FindingId, fix: WasteAction, apply?: FindingApply): WasteFinding {
return { id, title: id, explanation: '', impact: 'medium', tokensSaved: 1000, fix, ...(apply ? { apply } : {}) }
}
const CMD_FIX: WasteAction = { type: 'command', label: '', text: '' }
async function hashTree(dir: string): Promise<string> {
const h = createHash('sha256')
async function walk(d: string): Promise<void> {
const entries = (await readdir(d, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name))
for (const entry of entries) {
const full = join(d, entry.name)
if (entry.isDirectory()) {
h.update('D:' + full + '\n')
await walk(full)
} else {
h.update('F:' + full + '\n')
h.update(await readFile(full))
}
}
}
await walk(dir)
return h.digest('hex')
}
describe('mcp-remove plan', () => {
it('deletes exactly the named server, leaves other keys untouched, and undo restores byte-identical', async () => {
const fx = await makeFixture()
const claudeJson = join(fx.home, '.claude.json')
const original = JSON.stringify({
mcpServers: { alpha: { command: 'a' }, beta: { command: 'b', args: ['x'] } },
numFoo: 3,
nested: { keep: true },
}, null, 2) + '\n'
await writeFile(claudeJson, original)
await writeFile(join(fx.project, '.mcp.json'), JSON.stringify({ mcpServers: { gamma: {} } }, null, 2) + '\n')
const finding = makeFinding('mcp-low-coverage', CMD_FIX, { kind: 'mcp-remove', servers: ['beta'] })
const plan = planFor(finding, { homeDir: fx.home, cwd: fx.project })
expect(plan).not.toBeNull()
expect(plan!.changes).toHaveLength(1)
expect(plan!.changes[0]!.path).toBe(claudeJson)
const rec = await runAction(plan!, fx.actionsDir)
const after = JSON.parse(await readFile(claudeJson, 'utf-8'))
expect(after.mcpServers).toEqual({ alpha: { command: 'a' } })
expect(after.numFoo).toBe(3)
expect(after.nested).toEqual({ keep: true })
// Untouched sibling config file.
expect(JSON.parse(await readFile(join(fx.project, '.mcp.json'), 'utf-8')).mcpServers).toEqual({ gamma: {} })
// 2-space indent + trailing newline contract.
expect(await readFile(claudeJson, 'utf-8')).toBe(JSON.stringify(after, null, 2) + '\n')
await undoAction({ id: rec.id }, { actionsDir: fx.actionsDir })
expect(await readFile(claudeJson, 'utf-8')).toBe(original)
})
it('does not plan connector removal and removes only the local server from a mixed finding', async () => {
const coverage = (server: string): McpServerCoverage => ({
server,
toolsAvailable: 20,
toolsInvoked: 0,
unusedTools: Array.from({ length: 20 }, (_, i) => `mcp__${server}__t${i}`),
invocations: 0,
loadedSessions: 2,
coverageRatio: 0,
})
const connector = coverage('claude_ai_Netlify')
const connectorOnly = detectMcpToolCoverage([], [connector])!
expect(connectorOnly.apply).toBeUndefined()
expect(planFor(connectorOnly)).toBeNull()
const fx = await makeFixture()
const claudeJson = join(fx.home, '.claude.json')
await writeFile(claudeJson, JSON.stringify({
mcpServers: {
filesystem: { command: 'filesystem' },
netlify: { command: 'local-netlify' },
},
}, null, 2) + '\n')
const mixed = detectMcpToolCoverage([], [connector, coverage('filesystem')])!
expect(mixed.apply).toEqual({ kind: 'mcp-remove', servers: ['filesystem'] })
const plan = planFor(mixed, { homeDir: fx.home, cwd: fx.project })
expect(plan).not.toBeNull()
await runAction(plan!, fx.actionsDir)
expect(JSON.parse(await readFile(claudeJson, 'utf-8')).mcpServers).toEqual({
netlify: { command: 'local-netlify' },
})
})
it('previews only the savings attributable to a mixed finding local mutation', async () => {
const fx = await makeFixture()
await writeFile(join(fx.home, '.claude.json'), JSON.stringify({
mcpServers: { filesystem: { command: 'filesystem' } },
}, null, 2) + '\n')
const finding: WasteFinding = {
id: 'mcp-low-coverage',
title: '2 MCP servers with low tool coverage',
explanation: '',
impact: 'medium',
tokensSaved: 80_000,
applyTokensSaved: 20_000,
fix: { type: 'command', label: '', text: "claude mcp remove 'filesystem'" },
apply: { kind: 'mcp-remove', servers: ['filesystem'] },
}
const plans = planFindings([finding], { homeDir: fx.home, cwd: fx.project })
const preview = stripAnsi(renderApplyList(plans, [], 0.000002))
expect(preview).toContain('(~20.0K tokens, ~$0.040)')
expect(preview).not.toContain('~80.0K tokens')
expect(preview).not.toContain('~$0.160')
})
it('scopes targets and savings to local servers actually present in editable config', async () => {
const fx = await makeFixture()
await writeFile(join(fx.home, '.claude.json'), JSON.stringify({
mcpServers: { filesystem: { command: 'filesystem' } },
}, null, 2) + '\n')
const finding: WasteFinding = {
id: 'mcp-low-coverage',
title: '3 MCP servers with low tool coverage',
explanation: '',
impact: 'medium',
tokensSaved: 60_000,
applyTokensSaved: 30_000,
applyTokensSavedByServer: { filesystem: 10_000, managed: 20_000 },
fix: { type: 'command', label: '', text: "claude mcp remove 'filesystem'\nclaude mcp remove 'managed'" },
apply: { kind: 'mcp-remove', servers: ['filesystem', 'managed'] },
}
const plans = planFindings([finding], { homeDir: fx.home, cwd: fx.project })
const preview = stripAnsi(renderApplyList(plans.filter(p => p.plan), plans.filter(p => !p.plan), 0))
expect(plans[0]!.plan?.affectedMcpServers).toEqual(['filesystem'])
expect(preview).toContain('Removes local MCP server: filesystem')
expect(preview).toContain('~10.0K tokens')
expect(preview).not.toContain('~30.0K tokens')
expect(preview).toContain('skipped managed: not found in editable config')
})
it('suppresses savings for a legacy partial plan without per-server attribution', async () => {
const fx = await makeFixture()
await writeFile(join(fx.home, '.claude.json'), JSON.stringify({
mcpServers: { filesystem: { command: 'filesystem' } },
}, null, 2) + '\n')
const finding: WasteFinding = {
id: 'mcp-low-coverage',
title: '2 MCP servers with low tool coverage',
explanation: '',
impact: 'medium',
tokensSaved: 30_000,
applyTokensSaved: 30_000,
fix: { type: 'command', label: '', text: '' },
apply: { kind: 'mcp-remove', servers: ['filesystem', 'managed'] },
}
const plans = planFindings([finding], { homeDir: fx.home, cwd: fx.project })
const preview = stripAnsi(renderApplyList(plans.filter(p => p.plan), plans.filter(p => !p.plan), 0))
expect(plans[0]!.plan?.affectedMcpServers).toEqual(['filesystem'])
expect(plans[0]!.plan?.mcpSavingsUncertain).toBe(true)
expect(preview).toContain('Savings not estimated')
expect(preview).not.toContain('~30.0K tokens')
})
it('deduplicates repeated removal targets before planning and pricing them', async () => {
const fx = await makeFixture()
await writeFile(join(fx.home, '.claude.json'), JSON.stringify({
mcpServers: { filesystem: { command: 'filesystem' } },
}, null, 2) + '\n')
const finding: WasteFinding = {
id: 'mcp-low-coverage',
title: '1 MCP server with low tool coverage',
explanation: '',
impact: 'medium',
tokensSaved: 10_000,
applyTokensSavedByServer: { filesystem: 10_000 },
fix: { type: 'command', label: '', text: '' },
apply: { kind: 'mcp-remove', servers: ['filesystem', 'filesystem'] },
}
const plans = planFindings([finding], { homeDir: fx.home, cwd: fx.project })
const preview = stripAnsi(renderApplyList(plans.filter(p => p.plan), [], 0))
expect(plans[0]!.plan?.affectedMcpServers).toEqual(['filesystem'])
expect(preview).toContain('~10.0K tokens')
expect(preview).not.toContain('~20.0K tokens')
})
it('does not claim savings when another relevant config scope is unreadable', async () => {
const fx = await makeFixture()
await writeFile(join(fx.home, '.claude.json'), JSON.stringify({
mcpServers: { filesystem: { command: 'filesystem' } },
}, null, 2) + '\n')
await writeFile(join(fx.project, '.mcp.json'), 'not json{{{')
const finding: WasteFinding = {
id: 'mcp-low-coverage',
title: '1 MCP server with low tool coverage',
explanation: '',
impact: 'medium',
tokensSaved: 10_000,
applyTokensSavedByServer: { filesystem: 10_000 },
fix: { type: 'command', label: '', text: "claude mcp remove 'filesystem'" },
apply: { kind: 'mcp-remove', servers: ['filesystem'] },
}
const plans = planFindings([finding], { homeDir: fx.home, cwd: fx.project })
const preview = stripAnsi(renderApplyList(plans.filter(p => p.plan), plans.filter(p => !p.plan), 0))
expect(plans[0]!.plan?.affectedMcpServers).toEqual(['filesystem'])
expect(plans[0]!.plan?.mcpSavingsUncertain).toBe(true)
expect(preview).toContain('Savings not estimated')
expect(preview).toContain('could not parse')
expect(preview).not.toContain('~10.0K tokens')
})
})
describe('mcp-project-scope plan', () => {
it('moves the entry from the global config into the keeper project .mcp.json, creating it when missing', async () => {
const fx = await makeFixture()
const claudeJson = join(fx.home, '.claude.json')
const serverValue = { command: 'srv', args: ['--flag'], env: { A: '1' } }
const original = JSON.stringify({ mcpServers: { srv: serverValue }, other: 1 }, null, 2) + '\n'
await writeFile(claudeJson, original)
const keeper = join(fx.root, 'keeper')
await mkdir(keeper, { recursive: true })
const keeperMcp = join(keeper, '.mcp.json')
expect(existsSync(keeperMcp)).toBe(false)
const finding = makeFinding('mcp-project-scope', { type: 'paste', destination: 'prompt', label: '', text: '' }, {
kind: 'mcp-project-scope',
servers: [{ server: 'srv', keepProjects: [keeper], removeProjects: [] }],
})
const plan = planFor(finding, { homeDir: fx.home, cwd: fx.project })
expect(plan).not.toBeNull()
const rec = await runAction(plan!, fx.actionsDir)
expect(JSON.parse(await readFile(claudeJson, 'utf-8')).mcpServers).toEqual({})
expect(existsSync(keeperMcp)).toBe(true)
expect(JSON.parse(await readFile(keeperMcp, 'utf-8')).mcpServers).toEqual({ srv: serverValue })
await undoAction({ id: rec.id }, { actionsDir: fx.actionsDir })
expect(await readFile(claudeJson, 'utf-8')).toBe(original)
expect(existsSync(keeperMcp)).toBe(false)
})
})
describe('unparseable config file', () => {
it('reports the parse error, skips that server, and still applies the servers it can read', async () => {
const fx = await makeFixture()
const claudeJson = join(fx.home, '.claude.json')
await writeFile(claudeJson, JSON.stringify({ mcpServers: { good: { command: 'g' } } }, null, 2) + '\n')
const brokenMcp = join(fx.project, '.mcp.json')
await writeFile(brokenMcp, '{ this is not valid json,,, ')
const finding = makeFinding('mcp-low-coverage', CMD_FIX, { kind: 'mcp-remove', servers: ['good', 'bad'] })
const { plan, notes } = planFindings([finding], { homeDir: fx.home, cwd: fx.project })[0]!
expect(notes.some(n => /could not parse/.test(n) && n.includes('.mcp.json'))).toBe(true)
expect(notes.some(n => n.includes('bad'))).toBe(true)
expect(plan).not.toBeNull()
expect(plan!.changes.map(c => c.path)).toEqual([claudeJson])
await runAction(plan!, fx.actionsDir)
expect(JSON.parse(await readFile(claudeJson, 'utf-8')).mcpServers).toEqual({})
// The broken file is left exactly as-is.
expect(await readFile(brokenMcp, 'utf-8')).toBe('{ this is not valid json,,, ')
})
})
describe('archive plan', () => {
it('archives a skill dir and an agent file, round-trips undo, and suffixes a colliding name with -2', async () => {
const fx = await makeFixture()
const skillsDir = join(fx.home, '.claude', 'skills')
const agentsDir = join(fx.home, '.claude', 'agents')
await mkdir(join(skillsDir, 'foo'), { recursive: true })
await writeFile(join(skillsDir, 'foo', 'SKILL.md'), 'skill body')
// Pre-existing archive with the same name forces the -2 suffix.
await mkdir(join(skillsDir, '.archived', 'foo'), { recursive: true })
await writeFile(join(skillsDir, '.archived', 'foo', 'SKILL.md'), 'old archived')
await mkdir(agentsDir, { recursive: true })
await writeFile(join(agentsDir, 'bar.md'), 'agent body')
const skillFinding = makeFinding('unused-skills', CMD_FIX, { kind: 'archive', names: ['foo'] })
const skillPlan = planFor(skillFinding, { homeDir: fx.home, cwd: fx.project })
expect(skillPlan!.changes[0]).toMatchObject({
op: 'move',
path: join(skillsDir, 'foo'),
movedTo: join(skillsDir, '.archived', 'foo-2'),
})
const skillRec = await runAction(skillPlan!, fx.actionsDir)
expect(existsSync(join(skillsDir, 'foo'))).toBe(false)
expect(await readFile(join(skillsDir, '.archived', 'foo-2', 'SKILL.md'), 'utf-8')).toBe('skill body')
// The pre-existing archive is preserved.
expect(await readFile(join(skillsDir, '.archived', 'foo', 'SKILL.md'), 'utf-8')).toBe('old archived')
const agentFinding = makeFinding('unused-agents', CMD_FIX, { kind: 'archive', names: ['bar'] })
const agentPlan = planFor(agentFinding, { homeDir: fx.home, cwd: fx.project })
expect(agentPlan!.changes[0]).toMatchObject({
op: 'move',
path: join(agentsDir, 'bar.md'),
movedTo: join(agentsDir, '.archived', 'bar.md'),
})
const agentRec = await runAction(agentPlan!, fx.actionsDir)
expect(existsSync(join(agentsDir, 'bar.md'))).toBe(false)
await undoAction({ id: agentRec.id }, { actionsDir: fx.actionsDir })
await undoAction({ id: skillRec.id }, { actionsDir: fx.actionsDir })
expect(await readFile(join(agentsDir, 'bar.md'), 'utf-8')).toBe('agent body')
expect(await readFile(join(skillsDir, 'foo', 'SKILL.md'), 'utf-8')).toBe('skill body')
expect(existsSync(join(skillsDir, '.archived', 'foo-2'))).toBe(false)
})
})
describe('claude-md rule plan', () => {
it('appends a fresh marker block, replaces it in place on re-apply, and undo removes it', async () => {
const fx = await makeFixture()
const claudeMd = join(fx.project, 'CLAUDE.md')
const original = '# Project\n\nExisting rules.\n'
await writeFile(claudeMd, original)
const first = makeFinding('read-edit-ratio', { type: 'paste', destination: 'claude-md', label: '', text: 'Read before editing.' })
const firstPlan = planFor(first, { homeDir: fx.home, cwd: fx.project })
const firstRec = await runAction(firstPlan!, fx.actionsDir)
let body = await readFile(claudeMd, 'utf-8')
expect(body).toContain('# Project')
expect(body).toContain('<!-- codeburn:begin read-edit-ratio -->')
expect(body).toContain('Read before editing.')
expect(body).toContain('<!-- codeburn:end read-edit-ratio -->')
// Second apply with the same id replaces the block instead of duplicating.
const second = makeFinding('read-edit-ratio', { type: 'paste', destination: 'claude-md', label: '', text: 'Read first, then edit.' })
const secondPlan = planFor(second, { homeDir: fx.home, cwd: fx.project })
const secondRec = await runAction(secondPlan!, fx.actionsDir)
body = await readFile(claudeMd, 'utf-8')
expect(body.match(/codeburn:begin read-edit-ratio/g)).toHaveLength(1)
expect(body).toContain('Read first, then edit.')
expect(body).not.toContain('Read before editing.')
await undoAction({ id: secondRec.id }, { actionsDir: fx.actionsDir })
await undoAction({ id: firstRec.id }, { actionsDir: fx.actionsDir })
expect(await readFile(claudeMd, 'utf-8')).toBe(original)
})
})
describe('shell-config plan', () => {
it('writes the bash cap inside # markers to the rc chosen from $SHELL', async () => {
const fx = await makeFixture()
const finding = makeFinding('bash-output-cap', { type: 'paste', destination: 'shell-config', label: '', text: 'export BASH_MAX_OUTPUT_LENGTH=15000' })
const plan = planFor(finding, { homeDir: fx.home, cwd: fx.project, shell: '/bin/zsh' })
expect(plan!.changes[0]!.path).toBe(join(fx.home, '.zshrc'))
await runAction(plan!, fx.actionsDir)
const body = await readFile(join(fx.home, '.zshrc'), 'utf-8')
expect(body).toBe('# codeburn:begin bash-output-cap\nexport BASH_MAX_OUTPUT_LENGTH=15000\n# codeburn:end bash-output-cap\n')
})
})
describe('dry-run', () => {
it('leaves the fixture tree byte-identical when only planning', async () => {
const fx = await makeFixture()
await writeFile(join(fx.home, '.claude.json'), JSON.stringify({ mcpServers: { s: { command: 'c' } } }, null, 2) + '\n')
await mkdir(join(fx.home, '.claude', 'skills', 'ghost'), { recursive: true })
await writeFile(join(fx.home, '.claude', 'skills', 'ghost', 'SKILL.md'), 'x')
await writeFile(join(fx.project, 'CLAUDE.md'), '# rules\n')
const findings: WasteFinding[] = [
makeFinding('mcp-low-coverage', CMD_FIX, { kind: 'mcp-remove', servers: ['s'] }),
makeFinding('unused-skills', CMD_FIX, { kind: 'archive', names: ['ghost'] }),
makeFinding('read-edit-ratio', { type: 'paste', destination: 'claude-md', label: '', text: 'rule' }),
makeFinding('bash-output-cap', { type: 'paste', destination: 'shell-config', label: '', text: 'export BASH_MAX_OUTPUT_LENGTH=15000' }),
]
const before = await hashTree(fx.root)
const plans = planFindings(findings, { homeDir: fx.home, cwd: fx.project, shell: '/bin/zsh' })
// Exercise the exact rendering the dry-run path prints.
renderApplyList(plans.filter(p => p.plan !== null), plans.filter(p => p.plan === null), 0.000002)
const after = await hashTree(fx.root)
expect(plans.every(p => p.plan !== null)).toBe(true)
expect(after).toBe(before)
})
})
describe('finding-id regression guard', () => {
const KEBAB = /^[a-z0-9]+(-[a-z0-9]+)*$/
const KNOWN: ReadonlySet<FindingId> = new Set<FindingId>([
'read-edit-ratio', 'build-folder-reads', 'redundant-rereads', 'warmup-heavy',
'unused-mcp', 'mcp-low-coverage', 'mcp-project-scope', 'retry-heavy-capabilities',
'low-worth-sessions', 'context-heavy-sessions', 'cost-outliers', 'claude-md-too-long',
'bash-output-cap', 'unused-agents', 'unused-skills', 'unused-commands',
])
it('every finding produced by a detector run carries a stable, known, non-empty id', async () => {
const fx = await makeFixture()
const bigClaudeMd = '# Rules\n' + Array.from({ length: 260 }, (_, i) => `- rule ${i}`).join('\n') + '\n'
await writeFile(join(fx.project, 'CLAUDE.md'), bigClaudeMd)
function read(file: string, session = 's1'): ToolCall {
return { name: 'Read', input: { file_path: file }, sessionId: session, project: 'p' }
}
const calls: ToolCall[] = [
read('/p/node_modules/a.js'), read('/p/node_modules/b.js'), read('/p/dist/c.js'),
...Array.from({ length: 6 }, () => read('/p/src/app.ts')),
...Array.from({ length: 10 }, (): ToolCall => ({ name: 'Edit', input: {}, sessionId: 's1', project: 'p' })),
]
const coverage: McpServerCoverage[] = [{
server: 'x', toolsAvailable: 20, toolsInvoked: 1,
unusedTools: Array.from({ length: 19 }, (_, i) => `mcp__x__t${i}`),
invocations: 1, loadedSessions: 3, coverageRatio: 0.05,
}]
const findings = [
detectLowReadEditRatio(calls),
detectJunkReads(calls),
detectDuplicateReads(calls),
detectBloatedClaudeMd(new Set([fx.project])),
detectMcpToolCoverage([], coverage),
].filter((f): f is WasteFinding => f !== null)
expect(findings.length).toBeGreaterThanOrEqual(5)
for (const f of findings) {
expect(f.id).toBeTruthy()
expect(f.id).toMatch(KEBAB)
expect(KNOWN.has(f.id)).toBe(true)
}
const ids = findings.map(f => f.id)
expect(new Set(ids).size).toBe(ids.length)
})
})
describe('unused-mcp plan', () => {
it('builds a remove-everywhere plan, including other projects[*] entries', async () => {
const fx = await makeFixture()
const claudeJson = join(fx.home, '.claude.json')
await writeFile(claudeJson, JSON.stringify({
mcpServers: { u: { command: 'u' } },
projects: { '/some/other': { mcpServers: { u: { command: 'u' }, keepme: {} } } },
}, null, 2) + '\n')
const finding = makeFinding('unused-mcp', CMD_FIX, { kind: 'mcp-remove', servers: ['u'] })
const plan = planFor(finding, { homeDir: fx.home, cwd: fx.project })
expect(plan).not.toBeNull()
expect(plan!.kind).toBe('mcp-remove')
await runAction(plan!, fx.actionsDir)
const after = JSON.parse(await readFile(claudeJson, 'utf-8'))
expect(after.mcpServers).toEqual({})
expect(after.projects['/some/other'].mcpServers).toEqual({ keepme: {} })
})
})
describe('BOM handling', () => {
it('parses a config file with a UTF-8 BOM', async () => {
const fx = await makeFixture()
const claudeJson = join(fx.home, '.claude.json')
await writeFile(claudeJson, '' + JSON.stringify({ mcpServers: { b: {} }, keep: 1 }, null, 2) + '\n')
const { plan, notes } = planFindings(
[makeFinding('mcp-low-coverage', CMD_FIX, { kind: 'mcp-remove', servers: ['b'] })],
{ homeDir: fx.home, cwd: fx.project },
)[0]!
expect(notes).toEqual([])
expect(plan).not.toBeNull()
const written = JSON.parse(String(plan!.changes[0]!.content))
expect(written).toEqual({ mcpServers: {}, keep: 1 })
})
})
// ---------------------------------------------------------------------------
// runOptimizeApply end-to-end (injected stdio, crafted findings, fixture home)
// ---------------------------------------------------------------------------
const ANSI = /\[[0-9;]*m/g
type Io = {
input: PassThrough
output: Writable
errorOutput: Writable
stdout(): string
stderr(): string
}
function makeIo(answer?: string): Io {
const input = new PassThrough()
input.end(answer ?? '')
const outChunks: Buffer[] = []
const errChunks: Buffer[] = []
const output = new Writable({ write(c, _e, cb) { outChunks.push(Buffer.from(c)); cb() } })
const errorOutput = new Writable({ write(c, _e, cb) { errChunks.push(Buffer.from(c)); cb() } })
return {
input,
output,
errorOutput,
stdout: () => Buffer.concat(outChunks).toString('utf-8').replace(ANSI, ''),
stderr: () => Buffer.concat(errChunks).toString('utf-8').replace(ANSI, ''),
}
}
function applyOpts(fx: Fixture, io: Io, extra: Partial<ApplyOptions> & { findings: WasteFinding[] }): ApplyOptions {
const ctx: PlanContext = { homeDir: fx.home, cwd: fx.project, shell: '/bin/zsh' }
return {
ctx,
actionsDir: fx.actionsDir,
input: io.input,
output: io.output,
errorOutput: io.errorOutput,
...extra,
}
}
// One mcp server, one skill, one shell cap: three appliable findings in a
// stable 1/2/3 order for the picker tests.
async function threeFindingFixture(): Promise<{ fx: Fixture; findings: WasteFinding[] }> {
const fx = await makeFixture()
await writeFile(join(fx.home, '.claude.json'), JSON.stringify({ mcpServers: { a: { command: 'a' } } }, null, 2) + '\n')
await mkdir(join(fx.home, '.claude', 'skills', 'foo'), { recursive: true })
await writeFile(join(fx.home, '.claude', 'skills', 'foo', 'SKILL.md'), 'x')
const findings: WasteFinding[] = [
makeFinding('mcp-low-coverage', CMD_FIX, { kind: 'mcp-remove', servers: ['a'] }),
makeFinding('unused-skills', CMD_FIX, { kind: 'archive', names: ['foo'] }),
makeFinding('bash-output-cap', { type: 'paste', destination: 'shell-config', label: '', text: 'export BASH_MAX_OUTPUT_LENGTH=15000' }),
]
return { fx, findings }
}
describe('runOptimizeApply end-to-end', () => {
it('prints connector-only manual guidance when there is nothing to apply', async () => {
const fx = await makeFixture()
const connector: McpServerCoverage = {
server: 'claude_ai_Netlify',
toolsAvailable: 20,
toolsInvoked: 0,
unusedTools: Array.from({ length: 20 }, (_, i) => `mcp__claude_ai_Netlify__t${i}`),
invocations: 0,
loadedSessions: 2,
coverageRatio: 0,
}
const finding = detectMcpToolCoverage([], [connector])!
const io = makeIo()
await runOptimizeApply([], undefined, applyOpts(fx, io, { findings: [finding], yes: true }))
expect(io.stdout()).toContain('No appliable config-class fixes')
expect(io.stdout()).toContain('/mcp')
expect(io.stdout()).toContain('claude.ai Netlify')
expect(io.stdout()).not.toContain('claude mcp remove')
})
it('names the exact local removal target and preserves connector follow-up in a mixed preview', async () => {
const fx = await makeFixture()
await writeFile(join(fx.home, '.claude.json'), JSON.stringify({
mcpServers: { filesystem: { command: 'filesystem' }, netlify: { command: 'local-netlify' } },
}, null, 2) + '\n')
const coverage = (server: string): McpServerCoverage => ({
server,
toolsAvailable: 20,
toolsInvoked: 0,
unusedTools: Array.from({ length: 20 }, (_, i) => `mcp__${server}__t${i}`),
invocations: 0,
loadedSessions: 2,
coverageRatio: 0,
})
const finding = detectMcpToolCoverage([], [coverage('filesystem'), coverage('claude_ai_Netlify')])!
const io = makeIo()
await runOptimizeApply([], undefined, applyOpts(fx, io, { findings: [finding], dryRun: true }))
expect(io.stdout()).toContain('Removes local MCP server: filesystem')
expect(io.stdout()).toContain('/mcp')
expect(io.stdout()).toContain('claude.ai Netlify')
expect(io.stdout()).not.toContain("claude mcp remove 'claude_ai_Netlify'")
})
it('keeps mixed connector follow-up explicitly pending after applying the local fix', async () => {
const fx = await makeFixture()
await writeFile(join(fx.home, '.claude.json'), JSON.stringify({
mcpServers: { filesystem: { command: 'filesystem' } },
}, null, 2) + '\n')
const coverage = (server: string): McpServerCoverage => ({
server,
toolsAvailable: 20,
toolsInvoked: 0,
unusedTools: Array.from({ length: 20 }, (_, i) => `mcp__${server}__t${i}`),
invocations: 0,
loadedSessions: 2,
coverageRatio: 0,
})
const finding = detectMcpToolCoverage([], [coverage('filesystem'), coverage('claude_ai_Netlify')])!
const io = makeIo()
await runOptimizeApply([], undefined, applyOpts(fx, io, { findings: [finding], yes: true }))
const out = io.stdout()
expect(out).toContain('Manual follow-up (not applied):')
expect(out).toContain('Still requires manual action:')
expect(out).toContain('claude.ai Netlify')
expect(await readRecords(fx.actionsDir)).toHaveLength(1)
expect(JSON.parse(await readFile(join(fx.home, '.claude.json'), 'utf-8')).mcpServers).toEqual({})
})
it('--yes applies every plan and prints journal short ids with the undo hint', async () => {
const { fx, findings } = await threeFindingFixture()
const io = makeIo()
await runOptimizeApply([], undefined, applyOpts(fx, io, { findings, yes: true }))
const records = await readRecords(fx.actionsDir)
expect(records).toHaveLength(3)
const out = io.stdout()
for (const rec of records) {
expect(out).toContain(`Applied ${shortId(rec.id)}`)
expect(out).toContain(`Undo anytime: codeburn act undo ${shortId(rec.id)}`)
}
expect(out).toContain('CodeBurn will re-measure these on your next optimize run after 3 days.')
expect(JSON.parse(await readFile(join(fx.home, '.claude.json'), 'utf-8')).mcpServers).toEqual({})
expect(existsSync(join(fx.home, '.claude', 'skills', '.archived', 'foo'))).toBe(true)
expect(existsSync(join(fx.home, '.zshrc'))).toBe(true)
})
it('--yes applies two fixes that edit the same config file', async () => {
const fx = await makeFixture()
const mcpJson = join(fx.project, '.mcp.json')
await writeFile(mcpJson, JSON.stringify({ mcpServers: { a: { command: 'a' }, b: { command: 'b', alwaysLoad: true } } }, null, 2))
const findings = [
makeFinding('unused-mcp', CMD_FIX, { kind: 'mcp-remove', servers: ['a'] }),
makeFinding('mcp-alwaysload-hygiene', CMD_FIX, { kind: 'defer-alwaysload', servers: [{ server: 'b', paths: [mcpJson] }] }),
]
const io = makeIo()
await runOptimizeApply([], undefined, applyOpts(fx, io, { findings, yes: true, ctx: { homeDir: fx.home, cwd: fx.project, claudeVersion: () => '2.1.200' } }))
expect(io.stderr()).toBe('')
expect(await readRecords(fx.actionsDir)).toHaveLength(2)
expect(JSON.parse(await readFile(mcpJson, 'utf-8')).mcpServers).toEqual({ b: { command: 'b' } })
})
it('rejects a fix whose file was edited outside this run after the plan was built', async () => {
const fx = await makeFixture()
const mcpJson = join(fx.project, '.mcp.json')
await writeFile(mcpJson, JSON.stringify({ mcpServers: { a: { command: 'a' } } }, null, 2))
const edited = JSON.stringify({ mcpServers: { a: { command: 'a' }, c: { command: 'c' } } }, null, 2)
const input = new PassThrough()
const io = makeIo()
const output = new Writable({
write(c, _e, cb) {
io.output.write(c)
if (String(c).includes('Apply all')) void writeFile(mcpJson, edited).then(() => input.end('a\n'))
cb()
},
})
const findings = [makeFinding('unused-mcp', CMD_FIX, { kind: 'mcp-remove', servers: ['a'] })]
const prevExit = process.exitCode
try {
await runOptimizeApply([], undefined, { ...applyOpts(fx, io, { findings }), input, output })
expect(io.stderr()).toContain('changed since the plan was built')
expect(await readFile(mcpJson, 'utf-8')).toBe(edited)
} finally {
process.exitCode = prevExit
}
})
it('does not promise a re-measure when nothing was applied', async () => {
const { fx, findings } = await threeFindingFixture()
const io = makeIo('q\n')
await runOptimizeApply([], undefined, applyOpts(fx, io, { findings }))
expect(io.stdout()).not.toContain('re-measure')
})
it('interactive pick "2" applies only the second plan', async () => {
const { fx, findings } = await threeFindingFixture()
const io = makeIo('2\n')
await runOptimizeApply([], undefined, applyOpts(fx, io, { findings }))
const records = await readRecords(fx.actionsDir)
expect(records).toHaveLength(1)
expect(records[0]!.kind).toBe('archive-skill')
expect(JSON.parse(await readFile(join(fx.home, '.claude.json'), 'utf-8')).mcpServers).toEqual({ a: { command: 'a' } })
expect(existsSync(join(fx.home, '.zshrc'))).toBe(false)
})
it('interactive pick "1,3" applies the first and third plans', async () => {
const { fx, findings } = await threeFindingFixture()
const io = makeIo('1,3\n')
await runOptimizeApply([], undefined, applyOpts(fx, io, { findings }))
const records = await readRecords(fx.actionsDir)
expect(records.map(r => r.kind).sort()).toEqual(['mcp-remove', 'shell-config'])
expect(existsSync(join(fx.home, '.claude', 'skills', 'foo'))).toBe(true)
})
it('a garbage answer applies nothing and prints the empty outcome', async () => {
const { fx, findings } = await threeFindingFixture()
const io = makeIo('wat\n')
await runOptimizeApply([], undefined, applyOpts(fx, io, { findings }))
expect(await readRecords(fx.actionsDir)).toHaveLength(0)
expect(io.stdout()).toContain('Nothing applied.')
})
it('EOF at the prompt prints "Nothing applied." and leaves the exit code untouched', async () => {
const { fx, findings } = await threeFindingFixture()
const io = makeIo()
const prevExit = process.exitCode
await runOptimizeApply([], undefined, applyOpts(fx, io, { findings }))
expect(process.exitCode).toBe(prevExit)
expect(io.stdout()).toContain('Nothing applied.')
expect(await readRecords(fx.actionsDir)).toHaveLength(0)
})
it('--only restricts the applied set', async () => {
const { fx, findings } = await threeFindingFixture()
const io = makeIo()
await runOptimizeApply([], undefined, applyOpts(fx, io, { findings, yes: true, only: 'unused-skills' }))
const records = await readRecords(fx.actionsDir)
expect(records).toHaveLength(1)
expect(records[0]!.kind).toBe('archive-skill')
expect(JSON.parse(await readFile(join(fx.home, '.claude.json'), 'utf-8')).mcpServers).toEqual({ a: { command: 'a' } })
})
it('--only with an unknown or not-appliable id errors with the valid ids and exit code 2', async () => {
const { fx, findings } = await threeFindingFixture()
const io = makeIo()
const prevExit = process.exitCode
try {
await runOptimizeApply([], undefined, applyOpts(fx, io, { findings, yes: true, only: 'read-edit-ratio' }))
expect(process.exitCode).toBe(2)
const err = io.stderr()
expect(err).toContain('read-edit-ratio')
expect(err).toContain('Appliable ids for this run:')
expect(err).toContain('mcp-low-coverage')
expect(await readRecords(fx.actionsDir)).toHaveLength(0)
expect(io.stdout()).not.toContain('No appliable config-class fixes')
} finally {
process.exitCode = prevExit
}
})
it('--yes skips claude-md plans with a reason unless explicitly selected via --only', async () => {
const { fx, findings } = await threeFindingFixture()
const claudeMdFinding = makeFinding('read-edit-ratio', { type: 'paste', destination: 'claude-md', label: '', text: 'Read first.' })
const io = makeIo()
await runOptimizeApply([], undefined, applyOpts(fx, io, { findings: [claudeMdFinding, ...findings], yes: true }))
expect(io.stdout()).toContain('Skipped read-edit-ratio: CLAUDE.md edits are not applied with --yes')
expect(existsSync(join(fx.project, 'CLAUDE.md'))).toBe(false)
expect((await readRecords(fx.actionsDir)).map(r => r.kind)).not.toContain('claude-md-rule')
const fx2 = await makeFixture()
const io2 = makeIo()
await runOptimizeApply([], undefined, applyOpts(fx2, io2, { findings: [claudeMdFinding], yes: true, only: 'read-edit-ratio' }))
expect((await readRecords(fx2.actionsDir)).map(r => r.kind)).toEqual(['claude-md-rule'])
expect(await readFile(join(fx2.project, 'CLAUDE.md'), 'utf-8')).toContain('<!-- codeburn:begin read-edit-ratio -->')
})
it('project-scope leaves unrelated projects[*] entries untouched and previews the cold removals', async () => {
const fx = await makeFixture()
const claudeJson = join(fx.home, '.claude.json')
const serverValue = { command: 'srv' }
await writeFile(claudeJson, JSON.stringify({
mcpServers: { srv: serverValue },
projects: {
'/cold/one': { mcpServers: { srv: serverValue } },
'/unrelated/proj': { mcpServers: { srv: serverValue, keepme: {} } },
},
}, null, 2) + '\n')
const keeper = join(fx.root, 'keeper')
await mkdir(keeper, { recursive: true })
const finding = makeFinding('mcp-project-scope', CMD_FIX, {
kind: 'mcp-project-scope',
servers: [{ server: 'srv', keepProjects: [keeper], removeProjects: ['/cold/one'] }],
})
const io = makeIo()
await runOptimizeApply([], undefined, applyOpts(fx, io, { findings: [finding], yes: true }))
expect(io.stdout()).toContain('(removes srv from 1 project entry: /cold/one)')
const after = JSON.parse(await readFile(claudeJson, 'utf-8'))
expect(after.mcpServers).toEqual({})
expect(after.projects['/cold/one'].mcpServers).toEqual({})
expect(after.projects['/unrelated/proj'].mcpServers).toEqual({ srv: serverValue, keepme: {} })
expect(JSON.parse(await readFile(join(keeper, '.mcp.json'), 'utf-8')).mcpServers).toEqual({ srv: serverValue })
})
it('surfaces parse-error notes when every plan resolves to null', async () => {
const fx = await makeFixture()
await writeFile(join(fx.home, '.claude.json'), 'not json{{{')
const finding = makeFinding('mcp-low-coverage', CMD_FIX, { kind: 'mcp-remove', servers: ['ghost'] })
const io = makeIo()
await runOptimizeApply([], undefined, applyOpts(fx, io, { findings: [finding], yes: true }))
const out = io.stdout()
expect(out).toContain('No appliable config-class fixes')
expect(out).toContain('could not parse')
expect(out).toContain('.claude.json')
expect(await readRecords(fx.actionsDir)).toHaveLength(0)
})
it('renders notes under manual findings alongside appliable ones', async () => {
const fx = await makeFixture()
await writeFile(join(fx.home, '.claude.json'), 'not json{{{')
await mkdir(join(fx.home, '.claude', 'skills', 'foo'), { recursive: true })
await writeFile(join(fx.home, '.claude', 'skills', 'foo', 'SKILL.md'), 'x')
const findings: WasteFinding[] = [
makeFinding('mcp-low-coverage', CMD_FIX, { kind: 'mcp-remove', servers: ['ghost'] }),
makeFinding('unused-skills', CMD_FIX, { kind: 'archive', names: ['foo'] }),
]
const io = makeIo()
await runOptimizeApply([], undefined, applyOpts(fx, io, { findings, dryRun: true }))
const out = io.stdout()
expect(out).toContain('[mcp-low-coverage] manual')
expect(out).toContain('could not parse')
})
})
describe('stale-plan detection', () => {
it('rejects when the target changed after the plan was built, leaving nothing behind', async () => {
const fx = await makeFixture()
const claudeJson = join(fx.home, '.claude.json')
await writeFile(claudeJson, JSON.stringify({ mcpServers: { s: {} } }, null, 2) + '\n')
const plan = planFor(
makeFinding('mcp-low-coverage', CMD_FIX, { kind: 'mcp-remove', servers: ['s'] }),
{ homeDir: fx.home, cwd: fx.project },
)
expect(plan).not.toBeNull()
const interim = JSON.stringify({ mcpServers: { s: {}, addedMeanwhile: {} } }, null, 2) + '\n'
await writeFile(claudeJson, interim)
await expect(runAction(plan!, fx.actionsDir)).rejects.toThrow(/changed since the plan was built; re-run codeburn optimize --apply/)
expect(await readFile(claudeJson, 'utf-8')).toBe(interim)
expect(await readRecords(fx.actionsDir)).toHaveLength(0)
const backups = await readdir(join(fx.actionsDir, 'backups')).catch(() => [])
expect(backups).toEqual([])
})
it('rejects a plan expecting an absent file when the file appeared', async () => {
const fx = await makeFixture()
const claudeMd = join(fx.project, 'CLAUDE.md')
const plan = planFor(
makeFinding('read-edit-ratio', { type: 'paste', destination: 'claude-md', label: '', text: 'rule' }),
{ homeDir: fx.home, cwd: fx.project },
)
expect(plan!.changes[0]).toMatchObject({ op: 'create', expectedHash: null })
await writeFile(claudeMd, '# appeared meanwhile\n')
await expect(runAction(plan!, fx.actionsDir)).rejects.toThrow(/changed since the plan was built/)
expect(await readFile(claudeMd, 'utf-8')).toBe('# appeared meanwhile\n')
expect(await readRecords(fx.actionsDir)).toHaveLength(0)
})
it('applies when the target still matches the expected hash', async () => {
const fx = await makeFixture()
const claudeJson = join(fx.home, '.claude.json')
await writeFile(claudeJson, JSON.stringify({ mcpServers: { s: {} } }, null, 2) + '\n')
const plan = planFor(
makeFinding('mcp-low-coverage', CMD_FIX, { kind: 'mcp-remove', servers: ['s'] }),
{ homeDir: fx.home, cwd: fx.project },
)
expect(plan!.changes[0]!.op === 'move' ? undefined : plan!.changes[0]!.expectedHash).toMatch(/^[0-9a-f]{64}$/)
const rec = await runAction(plan!, fx.actionsDir)
expect(rec.status).toBe('applied')
expect(JSON.parse(await readFile(claudeJson, 'utf-8')).mcpServers).toEqual({})
})
it('a change without expectedHash skips validation (framework back-compat)', async () => {
const fx = await makeFixture()
const p = join(fx.home, 'free.txt')
await writeFile(p, 'anything at all')
const rec = await runAction({
kind: 'claude-md-rule',
description: 'no expected hash',
changes: [{ op: 'edit', path: p, content: 'overwritten' }],
}, fx.actionsDir)
expect(rec.status).toBe('applied')
expect(await readFile(p, 'utf-8')).toBe('overwritten')
})
})
describe('finding class', () => {
it('covers every finding id with a class and a basis', () => {
expect(Object.keys(FINDING_BASIS).sort()).toEqual(Object.keys(FINDING_CLASS).sort())
})
it("classes a finding 'fix' exactly when a plan can be built for it", async () => {
const fx = await makeFixture()
const claudeJson = join(fx.home, '.claude.json')
await writeFile(claudeJson, JSON.stringify({ mcpServers: { srv: { command: 's' } } }, null, 2) + '\n')
const settings = join(fx.project, '.claude', 'settings.json')
await mkdir(join(fx.project, '.claude'), { recursive: true })
await writeFile(settings, JSON.stringify({ env: { ENABLE_TOOL_SEARCH: 'auto' } }, null, 2) + '\n')
const mcpJson = join(fx.project, '.mcp.json')
await writeFile(mcpJson, JSON.stringify({ mcpServers: { pinned: { command: 'x', alwaysLoad: true } } }, null, 2) + '\n')
await mkdir(join(fx.home, '.claude', 'skills', 'ghost'), { recursive: true })
await mkdir(join(fx.home, '.claude', 'agents'), { recursive: true })
await mkdir(join(fx.home, '.claude', 'commands'), { recursive: true })
await writeFile(join(fx.home, '.claude', 'agents', 'ghost.md'), 'x')
await writeFile(join(fx.home, '.claude', 'commands', 'ghost.md'), 'x')
const CLAUDE_MD_FIX: WasteAction = { type: 'paste', destination: 'claude-md', label: '', text: 'rule' }
const SHELL_FIX: WasteAction = { type: 'paste', destination: 'shell-config', label: '', text: 'export X=1' }
const PROMPT_FIX: WasteAction = { type: 'paste', destination: 'prompt', label: '', text: 'ask' }
const OPENER_FIX: WasteAction = { type: 'paste', destination: 'session-opener', label: '', text: 'o' }
// One representative finding per id, carrying the payload its plan
// builder needs. Ids without a builder get a plain prompt fix.
const representatives: Record<FindingId, WasteFinding> = {
'read-edit-ratio': makeFinding('read-edit-ratio', CLAUDE_MD_FIX),
'build-folder-reads': makeFinding('build-folder-reads', CLAUDE_MD_FIX),
'redundant-rereads': makeFinding('redundant-rereads', PROMPT_FIX),
'warmup-heavy': makeFinding('warmup-heavy', SHELL_FIX),
'unused-mcp': makeFinding('unused-mcp', CMD_FIX, { kind: 'mcp-remove', servers: ['srv'] }),
'mcp-low-coverage': makeFinding('mcp-low-coverage', CMD_FIX, { kind: 'mcp-remove', servers: ['srv'] }),
'mcp-project-scope': makeFinding('mcp-project-scope', PROMPT_FIX, {
kind: 'mcp-project-scope',
servers: [{ server: 'srv', keepProjects: [fx.project], removeProjects: [] }],
}),
'mcp-deferral-off': makeFinding('mcp-deferral-off', CMD_FIX, {
kind: 'defer-enable', cause: 'env-false', settingPath: settings, settingScope: 'project settings', value: 'false',
}),
'mcp-alwaysload-hygiene': makeFinding('mcp-alwaysload-hygiene', PROMPT_FIX, {
kind: 'defer-alwaysload',
servers: [{ server: 'pinned', paths: [mcpJson] }],
}),
'mcp-defer-threshold': makeFinding('mcp-defer-threshold', PROMPT_FIX, {
kind: 'defer-threshold', settingPath: settings, settingScope: 'project settings',
value: 'auto', recommendedPercent: 2, removeOverride: false,
}),
'retry-heavy-capabilities': makeFinding('retry-heavy-capabilities', PROMPT_FIX),
'low-worth-sessions': makeFinding('low-worth-sessions', OPENER_FIX),
'context-heavy-sessions': makeFinding('context-heavy-sessions', OPENER_FIX),
'cost-outliers': makeFinding('cost-outliers', OPENER_FIX),
'low-cache-hit-sessions': makeFinding('low-cache-hit-sessions', OPENER_FIX),
'one-hour-cache-unused': makeFinding('one-hour-cache-unused', PROMPT_FIX),
'claude-md-too-long': makeFinding('claude-md-too-long', PROMPT_FIX),
'bash-output-cap': makeFinding('bash-output-cap', SHELL_FIX),
'unused-agents': makeFinding('unused-agents', CMD_FIX, { kind: 'archive', names: ['ghost'] }),
'unused-skills': makeFinding('unused-skills', CMD_FIX, { kind: 'archive', names: ['ghost'] }),
'unused-commands': makeFinding('unused-commands', CMD_FIX, { kind: 'archive', names: ['ghost'] }),
'recurring-context': makeFinding('recurring-context', PROMPT_FIX),
'fast-mode-background': makeFinding('fast-mode-background', PROMPT_FIX),
'long-context-premium': makeFinding('long-context-premium', PROMPT_FIX),
'idle-compaction-blocked': makeFinding('idle-compaction-blocked', PROMPT_FIX),
}
const planCtx: PlanContext = { homeDir: fx.home, cwd: fx.project, shell: '/bin/zsh', claudeVersion: () => '2.1.130' }
for (const finding of Object.values(representatives)) {
const hasPlan = planFor(finding, planCtx) !== null
expect([finding.id, hasPlan]).toEqual([finding.id, findingClass(finding) === 'fix'])
}
})
it("drops to 'nudge' when the instance lacks the payload its plan needs", () => {
const finding = makeFinding('mcp-deferral-off', { type: 'paste', destination: 'shell-config', label: '', text: 'x' })
expect(FINDING_CLASS['mcp-deferral-off']).toBe('fix')
expect(findingClass(finding)).toBe('nudge')
expect(planFor(finding)).toBeNull()
})
})