laterite 0.5.1 → 0.6.0

package/index.d.ts

@@ -1,7 +1,115 @@
-/* tslint:disable */
+/* auto-generated by NAPI-RS */
 /* eslint-disable */
+/**
+ * A parsed AGS4 file held native-side — the Node analog of laterite-py's
+ * `Reading` handle (and `laterite-ags4-wasm`'s `ParsedDataset`). Each group's typed
+ * `RecordBatch` is built lazily on `tableIpc(code)` and dropped after the
+ * bytes are returned, so peak residency is one batch.
+ */
+export declare class Reading {
+  /** Group codes in file order (the order to load tables in). */
+  groupCodes(): Array<string>
+  /** The file's `TRAN_AGS` edition string, if present. */
+  get tranAgs(): string | null
+  /**
+   * `{headings, units, types, sqlTypes}` for one group, or `null` if the
+   * code isn't present. No Arrow built — cheap metadata only.
+   */
+  meta(code: string): GroupMeta | null
+  /**
+   * One group's rows as an Arrow **IPC stream** (`Buffer`), columns already
+   * correctly typed. The Node analog of the pyo3-arrow capsule: the typed
+   * columns come from the one shared emitter (`laterite_types::arrow_cols`), the
+   * SAME casting Python/wasm use — so a file types byte-identically across
+   * hosts. Returns `null` if the code isn't in the file.
+   */
+  tableIpc(code: string): Buffer | null
+  /**
+   * Re-emit byte-faithful AGS4 text from the retained parse (the raw DATA
+   * values, unchanged). = laterite-py's `Reading::emit`.
+   */
+  emit(): string
+}
 
-/* auto-generated by NAPI-RS */
+/**
+ * The `.ags.idx` validity certificate — the Node mirror of laterite-py's
+ * `Sidecar` pyclass, wrapping the ONE core `laterite_ags4_core::index::Sidecar`
+ * so a Node-minted cert is byte-identical + checker-compatible with Python,
+ * `lat-check --emit-index`, and the DuckDB extension. `Ags4File.certify()` mints
+ * one; `read(file, {index})` consumes it; a fresh + engine-matching cert lets a
+ * later `.validate()` skip the rule engine.
+ */
+export declare class Sidecar {
+  /**
+   * Assemble a certificate for an ALREADY-clean file — the caller MUST have
+   * validated `data` clean (0 error findings); core trusts that, it cannot
+   * re-check. `edition` is the resolved AGS edition (e.g. `"4.1.1"`); `checkedAt`
+   * an RFC-3339 UTC timestamp (the TS side passes `new Date().toISOString()`);
+   * `warnings`/`fyi` the advisory counts present at validation. The validator
+   * name + engine version are stamped here. Throws if `data` isn't indexable
+   * AGS4 (e.g. non-UTF-8, which the byte index rejects).
+   */
+  static assemble(data: Uint8Array, edition: string, checkedAt: string, warnings?: number | undefined | null, fyi?: number | undefined | null, compat?: string | undefined | null, checkFiles?: boolean | undefined | null, editionForced?: boolean | undefined | null): Sidecar
+  /**
+   * Parse a certificate from its on-disk `.ags.idx` JSON bytes, rejecting an
+   * unknown format version. Throws on malformed / unsupported JSON.
+   */
+  static fromJson(data: Uint8Array): Sidecar
+  /** Serialise to the on-disk `.ags.idx` JSON (pretty). */
+  toJson(): Buffer
+  /**
+   * Is this certificate still current for `data`? Strong check: format version +
+   * byte length + SHA-256. A mismatch means the source changed under the cert.
+   */
+  isFreshFor(data: Uint8Array): boolean
+  /**
+   * Was this cert minted by the CURRENT native validator engine (same engine
+   * version, native — not a compat profile)? The `.validate()` skip trusts a
+   * carried cert only when this holds AND it's fresh.
+   */
+  matchesNativeValidator(): boolean
+  /**
+   * Does this cert's check profile cover a request's? (`checkFiles`: the cert ran
+   * at least what's asked; `forcedEdition`: a forced request needs the same
+   * forced edition, an auto request an auto cert.)
+   */
+  profileCovers(checkFiles: boolean, forcedEdition?: string | undefined | null): boolean
+  get version(): number
+  /**
+   * The certified source's byte length (a JS number; AGS files are well within
+   * the 2^53 safe-integer range).
+   */
+  get size(): number
+  get sha256(): string
+  get edition(): string
+  get validator(): string
+  get validatorVersion(): string
+  get compat(): string | null
+  get checkedAt(): string
+  get checkFiles(): boolean
+  get editionForced(): boolean
+  get warnings(): number
+  get fyi(): number
+}
+
+/**
+ * Write an AGS4 file's groups to an `.xlsx` — one worksheet per group.
+ * `orderedKeys` forces the worksheet order; otherwise AGS4 source order.
+ */
+export declare function ags4ToExcel(agsPath: string, xlsxPath: string, orderedKeys?: Array<string> | undefined | null): ExcelStats
+
+/**
+ * One applied fix — the Node mirror of laterite-py's `applied[]` entries.
+ * `kind`/`risk` are the serde snake_case strings (`strip_bom`, `safe`, …) so
+ * the shape is identical across Python / CLI / Node.
+ */
+export interface AppliedFix {
+  kind: string
+  label: string
+  rule: string
+  line?: number
+  risk: string
+}
 
 /**
  * AGS spec type code → canonical category label (`"string"`, `"integer"`,
@@ -9,49 +117,106 @@
  * for unknown codes (the TS wrapper re-raises as an error).
  */
 export declare function canonicalType(agsType: string): string | null
+
+/**
+ * Compare two AGS4 documents (raw `a` baseline / `b` revision bytes) — the
+ * revision diff, mirroring laterite-py's `diff()` and the wasm `diff()`.
+ * `dict_version` `None`/`"auto"` resolves the KEY-heading edition from the
+ * revision (`b`)'s `TRAN_AGS`, else forces it; `encoding` decodes both sides
+ * (default UTF-8). Returns the serialised `RevisionDelta` JSON — the shared
+ * `laterite-ags4-diff` leaf's `{groups, groups_added, groups_removed,
+ * total_added, total_removed, total_changed}` shape — that the TS `diff()`
+ * parses. Parse failure throws the mapped error (`NotAgs4Error`, …).
+ */
+export declare function diff(a: Uint8Array, b: Uint8Array, dictVersion?: string | undefined | null, encoding?: string | undefined | null): string
+
 /**
  * Presentation hint for a numeric AGS type: `"2DP"` → `"%.2f"`, `"3SF"` →
  * `"%.3g"`, `"1SCI"` → `"%.1e"`; `null` for non-numeric / unknown codes.
  */
 export declare function displayHint(agsType: string): string | null
+
 /**
- * Parse an AGS4-shaped raw string into its canonical value — the same engine
- * the read path uses. Permissive: empty / unparseable → `null`. Returns native
- * JS: integer/decimal → number, bool → boolean, string/enum → string,
- * **datetime/date/time → the canonical string** (`"YYYY-MM-DD HH:MM:SS"` /
- * `"YYYY-MM-DD"` / `"HH:MM:SS"`), unknown code → the trimmed input.
+ * Build valid AGS4 from per-group **Arrow IPC** streams (the columnar
+ * producer; the read boundary reversed). = `laterite-ags4-wasm`'s `to_ags4_ipc`.
  */
-export declare function parseValue(raw: string | undefined | null, agsType: string): any
+export declare function emitAgs4FromIpc(groups: Array<GroupIpc>, edition?: string | undefined | null, mode?: string | undefined | null, units?: Record<string, Record<string, string>> | undefined | null, types?: Record<string, Record<string, string>> | undefined | null): EmitResult
+
 /**
- * Result of `transportPack` / `transportLock`: output size, ratio vs source,
- * elapsed seconds.
+ * The emit result. `bytes` is the AGS4 document; `findingsJson` is the
+ * validator's `{rule:[…]}` map on the output; `applied` is the safe-fix ledger
+ * AutoFix made (same shape as `fix()`'s `FixReport.applied`); `fixesApplied`
+ * is its length.
  */
-export interface PackStats {
-  bytes: bigint
-  ratio: number
-  elapsedS: number
+export interface EmitResult {
+  bytes: Buffer
+  findingsJson: string
+  applied: Array<AppliedFix>
+  fixesApplied: number
 }
-/** Result of `transportUnpack` / `transportUnlock`: output size, elapsed seconds. */
-export interface UnpackStats {
-  bytes: bigint
-  elapsedS: number
+
+/** The outcome of an Excel conversion (mirrors `laterite_excel::ExcelStats`). */
+export interface ExcelStats {
+  /** Worksheets written (AGS4→XLSX) or read (XLSX→AGS4). */
+  sheetsWritten: number
+  /** DATA rows written across all sheets. */
+  rowsWritten: number
+  /** Non-fatal conversion warnings. */
+  warnings: Array<string>
 }
-/** zstd-compress `src` → `dest`. `level` is 1–22 (default 9, the AGS sweet spot). */
-export declare function transportPack(src: string, dest: string, level?: number | undefined | null): PackStats
-/** zstd-decompress `src` → `dest`. */
-export declare function transportUnpack(src: string, dest: string): UnpackStats
+
 /**
- * zstd-compress, then age-encrypt with `password` → `dest`. Compress-then-
- * encrypt is load-bearing: zstd needs low-entropy input; ciphertext is random.
+ * Read an `.xlsx` back into an AGS4 file. `formatNumericColumns` (default
+ * true) re-applies AGS4 numeric formatting to numeric-looking columns.
  */
-export declare function transportLock(src: string, dest: string, password: string, level?: number | undefined | null): PackStats
+export declare function excelToAgs4(xlsxPath: string, agsPath: string, formatNumericColumns?: boolean | undefined | null): ExcelStats
+
+/** One rule violation (omitting `severity` ⇒ error, matching the engine). */
+export interface Finding {
+  rule: string
+  line?: number
+  group: string
+  desc: string
+  severity?: string
+}
+
 /**
- * age-decrypt with `password`, then zstd-decompress → `dest`. Wrong passphrase
- * / non-passphrase envelopes surface as an error.
+ * Mechanically repair an AGS4 file (`path`) / `text` / `data`: apply the SAFE
+ * fixes (plus the risky set when `includeRisky`), re-validate, and return the
+ * fixed bytes + residual findings. Mirrors laterite-py's `fix()` /
+ * `lat-check --fix`; the single `fix_document` orchestration is shared. The TS
+ * layer wraps this into a `FixResult` (`.bytes` / `.text` / `.save(path)`).
  */
-export declare function transportUnlock(src: string, dest: string, password: string): UnpackStats
-/** The crate version. */
-export declare function version(): string
+export declare function fixFile(path?: string | undefined | null, text?: string | undefined | null, data?: Uint8Array | undefined | null, dictVersion?: string | undefined | null, encoding?: string | undefined | null, includeRisky?: boolean | undefined | null): FixReport
+
+/**
+ * The repair report — the Node mirror of laterite-py's `fix_file` dict. `ok` is
+ * false only for un-fixable input (the TS layer raises then). `fixed` is the
+ * repaired bytes (the original verbatim when nothing applied); `residual` is
+ * what could *not* be mechanically fixed.
+ */
+export interface FixReport {
+  ok: boolean
+  errorKind?: string
+  error?: string
+  exitCode: number
+  fixed: Buffer
+  dictVersion: string
+  resolution: string
+  fixesApplied: number
+  applied: Array<AppliedFix>
+  residual: Array<Finding>
+}
+
+/**
+ * One group of columnar input — its code + an Arrow IPC stream (`Buffer`)
+ * whose column names are the AGS headings.
+ */
+export interface GroupIpc {
+  code: string
+  ipc: Buffer
+}
+
 /** Per-group schema — parallel arrays, one entry per heading. */
 export interface GroupMeta {
   headings: Array<string>
@@ -66,6 +231,24 @@ export interface GroupMeta {
   /** 1-indexed source line of each DATA row (parallel to the group's rows). */
   lineNumbers: Array<number>
 }
+
+/**
+ * The AGS4 rule catalogue as the gated `rules_meta.json` — byte-identical to
+ * laterite-py's `list_rules()` and `lat-check --list-rules --json`. The TS
+ * layer parses it into typed `RuleMeta[]`. No input file.
+ */
+export declare function listRules(): string
+
+/**
+ * Result of `transportPack` / `transportLock`: output size, ratio vs source,
+ * elapsed seconds.
+ */
+export interface PackStats {
+  bytes: bigint
+  ratio: number
+  elapsedS: number
+}
+
 /**
  * Parse an AGS4 file (`path`), in-memory `text`, or raw `data` bytes into a
  * `Reading` handle. `encoding`: `"utf-8"` (default) / `"windows-1252"` / a label
@@ -73,14 +256,61 @@ export interface GroupMeta {
  * `kind␟code␟message` (see the error-protocol note) on bad input.
  */
 export declare function parseArrow(path?: string | undefined | null, text?: string | undefined | null, data?: Uint8Array | undefined | null, encoding?: string | undefined | null): Reading
-/** One rule violation (omitting `severity` ⇒ error, matching the engine). */
-export interface Finding {
-  rule: string
-  line?: number
-  group: string
-  desc: string
-  severity?: string
+
+/**
+ * Parse an AGS4-shaped raw string into its canonical value — the same engine
+ * the read path uses. Permissive: empty / unparseable → `null`. Returns native
+ * JS: integer/decimal → number, bool → boolean, string/enum → string,
+ * **datetime/date/time → the canonical string** (`"YYYY-MM-DD HH:MM:SS"` /
+ * `"YYYY-MM-DD"` / `"HH:MM:SS"`), unknown code → the trimmed input.
+ */
+export declare function parseValue(raw: string | undefined | null, agsType: string): any
+
+/**
+ * The bundled standard dictionary for `edition` as JSON — the
+ * `{ags_edition, groups:[{code, contents, parent, headings:[…]}]}` shape the
+ * browser and `laterite.registry.dictionary()` also render, from the ONE shared
+ * `dict::dictionary_dto` builder (#294 F#6). `None`/`"auto"` → the fallback
+ * edition; else 4.0.3|4.0.4|4.1|4.1.1|4.2. The TS `registry.dictionary()` parses
+ * it. (The generated `GROUPS` stays the default union registry.)
+ */
+export declare function registryDictionaryJson(edition?: string | undefined | null): string
+
+/**
+ * Validate an AGS4 file (`path`) or `text` against the AGS4 rules. `dict_version`
+ * `None`/`"auto"` auto-detects from `TRAN_AGS`, else forces an edition. Returns
+ * the `{ok:false}` failure report (not a throw) for un-validatable input.
+ *
+ * Severity tiers track importance (like a compiler): errors **and WARNINGs** are
+ * returned by default (`includeWarnings` defaults to `true`); pass `false` for
+ * errors-only. `includeFyi` (default `false`) adds the low-signal FYI tier.
+ */
+export declare function runCheck(path?: string | undefined | null, text?: string | undefined | null, data?: Uint8Array | undefined | null, dictVersion?: string | undefined | null, includeWarnings?: boolean | undefined | null, includeFyi?: boolean | undefined | null, checkFiles?: boolean | undefined | null, encoding?: string | undefined | null): ValidationReport
+
+/**
+ * zstd-compress, then age-encrypt with `password` → `dest`. Compress-then-
+ * encrypt is load-bearing: zstd needs low-entropy input; ciphertext is random.
+ */
+export declare function transportLock(src: string, dest: string, password: string, level?: number | undefined | null): PackStats
+
+/** zstd-compress `src` → `dest`. `level` is 1–22 (default 9, the AGS sweet spot). */
+export declare function transportPack(src: string, dest: string, level?: number | undefined | null): PackStats
+
+/**
+ * age-decrypt with `password`, then zstd-decompress → `dest`. Wrong passphrase
+ * / non-passphrase envelopes surface as an error.
+ */
+export declare function transportUnlock(src: string, dest: string, password: string): UnpackStats
+
+/** zstd-decompress `src` → `dest`. */
+export declare function transportUnpack(src: string, dest: string): UnpackStats
+
+/** Result of `transportUnpack` / `transportUnlock`: output size, elapsed seconds. */
+export interface UnpackStats {
+  bytes: bigint
+  elapsedS: number
 }
+
 /**
  * The validation report — the Node mirror of laterite-py's `run_check` dict.
  * `ok` is **false only for un-validatable input** (the TS `raiseFor` raises
@@ -109,109 +339,6 @@ export interface ValidationReport {
   json: string
   ndjson: string
 }
-/**
- * Validate an AGS4 file (`path`) or `text` against the AGS4 rules. `dict_version`
- * `None`/`"auto"` auto-detects from `TRAN_AGS`, else forces an edition. Returns
- * the `{ok:false}` failure report (not a throw) for un-validatable input.
- *
- * Severity tiers track importance (like a compiler): errors **and WARNINGs** are
- * returned by default (`includeWarnings` defaults to `true`); pass `false` for
- * errors-only. `includeFyi` (default `false`) adds the low-signal FYI tier.
- */
-export declare function runCheck(path?: string | undefined | null, text?: string | undefined | null, data?: Uint8Array | undefined | null, dictVersion?: string | undefined | null, includeWarnings?: boolean | undefined | null, includeFyi?: boolean | undefined | null, checkFiles?: boolean | undefined | null, encoding?: string | undefined | null): ValidationReport
-/**
- * The AGS4 rule catalogue as the gated `rules_meta.json` — byte-identical to
- * laterite-py's `list_rules()` and `lat-check --list-rules --json`. The TS
- * layer parses it into typed `RuleMeta[]`. No input file.
- */
-export declare function listRules(): string
-/**
- * One applied fix — the Node mirror of laterite-py's `applied[]` entries.
- * `kind`/`risk` are the serde snake_case strings (`strip_bom`, `safe`, …) so
- * the shape is identical across Python / CLI / Node.
- */
-export interface AppliedFix {
-  kind: string
-  label: string
-  rule: string
-  line?: number
-  risk: string
-}
-/**
- * The repair report — the Node mirror of laterite-py's `fix_file` dict. `ok` is
- * false only for un-fixable input (the TS layer raises then). `fixed` is the
- * repaired bytes (the original verbatim when nothing applied); `residual` is
- * what could *not* be mechanically fixed.
- */
-export interface FixReport {
-  ok: boolean
-  errorKind?: string
-  error?: string
-  exitCode: number
-  fixed: Buffer
-  dictVersion: string
-  resolution: string
-  fixesApplied: number
-  applied: Array<AppliedFix>
-  residual: Array<Finding>
-}
-/**
- * Mechanically repair an AGS4 file (`path`) / `text` / `data`: apply the SAFE
- * fixes (plus the risky set when `includeRisky`), re-validate, and return the
- * fixed bytes + residual findings. Mirrors laterite-py's `fix()` /
- * `lat-check --fix`; the single `fix_document` orchestration is shared. The TS
- * layer wraps this into a `FixResult` (`.bytes` / `.text` / `.save(path)`).
- */
-export declare function fixFile(path?: string | undefined | null, text?: string | undefined | null, data?: Uint8Array | undefined | null, dictVersion?: string | undefined | null, encoding?: string | undefined | null, includeRisky?: boolean | undefined | null): FixReport
-/**
- * One group of columnar input — its code + an Arrow IPC stream (`Buffer`)
- * whose column names are the AGS headings.
- */
-export interface GroupIpc {
-  code: string
-  ipc: Buffer
-}
-/**
- * The emit result. `bytes` is the AGS4 document; `findingsJson` is the
- * validator's `{rule:[…]}` map on the output; `fixesApplied` counts safe fixes.
- */
-export interface EmitResult {
-  bytes: Buffer
-  findingsJson: string
-  fixesApplied: number
-}
-/**
- * Build valid AGS4 from per-group **Arrow IPC** streams (the columnar
- * producer; the read boundary reversed). = `laterite-ags4-wasm`'s `to_ags4_ipc`.
- */
-export declare function emitAgs4FromIpc(groups: Array<GroupIpc>, edition?: string | undefined | null, mode?: string | undefined | null): EmitResult
-/**
- * A parsed AGS4 file held native-side — the Node analog of laterite-py's
- * `Reading` handle (and `laterite-ags4-wasm`'s `ParsedDataset`). Each group's typed
- * `RecordBatch` is built lazily on `tableIpc(code)` and dropped after the
- * bytes are returned, so peak residency is one batch.
- */
-export declare class Reading {
-  /** Group codes in file order (the order to load tables in). */
-  groupCodes(): Array<string>
-  /** The file's `TRAN_AGS` edition string, if present. */
-  get tranAgs(): string | null
-  /**
-   * `{headings, units, types, sqlTypes}` for one group, or `null` if the
-   * code isn't present. No Arrow built — cheap metadata only.
-   */
-  meta(code: string): GroupMeta | null
-  /**
-   * One group's rows as an Arrow **IPC stream** (`Buffer`), columns already
-   * correctly typed. The Node analog of the pyo3-arrow capsule: the typed
-   * columns come from the one shared emitter (`laterite_types::arrow_cols`), the
-   * SAME casting Python/wasm use — so a file types byte-identically across
-   * hosts. Returns `null` if the code isn't in the file.
-   */
-  tableIpc(code: string): Buffer | null
-  /**
-   * Re-emit byte-faithful AGS4 text from the retained parse (the raw DATA
-   * values, unchanged). = laterite-py's `Reading::emit`.
-   */
-  emit(): string
-}
+
+/** The crate version. */
+export declare function version(): string