@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.
Files changed (43) hide show
  1. package/able.ts +10 -2
  2. package/config.ts +11 -0
  3. package/package.json +1 -1
  4. package/src/audit/bloat/apply.test.ts +81 -0
  5. package/src/audit/bloat/apply.ts +49 -0
  6. package/src/{agents → audit/bloat}/blocks.ts +2 -2
  7. package/src/{agents → audit/bloat}/checks.ts +3 -3
  8. package/src/audit/bloat/compare.ts +63 -0
  9. package/src/{agents → audit/bloat}/findings.ts +11 -7
  10. package/src/{agents → audit/bloat}/grid.ts +6 -6
  11. package/src/audit/bloat/index.ts +258 -0
  12. package/src/{agents → audit/bloat}/load.ts +2 -2
  13. package/src/{agents → audit/bloat}/picker.ts +4 -4
  14. package/src/audit/bloat/report.ts +286 -0
  15. package/src/{agents → audit/bloat}/scan.ts +3 -3
  16. package/src/audit/bloat/show.ts +79 -0
  17. package/src/audit/bloat/steps.ts +32 -0
  18. package/src/{agents → audit/bloat}/types.ts +48 -3
  19. package/src/audit/index.ts +19 -0
  20. package/src/commit.ts +2 -1
  21. package/src/git.ts +43 -2
  22. package/src/push.ts +2 -1
  23. package/src/ui.ts +3 -0
  24. package/src/workspaces/fixture.ts +49 -0
  25. package/src/workspaces/index.ts +3 -1
  26. package/src/workspaces/ls.ts +56 -11
  27. package/src/workspaces/merge.ts +31 -15
  28. package/src/workspaces/new.ts +17 -15
  29. package/src/workspaces/overlap.test.ts +53 -0
  30. package/src/workspaces/overlap.ts +86 -0
  31. package/src/workspaces/preview.test.ts +81 -0
  32. package/src/workspaces/preview.ts +162 -0
  33. package/src/workspaces/refresh.ts +26 -24
  34. package/src/workspaces/rm.ts +6 -1
  35. package/src/workspaces/services.ts +2 -2
  36. package/src/workspaces/state.ts +56 -9
  37. package/src/workspaces/trunk.test.ts +88 -0
  38. package/sync.ts +5 -2
  39. package/src/agents/index.ts +0 -198
  40. package/src/agents/report.ts +0 -211
  41. package/src/agents/show.ts +0 -73
  42. package/src/agents/steps.ts +0 -32
  43. /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 agents run`. */
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 agents load`. */
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 '../ui.ts'
6
+ import { bold, dim, paint256 } from '../../ui.ts'
7
7
  import { kinds } from './kinds.ts'
8
- import type { Run } from './report.ts'
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(run: Run, path: string, root: string): Promise<Map<number, 'yes' | 'no'> | undefined> {
22
- const items = run.rules.filter((r) => r.n)
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 '../git.ts'
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 agents run`. */
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 agents scan`. */
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)}`]