turntax 0.3.0 → 0.4.0

package/README.md

@@ -6,7 +6,7 @@ Coding agents re-send their instruction files with every turn. `turntax` measure
 npx turntax
 ```
 
-Try it in the browser, with nothing uploaded: https://torutdev.github.io/turntax/
+Try it in the browser, with nothing uploaded: https://torutdev.github.io/turntax/ — drop a folder or enter a public GitHub repository. Links like `https://torutdev.github.io/turntax/?repo=owner/name` open straight to that repository's report.
 
 ## Supported agents
 
@@ -83,6 +83,23 @@ All checks are deterministic. Each one shows an estimated saving in o200k tokens
 - **stale-reference**: referenced files or `npm run` scripts that no longer exist.
 - **non-english**: non-English sections. The token multiplier is measured only against an English version you supply (`--english CLAUDE.md=CLAUDE.en.md`) or, if you opt in, a Claude translation (`--translate`).
 
+## Fixing
+
+```bash
+npx turntax --fix            # print a diff of the safe fixes; nothing is changed
+npx turntax --fix --write    # apply them
+```
+
+`--fix` handles three kinds of advice:
+
+- **duplicate**: removes lines from a file when every agent that reads the file also reads the same lines every turn from another file. Skill, command and subagent files are left whole.
+- **scopable-section**: moves a section into the folder it is about: the same file name there (`packages/api/CLAUDE.md`), a nested `AGENTS.md`, or a Claude Code rule with `paths:`. The folder the section is about must already exist, and sections with `@imports` or relative links stay put. A section moves together with its subsections.
+- **misconfigured**: renames `.md` files in `.cursor/rules` to `.mdc`.
+
+Before a fix is kept, the files are classified again with the change applied: every agent must still read every line it read before, including files reached through `@imports`, and as often as before. The only exception is a moved section, which may load only when the agent works in that folder. Otherwise the fix is skipped and the reason is printed. A moved section can reach agents that did not read it before (a nested `AGENTS.md` is read by more agents than a `CLAUDE.md`); the summary names them. By default that check covers every supported agent, so a section of `AGENTS.md` usually stays where it is, because some agents read only the root file. `--tools codex,claude-code` limits the check to the agents you use.
+
+In preview the diff is on stdout and works with `git apply`, and the summary is on stderr; with `--write` the summary is on stdout. `--write` checks that no file changed since it was read and writes nothing if one did. Symlinked files, their targets and files in symlinked folders are never changed. Contradictions and stale references need a person to decide, so `--fix` leaves them alone.
+
 ## MCP servers
 
 Every MCP server an agent starts adds its tool definitions (names, descriptions, input schemas) to the context. `turntax` reads the agents' MCP configs and lists the servers each agent starts:
@@ -148,7 +165,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: TorutDev/turntax@v0.3.0
+      - uses: TorutDev/turntax@v0.4.0
         with:
           max-increase: 500      # optional: fail when an agent grows by more than 500 tokens per turn
           # max-tokens: 8000     # optional: absolute budget
@@ -180,18 +197,22 @@ turntax [path]
   --translate               opt-in Claude translation for that measurement (needs --claude-api)
   --prices <file.json>      your own price table
   --section-tokens <n>      threshold for oversized sections (default 600)
+  --fix                     print a diff of the safe fixes (--tools limits the agents whose context is kept)
+  --write                   with --fix, apply the changes
 ```
 
 ## Privacy
 
 Offline by default: no network calls, no telemetry. File contents are sent only when you pass `--claude-api`, `--gemini-api` or `--translate`, and only to that vendor's API. Keys are read from environment variables and sent only in request headers.
 
-`--mcp` runs the commands in the MCP configs it finds and connects to the configured HTTP servers, as the agents themselves would. Run it only on repositories whose configs you trust. `turntax` prints each command before starting it. `--include-user` reads files in your home directory and never sends them anywhere.
+`--mcp` runs the commands in the MCP configs it finds and connects to the configured HTTP servers, as the agents themselves would. Run it only on repositories whose configs you trust. `turntax` prints each command before starting it. `--include-user` reads files in your home directory and never sends them anywhere. `--fix --write` is the only option that changes files, and only repository files.
 
 ## Web page
 
 [`web/`](web) is a static page that runs the same engine in the browser with the offline tokenizer only. Drop a repository folder or paste files; nothing is uploaded.
 
+It can also load a public GitHub repository: it lists the files with the GitHub API (`api.github.com`, unauthenticated, 60 requests per hour) and downloads only the instruction files, and files they `@import`, from `raw.githubusercontent.com`. Those are the only network requests the page makes, and only when you load a repository or open a `?repo=` link.
+
 ```bash
 npm run build:web
 ```

package/dist/cli.js

@@ -6,12 +6,14 @@ import { hasNonEnglish } from './core/advice.js';
 import { audit } from './core/audit.js';
 import { classify } from './core/classify.js';
 import { asDiffInput, diffReports, maxIncrease } from './core/diff.js';
+import { planFixes, unifiedDiff } from './core/fix.js';
 import { parseMcpConfigs, serverKey, toolDefinitionsText, toolNamesText } from './core/mcp.js';
 import { DEFAULT_MODEL_IDS, MODELS, validateModels } from './core/prices.js';
 import { badgeMarkdown, headlineTokens, renderMarkdown, renderPrComment, renderText } from './core/render.js';
 import { countO200k } from './core/tokenize.js';
 import { TOOL_IDS } from './core/tools.js';
-import { discover, discoverMcpConfigs, discoverUser, existsIn, packageScripts } from './node/discover.js';
+import { applyChanges } from './node/apply.js';
+import { discover, discoverMcpConfigs, discoverUser, existsIn, linkedPaths, packageScripts } from './node/discover.js';
 import { filesAtRef } from './node/git.js';
 import { measureServer } from './node/mcp.js';
 import { anthropicCounter, geminiCounter, translateToEnglish } from './node/remote.js';
@@ -51,6 +53,10 @@ Options:
                           (needs --claude-api; sends those files to api.anthropic.com)
   --prices <file.json>    Use your own price table (same shape as --list-models --json)
   --section-tokens <n>    Flag always-loaded sections at or above n o200k tokens (default: 600)
+  --fix                   Print a diff of the safe fixes: duplicate lines, sections that can load only in
+                          their folder, misnamed Cursor rules. Every agent keeps reading the moved text;
+                          --tools limits the agents whose context is kept
+  --write                 With --fix, apply the changes to the files
   -h, --help              Show help
   -v, --version           Show version
 
@@ -101,6 +107,8 @@ export async function main(argv, env = process.env) {
                 baseline: { type: 'string' },
                 compare: { type: 'string' },
                 'max-increase': { type: 'string' },
+                fix: { type: 'boolean' },
+                write: { type: 'boolean' },
                 help: { type: 'boolean', short: 'h' },
                 version: { type: 'boolean', short: 'v' },
             },
@@ -144,6 +152,16 @@ export async function main(argv, env = process.env) {
             if (!TOOL_IDS.includes(t))
                 throw new UsageError(`Unknown tool "${t}". Use: ${TOOL_IDS.join(', ')}`);
         const root = resolve(positionals[0] ?? '.');
+        if (o.write && !o.fix)
+            throw new UsageError('--write needs --fix.');
+        if (o.fix) {
+            const other = ['json', 'md', 'pr-comment', 'badge', 'baseline', 'compare', 'max-tokens', 'max-increase', 'include-user', 'mcp'].filter((k) => o[k] !== undefined);
+            if (o.write && o.out)
+                other.push('out');
+            if (other.length)
+                throw new UsageError(`--fix${o.write ? ' --write' : ''} cannot be combined with --${other.join(', --')}.`);
+            return await fix(root, tools, Boolean(o.write), o.out);
+        }
         const files = await discover(root);
         if (o.baseline && o.compare)
             throw new UsageError('Use --baseline or --compare, not both.');
@@ -276,6 +294,34 @@ export async function main(argv, env = process.env) {
         return 1;
     }
 }
+async function fix(root, tools, write, out) {
+    const files = await discover(root);
+    const plan = planFixes(files, { tools, exists: existsIn(root), readOnly: linkedPaths(root, files) });
+    const log = (line) => (write ? process.stdout : process.stderr).write(line + '\n');
+    for (const f of plan.fixes)
+        log(`fix: ${f.message}${f.savingTokens ? ` [saves ~${f.savingTokens} tokens/turn]` : ''}`);
+    for (const s of plan.skipped)
+        log(`skipped ${s.kind}: ${s.reason}`);
+    if (!plan.changes.length) {
+        // An empty patch, so an earlier patch in the same file is not applied again.
+        if (out && !write)
+            writeFileSync(out, '');
+        log('Nothing to fix automatically.');
+        return 0;
+    }
+    if (write) {
+        applyChanges(root, plan.changes);
+        log(`Changed ${plan.changes.length} file(s): ${plan.changes.map((c) => c.path).join(', ')}`);
+        return 0;
+    }
+    const diff = unifiedDiff(plan.changes);
+    if (out)
+        writeFileSync(out, diff);
+    else
+        process.stdout.write(diff);
+    log('Preview only. Run again with --write to apply, or save the diff and use git apply.');
+    return 0;
+}
 function nonNegativeInt(name, value) {
     const n = Number(value);
     if (!Number.isInteger(n) || n < 0)

package/dist/core/advice.js

@@ -265,11 +265,8 @@ function sections(units, threshold) {
         const tools = toolsWith(units, u.path, 'always');
         for (const s of splitSections(u.text)) {
             const tokens = countO200k(s.text);
-            const refs = pathRefs(s.text).filter((r) => !r.startsWith('.'));
-            const dirs = refs.map((r) => r.split('/')[0]);
-            const top = mostCommon(dirs);
-            if (tokens >= 100 && top && top.count >= 2 && top.count / dirs.length >= 0.6) {
-                const scope = commonDir(refs.filter((r) => r.startsWith(top.value + '/')));
+            const scope = sectionScope(s.text);
+            if (scope) {
                 out.push({
                     kind: 'scopable-section',
                     severity: 'medium',
@@ -297,6 +294,17 @@ function sections(units, threshold) {
     }
     return out;
 }
+/** The directory a section is mostly about (for example `packages/api`), or null when it is not scopable. */
+export function sectionScope(text) {
+    if (countO200k(text) < 100)
+        return null;
+    const refs = pathRefs(text).filter((r) => !r.startsWith('.'));
+    const dirs = refs.map((r) => r.split('/')[0]);
+    const top = mostCommon(dirs);
+    if (!top || top.count < 2 || top.count / dirs.length < 0.6)
+        return null;
+    return commonDir(refs.filter((r) => r.startsWith(top.value + '/')));
+}
 /** Longest directory prefix shared by all refs, e.g. `packages/api` for `packages/api/db.ts` and `packages/api/handlers/`. */
 function commonDir(refs) {
     const dirs = refs.map((r) => (r.endsWith('/') ? r.slice(0, -1) : r.slice(0, r.lastIndexOf('/'))).split('/'));

package/dist/core/fix.js

@@ -0,0 +1,431 @@
+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) => !isInstructionFile(path)
+        ? `${path} is not an agent instruction file (it is @imported); it is left alone.`
+        : opts.readOnly?.(path)
+            ? `${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');
+        if (readOnly(f.path) || ws.files.has(to)) {
+            skipped.push({ kind: 'misconfigured', paths: [f.path], reason: readOnly(f.path) ?? `${to} already exists.` });
+            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));
+                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)}.` : ''),
+                    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.`,
+                });
+        }
+    }
+}
+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/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/discover.js

@@ -1,5 +1,5 @@
-import { existsSync, lstatSync, readdirSync, readFileSync, statSync } from 'node:fs';
-import { join } from 'node:path';
+import { existsSync, lstatSync, readdirSync, readFileSync, realpathSync, statSync } from 'node:fs';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { MAX_DEPTH, addImports, isInstructionFile, isSkippedDir } from '../core/files.js';
 import { MCP_CONFIGS, USER_MCP_PATHS } from '../core/mcp.js';
 import { USER_ROOTS, isUserInstructionFile } from '../core/user.js';
@@ -106,3 +106,36 @@ export function discoverUser(home) {
     });
     return { files: [...files.values()].sort((a, b) => a.path.localeCompare(b.path)), mcpConfigs };
 }
+/** The real location of `p`, following symlinks in the part of the path that exists; null behind a dangling symlink. */
+export function realLocation(p) {
+    if (lstatSync(p, { throwIfNoEntry: false })) {
+        try {
+            return realpathSync(p);
+        }
+        catch {
+            return null;
+        }
+    }
+    const parent = dirname(p);
+    if (parent === p)
+        return p;
+    const real = realLocation(parent);
+    return real === null ? null : resolve(real, relative(parent, p));
+}
+/**
+ * A check for paths that must not be changed: paths that are symlinks or lie under a symlinked folder
+ * (existing or not), and repository files that such a link points to.
+ */
+export function linkedPaths(root, files) {
+    const realRoot = realpathSync(root);
+    const linked = (path) => realLocation(join(root, path)) !== join(realRoot, path);
+    const targets = new Set();
+    for (const f of files) {
+        if (!linked(f.path))
+            continue;
+        const rel = relative(realRoot, realLocation(join(root, f.path)) ?? realRoot);
+        if (!rel.startsWith('..') && !isAbsolute(rel))
+            targets.add(rel.split(sep).join('/'));
+    }
+    return (path) => targets.has(path) || linked(path);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "turntax",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Measure the per-turn token cost of AI coding-agent instruction files (AGENTS.md, CLAUDE.md, Cursor, Copilot, Cline, Roo, Kiro, Windsurf and more) for every agent that reads them.",
   "license": "MIT",
   "author": "TORUT LTD",