@astudioplus/compressor 0.1.0

package/dist/adapters/markers.js

@@ -0,0 +1,129 @@
+import { MARKER_BEGIN_LINE_RE, MARKER_END } from "../packs/render.js";
+/** Code fence delimiter: up to 3 leading spaces, then ``` / ~~~ (CommonMark). */
+const FENCE_LINE_RE = /^ {0,3}(`{3,}|~{3,})(.*)$/;
+/** 4+ spaces or a tab opens an indented code block — never our marker. */
+const INDENTED_CODE_RE = /^(?: {4,}|\t)/;
+/**
+ * Per-line mask: true ⇨ the line belongs to a CLOSED fenced code block
+ * (including its delimiter lines) and must be ignored when locating markers.
+ *
+ * CommonMark-faithful where it matters for safety:
+ * - a fence closes only on the same character, at least as long as the
+ *   opener, with nothing but whitespace after it — a ``` line inside an open
+ *   ~~~ block is literal text, not a toggle;
+ * - a backtick opening fence cannot carry backticks in its info string;
+ * - a fence left open at EOF deliberately does NOT mask its content: install
+ *   appends our section after such files, and hiding those lines would break
+ *   idempotency (duplicate sections) and strand the section with no
+ *   uninstall path.
+ */
+function closedFenceMask(lines) {
+    const mask = new Array(lines.length).fill(false);
+    let open = null;
+    for (let i = 0; i < lines.length; i += 1) {
+        const match = FENCE_LINE_RE.exec(lines[i] ?? '');
+        if (match === null) {
+            continue;
+        }
+        const seq = match[1] ?? '';
+        const rest = match[2] ?? '';
+        const char = seq.charAt(0);
+        if (open === null) {
+            if (char === '~' || !rest.includes('`')) {
+                open = { char, len: seq.length, from: i };
+            }
+        }
+        else if (char === open.char &&
+            seq.length >= open.len &&
+            rest.trim() === '') {
+            for (let j = open.from; j <= i; j += 1) {
+                mask[j] = true;
+            }
+            open = null;
+        }
+    }
+    return mask;
+}
+function isBeginLine(line) {
+    return !INDENTED_CODE_RE.test(line) && MARKER_BEGIN_LINE_RE.test(line.trim());
+}
+function isEndLine(line) {
+    return !INDENTED_CODE_RE.test(line) && line.trim() === MARKER_END;
+}
+/**
+ * Locate our marked section. Safety rules:
+ * - a begin line must match the FULL marker grammar (prefix-only prose lines
+ *   are ignored);
+ * - markers inside closed code fences or indented code blocks are examples,
+ *   not boundaries;
+ * - an end line pairs with the NEAREST preceding begin: an orphan begin
+ *   (user hand-deleted our end) re-anchors to a later real begin instead of
+ *   greedily swallowing the user content in between.
+ */
+function findSpan(lines) {
+    const fenced = closedFenceMask(lines);
+    let start = -1;
+    for (let i = 0; i < lines.length; i += 1) {
+        if (fenced[i] === true) {
+            continue;
+        }
+        const line = lines[i] ?? '';
+        if (isBeginLine(line)) {
+            start = i;
+        }
+        else if (start !== -1 && isEndLine(line)) {
+            return { start, end: i };
+        }
+    }
+    return null;
+}
+function asBlock(section) {
+    return section.endsWith('\n') ? section.slice(0, -1) : section;
+}
+/**
+ * Replace the compressor section in place if present; else append with exactly
+ * one blank line of separation. Bytes outside the markers are never modified.
+ */
+export function upsertMarkedSection(existing, section) {
+    const block = asBlock(section);
+    if (existing === null) {
+        return `${block}\n`;
+    }
+    const lines = existing.split('\n');
+    const span = findSpan(lines);
+    if (span !== null) {
+        return [
+            ...lines.slice(0, span.start),
+            ...block.split('\n'),
+            ...lines.slice(span.end + 1),
+        ].join('\n');
+    }
+    const trimmed = existing.replace(/\n+$/u, '');
+    return trimmed === '' ? `${block}\n` : `${trimmed}\n\n${block}\n`;
+}
+export function removeMarkedSection(existing) {
+    const lines = existing.split('\n');
+    const span = findSpan(lines);
+    if (span === null) {
+        return existing;
+    }
+    const before = lines.slice(0, span.start);
+    const after = lines.slice(span.end + 1);
+    if (before.length > 0 && before[before.length - 1] === '') {
+        before.pop();
+    }
+    else if (after.length > 0 && after[0] === '') {
+        after.shift();
+    }
+    // No whitespace collapsing here: residue bytes (e.g. a whitespace-only
+    // user file that received our section) must survive removal untouched.
+    return [...before, ...after].join('\n');
+}
+export function readMarkedSection(existing) {
+    const lines = existing.split('\n');
+    const span = findSpan(lines);
+    if (span === null) {
+        return null;
+    }
+    return lines.slice(span.start, span.end + 1).join('\n');
+}

package/dist/adapters/types.d.ts

@@ -0,0 +1,44 @@
+import type { AgentName, PackMode } from '../packs/types.ts';
+/** Mode argument accepted by the CLI; 'full' maps to uninstall (true baseline). */
+export type ModeArg = PackMode | 'full';
+export interface AdapterContext {
+    /** project root (cwd) */
+    projectDir: string;
+    /** os.homedir() in production; overridden in tests */
+    homeDir: string;
+    /** install at user level instead of project level */
+    global: boolean;
+    /** command line for the PostToolUse hook entry, resolved at install time */
+    hookCommand: string;
+}
+/**
+ * A planned file mutation. `before === null` means the file did not exist;
+ * `after === null` means the file is deleted. The CLI renders these as diffs
+ * for --dry-run and applies them otherwise. Adapters never write directly.
+ */
+export interface FileChange {
+    path: string;
+    before: string | null;
+    after: string | null;
+}
+export interface AdapterStatus {
+    agent: AgentName;
+    installed: boolean;
+    mode?: PackMode;
+    /** human line, e.g. 'output style + hook installed (project)' or 'unknown layout — not touching' */
+    detail: string;
+}
+/**
+ * Adapters are pure planners: every method returns the FileChanges that WOULD
+ * make the target state true, computed from current disk content. Idempotent:
+ * planning install over an existing install yields replace-in-place, never
+ * duplicates. Uninstall touches only compressor-owned files/sections/entries.
+ */
+export interface Adapter {
+    name: AgentName;
+    /** is this agent plausibly used in this project/home? */
+    detect(ctx: AdapterContext): Promise<boolean>;
+    install(mode: PackMode, ctx: AdapterContext): Promise<FileChange[]>;
+    uninstall(ctx: AdapterContext): Promise<FileChange[]>;
+    status(ctx: AdapterContext): Promise<AdapterStatus>;
+}

package/dist/adapters/types.js

@@ -0,0 +1 @@
+export {};

package/dist/bench/ablate.d.ts

@@ -0,0 +1,35 @@
+import type { Mode } from '../engine/types.ts';
+import type { AtomCategory } from '../packs/types.ts';
+import type { Variant } from './types.ts';
+/** Atom categories ablatable wholesale via --ablate-group. */
+export declare const ABLATE_GROUPS: readonly AtomCategory[];
+export interface BuildVariantsOptions {
+    modes: Mode[];
+    /** atom ids removed one at a time from the optimized baseline */
+    ablate: string[];
+    /** REJECTED atom ids added one at a time to the optimized baseline */
+    ablateAdd: string[];
+    /** atom categories ('output' | 'behavior') removed wholesale from the optimized baseline */
+    ablateGroups: string[];
+    hook: boolean;
+    /**
+     * Extra args appended to the hook command of EVERY hook-bearing variant
+     * (Variant.hookArgs), e.g. '--marker-style informative'. Whitespace-only
+     * values are ignored.
+     */
+    hookArgs?: string;
+    /**
+     * Marker-style ARMS: each hook-bearing variant fans out into one variant
+     * per style (id '<variant>-marker-<style>', hookArgs '--marker-style
+     * <style>') so all arms coexist IN THE SAME RUN. Running arms as separate
+     * `--hook-args` runs gives each its own --max-budget-usd ceiling and its
+     * own truncation point — a more expensive arm loses later trials/tasks
+     * while others complete, unbalancing the comparison. In-run arms share one
+     * ceiling and the runner's variants-innermost, group-atomic scheduling
+     * keeps every arm present on exactly the same task×trial groups.
+     */
+    markerStyles?: string[];
+}
+/** Atom ids become style/file names — dots would read as extensions. */
+export declare function sanitizeAtomId(id: string): string;
+export declare function buildVariants(opts: BuildVariantsOptions): Variant[];

package/dist/bench/ablate.js

@@ -0,0 +1,163 @@
+import { getAtom } from "../packs/atoms.js";
+import { atomsForMode, MODE_DESCRIPTIONS } from "../packs/modes.js";
+import { renderOutputStyle, renderOutputStyleFromAtoms } from "../packs/render.js";
+/** Atom categories ablatable wholesale via --ablate-group. */
+export const ABLATE_GROUPS = ['output', 'behavior'];
+function isAblateGroup(value) {
+    return ABLATE_GROUPS.includes(value);
+}
+const MARKER_STYLES = ['plain', 'deterrent', 'informative'];
+function isMarkerStyle(value) {
+    return MARKER_STYLES.includes(value);
+}
+/** Atom ids become style/file names — dots would read as extensions. */
+export function sanitizeAtomId(id) {
+    return id.replaceAll('.', '-');
+}
+function modeVariant(mode, hook) {
+    if (mode === 'full') {
+        return { id: 'full', baseMode: 'full', styleBody: null, styleName: null, hook: false };
+    }
+    return {
+        id: mode,
+        baseMode: mode,
+        styleBody: renderOutputStyle(mode).body,
+        styleName: `compressor-${mode}`,
+        hook,
+    };
+}
+export function buildVariants(opts) {
+    const variants = opts.modes.map((mode) => modeVariant(mode, opts.hook));
+    if (opts.ablateAdd.length > 0 && !opts.modes.includes('optimized')) {
+        throw new Error("--ablate-add requires 'optimized' in --modes — rejected atoms are added back to the optimized baseline");
+    }
+    const baseline = atomsForMode('optimized', 'claude-code');
+    const slimBaseline = atomsForMode('slim', 'claude-code');
+    // Atoms in the optimized baseline ablate against optimized; slim-only atoms
+    // (out.explanation-budget, out.code-only-default) have no optimized data
+    // path, so they ablate against the slim baseline as slim-minus-<id> —
+    // otherwise the per-atom gate is structurally unanswerable for them.
+    for (const id of opts.ablate) {
+        if (getAtom(id) === undefined) {
+            throw new Error(`--ablate: unknown atom id '${id}'`);
+        }
+        const inOptimized = baseline.some((atom) => atom.id === id);
+        const inSlim = slimBaseline.some((atom) => atom.id === id);
+        if (!inOptimized && !inSlim) {
+            throw new Error(`--ablate: atom '${id}' is not in the optimized baseline or the slim baseline — removing it would change nothing`);
+        }
+        const baseMode = inOptimized ? 'optimized' : 'slim';
+        if (!opts.modes.includes(baseMode)) {
+            throw new Error(inOptimized
+                ? `--ablate: atom '${id}' is measured against the optimized baseline — include 'optimized' in --modes`
+                : `--ablate: atom '${id}' is not in the optimized baseline — it is slim-only; include 'slim' in --modes to measure slim-minus-${sanitizeAtomId(id)}`);
+        }
+        const baseAtoms = inOptimized ? baseline : slimBaseline;
+        const variantId = `${baseMode}-minus-${sanitizeAtomId(id)}`;
+        const rendered = renderOutputStyleFromAtoms(baseAtoms.filter((atom) => atom.id !== id), `compressor-${variantId}`, `${MODE_DESCRIPTIONS[baseMode]} (minus ${id})`);
+        variants.push({
+            id: variantId,
+            baseMode,
+            styleBody: rendered.body,
+            styleName: `compressor-${variantId}`,
+            hook: opts.hook,
+        });
+    }
+    for (const group of opts.ablateGroups) {
+        if (!isAblateGroup(group)) {
+            throw new Error(`--ablate-group: unknown group '${group}' (valid groups: ${ABLATE_GROUPS.join(', ')})`);
+        }
+        if (!opts.modes.includes('optimized')) {
+            throw new Error(`--ablate-group: group '${group}' is measured against the optimized baseline — include 'optimized' in --modes`);
+        }
+        const variantId = `optimized-minus-${group}-atoms`;
+        const styleName = `compressor-ablate-no-${group}`;
+        // No empty-result guard needed: if removing the group leaves zero atoms,
+        // renderOutputStyleFromAtoms still emits frontmatter + empty sections —
+        // the variant measures "style file present but says nothing of that category".
+        const rendered = renderOutputStyleFromAtoms(baseline.filter((atom) => atom.category !== group), styleName, `${MODE_DESCRIPTIONS.optimized} (minus all ${group} atoms)`);
+        variants.push({
+            id: variantId,
+            baseMode: 'optimized',
+            styleBody: rendered.body,
+            styleName,
+            hook: opts.hook,
+        });
+    }
+    for (const id of opts.ablateAdd) {
+        const atom = getAtom(id);
+        if (atom === undefined) {
+            throw new Error(`--ablate-add: unknown atom id '${id}'`);
+        }
+        if (atom.rejected === undefined) {
+            throw new Error(`--ablate-add: atom '${id}' is not rejected — active atoms belong in --modes/--ablate; --ablate-add exists to test rejected atoms against data`);
+        }
+        const variantId = `optimized-plus-${sanitizeAtomId(id)}`;
+        const rendered = renderOutputStyleFromAtoms([...baseline, atom], `compressor-${variantId}`, `${MODE_DESCRIPTIONS.optimized} (plus rejected ${id})`);
+        variants.push({
+            id: variantId,
+            baseMode: 'optimized',
+            styleBody: rendered.body,
+            styleName: `compressor-${variantId}`,
+            hook: opts.hook,
+        });
+    }
+    const hookArgs = opts.hookArgs?.trim();
+    if (hookArgs !== undefined && hookArgs !== '') {
+        const hooked = variants.filter((variant) => variant.hook);
+        if (hooked.length === 0) {
+            throw new Error('--hook-args: no hook-bearing variants to apply it to — remove --no-hook and include optimized/slim in --modes');
+        }
+        for (const variant of hooked) {
+            variant.hookArgs = hookArgs;
+        }
+    }
+    const markerStyles = opts.markerStyles ?? [];
+    let expanded = variants;
+    if (markerStyles.length > 0) {
+        for (const style of markerStyles) {
+            if (!isMarkerStyle(style)) {
+                throw new Error(`--marker-styles: unknown style '${style}' (valid: ${MARKER_STYLES.join(', ')})`);
+            }
+        }
+        if (new Set(markerStyles).size !== markerStyles.length) {
+            throw new Error('--marker-styles: duplicate style');
+        }
+        // The hook entries take the FIRST --marker-style on their command line;
+        // a shared --hook-args value carrying the flag would silently override
+        // every arm, collapsing the experiment to one style.
+        if (hookArgs !== undefined && hookArgs.includes('--marker-style')) {
+            throw new Error('--marker-styles cannot be combined with --hook-args containing --marker-style — the shared value would override every arm');
+        }
+        if (!variants.some((variant) => variant.hook)) {
+            throw new Error('--marker-styles: no hook-bearing variants to fan out — remove --no-hook and include optimized/slim in --modes');
+        }
+        expanded = variants.flatMap((variant) => variant.hook
+            ? markerStyles.map((style) => ({
+                ...variant,
+                id: `${variant.id}-marker-${style}`,
+                // unique style file per arm (same body): keeps the duplicate
+                // checks meaningful and the installed outputStyle traceable
+                styleName: variant.styleName === null ? null : `${variant.styleName}-marker-${style}`,
+                hookArgs: variant.hookArgs === undefined
+                    ? `--marker-style ${style}`
+                    : `${variant.hookArgs} --marker-style ${style}`,
+            }))
+            : [variant]);
+    }
+    const seenIds = new Set();
+    const seenStyles = new Set();
+    for (const variant of expanded) {
+        if (seenIds.has(variant.id)) {
+            throw new Error(`duplicate variant id '${variant.id}' (repeated mode or atom id?)`);
+        }
+        seenIds.add(variant.id);
+        if (variant.styleName !== null) {
+            if (seenStyles.has(variant.styleName)) {
+                throw new Error(`duplicate variant style name '${variant.styleName}'`);
+            }
+            seenStyles.add(variant.styleName);
+        }
+    }
+    return expanded;
+}

package/dist/bench/cell.d.ts

@@ -0,0 +1,33 @@
+import type { CellResult, CellSpec, Variant } from './types.ts';
+export interface CellContext {
+    runId: string;
+    fixturesDir: string;
+}
+/**
+ * Hook command installed in a cell: the resolved bundle command plus the
+ * variant's extra args (Variant.hookArgs, e.g. '--marker-style informative')
+ * so experiments can vary engine behavior per variant. `root` is exposed for
+ * tests only; production callers use the package default.
+ */
+export declare function hookCommandForVariant(variant: Variant, root?: string): string;
+/**
+ * Environment for the claude child process (and therefore for the PostToolUse
+ * hook it spawns). CLAUDE_CONFIG_DIR isolates the cell; COMPRESSOR_NO_LEDGER
+ * keeps benchmark cells out of the user's LIVE savings ledger — hook-bearing
+ * cells run the real hook, and without the kill switch every worthwhile
+ * compression would append a synthetic event to ~/.compressor/ledger,
+ * corrupting what `compressor savings` reports. Exported for tests.
+ */
+export declare function cellEnv(scratch: string): NodeJS.ProcessEnv;
+/**
+ * Transcript totals and summed per-turn result JSONs count the same API
+ * responses, so they must roughly agree. Divergence beyond this relative
+ * tolerance means one of the two known failure topologies happened: a
+ * resumed session forked ids and the final transcript does NOT carry the
+ * full copied history (transcript ≪ sum: usage silently undercounts to
+ * roughly the last turn), or per-turn result JSONs report cumulative
+ * session usage (sum ≫ transcript: the fallback double-counts). Neither is
+ * detectable from one side alone; the cell is flagged data-quality-suspect.
+ */
+export declare const USAGE_MISMATCH_TOLERANCE = 0.25;
+export declare function runCell(spec: CellSpec, ctx: CellContext): Promise<CellResult>;