simpler-forms 0.1.0-alpha.0 → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (90) hide show
  1. package/README.md +221 -76
  2. package/dist/src/casing.d.ts +43 -0
  3. package/dist/src/casing.js +146 -0
  4. package/dist/src/casing.js.map +1 -0
  5. package/dist/src/decorators/index.d.ts +1 -0
  6. package/dist/src/decorators/index.js +1 -0
  7. package/dist/src/decorators/index.js.map +1 -1
  8. package/dist/src/decorators/mapping.d.ts +11 -0
  9. package/dist/src/decorators/mapping.js +22 -0
  10. package/dist/src/decorators/mapping.js.map +1 -0
  11. package/dist/src/decorators/meta.d.ts +13 -3
  12. package/dist/src/decorators/meta.js +31 -4
  13. package/dist/src/decorators/meta.js.map +1 -1
  14. package/dist/src/decorators/shared.d.ts +10 -0
  15. package/dist/src/decorators/shared.js +8 -0
  16. package/dist/src/decorators/shared.js.map +1 -1
  17. package/dist/src/decorators/ui.d.ts +33 -12
  18. package/dist/src/decorators/ui.js +39 -43
  19. package/dist/src/decorators/ui.js.map +1 -1
  20. package/dist/src/emitter.d.ts +8 -0
  21. package/dist/src/emitter.js +48 -13
  22. package/dist/src/emitter.js.map +1 -1
  23. package/dist/src/emitters/block-ui.d.ts +17 -3
  24. package/dist/src/emitters/block-ui.js +144 -124
  25. package/dist/src/emitters/block-ui.js.map +1 -1
  26. package/dist/src/emitters/layout-ui.d.ts +12 -0
  27. package/dist/src/emitters/layout-ui.js +225 -0
  28. package/dist/src/emitters/layout-ui.js.map +1 -0
  29. package/dist/src/emitters/overlay.d.ts +3 -6
  30. package/dist/src/emitters/overlay.js +3 -86
  31. package/dist/src/emitters/overlay.js.map +1 -1
  32. package/dist/src/forms.d.ts +23 -0
  33. package/dist/src/forms.js +54 -0
  34. package/dist/src/forms.js.map +1 -0
  35. package/dist/src/index.d.ts +17 -6
  36. package/dist/src/index.js +14 -3
  37. package/dist/src/index.js.map +1 -1
  38. package/dist/src/layout.d.ts +50 -0
  39. package/dist/src/layout.js +397 -0
  40. package/dist/src/layout.js.map +1 -0
  41. package/dist/src/lib.d.ts +485 -39
  42. package/dist/src/lib.js +216 -16
  43. package/dist/src/lib.js.map +1 -1
  44. package/dist/src/linter.js +2 -41
  45. package/dist/src/linter.js.map +1 -1
  46. package/dist/src/mapping-from.d.ts +20 -0
  47. package/dist/src/mapping-from.js +149 -0
  48. package/dist/src/mapping-from.js.map +1 -0
  49. package/dist/src/mapping.d.ts +58 -0
  50. package/dist/src/mapping.js +209 -0
  51. package/dist/src/mapping.js.map +1 -0
  52. package/dist/src/model.d.ts +87 -9
  53. package/dist/src/model.js +65 -10
  54. package/dist/src/model.js.map +1 -1
  55. package/dist/src/public.d.ts +19 -3
  56. package/dist/src/public.js +27 -3
  57. package/dist/src/public.js.map +1 -1
  58. package/dist/src/validate.d.ts +2 -1
  59. package/dist/src/validate.js +181 -59
  60. package/dist/src/validate.js.map +1 -1
  61. package/lib/main.tsp +1 -0
  62. package/lib/mapping.tsp +71 -0
  63. package/lib/meta.tsp +23 -4
  64. package/lib/types.tsp +13 -65
  65. package/lib/ui.tsp +60 -17
  66. package/package.json +7 -1
  67. package/src/casing.ts +172 -0
  68. package/src/decorators/index.ts +1 -0
  69. package/src/decorators/mapping.ts +57 -0
  70. package/src/decorators/meta.ts +50 -11
  71. package/src/decorators/shared.ts +13 -0
  72. package/src/decorators/ui.ts +81 -59
  73. package/src/emitter.ts +59 -13
  74. package/src/emitters/block-ui.ts +156 -140
  75. package/src/emitters/layout-ui.ts +280 -0
  76. package/src/emitters/overlay.ts +3 -103
  77. package/src/forms.ts +82 -0
  78. package/src/index.ts +14 -3
  79. package/src/layout.ts +592 -0
  80. package/src/lib.ts +222 -16
  81. package/src/linter.ts +1 -42
  82. package/src/mapping-from.ts +193 -0
  83. package/src/mapping.ts +351 -0
  84. package/src/model.ts +192 -24
  85. package/src/public.ts +50 -5
  86. package/src/validate.ts +189 -60
  87. package/dist/src/emitters/override-condition.d.ts +0 -12
  88. package/dist/src/emitters/override-condition.js +0 -25
  89. package/dist/src/emitters/override-condition.js.map +0 -1
  90. package/src/emitters/override-condition.ts +0 -37
package/README.md CHANGED
@@ -1,110 +1,255 @@
1
1
  # simpler-forms
2
2
 
3
- A [TypeSpec](https://typespec.io) library for specifying grant application forms once and
4
- emitting portable form artifacts — a JSON Schema for the data, a UI schema for the layout,
5
- and an index describing how the two relate.
3
+ A [TypeSpec](https://typespec.io) library for specifying forms once and emitting portable form
4
+ artifacts: a JSON Schema for the data, a UI schema for the layout, and an index describing how
5
+ the two relate.
6
6
 
7
- The library holds no form content and no vocabulary specific to any consuming application.
8
- Form definitions, a shared question bank, and target-specific emitters live in the
9
- repositories that consume this package.
7
+ The library holds no form content and no vocabulary of its own. Your program supplies the
8
+ questions, the forms, and the widgets, tags and mapping targets they use.
10
9
 
11
- ## Status
10
+ ## Install
12
11
 
13
- Pre-release, published from `main` as `simpler-forms`, unscoped.
12
+ ```bash
13
+ pnpm add -D simpler-forms @typespec/compiler @typespec/json-schema
14
+ ```
14
15
 
15
- Versions stay below 1.0 for now. release-please is configured with `bump-minor-pre-major`,
16
- so a breaking change moves the minor — 0.1.0 to 0.2.0 — instead of jumping to 1.0.0. Read any
17
- minor bump as potentially breaking until this section says otherwise.
16
+ `@typespec/compiler` and `@typespec/json-schema` are peer dependencies, so you control the
17
+ compiler version.
18
18
 
19
- The library name is passed to `createTypeSpecLibrary` as both `name` and `alias`, and it is
20
- the alias that prefixes every diagnostic code and lint rule id. So a suppression in a form
21
- specification reads:
19
+ ## Quick start
20
+
21
+ `tspconfig.yaml`:
22
+
23
+ ```yaml
24
+ emit:
25
+ - simpler-forms
26
+ options:
27
+ simpler-forms:
28
+ property-casing: snake
29
+ linter:
30
+ extends:
31
+ - simpler-forms/recommended
32
+ ```
33
+
34
+ `main.tsp`:
22
35
 
23
36
  ```tsp
24
- #suppress "simpler-forms/no-orphan-question"
37
+ import "@typespec/json-schema";
38
+ import "simpler-forms";
39
+
40
+ using SimplerForms;
41
+
42
+ @Meta.tags(Tag)
43
+ @Meta.entities(Entity)
44
+ namespace Catalogue {
45
+ enum Tag { name, contact }
46
+ enum Entity { poc }
47
+ }
48
+
49
+ @UI.widgets(Widget)
50
+ namespace Rendering {
51
+ enum Widget { Text, TextArea }
52
+ }
53
+
54
+ @JsonSchema.jsonSchema
55
+ namespace Questions {
56
+ /** The name of the person to contact. */
57
+ @Meta.question(#{ id: "poc/name", entity: Catalogue.Entity.poc })
58
+ @Meta.tag(Catalogue.Tag.name, Catalogue.Tag.contact)
59
+ model PersonName {
60
+ @UI.label("First Name") firstName: string;
61
+ @UI.label("Last Name") lastName: string;
62
+ }
63
+ }
64
+
65
+ @JsonSchema.jsonSchema
66
+ namespace Forms {
67
+ /** Who to contact about this application. */
68
+ @Meta.form(#{ id: "point-of-contact", formName: "POINT OF CONTACT" })
69
+ model PointOfContact {
70
+ @UI.label("Contact Name")
71
+ name: Questions.PersonName;
72
+
73
+ @UI.label("Notes")
74
+ @UI.widget(Rendering.Widget.TextArea)
75
+ notes?: string;
76
+ }
77
+ }
25
78
  ```
26
79
 
27
- Because that prefix comes from the alias and not from the package name, moving the package
28
- into an npm scope later — `@agilesix/simpler-forms`, say — leaves every suppression already
29
- written in a specification working. What such a move does change is the import specifier in a
30
- consumer's specs and its dependency entry, one line each.
80
+ `tsp compile main.tsp` writes:
31
81
 
32
- ## Install
82
+ ```
83
+ tsp-output/simpler-forms/
84
+ question-bank/poc/name/ schema.json ui.json index.json
85
+ forms/point-of-contact/ schema.json ui.json index.json manifest.json
86
+ ```
33
87
 
34
- ```bash
35
- pnpm add -D simpler-forms @typespec/compiler @typespec/json-schema
88
+ | Artifact | What it holds |
89
+ | --------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
90
+ | `schema.json` | The JSON Schema for the data, with its validation |
91
+ | `ui.json` | A [JSON Forms](https://jsonforms.io) UI schema laying the data out |
92
+ | `index.json` | A catalogue entry: name, description and tags; for a question, its entity and what it composes; for a form, where each field occurs |
93
+ | `manifest.json` | The form's identity and the artifacts in its package |
94
+
95
+ Where the artifacts go from there is up to you: the emitter writes the same layout to
96
+ `emitter-output-dir` regardless of where your application installs them.
97
+
98
+ ## Questions
99
+
100
+ A question is a reusable block of a form, given a stable id with `@Meta.question`. It is
101
+ published under `question-bank/<id>/`, and a form that composes it refers to its schema.
102
+
103
+ - `entity` names what the question is asked about, and is the first segment of its id.
104
+ - `@Meta.tag` files it under headings in a question catalogue.
105
+ - Its doc comment is its description; `@UI.label` and `@UI.helpText` are how it reads in a form.
106
+ - A property whose type is a question takes the question's label unless it sets its own.
107
+
108
+ ## Forms
109
+
110
+ `@Meta.form` goes on the model holding the data an applicant submits, and publishes it under
111
+ `forms/<id>/`. Its fields' `@UI.*` decorators lay it out, and each object field becomes a
112
+ labeled group.
113
+
114
+ Validation lives on the form and its questions, in the `@Validation.*` decorators:
115
+ conditional requiredness (`@Validation.requiredPaths`, `@Validation.requiredWhen`), constraints
116
+ that apply under a condition, calculated values and more. See `lib/validation.tsp` for the
117
+ full set.
118
+
119
+ A platform's own identity for a form, such as the name and version a submission system knows it
120
+ by, belongs in that platform's TypeSpec library, as a decorator of its own on the same model.
121
+
122
+ ## Layouts
123
+
124
+ A `@UI.layout` model presents a form differently from how its data is shaped, and is published
125
+ as the form's `ui.json`. It points at the form's fields with typed references, so a misspelled
126
+ field is a compiler error.
127
+
128
+ ```tsp
129
+ @UI.layout(PointOfContact)
130
+ model PointOfContactLayout {
131
+ /** Enter the contact's name. */
132
+ @UI.label("Contact")
133
+ contact: {
134
+ name: PointOfContact.name;
135
+ };
136
+
137
+ @UI.label("Other")
138
+ other: {
139
+ notes: PointOfContact.notes;
140
+ };
141
+ }
36
142
  ```
37
143
 
38
- `@typespec/compiler` and `@typespec/json-schema` are peer dependencies, so a consumer
39
- controls its own compiler version.
144
+ - Its top-level properties are sections, in order, and a doc comment is a section's description.
145
+ - A field reference places that field as its own model lays it out.
146
+ - An entry typed as a model with `@UI.field(ref)` lays out that field's contents, listing only
147
+ what changes and keeping the rest in their declared order. References inside it are relative
148
+ to the field, so one entry model can serve several fields.
149
+ - An entry can set a label, help text, a widget, `@UI.omit`, `@UI.flatten` (place a field's
150
+ children without their group) and one display condition.
151
+ - Validation stays on the form, so a `@Validation.*` decorator on a layout entry is an error.
40
152
 
41
- ## Develop
153
+ A form has at most one layout.
42
154
 
43
- ```bash
44
- pnpm install
45
- pnpm build # required before anything else — see below
46
- pnpm test
47
- pnpm checks # format, lint, types, tests
155
+ ## Your program's vocabulary
156
+
157
+ Which widgets your renderers provide, which tags and entities your question bank uses, and
158
+ which representations your forms map to are yours to declare. Declare each set once, on a
159
+ namespace, and the decorators that use them take its members:
160
+
161
+ | Declare | Used by |
162
+ | ------------------------ | ------------------------------ |
163
+ | `@UI.widgets(Enum)` | `@UI.widget` |
164
+ | `@Meta.tags(Enum)` | `@Meta.tag` |
165
+ | `@Meta.entities(Enum)` | `@Meta.question`'s `entity` |
166
+ | `@Mapping.targets(Enum)` | `@Mapping.to`, `@Mapping.from` |
167
+
168
+ A member of an enum no namespace declares is an error. Where a member is emitted, its string
169
+ value is used when it has one, and its name otherwise.
170
+
171
+ ## Mappings
172
+
173
+ A response often has to be written in another shape too, such as an XML document or a CSV row.
174
+ A mapping links a form to a TypeSpec model of that shape, the mapping target. Wire details
175
+ such as element names and namespaces stay on the target, in whatever vocabulary its
176
+ representation uses.
177
+
178
+ Declare the links on the target with `@Mapping.from`. The target's root names the form, and
179
+ each property names the field it is filled from, relative to its parent's field. A target type
180
+ shared by many forms is annotated once, against the questions that fill it:
181
+
182
+ ```tsp
183
+ @Mapping.targets(Target)
184
+ namespace Mappings {
185
+ enum Target { xml }
186
+ }
187
+
188
+ model Name {
189
+ @Mapping.from(Mappings.Target.xml, Questions.PersonName.firstName) first: string;
190
+ @Mapping.from(Mappings.Target.xml, Questions.PersonName.lastName) last: string;
191
+ }
192
+
193
+ @Mapping.from(Mappings.Target.xml, Forms.PointOfContact)
194
+ model Root {
195
+ @Mapping.from(Mappings.Target.xml, Forms.PointOfContact.name) contactName: Name;
196
+ @Mapping.from(Mappings.Target.xml, Forms.PointOfContact.notes) notes?: string;
197
+ }
48
198
  ```
49
199
 
50
- **Build before you type-check.** Each `lib/*.tsp` file imports `dist/src/index.js` to resolve
51
- the `extern dec` declarations it makes, so the TypeSpec sources do not type-check until the
52
- compiled JavaScript exists. This is why CI runs `pnpm build` ahead of `pnpm checks`, and why
53
- a fresh clone reports unimplemented decorators until the first build.
200
+ The same links can be declared from the form's side with `@Mapping.to`, plus `@Mapping.path`
201
+ for nested paths. Every link is checked as it resolves, against the target's type and
202
+ cardinality.
203
+
204
+ simpler-forms emits no mapping artifact itself: an emitter for the target format reads the
205
+ links (see [Writing a target emitter](#writing-a-target-emitter)).
54
206
 
55
- ## Release
207
+ ## Options
56
208
 
57
- `main` is released by [release-please](https://github.com/googleapis/release-please). Pushing a
58
- conventional commit opens or updates a release pull request; merging that pull request tags the
59
- release and publishes the tarball to npm.
209
+ Set under `options: simpler-forms:` in `tspconfig.yaml`.
60
210
 
61
- Publication authenticates through npm trusted publishing, so this repository holds no npm
62
- token. The workflow exchanges a GitHub OIDC token for a short-lived credential, and npm
63
- attaches a provenance attestation to the version it accepts. The trusted publisher is
64
- configured against `.github/workflows/release.yml` by path, so renaming or moving that file
65
- stops publication until the publisher is updated to match.
211
+ | Option | Default | Effect |
212
+ | ----------------- | ---------- | ------------------------------------------------------------ |
213
+ | `base-uri` | none | Makes every `$id` and cross-block `$ref` absolute |
214
+ | `property-casing` | `preserve` | `snake` writes `firstName` as `first_name` in every artifact |
66
215
 
67
- ## Layout
216
+ With `snake`, specifications are still written in TypeSpec names, including string paths such as
217
+ `@Validation.requiredPaths("contact.name.firstName")`. A run of capitals is one word
218
+ (`OMBNumber` becomes `omb_number`), and digits stay with the word before them (`street1` is
219
+ unchanged). For a name the rule converts badly, set `@encodedName("application/json", "...")`
220
+ on every property with that name.
68
221
 
222
+ ## Diagnostics
223
+
224
+ Checks run as you type in an editor with the TypeSpec extension, as well as on compile. Extend
225
+ `simpler-forms/recommended` in `tspconfig.yaml` for the lint rules, and suppress a diagnostic by
226
+ its code:
227
+
228
+ ```tsp
229
+ #suppress "simpler-forms/no-orphan-question" "Asked only by forms in another repository"
69
230
  ```
70
- lib/ TypeSpec declarations — the decorator vocabulary
71
- main.tsp the entry point a consumer imports
72
- meta.tsp @Meta.* — question, form, tag, role
73
- ui.tsp @UI.* — labels, sections, widgets, overrides
74
- validation.tsp @Validation.*
75
- types.tsp shared scalars and enums
76
- src/ the library implementation
77
- public.ts the API a target emitter reads — the only semver-governed surface
78
- decorators/ decorator entry points, one module per namespace
79
- model.ts typed accessors over decorator state
80
- validate.ts $onValidate — cross-cutting checks reported as diagnostics
81
- linter.ts lint rules
82
- emitter.ts $onEmit — writes the canonical artifacts
83
- emitters/ one module per emitted artifact
84
- lib.ts createTypeSpecLibrary — diagnostics, lint rules, emitter options
85
- test/ vitest suites, driven by the compiler's createTester
231
+
232
+ ## Writing a target emitter
233
+
234
+ An emitter for another format, such as the XML a mapping target describes, is a TypeSpec
235
+ library of its own, listed beside this one in `tspconfig.yaml`. It reads forms, layouts and
236
+ mappings through the package's JavaScript API:
237
+
238
+ ```ts
239
+ import { resolveForms, resolveMappingFrom } from "simpler-forms";
86
240
  ```
87
241
 
88
- Only `src/public.ts` is public API. The decorator implementations, emitters and validators
89
- are internal, and a target emitter reaching past that module depends on something that can
90
- change in a patch.
242
+ That API, from `src/public.ts`, is the supported surface. Anything else in the package is
243
+ internal and can change in any release.
91
244
 
92
- ## Design notes
245
+ ## Versioning
93
246
 
94
- **Diagnostics are live in the editor.** `$onValidate` runs in the standard compile pipeline
95
- before the linter and is not gated by `noEmit`, and the language server routes through that
96
- same pipeline. A custom diagnostic therefore appears as a squiggle while an author types,
97
- not only in CI.
247
+ simpler-forms is below 1.0. A breaking change bumps the minor version (0.1.0 to 0.2.0), so
248
+ treat every minor release as potentially breaking. The changelog lists breaking changes first.
98
249
 
99
- **Where artifacts land is the consumer's decision.** The emitter writes to
100
- `emitter-output-dir` in a stable layout of its own. It deliberately knows nothing about any
101
- consuming application's directory conventions; installing artifacts into a particular tree is
102
- a separate step owned by the consumer, so that a downstream layout change is not a breaking
103
- change here.
250
+ ## Contributing
104
251
 
105
- **Target vocabulary belongs downstream.** A consuming application's own decorators, state,
106
- validation and emitted files are contributed by its own TypeSpec library listed alongside
107
- this one in `tspconfig.yaml`, rather than by a plugin interface here.
252
+ See [CONTRIBUTING.md](./CONTRIBUTING.md).
108
253
 
109
254
  ## License
110
255
 
@@ -0,0 +1,43 @@
1
+ import type { ModelProperty, Program } from "@typespec/compiler";
2
+ /** How a property's TypeSpec name becomes its name in every emitted artifact. */
3
+ export type PropertyCasing = "preserve" | "snake";
4
+ /**
5
+ * `firstName` to `first_name`.
6
+ *
7
+ * A word starts at each capital that follows a lowercase letter or a digit, and at the last
8
+ * capital of a run that a lowercase letter follows, so an acronym is one word: `ombNumber`
9
+ * and `OMBNumber` both become `omb_number`, and `HTTPServer` becomes `http_server`. Digits
10
+ * stay with the word before them, so `street1` and `sf424Version` become `street1` and
11
+ * `sf424_version`. A name that is already snake case is unchanged.
12
+ */
13
+ export declare function snakeCase(name: string): string;
14
+ /**
15
+ * The name a property is emitted under.
16
+ *
17
+ * `@encodedName("application/json", ...)` wins over the casing, so a name the rule
18
+ * converts badly can be stated outright.
19
+ */
20
+ export declare function jsonPropertyName(program: Program, property: ModelProperty, casing: PropertyCasing): string;
21
+ /**
22
+ * Renames properties in a finished artifact.
23
+ *
24
+ * The emitters build every artifact in TypeSpec names, which is also what an author writes in
25
+ * a string path, so the casing is applied once, after everything that resolves a path has run.
26
+ * One table maps each TypeSpec name to its emitted name across the whole program. That keeps
27
+ * renaming independent of where in an artifact a name appears, at the cost of requiring a name
28
+ * to be emitted the same way everywhere it is declared.
29
+ */
30
+ export declare class Casing {
31
+ private readonly casing;
32
+ private readonly names;
33
+ constructor(program: Program, casing: PropertyCasing);
34
+ /** The name a property named `key` in TypeSpec is emitted under. */
35
+ name(key: string): string;
36
+ /** A JSON Schema or JSON Forms layout. */
37
+ json<T>(node: T): T;
38
+ /** A JSON Pointer such as `/keyContacts/[]/name`. */
39
+ pointer(path: string): string;
40
+ /** Data shaped like the schema, such as an `@example` value. */
41
+ private instance;
42
+ private keys;
43
+ }
@@ -0,0 +1,146 @@
1
+ import { resolveEncodedName } from "@typespec/compiler";
2
+ import { reportDiagnostic } from "./lib.js";
3
+ import { modelProperties } from "./model.js";
4
+ /**
5
+ * `firstName` to `first_name`.
6
+ *
7
+ * A word starts at each capital that follows a lowercase letter or a digit, and at the last
8
+ * capital of a run that a lowercase letter follows, so an acronym is one word: `ombNumber`
9
+ * and `OMBNumber` both become `omb_number`, and `HTTPServer` becomes `http_server`. Digits
10
+ * stay with the word before them, so `street1` and `sf424Version` become `street1` and
11
+ * `sf424_version`. A name that is already snake case is unchanged.
12
+ */
13
+ export function snakeCase(name) {
14
+ return name
15
+ .replace(/([a-z\d])([A-Z])/g, "$1_$2")
16
+ .replace(/([A-Z]+)([A-Z][a-z])/g, "$1_$2")
17
+ .toLowerCase();
18
+ }
19
+ /**
20
+ * The name a property is emitted under.
21
+ *
22
+ * `@encodedName("application/json", ...)` wins over the casing, so a name the rule
23
+ * converts badly can be stated outright.
24
+ */
25
+ export function jsonPropertyName(program, property, casing) {
26
+ const encoded = resolveEncodedName(program, property, "application/json");
27
+ if (encoded !== property.name)
28
+ return encoded;
29
+ return casing === "snake" ? snakeCase(property.name) : property.name;
30
+ }
31
+ /**
32
+ * Renames properties in a finished artifact.
33
+ *
34
+ * The emitters build every artifact in TypeSpec names, which is also what an author writes in
35
+ * a string path, so the casing is applied once, after everything that resolves a path has run.
36
+ * One table maps each TypeSpec name to its emitted name across the whole program. That keeps
37
+ * renaming independent of where in an artifact a name appears, at the cost of requiring a name
38
+ * to be emitted the same way everywhere it is declared.
39
+ */
40
+ export class Casing {
41
+ casing;
42
+ names = new Map();
43
+ constructor(program, casing) {
44
+ this.casing = casing;
45
+ const declared = new Map();
46
+ const visit = (namespace) => {
47
+ for (const model of namespace.models.values()) {
48
+ const claimed = new Map();
49
+ for (const property of modelProperties(model)) {
50
+ const name = jsonPropertyName(program, property, casing);
51
+ const sibling = claimed.get(name);
52
+ if (sibling) {
53
+ reportDiagnostic(program, {
54
+ code: "property-casing-collision",
55
+ target: property,
56
+ format: {
57
+ model: model.name,
58
+ first: sibling.name,
59
+ second: property.name,
60
+ name,
61
+ },
62
+ });
63
+ }
64
+ else
65
+ claimed.set(name, property);
66
+ const elsewhere = declared.get(property.name);
67
+ const previous = this.names.get(property.name);
68
+ if (elsewhere && previous !== name) {
69
+ reportDiagnostic(program, {
70
+ code: "property-casing-inconsistent",
71
+ target: property,
72
+ format: {
73
+ property: property.name,
74
+ name,
75
+ other: `${elsewhere.model?.name}.${elsewhere.name}`,
76
+ otherName: previous,
77
+ },
78
+ });
79
+ }
80
+ else if (!elsewhere) {
81
+ declared.set(property.name, property);
82
+ this.names.set(property.name, name);
83
+ }
84
+ }
85
+ }
86
+ for (const child of namespace.namespaces.values())
87
+ visit(child);
88
+ };
89
+ visit(program.getGlobalNamespaceType());
90
+ // The stock emitter serializes an `@example` with encoded names already applied.
91
+ for (const name of [...this.names.values()])
92
+ this.names.set(name, name);
93
+ }
94
+ /** The name a property named `key` in TypeSpec is emitted under. */
95
+ name(key) {
96
+ return (this.names.get(key) ?? (this.casing === "snake" ? snakeCase(key) : key));
97
+ }
98
+ /** A JSON Schema or JSON Forms layout. */
99
+ json(node) {
100
+ if (Array.isArray(node))
101
+ return node.map((entry) => this.json(entry));
102
+ if (!isObject(node))
103
+ return node;
104
+ return Object.fromEntries(Object.entries(node).map(([key, value]) => {
105
+ if (key === "properties" && isObject(value))
106
+ return [key, this.keys(value, (entry) => this.json(entry))];
107
+ if (key === "required" && Array.isArray(value))
108
+ return [key, value.map((name) => this.name(name))];
109
+ if (key === "scope" && typeof value === "string")
110
+ return [
111
+ key,
112
+ value.replace(/(?<=properties\/)[^/]+/g, (name) => this.name(name)),
113
+ ];
114
+ if (key === "examples" || key === "default" || key === "const")
115
+ return [key, this.instance(value)];
116
+ return [key, this.json(value)];
117
+ }));
118
+ }
119
+ /** A JSON Pointer such as `/keyContacts/[]/name`. */
120
+ pointer(path) {
121
+ return path
122
+ .split("/")
123
+ .map((token, index) => index === 0 || token === "[]"
124
+ ? token
125
+ : escapePointer(this.name(unescapePointer(token))))
126
+ .join("/");
127
+ }
128
+ /** Data shaped like the schema, such as an `@example` value. */
129
+ instance(value) {
130
+ if (Array.isArray(value))
131
+ return value.map((entry) => this.instance(entry));
132
+ return isObject(value)
133
+ ? this.keys(value, (entry) => this.instance(entry))
134
+ : value;
135
+ }
136
+ keys(value, inner) {
137
+ return Object.fromEntries(Object.entries(value).map(([name, entry]) => [
138
+ this.name(name),
139
+ inner(entry),
140
+ ]));
141
+ }
142
+ }
143
+ const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
144
+ const unescapePointer = (token) => token.replaceAll("~1", "/").replaceAll("~0", "~");
145
+ const escapePointer = (token) => token.replaceAll("~", "~0").replaceAll("/", "~1");
146
+ //# sourceMappingURL=casing.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"casing.js","sourceRoot":"","sources":["../../src/casing.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAC5C,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAK7C;;;;;;;;GAQG;AACH,MAAM,UAAU,SAAS,CAAC,IAAY;IACpC,OAAO,IAAI;SACR,OAAO,CAAC,mBAAmB,EAAE,OAAO,CAAC;SACrC,OAAO,CAAC,uBAAuB,EAAE,OAAO,CAAC;SACzC,WAAW,EAAE,CAAC;AACnB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAC9B,OAAgB,EAChB,QAAuB,EACvB,MAAsB;IAEtB,MAAM,OAAO,GAAG,kBAAkB,CAAC,OAAO,EAAE,QAAQ,EAAE,kBAAkB,CAAC,CAAC;IAC1E,IAAI,OAAO,KAAK,QAAQ,CAAC,IAAI;QAAE,OAAO,OAAO,CAAC;IAC9C,OAAO,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC;AACvE,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,OAAO,MAAM;IAKE;IAJF,KAAK,GAAG,IAAI,GAAG,EAAkB,CAAC;IAEnD,YACE,OAAgB,EACC,MAAsB;QAAtB,WAAM,GAAN,MAAM,CAAgB;QAEvC,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAyB,CAAC;QAClD,MAAM,KAAK,GAAG,CAAC,SAAoB,EAAQ,EAAE;YAC3C,KAAK,MAAM,KAAK,IAAI,SAAS,CAAC,MAAM,CAAC,MAAM,EAAE,EAAE,CAAC;gBAC9C,MAAM,OAAO,GAAG,IAAI,GAAG,EAAyB,CAAC;gBACjD,KAAK,MAAM,QAAQ,IAAI,eAAe,CAAC,KAAK,CAAC,EAAE,CAAC;oBAC9C,MAAM,IAAI,GAAG,gBAAgB,CAAC,OAAO,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC;oBACzD,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;oBAClC,IAAI,OAAO,EAAE,CAAC;wBACZ,gBAAgB,CAAC,OAAO,EAAE;4BACxB,IAAI,EAAE,2BAA2B;4BACjC,MAAM,EAAE,QAAQ;4BAChB,MAAM,EAAE;gCACN,KAAK,EAAE,KAAK,CAAC,IAAI;gCACjB,KAAK,EAAE,OAAO,CAAC,IAAI;gCACnB,MAAM,EAAE,QAAQ,CAAC,IAAI;gCACrB,IAAI;6BACL;yBACF,CAAC,CAAC;oBACL,CAAC;;wBAAM,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;oBAEnC,MAAM,SAAS,GAAG,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;oBAC9C,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;oBAC/C,IAAI,SAAS,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;wBACnC,gBAAgB,CAAC,OAAO,EAAE;4BACxB,IAAI,EAAE,8BAA8B;4BACpC,MAAM,EAAE,QAAQ;4BAChB,MAAM,EAAE;gCACN,QAAQ,EAAE,QAAQ,CAAC,IAAI;gCACvB,IAAI;gCACJ,KAAK,EAAE,GAAG,SAAS,CAAC,KAAK,EAAE,IAAI,IAAI,SAAS,CAAC,IAAI,EAAE;gCACnD,SAAS,EAAE,QAAS;6BACrB;yBACF,CAAC,CAAC;oBACL,CAAC;yBAAM,IAAI,CAAC,SAAS,EAAE,CAAC;wBACtB,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;wBACtC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;oBACtC,CAAC;gBACH,CAAC;YACH,CAAC;YACD,KAAK,MAAM,KAAK,IAAI,SAAS,CAAC,UAAU,CAAC,MAAM,EAAE;gBAAE,KAAK,CAAC,KAAK,CAAC,CAAC;QAClE,CAAC,CAAC;QACF,KAAK,CAAC,OAAO,CAAC,sBAAsB,EAAE,CAAC,CAAC;QACxC,iFAAiF;QACjF,KAAK,MAAM,IAAI,IAAI,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;YAAE,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IAC1E,CAAC;IAED,oEAAoE;IACpE,IAAI,CAAC,GAAW;QACd,OAAO,CACL,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CACxE,CAAC;IACJ,CAAC;IAED,0CAA0C;IAC1C,IAAI,CAAI,IAAO;QACb,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC;YAAE,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAM,CAAC;QAC3E,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC;YAAE,OAAO,IAAI,CAAC;QACjC,OAAO,MAAM,CAAC,WAAW,CACvB,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE;YACxC,IAAI,GAAG,KAAK,YAAY,IAAI,QAAQ,CAAC,KAAK,CAAC;gBACzC,OAAO,CAAC,GAAG,EAAE,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;YAC9D,IAAI,GAAG,KAAK,UAAU,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;gBAC5C,OAAO,CAAC,GAAG,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YACrD,IAAI,GAAG,KAAK,OAAO,IAAI,OAAO,KAAK,KAAK,QAAQ;gBAC9C,OAAO;oBACL,GAAG;oBACH,KAAK,CAAC,OAAO,CAAC,yBAAyB,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;iBACpE,CAAC;YACJ,IAAI,GAAG,KAAK,UAAU,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,KAAK,OAAO;gBAC5D,OAAO,CAAC,GAAG,EAAE,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC;YACrC,OAAO,CAAC,GAAG,EAAE,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;QACjC,CAAC,CAAC,CACE,CAAC;IACT,CAAC;IAED,qDAAqD;IACrD,OAAO,CAAC,IAAY;QAClB,OAAO,IAAI;aACR,KAAK,CAAC,GAAG,CAAC;aACV,GAAG,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE,CACpB,KAAK,KAAK,CAAC,IAAI,KAAK,KAAK,IAAI;YAC3B,CAAC,CAAC,KAAK;YACP,CAAC,CAAC,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC,CAAC,CACrD;aACA,IAAI,CAAC,GAAG,CAAC,CAAC;IACf,CAAC;IAED,gEAAgE;IACxD,QAAQ,CAAC,KAAc;QAC7B,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;YAAE,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC;QAC5E,OAAO,QAAQ,CAAC,KAAK,CAAC;YACpB,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;YACnD,CAAC,CAAC,KAAK,CAAC;IACZ,CAAC;IAEO,IAAI,CACV,KAA8B,EAC9B,KAAkC;QAElC,OAAO,MAAM,CAAC,WAAW,CACvB,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC;YAC3C,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC;YACf,KAAK,CAAC,KAAK,CAAC;SACb,CAAC,CACH,CAAC;IACJ,CAAC;CACF;AAED,MAAM,QAAQ,GAAG,CAAC,KAAc,EAAoC,EAAE,CACpE,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAEvE,MAAM,eAAe,GAAG,CAAC,KAAa,EAAE,EAAE,CACxC,KAAK,CAAC,UAAU,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,UAAU,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;AAEpD,MAAM,aAAa,GAAG,CAAC,KAAa,EAAE,EAAE,CACtC,KAAK,CAAC,UAAU,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,UAAU,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC"}
@@ -2,3 +2,4 @@ export { blockSchemaRef } from "./shared.js";
2
2
  export * from "./meta.js";
3
3
  export * from "./ui.js";
4
4
  export * from "./validation.js";
5
+ export * from "./mapping.js";
@@ -4,4 +4,5 @@ export { blockSchemaRef } from "./shared.js";
4
4
  export * from "./meta.js";
5
5
  export * from "./ui.js";
6
6
  export * from "./validation.js";
7
+ export * from "./mapping.js";
7
8
  //# sourceMappingURL=index.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/decorators/index.ts"],"names":[],"mappings":"AAAA,mFAAmF;AACnF,yDAAyD;AACzD,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,cAAc,WAAW,CAAC;AAC1B,cAAc,SAAS,CAAC;AACxB,cAAc,iBAAiB,CAAC"}
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/decorators/index.ts"],"names":[],"mappings":"AAAA,mFAAmF;AACnF,yDAAyD;AACzD,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,cAAc,WAAW,CAAC;AAC1B,cAAc,SAAS,CAAC;AACxB,cAAc,iBAAiB,CAAC;AAChC,cAAc,cAAc,CAAC"}
@@ -0,0 +1,11 @@
1
+ import type { Enum, EnumMember, Model, ModelProperty, Namespace } from "@typespec/compiler";
2
+ import { type Ctx } from "./shared.js";
3
+ export declare const $targets: (ctx: Ctx, target: Namespace, targets: Enum) => void;
4
+ /**
5
+ * Accumulated rather than overwritten: one model or property carries a link per mapping.
6
+ * Two links for the same mapping are reported by `$onValidate`, not here, so the check sees
7
+ * every decorator before it decides which one is the duplicate.
8
+ */
9
+ export declare const $to: (ctx: Ctx, target: Model | ModelProperty, mapping: EnumMember, mappedTo: Model | ModelProperty) => void;
10
+ export declare const $path: (ctx: Ctx, target: Model, mapping: EnumMember, sourcePath: string, mappedTo: ModelProperty) => void;
11
+ export declare const $from: (ctx: Ctx, target: Model | ModelProperty, mapping: EnumMember, source: Model | ModelProperty) => void;
@@ -0,0 +1,22 @@
1
+ import { stateKeys } from "../lib.js";
2
+ import { push, set } from "./shared.js";
3
+ export const $targets = (ctx, target, targets) => set(ctx, stateKeys.mappingTargets, target, targets);
4
+ /**
5
+ * Accumulated rather than overwritten: one model or property carries a link per mapping.
6
+ * Two links for the same mapping are reported by `$onValidate`, not here, so the check sees
7
+ * every decorator before it decides which one is the duplicate.
8
+ */
9
+ export const $to = (ctx, target, mapping, mappedTo) => push(ctx, stateKeys.mappedTo, target, {
10
+ mapping,
11
+ mappedTo,
12
+ });
13
+ export const $path = (ctx, target, mapping, sourcePath, mappedTo) => push(ctx, stateKeys.mappingPaths, target, {
14
+ mapping,
15
+ sourcePath,
16
+ mappedTo,
17
+ });
18
+ export const $from = (ctx, target, mapping, source) => push(ctx, stateKeys.mappedFrom, target, {
19
+ mapping,
20
+ source,
21
+ });
22
+ //# sourceMappingURL=mapping.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"mapping.js","sourceRoot":"","sources":["../../../src/decorators/mapping.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAMtC,OAAO,EAAY,IAAI,EAAE,GAAG,EAAE,MAAM,aAAa,CAAC;AAElD,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,GAAQ,EAAE,MAAiB,EAAE,OAAa,EAAE,EAAE,CACrE,GAAG,CAAC,GAAG,EAAE,SAAS,CAAC,cAAc,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;AAEtD;;;;GAIG;AACH,MAAM,CAAC,MAAM,GAAG,GAAG,CACjB,GAAQ,EACR,MAA6B,EAC7B,OAAmB,EACnB,QAA+B,EAC/B,EAAE,CACF,IAAI,CAAC,GAAG,EAAE,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE;IACpC,OAAO;IACP,QAAQ;CACa,CAAC,CAAC;AAE3B,MAAM,CAAC,MAAM,KAAK,GAAG,CACnB,GAAQ,EACR,MAAa,EACb,OAAmB,EACnB,UAAkB,EAClB,QAAuB,EACvB,EAAE,CACF,IAAI,CAAC,GAAG,EAAE,SAAS,CAAC,YAAY,EAAE,MAAM,EAAE;IACxC,OAAO;IACP,UAAU;IACV,QAAQ;CACiB,CAAC,CAAC;AAE/B,MAAM,CAAC,MAAM,KAAK,GAAG,CACnB,GAAQ,EACR,MAA6B,EAC7B,OAAmB,EACnB,MAA6B,EAC7B,EAAE,CACF,IAAI,CAAC,GAAG,EAAE,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE;IACtC,OAAO;IACP,MAAM;CACmB,CAAC,CAAC"}
@@ -1,19 +1,29 @@
1
- import type { Model, ModelProperty, Scalar } from "@typespec/compiler";
1
+ import type { Enum, EnumMember, Model, ModelProperty, Namespace, Scalar } from "@typespec/compiler";
2
2
  import { type Ctx } from "./shared.js";
3
3
  /**
4
4
  * `@Meta.question`: the question's stable identity, the entity it is asked about, and
5
5
  * its classification. Also establishes the JSON Schema `$id`, so this is what makes a
6
6
  * model a question rather than an ordinary model.
7
+ *
8
+ * The entity is recorded as its name now and as the member itself for `$onValidate`, which
9
+ * checks it against the declared sets once every `@Meta.entities` has run.
7
10
  */
8
11
  export declare const $question: (ctx: Ctx, target: Model | Scalar, meta: unknown) => void;
9
- /** `@Meta.form`: the form's identity and the provenance of the paper form it mirrors. */
12
+ /** `@Meta.tags`: the tags the program catalogues its questions by. */
13
+ export declare const $tags: (ctx: Ctx, target: Namespace, tags: Enum) => void;
14
+ /** `@Meta.entities`: the entities the program's questions are asked about. */
15
+ export declare const $entities: (ctx: Ctx, target: Namespace, entities: Enum) => void;
16
+ /**
17
+ * `@Meta.form`: a form an applicant opens, and the data it submits. Publishes the model's
18
+ * JSON Schema, as `@Meta.question` does, so a form is a block.
19
+ */
10
20
  export declare const $form: (ctx: Ctx, target: Model, meta: unknown) => void;
11
21
  /**
12
22
  * `@Meta.tag`: catalogue markers. Unlike the entity, a tag also applies to a bare
13
23
  * constrained scalar with no question identity, so it stays a decorator of its own
14
24
  * rather than a field of the question meta.
15
25
  */
16
- export declare const $tag: (ctx: Ctx, target: Model | Scalar, ...tags: unknown[]) => void;
26
+ export declare const $tag: (ctx: Ctx, target: Model | Scalar, ...tags: EnumMember[]) => void;
17
27
  /**
18
28
  * `@Meta.role`: why a field exists in a response -- applicant input, calculated output,
19
29
  * a value a platform supplies, a technical field, an attestation, or static content.