@claudiu.ceia/astkit 0.1.0

package/dist/src/spatch/template.js

@@ -0,0 +1 @@
+export { compileTemplate, findTemplateMatches, renderTemplate } from "../pattern/index.js";

package/dist/src/spatch/text.d.ts

@@ -0,0 +1,5 @@
+export declare function createLineStarts(text: string): number[];
+export declare function toLineCharacter(lineStarts: readonly number[], index: number): {
+    line: number;
+    character: number;
+};

package/dist/src/spatch/text.js

@@ -0,0 +1,35 @@
+export function createLineStarts(text) {
+    const starts = [0];
+    for (let index = 0; index < text.length; index += 1) {
+        if (text[index] === "\n") {
+            starts.push(index + 1);
+        }
+    }
+    return starts;
+}
+export function toLineCharacter(lineStarts, index) {
+    if (lineStarts.length === 0) {
+        return { line: 1, character: Math.max(index + 1, 1) };
+    }
+    let low = 0;
+    let high = lineStarts.length - 1;
+    while (low <= high) {
+        const middle = Math.floor((low + high) / 2);
+        const start = lineStarts[middle] ?? 0;
+        const nextStart = lineStarts[middle + 1] ?? Number.POSITIVE_INFINITY;
+        if (start <= index && index < nextStart) {
+            return { line: middle + 1, character: index - start + 1 };
+        }
+        if (index < start) {
+            high = middle - 1;
+            continue;
+        }
+        low = middle + 1;
+    }
+    const fallback = lineStarts[lineStarts.length - 1] ?? 0;
+    const line = Math.max(lineStarts.length, 1);
+    return {
+        line,
+        character: Math.max(index - fallback + 1, 1),
+    };
+}

package/dist/src/spatch/types.d.ts

@@ -0,0 +1,40 @@
+export declare const DEFAULT_PATCHABLE_EXTENSIONS: readonly [".ts", ".tsx", ".mts", ".cts", ".js", ".jsx", ".mjs", ".cjs"];
+export declare const DEFAULT_EXCLUDED_DIRECTORIES: readonly [".git", "node_modules", ".next", ".turbo", "dist", "build", "coverage", "out"];
+export type SpatchOptions = {
+    scope?: string;
+    cwd?: string;
+    dryRun?: boolean;
+    extensions?: readonly string[];
+    excludedDirectories?: readonly string[];
+    encoding?: BufferEncoding;
+};
+export type SpatchOccurrence = {
+    start: number;
+    end: number;
+    line: number;
+    character: number;
+    matched: string;
+    replacement: string;
+    captures: Record<string, string>;
+};
+export type SpatchFileResult = {
+    file: string;
+    matchCount: number;
+    replacementCount: number;
+    changed: boolean;
+    byteDelta: number;
+    occurrences: SpatchOccurrence[];
+};
+export type SpatchResult = {
+    dryRun: boolean;
+    scope: string;
+    pattern: string;
+    replacement: string;
+    filesScanned: number;
+    filesMatched: number;
+    filesChanged: number;
+    totalMatches: number;
+    totalReplacements: number;
+    elapsedMs: number;
+    files: SpatchFileResult[];
+};

package/dist/src/spatch/types.js

@@ -0,0 +1,20 @@
+export const DEFAULT_PATCHABLE_EXTENSIONS = [
+    ".ts",
+    ".tsx",
+    ".mts",
+    ".cts",
+    ".js",
+    ".jsx",
+    ".mjs",
+    ".cjs",
+];
+export const DEFAULT_EXCLUDED_DIRECTORIES = [
+    ".git",
+    "node_modules",
+    ".next",
+    ".turbo",
+    "dist",
+    "build",
+    "coverage",
+    "out",
+];

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@claudiu.ceia/astkit",
+  "version": "0.1.0",
+  "description": "Structural navigation, search, and rewrite tooling for TypeScript/JavaScript repositories.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ClaudiuCeia/astkit.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ClaudiuCeia/astkit/issues"
+  },
+  "homepage": "https://github.com/ClaudiuCeia/astkit#readme",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "astkit": "./dist/src/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "skills/astkit-tooling"
+  ],
+  "keywords": [
+    "typescript",
+    "javascript",
+    "ast",
+    "codemod",
+    "code-search",
+    "code-navigation",
+    "llm-tools"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "astkit": "bun run src/cli.ts",
+    "dev": "bun src/cli.ts",
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "prepack": "npm run build",
+    "pack:check": "npm_config_cache=.npm-cache npm pack --dry-run",
+    "skill:install": "npx skills add ./skills/astkit-tooling -a codex -y"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "@claudiu-ceia/combine": "npm:@jsr/claudiu-ceia__combine",
+    "@stricli/core": "^1.2.5",
+    "chalk": "^5.6.2"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  }
+}

package/skills/astkit-tooling/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: astkit-tooling
+description: Use when a TypeScript/JavaScript task needs symbol navigation (`nav declarations|definition|references`), structural pattern search (`search`), structural rewrites (`patch`), or reference-based blast-radius estimation (`code-rank`). Prefer for compact, scoped repository analysis and migration work; do not use for runtime-path proofs, correctness guarantees, or replacing compiler/tests.
+---
+
+# astkit tooling
+
+Use `astkit` for token-efficient repository exploration and structural edits in TS/JS projects.
+Keep scope narrow first, expand only when evidence is insufficient.
+
+## Quick Start
+
+1. Confirm tool availability.
+- `astkit --help`
+- or `npx astkit --help`
+- or `bunx astkit --help`
+
+2. Start with one focused operation.
+- `astkit nav declarations <file>`
+- `astkit nav definition <file:line:character>`
+- `astkit nav references <file:line:character>`
+- `astkit search '<pattern>' <scope> --json`
+- `astkit patch --dry-run '<patch-document>' <scope>`
+- `astkit code-rank <scope> --limit 25 --json`
+
+3. Expand scope only if needed.
+
+## Working Workflow
+
+1. Map contracts before implementation details.
+- Use `nav declarations` and `nav definition` first.
+- Treat signatures/docs as intended contracts until contradicted by evidence.
+
+2. Clarify behavior from usage.
+- Use `nav references` to inspect representative callsites.
+- Prefer usage patterns over deep source reading for initial understanding.
+
+3. Estimate blast radius before edits.
+- Use `code-rank` and references to identify high-impact symbols.
+- Prefer localized changes when task scope is localized.
+
+4. Rewrite with structural tools.
+- Use `search` to find candidate shapes.
+- Use `patch --dry-run` before writing changes.
+- Use `patch --interactive` for high-risk or broad rewrites.
+
+5. Re-check and validate.
+- Re-run focused `search`/`nav references` on touched symbols.
+- Validate with `tsc` and relevant tests when available.
+
+## Safe Rewrite Workflow
+
+1. Find candidate sites.
+- `astkit search '<pattern>' <scope> --json`
+
+2. Preview rewrite.
+- `astkit patch --dry-run '<patch-document>' <scope>`
+
+3. Apply rewrite.
+- `astkit patch '<patch-document>' <scope>`
+- Use `--interactive` for high-risk or broad edits.
+
+4. Re-check surfaced contracts.
+- Re-run focused `search` queries and `nav references` on touched symbols.
+
+5. Validate with compiler and tests.
+- Run `tsc` diagnostics.
+- Run focused tests for touched behavior.
+
+## Reporting Contract
+
+When reporting findings, include:
+
+- system boundaries and entry points
+- invariants/contracts with explicit status (`observed` vs `inferred`)
+- definition/reference flow summary
+- change hotspots/dependency hubs
+- suggested edits with blast-radius notes
+- validation status and remaining gaps
+
+Keep output concise and include file paths/spans where possible.
+
+## Guardrails
+
+- Structural similarity does not imply behavioral equivalence.
+- Structural rewrites reduce accidental matches but do not guarantee correctness.
+- Reference ranking approximates impact, not runtime criticality.
+- No matches do not prove absence of behavior.
+- Do not use this skill as a substitute for compiler diagnostics or tests.
+
+## Common Failure Modes
+
+- Too many matches: narrow scope, add delimiters, add regex constraints.
+- No matches: verify pattern shape, scope, and `--no-isomorphisms` usage.
+- Rewrite too broad: switch to `--interactive` and re-run dry-run first.
+- Unclear impact: inspect `nav references` and `code-rank` before applying.
+
+## References
+
+- `./references/cognitive-model.md`
+- `./references/non-goals.md`

package/skills/astkit-tooling/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Astkit Structural Tooling"
+  short_description: "Token-efficient structural code inspection"
+  default_prompt: "Use $astkit-tooling to map boundaries, invariants, flow, and change hotspots before proposing edits."

package/skills/astkit-tooling/references/cognitive-model.md

@@ -0,0 +1,61 @@
+# Repository Comprehension Model
+
+Use this vocabulary when building repository summaries and implementation plans.
+
+## System Boundaries and Entry Points
+
+Capture:
+- subsystem boundaries
+- external interfaces
+- entry points (HTTP handlers, queue consumers, CLI commands)
+
+Prioritize purpose and responsibility over local implementation detail.
+
+## Invariants and Contracts
+
+Track rules that appear to remain stable across edits.
+Examples:
+- idempotency requirements
+- authentication/authorization preconditions
+- non-blocking or latency constraints
+- schema or API compatibility contracts
+
+Treat these as working hypotheses and re-check them after structural rewrites.
+
+## Control Flow and Data Flow
+
+Start from definitions and references, then inspect local implementation where needed.
+Use navigation queries to map how symbols and values move across boundaries.
+This gives a practical flow model, not whole-program path analysis.
+
+## Change Hotspots and Dependency Hubs
+
+Use recognized maintenance signals:
+- change hotspots: areas with frequent edits and defect risk
+- dependency hubs: symbols/modules with high fan-in or centrality
+- blast radius: expected impact surface of a change
+
+Use `code-rank` as an initial signal, then validate with local code inspection.
+
+## Cognitive Load and Working Set
+
+Treat active reasoning capacity as limited.
+Keep in the working set:
+- boundaries
+- invariants
+- flow skeleton
+- top hotspots/hubs
+
+Treat as recoverable on demand through tools:
+- boilerplate
+- generated code
+- straightforward adapters
+- low-signal implementation details
+
+## Practical Heuristics
+
+- Prefer design intent over mechanism detail.
+- Track invariants and contracts, not full function bodies.
+- Follow definition/reference links before deep local reading.
+- Prioritize high-impact hotspots and dependency hubs.
+- Defer low-signal code until required by a concrete task.

package/skills/astkit-tooling/references/non-goals.md

@@ -0,0 +1,11 @@
+# Non-Goals
+
+`astkit` is not designed to:
+
+- infer developer intent from naming or style alone
+- model full runtime behavior across dynamic dispatch and I/O
+- guarantee that structural rewrites preserve behavior
+- replace compiler diagnostics, linters, or test suites
+- decide whether a refactor should be applied without human review
+- rank runtime criticality from references alone
+- treat missing matches as proof that a pattern is absent