@intentius/chant 0.124.56 → 0.124.58
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/ci-audit/index.d.ts.map +1 -1
- package/dist/ci-audit/index.js +1 -2
- package/dist/ci-product-words.d.ts +47 -2
- package/dist/ci-product-words.d.ts.map +1 -1
- package/dist/ci-product-words.js +59 -1
- package/dist/ci-product.d.ts +26 -2
- package/dist/ci-product.d.ts.map +1 -1
- package/dist/ci-product.js +30 -7
- package/dist/cli/commands/init.d.ts +2 -0
- package/dist/cli/commands/init.d.ts.map +1 -1
- package/dist/cli/commands/init.js +1 -1
- package/dist/cli/handlers/build.d.ts.map +1 -1
- package/dist/cli/handlers/build.js +5 -1
- package/dist/cli/handlers/init.d.ts.map +1 -1
- package/dist/cli/handlers/init.js +16 -0
- package/dist/cli/handlers/lifecycle.d.ts.map +1 -1
- package/dist/cli/handlers/lifecycle.js +14 -0
- package/dist/cli/handlers/pr.d.ts.map +1 -1
- package/dist/cli/handlers/pr.js +90 -35
- package/dist/cli/handlers/serve.d.ts.map +1 -1
- package/dist/cli/handlers/serve.js +9 -0
- package/dist/cli/main.d.ts.map +1 -1
- package/dist/cli/main.js +6 -2
- package/dist/cli/mcp/product-tools.d.ts +40 -7
- package/dist/cli/mcp/product-tools.d.ts.map +1 -1
- package/dist/cli/mcp/product-tools.js +59 -15
- package/dist/cli/mcp/read-only.d.ts +2 -1
- package/dist/cli/mcp/read-only.d.ts.map +1 -1
- package/dist/cli/mcp/read-only.js +2 -1
- package/dist/cli/mcp/server.d.ts +11 -0
- package/dist/cli/mcp/server.d.ts.map +1 -1
- package/dist/cli/mcp/server.js +15 -3
- package/dist/cli/mcp-config.d.ts +4 -1
- package/dist/cli/mcp-config.d.ts.map +1 -1
- package/dist/cli/mcp-config.js +6 -2
- package/dist/cli/parse-args.d.ts.map +1 -1
- package/dist/cli/parse-args.js +9 -0
- package/dist/cli/registry.d.ts +8 -0
- package/dist/cli/registry.d.ts.map +1 -1
- package/dist/components/auto-release.d.ts +5 -2
- package/dist/components/auto-release.d.ts.map +1 -1
- package/dist/components/auto-release.js +9 -4
- package/dist/components/capability.d.ts +10 -0
- package/dist/components/capability.d.ts.map +1 -1
- package/dist/components/deploy-units.d.ts +12 -0
- package/dist/components/deploy-units.d.ts.map +1 -1
- package/dist/components/deploy-units.js +20 -1
- package/dist/components/pr-pipeline.d.ts +64 -2
- package/dist/components/pr-pipeline.d.ts.map +1 -1
- package/dist/components/pr-pipeline.js +66 -5
- package/dist/components/product-pipeline.d.ts +18 -1
- package/dist/components/product-pipeline.d.ts.map +1 -1
- package/dist/components/product-pipeline.js +8 -2
- package/dist/components/row-lease.d.ts +22 -1
- package/dist/components/row-lease.d.ts.map +1 -1
- package/dist/components/row-lease.js +32 -6
- package/dist/e2e-harness/driver.d.ts.map +1 -1
- package/dist/e2e-harness/driver.js +97 -0
- package/dist/e2e-harness/forgejo.d.ts +5 -1
- package/dist/e2e-harness/forgejo.d.ts.map +1 -1
- package/dist/e2e-harness/forgejo.js +35 -0
- package/dist/e2e-harness/index.d.ts +7 -0
- package/dist/e2e-harness/index.d.ts.map +1 -1
- package/dist/e2e-harness/index.js +11 -2
- package/dist/e2e-harness/ports.d.ts +31 -0
- package/dist/e2e-harness/ports.d.ts.map +1 -1
- package/dist/e2e-harness/scenario.d.ts.map +1 -1
- package/dist/e2e-harness/scenario.js +9 -5
- package/dist/e2e-harness/schemas/e2e-scenario.schema.json +43 -3
- package/dist/e2e-harness/schemas/index.d.ts +22 -1
- package/dist/e2e-harness/schemas/index.d.ts.map +1 -1
- package/dist/e2e-harness/schemas/index.js +1 -1
- package/dist/e2e-harness/steps.d.ts.map +1 -1
- package/dist/e2e-harness/steps.js +4 -0
- package/dist/lexicon.d.ts +9 -0
- package/dist/lexicon.d.ts.map +1 -1
- package/dist/lifecycle/git.d.ts +39 -3
- package/dist/lifecycle/git.d.ts.map +1 -1
- package/dist/lifecycle/git.js +223 -15
- package/dist/lifecycle/lock-rows.d.ts +23 -0
- package/dist/lifecycle/lock-rows.d.ts.map +1 -1
- package/dist/lifecycle/lock-rows.js +47 -8
- package/dist/lifecycle/resource-lock.d.ts +70 -0
- package/dist/lifecycle/resource-lock.d.ts.map +1 -1
- package/dist/lifecycle/resource-lock.js +241 -5
- package/dist/mcp/types.d.ts +9 -0
- package/dist/mcp/types.d.ts.map +1 -1
- package/dist/op/gate.js +21 -4
- package/dist/op/op-waves-release-port.js +1 -1
- package/dist/op/op-waves-release.d.ts +2 -1
- package/dist/op/op-waves-release.d.ts.map +1 -1
- package/dist/op/op-waves-run.d.ts +8 -0
- package/dist/op/op-waves-run.d.ts.map +1 -1
- package/dist/op/op-waves-run.js +101 -29
- package/dist/op/op-waves.d.ts +18 -0
- package/dist/op/op-waves.d.ts.map +1 -1
- package/dist/op/op-waves.js +16 -0
- package/dist/pr-loop.d.ts.map +1 -1
- package/dist/pr-loop.js +1 -2
- package/dist/release-floors.d.ts +1 -1
- package/dist/release-floors.js +1 -1
- package/dist/template-request/index.d.ts +9 -0
- package/dist/template-request/index.d.ts.map +1 -0
- package/dist/template-request/index.js +8 -0
- package/dist/template-request/request-body.d.ts +21 -0
- package/dist/template-request/request-body.d.ts.map +1 -0
- package/dist/template-request/request-body.js +86 -0
- package/dist/template-request/template-request.d.ts +100 -0
- package/dist/template-request/template-request.d.ts.map +1 -0
- package/dist/template-request/template-request.js +150 -0
- package/dist/template-request/template-request.schema.json +100 -0
- package/dist/template-request/template-spec.d.ts +83 -0
- package/dist/template-request/template-spec.d.ts.map +1 -0
- package/dist/template-request/template-spec.js +146 -0
- package/dist/template-request/template.schema.json +114 -0
- package/dist/template-request/validate.d.ts +4 -0
- package/dist/template-request/validate.d.ts.map +1 -0
- package/dist/template-request/validate.js +21 -0
- package/dist/wave-runtime.mjs +310 -300
- package/package.json +8 -1
- package/src/ci-audit/index.ts +1 -2
- package/src/ci-product-words.test.ts +23 -0
- package/src/ci-product-words.ts +68 -3
- package/src/ci-product.ts +36 -6
- package/src/cli/commands/init.ts +3 -1
- package/src/cli/handlers/build.ts +5 -1
- package/src/cli/handlers/init.ts +18 -0
- package/src/cli/handlers/lifecycle.ts +13 -0
- package/src/cli/handlers/pr-before-merge.test.ts +1 -1
- package/src/cli/handlers/pr-deploy-inputs.test.ts +1 -1
- package/src/cli/handlers/pr-endpoint.test.ts +1 -1
- package/src/cli/handlers/pr-green.test.ts +1 -1
- package/src/cli/handlers/pr-plan-comment-targets.test.ts +1 -1
- package/src/cli/handlers/pr-plan-flags.test.ts +1 -1
- package/src/cli/handlers/pr-plan-targets.test.ts +1 -1
- package/src/cli/handlers/pr-record.test.ts +34 -2
- package/src/cli/handlers/pr-waves-blocked.test.ts +1 -1
- package/src/cli/handlers/pr-waves.test.ts +1 -1
- package/src/cli/handlers/pr.test.ts +1 -1
- package/src/cli/handlers/pr.ts +86 -31
- package/src/cli/handlers/serve.ts +9 -0
- package/src/cli/main.ts +6 -2
- package/src/cli/mcp/product-tools.test.ts +57 -1
- package/src/cli/mcp/product-tools.ts +67 -15
- package/src/cli/mcp/read-only.ts +2 -1
- package/src/cli/mcp/server.ts +20 -5
- package/src/cli/mcp-config.test.ts +52 -2
- package/src/cli/mcp-config.ts +6 -3
- package/src/cli/parse-args.ts +7 -0
- package/src/cli/registry.ts +8 -0
- package/src/components/auto-release.test.ts +4 -2
- package/src/components/auto-release.ts +9 -5
- package/src/components/capability.ts +10 -0
- package/src/components/deploy-units.test.ts +18 -1
- package/src/components/deploy-units.ts +26 -1
- package/src/components/pr-pipeline.ts +99 -5
- package/src/components/product-actions.test.ts +76 -0
- package/src/components/product-pipeline.ts +21 -2
- package/src/components/row-lease.test.ts +61 -1
- package/src/components/row-lease.ts +48 -7
- package/src/e2e-harness/driver.test.ts +163 -0
- package/src/e2e-harness/driver.ts +86 -1
- package/src/e2e-harness/forgejo.ts +42 -1
- package/src/e2e-harness/index.ts +12 -2
- package/src/e2e-harness/ports.ts +33 -0
- package/src/e2e-harness/scenario.ts +8 -6
- package/src/e2e-harness/schemas/README.md +11 -2
- package/src/e2e-harness/schemas/e2e-scenario.schema.json +43 -3
- package/src/e2e-harness/schemas/index.ts +5 -1
- package/src/e2e-harness/schemas.test.ts +44 -1
- package/src/e2e-harness/steps.ts +4 -0
- package/src/lexicon.ts +9 -0
- package/src/lifecycle/git.test.ts +155 -0
- package/src/lifecycle/git.ts +213 -17
- package/src/lifecycle/lock-rows.test.ts +6 -1
- package/src/lifecycle/lock-rows.ts +58 -7
- package/src/lifecycle/resource-lock-wait.test.ts +292 -0
- package/src/lifecycle/resource-lock.ts +261 -7
- package/src/mcp/types.ts +9 -0
- package/src/op/gate.test.ts +7 -5
- package/src/op/gate.ts +20 -4
- package/src/op/op-waves-after-plan.test.ts +1 -2
- package/src/op/op-waves-ledger-lock.test.ts +208 -0
- package/src/op/op-waves-release-port.ts +1 -1
- package/src/op/op-waves-release.ts +1 -1
- package/src/op/op-waves-run.ts +104 -29
- package/src/op/op-waves.ts +18 -0
- package/src/pr-loop-bundle.test.ts +0 -2
- package/src/pr-loop.ts +1 -2
- package/src/release-floors.ts +1 -1
- package/src/template-request/__fixtures__/request-body.md +41 -0
- package/src/template-request/index.ts +8 -0
- package/src/template-request/request-body.ts +91 -0
- package/src/template-request/template-request.schema.json +100 -0
- package/src/template-request/template-request.test.ts +316 -0
- package/src/template-request/template-request.ts +235 -0
- package/src/template-request/template-spec.ts +176 -0
- package/src/template-request/template.schema.json +114 -0
- package/src/template-request/validate.ts +28 -0
|
@@ -0,0 +1,100 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The template request, template-request/v1 (#4651): "an app named orders
|
|
3
|
+
* from template X at version Y with these inputs", as one JSON document.
|
|
4
|
+
* terragucci, plywood and behold all turn one into a pull request, and this
|
|
5
|
+
* module is where they agree on the document, its refusals and its branch.
|
|
6
|
+
* ./request-body.ts writes the pull request body that carries it.
|
|
7
|
+
*
|
|
8
|
+
* {@link checkTemplateRequest} reads the release catalog for the version's
|
|
9
|
+
* status and attestation, and the version's template.yml (./template-spec.ts)
|
|
10
|
+
* for its inputs. It reads no engine field: the inputs' kinds are
|
|
11
|
+
* engine-neutral.
|
|
12
|
+
*/
|
|
13
|
+
import { type AttestationState, type ReleaseCatalog } from "../lifecycle/release-catalog.js";
|
|
14
|
+
import { type TemplateSpec } from "./template-spec.js";
|
|
15
|
+
/** The first chant that writes and reads template-request/v1 and template.yml/v1 (#4651). */
|
|
16
|
+
export declare const TEMPLATE_REQUEST_FLOOR = "0.124.58";
|
|
17
|
+
/** The request document's `$schema`. */
|
|
18
|
+
export declare const TEMPLATE_REQUEST_SCHEMA_ID: string;
|
|
19
|
+
/** The request's contract version. */
|
|
20
|
+
export declare const TEMPLATE_REQUEST_CONTRACT = 1;
|
|
21
|
+
/** An app or add-on name: a lowercase letter, then up to 39 lowercase letters, digits and -. */
|
|
22
|
+
export declare const REQUEST_NAME_PATTERN: RegExp;
|
|
23
|
+
/** Where a request came from. */
|
|
24
|
+
export type TemplateRequestVia = "form" | "mcp" | "cli";
|
|
25
|
+
/** A template request. */
|
|
26
|
+
export interface TemplateRequest {
|
|
27
|
+
$schema: string;
|
|
28
|
+
contract: 1;
|
|
29
|
+
kind: "app" | "addon";
|
|
30
|
+
/** The template's address, such as `acme/bucket/aws`. */
|
|
31
|
+
template: string;
|
|
32
|
+
/** The version in the catalog, or a digest for a release that names none. */
|
|
33
|
+
version: string;
|
|
34
|
+
app: string;
|
|
35
|
+
/** For kind `addon`: the add-on's name. */
|
|
36
|
+
addon?: string;
|
|
37
|
+
/** The values given, by input name. */
|
|
38
|
+
inputs: Record<string, unknown>;
|
|
39
|
+
/** Who asked, as the forge vouches for it: the login of the run's actor. */
|
|
40
|
+
requestedBy: string;
|
|
41
|
+
/**
|
|
42
|
+
* The person the client says filled the form or asked the agent, when it
|
|
43
|
+
* names one. The forge does not vouch for it; it is shown as claimed.
|
|
44
|
+
*/
|
|
45
|
+
claimedBy?: string;
|
|
46
|
+
via: TemplateRequestVia;
|
|
47
|
+
}
|
|
48
|
+
/** The fields a caller gives {@link makeTemplateRequest}; `$schema` and `contract` are filled in. */
|
|
49
|
+
export type TemplateRequestInput = Omit<TemplateRequest, "$schema" | "contract">;
|
|
50
|
+
/**
|
|
51
|
+
* Why a request is refused. `invalid` is a document the schema refuses for
|
|
52
|
+
* a reason no other code names (a missing field, a `via` it does not know).
|
|
53
|
+
*/
|
|
54
|
+
export type TemplateRequestRefusalCode = "unknown-version" | "not-active" | "unsigned" | "unknown-input" | "missing-input" | "sensitive-input" | "input-type" | "bad-name" | "invalid";
|
|
55
|
+
/** Every refusal code, in the order {@link checkTemplateRequest} checks them. */
|
|
56
|
+
export declare const TEMPLATE_REQUEST_REFUSAL_CODES: readonly TemplateRequestRefusalCode[];
|
|
57
|
+
/** One refusal: its code, the request field it is about, and a sentence naming that field. */
|
|
58
|
+
export interface TemplateRequestRefusal {
|
|
59
|
+
code: TemplateRequestRefusalCode;
|
|
60
|
+
/** `app`, `addon`, `version`, `inputs.<name>`, or the schema path for `invalid`. */
|
|
61
|
+
field: string;
|
|
62
|
+
reason: string;
|
|
63
|
+
}
|
|
64
|
+
export type TemplateRequestCheck = {
|
|
65
|
+
ok: true;
|
|
66
|
+
request: TemplateRequest;
|
|
67
|
+
} | {
|
|
68
|
+
ok: false;
|
|
69
|
+
refusals: TemplateRequestRefusal[];
|
|
70
|
+
};
|
|
71
|
+
export interface CheckTemplateRequestOptions {
|
|
72
|
+
/**
|
|
73
|
+
* The catalog component the template is. Absent: the component named
|
|
74
|
+
* `request.template`. A product that lists components by path looks the
|
|
75
|
+
* address up itself and passes the name here.
|
|
76
|
+
*/
|
|
77
|
+
component?: string;
|
|
78
|
+
/** The lowest attestation a version may have. Default `signed`; `unsigned` accepts any. */
|
|
79
|
+
require?: AttestationState;
|
|
80
|
+
}
|
|
81
|
+
/** Fill `$schema` and `contract` into a request. */
|
|
82
|
+
export declare function makeTemplateRequest(input: TemplateRequestInput): TemplateRequest;
|
|
83
|
+
/** The schema problems of a request document, one line each; empty when it is valid. */
|
|
84
|
+
export declare function validateTemplateRequest(doc: unknown): string[];
|
|
85
|
+
/**
|
|
86
|
+
* Check a request against the catalog and the version's template.yml.
|
|
87
|
+
* Returns every refusal, each with its code and a reason naming the field.
|
|
88
|
+
* A bad name or a document the schema refuses stops the check there, and so
|
|
89
|
+
* does a version the catalog does not list; past that, the version's status
|
|
90
|
+
* and attestation and each input are all checked.
|
|
91
|
+
*/
|
|
92
|
+
export declare function checkTemplateRequest(request: unknown, catalog: ReleaseCatalog, templateSpec: TemplateSpec, options?: CheckTemplateRequestOptions): TemplateRequestCheck;
|
|
93
|
+
/**
|
|
94
|
+
* A template's name as a branch uses it: the second-to-last segment of an
|
|
95
|
+
* address with three or more (`acme/bucket/aws` is `bucket`), else the last.
|
|
96
|
+
*/
|
|
97
|
+
export declare function templateName(template: string): string;
|
|
98
|
+
/** The request's branch: `request/<template-name>/<app>`, and `/<addon>` after it for an add-on. */
|
|
99
|
+
export declare function requestBranch(request: Pick<TemplateRequest, "template" | "app"> & Partial<Pick<TemplateRequest, "kind" | "addon">>): string;
|
|
100
|
+
//# sourceMappingURL=template-request.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"template-request.d.ts","sourceRoot":"","sources":["../../src/template-request/template-request.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,150 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The template request, template-request/v1 (#4651): "an app named orders
|
|
3
|
+
* from template X at version Y with these inputs", as one JSON document.
|
|
4
|
+
* terragucci, plywood and behold all turn one into a pull request, and this
|
|
5
|
+
* module is where they agree on the document, its refusals and its branch.
|
|
6
|
+
* ./request-body.ts writes the pull request body that carries it.
|
|
7
|
+
*
|
|
8
|
+
* {@link checkTemplateRequest} reads the release catalog for the version's
|
|
9
|
+
* status and attestation, and the version's template.yml (./template-spec.ts)
|
|
10
|
+
* for its inputs. It reads no engine field: the inputs' kinds are
|
|
11
|
+
* engine-neutral.
|
|
12
|
+
*/
|
|
13
|
+
import schema from "./template-request.schema.json" with { type: "json" };
|
|
14
|
+
import { NEXT_RELEASE } from "../release-floors.js";
|
|
15
|
+
import { catalogVersion } from "../lifecycle/release-catalog.js";
|
|
16
|
+
import { inputKindProblem, inputRequired, isAppOutputRef } from "./template-spec.js";
|
|
17
|
+
import { schemaProblems } from "./validate.js";
|
|
18
|
+
/** The first chant that writes and reads template-request/v1 and template.yml/v1 (#4651). */
|
|
19
|
+
export const TEMPLATE_REQUEST_FLOOR = NEXT_RELEASE;
|
|
20
|
+
/** The request document's `$schema`. */
|
|
21
|
+
export const TEMPLATE_REQUEST_SCHEMA_ID = schema.$id;
|
|
22
|
+
/** The request's contract version. */
|
|
23
|
+
export const TEMPLATE_REQUEST_CONTRACT = 1;
|
|
24
|
+
/** An app or add-on name: a lowercase letter, then up to 39 lowercase letters, digits and -. */
|
|
25
|
+
export const REQUEST_NAME_PATTERN = /^[a-z][a-z0-9-]{0,39}$/;
|
|
26
|
+
/** Every refusal code, in the order {@link checkTemplateRequest} checks them. */
|
|
27
|
+
export const TEMPLATE_REQUEST_REFUSAL_CODES = [
|
|
28
|
+
"bad-name",
|
|
29
|
+
"invalid",
|
|
30
|
+
"unknown-version",
|
|
31
|
+
"not-active",
|
|
32
|
+
"unsigned",
|
|
33
|
+
"unknown-input",
|
|
34
|
+
"sensitive-input",
|
|
35
|
+
"input-type",
|
|
36
|
+
"missing-input",
|
|
37
|
+
];
|
|
38
|
+
const ATTESTATION_RANK = { unsigned: 0, signed: 1, verified: 2 };
|
|
39
|
+
/** Fill `$schema` and `contract` into a request. */
|
|
40
|
+
export function makeTemplateRequest(input) {
|
|
41
|
+
const { kind, template, version, app, addon, inputs, requestedBy, claimedBy, via } = input;
|
|
42
|
+
return {
|
|
43
|
+
$schema: TEMPLATE_REQUEST_SCHEMA_ID,
|
|
44
|
+
contract: TEMPLATE_REQUEST_CONTRACT,
|
|
45
|
+
kind,
|
|
46
|
+
template,
|
|
47
|
+
version,
|
|
48
|
+
app,
|
|
49
|
+
...(addon !== undefined ? { addon } : {}),
|
|
50
|
+
inputs,
|
|
51
|
+
requestedBy,
|
|
52
|
+
...(claimedBy !== undefined ? { claimedBy } : {}),
|
|
53
|
+
via,
|
|
54
|
+
};
|
|
55
|
+
}
|
|
56
|
+
/** The schema problems of a request document, one line each; empty when it is valid. */
|
|
57
|
+
export function validateTemplateRequest(doc) {
|
|
58
|
+
return schemaProblems(TEMPLATE_REQUEST_SCHEMA_ID, doc);
|
|
59
|
+
}
|
|
60
|
+
const isRecord = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
|
|
61
|
+
/**
|
|
62
|
+
* Check a request against the catalog and the version's template.yml.
|
|
63
|
+
* Returns every refusal, each with its code and a reason naming the field.
|
|
64
|
+
* A bad name or a document the schema refuses stops the check there, and so
|
|
65
|
+
* does a version the catalog does not list; past that, the version's status
|
|
66
|
+
* and attestation and each input are all checked.
|
|
67
|
+
*/
|
|
68
|
+
export function checkTemplateRequest(request, catalog, templateSpec, options = {}) {
|
|
69
|
+
const refused = (refusals) => ({ ok: false, refusals });
|
|
70
|
+
// Names first, so a bad one reads as bad-name and not as a schema pattern.
|
|
71
|
+
const names = [];
|
|
72
|
+
const probe = isRecord(request) ? { ...request } : {};
|
|
73
|
+
for (const field of ["app", "addon"]) {
|
|
74
|
+
const v = probe[field];
|
|
75
|
+
if (typeof v !== "string" || REQUEST_NAME_PATTERN.test(v))
|
|
76
|
+
continue;
|
|
77
|
+
names.push({
|
|
78
|
+
code: "bad-name",
|
|
79
|
+
field,
|
|
80
|
+
reason: `${field} ${JSON.stringify(v)} is not a name: a lowercase letter, then up to 39 lowercase letters, digits and -`,
|
|
81
|
+
});
|
|
82
|
+
probe[field] = "x";
|
|
83
|
+
}
|
|
84
|
+
if (names.length > 0)
|
|
85
|
+
return refused(names);
|
|
86
|
+
const problems = validateTemplateRequest(isRecord(request) ? probe : request);
|
|
87
|
+
if (problems.length > 0) {
|
|
88
|
+
return refused(problems.map((p) => ({ code: "invalid", field: p.split(" ")[0], reason: `the request ${p}` })));
|
|
89
|
+
}
|
|
90
|
+
const req = request;
|
|
91
|
+
const componentName = options.component ?? req.template;
|
|
92
|
+
const component = catalog.components.find((c) => c.name === componentName);
|
|
93
|
+
if (!component) {
|
|
94
|
+
return refused([{ code: "unknown-version", field: "version", reason: `version ${JSON.stringify(req.version)}: the catalog lists no template ${JSON.stringify(componentName)}` }]);
|
|
95
|
+
}
|
|
96
|
+
const version = catalogVersion(catalog, component.name, req.version);
|
|
97
|
+
if (!version) {
|
|
98
|
+
const listed = component.versions.map((v) => v.version ?? v.digest).join(", ") || "none";
|
|
99
|
+
return refused([{ code: "unknown-version", field: "version", reason: `version ${JSON.stringify(req.version)} of ${req.template} is not in the catalog (it lists ${listed})` }]);
|
|
100
|
+
}
|
|
101
|
+
const refusals = [];
|
|
102
|
+
if (version.status.state !== "active") {
|
|
103
|
+
const instead = version.status.replacement ? `; use ${version.status.replacement}` : "";
|
|
104
|
+
refusals.push({ code: "not-active", field: "version", reason: `version ${req.version} of ${req.template} is ${version.status.state}${instead}` });
|
|
105
|
+
}
|
|
106
|
+
const require = options.require ?? "signed";
|
|
107
|
+
if (ATTESTATION_RANK[version.attestation.state] < ATTESTATION_RANK[require]) {
|
|
108
|
+
refusals.push({ code: "unsigned", field: "version", reason: `version ${req.version} of ${req.template} is ${version.attestation.state}, and requests need ${require}` });
|
|
109
|
+
}
|
|
110
|
+
const byName = new Map(templateSpec.inputs.map((i) => [i.name, i]));
|
|
111
|
+
for (const [name, value] of Object.entries(req.inputs)) {
|
|
112
|
+
const field = `inputs.${name}`;
|
|
113
|
+
const input = byName.get(name);
|
|
114
|
+
if (!input) {
|
|
115
|
+
refusals.push({ code: "unknown-input", field, reason: `${field}: ${req.template} ${req.version} has no input ${JSON.stringify(name)}` });
|
|
116
|
+
continue;
|
|
117
|
+
}
|
|
118
|
+
if (input.sensitive) {
|
|
119
|
+
refusals.push({ code: "sensitive-input", field, reason: `${field} is sensitive, and a request is written into a pull request; the app reads it from its secret store` });
|
|
120
|
+
continue;
|
|
121
|
+
}
|
|
122
|
+
// An add-on's `app.<output>` names the app module's output; the renderer resolves it.
|
|
123
|
+
if (req.addon !== undefined && isAppOutputRef(value))
|
|
124
|
+
continue;
|
|
125
|
+
const p = inputKindProblem(input, value);
|
|
126
|
+
if (!p)
|
|
127
|
+
continue;
|
|
128
|
+
const why = isAppOutputRef(value) ? `; ${JSON.stringify(value)} reads as an app output, and only an add-on request can name one` : "";
|
|
129
|
+
refusals.push({ code: "input-type", field, reason: `${field} ${p}${why}` });
|
|
130
|
+
}
|
|
131
|
+
for (const input of templateSpec.inputs) {
|
|
132
|
+
if (input.sensitive || !inputRequired(input) || input.name in req.inputs)
|
|
133
|
+
continue;
|
|
134
|
+
refusals.push({ code: "missing-input", field: `inputs.${input.name}`, reason: `inputs.${input.name} is required by ${req.template} ${req.version} and the request gives none` });
|
|
135
|
+
}
|
|
136
|
+
return refusals.length > 0 ? refused(refusals) : { ok: true, request: req };
|
|
137
|
+
}
|
|
138
|
+
/**
|
|
139
|
+
* A template's name as a branch uses it: the second-to-last segment of an
|
|
140
|
+
* address with three or more (`acme/bucket/aws` is `bucket`), else the last.
|
|
141
|
+
*/
|
|
142
|
+
export function templateName(template) {
|
|
143
|
+
const parts = template.split("/").filter(Boolean);
|
|
144
|
+
return (parts.length >= 3 ? parts[parts.length - 2] : parts[parts.length - 1]) ?? template;
|
|
145
|
+
}
|
|
146
|
+
/** The request's branch: `request/<template-name>/<app>`, and `/<addon>` after it for an add-on. */
|
|
147
|
+
export function requestBranch(request) {
|
|
148
|
+
const base = `request/${templateName(request.template)}/${request.app}`;
|
|
149
|
+
return request.addon !== undefined ? `${base}/${request.addon}` : base;
|
|
150
|
+
}
|
|
@@ -0,0 +1,100 @@
|
|
|
1
|
+
{
|
|
2
|
+
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
|
3
|
+
"$id": "https://intentius.io/chant/schemas/template-request/v1/template-request.schema.json",
|
|
4
|
+
"title": "chant template request",
|
|
5
|
+
"description": "A request for an app, or an add-on to an app, made from one version of a template in a release catalog, version 1 of its contract. A product turns it into a pull request on the branch requestBranch names, with requestBody as the body; the body carries this document in a fenced block whose info string is `json` and this schema's id, so a reader recovers it from the pull request alone. checkTemplateRequest refuses a request against the catalog and the version's template.yml (template.schema.json). Readers ignore fields they do not know; a field is only ever added within a version.",
|
|
6
|
+
"type": "object",
|
|
7
|
+
"required": [
|
|
8
|
+
"$schema",
|
|
9
|
+
"contract",
|
|
10
|
+
"kind",
|
|
11
|
+
"template",
|
|
12
|
+
"version",
|
|
13
|
+
"app",
|
|
14
|
+
"inputs",
|
|
15
|
+
"requestedBy",
|
|
16
|
+
"via"
|
|
17
|
+
],
|
|
18
|
+
"properties": {
|
|
19
|
+
"$schema": {
|
|
20
|
+
"const": "https://intentius.io/chant/schemas/template-request/v1/template-request.schema.json"
|
|
21
|
+
},
|
|
22
|
+
"contract": {
|
|
23
|
+
"const": 1
|
|
24
|
+
},
|
|
25
|
+
"kind": {
|
|
26
|
+
"enum": [
|
|
27
|
+
"app",
|
|
28
|
+
"addon"
|
|
29
|
+
],
|
|
30
|
+
"description": "app: a new app. addon: an add-on to the app named in `app`, which must exist."
|
|
31
|
+
},
|
|
32
|
+
"template": {
|
|
33
|
+
"type": "string",
|
|
34
|
+
"pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*(/[A-Za-z0-9][A-Za-z0-9._-]*)*$",
|
|
35
|
+
"description": "The template's address, such as `acme/bucket/aws` (namespace, name, system). The branch uses its name: the second-to-last segment of an address with three or more, else the last."
|
|
36
|
+
},
|
|
37
|
+
"version": {
|
|
38
|
+
"type": "string",
|
|
39
|
+
"minLength": 1,
|
|
40
|
+
"description": "The version in the catalog, or its digest for a release that names no version."
|
|
41
|
+
},
|
|
42
|
+
"app": {
|
|
43
|
+
"type": "string",
|
|
44
|
+
"pattern": "^[a-z][a-z0-9-]{0,39}$",
|
|
45
|
+
"description": "The app's name: a lowercase letter, then up to 39 lowercase letters, digits and -."
|
|
46
|
+
},
|
|
47
|
+
"addon": {
|
|
48
|
+
"type": "string",
|
|
49
|
+
"pattern": "^[a-z][a-z0-9-]{0,39}$",
|
|
50
|
+
"description": "For kind addon: the add-on's name, with the same rule as `app`."
|
|
51
|
+
},
|
|
52
|
+
"inputs": {
|
|
53
|
+
"type": "object",
|
|
54
|
+
"description": "The values given, by input name. An input left out takes its default. A sensitive input is never here. In an add-on request, a string `app.<output>` names an output of the app's module, for an input of any kind; the engine's renderer resolves it. In an app request it is a plain string and is checked against the input's kind.",
|
|
55
|
+
"additionalProperties": true
|
|
56
|
+
},
|
|
57
|
+
"requestedBy": {
|
|
58
|
+
"type": "string",
|
|
59
|
+
"minLength": 1,
|
|
60
|
+
"description": "Who asked, as the forge vouches for it: the login of the run's actor, a person or the identity an agent runs as."
|
|
61
|
+
},
|
|
62
|
+
"claimedBy": {
|
|
63
|
+
"type": "string",
|
|
64
|
+
"minLength": 1,
|
|
65
|
+
"description": "The person the client says filled the form or asked the agent, when it names one. The forge does not vouch for it, so a reader shows it as claimed, next to requestedBy."
|
|
66
|
+
},
|
|
67
|
+
"via": {
|
|
68
|
+
"enum": [
|
|
69
|
+
"form",
|
|
70
|
+
"mcp",
|
|
71
|
+
"cli"
|
|
72
|
+
],
|
|
73
|
+
"description": "Where the request came from: a form, an agent over MCP, or the command line."
|
|
74
|
+
}
|
|
75
|
+
},
|
|
76
|
+
"allOf": [
|
|
77
|
+
{
|
|
78
|
+
"if": {
|
|
79
|
+
"properties": {
|
|
80
|
+
"kind": {
|
|
81
|
+
"const": "addon"
|
|
82
|
+
}
|
|
83
|
+
}
|
|
84
|
+
},
|
|
85
|
+
"then": {
|
|
86
|
+
"properties": {
|
|
87
|
+
"addon": true
|
|
88
|
+
},
|
|
89
|
+
"required": [
|
|
90
|
+
"addon"
|
|
91
|
+
]
|
|
92
|
+
},
|
|
93
|
+
"else": {
|
|
94
|
+
"properties": {
|
|
95
|
+
"addon": false
|
|
96
|
+
}
|
|
97
|
+
}
|
|
98
|
+
}
|
|
99
|
+
]
|
|
100
|
+
}
|
|
@@ -0,0 +1,83 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* template.yml, version 1 (#4651, ruling B of #4642): what a template asks
|
|
3
|
+
* for when someone requests an app or an add-on from it. The file sits in
|
|
4
|
+
* the template's signed release; a form shows one field per input, and an
|
|
5
|
+
* agent or a command line reads the same list.
|
|
6
|
+
*
|
|
7
|
+
* Each input has an engine-neutral kind (`string`, `number`, `bool`,
|
|
8
|
+
* `list`, `map`, `object`, with `of` naming a list's or map's element kind).
|
|
9
|
+
* Core checks request values against the kind and never parses an engine's
|
|
10
|
+
* own type syntax; an engine maps the kinds to its types (the terraform
|
|
11
|
+
* lexicon, #4652).
|
|
12
|
+
*
|
|
13
|
+
* In an add-on request, a value `app.<output>` names an output of the app's
|
|
14
|
+
* own module, whatever the input's kind. Core accepts it as is and leaves
|
|
15
|
+
* the engine's renderer to resolve it and refuse an output the module lacks.
|
|
16
|
+
*/
|
|
17
|
+
/** The template.yml `$schema`, when the file names one. */
|
|
18
|
+
export declare const TEMPLATE_SPEC_SCHEMA_ID: string;
|
|
19
|
+
/** The template.yml contract version. */
|
|
20
|
+
export declare const TEMPLATE_SPEC_CONTRACT = 1;
|
|
21
|
+
/** A kind whose values are JSON scalars. */
|
|
22
|
+
export type TemplateScalarKind = "string" | "number" | "bool";
|
|
23
|
+
/** An input's engine-neutral kind. */
|
|
24
|
+
export type TemplateInputKind = TemplateScalarKind | "list" | "map" | "object";
|
|
25
|
+
/** Every input kind, in the order the schema lists them. */
|
|
26
|
+
export declare const TEMPLATE_INPUT_KINDS: readonly TemplateInputKind[];
|
|
27
|
+
/** One input of a template. */
|
|
28
|
+
export interface TemplateInput {
|
|
29
|
+
name: string;
|
|
30
|
+
kind: TemplateInputKind;
|
|
31
|
+
/** For a list or a map: the kind of each element or value. Absent: any JSON value. */
|
|
32
|
+
of?: TemplateScalarKind;
|
|
33
|
+
/** The form field's label. Absent: the name. */
|
|
34
|
+
label?: string;
|
|
35
|
+
description?: string;
|
|
36
|
+
/** The value a request that gives none takes. */
|
|
37
|
+
default?: unknown;
|
|
38
|
+
/** Absent: true when there is no default. */
|
|
39
|
+
required?: boolean;
|
|
40
|
+
/** A secret, which a request never carries. */
|
|
41
|
+
sensitive?: boolean;
|
|
42
|
+
}
|
|
43
|
+
/** A parsed template.yml. */
|
|
44
|
+
export interface TemplateSpec {
|
|
45
|
+
$schema?: string;
|
|
46
|
+
contract: 1;
|
|
47
|
+
/** Absent: `app`. */
|
|
48
|
+
kind?: "app" | "addon";
|
|
49
|
+
description: string;
|
|
50
|
+
inputs: TemplateInput[];
|
|
51
|
+
}
|
|
52
|
+
/** Thrown when a template.yml is not valid, with one line per problem. */
|
|
53
|
+
export declare class TemplateSpecError extends Error {
|
|
54
|
+
readonly problems: string[];
|
|
55
|
+
constructor(problems: string[]);
|
|
56
|
+
}
|
|
57
|
+
/** Whether a request must give `input`: its own `required`, else true when it has no default. */
|
|
58
|
+
export declare function inputRequired(input: TemplateInput): boolean;
|
|
59
|
+
/** The JSON type a value has, as a problem line names it. */
|
|
60
|
+
export declare function jsonKindOf(value: unknown): string;
|
|
61
|
+
/** An app-output reference, `app.<output>`, with the output in group 1. */
|
|
62
|
+
export declare const APP_OUTPUT_REF: RegExp;
|
|
63
|
+
/** The output an `app.<output>` value names, or undefined when `value` is not one. */
|
|
64
|
+
export declare function appOutputRef(value: unknown): string | undefined;
|
|
65
|
+
/** True when `value` is an app-output reference, `app.<output>`. */
|
|
66
|
+
export declare function isAppOutputRef(value: unknown): value is string;
|
|
67
|
+
/**
|
|
68
|
+
* Why `value` is not of `input`'s kind, or undefined when it is. A null is
|
|
69
|
+
* never of a kind: a request that wants the default leaves the input out.
|
|
70
|
+
*/
|
|
71
|
+
export declare function inputKindProblem(input: Pick<TemplateInput, "kind" | "of">, value: unknown): string | undefined;
|
|
72
|
+
/**
|
|
73
|
+
* Every problem with a template.yml document, one line each: the schema's,
|
|
74
|
+
* then two inputs with one name, a default that is not of its input's kind,
|
|
75
|
+
* and an input both required and given a default.
|
|
76
|
+
*/
|
|
77
|
+
export declare function templateSpecProblems(doc: unknown): string[];
|
|
78
|
+
/**
|
|
79
|
+
* Read a template.yml from its YAML text or its parsed value. Throws
|
|
80
|
+
* {@link TemplateSpecError} when it does not parse or is not valid.
|
|
81
|
+
*/
|
|
82
|
+
export declare function parseTemplateSpec(text: string | unknown): TemplateSpec;
|
|
83
|
+
//# sourceMappingURL=template-spec.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"template-spec.d.ts","sourceRoot":"","sources":["../../src/template-request/template-spec.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAMH,2DAA2D;AAC3D,eAAO,MAAM,uBAAuB,EAAE,MAAmB,CAAC;AAE1D,yCAAyC;AACzC,eAAO,MAAM,sBAAsB,IAAI,CAAC;AAExC,4CAA4C;AAC5C,MAAM,MAAM,kBAAkB,GAAG,QAAQ,GAAG,QAAQ,GAAG,MAAM,CAAC;AAE9D,sCAAsC;AACtC,MAAM,MAAM,iBAAiB,GAAG,kBAAkB,GAAG,MAAM,GAAG,KAAK,GAAG,QAAQ,CAAC;AAE/E,4DAA4D;AAC5D,eAAO,MAAM,oBAAoB,EAAE,SAAS,iBAAiB,EAA0D,CAAC;AAExH,+BAA+B;AAC/B,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,iBAAiB,CAAC;IACxB,sFAAsF;IACtF,EAAE,CAAC,EAAE,kBAAkB,CAAC;IACxB,gDAAgD;IAChD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iDAAiD;IACjD,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,6CAA6C;IAC7C,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,+CAA+C;IAC/C,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,6BAA6B;AAC7B,MAAM,WAAW,YAAY;IAC3B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,CAAC,CAAC;IACZ,qBAAqB;IACrB,IAAI,CAAC,EAAE,KAAK,GAAG,OAAO,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,aAAa,EAAE,CAAC;CACzB;AAED,0EAA0E;AAC1E,qBAAa,iBAAkB,SAAQ,KAAK;aACd,QAAQ,EAAE,MAAM,EAAE;IAA9C,YAA4B,QAAQ,EAAE,MAAM,EAAE,EAG7C;CACF;AAED,iGAAiG;AACjG,wBAAgB,aAAa,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAE3D;AAED,6DAA6D;AAC7D,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAMjD;AAUD,2EAA2E;AAC3E,eAAO,MAAM,cAAc,EAAE,MAA2C,CAAC;AAEzE,sFAAsF;AACtF,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAE/D;AAED,oEAAoE;AACpE,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAE9D;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,IAAI,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC,EAAE,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAuB9G;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,EAAE,CAgB3D;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,YAAY,CAatE"}
|
|
@@ -0,0 +1,146 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* template.yml, version 1 (#4651, ruling B of #4642): what a template asks
|
|
3
|
+
* for when someone requests an app or an add-on from it. The file sits in
|
|
4
|
+
* the template's signed release; a form shows one field per input, and an
|
|
5
|
+
* agent or a command line reads the same list.
|
|
6
|
+
*
|
|
7
|
+
* Each input has an engine-neutral kind (`string`, `number`, `bool`,
|
|
8
|
+
* `list`, `map`, `object`, with `of` naming a list's or map's element kind).
|
|
9
|
+
* Core checks request values against the kind and never parses an engine's
|
|
10
|
+
* own type syntax; an engine maps the kinds to its types (the terraform
|
|
11
|
+
* lexicon, #4652).
|
|
12
|
+
*
|
|
13
|
+
* In an add-on request, a value `app.<output>` names an output of the app's
|
|
14
|
+
* own module, whatever the input's kind. Core accepts it as is and leaves
|
|
15
|
+
* the engine's renderer to resolve it and refuse an output the module lacks.
|
|
16
|
+
*/
|
|
17
|
+
import schema from "./template.schema.json" with { type: "json" };
|
|
18
|
+
import { parseYAMLDocument, YAMLParseError } from "../yaml.js";
|
|
19
|
+
import { schemaProblems } from "./validate.js";
|
|
20
|
+
/** The template.yml `$schema`, when the file names one. */
|
|
21
|
+
export const TEMPLATE_SPEC_SCHEMA_ID = schema.$id;
|
|
22
|
+
/** The template.yml contract version. */
|
|
23
|
+
export const TEMPLATE_SPEC_CONTRACT = 1;
|
|
24
|
+
/** Every input kind, in the order the schema lists them. */
|
|
25
|
+
export const TEMPLATE_INPUT_KINDS = ["string", "number", "bool", "list", "map", "object"];
|
|
26
|
+
/** Thrown when a template.yml is not valid, with one line per problem. */
|
|
27
|
+
export class TemplateSpecError extends Error {
|
|
28
|
+
constructor(problems) {
|
|
29
|
+
super(`template.yml is not valid: ${problems.join("; ")}`);
|
|
30
|
+
this.problems = problems;
|
|
31
|
+
this.name = "TemplateSpecError";
|
|
32
|
+
}
|
|
33
|
+
}
|
|
34
|
+
/** Whether a request must give `input`: its own `required`, else true when it has no default. */
|
|
35
|
+
export function inputRequired(input) {
|
|
36
|
+
return input.required ?? !("default" in input);
|
|
37
|
+
}
|
|
38
|
+
/** The JSON type a value has, as a problem line names it. */
|
|
39
|
+
export function jsonKindOf(value) {
|
|
40
|
+
if (value === null)
|
|
41
|
+
return "null";
|
|
42
|
+
if (Array.isArray(value))
|
|
43
|
+
return "list";
|
|
44
|
+
if (typeof value === "boolean")
|
|
45
|
+
return "bool";
|
|
46
|
+
if (typeof value === "object")
|
|
47
|
+
return "object";
|
|
48
|
+
return typeof value;
|
|
49
|
+
}
|
|
50
|
+
const isPlainObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
|
|
51
|
+
function scalarFits(kind, value) {
|
|
52
|
+
if (kind === "string")
|
|
53
|
+
return typeof value === "string";
|
|
54
|
+
if (kind === "number")
|
|
55
|
+
return typeof value === "number" && Number.isFinite(value);
|
|
56
|
+
return typeof value === "boolean";
|
|
57
|
+
}
|
|
58
|
+
/** An app-output reference, `app.<output>`, with the output in group 1. */
|
|
59
|
+
export const APP_OUTPUT_REF = /^app\.([A-Za-z_][A-Za-z0-9_-]*)$/;
|
|
60
|
+
/** The output an `app.<output>` value names, or undefined when `value` is not one. */
|
|
61
|
+
export function appOutputRef(value) {
|
|
62
|
+
return typeof value === "string" ? APP_OUTPUT_REF.exec(value)?.[1] : undefined;
|
|
63
|
+
}
|
|
64
|
+
/** True when `value` is an app-output reference, `app.<output>`. */
|
|
65
|
+
export function isAppOutputRef(value) {
|
|
66
|
+
return appOutputRef(value) !== undefined;
|
|
67
|
+
}
|
|
68
|
+
/**
|
|
69
|
+
* Why `value` is not of `input`'s kind, or undefined when it is. A null is
|
|
70
|
+
* never of a kind: a request that wants the default leaves the input out.
|
|
71
|
+
*/
|
|
72
|
+
export function inputKindProblem(input, value) {
|
|
73
|
+
const want = input.of ? `${input.kind} of ${input.of}` : input.kind;
|
|
74
|
+
const bad = (detail) => `is ${detail ?? jsonKindOf(value)}, and the input is a ${want}`;
|
|
75
|
+
switch (input.kind) {
|
|
76
|
+
case "string":
|
|
77
|
+
case "number":
|
|
78
|
+
case "bool":
|
|
79
|
+
return scalarFits(input.kind, value) ? undefined : bad();
|
|
80
|
+
case "list": {
|
|
81
|
+
if (!Array.isArray(value))
|
|
82
|
+
return bad();
|
|
83
|
+
if (!input.of)
|
|
84
|
+
return undefined;
|
|
85
|
+
const at = value.findIndex((v) => !scalarFits(input.of, v));
|
|
86
|
+
return at < 0 ? undefined : bad(`a list whose element ${at} is ${jsonKindOf(value[at])}`);
|
|
87
|
+
}
|
|
88
|
+
case "map": {
|
|
89
|
+
if (!isPlainObject(value))
|
|
90
|
+
return bad();
|
|
91
|
+
if (!input.of)
|
|
92
|
+
return undefined;
|
|
93
|
+
const key = Object.keys(value).find((k) => !scalarFits(input.of, value[k]));
|
|
94
|
+
return key === undefined ? undefined : bad(`a map whose ${JSON.stringify(key)} is ${jsonKindOf(value[key])}`);
|
|
95
|
+
}
|
|
96
|
+
case "object":
|
|
97
|
+
return isPlainObject(value) ? undefined : bad();
|
|
98
|
+
}
|
|
99
|
+
}
|
|
100
|
+
/**
|
|
101
|
+
* Every problem with a template.yml document, one line each: the schema's,
|
|
102
|
+
* then two inputs with one name, a default that is not of its input's kind,
|
|
103
|
+
* and an input both required and given a default.
|
|
104
|
+
*/
|
|
105
|
+
export function templateSpecProblems(doc) {
|
|
106
|
+
const problems = schemaProblems(TEMPLATE_SPEC_SCHEMA_ID, doc);
|
|
107
|
+
if (problems.length > 0)
|
|
108
|
+
return problems;
|
|
109
|
+
const spec = doc;
|
|
110
|
+
const seen = new Set();
|
|
111
|
+
spec.inputs.forEach((input, i) => {
|
|
112
|
+
const where = `/inputs/${i} (${input.name})`;
|
|
113
|
+
if (seen.has(input.name))
|
|
114
|
+
problems.push(`${where} repeats the name ${JSON.stringify(input.name)}`);
|
|
115
|
+
seen.add(input.name);
|
|
116
|
+
if ("default" in input) {
|
|
117
|
+
const p = inputKindProblem(input, input.default);
|
|
118
|
+
if (p)
|
|
119
|
+
problems.push(`${where} default ${p}`);
|
|
120
|
+
if (input.required === true)
|
|
121
|
+
problems.push(`${where} is required and has a default; an input with a default is optional`);
|
|
122
|
+
}
|
|
123
|
+
});
|
|
124
|
+
return problems;
|
|
125
|
+
}
|
|
126
|
+
/**
|
|
127
|
+
* Read a template.yml from its YAML text or its parsed value. Throws
|
|
128
|
+
* {@link TemplateSpecError} when it does not parse or is not valid.
|
|
129
|
+
*/
|
|
130
|
+
export function parseTemplateSpec(text) {
|
|
131
|
+
let doc = text;
|
|
132
|
+
if (typeof text === "string") {
|
|
133
|
+
try {
|
|
134
|
+
doc = parseYAMLDocument(text);
|
|
135
|
+
}
|
|
136
|
+
catch (e) {
|
|
137
|
+
if (e instanceof YAMLParseError)
|
|
138
|
+
throw new TemplateSpecError([`not YAML: ${e.message}`]);
|
|
139
|
+
throw e;
|
|
140
|
+
}
|
|
141
|
+
}
|
|
142
|
+
const problems = templateSpecProblems(doc);
|
|
143
|
+
if (problems.length > 0)
|
|
144
|
+
throw new TemplateSpecError(problems);
|
|
145
|
+
return doc;
|
|
146
|
+
}
|