clast-ai 0.2.2 → 0.2.4

package/skills/audit/SKILL.md

@@ -1,37 +1,30 @@
 ---
 name: audit
-description: Produce a factual inventory of a code base for due diligence or onboarding - size, languages, structure, endpoints, database access, dependencies, largest hot spots and dead code.
+description: Factual inventory of a code base for due diligence or onboarding - size, structure, endpoints, database access, dependencies, dead code.
 argument-hint: "[path]"
 disable-model-invocation: true
 allowed-tools: mcp__plugin_clast_clast__clast_stats, mcp__plugin_clast_clast__clast_overview, mcp__plugin_clast_clast__clast_unused, mcp__plugin_clast_clast__clast_file_summary, mcp__plugin_clast_clast__clast_grep, Grep, Read, Glob
 ---
 
-Produce an inventory of this code base. Scope: `$ARGUMENTS` (the whole project when empty; pass it as
-`path` to every call below).
+Scope: `$ARGUMENTS` (empty = whole project). Pass it as `path` to every call.
 
-Gather the facts with these calls. They are independent, so issue them together:
+Issue these calls together:
 
-- `clast_stats` what=inventory: files, lines, languages, production vs tests vs vendored, symbols by
-  kind, longest functions.
-- `clast_overview`: the main directories and what lives in them.
-- `clast_stats` what=endpoints: HTTP / RPC routes by framework and by directory, and outbound client
-  calls.
-- `clast_stats` what=database: SQL, schema, ORM models, migrations, query call sites by receiver.
-- `clast_stats` what=imports: external dependencies by how many files use them.
-- `clast_unused` with the default limit: only the totals and the largest files matter here.
+- `clast_stats` what=inventory
+- `clast_overview`
+- `clast_stats` what=endpoints
+- `clast_stats` what=database
+- `clast_stats` what=imports
+- `clast_unused` (totals and largest files only)
 
-Then write the report:
+Report:
 
-1. **Size and shape**: lines and files per language, share of tests, vendored or generated code.
-2. **Structure**: the top-level areas with one line each on what they contain.
-3. **Interfaces**: number of endpoints by framework and area; outbound calls.
-4. **Data**: tables or models, migrations, where queries are issued from, the most-used models.
-5. **Dependencies**: the most-used external packages; anything unusual (several libraries for the same
-   job, very old or abandoned-looking packages if the manifest shows versions).
-6. **Maintainability signals**: the longest functions and largest files, the share of code used only
-   by tests, the amount of unused code.
-7. **Caveats**: endpoint and database figures come from pattern matching; dead code is judged by name.
-   Spot-check one figure from each of sections 3 and 4 with a Grep and state whether it matched.
+1. Size and shape: lines and files per language, share of tests, vendored or generated code.
+2. Structure: top-level areas, one line each.
+3. Interfaces: endpoints by framework and area, outbound calls.
+4. Data: tables or models, migrations, where queries are issued, most-used models.
+5. Dependencies: most-used packages, duplicates for the same job.
+6. Maintainability: longest functions, largest files, code used only by tests, unused code.
+7. Caveats: endpoint and database figures are pattern-based, dead code is judged by name. Spot-check one figure from sections 3 and 4 with Grep and state the result.
 
-Use exact numbers from the tools; do not estimate or tally by hand. Keep it to what was measured: no
-opinions on quality that the numbers do not support.
+Use exact tool numbers. No estimates. No quality opinions beyond the numbers.

package/skills/deadcode/SKILL.md

@@ -1,33 +1,20 @@
 ---
 name: deadcode
-description: Find dead code (unused functions, methods and types) in the project or under a path, verify the candidates, and offer to remove them.
+description: Find dead code in the project or under a path, verify it, remove what the user confirms.
 argument-hint: "[path]"
 disable-model-invocation: true
 allowed-tools: mcp__plugin_clast_clast__clast_unused, mcp__plugin_clast_clast__clast_call_graph, mcp__plugin_clast_clast__clast_references, mcp__plugin_clast_clast__clast_grep, Grep, Read
 ---
 
-Find dead code. Scope: `$ARGUMENTS` (the whole project when empty).
+Scope: `$ARGUMENTS` (empty = whole project).
 
-1. Call `clast_unused` with `path` set to the scope (omit it for the whole project). On a large
-   project start with the default limit; raise it only if the user wants the full list.
-2. The result has groups. Treat them differently:
-   - **unused**: the name is never referenced, or only by other unused code. Strong candidates.
-   - **probably unused**: the name is called, but every call binds to another definition. Check each
-     with `clast_call_graph` before reporting it.
-   - **used only by tests**: dead in production; removing it means removing the tests too. Report, do
-     not propose deleting without asking.
-   - **name appears in a string, config or template**: may be reached by reflection, routing or a
-     template. Open the cited location and say what it is.
-   - symbols marked `exported`: unused inside this project. In an application that is dead code; in a
-     library it may be public API. Say which case applies here (look for a published package, a
-     public header directory, or an API surface file).
-3. Verify before you present: for the candidates you intend to recommend (at most about 15), run one
-   Grep for the bare name across the repository and drop any that turn up in build files, scripts,
-   generated code or documentation that shows it is an entry point.
-4. Report as a short table grouped by file: symbol, lines, size, and why it is considered unused. Give
-   the total number of removable lines. State the limits in one sentence: the check is by name, so
-   members with common names (`get`, `run`) are never listed, and code reached only through reflection
-   can be listed wrongly.
-5. Do not delete anything yet. Ask which of the candidates to remove. When the user confirms, delete
-   them (and helpers that only they used), then build or run the tests the project has to confirm
-   nothing broke, and report the result.
+1. Call `clast_unused` with `path` = scope.
+2. Treat each group:
+   - unused: strong candidates.
+   - probably unused: confirm each with `clast_call_graph`.
+   - used only by tests: report only.
+   - name in a string, config or template: open the cited location, state what it is.
+   - `exported`: dead in an application, possibly public API in a library. State which applies.
+3. For up to 15 candidates, Grep the bare name repo-wide. Drop any found in build files, scripts or generated code.
+4. Report a table by file: symbol, lines, size, reason. Give total removable lines. State once: judged by name, common member names are never listed, reflection can cause false entries.
+5. Delete nothing until the user selects. Then delete the selection and helpers only it used, run the build or tests, report the result.

package/skills/explore/SKILL.md

@@ -1,54 +1,35 @@
 ---
 name: explore
-description: >
-  How to get the most out of the clast code index: which tool answers which question, and the habits
-  that save round trips. Use when navigating, reviewing or about to change code in a repository that
-  has the clast MCP tools, especially for multi-step questions (call chains, subclasses, impact, counts,
-  dead code) or code described by behaviour instead of by name.
+description: Which clast tool answers which question, and when to skip clast. Use when navigating, reviewing or about to change code in a repository that has the clast MCP tools.
 ---
 
-# Using the clast code index well
+# clast
 
-Clast answers structural questions in one call. It does not replace Grep for "where is this exact
-name" or Read for code you are about to edit: measured against plain grep, clast wins on questions that
-take several hops, on counting, on dead code and on finding code by what it does; simple lookups are a
-tie. Use it where it wins.
-
-## Pick the tool by question
+Use clast for multi-hop questions, counts, dead code and code described by behaviour.
+Skip clast for one exact name (Grep) and for mechanical edits.
 
 | Question | Tool |
 |----------|------|
-| What is in this repo / directory / file? | `clast_overview`, then `clast_file_summary` |
-| Where is the code that does X (no name known)? | `clast_search` with a short description of the behaviour |
-| Show me X, I am about to edit X | `clast_get_context` (that symbol's source, callers, callees) |
-| Who calls X, through how many levels? | `clast_call_graph` (`depth` 2-3, `within` to scope) |
+| What is in this repo / directory / file? | `clast_overview`, `clast_file_summary` |
+| Where is the code that does X (no name known)? | `clast_search` with a short description |
+| Show X before editing | `clast_get_context` |
+| Who calls X, N levels up? | `clast_call_graph` (`depth`, `within`) |
 | What implements / extends / overrides X? | `clast_hierarchy` |
-| What else must change with X, and which tests do I run? | `clast_impact` |
-| How many X? How big? Endpoints, database access, dependencies? | `clast_stats` (never tally search results by hand) |
-| What is unused? What did a refactor leave behind? | `clast_unused` |
-| What did my diff touch? | `clast_changes` |
-| Every use of an identifier, or a string / config key | `clast_references`, `clast_grep` |
-
-## Habits that save round trips
+| What changes with X, which tests run? | `clast_impact` |
+| How many X? Endpoints, database access, dependencies? | `clast_stats` |
+| What is unused? | `clast_unused` |
+| What did the diff touch? | `clast_changes` |
+| Every use of an identifier / a string or config key | `clast_references` / `clast_grep` |
 
-- One call, not a loop: `clast_search` and `clast_get_context` take arrays of names; `clast_call_graph`
-  and `clast_hierarchy` take a `depth`.
-- Address symbols precisely: `Class.method`, `path/file.ext:name`, `path/file.ext:123`. A bare name
-  with several definitions returns the candidates; pick one, do not guess.
-- Read the symbol, not the file: `clast_get_context` returns exactly the definition's lines.
-- An edge marked `?` was matched by name only (the receiver's type is unknown). Verify it with a quick
-  Grep or Read before you rely on it; unmarked edges are resolved through types and imports.
-- Callers of a method include calls through its interface or base class, not calls bound to an override
-  in a subclass. For every implementation's callers ask for the interface or base method.
-- Before a signature change: `clast_impact` lists the overrides and declarations that change with it,
-  the callers by file and line, and the tests that reach it even when none names it.
-- `clast_unused` lists candidates judged by name. Members with common names (`get`, `run`) are never
-  listed, and reflection or framework wiring can keep a listed symbol alive: confirm with the compiler
-  or the tests before deleting.
-- Narrow with `path` (and `within` for call graphs) on large repositories; results and run time shrink.
-- The index follows file changes, including your own edits. There is no need to reindex.
-- If a tool says a name is not defined in the project, it is external or built at run time:
-  `clast_references` and `clast_grep` still find its uses.
+Rules:
 
-Slash commands in this plugin: `/clast:deadcode [path]`, `/clast:impact <symbol>`, `/clast:audit [path]`,
-`/clast:status`.
+- Batch: `clast_search` and `clast_get_context` take arrays. Use `depth` instead of repeated calls.
+- Address symbols as `Class.method`, `path/file.ext:name` or `path/file.ext:123`. If candidates are listed, pick one.
+- `?` on an edge = name-only match. Verify it before use.
+- Callers of a method include calls through its interface or base type, not calls bound to a subclass override.
+- Rename or signature change of a distinctive name: no clast. Grep the name, then edit.
+- `clast_impact` before a change only if the name is common (`get`, `run`), overrides must change too, or tests must be chosen.
+- `clast_unused` results are candidates. Common member names are never listed. Confirm with the compiler or tests before deletion.
+- Narrow large repositories with `path` / `within`.
+- Never reindex. The index follows edits.
+- "Not defined in the project" = external or built at run time. `clast_references` and `clast_grep` still find uses.

package/skills/impact/SKILL.md

@@ -1,24 +1,18 @@
 ---
 name: impact
-description: Show what a change to one function, method or type affects - what must change with it, every caller, and the tests to run.
+description: Show what a change to one symbol affects - what changes with it, every caller, the tests to run.
 argument-hint: "<symbol>"
 disable-model-invocation: true
 allowed-tools: mcp__plugin_clast_clast__clast_impact, mcp__plugin_clast_clast__clast_search, mcp__plugin_clast_clast__clast_get_context, mcp__plugin_clast_clast__clast_call_graph, mcp__plugin_clast_clast__clast_hierarchy, Grep, Read
 ---
 
-Assess the impact of changing `$ARGUMENTS`.
+Symbol: `$ARGUMENTS`. If empty, ask. If ambiguous, pick the candidate the user means and address it as `Container.name` or `path/file.ext:name`.
 
-1. If no symbol was given, ask which one. If the name is ambiguous, `clast_impact` lists the
-   candidates: pick the one the user means (ask when it is not obvious) and address it as
-   `Container.name` or `path/file.ext:name`.
-2. Call `clast_impact` for the symbol (default depth 3).
-3. Report, in this order and without padding:
-   - **Changes together**: declarations, overrides, implementations and overloads of the same member.
-   - **Direct callers**: by file with line numbers. Callers marked `?` are name-only matches: check
-     each with a quick Read of the cited line and say whether it is a real caller.
-   - **Reach**: how many functions in how many files depend on it indirectly, by area.
-   - **Tests to run**: the test files, split into those that call it directly and those that reach it
-     through callers. Give the project's command to run exactly those tests if you can tell what it is.
-   - If no test reaches it, say so plainly: that is the main risk of the change.
-4. End with a one-line verdict on the size of the change (local, moderate, wide) and what to edit
-   first. Do not start editing unless the user asks.
+1. Call `clast_impact`.
+2. Report in this order:
+   - Changes together: declarations, overrides, implementations, overloads.
+   - Direct callers by file and line. Read each `?` caller and state if it is real.
+   - Reach: indirect callers, count by area.
+   - Tests to run: direct, then through callers. Give the command to run them if known.
+   - If no test reaches it, state that as the main risk.
+3. End with one line: size of the change (local, moderate, wide) and what to edit first. Do not edit unless asked.

package/skills/status/SKILL.md

@@ -1,11 +1,8 @@
 ---
 name: status
-description: Show the state of the clast index for this project - files, symbols, languages, whether it is up to date.
+description: Show the state of the clast index for this project.
 disable-model-invocation: true
 allowed-tools: mcp__plugin_clast_clast__clast_status, mcp__plugin_clast_clast__clast_reindex
 ---
 
-Call `clast_status` and report in a few lines: files and symbols indexed, languages, whether the index
-is up to date or still building, and where the database is. If the index is still building, say how
-far it is. If the status shows a problem (no files, a failed run), say so and offer to run
-`clast_reindex`; do not reindex unasked.
+Call `clast_status`. Report files, symbols, languages, up to date or building (with progress), database location. If it shows a problem, state it and offer `clast_reindex`. Do not reindex unasked.

package/src/cli.ts

@@ -4,7 +4,8 @@
 process.env.UV_THREADPOOL_SIZE ??= '16';
 
 import { readFileSync } from 'node:fs';
-import { resolve } from 'node:path';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { Clast } from './engine.js';
 import { SourceParser } from './parser/index.js';
 import { ToolContext } from './tools/context.js';
@@ -35,6 +36,7 @@ usage: clast-ai [command] [args] [--root <dir>]
   unused [path]              dead code   [--kind k] [--lang l] [--limit n] [--no-exported]
   stats [what] [name]        exact counts: inventory | symbols | subtypes | calls | text | imports | endpoints | database
                              [--kind k] [--on receiver] [--path p] [--lang l] [--group-by g] [--depth n] [--limit n] [--tests]
+  guide                      print the usage guide for agents (append it to AGENTS.md, GEMINI.md or a rules file)
   migrate [--apply]          find (and with --apply remove) what older installs left behind: duplicate
                              MCP registrations next to the plugin, the v0.1 index file
   parse <file> [--json]      debug: show what the extractor produces for a file
@@ -107,6 +109,15 @@ async function main(): Promise<void> {
     return;
   }
 
+  if (cmd === 'guide') {
+    // The usage guide the Claude Code plugin ships as a skill, as plain Markdown for agents that take
+    // their instructions from a file: `clast-ai guide >> AGENTS.md`.
+    const file = join(dirname(fileURLToPath(import.meta.url)), '..', 'skills', 'explore', 'SKILL.md');
+    const text = readFileSync(file, 'utf-8').replace(/\r\n/g, '\n');
+    const body = text.replace(/^---\n[\s\S]*?\n---\n+/, '').replace(/\nSlash commands in this plugin:[\s\S]*$/, '\n');
+    return void console.log(body.trimEnd());
+  }
+
   if (cmd === 'migrate') {
     const { migrate } = await import('./migrate.js');
     const out = await migrate({ apply: flags.has('apply'), auto: flags.has('auto'), force: flags.has('force'), cwd: str('root') });

package/src/indexer/scan.ts

@@ -5,6 +5,9 @@ import { extname, join } from 'node:path';
 import type { ClastConfig } from '../config/index.js';
 import { supportedExtensions } from '../parser/registry.js';
 
+/** A project has thousands of directories; a home, temp or system directory has hundreds of thousands. */
+const MAX_DIRS = 150_000;
+
 // `ignore` is CJS; under NodeNext the default import may be the module object.
 const createIgnore: () => Ignore =
   (ignoreFactory as unknown as { default?: () => Ignore }).default ?? (ignoreFactory as unknown as () => Ignore);
@@ -119,8 +122,12 @@ export class IgnoreRules {
 
   /** Files skipped by the last scan because they exceed maxFileSize. */
   skippedLarge = 0;
-  /** True when the last scan stopped at the maxFiles cap. */
+  /** True when the last scan stopped at the maxFiles cap or the directory cap. */
   truncated = false;
+  /** True when the last scan stopped because the tree has more directories than a project plausibly has. */
+  tooBroad = false;
+  private dirsWalked = 0;
+  private sliceStart = 0;
   private readonly maxFiles: number;
 
   /**
@@ -166,8 +173,11 @@ export class IgnoreRules {
     const candidates: string[] = [];
     this.skippedLarge = 0;
     this.truncated = false;
+    this.tooBroad = false;
+    this.dirsWalked = 0;
+    this.sliceStart = performance.now();
     const rules: Rule[] = [this.rootRule];
-    this.walk('', rules, candidates, 0);
+    await this.walk('', rules, candidates, 0);
 
     // stat() dominates a warm start (especially on Windows); run it on the
     // libuv thread pool instead of serially on the main thread.
@@ -191,12 +201,26 @@ export class IgnoreRules {
     return out.filter(Boolean);
   }
 
-  private walk(dirRel: string, parentRules: Rule[], out: string[], depth: number): void {
-    if (depth > 40) return;
+  /**
+   * Reads directories synchronously (fastest for a normal project) but hands the event loop back every
+   * few milliseconds: the walk starts right after the server connects, and a client that gets no answer
+   * to its first request gives up. A tree far larger than a project (a home or temp directory) is cut off.
+   */
+  private async walk(dirRel: string, parentRules: Rule[], out: string[], depth: number): Promise<void> {
+    if (depth > 40 || this.truncated) return;
     if (out.length >= this.maxFiles) {
       this.truncated = true;
       return;
     }
+    if (++this.dirsWalked > MAX_DIRS) {
+      this.truncated = true;
+      this.tooBroad = true;
+      return;
+    }
+    if (performance.now() - this.sliceStart > 15) {
+      await new Promise<void>(done => setImmediate(done));
+      this.sliceStart = performance.now();
+    }
     const rule = this.ruleFor(dirRel);
     const rules = rule ? [...parentRules, rule] : parentRules;
 
@@ -213,7 +237,7 @@ export class IgnoreRules {
         if (name.startsWith('.')) continue;
         const rel = dirRel + name;
         if (IgnoreRules.test(rules, rel, true)) continue;
-        this.walk(rel + '/', rules, out, depth + 1);
+        await this.walk(rel + '/', rules, out, depth + 1);
       } else if (e.isFile()) {
         if (!this.extensions.has(extname(name).toLowerCase())) continue;
         const rel = dirRel + name;

package/src/server/index.ts

@@ -28,7 +28,8 @@ const INSTRUCTIONS = `Clast is a pre-built, always-fresh code index for this rep
 - How many X, how big, what is it made of -> clast_stats (exact totals; do not count search results by hand).
 - Strings, comments, config keys -> clast_grep. After a change -> clast_changes (touched symbols, affected callers, tests).
 
-When implementing a change: find the sibling implementations with clast_hierarchy or clast_search, read one with clast_get_context, and list every caller or switch you must update with clast_call_graph / clast_references before editing.
+When adding something new (a subclass, a handler, a provider): find the siblings with clast_hierarchy or clast_search and read one with clast_get_context.
+When renaming a symbol or changing a signature: if the name is distinctive, do NOT use clast - one Grep for the name lists every site, then edit. Use clast_impact first only when the name is common (get, run, close) so that Grep would drown in unrelated hits, when overrides or interface implementations must change with it, or to choose the tests to run.
 Most tools take several names at once (arrays). Symbols: name, Container.name, or path/to/file.ext:name. "?" marks a name-based guess. The index follows file changes, including your own edits.`;
 
 const text = (t: string) => ({ content: [{ type: 'text' as const, text: t }] });

package/src/tools/explore.ts

@@ -829,7 +829,12 @@ export async function status(ctx: ToolContext, watcher?: { isActive: boolean; pe
   if (ctx.indexer.rules.skippedLarge) {
     out.push(`skipped: ${plural(ctx.indexer.rules.skippedLarge, 'file')} larger than ${ctx.clast.config.maxFileSize} bytes (maxFileSize)`);
   }
-  if (ctx.indexer.rules.truncated) {
+  if (ctx.indexer.rules.tooBroad) {
+    out.push(
+      `warning: ${ctx.clast.root} has more directories than a project (the scan stopped). ` +
+        `Start the agent inside a project, or set CLAST_PROJECT_DIR to one.`
+    );
+  } else if (ctx.indexer.rules.truncated) {
     out.push(
       `warning: stopped at ${ctx.clast.config.maxFiles} source files (maxFiles). Is the project root too broad? ` +
         `Set CLAST_PROJECT_DIR or raise maxFiles in clast.config.json.`

package/src/version.ts

@@ -1,2 +1,2 @@
 /** Package version (keep in sync with package.json; checked by a test). */
-export const VERSION = '0.2.2';
+export const VERSION = '0.2.4';