@imferno/node 3.0.2-beta.1b73397 → 3.0.2-beta.2427eb9

package/README.md

@@ -22,15 +22,17 @@ Prebuilt binaries are provided for:
 
 ### Validate a package on disk
 
-```js
-import { buildReportFromPath } from "@imferno/node";
+```ts
+import { validatePath } from "@imferno/node";
 
-const report = buildReportFromPath("./my-imp");
+const { package: pkg, validation } = validatePath("./my-imp");
 
-console.log("Compliant:", report.validation.is_compliant);
-console.log("Errors:", report.validation.errors.length);
-console.log("Warnings:", report.validation.warnings.length);
-console.log("CPLs:", report.package.cplCount);
+console.log("Compliant:", validation.is_compliant);
+console.log("Errors:", validation.errors.length);
+for (const issue of validation.errors) {
+  console.log(issue.severity, issue.code, issue.message, issue.location.file);
+}
+console.log("CPLs:", Object.keys(pkg.compositionPlaylists).length);
 ```
 
 ### Validate from a URI (filesystem or S3)
@@ -54,10 +56,10 @@ const report = buildReportFromUri("s3://my-bucket/path/to/imp/", {
 
 ### Validate with options
 
-```js
-import { buildReportFromPath } from "@imferno/node";
+```ts
+import { validatePath, type PathValidateOptions } from "@imferno/node";
 
-const report = buildReportFromPath("./my-imp", {
+const options: PathValidateOptions = {
   coreSpec: "v2020",
   app2eSpec: "v2023",
   skipDiskChecks: true,
@@ -65,15 +67,16 @@ const report = buildReportFromPath("./my-imp", {
     "ST2067-21:2023:7.1/AppIdMismatch": "error",
     "IMFERNO:Package/UnreferencedAsset": "off",
   },
-});
+};
+const result = validatePath("./my-imp", options);
 ```
 
 ### Validate from in-memory strings
 
 ```js
-import { buildReport } from "@imferno/node";
+import { validate } from "@imferno/node";
 
-const report = buildReport({
+const result = validate({
   "ASSETMAP.xml": assetmapXml,
   "PKL_abc.xml": pklXml,
   "CPL_def.xml": cplXml,
@@ -83,10 +86,10 @@ const report = buildReport({
 ### Pretty-print a report
 
 ```js
-import { buildReportFromPath, formatReport } from "@imferno/node";
+import { validatePath, formatReport } from "@imferno/node";
 
-const report = buildReportFromPath("./my-imp");
-console.log(formatReport(report));
+const result = validatePath("./my-imp");
+console.log(formatReport(result)); // same text as `imferno validate`
 ```
 
 ### Get the library version
@@ -109,7 +112,7 @@ console.log(getVersion()); // e.g. "2.0.0"
 | `buildReport(files, options?)` | Legacy: validate from strings (returns `ImfReport`) |
 | `buildReportFromPath(path, options?)` | Legacy: validate from disk (returns `ImfReport`) |
 | `buildReportFromUri(uri, options?)` | Legacy: validate via URI (returns `ImfReport`) |
-| `formatReport(report)` | Pretty-print a report as a human-readable string |
+| `formatReport(result)` | Pretty-print a `ValidationResult` (or legacy `ImfReport`) as text |
 | `listRules()` | Get the full catalogue of validation rule codes |
 | `getVersion()` | Get the library version |
 
@@ -119,8 +122,34 @@ console.log(getVersion()); // e.g. "2.0.0"
 |--------|------|-------------|
 | `coreSpec` | `"auto" \| "v2013" \| "v2016" \| "v2020"` | Core constraints spec version |
 | `app2eSpec` | `"auto" \| "none" \| "v2014" \| "v2016" \| "v2020" \| "v2023" \| "v2026"` | Application spec version |
-| `skipDiskChecks` | `boolean` | Skip file manifest and MXF checks (`buildReportFromPath` only) |
-| `rules` | `Record<string, "error" \| "warn" \| "info" \| "off">` | ESLint-style per-rule severity overrides |
+| `rules` | `Record<string, "off" \| "info" \| "warn" \| "error" \| "critical">` | ESLint-style per-rule severity overrides |
+| `aggregateRepeats` | `boolean` | Collapse repeated identical findings into one issue with `additional_instances` |
+| `skipDiskChecks` | `boolean` | Skip file manifest and MXF checks (path / URI functions only; in-memory input never touches disk) |
+| `credentials` | `S3Credentials \| null` | Explicit S3 credentials (URI functions only) |
+
+### TypeScript
+
+The package ships precise declarations, generated from the Rust types (no
+`any`). Every function is synchronous. All value types are exported from the
+main entry:
+
+```ts
+import type {
+  ValidationResult,   // validate*, { package, validation }
+  Imferno,            // parsePackage*, the full parsed package
+  ImfReport,          // buildReport* (legacy)
+  ValidationIssue,    // severity, category, code, message, location, ...
+  ValidateOptions,    // coreSpec, app2eSpec, rules, aggregateRepeats
+  PathValidateOptions,
+  UriValidateOptions,
+  RuleInfo,           // listRules() entries
+} from "@imferno/node";
+```
+
+Field casing follows the serialised output: the validation report uses
+snake_case (`is_compliant`, `cpl_id`), the parsed package uses camelCase at the
+top level (`compositionPlaylists`) and the SMPTE element names inside CPLs
+(`ContentTitle`, `SegmentList`).
 
 ### Return types
 
@@ -133,6 +162,7 @@ console.log(getVersion()); // e.g. "2.0.0"
     "is_compliant": true,
     "is_playable": true,
     "profile": "SMPTE",
+    "timestamp": "2026-01-01T12:00:00.000000+00:00",
     "critical": [],
     "errors": [],
     "warnings": [],

package/codes.d.ts

@@ -3,6 +3,11 @@ export declare const codes: {
   readonly ST429_9_2014: {
     readonly VolindexMissing: "ST429-9:2014:7/VolindexMissing";
     readonly MalformedXml: "ST429-9:2014:7/MalformedXml";
+    readonly PathNotRelative: "ST429-9:2014:A.2/PathNotRelative";
+    readonly PathCharacters: "ST429-9:2014:A.2/PathCharacters";
+    readonly PathTooLong: "ST429-9:2014:A.2/PathTooLong";
+    readonly PathTooManySegments: "ST429-9:2014:A.2/PathTooManySegments";
+    readonly PathDuplicate: "ST429-9:2014:A.2/PathDuplicate";
   };
   readonly ST377_1_2011: {
     readonly NotMxf: "ST377-1:2011:5/NotMxf";
@@ -12,6 +17,7 @@ export declare const codes: {
     readonly NonHeaderFirstPartition: "ST377-1:2011:6.4/NonHeaderFirstPartition";
     readonly HeaderPartitionOpen: "ST377-1:2011:8.3.3/HeaderPartitionOpen";
     readonly MissingHeaderMetadata: "ST377-1:2011:8.3.3/MissingHeaderMetadata";
+    readonly StructuralComponentDurationMissing: "ST377-1:2011:B.8/StructuralComponentDurationMissing";
   };
   readonly ST2067_2_2020: {
     readonly AssetMap: "ST2067-2:2020:7/AssetMap";
@@ -22,6 +28,7 @@ export declare const codes: {
     readonly FileNotFound: "ST2067-2:2020:8.3/FileNotFound";
     readonly ChecksumMismatch: "ST2067-2:2020:8.3/ChecksumMismatch";
     readonly UnresolvedUuid: "ST2067-2:2020:7/UnresolvedUuid";
+    readonly TrackFileNotInPackage: "ST2067-2:2020:7.1/TrackFileNotInPackage";
     readonly DuplicateUuid: "ST2067-2:2020:7/DuplicateUuid";
     readonly IoError: "IMF:General/IoError";
     readonly EssenceDescriptorList: "ST2067-2:2020:6.4.2/EssenceDescriptorList";
@@ -387,6 +394,8 @@ export declare const codes: {
     readonly J2CLayout: "ST2067-21:2026:7.5.2/J2CLayout";
     readonly J2KExtendedCapabilities: "ST2067-21:2026:7.5.1/J2KExtendedCapabilities";
     readonly JPEG2000SubDescriptor: "ST2067-21:2026:7.5.1/JPEG2000SubDescriptor";
+    readonly HTIRVParameterBMax: "ST2067-21:2026:H/HT-IRV-ParameterB-Max";
+    readonly HTIRVParameterBRecommended: "ST2067-21:2026:H/HT-IRV-ParameterB-Recommended";
     readonly J2K4KResolution: "ST2067-21:2026:7.2.5/J2K-4K-Resolution";
     readonly J2K2KResolution: "ST2067-21:2026:7.2.5/J2K-2K-Resolution";
     readonly J2KBCPResolution: "ST2067-21:2026:7.2.5/J2K-BCP-Resolution";
@@ -468,5 +477,6 @@ export declare const codes: {
     readonly ReadDirError: "IMFERNO:Package/ReadDirError";
     readonly DirEntryError: "IMFERNO:Package/DirEntryError";
     readonly PathTraversal: "IMFERNO:Package/PathTraversal";
+    readonly ApplicationProfileNotValidated: "IMFERNO:Package/ApplicationProfileNotValidated";
   }
 };

package/codes.js

@@ -3,6 +3,11 @@ const codes = {
   ST429_9_2014: {
     VolindexMissing: "ST429-9:2014:7/VolindexMissing",
     MalformedXml: "ST429-9:2014:7/MalformedXml",
+    PathNotRelative: "ST429-9:2014:A.2/PathNotRelative",
+    PathCharacters: "ST429-9:2014:A.2/PathCharacters",
+    PathTooLong: "ST429-9:2014:A.2/PathTooLong",
+    PathTooManySegments: "ST429-9:2014:A.2/PathTooManySegments",
+    PathDuplicate: "ST429-9:2014:A.2/PathDuplicate",
   },
   ST377_1_2011: {
     NotMxf: "ST377-1:2011:5/NotMxf",
@@ -12,6 +17,7 @@ const codes = {
     NonHeaderFirstPartition: "ST377-1:2011:6.4/NonHeaderFirstPartition",
     HeaderPartitionOpen: "ST377-1:2011:8.3.3/HeaderPartitionOpen",
     MissingHeaderMetadata: "ST377-1:2011:8.3.3/MissingHeaderMetadata",
+    StructuralComponentDurationMissing: "ST377-1:2011:B.8/StructuralComponentDurationMissing",
   },
   ST2067_2_2020: {
     AssetMap: "ST2067-2:2020:7/AssetMap",
@@ -22,6 +28,7 @@ const codes = {
     FileNotFound: "ST2067-2:2020:8.3/FileNotFound",
     ChecksumMismatch: "ST2067-2:2020:8.3/ChecksumMismatch",
     UnresolvedUuid: "ST2067-2:2020:7/UnresolvedUuid",
+    TrackFileNotInPackage: "ST2067-2:2020:7.1/TrackFileNotInPackage",
     DuplicateUuid: "ST2067-2:2020:7/DuplicateUuid",
     IoError: "IMF:General/IoError",
     EssenceDescriptorList: "ST2067-2:2020:6.4.2/EssenceDescriptorList",
@@ -387,6 +394,8 @@ const codes = {
     J2CLayout: "ST2067-21:2026:7.5.2/J2CLayout",
     J2KExtendedCapabilities: "ST2067-21:2026:7.5.1/J2KExtendedCapabilities",
     JPEG2000SubDescriptor: "ST2067-21:2026:7.5.1/JPEG2000SubDescriptor",
+    HTIRVParameterBMax: "ST2067-21:2026:H/HT-IRV-ParameterB-Max",
+    HTIRVParameterBRecommended: "ST2067-21:2026:H/HT-IRV-ParameterB-Recommended",
     J2K4KResolution: "ST2067-21:2026:7.2.5/J2K-4K-Resolution",
     J2K2KResolution: "ST2067-21:2026:7.2.5/J2K-2K-Resolution",
     J2KBCPResolution: "ST2067-21:2026:7.2.5/J2K-BCP-Resolution",
@@ -468,6 +477,7 @@ const codes = {
     ReadDirError: "IMFERNO:Package/ReadDirError",
     DirEntryError: "IMFERNO:Package/DirEntryError",
     PathTraversal: "IMFERNO:Package/PathTraversal",
+    ApplicationProfileNotValidated: "IMFERNO:Package/ApplicationProfileNotValidated",
   }
 };
 module.exports = { codes };

package/index.d.ts

@@ -1,102 +1,170 @@
-/* auto-generated by NAPI-RS */
+/* auto-generated by NAPI-RS (`napi build`) — edit src/lib.rs or dts-header.d.ts instead */
 /* eslint-disable */
 
-/**
- * Returns the imferno library version string.
- */
-export declare function getVersion(): string
+import type {
+  Category,
+  ImfReport,
+  Imferno,
+  ValidateOptions,
+  ValidationResult,
+} from "./types";
+
+export * from "./types";
+export { codes } from "./codes";
+
+/** Options for validating a package on disk (`validatePath`, `buildReportFromPath`). */
+export interface PathValidateOptions extends ValidateOptions {
+  /** Skip file-manifest (size/presence) and MXF header checks. Default: `false`. */
+  skipDiskChecks?: boolean;
+}
+
+/** Explicit S3 credentials for `s3://` URIs. Omit to use the default AWS credential chain. */
+export interface S3Credentials {
+  accessKeyId: string;
+  secretAccessKey: string;
+  sessionToken?: string;
+  region?: string;
+  endpoint?: string;
+}
+
+/** Options for `validateUri` / `buildReportFromUri`. */
+export interface UriValidateOptions extends PathValidateOptions {
+  /** Ignored for filesystem URIs. */
+  credentials?: S3Credentials | null;
+}
+
+/** Which rule catalogue a code belongs to. */
+export type RuleSpec =
+  | "core"
+  | "cpl"
+  | "app2e"
+  | "volindex"
+  | "mxf"
+  | "scm"
+  | "isxd"
+  | "iab"
+  | "imferno";
+
+/** One entry of the `listRules()` catalogue. */
+export interface RuleInfo {
+  /** Normalised rule code, usable as a `rules` key. */
+  code: string;
+  spec: RuleSpec;
+  description: string;
+  defaultSeverity: "info" | "warning" | "error" | "critical";
+  category: Extract<Category, string>;
+  /** Present when this edition's code set is identical to an earlier edition's (that edition's prefix). */
+  sameAsPreviousEdition?: string;
+}
 
 /**
- * Validate an IMF package from in-memory XML strings.
+ * Validate an IMF package from in-memory XML strings, returning the legacy
+ * `ImfReport` summary. Prefer `validate` for new code.
+ *
+ * Disk checks are always skipped (there is no package on disk).
  *
  * @param files - A map of filename to XML content (e.g. `{ "ASSETMAP.xml": "..." }`)
- * @param options - Optional validation options (`coreSpec`, `app2eSpec`, `rules`, etc.)
- * @returns An `ImfReport` object with `package`, `cpls`, and `validation` fields.
+ * @param options - Optional validation options (`coreSpec`, `app2eSpec`, `rules`, `aggregateRepeats`)
+ * @returns An `ImfReport` with `package`, `cpls`, and `validation` fields.
+ * @throws If the package cannot be parsed or the options are invalid.
  */
-export declare function buildReport(files: Record<string, string>, options?: any | undefined | null): any
+export declare function buildReport(files: Record<string, string>, options?: ValidateOptions | undefined | null): ImfReport
 
 /**
- * Validate an IMF package directory on disk.
+ * Validate an IMF package directory on disk, returning the legacy
+ * `ImfReport` summary. Prefer `validatePath` for new code.
  *
  * @param path - Path to the IMP directory
- * @param options - Optional validation options (`coreSpec`, `app2eSpec`, `skipDiskChecks`, `rules`, etc.)
- * @returns An `ImfReport` object with `package`, `cpls`, and `validation` fields.
+ * @param options - Optional validation options (`coreSpec`, `app2eSpec`, `skipDiskChecks`, `rules`, `aggregateRepeats`)
+ * @returns An `ImfReport` with `package`, `cpls`, and `validation` fields.
+ * @throws If the directory cannot be read, the package cannot be parsed, or the options are invalid.
  */
-export declare function buildReportFromPath(path: string, options?: any | undefined | null): any
+export declare function buildReportFromPath(path: string, options?: PathValidateOptions | undefined | null): ImfReport
 
 /**
- * Pretty-print an `ImfReport` as a human-readable string.
+ * Build the legacy `ImfReport` summary from a URI. Accepts the same URI forms
+ * as `validateUri`; prefer `validateUri` for new code.
  *
- * @param report - A previously returned `ImfReport` object
- * @returns A formatted plain-text report string.
+ * @param uri - Path or URI to the IMP
+ * @param options - Optional validation options
+ * @returns An `ImfReport` with `package`, `cpls`, and `validation` fields.
+ * @throws If the URI cannot be read, the package cannot be parsed, or the options are invalid.
  */
-export declare function formatReport(report: any): string
+export declare function buildReportFromUri(uri: string, options?: UriValidateOptions | undefined | null): ImfReport
 
 /**
- * Parse an IMF package from in-memory XML strings, returning the full parsed package.
+ * Pretty-print a validation result as a human-readable string.
  *
- * Unlike `buildReport` which returns a validation summary, this returns the
- * complete `Imferno` struct with all essence descriptors, locales, content versions, etc.
+ * @param report - The object returned by `validate*`, or (legacy) by `buildReport*`
+ * @returns A formatted plain-text report.
+ * @throws If `report` is neither a `ValidationResult` nor an `ImfReport`.
+ */
+export declare function formatReport(report: ValidationResult | ImfReport): string
+
+/** Returns the imferno library version string. */
+export declare function getVersion(): string
+
+/**
+ * Returns the engine's full catalogue of validation rule codes, one entry per
+ * per-spec enum variant. Useful for building settings UIs that render a
+ * configurable severity dropdown per rule. The shape is stable JSON, so
+ * downstream callers can store severity overrides keyed by `code`.
+ */
+export declare function listRules(): RuleInfo[]
+
+/**
+ * Parse an IMF package from in-memory XML strings, returning the full parsed
+ * package without validating it.
  *
  * @param files - A map of filename to XML content (e.g. `{ "ASSETMAP.xml": "..." }`)
- * @returns The full parsed Imferno package object.
+ * @returns The full parsed `Imferno` package.
+ * @throws If the package cannot be parsed.
  */
-export declare function parsePackage(files: Record<string, string>): any
+export declare function parsePackage(files: Record<string, string>): Imferno
 
 /**
- * Parse an IMF package directory on disk, returning the full parsed package.
- *
- * Unlike `buildReportFromPath` which returns a validation summary, this returns the
- * complete `Imferno` struct with all essence descriptors, locales, content versions, etc.
+ * Parse an IMF package directory on disk, returning the full parsed package
+ * without validating it.
  *
  * @param path - Path to the IMP directory
- * @returns The full parsed Imferno package object.
+ * @returns The full parsed `Imferno` package.
+ * @throws If the directory cannot be read or the package cannot be parsed.
  */
-export declare function parsePackageFromPath(path: string): any
+export declare function parsePackageFromPath(path: string): Imferno
 
 /**
- * Parse and validate an IMF package from in-memory XML strings.
+ * Parse and validate an IMF package from in-memory XML strings. This is the
+ * recommended entry point.
  *
- * This is the recommended entry point. Returns the full parsed package
- * plus all validation findings.
+ * Parse failures are reported as findings in `validation`, not thrown.
+ * Disk checks are always skipped (there is no package on disk).
  *
  * @param files - A map of filename to XML content
  * @param options - Optional validation options
- * @returns `{ package, validation }` — full Imferno struct + ValidationReport
+ * @returns `{ package, validation }` — the full parsed package and all findings.
+ * @throws Only if the options are invalid.
  */
-export declare function validate(files: Record<string, string>, options?: any | undefined | null): any
+export declare function validate(files: Record<string, string>, options?: ValidateOptions | undefined | null): ValidationResult
 
 /**
  * Parse and validate an IMF package directory on disk.
  *
  * @param path - Path to the IMP directory
  * @param options - Optional validation options
- * @returns `{ package, validation }` — full Imferno struct + ValidationReport
+ * @returns `{ package, validation }` — the full parsed package and all findings.
+ * @throws If the directory cannot be read or the options are invalid.
  */
-export declare function validatePath(path: string, options?: any | undefined | null): any
+export declare function validatePath(path: string, options?: PathValidateOptions | undefined | null): ValidationResult
 
 /**
  * Parse and validate an IMF package from a URI.
  *
- * Accepts `file://` URIs, bare filesystem paths, and (when the binary is built
- * with the `aws-s3` feature) `s3://bucket/prefix/` URIs. The prebuilt binaries
- * on npm include `aws-s3` enabled.
- *
- * @param uri - Path or URI to the IMP
- * @param options - Optional validation options
- * @returns `{ package, validation }` — full Imferno struct + ValidationReport
- */
-export declare function validateUri(uri: string, options?: any | undefined | null): any
-
-/**
- * Build an ImfReport summary from a URI.
- *
- * Accepts the same URI forms as `validateUri`. Prefer `validateUri` for new
- * code — `buildReportFromUri` is kept for parity with `buildReport` /
- * `buildReportFromPath`.
+ * Accepts `file://` URIs, bare filesystem paths, and (when built with the
+ * `aws-s3` feature, as the prebuilt npm binaries are) `s3://bucket/prefix/`.
  *
  * @param uri - Path or URI to the IMP
- * @param options - Optional validation options
- * @returns An `ImfReport` object with `package`, `cpls`, and `validation` fields.
+ * @param options - Optional validation options (plus `credentials` for S3)
+ * @returns `{ package, validation }` — the full parsed package and all findings.
+ * @throws If the URI cannot be read or the options are invalid.
  */
-export declare function buildReportFromUri(uri: string, options?: any | undefined | null): any
+export declare function validateUri(uri: string, options?: UriValidateOptions | undefined | null): ValidationResult

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imferno/node",
-  "version": "3.0.2-beta.1b73397",
+  "version": "3.0.2-beta.2427eb9",
   "description": "Native Node.js bindings for the imferno SMPTE ST 2067 IMF validator",
   "main": "index.js",
   "module": "index.mjs",
@@ -26,25 +26,31 @@
       "aarch64-unknown-linux-gnu",
       "x86_64-pc-windows-msvc",
       "aarch64-pc-windows-msvc"
-    ]
+    ],
+    "dtsHeaderFile": "dts-header.d.ts"
   },
   "files": [
     "index.js",
     "index.mjs",
     "index.d.ts",
+    "types.d.ts",
     "codes.js",
     "codes.mjs",
     "codes.d.ts",
     "README.md",
     "LICENSE"
   ],
+  "scripts": {
+    "build": "napi build --release",
+    "test": "vitest run"
+  },
   "optionalDependencies": {
-    "@imferno/node-darwin-arm64": "3.0.2-beta.1b73397",
-    "@imferno/node-darwin-x64": "3.0.2-beta.1b73397",
-    "@imferno/node-linux-x64-gnu": "3.0.2-beta.1b73397",
-    "@imferno/node-linux-arm64-gnu": "3.0.2-beta.1b73397",
-    "@imferno/node-win32-x64-msvc": "3.0.2-beta.1b73397",
-    "@imferno/node-win32-arm64-msvc": "3.0.2-beta.1b73397"
+    "@imferno/node-darwin-arm64": "3.0.2-beta.2427eb9",
+    "@imferno/node-darwin-x64": "3.0.2-beta.2427eb9",
+    "@imferno/node-linux-x64-gnu": "3.0.2-beta.2427eb9",
+    "@imferno/node-linux-arm64-gnu": "3.0.2-beta.2427eb9",
+    "@imferno/node-win32-x64-msvc": "3.0.2-beta.2427eb9",
+    "@imferno/node-win32-arm64-msvc": "3.0.2-beta.2427eb9"
   },
   "publishConfig": {
     "access": "public"
@@ -60,5 +66,18 @@
   },
   "engines": {
     "node": ">=16.0.0"
+  },
+  "devDependencies": {
+    "@napi-rs/cli": "3.10.12",
+    "ajv": "^8.20.0",
+    "json-schema-to-typescript": "16.0.0",
+    "prettier": "3.9.10",
+    "ts-json-schema-generator": "2.9.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  },
+  "overrides": {
+    "prettier": "3.9.10",
+    "@apidevtools/json-schema-ref-parser": "11.9.3"
   }
 }