@flighthq/importdiagnostics 0.2.1-next.701.409c279

package/dist/importDiagnosticCollector.d.ts

@@ -0,0 +1,4 @@
+import type { ImportDiagnostic, ImportDiagnosticSeverity } from '@flighthq/types';
+export declare function collectImportDiagnostics(run: (sink: ImportDiagnostic[]) => void): ImportDiagnostic[];
+export declare function reportImportDiagnostic(sink: ImportDiagnostic[] | undefined, severity: ImportDiagnosticSeverity, kind: string, origin: string, detail?: Readonly<Record<string, boolean | number | string>>): void;
+//# sourceMappingURL=importDiagnosticCollector.d.ts.map

package/dist/importDiagnosticCollector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"importDiagnosticCollector.d.ts","sourceRoot":"","sources":["../src/importDiagnosticCollector.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,wBAAwB,EAAE,MAAM,iBAAiB,CAAC;AAiBlF,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,CAAC,IAAI,EAAE,gBAAgB,EAAE,KAAK,IAAI,GAAG,gBAAgB,EAAE,CAIpG;AAcD,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,gBAAgB,EAAE,GAAG,SAAS,EACpC,QAAQ,EAAE,wBAAwB,EAClC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC,CAAC,GAC3D,IAAI,CAGN"}

package/dist/importDiagnosticCollector.js

@@ -0,0 +1,37 @@
+// The collector seam for importer diagnostics: where crumbs are recorded, and the opt-in that engages
+// the recording. An `ImportDiagnostic[]` sink IS the collector — parsers write to it through
+// `reportImportDiagnostic`; consumers create and drain one through `collectImportDiagnostics`.
+// The opt-in engagement surface: runs `run` with a fresh collector installed and returns the crumbs it
+// emitted, as plain data agents and tests can assert on. Engaging a collector is the ONLY thing that
+// makes a parser record — the default parse (no collector) stays near-free and records nothing. Import
+// it to inspect what an importer dropped/skipped/recovered/rejected; it and the text machinery it feeds
+// (`formatImportDiagnostic`, per-package `explain*`) shed from a production bundle that never opts in.
+//
+// This is the importer analogue of an `explain*` query, but it COLLECTS during the single consume-once
+// parse pass instead of re-walking the drop conditions in a duplicate implementation — so it can never
+// drift out of sync with the parser the way a hand-mirrored explainer would.
+//
+// Usage: `collectImportDiagnostics((sink) => parseAwd2(bytes, sink))`.
+export function collectImportDiagnostics(run) {
+    const diagnostics = [];
+    run(diagnostics);
+    return diagnostics;
+}
+// The colocated seam every `*-formats` parser calls at a data-dropping branch. When `sink` is
+// undefined — the default parse path, where no caller engaged a collector — it does nothing, so an
+// unopted parse pays only this single `undefined` check and no crumb is built or allocated. `kind` is a
+// stable dot-namespaced code that lives here at the drop site (never a central registry, so it vanishes
+// when the branch is removed); `origin` is the emitting function's own name (the true origin, not a
+// wrapper); `detail` is a minimal plain-data tag, never prose (the words live in `formatImportDiagnostic`).
+//
+// PERF CONTRACT (the normal path must not slow): the call sits INSIDE the drop branch, so a well-formed
+// parse never reaches it. In a HOT LOOP (per-vertex/per-element validation) do NOT call this per element
+// — aggregate the offenders and report once after the loop (a count in `detail`), so no engaged-or-not
+// per-element seam cost exists. `detail` is evaluated by the caller before the call, so keep it a small
+// literal built only within the (rare, non-hot) drop branch.
+export function reportImportDiagnostic(sink, severity, kind, origin, detail) {
+    if (sink === undefined)
+        return;
+    sink.push({ detail, kind, origin, severity });
+}
+//# sourceMappingURL=importDiagnosticCollector.js.map

package/dist/importDiagnosticCollector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"importDiagnosticCollector.js","sourceRoot":"","sources":["../src/importDiagnosticCollector.ts"],"names":[],"mappings":"AAEA,sGAAsG;AACtG,6FAA6F;AAC7F,+FAA+F;AAE/F,uGAAuG;AACvG,qGAAqG;AACrG,uGAAuG;AACvG,wGAAwG;AACxG,uGAAuG;AACvG,EAAE;AACF,uGAAuG;AACvG,uGAAuG;AACvG,6EAA6E;AAC7E,EAAE;AACF,uEAAuE;AACvE,MAAM,UAAU,wBAAwB,CAAC,GAAuC;IAC9E,MAAM,WAAW,GAAuB,EAAE,CAAC;IAC3C,GAAG,CAAC,WAAW,CAAC,CAAC;IACjB,OAAO,WAAW,CAAC;AACrB,CAAC;AAED,8FAA8F;AAC9F,mGAAmG;AACnG,wGAAwG;AACxG,wGAAwG;AACxG,oGAAoG;AACpG,4GAA4G;AAC5G,EAAE;AACF,wGAAwG;AACxG,yGAAyG;AACzG,uGAAuG;AACvG,wGAAwG;AACxG,6DAA6D;AAC7D,MAAM,UAAU,sBAAsB,CACpC,IAAoC,EACpC,QAAkC,EAClC,IAAY,EACZ,MAAc,EACd,MAA4D;IAE5D,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO;IAC/B,IAAI,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,CAAC;AAChD,CAAC"}

package/dist/importDiagnosticText.d.ts

@@ -0,0 +1,3 @@
+import type { ImportDiagnostic } from '@flighthq/types';
+export declare function formatImportDiagnostic(diagnostic: Readonly<ImportDiagnostic>): string;
+//# sourceMappingURL=importDiagnosticText.d.ts.map

package/dist/importDiagnosticText.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"importDiagnosticText.d.ts","sourceRoot":"","sources":["../src/importDiagnosticText.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AASxD,wBAAgB,sBAAsB,CAAC,UAAU,EAAE,QAAQ,CAAC,gBAAgB,CAAC,GAAG,MAAM,CAQrF"}

package/dist/importDiagnosticText.js

@@ -0,0 +1,17 @@
+// The human-text side of an import diagnostic — kept in its own concept module so a production bundle
+// that records crumbs (or never engages diagnostics at all) sheds every byte of the text machinery.
+// Renders one ImportDiagnostic crumb as a stable human-readable line for logs or a CLI. Shape:
+// `<severity> <origin>: <kind>[ key=value …]`, detail keys sorted for deterministic output. Pure and
+// never throws; allocates only on this opt-in formatting path (the returned string, plus a sorted keys
+// array when the crumb carries detail) — a bundle that never expands a crumb sheds it entirely.
+export function formatImportDiagnostic(diagnostic) {
+    const { detail, kind, origin, severity } = diagnostic;
+    let detailText = '';
+    if (detail !== undefined) {
+        const keys = Object.keys(detail).sort();
+        for (const key of keys)
+            detailText += ` ${key}=${detail[key]}`;
+    }
+    return `${severity} ${origin}: ${kind}${detailText}`;
+}
+//# sourceMappingURL=importDiagnosticText.js.map

package/dist/importDiagnosticText.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"importDiagnosticText.js","sourceRoot":"","sources":["../src/importDiagnosticText.ts"],"names":[],"mappings":"AAEA,sGAAsG;AACtG,oGAAoG;AAEpG,+FAA+F;AAC/F,qGAAqG;AACrG,uGAAuG;AACvG,gGAAgG;AAChG,MAAM,UAAU,sBAAsB,CAAC,UAAsC;IAC3E,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,UAAU,CAAC;IACtD,IAAI,UAAU,GAAG,EAAE,CAAC;IACpB,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC;QACxC,KAAK,MAAM,GAAG,IAAI,IAAI;YAAE,UAAU,IAAI,IAAI,GAAG,IAAI,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;IACjE,CAAC;IACD,OAAO,GAAG,QAAQ,IAAI,MAAM,KAAK,IAAI,GAAG,UAAU,EAAE,CAAC;AACvD,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from './importDiagnosticCollector';
+export * from './importDiagnosticText';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,6BAA6B,CAAC;AAC5C,cAAc,wBAAwB,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export * from './importDiagnosticCollector';
+export * from './importDiagnosticText';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,6BAA6B,CAAC;AAC5C,cAAc,wBAAwB,CAAC"}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@flighthq/importdiagnostics",
+  "version": "0.2.1-next.701.409c279",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/flighthq/flight.git",
+    "directory": "packages/importdiagnostics"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src/**/*.test.ts",
+    "!dist/**/*.test.js",
+    "!dist/**/*.test.d.ts",
+    "!dist/**/*.test.js.map",
+    "!dist/**/*.test.d.ts.map"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "clean": "tsc -b --clean",
+    "test": "vitest run --config vitest.config.ts",
+    "test:watch": "vitest --watch --config vitest.config.ts",
+    "prepack": "npm run clean && npm run clean:dist && npm run build",
+    "clean:dist": "tsx ../../scripts/clean-package-dist.ts"
+  },
+  "dependencies": {
+    "@flighthq/types": "0.2.1-next.701.409c279"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.0"
+  },
+  "description": "Shared structured-diagnostics seam for the *-formats importers — reportImportDiagnostic colocates a stable-kind ImportDiagnostic at each parser data-dropping branch (a no-op when no collector is passed, so an unopted parse pays only one undefined check), collectImportDiagnostics runs a parse with a collector installed as the drift-free explain* alternative to re-walking drop conditions, and formatImportDiagnostic renders one line for humans; deps types only, sideEffects false",
+  "sideEffects": false
+}

package/src/importDiagnosticCollector.test.ts

@@ -0,0 +1,55 @@
+import type { ImportDiagnostic } from '@flighthq/types';
+import { ImportDiagnosticSeverity } from '@flighthq/types';
+import { describe, expect, it } from 'vitest';
+
+import { collectImportDiagnostics, reportImportDiagnostic } from './importDiagnosticCollector';
+
+describe('collectImportDiagnostics', () => {
+  it('returns the crumbs the run callback emits into its engaged collector', () => {
+    // Stands in for `collectImportDiagnostics((sink) => parseAwd2(bytes, sink))`.
+    const diagnostics = collectImportDiagnostics((sink) => {
+      reportImportDiagnostic(sink, ImportDiagnosticSeverity.Skip, 'awd2.method-material', 'resolveAwdMaterial', {
+        count: 2,
+      });
+      reportImportDiagnostic(sink, ImportDiagnosticSeverity.Reject, 'awd2.unsupported-version', 'parseAwd2', {
+        version: 3,
+      });
+    });
+    expect(diagnostics).toHaveLength(2);
+    expect(diagnostics.map((d) => d.kind)).toEqual(['awd2.method-material', 'awd2.unsupported-version']);
+  });
+
+  it('returns an empty array when the parse emits nothing (well-formed input)', () => {
+    expect(collectImportDiagnostics(() => {})).toEqual([]);
+  });
+});
+
+describe('reportImportDiagnostic', () => {
+  it('pushes a structured crumb onto the collector when one is engaged', () => {
+    const sink: ImportDiagnostic[] = [];
+    reportImportDiagnostic(sink, ImportDiagnosticSeverity.Drop, 'awd2.skin-vertex-mismatch', 'buildAwdSkin', {
+      actual: 3,
+      expected: 4,
+    });
+    expect(sink).toHaveLength(1);
+    expect(sink[0]).toEqual({
+      detail: { actual: 3, expected: 4 },
+      kind: 'awd2.skin-vertex-mismatch',
+      origin: 'buildAwdSkin',
+      severity: 'Drop',
+    });
+  });
+
+  it('carries the detail through undefined when none is supplied', () => {
+    const sink: ImportDiagnostic[] = [];
+    reportImportDiagnostic(sink, ImportDiagnosticSeverity.Reject, 'md2.bad-magic', 'parseMd2');
+    expect(sink[0].detail).toBeUndefined();
+    expect(sink[0].severity).toBe('Reject');
+  });
+
+  it('does nothing (no throw, no allocation) when the collector is undefined — the default silent path', () => {
+    expect(() =>
+      reportImportDiagnostic(undefined, ImportDiagnosticSeverity.Drop, 'gltf.accessor-out-of-bounds', 'readAccessor'),
+    ).not.toThrow();
+  });
+});

package/src/importDiagnosticText.test.ts

@@ -0,0 +1,25 @@
+import { ImportDiagnosticSeverity } from '@flighthq/types';
+import { describe, expect, it } from 'vitest';
+
+import { formatImportDiagnostic } from './importDiagnosticText';
+
+describe('formatImportDiagnostic', () => {
+  it('renders severity, origin, and kind with detail keys sorted', () => {
+    const line = formatImportDiagnostic({
+      detail: { expected: 4, actual: 3 },
+      kind: 'awd2.skin-vertex-mismatch',
+      origin: 'buildAwdSkin',
+      severity: ImportDiagnosticSeverity.Drop,
+    });
+    expect(line).toBe('Drop buildAwdSkin: awd2.skin-vertex-mismatch actual=3 expected=4');
+  });
+
+  it('omits the detail section when there is no detail', () => {
+    const line = formatImportDiagnostic({
+      kind: 'md2.bad-magic',
+      origin: 'parseMd2',
+      severity: ImportDiagnosticSeverity.Reject,
+    });
+    expect(line).toBe('Reject parseMd2: md2.bad-magic');
+  });
+});