@able-autonomy/able 0.0.21 → 0.2.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/able.ts +10 -2
- package/config.ts +11 -0
- package/package.json +1 -1
- package/src/audit/bloat/apply.test.ts +81 -0
- package/src/audit/bloat/apply.ts +49 -0
- package/src/{agents → audit/bloat}/blocks.ts +2 -2
- package/src/{agents → audit/bloat}/checks.ts +3 -3
- package/src/audit/bloat/compare.ts +63 -0
- package/src/{agents → audit/bloat}/findings.ts +11 -7
- package/src/{agents → audit/bloat}/grid.ts +6 -6
- package/src/audit/bloat/index.ts +258 -0
- package/src/{agents → audit/bloat}/load.ts +2 -2
- package/src/{agents → audit/bloat}/picker.ts +4 -4
- package/src/audit/bloat/report.ts +286 -0
- package/src/{agents → audit/bloat}/scan.ts +3 -3
- package/src/audit/bloat/show.ts +79 -0
- package/src/audit/bloat/steps.ts +32 -0
- package/src/{agents → audit/bloat}/types.ts +48 -3
- package/src/audit/index.ts +19 -0
- package/src/commit.ts +2 -1
- package/src/git.ts +43 -2
- package/src/push.ts +2 -1
- package/src/ui.ts +3 -0
- package/src/workspaces/fixture.ts +49 -0
- package/src/workspaces/index.ts +3 -1
- package/src/workspaces/ls.ts +56 -11
- package/src/workspaces/merge.ts +31 -15
- package/src/workspaces/new.ts +17 -15
- package/src/workspaces/overlap.test.ts +53 -0
- package/src/workspaces/overlap.ts +86 -0
- package/src/workspaces/preview.test.ts +81 -0
- package/src/workspaces/preview.ts +162 -0
- package/src/workspaces/refresh.ts +26 -24
- package/src/workspaces/rm.ts +6 -1
- package/src/workspaces/services.ts +2 -2
- package/src/workspaces/state.ts +56 -9
- package/src/workspaces/trunk.test.ts +88 -0
- package/sync.ts +5 -2
- package/src/agents/index.ts +0 -198
- package/src/agents/report.ts +0 -211
- package/src/agents/show.ts +0 -73
- package/src/agents/steps.ts +0 -32
- /package/src/{agents → audit/bloat}/kinds.ts +0 -0
|
@@ -0,0 +1,258 @@
|
|
|
1
|
+
// able audit bloat: the bloat diagnostic, the Audit module's first. What a host's agent files load, the rules in them,
|
|
2
|
+
// and where each rule belongs, as a report (knowledge/product/modules/audit.md).
|
|
3
|
+
//
|
|
4
|
+
// able audit bloat status every step in order, one line each, for the latest report
|
|
5
|
+
// able audit bloat scan [--json|--grid] step 1: every agent file, its kind and size (--grid: one box per file)
|
|
6
|
+
// able audit bloat load [--json] step 2: when each file loads, and the words at start per folder
|
|
7
|
+
// able audit bloat blocks [--json|--grid] step 3: the files cut into blocks, with spans and stable ids (--grid: one square per block)
|
|
8
|
+
// able audit bloat checks [--json|--grid] step 4: what the host already enforces (--grid: per folder, per tool)
|
|
9
|
+
// able audit bloat classify [--json] step 5's result: the agent's findings checked against the blocks, drawn by kind
|
|
10
|
+
// able audit bloat propose [--json] step 6's result: each rule not kept with its proposal, or what is still owed
|
|
11
|
+
// able audit bloat report step 7: checks the findings and writes a report to <journal>/bloat/<date>-<hhmm>.json
|
|
12
|
+
// able audit bloat show [<report>] [--step <n>|--json] step 8: a report read back from its file (the latest by default)
|
|
13
|
+
// able audit bloat history [--json] every report, oldest first, one line each: the picker and the trend
|
|
14
|
+
// able audit bloat pick [<yes|no> <n>…]… [--report <report>] step 9: the operator's picks in the latest report, or the one named
|
|
15
|
+
// (no arguments on a terminal: checkboxes)
|
|
16
|
+
// able audit bloat apply [--json] step 10: the yes picks not applied yet, in the order the agent applies them
|
|
17
|
+
// able audit bloat apply --record <n> [<target>] step 10: finding n is applied, to target (its proposal's by default)
|
|
18
|
+
// able audit bloat compare [<report>] [<new>] [--json] step 11: a report against the one before it (the latest by default),
|
|
19
|
+
// or two reports named, old then new
|
|
20
|
+
//
|
|
21
|
+
// Read-only on the host's agent files: the only files written are the findings (by the skill) and the report. The
|
|
22
|
+
// agent changes them at step 10, as the skill says, only when the operator asks.
|
|
23
|
+
|
|
24
|
+
import { basename, join, relative } from 'node:path'
|
|
25
|
+
import { hostRoot, loadConfig } from '../../../config.ts'
|
|
26
|
+
import { confirm, dim, fail, green, tty } from '../../ui.ts'
|
|
27
|
+
import * as apply from './apply.ts'
|
|
28
|
+
import * as blocks from './blocks.ts'
|
|
29
|
+
import * as checks from './checks.ts'
|
|
30
|
+
import * as compare from './compare.ts'
|
|
31
|
+
import * as findings from './findings.ts'
|
|
32
|
+
import * as grid from './grid.ts'
|
|
33
|
+
import * as load from './load.ts'
|
|
34
|
+
import { pickInteractive } from './picker.ts'
|
|
35
|
+
import * as report from './report.ts'
|
|
36
|
+
import * as scan from './scan.ts'
|
|
37
|
+
import * as show from './show.ts'
|
|
38
|
+
import { steps, who } from './steps.ts'
|
|
39
|
+
import type { Compared } from './types.ts'
|
|
40
|
+
|
|
41
|
+
const [sub = '', ...args] = process.argv.slice(4)
|
|
42
|
+
const valued = ['--step', '--report', '--record']
|
|
43
|
+
const names = args.filter((a, i) => !a.startsWith('--') && !valued.includes(args[i - 1] ?? ''))
|
|
44
|
+
const option = (name: string) => (args.includes(name) ? args[args.indexOf(name) + 1] : undefined)
|
|
45
|
+
const stepArg = option('--step')
|
|
46
|
+
const json = args.includes('--json')
|
|
47
|
+
const asGrid = args.includes('--grid')
|
|
48
|
+
const root = hostRoot()
|
|
49
|
+
|
|
50
|
+
/** Each step's result, worked out once and shared by the steps after it. */
|
|
51
|
+
const once = <T>(f: () => T) => {
|
|
52
|
+
let value: { v: T } | undefined
|
|
53
|
+
return () => (value ??= { v: f() }).v
|
|
54
|
+
}
|
|
55
|
+
const files = once(() => scan.listFiles(root))
|
|
56
|
+
const entries = once(() => scan.scan(root, files()))
|
|
57
|
+
|
|
58
|
+
const scope = dim([` root ${root}`, ' scanned the root downwards, gitignored files skipped', ' outside folders above the root and ~/.claude/: counted in the load map (step 2)'].join('\n'))
|
|
59
|
+
|
|
60
|
+
/** A built step: its result, the line `status` prints, and its views. */
|
|
61
|
+
interface Built<T> {
|
|
62
|
+
result: () => T | Promise<T>
|
|
63
|
+
summary: (r: T) => string
|
|
64
|
+
render: (r: T) => string
|
|
65
|
+
grid?: (r: T) => string
|
|
66
|
+
}
|
|
67
|
+
const built = <T>(b: Built<T>) => b as Built<unknown>
|
|
68
|
+
|
|
69
|
+
const cut = once(() => blocks.blocks(root, entries()))
|
|
70
|
+
const classified = once(() => {
|
|
71
|
+
const f = findings.readFindings(join(root, findings.findingsPath)) ?? findings.readFindings(join(root, findings.legacyFindingsPath))
|
|
72
|
+
return f && findings.check(f, cut().blocks)
|
|
73
|
+
})
|
|
74
|
+
|
|
75
|
+
const journal = once(async () => (await loadConfig(root)).journal)
|
|
76
|
+
/** The latest report, or the one named on the command line: `show <report>`, `pick --report <report>`. */
|
|
77
|
+
const latest = once(async () => {
|
|
78
|
+
const path = report.findReport(root, await journal(), sub === 'show' ? names[0] : option('--report'))
|
|
79
|
+
return path ? { path, report: report.readReport(path) } : undefined
|
|
80
|
+
})
|
|
81
|
+
type Latest = Awaited<ReturnType<typeof latest>>
|
|
82
|
+
const requireLatest = async () => (await latest()) ?? fail(option('--report') || (sub === 'show' && names[0]) ? 'no such report' : 'no report yet: able audit bloat report writes one')
|
|
83
|
+
/** Steps 7 to 9 all show the latest report; only their line in `status` differs. */
|
|
84
|
+
const latestView = (summary: (l: NonNullable<Latest>) => string, none: string) =>
|
|
85
|
+
built<Latest>({ result: latest, summary: (l) => (l ? summary(l) : none), render: (l) => (l ? show.render(l.report, l.path, root) : ' No report yet.') })
|
|
86
|
+
|
|
87
|
+
const views: Record<string, Built<unknown>> = {
|
|
88
|
+
scan: built({ result: entries, summary: scan.summary, render: (e) => `${scope}\n\n${scan.render(e)}`, grid: (e) => `${scope}\n\n${grid.files(e)}` }),
|
|
89
|
+
load: built({ result: once(() => load.load(root, entries())), summary: load.summary, render: load.render }),
|
|
90
|
+
blocks: built({ result: cut, summary: blocks.summary, render: blocks.render, grid: grid.blocks }),
|
|
91
|
+
checks: built({ result: once(() => checks.checks(root, entries(), files())), summary: checks.summary, render: checks.render, grid: (c) => grid.enforcement(c, entries()) }),
|
|
92
|
+
classify: built({
|
|
93
|
+
result: classified,
|
|
94
|
+
summary: (c) => (c ? findings.summary(c) : `not run: the skill writes ${findings.findingsPath}`),
|
|
95
|
+
render: (c) =>
|
|
96
|
+
c
|
|
97
|
+
? [grid.byKind(cut(), c), ...(c.errors.length ? ['', ' ERRORS', ...c.errors.map((e) => ` ${e}`)] : [])].join('\n')
|
|
98
|
+
: ` No findings yet: the skill (able-audit-bloat) writes ${findings.findingsPath} at step 5.`,
|
|
99
|
+
}),
|
|
100
|
+
propose: built({
|
|
101
|
+
result: classified,
|
|
102
|
+
summary: (c) => (c ? findings.proposeSummary(c) : 'waits for classify'),
|
|
103
|
+
render: (c) =>
|
|
104
|
+
c
|
|
105
|
+
? c.rules
|
|
106
|
+
.filter((r) => r.kind !== 'keep')
|
|
107
|
+
.map(
|
|
108
|
+
(r) => ` ${r.kind.padEnd(12)} ${r.id}
|
|
109
|
+
${r.proposal ? `→ ${r.proposal.target}: ${r.proposal.change}` : dim('no proposal yet')}`,
|
|
110
|
+
)
|
|
111
|
+
.join('\n')
|
|
112
|
+
: ' No findings yet.',
|
|
113
|
+
}),
|
|
114
|
+
report: latestView((l) => `latest: ${relative(root, l.path)}`, 'not run yet'),
|
|
115
|
+
show: latestView(() => 'able audit bloat show', 'no report yet'),
|
|
116
|
+
pick: latestView((l) => report.tally(l.report).line, 'no report yet'),
|
|
117
|
+
apply: built<apply.Left | undefined>({
|
|
118
|
+
result: once(async () => {
|
|
119
|
+
const l = await latest()
|
|
120
|
+
return l && apply.left(l.report)
|
|
121
|
+
}),
|
|
122
|
+
summary: (t) => (t ? t.line : 'no report yet'),
|
|
123
|
+
render: (t) => (t ? apply.render(t) : ' No report yet.'),
|
|
124
|
+
}),
|
|
125
|
+
compare: built({
|
|
126
|
+
result: pair,
|
|
127
|
+
summary: (p) => (p ? compare.summary(p.c) : 'waits for a second report'),
|
|
128
|
+
render: (p) => (p ? compare.render(p.c, p.names) : ' Nothing to compare: one report so far.'),
|
|
129
|
+
}),
|
|
130
|
+
}
|
|
131
|
+
|
|
132
|
+
/** Step 11's two reports: `compare <old> <new>`, or one report (the latest by default) and the one before it. */
|
|
133
|
+
async function pair(): Promise<Compared | undefined> {
|
|
134
|
+
const dir = await journal()
|
|
135
|
+
const all = report.reports(root, dir)
|
|
136
|
+
const find = (name: string) => report.findReport(root, dir, name)
|
|
137
|
+
const next = names[1] ? find(names[1]) : names[0] ? find(names[0]) : all.at(-1)
|
|
138
|
+
const old = names[1] ? find(names[0]!) : next && all[all.indexOf(next) - 1]
|
|
139
|
+
if (!old || !next) return
|
|
140
|
+
const name = (p: string) => basename(p, '.json')
|
|
141
|
+
return { c: compare.compare(report.readReport(old), report.readReport(next)), names: { old: name(old), next: name(next) } }
|
|
142
|
+
}
|
|
143
|
+
|
|
144
|
+
/** Step 10's record: finding n was applied, to the target named or its proposal's. */
|
|
145
|
+
async function recordApplied() {
|
|
146
|
+
const l = await requireLatest()
|
|
147
|
+
const n = Number(option('--record'))
|
|
148
|
+
if (!Number.isInteger(n) || n < 1) fail('usage: able audit bloat apply --record <n> [<target>]')
|
|
149
|
+
const r = await apply.record(l.path, l.report, n, names[0])
|
|
150
|
+
if (typeof r === 'string') fail(r)
|
|
151
|
+
if (json) return console.log(JSON.stringify({ report: relative(root, l.path), n, applied: r.applied }))
|
|
152
|
+
console.log(`\n ${green('recorded')} ${n} applied, to ${r.applied!.target} ${dim(report.applyTally(l.report).line)}\n`)
|
|
153
|
+
}
|
|
154
|
+
|
|
155
|
+
/** Step 7: refuses while the findings owe anything, then writes the report and shows it. */
|
|
156
|
+
async function writeReport() {
|
|
157
|
+
const c = classified()
|
|
158
|
+
if (!c) fail(`no findings: the skill writes ${findings.findingsPath} at steps 5 and 6`)
|
|
159
|
+
const owed = report.problems(c)
|
|
160
|
+
if (owed.length) fail(`the findings are not ready:\n${owed.map((p) => ` ${p}`).join('\n')}`)
|
|
161
|
+
const summaries: Record<string, string> = {}
|
|
162
|
+
for (const id of ['scan', 'load', 'blocks', 'checks', 'classify', 'propose']) summaries[id] = views[id].summary(await views[id].result())
|
|
163
|
+
const at = new Date()
|
|
164
|
+
const path = report.reportPath(root, await journal(), at)
|
|
165
|
+
const before = report.findReport(root, await journal())
|
|
166
|
+
const written = report.build({
|
|
167
|
+
scan: entries(),
|
|
168
|
+
load: (await views.load.result()) as load.LoadMap,
|
|
169
|
+
blocks: cut(),
|
|
170
|
+
checks: (await views.checks.result()) as checks.Checks,
|
|
171
|
+
checked: c,
|
|
172
|
+
summaries,
|
|
173
|
+
root,
|
|
174
|
+
path,
|
|
175
|
+
at,
|
|
176
|
+
previous: before ? report.readReport(before) : undefined,
|
|
177
|
+
})
|
|
178
|
+
await report.saveReport(path, written)
|
|
179
|
+
console.log(`\n ${green('wrote')} ${relative(root, path)}\n\n${show.render(written, path, root)}\n`)
|
|
180
|
+
}
|
|
181
|
+
|
|
182
|
+
/** Step 9: on a terminal with no arguments, the checkbox picker; otherwise `pick yes 1 3 5`, `pick no 2`, or both at
|
|
183
|
+
* once, `pick yes 1 3 no 2` (the dashboard's page records its checkboxes this way). */
|
|
184
|
+
async function writePicks() {
|
|
185
|
+
const l = await requireLatest()
|
|
186
|
+
let answers: Map<number, 'yes' | 'no'> | undefined
|
|
187
|
+
if (!names.length && tty && process.stdin.isTTY) {
|
|
188
|
+
answers = await pickInteractive(l.report, l.path, root)
|
|
189
|
+
if (!answers) return console.log('\n Nothing recorded.\n')
|
|
190
|
+
} else if (names[0] === 'yes' || names[0] === 'no') {
|
|
191
|
+
answers = new Map()
|
|
192
|
+
let answer: 'yes' | 'no' = names[0]
|
|
193
|
+
for (const x of names.slice(1))
|
|
194
|
+
if (x === 'yes' || x === 'no') answer = x
|
|
195
|
+
else if (/^\d+$/.test(x)) answers.set(Number(x), answer)
|
|
196
|
+
else fail(`not a finding number: ${x}`)
|
|
197
|
+
} else fail('usage: able audit bloat pick [<yes|no> <n>…]… [--report <report>] (no arguments on a terminal opens the checkboxes)')
|
|
198
|
+
const unknown = await report.pick(l.path, l.report, answers)
|
|
199
|
+
if (unknown.length) fail(`no finding numbered ${unknown.join(', ')} in ${relative(root, l.path)}`)
|
|
200
|
+
const { yes, no, open } = report.tally(l.report)
|
|
201
|
+
if (json) return console.log(JSON.stringify({ report: relative(root, l.path), yes, no, open }))
|
|
202
|
+
console.log(`\n ${green('recorded')} ${yes} yes, ${no} no, ${open} not picked, in ${relative(root, l.path)}\n`)
|
|
203
|
+
}
|
|
204
|
+
|
|
205
|
+
async function status() {
|
|
206
|
+
console.log()
|
|
207
|
+
for (const step of steps) {
|
|
208
|
+
const label = ` ${String(step.n).padStart(2)} ${who[step.kind]} ${step.id.padEnd(10)}`
|
|
209
|
+
const view = views[step.id]
|
|
210
|
+
if (!view) {
|
|
211
|
+
console.log(`${label} ${dim('not built yet')}`)
|
|
212
|
+
continue
|
|
213
|
+
}
|
|
214
|
+
const started = performance.now()
|
|
215
|
+
const result = await view.result()
|
|
216
|
+
const summary = view.summary(result)
|
|
217
|
+
const done = result !== undefined ? `${green('ok')} ${dim(`${Math.round(performance.now() - started)}ms`)}` : ''
|
|
218
|
+
console.log(`${label} ${result !== undefined ? summary.padEnd(44) : dim(summary)} ${done}`.trimEnd())
|
|
219
|
+
}
|
|
220
|
+
console.log(dim('\n M mechanical (the CLI) · A agent · O operator (you)\n'))
|
|
221
|
+
// On a terminal, step 9 follows on: the latest report's unpicked findings, as checkboxes.
|
|
222
|
+
const l = await latest()
|
|
223
|
+
if (l && tty && process.stdin.isTTY && report.tally(l.report).open && confirm('Pick now?')) await writePicks()
|
|
224
|
+
}
|
|
225
|
+
|
|
226
|
+
// `run` was its name before the report vocabulary.
|
|
227
|
+
if (sub === 'status' || sub === 'run') await status()
|
|
228
|
+
else if (sub === 'report') await writeReport()
|
|
229
|
+
else if (sub === 'pick') await writePicks()
|
|
230
|
+
else if (sub === 'apply' && args.includes('--record')) await recordApplied()
|
|
231
|
+
else if (sub === 'history') {
|
|
232
|
+
const lines = report.history(root, await journal())
|
|
233
|
+
if (json) console.log(JSON.stringify(lines))
|
|
234
|
+
else {
|
|
235
|
+
console.log()
|
|
236
|
+
for (const h of lines)
|
|
237
|
+
console.log(
|
|
238
|
+
` ${h.code} ${h.name} ${String(h.files).padStart(3)} files ${String(h.rules).padStart(4)} rules ${String(h.start.before).padStart(6)} → ${String(h.start.after).padStart(6)} words at start ${h.picks.yes + h.picks.no} of ${h.picks.numbered} picked`,
|
|
239
|
+
)
|
|
240
|
+
console.log(lines.length ? '' : ' No report yet.\n')
|
|
241
|
+
}
|
|
242
|
+
} else if (sub === 'show' && stepArg) {
|
|
243
|
+
const l = await requireLatest()
|
|
244
|
+
const id = l.report.steps.find((s) => String(s.n) === stepArg || s.id === stepArg)?.id
|
|
245
|
+
if (!id) fail(`no step ${stepArg}: 1 to ${l.report.steps.length}, or a name`)
|
|
246
|
+
console.log(`\n${show.step(l.report, id)}\n`)
|
|
247
|
+
} else if (sub === 'show' && json) console.log(JSON.stringify((await requireLatest()).report))
|
|
248
|
+
else if (views[sub]) {
|
|
249
|
+
const view = views[sub]
|
|
250
|
+
const r = await view.result()
|
|
251
|
+
// Nothing to show is `null` in JSON, so a reader always gets JSON.
|
|
252
|
+
console.log(json ? JSON.stringify(r ?? null) : `\n${asGrid && view.grid ? view.grid(r) : view.render(r)}\n`)
|
|
253
|
+
} else {
|
|
254
|
+
console.error(`usage: able audit bloat status | ${Object.keys(views).join(' | ')} [--json] [--grid]`)
|
|
255
|
+
process.exit(sub ? 1 : 0)
|
|
256
|
+
}
|
|
257
|
+
|
|
258
|
+
export {}
|
|
@@ -140,14 +140,14 @@ export function load(root: string, entries: Entry[]): LoadMap {
|
|
|
140
140
|
return { files, folders, outside }
|
|
141
141
|
}
|
|
142
142
|
|
|
143
|
-
/** One line for `able
|
|
143
|
+
/** One line for `able audit bloat status`. */
|
|
144
144
|
export function summary(map: LoadMap) {
|
|
145
145
|
const words = map.folders.map((f) => f.host)
|
|
146
146
|
const range = words.length > 1 ? `${n(Math.min(...words))}-${n(Math.max(...words))}` : n(words[0] ?? 0)
|
|
147
147
|
return `${map.folders.length} folder${map.folders.length === 1 ? '' : 's'}, ${range} at start, +${n(map.folders[0]?.outside ?? 0)} outside`
|
|
148
148
|
}
|
|
149
149
|
|
|
150
|
-
/** The human view of `able
|
|
150
|
+
/** The human view of `able audit bloat load`. */
|
|
151
151
|
export function render(map: LoadMap) {
|
|
152
152
|
const out: string[] = []
|
|
153
153
|
const width = Math.min(40, Math.max(4, ...map.files.map((f) => f.path.length)))
|
|
@@ -3,9 +3,9 @@
|
|
|
3
3
|
// Plain keys and ANSI codes on Bun's raw stdin, no dependency; outside a terminal, `pick yes|no <n>…` does the same.
|
|
4
4
|
|
|
5
5
|
import { relative } from 'node:path'
|
|
6
|
-
import { bold, dim, paint256 } from '
|
|
6
|
+
import { bold, dim, paint256 } from '../../ui.ts'
|
|
7
7
|
import { kinds } from './kinds.ts'
|
|
8
|
-
import type {
|
|
8
|
+
import type { Report } from './report.ts'
|
|
9
9
|
import { clip, fit } from './scan.ts'
|
|
10
10
|
|
|
11
11
|
const perPage = 10
|
|
@@ -18,8 +18,8 @@ const key = () =>
|
|
|
18
18
|
})
|
|
19
19
|
|
|
20
20
|
/** Lets the operator check findings on a terminal. Returns the answers to record, or undefined when they quit. */
|
|
21
|
-
export async function pickInteractive(
|
|
22
|
-
const items =
|
|
21
|
+
export async function pickInteractive(report: Report, path: string, root: string): Promise<Map<number, 'yes' | 'no'> | undefined> {
|
|
22
|
+
const items = report.rules.filter((r) => r.n)
|
|
23
23
|
if (!items.length) return new Map()
|
|
24
24
|
const checked = new Set(items.filter((r) => (r.pick ?? r.recommend) === 'yes').map((r) => r.n!))
|
|
25
25
|
const pages = Math.ceil(items.length / perPage)
|
|
@@ -0,0 +1,286 @@
|
|
|
1
|
+
// Step 7, report: checks the agent's findings (every block classified, every rule not kept proposed), merges them with
|
|
2
|
+
// steps 1 to 4, works out the impact, and writes the report to `<journal>/bloat/<yyyy-mm-dd>-<hhmm>.json`. Every report is
|
|
3
|
+
// kept. Step 9's picks are written into the same file by `able audit bloat pick`. The report is the one source `show` and the
|
|
4
|
+
// dashboard read; it holds each rule's span, so a view can highlight its words.
|
|
5
|
+
//
|
|
6
|
+
// On disk (`able.bloat.report@1`) a rule keeps no copy of its words or its path: both come from its block (the block's
|
|
7
|
+
// text at the rule's span), filled in again by `readReport`. Reports from before the rename (`able.agents@1`, which
|
|
8
|
+
// stored both, and `able.agents@2`, the same as now) still read, from the old folder too (steps.ts, legacyReportsDir).
|
|
9
|
+
// A report is written again only by `pick`, in the current format.
|
|
10
|
+
|
|
11
|
+
import { existsSync, mkdirSync, readdirSync, readFileSync } from 'node:fs'
|
|
12
|
+
import { basename, dirname, join, relative } from 'node:path'
|
|
13
|
+
import type { Blocks } from './blocks.ts'
|
|
14
|
+
import type { Checks } from './checks.ts'
|
|
15
|
+
import type { Checked, Rule } from './findings.ts'
|
|
16
|
+
import { unproposed } from './findings.ts'
|
|
17
|
+
import { pickOrder, type Kind } from './kinds.ts'
|
|
18
|
+
import { chain, type LoadMap } from './load.ts'
|
|
19
|
+
import { countWords, type Entry } from './scan.ts'
|
|
20
|
+
import { legacyReportsDir, reportsDir, steps } from './steps.ts'
|
|
21
|
+
import type { Finding, HistoryLine, Report } from './types.ts'
|
|
22
|
+
|
|
23
|
+
export type { Finding, HistoryLine, Report }
|
|
24
|
+
|
|
25
|
+
export const format = 'able.bloat.report@1'
|
|
26
|
+
|
|
27
|
+
/** The formats `readReport` reads: every one written so far. */
|
|
28
|
+
export const formats = ['able.agents@1', 'able.agents@2', format] as const satisfies Report['format'][]
|
|
29
|
+
|
|
30
|
+
/** Kinds whose words leave the start-up set once applied: everything but keep, and a conflict until it is picked. */
|
|
31
|
+
const leaves = (k: Kind) => k !== 'keep' && k !== 'conflict'
|
|
32
|
+
|
|
33
|
+
/** Whether a rule's words load at start for an agent in `folder`: its file is an instruction file or always-on rule in
|
|
34
|
+
* the folder's chain, or it is a skill's description. */
|
|
35
|
+
export function atStart(load: LoadMap, blocks: Blocks) {
|
|
36
|
+
const fileLoad = new Map(load.files.map((f) => [f.path, f]))
|
|
37
|
+
const blockOf = new Map(blocks.blocks.map((b) => [b.id, b]))
|
|
38
|
+
return (r: { path: string; block: string }, folder: string) => {
|
|
39
|
+
const f = fileLoad.get(r.path)
|
|
40
|
+
if (!f) return false
|
|
41
|
+
if (f.load === 'skill') return blockOf.get(r.block)?.heading[0] === 'description'
|
|
42
|
+
return (f.load === 'always' || f.load === 'folder') && chain(folder).includes(f.folder)
|
|
43
|
+
}
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
const words = (s: string) => new Set(s.toLowerCase().match(/[a-z0-9]+/g) ?? [])
|
|
47
|
+
/** How alike two sets of words are, 0 to 1: the share of their words they have in common. */
|
|
48
|
+
function alike(x: Set<string>, y: Set<string>) {
|
|
49
|
+
const both = [...x].filter((w) => y.has(w)).length
|
|
50
|
+
return both / (x.size + y.size - both || 1)
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
/** Lineage: for each rule, the applied finding of the report before whose words it carries, in the file the finding
|
|
54
|
+
* was applied to. Half alike or more counts; the most alike wins. */
|
|
55
|
+
export function lineage(previous: Report | undefined) {
|
|
56
|
+
const applied = (previous?.rules ?? []).flatMap((r) => (r.applied ? [{ id: r.id, target: r.applied.target, words: words(r.text) }] : []))
|
|
57
|
+
return (r: { path: string; text: string }) => {
|
|
58
|
+
const mine = words(r.text)
|
|
59
|
+
let best: { id: string; score: number } | undefined
|
|
60
|
+
for (const a of applied) {
|
|
61
|
+
if (a.target !== r.path) continue
|
|
62
|
+
const score = alike(a.words, mine)
|
|
63
|
+
if (score >= 0.5 && score > (best?.score ?? 0)) best = { id: a.id, score }
|
|
64
|
+
}
|
|
65
|
+
return best?.id
|
|
66
|
+
}
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
export function reportsFolder(root: string, journal: string) {
|
|
70
|
+
return join(root, journal, reportsDir)
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
/** The report files, oldest first, from the folder and the one before the rename; a name in both is the folder's. */
|
|
74
|
+
export function reports(root: string, journal: string) {
|
|
75
|
+
const byName = new Map<string, string>()
|
|
76
|
+
for (const name of [reportsDir, legacyReportsDir]) {
|
|
77
|
+
const dir = join(root, journal, name)
|
|
78
|
+
if (existsSync(dir)) for (const f of readdirSync(dir)) if (/^\d{4}-\d{2}-\d{2}-\d{4}\.json$/.test(f) && !byName.has(f)) byName.set(f, join(dir, f))
|
|
79
|
+
}
|
|
80
|
+
return [...byName.values()].sort((a, b) => basename(a).localeCompare(basename(b)))
|
|
81
|
+
}
|
|
82
|
+
|
|
83
|
+
/** A report from its text, whichever format it was written in, with each rule's words and path filled in from its block. */
|
|
84
|
+
export function parseReport(text: string): Report {
|
|
85
|
+
const report = JSON.parse(text) as Report
|
|
86
|
+
if (!formats.includes(report.format)) throw new Error(`a report in format ${JSON.stringify(report.format)}: this able reads ${formats.join(' and ')}`)
|
|
87
|
+
const blockOf = new Map(report.blocks.blocks.map((b) => [b.id, b]))
|
|
88
|
+
for (const r of report.rules) {
|
|
89
|
+
const b = blockOf.get(r.block)
|
|
90
|
+
if (!b) continue
|
|
91
|
+
r.path ??= b.path
|
|
92
|
+
r.text ??= b.text.slice(r.span[0] - b.span[0], r.span[1] - b.span[0])
|
|
93
|
+
}
|
|
94
|
+
return report
|
|
95
|
+
}
|
|
96
|
+
|
|
97
|
+
export const readReport = (path: string) => parseReport(readFileSync(path, 'utf8'))
|
|
98
|
+
|
|
99
|
+
/** A report file by its name or the start of it (`2026-11-16`, `2026-11-16-2240`), or its code (`K3M9QA`); else the
|
|
100
|
+
* latest. */
|
|
101
|
+
export function findReport(root: string, journal: string, name?: string) {
|
|
102
|
+
const all = reports(root, journal)
|
|
103
|
+
if (!name) return all.at(-1)
|
|
104
|
+
const asked = name.replace(/\.json$/, '')
|
|
105
|
+
return all.filter((p) => basename(p).startsWith(asked) || reportCode(basename(p, '.json')) === asked.toUpperCase()).at(-1)
|
|
106
|
+
}
|
|
107
|
+
|
|
108
|
+
/** What blocks the report: findings errors, blocks not classified, rules not proposed. */
|
|
109
|
+
export function problems(c: Checked) {
|
|
110
|
+
return [...c.errors, ...c.missing.map((id) => `${id}: not classified`), ...unproposed(c).map((r) => `${r.id}: ${r.kind}, no proposal yet`)]
|
|
111
|
+
}
|
|
112
|
+
|
|
113
|
+
/** Step 10's tally: yes picks applied, and still to apply. */
|
|
114
|
+
export function applyTally(report: Report) {
|
|
115
|
+
const yes = report.rules.filter((r) => r.n && r.pick === 'yes')
|
|
116
|
+
const applied = yes.filter((r) => r.applied).length
|
|
117
|
+
return { applied, left: yes.length - applied, line: yes.length ? `${applied} applied, ${yes.length - applied} to apply` : 'waits for yes picks' }
|
|
118
|
+
}
|
|
119
|
+
|
|
120
|
+
/** The step lines that change after a report is written (picks, applies), worked out again from the report; a report
|
|
121
|
+
* from before a step existed gains it. */
|
|
122
|
+
function refreshSteps(report: Report) {
|
|
123
|
+
for (const s of steps) if (!report.steps.some((x) => x.id === s.id)) report.steps.push({ n: s.n, id: s.id, kind: s.kind, summary: '' })
|
|
124
|
+
const lines: Record<string, string> = { pick: tally(report).line, apply: applyTally(report).line }
|
|
125
|
+
for (const s of report.steps) if (s.id in lines) s.summary = lines[s.id]!
|
|
126
|
+
}
|
|
127
|
+
|
|
128
|
+
/** Step 9's tally: findings to pick, and the answers so far. */
|
|
129
|
+
export function tally(report: Report) {
|
|
130
|
+
const numbered = report.rules.filter((r) => r.n)
|
|
131
|
+
const yes = numbered.filter((r) => r.pick === 'yes').length
|
|
132
|
+
const no = numbered.filter((r) => r.pick === 'no').length
|
|
133
|
+
return { numbered: numbered.length, yes, no, open: numbered.length - yes - no, line: `${yes + no} of ${numbered.length} picked` }
|
|
134
|
+
}
|
|
135
|
+
|
|
136
|
+
// Letters and digits that can't be mistaken for each other read aloud or copied by hand: no 0/O, no 1/I/L.
|
|
137
|
+
const codeAlphabet = 'ABCDEFGHJKMNPQRSTUVWXYZ23456789'
|
|
138
|
+
/** A report's short handle (as conformance reports have, `X7E5LI`), from its name, so it needs no storing and never
|
|
139
|
+
* changes: the name's FNV-1a hash in six of `codeAlphabet`'s characters. */
|
|
140
|
+
export function reportCode(name: string) {
|
|
141
|
+
let h = 0x811c9dc5
|
|
142
|
+
for (const ch of name) h = Math.imul(h ^ ch.charCodeAt(0), 0x01000193) >>> 0
|
|
143
|
+
let code = ''
|
|
144
|
+
for (let i = 0; i < 6; i++, h = Math.floor(h / codeAlphabet.length)) code += codeAlphabet[h % codeAlphabet.length]
|
|
145
|
+
return code
|
|
146
|
+
}
|
|
147
|
+
|
|
148
|
+
/** A report's line in the history: the picker's label and the trend's point. */
|
|
149
|
+
export function historyLine(path: string, report: Report, from = ''): HistoryLine {
|
|
150
|
+
const root = report.impact.folders.find((f) => f.folder === '.')
|
|
151
|
+
const { line: _line, ...picks } = tally(report)
|
|
152
|
+
const name = basename(path, '.json')
|
|
153
|
+
return {
|
|
154
|
+
name,
|
|
155
|
+
code: reportCode(name),
|
|
156
|
+
file: from ? relative(from, path) : path,
|
|
157
|
+
format: report.format,
|
|
158
|
+
at: report.at,
|
|
159
|
+
files: report.scan.length,
|
|
160
|
+
rules: report.rules.length,
|
|
161
|
+
start: { before: root?.before ?? 0, after: root?.after ?? 0 },
|
|
162
|
+
byKind: Object.fromEntries(Object.entries(report.impact.byKind).map(([k, v]) => [k, v.rules])),
|
|
163
|
+
picks,
|
|
164
|
+
}
|
|
165
|
+
}
|
|
166
|
+
|
|
167
|
+
/** Every report's line, oldest first. */
|
|
168
|
+
export const history = (root: string, journal: string) => reports(root, journal).map((p) => historyLine(p, readReport(p), root))
|
|
169
|
+
|
|
170
|
+
/** Builds the report. `path` is where it will be written; `summaries` are steps 1 to 6's lines, the rest are worked out here. */
|
|
171
|
+
export function build(input: {
|
|
172
|
+
scan: Entry[]
|
|
173
|
+
load: LoadMap
|
|
174
|
+
blocks: Blocks
|
|
175
|
+
checks: Checks
|
|
176
|
+
checked: Checked
|
|
177
|
+
summaries: Record<string, string>
|
|
178
|
+
root: string
|
|
179
|
+
path: string
|
|
180
|
+
at: Date
|
|
181
|
+
/** The report before this one: its picks carry forward by rule id, so what was answered isn't asked again. */
|
|
182
|
+
previous?: Report
|
|
183
|
+
}): Report {
|
|
184
|
+
const { scan, load, blocks, checks, checked } = input
|
|
185
|
+
const earlier = new Map(input.previous?.rules.flatMap((r) => (r.pick ? [[r.id, r.pick] as const] : [])))
|
|
186
|
+
const cameFrom = lineage(input.previous)
|
|
187
|
+
const blockOf = new Map(blocks.blocks.map((b) => [b.id, b]))
|
|
188
|
+
let n = 0
|
|
189
|
+
const rules = checked.rules
|
|
190
|
+
.map((r) => {
|
|
191
|
+
const b = blockOf.get(r.block)!
|
|
192
|
+
const line = b.lines[0] + b.text.slice(0, r.span[0] - b.span[0]).split('\n').length - 1
|
|
193
|
+
const from = cameFrom(r)
|
|
194
|
+
return { ...r, line, words: countWords(r.text), ...(from && { from }) }
|
|
195
|
+
})
|
|
196
|
+
.sort((a, b) => pickOrder.indexOf(a.kind) - pickOrder.indexOf(b.kind) || a.path.localeCompare(b.path) || a.span[0] - b.span[0])
|
|
197
|
+
.map((r) => (r.kind === 'keep' ? r : { ...r, n: ++n, ...(earlier.has(r.id) && { pick: earlier.get(r.id) }) }))
|
|
198
|
+
|
|
199
|
+
const starts = atStart(load, blocks)
|
|
200
|
+
const folders = load.folders.map((f) => ({
|
|
201
|
+
folder: f.folder,
|
|
202
|
+
before: f.host,
|
|
203
|
+
after: f.host - rules.filter((r) => leaves(r.kind) && starts(r, f.folder)).reduce((s, r) => s + r.words, 0),
|
|
204
|
+
}))
|
|
205
|
+
const byKind: Report['impact']['byKind'] = {}
|
|
206
|
+
for (const r of rules) {
|
|
207
|
+
const k = (byKind[r.kind] ??= { rules: 0, words: 0 })
|
|
208
|
+
k.rules++
|
|
209
|
+
k.words += r.words
|
|
210
|
+
}
|
|
211
|
+
|
|
212
|
+
const pathRules = scan.some((e) => e.kind === 'rule')
|
|
213
|
+
const agentsMd = scan
|
|
214
|
+
.filter((e) => e.kind === 'instructions' && e.path.endsWith('CLAUDE.md') && !e.path.endsWith('CLAUDE.local.md'))
|
|
215
|
+
.map((e) => {
|
|
216
|
+
const dir = dirname(e.path)
|
|
217
|
+
const at = (name: string) => (dir === '.' ? name : `${dir}/${name}`)
|
|
218
|
+
const blockers = [
|
|
219
|
+
...(existsSync(join(input.root, at('CLAUDE.local.md'))) ? ['a CLAUDE.local.md beside it stops Claude reading AGENTS.md'] : []),
|
|
220
|
+
...(scan.some((x) => x.path === at('AGENTS.md')) ? ['an AGENTS.md already exists beside it: merge, do not overwrite'] : []),
|
|
221
|
+
...(pathRules && dir === '.' ? ['.claude/rules with paths: are Claude-only and stay where they are'] : []),
|
|
222
|
+
]
|
|
223
|
+
return { path: e.path, blockers }
|
|
224
|
+
})
|
|
225
|
+
|
|
226
|
+
const root = folders.find((f) => f.folder === '.')
|
|
227
|
+
const summaries: Record<string, string> = {
|
|
228
|
+
...input.summaries,
|
|
229
|
+
report: relative(input.root, input.path),
|
|
230
|
+
show: `${root ? root.before - root.after : 0} words leave the root's start`,
|
|
231
|
+
compare: input.previous ? 'able audit bloat compare: this report against the one before' : 'waits for a second report',
|
|
232
|
+
}
|
|
233
|
+
const report: Report = {
|
|
234
|
+
format,
|
|
235
|
+
at: input.at.toISOString(),
|
|
236
|
+
steps: steps.map((s) => ({ n: s.n, id: s.id, kind: s.kind, summary: summaries[s.id] ?? '' })),
|
|
237
|
+
scan,
|
|
238
|
+
load,
|
|
239
|
+
blocks,
|
|
240
|
+
checks,
|
|
241
|
+
rules,
|
|
242
|
+
impact: { folders, byKind },
|
|
243
|
+
agentsMd,
|
|
244
|
+
}
|
|
245
|
+
refreshSteps(report)
|
|
246
|
+
return report
|
|
247
|
+
}
|
|
248
|
+
|
|
249
|
+
/** The report's file name: local date and time, so two reports a minute apart are both kept. */
|
|
250
|
+
export function reportName(at = new Date()) {
|
|
251
|
+
const p = (v: number) => String(v).padStart(2, '0')
|
|
252
|
+
return `${at.getFullYear()}-${p(at.getMonth() + 1)}-${p(at.getDate())}-${p(at.getHours())}${p(at.getMinutes())}.json`
|
|
253
|
+
}
|
|
254
|
+
|
|
255
|
+
/** Where a report taken at `at` is written. */
|
|
256
|
+
export const reportPath = (root: string, journal: string, at: Date) => join(reportsFolder(root, journal), reportName(at))
|
|
257
|
+
|
|
258
|
+
/** JSON broken into lines down to the lists (rules, blocks, files), each of their items on one line: small, and still a
|
|
259
|
+
* readable diff. */
|
|
260
|
+
export function lines(value: unknown, depth = 0): string {
|
|
261
|
+
const flat = JSON.stringify(value)
|
|
262
|
+
if (value === null || typeof value !== 'object' || flat.length <= 100 || depth > 2 || (depth === 2 && !Array.isArray(value))) return flat
|
|
263
|
+
const pad = ' '.repeat(depth + 1)
|
|
264
|
+
const items = Array.isArray(value) ? value.map((v) => lines(v, depth + 1)) : Object.entries(value).map(([k, v]) => `${JSON.stringify(k)}: ${lines(v, depth + 1)}`)
|
|
265
|
+
const [open, close] = Array.isArray(value) ? ['[', ']'] : ['{', '}']
|
|
266
|
+
return `${open}\n${items.map((i) => pad + i).join(',\n')}\n${' '.repeat(depth)}${close}`
|
|
267
|
+
}
|
|
268
|
+
|
|
269
|
+
/** Writes a report file, always in the current format, its step lines up to date; the one place its form on disk is set. */
|
|
270
|
+
export async function saveReport(path: string, report: Report) {
|
|
271
|
+
mkdirSync(dirname(path), { recursive: true })
|
|
272
|
+
refreshSteps(report)
|
|
273
|
+
const rules = report.rules.map(({ text: _text, path: _path, ...r }) => r)
|
|
274
|
+
await Bun.write(path, `${lines({ ...report, format, rules })}\n`)
|
|
275
|
+
}
|
|
276
|
+
|
|
277
|
+
/** Step 9: records the operator's yes or no on numbered findings in the report, and saves it. An applied finding keeps
|
|
278
|
+
* its yes. */
|
|
279
|
+
export async function pick(path: string, report: Report, answers: Map<number, 'yes' | 'no'>) {
|
|
280
|
+
const known = new Set(report.rules.flatMap((r) => (r.n ? [r.n] : [])))
|
|
281
|
+
const unknown = [...answers.keys()].filter((x) => !known.has(x))
|
|
282
|
+
if (unknown.length) return unknown
|
|
283
|
+
for (const r of report.rules) if (r.n && answers.has(r.n) && !r.applied) r.pick = answers.get(r.n)
|
|
284
|
+
await saveReport(path, report)
|
|
285
|
+
return unknown
|
|
286
|
+
}
|
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
|
|
4
4
|
import { existsSync, lstatSync, readFileSync, realpathSync } from 'node:fs'
|
|
5
5
|
import { join, relative } from 'node:path'
|
|
6
|
-
import { lines as gitLines } from '
|
|
6
|
+
import { lines as gitLines } from '../../git.ts'
|
|
7
7
|
import type { FileKind, SkillOrigin, Entry } from './types.ts'
|
|
8
8
|
|
|
9
9
|
export type { FileKind, SkillOrigin, Entry }
|
|
@@ -81,13 +81,13 @@ export function scan(root: string, files: string[]): Entry[] {
|
|
|
81
81
|
.sort((a, b) => a.path.localeCompare(b.path))
|
|
82
82
|
}
|
|
83
83
|
|
|
84
|
-
/** One line for `able
|
|
84
|
+
/** One line for `able audit bloat status`. */
|
|
85
85
|
export const summary = (entries: Entry[]) => `${entries.length} files, ${n(entries.reduce((sum, e) => sum + e.words, 0))} words`
|
|
86
86
|
|
|
87
87
|
/** A path cut in the middle to fit, so the view stays narrow enough for a terminal and a chat. */
|
|
88
88
|
export const fit = (path: string, max: number) => (path.length <= max ? path : `${path.slice(0, 12)}...${path.slice(-(max - 15))}`)
|
|
89
89
|
|
|
90
|
-
/** The human view of `able
|
|
90
|
+
/** The human view of `able audit bloat scan`. */
|
|
91
91
|
export function render(entries: Entry[]) {
|
|
92
92
|
const width = Math.min(48, Math.max(4, ...entries.map((e) => e.path.length)))
|
|
93
93
|
const lines = [` ${'PATH'.padEnd(width)} ${'KIND'.padEnd(16)} ${'WORDS'.padStart(6)} ${'LINES'.padStart(5)}`]
|