@lde/pipeline-shacl-validator 0.2.0

package/README.md

@@ -0,0 +1,57 @@
+# @lde/pipeline-shacl-validator
+
+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.).
+
+## Usage
+
+```typescript
+import { Pipeline, Stage, SparqlConstructExecutor } from '@lde/pipeline';
+import { ShaclValidator } from '@lde/pipeline-shacl-validator';
+
+const validator = new ShaclValidator({
+  shapesFile: './shapes.ttl',
+  reportDir: './validation',
+});
+
+const pipeline = new Pipeline({
+  // ...
+  stages: [
+    new Stage({
+      name: 'transform',
+      executors: new SparqlConstructExecutor({ query: '...' }),
+      validation: {
+        validator,
+        onInvalid: 'write', // 'write' | 'skip' | 'halt'
+      },
+    }),
+  ],
+});
+
+await pipeline.run();
+```
+
+### `onInvalid` options
+
+| Value     | Behaviour                                                        |
+| --------- | ---------------------------------------------------------------- |
+| `'write'` | Write quads to the output even if validation fails **(default)** |
+| `'skip'`  | Discard invalid quads silently                                   |
+| `'halt'`  | Throw an error, stopping the pipeline                            |
+
+### Report files
+
+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:
+
+```typescript
+const validator = new ShaclValidator({
+  shapesFile: './shapes.ttl',
+  reportDir: './validation',
+  reportFormat: 'N-Triples', // 'Turtle' (default) | 'N-Triples' | 'N-Quads'
+});
+```

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export type { Validator, ValidationReport, ValidationResult, } from '@lde/pipeline';
+export { ShaclValidator, type ShaclValidatorOptions, } from './shacl-validator.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,YAAY,EACV,SAAS,EACT,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,cAAc,EACd,KAAK,qBAAqB,GAC3B,MAAM,sBAAsB,CAAC"}

package/dist/index.js

@@ -0,0 +1 @@
+export { ShaclValidator, } from './shacl-validator.js';

package/dist/shacl-validator.d.ts

@@ -0,0 +1,29 @@
+import type { Quad } from '@rdfjs/types';
+import type { Dataset } from '@lde/dataset';
+import type { Validator, ValidationResult, ValidationReport } 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;
+}
+/**
+ * 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.
+ */
+export declare class ShaclValidator implements Validator {
+    private readonly shapesFile;
+    private readonly reportDir;
+    private shapesDataset;
+    private readonly accumulators;
+    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

@@ -0,0 +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;AAEzC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,KAAK,EACV,SAAS,EACT,gBAAgB,EAChB,gBAAgB,EACjB,MAAM,eAAe,CAAC;AAQvB,0CAA0C;AAC1C,MAAM,WAAW,qBAAqB;IACpC,6FAA6F;IAC7F,UAAU,EAAE,MAAM,CAAC;IACnB,6CAA6C;IAC7C,SAAS,EAAE,MAAM,CAAC;CACnB;AAQD;;;;;;GAMG;AACH,qBAAa,cAAe,YAAW,SAAS;IAC9C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IAEnC,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;IAmCpE,MAAM,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,gBAAgB,CAAC;YAc3C,SAAS;YAcT,eAAe;CAoC9B"}

package/dist/shacl-validator.js

@@ -0,0 +1,115 @@
+import { mkdir, appendFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { Writer } from 'n3';
+// @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';
+/**
+ * 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.
+ */
+export class ShaclValidator {
+    shapesFile;
+    reportDir;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    shapesDataset;
+    accumulators = new Map();
+    constructor(options) {
+        this.shapesFile = options.shapesFile;
+        this.reportDir = options.reportDir;
+    }
+    async validate(quads, dataset) {
+        if (quads.length === 0) {
+            return { conforms: true, violations: 0 };
+        }
+        const shapes = await this.getShapes();
+        const dataDataset = rdf.dataset(quads);
+        const validator = new ShaclEngine(shapes, { factory: rdf });
+        const report = await validator.validate({ dataset: dataDataset });
+        const violations = report.results.length;
+        const conforms = report.conforms;
+        // Accumulate per dataset.
+        const key = dataset.iri.toString();
+        const acc = this.accumulators.get(key) ?? {
+            quadsValidated: 0,
+            violations: 0,
+            conforms: true,
+        };
+        acc.quadsValidated += quads.length;
+        acc.violations += violations;
+        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}` };
+        }
+        return { conforms, violations };
+    }
+    async report(dataset) {
+        const key = dataset.iri.toString();
+        const acc = this.accumulators.get(key);
+        if (!acc) {
+            return { conforms: true, violations: 0, quadsValidated: 0 };
+        }
+        return {
+            conforms: acc.conforms,
+            violations: acc.violations,
+            quadsValidated: acc.quadsValidated,
+        };
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    async getShapes() {
+        if (this.shapesDataset)
+            return this.shapesDataset;
+        const { data } = await rdfDereferencer.dereference(this.shapesFile, {
+            localFiles: true,
+        });
+        const dataset = rdf.dataset();
+        for await (const quad of data) {
+            dataset.add(quad);
+        }
+        this.shapesDataset = dataset;
+        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 filePath = join(this.reportDir, `${datasetName}.validation.ttl`);
+        // Serialize the SHACL report dataset to Turtle.
+        const reportQuads = [...report.dataset];
+        const turtle = await new Promise((resolve, reject) => {
+            const writer = new Writer({
+                prefixes: {
+                    sh: 'http://www.w3.org/ns/shacl#',
+                },
+            });
+            for (const quad of reportQuads) {
+                writer.addQuad(quad);
+            }
+            writer.end((error, result) => {
+                if (error)
+                    reject(error);
+                else
+                    resolve(result);
+            });
+        });
+        // Check if file exists; if so, append. Otherwise, create.
+        try {
+            await appendFile(filePath, '\n' + turtle);
+        }
+        catch {
+            await writeFile(filePath, turtle);
+        }
+        return filePath;
+    }
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@lde/pipeline-shacl-validator",
+  "version": "0.2.0",
+  "description": "SHACL validation for @lde/pipeline",
+  "repository": {
+    "url": "git+https://github.com/ldelements/lde.git",
+    "directory": "packages/pipeline-shacl-validator"
+  },
+  "type": "module",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "development": "./src/index.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "!**/*.tsbuildinfo"
+  ],
+  "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",
+    "tslib": "^2.3.0"
+  },
+  "devDependencies": {
+    "n3": "^2.0.1"
+  },
+  "peerDependencies": {
+    "@lde/dataset": "0.7.1",
+    "@lde/pipeline": "0.20.0"
+  }
+}