@arcforge/platform 2.0.219 → 2.0.244

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 (127) hide show
  1. package/package.json +27 -19
  2. package/src/build/blueprint/blueprint.ts +48 -64
  3. package/src/build/blueprint/cognet/abi.ts +3 -257
  4. package/src/build/blueprint/cognet/bundle-worker.ts +11 -0
  5. package/src/build/blueprint/cognet/bundle.ts +294 -89
  6. package/src/build/blueprint/cognet/cognet.ts +8 -7
  7. package/src/build/blueprint/cognet/config/config.ts +52 -0
  8. package/src/build/blueprint/cognet/config/index.ts +4 -0
  9. package/src/build/blueprint/cognet/config/literal.ts +83 -0
  10. package/src/build/blueprint/cognet/config/provider.ts +43 -0
  11. package/src/build/blueprint/cognet/config/shape.ts +183 -0
  12. package/src/build/blueprint/cognet/index.ts +4 -2
  13. package/src/build/blueprint/cognet/native/cargo.ts +31 -0
  14. package/src/build/blueprint/cognet/native/crate.ts +126 -0
  15. package/src/build/blueprint/cognet/native/index.ts +2 -0
  16. package/src/build/blueprint/cognet/native/library.ts +125 -0
  17. package/src/build/blueprint/cognet/native/manifest.ts +137 -0
  18. package/src/build/blueprint/cognet/python/index.ts +1 -0
  19. package/src/build/blueprint/cognet/python/project.ts +119 -0
  20. package/src/build/blueprint/cognet/schema/arrays.ts +23 -0
  21. package/src/build/blueprint/cognet/schema/authored.ts +273 -0
  22. package/src/build/blueprint/cognet/schema/compile.ts +78 -0
  23. package/src/build/blueprint/cognet/schema/components/external.ts +15 -0
  24. package/src/build/blueprint/cognet/schema/components/index.ts +3 -0
  25. package/src/build/blueprint/cognet/schema/components/lock.ts +58 -0
  26. package/src/build/blueprint/cognet/schema/components/model.ts +34 -0
  27. package/src/build/blueprint/cognet/schema/components/python.ts +15 -0
  28. package/src/build/blueprint/cognet/schema/components/python_source.py +69 -0
  29. package/src/build/blueprint/cognet/schema/components/rust.ts +33 -0
  30. package/src/build/blueprint/cognet/schema/components/rust_source/Cargo.lock +117 -0
  31. package/src/build/blueprint/cognet/schema/components/rust_source/Cargo.toml +11 -0
  32. package/src/build/blueprint/cognet/schema/components/rust_source/src/main.rs +104 -0
  33. package/src/build/blueprint/cognet/schema/components/source.ts +220 -0
  34. package/src/build/blueprint/cognet/schema/components/tags.ts +66 -0
  35. package/src/build/blueprint/cognet/schema/components/typescript.ts +157 -0
  36. package/src/build/blueprint/cognet/schema/index.ts +5 -0
  37. package/src/build/blueprint/cognet/schema/interfaces/index.ts +3 -0
  38. package/src/build/blueprint/cognet/schema/interfaces/source.ts +218 -0
  39. package/src/build/blueprint/cognet/schema/python.ts +260 -0
  40. package/src/build/blueprint/cognet/schema/rust.ts +316 -0
  41. package/src/build/blueprint/cognet/schema/schema.ts +248 -0
  42. package/src/build/blueprint/cognet/schema/typescript.ts +352 -0
  43. package/src/build/blueprint/index.ts +1 -1
  44. package/src/build/blueprint/modules/index.ts +7 -5
  45. package/src/build/blueprint/modules/meta.ts +47 -3
  46. package/src/build/blueprint/scan/config.ts +22 -16
  47. package/src/build/blueprint/scan/provider-globals.ts +46 -0
  48. package/src/build/blueprint/scan/providers.ts +25 -0
  49. package/src/build/blueprint/scan/tools.ts +21 -15
  50. package/src/build/extensions/edit.ts +66 -2
  51. package/src/build/extensions/extensions.ts +16 -3
  52. package/src/build/extensions/index.ts +1 -1
  53. package/src/build/project/bundle/agent.ts +26 -17
  54. package/src/build/project/bundle/source.ts +2 -2
  55. package/src/build/project/create/cognet.ts +84 -33
  56. package/src/build/project/create/profile.ts +13 -3
  57. package/src/build/project/index.ts +1 -1
  58. package/src/build/project/installer.ts +6 -5
  59. package/src/build/project/kinds.ts +4 -0
  60. package/src/build/project/manifest/env.ts +10 -0
  61. package/src/build/project/models/blobs/blobs.ts +57 -0
  62. package/src/build/project/models/blobs/index.ts +1 -0
  63. package/src/build/project/models/fetch.ts +46 -51
  64. package/src/build/project/models/index.ts +2 -1
  65. package/src/build/project/models/models.ts +12 -38
  66. package/src/build/project/models/onnx.ts +82 -0
  67. package/src/build/project/models/specifier.ts +9 -3
  68. package/src/build/project/models/storage/index-store.ts +27 -0
  69. package/src/build/project/models/storage/index.ts +1 -0
  70. package/src/build/project/models/store.ts +21 -16
  71. package/src/build/project/prepare.ts +82 -27
  72. package/src/build/project/project.ts +8 -14
  73. package/src/build/project/projects.ts +12 -1
  74. package/src/build/project/tree.ts +13 -3
  75. package/src/build/project/treecache.ts +8 -4
  76. package/src/build/project/typegen/axon-dts.ts +18 -0
  77. package/src/build/project/typegen/cognet-dts.ts +248 -59
  78. package/src/build/project/typegen/prompt-dts.ts +2 -3
  79. package/src/build/project/typegen/registry-dts.ts +2 -2
  80. package/src/build/project/typegen/tsconfig.ts +13 -13
  81. package/src/build/project/typegen/tui-dts.ts +3 -4
  82. package/src/build/project/typegen/workspace-scripts.ts +8 -7
  83. package/src/build/project/typegen/write.ts +15 -2
  84. package/src/build/project/watcher.ts +27 -0
  85. package/src/build/runtime/agent.ts +102 -63
  86. package/src/build/runtime/conformance.ts +25 -0
  87. package/src/build/runtime/escalations.ts +3 -8
  88. package/src/build/runtime/index.ts +2 -0
  89. package/src/build/runtime/instances.ts +7 -4
  90. package/src/build/runtime/progress.ts +6 -2
  91. package/src/build/runtime/reload-watch.ts +11 -8
  92. package/src/debug/README.md +398 -0
  93. package/src/debug/debug.ts +101 -0
  94. package/src/debug/events.ts +156 -0
  95. package/src/debug/graph.ts +94 -0
  96. package/src/debug/index.ts +5 -0
  97. package/src/debug/indexer.ts +286 -0
  98. package/src/debug/inference.ts +53 -0
  99. package/src/debug/log.ts +68 -0
  100. package/src/debug/overview.ts +78 -0
  101. package/src/debug/perf.ts +75 -0
  102. package/src/debug/resources.ts +125 -0
  103. package/src/debug/ring.ts +31 -0
  104. package/src/debug/sessions.ts +90 -0
  105. package/src/debug/signs.ts +119 -0
  106. package/src/debug/tally.ts +44 -0
  107. package/src/debug/types.ts +146 -0
  108. package/src/index.ts +9 -0
  109. package/src/link/agent-main.ts +36 -10
  110. package/src/link/index.ts +1 -1
  111. package/src/link/services.ts +88 -57
  112. package/src/platform.ts +17 -25
  113. package/src/services/cloud.ts +1 -4
  114. package/src/services/control/client.ts +1 -1
  115. package/src/services/control/server.ts +1 -1
  116. package/src/services/index.ts +1 -0
  117. package/src/services/ollama/daemon.ts +23 -0
  118. package/src/services/ollama/http.ts +7 -1
  119. package/src/services/ollama/ollama.ts +8 -14
  120. package/src/services/probe/ask.ts +139 -0
  121. package/src/services/probe/index.ts +3 -0
  122. package/src/services/providers.ts +18 -0
  123. package/src/services/resources/hardware.ts +15 -18
  124. package/src/services/resources/resources.ts +4 -5
  125. package/src/services/store/types.ts +3 -0
  126. package/src/services/running/index.ts +0 -1
  127. package/src/services/running/running.ts +0 -216
@@ -0,0 +1,220 @@
1
+ import { readFileSync } from "node:fs"
2
+ import { dirname } from "node:path"
3
+ import type { Source } from "../compile"
4
+ import { external, type External } from "./external"
5
+ import { fail, type Field, type File, type Shape } from "./model"
6
+ import { Lock } from "./lock"
7
+ import { typescript } from "./typescript"
8
+ import { PythonSource } from "./python"
9
+ import { RustSource } from "./rust"
10
+ import { said, type Said } from "./tags"
11
+
12
+ /** Native component sources compiled to the same protobuf image as the legacy schemas. */
13
+ export function Components(opts: { root: string; files: readonly { absPath: string; relPath: string }[]; legacy: readonly Source[] }) {
14
+ // Beside the source and committed, as Cargo.lock is: a field's number is its identity in every recorded session.
15
+ const lock = Lock({ path: `${opts.root}/components.lock.json` })
16
+ const python = PythonSource({})
17
+ const rust = RustSource({})
18
+ return {
19
+ /** The proto for every component file, and the files as read — which interfaces resolve their value types against. */
20
+ sources(): { sources: Source[]; files: File[] } {
21
+ const files = opts.files.flatMap(file => {
22
+ const ext = file.relPath.match(/\.components\.(ts|rs|py)$/)?.[1]
23
+ if (!ext) fail(file.absPath, "expected a *.components.ts, *.components.rs or *.components.py file")
24
+ const named = file.relPath.replace(/^(types|src)\//, "").replace(/\.components\.(ts|rs|py)$/, `.$1-components.proto`)
25
+ const packageName = `cognet_source.${named.slice(0, -6).split("/").map(segment => segment.replace(/[^A-Za-z0-9_]/g, "_").replace(/^(?=\d)/, "_")).join(".")}`
26
+ const parsed = ext === "ts" ? typescript(file.absPath, readFileSync(file.absPath, "utf8")) : { shapes: ext === "py" ? python.read(file.absPath) : rust.read(file.absPath), imports: {} }
27
+ // Declares nothing yet: a file being started, not a mistake. Declaring types and exporting none is.
28
+ if (parsed.shapes.length === 0) return []
29
+ const told = new Map(parsed.shapes.map(shape => [shape.name, said(file.absPath, shape)]))
30
+ // A frame is an export that says `@space`: it holds no value, so it is no component and no message.
31
+ const shapes = parsed.shapes.map(shape => ({ ...shape, doc: told.get(shape.name)!.doc, component: shape.component && !told.get(shape.name)!.space }))
32
+ for (const shape of shapes.filter(shape => told.get(shape.name)!.space)) {
33
+ if (!parsed.shapes.find(one => one.name === shape.name)!.component) fail(file.absPath, `${shape.name}: a frame is exported`)
34
+ if (shape.fields.length || shape.alias) fail(file.absPath, `${shape.name}: a frame holds no fields — it is a space, not a value`)
35
+ }
36
+ if (!shapes.some(shape => shape.component || told.get(shape.name)!.space)) fail(file.absPath, "a component file must export at least one component or frame")
37
+ return [{ ...file, named: named, package: packageName, shapes: shapes, imports: parsed.imports, said: told }]
38
+ })
39
+ const names = new Map<string, { file: File; shape: Shape }>()
40
+ for (const file of files) for (const shape of file.shapes.filter(shape => shape.component)) {
41
+ if (shape.name === "Components" || shape.name === "Frames") fail(file.absPath, `${shape.name} is reserved for a generated container`)
42
+ if (!/^[A-Z][A-Za-z0-9]*$/.test(shape.name)) fail(file.absPath, `${shape.name}: component type names must be PascalCase`)
43
+ const name = fullName(file.named, componentName(shape.name))
44
+ const existing = names.get(name)
45
+ if (existing) fail(file.absPath, `component ${shape.name} overlaps ${existing.shape.name} in ${existing.file.relPath}; every component has one owning definition`)
46
+ names.set(name, { file: file, shape: shape })
47
+ }
48
+ const shapes = new Map<string, Array<{ file: File; shape: Shape }>>()
49
+ for (const file of files) for (const shape of file.shapes) {
50
+ const owners = shapes.get(shape.name) ?? []
51
+ owners.push({ file: file, shape: shape })
52
+ shapes.set(shape.name, owners)
53
+ }
54
+ const existing = files.length ? external(opts.legacy) : []
55
+ const resolve = (file: File, name: string): string => {
56
+ const local = file.shapes.find(shape => shape.name === name)
57
+ if (local) return local.name
58
+ const imported = file.imports[name]
59
+ if (imported) {
60
+ const nativeFile = files.find(one => one.absPath === imported.path)
61
+ const native = nativeFile?.shapes.find(shape => shape.name === imported.name)
62
+ if (nativeFile && native) return `.${nativeFile.package}.${native.name}`
63
+ const legacy = existing.find(one => one.absPath === imported.path && one.name === imported.name)
64
+ if (legacy) return `.${legacy.package}.${legacy.name}`
65
+ fail(file.absPath, `${name}: import ${imported.path} does not name a known schema type`)
66
+ }
67
+ const owners = shapes.get(name) ?? []
68
+ const legacy = existing.filter(one => one.name === name)
69
+ if (owners.length + legacy.length !== 1) fail(file.absPath, `${name} refers to ${owners.length + legacy.length === 0 ? "no component or known value type" : "more than one type"}; use a unique name`)
70
+ return owners.length ? `.${owners[0]!.file.package}.${name}` : `.${legacy[0]!.package}.${name}`
71
+ }
72
+ const sources = files.map(file => ({ absPath: file.absPath, named: file.named, content: emit(file, files, existing, lock, resolve) }))
73
+ const active = files.flatMap(file => [...file.shapes.map(shape => owner(file, shape)), `${file.named}/Components`, `${file.named}/Frames`])
74
+ lock.finishAll(active)
75
+ return { sources: sources, files: files }
76
+ },
77
+ save(): void { lock.save() },
78
+ }
79
+ }
80
+
81
+ /** A component file as read: its shapes, and what each one's doc said. */
82
+ type Read = File & { said: Map<string, Said> }
83
+
84
+ function emit(file: Read, files: File[], existing: External[], lock: ReturnType<typeof Lock>, resolve: (file: File, name: string) => string): string {
85
+ const imports = new Set<string>()
86
+ const blocks: string[] = []
87
+ /** Each container field's comment and options — what the component or frame is, beyond its type. */
88
+ type Member = { doc?: string; options: string[] }
89
+ const emitMessage = (shape: Shape, container: "components" | "frames" | null, members: Map<string, Member> = new Map()): void => {
90
+ const identity = owner(file, shape)
91
+ const fields = shape.fields.map(field => {
92
+ const fieldName = protoName(field.name)
93
+ const type = container === "frames" ? { proto: "cognet.Frame", repeated: false, options: [] } : fieldType(field.type, file, resolve)
94
+ const member = members.get(field.name)
95
+ if (field.nullable && type.repeated) fail(file.absPath, `${shape.name}.${field.name}: nullable lists and maps are not supported`)
96
+ if (type.reference?.startsWith(".")) {
97
+ const foreign = files.find(one => type.reference!.startsWith(`.${one.package}.`)) ?? existing.find(one => type.reference === `.${one.package}.${one.name}`)
98
+ if (!foreign) fail(file.absPath, `${shape.name}.${field.name}: ${type.reference} has no source`)
99
+ if (foreign !== file) imports.add(foreign.named)
100
+ }
101
+ const signature = `${type.proto}|${field.optional}|${!!field.nullable}|${type.options.join(",")}`
102
+ const number = lock.field(identity, fieldName, signature)
103
+ const options = [...type.options, ...member?.options ?? []]
104
+ if (field.optional && type.repeated) options.push("(cognet.optional) = true")
105
+ if (field.nullable) options.push("(cognet.nullable) = true")
106
+ const option = options.length ? ` [${options.join(", ")}]` : ""
107
+ const comment = member?.doc ? member.doc.split("\n").map(line => ` // ${line}`) : []
108
+ return [...comment, ` ${field.optional && !type.repeated ? "optional " : ""}${type.proto} ${fieldName} = ${number}${option};`].join("\n")
109
+ })
110
+ const removed = lock.finish(identity, shape.fields.map(field => protoName(field.name)))
111
+ const reserved = removed.length ? [` reserved ${removed.join(", ")};`] : []
112
+ blocks.push(...(shape.doc ? shape.doc.split("\n").map(line => `// ${line}`) : []), `message ${shape.name} {`, ...(container ? [` option (cognet.${container}) = true;`] : []), ...reserved, ...fields, "}", "")
113
+ }
114
+ const spaces = new Map([...file.said].filter(([, told]) => told.space).map(([name, told]) => [name, told.space!]))
115
+ for (const shape of file.shapes) if (!shape.alias && !spaces.has(shape.name)) emitMessage(shape, null)
116
+ const components = file.shapes.filter(shape => shape.component)
117
+ for (const shape of components.filter(shape => shape.alias)) {
118
+ const type = fieldType(shape.alias!, file, resolve)
119
+ lock.field(owner(file, shape), "value", `${type.proto}|${type.options.join(",")}`)
120
+ lock.finish(owner(file, shape), ["value"])
121
+ }
122
+ const componentFields = components.map(shape => ({ name: componentName(shape.name), type: shape.alias ?? shape.name, optional: false }))
123
+ // Frames first: the components after them are drawn in them.
124
+ if (spaces.size) {
125
+ const frames = file.shapes.filter(shape => spaces.has(shape.name))
126
+ const frameMembers = new Map(frames.map(shape => [componentName(shape.name), { doc: shape.doc, options: [`(cognet.frame) = { kind: ${kind(file, shape.name, spaces.get(shape.name)!)} }`] }]))
127
+ emitMessage({ name: "Frames", fields: frames.map(shape => ({ name: componentName(shape.name), type: "Frame", optional: false })), component: false }, "frames", frameMembers)
128
+ }
129
+ const componentMembers = new Map(components.map(shape => [componentName(shape.name), { doc: shape.doc, options: display(file, shape, spaces) }]))
130
+ emitMessage({ name: "Components", fields: componentFields, component: false }, "components", componentMembers)
131
+ const head = [
132
+ `// Generated by axon prepare from ${file.relPath}.`,
133
+ 'syntax = "proto3";',
134
+ `package ${file.package};`,
135
+ 'import "cognet/cognet.proto";',
136
+ ...[...imports].sort().map(name => `import ${JSON.stringify(name)};`),
137
+ "",
138
+ ]
139
+ return [...head, ...blocks].join("\n")
140
+ }
141
+
142
+ /**
143
+ * A component's display option: what its doc wrote, and what the type implies
144
+ * for the rest — a number is a scalar, a word categorical, a list a vector,
145
+ * anything with fields a record; indexed by its frame's space, or by nothing
146
+ * when it has no frame.
147
+ */
148
+ function display(file: Read, shape: Shape, spaces: Map<string, string>): string[] {
149
+ const told = file.said.get(shape.name)!
150
+ const written = told.display
151
+ const frame = told.frame
152
+ const local = frame ? [...spaces].find(([name]) => componentName(name) === frame)?.[1] : undefined
153
+ const domain = !frame ? "POINT" : local === "sequence" ? "SEQUENCE" : local === "tree" ? "TREE" : local === "graph" ? "SET" : "SPACE"
154
+ const type = shape.alias?.trim()
155
+ const form = !type ? "RECORD" : ["number", "f64", "f32", "u32", "i32"].includes(type) ? "SCALAR" : ["string", "boolean"].includes(type) ? "CATEGORICAL" : /^(Fixed<|Vec<|Array<|Float|Int|Uint)/.test(type) ? "VECTOR" : "RECORD"
156
+ const options = { domain: `DOMAIN_${domain}`, shape: `SHAPE_${form}`, ...written }
157
+ return [`(cognet.component) = { display: { ${Object.entries(options).map(([key, value]) => `${key}: ${value}`).join(", ")} } }`]
158
+ }
159
+
160
+ /** A frame's space kind, as protobuf names it. */
161
+ function kind(file: Read, name: string, space: string): string {
162
+ const known = ["metric2d", "metric3d", "graph", "tree", "sequence"]
163
+ if (!known.includes(space)) fail(file.absPath, `${name}: @space is one of ${known.join(", ")}, not ${space}`)
164
+ return `KIND_${space.toUpperCase()}`
165
+ }
166
+
167
+ export function protoName(name: string): string { return name.replace(/([A-Z]+)([A-Z][a-z])/g, "$1_$2").replace(/([a-z0-9])([A-Z])/g, "$1_$2").toLowerCase() }
168
+ function componentName(name: string): string { return protoName(name).replace(/_([a-z])/g, (_, letter: string) => letter.toUpperCase()) }
169
+ function fullName(named: string, name: string): string { const folder = dirname(named); return folder === "." ? name : `${folder}/${name}` }
170
+ function owner(file: File, shape: Shape): string { return shape.component ? `component/${fullName(file.named, componentName(shape.name))}` : `${file.named}/${shape.name}` }
171
+
172
+ export function fieldType(raw: string, file: File, resolve: (file: File, name: string) => string): { proto: string; reference?: string; repeated: boolean; options: string[] } {
173
+ const type = raw.trim()
174
+ const scalar: Record<string, string> = { number: "double", f64: "double", f32: "float", u32: "uint32", i32: "int32", string: "string", boolean: "bool", bytes: "bytes" }
175
+ if (scalar[type]) return { proto: scalar[type], repeated: false, options: [] }
176
+ const arrays: Record<string, string> = { Float32Array: "float", Float64Array: "double", Int32Array: "int32", Uint32Array: "uint32", Uint8Array: "bytes" }
177
+ if (arrays[type]) return { proto: `${type === "Uint8Array" ? "" : "repeated "}${arrays[type]}`, repeated: type !== "Uint8Array", options: type === "Uint8Array" ? [] : ["(cognet.array) = true"] }
178
+ if (type === "Vec<u8>") return { proto: "bytes", repeated: false, options: [] }
179
+ const fixed = type.match(/^Fixed<(.+),(\d+)>$/)
180
+ if (fixed) {
181
+ const length = Number(fixed[2])
182
+ if (!Number.isSafeInteger(length) || length < 1 || length > 1024) fail(file.absPath, `${type}: fixed tuple length must be 1..1024`)
183
+ const inner = fieldType(fixed[1]!, file, resolve)
184
+ if (inner.repeated || inner.proto.startsWith("map<")) fail(file.absPath, `${type}: fixed tuple elements cannot be collections`)
185
+ return { proto: `repeated ${inner.proto}`, reference: inner.reference, repeated: true, options: [...inner.options, `(cognet.fixed) = ${length}`] }
186
+ }
187
+ const list = type.match(/^(?:Vec|Array|list)<(.+)>$/) ?? type.match(/^(.+)\[\]$/)
188
+ if (list) {
189
+ const inner = fieldType(list[1]!, file, resolve)
190
+ if (inner.repeated || inner.proto.startsWith("map<")) fail(file.absPath, `${type}: nested collections are not supported`)
191
+ return { proto: `repeated ${inner.proto}`, reference: inner.reference, repeated: true, options: inner.options }
192
+ }
193
+ const map = type.match(/^(?:Record|BTreeMap|HashMap|dict)<(.+)>$/)
194
+ if (map) {
195
+ const parts = split(map[1]!)
196
+ if (parts.length !== 2) fail(file.absPath, `${type}: expected a map key and value`)
197
+ const inner = fieldType(parts[1]!, file, resolve)
198
+ if (inner.repeated || inner.proto.startsWith("map<")) fail(file.absPath, `${type}: map values cannot be collections`)
199
+ const key = parts[0]!
200
+ const scalarKey = key === "string" ? "string" : key === "u32" ? "uint32" : key === "i32" ? "int32" : null
201
+ const namedKey = scalarKey ? null : resolve(file, key)
202
+ return { proto: `map<${scalarKey ?? "string"}, ${inner.proto}>`, reference: inner.reference, repeated: true, options: namedKey ? [`(cognet.keys) = ${JSON.stringify(namedKey.replace(/^\./, ""))}`] : [] }
203
+ }
204
+ if (!/^[A-Za-z_]\w*$/.test(type)) fail(file.absPath, `unsupported component field type ${type}`)
205
+ const reference = resolve(file, type)
206
+ return { proto: reference, reference: reference, repeated: false, options: [] }
207
+ }
208
+
209
+ function split(input: string): string[] {
210
+ let depth = 0
211
+ const parts: string[] = []
212
+ let start = 0
213
+ for (let index = 0; index < input.length; index++) {
214
+ if (input[index] === "<") depth++
215
+ if (input[index] === ">") depth--
216
+ if (input[index] === "," && depth === 0) { parts.push(input.slice(start, index).trim()); start = index + 1 }
217
+ }
218
+ parts.push(input.slice(start).trim())
219
+ return parts
220
+ }
@@ -0,0 +1,66 @@
1
+ import { fail, type Shape } from "./model"
2
+
3
+ /** What a declaration's doc says beyond prose: how it is drawn, or — for a frame — what space it is. */
4
+ export type Said = {
5
+ /** The prose, tags removed. */
6
+ doc?: string
7
+ /** `@space <kind>` — the declaration is a frame, not a component. */
8
+ space?: string
9
+ /** `@frame <name>` — the frame its value lives in, as written. */
10
+ frame?: string
11
+ /** Display options written, before what the type implies is added. */
12
+ display: Record<string, string>
13
+ }
14
+
15
+ /**
16
+ * Tags — the words in a doc comment that say what a declaration is, read the
17
+ * same from TypeScript's `/** *\/`, Rust's `///` and a Python docstring, so a
18
+ * component is described once, in whichever language holds it.
19
+ *
20
+ * @frame session the frame its value lives in
21
+ * @archetype span how a viewer draws it there
22
+ * @range 0 1 its expected low and high
23
+ * @unit m its physical unit
24
+ * @instrument power its physical meaning, for a cockpit
25
+ * @domain / @shape what it is indexed by and its form — written only to overrule the type
26
+ * @workspace attention may draw from it
27
+ * @space sequence this export is a frame (it holds no fields)
28
+ *
29
+ * An unknown tag fails: a typo must not quietly draw nothing.
30
+ */
31
+ export function said(path: string, shape: Pick<Shape, "name" | "doc">): Said {
32
+ const display: Record<string, string> = {}
33
+ let space: string | undefined
34
+ let frame: string | undefined
35
+ // A tag takes one word — two numbers for @range — so prose may follow it on the line.
36
+ const prose = (shape.doc ?? "").replace(/(^|\s)@([a-z]+)(?:[ \t]+(-?[\d.]+[ \t]+-?[\d.]+|[^\s@]+))?/g, (_, lead: string, tag: string, word: string | undefined) => {
37
+ const value = word ?? ""
38
+ if (tag === "space") space = need(value, tag)
39
+ else if (tag === "workspace") {
40
+ display.workspace = "true"
41
+ return `${lead}${value}`
42
+ }
43
+ else if (tag === "range") {
44
+ const bounds = value.split(/\s+/).map(Number)
45
+ if (bounds.length !== 2 || bounds.some(bound => !Number.isFinite(bound))) fail(path, `${shape.name}: @range takes a low and a high — @range 0 1`)
46
+ display.range = `[${bounds.join(", ")}]`
47
+ }
48
+ else if (tag === "frame") {
49
+ frame = need(value, tag)
50
+ display.frame = JSON.stringify(frame)
51
+ }
52
+ else if (tag === "unit") display.unit = JSON.stringify(need(value, tag))
53
+ else if (tag in ENUMS) display[tag] = `${ENUMS[tag]}_${need(value, tag).replace(/-/g, "_").toUpperCase()}`
54
+ else fail(path, `${shape.name}: unknown tag @${tag} — a component says @frame, @archetype, @range, @unit, @instrument, @domain, @shape or @workspace; a frame says @space`)
55
+ return lead
56
+ }).replace(/[ \t]+$/gm, "").trim()
57
+ return { doc: prose || undefined, space: space, frame: frame, display: display }
58
+
59
+ function need(value: string, tag: string): string {
60
+ if (!value || /\s/.test(value)) fail(path, `${shape.name}: @${tag} takes one word`)
61
+ return value
62
+ }
63
+ }
64
+
65
+ /** Tags whose word is a protobuf enum value: `@archetype span` → `ARCHETYPE_SPAN`. */
66
+ const ENUMS: Record<string, string> = { archetype: "ARCHETYPE", instrument: "INSTRUMENT", domain: "DOMAIN", shape: "SHAPE" }
@@ -0,0 +1,157 @@
1
+ import { dirname, resolve } from "node:path"
2
+ import ts from "typescript"
3
+ import { fail, type Answer, type Contract, type Field, type Import, type Method, type Shape } from "./model"
4
+
5
+ /** How an interface file differs from a component file: it holds a contract, and handles, and imports the standard interfaces by package. */
6
+ type InterfaceOpts = { contract: true; resolve(specifier: string): string | null }
7
+
8
+ /**
9
+ * Read native TypeScript declarations; exports select components, not wrappers.
10
+ * With `contract`, the file is an interface: its one exported interface with
11
+ * methods is the contract, and `Handle<"Name">` aliases are handles.
12
+ */
13
+ export function typescript(path: string, text: string, opts?: InterfaceOpts): { shapes: Shape[]; imports: Record<string, Import>; contracts: Contract[] } {
14
+ const diagnostic = ts.transpileModule(text, { fileName: path, reportDiagnostics: true }).diagnostics?.find(one => one.category === ts.DiagnosticCategory.Error)
15
+ if (diagnostic) fail(path, ts.flattenDiagnosticMessageText(diagnostic.messageText, "\n"))
16
+ const ast = ts.createSourceFile(path, text, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS)
17
+ const shapes: Shape[] = []
18
+ const contracts: Contract[] = []
19
+ const imports: Record<string, Import> = {}
20
+ for (const node of ast.statements) {
21
+ if (ts.isImportDeclaration(node)) {
22
+ if (!node.importClause?.isTypeOnly) fail(path, "component sources may only import types")
23
+ if (!ts.isStringLiteral(node.moduleSpecifier)) fail(path, "component type imports need a string path")
24
+ const packaged = node.moduleSpecifier.text.startsWith(".") ? null : opts?.resolve(node.moduleSpecifier.text) ?? null
25
+ if (node.moduleSpecifier.text.startsWith(".") || packaged) {
26
+ const target = packaged ?? resolve(dirname(path), withTs(node.moduleSpecifier.text))
27
+ const bindings = node.importClause.namedBindings
28
+ if (!bindings || !ts.isNamedImports(bindings)) fail(path, "component type imports must name their types")
29
+ for (const binding of bindings.elements) imports[binding.name.text] = { path: target, name: binding.propertyName?.text ?? binding.name.text }
30
+ }
31
+ continue
32
+ }
33
+ if (!ts.isInterfaceDeclaration(node) && !ts.isTypeAliasDeclaration(node)) fail(path, `unsupported statement ${ts.SyntaxKind[node.kind]}; use interfaces and type aliases`)
34
+ if (opts && ts.isInterfaceDeclaration(node) && node.members.some(ts.isMethodSignature)) {
35
+ contracts.push(contract(node))
36
+ continue
37
+ }
38
+ if (opts && ts.isTypeAliasDeclaration(node) && handle(node.type)) {
39
+ if (handle(node.type) !== node.name.text) fail(path, `${node.name.text}: a handle is named as its type — Handle<"${node.name.text}">`)
40
+ shapes.push({ name: node.name.text, fields: [], component: false, handle: true, doc: docOf(node) })
41
+ continue
42
+ }
43
+ const component = node.modifiers?.some(modifier => modifier.kind === ts.SyntaxKind.ExportKeyword) ?? false
44
+ if (node.modifiers?.some(modifier => modifier.kind === ts.SyntaxKind.DefaultKeyword)) fail(path, "components need named exports")
45
+ if (ts.isInterfaceDeclaration(node) && node.heritageClauses?.length) fail(path, `${node.name.text}: interface extension is not a wire shape`)
46
+ const doc = docOf(node)
47
+ const literal = ts.isInterfaceDeclaration(node) ? node.members : ts.isTypeLiteralNode(node.type) ? node.type.members : null
48
+ const alias = literal ? undefined : ts.isTypeAliasDeclaration(node) ? type(node.type) : undefined
49
+ if (!literal && !alias) fail(path, `${node.name.text}: expected an object type or supported alias`)
50
+ const fields: Field[] = []
51
+ for (const member of literal ?? []) {
52
+ if (!ts.isPropertySignature(member) || !member.type || !member.name || !(ts.isIdentifier(member.name) || ts.isStringLiteral(member.name))) fail(path, `${node.name.text}: only named, typed fields are supported`)
53
+ const nullable = nullableType(member.type)
54
+ const value = type(nullable ?? member.type)
55
+ fields.push({ name: member.name.text, type: value, optional: !!member.questionToken, nullable: !!nullable })
56
+ }
57
+ shapes.push({ name: node.name.text, fields: fields, component: component, alias: alias, doc: doc })
58
+ }
59
+ return { shapes: shapes, imports: imports, contracts: contracts }
60
+
61
+ function contract(node: ts.InterfaceDeclaration): Contract {
62
+ const methods = node.members.map((member): Method => {
63
+ if (!ts.isMethodSignature(member) || !ts.isIdentifier(member.name) || !member.type) fail(path, `${node.name.text}: an interface holds only methods, each with a return type`)
64
+ const name = member.name.text
65
+ const params = member.parameters.map(parameter => {
66
+ if (!ts.isIdentifier(parameter.name) || !parameter.type) fail(path, `${node.name.text}.${name}: every argument needs a name and a type`)
67
+ return { name: parameter.name.text, type: type(parameter.type), optional: !!parameter.questionToken }
68
+ })
69
+ const returned = member.type
70
+ const wrapper = ts.isTypeReferenceNode(returned) ? returned.typeName.getText(ast) : null
71
+ const args = ts.isTypeReferenceNode(returned) ? returned.typeArguments ?? [] : []
72
+ const doc = docOf(member)
73
+ if (name === "describe") {
74
+ if (params.length) fail(path, `${node.name.text}.describe: takes no arguments`)
75
+ if (wrapper) fail(path, `${node.name.text}.describe: answers plainly, at once — not a Promise; write what it reports`)
76
+ return { name: name, doc: doc, params: [], kind: "describe", answer: answer(returned, `${node.name.text}.describe`) }
77
+ }
78
+ if (wrapper === "Promise" && args.length === 1) return { name: name, doc: doc, params: params, kind: "call", answer: answer(args[0]!, `${node.name.text}.${name}`) }
79
+ if (wrapper === "AsyncIterable" && args.length === 1) return { name: name, doc: doc, params: params, kind: "stream", answer: required(answer(args[0]!, `${node.name.text}.${name}`), name) }
80
+ if (wrapper === "Session" && args.length === 2) {
81
+ if (params.length) fail(path, `${node.name.text}.${name}: a session opens with no arguments — what it needs is pushed`)
82
+ return { name: name, doc: doc, params: [], kind: "session", push: named(args[0]!, `${node.name.text}.${name}`), answer: required(answer(args[1]!, `${node.name.text}.${name}`), name) }
83
+ }
84
+ fail(path, `${node.name.text}.${name}: must return Promise<T>, AsyncIterable<T> or Session<Push, Answer>`)
85
+ })
86
+ if (!methods.some(method => method.kind === "describe")) fail(path, `${node.name.text}: every interface declares describe(), even one reporting nothing — describe(): {}`)
87
+ return { name: node.name.text, doc: docOf(node), methods: methods }
88
+ }
89
+
90
+ function answer(node: ts.TypeNode, owner: string): Answer {
91
+ if (node.kind === ts.SyntaxKind.VoidKeyword) return null
92
+ if (ts.isTypeLiteralNode(node)) {
93
+ return { inline: node.members.map(member => {
94
+ if (!ts.isPropertySignature(member) || !member.type || !member.name || !(ts.isIdentifier(member.name) || ts.isStringLiteral(member.name))) fail(path, `${owner}: only named, typed fields are supported`)
95
+ return { name: member.name.text, type: type(member.type), optional: !!member.questionToken }
96
+ }) }
97
+ }
98
+ return { named: named(node, owner) }
99
+ }
100
+
101
+ function named(node: ts.TypeNode, owner: string): string {
102
+ if (!ts.isTypeReferenceNode(node) || node.typeArguments?.length) fail(path, `${owner}: answers and pushes are named types or fields written inline, not ${node.getText(ast)}`)
103
+ return node.typeName.getText(ast)
104
+ }
105
+
106
+ function required(value: Answer, name: string): Answer {
107
+ if (value === null) fail(path, `${name}: a stream or session answers with something`)
108
+ return value
109
+ }
110
+
111
+ function handle(node: ts.TypeNode): string | null {
112
+ if (!ts.isTypeReferenceNode(node) || node.typeName.getText(ast) !== "Handle") return null
113
+ const [name] = node.typeArguments ?? []
114
+ if (!name || !ts.isLiteralTypeNode(name) || !ts.isStringLiteral(name.literal)) fail(path, `Handle<"Name"> takes its name as a string`)
115
+ return name.literal.text
116
+ }
117
+
118
+ function docOf(node: ts.Node): string | undefined {
119
+ // As written, tags and all: what a tag says is read by `said`, the same for every language.
120
+ const doc = ts.getJSDocCommentsAndTags(node).filter(ts.isJSDoc).map(comment => comment.getText(ast).replace(/^\/\*\*|\*\/$/g, "").split("\n").map(line => line.replace(/^\s*\*?\s?/, "").trimEnd()).join("\n").trim()).join("\n")
121
+ return doc || undefined
122
+ }
123
+
124
+ function type(node: ts.TypeNode): string {
125
+ if (ts.isParenthesizedTypeNode(node)) return type(node.type)
126
+ if (ts.isArrayTypeNode(node)) return `Vec<${type(node.elementType)}>`
127
+ if (ts.isTupleTypeNode(node)) {
128
+ if (node.elements.length === 0) fail(path, "empty tuples are not component values")
129
+ const elements = node.elements.map(type)
130
+ if (elements.some(element => element !== elements[0])) fail(path, "fixed tuples must use one element type")
131
+ return `Fixed<${elements[0]},${elements.length}>`
132
+ }
133
+ if (ts.isTypeReferenceNode(node)) {
134
+ const name = node.typeName.getText(ast)
135
+ const args = node.typeArguments?.map(type) ?? []
136
+ if (name === "Array" && args.length === 1) return `Vec<${args[0]}>`
137
+ if (name === "Record" && args.length === 2) return `Record<${args.join(",")}>`
138
+ if (name === "Partial" && args.length === 1 && args[0]!.startsWith("Record<")) return args[0]!
139
+ if (args.length) fail(path, `unsupported type ${node.getText(ast)}`)
140
+ return name
141
+ }
142
+ if (node.kind === ts.SyntaxKind.NumberKeyword) return "number"
143
+ if (node.kind === ts.SyntaxKind.StringKeyword) return "string"
144
+ if (node.kind === ts.SyntaxKind.BooleanKeyword) return "boolean"
145
+ fail(path, `unsupported TypeScript field type ${node.getText(ast)}`)
146
+ }
147
+
148
+ function nullableType(node: ts.TypeNode): ts.TypeNode | null {
149
+ if (!ts.isUnionTypeNode(node)) return null
150
+ const values = node.types.filter(part => !(ts.isLiteralTypeNode(part) && part.literal.kind === ts.SyntaxKind.NullKeyword))
151
+ return values.length === 1 && values.length < node.types.length ? values[0]! : null
152
+ }
153
+ }
154
+
155
+ function withTs(specifier: string): string {
156
+ return specifier.endsWith(".ts") ? specifier : `${specifier}.ts`
157
+ }
@@ -0,0 +1,5 @@
1
+ // schema — native component sources and older schemas compiled through protobuf for every language.
2
+ export { Schema, type SchemaOpts, type SchemaT, type Described } from "./schema"
3
+ // The name a path segment has as a Rust module — what the crate mounts a cognet's own .rs files by, as the schemas' are.
4
+ export { rust } from "./rust"
5
+ export { contractOf } from "./interfaces"
@@ -0,0 +1,3 @@
1
+ // interfaces — the service contracts a cognet uses, compiled beside its components.
2
+
3
+ export { Interfaces, contractOf, type InterfacesOpts, type Compiled } from "./source"