| # 10. The resolved document |
|
|
| The resolver turns one source file into a *resolved document*. This chapter defines its exact |
| shape and how two implementations are compared. This is what makes Level 2 testable without a |
| browser. |
|
|
| ## 10.1 Inputs |
|
|
| - **DOC-1.** The resolver takes: the source text, the file name, the token registry (4.5) and |
| the motion registry (7.3). The registry defaults are the built-in tokens and no motions. |
|
|
| ## 10.2 The document |
|
|
| ``` |
| { |
| errors: [ { file, line, message, hint? } ], // parser errors, then resolver errors |
| warnings: [ { file, line, message, hint? } ], |
| rules: [ Rule ], |
| shadowRules: [ Rule ], |
| raws: [ { css, file, line, order } ], |
| fontLinks: [ { url, line, file } ], |
| motionNames: [ name ], // motions defined in this file, in source order |
| motionFrames: { name: { essential, frames: [ { offset, props } ] } }, |
| mediaQueries: [ query ], // distinct, in first-use order |
| tokens: { key: value }, // the final token map |
| registryRule: Rule |
| } |
| Rule = { id, sel, media, signals, containers, layer, order, decls, file, line, pseudo, states } |
| decl = { prop, value, line, via?, fromGradient? } |
| ``` |
|
|
| - **DOC-2.** `rules` holds the ordinary rules and the token rules from `tokens` blocks, in the |
| order they were emitted. `shadowRules` holds pseudo-element rules (5.8). `raws` holds `raw` |
| and `fonts` font-face blocks in emission order. The registry rule is not in `rules`. |
| - **DOC-3.** `mediaQueries` lists every distinct entry of `media` found in `rules` and |
| `shadowRules`, in the order first seen, rules first. |
| - **DOC-4.** `tokens` is the final map of 4.3 (every key, with the last definition in source |
| order). Keys are compared as a set; the canonical form sorts them. |
| - **DOC-5.** A declaration may carry `via` (the semantic property that produced a `display` |
| value) and `fromGradient` (true for the `background-image` from `gradient:`). Both are part |
| of the record. |
| - **DOC-6.** `states` is a set of state words. It is written as a sorted array. |
| - **DOC-7.** `ok` is not stored. It is `errors.length == 0`. |
|
|
| ## 10.3 Canonical form |
|
|
| To compare two documents they are written as JSON in this form. |
|
|
| - **DOC-8.** Object keys are sorted by code point. Arrays keep their order, except `states` |
| and the `tokens` object, which are sorted. |
| - **DOC-9.** Numbers are written as the shortest decimal that reads back to the same |
| double, with no exponent for values between 1e-6 and 1e21, and no `-0`. Infinity is the |
| string `"Infinity"` (an `iterations` of `infinite`). |
| - **DOC-10.** A field that is `undefined` is omitted. A field that is `null` is `null`. |
| - **DOC-11.** Strings are compared as UTF-8 text. |
| - **DOC-12.** Two implementations are equal on a source when their canonical JSON is |
| byte-identical, after removing lint warnings from implementations that declared `lint: false` |
| (DIA-12). |
|
|
| ## 10.4 The corpus |
|
|
| The comparison needs inputs. The corpus is a folder of `.dssl` files: |
|
|
| - every stylesheet the site ships (`public/styles/*.dssl`), |
| - every fenced `dssl` block from the guide, the readme and this spec, |
| - the fixtures of the existing test suites, |
| - one file per diagnostic message, written to trigger it. |
|
|
| For each input, `scripts/native-dump.mjs` writes the canonical JSON of the reference engine's |
| output to `native/expected/`. The Rust test `native/tests/differential.rs` resolves the same |
| input and compares. |
|
|
| - **DOC-13.** The expected files are generated. They are committed so that a change in the |
| reference engine shows up in review as a change in expected output, and so the Rust tests run |
| without Node. |
| - **DOC-14.** A divergence (chapter 12) is excluded from the comparison by listing the input in |
| `native/corpus/EXCLUDED.md` with the divergence id. An excluded input is still run, and its |
| diff is printed, so a fix is noticed. |
| - **DOC-15.** Once the harness exists, `native/PARITY.md` lists, per chapter, how many corpus |
| inputs pass, fail and are excluded. It is generated by the test run and not written by hand. |
|
|
| ## 10.5 What the document does not contain |
|
|
| - The syntax tree (Level 1 compares it separately, 2.9). |
| - Behaviors (they are expanded during the walk and do not appear in the output). |
| - Anything about a particular element. Matching is stage 3 and needs a document. |
|
|
