@kubohiroya/turbowarp-http-server 0.1.0 → 0.2.1

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.
Files changed (234) hide show
  1. package/README.ja.md +29 -13
  2. package/README.md +101 -42
  3. package/dist/cli.js +131 -17
  4. package/dist/cli.js.map +1 -1
  5. package/dist/compiler/adapters/cloudflare.d.ts +2 -0
  6. package/dist/compiler/adapters/cloudflare.js +477 -0
  7. package/dist/compiler/adapters/cloudflare.js.map +1 -0
  8. package/dist/compiler/adapters/firebase.d.ts +2 -0
  9. package/dist/compiler/adapters/firebase.js +489 -0
  10. package/dist/compiler/adapters/firebase.js.map +1 -0
  11. package/dist/compiler/adapters/index.d.ts +2 -0
  12. package/dist/compiler/adapters/index.js +3 -0
  13. package/dist/compiler/adapters/index.js.map +1 -0
  14. package/dist/compiler/binary/codec.d.ts +4 -0
  15. package/dist/compiler/binary/codec.js +45 -0
  16. package/dist/compiler/binary/codec.js.map +1 -0
  17. package/dist/compiler/binary/error.d.ts +3 -0
  18. package/dist/compiler/binary/error.js +21 -0
  19. package/dist/compiler/binary/error.js.map +1 -0
  20. package/dist/compiler/binary/index.d.ts +4 -0
  21. package/dist/compiler/binary/index.js +5 -0
  22. package/dist/compiler/binary/index.js.map +1 -0
  23. package/dist/compiler/binary/runtime.d.ts +18 -0
  24. package/dist/compiler/binary/runtime.js +123 -0
  25. package/dist/compiler/binary/runtime.js.map +1 -0
  26. package/dist/compiler/binary/types.d.ts +17 -0
  27. package/dist/compiler/binary/types.js +2 -0
  28. package/dist/compiler/binary/types.js.map +1 -0
  29. package/dist/compiler/feature-flags.d.ts +4 -0
  30. package/dist/compiler/feature-flags.js +4 -0
  31. package/dist/compiler/feature-flags.js.map +1 -0
  32. package/dist/compiler/index.d.ts +35 -0
  33. package/dist/compiler/index.js +84 -0
  34. package/dist/compiler/index.js.map +1 -0
  35. package/dist/compiler/ir-v2/canonical.d.ts +3 -0
  36. package/dist/compiler/ir-v2/canonical.js +50 -0
  37. package/dist/compiler/ir-v2/canonical.js.map +1 -0
  38. package/dist/compiler/ir-v2/index.d.ts +4 -0
  39. package/dist/compiler/ir-v2/index.js +5 -0
  40. package/dist/compiler/ir-v2/index.js.map +1 -0
  41. package/dist/compiler/ir-v2/parse.d.ts +10 -0
  42. package/dist/compiler/ir-v2/parse.js +753 -0
  43. package/dist/compiler/ir-v2/parse.js.map +1 -0
  44. package/dist/compiler/ir-v2/strict-json.d.ts +4 -0
  45. package/dist/compiler/ir-v2/strict-json.js +133 -0
  46. package/dist/compiler/ir-v2/strict-json.js.map +1 -0
  47. package/dist/compiler/ir-v2/types.d.ts +412 -0
  48. package/dist/compiler/ir-v2/types.js +84 -0
  49. package/dist/compiler/ir-v2/types.js.map +1 -0
  50. package/dist/compiler/kvs/lowering.d.ts +13 -0
  51. package/dist/compiler/kvs/lowering.js +77 -0
  52. package/dist/compiler/kvs/lowering.js.map +1 -0
  53. package/dist/compiler/manifest/error.d.ts +7 -0
  54. package/dist/compiler/manifest/error.js +9 -0
  55. package/dist/compiler/manifest/error.js.map +1 -0
  56. package/dist/compiler/manifest/index.d.ts +6 -0
  57. package/dist/compiler/manifest/index.js +7 -0
  58. package/dist/compiler/manifest/index.js.map +1 -0
  59. package/dist/compiler/manifest/operations.d.ts +12 -0
  60. package/dist/compiler/manifest/operations.js +60 -0
  61. package/dist/compiler/manifest/operations.js.map +1 -0
  62. package/dist/compiler/manifest/parse.d.ts +9 -0
  63. package/dist/compiler/manifest/parse.js +280 -0
  64. package/dist/compiler/manifest/parse.js.map +1 -0
  65. package/dist/compiler/manifest/registry.d.ts +3 -0
  66. package/dist/compiler/manifest/registry.js +48 -0
  67. package/dist/compiler/manifest/registry.js.map +1 -0
  68. package/dist/compiler/manifest/resolve.d.ts +14 -0
  69. package/dist/compiler/manifest/resolve.js +116 -0
  70. package/dist/compiler/manifest/resolve.js.map +1 -0
  71. package/dist/compiler/manifest/types.d.ts +95 -0
  72. package/dist/compiler/manifest/types.js +3 -0
  73. package/dist/compiler/manifest/types.js.map +1 -0
  74. package/dist/compiler/named-body/index.d.ts +1 -0
  75. package/dist/compiler/named-body/index.js +2 -0
  76. package/dist/compiler/named-body/index.js.map +1 -0
  77. package/dist/compiler/named-body/lowering.d.ts +18 -0
  78. package/dist/compiler/named-body/lowering.js +83 -0
  79. package/dist/compiler/named-body/lowering.js.map +1 -0
  80. package/dist/compiler/pipeline/compiler.d.ts +18 -0
  81. package/dist/compiler/pipeline/compiler.js +105 -0
  82. package/dist/compiler/pipeline/compiler.js.map +1 -0
  83. package/dist/compiler/pipeline/core-generator.d.ts +3 -0
  84. package/dist/compiler/pipeline/core-generator.js +483 -0
  85. package/dist/compiler/pipeline/core-generator.js.map +1 -0
  86. package/dist/compiler/pipeline/index.d.ts +5 -0
  87. package/dist/compiler/pipeline/index.js +6 -0
  88. package/dist/compiler/pipeline/index.js.map +1 -0
  89. package/dist/compiler/pipeline/registry.d.ts +7 -0
  90. package/dist/compiler/pipeline/registry.js +17 -0
  91. package/dist/compiler/pipeline/registry.js.map +1 -0
  92. package/dist/compiler/pipeline/requirements.d.ts +9 -0
  93. package/dist/compiler/pipeline/requirements.js +135 -0
  94. package/dist/compiler/pipeline/requirements.js.map +1 -0
  95. package/dist/compiler/pipeline/types.d.ts +65 -0
  96. package/dist/compiler/pipeline/types.js +2 -0
  97. package/dist/compiler/pipeline/types.js.map +1 -0
  98. package/dist/compiler/runtime/error.d.ts +6 -0
  99. package/dist/compiler/runtime/error.js +9 -0
  100. package/dist/compiler/runtime/error.js.map +1 -0
  101. package/dist/compiler/runtime/index.d.ts +1 -0
  102. package/dist/compiler/runtime/index.js +2 -0
  103. package/dist/compiler/runtime/index.js.map +1 -0
  104. package/dist/compiler/structured-data/index.d.ts +3 -0
  105. package/dist/compiler/structured-data/index.js +4 -0
  106. package/dist/compiler/structured-data/index.js.map +1 -0
  107. package/dist/compiler/structured-data/lowering.d.ts +30 -0
  108. package/dist/compiler/structured-data/lowering.js +202 -0
  109. package/dist/compiler/structured-data/lowering.js.map +1 -0
  110. package/dist/compiler/structured-data/path.d.ts +2 -0
  111. package/dist/compiler/structured-data/path.js +60 -0
  112. package/dist/compiler/structured-data/path.js.map +1 -0
  113. package/dist/compiler/structured-data/runtime.d.ts +20 -0
  114. package/dist/compiler/structured-data/runtime.js +210 -0
  115. package/dist/compiler/structured-data/runtime.js.map +1 -0
  116. package/dist/compiler/turbowarp-v2.d.ts +8 -0
  117. package/dist/compiler/turbowarp-v2.js +479 -0
  118. package/dist/compiler/turbowarp-v2.js.map +1 -0
  119. package/dist/compiler/validator/index.d.ts +4 -0
  120. package/dist/compiler/validator/index.js +5 -0
  121. package/dist/compiler/validator/index.js.map +1 -0
  122. package/dist/compiler/validator/ir-validator.d.ts +10 -0
  123. package/dist/compiler/validator/ir-validator.js +463 -0
  124. package/dist/compiler/validator/ir-validator.js.map +1 -0
  125. package/dist/compiler/validator/resource-lifetime.d.ts +18 -0
  126. package/dist/compiler/validator/resource-lifetime.js +106 -0
  127. package/dist/compiler/validator/resource-lifetime.js.map +1 -0
  128. package/dist/compiler/validator/turbowarp-subset.d.ts +3 -0
  129. package/dist/compiler/validator/turbowarp-subset.js +241 -0
  130. package/dist/compiler/validator/turbowarp-subset.js.map +1 -0
  131. package/dist/compiler/validator/types.d.ts +30 -0
  132. package/dist/compiler/validator/types.js +7 -0
  133. package/dist/compiler/validator/types.js.map +1 -0
  134. package/dist/config.d.ts +11 -0
  135. package/dist/config.js +12 -0
  136. package/dist/config.js.map +1 -0
  137. package/dist/digest-cli.js +0 -0
  138. package/dist/extension-manifest.json +102 -0
  139. package/dist/named-body.d.ts +57 -0
  140. package/dist/named-body.js +396 -0
  141. package/dist/named-body.js.map +1 -0
  142. package/dist/named-data-namespace.d.ts +3 -0
  143. package/dist/named-data-namespace.js +6 -0
  144. package/dist/named-data-namespace.js.map +1 -0
  145. package/dist/protocol.d.ts +13 -1
  146. package/dist/protocol.js +34 -0
  147. package/dist/protocol.js.map +1 -1
  148. package/dist/resource-named-body-provider.d.ts +8 -0
  149. package/dist/resource-named-body-provider.js +88 -0
  150. package/dist/resource-named-body-provider.js.map +1 -0
  151. package/dist/server.d.ts +10 -1
  152. package/dist/server.js +37 -7
  153. package/dist/server.js.map +1 -1
  154. package/dist/turbowarp-http-server.js +516 -1
  155. package/docs/binary-resource-semantics.ja.md +84 -0
  156. package/docs/cloudflare-worker-compiler.ja.md +90 -0
  157. package/docs/compiler-manifest-registry.ja.md +79 -0
  158. package/docs/compiler-platform-pipeline.ja.md +94 -0
  159. package/docs/deploy-ir-v2.ja.md +123 -0
  160. package/docs/fixed-input-editors.ja.md +23 -0
  161. package/docs/index.html +80 -0
  162. package/docs/ir-v2-conformance.ja.md +65 -0
  163. package/docs/named-response-body.ja.md +120 -0
  164. package/docs/platform-storage-adapters.ja.md +99 -0
  165. package/docs/server-executable-subset.ja.md +88 -0
  166. package/docs/structured-data-lowering.ja.md +63 -0
  167. package/examples/compiler/message-app.v2.ir.json +41 -0
  168. package/package.json +44 -20
  169. package/schemas/block-editor-fixed-inputs.schema.json +85 -0
  170. package/schemas/compiler-extension-manifest.schema.json +126 -0
  171. package/schemas/compiler-manifest-lock-v1.schema.json +48 -0
  172. package/schemas/deploy-ir-v2.schema.json +835 -0
  173. package/schemas/ir-v2-conformance-fixture.schema.json +44 -0
  174. package/src/block-definitions.json +76 -0
  175. package/src/cli.ts +136 -23
  176. package/src/compiler/adapters/cloudflare.ts +510 -0
  177. package/src/compiler/adapters/firebase.ts +538 -0
  178. package/src/compiler/adapters/index.ts +2 -0
  179. package/src/compiler/binary/codec.ts +61 -0
  180. package/src/compiler/binary/error.ts +25 -0
  181. package/src/compiler/binary/index.ts +4 -0
  182. package/src/compiler/binary/runtime.ts +133 -0
  183. package/src/compiler/binary/types.ts +26 -0
  184. package/src/compiler/feature-flags.ts +7 -0
  185. package/src/compiler/index.ts +114 -0
  186. package/src/compiler/ir-v2/canonical.ts +46 -0
  187. package/src/compiler/ir-v2/index.ts +9 -0
  188. package/src/compiler/ir-v2/parse.ts +921 -0
  189. package/src/compiler/ir-v2/strict-json.ts +129 -0
  190. package/src/compiler/ir-v2/types.ts +462 -0
  191. package/src/compiler/kvs/lowering.ts +88 -0
  192. package/src/compiler/manifest/error.ts +29 -0
  193. package/src/compiler/manifest/index.ts +17 -0
  194. package/src/compiler/manifest/operations.ts +175 -0
  195. package/src/compiler/manifest/parse.ts +390 -0
  196. package/src/compiler/manifest/registry.ts +74 -0
  197. package/src/compiler/manifest/resolve.ts +159 -0
  198. package/src/compiler/manifest/types.ts +112 -0
  199. package/src/compiler/named-body/index.ts +1 -0
  200. package/src/compiler/named-body/lowering.ts +186 -0
  201. package/src/compiler/pipeline/compiler.ts +138 -0
  202. package/src/compiler/pipeline/core-generator.ts +486 -0
  203. package/src/compiler/pipeline/index.ts +5 -0
  204. package/src/compiler/pipeline/registry.ts +18 -0
  205. package/src/compiler/pipeline/requirements.ts +139 -0
  206. package/src/compiler/pipeline/types.ts +59 -0
  207. package/src/compiler/runtime/error.ts +11 -0
  208. package/src/compiler/runtime/index.ts +1 -0
  209. package/src/compiler/structured-data/index.ts +3 -0
  210. package/src/compiler/structured-data/lowering.ts +314 -0
  211. package/src/compiler/structured-data/path.ts +53 -0
  212. package/src/compiler/structured-data/runtime.ts +221 -0
  213. package/src/compiler/turbowarp-v2.ts +610 -0
  214. package/src/compiler/validator/index.ts +4 -0
  215. package/src/compiler/validator/ir-validator.ts +812 -0
  216. package/src/compiler/validator/resource-lifetime.ts +153 -0
  217. package/src/compiler/validator/turbowarp-subset.ts +387 -0
  218. package/src/compiler/validator/types.ts +68 -0
  219. package/src/extension.ts +87 -1
  220. package/src/fixed-input-editors.ts +181 -0
  221. package/src/fixed-input-schema.ts +15 -0
  222. package/src/named-body.ts +495 -0
  223. package/src/named-data-namespace.ts +6 -0
  224. package/src/protocol.ts +50 -1
  225. package/src/resource-named-body-provider.ts +106 -0
  226. package/src/server.ts +88 -8
  227. package/docs/turbowarp-http-server.architecture.visual-check.1440x900.dark.png +0 -0
  228. package/docs/turbowarp-http-server.architecture.visual-check.1440x900.light.png +0 -0
  229. package/docs/turbowarp-http-server.architecture.visual-check.2048x1320.dark.png +0 -0
  230. package/docs/turbowarp-http-server.architecture.visual-check.2048x1320.light.png +0 -0
  231. package/docs/turbowarp-http-server.architecture.visual-check.html +0 -32
  232. package/docs/turbowarp-http-server.architecture.visual-check.json +0 -547
  233. package/schemas/extension-manifest.schema.json +0 -49
  234. package/src/extension-manifest.ts +0 -149
@@ -0,0 +1,59 @@
1
+ import type {DeployIrV2, SourceRefV2} from '../ir-v2/types.js';
2
+
3
+ export type GeneratedProject = Record<string, string>;
4
+
5
+ export interface GeneratedCore {
6
+ files: GeneratedProject;
7
+ entryModule: string;
8
+ }
9
+
10
+ export interface CapabilityRequirements {
11
+ keys: readonly string[];
12
+ }
13
+
14
+ export interface PlatformCapabilities {
15
+ keys: readonly string[];
16
+ maxBinaryBytes?: number;
17
+ }
18
+
19
+ export interface PlatformPlan {
20
+ targetId: string;
21
+ adapterVersion: string;
22
+ requirements: readonly string[];
23
+ bindings: Readonly<Record<string, string>>;
24
+ }
25
+
26
+ export interface PipelineDiagnostic {
27
+ severity: 'error';
28
+ code: `TW2_${string}`;
29
+ message: string;
30
+ reason: string;
31
+ suggestion: string;
32
+ targetId?: string;
33
+ routeId?: string;
34
+ sourceRef?: SourceRefV2;
35
+ }
36
+
37
+ export type PlanResult =
38
+ | {ok: true; plan: PlatformPlan}
39
+ | {ok: false; diagnostics: PipelineDiagnostic[]};
40
+
41
+ export interface PlatformAdapter {
42
+ readonly id: string;
43
+ readonly version: string;
44
+ capabilities(): PlatformCapabilities;
45
+ plan(input: {ir: DeployIrV2; requirements: CapabilityRequirements; config: unknown}): PlanResult;
46
+ generate(input: {ir: DeployIrV2; plan: PlatformPlan; core: GeneratedCore}): GeneratedProject;
47
+ }
48
+
49
+ export interface GeneratorOutputManifest {
50
+ formatVersion: 1;
51
+ irVersion: 2;
52
+ adapter: {id: string; version: string};
53
+ requirements: readonly string[];
54
+ plan: {
55
+ requirements: readonly string[];
56
+ bindings: Readonly<Record<string, string>>;
57
+ };
58
+ files: readonly string[];
59
+ }
@@ -0,0 +1,11 @@
1
+ export class IrRuntimeError extends Error {
2
+ public readonly name = 'IrRuntimeError';
3
+
4
+ public constructor(
5
+ public readonly code: string,
6
+ message: string,
7
+ public readonly httpStatus: number
8
+ ) {
9
+ super(message);
10
+ }
11
+ }
@@ -0,0 +1 @@
1
+ export {IrRuntimeError} from './error.js';
@@ -0,0 +1,3 @@
1
+ export * from './lowering.js';
2
+ export {parseStructuredDataPath} from './path.js';
3
+ export * from './runtime.js';
@@ -0,0 +1,314 @@
1
+ import type {CompilerOpcodeRegistryEntry} from '../manifest/types.js';
2
+ import {
3
+ JSON_VALUE_TYPE_V2,
4
+ type AtomicValueTypeV2,
5
+ type ExpressionIrV2,
6
+ type JsonValue,
7
+ type PathSegmentV2,
8
+ type SourceRefV2,
9
+ type StatementIrV2
10
+ } from '../ir-v2/types.js';
11
+ import {IrRuntimeError} from '../runtime/error.js';
12
+ import {isValidApplicationJson, parseApplicationJson} from './runtime.js';
13
+ import {parseStructuredDataPath} from './path.js';
14
+
15
+ export type StructuredDataLoweringDiagnosticCode =
16
+ | 'TW2_STRUCTURED_INVALID_LITERAL'
17
+ | 'TW2_STRUCTURED_DYNAMIC_PATH'
18
+ | 'TW2_STRUCTURED_INVALID_PATH'
19
+ | 'TW2_STRUCTURED_INVALID_MAX'
20
+ | 'TW2_STRUCTURED_TYPE_MISMATCH'
21
+ | 'TW2_ITERATION_CONTEXT_REQUIRED'
22
+ | 'TW2_UNSUPPORTED_OPERATION';
23
+
24
+ export interface StructuredDataLoweringDiagnostic {
25
+ severity: 'error';
26
+ code: StructuredDataLoweringDiagnosticCode;
27
+ message: string;
28
+ reason: string;
29
+ suggestion: string;
30
+ sourceRef: SourceRefV2;
31
+ }
32
+
33
+ export type StructuredDataArguments = Readonly<Record<string, ExpressionIrV2>>;
34
+
35
+ export const STRUCTURED_DATA_PACKAGE_NAME = '@kubohiroya/turbowarp-structured-data';
36
+ export const STRUCTURED_DATA_PACKAGE_VERSION = '0.4.0';
37
+
38
+ export class StructuredDataLoweringContext {
39
+ public readonly diagnostics: StructuredDataLoweringDiagnostic[];
40
+
41
+ public constructor(
42
+ diagnostics: StructuredDataLoweringDiagnostic[] = [],
43
+ private readonly loopIds: readonly string[] = []
44
+ ) {
45
+ this.diagnostics = diagnostics;
46
+ }
47
+
48
+ public lowerReporter(
49
+ entry: CompilerOpcodeRegistryEntry,
50
+ args: StructuredDataArguments,
51
+ sourceRef: SourceRefV2
52
+ ): ExpressionIrV2 | undefined {
53
+ const operation = this.operation(entry, sourceRef);
54
+ if (operation === undefined) return undefined;
55
+ if (operation === 'structuredData.currentKey') return this.current('key', sourceRef);
56
+ if (operation === 'structuredData.currentIndex') return this.current('index', sourceRef);
57
+ if (operation === 'structuredData.currentValue') {
58
+ const value = this.current('value', sourceRef);
59
+ return value === undefined ? undefined : jsonStringify(value, sourceRef);
60
+ }
61
+
62
+ const jsonArgument = requireArgument(args, 'JSON');
63
+ if (jsonArgument === undefined) return this.missingArgument('JSON', sourceRef);
64
+ if (operation === 'structuredData.isValidJson') {
65
+ if (isLiteralText(jsonArgument)) return literal('boolean', isValidApplicationJson(jsonArgument.value), sourceRef);
66
+ const text = this.jsonText(jsonArgument, sourceRef);
67
+ return text === undefined ? undefined : {kind: 'json-is-valid', valueType: 'boolean', text, sourceRef};
68
+ }
69
+ const root = this.parseJsonArgument(jsonArgument, inputSource(sourceRef, 'JSON'));
70
+ if (root === undefined) return undefined;
71
+ if (operation === 'structuredData.normalizeJson') return jsonStringify(root, sourceRef);
72
+
73
+ const path = this.literalPath(args.PATH, inputSource(sourceRef, 'PATH'));
74
+ if (path === undefined) return undefined;
75
+ if (operation === 'structuredData.get') {
76
+ return jsonStringify({kind: 'json-get', valueType: JSON_VALUE_TYPE_V2, root, path, sourceRef}, sourceRef);
77
+ }
78
+ if (operation === 'structuredData.has') return {kind: 'json-has', valueType: 'boolean', root, path, sourceRef};
79
+ if (operation === 'structuredData.delete') {
80
+ if (path.length === 0) {
81
+ this.report(
82
+ 'TW2_STRUCTURED_INVALID_PATH',
83
+ 'Structured Data delete cannot target the root path.',
84
+ 'The browser extension rejects deleting the root value.',
85
+ 'Delete a child key/index or use a different root value.',
86
+ inputSource(sourceRef, 'PATH')
87
+ );
88
+ return undefined;
89
+ }
90
+ return jsonStringify({kind: 'json-delete', valueType: JSON_VALUE_TYPE_V2, root, path, sourceRef}, sourceRef);
91
+ }
92
+ if (operation === 'structuredData.keys') {
93
+ return jsonStringify({kind: 'json-keys', valueType: 'json-array', root, path, sourceRef}, sourceRef);
94
+ }
95
+ if (operation === 'structuredData.length') {
96
+ return {kind: 'json-length', valueType: 'number', root, path, sourceRef};
97
+ }
98
+ if (operation === 'structuredData.set') {
99
+ const valueArgument = requireArgument(args, 'VALUE');
100
+ if (valueArgument === undefined) return this.missingArgument('VALUE', sourceRef);
101
+ const value = this.parseJsonArgument(valueArgument, inputSource(sourceRef, 'VALUE'));
102
+ return value === undefined
103
+ ? undefined
104
+ : jsonStringify({kind: 'json-set', valueType: JSON_VALUE_TYPE_V2, root, path, value, sourceRef}, sourceRef);
105
+ }
106
+ this.unsupported(operation, sourceRef);
107
+ }
108
+
109
+ public lowerForEach(
110
+ entry: CompilerOpcodeRegistryEntry,
111
+ args: StructuredDataArguments,
112
+ sourceRef: SourceRefV2,
113
+ lowerBody: (context: StructuredDataLoweringContext) => StatementIrV2[]
114
+ ): StatementIrV2 | undefined {
115
+ const operation = this.operation(entry, sourceRef);
116
+ if (operation !== 'structuredData.forEach') {
117
+ if (operation !== undefined) this.unsupported(operation, sourceRef);
118
+ return undefined;
119
+ }
120
+ const jsonArgument = requireArgument(args, 'JSON');
121
+ if (jsonArgument === undefined) return this.missingArgument('JSON', sourceRef);
122
+ const root = this.parseJsonArgument(jsonArgument, inputSource(sourceRef, 'JSON'));
123
+ const path = this.literalPath(args.PATH, inputSource(sourceRef, 'PATH'));
124
+ const maxIterations = this.literalMaximum(args.MAX, inputSource(sourceRef, 'MAX'));
125
+ if (root === undefined || path === undefined || maxIterations === undefined) return undefined;
126
+ const loopId = `structured_${sourceRef.targetIndex}_${sanitizeId(sourceRef.blockId)}`;
127
+ const nested = new StructuredDataLoweringContext(this.diagnostics, [...this.loopIds, loopId]);
128
+ const body = lowerBody(nested);
129
+ return {kind: 'json-for-each', loopId, root, path, maxIterations, body, sourceRef};
130
+ }
131
+
132
+ private operation(entry: CompilerOpcodeRegistryEntry, sourceRef: SourceRefV2): string | undefined {
133
+ if (
134
+ entry.extensionId !== 'kubohiroyastructureddata' ||
135
+ entry.packageName !== STRUCTURED_DATA_PACKAGE_NAME ||
136
+ entry.packageVersion !== STRUCTURED_DATA_PACKAGE_VERSION ||
137
+ entry.block.server?.supported !== true ||
138
+ entry.block.server.irOperation === undefined
139
+ ) {
140
+ this.unsupported(entry.projectOpcode, sourceRef);
141
+ return undefined;
142
+ }
143
+ return entry.block.server.irOperation;
144
+ }
145
+
146
+ private current(
147
+ field: 'key' | 'index' | 'value',
148
+ sourceRef: SourceRefV2
149
+ ): ExpressionIrV2 | undefined {
150
+ const loopId = this.loopIds[this.loopIds.length - 1];
151
+ if (loopId === undefined) {
152
+ this.report(
153
+ 'TW2_ITERATION_CONTEXT_REQUIRED',
154
+ `Structured Data current ${field} requires an enclosing for-each.`,
155
+ 'Iteration reporters bind to the nearest lexical Structured Data loop.',
156
+ 'Move the reporter into a for-each body.',
157
+ sourceRef
158
+ );
159
+ return undefined;
160
+ }
161
+ if (field === 'key') return {kind: 'iteration-key', valueType: 'string', loopId, sourceRef};
162
+ if (field === 'index') return {kind: 'iteration-index', valueType: 'number', loopId, sourceRef};
163
+ return {kind: 'iteration-value', valueType: JSON_VALUE_TYPE_V2, loopId, sourceRef};
164
+ }
165
+
166
+ private parseJsonArgument(expression: ExpressionIrV2, sourceRef: SourceRefV2): ExpressionIrV2 | undefined {
167
+ if (isLiteralText(expression)) {
168
+ try {
169
+ const value = parseApplicationJson(expression.value);
170
+ return literal(jsonLiteralType(value), value, sourceRef);
171
+ } catch (error) {
172
+ if (!(error instanceof IrRuntimeError)) throw error;
173
+ this.report(
174
+ 'TW2_STRUCTURED_INVALID_LITERAL',
175
+ 'Structured Data JSON literal is invalid.',
176
+ 'Literal JSON is validated during compilation instead of deferring a known failure to runtime.',
177
+ 'Provide valid JSON text.',
178
+ sourceRef
179
+ );
180
+ return undefined;
181
+ }
182
+ }
183
+ const text = this.jsonText(expression, sourceRef);
184
+ return text === undefined ? undefined : {kind: 'json-parse', valueType: JSON_VALUE_TYPE_V2, text, sourceRef};
185
+ }
186
+
187
+ private jsonText(expression: ExpressionIrV2, sourceRef: SourceRefV2): ExpressionIrV2 | undefined {
188
+ if (expression.valueType === 'json-text') return expression;
189
+ if (expression.valueType === 'string') {
190
+ return {kind: 'json-text-coerce', valueType: 'json-text', input: expression, sourceRef};
191
+ }
192
+ this.report(
193
+ 'TW2_STRUCTURED_TYPE_MISMATCH',
194
+ 'Structured Data JSON input must be string or json-text.',
195
+ 'Application JSON text is a nominal boundary and is not interchangeable with typed JSON values.',
196
+ 'Serialize the typed JSON value or pass a string expression.',
197
+ sourceRef
198
+ );
199
+ return undefined;
200
+ }
201
+
202
+ private literalPath(expression: ExpressionIrV2 | undefined, sourceRef: SourceRefV2): PathSegmentV2[] | undefined {
203
+ if (!isLiteralText(expression)) {
204
+ this.report(
205
+ 'TW2_STRUCTURED_DYNAMIC_PATH',
206
+ 'Structured Data path must be a compile-time string literal.',
207
+ 'The MVP accepts only the locked tw-structured-path grammar and does not evaluate dynamic paths.',
208
+ 'Replace the path input with a literal such as $.items[0].',
209
+ sourceRef
210
+ );
211
+ return undefined;
212
+ }
213
+ try {
214
+ return parseStructuredDataPath(expression.value);
215
+ } catch {
216
+ this.report(
217
+ 'TW2_STRUCTURED_INVALID_PATH',
218
+ 'Structured Data path literal is invalid.',
219
+ 'The path does not match $, .identifier, [index], or ["key"].',
220
+ 'Correct the literal path syntax.',
221
+ sourceRef
222
+ );
223
+ return undefined;
224
+ }
225
+ }
226
+
227
+ private literalMaximum(expression: ExpressionIrV2 | undefined, sourceRef: SourceRefV2): number | undefined {
228
+ const value = expression?.kind === 'literal' && expression.valueType === 'number' ? expression.value : undefined;
229
+ if (typeof value === 'number' && Number.isSafeInteger(value) && value >= 1 && value <= 1000) return value;
230
+ this.report(
231
+ 'TW2_STRUCTURED_INVALID_MAX',
232
+ 'Structured Data for-each maximum must be an integer literal from 1 to 1000.',
233
+ 'A static maximum is required to prove the route work bound.',
234
+ 'Use a numeric literal within the supported range.',
235
+ sourceRef
236
+ );
237
+ return undefined;
238
+ }
239
+
240
+ private missingArgument(name: string, sourceRef: SourceRefV2): undefined {
241
+ this.report(
242
+ 'TW2_STRUCTURED_TYPE_MISMATCH',
243
+ `Structured Data argument ${name} is missing.`,
244
+ 'The project block does not match its locked manifest signature.',
245
+ 'Recreate the block with the locked extension version.',
246
+ inputSource(sourceRef, name)
247
+ );
248
+ }
249
+
250
+ private unsupported(operation: string, sourceRef: SourceRefV2): undefined {
251
+ this.report(
252
+ 'TW2_UNSUPPORTED_OPERATION',
253
+ `Structured Data operation is not supported by this lowering phase: ${operation}`,
254
+ 'Only compiler-allowlisted operations from the locked manifest may be lowered.',
255
+ 'Use a supported manifest version and opcode.',
256
+ sourceRef
257
+ );
258
+ }
259
+
260
+ private report(
261
+ code: StructuredDataLoweringDiagnosticCode,
262
+ message: string,
263
+ reason: string,
264
+ suggestion: string,
265
+ sourceRef: SourceRefV2
266
+ ): void {
267
+ this.diagnostics.push({severity: 'error', code, message, reason, suggestion, sourceRef});
268
+ }
269
+ }
270
+
271
+ function requireArgument(args: StructuredDataArguments, name: string): ExpressionIrV2 | undefined {
272
+ return args[name];
273
+ }
274
+
275
+ function isLiteralText(expression: ExpressionIrV2 | undefined): expression is Extract<ExpressionIrV2, {kind: 'literal'}> & {
276
+ valueType: 'string' | 'json-text';
277
+ value: string;
278
+ } {
279
+ return (
280
+ expression?.kind === 'literal' &&
281
+ (expression.valueType === 'string' || expression.valueType === 'json-text') &&
282
+ typeof expression.value === 'string'
283
+ );
284
+ }
285
+
286
+ function jsonLiteralType(value: JsonValue): Exclude<AtomicValueTypeV2, 'binary-ref' | 'json-text'> {
287
+ if (value === null) return 'null';
288
+ if (Array.isArray(value)) return 'json-array';
289
+ if (typeof value === 'object') return 'json-object';
290
+ if (typeof value === 'boolean') return 'boolean';
291
+ if (typeof value === 'number') return 'number';
292
+ return 'string';
293
+ }
294
+
295
+ function literal(
296
+ valueType: Exclude<AtomicValueTypeV2, 'binary-ref'>,
297
+ value: JsonValue,
298
+ sourceRef: SourceRefV2
299
+ ): ExpressionIrV2 {
300
+ return {kind: 'literal', valueType, value, sourceRef} as ExpressionIrV2;
301
+ }
302
+
303
+ function jsonStringify(value: ExpressionIrV2, sourceRef: SourceRefV2): ExpressionIrV2 {
304
+ return {kind: 'json-stringify', valueType: 'json-text', value, sourceRef};
305
+ }
306
+
307
+ function inputSource(sourceRef: SourceRefV2, input: string): SourceRefV2 {
308
+ return {...sourceRef, input};
309
+ }
310
+
311
+ function sanitizeId(value: string): string {
312
+ const sanitized = value.replace(/[^A-Za-z0-9_]/g, '_');
313
+ return /^[A-Za-z_]/.test(sanitized) ? sanitized : `_${sanitized}`;
314
+ }
@@ -0,0 +1,53 @@
1
+ import type {PathSegmentV2} from '../ir-v2/types.js';
2
+
3
+ export function parseStructuredDataPath(input: string): PathSegmentV2[] {
4
+ if (!input.startsWith('$')) throw new Error('Path must start with $.');
5
+ const segments: PathSegmentV2[] = [];
6
+ let cursor = 1;
7
+ while (cursor < input.length) {
8
+ if (input[cursor] === '.') {
9
+ const match = /^[A-Za-z_][A-Za-z0-9_]*/u.exec(input.slice(cursor + 1));
10
+ if (match === null) throw new Error('Invalid identifier path segment.');
11
+ segments.push({kind: 'key', value: match[0]});
12
+ cursor += match[0].length + 1;
13
+ continue;
14
+ }
15
+ if (input[cursor] !== '[') throw new Error('Expected a bracket path segment.');
16
+ cursor += 1;
17
+ if (input[cursor] === '"') {
18
+ const end = scanJsonString(input, cursor);
19
+ let key: unknown;
20
+ try {
21
+ key = JSON.parse(input.slice(cursor, end));
22
+ } catch {
23
+ throw new Error('Invalid quoted path key.');
24
+ }
25
+ if (typeof key !== 'string' || input[end] !== ']') throw new Error('Invalid quoted path key.');
26
+ segments.push({kind: 'key', value: key});
27
+ cursor = end + 1;
28
+ continue;
29
+ }
30
+ const match = /^(0|[1-9][0-9]*)\]/u.exec(input.slice(cursor));
31
+ if (match === null) throw new Error('Invalid array index path segment.');
32
+ const index = Number(match[1]);
33
+ if (!Number.isSafeInteger(index)) throw new Error('Array index is not a safe integer.');
34
+ segments.push({kind: 'index', value: index});
35
+ cursor += match[0].length;
36
+ }
37
+ return segments;
38
+ }
39
+
40
+ function scanJsonString(path: string, start: number): number {
41
+ let escaped = false;
42
+ for (let index = start + 1; index < path.length; index += 1) {
43
+ const character = path[index];
44
+ if (escaped) {
45
+ escaped = false;
46
+ } else if (character === '\\') {
47
+ escaped = true;
48
+ } else if (character === '"') {
49
+ return index + 1;
50
+ }
51
+ }
52
+ throw new Error('Unterminated quoted path key.');
53
+ }
@@ -0,0 +1,221 @@
1
+ import type {JsonValue, PathSegmentV2} from '../ir-v2/types.js';
2
+ import {IrRuntimeError} from '../runtime/error.js';
3
+
4
+ export const STRUCTURED_DATA_HTTP_STATUS = 422;
5
+
6
+ export const STRUCTURED_DATA_RUNTIME_ERROR_CODES = [
7
+ 'INVALID_JSON',
8
+ 'INVALID_PATH',
9
+ 'PATH_NOT_FOUND',
10
+ 'TYPE_MISMATCH',
11
+ 'INDEX_OUT_OF_RANGE',
12
+ 'ITERATION_LIMIT_EXCEEDED',
13
+ 'ITERATION_CONTEXT_REQUIRED'
14
+ ] as const;
15
+
16
+ export type StructuredDataRuntimeErrorCode = (typeof STRUCTURED_DATA_RUNTIME_ERROR_CODES)[number];
17
+
18
+ export interface StructuredIterationEntry {
19
+ key: string;
20
+ index: number;
21
+ value: JsonValue;
22
+ }
23
+
24
+ export function parseApplicationJson(text: unknown): JsonValue {
25
+ try {
26
+ const value: unknown = JSON.parse(String(text));
27
+ assertJsonValue(value);
28
+ return value;
29
+ } catch (error) {
30
+ if (error instanceof IrRuntimeError) throw error;
31
+ runtimeError('INVALID_JSON', 'Input must be valid application JSON.');
32
+ }
33
+ }
34
+
35
+ export function isValidApplicationJson(text: unknown): boolean {
36
+ try {
37
+ parseApplicationJson(text);
38
+ return true;
39
+ } catch {
40
+ return false;
41
+ }
42
+ }
43
+
44
+ export function stringifyApplicationJson(value: JsonValue): string {
45
+ if (Array.isArray(value)) return `[${value.map(stringifyApplicationJson).join(',')}]`;
46
+ if (isJsonObject(value)) {
47
+ return `{${Object.keys(value)
48
+ .sort(compareUnicodeCodePoints)
49
+ .map((key) => `${JSON.stringify(key)}:${stringifyApplicationJson(value[key] as JsonValue)}`)
50
+ .join(',')}}`;
51
+ }
52
+ return JSON.stringify(value);
53
+ }
54
+
55
+ export function getJsonAtPath(root: JsonValue, path: readonly PathSegmentV2[]): JsonValue {
56
+ let current = root;
57
+ for (const segment of path) current = readSegment(current, segment);
58
+ return current;
59
+ }
60
+
61
+ export function hasJsonAtPath(root: JsonValue, path: readonly PathSegmentV2[]): boolean {
62
+ try {
63
+ getJsonAtPath(root, path);
64
+ return true;
65
+ } catch (error) {
66
+ if (
67
+ error instanceof IrRuntimeError &&
68
+ (error.code === 'PATH_NOT_FOUND' || error.code === 'INDEX_OUT_OF_RANGE')
69
+ ) {
70
+ return false;
71
+ }
72
+ throw error;
73
+ }
74
+ }
75
+
76
+ export function setJsonAtPath(
77
+ root: JsonValue,
78
+ path: readonly PathSegmentV2[],
79
+ replacement: JsonValue
80
+ ): JsonValue {
81
+ if (path.length === 0) return cloneJson(replacement);
82
+ return updateParent(root, path, (parent, segment) => {
83
+ if (segment.kind === 'key') {
84
+ if (!isJsonObject(parent)) runtimeError('TYPE_MISMATCH', 'Object path segment requires an object.');
85
+ return {...parent, [segment.value]: cloneJson(replacement)};
86
+ }
87
+ if (!Array.isArray(parent)) runtimeError('TYPE_MISMATCH', 'Index path segment requires an array.');
88
+ if (segment.value >= parent.length) runtimeError('INDEX_OUT_OF_RANGE', 'Array index is out of range.');
89
+ const result = parent.slice();
90
+ result[segment.value] = cloneJson(replacement);
91
+ return result;
92
+ });
93
+ }
94
+
95
+ export function deleteJsonAtPath(root: JsonValue, path: readonly PathSegmentV2[]): JsonValue {
96
+ if (path.length === 0) runtimeError('INVALID_PATH', 'The root value cannot be deleted.');
97
+ return updateParent(root, path, (parent, segment) => {
98
+ if (segment.kind === 'key') {
99
+ if (!isJsonObject(parent)) runtimeError('TYPE_MISMATCH', 'Object path segment requires an object.');
100
+ if (!hasOwn(parent, segment.value)) runtimeError('PATH_NOT_FOUND', 'Path does not exist.');
101
+ const result = {...parent};
102
+ delete result[segment.value];
103
+ return result;
104
+ }
105
+ if (!Array.isArray(parent)) runtimeError('TYPE_MISMATCH', 'Index path segment requires an array.');
106
+ if (segment.value >= parent.length) runtimeError('INDEX_OUT_OF_RANGE', 'Array index is out of range.');
107
+ const result = parent.slice();
108
+ result.splice(segment.value, 1);
109
+ return result;
110
+ });
111
+ }
112
+
113
+ export function jsonKeysAtPath(root: JsonValue, path: readonly PathSegmentV2[]): string[] {
114
+ const value = getJsonAtPath(root, path);
115
+ if (!isJsonObject(value)) runtimeError('TYPE_MISMATCH', 'Keys require an object.');
116
+ return Object.keys(value).sort(compareUnicodeCodePoints);
117
+ }
118
+
119
+ export function jsonLengthAtPath(root: JsonValue, path: readonly PathSegmentV2[]): number {
120
+ const value = getJsonAtPath(root, path);
121
+ if (!Array.isArray(value)) runtimeError('TYPE_MISMATCH', 'Length requires an array.');
122
+ return value.length;
123
+ }
124
+
125
+ export function structuredIterationEntries(
126
+ root: JsonValue,
127
+ path: readonly PathSegmentV2[],
128
+ maximum: number
129
+ ): StructuredIterationEntry[] {
130
+ if (!Number.isInteger(maximum) || maximum < 1 || maximum > 1000) {
131
+ runtimeError('ITERATION_LIMIT_EXCEEDED', 'Maximum must be from 1 to 1000.');
132
+ }
133
+ const value = getJsonAtPath(root, path);
134
+ const entries = Array.isArray(value)
135
+ ? value.map((item, index) => ({key: String(index), index, value: item}))
136
+ : isJsonObject(value)
137
+ ? Object.keys(value)
138
+ .sort(compareUnicodeCodePoints)
139
+ .map((key, index) => ({key, index, value: value[key] as JsonValue}))
140
+ : runtimeError('TYPE_MISMATCH', 'Iteration requires an array or object.');
141
+ if (entries.length > maximum) {
142
+ runtimeError('ITERATION_LIMIT_EXCEEDED', 'Collection exceeds the declared iteration maximum.');
143
+ }
144
+ return entries;
145
+ }
146
+
147
+ export function compareUnicodeCodePoints(left: string, right: string): number {
148
+ const leftPoints = Array.from(left, (character) => character.codePointAt(0) as number);
149
+ const rightPoints = Array.from(right, (character) => character.codePointAt(0) as number);
150
+ const length = Math.min(leftPoints.length, rightPoints.length);
151
+ for (let index = 0; index < length; index += 1) {
152
+ const difference = (leftPoints[index] as number) - (rightPoints[index] as number);
153
+ if (difference !== 0) return difference;
154
+ }
155
+ return leftPoints.length - rightPoints.length;
156
+ }
157
+
158
+ function updateParent(
159
+ root: JsonValue,
160
+ path: readonly PathSegmentV2[],
161
+ update: (parent: JsonValue, segment: PathSegmentV2) => JsonValue
162
+ ): JsonValue {
163
+ const [segment, ...remaining] = path;
164
+ if (segment === undefined) return root;
165
+ if (remaining.length === 0) return update(root, segment);
166
+ const child = readSegment(root, segment);
167
+ const next = updateParent(child, remaining, update);
168
+ if (segment.kind === 'key') {
169
+ if (!isJsonObject(root)) runtimeError('TYPE_MISMATCH', 'Object path segment requires an object.');
170
+ return {...root, [segment.value]: next};
171
+ }
172
+ if (!Array.isArray(root)) runtimeError('TYPE_MISMATCH', 'Index path segment requires an array.');
173
+ const result = root.slice();
174
+ result[segment.value] = next;
175
+ return result;
176
+ }
177
+
178
+ function readSegment(value: JsonValue, segment: PathSegmentV2): JsonValue {
179
+ if (segment.kind === 'key') {
180
+ if (!isJsonObject(value)) runtimeError('TYPE_MISMATCH', 'Object path segment requires an object.');
181
+ if (!hasOwn(value, segment.value)) runtimeError('PATH_NOT_FOUND', 'Path does not exist.');
182
+ return value[segment.value] as JsonValue;
183
+ }
184
+ if (!Array.isArray(value)) runtimeError('TYPE_MISMATCH', 'Index path segment requires an array.');
185
+ if (segment.value >= value.length) runtimeError('INDEX_OUT_OF_RANGE', 'Array index is out of range.');
186
+ return value[segment.value] as JsonValue;
187
+ }
188
+
189
+ function cloneJson(value: JsonValue): JsonValue {
190
+ if (Array.isArray(value)) return value.map(cloneJson);
191
+ if (isJsonObject(value)) {
192
+ return Object.fromEntries(Object.keys(value).map((key) => [key, cloneJson(value[key] as JsonValue)]));
193
+ }
194
+ return value;
195
+ }
196
+
197
+ function assertJsonValue(value: unknown): asserts value is JsonValue {
198
+ if (value === null || typeof value === 'string' || typeof value === 'boolean') return;
199
+ if (typeof value === 'number' && Number.isFinite(value)) return;
200
+ if (Array.isArray(value)) {
201
+ for (const item of value) assertJsonValue(item);
202
+ return;
203
+ }
204
+ if (typeof value === 'object') {
205
+ for (const item of Object.values(value)) assertJsonValue(item);
206
+ return;
207
+ }
208
+ runtimeError('INVALID_JSON', 'JSON contains an unsupported value.');
209
+ }
210
+
211
+ function isJsonObject(value: JsonValue): value is {[key: string]: JsonValue} {
212
+ return typeof value === 'object' && value !== null && !Array.isArray(value);
213
+ }
214
+
215
+ function hasOwn(value: object, key: PropertyKey): boolean {
216
+ return Object.prototype.hasOwnProperty.call(value, key);
217
+ }
218
+
219
+ function runtimeError(code: StructuredDataRuntimeErrorCode, message: string): never {
220
+ throw new IrRuntimeError(code, message, STRUCTURED_DATA_HTTP_STATUS);
221
+ }