| # 9. Diagnostics |
|
|
| DSSL is loud. A mistake is an error with a place and a hint, not a silent no-op. |
|
|
| ## 9.1 Records |
|
|
| - **DIA-1.** A diagnostic is `{ file, line, message, hint? }`. `hint` is omitted (not null) |
| when there is none. Messages and hints are English text and are compared exactly by the |
| conformance tests, so an implementation MUST use the wording in this spec. |
| - **DIA-2.** *Errors* mean something was wrong and was dropped or replaced. A source is `ok` |
| when it has no errors. *Warnings* mean the source compiles and runs but is probably not what |
| the author meant. Warnings never change `ok`. |
| - **DIA-3.** A tool may offer a strict mode that treats warnings as failures |
| (`dssl check --strict`). That is a tool choice, not part of resolving. |
| - **DIA-4.** Errors from the parser come first, then errors from the resolver, each in the |
| order found. |
| - **DIA-5.** *Deduplication.* At the end of resolving, errors with the same file, line and |
| message are reduced to one, keeping the last occurrence, and the order of the others is |
| unchanged. |
| - **DIA-6.** Unknown words are errors, never noise. A word that is left over after a construct |
| has used what it understands is an error, not ignored. |
| - **DIA-7.** A lint or any other helper MUST NOT be able to break a compile. If it fails, its |
| warnings are dropped and everything else stands. |
|
|
| ## 9.2 Where each message is defined |
|
|
| Each message appears in the chapter that defines the construct it belongs to, in code font. The |
| conformance corpus (chapter 10) covers every message at least once. Appendix B is generated from |
| the reference implementation and lists every message template, so a gap between this spec and |
| the corpus shows up as a failing check. |
|
|
| ## 9.3 Did-you-mean |
|
|
| - **DIA-8.** `didYouMean(word, candidates)` returns the best candidate, or nothing: |
| 1. If the word or the candidate list is empty, return nothing. |
| 2. Lowercase the word. For each candidate in order, skipping empty ones, compute the |
| Levenshtein distance (insert, delete, substitute, each cost 1) between the lowercase word |
| and the lowercase text of the candidate. |
| 3. Keep the first candidate with the smallest distance. A later candidate with an equal |
| distance does not replace it. |
| 4. The tolerance is `max(2, floor(length of the word / 3))`. If the smallest distance is |
| larger, return nothing. Otherwise return the candidate as text, in its original case. |
| - **DIA-9.** The order of the candidates is the order of the sets and lists in appendix A, |
| which is the insertion order in the reference implementation. A different order can change |
| which of two equally close words is suggested, so implementations MUST keep it. |
| |
| ## 9.4 Warnings the resolver emits |
|
|
| | Where | Message starts with | |
| |---|---| |
| | 5.3, nested word near a state word | `"<w>" compiled as a descendant selector` | |
| | 6.3, row and column words | `two words in ...`, `"<w>" is written twice in ...`, `"<w>" has nowhere to go ...` | |
| | 6.6, `gradient:` and another image | `"<sel>" sets the background image twice` | |
| | 7.4, animation shorthand | `animation "<v>" references no motion ...`, `<prop> does nothing here ...` | |
| | 2.7, `raw { }` | `raw { } is verbatim CSS, so this line needs a ";" at the end` | |
| | same-rule display clash | `"<prop>:" expands to display: <v>, which overrides the earlier ...` | |
|
|
| - **DIA-10.** *Display clash.* Inside one rule, when a semantic property that expands to |
| `display` (`row`, `column`, `grid`, `stack`) comes after an explicit `display:` with a |
| different value, the warning is |
| `"<via>:" expands to display: <new>, which overrides the earlier "display: <old>" (line <n>) |
| in the same rule - later wins, so the earlier one is dead`. At most 400 warnings of this kind |
| are kept per file. Overrides across different rules are the cascade at work and get no |
| warning. |
| - **DIA-11.** *Raw semicolons.* In a `raw { }` body (comments blanked), a line that looks like |
| `name: value`, does not end in `;`, `{`, `}` or `,`, and is followed by another declaration |
| line or a line starting with `}`, is a warning at the line of that declaration inside the |
| block. |
|
|
| ## 9.5 Lint |
|
|
| A lint pass runs on the finished rules and adds warnings. It covers text contrast (WCAG ratio, |
| 4.5 for body text, 3 for large text), an outline removed from something you can tab to with no |
| `focus-visible` replacement, and an explicit width or height under 24px on a button or link. It |
| looks only at unconditional rules, follows tokens, alpha and `color-mix`, and is defined by |
| `lint.js`. |
|
|
| - **DIA-12.** A Level 2 implementation MAY omit the lint pass. It then declares `lint: false`, |
| and conformance tests compare warnings with the lint warnings removed. A lint warning is one |
| whose message starts with `text contrast is`, starts with `the focus outline is removed`, or |
| ends with `the smallest target WCAG 2.2 allows`. |
|
|
