@alint-js/tools-fs 0.0.20

package/README.md

@@ -0,0 +1,34 @@
+# `@alint-js/tools-fs`
+
+Shared filesystem `AgentTool`s for alint plugins whose rules let an agent explore a project.
+`createTools(cwd, options?)` returns four tools, all reporting paths relative to `cwd`:
+
+- `read_file` — read a UTF-8 file (path relative to `cwd` or absolute).
+- `list_files` — list files, with optional glob `patterns`, `ignore`, and `directory`.
+- `search_files` — match file paths by substring.
+- `search_in_files` — match file contents, returning `path:line: snippet` lines.
+
+## Usage
+
+```ts
+import { createTools, DEFAULT_IGNORE_PATTERNS } from '@alint-js/tools-fs'
+
+// Built-in ignores:
+const tools = createTools(ctx.cwd)
+// Extend the builtins:
+const py = createTools(ctx.cwd, { ignore: [...DEFAULT_IGNORE_PATTERNS, '**/.venv/**'] })
+// Replace the builtins:
+const bare = createTools(ctx.cwd, { ignore: ['**/generated/**'] })
+```
+
+`options.ignore` **replaces** the builtins (`git/build/dist/node_modules/vendor`); spread
+`DEFAULT_IGNORE_PATTERNS` to extend them instead. Per-call ignores from the agent always append to the ignore list set at tool creation time.
+The underlying `listFiles` / `readFile` / `searchFiles` / `searchInFiles` are exported too.
+
+## When to use
+
+- **Use** when a `ctx.agent` rule needs generic read/list/search tools to explore a project.
+
+## When not to use
+
+- **Don't** for a single structured model judgement without an agent loop, or when you need real code search (regex/AST/ranking).

package/dist/index.d.mts

@@ -0,0 +1,28 @@
+import { AgentTool } from "@alint-js/core/agent";
+
+//#region src/list.d.ts
+declare const DEFAULT_IGNORE_PATTERNS: readonly string[];
+interface ListFilesOptions {
+  ignore?: readonly string[] | string;
+  patterns?: readonly string[] | string;
+}
+declare function listFiles(root: string, options?: ListFilesOptions): Promise<string[]>;
+declare function toStringArray(value: readonly string[] | string | undefined): string[];
+//#endregion
+//#region src/read.d.ts
+declare function readFile(cwd: string, inputPath: string | undefined): Promise<string>;
+//#endregion
+//#region src/search.d.ts
+interface SearchOptions extends ListFilesOptions {
+  directory?: string;
+}
+declare function searchFiles(cwd: string, query: string, options?: SearchOptions): Promise<string>;
+declare function searchInFiles(cwd: string, query: string, options?: SearchOptions): Promise<string>;
+//#endregion
+//#region src/index.d.ts
+interface CreateToolsOptions {
+  ignore?: readonly string[] | string;
+}
+declare function createTools(cwd: string, options?: CreateToolsOptions): AgentTool[];
+//#endregion
+export { CreateToolsOptions, DEFAULT_IGNORE_PATTERNS, type ListFilesOptions, type SearchOptions, createTools, listFiles, readFile, searchFiles, searchInFiles, toStringArray };

package/dist/index.mjs

@@ -0,0 +1,144 @@
+import { relative, resolve } from "node:path";
+import { glob } from "tinyglobby";
+import { readFile as readFile$1 } from "node:fs/promises";
+//#region src/list.ts
+const maxListedFiles = 160;
+const DEFAULT_IGNORE_PATTERNS = [
+	"**/.git/**",
+	"**/build/**",
+	"**/dist/**",
+	"**/node_modules/**",
+	"**/vendor/**"
+];
+async function listFiles(root, options = {}) {
+	try {
+		return (await glob(options.patterns ?? "**/*", {
+			absolute: true,
+			cwd: root,
+			ignore: toStringArray(options.ignore),
+			onlyFiles: true
+		})).slice(0, maxListedFiles);
+	} catch {
+		return [];
+	}
+}
+function toStringArray(value) {
+	if (Array.isArray(value)) return [...value];
+	return typeof value === "string" ? [value] : [];
+}
+//#endregion
+//#region src/read.ts
+async function readFile(cwd, inputPath) {
+	if (!inputPath) throw new TypeError("Expected file path");
+	return readFile$1(resolve(cwd, inputPath), "utf8");
+}
+//#endregion
+//#region src/search.ts
+const maxSearchResults = 24;
+const maxSearchBytesPerFile = 2e5;
+async function searchFiles(cwd, query, options = {}) {
+	return (await listFiles(resolve(cwd, options.directory ?? "."), options)).filter((file) => relative(cwd, file).includes(query)).slice(0, maxSearchResults).map((file) => relative(cwd, file)).join("\n");
+}
+async function searchInFiles(cwd, query, options = {}) {
+	const files = await listFiles(resolve(cwd, options.directory ?? "."), options);
+	const snippets = [];
+	for (const file of files) {
+		if (snippets.length >= maxSearchResults) break;
+		let text;
+		try {
+			text = await readFile$1(file, "utf8");
+		} catch {
+			continue;
+		}
+		if (text.length > maxSearchBytesPerFile || !text.includes(query)) continue;
+		for (const [index, line] of text.split("\n").entries()) {
+			if (!line.includes(query)) continue;
+			snippets.push(`${relative(cwd, file)}:${index + 1}: ${line.trim()}`);
+			if (snippets.length >= maxSearchResults) break;
+		}
+	}
+	return snippets.join("\n");
+}
+//#endregion
+//#region src/index.ts
+function createTools(cwd, options = {}) {
+	const baseIgnore = options.ignore === void 0 ? DEFAULT_IGNORE_PATTERNS : toStringArray(options.ignore);
+	return [
+		{
+			description: "Read a UTF-8 text file. The path may be relative to the project root or absolute.",
+			execute: (input) => readFile(cwd, getStringProperty(input, "path")),
+			name: "read_file",
+			parameters: {
+				additionalProperties: false,
+				properties: { path: { type: "string" } },
+				required: ["path"],
+				type: "object"
+			}
+		},
+		{
+			description: "List files under a directory with optional glob patterns and ignore patterns.",
+			execute: async (input) => {
+				const listOptions = getListOptions(input, baseIgnore);
+				return (await listFiles(resolve(cwd, listOptions.directory ?? "."), listOptions)).map((path) => relative(cwd, path)).join("\n");
+			},
+			name: "list_files",
+			parameters: fileSearchParameters(false)
+		},
+		{
+			description: "Search listed file paths by substring. Use search_in_files to search file contents.",
+			execute: (input) => searchFiles(cwd, getRequiredStringProperty(input, "query"), getListOptions(input, baseIgnore)),
+			name: "search_files",
+			parameters: fileSearchParameters(true)
+		},
+		{
+			description: "Search file contents by literal substring and return path:line snippets.",
+			execute: (input) => searchInFiles(cwd, getRequiredStringProperty(input, "query"), getListOptions(input, baseIgnore)),
+			name: "search_in_files",
+			parameters: fileSearchParameters(true)
+		}
+	];
+}
+function fileSearchParameters(requiresQuery) {
+	return {
+		additionalProperties: false,
+		properties: {
+			directory: { type: "string" },
+			ignore: stringOrStringArraySchema(),
+			patterns: stringOrStringArraySchema(),
+			...requiresQuery ? { query: { type: "string" } } : {}
+		},
+		required: requiresQuery ? ["query"] : [],
+		type: "object"
+	};
+}
+function getListOptions(input, baseIgnore) {
+	return {
+		directory: getStringProperty(input, "directory"),
+		ignore: [...baseIgnore, ...toStringArray(getStringOrStringArrayProperty(input, "ignore"))],
+		patterns: getStringOrStringArrayProperty(input, "patterns")
+	};
+}
+function getRequiredStringProperty(input, key) {
+	const value = getStringProperty(input, key);
+	if (value === void 0) throw new TypeError(`Expected tool input property "${key}" to be a string`);
+	return value;
+}
+function getStringOrStringArrayProperty(input, key) {
+	if (!input || typeof input !== "object" || Array.isArray(input)) return;
+	const value = input[key];
+	if (typeof value === "string") return value;
+	return Array.isArray(value) && value.every((item) => typeof item === "string") ? value : void 0;
+}
+function getStringProperty(input, key) {
+	if (!input || typeof input !== "object" || Array.isArray(input)) return;
+	const value = input[key];
+	return typeof value === "string" ? value : void 0;
+}
+function stringOrStringArraySchema() {
+	return { anyOf: [{ type: "string" }, {
+		items: { type: "string" },
+		type: "array"
+	}] };
+}
+//#endregion
+export { DEFAULT_IGNORE_PATTERNS, createTools, listFiles, readFile, searchFiles, searchInFiles, toStringArray };

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@alint-js/tools-fs",
+  "type": "module",
+  "version": "0.0.20",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "tinyglobby": "^0.2.17",
+    "@alint-js/core": "0.0.20"
+  },
+  "devDependencies": {
+    "tsdown": "^0.22.3",
+    "typescript": "^6.0.3"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}