@mrclrchtr/supi-code-intelligence 1.6.0 → 1.7.0

package/node_modules/@mrclrchtr/supi-tree-sitter/node_modules/@mrclrchtr/supi-core/src/tool-framework.ts

@@ -0,0 +1,116 @@
+// Shared tool framework for SuPi extensions.
+//
+// Provides a standard ToolSpec→PromptSurface→registerTool pipeline so
+// individual packages do not duplicate spec interfaces, guidance derivation,
+// registration loops, or common TypeBox parameter schemas.
+
+import type {
+  AgentToolResult,
+  AgentToolUpdateCallback,
+  ExtensionAPI,
+  ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import { type TSchema, Type } from "typebox";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** Minimum contract for a SuPi tool definition. */
+export interface SuiPiToolSpec {
+  name: string;
+  label: string;
+  description: string;
+  promptSnippet: string;
+  promptGuidelines: string[];
+  parameters: TSchema;
+}
+
+/** Derived prompt surface — what pi flattens into the system prompt. */
+export interface SuiPiToolPromptSurface {
+  description: string;
+  promptSnippet: string;
+  promptGuidelines: string[];
+}
+
+// ---------------------------------------------------------------------------
+// Guidance derivation
+// ---------------------------------------------------------------------------
+
+/**
+ * Static derivation: copies spec fields into a prompt surface.
+ *
+ * Packages that need dynamic guidance (e.g. server-coverage injection) should
+ * build their own surfaces, optionally starting from the output of this helper.
+ */
+export function derivePromptSurface(spec: SuiPiToolSpec): SuiPiToolPromptSurface {
+  return {
+    description: spec.description,
+    promptSnippet: spec.promptSnippet,
+    promptGuidelines: [...spec.promptGuidelines],
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Registration
+// ---------------------------------------------------------------------------
+
+// biome-ignore lint/complexity/useMaxParams: matches pi ToolDefinition.execute signature
+export type ToolExecuteFn = (
+  toolCallId: string,
+  params: unknown,
+  signal: AbortSignal | undefined,
+  onUpdate: AgentToolUpdateCallback<Record<string, unknown>> | undefined,
+  ctx: ExtensionContext,
+) => Promise<AgentToolResult<Record<string, unknown>>>;
+
+/**
+ * Register a set of tools from specs + pre-derived surfaces.
+ *
+ * `createExecute` receives the spec and returns a pi-compatible execute
+ * function.  This keeps execute-logic package-local while the framework owns
+ * the declarative surface and registration boilerplate.
+ */
+export function registerSuiPiTools(
+  pi: ExtensionAPI,
+  specs: readonly SuiPiToolSpec[],
+  surfaces: Record<string, SuiPiToolPromptSurface>,
+  createExecute: (spec: SuiPiToolSpec) => ToolExecuteFn,
+): void {
+  for (const spec of specs) {
+    const surface = surfaces[spec.name];
+    pi.registerTool({
+      name: spec.name,
+      label: spec.label,
+      description: surface?.description ?? spec.description,
+      promptSnippet: surface?.promptSnippet ?? spec.promptSnippet,
+      promptGuidelines: surface?.promptGuidelines ?? [...spec.promptGuidelines],
+      parameters: spec.parameters,
+      execute: createExecute(spec),
+    });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Shared parameter builders
+// ---------------------------------------------------------------------------
+
+/** File path (relative or absolute). */
+export const FileParam = Type.String({ description: "File path (relative or absolute)" });
+
+/** 1-based line number. */
+export const LineParam = Type.Number({ description: "1-based line number", minimum: 1 });
+
+/** 1-based character column (UTF-16). */
+export const CharacterParam = Type.Number({
+  description: "1-based column number (UTF-16)",
+  minimum: 1,
+});
+
+/** Symbol name for discovery-based resolution. */
+export const SymbolParam = Type.String({
+  description: "Symbol name for discovery-based resolution",
+});
+
+/** Maximum results to return. */
+export const MaxResultsParam = Type.Number({ description: "Maximum results to return" });

package/node_modules/@mrclrchtr/supi-tree-sitter/node_modules/web-tree-sitter/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2018 Max Brunsfeld
+
+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/node_modules/@mrclrchtr/supi-tree-sitter/node_modules/web-tree-sitter/README.md

@@ -0,0 +1,265 @@
+# Web Tree-sitter
+
+[![npmjs.com badge]][npmjs.com]
+
+[npmjs.com]: https://www.npmjs.org/package/web-tree-sitter
+[npmjs.com badge]: https://img.shields.io/npm/v/web-tree-sitter.svg?color=%23BF4A4A
+
+WebAssembly bindings to the [Tree-sitter](https://github.com/tree-sitter/tree-sitter) parsing library.
+
+## Setup
+
+You can download the `web-tree-sitter.js` and `web-tree-sitter.wasm` files from [the latest GitHub release][gh release] and load
+them using a standalone script:
+
+```html
+<script src="/the/path/to/web-tree-sitter.js"></script>
+
+<script>
+  const { Parser } = window.TreeSitter;
+  Parser.init().then(() => { /* the library is ready */ });
+</script>
+```
+
+You can also install [the `web-tree-sitter` module][npm module] from NPM and load it using a system like Webpack:
+
+```js
+const { Parser } = require('web-tree-sitter');
+Parser.init().then(() => { /* the library is ready */ });
+```
+
+or Vite:
+
+```js
+import { Parser }  from 'web-tree-sitter';
+Parser.init().then(() => { /* the library is ready */ });
+```
+
+With Vite, you also need to make sure your server provides the `tree-sitter.wasm`
+file to your `public` directory. You can do this automatically with a `postinstall`
+[script](https://docs.npmjs.com/cli/v10/using-npm/scripts) in your `package.json`:
+
+```js
+"postinstall": "cp node_modules/web-tree-sitter/tree-sitter.wasm public"
+```
+
+You can also use this module with [deno](https://deno.land/):
+
+```js
+import { Parser } from "npm:web-tree-sitter";
+await Parser.init();
+// the library is ready
+```
+
+To use the debug version of the library, replace your import of `web-tree-sitter` with `web-tree-sitter/debug`:
+
+```js
+import { Parser } from 'web-tree-sitter/debug'; // or require('web-tree-sitter/debug')
+
+Parser.init().then(() => { /* the library is ready */ });
+```
+
+This will load the debug version of the `.js` and `.wasm` file, which includes debug symbols and assertions.
+
+> [!NOTE]
+> The `web-tree-sitter.js` file on GH releases is an ES6 module. If you are interested in using a pure CommonJS library, such
+> as for Electron, you should use the `web-tree-sitter.cjs` file instead.
+
+### Basic Usage
+
+First, create a parser:
+
+```js
+const parser = new Parser();
+```
+
+Then assign a language to the parser. Tree-sitter languages are packaged as individual `.wasm` files (more on this below):
+
+```js
+const { Language } = require('web-tree-sitter');
+const JavaScript = await Language.load('/path/to/tree-sitter-javascript.wasm');
+parser.setLanguage(JavaScript);
+```
+
+Now you can parse source code:
+
+```js
+const sourceCode = 'let x = 1; console.log(x);';
+const tree = parser.parse(sourceCode);
+```
+
+and inspect the syntax tree.
+
+```javascript
+console.log(tree.rootNode.toString());
+
+// (program
+//   (lexical_declaration
+//     (variable_declarator (identifier) (number)))
+//   (expression_statement
+//     (call_expression
+//       (member_expression (identifier) (property_identifier))
+//       (arguments (identifier)))))
+
+const callExpression = tree.rootNode.child(1).firstChild;
+console.log(callExpression);
+
+// { type: 'call_expression',
+//   startPosition: {row: 0, column: 16},
+//   endPosition: {row: 0, column: 30},
+//   startIndex: 0,
+//   endIndex: 30 }
+```
+
+### Editing
+
+If your source code *changes*, you can update the syntax tree. This will take less time than the first parse.
+
+```javascript
+// Replace 'let' with 'const'
+const newSourceCode = 'const x = 1; console.log(x);';
+
+tree.edit({
+  startIndex: 0,
+  oldEndIndex: 3,
+  newEndIndex: 5,
+  startPosition: {row: 0, column: 0},
+  oldEndPosition: {row: 0, column: 3},
+  newEndPosition: {row: 0, column: 5},
+});
+
+const newTree = parser.parse(newSourceCode, tree);
+```
+
+### Parsing Text From a Custom Data Structure
+
+If your text is stored in a data structure other than a single string, you can parse it by supplying a callback to `parse`
+instead of a string:
+
+```javascript
+const sourceLines = [
+  'let x = 1;',
+  'console.log(x);'
+];
+
+const tree = parser.parse((index, position) => {
+  let line = sourceLines[position.row];
+  if (line) return line.slice(position.column);
+});
+```
+
+### Getting the `.wasm` language files
+
+There are several options on how to get the `.wasm` files for the languages you want to parse.
+
+#### From npmjs.com
+
+The recommended way is to just install the package from npm. For example, to parse JavaScript, you can install the `tree-sitter-javascript`
+package:
+
+```sh
+npm install tree-sitter-javascript
+```
+
+Then you can find the `.wasm` file in the `node_modules/tree-sitter-javascript` directory.
+
+#### From GitHub
+
+You can also download the `.wasm` files from GitHub releases, so long as the repository uses our reusable workflow to publish
+them.
+For example, you can download the JavaScript `.wasm` file from the tree-sitter-javascript [releases page][gh release js].
+
+#### Generating `.wasm` files
+
+You can also generate the `.wasm` file for your desired grammar. Shown below is an example of how to generate the `.wasm`
+file for the JavaScript grammar.
+
+**IMPORTANT**: [Emscripten][emscripten], [Docker][docker], or [Podman][podman] need to be installed.
+
+First install `tree-sitter-cli`, and the tree-sitter language for which to generate `.wasm`
+(`tree-sitter-javascript` in this example):
+
+```sh
+npm install --save-dev tree-sitter-cli tree-sitter-javascript
+```
+
+Then just use tree-sitter cli tool to generate the `.wasm`.
+
+```sh
+npx tree-sitter build --wasm node_modules/tree-sitter-javascript
+```
+
+If everything is fine, file `tree-sitter-javascript.wasm` should be generated in current directory.
+
+### Running .wasm in Node.js
+
+Notice that executing `.wasm` files in Node.js is considerably slower than running [Node.js bindings][node bindings].
+However, this could be useful for testing purposes:
+
+```javascript
+const Parser = require('web-tree-sitter');
+
+(async () => {
+  await Parser.init();
+  const parser = new Parser();
+  const Lang = await Parser.Language.load('tree-sitter-javascript.wasm');
+  parser.setLanguage(Lang);
+  const tree = parser.parse('let x = 1;');
+  console.log(tree.rootNode.toString());
+})();
+```
+
+### Running .wasm in browser
+
+`web-tree-sitter` can run in the browser, but there are some common pitfalls.
+
+#### Loading the .wasm file
+
+`web-tree-sitter` needs to load the `tree-sitter.wasm` file. By default, it assumes that this file is available in the
+same path as the JavaScript code. Therefore, if the code is being served from `http://localhost:3000/bundle.js`, then
+the Wasm file should be at `http://localhost:3000/tree-sitter.wasm`.
+
+For server side frameworks like NextJS, this can be tricky as pages are often served from a path such as
+`http://localhost:3000/_next/static/chunks/pages/index.js`. The loader will therefore look for the Wasm file at
+`http://localhost:3000/_next/static/chunks/pages/tree-sitter.wasm`. The solution is to pass a `locateFile` function in
+the `moduleOptions` argument to `Parser.init()`:
+
+```javascript
+await Parser.init({
+  locateFile(scriptName: string, scriptDirectory: string) {
+    return scriptName;
+  },
+});
+```
+
+`locateFile` takes in two parameters, `scriptName`, i.e. the Wasm file name, and `scriptDirectory`, i.e. the directory
+where the loader expects the script to be. It returns the path where the loader will look for the Wasm file. In the NextJS
+case, we want to return just the `scriptName` so that the loader will look at `http://localhost:3000/tree-sitter.wasm`
+and not `http://localhost:3000/_next/static/chunks/pages/tree-sitter.wasm`.
+
+For more information on the module options you can pass in, see the [emscripten documentation][emscripten-module-options].
+
+#### "Can't resolve 'fs' in 'node_modules/web-tree-sitter"
+
+Most bundlers will notice that the `web-tree-sitter.js` file is attempting to import `fs`, i.e. node's file system library.
+Since this doesn't exist in the browser, the bundlers will get confused. For Webpack, you can fix this by adding the
+following to your webpack config:
+
+```javascript
+{
+  resolve: {
+    fallback: {
+      fs: false
+    }
+  }
+}
+```
+
+[docker]: https://www.docker.com
+[emscripten]: https://emscripten.org
+[emscripten-module-options]: https://emscripten.org/docs/api_reference/module.html#affecting-execution
+[gh release]: https://github.com/tree-sitter/tree-sitter/releases/latest
+[gh release js]: https://github.com/tree-sitter/tree-sitter-javascript/releases/latest
+[node bindings]: https://github.com/tree-sitter/node-tree-sitter
+[npm module]: https://www.npmjs.com/package/web-tree-sitter
+[podman]: https://podman.io