@kanonak-protocol/cli 2.5.0 → 3.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/index.js +78 -78
- package/dist/transformations/DocAstUriConstants.d.ts +57 -0
- package/dist/transformations/FormatOverride.d.ts +21 -0
- package/dist/transformations/backends/HtmlBackend.d.ts +2 -2
- package/dist/transformations/backends/IDocumentAstBackend.d.ts +2 -2
- package/dist/transformations/backends/JsonBackend.d.ts +2 -2
- package/dist/transformations/backends/MarkdownFrontmatterBackend.d.ts +2 -2
- package/dist/transformations/backends/SvgBackend.d.ts +2 -2
- package/dist/transformations/backends/TomlBackend.d.ts +2 -2
- package/dist/transformations/v3/CompiledTransformationV3.d.ts +215 -0
- package/dist/transformations/v3/ExpressionEngineV3.d.ts +49 -0
- package/dist/transformations/v3/TransformationLoaderV3.d.ts +22 -0
- package/dist/transformations/v3/TransformationRunnerV3.d.ts +90 -0
- package/dist/transformations/v3/TransformationUriConstantsV3.d.ts +131 -0
- package/package.json +3 -3
- package/dist/transformations/CompiledTransformation.d.ts +0 -155
- package/dist/transformations/ExpressionEngine.d.ts +0 -28
- package/dist/transformations/TransformationLoader.d.ts +0 -20
- package/dist/transformations/TransformationRunner.d.ts +0 -81
- package/dist/transformations/UriConstants.d.ts +0 -147
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Hardcoded canonical URIs for the document-ast ontology.
|
|
3
|
+
*
|
|
4
|
+
* Version-agnostic — docast is its own ontology and doesn't move
|
|
5
|
+
* with the transformations major version. Both the v2 runtime
|
|
6
|
+
* (legacy) and the v3 runtime read from this same file.
|
|
7
|
+
*
|
|
8
|
+
* Per the typescript repo's CLAUDE.md rule 6, hardcoded URI
|
|
9
|
+
* constants are fine and expected — they are the ontology contract.
|
|
10
|
+
* String-based alias or suffix matching is NOT.
|
|
11
|
+
*/
|
|
12
|
+
import type { EntityUri } from '../capabilities/UriHelpers.js';
|
|
13
|
+
export declare const DOCAST_PUB = "kanonak.org";
|
|
14
|
+
export declare const DOCAST_PKG = "document-ast";
|
|
15
|
+
export declare const DOCAST: {
|
|
16
|
+
readonly Document: EntityUri;
|
|
17
|
+
readonly Block: EntityUri;
|
|
18
|
+
readonly Inline: EntityUri;
|
|
19
|
+
readonly StructuredValue: EntityUri;
|
|
20
|
+
readonly Heading: EntityUri;
|
|
21
|
+
readonly Paragraph: EntityUri;
|
|
22
|
+
readonly RawBlock: EntityUri;
|
|
23
|
+
readonly Text: EntityUri;
|
|
24
|
+
readonly StructuredMap: EntityUri;
|
|
25
|
+
readonly StructuredEntry: EntityUri;
|
|
26
|
+
readonly StructuredList: EntityUri;
|
|
27
|
+
readonly StringScalar: EntityUri;
|
|
28
|
+
readonly IntegerScalar: EntityUri;
|
|
29
|
+
readonly EscapeHint: EntityUri;
|
|
30
|
+
readonly MediaType: EntityUri;
|
|
31
|
+
readonly metadata: EntityUri;
|
|
32
|
+
readonly children: EntityUri;
|
|
33
|
+
readonly level: EntityUri;
|
|
34
|
+
readonly inlines: EntityUri;
|
|
35
|
+
readonly text: EntityUri;
|
|
36
|
+
readonly entries: EntityUri;
|
|
37
|
+
readonly key: EntityUri;
|
|
38
|
+
readonly value: EntityUri;
|
|
39
|
+
readonly escapeHint: EntityUri;
|
|
40
|
+
readonly items: EntityUri;
|
|
41
|
+
readonly stringValue: EntityUri;
|
|
42
|
+
readonly integerValue: EntityUri;
|
|
43
|
+
readonly rawContent: EntityUri;
|
|
44
|
+
readonly mediaType: EntityUri;
|
|
45
|
+
readonly mimeType: EntityUri;
|
|
46
|
+
readonly ESC_RAW: EntityUri;
|
|
47
|
+
readonly ESC_YAML_SAFE: EntityUri;
|
|
48
|
+
readonly ESC_TOML_STRING: EntityUri;
|
|
49
|
+
readonly ESC_TOML_MULTILINE: EntityUri;
|
|
50
|
+
readonly ESC_JSON: EntityUri;
|
|
51
|
+
readonly TEXT_PLAIN: EntityUri;
|
|
52
|
+
readonly TEXT_MARKDOWN: EntityUri;
|
|
53
|
+
readonly TEXT_HTML: EntityUri;
|
|
54
|
+
readonly APPLICATION_JSON: EntityUri;
|
|
55
|
+
readonly TEXT_YAML: EntityUri;
|
|
56
|
+
readonly IMAGE_SVG_XML: EntityUri;
|
|
57
|
+
};
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Backend-facing FormatOverride contract.
|
|
3
|
+
*
|
|
4
|
+
* Version-agnostic — backends operate on docast trees and accept
|
|
5
|
+
* format-specific tweaks via this shape, regardless of which
|
|
6
|
+
* transformation runtime produced it. Each runtime version compiles
|
|
7
|
+
* its FormatOverride YAML into a value of this shape before handing
|
|
8
|
+
* it to a backend.
|
|
9
|
+
*/
|
|
10
|
+
export interface BackendFormatOverride {
|
|
11
|
+
/**
|
|
12
|
+
* Optional include-list of metadata entry keys the backend should
|
|
13
|
+
* emit, in order. Keys outside this list are skipped. If omitted,
|
|
14
|
+
* the backend emits all metadata entries in their AST order.
|
|
15
|
+
*/
|
|
16
|
+
metadataKeys?: string[];
|
|
17
|
+
/** AST-key → emitted-key renames. */
|
|
18
|
+
metadataRenames: Map<string, string>;
|
|
19
|
+
/** Whether to append a final newline to the serialized output. */
|
|
20
|
+
trailingNewline?: boolean;
|
|
21
|
+
}
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
import type { DocAstDocument } from '../DocAst.js';
|
|
2
|
-
import type {
|
|
2
|
+
import type { BackendFormatOverride } from '../FormatOverride.js';
|
|
3
3
|
import type { IDocumentAstBackend } from './IDocumentAstBackend.js';
|
|
4
4
|
export declare class HtmlBackend implements IDocumentAstBackend {
|
|
5
5
|
readonly backendUri = "kanonak.org/transformations/html";
|
|
6
|
-
render(document: DocAstDocument, override?:
|
|
6
|
+
render(document: DocAstDocument, override?: BackendFormatOverride): string;
|
|
7
7
|
}
|
|
@@ -8,9 +8,9 @@
|
|
|
8
8
|
* handler's job.
|
|
9
9
|
*/
|
|
10
10
|
import type { DocAstDocument } from '../DocAst.js';
|
|
11
|
-
import type {
|
|
11
|
+
import type { BackendFormatOverride } from '../FormatOverride.js';
|
|
12
12
|
export interface IDocumentAstBackend {
|
|
13
13
|
/** The backendUri string this backend registers under. */
|
|
14
14
|
readonly backendUri: string;
|
|
15
|
-
render(document: DocAstDocument, override?:
|
|
15
|
+
render(document: DocAstDocument, override?: BackendFormatOverride): string;
|
|
16
16
|
}
|
|
@@ -4,9 +4,9 @@
|
|
|
4
4
|
* immune to the whitespace sensitivity of the text backends.
|
|
5
5
|
*/
|
|
6
6
|
import type { DocAstDocument } from '../DocAst.js';
|
|
7
|
-
import type {
|
|
7
|
+
import type { BackendFormatOverride } from '../FormatOverride.js';
|
|
8
8
|
import type { IDocumentAstBackend } from './IDocumentAstBackend.js';
|
|
9
9
|
export declare class JsonBackend implements IDocumentAstBackend {
|
|
10
10
|
readonly backendUri = "kanonak.org/transformations/json";
|
|
11
|
-
render(document: DocAstDocument, override?:
|
|
11
|
+
render(document: DocAstDocument, override?: BackendFormatOverride): string;
|
|
12
12
|
}
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
import type { DocAstDocument } from '../DocAst.js';
|
|
2
|
-
import type {
|
|
2
|
+
import type { BackendFormatOverride } from '../FormatOverride.js';
|
|
3
3
|
import type { IDocumentAstBackend } from './IDocumentAstBackend.js';
|
|
4
4
|
export declare class MarkdownFrontmatterBackend implements IDocumentAstBackend {
|
|
5
5
|
readonly backendUri = "kanonak.org/transformations/markdown-with-frontmatter";
|
|
6
|
-
render(document: DocAstDocument, override?:
|
|
6
|
+
render(document: DocAstDocument, override?: BackendFormatOverride): string;
|
|
7
7
|
}
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
import type { DocAstDocument } from '../DocAst.js';
|
|
2
|
-
import type {
|
|
2
|
+
import type { BackendFormatOverride } from '../FormatOverride.js';
|
|
3
3
|
import type { IDocumentAstBackend } from './IDocumentAstBackend.js';
|
|
4
4
|
export declare class SvgBackend implements IDocumentAstBackend {
|
|
5
5
|
readonly backendUri = "kanonak.org/transformations/svg";
|
|
6
|
-
render(document: DocAstDocument, override?:
|
|
6
|
+
render(document: DocAstDocument, override?: BackendFormatOverride): string;
|
|
7
7
|
}
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
import type { DocAstDocument } from '../DocAst.js';
|
|
2
|
-
import type {
|
|
2
|
+
import type { BackendFormatOverride } from '../FormatOverride.js';
|
|
3
3
|
import type { IDocumentAstBackend } from './IDocumentAstBackend.js';
|
|
4
4
|
export declare class TomlBackend implements IDocumentAstBackend {
|
|
5
5
|
readonly backendUri = "kanonak.org/transformations/toml";
|
|
6
|
-
render(document: DocAstDocument, override?:
|
|
6
|
+
render(document: DocAstDocument, override?: BackendFormatOverride): string;
|
|
7
7
|
}
|
|
@@ -0,0 +1,215 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Typed, parsed-once representation of a transformations@3.0.0
|
|
3
|
+
* Transformation. Produced by `TransformationLoaderV3` from a
|
|
4
|
+
* `SubjectKanonak` whose RDF type is either `InstanceTransformation`
|
|
5
|
+
* or `SetTransformation`; consumed by `TransformationRunnerV3` and
|
|
6
|
+
* `ExpressionEngineV3`.
|
|
7
|
+
*
|
|
8
|
+
* The full Expression type union is declared here even though slice 1
|
|
9
|
+
* only implements a subset — declaring it upfront means later slices
|
|
10
|
+
* add behavior (loader cases, engine cases) rather than type members.
|
|
11
|
+
*
|
|
12
|
+
* V3 SHAPE NOTES (vs V2):
|
|
13
|
+
* - Top level is a discriminated union over `kind: 'instance' | 'set'`,
|
|
14
|
+
* mirroring the InstanceTransformation/SetTransformation split.
|
|
15
|
+
* - InputPattern carries `sortBy` (ordered list of SortKeys); the V2
|
|
16
|
+
* pattern had no sort.
|
|
17
|
+
* - SetTransformation may carry `partitionBy` for fan-out.
|
|
18
|
+
* - Expression nodes are tagged by their `kind` string here (the
|
|
19
|
+
* compiled form), but in the YAML they're dispatched by RDF type
|
|
20
|
+
* (real OWL hierarchy, not a discriminator instance).
|
|
21
|
+
*/
|
|
22
|
+
import type { EntityUri } from '../../capabilities/UriHelpers.js';
|
|
23
|
+
export type CompiledTransformationV3 = CompiledInstanceTransformationV3 | CompiledSetTransformationV3;
|
|
24
|
+
export interface CompiledTransformationV3Base {
|
|
25
|
+
/** Local name of the transformation entity, for diagnostics. */
|
|
26
|
+
name: string;
|
|
27
|
+
inputPattern: CompiledInputPatternV3;
|
|
28
|
+
rule: CompiledExpressionV3;
|
|
29
|
+
artifactName: CompiledExpressionV3;
|
|
30
|
+
/**
|
|
31
|
+
* The set of OutputFormat URIs this transformation supports, keyed
|
|
32
|
+
* by the OutputFormat's local name. The runner rejects requests to
|
|
33
|
+
* render in a format not in this set.
|
|
34
|
+
*/
|
|
35
|
+
outputs: Set<string>;
|
|
36
|
+
/** Per-output-format overrides keyed by the OutputFormat's local name. */
|
|
37
|
+
overrides: Map<string, CompiledFormatOverrideV3>;
|
|
38
|
+
}
|
|
39
|
+
export interface CompiledInstanceTransformationV3 extends CompiledTransformationV3Base {
|
|
40
|
+
kind: 'instance';
|
|
41
|
+
}
|
|
42
|
+
export interface CompiledSetTransformationV3 extends CompiledTransformationV3Base {
|
|
43
|
+
kind: 'set';
|
|
44
|
+
/**
|
|
45
|
+
* When set, the runner partitions the matched input set on this
|
|
46
|
+
* property and emits one Artifact per partition; `key` and `inputs`
|
|
47
|
+
* are bound for each evaluation. When undefined, the runner runs
|
|
48
|
+
* `rule` and `artifactName` once with `inputs` bound to the whole
|
|
49
|
+
* matched set, emitting a single Artifact.
|
|
50
|
+
*/
|
|
51
|
+
partitionBy?: EntityUri;
|
|
52
|
+
}
|
|
53
|
+
export interface CompiledInputPatternV3 {
|
|
54
|
+
/** The class URI whose instances are eligible. */
|
|
55
|
+
matchesClass: EntityUri;
|
|
56
|
+
/** Property URIs that must each resolve to non-empty on each instance. */
|
|
57
|
+
requires: EntityUri[];
|
|
58
|
+
/**
|
|
59
|
+
* Ordered list of sort criteria (primary first, ties broken by
|
|
60
|
+
* subsequent keys). Empty for transformations that don't need order.
|
|
61
|
+
*/
|
|
62
|
+
sortBy: CompiledSortKeyV3[];
|
|
63
|
+
}
|
|
64
|
+
export interface CompiledSortKeyV3 {
|
|
65
|
+
byProperty: EntityUri;
|
|
66
|
+
order: 'ascending' | 'descending';
|
|
67
|
+
}
|
|
68
|
+
export interface CompiledFormatOverrideV3 {
|
|
69
|
+
metadataKeys?: string[];
|
|
70
|
+
metadataRenames: Map<string, string>;
|
|
71
|
+
trailingNewline?: boolean;
|
|
72
|
+
}
|
|
73
|
+
export type CompiledExpressionV3 = CompiledStringLiteralV3 | CompiledIntegerLiteralV3 | CompiledDecimalLiteralV3 | CompiledBooleanLiteralV3 | CompiledVarRefV3 | CompiledPropertyReadV3 | CompiledTraverseV3 | CompiledBuildAstNodeV3 | CompiledWhenV3 | CompiledConcatV3 | CompiledFallbackV3 | CompiledUriNameV3 | CompiledUriLiteralV3 | CompiledDisplayLabelV3 | CompiledResolveRefV3 | CompiledNormalizeV3 | CompiledIsSetV3 | CompiledCallFragmentV3 | CompiledJoinV3 | CompiledCountV3 | CompiledSumV3 | CompiledMinV3 | CompiledMaxV3 | CompiledAverageV3 | CompiledForEachV3 | CompiledListMapV3 | CompiledFilterV3 | CompiledPartitionByV3 | CompiledDistinctByV3;
|
|
74
|
+
export interface CompiledStringLiteralV3 {
|
|
75
|
+
kind: 'string-literal';
|
|
76
|
+
value: string;
|
|
77
|
+
}
|
|
78
|
+
export interface CompiledIntegerLiteralV3 {
|
|
79
|
+
kind: 'integer-literal';
|
|
80
|
+
value: number;
|
|
81
|
+
}
|
|
82
|
+
export interface CompiledDecimalLiteralV3 {
|
|
83
|
+
kind: 'decimal-literal';
|
|
84
|
+
value: number;
|
|
85
|
+
}
|
|
86
|
+
export interface CompiledBooleanLiteralV3 {
|
|
87
|
+
kind: 'boolean-literal';
|
|
88
|
+
value: boolean;
|
|
89
|
+
}
|
|
90
|
+
export interface CompiledVarRefV3 {
|
|
91
|
+
kind: 'var-ref';
|
|
92
|
+
varName: string;
|
|
93
|
+
}
|
|
94
|
+
export interface CompiledPropertyReadV3 {
|
|
95
|
+
kind: 'property-read';
|
|
96
|
+
source: CompiledExpressionV3;
|
|
97
|
+
readProp: EntityUri;
|
|
98
|
+
}
|
|
99
|
+
export interface CompiledTraverseV3 {
|
|
100
|
+
kind: 'traverse';
|
|
101
|
+
source: CompiledExpressionV3;
|
|
102
|
+
through: EntityUri;
|
|
103
|
+
step: CompiledExpressionV3;
|
|
104
|
+
}
|
|
105
|
+
export interface CompiledBuildAstNodeV3 {
|
|
106
|
+
kind: 'build-ast-node';
|
|
107
|
+
astClass: EntityUri;
|
|
108
|
+
set: CompiledFieldBindingV3[];
|
|
109
|
+
}
|
|
110
|
+
export interface CompiledFieldBindingV3 {
|
|
111
|
+
field: EntityUri;
|
|
112
|
+
value: CompiledExpressionV3;
|
|
113
|
+
}
|
|
114
|
+
export interface CompiledWhenV3 {
|
|
115
|
+
kind: 'when';
|
|
116
|
+
condition: CompiledExpressionV3;
|
|
117
|
+
thenBuild: CompiledExpressionV3;
|
|
118
|
+
elseBuild?: CompiledExpressionV3;
|
|
119
|
+
}
|
|
120
|
+
export interface CompiledConcatV3 {
|
|
121
|
+
kind: 'concat';
|
|
122
|
+
parts: CompiledExpressionV3[];
|
|
123
|
+
}
|
|
124
|
+
export interface CompiledFallbackV3 {
|
|
125
|
+
kind: 'fallback';
|
|
126
|
+
primary: CompiledExpressionV3;
|
|
127
|
+
alternate: CompiledExpressionV3;
|
|
128
|
+
}
|
|
129
|
+
export interface CompiledUriNameV3 {
|
|
130
|
+
kind: 'uri-name';
|
|
131
|
+
source: CompiledExpressionV3;
|
|
132
|
+
}
|
|
133
|
+
export interface CompiledUriLiteralV3 {
|
|
134
|
+
kind: 'uri-literal';
|
|
135
|
+
refTo: EntityUri;
|
|
136
|
+
}
|
|
137
|
+
export interface CompiledDisplayLabelV3 {
|
|
138
|
+
kind: 'display-label';
|
|
139
|
+
labelTarget: EntityUri;
|
|
140
|
+
labelSource: EntityUri;
|
|
141
|
+
}
|
|
142
|
+
export interface CompiledResolveRefV3 {
|
|
143
|
+
kind: 'resolve-ref';
|
|
144
|
+
source: CompiledExpressionV3;
|
|
145
|
+
}
|
|
146
|
+
export type NormalizeKindV3 = 'trim-end';
|
|
147
|
+
export interface CompiledNormalizeV3 {
|
|
148
|
+
kind: 'normalize';
|
|
149
|
+
source: CompiledExpressionV3;
|
|
150
|
+
normKind: NormalizeKindV3;
|
|
151
|
+
}
|
|
152
|
+
export interface CompiledIsSetV3 {
|
|
153
|
+
kind: 'is-set';
|
|
154
|
+
check: CompiledExpressionV3;
|
|
155
|
+
}
|
|
156
|
+
export interface CompiledCallFragmentV3 {
|
|
157
|
+
kind: 'call-fragment';
|
|
158
|
+
/** The fragment's compiled body, inlined at compile time. */
|
|
159
|
+
body: CompiledExpressionV3;
|
|
160
|
+
}
|
|
161
|
+
export interface CompiledJoinV3 {
|
|
162
|
+
kind: 'join';
|
|
163
|
+
source: CompiledExpressionV3;
|
|
164
|
+
separator: string;
|
|
165
|
+
}
|
|
166
|
+
export interface CompiledCountV3 {
|
|
167
|
+
kind: 'count';
|
|
168
|
+
source: CompiledExpressionV3;
|
|
169
|
+
}
|
|
170
|
+
export interface CompiledSumV3 {
|
|
171
|
+
kind: 'sum';
|
|
172
|
+
source: CompiledExpressionV3;
|
|
173
|
+
}
|
|
174
|
+
export interface CompiledMinV3 {
|
|
175
|
+
kind: 'min';
|
|
176
|
+
source: CompiledExpressionV3;
|
|
177
|
+
}
|
|
178
|
+
export interface CompiledMaxV3 {
|
|
179
|
+
kind: 'max';
|
|
180
|
+
source: CompiledExpressionV3;
|
|
181
|
+
}
|
|
182
|
+
export interface CompiledAverageV3 {
|
|
183
|
+
kind: 'average';
|
|
184
|
+
source: CompiledExpressionV3;
|
|
185
|
+
}
|
|
186
|
+
export interface CompiledForEachV3 {
|
|
187
|
+
kind: 'for-each';
|
|
188
|
+
source: CompiledExpressionV3;
|
|
189
|
+
loopVar: string;
|
|
190
|
+
emit: CompiledExpressionV3;
|
|
191
|
+
}
|
|
192
|
+
export interface CompiledListMapV3 {
|
|
193
|
+
kind: 'list-map';
|
|
194
|
+
source: CompiledExpressionV3;
|
|
195
|
+
loopVar: string;
|
|
196
|
+
mapBody: CompiledExpressionV3;
|
|
197
|
+
}
|
|
198
|
+
export interface CompiledFilterV3 {
|
|
199
|
+
kind: 'filter';
|
|
200
|
+
source: CompiledExpressionV3;
|
|
201
|
+
loopVar: string;
|
|
202
|
+
predicate: CompiledExpressionV3;
|
|
203
|
+
}
|
|
204
|
+
export interface CompiledPartitionByV3 {
|
|
205
|
+
kind: 'partition-by';
|
|
206
|
+
source: CompiledExpressionV3;
|
|
207
|
+
loopVar: string;
|
|
208
|
+
partitionKey: CompiledExpressionV3;
|
|
209
|
+
}
|
|
210
|
+
export interface CompiledDistinctByV3 {
|
|
211
|
+
kind: 'distinct-by';
|
|
212
|
+
source: CompiledExpressionV3;
|
|
213
|
+
loopVar: string;
|
|
214
|
+
distinctKey: CompiledExpressionV3;
|
|
215
|
+
}
|
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Evaluates a `CompiledExpressionV3` tree against an environment.
|
|
3
|
+
*
|
|
4
|
+
* Covers the full v3 Expression hierarchy. Aggregations are strict
|
|
5
|
+
* about element types — non-numeric elements in a Sum/Min/Max/Average
|
|
6
|
+
* raise a runtime error. Min/Max/Average on an empty list also error
|
|
7
|
+
* (per the ontology contract); Sum on empty returns 0; Count works
|
|
8
|
+
* regardless of element type.
|
|
9
|
+
*
|
|
10
|
+
* Property reads walk `statement[]` by canonical predicate URI via
|
|
11
|
+
* `UriHelpers`. Reference resolution during traversal goes through
|
|
12
|
+
* the shared `ReferenceResolver`.
|
|
13
|
+
*/
|
|
14
|
+
import { type Kanonak } from '@kanonak-protocol/sdk';
|
|
15
|
+
import { type EntityUri } from '../../capabilities/UriHelpers.js';
|
|
16
|
+
import { ReferenceResolver } from '../ReferenceResolver.js';
|
|
17
|
+
import type { CompiledExpressionV3 } from './CompiledTransformationV3.js';
|
|
18
|
+
/**
|
|
19
|
+
* Runtime representation of a Partition produced by the
|
|
20
|
+
* `PartitionBy` expression. Carries the partition key value plus
|
|
21
|
+
* the list of source elements that share that key.
|
|
22
|
+
*
|
|
23
|
+
* The engine surfaces Partitions as plain JS objects; PropertyRead
|
|
24
|
+
* special-cases this shape so authors can read `partition.key` and
|
|
25
|
+
* `partition.members` from inside a ForEach over the partition list.
|
|
26
|
+
*/
|
|
27
|
+
export interface RuntimePartitionV3 {
|
|
28
|
+
kind: 'Partition';
|
|
29
|
+
key: EnvValue;
|
|
30
|
+
members: Kanonak[];
|
|
31
|
+
}
|
|
32
|
+
export type EnvValue = string | number | boolean | Kanonak | Kanonak[] | EnvValue[] | RuntimePartitionV3 | EntityUri | unknown | undefined | null;
|
|
33
|
+
export type Env = Map<string, EnvValue>;
|
|
34
|
+
export declare class ExpressionEvalErrorV3 extends Error {
|
|
35
|
+
}
|
|
36
|
+
export declare class ExpressionEngineV3 {
|
|
37
|
+
private readonly resolver;
|
|
38
|
+
private readonly catalog;
|
|
39
|
+
constructor(resolver: ReferenceResolver, catalog: Kanonak[]);
|
|
40
|
+
evaluate(expr: CompiledExpressionV3, env: Env): Promise<EnvValue>;
|
|
41
|
+
/**
|
|
42
|
+
* Evaluate a source expression and coerce its result into a list.
|
|
43
|
+
* Single-valued results are wrapped in a single-element list so
|
|
44
|
+
* downstream operations don't have to special-case scalar sources
|
|
45
|
+
* (e.g. an aggregation over a property that happens to be
|
|
46
|
+
* single-valued for one instance and multi-valued for another).
|
|
47
|
+
*/
|
|
48
|
+
private evaluateList;
|
|
49
|
+
}
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Compiles a transformations@3.0.0 SubjectKanonak into a typed
|
|
3
|
+
* CompiledTransformationV3. Walks `statement[]` via the SDK's parsed
|
|
4
|
+
* object model — never re-parses YAML, never matches on alias
|
|
5
|
+
* prefixes. Property reads go through `UriHelpers`; type dispatch
|
|
6
|
+
* uses `hasType` against canonical `TX_V3` URIs.
|
|
7
|
+
*
|
|
8
|
+
* Throws `TransformationLoadErrorV3` with a breadcrumb path on the
|
|
9
|
+
* first shape violation.
|
|
10
|
+
*/
|
|
11
|
+
import { SubjectKanonak, type Kanonak } from '@kanonak-protocol/sdk';
|
|
12
|
+
import type { CompiledTransformationV3 } from './CompiledTransformationV3.js';
|
|
13
|
+
export declare class TransformationLoadErrorV3 extends Error {
|
|
14
|
+
readonly path: string;
|
|
15
|
+
constructor(message: string, path: string);
|
|
16
|
+
}
|
|
17
|
+
/**
|
|
18
|
+
* Top-level entry point. Determines whether the SubjectKanonak is an
|
|
19
|
+
* InstanceTransformation or SetTransformation by RDF type, then
|
|
20
|
+
* dispatches to the appropriate compiler.
|
|
21
|
+
*/
|
|
22
|
+
export declare function compileTransformationV3(transformation: SubjectKanonak, catalog: Kanonak[]): CompiledTransformationV3;
|
|
@@ -0,0 +1,90 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Runtime entry point for transformations@3.0.0.
|
|
3
|
+
*
|
|
4
|
+
* Two pipelines:
|
|
5
|
+
*
|
|
6
|
+
* - InstanceTransformation: 1 input → 1 artifact. The runner filters
|
|
7
|
+
* candidates by InputPattern, then evaluates `rule` and
|
|
8
|
+
* `artifactName` once per candidate with `input` bound. Sort
|
|
9
|
+
* order on the InputPattern affects the order of emitted
|
|
10
|
+
* artifacts but doesn't change the cardinality.
|
|
11
|
+
*
|
|
12
|
+
* - SetTransformation:
|
|
13
|
+
* Without partitionBy: N candidates → 1 artifact, with `inputs`
|
|
14
|
+
* bound to the entire matched (and optionally sorted) list.
|
|
15
|
+
* With partitionBy: candidates are partitioned by the property
|
|
16
|
+
* value; one artifact per partition, with `inputs` bound to
|
|
17
|
+
* that partition's members and `key` bound to the partition
|
|
18
|
+
* value. Candidates whose partition property is absent are
|
|
19
|
+
* dropped (no group is created).
|
|
20
|
+
*
|
|
21
|
+
* Sort behavior:
|
|
22
|
+
* - SortKey.byProperty is read off each candidate. Missing values
|
|
23
|
+
* sort last (ascending) or first (descending). Lists or
|
|
24
|
+
* references on the sort property are an authoring error caught
|
|
25
|
+
* here at runtime.
|
|
26
|
+
*
|
|
27
|
+
* The runner does NOT touch the filesystem — writing is the
|
|
28
|
+
* deployment handler / CLI's job. Backends are version-agnostic and
|
|
29
|
+
* shared with any other transformation runtime.
|
|
30
|
+
*/
|
|
31
|
+
import { SubjectKanonak, type Kanonak, type IKanonakDocumentRepository, KanonakParser, KanonakObjectParser } from '@kanonak-protocol/sdk';
|
|
32
|
+
import type { IDocumentAstBackend } from '../backends/IDocumentAstBackend.js';
|
|
33
|
+
import { TransformationLoadErrorV3 } from './TransformationLoaderV3.js';
|
|
34
|
+
import type { CompiledTransformationV3 } from './CompiledTransformationV3.js';
|
|
35
|
+
export interface ArtifactV3 {
|
|
36
|
+
/** Filename stem (no directory, no extension). */
|
|
37
|
+
fileName: string;
|
|
38
|
+
/** OutputFormat local name this was rendered as. */
|
|
39
|
+
format: string;
|
|
40
|
+
/** Serialized bytes. */
|
|
41
|
+
content: string;
|
|
42
|
+
/** Provenance — which subject(s) drove this artifact. */
|
|
43
|
+
source: ArtifactProvenanceV3;
|
|
44
|
+
}
|
|
45
|
+
export type ArtifactProvenanceV3 = {
|
|
46
|
+
kind: 'instance';
|
|
47
|
+
sourceName: string;
|
|
48
|
+
} | {
|
|
49
|
+
kind: 'set';
|
|
50
|
+
memberCount: number;
|
|
51
|
+
partitionKey?: string;
|
|
52
|
+
};
|
|
53
|
+
export interface FormatDescriptorV3 {
|
|
54
|
+
formatUri: string;
|
|
55
|
+
extension: string;
|
|
56
|
+
}
|
|
57
|
+
export declare const SUPPORTED_FORMATS_V3: Record<string, FormatDescriptorV3>;
|
|
58
|
+
export interface RunInputV3 {
|
|
59
|
+
transformation: SubjectKanonak;
|
|
60
|
+
/** Candidate input subjects. Caller is responsible for subclass-aware selection. */
|
|
61
|
+
instances: SubjectKanonak[];
|
|
62
|
+
/** All loaded kanonaks for fragment lookup + reference resolution. */
|
|
63
|
+
allKanonaks: Kanonak[];
|
|
64
|
+
/**
|
|
65
|
+
* Optional kanonaks of the transformation's own package (where any
|
|
66
|
+
* ExpressionFragments live). Falls back to allKanonaks.
|
|
67
|
+
*/
|
|
68
|
+
transformationKanonaks?: Kanonak[];
|
|
69
|
+
/** Repository for cross-package reference resolution at evaluation time. */
|
|
70
|
+
repository: IKanonakDocumentRepository;
|
|
71
|
+
parser: KanonakParser;
|
|
72
|
+
objectParser: KanonakObjectParser;
|
|
73
|
+
/** OutputFormat local name (e.g. `'markdown-with-frontmatter'`). */
|
|
74
|
+
outputFormat: string;
|
|
75
|
+
}
|
|
76
|
+
export declare class TransformationRunnerErrorV3 extends Error {
|
|
77
|
+
}
|
|
78
|
+
export declare class TransformationRunnerV3 {
|
|
79
|
+
private readonly backends;
|
|
80
|
+
constructor();
|
|
81
|
+
register(backend: IDocumentAstBackend): void;
|
|
82
|
+
run(input: RunInputV3): Promise<ArtifactV3[]>;
|
|
83
|
+
private runInstance;
|
|
84
|
+
private runSet;
|
|
85
|
+
private runSetSingle;
|
|
86
|
+
private runSetWithPartition;
|
|
87
|
+
private findBackend;
|
|
88
|
+
}
|
|
89
|
+
export { TransformationLoadErrorV3 };
|
|
90
|
+
export type { CompiledTransformationV3 };
|
|
@@ -0,0 +1,131 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Hardcoded canonical URIs for the transformations@3.0.0 ontology.
|
|
3
|
+
*
|
|
4
|
+
* Versioned in the file path (`v3/`) and the symbol (`TX_V3`) so a
|
|
5
|
+
* future v4 ontology can ship a sibling `v4/TransformationUriConstantsV4.ts`
|
|
6
|
+
* and the runtime can dispatch by the resolved type's package version
|
|
7
|
+
* without forcing existing v3 transformations to upgrade.
|
|
8
|
+
*
|
|
9
|
+
* Per the typescript repo's CLAUDE.md rule 6, hardcoded URI constants
|
|
10
|
+
* are fine and expected — they are the ontology contract. String
|
|
11
|
+
* heuristics on aliases or suffixes are NOT.
|
|
12
|
+
*/
|
|
13
|
+
import type { EntityUri } from '../../capabilities/UriHelpers.js';
|
|
14
|
+
export declare const TX_V3_PUB = "kanonak.org";
|
|
15
|
+
export declare const TX_V3_PKG = "transformations";
|
|
16
|
+
export declare const TX_V3_VERSION_MAJOR = 3;
|
|
17
|
+
export declare const TX_V3: {
|
|
18
|
+
readonly Transformation: EntityUri;
|
|
19
|
+
readonly InstanceTransformation: EntityUri;
|
|
20
|
+
readonly SetTransformation: EntityUri;
|
|
21
|
+
readonly inputPattern: EntityUri;
|
|
22
|
+
readonly rule: EntityUri;
|
|
23
|
+
readonly artifactName: EntityUri;
|
|
24
|
+
readonly outputs: EntityUri;
|
|
25
|
+
readonly formatOverrides: EntityUri;
|
|
26
|
+
readonly partitionBy: EntityUri;
|
|
27
|
+
readonly InputPattern: EntityUri;
|
|
28
|
+
readonly matchesClass: EntityUri;
|
|
29
|
+
readonly requires: EntityUri;
|
|
30
|
+
readonly sortBy: EntityUri;
|
|
31
|
+
readonly SortKey: EntityUri;
|
|
32
|
+
readonly byProperty: EntityUri;
|
|
33
|
+
readonly order: EntityUri;
|
|
34
|
+
readonly SortOrder: EntityUri;
|
|
35
|
+
readonly ascending: EntityUri;
|
|
36
|
+
readonly descending: EntityUri;
|
|
37
|
+
readonly OutputFormat: EntityUri;
|
|
38
|
+
readonly backendUri: EntityUri;
|
|
39
|
+
readonly FormatOverride: EntityUri;
|
|
40
|
+
readonly formatTarget: EntityUri;
|
|
41
|
+
readonly metadataKeys: EntityUri;
|
|
42
|
+
readonly metadataRenames: EntityUri;
|
|
43
|
+
readonly trailingNewline: EntityUri;
|
|
44
|
+
readonly RenameEntry: EntityUri;
|
|
45
|
+
readonly fromKey: EntityUri;
|
|
46
|
+
readonly toKey: EntityUri;
|
|
47
|
+
readonly FMT_MARKDOWN_FRONTMATTER: EntityUri;
|
|
48
|
+
readonly FMT_PLAIN_MARKDOWN: EntityUri;
|
|
49
|
+
readonly FMT_TOML: EntityUri;
|
|
50
|
+
readonly FMT_JSON: EntityUri;
|
|
51
|
+
readonly FMT_HTML: EntityUri;
|
|
52
|
+
readonly FMT_SVG: EntityUri;
|
|
53
|
+
readonly Expression: EntityUri;
|
|
54
|
+
readonly ListSourcedExpression: EntityUri;
|
|
55
|
+
readonly ListAggregate: EntityUri;
|
|
56
|
+
readonly IteratingExpression: EntityUri;
|
|
57
|
+
readonly BuildAstNode: EntityUri;
|
|
58
|
+
readonly astClass: EntityUri;
|
|
59
|
+
readonly set: EntityUri;
|
|
60
|
+
readonly AstFieldBinding: EntityUri;
|
|
61
|
+
readonly field: EntityUri;
|
|
62
|
+
readonly bindValue: EntityUri;
|
|
63
|
+
readonly When: EntityUri;
|
|
64
|
+
readonly condition: EntityUri;
|
|
65
|
+
readonly thenBuild: EntityUri;
|
|
66
|
+
readonly elseBuild: EntityUri;
|
|
67
|
+
readonly Concat: EntityUri;
|
|
68
|
+
readonly parts: EntityUri;
|
|
69
|
+
readonly Fallback: EntityUri;
|
|
70
|
+
readonly primary: EntityUri;
|
|
71
|
+
readonly alternate: EntityUri;
|
|
72
|
+
readonly StringLiteral: EntityUri;
|
|
73
|
+
readonly stringLiteral: EntityUri;
|
|
74
|
+
readonly IntegerLiteral: EntityUri;
|
|
75
|
+
readonly integerLiteral: EntityUri;
|
|
76
|
+
readonly DecimalLiteral: EntityUri;
|
|
77
|
+
readonly decimalLiteral: EntityUri;
|
|
78
|
+
readonly BooleanLiteral: EntityUri;
|
|
79
|
+
readonly booleanLiteral: EntityUri;
|
|
80
|
+
readonly VarRef: EntityUri;
|
|
81
|
+
readonly varName: EntityUri;
|
|
82
|
+
readonly PropertyRead: EntityUri;
|
|
83
|
+
readonly readSource: EntityUri;
|
|
84
|
+
readonly readProp: EntityUri;
|
|
85
|
+
readonly Traverse: EntityUri;
|
|
86
|
+
readonly traverseSource: EntityUri;
|
|
87
|
+
readonly through: EntityUri;
|
|
88
|
+
readonly step: EntityUri;
|
|
89
|
+
readonly UriName: EntityUri;
|
|
90
|
+
readonly uriNameOf: EntityUri;
|
|
91
|
+
readonly UriLiteral: EntityUri;
|
|
92
|
+
readonly refTo: EntityUri;
|
|
93
|
+
readonly DisplayLabel: EntityUri;
|
|
94
|
+
readonly labelTarget: EntityUri;
|
|
95
|
+
readonly labelSource: EntityUri;
|
|
96
|
+
readonly ResolveRef: EntityUri;
|
|
97
|
+
readonly resolveSource: EntityUri;
|
|
98
|
+
readonly Normalize: EntityUri;
|
|
99
|
+
readonly normSource: EntityUri;
|
|
100
|
+
readonly normKind: EntityUri;
|
|
101
|
+
readonly NormalizeKind: EntityUri;
|
|
102
|
+
readonly NORM_TRIM_END: EntityUri;
|
|
103
|
+
readonly IsSet: EntityUri;
|
|
104
|
+
readonly checkExpr: EntityUri;
|
|
105
|
+
readonly ExpressionFragment: EntityUri;
|
|
106
|
+
readonly body: EntityUri;
|
|
107
|
+
readonly CallFragment: EntityUri;
|
|
108
|
+
readonly fragmentRef: EntityUri;
|
|
109
|
+
readonly source: EntityUri;
|
|
110
|
+
readonly Join: EntityUri;
|
|
111
|
+
readonly separator: EntityUri;
|
|
112
|
+
readonly Count: EntityUri;
|
|
113
|
+
readonly Sum: EntityUri;
|
|
114
|
+
readonly Min: EntityUri;
|
|
115
|
+
readonly Max: EntityUri;
|
|
116
|
+
readonly Average: EntityUri;
|
|
117
|
+
readonly loopVar: EntityUri;
|
|
118
|
+
readonly ForEach: EntityUri;
|
|
119
|
+
readonly emit: EntityUri;
|
|
120
|
+
readonly ListMap: EntityUri;
|
|
121
|
+
readonly mapBody: EntityUri;
|
|
122
|
+
readonly Filter: EntityUri;
|
|
123
|
+
readonly predicate: EntityUri;
|
|
124
|
+
readonly PartitionBy: EntityUri;
|
|
125
|
+
readonly partitionKey: EntityUri;
|
|
126
|
+
readonly DistinctBy: EntityUri;
|
|
127
|
+
readonly distinctKey: EntityUri;
|
|
128
|
+
readonly Partition: EntityUri;
|
|
129
|
+
readonly key: EntityUri;
|
|
130
|
+
readonly members: EntityUri;
|
|
131
|
+
};
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@kanonak-protocol/cli",
|
|
3
|
-
"version": "
|
|
3
|
+
"version": "3.0.0",
|
|
4
4
|
"description": "Kanonak Protocol CLI - Validate and resolve Kanonak ontology packages",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "./dist/index.js",
|
|
@@ -34,8 +34,8 @@
|
|
|
34
34
|
"semantic-web"
|
|
35
35
|
],
|
|
36
36
|
"dependencies": {
|
|
37
|
-
"@kanonak-protocol/sdk": "^
|
|
38
|
-
"@kanonak-protocol/types": "^
|
|
37
|
+
"@kanonak-protocol/sdk": "^3.0.0",
|
|
38
|
+
"@kanonak-protocol/types": "^3.0.0",
|
|
39
39
|
"commander": "^13.0.0",
|
|
40
40
|
"js-yaml": "^4.1.1"
|
|
41
41
|
},
|