@josueavalosjim/taste-check 0.8.0 → 0.9.0

package/README.md

@@ -342,6 +342,23 @@ Point your editor at `schema/config.schema.json` for completion and inline
 docs. Paths inside a config resolve against the config file, so it can be run
 from anywhere.
 
+Unknown keys are rejected, because a misspelled key that silently does nothing
+is a config that looks like it is working. `$comment` is the exception: it is
+allowed wherever an object is, ignored, and takes a string or an array of them.
+A config you are expected to live with for years should let you write down why
+it is the way it is.
+
+```json
+{
+  "$comment": "Guards the ramp itself. The browser suite only covers tokens some selector reaches.",
+  "contrast": {
+    "pairs": [
+      { "$comment": "Documented at 6.13:1 in tokens.css.", "fg": "--ink-muted", "bg": "--bg", "min": 4.5 }
+    ]
+  }
+}
+```
+
 | Key | Meaning |
 | --- | --- |
 | `contrast.tokens` | CSS files holding the custom properties. Later files override earlier ones. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@josueavalosjim/taste-check",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Design review in CI with a line down the middle: measured checks that gate the build (WCAG contrast from your tokens or from a real rendered page, one-off values in your markup) and a fresh-eyes model judge whose verdicts stay advisory. Zero dependencies. Ships no design rules of its own.",
   "keywords": [
     "accessibility",

package/schema/config.schema.json

@@ -89,11 +89,39 @@
                         "atRule": {
                           "type": "string",
                           "description": "Opt into declarations nested in a matching at-rule prelude, for example \"prefers-color-scheme: dark\". Conditional at-rules (@media, @supports, @container, @scope) are ignored without this. Grouping at-rules like @layer are always transparent, so you only name one to narrow a scope to it."
+                        },
+                        "$comment": {
+                          "oneOf": [
+                            {
+                              "type": "string"
+                            },
+                            {
+                              "type": "array",
+                              "items": {
+                                "type": "string"
+                              }
+                            }
+                          ],
+                          "description": "Ignored. Somewhere to write down why this config, or this pair, is the way it is."
                         }
                       }
                     }
                   ]
                 }
+              },
+              "$comment": {
+                "oneOf": [
+                  {
+                    "type": "string"
+                  },
+                  {
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    }
+                  }
+                ],
+                "description": "Ignored. Somewhere to write down why this config, or this pair, is the way it is."
               }
             }
           }
@@ -137,9 +165,37 @@
                 "items": {
                   "type": "string"
                 }
+              },
+              "$comment": {
+                "oneOf": [
+                  {
+                    "type": "string"
+                  },
+                  {
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    }
+                  }
+                ],
+                "description": "Ignored. Somewhere to write down why this config, or this pair, is the way it is."
               }
             }
           }
+        },
+        "$comment": {
+          "oneOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            }
+          ],
+          "description": "Ignored. Somewhere to write down why this config, or this pair, is the way it is."
         }
       }
     },
@@ -187,6 +243,20 @@
           "items": {
             "type": "string"
           }
+        },
+        "$comment": {
+          "oneOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            }
+          ],
+          "description": "Ignored. Somewhere to write down why this config, or this pair, is the way it is."
         }
       }
     },
@@ -227,6 +297,20 @@
           ],
           "default": "never",
           "description": "Whether a \"fail\" verdict affects the exit code. Defaults to never: a model's verdict is not reproducible, so it does not gate a build unless you decide it should. Independent of this, a judge that could not run always exits 1."
+        },
+        "$comment": {
+          "oneOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            }
+          ],
+          "description": "Ignored. Somewhere to write down why this config, or this pair, is the way it is."
         }
       }
     },
@@ -282,6 +366,20 @@
               "waitFor": {
                 "type": "string",
                 "description": "A selector to wait for before measuring."
+              },
+              "$comment": {
+                "oneOf": [
+                  {
+                    "type": "string"
+                  },
+                  {
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    }
+                  }
+                ],
+                "description": "Ignored. Somewhere to write down why this config, or this pair, is the way it is."
               }
             }
           }
@@ -318,11 +416,53 @@
               "againstParent": {
                 "type": "boolean",
                 "description": "Measure against what is behind the element rather than its own background. Use when the thing being measured is a fill: measuring a fill against itself scores 1.00 and means nothing."
+              },
+              "$comment": {
+                "oneOf": [
+                  {
+                    "type": "string"
+                  },
+                  {
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    }
+                  }
+                ],
+                "description": "Ignored. Somewhere to write down why this config, or this pair, is the way it is."
               }
             }
           }
+        },
+        "$comment": {
+          "oneOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            }
+          ],
+          "description": "Ignored. Somewhere to write down why this config, or this pair, is the way it is."
         }
       }
+    },
+    "$comment": {
+      "oneOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      ],
+      "description": "Ignored. Somewhere to write down why this config, or this pair, is the way it is."
     }
   }
 }

package/src/config.mjs

@@ -27,8 +27,28 @@ function stringArray(value, where, errors, { required = true } = {}) {
   return value;
 }
 
+/**
+ * Allowed anywhere an object is, and ignored.
+ *
+ * The validator rejects keys it does not know, which is right: a misspelled
+ * key that silently does nothing is a config that looks like it is working.
+ * The cost is that a config had nowhere to say why it exists. Per-pair labels
+ * carry the reasoning for a pair, and nothing carried the reasoning for the
+ * file. A format people are expected to live with for years should let them
+ * write that down.
+ */
+const COMMENT = '$comment';
+
 function rejectUnknown(object, allowed, where, errors) {
   for (const key of Object.keys(object)) {
+    if (key === COMMENT) {
+      const value = object[key];
+      const ok =
+        typeof value === 'string' ||
+        (Array.isArray(value) && value.every((v) => typeof v === 'string'));
+      if (!ok) errors.push(`${where}.${COMMENT} must be a string, or an array of them`);
+      continue;
+    }
     if (!allowed.includes(key)) {
       errors.push(`${where} has an unknown key "${key}". Allowed: ${allowed.join(', ')}.`);
     }