design-constraint-validator 2.1.0 → 2.2.1

package/cli/constraint-registry.ts

@@ -12,8 +12,8 @@
  */
 
 import { existsSync, readFileSync } from 'node:fs';
-import { join } from 'node:path';
-import type { Engine } from '../core/engine.js';
+import { isAbsolute, join } from 'node:path';
+import type { Engine, ConstraintIssue, ConstraintPlugin } from '../core/engine.js';
 import type { Breakpoint } from '../core/breakpoints.js';
 import type { DcvConfig } from './types.js';
 import { MonotonicPlugin, parseSize as parseSizePx } from '../core/constraints/monotonic.js';
@@ -21,7 +21,17 @@ import { MonotonicLightness } from '../core/constraints/monotonic-lightness.js';
 import { WcagContrastPlugin } from '../core/constraints/wcag.js';
 import { ThresholdPlugin } from '../core/constraints/threshold.js';
 import { CrossAxisPlugin } from '../core/constraints/cross-axis.js';
-import { loadCrossAxisRules } from './cross-axis-loader.js';
+import { loadCrossAxisRulesDetailed, referencedIdsForFile } from './cross-axis-loader.js';
+
+/**
+ * A plugin that emits a fixed set of pre-computed issues unconditionally (it
+ * ignores the candidate set). Used to surface cross-axis loader notices —
+ * present-but-unusable files and skipped invalid rules (TASK-037) — through the
+ * normal issue channel so they appear as warnings instead of vanishing.
+ */
+function noticePlugin(notices: ConstraintIssue[]): ConstraintPlugin {
+  return { id: 'cross-axis-notices', evaluate: () => notices };
+}
 
 // ============================================================================
 // Types
@@ -98,6 +108,7 @@ export function discoverConstraints(opts: DiscoveryOptions): ConstraintSource[]
   const { config, basePath = '.', bp, constraintsDir = 'themes' } = opts;
   const sources: ConstraintSource[] = [];
   const constraintsCfg = config.constraints ?? {};
+  const constraintsRoot = isAbsolute(constraintsDir) ? constraintsDir : join(basePath, constraintsDir);
 
   // 1. Built-in WCAG defaults
   const enableBuiltInWcag =
@@ -134,17 +145,29 @@ export function discoverConstraints(opts: DiscoveryOptions): ConstraintSource[]
       op: r.op,
       valuePx: r.valuePx,
       where: r.where,
+      // Preserve configured severity (TASK-037): the core plugin honors `level`,
+      // but dropping it here silently promoted a `warn` threshold to an error.
+      level: r.level,
     }));
     sources.push({ type: 'custom-threshold', rules });
   }
 
+  // A breakpoint uses its own `<axis>.<bp>.order.json` when present, but MUST fall
+  // back to the global `<axis>.order.json` otherwise — without this, any axis
+  // lacking a per-bp file (e.g. spacing) contributed ZERO constraints under
+  // --breakpoint/--all-breakpoints, a silent false-pass (TASK-034).
+  const orderPathFor = (base: string): string | undefined => {
+    const bpPath = bp ? join(constraintsRoot, `${base}.${bp}.order.json`) : undefined;
+    if (bpPath && existsSync(bpPath)) return bpPath;
+    const globalPath = join(constraintsRoot, `${base}.order.json`);
+    return existsSync(globalPath) ? globalPath : undefined;
+  };
+
   // 5. Order files (monotonic constraints)
   const axes = ['typography', 'spacing', 'layout'] as const;
   for (const axis of axes) {
-    const suffix = bp ? `.${bp}` : '';
-    const orderPath = join(basePath, constraintsDir, `${axis}${suffix}.order.json`);
-
-    if (existsSync(orderPath)) {
+    const orderPath = orderPathFor(axis);
+    if (orderPath) {
       try {
         const data = JSON.parse(readFileSync(orderPath, 'utf8'));
         const orders: OrderRule[] = data.order || [];
@@ -157,11 +180,9 @@ export function discoverConstraints(opts: DiscoveryOptions): ConstraintSource[]
     }
   }
 
-  // 6. Color lightness order files
-  const suffix = bp ? `.${bp}` : '';
-  const colorOrderPath = join(basePath, constraintsDir, `color${suffix}.order.json`);
-
-  if (existsSync(colorOrderPath)) {
+  // 6. Color lightness order files (same bp → global fallback)
+  const colorOrderPath = orderPathFor('color');
+  if (colorOrderPath) {
     try {
       const data = JSON.parse(readFileSync(colorOrderPath, 'utf8'));
       const orders: OrderRule[] = data.order || [];
@@ -174,14 +195,14 @@ export function discoverConstraints(opts: DiscoveryOptions): ConstraintSource[]
   }
 
   // 7. Cross-axis rules (global)
-  const crossAxisPath = join(basePath, constraintsDir, 'cross-axis.rules.json');
+  const crossAxisPath = join(constraintsRoot, 'cross-axis.rules.json');
   if (existsSync(crossAxisPath)) {
     sources.push({ type: 'cross-axis-file', path: crossAxisPath });
   }
 
   // 8. Cross-axis rules (breakpoint-specific)
   if (bp) {
-    const crossAxisBpPath = join(basePath, constraintsDir, `cross-axis.${bp}.rules.json`);
+    const crossAxisBpPath = join(constraintsRoot, `cross-axis.${bp}.rules.json`);
     if (existsSync(crossAxisBpPath)) {
       sources.push({ type: 'cross-axis-file', path: crossAxisBpPath, bp });
     }
@@ -246,13 +267,16 @@ export function attachConstraints(engine: Engine, sources: ConstraintSource[], o
         }
 
         case 'cross-axis-file': {
-          // Phase 3B: Load rules from filesystem in CLI layer, pass to core plugin
-          const rules = loadCrossAxisRules(source.path, {
+          // Phase 3B: Load rules from filesystem in CLI layer, pass to core plugin.
+          // Detailed load also surfaces notices (unusable file / skipped invalid
+          // rules) as warnings so they are never silently dropped (TASK-037).
+          const { rules, notices } = loadCrossAxisRulesDetailed(source.path, {
             bp: source.bp,
             knownIds,
             debug: crossAxisDebug,
           });
           engine.use(CrossAxisPlugin(rules, source.bp));
+          if (notices.length) engine.use(noticePlugin(notices));
           break;
         }
       }
@@ -330,9 +354,20 @@ export function collectReferencedIds(sources: ConstraintSource[]): { ids: Set<st
       case 'lightness-file':
         addOrders(source.orders);
         break;
-      case 'cross-axis-file':
-        coverageKnown = false;
+      case 'cross-axis-file': {
+        // TASK-031/037: enumerate referenced ids so coverage stays KNOWN, but
+        // MIRROR attach exactly — same `source.bp` filter and same shape
+        // validation. A rule that did not run (wrong breakpoint, or invalid)
+        // must not make coverage look "matched" and suppress the no-match note.
+        // An unusable file stays conservative (coverageKnown=false).
+        const { ids: caIds, coverageKnown: known } = referencedIdsForFile(source.path, source.bp);
+        if (!known) {
+          coverageKnown = false;
+          break;
+        }
+        for (const id of caIds) ids.add(id);
         break;
+      }
     }
   }
 

package/cli/cross-axis-loader.d.ts

@@ -8,6 +8,7 @@
  * while CLI modules use this loader to read from filesystem.
  */
 import type { CrossAxisRule } from '../core/constraints/cross-axis.js';
+import type { ConstraintIssue } from '../core/engine.js';
 /**
  * Raw rule format as stored in JSON files.
  */
@@ -64,7 +65,45 @@ export type LoadCrossAxisOptions = {
  * @param path Path to cross-axis rules JSON file
  * @returns Parsed rules or undefined if file missing/invalid
  */
+/**
+ * Outcome of reading a cross-axis rules file, distinguishing the three cases a
+ * validator must not collapse (TASK-037): a *missing* file (no rules, fine) vs.
+ * a *present-but-unusable* file (bad JSON / wrong shape — must be surfaced, never
+ * silently treated as "no rules → green") vs. a successfully read rule array.
+ */
+export type RawCrossAxisFileResult = {
+    status: 'missing';
+} | {
+    status: 'invalid';
+    reason: string;
+} | {
+    status: 'ok';
+    rules: RawCrossAxisRule[];
+};
+export declare function readCrossAxisRulesFile(path: string): RawCrossAxisFileResult;
+/**
+ * Back-compat shim: returns the rule array, or `undefined` for both missing and
+ * present-but-unusable files. Prefer {@link readCrossAxisRulesFile} when the
+ * caller needs to surface the unusable case.
+ */
 export declare function loadCrossAxisRulesFromFile(path: string): RawCrossAxisRule[] | undefined;
+export type RuleValidation = {
+    ok: true;
+    rule: RawCrossAxisRule;
+} | {
+    ok: false;
+    id?: string;
+    reason: string;
+};
+export declare function validateRawRule(raw: unknown): RuleValidation;
+/**
+ * Whether a rule is active for a given breakpoint scope. Shared by rule
+ * compilation and coverage enumeration so the two never drift (TASK-037): a
+ * rule that did not run must not be able to make coverage look "matched".
+ */
+export declare function ruleMatchesBp(r: {
+    bp?: string;
+}, bp?: string): boolean;
 /**
  * Parse raw cross-axis rules into executable constraint rules.
  *
@@ -88,4 +127,27 @@ export declare function parseCrossAxisRules(rawRules: RawCrossAxisRule[], opts?:
  * @returns Parsed rules (empty array if file doesn't exist)
  */
 export declare function loadCrossAxisRules(path: string, opts?: LoadCrossAxisOptions): CrossAxisRule[];
+/**
+ * Load + parse cross-axis rules AND return notices to surface (TASK-037).
+ *
+ * Unlike {@link loadCrossAxisRules}, a present-but-unusable file or a skipped
+ * (invalid) rule produces a `warn`-level {@link ConstraintIssue} so it appears
+ * in the validation result instead of vanishing into a silent "no rules → green".
+ */
+export declare function loadCrossAxisRulesDetailed(path: string, opts?: LoadCrossAxisOptions): {
+    rules: CrossAxisRule[];
+    notices: ConstraintIssue[];
+};
+/**
+ * Token ids a cross-axis file contributes to constraint coverage for a given
+ * breakpoint scope (TASK-037). Mirrors compilation exactly: the SAME bp filter
+ * and the SAME shape validation, so a rule that did not run cannot make coverage
+ * look "matched" (which would suppress the "nothing was checked" note).
+ *
+ * `coverageKnown` is false only when the file is present-but-unusable.
+ */
+export declare function referencedIdsForFile(path: string, bp?: string): {
+    ids: string[];
+    coverageKnown: boolean;
+};
 //# sourceMappingURL=cross-axis-loader.d.ts.map

package/cli/cross-axis-loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cross-axis-loader.d.ts","sourceRoot":"","sources":["cross-axis-loader.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mCAAmC,CAAC;AAEvE;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE;QACL,EAAE,EAAE,MAAM,CAAC;QACX,EAAE,EAAE,IAAI,GAAG,IAAI,GAAG,GAAG,GAAG,GAAG,GAAG,IAAI,GAAG,IAAI,CAAC;QAC1C,KAAK,EAAE,MAAM,CAAC;KACf,CAAC;IACF,OAAO,CAAC,EAAE;QACR,EAAE,EAAE,MAAM,CAAC;QACX,EAAE,EAAE,IAAI,GAAG,IAAI,GAAG,GAAG,GAAG,GAAG,GAAG,IAAI,GAAG,IAAI,CAAC;QAC1C,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;KAC5B,CAAC;IACF,OAAO,CAAC,EAAE;QACR,CAAC,EAAE,MAAM,CAAC;QACV,EAAE,EAAE,IAAI,GAAG,IAAI,GAAG,GAAG,GAAG,GAAG,GAAG,IAAI,GAAG,IAAI,CAAC;QAC1C,CAAC,EAAE,MAAM,CAAC;QACV,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;KACzB,CAAC;CACH,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAChC,KAAK,EAAE,aAAa,EAAE,CAAC;IACvB,UAAU,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACxB,OAAO,EAAE,KAAK,CAAC;QAAE,EAAE,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACjD,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAAG;IACjC,qCAAqC;IACrC,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,4CAA4C;IAC5C,QAAQ,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACvB,2BAA2B;IAC3B,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,CAAC;AAMF;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,MAAM,GAAG,gBAAgB,EAAE,GAAG,SAAS,CAYvF;AAwDD;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,gBAAgB,EAAE,EAAE,IAAI,GAAE,oBAAyB,GAAG,mBAAmB,CA6GtH;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,oBAAyB,GAAG,aAAa,EAAE,CAejG"}
+{"version":3,"file":"cross-axis-loader.d.ts","sourceRoot":"","sources":["cross-axis-loader.ts"],"names":[],"mappings":"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"}

package/cli/cross-axis-loader.js

@@ -8,35 +8,117 @@
  * while CLI modules use this loader to read from filesystem.
  */
 import { existsSync, readFileSync } from 'node:fs';
-// ============================================================================
-// Filesystem Loading
-// ============================================================================
+import { z } from 'zod';
+export function readCrossAxisRulesFile(path) {
+    if (!existsSync(path))
+        return { status: 'missing' };
+    let data;
+    try {
+        data = JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch (e) {
+        return { status: 'invalid', reason: `invalid JSON (${e?.message ?? e})` };
+    }
+    const rules = data?.rules;
+    if (!Array.isArray(rules)) {
+        return { status: 'invalid', reason: 'expected a top-level "rules" array' };
+    }
+    return { status: 'ok', rules: rules };
+}
 /**
- * Load raw cross-axis rules from a JSON file.
- *
- * Returns undefined if file doesn't exist or can't be parsed.
- *
- * @param path Path to cross-axis rules JSON file
- * @returns Parsed rules or undefined if file missing/invalid
+ * Back-compat shim: returns the rule array, or `undefined` for both missing and
+ * present-but-unusable files. Prefer {@link readCrossAxisRulesFile} when the
+ * caller needs to surface the unusable case.
  */
 export function loadCrossAxisRulesFromFile(path) {
-    if (!existsSync(path)) {
-        return undefined;
+    const res = readCrossAxisRulesFile(path);
+    return res.status === 'ok' ? res.rules : undefined;
+}
+// ---------------------------------------------------------------------------
+// Rule shape validation (TASK-037)
+//
+// A cross-axis rule that fails to compile must be SKIPPED WITH A REASON, never
+// compiled into an always-true predicate or a NaN comparison. Examples the old
+// code admitted silently: a `when` missing `op`/`value` (always-true), a
+// `require` with no RHS (compared against 0), a non-numeric `fallback` (NaN).
+// ---------------------------------------------------------------------------
+const opEnum = z.enum(['<=', '>=', '<', '>', '==', '!=']);
+const sizeConst = z.union([z.number(), z.string()]);
+const RawCrossAxisRuleSchema = z
+    .object({
+    id: z.string(),
+    level: z.enum(['error', 'warn']).optional(),
+    where: z.string().optional(),
+    bp: z.string().optional(),
+    when: z.object({ id: z.string(), op: opEnum, value: z.number().finite() }).strict().optional(),
+    require: z
+        .object({ id: z.string(), op: opEnum, ref: z.string().optional(), fallback: sizeConst.optional() })
+        .strict()
+        .optional(),
+    compare: z.object({ a: z.string(), op: opEnum, b: z.string(), delta: sizeConst.optional() }).strict().optional(),
+})
+    .strict();
+export function validateRawRule(raw) {
+    const parsed = RawCrossAxisRuleSchema.safeParse(raw);
+    if (!parsed.success) {
+        const id = raw && typeof raw === 'object' && 'id' in raw && typeof raw.id === 'string'
+            ? raw.id
+            : undefined;
+        const reason = parsed.error.issues.map((e) => `${e.path.join('.') || '<root>'}: ${e.message}`).join('; ');
+        return { ok: false, id, reason };
     }
-    try {
-        const data = JSON.parse(readFileSync(path, 'utf8'));
-        return data.rules || [];
+    const rule = parsed.data;
+    const hasWhenReq = !!(rule.when && rule.require);
+    const hasCompare = !!rule.compare;
+    if (!hasWhenReq && !hasCompare) {
+        return { ok: false, id: rule.id, reason: 'must define when+require or compare' };
     }
-    catch {
-        // Return undefined on parse errors (consistent with silent failure behavior)
-        return undefined;
+    if (hasWhenReq && hasCompare) {
+        return { ok: false, id: rule.id, reason: 'must define exactly one of when+require or compare' };
     }
+    // Size constants must parse, or the compiled predicate degrades to NaN/0.
+    if (rule.require?.fallback !== undefined && px(rule.require.fallback) === null) {
+        return { ok: false, id: rule.id, reason: `require.fallback is not a parseable size: ${JSON.stringify(rule.require.fallback)}` };
+    }
+    if (rule.compare?.delta !== undefined && px(rule.compare.delta) === null) {
+        return { ok: false, id: rule.id, reason: `compare.delta is not a parseable size: ${JSON.stringify(rule.compare.delta)}` };
+    }
+    return { ok: true, rule };
+}
+/**
+ * Whether a rule is active for a given breakpoint scope. Shared by rule
+ * compilation and coverage enumeration so the two never drift (TASK-037): a
+ * rule that did not run must not be able to make coverage look "matched".
+ */
+export function ruleMatchesBp(r, bp) {
+    if (r?.bp && bp && r.bp !== bp)
+        return false; // targets a different bp
+    if (r?.bp && !bp)
+        return false; // bp-specific rule in a global run
+    return true;
 }
 // ============================================================================
 // Rule Parsing and Validation
 // ============================================================================
-// Helper functions (copied from core/cross-axis-config.ts)
-const px = (v) => typeof v === 'number' ? v : parseFloat(String(v)) * (String(v).trim().endsWith('rem') ? 16 : 1);
+// Parse a cross-axis size CONSTANT (rule `fallback`/`delta`), not a token value.
+// Mirrors the hardened finite-size policy (TASK-037): real numbers only, `rem`/
+// `em` 16px-relative, non-finite rejected — but allows a leading `-` because a
+// `compare.delta` is a signed offset (e.g. "-560px"). Returns null on garbage so
+// callers reject the rule instead of silently degrading to NaN/0.
+const px = (v) => {
+    if (typeof v === 'number')
+        return Number.isFinite(v) ? v : null;
+    if (typeof v !== 'string')
+        return null;
+    const m = v.trim().match(/^(-?\d*\.?\d+)\s*(px|rem|em)?$/i);
+    if (!m)
+        return null;
+    const n = parseFloat(m[1]);
+    if (!Number.isFinite(n))
+        return null;
+    const unit = (m[2] || 'px').toLowerCase();
+    return unit === 'rem' || unit === 'em' ? n * 16 : n;
+};
 const cmp = (a, b, op) => op === '>=' ? a >= b : op === '>' ? a > b : op === '<=' ? a <= b : op === '<' ? a < b : op === '==' ? a === b : a !== b;
 const prettyFail = (op) => ({ '>=': '<', '>': '≤', '<=': '>', '<': '≥', '==': '≠', '!=': '=' }[op] || '≠');
 const fmt = (v) => (Number.isFinite(Number(v)) ? `${Number(v)}px` : String(v));
@@ -46,7 +128,11 @@ function valueOrRef(ctx, ref, fallback) {
         if (v != null)
             return v;
     }
-    return typeof fallback === 'number' ? fallback : px(fallback ?? 0);
+    if (typeof fallback === 'number')
+        return fallback;
+    // `?? 0` is defensive only: validateRawRule rejects rules whose fallback does
+    // not parse, so a compiled rule never reaches here with garbage.
+    return px(fallback ?? 0) ?? 0;
 }
 function makeOp(op, rhs) {
     return (v) => cmp(v, rhs, op);
@@ -104,15 +190,18 @@ export function parseCrossAxisRules(rawRules, opts = {}) {
         }
         return true;
     };
-    for (const r of rawRules) {
-        // Filter by breakpoint
-        if (r.bp && bp && r.bp !== bp) {
+    for (const raw of rawRules) {
+        // Filter by breakpoint (shared with coverage enumeration so they never drift).
+        if (!ruleMatchesBp(raw, bp))
             continue;
-        }
-        if (r.bp && !bp) {
-            // Rule targets specific breakpoint; skip in global run
+        // Validate shape BEFORE compiling: an invalid rule is skipped with a reason,
+        // never compiled into an always-true or NaN predicate (TASK-037).
+        const valid = validateRawRule(raw);
+        if (!valid.ok) {
+            skipped.push({ id: valid.id, reason: valid.reason });
             continue;
         }
+        const r = valid.rule;
         try {
             if (r.when && r.require) {
                 // Validate IDs
@@ -151,7 +240,7 @@ export function parseCrossAxisRules(rawRules, opts = {}) {
                         test: (_, ctx) => {
                             const a = ctx.getPx(r.compare.a) ?? NaN;
                             const b = ctx.getPx(r.compare.b) ?? NaN;
-                            const delta = px(r.compare.delta ?? 0);
+                            const delta = px(r.compare.delta ?? 0) ?? 0;
                             if (Number.isNaN(a) || Number.isNaN(b))
                                 return true; // skip check if missing
                             return cmp(a, b + delta, r.compare.op);
@@ -159,15 +248,12 @@ export function parseCrossAxisRules(rawRules, opts = {}) {
                         msg: (_, ctx) => {
                             const a = ctx.getPx(r.compare.a);
                             const b = ctx.getPx(r.compare.b);
-                            const delta = px(r.compare.delta ?? 0);
+                            const delta = px(r.compare.delta ?? 0) ?? 0;
                             return `${r.compare.a} ${prettyFail(r.compare.op)} ${fmt((b ?? 0) + delta)} (was ${fmt(a ?? NaN)})`;
                         },
                     },
                 });
             }
-            else {
-                skipped.push({ id: r.id, reason: 'neither when+require nor compare present' });
-            }
         }
         catch (e) {
             skipped.push({ id: r.id, reason: `exception: ${e?.message ?? e}` });
@@ -220,3 +306,72 @@ export function loadCrossAxisRules(path, opts = {}) {
     const result = parseCrossAxisRules(rawRules, opts);
     return result.rules;
 }
+/**
+ * Load + parse cross-axis rules AND return notices to surface (TASK-037).
+ *
+ * Unlike {@link loadCrossAxisRules}, a present-but-unusable file or a skipped
+ * (invalid) rule produces a `warn`-level {@link ConstraintIssue} so it appears
+ * in the validation result instead of vanishing into a silent "no rules → green".
+ */
+export function loadCrossAxisRulesDetailed(path, opts = {}) {
+    const file = readCrossAxisRulesFile(path);
+    if (file.status === 'missing')
+        return { rules: [], notices: [] };
+    if (file.status === 'invalid') {
+        return {
+            rules: [],
+            notices: [
+                {
+                    id: 'cross-axis',
+                    rule: 'cross-axis',
+                    level: 'warn',
+                    where: path,
+                    message: `Cross-axis rules file present but unusable: ${file.reason}`,
+                },
+            ],
+        };
+    }
+    const result = parseCrossAxisRules(file.rules, opts);
+    const notices = result.skipped.map((s) => ({
+        id: `cross-axis:${s.id ?? '(no id)'}`,
+        rule: 'cross-axis',
+        level: 'warn',
+        message: `Cross-axis rule ${s.id ? `"${s.id}" ` : ''}skipped: ${s.reason}`,
+    }));
+    return { rules: result.rules, notices };
+}
+/**
+ * Token ids a cross-axis file contributes to constraint coverage for a given
+ * breakpoint scope (TASK-037). Mirrors compilation exactly: the SAME bp filter
+ * and the SAME shape validation, so a rule that did not run cannot make coverage
+ * look "matched" (which would suppress the "nothing was checked" note).
+ *
+ * `coverageKnown` is false only when the file is present-but-unusable.
+ */
+export function referencedIdsForFile(path, bp) {
+    const file = readCrossAxisRulesFile(path);
+    if (file.status === 'missing')
+        return { ids: [], coverageKnown: true };
+    if (file.status === 'invalid')
+        return { ids: [], coverageKnown: false };
+    const ids = [];
+    for (const raw of file.rules) {
+        if (!ruleMatchesBp(raw, bp))
+            continue;
+        const v = validateRawRule(raw);
+        if (!v.ok)
+            continue; // invalid rule did not compile → contributes no coverage
+        const r = v.rule;
+        if (r.when?.id)
+            ids.push(r.when.id);
+        if (r.require?.id)
+            ids.push(r.require.id);
+        if (r.require?.ref)
+            ids.push(r.require.ref);
+        if (r.compare?.a)
+            ids.push(r.compare.a);
+        if (r.compare?.b)
+            ids.push(r.compare.b);
+    }
+    return { ids, coverageKnown: true };
+}