@lde/docgen 0.6.13 → 0.6.15

package/README.md

@@ -1,3 +1,127 @@
-# docgen
+# @lde/docgen
 
-Generate documentation RDF such as SHACL shapes.
+Generate human-readable documentation from [SHACL](https://www.w3.org/TR/shacl/) shapes using [Liquid](https://liquidjs.com) templates.
+
+- **Template-driven:** you control the output format (Markdown, HTML, plain text) with Liquid templates.
+- **Standards-based:** reads any RDF serialization (Turtle, JSON-LD, N-Triples, etc.) via [rdf-dereference](https://github.com/rubensworks/rdf-dereference.js).
+- **Structured output:** SHACL shapes are framed into a clean JSON-LD tree before rendering, so templates work with predictable, nested objects.
+
+## How it works
+
+```mermaid
+graph LR
+    A[SHACL file] --> B[Parse to JSON-LD] --> C[Frame by NodeShape] --> D[Render with Liquid template] --> E[Output]
+```
+
+1. **Parse** — the SHACL file is dereferenced and converted to JSON-LD.
+2. **Frame** — the JSON-LD is [framed](https://www.w3.org/TR/json-ld11-framing/) using a JSON-LD Frame that selects `sh:NodeShape` resources and nests their property shapes. A default frame is included; you can supply your own.
+3. **Render** — the framed data is passed to a Liquid template as `nodeShapes`, an array of node shape objects.
+
+## CLI usage
+
+```sh
+npx @lde/docgen@latest from-shacl <shacl-file> <template-file> [options]
+```
+
+### Arguments
+
+| Argument          | Description                                         |
+| ----------------- | --------------------------------------------------- |
+| `<shacl-file>`    | Path to a SHACL shapes file (any RDF serialization) |
+| `<template-file>` | Path to a Liquid template file                      |
+
+### Options
+
+| 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
+
+Given a SHACL file `shapes.ttl`:
+
+```turtle
+@prefix dcat: <http://www.w3.org/ns/dcat#> .
+@prefix dct:  <http://purl.org/dc/terms/> .
+@prefix sh:   <http://www.w3.org/ns/shacl#> .
+@prefix xsd:  <http://www.w3.org/2001/XMLSchema#> .
+
+[] a sh:NodeShape ;
+    sh:targetClass dcat:Dataset ;
+    sh:property [
+        sh:path dct:title ;
+        sh:minCount 1 ;
+    ] ,
+    [
+        sh:path dct:description ;
+        sh:minCount 1 ;
+        sh:datatype xsd:string ;
+        sh:description "A description of the dataset"@en ;
+    ] .
+```
+
+And a template `spec.md.liquid`:
+
+```liquid
+{% for nodeShape in nodeShapes -%}
+## {{ nodeShape.targetClass }}
+
+| Property | Required | Type | Description |
+|---|---|---|---|
+{% assign mergedProperties = nodeShape.property | mergePropertiesByPath -%}
+{% for property in mergedProperties -%}
+| `{{ property.path }}` | {{ property.minCount | default: "no" }} | {{ property.datatype }} | {{ property.description | lang: "en" }} |
+{% endfor %}
+{% endfor %}
+```
+
+Run:
+
+```sh
+npx @lde/docgen@latest from-shacl shapes.ttl spec.md.liquid > spec.md
+```
+
+## Programmatic usage
+
+```typescript
+import { generateDocumentation } from '@lde/docgen';
+
+const output = await generateDocumentation(
+  'shapes.ttl',
+  'spec.md.liquid',
+  'frames/shacl.frame.jsonld', // optional: path to custom frame
+);
+```
+
+## Template data
+
+The Liquid template receives a `nodeShapes` array. Each node shape object has the structure produced by the JSON-LD Frame — keys are SHACL term names (`targetClass`, `property`, `name`, etc.) with IRIs as values.
+
+Property shapes with the same `sh:path` are common in SHACL (e.g. one for cardinality, another for datatype). The `mergePropertiesByPath` filter combines them into a single object per path.
+
+### Custom filters
+
+| Filter                  | Description                                         | Example                                                             |
+| ----------------------- | --------------------------------------------------- | ------------------------------------------------------------------- |
+| `lang`                  | Select a value by language tag                      | `{{ property.description \| lang: "en" }}`                          |
+| `mergePropertiesByPath` | Merge property shapes that share the same `sh:path` | `{% assign merged = nodeShape.property \| mergePropertiesByPath %}` |
+
+## Custom frames
+
+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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lde/docgen",
-  "version": "0.6.13",
+  "version": "0.6.15",
   "description": "Generate documentation from SHACL shapes",
   "keywords": [
     "shacl",
@@ -9,15 +9,16 @@
     "generator"
   ],
   "repository": {
-    "url": "https://github.com/ldengine/lde",
+    "url": "git+https://github.com/ldelements/lde.git",
     "directory": "packages/docgen"
   },
+  "license": "MIT",
   "type": "module",
   "exports": {
     "./package.json": "./package.json",
     ".": {
-      "development": "./src/index.ts",
       "types": "./dist/index.d.ts",
+      "development": "./src/index.ts",
       "import": "./dist/index.js",
       "default": "./dist/index.js"
     }
@@ -26,7 +27,7 @@
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "bin": {
-    "docgen": "./dist/cli.js"
+    "docgen": "dist/cli.js"
   },
   "files": [
     "dist",
@@ -35,9 +36,9 @@
   ],
   "dependencies": {
     "commander": "^14.0.3",
-    "jsonld": "^8.3.3",
-    "liquidjs": "^10.24.0",
-    "rdf-dereference": "^4.0.0",
+    "jsonld": "^9.0.0",
+    "liquidjs": "^10.25.5",
+    "rdf-dereference": "^5.0.0",
     "rdf-serialize": "^5.1.0",
     "stream-to-string": "^1.2.1",
     "tslib": "^2.3.0"