@surea11y/core 1.0.0

package/src/policy/schemas/engine-options.schema.json

@@ -0,0 +1,103 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://a11ycore.dev/schemas/engine-options.schema.json",
+  "title": "EngineOptions",
+  "description": "Top-level configuration object for the engine runtime (v1).",
+  "type": "object",
+  "additionalProperties": true,
+  "properties": {
+    "locale": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Requested locale for i18n resolution (fallback to 'en' if missing)."
+    },
+    "includeShadowDom": {
+      "type": "boolean",
+      "description": "When true, queries traverse open shadow roots via helpers.queryAllSmart."
+    },
+    "excludeSelectors": {
+      "description": "CSS selector(s) that define subtrees to exclude from scanning.",
+      "oneOf": [
+        { "type": "string", "minLength": 1 },
+        { "type": "array", "items": { "type": "string", "minLength": 1 } }
+      ]
+    },
+
+    "contrast": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Options that control contrast-related computations and assumptions.",
+      "properties": {
+        "mode": {
+          "type": "string",
+          "enum": ["strictConformance", "auditorAssist"],
+          "default": "strictConformance",
+          "description": "Controls whether the engine may apply explicit assumptions to reduce cantTell for contrast checks."
+        },
+        "rootCanvasFallback": {
+          "type": "string",
+          "minLength": 1,
+          "default": "#ffffff",
+          "description": "Used only when the effective root/canvas background is not computable and contrast.mode allows assumptions."
+        }
+      }
+    },
+
+    "rules": {
+      "type": "object",
+      "description": "Per-rule configuration. Keys are canonical ruleIds (e.g. 'img-alt-attr-present').",
+      "additionalProperties": {
+        "type": "object",
+        "additionalProperties": true
+      }
+    },
+    "policyContract": {
+      "oneOf": [
+        { "type": "string", "minLength": 1 },
+        { "$ref": "policy-contract.schema.json" }
+      ],
+      "description": "Policy contract identifier or inline policy contract object."
+    },
+    "policy": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "allowedOutcomes": {
+          "type": ["array", "null"],
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "enum": ["fail", "pass", "cantTell", "notApplicable"]
+          }
+        },
+        "allowedConfidence": {
+          "type": ["array", "null"],
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "enum": ["high", "medium", "low"]
+          }
+        },
+        "coerceManualFailToCantTell": {
+          "type": ["boolean", "null"]
+        }
+      },
+      "description": "Optional policy overrides applied on top of the resolved policy contract."
+    },
+    "output": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "includeSelector": {
+          "type": ["boolean", "null"],
+          "description": "When false, the engine will not populate occurrence.selector (kept as empty string)."
+        },
+        "includeHtml": {
+          "type": ["boolean", "null"],
+          "description": "When false, the engine will not populate occurrence.html (kept as empty string)."
+        }
+      },
+      "description": "Output shaping options for reporting/performance."
+    }
+  }
+}

package/src/policy/schemas/policy-contract.schema.json

@@ -0,0 +1,40 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://a11ycore.dev/schemas/policy-contract.schema.json",
+  "title": "PolicyContract",
+  "description": "Defines the enforcement policy for rule outcomes and confidence handling (v1).",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "id": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Identifier for the policy contract."
+    },
+    "allowedOutcomes": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": {
+        "type": "string",
+        "enum": ["fail", "pass", "cantTell", "notApplicable"]
+      },
+      "description": "Allowed normalized outcomes for rules."
+    },
+    "allowedConfidence": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": {
+        "type": "string",
+        "enum": ["high", "medium", "low"]
+      },
+      "description": "Allowed confidence levels for rule results."
+    },
+    "coerceManualFailToCantTell": {
+      "type": "boolean",
+      "description": "Whether manual rules are prevented from producing a fail outcome (coerced to cantTell)."
+    }
+  },
+  "required": ["id", "allowedOutcomes", "allowedConfidence", "coerceManualFailToCantTell"]
+}