turntax 0.3.0 → 0.5.0

package/dist/core/fix.js

@@ -0,0 +1,442 @@
+import { sectionScope } from './advice.js';
+import { classify } from './classify.js';
+import { isInstructionFile } from './files.js';
+import { basename, findImports, linesWithFences, parseFrontmatter, splitSections } from './markdown.js';
+import { countO200k } from './tokenize.js';
+import { TOOLS } from './tools.js';
+const RANK = { ignored: 0, manual: 1, 'on-demand': 2, always: 3 };
+const toolName = (id) => TOOLS.find((t) => t.id === id)?.name ?? id;
+const names = (ids) => [...ids].map(toolName).join(', ');
+/** Text with LF line endings, plus the line ending to write back. */
+function lf(text) {
+    return { text: text.replace(/\r\n/g, '\n'), eol: text.includes('\r\n') ? '\r\n' : '\n' };
+}
+function contentUnits(units) {
+    return units.filter((u) => u.part !== 'description' && u.mode !== 'ignored');
+}
+/**
+ * A line as compared by the fixes: only list markers and whitespace are ignored. Case, underscores,
+ * asterisks and backticks can carry meaning (`create_user`, globs), so lines that differ there differ.
+ */
+function lineKey(line) {
+    return line.replace(/^\s*(?:[-*+]|\d+[.)])\s+/, '').replace(/\s+/g, ' ').trim();
+}
+/** Prose lines long enough to be meaningful (outside fenced code, not headings), by key. */
+function proseLines(text) {
+    const out = new Map();
+    for (const { line, inFence } of linesWithFences(text)) {
+        const key = lineKey(line);
+        if (!inFence && key.length >= 30 && !key.startsWith('#'))
+            out.set(key, line);
+    }
+    return out;
+}
+function keysOf(text) {
+    return text
+        .split('\n')
+        .map(lineKey)
+        .filter((k) => k.replace(/[#\s]/g, '').length > 0);
+}
+function loadedLines(units) {
+    const out = new Map();
+    for (const u of contentUnits(units)) {
+        const lines = out.get(u.tool) ?? new Map();
+        out.set(u.tool, lines);
+        for (const key of keysOf(u.text))
+            lines.set(key, Math.max(lines.get(key) ?? 0, RANK[u.mode]));
+    }
+    return out;
+}
+/**
+ * Agents that would lose something: every line an agent read before must still be read at least as
+ * often, except the `edited` lines, which need only `need(before)`.
+ */
+function check(before, after, edited, need) {
+    const lost = [];
+    for (const [tool, lines] of before) {
+        const now = after.get(tool);
+        for (const [key, rank] of lines) {
+            if ((now?.get(key) ?? 0) < (edited.has(key) ? need(rank) : rank)) {
+                lost.push(tool);
+                break;
+            }
+        }
+    }
+    return lost;
+}
+class Workspace {
+    tools;
+    state;
+    constructor(input, tools) {
+        this.tools = tools;
+        this.state = this.build(new Map(input.map((f) => [f.path, f])));
+    }
+    build(files) {
+        const units = classify([...files.values()], this.tools);
+        return { files, units, loaded: loadedLines(units) };
+    }
+    get files() {
+        return this.state.files;
+    }
+    get units() {
+        return this.state.units;
+    }
+    /** The state with `edits` applied (null deletes a file). */
+    trial(edits) {
+        const files = new Map(this.state.files);
+        for (const [path, text] of edits) {
+            if (text === null)
+                files.delete(path);
+            else
+                files.set(path, { path, text });
+        }
+        return this.build(files);
+    }
+    check(next, edited, need) {
+        return check(this.state.loaded, next.loaded, new Set(edited), need);
+    }
+    commit(next) {
+        this.state = next;
+    }
+}
+export function planFixes(input, opts = {}) {
+    // Only repository files are ever changed; user-level files (~/...) are not passed in.
+    const ws = new Workspace(input.filter((f) => !f.path.startsWith('~')), opts.tools);
+    // Files reached only through @imports (a README, docs) are for people too; they are never changed.
+    const readOnly = (path) => {
+        if (!isInstructionFile(path))
+            return `${path} is not an agent instruction file (it is @imported); it is left alone.`;
+        const reason = opts.readOnly?.(path);
+        return typeof reason === 'string' ? reason : reason ? `${path} is a symlink, in a symlinked folder or the target of a symlink; it is left alone.` : null;
+    };
+    const original = new Map(ws.files);
+    const renames = new Map();
+    const fixes = [];
+    const skipped = [];
+    if (!opts.tools || opts.tools.includes('cursor'))
+        renameCursorRules(ws, readOnly, renames, fixes, skipped);
+    // Moves run before duplicate removal: a move may relax how often lines load, so a line must not be
+    // removed elsewhere on the strength of a copy that is moved later.
+    moveScopableSections(ws, opts, readOnly, fixes, skipped);
+    removeDuplicates(ws, readOnly, fixes, skipped);
+    const renamedTo = new Map([...renames].map(([from, to]) => [to, from]));
+    const changes = [];
+    for (const [path, file] of ws.files) {
+        const from = renamedTo.get(path);
+        const before = original.get(from ?? path)?.text ?? null;
+        if (from)
+            changes.push({ path, before, after: file.text, renamedFrom: from });
+        else if (before !== file.text)
+            changes.push({ path, before, after: file.text });
+    }
+    changes.sort((a, b) => a.path.localeCompare(b.path));
+    return { fixes, skipped, changes };
+}
+/** `.md` files in `.cursor/rules` are ignored by Cursor; `.mdc` is the documented extension. */
+function renameCursorRules(ws, readOnly, renames, fixes, skipped) {
+    for (const f of [...ws.files.values()]) {
+        if (!/^(?:.*\/)?\.cursor\/rules\/.+\.md$/.test(f.path))
+            continue;
+        const to = f.path.replace(/\.md$/, '.mdc');
+        const blocked = readOnly(f.path) ?? (ws.files.has(to) ? `${to} already exists.` : readOnly(to));
+        if (blocked) {
+            skipped.push({ kind: 'misconfigured', paths: [f.path], reason: blocked });
+            continue;
+        }
+        const next = ws.trial(new Map([[f.path, null], [to, f.text]]));
+        const lost = ws.check(next, [], (r) => r);
+        if (lost.length) {
+            skipped.push({ kind: 'misconfigured', paths: [f.path], reason: `${names(lost)} would stop reading it.` });
+            continue;
+        }
+        const mode = next.units.find((u) => u.tool === 'cursor' && u.path === to && u.part !== 'description')?.mode;
+        ws.commit(next);
+        renames.set(f.path, to);
+        fixes.push({
+            kind: 'misconfigured',
+            paths: [f.path, to],
+            message: `Renamed ${f.path} to ${basename(to)} so Cursor reads it` +
+                (mode === 'manual' ? '; without frontmatter it applies only when @-mentioned (add alwaysApply, globs or description).' : '.'),
+            savingTokens: null,
+        });
+    }
+}
+/** Indexes of body lines (after any frontmatter) outside fenced code. */
+function bodyLines(text) {
+    const start = text.split('\n').length - parseFrontmatter(text).body.split('\n').length;
+    return linesWithFences(text)
+        .map(({ line, inFence }, index) => ({ line, inFence, index }))
+        .filter((l) => !l.inFence && l.index >= start);
+}
+/** Drops the given line indexes; a blank line left next to another blank line where a line was removed goes too. */
+function dropLines(lines, drop) {
+    const kept = [];
+    let removed = false;
+    lines.forEach((line, i) => {
+        if (drop.has(i)) {
+            removed = true;
+            return;
+        }
+        if (removed && line.trim() === '' && (kept.length === 0 || kept[kept.length - 1].trim() === ''))
+            return;
+        removed = false;
+        kept.push(line);
+    });
+    return kept;
+}
+/**
+ * Removes a line from a file when every agent that reads the file also reads the same line every turn
+ * from another file. Files read by fewer agents are trimmed first, so the broadest copy stays.
+ */
+function removeDuplicates(ws, readOnly, fixes, skipped) {
+    const readers = (path) => new Set(contentUnits(ws.units).filter((u) => u.path === path).map((u) => u.tool));
+    const order = [...ws.files.keys()].sort((a, b) => readers(a).size - readers(b).size || b.localeCompare(a));
+    for (const path of order) {
+        const tools = readers(path);
+        // Skill, command and subagent bodies are procedures or separate prompts; they are left whole.
+        if (!tools.size || ws.units.some((u) => u.path === path && u.part === 'body'))
+            continue;
+        const { text, eol } = lf(ws.files.get(path).text);
+        const elsewhere = (key) => contentUnits(ws.units).filter((u) => u.path !== path && u.mode === 'always' && proseLines(u.text).has(key));
+        // Lines this file shares with another file that some agent reads every turn.
+        const shared = new Map();
+        const blockers = new Set();
+        const removable = new Set();
+        for (const [key] of proseLines(text)) {
+            const others = elsewhere(key);
+            if (!others.length)
+                continue;
+            shared.set(key, [...new Set(others.map((u) => u.path))]);
+            const missing = [...tools].filter((t) => !others.some((u) => u.tool === t));
+            missing.forEach((t) => blockers.add(t));
+            if (!missing.length)
+                removable.add(key);
+        }
+        if (!shared.size)
+            continue;
+        const otherPaths = [...new Set([...shared.values()].flat())];
+        if (readOnly(path)) {
+            skipped.push({ kind: 'duplicate', paths: [path, ...otherPaths], reason: readOnly(path) });
+            continue;
+        }
+        if (removable.size) {
+            const lines = text.split('\n');
+            const drop = new Set(bodyLines(text).filter((l) => removable.has(lineKey(l.line))).map((l) => l.index));
+            const removed = [...drop].map((i) => lines[i]);
+            const next = ws.trial(new Map([[path, dropLines(lines, drop).join('\n').replace(/\n/g, eol)]]));
+            const lost = ws.check(next, removable, (r) => r);
+            if (lost.length) {
+                skipped.push({ kind: 'duplicate', paths: [path, ...otherPaths], reason: `Kept ${removable.size} line(s) in ${path}: ${names(lost)} would lose context without them (for example a file they @import).` });
+            }
+            else {
+                const everyTurn = contentUnits(ws.units).some((u) => u.path === path && u.mode === 'always');
+                const from = [...new Set([...removable].flatMap((k) => shared.get(k)))];
+                ws.commit(next);
+                fixes.push({
+                    kind: 'duplicate',
+                    paths: [path, ...from],
+                    message: `Removed ${removed.length} line(s) from ${path} that ${names(tools)} already read every turn from ${from.join(', ')}.`,
+                    savingTokens: everyTurn ? countO200k(removed.join('\n')) : 0,
+                });
+            }
+        }
+        const kept = shared.size - removable.size;
+        if (kept && blockers.size)
+            skipped.push({
+                kind: 'duplicate',
+                paths: [path, ...otherPaths],
+                reason: `Kept ${kept} line(s) in ${path} that are also in ${otherPaths.join(', ')}: ${names(blockers)} would lose them.`,
+            });
+    }
+}
+/** Where a section about `scope` can live so it loads only there: the same file name nested, AGENTS.md, or a Claude rule. */
+function targets(source, scope, heading) {
+    const name = basename(source);
+    const slug = heading.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '') || 'section';
+    const out = [];
+    if (['CLAUDE.md', 'AGENTS.md', 'GEMINI.md'].includes(name))
+        out.push({ path: `${scope}/${name}`, header: '' });
+    if (name !== 'AGENTS.md')
+        out.push({ path: `${scope}/AGENTS.md`, header: '' });
+    out.push({ path: `.claude/rules/${slug}.md`, header: `---\npaths:\n  - "${scope}/**"\n---\n\n` });
+    return out;
+}
+const headingLevel = (line) => /^\s{0,3}(#{1,6})\s/.exec(line)?.[1].length ?? 0;
+/** Level 2 and 3 sections of the LF text, each running to the next heading of the same or a higher level. */
+function movableSections(text) {
+    const lines = text.split('\n');
+    const all = splitSections(text).filter((s) => s.heading !== '(top)');
+    return all
+        .map((s) => ({ s, level: headingLevel(lines[s.line - 1]) }))
+        .filter((x) => x.level >= 2)
+        .map(({ s, level }) => {
+        const next = all.find((o) => o.line > s.line && headingLevel(lines[o.line - 1]) <= level);
+        const end = next ? next.line - 1 : lines.length;
+        return { heading: s.heading, start: s.line - 1, end, body: lines.slice(s.line - 1, end).join('\n').replace(/\n+$/, '') };
+    });
+}
+function moveScopableSections(ws, opts, readOnly, fixes, skipped) {
+    const sources = [...new Set(ws.units.filter((u) => u.mode === 'always' && u.part === 'full').map((u) => u.path))].sort();
+    const tried = new Set();
+    for (const path of sources) {
+        // Sections are found in the raw file so that comments and formatting move as they are.
+        for (;;) {
+            const { text, eol } = lf(ws.files.get(path).text);
+            const next = movableSections(text)
+                .map((x) => ({ ...x, scope: sectionScope(x.body) }))
+                .find((x) => x.scope && !tried.has(`${path}\0${x.body}`));
+            if (!next)
+                break;
+            tried.add(`${path}\0${next.body}`);
+            const { heading, body, start, end } = next;
+            const scope = next.scope;
+            const reason = readOnly(path) ?? moveBlocker(body, scope, opts);
+            if (reason) {
+                skipped.push({ kind: 'scopable-section', paths: [path], reason: `Section "${heading}": ${reason}` });
+                continue;
+            }
+            const lines = text.split('\n');
+            const head = lines.slice(0, start);
+            const tail = lines.slice(end);
+            while (head.length && tail.length && head[head.length - 1].trim() === '' && tail[0].trim() === '')
+                tail.shift();
+            const rest = [...head, ...tail].join('\n').replace(/\n*$/, '\n');
+            let moved = false;
+            const refused = [];
+            for (const t of targets(path, scope, heading)) {
+                const existing = ws.files.get(t.path);
+                if (t.path === path || readOnly(t.path) || (existing && t.header))
+                    continue;
+                const target = existing ? lf(existing.text) : { text: '', eol };
+                const targetText = existing ? `${target.text.replace(/\n+$/, '')}\n\n${body}\n` : `${t.header}${body}\n`;
+                const trial = ws.trial(new Map([
+                    [path, rest.replace(/\n/g, eol)],
+                    [t.path, targetText.replace(/\n/g, target.eol)],
+                ]));
+                // Agents that loaded the section every turn may now load it only when working in that folder.
+                const lost = ws.check(trial, keysOf(body), (r) => Math.min(r, RANK['on-demand']));
+                if (lost.length) {
+                    refused.push(`${t.path} (${names(lost)} would lose context)`);
+                    continue;
+                }
+                const readers = [...new Set(ws.units.filter((u) => u.path === path && u.mode === 'always' && u.part !== 'description').map((u) => u.tool))];
+                const reads = (l, tool) => keysOf(body).some((k) => l.get(tool)?.has(k));
+                const added = [...trial.loaded.keys()].filter((tool) => !reads(ws.state.loaded, tool) && reads(trial.loaded, tool));
+                const dropped = opts.tools ? leftOut(ws.files, trial.files, body, opts.tools) : [];
+                ws.commit(trial);
+                fixes.push({
+                    kind: 'scopable-section',
+                    paths: [path, t.path],
+                    message: `Moved section "${heading}" from ${path} to ${t.path}${existing ? '' : ' (new file)'}; ${names(readers)} load it only when working in ${scope}/.` +
+                        (added.length ? ` Now also read there by ${names(added)}.` : '') +
+                        (dropped.length ? ` Not kept for ${names(dropped)} (outside --tools).` : ''),
+                    savingTokens: countO200k(body),
+                });
+                moved = true;
+                break;
+            }
+            if (!moved)
+                skipped.push({
+                    kind: 'scopable-section',
+                    paths: [path],
+                    reason: `Section "${heading}": no target keeps every agent's context: ${refused.join('; ')}. Use --tools to choose the agents to keep it for.`,
+                });
+        }
+    }
+}
+/** Agents outside `tools` that read some of `body` before the move and none of those lines after it. */
+function leftOut(before, after, body, tools) {
+    const others = TOOLS.map((t) => t.id).filter((id) => !tools.includes(id));
+    const was = loadedLines(classify([...before.values()], others));
+    const now = loadedLines(classify([...after.values()], others));
+    return others.filter((tool) => keysOf(body).some((k) => was.get(tool)?.has(k) && !now.get(tool)?.has(k)));
+}
+function moveBlocker(body, scope, opts) {
+    if (scope.split('/').some((seg) => seg === '' || seg === '.' || seg === '..'))
+        return `unusual folder ${scope}.`;
+    if (opts.exists && !opts.exists(scope))
+        return `folder ${scope}/ does not exist.`;
+    if (findImports(body).length)
+        return 'it has @imports, which resolve relative to the file they are in.';
+    if (/\]\((?!https?:|#|\/|mailto:)[^)]+\)/.test(body))
+        return 'it has relative links, which resolve relative to the file they are in.';
+    return null;
+}
+/** Unified diff of the planned changes, in the format `git apply` accepts. */
+export function unifiedDiff(changes) {
+    let out = '';
+    for (const c of changes) {
+        const from = c.renamedFrom ?? c.path;
+        out += `diff --git a/${from} b/${c.path}\n`;
+        if (c.renamedFrom) {
+            if (c.before === c.after)
+                out += 'similarity index 100%\n';
+            out += `rename from ${c.renamedFrom}\nrename to ${c.path}\n`;
+            if (c.before === c.after)
+                continue;
+        }
+        if (c.before === null)
+            out += 'new file mode 100644\n';
+        out += `--- ${c.before === null ? '/dev/null' : `a/${from}`}\n+++ b/${c.path}\n`;
+        out += hunks(c.before ?? '', c.after);
+    }
+    return out;
+}
+function split(text) {
+    if (text === '')
+        return [];
+    const lines = text.split('\n');
+    const noEol = lines[lines.length - 1] !== '';
+    if (!noEol)
+        lines.pop();
+    return lines.map((t, i) => ({ text: t, noEol: noEol && i === lines.length - 1 }));
+}
+/** Line diff by longest common subsequence; instruction files are small. */
+function diffLines(a, b) {
+    const n = a.length;
+    const m = b.length;
+    const same = (i, j) => a[i].text === b[j].text && a[i].noEol === b[j].noEol;
+    if (n * m > 4_000_000)
+        return [...a.map((l) => ({ op: '-', ...l })), ...b.map((l) => ({ op: '+', ...l }))];
+    const lcs = Array.from({ length: n + 1 }, () => new Uint32Array(m + 1));
+    for (let i = n - 1; i >= 0; i--)
+        for (let j = m - 1; j >= 0; j--)
+            lcs[i][j] = same(i, j) ? lcs[i + 1][j + 1] + 1 : Math.max(lcs[i + 1][j], lcs[i][j + 1]);
+    const out = [];
+    let i = 0;
+    let j = 0;
+    while (i < n || j < m) {
+        if (i < n && j < m && same(i, j)) {
+            out.push({ op: ' ', ...a[i++] });
+            j++;
+        }
+        else if (i < n && (j === m || lcs[i + 1][j] >= lcs[i][j + 1]))
+            out.push({ op: '-', ...a[i++] });
+        else
+            out.push({ op: '+', ...b[j++] });
+    }
+    return out;
+}
+function hunks(before, after, context = 3) {
+    const lines = diffLines(split(before), split(after));
+    const changed = lines.map((l, i) => (l.op === ' ' ? -1 : i)).filter((i) => i >= 0);
+    let out = '';
+    let k = 0;
+    while (k < changed.length) {
+        const start = Math.max(0, changed[k] - context);
+        let end = Math.min(lines.length, changed[k] + context + 1);
+        while (k + 1 < changed.length && changed[k + 1] - context <= end)
+            end = Math.min(lines.length, changed[++k] + context + 1);
+        k++;
+        const slice = lines.slice(start, end);
+        const prefix = lines.slice(0, start);
+        const oldStart = prefix.filter((l) => l.op !== '+').length;
+        const newStart = prefix.filter((l) => l.op !== '-').length;
+        const oldLen = slice.filter((l) => l.op !== '+').length;
+        const newLen = slice.filter((l) => l.op !== '-').length;
+        out += `@@ -${oldLen ? oldStart + 1 : oldStart},${oldLen} +${newLen ? newStart + 1 : newStart},${newLen} @@\n`;
+        for (const l of slice)
+            out += `${l.op}${l.text}\n${l.noEol ? '\\n' : ''}`;
+    }
+    return out;
+}

package/dist/core/glob.js

@@ -0,0 +1,34 @@
+/**
+ * Repository-relative globs: `*` and `?` match within one path segment, `**` matches any number of
+ * segments, and a trailing `/` matches everything in that folder. Patterns match the whole path.
+ */
+export function globToRegExp(glob) {
+    let g = glob.replace(/\\/g, '/').replace(/^\.?\//, '');
+    if (g.endsWith('/'))
+        g += '**';
+    let re = '';
+    for (let i = 0; i < g.length; i++) {
+        const c = g[i];
+        const segmentStart = i === 0 || g[i - 1] === '/';
+        if (c === '*' && g[i + 1] === '*' && segmentStart && (g[i + 2] === '/' || i + 2 === g.length)) {
+            // `**/` matches zero or more folders; a final `**` matches the rest of the path.
+            re += g[i + 2] === '/' ? '(?:[^/]+/)*' : '.*';
+            i += 2;
+        }
+        else if (c === '*') {
+            while (g[i + 1] === '*')
+                i++;
+            re += '[^/]*';
+        }
+        else if (c === '?')
+            re += '[^/]';
+        else
+            re += c.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+    }
+    return new RegExp(`^${re}$`);
+}
+/** A test for paths that match any of the globs. */
+export function globMatcher(globs) {
+    const res = globs.map(globToRegExp);
+    return (path) => res.some((re) => re.test(path));
+}

package/dist/core/render.js

@@ -1,3 +1,4 @@
+import { unifiedDiff } from './fix.js';
 import { DEFERRED_NOTE } from './mcp.js';
 export const METHOD_LABEL = {
     'offline-exact': 'exact (offline tokenizer)',
@@ -330,15 +331,71 @@ export function badgeMarkdown(report) {
 }
 export const PR_COMMENT_MARKER = '<!-- turntax-report -->';
 const COMMENT_LIMIT = 60_000;
+/** Most of the comment the fix diff may take; the full report gets the rest. */
+const FIX_DIFF_LIMIT = 20_000;
 /**
- * A pull request comment: the change against the base branch first, the full report folded below.
- * Starts with a marker so the GitHub Action can update its own comment instead of adding new ones.
+ * A pull request comment: the change against the base branch first, then the safe fixes (when `fixes`
+ * has changes), the full report folded below. Starts with a marker so the GitHub Action can update its
+ * own comment instead of adding new ones.
  */
-export function renderPrComment(report) {
+export function renderPrComment(report, fixes, fixCommand = 'npx turntax --fix') {
     const top = report.diff ? renderDiffMarkdown(report.diff) : '## Agent context tax';
     const headline = `Largest per-turn cost: **${fmtTokens(headlineTokens(report))}** o200k tokens (repository files and measured project MCP tools).`;
+    const fixPart = fixes?.changes.length ? ['', renderFixes(fixes, fixCommand)] : [];
+    // GitHub rejects comments over 65,536 characters; everything but the full report counts against the limit.
+    const limit = Math.max(0, COMMENT_LIMIT - [top, headline, ...fixPart].join('\n').length);
     let full = renderMarkdown({ ...report, diff: undefined }).replace(/^# .*\n\n/, '');
-    if (full.length > COMMENT_LIMIT)
-        full = full.slice(0, COMMENT_LIMIT) + '\n\n_Report cut to fit in a comment; the job summary has all of it._\n';
-    return [PR_COMMENT_MARKER, top, '', headline, '', '<details><summary>Full report</summary>', '', full, '</details>', ''].join('\n');
+    if (full.length > limit)
+        full = full.slice(0, limit) + '\n\n_Report cut to fit in a comment; run turntax locally for all of it._\n';
+    return [PR_COMMENT_MARKER, top, '', headline, ...fixPart, '', '<details><summary>Full report</summary>', '', full, '</details>', ''].join('\n');
+}
+function renderFixes(plan, command) {
+    const n = plan.fixes.length;
+    const saving = plan.fixes.reduce((a, f) => a + (f.savingTokens ?? 0), 0);
+    let diff = unifiedDiff(plan.changes);
+    let cut = '';
+    if (diff.length > FIX_DIFF_LIMIT) {
+        const end = diff.lastIndexOf('\n', FIX_DIFF_LIMIT);
+        diff = diff.slice(0, end > 0 ? end + 1 : FIX_DIFF_LIMIT);
+        cut = `\n_Diff cut to fit in a comment; run \`${command}\` for all of it._\n`;
+    }
+    // A fence longer than any backtick run in the diff, so moved code blocks cannot close it.
+    const fence = '`'.repeat(Math.max(3, ...[...diff.matchAll(/`+/g)].map((m) => m[0].length + 1)));
+    return [
+        `**${n} safe ${n === 1 ? 'fix' : 'fixes'} available**${saving ? ` (saves ~${fmtTokens(saving)} o200k tokens/turn)` : ''}: run \`${command}\` to preview.`,
+        '',
+        '<details><summary>Fixes</summary>',
+        '',
+        // Section headings in the messages may contain @names; keep them from mentioning people.
+        ...plan.fixes.map((f) => `- ${f.message.replace(/@(?=[A-Za-z0-9])/g, '@&#8203;')}`),
+        '',
+        `${fence}diff`,
+        diff.replace(/\n$/, ''),
+        fence,
+        cut,
+        '</details>',
+    ].join('\n');
+}
+/** GitHub workflow command escaping: message data, and property values (file, title). */
+const escapeData = (s) => s.replace(/%/g, '%25').replace(/\r/g, '%0D').replace(/\n/g, '%0A');
+const escapeProperty = (s) => escapeData(s).replace(/:/g, '%3A').replace(/,/g, '%2C');
+/**
+ * GitHub Actions annotations, one per advice item on a repository file, so findings show inline on a
+ * pull request. `prefix` makes paths relative to the workspace when the audited folder is not its root.
+ */
+export function renderAnnotations(report, prefix = '') {
+    let out = '';
+    for (const a of report.advice) {
+        const path = a.paths.find((p) => !p.startsWith('~'));
+        if (!path)
+            continue;
+        const props = [`file=${escapeProperty(prefix + path)}`];
+        // `line` belongs to the first path.
+        if (a.line && path === a.paths[0])
+            props.push(`line=${a.line}`);
+        props.push(`title=${escapeProperty(`turntax ${a.kind}`)}`);
+        const saving = a.savingTokens ? ` (saves ~${fmtTokens(a.savingTokens)} tokens/turn)` : '';
+        out += `::${a.severity === 'low' ? 'notice' : 'warning'} ${props.join(',')}::${escapeData(a.message + saving)}\n`;
+    }
+    return out;
 }

package/dist/node/apply.js

@@ -0,0 +1,43 @@
+import { lstatSync, mkdirSync, readFileSync, realpathSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname, isAbsolute, relative, resolve } from 'node:path';
+import { realLocation } from './discover.js';
+const inside = (root, p) => {
+    const rel = relative(root, p);
+    return !rel.startsWith('..') && !isAbsolute(rel);
+};
+/**
+ * Writes planned changes under `root`. Every file is checked first: files to change must still have the
+ * content the plan was made from, new files must not exist, and nothing may be written through a symlink
+ * (dangling ones included) or outside the repository. Nothing is written when a check fails.
+ */
+export function applyChanges(root, changes) {
+    const realRoot = realpathSync(root);
+    const exists = (p) => lstatSync(p, { throwIfNoEntry: false }) !== undefined;
+    const abs = (path) => {
+        const p = resolve(root, path);
+        if (lstatSync(p, { throwIfNoEntry: false })?.isSymbolicLink())
+            throw new Error(`${path} is a symlink; nothing was written.`);
+        const real = realLocation(p);
+        if (!inside(root, p) || real === null || !inside(realRoot, real))
+            throw new Error(`${path} is outside ${root}; nothing was written.`);
+        return p;
+    };
+    for (const c of changes) {
+        const source = c.renamedFrom ?? c.path;
+        if (c.renamedFrom && exists(abs(c.path)))
+            throw new Error(`${c.path} already exists; nothing was written.`);
+        if (c.before === null ? exists(abs(c.path)) : !exists(abs(source)) || readFileSync(abs(source), 'utf8') !== c.before)
+            throw new Error(`${source} ${c.before === null ? 'already exists' : 'changed since it was read'}; nothing was written.`);
+    }
+    for (const c of changes) {
+        const target = abs(c.path);
+        mkdirSync(dirname(target), { recursive: true });
+        if (c.renamedFrom)
+            renameSync(abs(c.renamedFrom), target);
+        // New files are created exclusively, so a link placed in the meantime is not followed.
+        if (c.before === null)
+            writeFileSync(target, c.after, { flag: 'wx' });
+        else if (c.after !== c.before || !c.renamedFrom)
+            writeFileSync(target, c.after);
+    }
+}

package/dist/node/config.js

@@ -0,0 +1,52 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { TOOL_IDS } from '../core/tools.js';
+export const CONFIG_FILE = 'turntax.config.json';
+const KEYS = {
+    tools: 'strings',
+    models: 'strings',
+    turns: 'positive',
+    maxTokens: 'positive',
+    maxIncrease: 'non-negative',
+    sectionTokens: 'positive',
+    ignore: 'strings',
+};
+/**
+ * Reads `file`, or turntax.config.json in `root` when no file is given. Returns {} when there is no
+ * config and throws, naming the file and key, when it is invalid.
+ */
+export function loadConfig(root, file, models) {
+    const path = file ?? join(root, CONFIG_FILE);
+    if (file === undefined && !existsSync(path))
+        return {};
+    const name = file ?? CONFIG_FILE;
+    let data;
+    try {
+        // Windows PowerShell 5.1 writes UTF-8 with a byte order mark, which JSON.parse rejects.
+        data = JSON.parse(readFileSync(path, 'utf8').replace(/^/, ''));
+    }
+    catch (e) {
+        throw new Error(`Could not read config ${name}: ${e.message}`);
+    }
+    if (typeof data !== 'object' || data === null || Array.isArray(data))
+        throw new Error(`${name}: expected a JSON object.`);
+    for (const [key, value] of Object.entries(data)) {
+        if (!Object.hasOwn(KEYS, key))
+            throw new Error(`${name}: unknown key "${key}". Use: ${Object.keys(KEYS).join(', ')}.`);
+        const kind = KEYS[key];
+        if (kind === 'strings' && !(Array.isArray(value) && value.every((v) => typeof v === 'string' && v)))
+            throw new Error(`${name}: "${key}" must be an array of non-empty strings.`);
+        if ((key === 'tools' || key === 'models') && value.length === 0)
+            throw new Error(`${name}: "${key}" must not be empty.`);
+        if (kind !== 'strings' && !(Number.isInteger(value) && value >= (kind === 'positive' ? 1 : 0)))
+            throw new Error(`${name}: "${key}" must be a ${kind} integer.`);
+    }
+    const config = data;
+    for (const t of config.tools ?? [])
+        if (!TOOL_IDS.includes(t))
+            throw new Error(`${name}: "tools" has unknown tool "${t}". Use: ${TOOL_IDS.join(', ')}`);
+    for (const m of config.models ?? [])
+        if (!models.some((x) => x.id === m))
+            throw new Error(`${name}: "models" has unknown model "${m}". Run --list-models.`);
+    return config;
+}