turntax 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TORUT LTD
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,111 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# turntax
+
+Coding agents re-send their instruction files with every turn. `turntax` measures that fixed per-turn cost for a repository, per tool and per model, and shows where to cut it.
+
+```bash
+npx turntax
+```
+
+It reads the files each agent actually loads (`CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, `.cursor/rules`, `.github/copilot-instructions.md`, Windsurf rules, skills) and applies each tool's documented loading rules: 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.
+
+```text
+tool          always  o200k/turn  on-demand  model              tokens/turn  counted by                                100 turns  cached
+Claude Code   4       272         53         Claude Sonnet 5.5  -            needs --claude-api and ANTHROPIC_API_KEY  -          -
+OpenAI Codex  1       63          0          GPT-6.1 Sol        63           estimate (o200k_base proxy)               $0.01      $0.0006
+Cursor        4       297         37         Claude Sonnet 5.5  -            needs --claude-api and ANTHROPIC_API_KEY  -          -
+                                             GPT-6.1 Sol        297          estimate (o200k_base proxy)               $0.06      $0.0030
+
+Advice (savings are estimates in o200k tokens per turn)
+  HIGH duplicate CLAUDE.md, AGENTS.md [saves ~48 tokens/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]
+    Section "API package" is mostly about packages/api/. Move it to packages/api/AGENTS.md ...
+```
+
+(Output for [`test/fixtures/mixed`](test/fixtures/mixed).)
+
+## What it counts, and how
+
+| Model family | How tokens are counted | Label |
+| --- | --- | --- |
+| OpenAI GPT-5.x, gpt-oss | Offline with `o200k_base` (the encoding OpenAI's tiktoken maps them to) | exact |
+| OpenAI GPT-6.x | Offline with `o200k_base`; OpenAI has not published a newer encoding | estimate |
+| Claude | Only Anthropic's `count_tokens` API, with your key and `--claude-api` | API count |
+| Gemini | Only Google's `countTokens` API, with your key and `--gemini-api` | API count |
+
+Claude's tokenizer is not public, and Anthropic's docs note that newer Claude models produce noticeably more tokens than older ones for the same text. `turntax` never shows an OpenAI count as a Claude or Gemini number: without a key those rows say "needs API key". The `o200k` column is a labelled reference count for every file.
+
+Cost per N turns = tokens per turn × N × input price. The "cached" column assumes every turn reads the context from the prompt cache. Prices come from a dated table with a source link per model (`turntax --list-models`); pass `--prices my-prices.json` to use your own.
+
+See [docs/how-it-counts.md](docs/how-it-counts.md) for the loading rules per tool and their sources.
+
+## Advice
+
+All checks are deterministic. Each one shows an estimated saving in o200k tokens per turn.
+
+- **duplicate**: identical lines in two files. A per-turn saving only when one tool loads both; otherwise flagged as drift risk.
+- **contradiction**: conflicting rules reaching the same agent (package manager, indentation, quotes, semicolons).
+- **scopable-section**: a section mostly about one directory that could load only there (nested file, path-scoped rule, `applyTo`).
+- **oversized-section**: a large always-loaded section that could become an on-demand skill.
+- **size-limit**: documented limits (CLAUDE.md under 200 lines, Codex's 32 KiB cut-off, Windsurf's 12,000 characters, Cursor's 500 lines).
+- **misconfigured**: files a tool ignores, such as `.md` files in `.cursor/rules` or Windsurf rules without a `trigger`.
+- **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`).
+
+## Options
+
+```text
+turntax [path]
+  --tools claude-code,codex,gemini-cli,cursor,copilot,windsurf
+  --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)
+  --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)
+  --claude-api              exact Claude counts (ANTHROPIC_API_KEY)
+  --gemini-api              Gemini counts (GEMINI_API_KEY)
+  --english <file=en>       measure a language multiplier against your English version
+  --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)
+```
+
+## 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.
+
+## 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.
+
+Try it: https://torutdev.github.io/turntax/
+
+```bash
+npm run build:web
+```
+
+## Badge
+
+```bash
+npx turntax --badge
+```
+
+[![context tax (o200k)](https://img.shields.io/badge/context%20tax%20(o200k)-297%20tokens%2Fturn-brightgreen)](https://github.com/TorutDev/turntax)
+
+The badge shows the largest always-loaded total among the tools found, counted with o200k_base.
+
+## Limits
+
+- Assumes the agent starts at the repository root. Files outside the repository (user-level `~/.claude/CLAUDE.md`, global rules, team rules in a dashboard) are not counted.
+- Counts instruction files only, not the agent's own system prompt, tool definitions or MCP servers.
+- Loading rules change. Each rule cites the vendor page and the date it was checked; please open an issue when one is out of date.
+
+## Contributing
+
+Loading rules and prices go out of date. Corrections with a link to the vendor's page are the most useful contribution; see [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+MIT

package/dist/bin.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import { main } from './cli.js';
+main(process.argv.slice(2)).then((code) => {
+    process.exitCode = code;
+});

package/dist/cli.js

@@ -0,0 +1,210 @@
+import { readFileSync, writeFileSync } from 'node:fs';
+import { 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 { DEFAULT_MODEL_IDS, MODELS, validateModels } from './core/prices.js';
+import { badgeMarkdown, headlineTokens, renderMarkdown, renderText } from './core/render.js';
+import { TOOL_IDS } from './core/tools.js';
+import { discover, existsIn, packageScripts } from './node/discover.js';
+import { anthropicCounter, geminiCounter, translateToEnglish } from './node/remote.js';
+const VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
+const HELP = `turntax ${VERSION}
+Measure the token tax that agent instruction files add to every turn.
+
+Usage: turntax [path] [options]
+
+Options:
+  --tools <list>          Tools to report: ${TOOL_IDS.join(', ')} (default: tools with files)
+  --models <list>         Model ids to price (default: ${DEFAULT_MODEL_IDS.join(', ')})
+  --list-models           Print the price table and exit
+  --turns <n>             Turns for the cost projection (default: 100)
+  --json                  Print the full report as JSON
+  --md                    Print a Markdown report
+  --out <file>            Write the report to a file instead of stdout
+  --badge                 Print a shields.io badge snippet
+  --max-tokens <n>        Exit with code 1 if any tool loads more than n o200k tokens per turn
+  --claude-api            Count Claude tokens with Anthropic's count_tokens (needs ANTHROPIC_API_KEY;
+                          sends file contents to api.anthropic.com)
+  --gemini-api            Count Gemini tokens with Google's countTokens (needs GEMINI_API_KEY;
+                          sends file contents to generativelanguage.googleapis.com)
+  --english <file=en>     English version of a file, to measure its language token multiplier (repeatable)
+  --translate             Translate non-English files to English with Claude to measure the multiplier
+                          (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)
+  -h, --help              Show help
+  -v, --version           Show version
+
+Without --claude-api or --gemini-api nothing leaves your machine.
+`;
+class UsageError extends Error {
+}
+function list(value) {
+    return value
+        ?.split(',')
+        .map((s) => s.trim())
+        .filter(Boolean);
+}
+function positiveInt(name, value, fallback) {
+    if (value === undefined)
+        return fallback;
+    const n = Number(value);
+    if (!Number.isInteger(n) || n <= 0)
+        throw new UsageError(`--${name} must be a positive integer`);
+    return n;
+}
+export async function main(argv, env = process.env) {
+    let parsed;
+    try {
+        parsed = parseArgs({
+            args: argv,
+            allowPositionals: true,
+            options: {
+                tools: { type: 'string' },
+                models: { type: 'string' },
+                'list-models': { type: 'boolean' },
+                turns: { type: 'string' },
+                json: { type: 'boolean' },
+                md: { type: 'boolean' },
+                out: { type: 'string' },
+                badge: { type: 'boolean' },
+                'max-tokens': { type: 'string' },
+                'claude-api': { type: 'boolean' },
+                'gemini-api': { type: 'boolean' },
+                english: { type: 'string', multiple: true },
+                translate: { type: 'boolean' },
+                prices: { type: 'string' },
+                'section-tokens': { type: 'string' },
+                help: { type: 'boolean', short: 'h' },
+                version: { type: 'boolean', short: 'v' },
+            },
+        });
+    }
+    catch (e) {
+        process.stderr.write(`${e.message}\n\n${HELP}`);
+        return 2;
+    }
+    const { values: o, positionals } = parsed;
+    if (o.help) {
+        process.stdout.write(HELP);
+        return 0;
+    }
+    if (o.version) {
+        process.stdout.write(`${VERSION}\n`);
+        return 0;
+    }
+    try {
+        let catalog = MODELS;
+        if (o.prices) {
+            const data = JSON.parse(readFileSync(o.prices, 'utf8'));
+            const problems = validateModels(data);
+            if (problems.length)
+                throw new UsageError(`Invalid price table ${o.prices}:\n  ${problems.join('\n  ')}`);
+            catalog = data;
+        }
+        if (o['list-models']) {
+            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 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);
+        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 files = await discover(root);
+        const counters = {};
+        if (o['claude-api']) {
+            const key = env.ANTHROPIC_API_KEY;
+            if (!key)
+                throw new UsageError('--claude-api needs the ANTHROPIC_API_KEY environment variable.');
+            counters.claude = anthropicCounter(key);
+            if (models.some((m) => m.family === 'claude'))
+                notice(`Sending instruction file contents to api.anthropic.com to count Claude tokens.`);
+        }
+        if (o['gemini-api']) {
+            const key = env.GEMINI_API_KEY;
+            if (!key)
+                throw new UsageError('--gemini-api needs the GEMINI_API_KEY environment variable.');
+            counters.gemini = geminiCounter(key);
+            if (models.some((m) => m.family === 'gemini'))
+                notice(`Sending instruction file contents to generativelanguage.googleapis.com to count Gemini tokens.`);
+        }
+        const english = new Map();
+        for (const pair of o.english ?? []) {
+            const [target, source] = pair.split('=');
+            if (!target || !source)
+                throw new UsageError(`--english expects file=englishFile, got "${pair}"`);
+            english.set(relative(root, resolve(root, target)).replace(/\\/g, '/'), readFileSync(source, 'utf8'));
+        }
+        if (o.translate) {
+            if (!o['claude-api'] || !env.ANTHROPIC_API_KEY)
+                throw new UsageError('--translate needs --claude-api and ANTHROPIC_API_KEY.');
+            const always = classify(files, tools).filter((u) => u.mode === 'always' && u.part !== 'description');
+            const targets = [...new Set(always.filter((u) => hasNonEnglish(u.text)).map((u) => u.path))];
+            for (const path of targets) {
+                if (english.has(path))
+                    continue;
+                notice(`Translating ${path} with Claude (api.anthropic.com) to measure its language multiplier.`);
+                try {
+                    english.set(path, await translateToEnglish(env.ANTHROPIC_API_KEY, files.find((f) => f.path === path).text));
+                }
+                catch (e) {
+                    notice(`Could not translate ${path}: ${e.message}. Its multiplier is not measured.`);
+                }
+            }
+        }
+        const report = await audit(files, {
+            tools,
+            models,
+            counters,
+            turns: positiveInt('turns', o.turns, 100),
+            advice: {
+                exists: existsIn(root),
+                packageScripts: packageScripts(root),
+                english,
+                sectionTokens: positiveInt('section-tokens', o['section-tokens'], 600),
+            },
+        });
+        const output = o.json
+            ? JSON.stringify({ root, ...report }, null, 2) + '\n'
+            : 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);
+        const max = o['max-tokens'] === undefined ? undefined : 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`);
+            return 1;
+        }
+        return 0;
+    }
+    catch (e) {
+        if (e instanceof UsageError) {
+            process.stderr.write(`turntax: ${e.message}\n`);
+            return 2;
+        }
+        process.stderr.write(`turntax: ${e.message}\n`);
+        return 1;
+    }
+}
+function notice(message) {
+    process.stderr.write(`turntax: ${message}\n`);
+}
+function describeModel(m) {
+    const counting = m.offline === 'o200k-exact' ? 'offline exact' : m.offline === 'o200k-proxy' ? 'offline proxy (o200k)' : 'API only';
+    return `${m.id.padEnd(20)} ${m.label.padEnd(26)} in $${m.inputPerMTok ?? 'n/a'}  cached $${m.cachedInputPerMTok ?? 'n/a'}  ${counting}  (${m.checkedAt})`;
+}