pi-shorthand 0.9.0 → 0.10.0

package/README.md

@@ -1,6 +1,6 @@
 # pi-shorthand
 
-![A code call in Pi](https://raw.githubusercontent.com/sebinsua/pi-shorthand/main/docs/screenshot.png?v=2)
+![A code call in Pi](https://raw.githubusercontent.com/sebinsua/shortsight/main/docs/shorthand.png)
 
 A [Pi](https://github.com/earendil-works/pi) tool for editing repositories with Bun programs, with first-class support for TypeScript and JavaScript.
 
@@ -36,10 +36,18 @@ sudo apt install bubblewrap build-essential lsof
 
 pi-shorthand gives Pi a programming environment instead of a patch format. This makes multi-file and structural edits possible in one call, but does not guarantee that Pi will find it easier or more reliable than its built-in edit tool. Which works better depends on the model and the task.
 
-Programs edit a private workspace, with host files outside the repository kept read-only. By default, a failure keeps completed files and rolls back failed or interrupted edits. Concurrent edits can cause a run to be rejected; conflict detection is best-effort, not an atomic commit.
+Programs edit a private workspace, with host files outside the repository kept read-only. Agents are good at improving things a step at a time, so changes are applied a whole file at a time and the agent is told which worked and which didn't. Concurrent edits can cause a run to be rejected; conflict detection is best-effort, not an atomic commit.
 
 The `code` tool uses Pi's working directory by default. Pass `cwd` to target another checkout; relative paths are resolved from Pi's working directory. For example, when Pi starts in a bare worktree container, `cwd: "child"` targets its `child` worktree. The chosen directory must be inside a Git worktree.
 
 ## Without Pi
 
-The engine is published separately as `shorthand-code`, with a `shorthand` command that runs a program from a file or stdin and prints the same result. See `shorthand --help`.
+The engine is published separately as [shorthand-code](https://github.com/sebinsua/shortsight/tree/main/packages/shorthand-code), with a `shorthand` command that runs a program from a file or stdin and prints the same result. See `shorthand --help`.
+
+## Code graph (optional)
+
+Install [`sightread`](https://github.com/sebinsua/shortsight/tree/main/packages/sightread) and programs can also ask the TypeScript compiler what calls what, with exact line ranges, before they edit:
+
+```sh
+npm i -g sightread
+```

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-shorthand",
-	"version": "0.9.0",
+	"version": "0.10.0",
 	"description": "Pi tool for editing repositories with Bun programs, with first-class support for TypeScript and JavaScript.",
 	"keywords": [
 		"ast-grep",
@@ -11,26 +11,22 @@
 		"pi-extension",
 		"pi-package"
 	],
-	"homepage": "https://github.com/sebinsua/pi-shorthand/tree/main/packages/pi-shorthand#readme",
-	"bugs": "https://github.com/sebinsua/pi-shorthand/issues",
+	"homepage": "https://github.com/sebinsua/shortsight/tree/main/packages/pi-shorthand#readme",
+	"bugs": "https://github.com/sebinsua/shortsight/issues",
 	"license": "MIT",
 	"author": "Seb Insua",
 	"repository": {
 		"type": "git",
-		"url": "git+https://github.com/sebinsua/pi-shorthand.git",
+		"url": "git+https://github.com/sebinsua/shortsight.git",
 		"directory": "packages/pi-shorthand"
 	},
 	"files": [
 		"src",
-		"skills",
 		"README.md"
 	],
 	"type": "module",
-	"scripts": {
-		"prepack": "cp ../../README.md README.md"
-	},
 	"dependencies": {
-		"shorthand-code": "0.9.0"
+		"shorthand-code": "0.10.0"
 	},
 	"peerDependencies": {
 		"@earendil-works/pi-ai": "*",
@@ -59,9 +55,6 @@
 		"extensions": [
 			"./src/index.ts"
 		],
-		"skills": [
-			"./skills"
-		],
-		"image": "https://raw.githubusercontent.com/sebinsua/pi-shorthand/main/docs/screenshot.png?v=2"
+		"image": "https://raw.githubusercontent.com/sebinsua/shortsight/main/docs/shorthand.png"
 	}
 }

package/src/index.ts

@@ -3,6 +3,7 @@
  * Its writes go to a copy-on-write overlay; if it succeeds, they're applied and the diff is returned.
  */
 
+import { createRequire } from "node:module";
 import * as path from "node:path";
 import { StringEnum } from "@earendil-works/pi-ai";
 import { type ExtensionAPI, type Theme, truncateHead, truncateTail } from "@earendil-works/pi-coding-agent";
@@ -16,6 +17,7 @@ import {
 	diagnosticLines,
 	runFailed,
 	runWithBun,
+	sightreadAvailable,
 	textForModel,
 } from "shorthand-code";
 import { callLine, resultLines, unstructuredResultText } from "./display.ts";
@@ -29,12 +31,30 @@ Common operations:
 - sg.one(pattern, files?) selects exactly one match; sg.find returns an array. sg.rewrite also accepts a selected match or array without a file scope.
 - A rewrite callback receives a match and returns text, a native node.replace(text) edit, or null to skip. Return native edits to apply them. Pass selected arrays together for independent edits; select again after changing their file.
 - await refactor.rename({ file, symbol, to }) renames one resolved TypeScript symbol across the project without changing unrelated names.
+- await refactor.references({ file, symbol }) returns resolved identifier matches that pass straight to sg.rewrite(matches, callback).
 - await refactor.renameFile({ from, to }) moves a TypeScript file and updates module paths that resolve to it.
 - await refactor.move({ file, symbol, to }) moves a top-level declaration to another file and updates the imports that follow it.
 
 See the shorthand skill for renames, moves and call-site migrations. Read its advanced-refactors.md guide only to extract code, move syntax or use rule objects. The default timeout is two seconds; request more for longer programs. Time spent inside the helpers above does not count toward it, up to 60 extra seconds.`;
 
-export default function (pi: ExtensionAPI) {
+const GRAPH_DESCRIPTION =
+	"- await graph.query(request | request[]) queries symbols and relationships; graph results can be passed to sg as scope. The graph shows the repository before this program's edits.\n";
+
+export const SKILLS_DIRECTORY = path.join(
+	path.dirname(createRequire(import.meta.url).resolve("shorthand-code/package.json")),
+	"skills",
+);
+
+export function codeDescription(graphAvailable: boolean): string {
+	return graphAvailable
+		? DESCRIPTION.replace("\n\nSee the shorthand skill", `\n${GRAPH_DESCRIPTION}\nSee the shorthand skill`)
+		: DESCRIPTION;
+}
+
+export default async function (pi: ExtensionAPI, findGraph: () => Promise<unknown> = sightreadAvailable) {
+	// The shorthand skill ships with shorthand-code, whose `shorthand --skill` prints it for other agents.
+	pi.on("resources_discover", () => ({ skillPaths: [SKILLS_DIRECTORY] }));
+	const graphAvailable = Boolean(await findGraph());
 	// A failed run is an error, both for the model and for how Pi shows it. (execute() returns its details
 	// rather than throwing, since a thrown error loses them.)
 	pi.on("tool_result", async (event) => {
@@ -45,7 +65,7 @@ export default function (pi: ExtensionAPI) {
 	pi.registerTool({
 		name: "code",
 		label: "Code",
-		description: DESCRIPTION,
+		description: codeDescription(graphAvailable),
 		promptSnippet:
 			"Make multi-file, repetitive or rename/move changes with one Bun program; a small change to one file is quicker as a direct edit. Run verification separately afterward",
 
@@ -91,6 +111,7 @@ export default function (pi: ExtensionAPI) {
 						program: params.program,
 						timeoutMs: (params.timeout ?? DEFAULT_TIMEOUT_SECONDS) * 1000,
 						rollback: params.rollback ?? "file",
+						graph: graphAvailable,
 					},
 					signal,
 					(step) => (latest = step),

package/skills/shorthand/SKILL.md

@@ -1,117 +0,0 @@
----
-name: shorthand
-description: Edit repository files with Bun programs using plain text edits or structural matching. Covers renames, file and declaration moves, and call-site migrations; the advanced guide covers extracting code, moving syntax and rule objects.
----
-
-# Shorthand
-
-Use text replacement for known source; use structural matching when it saves enumerating
-occurrences or preserves varying syntax. Ordinary JavaScript strings, loops and Bun APIs work.
-Run tests, type-checks and builds separately with the shell tool after editing.
-
-## Replace known text
-
-```ts
-edit({ path: "src/config.ts", oldText: "timeoutMs: 1000", newText: "timeoutMs: 3000" });
-```
-
-`edit` replaces exactly one literal occurrence, throwing if it is missing or ambiguous. Include
-surrounding text to distinguish repeated occurrences. Replacement text is literal, including `$`.
-Line-ending differences are accepted when matching.
-`edit` calls are synchronous and can be combined in one program; later calls see earlier changes.
-
-## Refactors
-
-Rename symbols, move files, or move a declaration to another file, updating the project to match:
-
-```ts
-await refactor.rename({ file: "src/users.ts", symbol: "parseUser", to: "decodeUser" });
-await refactor.renameFile({ from: "src/users.ts", to: "src/models/users.ts" });
-await refactor.move({ file: "src/api.ts", symbol: "parseUser", to: "src/users/parse.ts" });
-```
-
-`refactor.rename` requires the declaration name to be unique in its file and leaves unrelated symbols
-alone. `refactor.renameFile` moves the file and updates imports and exports that resolve to it. Read
-[Semantic TypeScript refactors](advanced-refactors.md#semantic-typescript-refactors) for selection
-rules, updated paths and failure conditions.
-
-`refactor.move` appends the top-level declaration of `symbol` to `to`, which may be a new file. The
-target imports what the declaration uses, exporting helpers from the source when needed; the source
-imports it back if it still uses it; and files importing it from the source import it from the target.
-Importers keep their style, including `tsconfig` path aliases. Default exports, overloads, namespace
-imports that use it and dynamic imports of the source are refused before anything is written.
-
-## Insert before or after a statement
-
-Validate an order immediately before saving it:
-
-```ts
-const save = sg.one("await saveOrder(order);", "checkout.ts");
-sg.insert("validateOrder(order);", { before: save });
-```
-
-Use `{ after: save }` to insert after it instead. `sg.one(pattern, files?)` requires exactly one
-match. Select the whole statement, including its semicolon, for before/after insertion in JS/TS.
-
-## Replace calls while keeping their arguments
-
-Switch logging calls without reproducing their arguments:
-
-```ts
-sg.rewrite("console.log($$$ARGS)", "logger.info($$$ARGS)", "src");
-```
-
-`sg.rewrite(pattern, replacement, files?)` discovers, parses and writes matching files. Omit the
-scope for the working directory, or pass a file, directory or glob. `$X` captures one syntax node;
-`$$$X` captures a sequence. Captures can appear in the replacement text.
-
-## Change one argument and preserve the rest
-
-Migrate numeric retry limits to options objects, leaving existing options alone:
-
-```ts
-sg.rewrite("connect($URL, $RETRIES)", (m) => {
-	const retries = m.node.getMatch("RETRIES")!;
-	return retries.kind() === "number" ? retries.replace(`{ retries: ${retries.text()} }`) : null;
-});
-```
-
-A callback returns text to replace the whole match, a native edit for part of it, or `null` to skip.
-Rewrites apply one after another. A pattern rewrite skips places an earlier rewrite produced, so one
-rewrite per call shape is safe in any order; select them with `sg.find` to rewrite them again.
-**`node.replace()` constructs an edit; return it from the callback so `sg.rewrite` applies it.**
-
-## Replace an implementation while keeping its signature
-
-Make `calculateTotal` sum its prices, preserving parameter and return types:
-
-```ts
-const fn = sg.one(
-	{ rule: { kind: "function_declaration", has: { field: "name", regex: "^calculateTotal$" } } },
-	"prices.ts",
-);
-sg.rewrite(fn, (m) => m.node.field("body")!.replace("{ return prices.reduce((total, price) => total + price, 0); }"));
-```
-
-Use `kind: "method_definition"` with the same `has` to select a class method; match names with
-`regex`, since a method's name is not an identifier pattern. `sg.rewrite(match, "new source")`
-replaces the whole selected node instead. `sg.find` returns an
-array: pass it once to `sg.rewrite(matches, callback)` for independent edits. Each call writes
-immediately within the editing workspace; select again if a later edit depends on that write.
-
-## Write files or replace plain text
-
-```ts
-await Bun.write("src/defaults.ts", "export const retryLimit = 3;\n");
-const source = await Bun.file("src/config.ts").text();
-await Bun.write("src/config.ts", source.replace("timeoutMs: 1000", "timeoutMs: 3000"));
-```
-
-Use repository-relative paths. Changes apply on successful exit by default; the tool reports the
-diff, preserves existing UTF-8 BOMs and uniform line endings across write methods, then uses a
-detected project formatter. Counters and console summaries aren't required.
-
-This page covers renames, file and declaration moves, and call-site migrations. Read
-[advanced-refactors.md](advanced-refactors.md) only to extract code into a new function or file,
-insert, move or remove other statements, or use rule objects or the native ast-grep API. The bundled
-TypeScript 7 package has no legacy compiler API; use the supplied structural tools instead.

package/skills/shorthand/advanced-refactors.md

@@ -1,146 +0,0 @@
-# Advanced refactors
-
-Use this guide for extraction, complex structural rewrites, syntax placement or other languages.
-The everyday file and replacement operations are in [SKILL.md](SKILL.md).
-
-## Semantic TypeScript refactors
-
-Prefer `refactor.rename` to a structural rewrite when changing a TypeScript symbol. It asks the TypeScript
-language server to rename the resolved symbol across the project, so unrelated names and strings are
-left alone. `file` is the declaration's file, and `symbol` must name exactly one declaration there.
-Missing names, repeated declarations and overloads are rejected without writing.
-
-Use `refactor.renameFile` to move a whole TypeScript file. It updates imports and exports that resolve to
-the file, as well as relative module paths inside the moved file, then performs the move. The source
-must exist, the destination must not exist, and both paths must remain inside the repository.
-
-Await each operation; when it resolves, all of its edits are complete. Use `sg.move` below for
-moving syntax between files; it does not repair imports or bindings. `refactor.move` moves a top-level
-declaration with its imports.
-
-## Extract existing source
-
-Select and reuse the implementation rather than copying it into the program or searching for braces.
-This extracts a state-independent method, leaves a delegate, and updates its direct caller:
-
-```ts
-const pattern = { rule: { kind: "method_definition", has: { field: "name", regex: "^format$" } } };
-const method = sg.one(pattern, "writer.ts");
-await Bun.write(
-	"table.ts",
-	'import type { Cell, FormatOptions } from "./types";\n' +
-		method.text.replace(/^format\b/, "export function renderTable"),
-);
-sg.rewrite(method, (m) => m.node.field("body")!.replace("{ return renderTable(rows, options); }"));
-await Bun.write("writer.ts", 'import { renderTable } from "./table";\n' + (await Bun.file("writer.ts").text()));
-sg.rewrite('import { TableWriter } from "./writer"', 'import { renderTable } from "./table"', "export.ts");
-sg.rewrite("new TableWriter().format($$$ARGS)", "renderTable($$$ARGS)", "export.ts");
-```
-
-Preserve imports and dependencies; moving source does not remove its dependence on instance state.
-`field("body")` selects the actual body even when defaults or comments contain braces.
-
-## Structural matching details
-
-Patterns must parse as one syntax node; a standalone class method such as
-`format($$$PARAMS) { $$$BODY }` is matched as a method. `$X` captures one node, `$$$X` a sequence, and `$_`
-matches without capturing. Capture text is available as `m.X` or `m.vars.X`.
-
-Callbacks are synchronous. They can return an array of native edits, or `null`/`undefined`/`false`
-to skip. `sg.rewrite` counts matches producing edits, not individual edits. Overlaps are rejected;
-an empty selection returns zero. Syntax fields and node kinds depend on the language.
-
-`sg.find` and `sg.rewrite` handle JS, TS, TSX, HTML and CSS. Scopes accept files, directories,
-globs or arrays. Paths may be relative or absolute within the editing workspace; results use
-repository-relative paths. String scopes use Git's tracked and non-ignored files. An explicit
-`sg.file()` target can also select an ignored JS/TS file; only files Git sees are applied afterward.
-
-## Inserting, moving and removing syntax
-
-For JS/TS, use matches from `sg.find` or `sg.one(pattern, files)`, which requires exactly one match.
-`sg.file(path)` selects a JS/TS file root for placement or for scoping `find`, `one` and `rewrite`.
-Pass paths or file targets individually or in mixed arrays. Missing targets are valid insertion destinations,
-but cannot be searched.
-
-```ts
-sg.insert("initialize();", { before: sg.one("run();", "src/app.ts") });
-sg.move(sg.one("function helper() { $$$BODY }", "src/old.ts"), {
-	endOf: sg.file("src/new.ts"),
-});
-sg.remove(sg.find("obsolete();", "src")); // single match or array; validates the batch before writing
-```
-
-Choose one destination: `before`/`after` a whole statement or declaration (`"run();"`), or
-`startOf`/`endOf` a file root or `statement_block`. For a function, select its body explicitly.
-Argument lists and class bodies aren't supported.
-
-To copy, use `sg.insert(source.text, destination)`. `sg.move(source, destination, transform?)`
-accepts an optional `(text) => string` returning non-empty replacement text.
-
-**Rematch placement targets after each edit**; use array removal for matches from one search. Adjacent comments stay in
-place, and interior whitespace is preserved. Imports and bindings aren't repaired; to move a top-level
-declaration with its imports, use `refactor.move`. If placement
-rejects joined statement boundaries, add explicit semicolons.
-
-## Rule objects
-
-When a pattern alone can't say it, pass a rule instead:
-
-```ts
-sg.find({ rule: { kind: "import_statement" } }, "src");
-sg.find({ rule: { pattern: "console.log($$$A)", inside: { kind: "function_declaration", stopBy: "end" } } }, "src");
-sg.find(
-	{ rule: { pattern: "console.log($$$A)", not: { inside: { kind: "function_declaration", stopBy: "end" } } } },
-	"src",
-);
-// constraints restrict what a capture may match
-sg.rewrite({ rule: { pattern: "$F($X)" }, constraints: { F: { regex: "^(oldApi|legacyApi)$" } } }, "newApi($X)", "src");
-```
-
-`kind` names come from tree-sitter (`function_declaration`, `call_expression`, `import_statement`,
-…). `stopBy: "end"` searches all ancestors, not just the parent.
-
-## Native ast-grep API
-
-For transformations outside file-backed rewrites, ast-grep's JavaScript API is exposed on `sg`:
-
-```ts
-const root = sg.parse(sg.Lang.TypeScript, sourceText).root();
-const edits = root.findAll("oldApi($$$ARGS)").map((node) => node.replace("newApi()"));
-await Bun.write("src/app.ts", root.commitEdits(edits));
-```
-
-`import { parse, Lang } from "@ast-grep/napi"` also works. Native `replace` constructs edits;
-`commitEdits` returns updated source text. Neither writes files by itself.
-The bundled TypeScript 7 package does not expose the legacy compiler API (`createSourceFile`,
-`ScriptTarget`); changing import syntax won't make it available.
-
-## File discovery and commands
-
-```ts
-glob("src/**/*.ts"); // sorted paths Git sees
-grep("oldApi(", "src"); // [{ file, line, text }]; accepts a RegExp too
-const files = await $`git ls-files`.text();
-```
-
-`glob`, `grep` and `sg` are synchronous. Bun's `$` needs `await`; interpolated values are
-quoted as single arguments, and arrays become multiple arguments. These globals and bundled CLIs
-belong to `code`, not necessarily ordinary shell calls. `node:fs` and ordinary Bun APIs also work.
-
-## Execution options
-
-Programs run in an isolated repository workspace. Use relative paths: the live checkout's absolute
-path is inaccessible on macOS. On both platforms, host paths outside the workspace are read-only
-(including external symlink targets). `$TMPDIR` is private to the run.
-Writes to `.git` are blocked.
-
-The default timeout is two seconds; request more for longer transformations. Time inside helpers
-(`edit`, `glob`, `grep`, `sg`, `refactor`) does not count toward it, up to 60 extra seconds per run.
-By default, rollback happens per file: files involved in failed or interrupted edits are discarded,
-while the others are retained, including after exceptions. Unattributed failures
-(such as failed checks) preserve completed edits and report the failure. A failed file loses all
-its edits from this run, even if the error is caught. Multi-file operations such as moves share
-one outcome. Arbitrary shell failures cannot identify failed closed
-files. Open writers are inspected before failure exits and timeout termination; inspection failures
-or crashes that bypass exit handling retain nothing. Cancellation still discards everything.
-Use `rollback: "all"` when the whole change must be atomic.