@claudiu.ceia/astkit 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Claudiu Ceia
+
+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

@@ -0,0 +1,393 @@
+# astkit
+
+`astkit` is a CLI for structural code inspection and navigation in TypeScript/JavaScript projects.
+It operates on AST structure, TypeScript type services, and reference graphs, and is designed for token-efficient workflows used by LLM agents and senior engineers.
+
+## What astkit provides
+
+- Definition and reference navigation via the TypeScript language service
+- Structural search and rewrite using AST-shaped patterns
+- Reference-based symbol ranking as an impact heuristic
+
+## Non-Goals
+
+`astkit` does not:
+- infer program intent or meaning
+- perform whole-program flow analysis
+- prove correctness or enforce architecture
+- replace the TypeScript compiler or type checker
+- make decisions automatically
+- guarantee behavioral equivalence after rewrites
+
+## Install
+
+```bash
+npm install --save-dev @claudiu.ceia/astkit typescript
+```
+
+`astkit` uses the project's `typescript` installation for type services.
+
+## Run
+
+```bash
+npx @claudiu.ceia/astkit <command> [args]
+```
+
+Or via the bin entry:
+
+```bash
+astkit <command> [args]
+```
+
+## Install Skill (Codex)
+
+From an installed npm package:
+
+```bash
+npx skills add ./node_modules/@claudiu.ceia/astkit/skills/astkit-tooling -a codex
+```
+
+From this repository:
+
+```bash
+npm run skill:install
+```
+
+## CLI Reference
+
+General help:
+
+```bash
+astkit --help
+astkit <command> --help
+```
+
+Full command surface:
+
+```bash
+astkit nav declarations <file>
+astkit nav definition <location>
+astkit nav references <location>
+astkit search [--json] [--no-color] [--no-isomorphisms] [--cwd <path>] <pattern-input> [scope]
+astkit patch [--interactive] [--json] [--no-color] [--dry-run] [--cwd <path>] <patch-input> [scope]
+astkit code-rank [--json] [--limit <n>] [--cwd <path>] [scope]
+```
+
+### `nav`
+
+```bash
+astkit nav declarations <file>
+astkit nav definition <location>
+astkit nav references <location>
+```
+
+`<location>` format:
+- `path/to/file.ts:120:17`
+
+Line and character are 1-indexed.
+
+Mock execution:
+
+```bash
+$ astkit nav declarations src/__tests__/fixtures/simple.ts
+{
+  "file": "src/__tests__/fixtures/simple.ts",
+  "declarations": [
+    {
+      "name": "User",
+      "kind": "interface",
+      "signature": "User",
+      "line": 1
+    },
+    {
+      "name": "UserService",
+      "kind": "class",
+      "signature": "UserService",
+      "line": 7
+    }
+  ]
+}
+
+$ astkit nav definition src/__tests__/fixtures/importer.ts:1:15
+{
+  "symbol": "User",
+  "definitions": [
+    {
+      "file": "src/__tests__/fixtures/simple.ts",
+      "line": 1,
+      "character": 18,
+      "kind": "interface",
+      "containerName": "\".../simple\""
+    }
+  ]
+}
+
+$ astkit nav references src/__tests__/fixtures/simple.ts:1:18
+{
+  "symbol": "interface User",
+  "definition": {
+    "file": "src/__tests__/fixtures/simple.ts",
+    "line": 1,
+    "character": 18
+  },
+  "references": [
+    {
+      "file": "src/__tests__/fixtures/simple.ts",
+      "line": 1,
+      "character": 18,
+      "isDefinition": true,
+      "isWriteAccess": true
+    },
+    {
+      "file": "src/__tests__/fixtures/importer.ts",
+      "line": 1,
+      "character": 15,
+      "isDefinition": false,
+      "isWriteAccess": true
+    }
+  ]
+}
+```
+
+### `search` (`sgrep`)
+
+```bash
+astkit search <pattern-input> [scope] [--cwd <path>] [--no-color] [--no-isomorphisms] [--json]
+```
+
+- Default output is compact, file-grouped text
+- In interactive terminals, captures are colorized
+- `--no-color` disables coloring
+- Isomorphism expansion is enabled by default (commutative binary operators, object-literal key order, redundant parentheses)
+- `--no-isomorphisms` disables isomorphism expansion
+- `--json` prints structured result
+
+Examples:
+
+```bash
+# inline pattern
+astkit search 'const :[name] = :[value];' src
+
+# pattern loaded from file
+astkit search rules/find-const.sgrep src --cwd /repo
+
+# machine output
+astkit search --json 'const :[name] = :[value];' src
+```
+
+Mock execution:
+
+```bash
+$ astkit search 'const :[name] = :[value];' src
+//src/example.ts
+12: const foo = 42;
+27: const bar = makeValue( ...
+
+$ astkit search --json 'const :[name] = :[value];' src
+{
+  "scope": "/repo/src",
+  "pattern": "const :[name] = :[value];",
+  "filesScanned": 24,
+  "filesMatched": 2,
+  "totalMatches": 3,
+  "files": [
+    {
+      "file": "src/example.ts",
+      "matchCount": 2,
+      "matches": [
+        {
+          "line": 12,
+          "character": 1,
+          "matched": "const foo = 42;",
+          "captures": {
+            "name": "foo",
+            "value": "42"
+          }
+        }
+      ]
+    }
+  ]
+}
+```
+
+### `patch` (`spatch`)
+
+```bash
+astkit patch <patch-input> [scope] [--cwd <path>] [--dry-run] [--json] [--no-color] [--interactive]
+```
+
+- `patch-input` can be inline patch text or a file path
+- Patch format uses `+`/`-`/context lines in one document
+- Default output is compact diff-style text
+- `--json` prints structured output
+- `--no-color` disables color in compact output
+- `--interactive` lets you accept/reject each match
+
+Example:
+
+```bash
+astkit patch $'-const :[name] = :[value];\n+let :[name] = :[value];' src
+```
+
+Mock execution:
+
+```bash
+$ astkit patch --dry-run $'-const :[name] = :[value];\n+let :[name] = :[value];' src
+diff --git a/src/example.ts b/src/example.ts
+--- a/src/example.ts
++++ b/src/example.ts
+@@ -12,1 +12,1 @@
+-const foo = 42;
++let foo = 42;
+1 file changed, 1 replacement, (dry-run)
+
+$ astkit patch --interactive $'-const :[name] = :[value];\n+let :[name] = :[value];' src
+------------------------------------------------------------------------
+Change 1/2: src/example.ts:12
+@@ -12,1 +12,1 @@
+-const foo = 42;
++let foo = 42;
+Choice [y/n/a/q] (default: n): y
+```
+
+### `code-rank`
+
+```bash
+astkit code-rank [scope] [--cwd <path>] [--limit <n>] [--json]
+```
+
+- Ranks exported symbols by TypeScript reference strength
+- Uses the TypeScript language service (`findReferences`)
+- Default output is compact, one symbol per line
+- `--json` prints structured output
+
+Example:
+
+```bash
+astkit code-rank src --limit 20
+```
+
+Mock execution:
+
+```bash
+$ astkit code-rank src --limit 3
+1. score=14 refs=3 ext=3 files=2 function hot src/a.ts:1:8
+2. score=9 refs=2 ext=2 files=1 function warm src/a.ts:5:8
+3. score=6 refs=1 ext=1 files=1 interface User src/model.ts:1:18
+
+$ astkit code-rank src --limit 1 --json
+{
+  "scope": "/repo/src",
+  "symbolsRanked": 1,
+  "symbols": [
+    {
+      "symbol": "hot",
+      "kind": "function",
+      "file": "src/a.ts",
+      "line": 1,
+      "character": 8,
+      "score": 14,
+      "referenceCount": 3
+    }
+  ]
+}
+```
+
+## Structural Pattern Syntax
+
+Both `search` and `patch` use the same hole/metavariable syntax:
+
+- `:[name]`
+- `:[_]` anonymous hole (ignored in captures)
+- `:[name~regex]` regex-constrained hole
+- `...` variadic wildcard (matches balanced text and can be reused in replacement)
+
+Repeated named holes enforce equality:
+
+```text
+:[x] + :[x]
+```
+
+This matches `foo + foo` but not `foo + bar`.
+
+Hole captures are structurally balanced (brackets/strings/comments), which helps avoid malformed partial matches.
+
+## Output Examples
+
+Default compact `search` output:
+
+```text
+//src/example.ts
+12: const foo = 42;
+34: const bar = compute( ...
+```
+
+JSON `search` output (`--json`) includes:
+- files scanned/matched
+- total matches
+- byte spans
+- line/character
+- captures
+
+`patch --json` includes structured match and replacement stats per file.
+
+## Programmatic API
+
+Root exports:
+- `patchProject` from `src/spatch`
+- `searchProject` from `src/sgrep`
+- `rankCode` from `src/code-rank`
+
+```ts
+import { patchProject, rankCode, searchProject } from "@claudiu.ceia/astkit";
+```
+
+See detailed internals:
+- `src/spatch/README.md`
+- `src/sgrep/README.md`
+
+## Development
+
+Run local CLI:
+
+```bash
+bun run astkit -- <command> [args]
+```
+
+Build distributable output:
+
+```bash
+npm run build
+```
+
+Run tests:
+
+```bash
+bun test
+```
+
+Run typecheck:
+
+```bash
+npm run typecheck
+```
+
+Preview npm package contents:
+
+```bash
+npm run pack:check
+```
+
+Install this repo's skill locally for Codex:
+
+```bash
+npm run skill:install
+```
+
+## Code Organization
+
+- `src/nav/*`: TypeScript language-service navigation commands
+- `src/sgrep/*`: search pipeline (`parse -> search -> output`)
+- `src/spatch/*`: patch pipeline (`parse -> rewrite -> output`)
+- `src/pattern/*`: shared structural parser/matcher/renderer
+- `src/common/*`: shared helpers (for example inline-or-file text resolution)

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./src/spatch/index.ts";
+export * from "./src/sgrep/index.ts";
+export * from "./src/code-rank/index.ts";

package/dist/index.js

@@ -0,0 +1,3 @@
+export * from "./src/spatch/index.js";
+export * from "./src/sgrep/index.js";
+export * from "./src/code-rank/index.js";

package/dist/src/app.d.ts

@@ -0,0 +1 @@
+export declare const app: import("@stricli/core").Application<import("@stricli/core").CommandContext>;

package/dist/src/app.js

@@ -0,0 +1,41 @@
+import { buildApplication, buildRouteMap, text_en } from "@stricli/core";
+import { codeRankCommand } from "./code-rank/code-rank.js";
+import { declarationsCommand } from "./nav/declarations.js";
+import { definitionCommand } from "./nav/definition.js";
+import { referencesCommand } from "./nav/references.js";
+import { patchCommand } from "./patch/patch.js";
+import { searchCommand } from "./search/search.js";
+const navRouteMap = buildRouteMap({
+    routes: {
+        declarations: declarationsCommand,
+        definition: definitionCommand,
+        references: referencesCommand,
+    },
+    docs: {
+        brief: "Code navigation and reading",
+    },
+});
+const rootRouteMap = buildRouteMap({
+    routes: {
+        nav: navRouteMap,
+        search: searchCommand,
+        patch: patchCommand,
+        "code-rank": codeRankCommand,
+    },
+    docs: {
+        brief: "Structural and type-aware code tooling for TS/JS",
+    },
+});
+export const app = buildApplication(rootRouteMap, {
+    name: "astkit",
+    scanner: {
+        caseStyle: "original",
+    },
+    documentation: {
+        caseStyle: "original",
+    },
+    localization: {
+        defaultLocale: "en",
+        loadText: () => text_en,
+    },
+});

package/dist/src/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/src/cli.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { run } from "@stricli/core";
+import { app } from "./app.js";
+await run(app, process.argv.slice(2), { process });

package/dist/src/code-rank/code-rank.d.ts

@@ -0,0 +1,9 @@
+import { type CodeRankResult } from "./rank.ts";
+export type CodeRankCommandFlags = {
+    cwd?: string;
+    limit?: number;
+    json?: boolean;
+};
+export declare function runCodeRankCommand(scope: string | undefined, flags: CodeRankCommandFlags): Promise<CodeRankResult>;
+export declare function formatCodeRankOutput(result: CodeRankResult): string;
+export declare const codeRankCommand: import("@stricli/core").Command<import("@stricli/core").CommandContext>;

package/dist/src/code-rank/code-rank.js

@@ -0,0 +1,71 @@
+import { buildCommand, numberParser } from "@stricli/core";
+import { rankCode } from "./rank.js";
+export async function runCodeRankCommand(scope, flags) {
+    return rankCode({
+        cwd: flags.cwd,
+        scope: scope ?? ".",
+        limit: flags.limit,
+    });
+}
+export function formatCodeRankOutput(result) {
+    if (result.symbols.length === 0) {
+        return "No ranked symbols.";
+    }
+    const lines = [];
+    for (let index = 0; index < result.symbols.length; index += 1) {
+        const symbol = result.symbols[index];
+        if (!symbol) {
+            continue;
+        }
+        const rank = index + 1;
+        lines.push(`${rank}. score=${symbol.score} refs=${symbol.referenceCount} ext=${symbol.externalReferenceCount} files=${symbol.referencingFileCount} ${symbol.kind} ${symbol.symbol} ${symbol.file}:${symbol.line}:${symbol.character}`);
+    }
+    return lines.join("\n");
+}
+export const codeRankCommand = buildCommand({
+    async func(flags, scope) {
+        const result = await runCodeRankCommand(scope, flags);
+        if (flags.json ?? false) {
+            this.process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+            return;
+        }
+        this.process.stdout.write(`${formatCodeRankOutput(result)}\n`);
+    },
+    parameters: {
+        flags: {
+            json: {
+                kind: "boolean",
+                optional: true,
+                brief: "Output structured JSON instead of compact text",
+            },
+            limit: {
+                kind: "parsed",
+                optional: true,
+                brief: "Maximum number of ranked symbols to return",
+                placeholder: "n",
+                parse: numberParser,
+            },
+            cwd: {
+                kind: "parsed",
+                optional: true,
+                brief: "Working directory for resolving scope",
+                placeholder: "path",
+                parse: (input) => input,
+            },
+        },
+        positional: {
+            kind: "tuple",
+            parameters: [
+                {
+                    brief: "Scope file or directory (defaults to current directory)",
+                    placeholder: "scope",
+                    parse: (input) => input,
+                    optional: true,
+                },
+            ],
+        },
+    },
+    docs: {
+        brief: "Rank exported symbols by reference strength",
+    },
+});

package/dist/src/code-rank/index.d.ts

@@ -0,0 +1 @@
+export { rankCode, type CodeRankOptions, type CodeRankResult, type RankedSymbol, } from "./rank.ts";

package/dist/src/code-rank/index.js

@@ -0,0 +1 @@
+export { rankCode, } from "./rank.js";

package/dist/src/code-rank/rank.d.ts

@@ -0,0 +1,29 @@
+export type CodeRankOptions = {
+    cwd?: string;
+    scope?: string;
+    limit?: number;
+    extensions?: readonly string[];
+    excludedDirectories?: readonly string[];
+};
+export type RankedSymbol = {
+    symbol: string;
+    kind: string;
+    file: string;
+    line: number;
+    character: number;
+    score: number;
+    referenceCount: number;
+    internalReferenceCount: number;
+    externalReferenceCount: number;
+    referencingFileCount: number;
+    referencingFiles: string[];
+};
+export type CodeRankResult = {
+    cwd: string;
+    scope: string;
+    filesScanned: number;
+    symbolsScanned: number;
+    symbolsRanked: number;
+    symbols: RankedSymbol[];
+};
+export declare function rankCode(options?: CodeRankOptions): Promise<CodeRankResult>;