@lde/pipeline-shacl-validator 0.11.2 → 0.12.1

package/README.md

@@ -3,18 +3,28 @@
 SHACL validation for [`@lde/pipeline`](../pipeline).
 
 Validates RDF quads produced by pipeline stages against [SHACL shapes](https://www.w3.org/TR/shacl/),
-writing per-dataset report files in SHACL validation report format.
-Shapes can be provided in any RDF serialization (Turtle, JSON-LD, N-Triples etc.).
+streaming the per-dataset SHACL validation report to any number of configured
+[`Writer`](../pipeline/src/writer/writer.ts)s. Shapes can be provided in any
+RDF serialization (Turtle, JSON-LD, N-Triples etc.).
 
 ## Usage
 
 ```typescript
-import { Pipeline, Stage, SparqlConstructExecutor } from '@lde/pipeline';
+import {
+  Pipeline,
+  Stage,
+  SparqlConstructExecutor,
+  FileWriter,
+  SparqlUpdateWriter,
+} from '@lde/pipeline';
 import { ShaclValidator } from '@lde/pipeline-shacl-validator';
 
 const validator = new ShaclValidator({
   shapesFile: './shapes.ttl',
-  reportDir: './validation',
+  reportWriters: [
+    new FileWriter({ outputDir: './validation', format: 'turtle' }),
+    new SparqlUpdateWriter({ endpoint: new URL('http://store/update') }),
+  ],
 });
 
 const pipeline = new Pipeline({
@@ -42,16 +52,54 @@ await pipeline.run();
 | `'skip'`  | Discard invalid quads silently                                   |
 | `'halt'`  | Throw an error, stopping the pipeline                            |
 
-### Report files
+### Report writers
 
-Validation violations are written to `<reportDir>/<dataset-iri>.validation.<ext>`
-as SHACL validation report triples. The output format defaults to Turtle (`.ttl`)
-and can be changed with the `reportFormat` option:
+Each `validate()` call that produces violations fans the SHACL report quads
+(`sh:ValidationResult` triples, etc.) out to every configured `reportWriter`
+via `Writer.write(dataset, quads)`. Each writer's `Writer.flush(dataset)` is
+invoked from `ShaclValidator.report(dataset)` — i.e. once the pipeline
+finishes a dataset.
 
-```typescript
-const validator = new ShaclValidator({
-  shapesFile: './shapes.ttl',
-  reportDir: './validation',
-  reportFormat: 'N-Triples', // 'Turtle' (default) | 'N-Triples' | 'N-Quads'
+Validators with no `reportWriters` only produce aggregate counts
+(`{ conforms, violations, quadsValidated }`); the report quads themselves are
+discarded. This is deliberate — callers who only need pass/fail metrics
+don't have to wire up a sink — but it does mean misconfiguring (passing
+`reportWriters: []` while expecting persistence) silently loses violation
+detail. Configure at least one writer in production pipelines.
+
+The bundled `FileWriter` and `SparqlUpdateWriter` already implement the
+`Writer` contract; bring your own for custom destinations.
+
+#### Filesystem collisions with `FileWriter`
+
+`FileWriter` derives its filename from `dataset.iri` only. If the pipeline's
+main writer and a report writer both target the same `outputDir` with the
+same format, they will collide on the same path and the second open will
+truncate the first. Use a separate `outputDir` for validation reports:
+
+```ts
+new ShaclValidator({
+  shapesFile,
+  reportWriters: [new FileWriter({ outputDir: './output/validation' })],
+});
+```
+
+#### Named graphs with `SparqlUpdateWriter`
+
+`SparqlUpdateWriter` defaults to `dataset.iri.toString()` as the named graph
+URI. A report writer that shares the endpoint with the pipeline's main
+writer would otherwise land the SHACL report in the same graph as the
+dataset's data — and `CLEAR GRAPH` on first write per dataset would erase
+it. To keep validation results in a separate graph, pass `graphIri` to
+derive the target graph from the dataset:
+
+```ts
+new SparqlUpdateWriter({
+  endpoint,
+  auth,
+  graphIri: (dataset) =>
+    new URL(
+      `https://example.org/shacl-validation/${encodeURIComponent(dataset.iri.toString())}`,
+    ),
 });
 ```

package/dist/shacl-validator.d.ts

@@ -1,34 +1,36 @@
 import type { Quad } from '@rdfjs/types';
 import type { Dataset } from '@lde/dataset';
-import type { Validator, ValidationResult, ValidationReport } from '@lde/pipeline';
-import { type SerializationFormat } from '@lde/pipeline';
+import type { Validator, ValidationResult, ValidationReport, Writer } from '@lde/pipeline';
 /** Options for {@link ShaclValidator}. */
 export interface ShaclValidatorOptions {
     /** Path to an RDF file containing SHACL shapes (any format supported by rdf-dereference). */
     shapesFile: string;
-    /** Directory for validation report files. */
-    reportDir: string;
-    /** Serialization format for report files. @default 'Turtle' */
-    reportFormat?: SerializationFormat;
+    /**
+     * Writers that receive the per-dataset SHACL validation report quads. Each
+     * batch with violations is streamed to every writer via {@link Writer.write};
+     * each writer's {@link Writer.flush} is called from {@link ShaclValidator.report}.
+     *
+     * Pass a {@link FileWriter} to mirror the previous on-disk behaviour, a
+     * {@link SparqlUpdateWriter} to land reports in a named graph, or any custom
+     * writer. Validators with no `reportWriters` only produce aggregate counts.
+     */
+    reportWriters?: Writer[];
 }
 /**
  * SHACL-based {@link Validator} for `@lde/pipeline`.
  *
  * Validates quads against shapes loaded from an RDF file (any format
- * supported by rdf-dereference) and writes per-dataset report files
- * in SHACL validation report format.
+ * supported by rdf-dereference) and streams the per-dataset SHACL validation
+ * report to any number of configured {@link Writer}s.
  */
 export declare class ShaclValidator implements Validator {
     private readonly shapesFile;
-    private readonly reportDir;
-    private readonly reportFormat;
+    private readonly reportWriters;
     private shapesDataset;
     private readonly accumulators;
-    private readonly initializedFiles;
     constructor(options: ShaclValidatorOptions);
     validate(quads: Quad[], dataset: Dataset): Promise<ValidationResult>;
     report(dataset: Dataset): Promise<ValidationReport>;
     private getShapes;
-    private writeReportFile;
 }
 //# sourceMappingURL=shacl-validator.d.ts.map

package/dist/shacl-validator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shacl-validator.d.ts","sourceRoot":"","sources":["../src/shacl-validator.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AACzC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAE5C,OAAO,KAAK,EACV,SAAS,EACT,gBAAgB,EAChB,gBAAgB,EACjB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAkB,KAAK,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAezE,0CAA0C;AAC1C,MAAM,WAAW,qBAAqB;IACpC,6FAA6F;IAC7F,UAAU,EAAE,MAAM,CAAC;IACnB,6CAA6C;IAC7C,SAAS,EAAE,MAAM,CAAC;IAClB,+DAA+D;IAC/D,YAAY,CAAC,EAAE,mBAAmB,CAAC;CACpC;AAQD;;;;;;GAMG;AACH,qBAAa,cAAe,YAAW,SAAS;IAC9C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAsB;IAEnD,OAAO,CAAC,aAAa,CAAkB;IACvC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAyC;IACtE,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAqB;gBAE1C,OAAO,EAAE,qBAAqB;IAMpC,QAAQ,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAmCpE,MAAM,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,gBAAgB,CAAC;YAc3C,SAAS;YAUT,eAAe;CA0B9B"}
+{"version":3,"file":"shacl-validator.d.ts","sourceRoot":"","sources":["../src/shacl-validator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AACzC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAE5C,OAAO,KAAK,EACV,SAAS,EACT,gBAAgB,EAChB,gBAAgB,EAChB,MAAM,EACP,MAAM,eAAe,CAAC;AAOvB,0CAA0C;AAC1C,MAAM,WAAW,qBAAqB;IACpC,6FAA6F;IAC7F,UAAU,EAAE,MAAM,CAAC;IACnB;;;;;;;;OAQG;IACH,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;CAC1B;AAQD;;;;;;GAMG;AACH,qBAAa,cAAe,YAAW,SAAS;IAC9C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAW;IAEzC,OAAO,CAAC,aAAa,CAAkB;IACvC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAyC;gBAE1D,OAAO,EAAE,qBAAqB;IAKpC,QAAQ,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,gBAAgB,CAAC;IA2CpE,MAAM,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,gBAAgB,CAAC;YAkB3C,SAAS;CASxB"}

package/dist/shacl-validator.js

@@ -1,37 +1,24 @@
-import { mkdir, appendFile, writeFile } from 'node:fs/promises';
-import { join } from 'node:path';
-import { serializeQuads } from '@lde/pipeline';
 // @ts-expect-error -- shacl-engine has no type declarations.
 import ShaclEngine from 'shacl-engine/Validator.js';
 // @ts-expect-error -- rdf-ext has no type declarations.
 import rdf from 'rdf-ext';
 import { rdfDereferencer } from 'rdf-dereference';
-import filenamifyUrl from 'filenamify-url';
-/** File extension per serialization format. */
-const formatExtensions = {
-    Turtle: '.ttl',
-    'N-Triples': '.nt',
-    'N-Quads': '.nq',
-};
 /**
  * SHACL-based {@link Validator} for `@lde/pipeline`.
  *
  * Validates quads against shapes loaded from an RDF file (any format
- * supported by rdf-dereference) and writes per-dataset report files
- * in SHACL validation report format.
+ * supported by rdf-dereference) and streams the per-dataset SHACL validation
+ * report to any number of configured {@link Writer}s.
  */
 export class ShaclValidator {
     shapesFile;
-    reportDir;
-    reportFormat;
+    reportWriters;
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     shapesDataset;
     accumulators = new Map();
-    initializedFiles = new Set();
     constructor(options) {
         this.shapesFile = options.shapesFile;
-        this.reportDir = options.reportDir;
-        this.reportFormat = options.reportFormat ?? 'Turtle';
+        this.reportWriters = options.reportWriters ?? [];
     }
     async validate(quads, dataset) {
         if (quads.length === 0) {
@@ -55,14 +42,23 @@ export class ShaclValidator {
         if (!conforms)
             acc.conforms = false;
         this.accumulators.set(key, acc);
-        // Write violations to report file.
-        if (violations > 0) {
-            const reportFile = await this.writeReportFile(dataset, report);
-            return { conforms, violations, message: `See ${reportFile}` };
+        if (violations > 0 && this.reportWriters.length > 0) {
+            const reportQuads = [...report.dataset];
+            for (const writer of this.reportWriters) {
+                await writer.write(dataset, asyncIterableOf(reportQuads));
+            }
         }
-        return { conforms, violations };
+        // Surface where to look for the report in halt-mode error messages
+        // (read by @lde/pipeline's Stage.validateBuffer when onInvalid:'halt').
+        const message = violations > 0 && this.reportWriters.length > 0
+            ? `Report sent to ${this.reportWriters.length} writer(s)`
+            : undefined;
+        return { conforms, violations, ...(message !== undefined && { message }) };
     }
     async report(dataset) {
+        for (const writer of this.reportWriters) {
+            await writer.flush?.(dataset);
+        }
         const key = dataset.iri.toString();
         const acc = this.accumulators.get(key);
         if (!acc) {
@@ -84,22 +80,8 @@ export class ShaclValidator {
         }
         return this.shapesDataset;
     }
-    async writeReportFile(dataset, 
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    report) {
-        await mkdir(this.reportDir, { recursive: true });
-        const datasetName = filenamifyUrl(dataset.iri.toString());
-        const extension = formatExtensions[this.reportFormat];
-        const filePath = join(this.reportDir, `${datasetName}.validation${extension}`);
-        const reportQuads = [...report.dataset];
-        const serialized = await serializeQuads(reportQuads, this.reportFormat);
-        if (this.initializedFiles.has(filePath)) {
-            await appendFile(filePath, '\n' + serialized);
-        }
-        else {
-            await writeFile(filePath, serialized);
-            this.initializedFiles.add(filePath);
-        }
-        return filePath;
-    }
+}
+async function* asyncIterableOf(items) {
+    for (const item of items)
+        yield item;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lde/pipeline-shacl-validator",
-  "version": "0.11.2",
+  "version": "0.12.1",
   "description": "SHACL validation for @lde/pipeline",
   "repository": {
     "url": "git+https://github.com/ldelements/lde.git",
@@ -26,7 +26,6 @@
   ],
   "dependencies": {
     "@rdfjs/types": "^2.0.1",
-    "filenamify-url": "^4.0.0",
     "rdf-dereference": "^5.0.0",
     "rdf-ext": "^2.5.2",
     "shacl-engine": "^1.1.0",
@@ -37,6 +36,6 @@
   },
   "peerDependencies": {
     "@lde/dataset": "0.7.4",
-    "@lde/pipeline": "0.29.2"
+    "@lde/pipeline": "0.30.1"
   }
 }