primitive-admin 1.2.0-alpha.14 → 1.2.0-alpha.15
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/README.md +102 -78
- package/assets/skill/skills/primitive-platform/SKILL.md +87 -23
- package/dist/bin/primitive.js +11 -82
- package/dist/bin/primitive.js.map +1 -1
- package/dist/src/commands/admins.js +79 -17
- package/dist/src/commands/admins.js.map +1 -1
- package/dist/src/commands/agent-sessions.js +2 -0
- package/dist/src/commands/agent-sessions.js.map +1 -1
- package/dist/src/commands/analytics.js +183 -12
- package/dist/src/commands/analytics.js.map +1 -1
- package/dist/src/commands/apps-children.js +2 -0
- package/dist/src/commands/apps-children.js.map +1 -1
- package/dist/src/commands/apps.js +19 -2
- package/dist/src/commands/apps.js.map +1 -1
- package/dist/src/commands/auth.js +11 -1
- package/dist/src/commands/auth.js.map +1 -1
- package/dist/src/commands/collections.js +13 -0
- package/dist/src/commands/collections.js.map +1 -1
- package/dist/src/commands/config.d.ts +1 -1
- package/dist/src/commands/config.js +40 -9
- package/dist/src/commands/config.js.map +1 -1
- package/dist/src/commands/connections.js +2 -0
- package/dist/src/commands/connections.js.map +1 -1
- package/dist/src/commands/database-type-configs.js +5 -3
- package/dist/src/commands/database-type-configs.js.map +1 -1
- package/dist/src/commands/databases.js +6 -4
- package/dist/src/commands/databases.js.map +1 -1
- package/dist/src/commands/db3-types.js +2 -0
- package/dist/src/commands/db3-types.js.map +1 -1
- package/dist/src/commands/db3.d.ts +12 -0
- package/dist/src/commands/db3.js +343 -24
- package/dist/src/commands/db3.js.map +1 -1
- package/dist/src/commands/documents.d.ts +52 -12
- package/dist/src/commands/documents.js +120 -29
- package/dist/src/commands/documents.js.map +1 -1
- package/dist/src/commands/email-templates.js +72 -0
- package/dist/src/commands/email-templates.js.map +1 -1
- package/dist/src/commands/functions.js +47 -10
- package/dist/src/commands/functions.js.map +1 -1
- package/dist/src/commands/groups.js +18 -3
- package/dist/src/commands/groups.js.map +1 -1
- package/dist/src/commands/init.js +7 -1
- package/dist/src/commands/init.js.map +1 -1
- package/dist/src/commands/integrations.js +80 -47
- package/dist/src/commands/integrations.js.map +1 -1
- package/dist/src/commands/metadata-category-configs.js +2 -0
- package/dist/src/commands/metadata-category-configs.js.map +1 -1
- package/dist/src/commands/metadata.js +41 -0
- package/dist/src/commands/metadata.js.map +1 -1
- package/dist/src/commands/prompts.js +73 -47
- package/dist/src/commands/prompts.js.map +1 -1
- package/dist/src/commands/rule-sets.js +2 -0
- package/dist/src/commands/rule-sets.js.map +1 -1
- package/dist/src/commands/schemas.d.ts +15 -0
- package/dist/src/commands/schemas.js +122 -0
- package/dist/src/commands/schemas.js.map +1 -0
- package/dist/src/commands/secrets.js +45 -3
- package/dist/src/commands/secrets.js.map +1 -1
- package/dist/src/commands/sessions.js +2 -0
- package/dist/src/commands/sessions.js.map +1 -1
- package/dist/src/commands/sync-schemas.d.ts +202 -0
- package/dist/src/commands/sync-schemas.js +629 -0
- package/dist/src/commands/sync-schemas.js.map +1 -0
- package/dist/src/commands/sync-user-properties.d.ts +118 -0
- package/dist/src/commands/sync-user-properties.js +276 -0
- package/dist/src/commands/sync-user-properties.js.map +1 -0
- package/dist/src/commands/sync.d.ts +243 -12
- package/dist/src/commands/sync.js +1474 -314
- package/dist/src/commands/sync.js.map +1 -1
- package/dist/src/commands/user-properties.d.ts +14 -0
- package/dist/src/commands/user-properties.js +79 -0
- package/dist/src/commands/user-properties.js.map +1 -0
- package/dist/src/commands/users.js +879 -16
- package/dist/src/commands/users.js.map +1 -1
- package/dist/src/commands/waitlist.js +39 -4
- package/dist/src/commands/waitlist.js.map +1 -1
- package/dist/src/lib/analytics-query.d.ts +58 -0
- package/dist/src/lib/analytics-query.js +134 -0
- package/dist/src/lib/analytics-query.js.map +1 -0
- package/dist/src/lib/api-client.d.ts +748 -95
- package/dist/src/lib/api-client.js +356 -158
- package/dist/src/lib/api-client.js.map +1 -1
- package/dist/src/lib/block-selector.d.ts +9 -15
- package/dist/src/lib/block-selector.js +9 -20
- package/dist/src/lib/block-selector.js.map +1 -1
- package/dist/src/lib/cli-manifest.d.ts +8 -0
- package/dist/src/lib/cli-manifest.js +10 -1
- package/dist/src/lib/cli-manifest.js.map +1 -1
- package/dist/src/lib/cli-version.d.ts +14 -0
- package/dist/src/lib/cli-version.js +38 -0
- package/dist/src/lib/cli-version.js.map +1 -0
- package/dist/src/lib/codegen-shared/prettierStable.d.ts +41 -0
- package/dist/src/lib/codegen-shared/prettierStable.js +146 -24
- package/dist/src/lib/codegen-shared/prettierStable.js.map +1 -1
- package/dist/src/lib/command-status.d.ts +110 -0
- package/dist/src/lib/command-status.js +184 -0
- package/dist/src/lib/command-status.js.map +1 -0
- package/dist/src/lib/config-object-descriptor.d.ts +6 -0
- package/dist/src/lib/config-object-descriptor.js +71 -0
- package/dist/src/lib/config-object-descriptor.js.map +1 -1
- package/dist/src/lib/config-toml.d.ts +11 -2
- package/dist/src/lib/config-toml.js +25 -2
- package/dist/src/lib/config-toml.js.map +1 -1
- package/dist/src/lib/data-input.d.ts +1 -1
- package/dist/src/lib/data-input.js +1 -1
- package/dist/src/lib/db-codegen/dbTsTypes.d.ts +1 -1
- package/dist/src/lib/db-codegen/dbTsTypes.js +3 -0
- package/dist/src/lib/db-codegen/dbTsTypes.js.map +1 -1
- package/dist/src/lib/db-codegen/dbTypeIR.d.ts +11 -1
- package/dist/src/lib/db-codegen/dbTypeIR.js +11 -5
- package/dist/src/lib/db-codegen/dbTypeIR.js.map +1 -1
- package/dist/src/lib/db-type-records.d.ts +95 -0
- package/dist/src/lib/db-type-records.js +219 -0
- package/dist/src/lib/db-type-records.js.map +1 -0
- package/dist/src/lib/db3-export.d.ts +51 -14
- package/dist/src/lib/db3-export.js +135 -27
- package/dist/src/lib/db3-export.js.map +1 -1
- package/dist/src/lib/db3-index-output.d.ts +68 -3
- package/dist/src/lib/db3-index-output.js +139 -3
- package/dist/src/lib/db3-index-output.js.map +1 -1
- package/dist/src/lib/db3-type-models.d.ts +39 -7
- package/dist/src/lib/db3-type-models.js +138 -27
- package/dist/src/lib/db3-type-models.js.map +1 -1
- package/dist/src/lib/deprecation.d.ts +2 -2
- package/dist/src/lib/deprecation.js +2 -2
- package/dist/src/lib/experimental-apis.d.ts +36 -0
- package/dist/src/lib/experimental-apis.js +46 -0
- package/dist/src/lib/experimental-apis.js.map +1 -0
- package/dist/src/lib/file-attachment.d.ts +24 -0
- package/dist/src/lib/file-attachment.js +31 -0
- package/dist/src/lib/file-attachment.js.map +1 -0
- package/dist/src/lib/function-authorize-check.d.ts +1 -1
- package/dist/src/lib/function-authorize-check.js +2 -1
- package/dist/src/lib/function-authorize-check.js.map +1 -1
- package/dist/src/lib/function-authorize-view.js +4 -0
- package/dist/src/lib/function-authorize-view.js.map +1 -1
- package/dist/src/lib/function-bundle.d.ts +27 -5
- package/dist/src/lib/function-bundle.js +106 -7
- package/dist/src/lib/function-bundle.js.map +1 -1
- package/dist/src/lib/function-collect.d.ts +2 -0
- package/dist/src/lib/function-collect.js +36 -7
- package/dist/src/lib/function-collect.js.map +1 -1
- package/dist/src/lib/function-db-types.d.ts +57 -40
- package/dist/src/lib/function-db-types.js +246 -285
- package/dist/src/lib/function-db-types.js.map +1 -1
- package/dist/src/lib/function-document-types.d.ts +19 -7
- package/dist/src/lib/function-document-types.js +24 -12
- package/dist/src/lib/function-document-types.js.map +1 -1
- package/dist/src/lib/function-run.d.ts +1 -1
- package/dist/src/lib/function-run.js +1 -1
- package/dist/src/lib/function-run.js.map +1 -1
- package/dist/src/lib/function-schema-codegen.d.ts +58 -18
- package/dist/src/lib/function-schema-codegen.js +85 -74
- package/dist/src/lib/function-schema-codegen.js.map +1 -1
- package/dist/src/lib/function-schema-refs.d.ts +98 -0
- package/dist/src/lib/function-schema-refs.js +177 -0
- package/dist/src/lib/function-schema-refs.js.map +1 -0
- package/dist/src/lib/function-sync.d.ts +38 -4
- package/dist/src/lib/function-sync.js +83 -14
- package/dist/src/lib/function-sync.js.map +1 -1
- package/dist/src/lib/function-typecheck.d.ts +52 -0
- package/dist/src/lib/function-typecheck.js +171 -54
- package/dist/src/lib/function-typecheck.js.map +1 -1
- package/dist/src/lib/generated-build-flags.d.ts +13 -0
- package/dist/src/lib/generated-build-flags.js +14 -0
- package/dist/src/lib/generated-build-flags.js.map +1 -0
- package/dist/src/lib/generated-config-surfaces.d.ts +211 -11
- package/dist/src/lib/generated-config-surfaces.js +579 -69
- package/dist/src/lib/generated-config-surfaces.js.map +1 -1
- package/dist/src/lib/generated-sdk-types.d.ts +1 -1
- package/dist/src/lib/generated-sdk-types.js +1 -1
- package/dist/src/lib/generated-sdk-types.js.map +1 -1
- package/dist/src/lib/integration-test-request.d.ts +54 -0
- package/dist/src/lib/integration-test-request.js +207 -0
- package/dist/src/lib/integration-test-request.js.map +1 -0
- package/dist/src/lib/metadata-report.d.ts +85 -0
- package/dist/src/lib/metadata-report.js +81 -0
- package/dist/src/lib/metadata-report.js.map +1 -0
- package/dist/src/lib/output.d.ts +1 -1
- package/dist/src/lib/output.js +1 -1
- package/dist/src/lib/platform-owned.js +5 -0
- package/dist/src/lib/platform-owned.js.map +1 -1
- package/dist/src/lib/primitive-declaration-names.d.ts +21 -0
- package/dist/src/lib/primitive-declaration-names.js +22 -0
- package/dist/src/lib/primitive-declaration-names.js.map +1 -0
- package/dist/src/lib/primitive-declaration.d.ts +143 -0
- package/dist/src/lib/primitive-declaration.js +658 -0
- package/dist/src/lib/primitive-declaration.js.map +1 -0
- package/dist/src/lib/prompt-schema-codegen.d.ts +36 -12
- package/dist/src/lib/prompt-schema-codegen.js +82 -98
- package/dist/src/lib/prompt-schema-codegen.js.map +1 -1
- package/dist/src/lib/prompt-schema-document.d.ts +35 -0
- package/dist/src/lib/prompt-schema-document.js +92 -0
- package/dist/src/lib/prompt-schema-document.js.map +1 -0
- package/dist/src/lib/prompt-schema-refs.d.ts +164 -0
- package/dist/src/lib/prompt-schema-refs.js +452 -0
- package/dist/src/lib/prompt-schema-refs.js.map +1 -0
- package/dist/src/lib/records-verbs.d.ts +12 -2
- package/dist/src/lib/records-verbs.js +7 -2
- package/dist/src/lib/records-verbs.js.map +1 -1
- package/dist/src/lib/register-commands.d.ts +28 -0
- package/dist/src/lib/register-commands.js +101 -0
- package/dist/src/lib/register-commands.js.map +1 -0
- package/dist/src/lib/retired-imports.d.ts +53 -0
- package/dist/src/lib/retired-imports.js +120 -0
- package/dist/src/lib/retired-imports.js.map +1 -0
- package/dist/src/lib/schema-codegen/compiledSpace.d.ts +62 -0
- package/dist/src/lib/schema-codegen/compiledSpace.js +103 -0
- package/dist/src/lib/schema-codegen/compiledSpace.js.map +1 -0
- package/dist/src/lib/schema-codegen/generated-db3-bridge.d.ts +86 -0
- package/dist/src/lib/schema-codegen/generated-db3-bridge.js +221 -0
- package/dist/src/lib/schema-codegen/generated-db3-bridge.js.map +1 -0
- package/dist/src/lib/schema-codegen/generated-db3-query-capabilities.d.ts +85 -0
- package/dist/src/lib/schema-codegen/generated-db3-query-capabilities.js +86 -0
- package/dist/src/lib/schema-codegen/generated-db3-query-capabilities.js.map +1 -0
- package/dist/src/lib/schema-codegen/generated-field-grammar.d.ts +209 -0
- package/dist/src/lib/schema-codegen/generated-field-grammar.js +379 -0
- package/dist/src/lib/schema-codegen/generated-field-grammar.js.map +1 -0
- package/dist/src/lib/schema-codegen/generated-field-table.d.ts +80 -0
- package/dist/src/lib/schema-codegen/generated-field-table.js +542 -0
- package/dist/src/lib/schema-codegen/generated-field-table.js.map +1 -0
- package/dist/src/lib/schema-codegen/generated-prompt-schemas.d.ts +195 -0
- package/dist/src/lib/schema-codegen/generated-prompt-schemas.js +503 -0
- package/dist/src/lib/schema-codegen/generated-prompt-schemas.js.map +1 -0
- package/dist/src/lib/schema-codegen/generated-schema-descriptor.d.ts +129 -0
- package/dist/src/lib/schema-codegen/generated-schema-descriptor.js +154 -1
- package/dist/src/lib/schema-codegen/generated-schema-descriptor.js.map +1 -1
- package/dist/src/lib/schema-codegen/generated-schema-file.d.ts +129 -0
- package/dist/src/lib/schema-codegen/generated-schema-file.js +475 -0
- package/dist/src/lib/schema-codegen/generated-schema-file.js.map +1 -0
- package/dist/src/lib/schema-codegen/generated-schema-provenance.d.ts +115 -0
- package/dist/src/lib/schema-codegen/generated-schema-provenance.js +274 -0
- package/dist/src/lib/schema-codegen/generated-schema-provenance.js.map +1 -0
- package/dist/src/lib/schema-codegen/generated-schema-refs.d.ts +366 -0
- package/dist/src/lib/schema-codegen/generated-schema-refs.js +1789 -0
- package/dist/src/lib/schema-codegen/generated-schema-refs.js.map +1 -0
- package/dist/src/lib/schema-codegen/namedRefs.d.ts +56 -0
- package/dist/src/lib/schema-codegen/namedRefs.js +143 -0
- package/dist/src/lib/schema-codegen/namedRefs.js.map +1 -0
- package/dist/src/lib/schema-codegen/schemaChanges.d.ts +74 -0
- package/dist/src/lib/schema-codegen/schemaChanges.js +277 -0
- package/dist/src/lib/schema-codegen/schemaChanges.js.map +1 -0
- package/dist/src/lib/schema-codegen/schemaDocs.d.ts +69 -0
- package/dist/src/lib/schema-codegen/schemaDocs.js +219 -0
- package/dist/src/lib/schema-codegen/schemaDocs.js.map +1 -0
- package/dist/src/lib/schema-codegen/schemaIR.d.ts +158 -0
- package/dist/src/lib/schema-codegen/schemaIR.js +279 -0
- package/dist/src/lib/schema-codegen/schemaIR.js.map +1 -0
- package/dist/src/lib/schema-codegen/schemaToTs.d.ts +40 -13
- package/dist/src/lib/schema-codegen/schemaToTs.js +124 -160
- package/dist/src/lib/schema-codegen/schemaToTs.js.map +1 -1
- package/dist/src/lib/schema-codegen/valuesLists.d.ts +35 -0
- package/dist/src/lib/schema-codegen/valuesLists.js +128 -0
- package/dist/src/lib/schema-codegen/valuesLists.js.map +1 -0
- package/dist/src/lib/schema-family-index.d.ts +228 -0
- package/dist/src/lib/schema-family-index.js +813 -0
- package/dist/src/lib/schema-family-index.js.map +1 -0
- package/dist/src/lib/schema-pins.d.ts +82 -0
- package/dist/src/lib/schema-pins.js +198 -0
- package/dist/src/lib/schema-pins.js.map +1 -0
- package/dist/src/lib/schema-preview.d.ts +244 -0
- package/dist/src/lib/schema-preview.js +498 -0
- package/dist/src/lib/schema-preview.js.map +1 -0
- package/dist/src/lib/skill-installer.d.ts +2 -2
- package/dist/src/lib/skill-installer.js +2 -21
- package/dist/src/lib/skill-installer.js.map +1 -1
- package/dist/src/lib/step-run-table.d.ts +1 -2
- package/dist/src/lib/step-run-table.js +1 -2
- package/dist/src/lib/step-run-table.js.map +1 -1
- package/dist/src/lib/swift-codegen/agentGenerator.d.ts +2 -1
- package/dist/src/lib/swift-codegen/agentGenerator.js +24 -22
- package/dist/src/lib/swift-codegen/agentGenerator.js.map +1 -1
- package/dist/src/lib/swift-codegen/banners.d.ts +12 -0
- package/dist/src/lib/swift-codegen/banners.js +12 -0
- package/dist/src/lib/swift-codegen/banners.js.map +1 -1
- package/dist/src/lib/swift-codegen/functionGenerator.d.ts +36 -1
- package/dist/src/lib/swift-codegen/functionGenerator.js +167 -50
- package/dist/src/lib/swift-codegen/functionGenerator.js.map +1 -1
- package/dist/src/lib/swift-codegen/schemaToSwift.d.ts +31 -7
- package/dist/src/lib/swift-codegen/schemaToSwift.js +213 -177
- package/dist/src/lib/swift-codegen/schemaToSwift.js.map +1 -1
- package/dist/src/lib/swift-codegen/sharedGenerator.d.ts +45 -0
- package/dist/src/lib/swift-codegen/sharedGenerator.js +120 -0
- package/dist/src/lib/swift-codegen/sharedGenerator.js.map +1 -0
- package/dist/src/lib/swift-codegen/userPropertiesGenerator.d.ts +30 -0
- package/dist/src/lib/swift-codegen/userPropertiesGenerator.js +69 -0
- package/dist/src/lib/swift-codegen/userPropertiesGenerator.js.map +1 -0
- package/dist/src/lib/sync-resource-types.d.ts +37 -5
- package/dist/src/lib/sync-resource-types.js +53 -5
- package/dist/src/lib/sync-resource-types.js.map +1 -1
- package/dist/src/lib/sync-selectors.d.ts +7 -0
- package/dist/src/lib/sync-selectors.js +22 -2
- package/dist/src/lib/sync-selectors.js.map +1 -1
- package/dist/src/lib/test-runs.d.ts +45 -0
- package/dist/src/lib/test-runs.js +150 -0
- package/dist/src/lib/test-runs.js.map +1 -0
- package/dist/src/lib/toml-database-config.d.ts +2 -1
- package/dist/src/lib/toml-database-config.js +4 -3
- package/dist/src/lib/toml-database-config.js.map +1 -1
- package/dist/src/lib/toml-scalar-edit.js +6 -4
- package/dist/src/lib/toml-scalar-edit.js.map +1 -1
- package/dist/src/lib/user-index.d.ts +80 -0
- package/dist/src/lib/user-index.js +166 -0
- package/dist/src/lib/user-index.js.map +1 -0
- package/dist/src/lib/user-properties/generated-properties-schema.d.ts +159 -0
- package/dist/src/lib/user-properties/generated-properties-schema.js +471 -0
- package/dist/src/lib/user-properties/generated-properties-schema.js.map +1 -0
- package/dist/src/lib/user-properties/user-properties-codegen.d.ts +55 -0
- package/dist/src/lib/user-properties/user-properties-codegen.js +129 -0
- package/dist/src/lib/user-properties/user-properties-codegen.js.map +1 -0
- package/dist/src/lib/user-walk.d.ts +31 -0
- package/dist/src/lib/user-walk.js +102 -0
- package/dist/src/lib/user-walk.js.map +1 -0
- package/dist/src/lib/worker-perf-format.d.ts +22 -0
- package/dist/src/lib/worker-perf-format.js +27 -0
- package/dist/src/lib/worker-perf-format.js.map +1 -0
- package/dist/src/types/index.d.ts +13 -34
- package/package.json +5 -3
|
@@ -0,0 +1,1789 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* GENERATED FILE — DO NOT EDIT BY HAND.
|
|
3
|
+
*
|
|
4
|
+
* Vendored from the canonical server module
|
|
5
|
+
* `src/function-runs/schema-refs.ts` — the SAME interpretation the server
|
|
6
|
+
* applies to a function's schemas. The CLI cannot import server `src/`
|
|
7
|
+
* at runtime, so the CLI imports this committed copy instead.
|
|
8
|
+
*
|
|
9
|
+
* Regenerate with:
|
|
10
|
+
* node cli/scripts/gen-schema-descriptor.mjs (runs at CLI prebuild)
|
|
11
|
+
*
|
|
12
|
+
* A CI freshness guard
|
|
13
|
+
* (`cli/scripts/gen-schema-descriptor.mjs --check`, also asserted by
|
|
14
|
+
* `cli/tests/unit/schema-codegen-descriptor-drift-guard.test.ts`) fails if
|
|
15
|
+
* this committed copy does not match the source — see issue #1442 / #998.
|
|
16
|
+
*/
|
|
17
|
+
/**
|
|
18
|
+
* Named types in a function schema: the `$ref` compiler.
|
|
19
|
+
*
|
|
20
|
+
* A function schema may define shapes once under a root `$defs` and use them
|
|
21
|
+
* with local refs (`{ "$ref": "#/$defs/Money" }`). The platform's validator
|
|
22
|
+
* never resolves a ref, so refs are resolved here, when a schema is written:
|
|
23
|
+
* `compileSchemaRefs` inlines every local `#/$defs/` ref whose target exists,
|
|
24
|
+
* and the existing schema fields store the compiled, inlined document. Every
|
|
25
|
+
* reader of those fields (the validator, the generated types, the provider
|
|
26
|
+
* translators) is unchanged.
|
|
27
|
+
*
|
|
28
|
+
* Which refs resolve:
|
|
29
|
+
*
|
|
30
|
+
* - a `#/$defs/<Name>[/...]` pointer (RFC 6901 escapes honoured) naming a
|
|
31
|
+
* plain-object node, whose expansion does not loop, is inlined;
|
|
32
|
+
* - every other ref stays inert, as written, and gets a warning: a dangling
|
|
33
|
+
* pointer, a target that is not a schema, `#`, a pointer outside `$defs`,
|
|
34
|
+
* a cycle, a remote URL, a bare name, and a family-prefixed ref
|
|
35
|
+
* (`schemas:`, `fn:`, `prompt:`, `db3:`), which resolves from the
|
|
36
|
+
* shared-shapes release.
|
|
37
|
+
*
|
|
38
|
+
* Beside a resolved ref only annotations (a table annotation row, a key the
|
|
39
|
+
* table does not name, or `nullable`) are kept; an enforced or refused keyword
|
|
40
|
+
* there is a refusal, because the definition replaces the node. A document that
|
|
41
|
+
* inlined a ref is held to `SCHEMA_EXPANSION_LIMITS` after expansion. A
|
|
42
|
+
* document with no resolvable ref compiles to itself, so no schema that pushes
|
|
43
|
+
* today is refused.
|
|
44
|
+
*
|
|
45
|
+
* Shared shapes (#5533): given a family index (`options.families`), a ref to a
|
|
46
|
+
* def in an app's `schemas/` files resolves too, written three ways: the
|
|
47
|
+
* explicit `{ "$ref": "schemas:<file>#/$defs/<Name>" }`, the long
|
|
48
|
+
* `{ "ref": "schemas.<file>.<Name>" }`, and the short `{ "ref": "<Name>" }`
|
|
49
|
+
* (one file declares it) or `{ "ref": "<file>.<Name>" }` (the key names one
|
|
50
|
+
* family, and that is `schemas/`). The def's compiled form is inlined, copied
|
|
51
|
+
* whole: its interior is never compiled again. Beside `ref` only
|
|
52
|
+
* `description`, `required` and `nullable` may sit. A ref that cannot resolve,
|
|
53
|
+
* an ambiguous short form, a tombstoned file and the reserved `platform`
|
|
54
|
+
* prefix are refusals. Without an index, every ref behaves as above.
|
|
55
|
+
*
|
|
56
|
+
* db3 models (#5540): given an index with a db3 slot, a ref to a db3 type's
|
|
57
|
+
* model resolves too: the explicit `{ "$ref": "db3:<type>#/$defs/<model>" }`
|
|
58
|
+
* (with an optional `/row` or `/declared` segment), the long
|
|
59
|
+
* `{ "ref": "db3.<type>.<model>" }` and the short `{ "ref": "<type>.<model>" }`
|
|
60
|
+
* (the key names one family, and that is db3), the last two with an optional
|
|
61
|
+
* `#row` or `#declared`. A projection written on the ref wins; otherwise the
|
|
62
|
+
* compile's `position` picks it: the row in an output schema, the declared
|
|
63
|
+
* shape elsewhere, and none in a `schemas/` def, which must name one. The
|
|
64
|
+
* projection, built by whoever builds the index (`db3-bridge.ts`), is inlined
|
|
65
|
+
* opaque, as a shared def is, and every db3 refusal names the projection and
|
|
66
|
+
* how it was chosen.
|
|
67
|
+
*
|
|
68
|
+
* Pure and deterministic, importing only the keyword table, the provenance
|
|
69
|
+
* module and the db3 bridge's projection names, so the CLI vendors it beside the descriptor
|
|
70
|
+
* (`cli/scripts/gen-schema-descriptor.mjs`) and both sides compile a schema to
|
|
71
|
+
* the same bytes.
|
|
72
|
+
*/
|
|
73
|
+
import { SCHEMA_KEYWORDS } from "./generated-schema-descriptor.js";
|
|
74
|
+
import { SCHEMA_CANONICAL_INVALID, SCHEMA_PROVENANCE_LIMIT_BYTES, SchemaCanonicalError, canonicalJson, } from "./generated-schema-provenance.js";
|
|
75
|
+
import { DB3_PROJECTIONS, parseDb3ProjectionMarker } from "./generated-db3-bridge.js";
|
|
76
|
+
/** The family prefixes a `$ref` resolves through once shared shapes ship. */
|
|
77
|
+
export const REF_FAMILY_PREFIXES = Object.freeze(["schemas:", "fn:", "prompt:", "db3:"]);
|
|
78
|
+
/**
|
|
79
|
+
* The caps on a compiled schema that inlined at least one ref: 160 KiB and
|
|
80
|
+
* 2048 objects and arrays. A function row holds both of its schemas inline,
|
|
81
|
+
* so the byte cap leaves room for the other schema under the row budget.
|
|
82
|
+
*/
|
|
83
|
+
export const SCHEMA_EXPANSION_LIMITS = Object.freeze({ bytes: 163840, nodes: 2048 });
|
|
84
|
+
/**
|
|
85
|
+
* The bytes a function row may spend on its two compiled schemas together
|
|
86
|
+
* (320 KiB), checked when a write inlined a ref. The row is one storage item,
|
|
87
|
+
* capped at 400 KB with the rest of the function's fields.
|
|
88
|
+
*/
|
|
89
|
+
export const FUNCTION_SCHEMA_ROW_BUDGET_BYTES = 327680;
|
|
90
|
+
/** The refusal code for a schema over an expansion limit or the row budget. */
|
|
91
|
+
export const FUNCTION_SCHEMA_EXPANSION_LIMIT = "FUNCTION_SCHEMA_EXPANSION_LIMIT";
|
|
92
|
+
/** The refusal code for a constraint keyword beside a resolved `$ref`. */
|
|
93
|
+
export const FUNCTION_SCHEMA_REF_SIBLING = "FUNCTION_SCHEMA_REF_SIBLING";
|
|
94
|
+
/** The refusal code for a ref to a shared def that no def answers. */
|
|
95
|
+
export const FUNCTION_SCHEMA_REF_UNRESOLVED = "FUNCTION_SCHEMA_REF_UNRESOLVED";
|
|
96
|
+
/** The refusal code for a short ref more than one target could answer. */
|
|
97
|
+
export const FUNCTION_SCHEMA_REF_AMBIGUOUS = "FUNCTION_SCHEMA_REF_AMBIGUOUS";
|
|
98
|
+
/** The refusal code for a ref to a deleted (tombstoned) `schemas/` file. */
|
|
99
|
+
export const FUNCTION_SCHEMA_REF_TOMBSTONED = "FUNCTION_SCHEMA_REF_TOMBSTONED";
|
|
100
|
+
/** The refusal code for a ref with the reserved `platform` prefix. */
|
|
101
|
+
export const FUNCTION_SCHEMA_REF_RESERVED = "FUNCTION_SCHEMA_REF_RESERVED";
|
|
102
|
+
// ── Walking a schema ─────────────────────────────────────────────────
|
|
103
|
+
/** Keywords whose value is a map of subschemas the compile descends into. */
|
|
104
|
+
const SUBSCHEMA_MAPS = new Set(["properties", "patternProperties", "dependentSchemas"]);
|
|
105
|
+
/** Keywords holding definitions: classified, never compiled in place. */
|
|
106
|
+
const DEFINITION_MAPS = new Set(["$defs", "definitions"]);
|
|
107
|
+
/** Keywords whose value is one subschema. */
|
|
108
|
+
const SUBSCHEMA_ONE = new Set([
|
|
109
|
+
"items",
|
|
110
|
+
"additionalProperties",
|
|
111
|
+
"additionalItems",
|
|
112
|
+
"not",
|
|
113
|
+
"if",
|
|
114
|
+
"then",
|
|
115
|
+
"else",
|
|
116
|
+
"contains",
|
|
117
|
+
"propertyNames",
|
|
118
|
+
"unevaluatedProperties",
|
|
119
|
+
"unevaluatedItems",
|
|
120
|
+
]);
|
|
121
|
+
/** Keywords whose value is a list of subschemas. */
|
|
122
|
+
const SUBSCHEMA_LIST = new Set(["anyOf", "oneOf", "allOf", "prefixItems", "items"]);
|
|
123
|
+
function isPlainObject(value) {
|
|
124
|
+
return value !== null && typeof value === "object" && !Array.isArray(value);
|
|
125
|
+
}
|
|
126
|
+
/**
|
|
127
|
+
* Set `key` as an own data property. Plain assignment would treat a key named
|
|
128
|
+
* `__proto__` (which `JSON.parse` gives as an ordinary key) as the prototype
|
|
129
|
+
* and drop it.
|
|
130
|
+
*/
|
|
131
|
+
function setOwn(target, key, value) {
|
|
132
|
+
Object.defineProperty(target, key, { value, enumerable: true, writable: true, configurable: true });
|
|
133
|
+
}
|
|
134
|
+
function pointerSegment(segment) {
|
|
135
|
+
return segment.replace(/~/g, "~0").replace(/\//g, "~1");
|
|
136
|
+
}
|
|
137
|
+
function dotted(path, segment) {
|
|
138
|
+
return path ? `${path}.${segment}` : segment;
|
|
139
|
+
}
|
|
140
|
+
function display(pointer) {
|
|
141
|
+
return `#${pointer}`;
|
|
142
|
+
}
|
|
143
|
+
/**
|
|
144
|
+
* The direct subschemas of `node`, in document order, with their pointer and
|
|
145
|
+
* dotted segments. `definitions: true` includes the definition maps.
|
|
146
|
+
*/
|
|
147
|
+
function subschemas(node, definitions) {
|
|
148
|
+
const out = [];
|
|
149
|
+
for (const [key, value] of Object.entries(node)) {
|
|
150
|
+
if ((SUBSCHEMA_MAPS.has(key) || (definitions && DEFINITION_MAPS.has(key))) && isPlainObject(value)) {
|
|
151
|
+
for (const [name, child] of Object.entries(value)) {
|
|
152
|
+
out.push({ key, name, child, pointer: `/${pointerSegment(key)}/${pointerSegment(name)}`, path: dotted(key, name) });
|
|
153
|
+
}
|
|
154
|
+
}
|
|
155
|
+
else if (SUBSCHEMA_LIST.has(key) && Array.isArray(value)) {
|
|
156
|
+
value.forEach((child, index) => out.push({ key, name: index, child, pointer: `/${pointerSegment(key)}/${index}`, path: `${key}[${index}]` }));
|
|
157
|
+
}
|
|
158
|
+
else if (SUBSCHEMA_ONE.has(key) && isPlainObject(value)) {
|
|
159
|
+
out.push({ key, child: value, pointer: `/${pointerSegment(key)}`, path: key });
|
|
160
|
+
}
|
|
161
|
+
}
|
|
162
|
+
return out;
|
|
163
|
+
}
|
|
164
|
+
/**
|
|
165
|
+
* Every string `$ref` at or below `root`, with where it sits relative to it,
|
|
166
|
+
* in document order. Walked with its own stack, so a deeply nested schema
|
|
167
|
+
* cannot exhaust the call stack.
|
|
168
|
+
*/
|
|
169
|
+
function eachRef(root, visit) {
|
|
170
|
+
// Last pushed runs first: subschemas are visited in document order.
|
|
171
|
+
const stack = [{ node: root, pointer: "", path: "" }];
|
|
172
|
+
while (stack.length > 0) {
|
|
173
|
+
const { node, pointer, path } = stack.pop();
|
|
174
|
+
if (!isPlainObject(node))
|
|
175
|
+
continue;
|
|
176
|
+
if (typeof node.$ref === "string")
|
|
177
|
+
visit(node.$ref, pointer, path);
|
|
178
|
+
const subs = subschemas(node, true);
|
|
179
|
+
for (let index = subs.length - 1; index >= 0; index--) {
|
|
180
|
+
const sub = subs[index];
|
|
181
|
+
stack.push({ node: sub.child, pointer: pointer + sub.pointer, path: path ? `${path}.${sub.path}` : sub.path });
|
|
182
|
+
}
|
|
183
|
+
}
|
|
184
|
+
}
|
|
185
|
+
/** The node a local JSON pointer (`#/a/b`, RFC 6901 escapes) names in `doc`, or `undefined`. */
|
|
186
|
+
function resolveLocalPointer(doc, pointer) {
|
|
187
|
+
if (pointer === "#")
|
|
188
|
+
return doc;
|
|
189
|
+
if (!pointer.startsWith("#/"))
|
|
190
|
+
return undefined;
|
|
191
|
+
let node = doc;
|
|
192
|
+
for (const raw of pointer.slice(2).split("/")) {
|
|
193
|
+
const segment = raw.replace(/~1/g, "/").replace(/~0/g, "~");
|
|
194
|
+
if (Array.isArray(node) && /^\d+$/.test(segment))
|
|
195
|
+
node = node[Number(segment)];
|
|
196
|
+
else if (isPlainObject(node) && Object.prototype.hasOwnProperty.call(node, segment))
|
|
197
|
+
node = node[segment];
|
|
198
|
+
else
|
|
199
|
+
return undefined;
|
|
200
|
+
}
|
|
201
|
+
return node;
|
|
202
|
+
}
|
|
203
|
+
/** What one compile knows about its document's refs, memoised per ref text. */
|
|
204
|
+
class RefAnalyzer {
|
|
205
|
+
doc;
|
|
206
|
+
verdicts = new Map();
|
|
207
|
+
/** Per `#/$defs/` pointer: null when its expansion never loops, else the loop. */
|
|
208
|
+
loops = new Map();
|
|
209
|
+
constructor(doc) {
|
|
210
|
+
this.doc = doc;
|
|
211
|
+
}
|
|
212
|
+
analyze(ref) {
|
|
213
|
+
let found = this.verdicts.get(ref);
|
|
214
|
+
if (!found) {
|
|
215
|
+
found = this.classify(ref);
|
|
216
|
+
this.verdicts.set(ref, found);
|
|
217
|
+
}
|
|
218
|
+
return found;
|
|
219
|
+
}
|
|
220
|
+
classify(ref) {
|
|
221
|
+
const family = REF_FAMILY_PREFIXES.find((prefix) => ref.startsWith(prefix) && ref.length > prefix.length);
|
|
222
|
+
if (family) {
|
|
223
|
+
return { verdict: "family", reason: `family-prefixed (${family}); it resolves from the shared-shapes release` };
|
|
224
|
+
}
|
|
225
|
+
if (ref === "#")
|
|
226
|
+
return { verdict: "inert", reason: "a ref to the document itself is a cycle" };
|
|
227
|
+
if (ref.startsWith("#/$defs/")) {
|
|
228
|
+
const target = resolveLocalPointer(this.doc, ref);
|
|
229
|
+
if (target === undefined)
|
|
230
|
+
return { verdict: "inert", reason: "a #/$defs/ pointer with no target in the document" };
|
|
231
|
+
if (!isPlainObject(target))
|
|
232
|
+
return { verdict: "inert", reason: "a #/$defs/ pointer whose target is not a schema object" };
|
|
233
|
+
const loop = this.loopFrom(ref);
|
|
234
|
+
if (loop)
|
|
235
|
+
return { verdict: "inert", reason: `a cycle: ${loop.join(" → ")}` };
|
|
236
|
+
return { verdict: "resolved", reason: "a #/$defs/ pointer whose target exists" };
|
|
237
|
+
}
|
|
238
|
+
if (ref.startsWith("#")) {
|
|
239
|
+
return {
|
|
240
|
+
verdict: "inert",
|
|
241
|
+
reason: resolveLocalPointer(this.doc, ref) === undefined
|
|
242
|
+
? "a local pointer outside #/$defs/ with no target"
|
|
243
|
+
: "a local pointer outside #/$defs/ (only #/$defs/ pointers resolve)",
|
|
244
|
+
};
|
|
245
|
+
}
|
|
246
|
+
if (/^[a-z][a-z0-9+.-]*:\/\//i.test(ref))
|
|
247
|
+
return { verdict: "inert", reason: "a remote URL, neither local nor family-prefixed" };
|
|
248
|
+
return { verdict: "inert", reason: "neither local nor family-prefixed" };
|
|
249
|
+
}
|
|
250
|
+
/**
|
|
251
|
+
* The ref chain that loops when `pointer` is expanded, or null. Expansion
|
|
252
|
+
* inlines the target and every `#/$defs/` ref inside it, so a recursive
|
|
253
|
+
* definition loops as surely as `A → B → A` does.
|
|
254
|
+
*
|
|
255
|
+
* A depth-first walk with its own stack rather than the call stack, so a
|
|
256
|
+
* long chain of definitions cannot exhaust it.
|
|
257
|
+
*/
|
|
258
|
+
loopFrom(start) {
|
|
259
|
+
const frames = [];
|
|
260
|
+
/** Pointer → its frame's index, while the frame is open. */
|
|
261
|
+
const onStack = new Map();
|
|
262
|
+
/** A known answer for `pointer`, or undefined once a frame is opened for it. */
|
|
263
|
+
const open = (pointer) => {
|
|
264
|
+
const at = onStack.get(pointer);
|
|
265
|
+
if (at !== undefined)
|
|
266
|
+
return [...frames.slice(at).map((frame) => frame.pointer), pointer];
|
|
267
|
+
if (this.loops.has(pointer))
|
|
268
|
+
return this.loops.get(pointer);
|
|
269
|
+
const inner = [];
|
|
270
|
+
eachRef(resolveLocalPointer(this.doc, pointer), (ref) => inner.push(ref));
|
|
271
|
+
onStack.set(pointer, frames.length);
|
|
272
|
+
frames.push({ pointer, inner, next: 0 });
|
|
273
|
+
return undefined;
|
|
274
|
+
};
|
|
275
|
+
const close = (loop) => {
|
|
276
|
+
const frame = frames.pop();
|
|
277
|
+
onStack.delete(frame.pointer);
|
|
278
|
+
this.loops.set(frame.pointer, loop);
|
|
279
|
+
};
|
|
280
|
+
// The answer the frame below the top is waiting for; undefined while it scans.
|
|
281
|
+
let answer = open(start);
|
|
282
|
+
while (frames.length > 0) {
|
|
283
|
+
const frame = frames[frames.length - 1];
|
|
284
|
+
if (answer === undefined) {
|
|
285
|
+
let loop = null;
|
|
286
|
+
let descended = false;
|
|
287
|
+
while (frame.next < frame.inner.length) {
|
|
288
|
+
const ref = frame.inner[frame.next++];
|
|
289
|
+
if (ref === "#") {
|
|
290
|
+
loop = [frame.pointer, ref];
|
|
291
|
+
break;
|
|
292
|
+
}
|
|
293
|
+
if (!ref.startsWith("#/$defs/") || resolveLocalPointer(this.doc, ref) === undefined)
|
|
294
|
+
continue;
|
|
295
|
+
const found = open(ref);
|
|
296
|
+
if (found === undefined) {
|
|
297
|
+
descended = true;
|
|
298
|
+
break;
|
|
299
|
+
}
|
|
300
|
+
if (found) {
|
|
301
|
+
loop = found;
|
|
302
|
+
break;
|
|
303
|
+
}
|
|
304
|
+
}
|
|
305
|
+
if (descended)
|
|
306
|
+
continue;
|
|
307
|
+
close(loop);
|
|
308
|
+
answer = loop;
|
|
309
|
+
}
|
|
310
|
+
else if (answer) {
|
|
311
|
+
close(answer);
|
|
312
|
+
}
|
|
313
|
+
else {
|
|
314
|
+
answer = undefined;
|
|
315
|
+
}
|
|
316
|
+
}
|
|
317
|
+
return answer ?? null;
|
|
318
|
+
}
|
|
319
|
+
}
|
|
320
|
+
/** Every `$ref` in `schema`, in document order (inside `$defs` too), with what a compile does with it. */
|
|
321
|
+
export function classifySchemaRefs(schema) {
|
|
322
|
+
const analyzer = new RefAnalyzer(schema);
|
|
323
|
+
const found = [];
|
|
324
|
+
eachRef(schema, (ref, pointer, path) => found.push({ path, pointer, ref, ...analyzer.analyze(ref) }));
|
|
325
|
+
return found;
|
|
326
|
+
}
|
|
327
|
+
// ── Shared refs ──────────────────────────────────────────────────────
|
|
328
|
+
/** What a `schemas/` file stem may be. */
|
|
329
|
+
const FILE_STEM = /^[a-z0-9_-]{1,64}$/;
|
|
330
|
+
const STEM_RULE = "a file name is 1-64 characters of a-z, 0-9, '_' or '-'";
|
|
331
|
+
/** What a prompt or function key may be, as a ref spells it. */
|
|
332
|
+
const FAMILY_KEY = /^[A-Za-z0-9_-]{1,64}$/;
|
|
333
|
+
/** What a db3 type name may be, as a ref spells it: what `PUT db3-types/:name` takes, any non-empty name without '#' (#5540). */
|
|
334
|
+
const DB3_TYPE_NAME = /^[^#]+$/;
|
|
335
|
+
/** Why a prompt or function ref does not resolve where no prompt or function slot is given (#5534, DSO-5534-001). */
|
|
336
|
+
const NO_PROMPT_OR_FUNCTION_SLOT = "prompt and function refs resolve from prompt and agent schemas; a function schema or a schemas/ def cannot ref a prompt or function in this release";
|
|
337
|
+
/** The four kinds of prompt target, for a ref that names none of them. */
|
|
338
|
+
const PROMPT_TARGET_KINDS = "a prompt ref names input, output, tools.<name>.input|output or events.<kind>";
|
|
339
|
+
const EVERY_DOLLAR_FAMILY = { prompt: true, fn: true, db3: true };
|
|
340
|
+
/** A pointer segment, unescaped (RFC 6901). */
|
|
341
|
+
function unescapeSegment(segment) {
|
|
342
|
+
return segment.replace(/~1/g, "/").replace(/~0/g, "~");
|
|
343
|
+
}
|
|
344
|
+
/** A `db3:<type>#/$defs/<model>[/<projection>]` `$ref` (#5540). */
|
|
345
|
+
function db3DollarRef(ref) {
|
|
346
|
+
const rest = ref.slice("db3:".length);
|
|
347
|
+
const hash = rest.indexOf("#");
|
|
348
|
+
const type = hash < 0 ? rest : rest.slice(0, hash);
|
|
349
|
+
if (!DB3_TYPE_NAME.test(type))
|
|
350
|
+
return { kind: "malformed", reason: `${JSON.stringify(type)} is not a db3 type name`, db3: true, explicit: true };
|
|
351
|
+
const fragment = hash < 0 ? "" : rest.slice(hash + 1);
|
|
352
|
+
const segments = fragment.startsWith("/$defs/") ? fragment.slice("/$defs/".length).split("/") : [];
|
|
353
|
+
if (segments.length === 0 || segments[0] === "") {
|
|
354
|
+
return { kind: "malformed", reason: 'a db3: ref names a model, "db3:<type>#/$defs/<model>"', db3: true, explicit: true };
|
|
355
|
+
}
|
|
356
|
+
if (segments.length > 2)
|
|
357
|
+
return { kind: "malformed", reason: "it points below a model; a db3 ref names a whole model", db3: true, explicit: true };
|
|
358
|
+
const model = unescapeSegment(segments[0]);
|
|
359
|
+
return segments.length === 2 ? { kind: "db3", type, model, projection: segments[1], explicit: true } : { kind: "db3", type, model, explicit: true };
|
|
360
|
+
}
|
|
361
|
+
/** The target path of a `prompt:` or `fn:` fragment (`#/$defs/<path>`), or null when it is not one. */
|
|
362
|
+
function definitionPath(fragment) {
|
|
363
|
+
if (!fragment.startsWith("/$defs/"))
|
|
364
|
+
return null;
|
|
365
|
+
const path = fragment.slice("/$defs/".length);
|
|
366
|
+
return path === "" ? null : path.split("/").map((segment) => segment.replace(/~1/g, "/").replace(/~0/g, "~")).join("/");
|
|
367
|
+
}
|
|
368
|
+
/**
|
|
369
|
+
* A `schemas:` or `platform:` `$ref` (and, where `families` allows, a
|
|
370
|
+
* `prompt:` or `fn:` one), or null for one this compile leaves to the local
|
|
371
|
+
* rules.
|
|
372
|
+
*/
|
|
373
|
+
function sharedDollarRef(ref, families = { prompt: false, fn: false }) {
|
|
374
|
+
if (ref.startsWith("platform:"))
|
|
375
|
+
return { kind: "reserved" };
|
|
376
|
+
if (ref.startsWith("db3:") && families.db3 && ref.length > "db3:".length)
|
|
377
|
+
return db3DollarRef(ref);
|
|
378
|
+
for (const [prefix, family] of [["prompt:", "prompt"], ["fn:", "fn"]]) {
|
|
379
|
+
if (!ref.startsWith(prefix) || !families[family] || ref.length === prefix.length)
|
|
380
|
+
continue;
|
|
381
|
+
const rest = ref.slice(prefix.length);
|
|
382
|
+
const hash = rest.indexOf("#");
|
|
383
|
+
const key = hash < 0 ? rest : rest.slice(0, hash);
|
|
384
|
+
const form = family === "prompt" ? '"prompt:<key>#/$defs/<target>"' : '"fn:<key>#/$defs/input" or "fn:<key>#/$defs/output"';
|
|
385
|
+
if (!FAMILY_KEY.test(key))
|
|
386
|
+
return { kind: "malformed", reason: `${JSON.stringify(key)} is not a ${family === "prompt" ? "prompt" : "function"} key` };
|
|
387
|
+
const path = hash < 0 ? null : definitionPath(rest.slice(hash + 1));
|
|
388
|
+
if (path === null)
|
|
389
|
+
return { kind: "malformed", reason: `a ${prefix} ref names ${form}` };
|
|
390
|
+
return family === "prompt" ? { kind: "prompt", key, target: path } : { kind: "fn", key, part: path };
|
|
391
|
+
}
|
|
392
|
+
if (!ref.startsWith("schemas:"))
|
|
393
|
+
return null;
|
|
394
|
+
const rest = ref.slice("schemas:".length);
|
|
395
|
+
const hash = rest.indexOf("#");
|
|
396
|
+
const file = hash < 0 ? rest : rest.slice(0, hash);
|
|
397
|
+
if (!FILE_STEM.test(file))
|
|
398
|
+
return { kind: "malformed", reason: `${JSON.stringify(file)} is not a schemas/ file name (${STEM_RULE})` };
|
|
399
|
+
const fragment = hash < 0 ? "" : rest.slice(hash + 1);
|
|
400
|
+
const segments = fragment.startsWith("/$defs/") ? fragment.slice("/$defs/".length).split("/") : [];
|
|
401
|
+
if (segments.length !== 1 || segments[0] === "") {
|
|
402
|
+
return {
|
|
403
|
+
kind: "malformed",
|
|
404
|
+
reason: segments.length > 1
|
|
405
|
+
? 'it points below a def; a schemas: ref names a whole def, "schemas:<file>#/$defs/<Name>". Give the part its own def and ref that'
|
|
406
|
+
: 'a schemas: ref names a whole def, "schemas:<file>#/$defs/<Name>"',
|
|
407
|
+
};
|
|
408
|
+
}
|
|
409
|
+
return { kind: "schemas", file, def: segments[0].replace(/~1/g, "/").replace(/~0/g, "~") };
|
|
410
|
+
}
|
|
411
|
+
/** A `ref` keyword's value, read as one of the ref forms, with its `#…` projection suffix. */
|
|
412
|
+
function sharedRefKeyword(value) {
|
|
413
|
+
if (typeof value !== "string")
|
|
414
|
+
return { kind: "malformed", reason: 'ref must be a string naming a shared def: "<Name>", "<file>.<Name>" or "schemas.<file>.<Name>"' };
|
|
415
|
+
const hash = value.indexOf("#");
|
|
416
|
+
if (hash < 0)
|
|
417
|
+
return refForm(value);
|
|
418
|
+
const ref = refForm(value.slice(0, hash));
|
|
419
|
+
return ref.kind === "reserved" ? ref : { ...ref, projection: value.slice(hash + 1) };
|
|
420
|
+
}
|
|
421
|
+
/** A `ref` keyword's value without its projection suffix, read as one of the ref forms. */
|
|
422
|
+
function refForm(value) {
|
|
423
|
+
const parts = value.split(".");
|
|
424
|
+
const notARef = { kind: "malformed", reason: 'it is not a ref. Write "<Name>", "<file>.<Name>" or "schemas.<file>.<Name>"' };
|
|
425
|
+
if (parts.some((part) => part === ""))
|
|
426
|
+
return notARef;
|
|
427
|
+
if (parts[0] === "platform" && parts.length > 1)
|
|
428
|
+
return { kind: "reserved" };
|
|
429
|
+
if (parts.length === 1)
|
|
430
|
+
return { kind: "bare", name: parts[0] };
|
|
431
|
+
if (parts.length === 2)
|
|
432
|
+
return { kind: "pair", key: parts[0], part: parts[1] };
|
|
433
|
+
if (parts[0] === "schemas") {
|
|
434
|
+
if (parts.length > 3)
|
|
435
|
+
return { kind: "malformed", reason: 'a long ref names a whole def, "schemas.<file>.<Name>"' };
|
|
436
|
+
if (!FILE_STEM.test(parts[1]))
|
|
437
|
+
return { kind: "malformed", reason: `${JSON.stringify(parts[1])} is not a schemas/ file name (${STEM_RULE})` };
|
|
438
|
+
return { kind: "schemas", file: parts[1], def: parts[2] };
|
|
439
|
+
}
|
|
440
|
+
if (parts[0] === "prompt") {
|
|
441
|
+
if (!FAMILY_KEY.test(parts[1]))
|
|
442
|
+
return { kind: "malformed", reason: `${JSON.stringify(parts[1])} is not a prompt key` };
|
|
443
|
+
return { kind: "prompt", key: parts[1], target: parts.slice(2).join("/") };
|
|
444
|
+
}
|
|
445
|
+
if (parts[0] === "fn") {
|
|
446
|
+
if (!FAMILY_KEY.test(parts[1]))
|
|
447
|
+
return { kind: "malformed", reason: `${JSON.stringify(parts[1])} is not a function key` };
|
|
448
|
+
if (parts.length !== 3)
|
|
449
|
+
return { kind: "malformed", reason: 'a function ref names "fn.<key>.input" or "fn.<key>.output"' };
|
|
450
|
+
return { kind: "fn", key: parts[1], part: parts[2] };
|
|
451
|
+
}
|
|
452
|
+
if (parts[0] === "db3") {
|
|
453
|
+
if (!DB3_TYPE_NAME.test(parts[1]))
|
|
454
|
+
return { kind: "malformed", reason: `${JSON.stringify(parts[1])} is not a db3 type name`, db3: true };
|
|
455
|
+
if (parts.length > 3)
|
|
456
|
+
return { kind: "malformed", reason: 'it points below a model; a db3 ref names a whole model, "db3.<type>.<model>"', db3: true };
|
|
457
|
+
return { kind: "db3", type: parts[1], model: parts[2] };
|
|
458
|
+
}
|
|
459
|
+
return notARef;
|
|
460
|
+
}
|
|
461
|
+
const FAMILY_NAMES = { fn: "function", prompt: "prompt" };
|
|
462
|
+
function unresolved(reason) {
|
|
463
|
+
return { ok: false, code: FUNCTION_SCHEMA_REF_UNRESOLVED, reason };
|
|
464
|
+
}
|
|
465
|
+
/** A def's explicit spelling: `schemas:<file>#/$defs/<Name>`. */
|
|
466
|
+
function explicitRef(file, def) {
|
|
467
|
+
return `schemas:${file}#/$defs/${pointerSegment(def)}`;
|
|
468
|
+
}
|
|
469
|
+
/** The def `file` declares as `def`, by the index's view of the file. */
|
|
470
|
+
function resolveInFile(index, file, def) {
|
|
471
|
+
const entry = index.files.get(file);
|
|
472
|
+
if (!entry)
|
|
473
|
+
return unresolved(`it names schemas/${file}.toml, which does not exist. Add schemas/${file}.toml, or fix the file name`);
|
|
474
|
+
if (entry.error)
|
|
475
|
+
return unresolved(`it names schemas/${file}.toml, which cannot be compiled: ${entry.error}`);
|
|
476
|
+
if (entry.tombstone) {
|
|
477
|
+
return {
|
|
478
|
+
ok: false,
|
|
479
|
+
code: FUNCTION_SCHEMA_REF_TOMBSTONED,
|
|
480
|
+
reason: `it names schemas/${file}.toml, which was deleted (tombstone version ${entry.version ?? "?"}). ` +
|
|
481
|
+
"New compiles cannot reference a deleted file; versions already pushed keep the snapshot they inlined. " +
|
|
482
|
+
"Restore the file, or ref a def in another file",
|
|
483
|
+
};
|
|
484
|
+
}
|
|
485
|
+
if (!entry.names.includes(def)) {
|
|
486
|
+
const declared = entry.names.length > 0 ? ` (it declares ${entry.names.join(", ")})` : "";
|
|
487
|
+
return unresolved(`schemas/${file}.toml declares no def ${JSON.stringify(def)}${declared}. Fix the name, or add [defs.${def}] to schemas/${file}.toml`);
|
|
488
|
+
}
|
|
489
|
+
return { ok: true, family: "schemas", file, def, entry, explicit: explicitRef(file, def) };
|
|
490
|
+
}
|
|
491
|
+
/** Why `target` is not a prompt target path, or null when it is one. */
|
|
492
|
+
function promptTargetError(target) {
|
|
493
|
+
const segments = target.split("/");
|
|
494
|
+
if (segments.length === 1 && (segments[0] === "input" || segments[0] === "output"))
|
|
495
|
+
return null;
|
|
496
|
+
if (segments.length === 3 && segments[0] === "tools" && segments[1] !== "" && (segments[2] === "input" || segments[2] === "output"))
|
|
497
|
+
return null;
|
|
498
|
+
if (segments.length === 2 && segments[0] === "events" && segments[1] !== "")
|
|
499
|
+
return null;
|
|
500
|
+
return `${PROMPT_TARGET_KINDS}; ${JSON.stringify(target.replace(/\//g, "."))} is none of them`;
|
|
501
|
+
}
|
|
502
|
+
/** A prompt or function seen as a file, so its targets inline and rebase as a def's do. */
|
|
503
|
+
const promptEntries = new WeakMap();
|
|
504
|
+
const functionEntries = new WeakMap();
|
|
505
|
+
function promptEntryOf(prompt) {
|
|
506
|
+
let entry = promptEntries.get(prompt);
|
|
507
|
+
if (!entry) {
|
|
508
|
+
const defs = {};
|
|
509
|
+
for (const [target, schema] of prompt.targets)
|
|
510
|
+
Object.defineProperty(defs, target, { value: schema, enumerable: true, writable: true, configurable: true });
|
|
511
|
+
entry = { names: [...prompt.targets.keys()], defs, provenance: prompt.provenance ?? null, ...(prompt.resolved ? { resolved: prompt.resolved } : {}) };
|
|
512
|
+
promptEntries.set(prompt, entry);
|
|
513
|
+
}
|
|
514
|
+
return entry;
|
|
515
|
+
}
|
|
516
|
+
function functionEntryOf(fn) {
|
|
517
|
+
let entry = functionEntries.get(fn);
|
|
518
|
+
if (!entry) {
|
|
519
|
+
const defs = {};
|
|
520
|
+
if (fn.input !== undefined)
|
|
521
|
+
defs.input = fn.input;
|
|
522
|
+
if (fn.output !== undefined)
|
|
523
|
+
defs.output = fn.output;
|
|
524
|
+
entry = { names: Object.keys(defs), defs, provenance: null };
|
|
525
|
+
functionEntries.set(fn, entry);
|
|
526
|
+
}
|
|
527
|
+
return entry;
|
|
528
|
+
}
|
|
529
|
+
/** The schema prompt `key` declares at `target`, by the index's view of the prompt. */
|
|
530
|
+
function resolveInPrompt(index, key, target) {
|
|
531
|
+
if (!index.prompts)
|
|
532
|
+
return unresolved(NO_PROMPT_OR_FUNCTION_SLOT);
|
|
533
|
+
const shape = promptTargetError(target);
|
|
534
|
+
if (shape)
|
|
535
|
+
return unresolved(shape);
|
|
536
|
+
const prompt = index.prompts.get(key);
|
|
537
|
+
if (!prompt)
|
|
538
|
+
return unresolved(`it names prompt ${key}, which this app does not have. Push prompts/${key}.toml first, or fix the key`);
|
|
539
|
+
if (prompt.error)
|
|
540
|
+
return unresolved(`it names prompt ${key}, which cannot be compiled: ${prompt.error}`);
|
|
541
|
+
if (prompt.tombstone) {
|
|
542
|
+
return {
|
|
543
|
+
ok: false,
|
|
544
|
+
code: FUNCTION_SCHEMA_REF_TOMBSTONED,
|
|
545
|
+
reason: `it names prompt ${key}, which is archived. New compiles cannot reference an archived prompt; ` +
|
|
546
|
+
"versions already pushed keep the snapshot they inlined. Restore the prompt, or ref another",
|
|
547
|
+
};
|
|
548
|
+
}
|
|
549
|
+
const long = target.replace(/\//g, ".");
|
|
550
|
+
const why = prompt.unresolvedTargets?.get(target);
|
|
551
|
+
if (why !== undefined)
|
|
552
|
+
return unresolved(`prompt ${key} cannot answer ${long}: ${why}`);
|
|
553
|
+
const schema = prompt.targets.get(target);
|
|
554
|
+
if (!prompt.targets.has(target)) {
|
|
555
|
+
const declared = [...prompt.targets.keys(), ...(prompt.unresolvedTargets?.keys() ?? [])].map((found) => found.replace(/\//g, "."));
|
|
556
|
+
return unresolved(`prompt ${key} declares no ${long} (${declared.length > 0 ? `it declares ${declared.join(", ")}` : "it declares nothing a ref can name"})`);
|
|
557
|
+
}
|
|
558
|
+
if (!isPlainObject(schema))
|
|
559
|
+
return unresolved(`prompt ${key}'s stored ${long} is not a JSON Schema object`);
|
|
560
|
+
return { ok: true, family: "prompt", file: key, def: target, entry: promptEntryOf(prompt), explicit: `prompt:${key}#/$defs/${target}` };
|
|
561
|
+
}
|
|
562
|
+
/** The schema function `key` declares as `part`, by the index's view of the function. */
|
|
563
|
+
function resolveInFunction(index, key, part) {
|
|
564
|
+
if (!index.functions)
|
|
565
|
+
return unresolved(NO_PROMPT_OR_FUNCTION_SLOT);
|
|
566
|
+
if (part !== "input" && part !== "output")
|
|
567
|
+
return unresolved(`a function ref names "fn.<key>.input" or "fn.<key>.output"; ${JSON.stringify(part)} is neither`);
|
|
568
|
+
const fn = index.functions.get(key);
|
|
569
|
+
if (!fn)
|
|
570
|
+
return unresolved(`it names function ${key}, which this app does not have. Push functions/${key}.toml first, or fix the key`);
|
|
571
|
+
if (fn.error)
|
|
572
|
+
return unresolved(`it names function ${key}, which cannot be compiled: ${fn.error}`);
|
|
573
|
+
if (fn.tombstone) {
|
|
574
|
+
return {
|
|
575
|
+
ok: false,
|
|
576
|
+
code: FUNCTION_SCHEMA_REF_TOMBSTONED,
|
|
577
|
+
reason: `it names function ${key}, which is archived. New compiles cannot reference an archived function; ` +
|
|
578
|
+
"versions already pushed keep the snapshot they inlined. Restore the function, or ref another",
|
|
579
|
+
};
|
|
580
|
+
}
|
|
581
|
+
const schema = part === "input" ? fn.input : fn.output;
|
|
582
|
+
const field = part === "input" ? "inputSchema" : "outputSchema";
|
|
583
|
+
if (schema === undefined || schema === null)
|
|
584
|
+
return unresolved(`function ${key} declares no ${field}`);
|
|
585
|
+
if (!isPlainObject(schema))
|
|
586
|
+
return unresolved(`function ${key}'s stored ${field} is not a JSON Schema object`);
|
|
587
|
+
return { ok: true, family: "fn", file: key, def: part, entry: functionEntryOf(fn), explicit: `fn:${key}#/$defs/${part}` };
|
|
588
|
+
}
|
|
589
|
+
/** A db3 type seen as a file, so its projections inline as a def's do. */
|
|
590
|
+
const db3Entries = new WeakMap();
|
|
591
|
+
function db3EntryOf(type) {
|
|
592
|
+
let entry = db3Entries.get(type);
|
|
593
|
+
if (!entry) {
|
|
594
|
+
entry = { names: Object.keys(type.defs), defs: type.defs, provenance: null };
|
|
595
|
+
db3Entries.set(type, entry);
|
|
596
|
+
}
|
|
597
|
+
return entry;
|
|
598
|
+
}
|
|
599
|
+
const isProjection = (value) => DB3_PROJECTIONS.includes(value);
|
|
600
|
+
/**
|
|
601
|
+
* The projection a db3 ref resolves to and how it was chosen, in words: the
|
|
602
|
+
* one written, or the position's default (none in a definition).
|
|
603
|
+
*/
|
|
604
|
+
function projectionNote(projection, explicit, position) {
|
|
605
|
+
if (isProjection(projection))
|
|
606
|
+
return `${projection} projection, named by ${explicit ? "/" : "#"}${projection}`;
|
|
607
|
+
if (position === "output")
|
|
608
|
+
return "row projection, the default for an output schema";
|
|
609
|
+
if (position === "input")
|
|
610
|
+
return "declared projection, the default for an input schema";
|
|
611
|
+
return "no projection: a schemas/ def names one";
|
|
612
|
+
}
|
|
613
|
+
/** Why a projection suffix on a ref that is not a db3 ref is refused. */
|
|
614
|
+
const PROJECTION_NOT_DB3 = "a projection (#row, #declared, /row, /declared) belongs to a db3 ref only";
|
|
615
|
+
/** The projection `type`'s `model` resolves to, by the index's db3 slot (#5540). */
|
|
616
|
+
function resolveInDb3(index, type, model, projection, explicit, position) {
|
|
617
|
+
const note = projectionNote(projection, explicit, position);
|
|
618
|
+
const fail = (reason) => ({ ok: false, code: FUNCTION_SCHEMA_REF_UNRESOLVED, reason, note });
|
|
619
|
+
if (projection !== undefined && !isProjection(projection)) {
|
|
620
|
+
return fail(`${projection} is not a projection; write ${explicit ? "/row or /declared" : "#row or #declared"}`);
|
|
621
|
+
}
|
|
622
|
+
if (!index.db3)
|
|
623
|
+
return fail("db3 refs resolve where the index has a db3 slot");
|
|
624
|
+
const entry = index.db3.get(type);
|
|
625
|
+
if (!entry)
|
|
626
|
+
return fail(`it names db3 type ${type}, which this app does not have. Push db3-types/${type}.toml first, or fix the key`);
|
|
627
|
+
if (entry.error)
|
|
628
|
+
return fail(`db3 type ${type} cannot be bridged: ${entry.error}`);
|
|
629
|
+
if (!entry.models.includes(model)) {
|
|
630
|
+
return fail(`db3 type ${type} declares no model ${model} (${entry.models.length > 0 ? `it declares ${entry.models.join(", ")}` : "it declares no models"})`);
|
|
631
|
+
}
|
|
632
|
+
if (entry.modelErrors && Object.prototype.hasOwnProperty.call(entry.modelErrors, model)) {
|
|
633
|
+
return fail(`model ${model} of db3 type ${type} cannot be bridged: ${entry.modelErrors[model]}`);
|
|
634
|
+
}
|
|
635
|
+
const chosen = isProjection(projection) ? projection : position === "output" ? "row" : position === "input" ? "declared" : null;
|
|
636
|
+
if (!chosen)
|
|
637
|
+
return fail(`a db3 ref in a schemas/ def must name its projection: write db3.${type}.${model}#row or db3.${type}.${model}#declared`);
|
|
638
|
+
return {
|
|
639
|
+
ok: true,
|
|
640
|
+
family: "db3",
|
|
641
|
+
file: type,
|
|
642
|
+
def: `${model}/${chosen}`,
|
|
643
|
+
entry: db3EntryOf(entry),
|
|
644
|
+
explicit: `db3:${type}#/$defs/${pointerSegment(model)}/${chosen}`,
|
|
645
|
+
};
|
|
646
|
+
}
|
|
647
|
+
/** The families a `<key>.<part>` short form's key belongs to, each with its long form. */
|
|
648
|
+
function pairFamilies(index, ref) {
|
|
649
|
+
const keys = index.keys ?? { function: [], prompt: [], db3: [] };
|
|
650
|
+
const families = [];
|
|
651
|
+
if (keys.db3.includes(ref.key))
|
|
652
|
+
families.push({ family: "db3", long: `db3.${ref.key}.${ref.part}` });
|
|
653
|
+
if (keys.function.includes(ref.key))
|
|
654
|
+
families.push({ family: "fn", long: `fn.${ref.key}.${ref.part}` });
|
|
655
|
+
if (keys.prompt.includes(ref.key))
|
|
656
|
+
families.push({ family: "prompt", long: `prompt.${ref.key}.${ref.part}` });
|
|
657
|
+
if (index.files.has(ref.key))
|
|
658
|
+
families.push({ family: "schemas", long: `schemas.${ref.key}.${ref.part}` });
|
|
659
|
+
return families;
|
|
660
|
+
}
|
|
661
|
+
/** Resolve a parsed shared ref at `position`. Never called for `reserved`. */
|
|
662
|
+
function resolveShared(index, ref, position = "input") {
|
|
663
|
+
const note = (explicit = false) => projectionNote(ref.projection, explicit, position);
|
|
664
|
+
const notDb3 = () => ({ ok: false, code: FUNCTION_SCHEMA_REF_UNRESOLVED, reason: PROJECTION_NOT_DB3, note: note() });
|
|
665
|
+
if (ref.projection !== undefined && (ref.kind === "schemas" || ref.kind === "prompt" || ref.kind === "fn" || ref.kind === "bare"))
|
|
666
|
+
return notDb3();
|
|
667
|
+
switch (ref.kind) {
|
|
668
|
+
case "malformed":
|
|
669
|
+
return ref.db3 || ref.projection !== undefined ? { ...unresolved(ref.reason), note: note(ref.explicit) } : unresolved(ref.reason);
|
|
670
|
+
case "db3":
|
|
671
|
+
return resolveInDb3(index, ref.type, ref.model, ref.projection, ref.explicit === true, position);
|
|
672
|
+
case "schemas":
|
|
673
|
+
return resolveInFile(index, ref.file, ref.def);
|
|
674
|
+
case "prompt":
|
|
675
|
+
return resolveInPrompt(index, ref.key, ref.target);
|
|
676
|
+
case "fn":
|
|
677
|
+
return resolveInFunction(index, ref.key, ref.part);
|
|
678
|
+
case "bare": {
|
|
679
|
+
const candidates = [...index.files.entries()]
|
|
680
|
+
.filter(([, entry]) => !entry.tombstone && !entry.error && entry.names.includes(ref.name))
|
|
681
|
+
.map(([file]) => file)
|
|
682
|
+
.sort();
|
|
683
|
+
if (candidates.length === 0)
|
|
684
|
+
return unresolved(`no schemas/ file declares ${ref.name}. Fix the name, or add [defs.${ref.name}] to a schemas/ file`);
|
|
685
|
+
if (candidates.length > 1) {
|
|
686
|
+
return {
|
|
687
|
+
ok: false,
|
|
688
|
+
code: FUNCTION_SCHEMA_REF_AMBIGUOUS,
|
|
689
|
+
reason: `more than one schemas/ file declares ${ref.name}. Use a long form: ${candidates.map((file) => `schemas.${file}.${ref.name}`).join(", ")}`,
|
|
690
|
+
};
|
|
691
|
+
}
|
|
692
|
+
return resolveInFile(index, candidates[0], ref.name);
|
|
693
|
+
}
|
|
694
|
+
case "pair": {
|
|
695
|
+
const families = pairFamilies(index, ref);
|
|
696
|
+
const named = ref.projection !== undefined || families.some((found) => found.family === "db3");
|
|
697
|
+
if (families.length > 1) {
|
|
698
|
+
return {
|
|
699
|
+
ok: false,
|
|
700
|
+
code: FUNCTION_SCHEMA_REF_AMBIGUOUS,
|
|
701
|
+
reason: `${ref.key} is a key in more than one family. Use a long form: ${families.map((found) => found.long).sort().join(", ")}`,
|
|
702
|
+
...(named ? { note: note() } : {}),
|
|
703
|
+
};
|
|
704
|
+
}
|
|
705
|
+
if (families.length === 0) {
|
|
706
|
+
const none = unresolved(FILE_STEM.test(ref.key)
|
|
707
|
+
? `no schemas/ file is named ${ref.key}, and no other family has that key. Fix the file name, or use "schemas.<file>.<Name>"`
|
|
708
|
+
: `${JSON.stringify(ref.key)} is not a schemas/ file name (${STEM_RULE}), and no other family has that key`);
|
|
709
|
+
return named ? { ...none, note: note() } : none;
|
|
710
|
+
}
|
|
711
|
+
const [only] = families;
|
|
712
|
+
if (only.family === "db3")
|
|
713
|
+
return resolveInDb3(index, ref.key, ref.part, ref.projection, false, position);
|
|
714
|
+
if (ref.projection !== undefined)
|
|
715
|
+
return notDb3();
|
|
716
|
+
if (only.family === "schemas")
|
|
717
|
+
return resolveInFile(index, ref.key, ref.part);
|
|
718
|
+
const slot = only.family === "prompt" ? index.prompts : index.functions;
|
|
719
|
+
if (!slot)
|
|
720
|
+
return unresolved(`${ref.key} is a ${FAMILY_NAMES[only.family]} key, not a schemas/ file; ${NO_PROMPT_OR_FUNCTION_SLOT}`);
|
|
721
|
+
if (ref.part !== "input" && ref.part !== "output") {
|
|
722
|
+
return unresolved(only.family === "prompt"
|
|
723
|
+
? `a short ref names a prompt's input or output; write the long form, prompt.${ref.key}.<target>, such as prompt.${ref.key}.tools.<name>.input or prompt.${ref.key}.events.<kind>`
|
|
724
|
+
: `a short ref names a function's input or output; write fn.${ref.key}.input or fn.${ref.key}.output`);
|
|
725
|
+
}
|
|
726
|
+
return only.family === "prompt" ? resolveInPrompt(index, ref.key, ref.part) : resolveInFunction(index, ref.key, ref.part);
|
|
727
|
+
}
|
|
728
|
+
}
|
|
729
|
+
}
|
|
730
|
+
/**
|
|
731
|
+
* Every ref to a shared def in a parsed document, in document order, with the
|
|
732
|
+
* file and def it names: explicit `schemas:` `$ref`s and `ref` long forms
|
|
733
|
+
* directly, short forms through `index` (a short form that does not resolve
|
|
734
|
+
* to exactly one file names nothing). This is how a push finds the files a
|
|
735
|
+
* document depends on, whichever spelling it uses: its selection closure, its
|
|
736
|
+
* order, the server's pre-read and its cycle walk.
|
|
737
|
+
*
|
|
738
|
+
* #5534 — the prompts and functions a document names are reported beside the
|
|
739
|
+
* files, the same way: long and explicit forms always, and a `<key>.input` or
|
|
740
|
+
* `<key>.output` short form whose key the index's keys give one family.
|
|
741
|
+
*
|
|
742
|
+
* @example
|
|
743
|
+
* schemaFamilyRefsIn({ properties: { p: { ref: "schemas.common.Money" } } }).edges;
|
|
744
|
+
* // → [{ pointer: "/properties/p", ref: "schemas.common.Money", file: "common", def: "Money" }]
|
|
745
|
+
*/
|
|
746
|
+
export function schemaFamilyRefsIn(document, index, options = {}) {
|
|
747
|
+
const edges = [];
|
|
748
|
+
const prompts = [];
|
|
749
|
+
const functions = [];
|
|
750
|
+
const db3 = [];
|
|
751
|
+
const db3Edge = (pointer, written, type, model, projection) => db3.push({ pointer, ref: written, type, model, projection: isProjection(projection) ? projection : null });
|
|
752
|
+
const shortKeys = new Set();
|
|
753
|
+
let shortForms = false;
|
|
754
|
+
let reserved = false;
|
|
755
|
+
const take = (pointer, written, ref) => {
|
|
756
|
+
switch (ref.kind) {
|
|
757
|
+
case "reserved":
|
|
758
|
+
reserved = true;
|
|
759
|
+
return;
|
|
760
|
+
case "schemas":
|
|
761
|
+
edges.push({ pointer, ref: written, file: ref.file, def: ref.def });
|
|
762
|
+
return;
|
|
763
|
+
case "prompt":
|
|
764
|
+
prompts.push({ pointer, ref: written, key: ref.key, target: ref.target });
|
|
765
|
+
return;
|
|
766
|
+
case "fn":
|
|
767
|
+
if (ref.part === "input" || ref.part === "output")
|
|
768
|
+
functions.push({ pointer, ref: written, key: ref.key, part: ref.part });
|
|
769
|
+
return;
|
|
770
|
+
case "db3":
|
|
771
|
+
db3Edge(pointer, written, ref.type, ref.model, ref.projection);
|
|
772
|
+
return;
|
|
773
|
+
case "bare":
|
|
774
|
+
case "pair":
|
|
775
|
+
break;
|
|
776
|
+
default:
|
|
777
|
+
return;
|
|
778
|
+
}
|
|
779
|
+
shortForms = true;
|
|
780
|
+
if (ref.kind === "pair")
|
|
781
|
+
shortKeys.add(ref.key);
|
|
782
|
+
if (!index)
|
|
783
|
+
return;
|
|
784
|
+
if (ref.kind === "pair") {
|
|
785
|
+
const families = pairFamilies(index, ref);
|
|
786
|
+
const io = ref.part === "input" || ref.part === "output";
|
|
787
|
+
if (families.length === 1 && families[0].family === "prompt") {
|
|
788
|
+
if (io)
|
|
789
|
+
prompts.push({ pointer, ref: written, key: ref.key, target: ref.part });
|
|
790
|
+
return;
|
|
791
|
+
}
|
|
792
|
+
if (families.length === 1 && families[0].family === "fn") {
|
|
793
|
+
if (io)
|
|
794
|
+
functions.push({ pointer, ref: written, key: ref.key, part: ref.part });
|
|
795
|
+
return;
|
|
796
|
+
}
|
|
797
|
+
if (families.length === 1 && families[0].family === "db3") {
|
|
798
|
+
db3Edge(pointer, written, ref.key, ref.part, ref.projection);
|
|
799
|
+
return;
|
|
800
|
+
}
|
|
801
|
+
}
|
|
802
|
+
const found = resolveShared(index, ref);
|
|
803
|
+
if (found.ok && found.family === "schemas")
|
|
804
|
+
edges.push({ pointer, ref: written, file: found.file, def: found.def });
|
|
805
|
+
};
|
|
806
|
+
// Last pushed is visited first, so entries are pushed in reverse.
|
|
807
|
+
const stack = [{ node: document, pointer: "" }];
|
|
808
|
+
while (stack.length > 0) {
|
|
809
|
+
const { node, pointer } = stack.pop();
|
|
810
|
+
if (Array.isArray(node)) {
|
|
811
|
+
for (let index = node.length - 1; index >= 0; index--)
|
|
812
|
+
stack.push({ node: node[index], pointer: `${pointer}/${index}` });
|
|
813
|
+
continue;
|
|
814
|
+
}
|
|
815
|
+
if (!isPlainObject(node))
|
|
816
|
+
continue;
|
|
817
|
+
if (typeof node.$ref === "string") {
|
|
818
|
+
const shared = sharedDollarRef(node.$ref, EVERY_DOLLAR_FAMILY);
|
|
819
|
+
if (shared)
|
|
820
|
+
take(pointer, node.$ref, shared);
|
|
821
|
+
}
|
|
822
|
+
if (typeof node.ref === "string" && Object.prototype.hasOwnProperty.call(node, "ref"))
|
|
823
|
+
take(pointer, node.ref, sharedRefKeyword(node.ref));
|
|
824
|
+
if (options.schemaPositions) {
|
|
825
|
+
const children = subschemas(node, true);
|
|
826
|
+
for (let index = children.length - 1; index >= 0; index--)
|
|
827
|
+
stack.push({ node: children[index].child, pointer: `${pointer}${children[index].pointer}` });
|
|
828
|
+
continue;
|
|
829
|
+
}
|
|
830
|
+
const entries = Object.entries(node);
|
|
831
|
+
for (let index = entries.length - 1; index >= 0; index--) {
|
|
832
|
+
const [key, child] = entries[index];
|
|
833
|
+
if (child !== null && typeof child === "object")
|
|
834
|
+
stack.push({ node: child, pointer: `${pointer}/${pointerSegment(key)}` });
|
|
835
|
+
}
|
|
836
|
+
}
|
|
837
|
+
return { edges, prompts, functions, db3, shortForms, shortKeys: [...shortKeys].sort(), reserved };
|
|
838
|
+
}
|
|
839
|
+
/** A shared ref the compile could not resolve, and where. */
|
|
840
|
+
class SharedRefRefusal extends Error {
|
|
841
|
+
code;
|
|
842
|
+
pointer;
|
|
843
|
+
display;
|
|
844
|
+
reason;
|
|
845
|
+
chain;
|
|
846
|
+
constructor(code, pointer, display, reason, chain) {
|
|
847
|
+
super(reason);
|
|
848
|
+
this.code = code;
|
|
849
|
+
this.pointer = pointer;
|
|
850
|
+
this.display = display;
|
|
851
|
+
this.reason = reason;
|
|
852
|
+
this.chain = chain;
|
|
853
|
+
}
|
|
854
|
+
}
|
|
855
|
+
// ── Compiling ────────────────────────────────────────────────────────
|
|
856
|
+
/** May `key` sit beside a resolved `$ref`? Annotations, unknown keys and `nullable`. */
|
|
857
|
+
function allowedSibling(key) {
|
|
858
|
+
if (key === "nullable")
|
|
859
|
+
return true;
|
|
860
|
+
if (!Object.prototype.hasOwnProperty.call(SCHEMA_KEYWORDS, key))
|
|
861
|
+
return true;
|
|
862
|
+
return SCHEMA_KEYWORDS[key].class === "annotation";
|
|
863
|
+
}
|
|
864
|
+
/** What may sit beside a `ref`: the def replaces the node, so only these three (intent, Decisions). */
|
|
865
|
+
const REF_SIBLINGS = new Set(["description", "required", "nullable"]);
|
|
866
|
+
class SiblingRefusal extends Error {
|
|
867
|
+
pointer;
|
|
868
|
+
key;
|
|
869
|
+
ref;
|
|
870
|
+
kind;
|
|
871
|
+
constructor(pointer, key, ref,
|
|
872
|
+
/**
|
|
873
|
+
* `dollar`: beside a `$ref`. `ref`: beside a `ref`. `required`: `required = true` beside a `ref`.
|
|
874
|
+
* `both`: a `$ref` and a `ref` together. `marker`: a `$comment` beside a `$ref` that resolves, directly or
|
|
875
|
+
* through aliases, to a db3 projection, which would replace the projection's marker.
|
|
876
|
+
*/
|
|
877
|
+
kind = "dollar") {
|
|
878
|
+
super(key);
|
|
879
|
+
this.pointer = pointer;
|
|
880
|
+
this.key = key;
|
|
881
|
+
this.ref = ref;
|
|
882
|
+
this.kind = kind;
|
|
883
|
+
}
|
|
884
|
+
}
|
|
885
|
+
/** The compile built enough inlined keys that the expansion is surely over the byte cap. */
|
|
886
|
+
class BuildBudgetRefusal extends Error {
|
|
887
|
+
pointer;
|
|
888
|
+
chain;
|
|
889
|
+
constructor(pointer, chain) {
|
|
890
|
+
super(pointer);
|
|
891
|
+
this.pointer = pointer;
|
|
892
|
+
this.chain = chain;
|
|
893
|
+
}
|
|
894
|
+
}
|
|
895
|
+
/** How the compile treats the value of `key`: a map, a list or one subschema, or as written. */
|
|
896
|
+
function childKind(key, value) {
|
|
897
|
+
if (SUBSCHEMA_MAPS.has(key) && isPlainObject(value))
|
|
898
|
+
return "map";
|
|
899
|
+
if (SUBSCHEMA_LIST.has(key) && Array.isArray(value))
|
|
900
|
+
return "list";
|
|
901
|
+
if (SUBSCHEMA_ONE.has(key) && isPlainObject(value))
|
|
902
|
+
return "one";
|
|
903
|
+
return "keep";
|
|
904
|
+
}
|
|
905
|
+
/**
|
|
906
|
+
* One compile's state. Compiled nodes are shared: a definition used twice is
|
|
907
|
+
* compiled once and referenced from both places, so an expansion is measured
|
|
908
|
+
* before it is ever built out.
|
|
909
|
+
*
|
|
910
|
+
* The walk keeps its own work list rather than recursing, and a definition
|
|
911
|
+
* that is only a ref to another (an alias) is followed in a loop, so neither
|
|
912
|
+
* a deep expansion nor a long alias chain can exhaust the call stack. A run of
|
|
913
|
+
* aliases builds only the node it is inlined at; the aliases inside it are
|
|
914
|
+
* built only if something else refs them, so a long run of annotated aliases
|
|
915
|
+
* costs memory in proportion to what the compiled document holds.
|
|
916
|
+
*
|
|
917
|
+
* A shared def from the family index ends a run: it is the run's base as
|
|
918
|
+
* stored, never compiled here (`opaque`), and the node built over it is marked
|
|
919
|
+
* (`sharedContent`) so nothing inside it is reported or counted as a local ref.
|
|
920
|
+
*/
|
|
921
|
+
class Compiler {
|
|
922
|
+
doc;
|
|
923
|
+
keyBudget;
|
|
924
|
+
families;
|
|
925
|
+
position;
|
|
926
|
+
analyzer;
|
|
927
|
+
/** Original node → its compiled form. */
|
|
928
|
+
compiled = new WeakMap();
|
|
929
|
+
/** An alias inside a run, not built yet → its place in the run. */
|
|
930
|
+
pending = new WeakMap();
|
|
931
|
+
/** Inlined node → the part of a run inlined there. */
|
|
932
|
+
links = new WeakMap();
|
|
933
|
+
chains = new WeakMap();
|
|
934
|
+
chainDefinitions = new WeakMap();
|
|
935
|
+
/** A run's alias not built into the document, merged only to be hashed. */
|
|
936
|
+
transient = new WeakMap();
|
|
937
|
+
/** Ref node → the ref as it resolved (a shared ref in its explicit form). */
|
|
938
|
+
refTexts = new WeakMap();
|
|
939
|
+
/** Ref node → the shared def it resolved to. */
|
|
940
|
+
sharedTargets = new WeakMap();
|
|
941
|
+
/** The shared defs inlined from the index: copied whole, never compiled. */
|
|
942
|
+
opaque = new WeakSet();
|
|
943
|
+
/** Inlined nodes holding a shared def's content. */
|
|
944
|
+
sharedContent = new WeakSet();
|
|
945
|
+
/** Keys written into inlined nodes so far. */
|
|
946
|
+
built = 0;
|
|
947
|
+
inlined = false;
|
|
948
|
+
/**
|
|
949
|
+
* @param keyBudget The most keys inlined nodes may hold together. Each key
|
|
950
|
+
* is at least 4 bytes of the expanded document (`"":0`), and an inlined node
|
|
951
|
+
* built only to be another's target is copied whole into one the document
|
|
952
|
+
* holds, so a budget of half the byte cap is passed only by an expansion
|
|
953
|
+
* that is over the cap.
|
|
954
|
+
*/
|
|
955
|
+
constructor(doc, keyBudget, families = null, position = "input") {
|
|
956
|
+
this.doc = doc;
|
|
957
|
+
this.keyBudget = keyBudget;
|
|
958
|
+
this.families = families;
|
|
959
|
+
this.position = position;
|
|
960
|
+
this.analyzer = new RefAnalyzer(doc);
|
|
961
|
+
}
|
|
962
|
+
/** The ref a ref node resolved as. */
|
|
963
|
+
refOf(node) {
|
|
964
|
+
return this.refTexts.get(node) ?? node.$ref;
|
|
965
|
+
}
|
|
966
|
+
/** The refs inlined at a compiled node, outermost first, or undefined when none was. */
|
|
967
|
+
chainOf(node) {
|
|
968
|
+
const link = this.links.get(node);
|
|
969
|
+
if (!link)
|
|
970
|
+
return undefined;
|
|
971
|
+
let chain = this.chains.get(link);
|
|
972
|
+
if (!chain) {
|
|
973
|
+
chain = this.chainFrom(link);
|
|
974
|
+
this.chains.set(link, chain);
|
|
975
|
+
}
|
|
976
|
+
return chain;
|
|
977
|
+
}
|
|
978
|
+
/** The refs of `first` and of every run its base was inlined from, in a loop rather than recursion. */
|
|
979
|
+
chainFrom(first) {
|
|
980
|
+
const chain = [];
|
|
981
|
+
for (let link = first; link; link = this.links.get(link.run.base)) {
|
|
982
|
+
for (let index = link.index; index < link.run.nodes.length; index++)
|
|
983
|
+
chain.push(this.refOf(link.run.nodes[index]));
|
|
984
|
+
}
|
|
985
|
+
return chain;
|
|
986
|
+
}
|
|
987
|
+
/** The shared def a compiled node's chain ends in, or null; cheap, for budgeting before any definition is built. */
|
|
988
|
+
sharedTargetOf(node) {
|
|
989
|
+
let last;
|
|
990
|
+
for (let link = this.links.get(node); link; link = this.links.get(link.run.base))
|
|
991
|
+
last = link;
|
|
992
|
+
if (!last)
|
|
993
|
+
return null;
|
|
994
|
+
return this.sharedTargets.get(last.run.nodes[last.run.nodes.length - 1]) ?? null;
|
|
995
|
+
}
|
|
996
|
+
/** The compiled definition each step of a node's chain referenced, parallel to `chainOf`. */
|
|
997
|
+
definitionsOf(node) {
|
|
998
|
+
const first = this.links.get(node);
|
|
999
|
+
if (!first)
|
|
1000
|
+
return undefined;
|
|
1001
|
+
let found = this.chainDefinitions.get(first);
|
|
1002
|
+
if (found)
|
|
1003
|
+
return found;
|
|
1004
|
+
const definitions = [];
|
|
1005
|
+
let shared = null;
|
|
1006
|
+
for (let link = first; link; link = this.links.get(link.run.base)) {
|
|
1007
|
+
const { run } = link;
|
|
1008
|
+
for (let index = link.index; index < run.nodes.length; index++) {
|
|
1009
|
+
definitions.push(index + 1 < run.nodes.length ? this.mergedAt(run, index + 1) : run.base);
|
|
1010
|
+
}
|
|
1011
|
+
shared = this.sharedTargets.get(run.nodes[run.nodes.length - 1]) ?? shared;
|
|
1012
|
+
}
|
|
1013
|
+
found = { definitions, shared };
|
|
1014
|
+
this.chainDefinitions.set(first, found);
|
|
1015
|
+
return found;
|
|
1016
|
+
}
|
|
1017
|
+
/** What `run.nodes[index]` compiles to: the node built into the document, or a copy merged only to be hashed. */
|
|
1018
|
+
mergedAt(run, index) {
|
|
1019
|
+
const built = this.compiled.get(run.nodes[index]);
|
|
1020
|
+
if (isPlainObject(built) && this.links.get(built)?.run === run)
|
|
1021
|
+
return built;
|
|
1022
|
+
let byIndex = this.transient.get(run);
|
|
1023
|
+
if (!byIndex) {
|
|
1024
|
+
byIndex = new Map();
|
|
1025
|
+
this.transient.set(run, byIndex);
|
|
1026
|
+
}
|
|
1027
|
+
let merged = byIndex.get(index);
|
|
1028
|
+
if (!merged) {
|
|
1029
|
+
merged = this.merge(run, index).merged;
|
|
1030
|
+
byIndex.set(index, merged);
|
|
1031
|
+
}
|
|
1032
|
+
return merged;
|
|
1033
|
+
}
|
|
1034
|
+
/** Let `to` carry the refs inlined at `from`. */
|
|
1035
|
+
carryChain(from, to) {
|
|
1036
|
+
const link = this.links.get(from);
|
|
1037
|
+
if (link)
|
|
1038
|
+
this.links.set(to, link);
|
|
1039
|
+
if (this.sharedContent.has(from))
|
|
1040
|
+
this.sharedContent.add(to);
|
|
1041
|
+
}
|
|
1042
|
+
compile(root, pointer = "") {
|
|
1043
|
+
const tasks = [{ kind: "visit", node: root, pointer }];
|
|
1044
|
+
const values = [];
|
|
1045
|
+
while (tasks.length > 0) {
|
|
1046
|
+
const task = tasks.pop();
|
|
1047
|
+
if (task.kind === "visit")
|
|
1048
|
+
this.visit(task.node, task.pointer, tasks, values, task.outer);
|
|
1049
|
+
else if (task.kind === "assemble")
|
|
1050
|
+
values.push(this.assemble(task.node, values.splice(values.length - task.count)));
|
|
1051
|
+
else
|
|
1052
|
+
values.push(this.inline(task.nodes, values.pop(), task.pointer));
|
|
1053
|
+
}
|
|
1054
|
+
return values.pop();
|
|
1055
|
+
}
|
|
1056
|
+
/** Is `node` a ref the compile considers: a string `$ref`, or, under a family index, a `ref`. */
|
|
1057
|
+
isRefNode(node) {
|
|
1058
|
+
return typeof node.$ref === "string" || (this.families !== null && Object.prototype.hasOwnProperty.call(node, "ref"));
|
|
1059
|
+
}
|
|
1060
|
+
/**
|
|
1061
|
+
* What the ref node `node` is replaced by, or null when it stays inert.
|
|
1062
|
+
* A shared ref that cannot resolve throws `SharedRefRefusal`.
|
|
1063
|
+
*/
|
|
1064
|
+
step(node, pointer, chain) {
|
|
1065
|
+
if (typeof node.$ref === "string") {
|
|
1066
|
+
const ref = node.$ref;
|
|
1067
|
+
const shared = this.families
|
|
1068
|
+
? sharedDollarRef(ref, { prompt: this.families.prompts !== undefined, fn: this.families.functions !== undefined, db3: this.families.db3 !== undefined })
|
|
1069
|
+
: null;
|
|
1070
|
+
if (shared)
|
|
1071
|
+
return this.sharedStep(shared, `$ref ${JSON.stringify(ref)}`, ref, pointer, chain);
|
|
1072
|
+
if (this.analyzer.analyze(ref).verdict !== "resolved")
|
|
1073
|
+
return null;
|
|
1074
|
+
return { target: resolveLocalPointer(this.doc, ref), ref };
|
|
1075
|
+
}
|
|
1076
|
+
const written = typeof node.ref === "string" ? node.ref : JSON.stringify(node.ref);
|
|
1077
|
+
return this.sharedStep(sharedRefKeyword(node.ref), `ref ${JSON.stringify(node.ref)}`, written, pointer, chain);
|
|
1078
|
+
}
|
|
1079
|
+
sharedStep(shared, display, written, pointer, chain) {
|
|
1080
|
+
if (shared.kind === "reserved") {
|
|
1081
|
+
throw new SharedRefRefusal(FUNCTION_SCHEMA_REF_RESERVED, pointer, display, "the platform prefix is reserved: platform refs are not available. Ref a def in a schemas/ file instead", [...chain, written]);
|
|
1082
|
+
}
|
|
1083
|
+
const found = resolveShared(this.families, shared, this.position);
|
|
1084
|
+
if (found.ok === false) {
|
|
1085
|
+
throw new SharedRefRefusal(found.code, pointer, found.note ? `${display} (${found.note})` : display, found.reason, [...chain, written]);
|
|
1086
|
+
}
|
|
1087
|
+
const target = found.entry.defs && Object.prototype.hasOwnProperty.call(found.entry.defs, found.def) ? found.entry.defs[found.def] : undefined;
|
|
1088
|
+
if (!isPlainObject(target))
|
|
1089
|
+
throw new Error(`the family index holds no compiled target for ${found.explicit}`);
|
|
1090
|
+
return { target, ref: found.explicit, shared: { file: found.file, def: found.def, entry: found.entry }, ...(found.family === "db3" ? { db3: true } : {}) };
|
|
1091
|
+
}
|
|
1092
|
+
/** Refuse a key beside a ref node that may not sit there. `db3`: the ref resolved to a db3 projection. */
|
|
1093
|
+
checkSiblings(node, pointer, db3 = false) {
|
|
1094
|
+
if (typeof node.$ref === "string") {
|
|
1095
|
+
for (const key of Object.keys(node)) {
|
|
1096
|
+
if (key === "$ref")
|
|
1097
|
+
continue;
|
|
1098
|
+
if (this.families && key === "ref")
|
|
1099
|
+
throw new SiblingRefusal(pointer, key, node.$ref, "both");
|
|
1100
|
+
if (db3 && key === "$comment")
|
|
1101
|
+
throw new SiblingRefusal(pointer, key, node.$ref, "marker");
|
|
1102
|
+
if (!allowedSibling(key))
|
|
1103
|
+
throw new SiblingRefusal(pointer, key, node.$ref);
|
|
1104
|
+
}
|
|
1105
|
+
return;
|
|
1106
|
+
}
|
|
1107
|
+
const written = typeof node.ref === "string" ? node.ref : JSON.stringify(node.ref);
|
|
1108
|
+
for (const key of Object.keys(node)) {
|
|
1109
|
+
if (key === "ref")
|
|
1110
|
+
continue;
|
|
1111
|
+
if (key === "required" && !Array.isArray(node.required))
|
|
1112
|
+
throw new SiblingRefusal(pointer, key, written, "required");
|
|
1113
|
+
if (!REF_SIBLINGS.has(key))
|
|
1114
|
+
throw new SiblingRefusal(pointer, key, written, "ref");
|
|
1115
|
+
}
|
|
1116
|
+
}
|
|
1117
|
+
/**
|
|
1118
|
+
* Push `node`'s compiled form, or the tasks that produce it. `outer` are the
|
|
1119
|
+
* ref nodes being inlined over `node`, when it is the target of a chain.
|
|
1120
|
+
*/
|
|
1121
|
+
visit(node, pointer, tasks, values, outer = []) {
|
|
1122
|
+
if (!isPlainObject(node) || this.opaque.has(node)) {
|
|
1123
|
+
values.push(node);
|
|
1124
|
+
return;
|
|
1125
|
+
}
|
|
1126
|
+
const cached = this.compiled.get(node);
|
|
1127
|
+
if (cached !== undefined) {
|
|
1128
|
+
values.push(cached);
|
|
1129
|
+
return;
|
|
1130
|
+
}
|
|
1131
|
+
const waiting = this.pending.get(node);
|
|
1132
|
+
if (waiting) {
|
|
1133
|
+
values.push(this.build(waiting, pointer, outer));
|
|
1134
|
+
return;
|
|
1135
|
+
}
|
|
1136
|
+
if (this.isRefNode(node)) {
|
|
1137
|
+
const outerChain = outer.map((ref) => this.refOf(ref));
|
|
1138
|
+
let step = this.step(node, pointer, outerChain);
|
|
1139
|
+
if (!step) {
|
|
1140
|
+
this.compiled.set(node, node);
|
|
1141
|
+
values.push(node);
|
|
1142
|
+
return;
|
|
1143
|
+
}
|
|
1144
|
+
// Follow the alias chain: every target that is itself a resolvable ref
|
|
1145
|
+
// not yet compiled or waiting in a run. A resolved local ref never
|
|
1146
|
+
// loops, and a shared def ends the chain, so the chain ends.
|
|
1147
|
+
const nodes = [];
|
|
1148
|
+
let current = node;
|
|
1149
|
+
for (;;) {
|
|
1150
|
+
this.checkSiblings(current, pointer, step.db3 === true);
|
|
1151
|
+
nodes.push(current);
|
|
1152
|
+
this.refTexts.set(current, step.ref);
|
|
1153
|
+
if (step.shared) {
|
|
1154
|
+
this.sharedTargets.set(current, step.shared);
|
|
1155
|
+
this.opaque.add(step.target);
|
|
1156
|
+
current = step.target;
|
|
1157
|
+
break;
|
|
1158
|
+
}
|
|
1159
|
+
current = step.target;
|
|
1160
|
+
if (!isPlainObject(current) || this.compiled.has(current) || this.pending.has(current) || !this.isRefNode(current))
|
|
1161
|
+
break;
|
|
1162
|
+
const next = this.step(current, pointer, [...outerChain, ...nodes.map((ref) => this.refOf(ref))]);
|
|
1163
|
+
if (!next)
|
|
1164
|
+
break;
|
|
1165
|
+
step = next;
|
|
1166
|
+
}
|
|
1167
|
+
tasks.push({ kind: "inline", nodes, pointer }, { kind: "visit", node: current, pointer, outer: nodes });
|
|
1168
|
+
return;
|
|
1169
|
+
}
|
|
1170
|
+
const children = [];
|
|
1171
|
+
for (const [key, value] of Object.entries(node)) {
|
|
1172
|
+
const kind = childKind(key, value);
|
|
1173
|
+
if (kind === "map") {
|
|
1174
|
+
for (const [name, child] of Object.entries(value)) {
|
|
1175
|
+
children.push({ node: child, pointer: `${pointer}/${pointerSegment(key)}/${pointerSegment(name)}` });
|
|
1176
|
+
}
|
|
1177
|
+
}
|
|
1178
|
+
else if (kind === "list") {
|
|
1179
|
+
value.forEach((child, index) => children.push({ node: child, pointer: `${pointer}/${pointerSegment(key)}/${index}` }));
|
|
1180
|
+
}
|
|
1181
|
+
else if (kind === "one") {
|
|
1182
|
+
children.push({ node: value, pointer: `${pointer}/${pointerSegment(key)}` });
|
|
1183
|
+
}
|
|
1184
|
+
}
|
|
1185
|
+
tasks.push({ kind: "assemble", node, count: children.length });
|
|
1186
|
+
// Last pushed runs first: children compile in document order.
|
|
1187
|
+
for (let index = children.length - 1; index >= 0; index--)
|
|
1188
|
+
tasks.push({ kind: "visit", ...children[index] });
|
|
1189
|
+
}
|
|
1190
|
+
/** `node` with its subschemas replaced by their compiled forms, in document order; `node` itself when none changed. */
|
|
1191
|
+
assemble(node, compiledChildren) {
|
|
1192
|
+
let next = 0;
|
|
1193
|
+
let changed = false;
|
|
1194
|
+
const out = {};
|
|
1195
|
+
for (const [key, value] of Object.entries(node)) {
|
|
1196
|
+
let replacement = value;
|
|
1197
|
+
const kind = childKind(key, value);
|
|
1198
|
+
if (kind === "map") {
|
|
1199
|
+
const map = {};
|
|
1200
|
+
let mapChanged = false;
|
|
1201
|
+
for (const [name, child] of Object.entries(value)) {
|
|
1202
|
+
const compiledChild = compiledChildren[next++];
|
|
1203
|
+
setOwn(map, name, compiledChild);
|
|
1204
|
+
if (compiledChild !== child)
|
|
1205
|
+
mapChanged = true;
|
|
1206
|
+
}
|
|
1207
|
+
if (mapChanged)
|
|
1208
|
+
replacement = map;
|
|
1209
|
+
}
|
|
1210
|
+
else if (kind === "list") {
|
|
1211
|
+
const list = value.map(() => compiledChildren[next++]);
|
|
1212
|
+
if (list.some((child, index) => child !== value[index]))
|
|
1213
|
+
replacement = list;
|
|
1214
|
+
}
|
|
1215
|
+
else if (kind === "one") {
|
|
1216
|
+
replacement = compiledChildren[next++];
|
|
1217
|
+
}
|
|
1218
|
+
setOwn(out, key, replacement);
|
|
1219
|
+
if (replacement !== value)
|
|
1220
|
+
changed = true;
|
|
1221
|
+
}
|
|
1222
|
+
const result = changed ? out : node;
|
|
1223
|
+
this.compiled.set(node, result);
|
|
1224
|
+
return result;
|
|
1225
|
+
}
|
|
1226
|
+
/** Inline an alias chain over its compiled target: build its outermost node, and leave the rest waiting. */
|
|
1227
|
+
inline(nodes, base, pointer) {
|
|
1228
|
+
const run = { nodes, base };
|
|
1229
|
+
for (let index = 1; index < nodes.length; index++)
|
|
1230
|
+
this.pending.set(nodes[index], { run, index });
|
|
1231
|
+
return this.build({ run, index: 0 }, pointer);
|
|
1232
|
+
}
|
|
1233
|
+
/**
|
|
1234
|
+
* The node `run.nodes[index]` inlines: as if each ref node of the run,
|
|
1235
|
+
* innermost first, became its compiled target's keys (less the ones it
|
|
1236
|
+
* overrides) followed by its own siblings. So a key takes its value and its
|
|
1237
|
+
* place from the outermost node that sets it, and the keys come base first,
|
|
1238
|
+
* then each node's own, innermost to outermost. Built in one pass over the run.
|
|
1239
|
+
*/
|
|
1240
|
+
merge(run, index) {
|
|
1241
|
+
const refKey = (node) => (typeof node.$ref === "string" ? "$ref" : "ref");
|
|
1242
|
+
const owner = new Map();
|
|
1243
|
+
for (let level = index; level < run.nodes.length; level++) {
|
|
1244
|
+
const skip = refKey(run.nodes[level]);
|
|
1245
|
+
for (const key of Object.keys(run.nodes[level])) {
|
|
1246
|
+
if (key !== skip && !owner.has(key))
|
|
1247
|
+
owner.set(key, level);
|
|
1248
|
+
}
|
|
1249
|
+
}
|
|
1250
|
+
const merged = {};
|
|
1251
|
+
let keys = 0;
|
|
1252
|
+
for (const [key, value] of Object.entries(run.base)) {
|
|
1253
|
+
if (owner.has(key))
|
|
1254
|
+
continue;
|
|
1255
|
+
setOwn(merged, key, value);
|
|
1256
|
+
keys++;
|
|
1257
|
+
}
|
|
1258
|
+
for (let level = run.nodes.length - 1; level >= index; level--) {
|
|
1259
|
+
const node = run.nodes[level];
|
|
1260
|
+
for (const key of Object.keys(node)) {
|
|
1261
|
+
if (owner.get(key) !== level)
|
|
1262
|
+
continue;
|
|
1263
|
+
setOwn(merged, key, node[key]);
|
|
1264
|
+
keys++;
|
|
1265
|
+
}
|
|
1266
|
+
}
|
|
1267
|
+
return { merged, keys };
|
|
1268
|
+
}
|
|
1269
|
+
/** Build the node `link` inlines into the document, counting its keys against the budget. */
|
|
1270
|
+
build(link, pointer, outer = []) {
|
|
1271
|
+
const { run, index } = link;
|
|
1272
|
+
const shared = this.sharedTargets.has(run.nodes[run.nodes.length - 1]) || this.sharedContent.has(run.base);
|
|
1273
|
+
// A db3 projection's marker survives every alias over it, local or shared:
|
|
1274
|
+
// a `$comment` beside any `$ref` of the run would replace it.
|
|
1275
|
+
if (shared && parseDb3ProjectionMarker(run.base.$comment)) {
|
|
1276
|
+
for (let level = index; level < run.nodes.length; level++) {
|
|
1277
|
+
const node = run.nodes[level];
|
|
1278
|
+
if (typeof node.$ref === "string" && Object.prototype.hasOwnProperty.call(node, "$comment")) {
|
|
1279
|
+
throw new SiblingRefusal(pointer, "$comment", node.$ref, "marker");
|
|
1280
|
+
}
|
|
1281
|
+
}
|
|
1282
|
+
}
|
|
1283
|
+
const { merged, keys } = this.merge(run, index);
|
|
1284
|
+
this.built += keys;
|
|
1285
|
+
if (this.built > this.keyBudget) {
|
|
1286
|
+
throw new BuildBudgetRefusal(pointer, [...outer.map((node) => this.refOf(node)), ...this.chainFrom(link)]);
|
|
1287
|
+
}
|
|
1288
|
+
this.links.set(merged, link);
|
|
1289
|
+
if (shared)
|
|
1290
|
+
this.sharedContent.add(merged);
|
|
1291
|
+
this.compiled.set(run.nodes[index], merged);
|
|
1292
|
+
this.pending.delete(run.nodes[index]);
|
|
1293
|
+
this.inlined = true;
|
|
1294
|
+
return merged;
|
|
1295
|
+
}
|
|
1296
|
+
}
|
|
1297
|
+
/** UTF-8 length of `text`. */
|
|
1298
|
+
function utf8Length(text) {
|
|
1299
|
+
let bytes = 0;
|
|
1300
|
+
for (let i = 0; i < text.length; i++) {
|
|
1301
|
+
const code = text.charCodeAt(i);
|
|
1302
|
+
if (code < 0x80)
|
|
1303
|
+
bytes += 1;
|
|
1304
|
+
else if (code < 0x800)
|
|
1305
|
+
bytes += 2;
|
|
1306
|
+
else if (code >= 0xd800 && code <= 0xdbff && i + 1 < text.length) {
|
|
1307
|
+
const next = text.charCodeAt(i + 1);
|
|
1308
|
+
if (next >= 0xdc00 && next <= 0xdfff) {
|
|
1309
|
+
bytes += 4;
|
|
1310
|
+
i++;
|
|
1311
|
+
}
|
|
1312
|
+
else
|
|
1313
|
+
bytes += 3;
|
|
1314
|
+
}
|
|
1315
|
+
else
|
|
1316
|
+
bytes += 3;
|
|
1317
|
+
}
|
|
1318
|
+
return bytes;
|
|
1319
|
+
}
|
|
1320
|
+
/**
|
|
1321
|
+
* The size of a compiled (possibly shared) value, as `JSON.stringify` would
|
|
1322
|
+
* write it. Measured with its own stack, so a deep expansion is measured, and
|
|
1323
|
+
* refused, rather than exhausting the call stack.
|
|
1324
|
+
*/
|
|
1325
|
+
class Measure {
|
|
1326
|
+
sizes = new WeakMap();
|
|
1327
|
+
of(value) {
|
|
1328
|
+
const known = this.known(value);
|
|
1329
|
+
if (known)
|
|
1330
|
+
return known;
|
|
1331
|
+
const frames = [];
|
|
1332
|
+
const open = (node) => {
|
|
1333
|
+
const keys = Array.isArray(node) ? null : Object.keys(node);
|
|
1334
|
+
const items = Array.isArray(node) ? node : keys.map((key) => node[key]);
|
|
1335
|
+
frames.push({ value: node, keys, items, next: 0, nodes: 1, bytes: 2 });
|
|
1336
|
+
};
|
|
1337
|
+
open(value);
|
|
1338
|
+
let result = { nodes: 0, bytes: 0 };
|
|
1339
|
+
while (frames.length > 0) {
|
|
1340
|
+
const frame = frames[frames.length - 1];
|
|
1341
|
+
if (frame.next < frame.items.length) {
|
|
1342
|
+
const item = frame.items[frame.next];
|
|
1343
|
+
const size = this.known(item);
|
|
1344
|
+
if (!size) {
|
|
1345
|
+
open(item);
|
|
1346
|
+
continue;
|
|
1347
|
+
}
|
|
1348
|
+
this.add(frame, size);
|
|
1349
|
+
continue;
|
|
1350
|
+
}
|
|
1351
|
+
result = { nodes: frame.nodes, bytes: frame.bytes };
|
|
1352
|
+
this.sizes.set(frame.value, result);
|
|
1353
|
+
frames.pop();
|
|
1354
|
+
if (frames.length > 0)
|
|
1355
|
+
this.add(frames[frames.length - 1], result);
|
|
1356
|
+
}
|
|
1357
|
+
return result;
|
|
1358
|
+
}
|
|
1359
|
+
/** The size of a primitive or an already measured object; null for an object not yet measured. */
|
|
1360
|
+
known(value) {
|
|
1361
|
+
if (value === null || typeof value !== "object") {
|
|
1362
|
+
return { nodes: 0, bytes: utf8Length(JSON.stringify(value) ?? "null") };
|
|
1363
|
+
}
|
|
1364
|
+
return this.sizes.get(value) ?? null;
|
|
1365
|
+
}
|
|
1366
|
+
/** Count the frame's next entry, of `size`. */
|
|
1367
|
+
add(frame, size) {
|
|
1368
|
+
const index = frame.next++;
|
|
1369
|
+
frame.nodes += size.nodes;
|
|
1370
|
+
frame.bytes += size.bytes + (index > 0 ? 1 : 0) + (frame.keys ? utf8Length(JSON.stringify(frame.keys[index])) + 1 : 0);
|
|
1371
|
+
}
|
|
1372
|
+
}
|
|
1373
|
+
/** The entries of a compiled object or array, with pointer segments. */
|
|
1374
|
+
function entriesOf(value) {
|
|
1375
|
+
if (Array.isArray(value))
|
|
1376
|
+
return value.map((item, index) => [String(index), item, `/${index}`]);
|
|
1377
|
+
return Object.entries(value).map(([key, item]) => [key, item, `/${pointerSegment(key)}`]);
|
|
1378
|
+
}
|
|
1379
|
+
/**
|
|
1380
|
+
* Where the running count first passes `cap`, walking the compiled document in
|
|
1381
|
+
* the order `JSON.stringify` writes it: the deepest object or array holding
|
|
1382
|
+
* that point, and the refs being expanded there.
|
|
1383
|
+
*/
|
|
1384
|
+
function crossing(root, metric, cap, measure, chainOf) {
|
|
1385
|
+
let node = root;
|
|
1386
|
+
let pointer = "";
|
|
1387
|
+
let chain = [...(chainOf(node) ?? [])];
|
|
1388
|
+
let before = 0;
|
|
1389
|
+
for (;;) {
|
|
1390
|
+
// The node itself, or its opening bracket.
|
|
1391
|
+
let acc = before + 1;
|
|
1392
|
+
if (acc > cap)
|
|
1393
|
+
return { pointer, chain };
|
|
1394
|
+
let next = null;
|
|
1395
|
+
const entries = entriesOf(node);
|
|
1396
|
+
for (let index = 0; index < entries.length; index++) {
|
|
1397
|
+
const [key, value, segment] = entries[index];
|
|
1398
|
+
if (metric === "bytes") {
|
|
1399
|
+
acc += (index > 0 ? 1 : 0) + (Array.isArray(node) ? 0 : utf8Length(JSON.stringify(key)) + 1);
|
|
1400
|
+
if (acc > cap)
|
|
1401
|
+
return { pointer, chain };
|
|
1402
|
+
}
|
|
1403
|
+
const size = measure.of(value)[metric];
|
|
1404
|
+
if (acc + size > cap) {
|
|
1405
|
+
if (value !== null && typeof value === "object")
|
|
1406
|
+
next = { value, segment, start: acc };
|
|
1407
|
+
break;
|
|
1408
|
+
}
|
|
1409
|
+
acc += size;
|
|
1410
|
+
}
|
|
1411
|
+
if (!next)
|
|
1412
|
+
return { pointer, chain };
|
|
1413
|
+
node = next.value;
|
|
1414
|
+
pointer += next.segment;
|
|
1415
|
+
chain = [...chain, ...(chainOf(node) ?? [])];
|
|
1416
|
+
before = next.start;
|
|
1417
|
+
}
|
|
1418
|
+
}
|
|
1419
|
+
/** Every inlined node and every inert ref of the compiled document, in document order. */
|
|
1420
|
+
function report(root, compiler, field, prefix = "") {
|
|
1421
|
+
const resolved = [];
|
|
1422
|
+
const entries = [];
|
|
1423
|
+
const warnings = [];
|
|
1424
|
+
const warn = (pointer, ref, reason) => warnings.push({ path: pointer, ref, reason, message: `${field} ${display(pointer)}: $ref ${JSON.stringify(ref)} stays inert (${reason})` });
|
|
1425
|
+
// Depth-first in document order, with its own stack (last pushed runs first).
|
|
1426
|
+
const stack = [{ node: root, pointer: prefix, chain: [], parent: -1 }];
|
|
1427
|
+
while (stack.length > 0) {
|
|
1428
|
+
const { node, pointer, chain: outer, parent: outerParent } = stack.pop();
|
|
1429
|
+
if (!isPlainObject(node))
|
|
1430
|
+
continue;
|
|
1431
|
+
let chain = outer;
|
|
1432
|
+
let parent = outerParent;
|
|
1433
|
+
const own = compiler.chainOf(node);
|
|
1434
|
+
if (own) {
|
|
1435
|
+
// Entries share a chain where they can, so many uses of one long run cost one array.
|
|
1436
|
+
chain = chain.length === 0 ? own : [...chain, ...own];
|
|
1437
|
+
resolved.push({ pointer, chain });
|
|
1438
|
+
entries.push({ pointer, chain, node, parent: outerParent });
|
|
1439
|
+
parent = entries.length - 1;
|
|
1440
|
+
}
|
|
1441
|
+
// A shared def's content is opaque: copied whole, nothing in it reported.
|
|
1442
|
+
if (compiler.sharedContent.has(node))
|
|
1443
|
+
continue;
|
|
1444
|
+
if (typeof node.$ref === "string") {
|
|
1445
|
+
warn(pointer, node.$ref, compiler.analyzer.analyze(node.$ref).reason);
|
|
1446
|
+
for (const sub of subschemas(node, false)) {
|
|
1447
|
+
eachRef(sub.child, (ref, inner) => {
|
|
1448
|
+
const analysis = compiler.analyzer.analyze(ref);
|
|
1449
|
+
warn(pointer + sub.pointer + inner, ref, analysis.verdict === "resolved" ? `it sits inside the inert $ref at ${display(pointer)}, which is left as written` : analysis.reason);
|
|
1450
|
+
});
|
|
1451
|
+
}
|
|
1452
|
+
continue;
|
|
1453
|
+
}
|
|
1454
|
+
const subs = subschemas(node, false);
|
|
1455
|
+
for (let index = subs.length - 1; index >= 0; index--) {
|
|
1456
|
+
stack.push({ node: subs[index].child, pointer: pointer + subs[index].pointer, chain, parent });
|
|
1457
|
+
}
|
|
1458
|
+
}
|
|
1459
|
+
return { resolved, warnings, entries };
|
|
1460
|
+
}
|
|
1461
|
+
/** A shared def's own provenance, as entries relative to the def: from this process's compile, or as stored. */
|
|
1462
|
+
function nestedEntries(target) {
|
|
1463
|
+
const local = target.entry.resolved;
|
|
1464
|
+
if (local && Object.prototype.hasOwnProperty.call(local, target.def))
|
|
1465
|
+
return [...local[target.def]];
|
|
1466
|
+
const stored = target.entry.provenance;
|
|
1467
|
+
if (!stored || !Object.prototype.hasOwnProperty.call(stored, target.def))
|
|
1468
|
+
return [];
|
|
1469
|
+
const provenance = stored[target.def];
|
|
1470
|
+
if (!isPlainObject(provenance))
|
|
1471
|
+
return [];
|
|
1472
|
+
return Object.entries(provenance).map(([pointer, entry]) => {
|
|
1473
|
+
const steps = Array.isArray(entry?.chain) ? entry.chain : [];
|
|
1474
|
+
return { pointer, chain: steps.map((step) => String(step?.ref)), hashes: steps.map((step) => String(step?.hash)) };
|
|
1475
|
+
});
|
|
1476
|
+
}
|
|
1477
|
+
/** Serialized bytes a provenance step takes beyond its ref: `{"ref":"","hash":"h1:<64 hex>"},`. */
|
|
1478
|
+
const PROVENANCE_STEP_BYTES = 90;
|
|
1479
|
+
/** Serialized bytes a provenance entry takes beyond its pointer and chain: `"":{"chain":[]},`. */
|
|
1480
|
+
const PROVENANCE_ENTRY_BYTES = 16;
|
|
1481
|
+
/** Bytes `text` takes inside a serialized JSON string, its escapes counted (a quote or a control is two or six). */
|
|
1482
|
+
function jsonStringBytes(text) {
|
|
1483
|
+
return utf8Length(JSON.stringify(text)) - 2;
|
|
1484
|
+
}
|
|
1485
|
+
/** `chain` written short: its first three and last two refs around a count. */
|
|
1486
|
+
function abbreviate(chain) {
|
|
1487
|
+
if (chain.length <= 8)
|
|
1488
|
+
return chain.join(" → ");
|
|
1489
|
+
return [...chain.slice(0, 3), `… (${chain.length - 5} more)`, ...chain.slice(-2)].join(" → ");
|
|
1490
|
+
}
|
|
1491
|
+
/**
|
|
1492
|
+
* The provenance budget: the serialized provenance the entries would record,
|
|
1493
|
+
* estimated from their pointers and chain steps (each step a ref and a hash)
|
|
1494
|
+
* before any definition is built or hashed. Null when it fits; else the
|
|
1495
|
+
* refusal, naming where the estimate crossed `limit`.
|
|
1496
|
+
*/
|
|
1497
|
+
function provenanceBudgetRefusal(field, entries, compiler, limit) {
|
|
1498
|
+
const refCosts = new WeakMap();
|
|
1499
|
+
const costOf = (refs) => {
|
|
1500
|
+
let cost = 0;
|
|
1501
|
+
for (const ref of refs)
|
|
1502
|
+
cost += jsonStringBytes(ref) + PROVENANCE_STEP_BYTES;
|
|
1503
|
+
return cost;
|
|
1504
|
+
};
|
|
1505
|
+
const chainCosts = [];
|
|
1506
|
+
let total = 0;
|
|
1507
|
+
let steps = 0;
|
|
1508
|
+
for (let index = 0; index < entries.length; index++) {
|
|
1509
|
+
const entry = entries[index];
|
|
1510
|
+
const own = compiler.chainOf(entry.node);
|
|
1511
|
+
let ownCost = refCosts.get(own);
|
|
1512
|
+
if (ownCost === undefined) {
|
|
1513
|
+
ownCost = costOf(own);
|
|
1514
|
+
refCosts.set(own, ownCost);
|
|
1515
|
+
}
|
|
1516
|
+
const chainCost = (entry.parent >= 0 ? chainCosts[entry.parent] : 0) + ownCost;
|
|
1517
|
+
chainCosts.push(chainCost);
|
|
1518
|
+
total += jsonStringBytes(entry.pointer) + PROVENANCE_ENTRY_BYTES + chainCost;
|
|
1519
|
+
steps += entry.chain.length;
|
|
1520
|
+
const shared = compiler.sharedTargetOf(entry.node);
|
|
1521
|
+
if (shared) {
|
|
1522
|
+
for (const nested of nestedEntries(shared)) {
|
|
1523
|
+
const nestedCost = costOf(nested.chain);
|
|
1524
|
+
total += nested.pointer === "" ? nestedCost : jsonStringBytes(entry.pointer + nested.pointer) + PROVENANCE_ENTRY_BYTES + chainCost + nestedCost;
|
|
1525
|
+
steps += nested.chain.length + (nested.pointer === "" ? 0 : entry.chain.length);
|
|
1526
|
+
}
|
|
1527
|
+
}
|
|
1528
|
+
if (total > limit) {
|
|
1529
|
+
return {
|
|
1530
|
+
code: FUNCTION_SCHEMA_EXPANSION_LIMIT,
|
|
1531
|
+
path: entry.pointer,
|
|
1532
|
+
chain: [...entry.chain],
|
|
1533
|
+
message: `${field} would record more provenance than the ${limit}-byte limit (${Math.round(limit / 1024)} KiB) allows: ` +
|
|
1534
|
+
`by ${display(entry.pointer)} its inlined refs already carry ${steps} chain steps, each recorded with its definition's hash, ` +
|
|
1535
|
+
`about ${total} bytes. The limit was crossed at ${display(entry.pointer)}, expanding ${abbreviate(entry.chain)}. ` +
|
|
1536
|
+
"Reference definitions through shorter alias chains, or fewer times.",
|
|
1537
|
+
};
|
|
1538
|
+
}
|
|
1539
|
+
}
|
|
1540
|
+
return null;
|
|
1541
|
+
}
|
|
1542
|
+
/**
|
|
1543
|
+
* The resolved entries with what provenance hashes: each step's compiled
|
|
1544
|
+
* definition, and each shared def's own provenance rebased under the pointer
|
|
1545
|
+
* it was inlined at, the importing chain first. A shared def's entry for its
|
|
1546
|
+
* own root extends the inlining entry's chain.
|
|
1547
|
+
*/
|
|
1548
|
+
function withDefinitions(entries, compiler) {
|
|
1549
|
+
const out = [];
|
|
1550
|
+
const definitions = [];
|
|
1551
|
+
for (const entry of entries) {
|
|
1552
|
+
const own = compiler.definitionsOf(entry.node);
|
|
1553
|
+
const defs = entry.parent >= 0 ? [...definitions[entry.parent], ...own.definitions] : own.definitions;
|
|
1554
|
+
definitions.push(defs);
|
|
1555
|
+
const resolution = { pointer: entry.pointer, chain: entry.chain, definitions: defs };
|
|
1556
|
+
out.push(resolution);
|
|
1557
|
+
if (!own.shared)
|
|
1558
|
+
continue;
|
|
1559
|
+
// The importing chain's hashes, fixed before the def's own root entry
|
|
1560
|
+
// extends `resolution`: every nested entry is prefixed by the same steps.
|
|
1561
|
+
const prefix = new Array(entry.chain.length).fill(undefined);
|
|
1562
|
+
for (const nested of nestedEntries(own.shared)) {
|
|
1563
|
+
const nestedDefinitions = nested.definitions ?? new Array(nested.chain.length).fill(undefined);
|
|
1564
|
+
const nestedHashes = nested.hashes ?? new Array(nested.chain.length).fill(undefined);
|
|
1565
|
+
const extended = {
|
|
1566
|
+
pointer: entry.pointer + nested.pointer,
|
|
1567
|
+
chain: [...entry.chain, ...nested.chain],
|
|
1568
|
+
definitions: [...defs, ...nestedDefinitions],
|
|
1569
|
+
hashes: [...prefix, ...nestedHashes],
|
|
1570
|
+
};
|
|
1571
|
+
if (nested.pointer === "")
|
|
1572
|
+
Object.assign(resolution, extended);
|
|
1573
|
+
else
|
|
1574
|
+
out.push(extended);
|
|
1575
|
+
}
|
|
1576
|
+
}
|
|
1577
|
+
return out;
|
|
1578
|
+
}
|
|
1579
|
+
/** Does any `$ref` in the compiled `root`, outside its root `$defs` and any shared def's content, start with `#/$defs/`? */
|
|
1580
|
+
function namesDefs(root, opaque) {
|
|
1581
|
+
if (opaque.has(root))
|
|
1582
|
+
return false;
|
|
1583
|
+
if (typeof root.$ref === "string" && root.$ref.startsWith("#/$defs/"))
|
|
1584
|
+
return true;
|
|
1585
|
+
const seen = new WeakSet();
|
|
1586
|
+
const stack = Object.entries(root)
|
|
1587
|
+
.filter(([key]) => key !== "$defs")
|
|
1588
|
+
.map(([, value]) => value);
|
|
1589
|
+
while (stack.length > 0) {
|
|
1590
|
+
const value = stack.pop();
|
|
1591
|
+
if (value === null || typeof value !== "object" || seen.has(value) || opaque.has(value))
|
|
1592
|
+
continue;
|
|
1593
|
+
seen.add(value);
|
|
1594
|
+
if (isPlainObject(value) && typeof value.$ref === "string" && value.$ref.startsWith("#/$defs/"))
|
|
1595
|
+
return true;
|
|
1596
|
+
for (const item of Object.values(value))
|
|
1597
|
+
stack.push(item);
|
|
1598
|
+
}
|
|
1599
|
+
return false;
|
|
1600
|
+
}
|
|
1601
|
+
/** The refusal for an expansion over `cap`, naming the figure, where the count crossed and the refs expanded there. */
|
|
1602
|
+
function expansionRefusal(field, over, cap, figure, at) {
|
|
1603
|
+
const limit = over === "nodes" ? `${cap}-node limit` : `${cap}-byte limit (${Math.round((cap / 1024) * 10) / 10} KiB)`;
|
|
1604
|
+
const where = at.chain.length > 0
|
|
1605
|
+
? `The ${over === "nodes" ? "count" : "size"} crossed the limit at ${display(at.pointer)}, expanding ${at.chain.join(" → ")}.`
|
|
1606
|
+
: `The ${over === "nodes" ? "count" : "size"} crossed the limit at ${display(at.pointer)}, where no ref is being expanded; the limit applies because the schema inlines refs.`;
|
|
1607
|
+
return {
|
|
1608
|
+
code: FUNCTION_SCHEMA_EXPANSION_LIMIT,
|
|
1609
|
+
path: at.pointer,
|
|
1610
|
+
chain: at.chain,
|
|
1611
|
+
message: `${field} is over the ${limit} once its refs are expanded: it expands to ${figure}. ${where} Reference large definitions fewer times, or split the schema.`,
|
|
1612
|
+
};
|
|
1613
|
+
}
|
|
1614
|
+
/** The refusal for a key beside a ref node that may not sit there. */
|
|
1615
|
+
function siblingRefusal(field, error) {
|
|
1616
|
+
const at = `${field} ${display(error.pointer)}`;
|
|
1617
|
+
const key = JSON.stringify(error.key);
|
|
1618
|
+
const ref = JSON.stringify(error.ref);
|
|
1619
|
+
const message = error.kind === "marker"
|
|
1620
|
+
? `${at}: "$comment" beside ${error.ref.startsWith("db3:") ? "the db3 ref" : "$ref"} ${ref}${error.ref.startsWith("db3:") ? "" : ", which resolves to a db3 projection,"} ` +
|
|
1621
|
+
"is not allowed: the projection's $comment is its marker, which validation messages and " +
|
|
1622
|
+
"generated hovers name. Write a description instead."
|
|
1623
|
+
: error.kind === "both"
|
|
1624
|
+
? `${at}: "ref" beside "$ref": ${ref} is not allowed: a node is one ref. Keep "$ref" or "ref", not both.`
|
|
1625
|
+
: error.kind === "required"
|
|
1626
|
+
? `${at}: "required" beside ref ${ref} must be the JSON Schema array of property names, such as required = ["amount"]; ` +
|
|
1627
|
+
"required = true is the field-table spelling, which arrives with the field-table release."
|
|
1628
|
+
: error.kind === "ref"
|
|
1629
|
+
? `${at}: ${key} beside ref ${ref} is not allowed. Beside ref only description, required and nullable may sit, ` +
|
|
1630
|
+
`because the def replaces the node; move ${key} into the def.`
|
|
1631
|
+
: `${at}: ${key} beside "$ref": ${ref} is not allowed. ` +
|
|
1632
|
+
"A resolved ref is replaced by its definition, so only annotations (description, title, default, examples, " +
|
|
1633
|
+
"an unknown key such as x-display) and nullable may sit beside it. Move the constraint into the definition, " +
|
|
1634
|
+
"or inline the definition.";
|
|
1635
|
+
return { code: FUNCTION_SCHEMA_REF_SIBLING, path: error.pointer, chain: [error.ref], message };
|
|
1636
|
+
}
|
|
1637
|
+
/**
|
|
1638
|
+
* Compile `schema`'s refs: inline every local `#/$defs/` ref whose target
|
|
1639
|
+
* exists (and, under `options.families`, every ref to a shared def), leave
|
|
1640
|
+
* every other ref as written with a warning, and drop the root `$defs` once
|
|
1641
|
+
* nothing left in the document points into it. The result is a fixed point:
|
|
1642
|
+
* compiling it again changes nothing and warns about the same refs, unless an
|
|
1643
|
+
* inlined shared def carries a dangling `#/$defs/<X>` that the document's root
|
|
1644
|
+
* `$defs` declares, which a second compile would resolve; a compile therefore
|
|
1645
|
+
* always starts from source.
|
|
1646
|
+
*
|
|
1647
|
+
* A refusal (a disallowed sibling, an expansion over a limit, a shared ref
|
|
1648
|
+
* that does not resolve) returns the input unchanged, with no warnings and
|
|
1649
|
+
* nothing resolved.
|
|
1650
|
+
*
|
|
1651
|
+
* Under a family index (unless `options.provenance` is false), each resolved
|
|
1652
|
+
* entry carries the compiled definition of each step of its chain, for
|
|
1653
|
+
* `schemaProvenanceOf`; the provenance those entries would record is held to
|
|
1654
|
+
* `SCHEMA_PROVENANCE_LIMIT_BYTES` before any definition is built, and a lone
|
|
1655
|
+
* surrogate the hash could not take is refused.
|
|
1656
|
+
*
|
|
1657
|
+
* @example
|
|
1658
|
+
* compileSchemaRefs({
|
|
1659
|
+
* $defs: { Money: { type: "number", minimum: 0 } },
|
|
1660
|
+
* type: "object",
|
|
1661
|
+
* properties: { price: { $ref: "#/$defs/Money" } },
|
|
1662
|
+
* }).schema;
|
|
1663
|
+
* // → { type: "object", properties: { price: { type: "number", minimum: 0 } } }
|
|
1664
|
+
*/
|
|
1665
|
+
export function compileSchemaRefs(schema, options = {}) {
|
|
1666
|
+
const field = options.field ?? "schema";
|
|
1667
|
+
const prefix = options.pointerPrefix ?? "";
|
|
1668
|
+
if (!isPlainObject(schema))
|
|
1669
|
+
return { schema, warnings: [], refusal: null, resolved: [] };
|
|
1670
|
+
const limits = { ...SCHEMA_EXPANSION_LIMITS, ...(options.limits ?? {}) };
|
|
1671
|
+
const compiler = new Compiler(schema, Math.floor(limits.bytes / 2), options.families ?? null, options.position ?? "input");
|
|
1672
|
+
const refused = (refusal) => ({ schema, warnings: [], resolved: [], refusal });
|
|
1673
|
+
let root;
|
|
1674
|
+
try {
|
|
1675
|
+
root = compiler.compile(schema, prefix);
|
|
1676
|
+
}
|
|
1677
|
+
catch (error) {
|
|
1678
|
+
if (error instanceof BuildBudgetRefusal) {
|
|
1679
|
+
return refused(expansionRefusal(field, "bytes", limits.bytes, `more than ${limits.bytes} bytes`, error));
|
|
1680
|
+
}
|
|
1681
|
+
if (error instanceof SharedRefRefusal) {
|
|
1682
|
+
return refused({
|
|
1683
|
+
code: error.code,
|
|
1684
|
+
path: error.pointer,
|
|
1685
|
+
chain: error.chain,
|
|
1686
|
+
message: `${field} ${display(error.pointer)}: ${error.display}: ${error.reason}.`,
|
|
1687
|
+
});
|
|
1688
|
+
}
|
|
1689
|
+
if (!(error instanceof SiblingRefusal))
|
|
1690
|
+
throw error;
|
|
1691
|
+
return refused(siblingRefusal(field, error));
|
|
1692
|
+
}
|
|
1693
|
+
if (isPlainObject(root) && isPlainObject(schema.$defs) && Object.prototype.hasOwnProperty.call(root, "$defs") && root.$defs === schema.$defs) {
|
|
1694
|
+
if (!namesDefs(root, compiler.sharedContent)) {
|
|
1695
|
+
const { $defs: _dropped, ...rest } = root;
|
|
1696
|
+
compiler.carryChain(root, rest);
|
|
1697
|
+
root = rest;
|
|
1698
|
+
}
|
|
1699
|
+
}
|
|
1700
|
+
if (compiler.inlined) {
|
|
1701
|
+
const measure = new Measure();
|
|
1702
|
+
const size = measure.of(root);
|
|
1703
|
+
const over = size.nodes > limits.nodes ? "nodes" : size.bytes > limits.bytes ? "bytes" : null;
|
|
1704
|
+
if (over) {
|
|
1705
|
+
const crossed = crossing(root, over, limits[over], measure, (node) => compiler.chainOf(node));
|
|
1706
|
+
const at = { ...crossed, pointer: prefix + crossed.pointer };
|
|
1707
|
+
const figure = over === "nodes" ? `${size.nodes} nodes (JSON objects and arrays)` : `${size.bytes} bytes`;
|
|
1708
|
+
return refused(expansionRefusal(field, over, limits[over], figure, at));
|
|
1709
|
+
}
|
|
1710
|
+
}
|
|
1711
|
+
const { resolved, warnings, entries } = report(root, compiler, field, prefix);
|
|
1712
|
+
if (!options.families || options.provenance === false || entries.length === 0) {
|
|
1713
|
+
return { schema: JSON.parse(JSON.stringify(root)), warnings, refusal: null, resolved };
|
|
1714
|
+
}
|
|
1715
|
+
const budget = provenanceBudgetRefusal(field, entries, compiler, SCHEMA_PROVENANCE_LIMIT_BYTES);
|
|
1716
|
+
if (budget)
|
|
1717
|
+
return refused(budget);
|
|
1718
|
+
try {
|
|
1719
|
+
canonicalJson(root);
|
|
1720
|
+
}
|
|
1721
|
+
catch (error) {
|
|
1722
|
+
if (!(error instanceof SchemaCanonicalError))
|
|
1723
|
+
throw error;
|
|
1724
|
+
return refused({
|
|
1725
|
+
code: SCHEMA_CANONICAL_INVALID,
|
|
1726
|
+
path: prefix + error.pointer,
|
|
1727
|
+
chain: [],
|
|
1728
|
+
message: `${field} ${display(prefix + error.pointer)} holds a lone surrogate (an unpaired \\ud800-\\udfff escape), which the provenance ` +
|
|
1729
|
+
"of a schema that inlines refs cannot hash. Remove it, or pair it.",
|
|
1730
|
+
});
|
|
1731
|
+
}
|
|
1732
|
+
return { schema: JSON.parse(JSON.stringify(root)), warnings, refusal: null, resolved: withDefinitions(entries, compiler) };
|
|
1733
|
+
}
|
|
1734
|
+
/**
|
|
1735
|
+
* A row budget (#5534, generalized from the function's): when a write inlined
|
|
1736
|
+
* a ref in any of `texts`, the texts plus `extraBytes` must fit `budget`. Null
|
|
1737
|
+
* when they fit, or when no ref was inlined, so a write that stores today is
|
|
1738
|
+
* never refused. The refusal names the longest chain inlined.
|
|
1739
|
+
*/
|
|
1740
|
+
export function schemaRowBudgetRefusal(input) {
|
|
1741
|
+
const fields = Object.keys(input.texts);
|
|
1742
|
+
const written = fields.filter((field) => (input.resolved[field]?.length ?? 0) > 0);
|
|
1743
|
+
if (written.length === 0)
|
|
1744
|
+
return null;
|
|
1745
|
+
const combined = fields.reduce((sum, field) => sum + utf8Length(input.texts[field] ?? ""), 0) + (input.extraBytes ?? 0);
|
|
1746
|
+
if (combined <= input.budget)
|
|
1747
|
+
return null;
|
|
1748
|
+
let longest = null;
|
|
1749
|
+
for (const field of written) {
|
|
1750
|
+
for (const entry of input.resolved[field]) {
|
|
1751
|
+
if (!longest || entry.chain.length > longest.entry.chain.length)
|
|
1752
|
+
longest = { field, entry };
|
|
1753
|
+
}
|
|
1754
|
+
}
|
|
1755
|
+
const { field, entry } = longest;
|
|
1756
|
+
return {
|
|
1757
|
+
code: FUNCTION_SCHEMA_EXPANSION_LIMIT,
|
|
1758
|
+
field,
|
|
1759
|
+
path: entry.pointer,
|
|
1760
|
+
chain: [...entry.chain],
|
|
1761
|
+
message: `${input.subject} are ${combined} bytes once refs are expanded in ${written.join(" and ")}, ` +
|
|
1762
|
+
`over the ${input.budget}-byte (${Math.round(input.budget / 1024)} KiB) ` +
|
|
1763
|
+
`budget ${input.holder}. ${field} inlines ${entry.chain.join(" → ")} at ${display(entry.pointer)}. ` +
|
|
1764
|
+
"Reference large definitions fewer times, or shorten the schemas.",
|
|
1765
|
+
};
|
|
1766
|
+
}
|
|
1767
|
+
/**
|
|
1768
|
+
* The function row budget: when a write inlined a ref in either schema, the
|
|
1769
|
+
* two compiled schemas the row will hold (`inputSchema` and `outputSchema`,
|
|
1770
|
+
* as stored strings) must fit `budget` bytes together. Null when they fit, or
|
|
1771
|
+
* when no ref was inlined, so a schema that stores today is never refused.
|
|
1772
|
+
* The server runs it on every function write; the CLI's preflight runs it on
|
|
1773
|
+
* the two compiled schemas a push sends, because the server never sees the
|
|
1774
|
+
* refs of an already-compiled schema.
|
|
1775
|
+
*/
|
|
1776
|
+
export function functionSchemaRowBudgetRefusal(inputSchema, outputSchema, resolved, budget = FUNCTION_SCHEMA_ROW_BUDGET_BYTES) {
|
|
1777
|
+
const refusal = schemaRowBudgetRefusal({
|
|
1778
|
+
texts: { inputSchema, outputSchema },
|
|
1779
|
+
resolved,
|
|
1780
|
+
budget,
|
|
1781
|
+
subject: "inputSchema and outputSchema together",
|
|
1782
|
+
holder: "a function holds for its two schemas",
|
|
1783
|
+
});
|
|
1784
|
+
if (!refusal)
|
|
1785
|
+
return null;
|
|
1786
|
+
const { field: _field, ...rest } = refusal;
|
|
1787
|
+
return rest;
|
|
1788
|
+
}
|
|
1789
|
+
//# sourceMappingURL=generated-schema-refs.js.map
|