turntax 0.4.0 → 0.5.0

package/README.md

@@ -8,6 +8,8 @@ npx 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.
 
+[State of agent instruction files, October 2026](https://torutdev.github.io/turntax/state/): what turntax finds in 100 popular repositories, with pinned commits and the script to reproduce it ([`scripts/state-of.mjs`](scripts/state-of.mjs)).
+
 ## Supported agents
 
 Each agent's documented loading rules decide what is sent on every turn, what loads only when the agent works in a folder or touches a matching file, and what is ignored.
@@ -49,7 +51,7 @@ Advice (savings are estimates in o200k tokens per turn)
     3 identical lines are loaded twice every turn by cursor. Keep them in one file.
   HIGH contradiction AGENTS.md, CLAUDE.md [saves ~11 tokens/turn]
     Conflicting package manager: "Always use npm ..." (AGENTS.md:3) vs "Always use pnpm ..." (CLAUDE.md:5).
-  MEDIUM scopable-section CLAUDE.md:11 [saves ~128 tokens/turn]
+  MEDIUM scopable-section CLAUDE.md:12 [saves ~128 tokens/turn]
     Section "API package" is mostly about packages/api/. Move it to packages/api/AGENTS.md ...
 ```
 
@@ -100,6 +102,24 @@ Before a fix is kept, the files are classified again with the change applied: ev
 
 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.
 
+The web page shows the same fixes for any repository you load, with a downloadable `fix.patch`.
+
+## Config file
+
+Put defaults in `turntax.config.json` in the audited folder (or pass `--config <file>`). Command-line flags override it.
+
+```json
+{
+  "tools": ["claude-code", "codex", "cursor"],
+  "models": ["claude-sonnet-5.5", "gpt-6.1-sol"],
+  "maxTokens": 8000,
+  "maxIncrease": 500,
+  "ignore": ["docs/agents/archive/", "**/*.draft.md"]
+}
+```
+
+Keys: `tools`, `models`, `turns`, `maxTokens`, `maxIncrease` (applies only with `--compare` or `--baseline`), `sectionTokens`, and `ignore`: globs of instruction files to leave out, relative to the audited folder (`*` and `?` within a folder name, `**` across folders, a trailing `/` for a whole folder). Ignored files are also left out of `--compare` and are never changed by `--fix`. Unknown keys and ids are errors.
+
 ## 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:
@@ -152,7 +172,7 @@ The comparison covers repository instruction files (o200k), per agent and per fi
 
 ## GitHub Action
 
-The repository is also an Action. On pull requests it compares with the base branch, posts one comment (updated on every push) and writes the report to the job summary:
+The repository is also an Action. On pull requests it compares with the base branch, posts one comment (updated on every push), writes the report to the job summary and marks findings on the lines they are about in the pull request's changed files (GitHub shows up to 10 warnings and 10 notices per step):
 
 ```yaml
 name: turntax
@@ -165,14 +185,15 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: TorutDev/turntax@v0.4.0
+      - uses: TorutDev/turntax@v0.5.0
         with:
           max-increase: 500      # optional: fail when an agent grows by more than 500 tokens per turn
           # max-tokens: 8000     # optional: absolute budget
           # args: --tools claude-code,cursor
+          # annotations: false   # optional: no findings on the changed lines
 ```
 
-The comment opens with a table of the change per agent and per file, and folds the full report below it. Pull requests from forks get a read-only token, so the comment step is skipped there; the job summary still has the report.
+The comment opens with a table of the change per agent and per file. When `--fix` has safe fixes, it says how many and how many tokens they save, with the diff folded; the full report is folded below. A `turntax.config.json` in the repository is read as well. Pull requests from forks get a read-only token, so the comment step is skipped there; the job summary still has the report.
 
 ## Options
 
@@ -182,7 +203,8 @@ turntax [path]
   --models <ids>            see --list-models (default: claude-sonnet-5.5, gpt-6.1-sol, gemini-3.8-flash)
   --turns <n>               cost projection (default 100)
   --json | --md | --badge   output format (default: terminal table)
-  --pr-comment              Markdown for a pull request comment (change first, full report folded)
+  --pr-comment              Markdown for a pull request comment (change first, fixes and full report folded)
+  --annotations             GitHub Actions annotations, one per finding (--path-prefix <dir> for a subfolder)
   --out <file>              write the output to a file
   --max-tokens <n>          exit 1 when any tool loads more than n o200k tokens per turn (CI gate)
   --include-user            add user-level files and MCP servers from your home directory
@@ -199,8 +221,11 @@ turntax [path]
   --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
+  --config <file>           read defaults from this file (default: turntax.config.json, if any)
 ```
 
+When a selected model's price was checked more than 90 days ago, turntax says so on stderr; check the source or pass `--prices`.
+
 ## 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.

package/dist/cli.js

@@ -1,18 +1,20 @@
 import { readFileSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { basename, relative, resolve } from 'node:path';
+import { basename, isAbsolute, posix, relative, resolve } from 'node:path';
 import { parseArgs } from 'node:util';
 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 { globMatcher } from './core/glob.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 { badgeMarkdown, headlineTokens, renderAnnotations, renderMarkdown, renderPrComment, renderText } from './core/render.js';
 import { countO200k } from './core/tokenize.js';
 import { TOOL_IDS } from './core/tools.js';
 import { applyChanges } from './node/apply.js';
+import { CONFIG_FILE, loadConfig } from './node/config.js';
 import { discover, discoverMcpConfigs, discoverUser, existsIn, linkedPaths, packageScripts } from './node/discover.js';
 import { filesAtRef } from './node/git.js';
 import { measureServer } from './node/mcp.js';
@@ -33,6 +35,8 @@ Options:
   --pr-comment            Print a pull request comment: the change first, the full report folded
   --out <file>            Write the report to a file instead of stdout
   --badge                 Print a shields.io badge snippet
+  --annotations           Print GitHub Actions annotations for the advice, shown inline on pull requests
+  --path-prefix <dir>     With --annotations, the audited folder relative to the repository root
   --max-tokens <n>        Exit with code 1 if any tool loads more than n o200k tokens per turn
                           (repository files plus measured project MCP tools)
   --include-user          Also count user-level files and MCP servers in your home directory
@@ -57,9 +61,17 @@ Options:
                           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
+  --config <file>         Read defaults from this file (default: ${CONFIG_FILE} in the audited folder, if any)
   -h, --help              Show help
   -v, --version           Show version
 
+Config file keys (all optional; command-line flags override them):
+  tools, models           Lists of ids, like --tools and --models
+  turns, maxTokens, maxIncrease, sectionTokens
+                          Integers, like the matching flags (maxIncrease applies only when comparing)
+  ignore                  Globs of instruction files to leave out, relative to the audited folder (* and ? within a
+                          folder name, ** across folders, a trailing / for a whole folder)
+
 Without --claude-api, --gemini-api or --mcp nothing leaves your machine.
 `;
 class UsageError extends Error {
@@ -78,7 +90,7 @@ function positiveInt(name, value, fallback) {
         throw new UsageError(`--${name} must be a positive integer`);
     return n;
 }
-export async function main(argv, env = process.env) {
+export async function main(argv, env = process.env, now = new Date()) {
     let parsed;
     try {
         parsed = parseArgs({
@@ -94,6 +106,9 @@ export async function main(argv, env = process.env) {
                 'pr-comment': { type: 'boolean' },
                 out: { type: 'string' },
                 badge: { type: 'boolean' },
+                annotations: { type: 'boolean' },
+                'path-prefix': { type: 'string' },
+                config: { type: 'string' },
                 'max-tokens': { type: 'string' },
                 'claude-api': { type: 'boolean' },
                 'gemini-api': { type: 'boolean' },
@@ -140,34 +155,56 @@ export async function main(argv, env = process.env) {
             process.stdout.write(o.json ? JSON.stringify(catalog, null, 2) + '\n' : catalog.map(describeModel).join('\n') + '\n');
             return 0;
         }
-        const modelIds = list(o.models) ?? DEFAULT_MODEL_IDS.filter((id) => catalog.some((m) => m.id === id));
+        const root = resolve(positionals[0] ?? '.');
+        let config;
+        try {
+            config = loadConfig(root, o.config, catalog);
+        }
+        catch (e) {
+            throw new UsageError(e.message);
+        }
+        const modelIds = list(o.models) ?? config.models ?? DEFAULT_MODEL_IDS.filter((id) => catalog.some((m) => m.id === id));
         const models = modelIds.map((id) => {
             const m = catalog.find((x) => x.id === id);
             if (!m)
                 throw new UsageError(`Unknown model "${id}". Run --list-models.`);
             return m;
         });
-        const tools = list(o.tools);
+        const tools = list(o.tools) ?? config.tools;
         for (const t of tools ?? [])
             if (!TOOL_IDS.includes(t))
                 throw new UsageError(`Unknown tool "${t}". Use: ${TOOL_IDS.join(', ')}`);
-        const root = resolve(positionals[0] ?? '.');
+        const ignored = globMatcher(config.ignore ?? []);
+        const repoFiles = (files) => files.filter((f) => !ignored(f.path));
         if (o.write && !o.fix)
             throw new UsageError('--write needs --fix.');
+        if (o['path-prefix'] !== undefined && !o.annotations)
+            throw new UsageError('--path-prefix needs --annotations.');
+        if (o.annotations) {
+            const other = ['json', 'md', 'pr-comment', 'badge', 'fix'].filter((k) => o[k] !== undefined);
+            if (other.length)
+                throw new UsageError(`--annotations cannot be combined with --${other.join(', --')}.`);
+        }
         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);
+            return await fix(root, tools, ignored, Boolean(o.write), o.out);
         }
-        const files = await discover(root);
+        const discovered = await discover(root);
+        const files = repoFiles(discovered);
+        // Budgets in the config are for report runs; an --annotations run only prints findings.
+        const gates = o.annotations ? {} : config;
+        const label = (flag, key) => o[flag] !== undefined ? `--${flag}` : `${key} in ${o.config ?? CONFIG_FILE}`;
         if (o.baseline && o.compare)
             throw new UsageError('Use --baseline or --compare, not both.');
+        // The config's maxIncrease applies only when a comparison runs, so plain local runs keep working.
         if (o['max-increase'] !== undefined && !o.baseline && !o.compare)
             throw new UsageError('--max-increase needs --baseline or --compare.');
-        const maxIncreaseLimit = o['max-increase'] === undefined ? undefined : nonNegativeInt('max-increase', o['max-increase']);
+        const maxIncreaseLimit = o['max-increase'] === undefined ? gates.maxIncrease : nonNegativeInt('max-increase', o['max-increase']);
+        stalePrices(models, now);
         let userFiles = [];
         let mcpFiles = discoverMcpConfigs(root);
         if (o['include-user']) {
@@ -229,14 +266,14 @@ export async function main(argv, env = process.env) {
             tools,
             models,
             counters,
-            turns: positiveInt('turns', o.turns, 100),
+            turns: positiveInt('turns', o.turns, config.turns ?? 100),
             userFiles,
             mcp: { servers, measured },
             advice: {
                 exists: existsIn(root),
                 packageScripts: packageScripts(root),
                 english,
-                sectionTokens: positiveInt('section-tokens', o['section-tokens'], 600),
+                sectionTokens: positiveInt('section-tokens', o['section-tokens'], config.sectionTokens ?? 600),
             },
         });
         if (o.baseline) {
@@ -253,7 +290,7 @@ export async function main(argv, env = process.env) {
             const base = await filesAtRef(root, o.compare).catch((e) => {
                 throw new UsageError(e.message);
             });
-            const before = await audit(base.files, {
+            const before = await audit(repoFiles(base.files), {
                 tools,
                 models: [],
                 mcp: { servers: parseMcpConfigs(base.mcpConfigs, root).servers },
@@ -263,24 +300,26 @@ export async function main(argv, env = process.env) {
         const output = o.json
             ? JSON.stringify({ root, ...report }, null, 2) + '\n'
             : o['pr-comment']
-                ? renderPrComment(report)
-                : o.md
-                    ? renderMarkdown(report)
-                    : o.badge
-                        ? badgeMarkdown(report) + '\n'
-                        : renderText(report, root) + '\n';
+                ? renderPrComment(report, files.length ? fixPlan(root, discovered, tools, ignored) : undefined, fixCommand(positionals[0], o.config, o.tools))
+                : o.annotations
+                    ? renderAnnotations(report, pathPrefix(o['path-prefix']))
+                    : o.md
+                        ? renderMarkdown(report)
+                        : o.badge
+                            ? badgeMarkdown(report) + '\n'
+                            : renderText(report, root) + '\n';
         if (o.out)
             writeFileSync(o.out, output);
         else
             process.stdout.write(output);
         let code = 0;
-        const max = o['max-tokens'] === undefined ? undefined : positiveInt('max-tokens', o['max-tokens'], 0);
+        const max = o['max-tokens'] === undefined ? gates.maxTokens : positiveInt('max-tokens', o['max-tokens'], 0);
         if (max !== undefined && headlineTokens(report) > max) {
-            process.stderr.write(`turntax: ${headlineTokens(report)} o200k tokens per turn exceeds --max-tokens ${max}\n`);
+            process.stderr.write(`turntax: ${headlineTokens(report)} o200k tokens per turn exceeds ${label('max-tokens', 'maxTokens')} ${max}\n`);
             code = 1;
         }
         if (maxIncreaseLimit !== undefined && report.diff && maxIncrease(report.diff) > maxIncreaseLimit) {
-            process.stderr.write(`turntax: per-turn tokens grew by ${maxIncrease(report.diff)} vs ${report.diff.base}, more than --max-increase ${maxIncreaseLimit}\n`);
+            process.stderr.write(`turntax: per-turn tokens grew by ${maxIncrease(report.diff)} vs ${report.diff.base}, more than ${label('max-increase', 'maxIncrease')} ${maxIncreaseLimit}\n`);
             code = 1;
         }
         return code;
@@ -294,9 +333,9 @@ 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) });
+async function fix(root, tools, ignored, write, out) {
+    const discovered = await discover(root);
+    const plan = fixPlan(root, discovered, tools, ignored);
     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]` : ''}`);
@@ -322,6 +361,47 @@ async function fix(root, tools, write, out) {
     log('Preview only. Run again with --write to apply, or save the diff and use git apply.');
     return 0;
 }
+/**
+ * Safe fixes. The plan sees every repository file, ignored ones included, because the agents still read
+ * them and the safety check must see what they read; symlinks, their targets and ignored files are never
+ * written.
+ */
+function fixPlan(root, discovered, tools, ignored) {
+    const linked = linkedPaths(root, discovered);
+    return planFixes(discovered, {
+        tools,
+        exists: existsIn(root),
+        readOnly: (p) => (ignored(p) ? `${p} is in the config's ignore list; it is left alone.` : linked(p)),
+    });
+}
+/** The --fix command matching the run that made a pull request comment. */
+function fixCommand(path, config, tools) {
+    const arg = (s) => (/^[\w./@:,=-]+$/.test(s) ? s : `"${s}"`);
+    const parts = ['npx turntax'];
+    if (path && path !== '.' && !isAbsolute(path))
+        parts.push(arg(path));
+    if (config)
+        parts.push('--config', arg(config));
+    if (tools)
+        parts.push('--tools', arg(tools));
+    return [...parts, '--fix'].join(' ');
+}
+/** `--path-prefix` as a POSIX folder ending in a slash, or '' for the repository root. */
+function pathPrefix(dir) {
+    if (!dir)
+        return '';
+    const p = posix.normalize(dir.replace(/\\/g, '/') + '/');
+    return p === './' ? '' : p;
+}
+/** One notice when a selected model's price was checked more than 90 days before `now`. */
+function stalePrices(models, now) {
+    const today = Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate());
+    const stale = models.filter((m) => today - Date.parse(m.checkedAt) > 90 * 86_400_000);
+    if (!stale.length)
+        return;
+    const dates = [...new Set(stale.map((m) => m.checkedAt))].sort();
+    notice(`prices for ${stale.map((m) => m.label).join(', ')} were checked on ${dates.join(', ')}, over 90 days ago; check the sources or pass --prices.`);
+}
 function nonNegativeInt(name, value) {
     const n = Number(value);
     if (!Number.isInteger(n) || n < 0)

package/dist/core/advice.js

@@ -5,18 +5,57 @@ const DEFAULT_SECTION_TOKENS = 600;
 export function buildAdvice(units, files, opts = {}) {
     // User-level files take part in checks across files; moving sections or checking paths only makes sense in the repository.
     const repo = units.filter((u) => !u.scope);
+    const raw = rawLines(files);
     const advice = [
         ...misconfigured(units),
         ...sizeLimits(units, files),
         ...duplicates(units),
-        ...contradictions(units),
-        ...sections(repo, opts.sectionTokens ?? DEFAULT_SECTION_TOKENS),
-        ...nonEnglish(units, opts.english),
-        ...staleReferences(repo, opts),
+        ...contradictions(units, raw),
+        ...sections(repo, opts.sectionTokens ?? DEFAULT_SECTION_TOKENS, raw, opts.exists),
+        ...nonEnglish(units, raw, opts.english),
+        ...staleReferences(repo, opts, raw),
     ];
     const order = { high: 0, medium: 1, low: 2 };
     return advice.sort((a, b) => order[a.severity] - order[b.severity] || (b.savingTokens ?? 0) - (a.savingTokens ?? 0));
 }
+function rawLines(files) {
+    const byPath = new Map(files.map((f) => [f.path, f.text]));
+    const cache = new Map();
+    return (u, line) => {
+        const key = `${u.path}\0${u.text}`;
+        let map = cache.get(key);
+        if (!map)
+            cache.set(key, (map = alignLines(u.text, byPath.get(u.path))));
+        return map[line - 1];
+    };
+}
+/**
+ * For each line of `text` (what an agent loads: frontmatter, HTML comments or a truncated tail removed),
+ * the 1-based line of `raw` it comes from. Lines are only ever removed, so line i is at raw line i or later.
+ */
+function alignLines(text, raw) {
+    if (raw === undefined)
+        return [];
+    const lines = text.split(/\r?\n/);
+    const rawLines = raw.split(/\r?\n/);
+    // Frontmatter removed: the text is the end of the file.
+    const offset = rawLines.length - lines.length;
+    if (offset >= 0 && rawLines.slice(offset).join('\n') === lines.join('\n'))
+        return lines.map((_, i) => offset + i + 1);
+    const out = [];
+    let next = 0;
+    lines.forEach((line, i) => {
+        const want = line.trim();
+        for (let j = Math.max(next, i); j < rawLines.length; j++) {
+            if (rawLines[j].trim() !== want)
+                continue;
+            out[i] = j + 1;
+            next = j + 1;
+            return;
+        }
+    });
+    return out;
+}
 /** Units that carry real instruction text (not skill descriptions), grouped by path. */
 function contentUnits(units, modes = ['always', 'on-demand']) {
     return units.filter((u) => u.part !== 'description' && modes.includes(u.mode));
@@ -146,6 +185,7 @@ function duplicates(units) {
     }
     return out;
 }
+const at = (d) => (d.line ? `${d.path}:${d.line}` : d.path);
 const DIRECTIVES = [
     {
         topic: 'package manager',
@@ -203,7 +243,7 @@ function conflicts(a, b) {
         return a === `not ${b}` || b === `not ${a}`;
     return true;
 }
-function contradictions(units) {
+function contradictions(units, raw) {
     const found = new Map();
     const tools = [...new Set(units.map((u) => u.tool))];
     for (const tool of tools) {
@@ -213,7 +253,7 @@ function contradictions(units) {
                 if (inFence)
                     return;
                 for (const d of directivesIn(line))
-                    directives.push({ ...d, path: u.path, line: i + 1, text: line.trim() });
+                    directives.push({ ...d, path: u.path, line: raw(u, i + 1), text: line.trim() });
             });
         }
         for (let i = 0; i < directives.length; i++) {
@@ -222,7 +262,7 @@ function contradictions(units) {
                 const b = directives[j];
                 if (a.topic !== b.topic || !conflicts(a.value, b.value))
                     continue;
-                const key = [a.topic, `${a.path}:${a.line}`, `${b.path}:${b.line}`].join('|');
+                const key = [a.topic, at(a), at(b), a.text, b.text].join('|');
                 const prev = found.get(key);
                 if (prev) {
                     prev.tools.push(tool);
@@ -234,7 +274,7 @@ function contradictions(units) {
                     severity: 'high',
                     tools: [tool],
                     paths: [...new Set([a.path, b.path])],
-                    message: `Conflicting ${a.topic}: "${a.text}" (${a.path}:${a.line}) vs "${b.text}" (${b.path}:${b.line}).`,
+                    message: `Conflicting ${a.topic}: "${a.text}" (${at(a)}) vs "${b.text}" (${at(b)}).`,
                     savingTokens: countO200k(shorter),
                     savingNote: 'Removing the outdated line.',
                 });
@@ -259,20 +299,21 @@ export function pathRefs(text) {
         .map((r) => r.replace(/^\.\//, '').replace(/[),.;:]+$/, ''))
         .filter((r) => r.includes('/') && !/^(https?:|~|\/|[A-Za-z]:|@|<)/.test(r) && !/[*?{}<>$]/.test(r));
 }
-function sections(units, threshold) {
+function sections(units, threshold, raw, exists) {
     const out = [];
     for (const u of uniqueByPath(contentUnits(units, ['always']))) {
         const tools = toolsWith(units, u.path, 'always');
         for (const s of splitSections(u.text)) {
             const tokens = countO200k(s.text);
+            // A folder that does not exist (a URL path, a placeholder) is not a place the section can move to.
             const scope = sectionScope(s.text);
-            if (scope) {
+            if (scope && (!exists || exists(scope))) {
                 out.push({
                     kind: 'scopable-section',
                     severity: 'medium',
                     tools,
                     paths: [u.path],
-                    line: s.line,
+                    line: raw(u, s.line),
                     message: `Section "${s.heading}" is mostly about ${scope}/. Move it to ${scope}/AGENTS.md (or CLAUDE.md), a path-scoped rule, or an instructions file with applyTo so it loads only when the agent works there.`,
                     savingTokens: tokens,
                     savingNote: 'Saved on turns that do not touch that directory.',
@@ -284,7 +325,7 @@ function sections(units, threshold) {
                     severity: 'medium',
                     tools,
                     paths: [u.path],
-                    line: s.line,
+                    line: raw(u, s.line),
                     message: `Section "${s.heading}" is ${tokens} tokens and loads every turn. If it is a procedure (release, deploy, migration), move it into an on-demand skill or rule and keep a one-line pointer.`,
                     savingTokens: Math.max(0, tokens - 30),
                     savingNote: 'Assumes about 30 tokens remain for the skill description or pointer.',
@@ -357,14 +398,16 @@ export function guessLanguage(text) {
     if (words.length < 15)
         return { nonEnglish: false, script: 'Latin' };
     const stop = words.filter((w) => EN_STOPWORDS.has(w)).length / words.length;
-    const diacritics = letters.filter((c) => /[^\u0000-\u007F]/.test(c)).length / letters.length;
-    return { nonEnglish: stop < 0.12 || (diacritics > 0.03 && stop < 0.2), script: 'Latin' };
+    // Terse English (bullet lists, commands) has few stopwords too, so Latin text also needs words with
+    // accented letters: a few percent of words in German, French, Spanish or Turkish, none in plain English.
+    const accented = words.filter((w) => /[^\u0000-\u007F]/.test(w)).length / words.length;
+    return { nonEnglish: stop < 0.2 && accented >= 0.04, script: 'Latin' };
 }
 /** True when any heading section of the text looks non-English. */
 export function hasNonEnglish(text) {
     return splitSections(text).some((s) => guessLanguage(s.text).nonEnglish);
 }
-function nonEnglish(units, english) {
+function nonEnglish(units, raw, english) {
     const out = [];
     for (const u of uniqueByPath(contentUnits(units, ['always']))) {
         const parts = splitSections(u.text).filter((s) => guessLanguage(s.text).nonEnglish);
@@ -394,7 +437,7 @@ function nonEnglish(units, english) {
                 severity: 'low',
                 tools,
                 paths: [u.path],
-                line: parts[0].line,
+                line: raw(u, parts[0].line),
                 message: `${parts.length} section(s) (${tokens} tokens) in ${script} script look non-English. Pass --english ${u.path}=<english file> or --translate to measure the multiplier.`,
                 savingTokens: null,
                 savingNote: 'Not measured without an English version.',
@@ -408,7 +451,7 @@ function isNested(path) {
     const dir = dirname(path);
     return dir !== '' && !/^\.(claude|github|cursor|windsurf|devin|agents|clinerules|cline|roo|kiro|junie|continue)(\/|$)/.test(dir);
 }
-function staleReferences(units, opts) {
+function staleReferences(units, opts, raw) {
     const out = [];
     for (const u of uniqueByPath(contentUnits(units))) {
         const tools = [...new Set(units.filter((x) => x.path === u.path && x.mode !== 'ignored').map((x) => x.tool))];
@@ -424,18 +467,21 @@ function staleReferences(units, opts) {
                     const first = ref.split('/')[0];
                     if (/^(path|example|foo|your|my)/i.test(first))
                         continue;
+                    // Paths with .. can point outside the repository, where nothing can be checked.
+                    if (ref.split('/').includes('..'))
+                        continue;
                     // Only flag when the top-level folder exists but the file does not: likely moved or deleted.
                     // Paths may be written relative to the repository root or to the instruction file.
                     const local = resolvePath(u.path, ref);
                     if (opts.exists(first) && !opts.exists(ref) && !(local && opts.exists(local)))
-                        missing.push({ ref, line, n: i + 1 });
+                        missing.push({ ref, line, n: raw(u, i + 1) });
                 }
             }
             // Root package.json scripts only apply to root-level instruction files, not nested packages.
             if (opts.packageScripts && !isNested(u.path)) {
                 for (const m of line.matchAll(/\b(?:npm|pnpm|yarn|bun) run (?!-)([\w:.-]+)/g)) {
                     if (!opts.packageScripts.has(m[1]))
-                        missing.push({ ref: `script "${m[1]}"`, line, n: i + 1 });
+                        missing.push({ ref: `script "${m[1]}"`, line, n: raw(u, i + 1) });
                 }
             }
         });
@@ -447,8 +493,8 @@ function staleReferences(units, opts) {
             severity: 'medium',
             tools,
             paths: [u.path],
-            line: missing[0].n,
-            message: `References that no longer exist: ${[...new Set(missing.map((m) => `${m.ref} (line ${m.n})`))].join(', ')}.`,
+            line: missing.find((m) => m.n)?.n,
+            message: `References that no longer exist: ${[...new Set(missing.map((m) => (m.n ? `${m.ref} (line ${m.n})` : m.ref)))].join(', ')}.`,
             savingTokens: countO200k(uniqueLines.join('\n')),
             savingNote: 'If those lines are obsolete; update them instead if they are still relevant.',
         });

package/dist/core/fix.js

@@ -103,11 +103,12 @@ 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 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 = [];
@@ -137,8 +138,9 @@ function renameCursorRules(ws, readOnly, renames, fixes, skipped) {
         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.` });
+        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]]));
@@ -320,12 +322,14 @@ function moveScopableSections(ws, opts, readOnly, fixes, skipped) {
                 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)}.` : ''),
+                        (added.length ? ` Now also read there by ${names(added)}.` : '') +
+                        (dropped.length ? ` Not kept for ${names(dropped)} (outside --tools).` : ''),
                     savingTokens: countO200k(body),
                 });
                 moved = true;
@@ -340,6 +344,13 @@ function moveScopableSections(ws, opts, readOnly, fixes, skipped) {
         }
     }
 }
+/** 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}.`;

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/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;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "turntax",
-  "version": "0.4.0",
+  "version": "0.5.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",