@lde/docgen 0.6.14 → 0.6.16

package/README.md

@@ -32,9 +32,9 @@ npx @lde/docgen@latest from-shacl <shacl-file> <template-file> [options]
 
 ### Options
 
-| Option               | Description                  | Default                              |
-| -------------------- | ---------------------------- | ------------------------------------ |
-| `-f, --frame <file>` | Path to a JSON-LD Frame file | Built-in `frames/shacl.frame.jsonld` |
+| Option               | Description                                                                                                                                          | Default                              |
+| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ |
+| `-f, --frame <file>` | Path to a JSON-LD Frame file. Deep-merged on top of the built-in default frame, so it only needs to contain your additions (e.g. extra `@context` entries). | Built-in `frames/shacl.frame.jsonld` |
 
 ### Example
 
@@ -108,8 +108,20 @@ Property shapes with the same `sh:path` are common in SHACL (e.g. one for cardin
 
 ## Custom frames
 
-The default frame selects all `sh:NodeShape` resources. To customise which shapes are selected or how they are nested, pass a custom [JSON-LD Frame](https://www.w3.org/TR/json-ld11-framing/):
+The default frame selects all `sh:NodeShape` resources and provides type coercions for common SHACL terms (`targetClass`, `path`, `severity`, etc.). To extend it, pass a partial [JSON-LD Frame](https://www.w3.org/TR/json-ld11-framing/) – it is **deep-merged** on top of the default, so you only need to specify your additions:
+
+```json
+{
+  "@context": {
+    "nde": "https://def.nde.nl#",
+    "nde:futureChange": {},
+    "nde:version": {}
+  }
+}
+```
 
 ```sh
 npx @lde/docgen@latest from-shacl shapes.ttl template.liquid -f my-frame.jsonld
 ```
+
+Plain objects are merged key-by-key, with user values winning; arrays and primitives in your frame replace the default. To override a built-in coercion (e.g. change `severity` from `@vocab` to `@id`), redefine the same key in your `@context`.

package/dist/cli.js

@@ -2,9 +2,6 @@
 import { Command } from 'commander';
 import { generateDocumentation } from './index.js';
 import packageJson from '../package.json' with { type: 'json' };
-import { dirname } from 'path';
-import { fileURLToPath } from 'url';
-const __dirname = dirname(fileURLToPath(import.meta.url));
 const program = new Command();
 program
     .name('docgen')
@@ -15,7 +12,7 @@ program
     .description('Generate documentation from a SHACL shapes file')
     .argument('<shacl-file>', 'Path to SHACL shapes file (in any RDF serialization format)')
     .argument('<template-file>', 'Path to Liquid template file')
-    .option('-f --frame <json-ld-frame-file>', 'Path to a JSON-LD Frame file', __dirname + '/../frames/shacl.frame.jsonld')
+    .option('-f --frame <json-ld-frame-file>', 'Path to a JSON-LD Frame file. Deep-merged on top of the built-in default frame, so it only needs to contain your additions.')
     .addHelpText('after', `
 Example:
   $ npx @lde/docgen@latest from-shacl shacl.ttl template.liquid

package/dist/frame.d.ts

@@ -1,4 +1,4 @@
 import type { JsonLdArray } from 'jsonld/jsonld-spec.js';
-import jsonld from 'jsonld';
-export declare function frame(document: JsonLdArray, frame: string): Promise<jsonld.NodeObject>;
+import type { NodeObject } from 'jsonld';
+export declare function frame(document: JsonLdArray, userFramePath?: string): Promise<NodeObject>;
 //# sourceMappingURL=frame.d.ts.map

package/dist/frame.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"frame.d.ts","sourceRoot":"","sources":["../src/frame.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,MAAM,MAAM,QAAQ,CAAC;AAG5B,wBAAsB,KAAK,CAAC,QAAQ,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,8BAS/D"}
+{"version":3,"file":"frame.d.ts","sourceRoot":"","sources":["../src/frame.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAS,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAChE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AAUzC,wBAAsB,KAAK,CACzB,QAAQ,EAAE,WAAW,EACrB,aAAa,CAAC,EAAE,MAAM,GACrB,OAAO,CAAC,UAAU,CAAC,CAUrB"}

package/dist/frame.js

@@ -1,8 +1,41 @@
 import jsonld from 'jsonld';
 import { readFile } from 'node:fs/promises';
-export async function frame(document, frame) {
-    return await jsonld.frame(document, JSON.parse(await readFile(frame, 'utf8')), {
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const defaultFramePath = join(__dirname, '../frames/shacl.frame.jsonld');
+export async function frame(document, userFramePath) {
+    const defaultFrame = await readFrame(defaultFramePath);
+    const mergedFrame = userFramePath
+        ? deepMerge(defaultFrame, await readFrame(userFramePath))
+        : defaultFrame;
+    return await jsonld.frame(document, mergedFrame, {
         omitGraph: false,
         embed: '@always',
     });
 }
+async function readFrame(path) {
+    return JSON.parse(await readFile(path, 'utf8'));
+}
+/**
+ * Recursively merges `source` into `target`, returning a new object. Plain
+ * objects are merged key-by-key; arrays and primitives in `source` replace
+ * those in `target`. Used to compose a user-supplied JSON-LD frame on top of
+ * docgen’s built-in default so consumers only need to specify their additions.
+ */
+function deepMerge(target, source) {
+    const result = { ...target };
+    for (const [key, sourceValue] of Object.entries(source)) {
+        const targetValue = result[key];
+        if (isPlainObject(targetValue) && isPlainObject(sourceValue)) {
+            result[key] = deepMerge(targetValue, sourceValue);
+        }
+        else {
+            result[key] = sourceValue;
+        }
+    }
+    return result;
+}
+function isPlainObject(value) {
+    return (typeof value === 'object' && value !== null && !Array.isArray(value));
+}

package/dist/index.d.ts

@@ -1,2 +1,11 @@
-export declare function generateDocumentation(rdfPath: string, templatePath: string, framePath: string): Promise<string>;
+/**
+ * Generate documentation from a SHACL shapes file using a Liquid template.
+ *
+ * @param rdfPath Path to a SHACL shapes file in any RDF serialization.
+ * @param templatePath Path to a Liquid template.
+ * @param framePath Optional path to a JSON-LD frame. When provided, it is
+ *   deep-merged on top of docgen’s built-in default frame, so consumers only
+ *   need to specify their additions (e.g. extra `@context` entries).
+ */
+export declare function generateDocumentation(rdfPath: string, templatePath: string, framePath?: string): Promise<string>;
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,MAAM,EACpB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,MAAM,CAAC,CAKjB"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA;;;;;;;;GAQG;AACH,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,MAAM,EACpB,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,MAAM,CAAC,CAKjB"}

package/dist/index.js

@@ -1,6 +1,15 @@
 import { parseRdfToJsonLd } from './parse.js';
 import { frame } from './frame.js';
 import { render } from './render.js';
+/**
+ * Generate documentation from a SHACL shapes file using a Liquid template.
+ *
+ * @param rdfPath Path to a SHACL shapes file in any RDF serialization.
+ * @param templatePath Path to a Liquid template.
+ * @param framePath Optional path to a JSON-LD frame. When provided, it is
+ *   deep-merged on top of docgen’s built-in default frame, so consumers only
+ *   need to specify their additions (e.g. extra `@context` entries).
+ */
 export async function generateDocumentation(rdfPath, templatePath, framePath) {
     const jsonld = await parseRdfToJsonLd(rdfPath);
     const framed = await frame(jsonld, framePath);

package/dist/parse.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parse.d.ts","sourceRoot":"","sources":["../src/parse.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAKpD,wBAAsB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAe7E"}
+{"version":3,"file":"parse.d.ts","sourceRoot":"","sources":["../src/parse.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAOpD,wBAAsB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAqB7E"}

package/dist/parse.js

@@ -2,6 +2,7 @@ import { rdfDereferencer } from 'rdf-dereference';
 import jsonld from 'jsonld';
 import { rdfSerializer } from 'rdf-serialize';
 import streamToString from 'stream-to-string';
+const XSD_STRING = 'http://www.w3.org/2001/XMLSchema#string';
 export async function parseRdfToJsonLd(filePath) {
     const { data } = await rdfDereferencer.dereference(filePath, {
         localFiles: true,
@@ -11,7 +12,30 @@ export async function parseRdfToJsonLd(filePath) {
         contentType: 'application/n-quads',
     });
     const nqString = await streamToString(nq);
-    return jsonld.fromRDF(nqString, {
+    const expanded = await jsonld.fromRDF(nqString, {
         useNativeTypes: true, // Convert xsd:integer to Number etc.
     });
+    // jsonld v9 emits @type: xsd:string on every plain string literal; v8 omitted
+    // it because xsd:string is the JSON-LD default datatype. Without this strip,
+    // framing yields { @value, @type } objects that templates render as
+    // ‘[object Object]’. See https://github.com/ldelements/lde/issues/369.
+    return stripDefaultStringType(expanded);
+}
+function stripDefaultStringType(value) {
+    if (Array.isArray(value)) {
+        return value.map(stripDefaultStringType);
+    }
+    if (value && typeof value === 'object') {
+        const record = value;
+        if (record['@value'] !== undefined && record['@type'] === XSD_STRING) {
+            const { ['@type']: _, ...rest } = record;
+            return rest;
+        }
+        const result = {};
+        for (const key of Object.keys(record)) {
+            result[key] = stripDefaultStringType(record[key]);
+        }
+        return result;
+    }
+    return value;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lde/docgen",
-  "version": "0.6.14",
+  "version": "0.6.16",
   "description": "Generate documentation from SHACL shapes",
   "keywords": [
     "shacl",