@visulima/vis 1.0.0-alpha.3 → 1.0.0-alpha.30

package/index.d.ts

@@ -0,0 +1,436 @@
+/* auto-generated by NAPI-RS */
+/* eslint-disable */
+/**
+ * Opaque handle wrapping a decoded `BloomFilter`. JS calls back into
+ * `osv_bloom_probe` / `osv_bloom_probe_batch` with this handle. Arc so
+ * the same filter can fan out to multiple probe calls without copying
+ * the bitset.
+ */
+export declare class OsvBloomHandle {
+    /**
+     * `n` field from the filter header — entry count the upstream
+     * builder inserted. Exposed for `vis advisories bloom status`.
+     */
+    get entriesInserted(): number;
+    /**
+     * `m` field — bit count. Returned as a decimal string so the full
+     * u64 round-trips without JS-Number precision loss; today's filter
+     * is ~3.1M bits but the wire format reserves 64-bit headroom.
+     */
+    get bitCountString(): string;
+    /** `k` field — hash-function count per probe. */
+    get hashCount(): number;
+    /**
+     * `built_at_unix_seconds` — UNIX seconds the upstream builder
+     * recorded, as a decimal string. JS reconstructs via
+     * `new Date(Number(s) * 1000)`. Use this in status output rather
+     * than the local fetch time.
+     */
+    get builtAtUnixSecondsString(): string;
+    /**
+     * `format_version` — currently 1. Surfaced so JS can flag a
+     * version-mismatch warning without re-decoding.
+     */
+    get formatVersion(): number;
+}
+
+export interface AddOptions {
+    packages: Array<string>;
+    saveDev: boolean;
+    exact: boolean;
+    peer: boolean;
+    optional: boolean;
+    global: boolean;
+    workspace: boolean;
+    workspaceRoot: boolean;
+    filter: Array<string>;
+}
+
+/**
+ * Ingest one OSV ecosystem dump into the local SQLite. Async because the
+ * zip → JSON → INSERT pipeline can take seconds; we run it on a libuv worker
+ * so the main JS thread is free.
+ */
+export declare function advisoriesIngest(options: AdvisoryIngestOptions, onProgress: (current: number, total: number) => void): Promise<AdvisoryIngestResult>;
+
+/**
+ * Synchronous query path. Returns one `AdvisoryQueryResult` per input,
+ * preserving order, so callers can zip back to their lockfile rows by index.
+ */
+export declare function advisoriesQuery(dbPath: string, queries: Array<AdvisoryQuery>): Array<AdvisoryQueryResult>;
+
+export declare function advisoriesStatus(dbPath: string): AdvisoryDbStatus;
+
+export interface AdvisoryDbStatus {
+    exists: boolean;
+    ecosystems: Array<AdvisoryEcosystemStatus>;
+    sizeBytes: number;
+    schemaVersion: number;
+}
+
+export interface AdvisoryEcosystemStatus {
+    name: string;
+    advisoryCount: number;
+    lastSyncIso: string;
+    manifestEtag?: string;
+}
+
+export interface AdvisoryIngestOptions {
+    /** Path to a previously-downloaded OSV dump zip on disk. */
+    zipPath: string;
+    dbPath: string;
+    ecosystem: string;
+    /**
+     * HTTP ETag header to write into the `manifest_etag` meta row for this
+     * ecosystem. `null` when the server didn't send one.
+     */
+    manifestEtag?: string;
+}
+
+export interface AdvisoryIngestResult {
+    advisoriesIngested: number;
+    durationMs: number;
+}
+
+export interface AdvisoryQuery {
+    ecosystem: string;
+    name: string;
+    version: string;
+}
+
+export interface AdvisoryQueryResult {
+    name: string;
+    version: string;
+    vulnerabilities: Array<NativeVulnerabilityJs>;
+}
+
+/**
+ * Returns the full prek-identify tag universe. Used by the vis migrator
+ * to validate `types:` / `types_or:` / `exclude_types:` filters in
+ * migrated `.pre-commit-config.yaml` files — anything outside this set
+ * (and outside the vis-specific overlay) is surfaced as a warning.
+ */
+export declare function allKnownTags(): Array<string>;
+
+export interface CleanResult {
+    /** Directories that were removed */
+    removed: Array<string>;
+    /** Directories that failed to remove (with error messages) */
+    errors: Array<string>;
+    /** Lockfiles that were removed (when --lockfile flag used) */
+    lockfilesRemoved: Array<string>;
+}
+
+/**
+ * Safely removes all node_modules directories in a workspace.
+ *
+ * Uses Rust's `fs::remove_dir_all` which correctly handles symlinks and
+ * NTFS junctions on Windows without following them into targets.
+ *
+ * When `remove_lockfile` is true, also removes lockfiles from the root.
+ */
+export declare function cleanWorkspace(root: string, removeLockfile: boolean): CleanResult;
+
+export interface DetectedPackageManager {
+    /** The package manager name: "pnpm", "npm", "yarn", "bun", or "deno" */
+    name: string;
+    /** The version string from packageManager field, or None if unknown */
+    version?: string;
+    /**
+     * Build metadata (sha256 hash) appended to packageManager field by
+     * corepack. `parts[1].split('+').next()` strips it from `version`;
+     * this field preserves it for callers that want to verify the pin.
+     */
+    buildMeta?: string;
+    /** Whether this is a monorepo/workspace */
+    isWorkspace: boolean;
+}
+
+/**
+ * Detects the package manager for the project at the given path.
+ * Priority: packageManager field > lockfiles > config files >
+ * `npm_config_user_agent` env var > default (pnpm).
+ *
+ * `opts` lets callers skip individual sources. `None` opts default
+ * to "use the source".
+ *
+ * Returns `napi::Result` so any I/O errors surface as JS exceptions.
+ */
+export declare function detectPackageManager(cwd: string, opts?: DetectPackageManagerOptions | undefined | null): DetectedPackageManager;
+
+/**
+ * Options controlling which detection sources to consult.
+ *
+ * Matches nypm's `detectPackageManager` opts. All flags are
+ * `Option<bool>` so callers can omit them; `None` is treated as the
+ * default (use the source). Mirrors the JS-side ergonomics where
+ * `{}` enables every source.
+ */
+export interface DetectPackageManagerOptions {
+    /** Skip reading the `packageManager` field in package.json. */
+    ignorePackageJson?: boolean;
+    /** Skip lockfile walk (pnpm-lock.yaml, yarn.lock, …). */
+    ignoreLockFile?: boolean;
+    /**
+     * Skip the `npm_config_user_agent` env-var fallback. Set by every
+     * PM when running scripts; lets a tool spawned from `pnpm run x`
+     * know it's pnpm even without a lockfile.
+     */
+    ignoreArgv?: boolean;
+}
+
+export interface DlxOptions {
+    package: string;
+    args: Array<string>;
+    additionalPackages: Array<string>;
+    shellMode: boolean;
+    silent: boolean;
+}
+
+export interface EditorconfigDefaults {
+    indent?: string;
+    lineEnding?: string;
+}
+
+export interface ExecOptions {
+    command: string;
+    args: Array<string>;
+    shellMode: boolean;
+    recursive: boolean;
+    workspaceRoot: boolean;
+    parallel: boolean;
+    reverse: boolean;
+    filter: Array<string>;
+}
+
+/**
+ * Executes a package manager command synchronously.
+ * Uses Rust's std::process::Command for maximum performance.
+ * Only allowed binaries can be executed (see ALLOWED_BINS).
+ *
+ * Returns `napi::Result<ExecResult>` -- throws a JS error for disallowed
+ * binaries or spawn failures, returns ExecResult with exit code otherwise.
+ */
+export declare function execPmCommand(bin: string, args: Array<string>, cwd: string): ExecResult;
+
+/**
+ * Executes a package manager command with inherited stdio (interactive).
+ * Returns exit code. Throws JS error for disallowed binaries or spawn failures.
+ */
+export declare function execPmCommandInteractive(bin: string, args: Array<string>, cwd: string): number;
+
+export interface ExecResult {
+    code: number;
+    stdout: string;
+    stderr: string;
+}
+
+export interface InstallOptions {
+    frozenLockfile: boolean;
+    prod: boolean;
+    dev: boolean;
+    noOptional: boolean;
+    force: boolean;
+    ignoreScripts: boolean;
+    lockfileOnly: boolean;
+    offline: boolean;
+    silent: boolean;
+    recursive: boolean;
+    workspaceRoot: boolean;
+    filter: Array<string>;
+}
+
+/**
+ * ABI compatibility version. Bump this whenever any `#[napi]` function
+ * signature changes so the TypeScript loader can reject stale `.node`
+ * files (e.g. a local build from before the change) that would
+ * otherwise silently misinterpret arguments.
+ *
+ * Version history:
+ *   1 — initial versioned ABI. `resolve_link` gained a `version` parameter.
+ *   2 — added `resolve_editorconfig_defaults` (replaces the `editorconfig` npm package).
+ *   3 — added prek-identify bindings: `tags_from_path`, `tags_from_paths`,
+ *       `parse_shebang`, `all_known_tags`.
+ *   4 — added offline advisories: `advisories_ingest`, `advisories_query`,
+ *       `advisories_status`. Backed by bundled SQLite (rusqlite) + zip.
+ *   5 — added osv-bloom prefilter: `osv_bloom_decode`, `osv_bloom_probe`,
+ *       `osv_bloom_probe_batch`. Backed by `blake3` keyed-hash double-hashing.
+ */
+export const NATIVE_BINDING_VERSION: number;
+
+export interface NativeSortPackageJsonOptions {
+    /** Enable formatted output with newlines (default: true) */
+    pretty?: boolean;
+    /** Alphabetize script commands (default: false) */
+    sortScripts?: boolean;
+}
+
+export interface NativeVulnerabilityJs {
+    id: string;
+    aliases: Array<string>;
+    /** Normalized severity: "CRITICAL" | "HIGH" | "MODERATE" | "LOW" | "UNKNOWN". */
+    severity: string;
+    summary: string;
+    fixedVersions: Array<string>;
+    cvssScore?: number;
+}
+
+export interface OsvBloomBatchHit {
+    /**
+     * Index into the input batch array. Lets JS reconstruct which
+     * lockfile row triggered the hit without re-walking the inputs.
+     */
+    index: number;
+    name: string;
+    version: string;
+}
+
+export interface OsvBloomBatchQuery {
+    name: string;
+    version: string;
+}
+
+/**
+ * Decode a v1 osv-bloom filter from `bytes` (the on-disk `filter.bin`).
+ * Returns an opaque handle; reuse it for every probe call until the
+ * JS-side cache invalidates.
+ */
+export declare function osvBloomDecode(bytes: Buffer): OsvBloomHandle;
+
+/**
+ * Probe a single `(name, version)` pair. Returns `true` when the pair
+ * *might* be a known-malicious advisory — callers must escalate to an
+ * authoritative source for `(name, version)` confirmation.
+ *
+ * The version is encoded into a semver-major bucket per the upstream
+ * scheme; the wildcard bucket is also probed so advisories with
+ * unbounded ranges still match. Unparseable versions probe only the
+ * wildcard bucket.
+ */
+export declare function osvBloomProbe(handle: OsvBloomHandle, name: string, version: string): boolean;
+
+/**
+ * Batch variant. Returns only the hits, with their original index — the
+ * expected hit rate is well under 1%, so allocating one bool per input
+ * (`Vec<bool>` of length N) would dominate the cost. Order of returned
+ * hits matches input order.
+ */
+export declare function osvBloomProbeBatch(handle: OsvBloomHandle, queries: Array<OsvBloomBatchQuery>): Array<OsvBloomBatchHit>;
+
+export interface OutdatedOptions {
+    packages: Array<string>;
+    long: boolean;
+    format: string;
+    recursive: boolean;
+    filter: Array<string>;
+    workspaceRoot: boolean;
+    prod: boolean;
+    dev: boolean;
+    noOptional: boolean;
+    compatible: boolean;
+    global: boolean;
+}
+
+/**
+ * Parses the shebang line of an executable file, returning the
+ * interpreter argv (e.g. `["python3"]`, `["env", "node"]`). Returns an
+ * empty vector when the file has no shebang or cannot be read — mirrors
+ * pre-commit's behavior of treating "no shebang" as "no interpreter
+ * tags" rather than as an error.
+ */
+export declare function parseShebang(path: string): Array<string>;
+
+export interface ProgressPayload {
+    current: number;
+    total: number;
+}
+
+export interface RemoveOptions {
+    packages: Array<string>;
+    saveDev: boolean;
+    global: boolean;
+    recursive: boolean;
+    workspaceRoot: boolean;
+    filter: Array<string>;
+}
+
+export declare function resolveAdd(pm: string, version: string, opts: AddOptions): ResolvedCommand;
+
+export interface ResolvedCommand {
+    bin: string;
+    args: Array<string>;
+    warnings: Array<string>;
+}
+
+export declare function resolveDedupe(pm: string, version: string, check: boolean): ResolvedCommand;
+
+export declare function resolveDlx(pm: string, version: string, opts: DlxOptions): ResolvedCommand;
+
+/**
+ * Resolves `.editorconfig` defaults for `file_path` using the spec-compliant
+ * `ec4rs` parser. Mirrors the previous `editorconfig` npm package surface
+ * consumed by `src/util/editorconfig.ts`: returns the indent string and a
+ * normalized line-ending tag, or `None` for either when no usable value is
+ * configured. Parse / IO failures collapse to an empty result so callers can
+ * fall back to content sniffing without try/catch noise.
+ */
+export declare function resolveEditorconfigDefaults(filePath: string): EditorconfigDefaults;
+
+export declare function resolveExec(pm: string, version: string, opts: ExecOptions): ResolvedCommand;
+
+export declare function resolveInstall(pm: string, version: string, opts: InstallOptions): ResolvedCommand;
+
+export declare function resolveLink(pm: string, version: string, target?: string | undefined | null): ResolvedCommand;
+
+export declare function resolveOutdated(pm: string, version: string, opts: OutdatedOptions): ResolvedCommand;
+
+export declare function resolvePmCommand(pm: string, version: string, subcommand: string, extraArgs: Array<string>): ResolvedCommand;
+
+export declare function resolveRemove(pm: string, version: string, opts: RemoveOptions): ResolvedCommand;
+
+export declare function resolveUnlink(pm: string, version: string, packages: Array<string>, recursive: boolean): ResolvedCommand;
+
+export declare function resolveWhy(pm: string, version: string, opts: WhyOptions): ResolvedCommand;
+
+export declare function sortPackageJsonString(contents: string): string;
+
+export declare function sortPackageJsonStringWithOptions(contents: string, options: NativeSortPackageJsonOptions): string;
+
+/**
+ * Classifies a single file path using `prek-identify`. Returns the set of
+ * tags (extensions, interpreters, metadata) that pre-commit / prek would
+ * associate with the file. Errors collapse to an empty vector so callers
+ * don't need try/catch — the vis hook runtime treats "unclassified" and
+ * "no tags" identically.
+ */
+export declare function tagsFromPath(path: string): Array<string>;
+
+/**
+ * Batch variant of [`tags_from_path`]. Returns one tag list per input
+ * path in the same order. Errors for individual paths collapse to empty
+ * vectors so partial classification failures don't fail the whole batch
+ * (the same behavior pre-commit applies when stat-ing a deleted staged
+ * file mid-run).
+ */
+export declare function tagsFromPaths(paths: Array<string>): Array<Array<string>>;
+
+/**
+ * Finds the full path to a binary using `which`-style lookup.
+ * Returns None if not found.
+ */
+export declare function whichBin(name: string): string | null;
+
+export interface WhyOptions {
+    packages: Array<string>;
+    json: boolean;
+    long: boolean;
+    parseable: boolean;
+    recursive: boolean;
+    dev: boolean;
+    prod: boolean;
+    noOptional: boolean;
+    global: boolean;
+    /** Depth limit. Uses Option<i32> directly (napi supports it). */
+    depth?: number;
+    filter: Array<string>;
+}