simpler-forms 0.1.0-alpha.1 → 0.2.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 (89) hide show
  1. package/README.md +300 -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 +17 -0
  9. package/dist/src/decorators/mapping.js +122 -0
  10. package/dist/src/decorators/mapping.js.map +1 -0
  11. package/dist/src/decorators/meta.d.ts +15 -5
  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 +2 -2
  15. package/dist/src/decorators/shared.js.map +1 -1
  16. package/dist/src/decorators/ui.d.ts +14 -12
  17. package/dist/src/decorators/ui.js +20 -43
  18. package/dist/src/decorators/ui.js.map +1 -1
  19. package/dist/src/emitter.d.ts +8 -0
  20. package/dist/src/emitter.js +55 -16
  21. package/dist/src/emitter.js.map +1 -1
  22. package/dist/src/emitters/block-ui.d.ts +14 -3
  23. package/dist/src/emitters/block-ui.js +81 -119
  24. package/dist/src/emitters/block-ui.js.map +1 -1
  25. package/dist/src/emitters/layout-ui.d.ts +12 -0
  26. package/dist/src/emitters/layout-ui.js +225 -0
  27. package/dist/src/emitters/layout-ui.js.map +1 -0
  28. package/dist/src/emitters/overlay.d.ts +10 -8
  29. package/dist/src/emitters/overlay.js +30 -105
  30. package/dist/src/emitters/overlay.js.map +1 -1
  31. package/dist/src/forms.d.ts +23 -0
  32. package/dist/src/forms.js +54 -0
  33. package/dist/src/forms.js.map +1 -0
  34. package/dist/src/index.d.ts +22 -8
  35. package/dist/src/index.js +17 -3
  36. package/dist/src/index.js.map +1 -1
  37. package/dist/src/layout.d.ts +50 -0
  38. package/dist/src/layout.js +397 -0
  39. package/dist/src/layout.js.map +1 -0
  40. package/dist/src/lib.d.ts +585 -39
  41. package/dist/src/lib.js +258 -15
  42. package/dist/src/lib.js.map +1 -1
  43. package/dist/src/linter.js +8 -43
  44. package/dist/src/linter.js.map +1 -1
  45. package/dist/src/mapping-from.d.ts +21 -0
  46. package/dist/src/mapping-from.js +169 -0
  47. package/dist/src/mapping-from.js.map +1 -0
  48. package/dist/src/mapping.d.ts +65 -0
  49. package/dist/src/mapping.js +209 -0
  50. package/dist/src/mapping.js.map +1 -0
  51. package/dist/src/model.d.ts +143 -23
  52. package/dist/src/model.js +108 -21
  53. package/dist/src/model.js.map +1 -1
  54. package/dist/src/public.d.ts +20 -4
  55. package/dist/src/public.js +28 -4
  56. package/dist/src/public.js.map +1 -1
  57. package/dist/src/validate.d.ts +2 -1
  58. package/dist/src/validate.js +208 -58
  59. package/dist/src/validate.js.map +1 -1
  60. package/lib/main.tsp +1 -0
  61. package/lib/mapping.tsp +173 -0
  62. package/lib/meta.tsp +25 -6
  63. package/lib/types.tsp +24 -63
  64. package/lib/ui.tsp +34 -17
  65. package/package.json +17 -11
  66. package/src/casing.ts +172 -0
  67. package/src/decorators/index.ts +1 -0
  68. package/src/decorators/mapping.ts +200 -0
  69. package/src/decorators/meta.ts +56 -13
  70. package/src/decorators/shared.ts +6 -1
  71. package/src/decorators/ui.ts +43 -59
  72. package/src/emitter.ts +76 -16
  73. package/src/emitters/block-ui.ts +83 -135
  74. package/src/emitters/layout-ui.ts +280 -0
  75. package/src/emitters/overlay.ts +43 -116
  76. package/src/forms.ts +82 -0
  77. package/src/index.ts +17 -3
  78. package/src/layout.ts +592 -0
  79. package/src/lib.ts +264 -15
  80. package/src/linter.ts +17 -49
  81. package/src/mapping-from.ts +216 -0
  82. package/src/mapping.ts +358 -0
  83. package/src/model.ts +287 -46
  84. package/src/public.ts +60 -6
  85. package/src/validate.ts +221 -60
  86. package/dist/src/emitters/override-condition.d.ts +0 -12
  87. package/dist/src/emitters/override-condition.js +0 -25
  88. package/dist/src/emitters/override-condition.js.map +0 -1
  89. package/src/emitters/override-condition.ts +0 -37
package/src/lib.ts CHANGED
@@ -1,4 +1,24 @@
1
- import { createTypeSpecLibrary, paramMessage } from "@typespec/compiler";
1
+ import {
2
+ createTypeSpecLibrary,
3
+ paramMessage,
4
+ type JSONSchemaType,
5
+ } from "@typespec/compiler";
6
+ import type { FormSpecOptions } from "./emitter.js";
7
+
8
+ const EmitterOptionsSchema: JSONSchemaType<FormSpecOptions> = {
9
+ type: "object",
10
+ additionalProperties: false,
11
+ properties: {
12
+ "base-uri": { type: "string", nullable: true },
13
+ "property-casing": {
14
+ type: "string",
15
+ enum: ["preserve", "snake"],
16
+ nullable: true,
17
+ default: "preserve",
18
+ },
19
+ },
20
+ required: [],
21
+ };
2
22
 
3
23
  /**
4
24
  * Named diagnostics for everything that makes an artifact wrong, and state keys for
@@ -18,7 +38,108 @@ export const $lib = createTypeSpecLibrary({
18
38
  "form-scoped-question-id": {
19
39
  severity: "error",
20
40
  messages: {
21
- default: paramMessage`Question id "${"id"}" names a form. Questions are named for what they mean; put form deltas in @UI.overrides.`,
41
+ default: paramMessage`Question id "${"id"}" names a form. Questions are named for what they mean; present a question differently in one form with that form's @UI.layout.`,
42
+ },
43
+ },
44
+ "layout-not-form": {
45
+ severity: "error",
46
+ messages: {
47
+ default: paramMessage`${"name"} presents ${"presented"}, which has no @Meta.form. A layout presents a form.`,
48
+ },
49
+ },
50
+ "layout-duplicate": {
51
+ severity: "error",
52
+ messages: {
53
+ default: paramMessage`${"form"} is presented by both ${"first"} and ${"second"}. A form has one layout; remove one of them.`,
54
+ },
55
+ },
56
+ "layout-ref-root": {
57
+ severity: "error",
58
+ messages: {
59
+ default: paramMessage`${"ref"} starts from ${"root"}, but entries here lay out ${"here"}. Start it from ${"start"}, or from ${"presented"} for a path from the form.`,
60
+ list: paramMessage`${"ref"} is outside the list ${"list"}, whose entries are laid out here. Place it outside that list's @UI.field.`,
61
+ },
62
+ },
63
+ "layout-entry-invalid": {
64
+ severity: "error",
65
+ messages: {
66
+ default: paramMessage`Layout entry ${"name"} is neither a field reference nor a model of entries. Give it a field as its type, e.g. \`${"name"}: Form.${"name"}\`, or a model of entries.`,
67
+ },
68
+ },
69
+ "layout-unplaced": {
70
+ severity: "error",
71
+ messages: {
72
+ default: paramMessage`${"presented"}.${"field"} is not placed in any section of ${"layout"}. Place it, or @UI.omit it.`,
73
+ partial: paramMessage`Only ${"parts"} of ${"presented"}.${"field"} is placed in ${"layout"}. Place the field itself, or lay out the rest of it with @UI.field.`,
74
+ },
75
+ },
76
+ "layout-placed-twice": {
77
+ severity: "error",
78
+ messages: {
79
+ default: paramMessage`${"path"} is placed twice in ${"layout"}.`,
80
+ },
81
+ },
82
+ "layout-section-not-group": {
83
+ severity: "error",
84
+ messages: {
85
+ default: paramMessage`Top-level entries of ${"layout"} are sections. Give ${"name"} a model of entries, with @UI.field to lay out one field's contents.`,
86
+ },
87
+ },
88
+ "layout-validation": {
89
+ severity: "error",
90
+ messages: {
91
+ default: paramMessage`@Validation.${"decorator"} on layout entry ${"name"} would make validity depend on the presentation. Declare it on ${"presented"}, which every layout of it shares.`,
92
+ },
93
+ },
94
+ "layout-condition-self": {
95
+ severity: "error",
96
+ messages: {
97
+ default: paramMessage`${"name"}'s condition reads ${"source"}, which is inside the field it controls.`,
98
+ },
99
+ },
100
+ "layout-condition-count": {
101
+ severity: "error",
102
+ messages: {
103
+ default: paramMessage`${"name"} has ${"count"} display conditions; an entry takes one.`,
104
+ },
105
+ },
106
+ "layout-duplicate-label": {
107
+ severity: "warning",
108
+ messages: {
109
+ default: paramMessage`Two entries in ${"where"} render as "${"label"}" (${"first"} and ${"second"}).`,
110
+ },
111
+ },
112
+ "layout-entry-name": {
113
+ severity: "warning",
114
+ messages: {
115
+ default: paramMessage`${"name"} places ${"path"}. Name it for the field (${"field"}) or for a step on its path.`,
116
+ },
117
+ },
118
+ "layout-flatten-leaf": {
119
+ severity: "warning",
120
+ messages: {
121
+ default: paramMessage`${"name"} has no fields of its own to flatten.`,
122
+ },
123
+ },
124
+ "layout-condition-hides-required": {
125
+ severity: "warning",
126
+ messages: {
127
+ always: paramMessage`${"name"} is always required, but "${"condition"}" can hide or disable it.`,
128
+ narrower: paramMessage`${"name"} is required when ${"required"}, but this layout makes it usable only when ${"condition"}.`,
129
+ inverted: paramMessage`${"name"} is required when ${"condition"}, which is exactly when this layout hides or disables it.`,
130
+ default: paramMessage`${"name"} can be hidden while it is required.`,
131
+ },
132
+ },
133
+ "layout-condition-source-omitted": {
134
+ severity: "warning",
135
+ messages: {
136
+ default: paramMessage`${"name"} waits on ${"source"}, which this layout omits, so an applicant can never answer it.`,
137
+ },
138
+ },
139
+ "layout-condition-replaces": {
140
+ severity: "warning",
141
+ messages: {
142
+ default: paramMessage`${"name"}'s condition replaces the one ${"field"} declares itself. Restate that condition here if both should hold.`,
22
143
  },
23
144
  },
24
145
  "duplicate-block-id": {
@@ -33,6 +154,122 @@ export const $lib = createTypeSpecLibrary({
33
154
  default: paramMessage`"${"value"}" is not a member of ${"enumName"}, so this condition is constant -- never holding, or always holding if it is negated. Members: ${"members"}.`,
34
155
  },
35
156
  },
157
+ "mapping-target-undeclared": {
158
+ severity: "error",
159
+ messages: {
160
+ default: paramMessage`${"name"} is linked in mapping ${"mapping"} from ${"enumName"}, which no namespace declares with @Mapping.targets, so no emitter is known to produce it. Declare the program's mappings once, e.g. @Mapping.targets(${"enumName"}).`,
161
+ },
162
+ },
163
+ "mapping-transform-undeclared": {
164
+ severity: "error",
165
+ messages: {
166
+ default: paramMessage`${"name"} is transformed with ${"transform"} from ${"enumName"}, which no namespace declares with @Mapping.transforms, so no emitter is known to implement it. Declare the program's transformations once, e.g. @Mapping.transforms(${"enumName"}).`,
167
+ },
168
+ },
169
+ "mapping-match-and-transform": {
170
+ severity: "error",
171
+ messages: {
172
+ default: paramMessage`${"name"} has both @Mapping.match and @Mapping.transform. A property changes its value one way: spell a lookup out with @Mapping.match, or name a transformation.`,
173
+ },
174
+ },
175
+ "mapping-when-value": {
176
+ severity: "error",
177
+ messages: {
178
+ exists: paramMessage`@Mapping.when on ${"name"} tests whether ${"source"} is answered, so it takes no value.`,
179
+ in: paramMessage`@Mapping.when on ${"name"} tests whether ${"source"} is one of a list's entries, so its value is a list.`,
180
+ default: paramMessage`@Mapping.when on ${"name"} compares ${"source"} with ${"operator"}, so it needs a value.`,
181
+ },
182
+ },
183
+ "mapping-when-source": {
184
+ severity: "error",
185
+ messages: {
186
+ default: paramMessage`@Mapping.when on ${"name"} names a model as its source: name a field of the form, or one item of a list field with Item.`,
187
+ },
188
+ },
189
+ "mapping-duplicate": {
190
+ severity: "error",
191
+ messages: {
192
+ default: paramMessage`${"name"} has more than one @Mapping.to for mapping ${"mapping"}. A model or property corresponds to one thing per mapping.`,
193
+ },
194
+ },
195
+ "mapping-path-unresolved": {
196
+ severity: "error",
197
+ messages: {
198
+ default: paramMessage`@Mapping.path "${"path"}" on ${"name"} does not resolve: ${"reason"}.`,
199
+ },
200
+ },
201
+ "mapping-target-out-of-context": {
202
+ severity: "error",
203
+ messages: {
204
+ default: paramMessage`In mapping ${"mapping"}, ${"source"} is linked to ${"target"}, which is not a property of ${"context"}, the model its parent maps to. Link the parent to the model that holds it, or link this path from the composing model with @Mapping.path.`,
205
+ },
206
+ },
207
+ "mapping-type-mismatch": {
208
+ severity: "error",
209
+ messages: {
210
+ default: paramMessage`In mapping ${"mapping"}, ${"source"} is linked to ${"target"}, but ${"reason"}.`,
211
+ },
212
+ },
213
+ "mapping-cardinality-mismatch": {
214
+ severity: "error",
215
+ messages: {
216
+ default: paramMessage`In mapping ${"mapping"}, ${"source"} is ${"sourceShape"} but ${"target"} is ${"targetShape"}.`,
217
+ },
218
+ },
219
+ "mapping-target-duplicate": {
220
+ severity: "error",
221
+ messages: {
222
+ default: paramMessage`In mapping ${"mapping"}, both ${"first"} and ${"second"} are linked to ${"target"}. Each target property takes its value from one source.`,
223
+ },
224
+ },
225
+ "mapping-from-unresolved": {
226
+ severity: "error",
227
+ messages: {
228
+ default: paramMessage`In mapping ${"mapping"}, ${"target"} is filled from ${"source"}, which is not a field of ${"context"}, the field its parent is filled from.`,
229
+ },
230
+ },
231
+ "mapping-from-cardinality-mismatch": {
232
+ severity: "error",
233
+ messages: {
234
+ default: paramMessage`In mapping ${"mapping"}, ${"target"} is ${"targetShape"} but ${"source"}, which fills it, is ${"sourceShape"}.`,
235
+ },
236
+ },
237
+ "mapping-from-select-not-a-list": {
238
+ severity: "error",
239
+ messages: {
240
+ default: paramMessage`In mapping ${"mapping"}, ${"target"} reads items of ${"source"} with Item or Slice, but ${"source"} is not a list.`,
241
+ },
242
+ },
243
+ "mapping-from-select-on-model": {
244
+ severity: "error",
245
+ messages: {
246
+ default: paramMessage`In mapping ${"mapping"}, ${"target"} is a target model, filled from a form: Item and Slice name items of a list field, for a target property.`,
247
+ },
248
+ },
249
+ "mapping-from-wrapper": {
250
+ severity: "warning",
251
+ messages: {
252
+ default: paramMessage`In mapping ${"mapping"}, ${"target"} has no field of its own: it wraps fields of ${"context"}. Rules keyed by the response's properties cannot write an element with no property behind it, so its contents are left out.`,
253
+ },
254
+ },
255
+ "tag-not-declared": {
256
+ severity: "error",
257
+ messages: {
258
+ default: paramMessage`${"name"} is tagged ${"tag"} from ${"enumName"}, which no namespace declares with @Meta.tags. Declare the program's tags once, e.g. @Meta.tags(${"enumName"}).`,
259
+ },
260
+ },
261
+ "entity-not-declared": {
262
+ severity: "error",
263
+ messages: {
264
+ default: paramMessage`${"name"} is asked about entity ${"entity"} from ${"enumName"}, which no namespace declares with @Meta.entities. Declare the program's entities once, e.g. @Meta.entities(${"enumName"}).`,
265
+ },
266
+ },
267
+ "widget-not-declared": {
268
+ severity: "error",
269
+ messages: {
270
+ default: paramMessage`${"name"} uses widget ${"widget"} from ${"enumName"}, which no namespace declares with @UI.widgets, so no renderer is known to provide it. Declare the program's widgets once, e.g. @UI.widgets(${"enumName"}).`,
271
+ },
272
+ },
36
273
  "condition-path-unresolved": {
37
274
  severity: "error",
38
275
  messages: {
@@ -135,39 +372,42 @@ export const $lib = createTypeSpecLibrary({
135
372
  default: paramMessage`${"name"} is always required but only sometimes visible, so an applicant can be blocked by a field they cannot see. Make it optional and use @Validation.requiredWhen, or drop the visibility condition.`,
136
373
  },
137
374
  },
138
- "override-path-unresolved": {
139
- severity: "error",
140
- messages: {
141
- default: paramMessage`@UI.overrides path "${"path"}" does not resolve: ${"reason"}.`,
142
- },
143
- },
144
- "visible-read-only-without-read-only": {
375
+ "property-casing-collision": {
145
376
  severity: "error",
146
377
  messages: {
147
- default: paramMessage`@UI.overrides path "${"path"}" requests visibleReadOnly without readOnly. A visible read-only control must also be marked readOnly so schema and UI cannot disagree.`,
378
+ default: paramMessage`${"model"}.${"first"} and ${"model"}.${"second"} would both be emitted as "${"name"}". Rename one, or give one an @encodedName("application/json", ...).`,
148
379
  },
149
380
  },
150
- "section-orphan": {
381
+ "property-casing-inconsistent": {
151
382
  severity: "error",
152
383
  messages: {
153
- default: paramMessage`${"name"} is in no section, so it renders nowhere. Give it a @UI.section, or @UI.omit it if that is deliberate.`,
384
+ default: paramMessage`${"property"} would be emitted as "${"name"}", but ${"other"} as "${"otherName"}". A property name is emitted the same way everywhere, so give both the same @encodedName.`,
154
385
  },
155
386
  },
156
387
  },
388
+ emitter: {
389
+ options: EmitterOptionsSchema,
390
+ },
157
391
  state: {
158
392
  questionMeta: {},
159
393
  formMeta: {},
394
+ layout: {},
395
+ layoutField: {},
396
+ flatten: {},
397
+ tagSets: {},
160
398
  tags: {},
399
+ tagMembers: {},
400
+ entitySets: {},
161
401
  entity: {},
402
+ entityMember: {},
162
403
  responseRole: {},
163
404
  label: {},
164
405
  helpText: {},
406
+ widgets: {},
165
407
  widget: {},
408
+ widgetMember: {},
166
409
  encodedCheckboxGroup: {},
167
- sections: {},
168
- section: {},
169
410
  order: {},
170
- overrides: {},
171
411
  readOnly: {},
172
412
  omit: {},
173
413
  visibleWhen: {},
@@ -189,6 +429,15 @@ export const $lib = createTypeSpecLibrary({
189
429
  calculationMaterialization: {},
190
430
  evaluationOrder: {},
191
431
  totals: {},
432
+ mappingTargets: {},
433
+ mappedTo: {},
434
+ mappingPaths: {},
435
+ mappedFrom: {},
436
+ mappingTransformSets: {},
437
+ mappingTransform: {},
438
+ mappingMatch: {},
439
+ mappingRequired: {},
440
+ mappingWhen: {},
192
441
  },
193
442
  } as const);
194
443
 
package/src/linter.ts CHANGED
@@ -1,4 +1,4 @@
1
- import type { Model, ModelProperty, Scalar } from "@typespec/compiler";
1
+ import type { Enum, Model, ModelProperty, Scalar } from "@typespec/compiler";
2
2
  import {
3
3
  createRule,
4
4
  defineCodeFix,
@@ -15,12 +15,10 @@ import {
15
15
  import {
16
16
  allBlocks,
17
17
  modelOrder,
18
- orderedProps,
19
18
  propEnabledWhen,
20
19
  propOmit,
21
20
  propReadOnlyWhen,
22
21
  propRequiredWhen,
23
- propSection,
24
22
  propValidationConstraintsWhen,
25
23
  propVisibleWhen,
26
24
  } from "./model.js";
@@ -49,12 +47,14 @@ const orphanQuestion = createRule({
49
47
  // property, by extending it, or by being reached through a model that is not itself
50
48
  // a question -- and all three have to count, or the rule reports a question that a
51
49
  // form does ask.
52
- const seen = new Set<Model | Scalar>();
53
- const reach = (type: Model | Scalar, viaComposition: boolean): void => {
50
+ const seen = new Set<Held>();
51
+ const reach = (type: Held, viaComposition: boolean): void => {
54
52
  const block = byType.get(type);
55
53
  if (block && viaComposition) referenced.add(block.id);
56
54
  if (seen.has(type)) return;
57
55
  seen.add(type);
56
+ // A code list holds nothing further.
57
+ if (type.kind === "Enum") return;
58
58
  // Extending a question composes it, for a scalar as much as for a model: naming a
59
59
  // shape does not make the shape unasked.
60
60
  const base = type.kind === "Model" ? type.baseModel : type.baseScalar;
@@ -93,16 +93,23 @@ const orphanQuestion = createRule({
93
93
  * three codes, so the *list* is what the form asks -- and the entries can be a question too.
94
94
  * Returning only the entries reports the list as composed by nothing.
95
95
  */
96
- function held(prop: ModelProperty): (Model | Scalar)[] {
96
+ function held(prop: ModelProperty): Held[] {
97
97
  const type = prop.type;
98
- if (type.kind === "Scalar") return [type];
98
+ if (type.kind === "Scalar" || type.kind === "Enum") return [type];
99
99
  if (type.kind !== "Model") return [];
100
- const out: (Model | Scalar)[] = [type];
100
+ const out: Held[] = [type];
101
101
  const item = type.indexer?.value;
102
- if (item && (item.kind === "Model" || item.kind === "Scalar")) out.push(item);
102
+ if (
103
+ item &&
104
+ (item.kind === "Model" || item.kind === "Scalar" || item.kind === "Enum")
105
+ )
106
+ out.push(item);
103
107
  return out;
104
108
  }
105
109
 
110
+ /** What a question can be: an object, a single value, or a code list. */
111
+ type Held = Model | Scalar | Enum;
112
+
106
113
  const questionDocs = createRule({
107
114
  name: "require-question-docs",
108
115
  severity: "warning",
@@ -127,43 +134,6 @@ const questionDocs = createRule({
127
134
  },
128
135
  });
129
136
 
130
- const sectionUnused = createRule({
131
- name: "section-unused",
132
- severity: "warning",
133
- description: "A declared section that no field is placed in.",
134
- messages: {
135
- default: paramMessage`Section "${"section"}" on ${"form"} holds no fields, so it will not render. Usually this means a field was dropped.`,
136
- },
137
- create(context) {
138
- return {
139
- root: (program) => {
140
- for (const block of allBlocks(program)) {
141
- if (
142
- block.kind !== "form" ||
143
- !block.sections ||
144
- block.model.kind !== "Model"
145
- )
146
- continue;
147
- const used = new Set<string>();
148
- for (const prop of orderedProps(program, block)) {
149
- const section = propSection(program, prop);
150
- if (section) used.add(section.name);
151
- }
152
- for (const member of block.sections.members.values()) {
153
- if (used.has(member.name)) continue;
154
- // A documented empty section is deliberate static presentation content.
155
- if (getDoc(program, member)) continue;
156
- context.reportDiagnostic({
157
- target: member,
158
- format: { section: member.name, form: block.id },
159
- });
160
- }
161
- }
162
- },
163
- };
164
- },
165
- });
166
-
167
137
  const orderIncomplete = createRule({
168
138
  name: "order-incomplete",
169
139
  severity: "warning",
@@ -231,7 +201,7 @@ const redeclaredProperty = createRule({
231
201
  severity: "warning",
232
202
  description: "A derived block re-declaring a property it already inherits.",
233
203
  messages: {
234
- default: paramMessage`${"model"} re-declares ${"names"} identically to ${"base"}. A redeclaration that narrows -- making an optional member required for this form -- says something; one that repeats says nothing, and leaves two copies to keep in step by hand. For presentation only, use @UI.overrides.`,
204
+ default: paramMessage`${"model"} re-declares ${"names"} identically to ${"base"}. A redeclaration that narrows -- making an optional member required for this form -- says something; one that repeats says nothing, and leaves two copies to keep in step by hand. To present it differently in one form, use a @UI.layout.`,
235
205
  },
236
206
  create(context) {
237
207
  return {
@@ -360,7 +330,6 @@ export const $linter = defineLinter({
360
330
  rules: [
361
331
  orphanQuestion,
362
332
  questionDocs,
363
- sectionUnused,
364
333
  orderIncomplete,
365
334
  redeclaredProperty,
366
335
  untaggedQuestion,
@@ -370,7 +339,6 @@ export const $linter = defineLinter({
370
339
  enable: {
371
340
  "simpler-forms/no-orphan-question": true,
372
341
  "simpler-forms/require-question-docs": true,
373
- "simpler-forms/section-unused": true,
374
342
  "simpler-forms/order-incomplete": true,
375
343
  "simpler-forms/no-redeclared-property": true,
376
344
  "simpler-forms/require-question-tags": true,
@@ -0,0 +1,216 @@
1
+ import type {
2
+ Diagnostic,
3
+ EnumMember,
4
+ Model,
5
+ ModelProperty,
6
+ Program,
7
+ } from "@typespec/compiler";
8
+ import { createDiagnostic } from "./lib.js";
9
+ import { type MappingNode, type ResolvedMapping, shapeOf } from "./mapping.js";
10
+ import {
11
+ allMappingFromLinks,
12
+ modelProperties,
13
+ propMappedFromLinks,
14
+ } from "./model.js";
15
+
16
+ /**
17
+ * `form`'s mapping in `mapping`, read from the `@Mapping.from` links on its target, or
18
+ * undefined if no target model names `form`.
19
+ *
20
+ * The result is the tree `resolveMapping` builds from `@Mapping.to`, keyed by the form's
21
+ * properties, so an emitter can read either. Each target property is filled from the field
22
+ * its `@Mapping.from` names, found among the fields of the one its parent is filled from; one
23
+ * found below a field with no element of its own lands in a group. A target property with
24
+ * no `@Mapping.from` whose own properties are filled is a wrapper element, which a tree keyed
25
+ * by the form's properties cannot hold: it is left out, with a `mapping-from-wrapper` problem
26
+ * for an emitter whose output cannot hold it either to report. A field named with `Item` or
27
+ * `Slice` fills its target with some of its items: the node's `select`.
28
+ */
29
+ export function resolveMappingFrom(
30
+ program: Program,
31
+ form: Model,
32
+ mapping: EnumMember,
33
+ ): { resolved: ResolvedMapping; problems: Diagnostic[] } | undefined {
34
+ const target = mappedFromRoot(program, form, mapping);
35
+ if (!target) return undefined;
36
+ const problems: Diagnostic[] = [];
37
+
38
+ const walk = (
39
+ into: Model,
40
+ from: Model,
41
+ prefix: string[],
42
+ stack: Model[],
43
+ ): MappingNode[] => {
44
+ const nodes: MappingNode[] = [];
45
+ for (const element of modelProperties(into)) {
46
+ const to = shapeOf(element.type);
47
+ const links = propMappedFromLinks(program, element, mapping);
48
+ if (!links.length) {
49
+ if (!to.object || to.array || stack.includes(to.object)) continue;
50
+ // Structure: its own elements are filled from the same field as its parent.
51
+ const inner = walk(to.object, from, prefix, [...stack, to.object]);
52
+ if (inner.length)
53
+ problems.push(
54
+ createDiagnostic({
55
+ code: "mapping-from-wrapper",
56
+ target: element,
57
+ format: {
58
+ mapping: mapping.name,
59
+ target: describe(element),
60
+ context: from.name || "an anonymous model",
61
+ },
62
+ }),
63
+ );
64
+ continue;
65
+ }
66
+ const found = links
67
+ .map((link) => ({ link, path: pathTo(from, link.source) }))
68
+ .find((candidate) => candidate.path !== undefined);
69
+ if (!found) {
70
+ problems.push(
71
+ createDiagnostic({
72
+ code: "mapping-from-unresolved",
73
+ target: element,
74
+ format: {
75
+ mapping: mapping.name,
76
+ target: describe(element),
77
+ source: links.map((link) => describe(link.source)).join(" or "),
78
+ context: from.name || "an anonymous model",
79
+ },
80
+ }),
81
+ );
82
+ continue;
83
+ }
84
+ const { link } = found;
85
+ const path = found.path!;
86
+ const source = path.at(-1)!;
87
+ const sourcePath = [...prefix, ...path.map((p) => p.name)];
88
+ const listed = shapeOf(source.type);
89
+ if (link.select && !listed.array) {
90
+ problems.push(
91
+ createDiagnostic({
92
+ code: "mapping-from-select-not-a-list",
93
+ target: element,
94
+ format: {
95
+ mapping: mapping.name,
96
+ target: describe(element),
97
+ source: sourcePath.join("."),
98
+ },
99
+ }),
100
+ );
101
+ continue;
102
+ }
103
+ // One item of a list is a single value, or a single object; a slice is still a list.
104
+ const shape =
105
+ link.select && "index" in link.select
106
+ ? { array: false, object: listed.object }
107
+ : listed;
108
+ if (shape.array !== to.array) {
109
+ problems.push(
110
+ createDiagnostic({
111
+ code: "mapping-from-cardinality-mismatch",
112
+ target: element,
113
+ format: {
114
+ mapping: mapping.name,
115
+ target: describe(element),
116
+ source: sourcePath.join("."),
117
+ targetShape: to.array ? "a list" : "a single value",
118
+ sourceShape: shape.array ? "a list" : "a single value",
119
+ },
120
+ }),
121
+ );
122
+ continue;
123
+ }
124
+ const children =
125
+ shape.object && to.object && !stack.includes(to.object)
126
+ ? walk(to.object, shape.object, sourcePath, [...stack, to.object])
127
+ : [];
128
+ insert(nodes, path, prefix, {
129
+ sourcePath,
130
+ source,
131
+ target: element,
132
+ kind: shape.array ? "array" : shape.object ? "object" : "leaf",
133
+ children,
134
+ ...(link.select ? { select: link.select } : {}),
135
+ });
136
+ }
137
+ return nodes;
138
+ };
139
+
140
+ const children = walk(target, form, [], [target]);
141
+ return {
142
+ resolved: { mapping, source: form, target, children },
143
+ problems,
144
+ };
145
+ }
146
+
147
+ /** The target model that names `form` with `@Mapping.from` in `mapping`. */
148
+ export function mappedFromRoot(
149
+ program: Program,
150
+ form: Model,
151
+ mapping: EnumMember,
152
+ ): Model | undefined {
153
+ for (const [target, links] of allMappingFromLinks(program))
154
+ if (
155
+ target.kind === "Model" &&
156
+ links.some((link) => link.mapping === mapping && link.source === form)
157
+ )
158
+ return target;
159
+ return undefined;
160
+ }
161
+
162
+ /**
163
+ * The properties from `model` to `field`, `field` last: a property of `model` itself, or one
164
+ * below an object property of it with no element of its own. A copy made by spread or `is`
165
+ * counts as the property it was copied from.
166
+ */
167
+ function pathTo(
168
+ model: Model,
169
+ field: ModelProperty,
170
+ seen: Model[] = [],
171
+ ): ModelProperty[] | undefined {
172
+ for (const prop of modelProperties(model))
173
+ if (copies(prop, field)) return [prop];
174
+ for (const prop of modelProperties(model)) {
175
+ const shape = shapeOf(prop.type);
176
+ if (!shape.object || shape.array || seen.includes(shape.object)) continue;
177
+ const below = pathTo(shape.object, field, [...seen, model]);
178
+ if (below) return [prop, ...below];
179
+ }
180
+ return undefined;
181
+ }
182
+
183
+ const copies = (prop: ModelProperty, field: ModelProperty) => {
184
+ for (let p: ModelProperty | undefined = prop; p; p = p.sourceProperty)
185
+ if (p === field) return true;
186
+ return false;
187
+ };
188
+
189
+ /** Adds `node` under group nodes for each property `path` passes through on the way to it. */
190
+ function insert(
191
+ nodes: MappingNode[],
192
+ path: ModelProperty[],
193
+ prefix: string[],
194
+ node: MappingNode,
195
+ ): void {
196
+ let level = nodes;
197
+ const steps = [...prefix];
198
+ for (const prop of path.slice(0, -1)) {
199
+ steps.push(prop.name);
200
+ let group = level.find((n) => n.kind === "group" && n.source === prop);
201
+ if (!group) {
202
+ group = {
203
+ sourcePath: [...steps],
204
+ source: prop,
205
+ kind: "group",
206
+ children: [],
207
+ };
208
+ level.push(group);
209
+ }
210
+ level = group.children;
211
+ }
212
+ level.push(node);
213
+ }
214
+
215
+ const describe = (prop: ModelProperty) =>
216
+ prop.model?.name ? `${prop.model.name}.${prop.name}` : prop.name;