@wrongstack/tools 0.306.3 → 0.307.0

package/dist/clarify.d.ts

@@ -0,0 +1,32 @@
+/**
+ * `clarify` tool — Proactive Ambiguity Clarifier & Intent Alignment.
+ *
+ * Prompts the user with structured, multiple-choice questions when architectural,
+ * database schema, API contract, or domain logic assumptions are underspecified.
+ * Prevents silent misaligned migrations, breaking changes, and refactoring re-work.
+ */
+import type { Tool } from '@wrongstack/core/types';
+export interface ClarifyQuestionInput {
+    /** The core decision or question to clarify with the user. */
+    question: string;
+    /** Context or explanation of why this decision matters (e.g. index performance, validation). */
+    context?: string | undefined;
+    /** 2 to 4 structured, distinct choices for the user to select. */
+    options: string[];
+    /** The option recommended by the assistant based on best practices. */
+    recommendedOption?: string | undefined;
+    /** Whether the user can select multiple options simultaneously. */
+    isMultiSelect?: boolean | undefined;
+    /** Allow write-in custom responses in addition to options (default: true). */
+    allowCustomResponse?: boolean | undefined;
+}
+export interface ClarifyOutput {
+    status: 'answered' | 'auto_decided' | 'skipped';
+    question: string;
+    selectedOptions: string[];
+    customResponse?: string | undefined;
+    decisionSummary: string;
+    error?: string | undefined;
+}
+export declare const clarifyTool: Tool<ClarifyQuestionInput, ClarifyOutput>;
+//# sourceMappingURL=clarify.d.ts.map

package/dist/codebase-index/ast-invariant-engine.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Polyglot AST Invariant Engine
+ *
+ * Deterministic backward-compatibility & invariant validator that checks AST
+ * diffs between original code and LLM mutations before changes are written to disk.
+ *
+ * Catches breaking changes across TypeScript/JavaScript, Python, Go, Rust, Java, etc.:
+ *   - INV-001: Export / Public Symbol Deletion or Rename
+ *   - INV-002: Mandatory / Non-Default Parameter Addition
+ *   - INV-003: Mandatory Interface / Trait / Model Property Addition
+ *   - INV-004: Incompatible Return Type Alteration
+ */
+import type { SymbolLang } from './schema.js';
+export type InvariantRuleId = 'INV-001' | 'INV-002' | 'INV-003' | 'INV-004';
+export interface InvariantViolation {
+    ruleId: InvariantRuleId;
+    symbolName: string;
+    lang: SymbolLang;
+    message: string;
+    severity: 'CRITICAL' | 'WARNING';
+    details?: {
+        addedParameter?: string | undefined;
+        addedProperty?: string | undefined;
+        expectedModifier?: string | undefined;
+        originalSignature?: string | undefined;
+        modifiedSignature?: string | undefined;
+    } | undefined;
+}
+export interface InvariantEvaluationResult {
+    valid: boolean;
+    violations: InvariantViolation[];
+    stats: {
+        originalSymbols: number;
+        modifiedSymbols: number;
+        durationMs: number;
+    };
+}
+export interface ParameterContract {
+    name: string;
+    isOptional: boolean;
+    hasDefault: boolean;
+    isRest: boolean;
+    type?: string | undefined;
+}
+export interface FunctionContract {
+    name: string;
+    isExported: boolean;
+    params: ParameterContract[];
+    returnType?: string | undefined;
+}
+export interface InterfacePropertyContract {
+    name: string;
+    isOptional: boolean;
+    hasDefault?: boolean | undefined;
+    type?: string | undefined;
+}
+export interface InterfaceContract {
+    name: string;
+    isExported: boolean;
+    properties: InterfacePropertyContract[];
+    methods: Array<{
+        name: string;
+        isOptional: boolean;
+        params: ParameterContract[];
+        returnType?: string | undefined;
+    }>;
+}
+export interface ModuleContract {
+    lang: SymbolLang;
+    exports: Set<string>;
+    functions: Map<string, FunctionContract>;
+    interfaces: Map<string, InterfaceContract>;
+}
+/**
+ * Universal AST Invariant Engine for deterministic backward compatibility validation.
+ */
+export declare class PolyglotInvariantEngine {
+    /**
+     * Evaluate whether a code mutation respects backward compatibility invariants.
+     */
+    evaluate(opts: {
+        originalCode: string;
+        modifiedCode: string;
+        lang?: SymbolLang | undefined;
+        filePath?: string | undefined;
+    }): Promise<InvariantEvaluationResult>;
+    /**
+     * Extract high-level contract signatures from source code.
+     */
+    extractContract(code: string, lang: SymbolLang): Promise<ModuleContract>;
+    /**
+     * TypeScript & JavaScript extraction via TS Compiler API.
+     */
+    private extractTsContract;
+    /**
+     * Polyglot extraction (Python, Go, Rust, Java, etc.) via Tree-sitter WASM.
+     */
+    private extractTreeSitterContract;
+}
+/** Singleton instance ready for use across WrongStack */
+export declare const polyglotInvariantEngine: PolyglotInvariantEngine;
+//# sourceMappingURL=ast-invariant-engine.d.ts.map

package/dist/codebase-index/ast-symbol-mutator.d.ts

@@ -0,0 +1,28 @@
+import { type InvariantViolation } from './ast-invariant-engine.js';
+export interface MutateSymbolOptions {
+    file: string;
+    symbol: string;
+    newBody: string;
+    target?: 'body' | 'full' | undefined;
+    checkInvariants?: boolean | undefined;
+    allowBreakingChanges?: boolean | undefined;
+}
+export interface MutateSymbolResult {
+    file: string;
+    symbol: string;
+    originalRange: {
+        startLine: number;
+        endLine: number;
+    };
+    newRange: {
+        startLine: number;
+        endLine: number;
+    };
+    updatedContent: string;
+    violations?: InvariantViolation[] | undefined;
+}
+/**
+ * Surgically replace a symbol's body or definition inside a source file.
+ */
+export declare function replaceSymbolInFile(opts: MutateSymbolOptions, projectRoot: string): Promise<MutateSymbolResult>;
+//# sourceMappingURL=ast-symbol-mutator.d.ts.map

package/dist/codebase-index/background-indexer.d.ts

@@ -85,6 +85,14 @@ export declare function enqueueReindex(opts: {
     files: string[];
     indexDir?: string | undefined;
     debounceMs?: number | undefined;
+    /**
+     * Per-project trailing coalescing window. After a file's debounce timer
+     * fires, the ready batch stays open for this long before flushing. Any file
+     * whose timer fires within the window joins the same batch and resets the
+     * timer (sliding). Default: 50ms. Set to 0 to flush immediately after each
+     * debounce timer fires (legacy behavior — staggered bursts don't coalesce).
+     */
+    coalesceWindowMs?: number | undefined;
     /** Watchdog timeout per file. Default: 30s. */
     timeoutMs?: number | undefined;
     onError?: ((err: unknown) => void) | undefined;
@@ -133,6 +141,7 @@ export declare function ensureCodebaseIndexServer(options: {
     indexDir?: string | undefined;
     watchExternal?: boolean | undefined;
     debounceMs?: number | undefined;
+    coalesceWindowMs?: number | undefined;
 }): Promise<void>;
 /**
  * Reset all process-global indexing state for test isolation.

package/dist/codebase-index/codebase-ast-replace-tool.d.ts

@@ -0,0 +1,31 @@
+/**
+ * `codebase-ast-replace` tool — surgically replace a function, method, or class body via AST.
+ *
+ * Usage: codebase-ast-replace({
+ *   file: string,             // relative or absolute file path
+ *   symbol: string,           // name of the function, method, or declaration to mutate
+ *   newBody: string,          // new implementation code
+ *   target?: 'body' | 'full', // whether to replace only the body (default) or the full declaration
+ * })
+ */
+import type { Tool } from '@wrongstack/core/types';
+import { type MutateSymbolOptions } from './ast-symbol-mutator.js';
+export interface CodebaseAstReplaceInput extends MutateSymbolOptions {
+}
+export interface CodebaseAstReplaceOutput {
+    status: 'ok' | 'error';
+    file: string;
+    symbol: string;
+    originalRange?: {
+        startLine: number;
+        endLine: number;
+    } | undefined;
+    newRange?: {
+        startLine: number;
+        endLine: number;
+    } | undefined;
+    violations?: string[] | undefined;
+    error?: string | undefined;
+}
+export declare const codebaseAstReplaceTool: Tool<CodebaseAstReplaceInput, CodebaseAstReplaceOutput>;
+//# sourceMappingURL=codebase-ast-replace-tool.d.ts.map

package/dist/codebase-index/codebase-impact-analysis-tool.d.ts

@@ -0,0 +1,40 @@
+/**
+ * `codebase-impact-analysis` tool — calculate the blast radius and breaking change risk of modifying a symbol.
+ *
+ * Usage: codebase-impact-analysis({
+ *   symbol: string,           // name of the function, method, class, or type to analyze
+ *   file?: string,            // optional file path to disambiguate
+ *   transitive?: boolean,     // traverse transitive callers (default: true)
+ * })
+ */
+import type { Tool } from '@wrongstack/core/types';
+export interface ImpactAnalysisInput {
+    /** The symbol name (function, method, class, interface, type) to analyze. */
+    symbol: string;
+    /** Optional file path to disambiguate when multiple symbols share a name. */
+    file?: string | undefined;
+    /** Whether to traverse transitive callers (callers of callers). Defaults to true. */
+    transitive?: boolean | undefined;
+}
+export interface ImpactCallSite {
+    file: string;
+    line: number;
+    callerName: string;
+    callerKind: string;
+    callType: string;
+    isTest: boolean;
+}
+export interface ImpactAnalysisOutput {
+    status: 'ok' | 'error';
+    symbol: string;
+    riskLevel: 'low' | 'medium' | 'high';
+    summary: string;
+    totalCallSites: number;
+    affectedProductionFiles: string[];
+    affectedTestFiles: string[];
+    callSites: ImpactCallSite[];
+    recommendedActionPlan: string[];
+    error?: string | undefined;
+}
+export declare const codebaseImpactAnalysisTool: Tool<ImpactAnalysisInput, ImpactAnalysisOutput>;
+//# sourceMappingURL=codebase-impact-analysis-tool.d.ts.map

package/dist/codebase-index/codebase-invariant-check-tool.d.ts

@@ -0,0 +1,23 @@
+/**
+ * `codebase-invariant-check` tool — deterministic backward-compatibility & invariant audit.
+ *
+ * Allows agents, auditors, and workflows to pre-screen candidate code modifications
+ * or compare file versions to identify breaking changes across TypeScript, Python, Go, Rust, etc.
+ */
+import type { Tool } from '@wrongstack/core/types';
+import { type InvariantViolation } from './ast-invariant-engine.js';
+import type { SymbolLang } from './schema.js';
+export interface CodebaseInvariantCheckInput {
+    file?: string | undefined;
+    originalCode?: string | undefined;
+    modifiedCode: string;
+    lang?: SymbolLang | undefined;
+}
+export interface CodebaseInvariantCheckOutput {
+    valid: boolean;
+    violations: InvariantViolation[];
+    summary: string;
+    error?: string | undefined;
+}
+export declare const codebaseInvariantCheckTool: Tool<CodebaseInvariantCheckInput, CodebaseInvariantCheckOutput>;
+//# sourceMappingURL=codebase-invariant-check-tool.d.ts.map

package/dist/codebase-index/codebase-repo-map-tool.d.ts

@@ -0,0 +1,22 @@
+/**
+ * `codebase-repo-map` tool — generate a reference-weighted, token-budgeted Repository Map.
+ *
+ * Usage: codebase-repo-map({
+ *   maxTokens?: number,       // maximum token budget for the map (default: 1200)
+ *   focusFiles?: string[],    // list of paths to prioritize/boost in the ranking
+ * })
+ */
+import type { Tool } from '@wrongstack/core/types';
+import { type RepoMapResult } from './repo-map.js';
+export interface CodebaseRepoMapInput {
+    /** Maximum token budget (approximate) for the generated map. Defaults to 1200. */
+    maxTokens?: number | undefined;
+    /** Optional file paths to prioritize and boost in the map generation. */
+    focusFiles?: string[] | undefined;
+}
+export interface CodebaseRepoMapOutput extends RepoMapResult {
+    status: 'ok' | 'error';
+    error?: string | undefined;
+}
+export declare const codebaseRepoMapTool: Tool<CodebaseRepoMapInput, CodebaseRepoMapOutput>;
+//# sourceMappingURL=codebase-repo-map-tool.d.ts.map

package/dist/codebase-index/codebase-skeleton-tool.d.ts

@@ -0,0 +1,36 @@
+/**
+ * `codebase-skeleton` tool — extract AST-based file skeletons with body redaction.
+ *
+ * Usage: codebase-skeleton({
+ *   path: string,             // relative or absolute file or directory path
+ *   includeDocs?: boolean,    // preserve JSDoc / docstrings (default: true)
+ *   collapseImports?: boolean,// collapse import headers (default: false)
+ *   exportsOnly?: boolean,    // filter to exported declarations (default: false)
+ *   maxFiles?: number,        // max files to scan when path is a directory (default: 20)
+ * })
+ *
+ * Returns: { path, isDir, skeleton, stats: { originalLines, skeletonLines, tokenSavingsPercent, symbolCount } }
+ */
+import type { Tool } from '@wrongstack/core/types';
+import { type FileSkeletonResult, type SkeletonOptions } from './skeleton-extractor.js';
+export interface CodebaseSkeletonInput extends SkeletonOptions {
+    /** Relative or absolute file or directory path. */
+    path: string;
+    /** Maximum number of files to process if `path` is a directory. Defaults to 20. */
+    maxFiles?: number;
+}
+export interface CodebaseSkeletonOutput {
+    path: string;
+    isDir: boolean;
+    skeleton: string;
+    stats: {
+        originalLines: number;
+        skeletonLines: number;
+        tokenSavingsPercent: number;
+        symbolCount: number;
+        fileCount?: number;
+    };
+    files?: FileSkeletonResult[];
+}
+export declare const codebaseSkeletonTool: Tool<CodebaseSkeletonInput, CodebaseSkeletonOutput>;
+//# sourceMappingURL=codebase-skeleton-tool.d.ts.map

package/dist/codebase-index/codebase-targeted-test-tool.d.ts

@@ -0,0 +1,30 @@
+/**
+ * `codebase-targeted-test` tool — automatically identify and run only the relevant tests for a modified symbol or file.
+ *
+ * Usage: codebase-targeted-test({
+ *   symbol?: string,          // function/class/type name that was changed
+ *   file?: string,            // source file that was changed
+ *   testFiles?: string[],     // explicitly specified test files (optional)
+ * })
+ */
+import type { Tool } from '@wrongstack/core/types';
+export interface TargetedTestInput {
+    /** Symbol name (function, class, method) whose tests should be discovered and run. */
+    symbol?: string | undefined;
+    /** Source file path whose corresponding test suite should be run. */
+    file?: string | undefined;
+    /** Optional explicit list of test files to run. */
+    testFiles?: string[] | undefined;
+}
+export interface TargetedTestOutput {
+    status: 'passed' | 'failed' | 'no_tests_found' | 'error';
+    discoveredSuites: string[];
+    testsRun: number;
+    passed: number;
+    failed: number;
+    durationMs: number;
+    output: string;
+    error?: string | undefined;
+}
+export declare const codebaseTargetedTestTool: Tool<TargetedTestInput, TargetedTestOutput>;
+//# sourceMappingURL=codebase-targeted-test-tool.d.ts.map

package/dist/codebase-index/index.d.ts

@@ -18,11 +18,20 @@ export { cancelPendingReindexes, checkCodebaseIndexServerHealth, codebaseIndexSt
 export { buildBm25Index, buildIndexableText, tokenise, } from './bm25.js';
 export type { CircuitSnapshot, CircuitState } from './circuit-breaker.js';
 export { CircuitOpenError, IndexCircuitBreaker, IndexTimeoutError, indexCircuitBreaker, resetIndexCircuitBreaker, } from './circuit-breaker.js';
-export { codebaseIndexTool } from './codebase-index-tool.js';
+export { codebaseAstReplaceTool } from './codebase-ast-replace-tool.js';
+export { codebaseInvariantCheckTool } from './codebase-invariant-check-tool.js';
+export { replaceSymbolInFile, type MutateSymbolOptions, type MutateSymbolResult, } from './ast-symbol-mutator.js';
+export { codebaseImpactAnalysisTool } from './codebase-impact-analysis-tool.js';
 export { codebaseIncomingCallsTool } from './codebase-incoming-calls-tool.js';
+export { codebaseIndexTool } from './codebase-index-tool.js';
 export { codebaseOutgoingCallsTool } from './codebase-outgoing-calls-tool.js';
+export { codebaseRepoMapTool } from './codebase-repo-map-tool.js';
 export { codebaseSearchTool } from './codebase-search-tool.js';
+export { codebaseSkeletonTool } from './codebase-skeleton-tool.js';
 export { codebaseStatsTool } from './codebase-stats-tool.js';
+export { codebaseTargetedTestTool } from './codebase-targeted-test-tool.js';
+export { generateRepoMap, type RepoMapOptions, type RepoMapResult, } from './repo-map.js';
+export { extractDirectorySkeleton, extractFileSkeleton, type FileSkeletonResult, type SkeletonOptions, type SkeletonSymbolRange, } from './skeleton-extractor.js';
 export { deadCodeScanTool, runDeadCodeScan } from './dead-code-scan.js';
 export type { DeadCodeScanInput, DeadCodeScanOutput, DeadFile, DeadPackage, DeadSymbol, } from './dead-code-scan.js';
 export { runIndexer } from './indexer.js';
@@ -34,4 +43,5 @@ export type { CallSite, CodeMapGraph, FileMeta, FileSymbols, GraphEdge, GraphNod
 export { projectIndexServerEndpoint, projectIndexServerMetadataPath, } from './project-server-endpoint.js';
 export { SCHEMA_VERSION } from './schema.js';
 export { codebaseIndexDirOverride, IndexStore, resolveIndexDir } from './writer.js';
+export { PolyglotInvariantEngine, polyglotInvariantEngine, type InvariantEvaluationResult, type InvariantRuleId, type InvariantViolation, type ModuleContract, } from './ast-invariant-engine.js';
 //# sourceMappingURL=index.d.ts.map