@octocodeai/octocode-engine 16.5.0 → 16.6.0

package/index.d.ts

@@ -1,4 +1,4 @@
-/* auto-generated by NAPI-RS */
+/* Public types for @octocodeai/octocode-engine */
 /* eslint-disable */
 export declare class NativeLspClient {
   constructor(config: JsLanguageServerConfig)
@@ -6,20 +6,10 @@ export declare class NativeLspClient {
   stop(): Promise<void>
   waitForReady(timeoutMs?: number | undefined | null): Promise<void>
   hasCapability(capability: string): boolean
+  /** Server-selected LSP `positionEncoding` (utf-16 unless the server is non-conformant); null if omitted/not started. */
+  positionEncoding(): string | null
   getRecentStderr(): Array<string>
-  /**
-   * Sync a document's in-memory content to the server, honoring the LSP
-   * document lifecycle: the FIRST sync of a URI sends `textDocument/didOpen`
-   * (version 1); every subsequent sync sends `textDocument/didChange` with an
-   * incremented version and a full-document content change. Re-sending
-   * `didOpen` (as before) is ignored or rejected by many servers and can make
-   * changed content resolve against the stale original.
-   */
   openDocument(filePath: string, content: string): Promise<void>
-  /**
-   * Close a previously opened document (`textDocument/didClose`) and forget
-   * its version, so a later `open_document` starts a fresh `didOpen`.
-   */
   closeDocument(filePath: string): Promise<void>
   getDefinition(filePath: string, line: number, character: number): Promise<Array<JsCodeSnippet>>
   getReferences(filePath: string, line: number, character: number, includeDeclaration?: boolean | undefined | null): Promise<Array<JsCodeSnippet>>
@@ -30,6 +20,16 @@ export declare class NativeLspClient {
   prepareCallHierarchy(filePath: string, line: number, character: number): Promise<any>
   incomingCalls(item: any): Promise<any>
   outgoingCalls(item: any): Promise<any>
+  /** Project-wide fuzzy symbol search — `workspace/symbol`. Returns `WorkspaceSymbol[] | SymbolInformation[]`. */
+  workspaceSymbol(query: string): Promise<any>
+  /** Prepare a type-hierarchy item at a position — `textDocument/prepareTypeHierarchy`. */
+  prepareTypeHierarchy(filePath: string, line: number, character: number): Promise<any>
+  /** Supertypes (base classes / implemented interfaces) — `typeHierarchy/supertypes`. */
+  typeHierarchySupertypes(item: any): Promise<any>
+  /** Subtypes (subclasses / implementors) — `typeHierarchy/subtypes`. */
+  typeHierarchySubtypes(item: any): Promise<any>
+  /** Pull diagnostics for a single file — `textDocument/diagnostic` (LSP 3.17+). */
+  getDiagnostics(filePath: string): Promise<any>
 }
 
 /**
@@ -108,6 +108,30 @@ export interface BinaryStrings {
   nextScanOffset?: number
 }
 
+/**
+ * Native strings extraction. Recovers printable ASCII **and** UTF-16 (LE/BE)
+ * runs of at least `min_length` from the scan window of `path` beginning at
+ * `scan_offset`, longest-first, optionally hex offset-prefixed. Replaces the
+ * `strings` shell-out and additionally surfaces the wide strings GNU
+ * `strings -a` misses.
+ *
+ * Lossless pagination: the returned `nextScanOffset` (when set) is the absolute
+ * byte offset of the next window, rewound to a safe break so no string is split
+ * across windows. Pass `scanOffset = 0` for the first window.
+ */
+export declare function extractBinaryStringsNative(path: string, minLength: number, includeOffsets: boolean, scanOffset: number): BinaryStrings
+
+/**
+ * Native binary inspection (format lane). Parses `path` as an executable /
+ * object / archive and returns its identity plus — for recognized executable
+ * formats — symbols, imports, exports, sections and dynamic dependencies.
+ *
+ * Replaces the `file` + `xxd` shell-outs. Never throws on malformed input: a
+ * parse failure degrades to magic-byte identity with an explanatory note. The
+ * only `Err` cases are unreadable / oversized files.
+ */
+export declare function inspectBinaryNative(path: string): BinaryInspectInfo
+
 /** Extract a byte-range substring from `content`. */
 export declare function byteSliceContent(content: string, byteStart: number, byteEnd: number): string
 
@@ -129,34 +153,6 @@ export declare function convertSymbolKind(kind?: number | undefined | null): str
 /** Return the LSP language identifier for the file at `file_path`. */
 export declare function detectLanguageId(filePath: string): string | null
 
-/**
- * Native strings extraction. Recovers printable ASCII **and** UTF-16 (LE/BE)
- * runs of at least `min_length` from the scan window of `path` beginning at
- * `scan_offset`, longest-first, optionally hex offset-prefixed. Replaces the
- * `strings` shell-out and additionally surfaces the wide strings GNU
- * `strings -a` misses.
- *
- * Lossless pagination: the returned `nextScanOffset` (when set) is the absolute
- * byte offset of the next window, rewound to a safe break so no string is split
- * across windows. Pass `scanOffset = 0` for the first window.
- */
-export declare function extractBinaryStringsNative(path: string, minLength: number, includeOffsets: boolean, scanOffset: number): BinaryStrings
-
-/**
- * Native JS/TS document symbols (server-free) as a JSON `DocumentSymbol[]`.
- *
- * Parses ECMAScript/TypeScript *syntax* with `oxc_parser` and walks
- * declarations into the LSP `DocumentSymbol` shape (nested, numeric
- * `SymbolKind`, 0-based UTF-16 ranges). **No type inference** — in-file
- * scope/binding accuracy only; type-aware outlines still require a language
- * server. Only `ts/tsx/js/jsx/mjs/cjs/mts/cts` are handled.
- *
- * Returns `null` for non-JS/TS files, oversized content, a hard parse failure
- * (caller should fall back to `extractSignatures`/tree-sitter), or a file with
- * no extractable top-level symbols.
- */
-export declare function extractJsSymbols(content: string, filePath: string): string | null
-
 /**
  * Search `content` line-by-line for `pattern` (literal or regex), returning
  * matched lines with context windows and omission markers.
@@ -189,12 +185,146 @@ export interface ExtractMatchingLinesResult {
 
 /**
  * Structural skeleton with an `NNN| ` line-number gutter, produced purely by
- * tree-sitter parsing (no regex heuristics). Returns `null` for data/config
- * formats, any language without a wired grammar, content above the 1MB guard,
- * and any skeleton that would not be smaller than the source.
+ * tree-sitter parsing. Returns `null` for data/config formats, any language
+ * without a wired grammar, content above the 1MB guard, and any skeleton that
+ * would not be smaller than the source.
  */
 export declare function extractSignatures(content: string, filePath: string): string | null
 
+/**
+ * Native JS/TS document symbols (server-free) as a JSON `DocumentSymbol[]`.
+ *
+ * Parses ECMAScript/TypeScript *syntax* with oxc and walks declarations into
+ * the LSP `DocumentSymbol` shape (nested, numeric `SymbolKind`, 0-based UTF-16
+ * ranges). **No type inference** — in-file scope/binding accuracy only; type-aware
+ * outlines still require a language server. Only `ts/tsx/js/jsx/mjs/cjs/mts/cts`
+ * are handled.
+ *
+ * Returns `null` for non-JS/TS files, oversized content, a hard parse failure
+ * (caller should fall back to `extractSignatures`), or a file with no
+ * extractable top-level symbols.
+ */
+export declare function extractJsSymbols(content: string, filePath: string): string | null
+
+/**
+ * Native in-file references (server-free) for the JS/TS symbol under
+ * `(line, character)` (0-based, UTF-16), as a JSON `Range[]` covering the
+ * declaration and every resolved in-file reference (declaration first).
+ *
+ * **Same-file only** — oxc resolves bindings within one module; cross-file
+ * references require a language server. No type inference. Returns `null` for
+ * non-JS/TS files, oversized content, a parse failure, or when the cursor is
+ * not on a resolvable binding/reference.
+ */
+export declare function findInFileReferences(content: string, filePath: string, line: number, character: number): string | null
+
+export interface GraphFactPosition {
+  line: number
+  character: number
+}
+
+export interface GraphFactRange {
+  start: GraphFactPosition
+  end: GraphFactPosition
+}
+
+export interface GraphFactDeclaration {
+  id: string
+  name: string
+  kind: string
+  line: number
+  range: GraphFactRange
+  selectionRange: GraphFactRange
+  exported: boolean
+  parent?: string
+}
+
+export interface GraphFactImport {
+  id: string
+  specifier: string
+  line: number
+  importKind: string
+  localName?: string
+  importedName?: string
+}
+
+export interface GraphFactExport {
+  id: string
+  name: string
+  line: number
+  exportKind: string
+  localName?: string
+  source?: string
+}
+
+export interface GraphFactCall {
+  id: string
+  caller: string
+  callee: string
+  line: number
+  range: GraphFactRange
+  kind: string
+}
+
+export interface GraphFactEdge {
+  id: string
+  from: string
+  to: string
+  relation: string
+  source: string
+  line: number
+}
+
+export interface GraphFacts {
+  kind: 'graphFacts'
+  source: 'native-ast'
+  language: string
+  file: string
+  declarations: Array<GraphFactDeclaration>
+  imports: Array<GraphFactImport>
+  exports: Array<GraphFactExport>
+  calls: Array<GraphFactCall>
+  edges: Array<GraphFactEdge>
+  diagnostics: Array<string>
+}
+
+export interface GraphFactCapability {
+  extension: string
+  language: string
+  languageId?: string
+  structuralSearch: boolean
+  signatureOutline: boolean
+  graphFacts: boolean
+  factFamilies: Array<string>
+}
+
+/**
+ * Native graph facts as a JSON `GraphFacts` object, or null when no graph-fact
+ * extractor supports the file. JS/TS use the richer OXC lane; other supported
+ * source languages use tree-sitter syntax inventory. Cross-file semantic
+ * identity still needs LSP proof.
+ */
+export declare function extractGraphFacts(content: string, filePath: string): string | null
+
+/**
+ * Canonical list of file extensions (lowercase, no leading dot) handled by the
+ * native oxc JS/TS path (`extractJsSymbols` / `findInFileReferences`). Gate
+ * native dispatch on this list instead of hardcoding it.
+ */
+export declare function getSupportedJsTsExtensions(): Array<string>
+
+/**
+ * Canonical list of file extensions (lowercase, no leading dot) that can emit
+ * native graph facts. JS/TS use OXC; other entries use tree-sitter syntax
+ * inventory.
+ */
+export declare function getSupportedGraphFactExtensions(): Array<string>
+
+/**
+ * JSON `GraphFactCapability[]` describing graph-fact coverage by extension.
+ */
+export declare function getGraphFactCapabilities(): string
+
 export interface FileSystemEntry {
   /** Absolute or input-root-relative path as returned by the platform. */
   path: string
@@ -226,6 +356,8 @@ export interface FileSystemQueryOptions {
   showHidden?: boolean
   /** Match basename globs, OR-combined. */
   names?: Array<string>
+  /** Match file extensions, OR-combined. Values may include a leading dot. Directories are preserved. */
+  extensions?: Array<string>
   /** Match full path glob. */
   pathPattern?: string
   /** Rust regex against basename. */
@@ -263,10 +395,30 @@ export interface FileSystemQueryResult {
   warnings: Array<string>
 }
 
+export type CommentPatternGroup =
+  | 'c-style'
+  | 'hash'
+  | 'html'
+  | 'sql'
+  | 'lua'
+  | 'haskell'
+  | 'semicolon'
+  | 'wasm-text'
+  | 'percent'
+  | 'haml'
+  | 'slim'
+  | 'powershell'
+  | 'bang'
+  | 'apostrophe'
+  | 'double-dash'
+  | 'fsharp-block'
+  | 'pascal'
+  | 'template'
+  | 'python-docstring'
+
 export interface FileTypeMinifyConfig {
   strategy: string
-  /** CommentPatternGroup | CommentPatternGroup[] */
-  comments?: any
+  comments?: CommentPatternGroup | CommentPatternGroup[] | null
 }
 
 /**
@@ -290,18 +442,6 @@ export interface FilterPatchOptions {
   contextLines?: number
 }
 
-/**
- * Native in-file references (server-free) for the JS/TS symbol under
- * `(line, character)` (0-based, UTF-16), as a JSON `Range[]` covering the
- * declaration and every resolved in-file reference (declaration first).
- *
- * **Same-file only.** oxc resolves bindings within one module; cross-file
- * references require a language server. No type inference. Returns `null` for
- * non-JS/TS files, oversized content, a parse failure, or when the cursor is
- * not on a resolvable binding/reference.
- */
-export declare function findInFileReferences(content: string, filePath: string, line: number, character: number): string | null
-
 /** Convert a `file://` URI string back to an absolute filesystem path. */
 export declare function fromUri(uri: string): string
 
@@ -326,17 +466,26 @@ export declare function getLanguageServerForFile(filePath: string, workspaceRoot
  * Returns the full MINIFY_CONFIG as a JS-compatible object.
  * Shape: `{ fileTypes: Record<string, { strategy: string, comments: string | string[] | null }> }`
  */
-export declare function getMINIFY_CONFIG(): any
+export declare function getMINIFY_CONFIG(): MinifyConfigSnapshot
+
+export interface MinifyConfigSnapshot {
+  fileTypes: Record<string, { strategy: string; comments: CommentPatternGroup | CommentPatternGroup[] | null }>
+}
+
+export declare const MINIFY_CONFIG: MinifyConfigSnapshot
+export declare const SUPPORTED_SIGNATURE_EXTENSIONS: readonly string[]
+export declare const SUPPORTED_GRAPH_FACT_EXTENSIONS: readonly string[]
+export declare const SUPPORTED_STRUCTURAL_EXTENSIONS: readonly string[]
 
 /**
  * Returns a sorted list of JS char offsets (UTF-16 code units) where
  * top-level semantic blocks begin in `content`.
  *
- * **Tree-sitter only** (exact AST): `ts tsx js jsx mjs cjs mts cts py pyi go rs
- *   java c h cpp cc cxx hpp hh hxx cs sh bash zsh`. Languages without a wired
- * grammar and structural-only grammars (HTML/CSS/Scala/JSON/YAML/TOML) return
- * `[]` — there is no regex/heuristic fallback. Also `[]` for data/config files,
- * plain text, and files above the 1 MB guard.
+ * **Tree-sitter** (exact AST): `ts tsx js jsx mjs cjs py go rs java c h sh bash zsh`
+ * **Heuristic** (pattern-based): `cpp hpp cc cxx cs kt kotlin scala rb php swift
+ *   css scss less html htm sql vue svelte ex exs hs lhs md lua` + 10 more
+ * **Returns `[]`** for data/config files (`json yaml toml ini csv xml …`),
+ *   plain text, and files above the 1 MB guard.
  *
  * Char offsets match JavaScript `string.substring()` — pass them directly to
  * JavaScript string slicing without conversion.
@@ -344,34 +493,13 @@ export declare function getMINIFY_CONFIG(): any
 export declare function getSemanticBoundaryOffsets(content: string, filePath: string): Array<number>
 
 /**
- * Canonical list of file extensions (lowercase, no leading dot) handled by the
- * native oxc JS/TS path (`extractJsSymbols` / `findInFileReferences`). Callers
- * should gate native dispatch on this list rather than hardcoding it, so the
- * Rust and JS sides never drift.
- */
-export declare function getSupportedJsTsExtensions(): Array<string>
-
-/**
- * Returns all extensions that have signature-outline support. This is exactly
- * the set of tree-sitter grammars with a function-body query (no regex
- * heuristics): structural-only grammars (HTML/CSS/Scala/JSON/YAML/TOML) are
- * excluded because they produce no outline.
+ * Returns all extensions that have signature extraction support
+ * (tree-sitter languages + heuristic-covered languages).
  */
 export declare function getSupportedSignatureExtensions(): Array<string>
 
 export declare function getSupportedStructuralExtensions(): Array<string>
 
-/**
- * Native binary inspection (format lane). Parses `path` as an executable /
- * object / archive and returns its identity plus — for recognized executable
- * formats — symbols, imports, exports, sections and dynamic dependencies.
- *
- * Replaces the `file` + `xxd` shell-outs. Never throws on malformed input: a
- * parse failure degrades to magic-byte identity with an explanatory note. The
- * only `Err` cases are unreadable / oversized files.
- */
-export declare function inspectBinaryNative(path: string): BinaryInspectInfo
-
 /** Check whether `command` is available on `PATH`. */
 export declare function isCommandAvailable(command: string): boolean
 
@@ -409,7 +537,15 @@ export interface JsLanguageServerConfig {
  * response. Optional key sorting and priority-key ordering; multiline
  * strings become block scalars. Emission is locked by yaml_utils tests.
  */
-export declare function jsonToYamlString(jsonObject: any, config?: YamlConversionConfig | undefined | null): string
+export type JsonPrimitive = string | number | boolean | null
+export type JsonValue = JsonPrimitive | JsonValue[] | { [key: string]: JsonValue }
+export type JsonInput =
+  | JsonPrimitive
+  | undefined
+  | JsonInput[]
+  | { [key: string]: JsonInput }
+
+export declare function jsonToYamlString(jsonObject: JsonInput, config?: YamlConversionConfig | undefined | null): string
 
 export interface JsRange {
   start: JsExactPosition
@@ -423,12 +559,6 @@ export interface JsResolvedSymbol {
   lineContent: string
 }
 
-/**
- * Mask secrets in place: every even-indexed char of a matched secret becomes
- * `*`, preserving partial readability. File-context patterns are skipped.
- */
-export declare function maskSensitiveData(text: string): string
-
 export interface MatchRange {
   /** 1-based inclusive start line. */
   start: number
@@ -458,7 +588,7 @@ export declare function minifyConservativeCore(content: string, config: FileType
  * Full minification on libuv's worker pool.
  * Returns a Promise from JavaScript and does not block the event loop.
  */
-export declare function minifyContent(content: string, filePath: string): Promise<unknown>
+export declare function minifyContent(content: string, filePath: string): Promise<MinifyResult>
 
 /** Synchronous full minification result. */
 export declare function minifyContentResult(content: string, filePath: string): MinifyResult
@@ -528,12 +658,6 @@ export interface MinifyResult {
   reason?: string
 }
 
-export interface ParsedPatchLine {
-  originalLineNumber?: number
-  newLineNumber?: number
-  content: string
-  lineType: PatchLineType
-}
 
 /**
  * Parse ripgrep `--json` NDJSON stdout into structured files + stats.
@@ -545,15 +669,23 @@ export interface ParsedPatchLine {
  */
 export declare function parseRipgrepJson(stdout: string, options?: RipgrepParseOptions | undefined | null): RipgrepParseResult
 
+/**
+ * Run ripgrep in-process: walk `path`, search every file with ripgrep's own
+ * engine, and return the same `{ files, stats }` shape the `--json` parser
+ * produced. Replaces shelling out to an `rg` binary (and the `@vscode/ripgrep`
+ * bundle) — octocode is now its own source of ripgrep.
+ *
+ * Runs on the libuv thread pool so the filesystem walk never blocks the event
+ * loop, mirroring the old async `spawn` of `rg`.
+ */
+export declare function searchRipgrep(options: RipgrepSearchOptions): Promise<RipgrepParseResult>
+
 export declare const enum PatchLineType {
   Addition = 'Addition',
   Deletion = 'Deletion',
   Context = 'Context'
 }
 
-/** Number of loaded secret-detection patterns (testing / benchmarking). */
-export declare function patternCount(): number
-
 /**
  * Cross-platform filesystem traversal and metadata filtering for local tools.
  *
@@ -593,13 +725,11 @@ export interface RipgrepMatch {
   column: number
   /** Assembled match + context window, truncated to `max_snippet_chars`. */
   value: string
-  /** Frequency for this value when `count_unique` is enabled. */
+  /** Frequency for `onlyMatching + countUnique` values. */
   count?: number
   /**
-   * AST node-kind label (declaration|import|export|callsite|identifier|
-   * comment|string|configKey|heading) when `classify_matches` is enabled.
-   * `None` when classification was off, the language is unsupported, or the
-   * file failed to parse.
+   * AST node-kind label (declaration|import|export|callsite|identifier|comment|
+   * string|configKey|heading) when `classifyMatches` is enabled.
    */
   kind?: string
   /** Deterministic relevance hint (0.0..1.0) derived from `kind`. */
@@ -625,8 +755,7 @@ export interface RipgrepPatternValidationResult {
 
 /**
  * Options for the in-process ripgrep search (`searchRipgrep`). Field semantics
- * mirror the ripgrep CLI flags the old `RipgrepCommandBuilder` emitted, so the
- * search behaves identically to shelling out to `rg`.
+ * mirror the ripgrep CLI flags the old `RipgrepCommandBuilder` emitted.
  */
 export interface RipgrepSearchOptions {
   /** Search root: a directory (recursive) or a single file. */
@@ -637,7 +766,7 @@ export interface RipgrepSearchOptions {
   fixedString?: boolean
   /** Use the PCRE2 engine for lookaround/backreferences (`-P`). */
   perlRegex?: boolean
-  /** Case-sensitive match (`-s`). Wins over `case_insensitive`. */
+  /** Case-sensitive match (`-s`). Wins over `caseInsensitive`. */
   caseSensitive?: boolean
   /** Case-insensitive match (`-i`). Default is smart-case (`-S`). */
   caseInsensitive?: boolean
@@ -677,34 +806,29 @@ export interface RipgrepSearchOptions {
   sortReverse?: boolean
   /** Max Unicode chars per assembled snippet (default 500). */
   maxSnippetChars?: number
-  /**
-   * When true, label each match with its AST node kind (tree-sitter) for
-   * language-aware ranking. Optional and capped by the caller; degrades to
-   * unlabeled matches on unsupported/unparseable files.
-   */
+  /** Label each match with its AST node kind (tree-sitter) for ranking. */
   classifyMatches?: boolean
   /**
-   * Emit one match per *submatch* with `value` set to the matched span
-   * (not the whole line) — ripgrep's `-o`/`--only-matching`. The win on a
-   * minified one-liner: line mode can only count hits, this enumerates them.
+   * Emit one match per submatch with `value` set to the matched span (not the
+   * whole line) — ripgrep's `-o`/`--only-matching`. Enumerates every hit on a
+   * minified one-liner that line mode can only count.
    */
   onlyMatching?: boolean
   /**
-   * With `only_matching`, widen each span by this many characters on each
-   * side (char-boundary safe), marking trimmed sides with `…`. 0/unset =
-   * the bare matched span.
-   */
-  matchWindow?: number
-  /**
-   * With `only_matching`, collapse duplicate values per file, preserving
-   * first-occurrence order and anchor.
+   * With `onlyMatching`, collapse repeated matched values per file while
+   * keeping the first occurrence anchor.
    */
   unique?: boolean
   /**
-   * With `only_matching`, collapse duplicate values and attach their
-   * frequency, sorted by count descending.
+   * With `onlyMatching`, collapse repeated values per file and attach a
+   * frequency count to each returned match. Sorted by count descending.
    */
   countUnique?: boolean
+  /**
+   * With `onlyMatching`, widen each span by this many characters on each side
+   * (char-boundary safe), marking trimmed sides with `…`. 0/unset = bare span.
+   */
+  matchWindow?: number
 }
 
 export interface RipgrepStats {
@@ -722,32 +846,6 @@ export interface RipgrepStats {
  */
 export declare function safeReadFile(filePath: string): string
 
-export interface SanitizationResult {
-  content: string
-  hasSecrets: boolean
-  secretsDetected: Array<string>
-  warnings: Array<string>
-}
-
-/**
- * Detect and redact all secrets from `content`, returning the sanitized string
- * with `[REDACTED-*]` placeholders plus detection metadata. `file_path` gates
- * file-context patterns (e.g. Kubernetes/`.env` secrets).
- */
-export declare function sanitizeContent(content: string, filePath?: string | undefined | null): SanitizationResult
-
-/**
- * Run ripgrep in-process: walk `path`, search every file with ripgrep's own
- * engine, and return the same `{ files, stats }` shape the `--json` parser
- * produced. Replaces shelling out to an `rg` binary (and the `@vscode/ripgrep`
- * bundle) — octocode is now its own source of ripgrep.
- *
- * Runs on the libuv thread pool so the filesystem walk never blocks the event
- * loop, mirroring the old async `spawn` of `rg`.
- */
-export declare function searchRipgrep(options: RipgrepSearchOptions): Promise<unknown>
-
-/** Native exports. */
 export const SIGNATURES_ONLY_HINT: string
 
 /**
@@ -779,37 +877,23 @@ export interface SliceContentResult {
  */
 export declare function stripPythonDocstrings(content: string): string
 
-/**
- * A structural match with stable evidence metadata. Existing
- * `StructuralMatch` remains unchanged for the legacy APIs; detailed APIs add
- * IDs and confidence without forcing old callers to carry metadata.
- */
-export interface StructuralDetailedMatch {
-  id: string
-  startLine: number
-  endLine: number
-  startCol: number
-  endCol: number
-  text: string
-  metavars: Record<string, Array<string>>
-  nodeKind?: string
-  confidence: string
-}
-
-export interface StructuralDiagnostic {
-  code: string
-  severity: string
-  stage: string
-  message: string
-  path?: string
-  recovery?: string
-}
-
 /**
  * One structural match. Line numbers are 1-based so `start_line` can be fed
  * directly as an `lspGetSemantics` `lineHint`; columns are 0-based char
  * offsets (tree-sitter native).
  */
+/**
+ * Precise position of one captured metavariable node. `line` is 1-based
+ * (usable as an `lspGetSemantics` lineHint); columns are 0-based char offsets.
+ */
+export interface MetavarRange {
+  text: string
+  line: number
+  column: number
+  endLine: number
+  endColumn: number
+}
+
 export interface StructuralMatch {
   startLine: number
   endLine: number
@@ -822,53 +906,82 @@ export interface StructuralMatch {
    * metavar name (no leading `$`).
    */
   metavars: Record<string, Array<string>>
+  /**
+   * Per-capture precise ranges, parallel to `metavars` (same keys/order).
+   * Lets an agent hand a capture straight to LSP without re-searching.
+   */
+  metavarRanges: Record<string, Array<MetavarRange>>
+}
+
+export interface StructuralDiagnostic {
+  code: string
+  severity: 'info' | 'warning' | 'error' | string
+  stage:
+    | 'snapshot'
+    | 'regionize'
+    | 'scan'
+    | 'parse'
+    | 'match'
+    | 'minify'
+    | 'sanitize'
+    | 'lsp'
+    | 'paginate'
+    | string
+  message: string
+  path?: string
+  recovery?: string
 }
 
 export interface StructuralQueryExplanation {
-  kind: string
+  kind: 'pattern' | 'rule' | 'invalid' | string
   source: string
   literalAnchor?: string
-  preFilter: string
+  preFilter: 'literal-anchor' | 'disabled' | 'unavailable' | string
   unsafeReason?: string
   diagnostics: Array<StructuralDiagnostic>
 }
 
-/**
- * Structural (AST) search — octocode's L2 layer. Resolves the grammar from
- * `file_path`'s extension and matches a code-shaped `pattern` OR a YAML `rule`
- * (exactly one). Returns node ranges (1-based lines, ready as `lineHint`s)
- * plus captured metavariables. Throws on unsupported extension, invalid
- * pattern/rule, or both/neither query supplied.
- */
-export declare function structuralSearch(content: string, filePath: string, pattern?: string | undefined | null, rule?: string | undefined | null): Array<StructuralMatch>
-
-/**
- * Detailed structural search. Unlike `structuralSearch`, unsupported
- * extensions and invalid queries are represented as status + diagnostics so
- * callers can distinguish true empty results from weak evidence.
- */
-export declare function structuralSearchDetailed(content: string, filePath: string, pattern?: string | undefined | null, rule?: string | undefined | null): StructuralSearchDetailedResult
-
-export interface StructuralSearchDetailedFileResult {
-  path: string
-  status: string
-  languageId?: string
-  skippedReason?: string
-  matches: Array<StructuralDetailedMatch>
-  diagnostics: Array<StructuralDiagnostic>
+export interface StructuralDetailedMatch extends StructuralMatch {
+  id: string
+  nodeKind?: string
+  confidence: 'exact-ast' | 'partial-ast' | 'fallback-text' | string
 }
 
 export interface StructuralSearchDetailedResult {
   path: string
   analyzer: string
   analyzerVersion: string
-  status: string
+  status:
+    | 'ok'
+    | 'partial'
+    | 'unsupported'
+    | 'ambiguous'
+    | 'parserFailed'
+    | 'fallback'
+    | 'truncated'
+    | 'stale'
+    | string
   languageId?: string
   query: StructuralQueryExplanation
   matches: Array<StructuralDetailedMatch>
   diagnostics: Array<StructuralDiagnostic>
 }
 
+/**
+ * Structural (AST) search — octocode's L2 layer. Resolves the grammar from
+ * `file_path`'s extension and matches an Octocode structural `pattern` OR a YAML `rule`
+ * (exactly one). Returns node ranges (1-based lines, ready as `lineHint`s)
+ * plus captured metavariables. Throws on unsupported extension, invalid
+ * pattern/rule, or both/neither query supplied.
+ */
+export declare function structuralSearch(content: string, filePath: string, pattern?: string | undefined | null, rule?: string | undefined | null): Array<StructuralMatch>
+
+/**
+ * Detailed structural search. Unsupported extensions and invalid queries return
+ * status + diagnostics instead of being collapsed into a thrown legacy error.
+ */
+export declare function structuralSearchDetailed(content: string, filePath: string, pattern?: string | undefined | null, rule?: string | undefined | null): StructuralSearchDetailedResult
+
 export interface StructuralSearchFileResult {
   path: string
   matches: Array<StructuralMatch>
@@ -878,22 +991,6 @@ export declare function structuralSearchFiles(options: StructuralSearchFilesOpti
 
 export declare function structuralSearchFilesDetailed(options: StructuralSearchFilesOptions): StructuralSearchFilesDetailedResult
 
-export interface StructuralSearchFilesDetailedResult {
-  files: Array<StructuralSearchDetailedFileResult>
-  totalMatches: number
-  parsedFiles: number
-  skippedByPreFilter: number
-  skippedUnsupported: number
-  skippedUnreadable: number
-  skippedLarge: number
-  analyzer: string
-  analyzerVersion: string
-  status: string
-  query: StructuralQueryExplanation
-  diagnostics: Array<StructuralDiagnostic>
-  warnings: Array<string>
-}
-
 export interface StructuralSearchFilesOptions {
   path: string
   pattern?: string
@@ -914,6 +1011,31 @@ export interface StructuralSearchFilesResult {
   warnings: Array<string>
 }
 
+export interface StructuralSearchDetailedFileResult {
+  path: string
+  status: string
+  languageId?: string
+  skippedReason?: string
+  matches: Array<StructuralDetailedMatch>
+  diagnostics: Array<StructuralDiagnostic>
+}
+
+export interface StructuralSearchFilesDetailedResult {
+  files: Array<StructuralSearchDetailedFileResult>
+  totalMatches: number
+  parsedFiles: number
+  skippedByPreFilter: number
+  skippedUnsupported: number
+  skippedUnreadable: number
+  skippedLarge: number
+  analyzer: string
+  analyzerVersion: string
+  status: string
+  query: StructuralQueryExplanation
+  diagnostics: Array<StructuralDiagnostic>
+  warnings: Array<string>
+}
+
 /**
  * Convert a human-readable symbol kind string back to the LSP `SymbolKind`
  * numeric code. Unknown strings return `13` (Variable).
@@ -932,3 +1054,27 @@ export interface YamlConversionConfig {
   sortKeys?: boolean
   keysPriority?: Array<string>
 }
+
+/** Result of secret detection + redaction over a string. */
+export interface SanitizationResult {
+  content: string
+  hasSecrets: boolean
+  secretsDetected: Array<string>
+  warnings: Array<string>
+}
+
+/**
+ * Detect and redact all secrets from `content`, returning the sanitized string
+ * with `[REDACTED-*]` placeholders plus detection metadata. `filePath` gates
+ * file-context patterns (e.g. Kubernetes/`.env` secrets).
+ */
+export declare function sanitizeContent(content: string, filePath?: string | undefined | null): SanitizationResult
+
+/**
+ * Mask secrets in place: every even-indexed char of a matched secret becomes
+ * `*`, preserving partial readability. File-context patterns are skipped.
+ */
+export declare function maskSensitiveData(text: string): string
+
+/** Number of loaded secret-detection patterns (testing / benchmarking). */
+export declare function patternCount(): number