ts-axi 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cristian Mos
+
+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,120 @@
-# Temporary Holding Version
+# ts-axi
 
-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.
+Agent-ergonomic **TypeScript / JavaScript** code CLI, built on the [AXI](https://axi.md) principles: token-efficient [TOON](https://toonformat.dev/) output, minimal schemas, pre-computed aggregates, definitive empty states, structured errors and next-step hints.
+
+It is **change-impact first**. When an agent reviews a diff, the expensive question is "what else does this touch?" - normally answered by grepping and reading dozens of files. `ts-axi impact` answers it from the compiler's own symbol resolution: for every declaration the diff changes, it lists the references *outside* the change set, grouped by file, with test coverage counted separately.
+
+```
+# real output: test/integration/sample on a branch that adds a `locale` parameter
+# to formatPrice and edits the body of Cart.total
+$ ts-axi impact main...HEAD
+base: 923fb4d7ddc8f4e5c4df9029be388f8cb29ce095
+head: HEAD
+changes: 2
+changed[2]{symbol,kind,change,exported,at,refs_total,refs_outside,files,tests}:
+  formatPrice,function,signature,true,"src/lib/format.ts:5",13,12,6,2
+  Cart.total,method,body,true,"src/lib/cart.ts:32",8,8,5,3
+refs[20]{symbol,file,line,context}:
+  formatPrice,src/components/Counter.tsx,2,"import { formatPrice } from '../lib';"
+  formatPrice,src/components/Counter.tsx,12,"{cups} cups = {formatPrice(cups * CUP_CENTS)}"
+  formatPrice,src/lib/analytics.js,4,"return { event: 'purchase', value: formatPrice(cents, 'EUR') };"
+  ...
+  Cart.total,src/components/CartSummary.tsx,10,setTotal(cart.total());
+  Cart.total,src/hooks/useCart.ts,35,"total: cart.total(),"
+  ...
+blind_spots[1]{symbol,file,line,reason}:
+  Cart.total,src/components/CartSummary.tsx,16,string key 'total' on a type without that member
+elapsed_ms: 679
+help[5]:
+  - "Run `ts-axi refs src/lib/format.ts:5` for every Reference of formatPrice"
+  - "Run `ts-axi callers src/lib/format.ts:5` for its call sites with the enclosing function"
+  - "Run `ts-axi def src/lib/format.ts:5` for the changed declaration"
+  - Run `ts-axi impact main...HEAD --grep` for textual matches the checker cannot see
+  - Run `ts-axi impact main...HEAD --depth 2` for who calls the callers
+```
+
+(`...` marks rows cut from this README; the command prints all 20.)
+
+Read-only: no lint, no refactor, no rename.
+
+> **Status: early (v0.1.x).**
+
+## Install
+
+Requires Node.js 20+.
+
+```sh
+npm install -g ts-axi
+```
+
+Then tell your agent about it - one line in `CLAUDE.md` / `AGENTS.md`:
+
+```
+Use `ts-axi` to find definitions, references and callers in TypeScript/JavaScript code, and `ts-axi impact` to see what a diff affects before reviewing it.
+```
+
+Or install the on-demand Agent Skill (no per-session cost):
+
+```sh
+npx skills add cmosgh/ts-axi --skill ts-axi
+```
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `ts-axi` | Home view: project root, tsconfig used (or implicit), source file count, test-file glob and match counts, git branch and dirty count, next steps. Under a second, exit 0 everywhere |
+| `def <target>` | Declarations of a symbol by name (`save`, `User.save`, `path:line`): one match prints detail and body, several print a compact list, none prints `did_you_mean` |
+| `refs <target>` | References of one symbol, grouped by file, with test counts. `--limit`, `--kind calls` |
+| `callers <target>` | Incoming calls of a function-like symbol. `--depth 1..3` |
+| `outline <file>` | Top-level declarations in source order, class members nested. `--exports` |
+| `impact [<git-range> \| -]` | Declarations changed by the working tree (untracked files included; `--staged`), a git range (`main...HEAD`) or a unified diff on stdin (`bb-axi pr diff 42 --raw \| ts-axi impact -`), riskiest first: change class (`signature`, `removed`, `type`, `added`, `body`, `modified`), References outside the change set, test-file counts, `blind_spots`, `local_only`, `file_level` and `skipped` (non-TS files in the diff). `--limit`, `--depth 2..3`, `--grep`. Analyses the current checkout |
+| `config` | Show effective settings with their source; `config set <key> <value>` and `config unset <key>` write `.ts-axi.json` |
+
+`ts-axi <command> --help` prints a concise, complete flag reference. `-P <tsconfig>` selects a project on any command that may analyse types; `--json` prints the decoded payload.
+
+<!-- TODO(phase 4): paste real examples for def / refs / outline / config from the fixture project. -->
+
+## Test files
+
+A file counts as a test by path pattern. Defaults: `**/*.test.*`, `**/*.spec.*`, `**/__tests__/**`, `**/test/**`, `**/tests/**`, `**/e2e/**`. The home view shows `test_globs` and `test_files` so a wrong rule is visible.
+
+## `.ts-axi.json`
+
+Optional, at the git root (or the current directory outside a repository). Manage it with `ts-axi config`, or edit it by hand:
+
+```json
+{ "testGlobs": ["**/*.it.ts", "packages/*/qa/**"], "testGlobsReplace": false, "project": "tsconfig.app.json" }
+```
+
+| Key | Meaning |
+| --- | --- |
+| `testGlobs` | Extra test-file globs, added to the defaults |
+| `testGlobsReplace` | `true` makes `testGlobs` replace the defaults |
+| `project` | Default tsconfig, relative to the repo root; `-P` overrides it |
+
+Any other key is a `VALIDATION_ERROR` naming the valid ones. `--test-glob <glob>` adds a glob for one run.
+
+## How it works
+
+One dependency: the `typescript` compiler API (ADR in `docs/adr/0001-typescript-language-service-engine.md`).
+
+- `outline`, `def` and the home view only parse files (`ts.createSourceFile`): no tsconfig needed, well under a second.
+- `refs`, `callers` and `impact` build a `LanguageService` over the nearest `tsconfig.json` (or an implicit project of every source file when none exists, with a warning) and ask it for references and call hierarchy. Symbol identity comes from the checker, so `user.save` resolves to `User.save` through imports and re-exports.
+- `impact` reads the "before" version of touched files with `git show` and compares signatures to classify each change (`added`, `removed`, `signature`, `body`, `type`, `modified`). Uses it cannot follow (access through `any`, dynamic string keys) are reported as `blind_spots`, never silently dropped.
+- Type errors in the analysed project never block anything; they are reported as a `diagnostics` count.
+
+Every semantic command starts cold and prints `elapsed_ms`.
+
+## Development
+
+```sh
+corepack pnpm install
+corepack pnpm run check   # typecheck, tests, build, skill freshness
+```
+
+`skills/ts-axi/SKILL.md` is generated: `corepack pnpm run build:skill`. See `PLAN.md` for the spec and `GLOSSARY.md` for the vocabulary.
+
+## License
+
+MIT

package/dist/bin/ts-axi.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { tryFastPath } from "axi-sdk-js/fast-path";
+import { VERSION } from "../src/version.js";
+if (!tryFastPath(process.argv.slice(2), { version: VERSION })) {
+    const { main } = await import("../src/cli.js");
+    await main();
+}

package/dist/src/args.js

@@ -0,0 +1,184 @@
+import { usageError } from "./errors.js";
+/**
+ * Flags agents commonly carry over from other CLIs. A targeted hint lets the
+ * agent self-correct in one turn instead of scanning the generic flag list.
+ */
+const RENAMED = {
+    "--project": "-P",
+    "--tsconfig": "-P",
+    "--type": "--kind",
+    "--exports": "--exported",
+    "--include": "--in",
+    "--path": "--in",
+    "--max": "--limit",
+    "--all": "--full",
+};
+/** Flags whose value is a positional argument in ts-axi. */
+const POSITIONAL = {
+    "--file": "pass the file as a positional argument",
+    "--symbol": "pass the symbol as a positional argument",
+    "--name": "pass the symbol as a positional argument",
+};
+/**
+ * Strict declarative parser: every flag must be declared, unknown flags fail
+ * loud with the valid set inline (AXI principle 6). Supports `--flag value`,
+ * `--flag=value`, boolean flags, repeatable flags, aliases and a `--`
+ * terminator. A bare `-` is a positional (stdin sentinel).
+ */
+export function parseArgs(args, specs, command) {
+    const byName = new Map();
+    for (const spec of specs) {
+        byName.set(spec.name, spec);
+        if (spec.alias)
+            byName.set(spec.alias, spec);
+    }
+    const parsed = {
+        values: new Map(),
+        bools: new Set(),
+        positionals: [],
+    };
+    const unknown = [];
+    for (let i = 0; i < args.length; i++) {
+        const token = args[i];
+        if (token === "--") {
+            parsed.positionals.push(...args.slice(i + 1));
+            break;
+        }
+        if (token === "-" || !token.startsWith("-")) {
+            parsed.positionals.push(token);
+            continue;
+        }
+        const eq = token.indexOf("=");
+        const name = eq === -1 ? token : token.slice(0, eq);
+        const inlineValue = eq === -1 ? undefined : token.slice(eq + 1);
+        if (name === "--help" || name === "-h")
+            continue;
+        const spec = byName.get(name);
+        if (!spec) {
+            if (!unknown.includes(name))
+                unknown.push(name);
+            continue;
+        }
+        if (spec.boolean) {
+            if (inlineValue !== undefined) {
+                throw usageError(`${spec.name} does not take a value`, [
+                    `Run \`${command} --help\``,
+                ]);
+            }
+            parsed.bools.add(spec.name);
+            continue;
+        }
+        let value = inlineValue;
+        if (value === undefined) {
+            const next = args[i + 1];
+            // A following declared flag (or `--`) means the value is missing. Other
+            // dash-leading tokens are accepted so bodies like "- item" still work.
+            if (next === undefined || next === "--" || byName.has(next)) {
+                throw usageError(`${spec.name} requires a value`, [
+                    `Run \`${command} --help\``,
+                ]);
+            }
+            value = next;
+            i++;
+        }
+        if (value.trim() === "") {
+            throw usageError(`${spec.name} requires a non-empty value`);
+        }
+        const existing = parsed.values.get(spec.name);
+        if (existing && !spec.repeatable) {
+            throw usageError(`${spec.name} may only be given once`);
+        }
+        parsed.values.set(spec.name, [...(existing ?? []), value]);
+    }
+    if (unknown.length > 0) {
+        const valid = specs.map((s) => s.name).join(", ") || "(none)";
+        const renamed = unknown
+            .filter((flag) => RENAMED[flag] && byName.has(RENAMED[flag]))
+            .map((flag) => `${flag} is not supported here; use ${RENAMED[flag]} instead`);
+        const positional = unknown
+            .filter((flag) => POSITIONAL[flag])
+            .map((flag) => `${flag} is not supported; ${POSITIONAL[flag]}`);
+        throw usageError(`unknown flag${unknown.length > 1 ? "s" : ""} ${unknown.join(", ")} for \`${command}\``, [
+            ...renamed,
+            ...positional,
+            `valid flags for \`${command}\`: ${valid} (--help always allowed)`,
+        ]);
+    }
+    return parsed;
+}
+export function flag(parsed, name) {
+    return parsed.values.get(name)?.[0];
+}
+export function flags(parsed, name) {
+    return parsed.values.get(name) ?? [];
+}
+export function bool(parsed, name) {
+    return parsed.bools.has(name);
+}
+export function requireFlag(parsed, name, usage) {
+    const value = flag(parsed, name);
+    if (value === undefined) {
+        throw usageError(`${name} is required`, [usage]);
+    }
+    return value;
+}
+export function intFlag(parsed, name, fallback, range) {
+    const raw = flag(parsed, name);
+    if (raw === undefined)
+        return fallback;
+    if (!/^\d+$/.test(raw)) {
+        throw usageError(`${name} must be a whole number, got '${raw}'`);
+    }
+    const value = Number(raw);
+    if (value < range.min || value > range.max) {
+        throw usageError(`${name} must be between ${range.min} and ${range.max}`);
+    }
+    return value;
+}
+export function enumFlag(parsed, name, allowed, fallback) {
+    const raw = flag(parsed, name);
+    if (raw === undefined)
+        return fallback;
+    const value = raw.toLowerCase();
+    if (!allowed.includes(value)) {
+        throw usageError(`invalid ${name} '${raw}'`, [
+            `valid values: ${allowed.join(", ")}`,
+        ]);
+    }
+    return value;
+}
+/** Require exactly `count` positionals; extra or missing ones are usage errors. */
+export function expectPositionals(parsed, count, usage) {
+    if (parsed.positionals.length !== count) {
+        const problem = parsed.positionals.length < count
+            ? "missing argument"
+            : `unexpected argument '${parsed.positionals[count]}'`;
+        throw usageError(problem, [`usage: ${usage}`]);
+    }
+    return parsed.positionals;
+}
+export function positiveId(raw, label) {
+    const cleaned = raw?.replace(/^#/, "");
+    if (!cleaned || !/^\d+$/.test(cleaned) || Number(cleaned) < 1) {
+        throw usageError(`invalid ${label} '${raw ?? ""}' - expected a positive number`);
+    }
+    return Number(cleaned);
+}
+/** Parse a comma-separated `--fields` value against the supported extras. */
+export function parseFields(raw, available) {
+    if (raw === undefined)
+        return [];
+    const requested = [
+        ...new Set(raw
+            .split(",")
+            .map((f) => f.trim())
+            .filter(Boolean)),
+    ];
+    const bad = requested.filter((f) => !available.includes(f));
+    if (bad.length > 0) {
+        throw usageError(`unknown field${bad.length > 1 ? "s" : ""}: ${bad.join(", ")}`, [
+            `available --fields: ${available.join(", ")}`,
+        ]);
+    }
+    return requested;
+}

package/dist/src/cli.js

@@ -0,0 +1,94 @@
+import { runAxiCli } from "axi-sdk-js";
+import { configCommand, CONFIG_HELP } from "./commands/config.js";
+import { defCommand, DEF_HELP } from "./commands/def.js";
+import { homeCommand } from "./commands/home.js";
+import { impactCommand, IMPACT_HELP } from "./commands/impact.js";
+import { outlineCommand, OUTLINE_HELP } from "./commands/outline.js";
+import { callersCommand, CALLERS_HELP, refsCommand, REFS_HELP } from "./commands/refs.js";
+import { AxiError, exitCodeForError } from "./errors.js";
+import { renderErrorOutput, setJsonMode, toJson } from "./render.js";
+import { VERSION } from "./version.js";
+export const DESCRIPTION = "TypeScript/JavaScript symbol CLI for agents - definitions, references, callers, file outlines and change impact (what a diff affects) from the TypeScript compiler. Prefer it over grep for 'who uses this'.";
+export const TOP_HELP = `usage: ts-axi [command] [args] [flags]
+commands[7]:
+  (none)=project overview, def, refs, callers, outline, impact, config
+targets:
+  name (save), member (User.save) or position (src/a.ts:42 or src/a.ts:42:7)
+flags[4]:
+  -P <tsconfig> (after the command; default nearest tsconfig.json), --json (anywhere), --help, -v/-V/--version
+examples:
+  ts-axi
+  ts-axi def User.save
+  ts-axi refs src/models/user.ts:12
+  ts-axi callers runSync --depth 2
+  ts-axi outline src/models/user.ts
+  ts-axi impact main...HEAD
+  ts-axi refs --help
+`;
+const COMMAND_HELP = {
+    def: DEF_HELP,
+    refs: REFS_HELP,
+    callers: CALLERS_HELP,
+    outline: OUTLINE_HELP,
+    impact: IMPACT_HELP,
+    config: CONFIG_HELP,
+};
+function command(name, handler, ctx) {
+    return async (args) => (args.includes("-h") ? (COMMAND_HELP[name] ?? "").trimEnd() : handler(args, ctx));
+}
+function formatError(error) {
+    const axi = error instanceof AxiError
+        ? error
+        : new AxiError(error instanceof Error ? error.message : String(error), "UNKNOWN");
+    return {
+        output: `${renderErrorOutput(axi.message, axi.code, axi.suggestions)}\n`,
+        exitCode: exitCodeForError(axi),
+    };
+}
+export async function main(options = {}) {
+    const argv = options.argv ?? process.argv.slice(2);
+    // Global flag: stripped here because the SDK rejects flags before the command.
+    const json = argv.includes("--json");
+    setJsonMode(json);
+    const stdout = options.stdout ?? process.stdout;
+    const ctx = { cwd: options.cwd ?? process.cwd(), ...(options.stdin !== undefined ? { stdin: options.stdin } : {}) };
+    // home/config may take the context as an optional second parameter.
+    const home = homeCommand;
+    let buffered = "";
+    try {
+        await runAxiCli({
+            argv: json ? argv.filter((a) => a !== "--json") : argv,
+            stdout: json ? { write: (chunk) => (buffered += chunk) } : stdout,
+            description: DESCRIPTION,
+            version: VERSION,
+            topLevelHelp: TOP_HELP,
+            home: (args) => home(args, ctx),
+            commands: {
+                def: command("def", defCommand, ctx),
+                refs: command("refs", refsCommand, ctx),
+                callers: command("callers", callersCommand, ctx),
+                outline: command("outline", outlineCommand, ctx),
+                impact: command("impact", impactCommand, ctx),
+                config: command("config", configCommand, ctx),
+            },
+            getCommandHelp: (name) => COMMAND_HELP[name],
+            renderUnknownCommand: (name) => `${renderErrorOutput(`unknown command '${name}'`, "VALIDATION_ERROR", [
+                "commands: def, refs, callers, outline, impact, config (no command = project overview)",
+                "Run `ts-axi --help` for examples",
+            ])}\n`,
+            formatError,
+        });
+    }
+    finally {
+        setJsonMode(false);
+    }
+    if (!json)
+        return;
+    if (stdout === process.stdout) {
+        process.stdout.on("error", (error) => {
+            if (error.code !== "EPIPE")
+                throw error;
+        });
+    }
+    stdout.write(toJson(buffered));
+}