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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@echelon-foundry/design-system",
-  "version": "0.12.0",
+  "version": "0.13.0-main.263.1",
   "private": false,
   "type": "module",
   "description": "Zero-component-runtime HTML and CSS design system for Echelon Foundry applications.",
@@ -47,6 +47,8 @@
     "docs/MARKETING-SITES.md",
     "tokens/echelon.tokens.json",
     "tools/color-contract",
+    "tools/TokenValidator/*.fs",
+    "tools/TokenValidator/TokenValidator.fsproj",
     "contracts/color-contract.json",
     "docs/COLOR.md",
     "figma/component-contracts.json",
@@ -71,7 +73,8 @@
     "assets:build": "node tools/build-assets.mjs",
     "build": "npm run clean && npm run tokens:build && npm run brands:build && npm run color:build && npm run marketing:theme && npm run runtime:build && npm run assets:build && npm run marketing:build && npm run example:install",
     "runtime:build": "node tools/build-runtime.mjs",
-    "test:tokens": "node --test tests/token-compiler.test.mjs",
+    "test:tokens": "node --test tests/token-compiler.test.mjs tests/token-validator.test.mjs",
+    "tokens:validate": "dotnet run --project tools/TokenValidator/TokenValidator.fsproj -c Release -- --self",
     "test:browser": "playwright test",
     "test:a11y": "playwright test tests/browser/accessibility.spec.mjs",
     "test:runtime": "node --test tests/zero-runtime.test.mjs",
@@ -79,7 +82,7 @@
     "test:color": "node --test tests/color-contract.test.mjs",
     "motion:audit": "node tools/motion-audit.mjs",
     "test:motion": "node --test tests/motion-audit.test.mjs tests/motion-gate.test.mjs && node tools/motion-audit.mjs --strict",
-    "check": "npm run build && npm run icons:check && npm run test:tokens && npm run test:brands && npm run test:runtime && npm run test:design && npm run test:color && npm run test:motion && npm run test:marketing && npm run test:character-grid && npm run test:figma && npm run test:css && npm run test:package && npm run workflow:test && npm run workflow:build && npm run test:workflow-package && npm run test:browser",
+    "check": "npm run build && npm run icons:check && npm run tokens:validate && npm run test:tokens && npm run test:brands && npm run test:runtime && npm run test:design && npm run test:color && npm run test:motion && npm run test:marketing && npm run test:character-grid && npm run test:figma && npm run test:css && npm run test:package && npm run workflow:test && npm run workflow:build && npm run test:workflow-package && npm run test:browser",
     "site:build": "npm run build && node tools/build-site.mjs",
     "site:test": "node --test tests/site-build.test.mjs tests/catalog-coverage.test.mjs tests/icon-docs.test.mjs tests/catalog-interaction.test.mjs",
     "site:check": "npm run site:build && npm run catalog:check && npm run site:test && npm run site:mobile",
@@ -97,7 +100,7 @@
     "test:marketing": "node --test tests/marketing-tokens.test.mjs tests/marketing-distribution.test.mjs tests/marketing-structure.test.mjs tests/site-css-policy.test.mjs",
     "example:install": "mkdir -p build/example && cp examples/echelon-marketing-site/forma.lock build/example/forma.lock && bash actions/install-presentation/install.sh --lock build/example/forma.lock --source dist/marketing --update --output examples/echelon-marketing-site/assets/forma",
     "policy:check": "dotnet run --project tools/SiteCssPolicy/SiteCssPolicy.fsproj --",
-    "release:check": "npm run build && npm run icons:check && npm run test:tokens && npm run test:brands && npm run test:runtime && npm run test:design && npm run test:motion && npm run test:marketing && npm run test:character-grid && npm run test:css && npm run test:package && npm run test:machine && playwright test tests/browser/marketing.spec.mjs && npm run site:check",
+    "release:check": "npm run build && npm run icons:check && npm run tokens:validate && npm run test:tokens && npm run test:brands && npm run test:runtime && npm run test:design && npm run test:motion && npm run test:marketing && npm run test:character-grid && npm run test:css && npm run test:package && npm run test:machine && playwright test tests/browser/marketing.spec.mjs && npm run site:check",
     "test:figma": "node --test tests/figma-contract.test.mjs",
     "catalog:check": "node tools/catalog/validate.mjs && node tools/catalog/inventory.mjs --check",
     "catalog:inventory": "node tools/catalog/inventory.mjs",

package/tools/TokenValidator/Css.fs

@@ -0,0 +1,171 @@
+/// A minimal, dependency-free CSS reader: enough structure to find custom
+/// property declarations and var() references with their selector, file and
+/// line. It is not a validating parser; malformed CSS still yields whatever
+/// declarations can be recognised.
+module Forma.TokenValidator.Css
+
+open System
+open System.Text
+
+type VarReference =
+    { Name: string
+      HasFallback: bool }
+
+type Declaration =
+    { File: string
+      Line: int
+      Selector: string
+      /// Every enclosing prelude, outermost first (at-rules and selectors).
+      Context: string
+      Property: string
+      Value: string
+      References: VarReference list }
+
+/// Replace comments with spaces and blank the contents of quoted strings,
+/// keeping their quotes and every newline, so offsets and line numbers still
+/// match the source. Braces, comment markers and var() inside a string
+/// (content: "}") are then inert.
+let normalise (text: string) =
+    let builder = StringBuilder(text.Length)
+    let blank (c: char) = if c = '\n' then '\n' else ' '
+    let rec go index (state: char option) inComment =
+        if index >= text.Length then ()
+        elif inComment then
+            if index + 1 < text.Length && text[index] = '*' && text[index + 1] = '/' then
+                builder.Append("  ") |> ignore
+                go (index + 2) None false
+            else
+                builder.Append(blank text[index]) |> ignore
+                go (index + 1) None true
+        else
+            match state with
+            | Some _ when text[index] = '\\' && index + 1 < text.Length ->
+                builder.Append(blank text[index]).Append(blank text[index + 1]) |> ignore
+                go (index + 2) state false
+            | Some quote when text[index] = quote ->
+                builder.Append(quote) |> ignore
+                go (index + 1) None false
+            | Some _ ->
+                builder.Append(blank text[index]) |> ignore
+                go (index + 1) state false
+            | None when index + 1 < text.Length && text[index] = '/' && text[index + 1] = '*' ->
+                builder.Append("  ") |> ignore
+                go (index + 2) None true
+            | None when text[index] = '"' || text[index] = '\'' ->
+                builder.Append(text[index]) |> ignore
+                go (index + 1) (Some text[index]) false
+            | None ->
+                builder.Append(text[index]) |> ignore
+                go (index + 1) None false
+    go 0 None false
+    builder.ToString()
+
+let private isNameChar (c: char) = Char.IsLetterOrDigit c || c = '-' || c = '_'
+
+/// Index of the parenthesis closing the one opened just before `start`.
+let private closingParen (value: string) start =
+    let rec go index depth =
+        if index >= value.Length then value.Length
+        else
+            match value[index] with
+            | '(' -> go (index + 1) (depth + 1)
+            | ')' when depth = 0 -> index
+            | ')' -> go (index + 1) (depth - 1)
+            | _ -> go (index + 1) depth
+    go start 0
+
+/// Every var(--name[, fallback]) in a value, including those nested in
+/// fallbacks, in source order.
+let rec references (value: string) : VarReference list =
+    let index = value.IndexOf("var(", StringComparison.OrdinalIgnoreCase)
+    if index < 0 then []
+    else
+        let start = index + 4
+        let close = closingParen value start
+        let inner = value.Substring(start, close - start)
+        let nameStart = inner.Length - inner.TrimStart().Length
+        let name = inner.Substring(nameStart) |> Seq.takeWhile isNameChar |> Seq.toArray |> String
+        let rest = inner.Substring(nameStart + name.Length).TrimStart()
+        let fallback = if rest.StartsWith(",") then rest.Substring(1) else ""
+        let own =
+            if name.StartsWith("--") then [ { Name = name; HasFallback = rest.StartsWith(",") } ] else []
+        own @ references fallback @ references (value.Substring(min value.Length (close + 1)))
+
+/// Offsets at which each line starts, for line lookup by binary search.
+let private lineStarts (text: string) =
+    Array.append [| 0 |] (text |> Seq.indexed |> Seq.filter (fun (_, c) -> c = '\n') |> Seq.map (fun (i, _) -> i + 1) |> Seq.toArray)
+
+let private lineAt (starts: int array) offset =
+    let found = Array.BinarySearch(starts, offset)
+    if found >= 0 then found + 1 else ~~~found
+
+/// Split a block body at top-level semicolons, keeping each piece's offset.
+let private pieces (body: string) (offset: int) =
+    let rec go index depth quote start acc =
+        if index >= body.Length then List.rev ((start, body.Substring(start)) :: acc)
+        else
+            let c = body[index]
+            match quote with
+            | Some q when c = q -> go (index + 1) depth None start acc
+            | Some _ -> go (index + 1) depth quote start acc
+            | None ->
+                match c with
+                | '"' | '\'' -> go (index + 1) depth (Some c) start acc
+                | '(' -> go (index + 1) (depth + 1) None start acc
+                | ')' -> go (index + 1) (max 0 (depth - 1)) None start acc
+                | ';' when depth = 0 -> go (index + 1) depth None (index + 1) ((start, body.Substring(start, index - start)) :: acc)
+                | _ -> go (index + 1) depth None start acc
+    go 0 0 None 0 [] |> List.map (fun (start, piece) -> offset + start, piece)
+
+/// Declarations of one file. Nested blocks (@media, @layer, nesting) are
+/// walked; a declaration's selector is the innermost enclosing prelude.
+let declarations (file: string) (source: string) : Declaration list =
+    let text = normalise source
+    let starts = lineStarts text
+    let declarationOf (stack: string list) (offset: int, piece: string) =
+        let selector = match stack with innermost :: _ -> innermost | [] -> ""
+        let colon = piece.IndexOf(':')
+        let property = if colon > 0 then piece.Substring(0, colon).Trim() else ""
+        if colon <= 0 || property.Length = 0 || property.Contains("{") || property.Contains("}") || property.StartsWith("@") then None
+        else
+            let value = piece.Substring(colon + 1).Trim()
+            let leading = piece.Length - piece.TrimStart().Length
+            Some
+                { File = file
+                  Line = lineAt starts (offset + leading)
+                  Selector = selector
+                  Context = stack |> List.rev |> String.concat " » "
+                  Property = property
+                  Value = value
+                  References = references value }
+    // Walk the text, splitting at braces. Text between braces at one level is
+    // either declarations (inside a block) or a prelude (before '{').
+    let rec walk index segmentStart stack acc =
+        if index >= text.Length then
+            let tail =
+                match stack with
+                | _ :: _ -> pieces (text.Substring(segmentStart)) segmentStart |> List.choose (declarationOf stack)
+                | [] -> []
+            List.rev acc @ tail
+        else
+            match text[index] with
+            | '{' ->
+                // The segment before '{' may hold declarations followed by a nested prelude.
+                let segment = text.Substring(segmentStart, index - segmentStart)
+                let lastSemicolon = segment.LastIndexOf(';')
+                let declared, prelude =
+                    if lastSemicolon >= 0 then segment.Substring(0, lastSemicolon + 1), segment.Substring(lastSemicolon + 1)
+                    else "", segment
+                let found =
+                    match stack with
+                    | _ :: _ when declared.Length > 0 -> pieces declared segmentStart |> List.choose (declarationOf stack)
+                    | _ -> []
+                walk (index + 1) (index + 1) (prelude.Trim() :: stack) (List.rev found @ acc)
+            | '}' ->
+                let found =
+                    match stack with
+                    | _ :: _ -> pieces (text.Substring(segmentStart, index - segmentStart)) segmentStart |> List.choose (declarationOf stack)
+                    | [] -> []
+                walk (index + 1) (index + 1) (match stack with _ :: rest -> rest | [] -> []) (List.rev found @ acc)
+            | _ -> walk (index + 1) segmentStart stack acc
+    walk 0 0 [] []

package/tools/TokenValidator/Program.fs

@@ -0,0 +1,104 @@
+module Forma.TokenValidator.Program
+
+open System
+open System.IO
+open System.Text.Json
+open Forma.TokenValidator.Validation
+
+let private usage =
+    """usage: TokenValidator [--forma DIR] [--json] (--self | PATH...)
+
+  --forma DIR  Forma root to validate against: an installed package
+               (node_modules/@echelon-foundry/design-system) or a built
+               checkout. Default: the current directory.
+  --self       Validate Forma itself: token sources (aliases, cycles, theme
+               completeness), brand manifests, and every var() in the built
+               stylesheets.
+  PATH...      Application CSS files or directories (searched for *.css,
+               skipping node_modules) to validate against that Forma version.
+  --json       Print findings as JSON.
+
+Exit status: 0 no errors, 1 errors found, 2 invalid arguments or unreadable input."""
+
+type private Options =
+    { Forma: string
+      Self: bool
+      Json: bool
+      Paths: string list }
+
+let rec private parse (options: Options) (args: string list) =
+    match args with
+    | [] -> Ok { options with Paths = List.rev options.Paths }
+    | "--forma" :: dir :: rest -> parse { options with Forma = dir } rest
+    | "--self" :: rest -> parse { options with Self = true } rest
+    | "--json" :: rest -> parse { options with Json = true } rest
+    | ("--help" | "-h") :: _ -> Error ""
+    | flag :: _ when flag.StartsWith("--") -> Error $"unknown option {flag}"
+    | path :: rest -> parse { options with Paths = path :: options.Paths } rest
+
+let private cssFiles (path: string) =
+    if Directory.Exists path then
+        Directory.EnumerateFiles(path, "*.css", SearchOption.AllDirectories)
+        |> Seq.filter (fun file -> not (file.Split(Path.DirectorySeparatorChar) |> Array.contains "node_modules"))
+        |> Seq.sort
+        |> Seq.toList
+    elif File.Exists path then [ path ]
+    else failwith $"no such file or directory: {path}"
+
+let private relative (file: string) =
+    if String.IsNullOrEmpty file then file else Path.GetRelativePath(Environment.CurrentDirectory, file)
+
+let private render json (findings: Finding list) =
+    if json then
+        let rows =
+            findings
+            |> List.map (fun f ->
+                dict [ "code", box f.Code
+                       "severity", box (match f.Severity with Blocking -> "error" | Advisory -> "warning")
+                       "file", box (relative f.File)
+                       "line", box f.Line
+                       "name", box f.Name
+                       "message", box f.Message ])
+        printfn "%s" (JsonSerializer.Serialize(rows, JsonSerializerOptions(WriteIndented = true)))
+    else
+        findings
+        |> List.iter (fun f ->
+            let location = if f.Line > 0 then $"{relative f.File}:{f.Line}" else relative f.File
+            let severity = match f.Severity with Blocking -> "error" | Advisory -> "warning"
+            printfn $"{location}: {severity} [{f.Code}] {f.Message}")
+
+[<EntryPoint>]
+let main argv =
+    match parse { Forma = "."; Self = false; Json = false; Paths = [] } (List.ofArray argv) with
+    | Error message ->
+        if message <> "" then eprintfn "%s" message
+        eprintfn "%s" usage
+        if message = "" then 0 else 2
+    | Ok options when not options.Self && options.Paths.IsEmpty ->
+        eprintfn "%s" usage
+        2
+    | Ok options ->
+        try
+            let root = Path.GetFullPath options.Forma
+            let registry = registryOf root
+            let selfFindings =
+                if options.Self then
+                    let tokens = validateTokens registry.Tokens
+                    let brands =
+                        let directory = Path.Combine(root, "brands")
+                        if Directory.Exists directory then
+                            Directory.EnumerateFiles(directory, "*.brand.json") |> Seq.sort |> Seq.toList |> List.collect validateBrand
+                        else []
+                    tokens @ brands @ validateFormaCss registry
+                else []
+            let appFindings =
+                options.Paths |> List.collect cssFiles |> declarationsOf |> validateCss registry
+            let findings = (selfFindings @ appFindings) |> List.distinct |> List.sortBy (fun f -> f.File, f.Line, f.Name, f.Code)
+            render options.Json findings
+            let errors = findings |> List.filter (fun f -> f.Severity = Blocking) |> List.length
+            if not options.Json then
+                eprintfn $"token validation: {errors} error(s); {registry.Defined.Count} defined Forma properties and {registry.Hooks.Count} documented inputs in {relative root}"
+            if errors > 0 then 1 else 0
+        with ex ->
+            eprintfn $"ERROR {ex.Message}"
+            2

package/tools/TokenValidator/TokenValidator.fsproj

@@ -0,0 +1,12 @@
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net10.0</TargetFramework>
+    <AssemblyName>forma-token-validator</AssemblyName>
+  </PropertyGroup>
+  <ItemGroup>
+    <Compile Include="Css.fs" />
+    <Compile Include="Validation.fs" />
+    <Compile Include="Program.fs" />
+  </ItemGroup>
+</Project>