@lde/distribution-health 0.1.1 → 0.1.3

package/README.md

@@ -32,3 +32,6 @@ into a SKOS failure scheme (`<scheme>#${reason}`) with no lookup table.
 
 The normative usability rule and the rejected alternatives are recorded in the
 PRD: netwerk-digitaal-erfgoed/dataset-register#2103.
+
+<!-- 0.1.1 was published to npm without its dist/; this republishes the package with the build output. -->
+

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { importOutcomeToVerdict, probeResultToVerdict, type ValidityVerdict, type ValidityFailureReason, type ValidityDepth, } from './verdict.js';
+export { usability, type Reachability, type Usability, type UsabilityState, type UsabilityCause, } from './usability.js';
+//# 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,OAAO,EACL,sBAAsB,EACtB,oBAAoB,EACpB,KAAK,eAAe,EACpB,KAAK,qBAAqB,EAC1B,KAAK,aAAa,GACnB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,SAAS,EACT,KAAK,YAAY,EACjB,KAAK,SAAS,EACd,KAAK,cAAc,EACnB,KAAK,cAAc,GACpB,MAAM,gBAAgB,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export { importOutcomeToVerdict, probeResultToVerdict, } from './verdict.js';
+export { usability, } from './usability.js';

package/dist/usability.d.ts

@@ -0,0 +1,35 @@
+import type { ValidityVerdict } from './verdict.js';
+/** The single derived health verdict consumers act on. */
+export type UsabilityState = 'usable' | 'unusable' | 'unknown';
+/**
+ * Why a distribution is not plainly `usable`. Carried separately from the
+ * state so a consumer can render the reason without re-deriving it.
+ */
+export type UsabilityCause = 'invalid' | 'unreachable' | 'no-verdict' | 'stale-verdict';
+/** The currently-observed reachability of a distribution. */
+export interface Reachability {
+    /** Whether the distribution could be fetched (HTTP/SPARQL level). */
+    reachable: boolean;
+    /**
+     * The source fingerprint observed on this reachability check – the shared
+     * key against which a validity verdict’s `validatedFingerprint` is matched.
+     */
+    fingerprint: string | null;
+}
+/** Result of the usability rollup. */
+export interface Usability {
+    state: UsabilityState;
+    cause?: UsabilityCause;
+    /**
+     * Set when the state rests on a shallow verdict only (no deep verdict
+     * applied), so a consumer can mark the result as not yet deeply confirmed.
+     */
+    shallow?: true;
+}
+/**
+ * Roll reachability and validity verdict(s) up into the one canonical
+ * usability verdict. Reachability dominates: an unreachable distribution is
+ * unusable regardless of any validity verdict.
+ */
+export declare function usability(reachability: Reachability, verdicts: readonly ValidityVerdict[]): Usability;
+//# sourceMappingURL=usability.d.ts.map

package/dist/usability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usability.d.ts","sourceRoot":"","sources":["../src/usability.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAEpD,0DAA0D;AAC1D,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,UAAU,GAAG,SAAS,CAAC;AAE/D;;;GAGG;AACH,MAAM,MAAM,cAAc,GACtB,SAAS,GACT,aAAa,GACb,YAAY,GACZ,eAAe,CAAC;AAEpB,6DAA6D;AAC7D,MAAM,WAAW,YAAY;IAC3B,qEAAqE;IACrE,SAAS,EAAE,OAAO,CAAC;IACnB;;;OAGG;IACH,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAED,sCAAsC;AACtC,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,cAAc,CAAC;IACtB,KAAK,CAAC,EAAE,cAAc,CAAC;IACvB;;;OAGG;IACH,OAAO,CAAC,EAAE,IAAI,CAAC;CAChB;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CACvB,YAAY,EAAE,YAAY,EAC1B,QAAQ,EAAE,SAAS,eAAe,EAAE,GACnC,SAAS,CAkBX"}

package/dist/usability.js

@@ -0,0 +1,43 @@
+/**
+ * Roll reachability and validity verdict(s) up into the one canonical
+ * usability verdict. Reachability dominates: an unreachable distribution is
+ * unusable regardless of any validity verdict.
+ */
+export function usability(reachability, verdicts) {
+    if (!reachability.reachable) {
+        return { state: 'unusable', cause: 'unreachable' };
+    }
+    const chosen = chooseVerdict(verdicts, reachability.fingerprint);
+    if (chosen === undefined) {
+        // A verdict that exists but no longer matches the observed fingerprint has
+        // gone stale (e.g. a since-fixed dump); distinguish that from never having
+        // been judged at all, so a stale negative stops showing as broken.
+        const cause = verdicts.length > 0 ? 'stale-verdict' : 'no-verdict';
+        return { state: 'unknown', cause };
+    }
+    const flag = chosen.depth === 'shallow' ? { shallow: true } : {};
+    return chosen.valid
+        ? { state: 'usable', ...flag }
+        : { state: 'unusable', cause: 'invalid', ...flag };
+}
+/**
+ * The authoritative verdict among those still fresh against the
+ * currently-observed fingerprint, or `undefined` when none apply. A deep
+ * verdict beats a shallow one; freshness is decided by the staleness gate.
+ */
+function chooseVerdict(verdicts, currentFingerprint) {
+    const fresh = verdicts.filter((verdict) => isFresh(verdict, currentFingerprint));
+    return fresh.find((verdict) => verdict.depth === 'deep') ?? fresh[0];
+}
+/**
+ * Whether a verdict still applies to the currently-observed source. A verdict
+ * applies only if the fingerprint it was judged against equals the current
+ * one; a `null` fingerprint never compares equal (mirroring
+ * `sourceFingerprint`), so an unfingerprintable source is never considered
+ * fresh.
+ */
+function isFresh(verdict, currentFingerprint) {
+    return (currentFingerprint !== null &&
+        verdict.validatedFingerprint !== null &&
+        verdict.validatedFingerprint === currentFingerprint);
+}

package/dist/verdict.d.ts

@@ -0,0 +1,38 @@
+import { ImportFailed, ImportSuccessful } from '@lde/sparql-importer';
+import { type ProbeResultType } from '@lde/distribution-probe';
+/**
+ * Why a distribution’s RDF was judged invalid. The local names are chosen to
+ * map 1:1 onto a consumer’s SKOS failure scheme (`<scheme>#${reason}`, no lookup
+ * table), mirroring how `@lde/iiif-validator`’s reason enum maps to NDE’s
+ * `manifest-validation-failure#`.
+ */
+export type ValidityFailureReason = 'parse-error' | 'empty';
+/** How thoroughly validity was assessed. */
+export type ValidityDepth = 'shallow' | 'deep';
+/**
+ * A verdict on whether a distribution’s fetched content parses as RDF.
+ *
+ * `reason` and `message` are present only when `valid` is `false`. The verdict
+ * carries the `validatedFingerprint` it was judged against so a consumer can
+ * tell whether it still applies to the currently-observed source.
+ */
+export interface ValidityVerdict {
+    valid: boolean;
+    reason?: ValidityFailureReason;
+    message?: string;
+    validatedFingerprint: string | null;
+    depth: ValidityDepth;
+}
+/**
+ * Map a deep import outcome (full parse) to a validity verdict. A failed import
+ * is invalid RDF; a successful one is valid.
+ */
+export declare function importOutcomeToVerdict(outcome: ImportFailed | ImportSuccessful, validatedFingerprint: string | null): ValidityVerdict;
+/**
+ * Map a shallow probe result to a validity verdict, or `null` when the probe
+ * carries no validity signal (a network or HTTP-level failure, or a body the
+ * probe did not parse). This is the shallow producer: it interprets the body
+ * validation `@lde/distribution-probe` already performs for small RDF dumps.
+ */
+export declare function probeResultToVerdict(result: ProbeResultType, validatedFingerprint: string | null): ValidityVerdict | null;
+//# sourceMappingURL=verdict.d.ts.map

package/dist/verdict.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verdict.d.ts","sourceRoot":"","sources":["../src/verdict.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AACtE,OAAO,EAEL,KAAK,eAAe,EACrB,MAAM,yBAAyB,CAAC;AAEjC;;;;;GAKG;AACH,MAAM,MAAM,qBAAqB,GAAG,aAAa,GAAG,OAAO,CAAC;AAE5D,4CAA4C;AAC5C,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,MAAM,CAAC;AAE/C;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,CAAC,EAAE,qBAAqB,CAAC;IAC/B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,oBAAoB,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,KAAK,EAAE,aAAa,CAAC;CACtB;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,YAAY,GAAG,gBAAgB,EACxC,oBAAoB,EAAE,MAAM,GAAG,IAAI,GAClC,eAAe,CAoBjB;AA6BD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,eAAe,EACvB,oBAAoB,EAAE,MAAM,GAAG,IAAI,GAClC,eAAe,GAAG,IAAI,CA4BxB"}

package/dist/verdict.js

@@ -0,0 +1,96 @@
+import { ImportSuccessful } from '@lde/sparql-importer';
+import { DataDumpProbeResult, } from '@lde/distribution-probe';
+/**
+ * Map a deep import outcome (full parse) to a validity verdict. A failed import
+ * is invalid RDF; a successful one is valid.
+ */
+export function importOutcomeToVerdict(outcome, validatedFingerprint) {
+    if (outcome instanceof ImportSuccessful) {
+        if (outcome.tripleCount === 0) {
+            return {
+                valid: false,
+                reason: 'empty',
+                validatedFingerprint,
+                depth: 'deep',
+            };
+        }
+        return { valid: true, validatedFingerprint, depth: 'deep' };
+    }
+    return {
+        valid: false,
+        reason: 'parse-error',
+        message: outcome.error,
+        validatedFingerprint,
+        depth: 'deep',
+    };
+}
+// The probe’s `failureReason` strings that signal an empty distribution rather
+// than a parse error. Mirrors `validateBody` in `@lde/distribution-probe`.
+const EMPTY_FAILURE_REASONS = new Set([
+    'Distribution is empty',
+    'Distribution contains no RDF triples',
+]);
+// Content types `@lde/distribution-probe` parse-validates; a successful probe
+// of one of these is positive evidence the body parsed. Mirrors
+// `rdfContentTypes` there. (Duplicated rather than imported because the probe
+// does not export it; a structured validity signal on the probe result would
+// remove this coupling — see #468.)
+const PROBE_PARSED_CONTENT_TYPES = new Set([
+    'text/turtle',
+    'application/n-triples',
+    'application/n-quads',
+    'application/trig',
+    'text/n3',
+    'application/ld+json',
+    'application/rdf+xml',
+]);
+// The probe only fetches and parses bodies at or below this size; larger ones
+// are HEAD-checked only, so a success carries no validity signal. Mirrors the
+// threshold in `probeDataDump`.
+const PROBE_PARSE_LIMIT_BYTES = 10_240;
+/**
+ * Map a shallow probe result to a validity verdict, or `null` when the probe
+ * carries no validity signal (a network or HTTP-level failure, or a body the
+ * probe did not parse). This is the shallow producer: it interprets the body
+ * validation `@lde/distribution-probe` already performs for small RDF dumps.
+ */
+export function probeResultToVerdict(result, validatedFingerprint) {
+    if (!(result instanceof DataDumpProbeResult)) {
+        return null;
+    }
+    if (result.failureReason !== null) {
+        if (EMPTY_FAILURE_REASONS.has(result.failureReason)) {
+            return {
+                valid: false,
+                reason: 'empty',
+                validatedFingerprint,
+                depth: 'shallow',
+            };
+        }
+        return {
+            valid: false,
+            reason: 'parse-error',
+            message: result.failureReason,
+            validatedFingerprint,
+            depth: 'shallow',
+        };
+    }
+    if (result.isSuccess() && probeParsedBody(result)) {
+        return { valid: true, validatedFingerprint, depth: 'shallow' };
+    }
+    return null;
+}
+/**
+ * Whether the probe actually parsed this distribution’s body – the only
+ * grounds on which a `valid: true` shallow verdict may rest. True when the
+ * content type is one the probe parse-validates and the body was small enough
+ * to have been fetched rather than only HEAD-checked.
+ */
+function probeParsedBody(result) {
+    const serialization = result.contentType?.split(';')[0].trim();
+    if (serialization === undefined ||
+        !PROBE_PARSED_CONTENT_TYPES.has(serialization)) {
+        return false;
+    }
+    return (result.contentSize === null || result.contentSize <= PROBE_PARSE_LIMIT_BYTES);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lde/distribution-health",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "repository": {
     "url": "git+https://github.com/ldelements/lde.git",
     "directory": "packages/distribution-health"
@@ -24,7 +24,7 @@
     "!**/*.tsbuildinfo"
   ],
   "dependencies": {
-    "@lde/distribution-probe": "0.1.10",
+    "@lde/distribution-probe": "0.1.11",
     "@lde/sparql-importer": "0.6.5",
     "tslib": "^2.3.0"
   },