/**
 * @module @nhtio/adk/batteries/artifacts/ecmascript
 *
 * Provides `SpooledEcmaScriptArtifact`, a structured query interface for JavaScript and
 * TypeScript source files.
 *
 * @remarks
 * Parse source code via the TypeScript compiler API to enable structural queries:
 * - `artifact_es_symbols` — top-level declarations (functions, classes, interfaces, types)
 * - `artifact_es_imports` — import declarations and their source modules
 * - `artifact_es_exports` — export declarations and re-exports
 * - `artifact_es_outline` — nested member index (class methods/properties, interface members)
 * - `artifact_es_signature` — declaration signature text (parameters, return types)
 * - `artifact_es_jsdoc` — JSDoc comments attached to declarations
 * - `artifact_es_references` — syntactic scan for identifier usage (not semantic)
 *
 * **Decoding note:** `decode()` on a `SpooledEcmaScriptArtifact` throws until
 * `registerArtifactEncodables()` has run. `encode()` requires no setup.
 */
import { E_TYPESCRIPT_PEER_MISSING } from "./exceptions";
import { ToolRegistry } from "../../../common";
import { SpooledArtifact } from "../../../spooled_artifact";
/**
 * Well-known @nhtio/encoder contract keys, resolved via the global symbol registry
 * to avoid a hard dependency on the optional @nhtio/encoder peer.
 */
declare const ENCODE_METHOD: unique symbol;
declare const DECODE_METHOD: unique symbol;
import type { DispatchContext, SpoolReader, ToolMethodDescriptor } from "../../../types";
/** Snapshot payload for the encoder contract; the encoder treats it as opaque. */
type AdkEncodableSnapshot = unknown;
/**
 * A top-level declaration (function, class, interface, type alias, enum, or binding).
 *
 * @remarks
 * Line numbers are 0-based. `startLine` is the line containing the declaration keyword or
 * identifier. `endLine` is the 0-based index of the last line belonging to this declaration
 * (inclusive).
 */
export interface EcmaScriptSymbol {
    /** Declaration kind: `'function'`, `'class'`, `'interface'`, `'type'`, `'enum'`, or `'const'`/`'let'`/`'var'`. */
    kind: string;
    /** The declared name. */
    name: string;
    /** Whether this declaration is exported. */
    exported: boolean;
    /** 0-based line of the first line of this declaration. */
    startLine: number;
    /** 0-based line of the last line of this declaration (inclusive). */
    endLine: number;
}
/**
 * An import declaration.
 *
 * @remarks
 * Line numbers are 0-based. The `named` array contains all imported identifiers from a named
 * import; `default` contains the default import name (if any); `namespace` contains the
 * namespace import name (if `import * as`). `typeOnly` indicates whether this is a
 * `import type` declaration.
 */
export interface EcmaScriptImport {
    /** The module specifier (e.g., `'@nhtio/adk/common'` or `'./utils'`). */
    moduleSpecifier: string;
    /** Array of named imports (empty if none). */
    named: string[];
    /** The default import name, or undefined. */
    default?: string;
    /** The namespace import name (for `import *`), or undefined. */
    namespace?: string;
    /** True for `import type` declarations. */
    typeOnly: boolean;
    /** 0-based line of this import statement. */
    line: number;
}
/**
 * An export declaration or re-export.
 *
 * @remarks
 * Includes named exports, default exports, re-exports (`export * from`), and re-export named
 * members. When `moduleSpecifier` is present, this is a re-export; otherwise it re-exports
 * locally-declared members.
 */
export interface EcmaScriptExport {
    /** 0-based line of this export statement. */
    line: number;
    /** The module specifier for re-exports (e.g., `'./utils'`), or undefined for local exports. */
    moduleSpecifier?: string;
    /** Array of named exports (empty if this is `export default` or `export * from`). */
    named: string[];
    /** True for `export default`. */
    isDefault: boolean;
    /** True for `export * from`. */
    isNamespaceReExport: boolean;
    /** True for `export type` declarations. */
    isTypeOnly: boolean;
}
/**
 * A class or interface member in the outline.
 */
export interface OutlineMember {
    /** The member name. */
    name: string;
    /** The member kind: `'method'`, `'property'`, `'accessor'`, or `'signature'`. */
    kind: string;
    /** 0-based line of this member. */
    startLine: number;
    /** 0-based line of the last line of this member (inclusive). */
    endLine: number;
}
/**
 * An entry in the structural outline (class or interface with its members).
 */
export interface OutlineEntry {
    /** The container kind: `'class'` or `'interface'`. */
    kind: 'class' | 'interface';
    /** The container name. */
    name: string;
    /** 0-based line of the container declaration. */
    startLine: number;
    /** 0-based line of the last line of this container (inclusive). */
    endLine: number;
    /** Array of members (methods, properties, accessors). */
    members: OutlineMember[];
}
/**
 * The location of an identifier reference.
 */
export interface IdentifierReference {
    /** 0-based line where this identifier appears. */
    line: number;
    /** 0-based column where this identifier starts. */
    column: number;
}
/**
 * A {@link @nhtio/adk!SpooledArtifact} specialisation for EcmaScript (JavaScript and TypeScript)
 * source files.
 *
 * @remarks
 * Parses source code syntactically (no type checker) using the TypeScript compiler API, enabling
 * structural queries without materialising the full file into memory.
 *
 * The parser automatically infers the script kind (`.js`, `.ts`, `.jsx`, `.tsx`) from the
 * `fileName` when provided; defaults to `ts` when omitted (it parses the widest grammar).
 *
 * All parsing errors are non-fatal — TypeScript's parser is error-tolerant and produces a
 * partial tree. Diagnostics are not surfaced by the query methods.
 */
export declare class SpooledEcmaScriptArtifact extends SpooledArtifact {
    #private;
    /**
     * @param reader - The backing store to read from.
     * @param options - Optional configuration.
     * @param options.fileName - The source file name. When provided, script kind is inferred from
     *   the extension (`.mts`/`.cts`/`.ts` → `'ts'`, `.mjs`/`.cjs`/`.js` → `'js'`, `.tsx` → `'tsx'`,
     *   `.jsx` → `'jsx'`). Defaults to `undefined`.
     * @param options.scriptKind - Explicit script kind override. Defaults to `'ts'` when not
     *   provided and cannot be inferred from `fileName`.
     */
    constructor(reader: SpoolReader, options?: {
        fileName?: string;
        scriptKind?: 'js' | 'jsx' | 'ts' | 'tsx';
    });
    /**
     * Returns `true` if `value` is a {@link SpooledEcmaScriptArtifact} instance.
     *
     * @remarks
     * Uses the cross-realm-safe {@link @nhtio/adk!isInstanceOf} guard. Safe against the
     * dual-module-copy case.
     */
    static isSpooledEcmaScriptArtifact(value: unknown): value is SpooledEcmaScriptArtifact;
    /**
     * The EcmaScript-specific artifact-query descriptors this class adds.
     *
     * @remarks
     * Lists seven descriptors; the base seven (`artifact_head`, etc.) are forged separately.
     */
    static toolMethods: ReadonlyArray<ToolMethodDescriptor>;
    /**
     * Forges base-class tools plus EcmaScript-specific tools narrowed to {@link SpooledEcmaScriptArtifact}.
     */
    static forgeTools(ctx: DispatchContext): ToolRegistry;
    /**
     * Return every top-level declaration, optionally filtered by kind.
     */
    es_symbols(kind?: string): Promise<EcmaScriptSymbol[]>;
    /**
     * Return every import declaration.
     */
    es_imports(): Promise<EcmaScriptImport[]>;
    /**
     * Return every export declaration and re-export.
     */
    es_exports(): Promise<EcmaScriptExport[]>;
    /**
     * Return a structural outline of classes and interfaces with their members.
     */
    es_outline(): Promise<OutlineEntry[]>;
    /**
     * Return the signature text for a named declaration.
     * Searches top-level declarations (functions, classes, interfaces, enums, type aliases,
     * const/let/var bindings), class members (methods, properties, constructors, accessors),
     * and interface members (method signatures, property signatures) — the same lookup
     * {@link SpooledEcmaScriptArtifact.es_jsdoc} uses, so the two always agree on what a
     * name resolves to.
     */
    es_signature(name: string): Promise<string>;
    /**
     * Return the JSDoc comment for a named declaration.
     * Searches top-level declarations (functions, classes, interfaces, enums, type aliases,
     * const/let/var bindings), class members (methods, properties, constructors, accessors),
     * and interface members (method signatures, property signatures) — the same lookup
     * {@link SpooledEcmaScriptArtifact.es_signature} uses, so the two always agree on what a
     * name resolves to.
     */
    es_jsdoc(name: string): Promise<string>;
    /**
     * Return every line where an identifier appears (syntactic scan only).
     */
    es_references(name: string): Promise<IdentifierReference[]>;
    /**
     * Serialise this SpooledEcmaScriptArtifact into an encoder snapshot.
     */
    [ENCODE_METHOD](): AdkEncodableSnapshot;
    /**
     * Reconstruct a SpooledEcmaScriptArtifact from an encoder snapshot.
     */
    static [DECODE_METHOD](data: AdkEncodableSnapshot): SpooledEcmaScriptArtifact;
}
/**
 * Battery exception re-export.
 */
export { E_TYPESCRIPT_PEER_MISSING };