@faceless-photolib/diagnostics
Runtime diagnostics for faceless-photolib — warnNotImplemented / warnDegraded / warnUnexpected beacons backed by a dedup registry, used instead of // TODO comments.
Runtime diagnostics for faceless-photolib — a headless, color-managed, GPU-accelerated image-editing engine.
Instead of dead // TODO / // FIXME comments, unfinished or degraded code paths fire a
diagnostic the first time they execute: deduplicated, greppable, and inspectable at runtime.
Install
pnpm add @faceless-photolib/diagnosticsUsage
import {
warnNotImplemented,
warnDegraded,
warnUnexpected,
getDiagnostics,
NotImplemented,
} from "@faceless-photolib/diagnostics";
// An unfinished branch returns a typed error carrying category + detail.
function lower(effect: string) {
if (effect === "vibrance") return warnNotImplemented("blend", "vibrance not implemented");
// ...
}
// A working-but-degraded path records a beacon and keeps going.
warnDegraded("backend-cpu", "ACES RRT not applied; using color-managed convert");
// Something genuinely unexpected, with structured context.
warnUnexpected("codec", "unknown ICC tag", { tag });
// Inspect everything recorded so far (e.g. to surface in a UI panel).
for (const record of getDiagnostics()) {
console.warn(`[${record.severity}] ${record.category}: ${record.detail} ×${record.count}`);
}API
| Export | Description |
|---|---|
warnNotImplemented(category, detail) | Records a not-implemented beacon and returns a NotImplemented error value. |
warnDegraded(category, detail) | Records a degraded beacon for a working-but-lossy path. |
warnUnexpected(category, detail, data?) | Records an unexpected beacon, retaining structured data on first sight. |
getDiagnostics() | Returns the deduplicated registry (severity + category + detail, with a hit count). |
resetDiagnostics() | Clears the registry (test isolation). |
NotImplemented | The typed error value returned by warnNotImplemented. |
Records are deduplicated by severity + category + detail; repeated hits increment count
rather than spamming. Severities are not-implemented, degraded, and unexpected.
License
MIT
API reference
8 public exports · 8 documented · generated from source.
getDiagnosticsfunctiongetDiagnostics(): readonly DiagnosticRecord[]Snapshot of every recorded beacon, for inspection in tests and UI panels.
resetDiagnosticsfunctionresetDiagnostics(): voidClear the registry. Intended for test isolation.
warnDegradedfunctionwarnDegraded(context: string, detail: string): voidBeacon for a path that produced a result via a documented, lower-fidelity fallback (e.g. an uncalibrated Special-8 Fill response, or a WebGL2 degraded node). Fires once per unique `context + detail`.
warnNotImplementedfunctionwarnNotImplemented(category: string, detail: string): NotImplementedBeacon for a code path that is recognized but not yet implemented. Fires `console.warn` once per unique `category + detail`, records the beacon, and **returns** a `NotImplemented` error so callers can `throw warnNotImplemented(...)` in a single expression. Never silently falls through to an identity result.
warnUnexpectedfunctionwarnUnexpected(context: string, detail: string, data?: unknown): voidBeacon for a genuinely unexpected condition (a "this should not happen" branch) carrying optional structured data for diagnosis. Fires once per unique `context + detail`.
NotImplementedclassclass NotImplementedError thrown by stub bodies that have not yet been implemented. Carries the diagnostic `category` and `detail` so a caller catching it can re-surface the same information that the `warnNotImplemented` beacon recorded. Bodies whose return type is a `Result`/`Resource` SHOULD return a `rejected("not-implemented", …)` variant instead of throwing; bodies that cannot express absence in their return type `throw warnNotImplemented(...)`.
DiagnosticRecordtypetype DiagnosticRecordA single recorded beacon. `count` increments each time the same key fires.
DiagnosticSeveritytypetype DiagnosticSeverityThe three kinds of beacon the engine emits instead of `// TODO`/`// FIXME`/`// HACK`.
@faceless-photolib/schemas
Zod schemas as the single source of truth for faceless-photolib types — branded IDs, the Result/Resource vocabulary, the Layer discriminated union, color spaces, transforms, and masks.
@faceless-photolib/color
Color science for faceless-photolib — transfer functions, RGB/XYZ primaries, Bradford chromatic adaptation, and OCIO-style hub-and-spoke conversions through an ACEScg (AP1) scene-linear connection space.