@axiapps/axilog 0.1.1

package/README.md

@@ -0,0 +1,119 @@
+# @axiapps/axilog
+
+Node bindings ([napi-rs](https://napi.rs)) for axilog's Rust GW2 arcdps WvW
+parsing core. Every export is a thin wrapper around the same
+decode → resolve → analyze → build_report pipeline the CLI
+(`axilog-cli`) drives — see `src/lib.rs`'s module doc for the exact FFI
+contract (no Rust panic ever crosses the boundary; every fallible step
+becomes a `napi::Error` carrying the underlying Rust error text).
+
+## Usage
+
+```js
+// CommonJS
+const { parseFile, parseBuffer, parseFileEi, anonymizeFile } = require('@axiapps/axilog')
+```
+
+```ts
+// ESM / TypeScript
+import { parseFile, parseBuffer, parseFileEi, anonymizeFile } from '@axiapps/axilog'
+import type { Report } from '@axiapps/axilog/types'
+```
+
+```js
+// Native report (axilog_schema::Report — schema_version, encounter,
+// players[], enemies[], timeline, warnings), typed as `Report` (see
+// "Types" below).
+const report = parseFile('./fight.zevtc')
+console.log(report.schema_version, report.players.length)
+
+// Same pipeline, from an already-read Buffer.
+const fs = require('fs')
+const reportFromBuffer = parseBuffer(fs.readFileSync('./fight.zevtc'))
+
+// Elite Insights-compatibility JSON (axilog_ei::to_ei_json) — the shape
+// axibridge-style consumers read (players[].account, dpsAll[0].damage,
+// support[0].condiCleanse, buffUptimes[], targets[].enemyPlayer,
+// wvWMapData.{red,blue,green}TeamID). Untyped (`any`) — see "Types" below.
+const ei = parseFileEi('./fight.zevtc')
+
+// Rewrite every player's character/account name in a .zevtc to a
+// deterministic Anon<N> placeholder (does not mutate metrics — safe for
+// producing PII-safe fixtures). Returns the number of player agents
+// rewritten.
+const rewritten = anonymizeFile('./fight.zevtc', './fight.anon.zevtc')
+```
+
+All four functions throw a plain `Error` (never a raw Rust panic) on
+failure — e.g. a missing file, a corrupt/unsupported `.evtc`.
+
+## Build
+
+```sh
+npm install
+npm run build        # napi build --platform --release, then patches index.d.ts (see "Types")
+npm run build:debug  # same, unoptimized (faster iteration)
+npm test              # node --test __test__/*.test.mjs
+```
+
+`npm run build`/`npm run build:debug` compile the Rust crate
+(`crates/axilog-node`) to a platform-specific `.node` addon (e.g.
+`axilog.linux-x64-gnu.node`) and regenerate `index.js`/`index.d.ts` via
+`@napi-rs/cli`.
+
+## Tests
+
+`__test__/sdk.test.mjs` (`node --test`, Node >= 18) covers, against the
+committed PII-safe fixture `fixtures/wvw-small.anon.zevtc` (repo-root
+relative, resolved from the test file's own location so it works from any
+cwd):
+
+- `parseFile`: `schema_version`, player count, squad damage total, one
+  boon uptime value, and the four support-stat squad sums — all pinned to
+  this fixture's exact calibrated values (see
+  `crates/axilog-core/tests/golden.rs`/`support_golden.rs` for how those
+  numbers were derived against a real dps.report EI export).
+- `parseBuffer` deep-equals `parseFile`.
+- `parseFileEi`: the specific keys axibridge-style consumers read
+  (`players[].account`, `dpsAll[0].damage`, `support[0].condiCleanse`,
+  non-empty `buffUptimes`, `targets[].enemyPlayer` booleans,
+  `wvWMapData`'s three team ids).
+- `anonymizeFile` round-trip: writes to a tmpdir, re-parses, checks player
+  count/metrics are unchanged (anonymization only rewrites names).
+- Missing-file error path: throws a real `Error` with a non-empty message.
+- **Dual-path parity**: builds nothing itself, but shells out to the
+  already-built CLI (`cargo build -p axilog-cli`; run that first if
+  `target/debug/axilog` is missing) and asserts
+  `axilog parse <fixture> --format json` parsed, deep-equals `parseFile`'s
+  return value — with a small first-N-differing-paths diff helper so a
+  future divergence prints something readable instead of two giant JSON
+  blobs.
+
+## Types
+
+`index.d.ts` is generated by `@napi-rs/cli` from `src/lib.rs`'s exported
+function signatures. Because every export returns a plain
+`serde_json::Value` (not a `#[napi(object)]`-derived struct — see
+`src/lib.rs`'s module doc for why), napi's typegen has no visibility into
+the actual JSON shape and can only emit `any` for `parseFile`/
+`parseBuffer`'s return type.
+
+To close that gap without hand-editing a generated file (which `napi
+build` would silently overwrite), this crate adds:
+
+- **`types.d.ts`** — a hand-maintained transcription of
+  `axilog_schema::Report` (`crates/axilog-schema/src/lib.rs`, the serde
+  struct definitions are the source of truth — keep this file in sync with
+  that one if the schema changes).
+- **`scripts/patch-dts.mjs`** — a small idempotent postbuild step (wired
+  into both `npm run build` and `npm run build:debug`) that patches the
+  freshly-regenerated `index.d.ts` to `import type { Report } from
+  './types'` and retypes `parseFile`/`parseBuffer`'s return type from
+  `any` to `Report`. Because it runs as part of the build script itself
+  (not a one-off manual edit), the reference survives every future `napi
+  build` regeneration instead of needing to be reapplied by hand.
+
+`parseFileEi`'s return value is a materially different, larger EI-JSON
+shape (not a serialized `Report`) and is intentionally left `any` — typing
+it faithfully is out of scope for this task (see `crates/axilog-ei/src/
+lib.rs`'s doc comments for what fields it does/doesn't carry).

package/index.d.ts

@@ -0,0 +1,91 @@
+/* auto-generated by NAPI-RS */
+import type { Report } from './types'
+/* eslint-disable */
+/**
+ * Rewrites every player's character/account name in the `.zevtc` at
+ * `in_path` to a deterministic `Anon<N>` placeholder and writes the
+ * result to `out_path` (same transform as `axilog anonymize` / the core
+ * `anonymize_raw_evtc` function -- reused here, not duplicated). Returns
+ * the number of player agents rewritten.
+ */
+export declare function anonymizeFile(inPath: string, outPath: string): number
+
+/**
+ * Parses an already-read `.evtc`/`.zevtc` buffer and returns the native
+ * `Report` as a plain JS object. `opts.replay` (M9, Task 2) opts into
+ * embedding the native combat-replay block; `opts.skill_damage` (M12,
+ * Task 1) opts into embedding the native per-skill damage distribution
+ * block; `opts.missiles` (final-review fix wave) opts into embedding the
+ * native top-level missile analytics block.
+ */
+export declare function parseBuffer(buf: Buffer, opts?: ParseOptions | undefined | null): Report
+
+/**
+ * Parses a `.evtc`/`.zevtc` file at `path` and returns the native
+ * `Report` as a plain JS object (see module docs for the field-name
+ * behavior). `opts.replay` (M9, Task 2) opts into embedding the native
+ * combat-replay block; omitted entirely for back-compat with every
+ * existing zero-arg call site.
+ */
+export declare function parseFile(path: string, opts?: ParseOptions | undefined | null): Report
+
+/**
+ * Parses a `.evtc`/`.zevtc` file at `path` and returns the Elite
+ * Insights-compatibility JSON (`axilog_ei::to_ei_json`) as a plain JS
+ * object. `opts` (final-review fix wave) accepts the same `ParseOptions`
+ * shape `parseFile`/`parseBuffer` do -- `opts.skill_damage`/
+ * `opts.timeseries` are what actually let `totalDamageDist`/`damage1S`/
+ * `dpsTargets`/etc (M12, Task 3's ei-json mapping) surface in the
+ * returned JSON, since `axilog_ei::to_ei_json` reads them straight off
+ * the native `Report` this function builds internally; previously this
+ * function always built that `Report` with both flags forced `false`,
+ * silently discarding any M12 detail regardless of what a caller wanted
+ * (axibridge consumes ei-json exclusively through this function). `opts.
+ * replay`/`opts.missiles` are accepted for parity with `parseFile` but
+ * have no effect on the output -- EI's JSON shape has no comparable field
+ * for either (see `axilog_ei::to_ei_json`'s module doc). Omitting `opts`
+ * entirely keeps every existing zero-arg call site's behavior unchanged.
+ */
+export declare function parseFileEi(path: string, opts?: ParseOptions | undefined | null): any
+
+/**
+ * Optional per-call parse settings (M9, Task 2). `replay: true` opts into
+ * computing and embedding the native combat-replay block (`ReplayOut`) in
+ * the returned `Report`; omitted (or `false`, or the argument itself
+ * omitted entirely -- napi treats a trailing `Option<T>` parameter as
+ * optional in the generated TypeScript signature) keeps the existing
+ * zero-arg call shape's behavior unchanged (no `replay` key in the
+ * output, matching `Report.replay`'s serde skip-when-absent).
+ * `skill_damage: true` (M12, Task 1) opts into embedding the native
+ * per-skill damage distribution block (`SkillDamageOut`) on every
+ * `players[]` entry -- see `axilog_schema::Report::players`'s
+ * `PlayerOut::skill_damage` doc comment for why this defaults to opt-in
+ * (measured +249% JSON size on the committed fixture when always-on).
+ * `timeseries: true` (M12, Task 2) opts into embedding the native
+ * per-player per-second series block (`PlayerPerSecondOut`) AND the
+ * per-enemy `dps_targets` summary on every `players[]` entry -- see
+ * `axilog_schema::Report::players`'s `PlayerOut::per_second`/`PlayerOut::
+ * dps_targets` doc comments (measured +147.7%/+36.4% JSON size
+ * respectively on the committed fixture when always-on -- `dps_targets`
+ * is NOT small on a real WvW log with many enemies, so both stay behind
+ * this one flag).
+ * `missiles: true` (final-review fix wave) opts into embedding the
+ * native top-level missile (projectile) analytics block
+ * (`Report::missiles`), mirroring the CLI's `--missiles` flag -- see
+ * `axilog_core::analysis::missiles`'s module doc for exactly what it
+ * contains. Omitted (or `false`) keeps `Report.missiles` absent, matching
+ * its serde skip-when-`None`.
+ * `rotation: true` (M14, Task 1) opts into embedding the native
+ * per-player rotation (cast tracking) block (`SkillRotationOut[]`) on
+ * every `players[]` entry -- see `axilog_schema::Report::players`'s
+ * `PlayerOut::rotation` doc comment for why this defaults to opt-in
+ * (well past the ~30% size-discipline guideline on the committed fixture
+ * when always-on).
+ */
+export interface ParseOptions {
+  replay?: boolean
+  skillDamage?: boolean
+  timeseries?: boolean
+  missiles?: boolean
+  rotation?: boolean
+}