@echelon-foundry/design-system 0.12.0 → 0.13.0-main.263.1

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.
@@ -0,0 +1,395 @@
1
+ /// Design-token reference validation (LRP-001). The source of truth is the
2
+ /// Forma installation being validated against: its DTCG token sources and
3
+ /// its shipped stylesheets. Nothing here lists token names of its own.
4
+ module Forma.TokenValidator.Validation
5
+
6
+ open System
7
+ open System.IO
8
+ open System.Text.Json.Nodes
9
+ open Forma.TokenValidator.Css
10
+
11
+ /// The Forma-owned custom property namespace.
12
+ let FormaPrefix = "--ef-"
13
+
14
+ /// Prefixes that look like an attempt at a Forma token but are not the
15
+ /// namespace (`--forma-text`, `--ef_color`, `--EF-color`).
16
+ let private lookalikePrefixes = [ "--forma-"; "--echelon-"; "--ef_"; "--ef--"; "--efc-" ]
17
+
18
+ type Severity =
19
+ | Blocking
20
+ | Advisory
21
+
22
+ type Finding =
23
+ { Code: string
24
+ Severity: Severity
25
+ File: string
26
+ Line: int
27
+ Name: string
28
+ Message: string }
29
+
30
+ type TokenEntry =
31
+ { Path: string list
32
+ CssName: string
33
+ Theme: string option
34
+ Alias: string option
35
+ Deprecated: string option
36
+ Source: string }
37
+
38
+ /// What a Forma installation exports.
39
+ type Registry =
40
+ { Tokens: TokenEntry list
41
+ /// Every --ef-* custom property Forma defines: token sources plus
42
+ /// declarations in its shipped CSS.
43
+ Defined: Set<string>
44
+ /// --ef-* properties Forma reads with a fallback but never declares:
45
+ /// documented inputs such as --ef-stack-gap. Consumers may set them.
46
+ Hooks: Set<string>
47
+ Deprecated: Map<string, string>
48
+ /// Prefixes Forma's color contract marks as implementation variables
49
+ /// (contracts/color-contract.json internalVariables): defined, but not
50
+ /// a consumer compatibility contract, so applications must not read them.
51
+ Internal: string list
52
+ FormaCss: Declaration list }
53
+
54
+ // ---------------------------------------------------------------------------
55
+ // Token sources (DTCG)
56
+ // ---------------------------------------------------------------------------
57
+
58
+ let private cssSegment (segment: string) = segment.Trim().ToLowerInvariant().Replace("_", "-").Replace(" ", "-")
59
+
60
+ /// The custom property a token compiles to (tools/TokenCompiler): semantic
61
+ /// tokens drop the "semantic.<theme>" prefix; every other path is used whole.
62
+ let cssNameOf (path: string list) =
63
+ match path with
64
+ | "semantic" :: _ :: rest when not rest.IsEmpty -> FormaPrefix + (rest |> List.map cssSegment |> String.concat "-")
65
+ | _ -> FormaPrefix + (path |> List.map cssSegment |> String.concat "-")
66
+
67
+ let private themeOf (path: string list) =
68
+ match path with
69
+ | "semantic" :: theme :: _ :: _ -> Some theme
70
+ | _ -> None
71
+
72
+ let private deprecationOf (node: JsonObject) =
73
+ match node["$deprecated"] with
74
+ | null -> None
75
+ | :? JsonValue as value ->
76
+ match value.GetValueKind() with
77
+ | Text.Json.JsonValueKind.True -> Some ""
78
+ | Text.Json.JsonValueKind.String -> Some(value.GetValue<string>())
79
+ | _ -> None
80
+ | _ -> None
81
+
82
+ let private aliasOf (node: JsonNode) =
83
+ match node with
84
+ | :? JsonValue as value when value.GetValueKind() = Text.Json.JsonValueKind.String ->
85
+ let text = value.GetValue<string>()
86
+ if text.Length > 2 && text.StartsWith("{") && text.EndsWith("}") then Some(text.Substring(1, text.Length - 2)) else None
87
+ | _ -> None
88
+
89
+ /// Tokens of one DTCG document. A group's $deprecated applies to its tokens.
90
+ let rec private collect (source: string) (deprecated: string option) (path: string list) (node: JsonNode) : TokenEntry list =
91
+ match node with
92
+ | :? JsonObject as obj ->
93
+ let deprecated = deprecationOf obj |> Option.orElse deprecated
94
+ match obj["$value"] with
95
+ | null ->
96
+ obj
97
+ |> Seq.filter (fun pair -> not (pair.Key.StartsWith("$")) && not (isNull pair.Value))
98
+ |> Seq.collect (fun pair -> collect source deprecated (path @ [ pair.Key ]) pair.Value)
99
+ |> Seq.toList
100
+ | value ->
101
+ [ { Path = path
102
+ CssName = cssNameOf path
103
+ Theme = themeOf path
104
+ Alias = aliasOf value
105
+ Deprecated = deprecated
106
+ Source = source } ]
107
+ | _ -> []
108
+
109
+ let tokensOf (file: string) =
110
+ match JsonNode.Parse(File.ReadAllText file) with
111
+ | null -> []
112
+ | root -> collect file None [] root
113
+
114
+ // ---------------------------------------------------------------------------
115
+ // Registry
116
+ // ---------------------------------------------------------------------------
117
+
118
+ let private cssFilesUnder (directory: string) =
119
+ if Directory.Exists directory then
120
+ Directory.EnumerateFiles(directory, "*.css", SearchOption.AllDirectories) |> Seq.sort |> Seq.toList
121
+ else []
122
+
123
+ let isForma (name: string) = name.StartsWith(FormaPrefix, StringComparison.Ordinal)
124
+
125
+ let declarationsOf (files: string list) =
126
+ files |> List.collect (fun file -> declarations file (File.ReadAllText file))
127
+
128
+ /// Token sources shipped with (or kept in) a Forma root: the core token file
129
+ /// and any theme token files.
130
+ let tokenSourcesOf (root: string) =
131
+ let core = Path.Combine(root, "tokens", "echelon.tokens.json")
132
+ let themes =
133
+ let directory = Path.Combine(root, "themes")
134
+ if Directory.Exists directory then
135
+ Directory.EnumerateFiles(directory, "*.tokens.json", SearchOption.AllDirectories) |> Seq.sort |> Seq.toList
136
+ else []
137
+ (if File.Exists core then [ core ] else []) @ themes
138
+
139
+ let private internalPrefixesOf (root: string) =
140
+ let contract = Path.Combine(root, "contracts", "color-contract.json")
141
+ if not (File.Exists contract) then []
142
+ else
143
+ match JsonNode.Parse(File.ReadAllText contract) with
144
+ | :? JsonObject as obj ->
145
+ match obj["internalVariables"] with
146
+ | :? JsonObject as internalVariables ->
147
+ match internalVariables["prefixes"] with
148
+ | :? JsonArray as prefixes -> prefixes |> Seq.choose (fun p -> if isNull p then None else Some(p.GetValue<string>())) |> Seq.toList
149
+ | _ -> []
150
+ | _ -> []
151
+ | _ -> []
152
+
153
+ /// Build the registry from a Forma root: a repository checkout after
154
+ /// `npm run build`, or an installed package
155
+ /// (node_modules/@echelon-foundry/design-system). Both carry the token source
156
+ /// and the built stylesheets in dist/.
157
+ let registryOf (root: string) =
158
+ let sources = tokenSourcesOf root
159
+ if sources.IsEmpty then failwith $"no token source under '{root}' (expected tokens/echelon.tokens.json)"
160
+ let dist = Path.Combine(root, "dist")
161
+ let css = cssFilesUnder dist
162
+ if css.IsEmpty then failwith $"no built stylesheets under '{dist}' (run npm run build, or point --forma at an installed package)"
163
+ let tokens = sources |> List.collect tokensOf
164
+ let formaCss = declarationsOf css
165
+ let declared = formaCss |> List.map (fun d -> d.Property) |> List.filter isForma |> Set.ofList
166
+ let defined = Set.union declared (tokens |> List.map (fun t -> t.CssName) |> Set.ofList)
167
+ let hooks =
168
+ formaCss
169
+ |> List.collect (fun d -> d.References)
170
+ |> List.filter (fun r -> r.HasFallback && isForma r.Name && not (defined.Contains r.Name))
171
+ |> List.map (fun r -> r.Name)
172
+ |> Set.ofList
173
+ { Tokens = tokens
174
+ Defined = defined
175
+ Hooks = hooks
176
+ Deprecated = tokens |> List.choose (fun t -> t.Deprecated |> Option.map (fun d -> t.CssName, d)) |> Map.ofList
177
+ Internal = internalPrefixesOf root
178
+ FormaCss = formaCss }
179
+
180
+ let exported (registry: Registry) = Set.union registry.Defined registry.Hooks
181
+
182
+ let isInternal (registry: Registry) (name: string) =
183
+ registry.Internal |> List.exists (fun prefix -> name.StartsWith(prefix, StringComparison.Ordinal))
184
+
185
+ // ---------------------------------------------------------------------------
186
+ // Rules
187
+ // ---------------------------------------------------------------------------
188
+
189
+ let private finding code file line name message =
190
+ { Code = code; Severity = Blocking; File = file; Line = line; Name = name; Message = message }
191
+
192
+ /// A known name this one would be if a namespace segment had not been
193
+ /// dropped (--ef-spacing-4 for --ef-primitive-spacing-4, --ef-text-primary
194
+ /// for --ef-color-text-primary).
195
+ let namespaceSlip (known: Set<string>) (name: string) =
196
+ let tail = name.Substring(FormaPrefix.Length)
197
+ known
198
+ |> Seq.tryFind (fun candidate ->
199
+ let parts = candidate.Substring(FormaPrefix.Length).Split('-') |> List.ofArray
200
+ parts.Length > 1
201
+ && (parts |> List.indexed |> List.exists (fun (i, _) ->
202
+ parts |> List.removeAt i |> String.concat "-" = tail)))
203
+
204
+ let private lookalike (name: string) =
205
+ lookalikePrefixes |> List.tryFind (fun prefix -> name.StartsWith(prefix, StringComparison.OrdinalIgnoreCase))
206
+ |> Option.orElse (if name.StartsWith("--ef-", StringComparison.OrdinalIgnoreCase) && not (isForma name) then Some "--EF-" else None)
207
+
208
+ /// Levenshtein distance, for "did you mean" on misspelt token names.
209
+ let editDistance (a: string) (b: string) =
210
+ let step (previous: int array) (i, ca: char) =
211
+ b
212
+ |> Seq.indexed
213
+ |> Seq.fold (fun (row: int list) (j, cb) ->
214
+ let cost = if ca = cb then 0 else 1
215
+ min (min (previous[j + 1] + 1) (List.head row + 1)) (previous[j] + cost) :: row) [ i + 1 ]
216
+ |> List.rev
217
+ |> Array.ofList
218
+ a |> Seq.indexed |> Seq.fold step [| 0 .. b.Length |] |> Array.last
219
+
220
+ let private nearest (known: Set<string>) (name: string) =
221
+ known
222
+ |> Seq.map (fun candidate -> candidate, editDistance name candidate)
223
+ |> Seq.filter (fun (_, distance) -> distance <= 2)
224
+ |> Seq.sortBy snd
225
+ |> Seq.tryHead
226
+ |> Option.map fst
227
+
228
+ let private suggestion (registry: Registry) (name: string) =
229
+ let known = exported registry
230
+ if isForma name then namespaceSlip known name |> Option.orElse (nearest known name)
231
+ else
232
+ let lowered = name.ToLowerInvariant()
233
+ lookalikePrefixes
234
+ |> List.tryPick (fun prefix ->
235
+ if lowered.StartsWith(prefix) then
236
+ let candidate = FormaPrefix + lowered.Substring(prefix.Length).TrimStart('-')
237
+ if known.Contains candidate then Some candidate else namespaceSlip known candidate
238
+ else None)
239
+ |> Option.orElse (if lowered.StartsWith(FormaPrefix) && known.Contains lowered then Some lowered else None)
240
+
241
+ let private hint registry name =
242
+ match suggestion registry name with
243
+ | Some known -> $" Did you mean {known}?"
244
+ | None -> ""
245
+
246
+ /// One var() reference in application or Forma CSS. A fallback never makes
247
+ /// an unknown Forma token valid: var(--ef-nonexistent, white) is reported.
248
+ let checkReference (registry: Registry) (declaration: Declaration) (reference: VarReference) : Finding list =
249
+ let name = reference.Name
250
+ let at code message = [ finding code declaration.File declaration.Line name message ]
251
+ let fallbackNote = if reference.HasFallback then " A fallback value does not make it valid." else ""
252
+ if isForma name then
253
+ match registry.Deprecated |> Map.tryFind name with
254
+ | Some note ->
255
+ let detail = if String.IsNullOrWhiteSpace note then "" else " " + note
256
+ at "deprecated-token" $"{name} is deprecated in this Forma version.{detail}"
257
+ | None when isInternal registry name ->
258
+ at "internal-variable" $"{name} is a Forma implementation variable (contracts/color-contract.json internalVariables), not a consumer contract. Use a public token."
259
+ | None when (exported registry).Contains name -> []
260
+ | None ->
261
+ match namespaceSlip (exported registry) name with
262
+ | Some known -> at "namespace" $"{name} is not a Forma token; it drops a namespace segment of {known}.{fallbackNote}"
263
+ | None -> at "unknown-token" $"{name} is not exported by this Forma version.{fallbackNote}{hint registry name}"
264
+ else
265
+ match lookalike name with
266
+ | Some prefix -> at "namespace" $"{name} uses '{prefix}', which is not the Forma namespace '{FormaPrefix}'.{hint registry name}"
267
+ | None -> [] // application-owned custom property
268
+
269
+ /// A custom property declared by application CSS. Applications may set
270
+ /// Forma tokens and hooks (themes, brands, component inputs) but may not
271
+ /// mint new names in the Forma namespace.
272
+ let checkDeclaration (registry: Registry) (declaration: Declaration) : Finding list =
273
+ let name = declaration.Property
274
+ if not (name.StartsWith("--")) then []
275
+ elif isForma name then
276
+ if (exported registry).Contains name then []
277
+ else
278
+ [ finding "namespace" declaration.File declaration.Line name
279
+ $"{name} declares a new name in the Forma-owned namespace '{FormaPrefix}'. Use an application prefix, or a token this Forma version exports.{hint registry name}" ]
280
+ else
281
+ match lookalike name with
282
+ | Some prefix ->
283
+ [ finding "namespace" declaration.File declaration.Line name
284
+ $"{name} uses '{prefix}', which is not the Forma namespace '{FormaPrefix}'.{hint registry name}" ]
285
+ | None -> []
286
+
287
+ /// Custom properties that refer to each other in a cycle within one rule are
288
+ /// invalid at computed-value time (CSS Variables 1, section 2.3); every
289
+ /// property on the cycle becomes the guaranteed-invalid value.
290
+ let cyclesIn (declarations: Declaration list) : Finding list =
291
+ let custom = declarations |> List.filter (fun d -> d.Property.StartsWith("--"))
292
+ let edges = custom |> List.map (fun d -> d.Property, d.References |> List.map (fun r -> r.Name)) |> Map.ofList
293
+ let rec reaches target visited current =
294
+ match edges |> Map.tryFind current with
295
+ | None -> false
296
+ | Some next -> next |> List.exists (fun n -> n = target || (not (Set.contains n visited) && reaches target (Set.add n visited) n))
297
+ custom
298
+ |> List.filter (fun d -> reaches d.Property (Set.singleton d.Property) d.Property)
299
+ |> List.map (fun d -> finding "cycle" d.File d.Line d.Property $"{d.Property} refers back to itself through custom properties in '{d.Selector}', so it is invalid at computed-value time.")
300
+
301
+ /// Declarations that apply together: one rule, keyed by its full context so
302
+ /// blocks under mutually exclusive at-rules are never combined.
303
+ let private byRule (declarations: Declaration list) =
304
+ declarations |> List.groupBy (fun d -> d.File, d.Context) |> List.map snd
305
+
306
+ /// Validate application CSS against a Forma installation.
307
+ let validateCss (registry: Registry) (declarations: Declaration list) : Finding list =
308
+ let referenceFindings =
309
+ declarations |> List.collect (fun d -> d.References |> List.collect (checkReference registry d))
310
+ let declarationFindings = declarations |> List.collect (checkDeclaration registry)
311
+ let cycleFindings = declarations |> byRule |> List.collect cyclesIn
312
+ referenceFindings @ declarationFindings @ cycleFindings
313
+
314
+ // ---------------------------------------------------------------------------
315
+ // Forma's own sources (--self)
316
+ // ---------------------------------------------------------------------------
317
+
318
+ /// Alias targets, alias cycles and theme completeness across the token
319
+ /// sources, reporting every problem rather than stopping at the first.
320
+ let validateTokens (tokens: TokenEntry list) : Finding list =
321
+ let dotted (t: TokenEntry) = String.concat "." t.Path
322
+ let byPath = tokens |> List.map (fun t -> dotted t, t) |> Map.ofList
323
+ let at (t: TokenEntry) code message = finding code t.Source 0 (dotted t) message
324
+ let invalidAliases =
325
+ tokens
326
+ |> List.choose (fun t ->
327
+ t.Alias
328
+ |> Option.filter (fun alias -> not (byPath.ContainsKey alias))
329
+ |> Option.map (fun alias -> at t "invalid-alias" $"{dotted t} aliases {{{alias}}}, which no token source defines."))
330
+ let rec onCycle origin visited (t: TokenEntry) =
331
+ match t.Alias |> Option.bind (fun alias -> byPath |> Map.tryFind alias) with
332
+ | Some next when dotted next = origin -> true
333
+ | Some next when Set.contains (dotted next) visited -> false
334
+ | Some next -> onCycle origin (Set.add (dotted next) visited) next
335
+ | None -> false
336
+ let cycles =
337
+ tokens
338
+ |> List.filter (fun t -> onCycle (dotted t) Set.empty t)
339
+ |> List.map (fun t -> at t "cycle" $"{dotted t} is on an alias cycle.")
340
+ let themed = tokens |> List.filter (fun t -> t.Theme.IsSome) |> List.groupBy (fun t -> t.Source)
341
+ let themeGaps =
342
+ themed
343
+ |> List.collect (fun (source, entries) ->
344
+ let names theme = entries |> List.filter (fun t -> t.Theme = Some theme) |> List.map (fun t -> t.CssName) |> Set.ofList
345
+ let themes = entries |> List.choose (fun t -> t.Theme) |> List.distinct
346
+ let all = themes |> List.map names |> Set.unionMany
347
+ themes
348
+ |> List.collect (fun theme ->
349
+ Set.difference all (names theme)
350
+ |> Set.toList
351
+ |> List.map (fun name -> finding "theme-missing" source 0 name $"theme '{theme}' does not define {name}, which another theme in this source defines.")))
352
+ invalidAliases @ cycles @ themeGaps
353
+
354
+ /// A brand manifest's themes must define the same color roles, or a dark
355
+ /// page would show the light brand value for the missing role.
356
+ let validateBrand (file: string) : Finding list =
357
+ match JsonNode.Parse(File.ReadAllText file) with
358
+ | :? JsonObject as root ->
359
+ match root["themes"] with
360
+ | :? JsonObject as themes ->
361
+ let rec leaves (prefix: string list) (node: JsonNode) =
362
+ match node with
363
+ | :? JsonObject as obj -> obj |> Seq.collect (fun pair -> leaves (prefix @ [ pair.Key ]) pair.Value) |> Seq.toList
364
+ | _ -> [ cssNameOf prefix ]
365
+ let perTheme = themes |> Seq.map (fun pair -> pair.Key, leaves [] pair.Value |> Set.ofList) |> Seq.toList
366
+ let all = perTheme |> List.map snd |> Set.unionMany
367
+ perTheme
368
+ |> List.collect (fun (theme, names) ->
369
+ Set.difference all names
370
+ |> Set.toList
371
+ |> List.map (fun name -> finding "theme-missing" file 0 name $"brand theme '{theme}' does not define {name}, which another theme of this brand defines."))
372
+ | _ -> []
373
+ | _ -> []
374
+
375
+ /// Forma's own CSS: every --ef-* reference without a fallback must be
376
+ /// defined (a missing required definition), every reference must be in the
377
+ /// namespace, and no rule may hold a custom property cycle.
378
+ let validateFormaCss (registry: Registry) : Finding list =
379
+ let missing =
380
+ registry.FormaCss
381
+ |> List.collect (fun d ->
382
+ d.References
383
+ |> List.filter (fun r -> isForma r.Name && not r.HasFallback && not (registry.Defined.Contains r.Name))
384
+ |> List.map (fun r -> finding "missing-definition" d.File d.Line r.Name $"{r.Name} is read without a fallback but no token source or stylesheet defines it.{hint registry r.Name}"))
385
+ let deprecatedUse =
386
+ registry.FormaCss
387
+ |> List.collect (fun d ->
388
+ d.References
389
+ |> List.filter (fun r -> registry.Deprecated.ContainsKey r.Name)
390
+ |> List.map (fun r -> finding "deprecated-token" d.File d.Line r.Name $"{r.Name} is deprecated but Forma's own CSS still reads it."))
391
+ let lookalikes =
392
+ registry.FormaCss
393
+ |> List.collect (fun d -> d.References |> List.filter (fun r -> lookalike r.Name |> Option.isSome) |> List.collect (checkReference registry d))
394
+ let cycles = registry.FormaCss |> byRule |> List.collect cyclesIn
395
+ missing @ deprecatedUse @ lookalikes @ cycles