/* auto-generated by NAPI-RS */
/* eslint-disable */
/**
 * Instrument a JavaScript or TypeScript source file for coverage collection.
 *
 * Parses `source` with Oxc, injects Istanbul-compatible coverage counters via
 * AST mutation, and returns the instrumented code with a coverage map.
 *
 * # Errors
 *
 * Returns an error if:
 *   * `emitDecoratorMetadata` is `true` while `experimentalDecorators` is not
 *   * `coverageVariable` is not a valid JavaScript identifier
 *   * `source` fails to parse
 *   * the TypeScript-strip pass reports a diagnostic
 */
export declare function instrument(source: string, filename: string, options?: InstrumentOptions | undefined | null): InstrumentResult

/** Options for the instrument function. */
export interface InstrumentOptions {
  /** Name of the global coverage variable. Defaults to `__coverage__`. */
  coverageVariable?: string
  /** Generate a source map for the instrumented output. Defaults to `false`. */
  sourceMap?: boolean
  /** Input source map JSON string from a prior transformation. */
  inputSourceMap?: string
  /**
   * Compose `inputSourceMap` into the coverage map during instrumentation.
   *
   * The returned `coverageMap`, and the `__coverage__` object baked into the
   * instrumented `code`, carry original-source positions, are keyed by the
   * original source path, and embed no `inputSourceMap`, so
   * `remapCoverageMap` on the result is a no-op.
   *
   * A coverage point whose positions have no mapping in `inputSourceMap` is
   * not instrumented at all: it gets neither a `statementMap` / `fnMap` /
   * `branchMap` entry nor a counter in the emitted `code`, so the runtime
   * `__coverage__` object and the emitted counters always agree. Has no
   * effect when `inputSourceMap` is unset or unusable.
   *
   * Defaults to `false`.
   */
  composeInputSourceMap?: boolean
  /**
   * Track truthy-value counts (`bT`) for logical expression operands.
   * Defaults to `false`.
   */
  reportLogic?: boolean
  /**
   * Track receiver-safe optional-chaining (`?.`) links as branches.
   * Receiver-bound optional calls stay native to preserve `this`.
   *
   * When `false`, optional chains are left native: no `_oc` helper is emitted
   * and no `optional-chain` branches are registered. This matches
   * `istanbul-lib-instrument`, which does not track `?.` as a branch, and
   * avoids the per-operand helper call in optional-chain-dense hot paths.
   * Statement and other branch coverage are unaffected.
   *
   * Defaults to `true`.
   */
  trackOptionalChainBranches?: boolean
  /** Class method names to exclude from coverage instrumentation. */
  ignoreClassMethods?: Array<string>
  /**
   * Run the TypeScript-strip pass before instrumentation.
   *
   * Set this when passing raw TypeScript that has not been pre-transformed by
   * Babel / tsc / esbuild. When `false`, raw TypeScript passes straight
   * through: the output contains TypeScript syntax and is not executable as
   * JavaScript, and no error is returned.
   *
   * Defaults to `false`, for callers that supply already-transformed
   * JavaScript.
   */
  stripTypescript?: boolean
  /**
   * Lower TypeScript `experimentalDecorators` syntax (`@Injectable()` /
   * `@Controller()` style) into runtime `_decorate(...)` calls.
   *
   * Mirrors the `experimentalDecorators` flag in `tsconfig.json`. The
   * instrumented output imports from `@oxc-project/runtime` at execution
   * time. Has no effect unless `stripTypescript` is also `true`.
   *
   * Defaults to `false`.
   */
  experimentalDecorators?: boolean
  /**
   * Emit TypeScript decorator metadata (`design:type`, `design:paramtypes`,
   * `design:returntype`) alongside each decorated class, method and property.
   *
   * Mirrors the `emitDecoratorMetadata` flag in `tsconfig.json`. Required by
   * NestJS dependency injection, TypeORM column type inference and
   * class-validator.
   *
   * Requires `experimentalDecorators: true`; the pair
   * `(experimentalDecorators: false, emitDecoratorMetadata: true)` throws a
   * JS `Error` rather than being silently promoted. The instrumented output
   * imports from `@oxc-project/runtime` at execution time. Has no effect
   * unless `stripTypescript` is also `true`.
   *
   * Defaults to `false`.
   */
  emitDecoratorMetadata?: boolean
  /**
   * Whether the source is compiled under `strictNullChecks`. Mirrors the
   * `strictNullChecks` flag in `tsconfig.json`.
   *
   * Only consulted when `emitDecoratorMetadata` is `true`, where it decides
   * how a nullable union is written into the emitted `design:type`. With
   * `true`, `foo: string | null` emits `Object`, matching what `tsc` does
   * under `strictNullChecks`. With `false`, `null` and `undefined` are elided
   * from the union first, so the same property emits `String`.
   *
   * A mismatch is silent: the code still runs, but NestJS dependency
   * injection, TypeORM column inference and class-validator read that
   * metadata and see a different type than `tsc` produced. Set it to match
   * the `tsconfig.json` the source is compiled with.
   *
   * Defaults to `true`, matching `tsc` under `strict`.
   */
  strictNullChecks?: boolean
  /**
   * Attach an `x_fallow_functionMap` overlay to the returned coverage map.
   *
   * The overlay carries a stable `fallow:fn:<hex>` identity per function,
   * keyed by the same ids as `fnMap` and derived from
   * `(path, name, decl span, loc span)`. Istanbul consumers ignore the
   * `x_`-prefixed field; downstream code quality tools use it as a long-lived
   * join key.
   *
   * Defaults to `false`, which keeps the JSON output byte-identical to what
   * Istanbul consumers expect.
   */
  functionIdentityOverlay?: boolean
  /**
   * Name an otherwise-anonymous callback argument after its callee.
   *
   * `arr.map(cb)` -> `"map"`,
   * `el.addEventListener("click", () => {})` -> `"addEventListener"`,
   * `new Promise((res) => {})` -> `"Promise"`.
   *
   * `istanbul-lib-instrument` leaves these `(anonymous_N)`. Names inferred
   * from a binding (variable declarator, property key, assignment target,
   * default value) still win; this only replaces the `(anonymous_N)` fallback
   * with a callee-derived name, which is also stable across rebuilds because
   * the `(anonymous_N)` counter renumbers. Only the callee is used, never a
   * sibling string argument.
   *
   * Defaults to `false`.
   */
  nameCallbackArguments?: boolean
}

/** Result of instrumenting a source file. */
export interface InstrumentResult {
  /** The instrumented source code with coverage counters injected. */
  code: string
  /**
   * Istanbul-compatible coverage map as a JSON string.
   * Parse with `JSON.parse()` to get the coverage object.
   */
  coverageMap: string
  /**
   * Output source map JSON string. Present only when the `sourceMap` option
   * is `true`.
   */
  sourceMap?: string
  /** Unhandled pragma comments found during instrumentation. */
  unhandledPragmas: Array<UnhandledPragma>
}

/**
 * Remap a `coverage-final.json`-shaped JSON string through each entry's
 * embedded `inputSourceMap`.
 *
 * Entries without an `inputSourceMap` are returned unchanged under their
 * original key. Entries with one are walked through the map and re-keyed by the
 * original source path, with `sourceRoot` joined per `istanbul-lib-source-maps`
 * semantics. A generated file that maps to several original sources fans out to
 * one entry per source; entries from several chunks that resolve to the same
 * path merge by Istanbul location identity and sum their counters. Equivalent
 * to `createSourceMapStore().transformCoverage(coverageMap)` in the Vitest
 * istanbul reporter path.
 *
 * Every returned entry satisfies the Istanbul merge invariant
 * `keys(s) ⊆ keys(statementMap)`, and the same for `f`/`fnMap` and
 * `b`/`bT`/`branchMap`: an orphan counter, an `s`/`f`/`b` key with no matching
 * location-map entry, is dropped rather than passed through. Such an orphan
 * crashes `istanbul-lib-coverage`'s `CoverageMap.merge`, and therefore
 * `nyc report`, with "Cannot destructure property 'start' of 'undefined'"
 * ([#107](https://github.com/fallow-rs/oxc-coverage-instrument/issues/107)). It
 * can reach the input when an upstream instrumenter incremented a counter whose
 * map slot was later pruned. Dropping it is a no-op on already-consistent
 * coverage.
 *
 * For nyc's disk-read flow (Mode A fallback) use
 * [`remap_coverage_map_with_loader`] and supply a `Record<string, string>` of
 * preloaded maps keyed by `FileCoverage` path.
 *
 * An unmapped entry in a multi-source map is omitted whatever `options` says,
 * because it has no safe original owner. Pass `{ dropUnmapped: true }` to prune
 * unmappable entries in the single-source case too; see [`RemapOptions`] for
 * the per-kind semantics.
 *
 * # Errors
 *
 * Returns an error if `coverage_json` is not an Istanbul `CoverageMap`, or if
 * the remapped map fails to serialize.
 */
export declare function remapCoverageMap(coverageJson: string, options?: RemapOptions | undefined | null): string

/**
 * Like [`remap_coverage_map`], but with a preloaded map dictionary used as the
 * Mode A disk-read fallback.
 *
 * Entries whose path is a key in `source_maps` and which carry no embedded
 * `inputSourceMap` use the dictionary's value as the source map JSON. Each
 * value must be a valid source map JSON string; an entry whose value fails to
 * parse passes through unremapped.
 *
 * The dictionary form matches the Jest / nyc / istanbul JS workflow, where the
 * caller has already read the maps from disk before calling the converter.
 * [`oxc_coverage_instrument::SourceMapStore`] (Mode B continuous remap) is not
 * exposed to JS.
 *
 * # Errors
 *
 * Returns an error if `coverage_json` is not an Istanbul `CoverageMap`, or if
 * the remapped map fails to serialize.
 */
export declare function remapCoverageMapWithLoader(coverageJson: string, sourceMaps: Record<string, string>, options?: RemapOptions | undefined | null): string

/** Options for `remapCoverageMap` and `remapCoverageMapWithLoader`. */
export interface RemapOptions {
  /**
   * Prune statement / function / branch entries whose positions cannot be
   * looked up in the source map, along with their matching `s` / `f` / `b` /
   * `bT` hit-count slots.
   *
   * Drop semantics mirror `istanbul-lib-source-maps`'s `transformer.js`:
   * statements drop when start or end fails to remap; functions drop when any
   * of `decl` / `loc` start or end fails (a matching `x_fallow_functionMap`
   * overlay entry drops with the function); branch arms drop per arm, and the
   * whole branch drops when no arms survive or retained mapped arms resolve
   * to different sources. Branch ownership comes from those retained arms,
   * and an unmapped umbrella `loc` falls back to the first retained arm.
   *
   * Defaults to `false`, which keeps unmapped entries at their
   * generated-output positions.
   */
  dropUnmapped?: boolean
}

/** A coverage pragma comment that was found but not handled. */
export interface UnhandledPragma {
  /** The full comment text. */
  comment: string
  /** 1-based line number. */
  line: number
  /** 0-based column. */
  column: number
}

/**
 * Convert V8 UTF-16 range coverage into Istanbul `FileCoverage` JSON.
 *
 * `v8FunctionsJson` is the JSON array shape that the V8 inspector emits under
 * `Profiler.takePreciseCoverage().result[].functions`, the same shape Node's
 * `--experimental-coverage` and `@vitest/coverage-v8` consume.
 *
 * `wrapperLength` is an explicit UTF-16 code-unit base for producers that
 * report wrapper-shifted ranges. It defaults to 0, which is correct for
 * source-relative Node inspector coverage.
 *
 * Returns a JSON object compatible with Istanbul's `FileCoverage`. Statement,
 * function and branch counts are populated from the V8 ranges. Branch arm
 * counts resolve for if-else (arm\[0\] via the collected consequent-body byte
 * span, arm\[1\] via the alternate-body span) and for switch cases with
 * `{ ... }` bodies. Branch arms with no matching V8 range (ternary
 * consequent/alternate, logical-expression right-hand operands and
 * `default-arg` expressions) report `0`; this under-reports rather than
 * over-reports, so CI coverage thresholds do not silently pass on
 * un-instrumented arms.
 *
 * When the source ends with a base64 or percent-encoded
 * `//# sourceMappingURL=data:application/json;...` trailer, the embedded map is
 * decoded and attached to the result as `inputSourceMap`. For external
 * `//# sourceMappingURL=foo.js.map` references, use
 * [`v8_to_istanbul_with_loader`] and pass a dictionary of URL to map JSON.
 *
 * If the returned object has `inputSourceMap` set, chain `remapCoverageMap`
 * next to resolve coverage positions back to the original source; otherwise the
 * inline map rides along and downstream JS reporters that also call into
 * `istanbul-lib-source-maps` may double-remap.
 *
 * # Errors
 *
 * Returns an error if `v8_functions_json` is not a V8 function-coverage array,
 * if `source` fails to parse, or if the result fails to serialize.
 */
export declare function v8ToIstanbul(source: string, filename: string, v8FunctionsJson: string, wrapperLength?: number | undefined | null): string

/**
 * Like [`v8_to_istanbul`], but resolves external `//# sourceMappingURL=`
 * references from the preloaded `external_source_maps` dictionary.
 *
 * The key is the URL as it appears in the source's trailing comment, for
 * example `foo.js.map`; the value is the map's JSON content. If the source has
 * an inline data-URL map the dictionary is not consulted. An entry whose value
 * fails to parse leaves `inputSourceMap` unset.
 *
 * # Errors
 *
 * Returns an error if `v8_functions_json` is not a V8 function-coverage array,
 * if `source` fails to parse, or if the result fails to serialize.
 */
export declare function v8ToIstanbulWithLoader(source: string, filename: string, v8FunctionsJson: string, externalSourceMaps: Record<string, string>, wrapperLength?: number | undefined | null): string