@event4u/agent-config 16.4.0 → 16.5.0

package/src/scripts/lint_consolidation_lineage.ts

@@ -313,18 +313,21 @@ export function analyseFolder(
     surface: Surface = 'inbox',
 ): Finding[] {
     const findings: Finding[] = [];
-    let names: string[];
+    let entries: string[];
     try {
-        names = fs.readdirSync(dir).filter((n) => ROADMAP_RE.test(n)).sort();
+        entries = fs.readdirSync(dir);
     } catch {
         return findings;
     }
+    const names = entries.filter((n) => ROADMAP_RE.test(n)).sort();
     const artifacts: Artifact[] = names.map((n) => ({
         stem: n.replace(/\.md$/i, ''),
         file: n,
         decl: parseDeclaration(fs.readFileSync(path.join(dir, n), 'utf-8'), surface),
     }));
-    const present = new Set(artifacts.map((a) => a.stem));
+    // A parent need not be named road-to-*: a dated deep-dive plan is a parent
+    // too, and only its absence makes it missing.
+    const present = new Set(entries.filter((n) => /\.md$/i.test(n)).map((n) => n.replace(/\.md$/i, '')));
 
     for (const a of artifacts) {
         if (a.decl.unparseable) {

package/src/scripts/lint_design_quality.ts

@@ -13,7 +13,8 @@
  *   DQ1 contrast       — Text/background contrast < WCAG AA (4.5:1 normal, 3:1 large)
  *   DQ2 font-size      — Body font-size < 14px (floor; 16px strongly preferred)
  *   DQ3 line-length    — Prose line-length > 75ch without column constraint
- *   DQ4 reduced-motion — @keyframes / animation present without prefers-reduced-motion alt
+ *   DQ4 reduced-motion — @keyframes / animation present without prefers-reduced-motion alt,
+ *                        and (for INLINE SVG in HTML) SMIL with no route or a CSS-only one
  *   DQ5 heading-skip   — Heading levels skipped (h1 → h3 without h2)
  *   DQ6 focus-indicator— Interactive element with no :focus-visible indicator
  *
@@ -45,6 +46,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { assertScanned, DeadScopeError } from "./_lib/scan_scope.js";
+import { firstSmilLine, smilVerdict } from "./_lib/svg_motion.js";
 
 interface Finding {
   rule: string;
@@ -94,25 +96,71 @@ function checkFontSize(lines: string[], filePath: string): Finding[] {
   return findings;
 }
 
-/** DQ4: @keyframes / animation without @media (prefers-reduced-motion) */
+/**
+ * DQ4: animation without a reduced-motion route.
+ *
+ * Two halves. The CSS half is the original rule. The SMIL half (step 1.3 of
+ * `road-to-svg-with-a-witness`) covers INLINE SVG inside an HTML document and
+ * closes a measured blind spot: an HTML file whose only animation is an
+ * infinite `<animate>` read "clean — 1 file(s) checked" here, because
+ * `@keyframes` and `animation:` are the only two things the CSS half looks
+ * for, and SMIL is neither (R10).
+ *
+ * It also reports the subtler case: SMIL whose ONLY reduced-motion route is a
+ * CSS declaration. Under an emulated `reduce`, a page-level
+ * `svg * { animation: none !important }` left an `<animate>` moving `cx` from
+ * 20.2 to 76.8 in 700 ms (R4) — CSS animation properties do not reach SMIL, so
+ * the file looks covered and is not.
+ *
+ * STANDALONE `.svg` IS DELIBERATELY NOT HERE. A file cannot see its host's
+ * `<picture>` route, so judging the route from inside it would red correct
+ * assets and break this linter's zero-false-positive promise (line 12). That
+ * case belongs to `lint_svg_asset`, which knows it is reading a whole asset.
+ * Both halves read the same `_lib/svg_motion.ts`, so the two cannot drift.
+ */
 function checkReducedMotion(content: string, filePath: string, lines: string[]): Finding[] {
-  const hasAnimation = /@keyframes\s+\w+|animation\s*:/i.test(content);
-  if (!hasAnimation) return [];
+  const findings: Finding[] = [];
 
+  const hasAnimation = /@keyframes\s+\w+|animation\s*:/i.test(content);
   const hasReducedMotion = /@media\s*\([^)]*prefers-reduced-motion/i.test(content);
-  if (hasReducedMotion) return [];
-
-  // Find first animation declaration for the line number
-  const animLine = lines.findIndex((l) => /@keyframes\s+\w+|animation\s*:/.test(l));
-  return [
-    {
+  if (hasAnimation && !hasReducedMotion) {
+    const animLine = lines.findIndex((l) => /@keyframes\s+\w+|animation\s*:/.test(l));
+    findings.push({
       rule: "dq4-reduced-motion",
       file: filePath,
       line: animLine + 1,
       snippet: "@keyframes or animation present without @media (prefers-reduced-motion) alternative",
       severity: "error",
-    },
-  ];
+    });
+  }
+
+  // The SMIL half runs for documents that can HOST an inline graphic. A `.css`
+  // file cannot carry one, and a standalone `.svg` is the other linter's.
+  if (!/\.(html|htm|vue|svelte|astro)$/i.test(filePath)) return findings;
+
+  const verdict = smilVerdict(content);
+  if (verdict === "no-route") {
+    findings.push({
+      rule: "dq4-reduced-motion",
+      file: filePath,
+      line: firstSmilLine(content),
+      snippet:
+        "inline SVG animates with SMIL (<animate>/<animateTransform>/<set>) and the document carries " +
+        "no @media (prefers-reduced-motion) route at all",
+      severity: "error",
+    });
+  } else if (verdict === "css-only") {
+    findings.push({
+      rule: "dq4-reduced-motion",
+      file: filePath,
+      line: firstSmilLine(content),
+      snippet:
+        "inline SVG animates with SMIL and the only reduced-motion route is a CSS animation/transition " +
+        "declaration — CSS does not reach SMIL, so the animation keeps running under `reduce`",
+      severity: "error",
+    });
+  }
+  return findings;
 }
 
 /** DQ5: heading levels skipped (h1 → h3 without h2) in HTML */

package/src/scripts/lint_motion_authority_drift.ts

@@ -325,6 +325,33 @@ interface Allowed {
 
 const norm = (s: string): string => s.replace(/\s+/g, ' ').trim();
 
+/**
+ * The reviewed statements, one verdict each.
+ *
+ * THE AUTHORITY IS NOT IN THIS TABLE, AND THAT IS THE DESIGN. The table is what
+ * the five DEPENDENTS are checked against; `design-patterns.md` § Motion is the
+ * thing they are compared TO, so it is PARSED — bands, ceiling, both curves —
+ * and never passed to {@link checkStatement}. A row keyed to it would be inert,
+ * and an inert row reads as enforcement.
+ *
+ * Measured 2026-10-11, when § Motion gained step 6b (the SVG mechanisms): of
+ * the 49 lines the authority gained, {@link carriesMotionValue} flags two when
+ * applied to them directly, and this gate reads neither, because neither
+ * reaches the scan path. Both verdicts are `permitted`, recorded here rather
+ * than left to be rediscovered by whoever next widens the scanned set:
+ *
+ *   · "Step 2's bounce prohibition already rules the intent out" — a deferral
+ *     to the prohibition, not a curve. The `keySplines` bullet states which
+ *     values the MECHANISM accepts; step 2 still owns whether to want one.
+ *   · "All of them still obey step 3's bands, step 2's single `ease-out` curve"
+ *     — the authority naming its own curve, in a sentence widened from the six
+ *     HTML mechanisms to those plus the SVG ones. No band, curve or duration
+ *     moved with it.
+ *
+ * If the authority is ever added to the scanned set, those two are the rows it
+ * needs on day one — and every band line in § Motion needs one too, which is
+ * the cost that keeps it parsed instead.
+ */
 export const PROSE_ALLOWLIST: readonly Allowed[] = [
     {
         file: CHECKLIST_REL, key: 'table:7',

package/src/scripts/lint_svg_asset.ts

@@ -0,0 +1,365 @@
+#!/usr/bin/env node
+/**
+ * lint_svg_asset — the command-line surface over the SVG rule set.
+ *
+ * The rules live in `_lib/svg_rules.ts`, because the design pass imports them
+ * into the hook bundle and must not drag a CLI in with them (see that file's
+ * header for the measurement). Everything this module adds is the part only a
+ * command needs: argument parsing, the directory walk, the project config, the
+ * scanned-nothing refusal, and the step 1.2 preservation readout.
+ *
+ * Inline-ignore (same shape as `lint_design_quality`, works in XML comments):
+ *   svg-asset-disable <rule-id> [-- reason]            (file scope)
+ *   svg-asset-disable-next-line <rule-id> [-- reason]
+ *   svg-asset-disable-line <rule-id> [-- reason]
+ *
+ * Per-project config (`.svg-asset.json` in the project root):
+ *   { "ignoreRules": ["svg-a11y-generic-id"], "ignoreFiles": ["vendor/**"] }
+ *
+ * Usage:
+ *   lint_svg_asset --dir <path> [--delivery inline|img|css-bg|document]
+ *   lint_svg_asset --file <a.svg> [--file <b.svg>] [--delivery …]
+ *   lint_svg_asset --file <after.svg> --baseline <before.svg> --allow id,id
+ *
+ * Exit codes: 0 = clean, 2 = findings, 1 = internal error (including the
+ * scanned-nothing refusal — a gate that scanned no file is not a clean gate).
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
+import {
+    DELIVERY_MODES,
+    parseElements,
+    scanHostHtml,
+    scanSvg,
+    type DeliveryMode,
+    type Finding,
+    type ProjectConfig,
+    type SvgElement,
+} from './_lib/svg_rules.js';
+
+export * from './_lib/svg_rules.js';
+
+// Step 1.2 — preservation readout for a surgical edit
+// ---------------------------------------------------------------------------
+
+export interface PreservationChange {
+    id: string;
+    element: string;
+    attribute: string;
+    before: string;
+    after: string;
+}
+
+/**
+ * Canonicalised attribute map — number formatting, attribute order and
+ * whitespace normalised away, so a re-serialisation that changed nothing reads
+ * as nothing changed.
+ */
+export function canonicalAttrs(attrs: Record<string, string>): Record<string, string> {
+    const out: Record<string, string> = {};
+    for (const key of Object.keys(attrs).sort()) {
+        const v = (attrs[key] ?? '')
+            .replace(/\s+/g, ' ')
+            .trim()
+            // Numbers only where a number is what it is. A hex color is a
+            // TOKEN, not a quantity: normalising inside `#00ff00` collapses it
+            // onto `#0ff0`, and the readout then reports no change for a color
+            // edit outside the allowed ids — a surgical-edit witness that
+            // cannot see a recolour.
+            .replace(/#[0-9a-fA-F]+|-?\d+\.?\d*(?:[eE][-+]?\d+)?/g, (tok) => {
+                if (tok.startsWith('#')) return tok.toLowerCase();
+                const num = Number(tok);
+                return Number.isFinite(num) ? String(Number(num.toFixed(4))) : tok;
+            });
+        out[key] = v;
+    }
+    return out;
+}
+
+/**
+ * Every element outside the allowed set that changed between two revisions.
+ *
+ * NO PIXEL DIFF decides this. Anti-aliasing and font metrics would make a
+ * pixel comparison a per-machine verdict, and the discipline this witnesses —
+ * `design-fidelity-mechanics.md` § surgical edits — is about which elements
+ * the edit was allowed to touch, which is an attribute fact.
+ */
+export function preservationReadout(
+    beforeContent: string,
+    afterContent: string,
+    allowedIds: readonly string[],
+): PreservationChange[] {
+    const allow = new Set(allowedIds.map((s) => s.trim()).filter(Boolean));
+
+    /**
+     * A stable key per element, and the id chain above it.
+     *
+     * An element WITHOUT an id is keyed by its nearest id-bearing ancestor plus
+     * its tag and its ordinal INSIDE that ancestor — never by a document-wide
+     * index. A document-wide index shifts for every element after an allowed
+     * deletion, so removing one child of the allowed group reported every
+     * un-idded element after it as changed. Measured on the `grouped-transforms`
+     * triple: the correct edit reported `rect#7 (element)` and the readout could
+     * not tell a clean surgical edit from a dirty one.
+     */
+    const index = (content: string): Map<string, { el: SvgElement; chain: string[] }> => {
+        const map = new Map<string, { el: SvgElement; chain: string[] }>();
+        const stack: Array<{ name: string; id: string | null }> = [];
+        const ordinals = new Map<string, number>();
+        for (const el of parseElements(content)) {
+            if (el.closing) {
+                if (stack[stack.length - 1]?.name === el.name) stack.pop();
+                continue;
+            }
+            const chain = stack.map((f) => f.id).filter((x): x is string => x !== null);
+            const ownerId = [...stack].reverse().find((f) => f.id !== null)?.id ?? '';
+            const own = el.attrs['id'] ?? null;
+            let key: string;
+            if (own) {
+                key = own;
+            } else {
+                const bucket = `${ownerId}/${el.name}`;
+                const n = (ordinals.get(bucket) ?? 0) + 1;
+                ordinals.set(bucket, n);
+                key = `${bucket}#${n}`;
+            }
+            map.set(key, { el, chain: own ? [...chain, own] : chain });
+            if (!el.selfClosing) stack.push({ name: el.name, id: own });
+        }
+        return map;
+    };
+
+    const before = index(beforeContent);
+    const after = index(afterContent);
+    const changes: PreservationChange[] = [];
+    /** An element inside an allowed subtree is itself allowed. */
+    const permitted = (entry: { chain: string[] } | undefined): boolean =>
+        Boolean(entry && entry.chain.some((id) => allow.has(id)));
+
+    for (const [key, beforeEntry] of before) {
+        if (permitted(beforeEntry)) continue;
+        const afterEntry = after.get(key);
+        if (!afterEntry) {
+            changes.push({
+                id: key,
+                element: beforeEntry.el.name,
+                attribute: '(element)',
+                before: 'present',
+                after: 'removed',
+            });
+            continue;
+        }
+        const a = canonicalAttrs(beforeEntry.el.attrs);
+        const b = canonicalAttrs(afterEntry.el.attrs);
+        for (const attr of new Set([...Object.keys(a), ...Object.keys(b)])) {
+            if ((a[attr] ?? '') === (b[attr] ?? '')) continue;
+            changes.push({
+                id: key,
+                element: beforeEntry.el.name,
+                attribute: attr,
+                before: a[attr] ?? '(absent)',
+                after: b[attr] ?? '(absent)',
+            });
+        }
+    }
+    for (const [key, afterEntry] of after) {
+        if (permitted(afterEntry) || before.has(key)) continue;
+        changes.push({
+            id: key,
+            element: afterEntry.el.name,
+            attribute: '(element)',
+            before: 'absent',
+            after: 'added',
+        });
+    }
+    return changes;
+}
+
+export function loadConfig(dir: string): ProjectConfig {
+    const configPath = path.join(dir, '.svg-asset.json');
+    if (!fs.existsSync(configPath)) return {};
+    try {
+        return JSON.parse(fs.readFileSync(configPath, 'utf-8')) as ProjectConfig;
+    } catch {
+        return {};
+    }
+}
+
+function* walkDir(dir: string, ext: RegExp): Generator<string> {
+    if (!fs.existsSync(dir)) return;
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        const full = path.join(dir, entry.name);
+        if (entry.name.startsWith('.') || entry.name === 'node_modules') continue;
+        if (entry.isDirectory()) yield* walkDir(full, ext);
+        else if (ext.test(entry.name)) yield full;
+    }
+}
+
+// ---------------------------------------------------------------------------
+// CLI
+// ---------------------------------------------------------------------------
+
+function readFlag(args: string[], name: string): string | undefined {
+    const i = args.indexOf(name);
+    return i >= 0 ? args[i + 1] : undefined;
+}
+
+function readAll(args: string[], name: string): string[] {
+    const out: string[] = [];
+    for (let i = 0; i < args.length; i++) if (args[i] === name && args[i + 1]) out.push(args[i + 1] as string);
+    return out;
+}
+
+export function main(argv: readonly string[] = process.argv.slice(2)): number {
+    const args = [...argv];
+    const jsonMode = args.includes('--json');
+    const quiet = args.includes('--quiet');
+    const deliveryRaw = readFlag(args, '--delivery');
+    if (deliveryRaw && !DELIVERY_MODES.includes(deliveryRaw as DeliveryMode)) {
+        process.stderr.write(
+            `[lint_svg_asset] unknown --delivery "${deliveryRaw}"; expected one of ${DELIVERY_MODES.join(', ')}\n`,
+        );
+        return 1;
+    }
+    const delivery = deliveryRaw as DeliveryMode | undefined;
+
+    // --- step 1.2: preservation readout -------------------------------------
+    const baseline = readFlag(args, '--baseline');
+    if (baseline) {
+        const files = readAll(args, '--file');
+        const after = files[0];
+        if (!after) {
+            process.stderr.write('[lint_svg_asset] --baseline needs a --file <after.svg> to compare against\n');
+            return 1;
+        }
+        if (!fs.existsSync(baseline) || !fs.existsSync(after)) {
+            process.stderr.write('[lint_svg_asset] --baseline or --file path not found\n');
+            return 1;
+        }
+        const allow = (readFlag(args, '--allow') ?? '').split(',').map((s) => s.trim()).filter(Boolean);
+        const changes = preservationReadout(
+            fs.readFileSync(baseline, 'utf-8'),
+            fs.readFileSync(after, 'utf-8'),
+            allow,
+        );
+        if (jsonMode) {
+            process.stdout.write(`${JSON.stringify(changes, null, 2)}\n`);
+            return changes.length ? 2 : 0;
+        }
+        if (!changes.length) {
+            if (!quiet) {
+                process.stdout.write(
+                    `✅  lint_svg_asset --baseline: nothing changed outside ${allow.length} allowed id(s).\n`,
+                );
+            }
+            return 0;
+        }
+        for (const c of changes) {
+            process.stdout.write(
+                `❌ ${after} [svg-preserve-changed-outside-allowed] <${c.element} id="${c.id}"> ` +
+                    `${c.attribute}: "${c.before}" → "${c.after}"\n`,
+            );
+        }
+        process.stdout.write(
+            `\nlint_svg_asset: ${changes.length} element change(s) outside the allowed set. ` +
+                'A surgical edit touches only what it declared.\n',
+        );
+        return 2;
+    }
+
+    // --- scanning -----------------------------------------------------------
+    const explicit = readAll(args, '--file');
+    const dirArg = readFlag(args, '--dir');
+    const targets: string[] = [];
+    let roots: string[] = [];
+
+    if (explicit.length) {
+        targets.push(...explicit.map((f) => path.resolve(f)));
+        roots = targets;
+    } else {
+        const scanDir = dirArg ? path.resolve(dirArg) : path.resolve(process.cwd(), 'src');
+        roots = [scanDir];
+        if (!fs.existsSync(scanDir)) {
+            // The two cases are NOT the same, and collapsing them into exit 0
+            // made a renamed or mistyped `--dir` report success in CI. An
+            // ABSENT DEFAULT root is the opt-in escape — a consumer with no
+            // `src/` has nothing to scan and must not red. An EXPLICIT `--dir`
+            // that does not resolve is a broken invocation, and this module's
+            // own header already says a gate that scanned no file is not a
+            // clean gate.
+            if (!quiet) process.stderr.write(`[lint_svg_asset] scan directory not found: ${scanDir}\n`);
+            if (dirArg) return 1;
+            process.stderr.write(
+                'This linter is opt-in. Run with --dir <path> or --file <a.svg> pointing at your assets.\n',
+            );
+            return 0;
+        }
+        for (const f of walkDir(scanDir, /\.(svg|html|htm)$/i)) targets.push(f);
+    }
+
+    const config = loadConfig(process.cwd());
+    const ignoreRules = new Set((config.ignoreRules ?? []).map((r) => r.toLowerCase()));
+    const ignoreGlobs = config.ignoreFiles ?? [];
+    const scanned = targets.filter((f) => !ignoreGlobs.some((g) => f.includes(g.replace('**', ''))));
+
+    try {
+        assertScanned({ gate: 'lint_svg_asset', scanned: scanned.length, units: 'SVG/HTML file(s)', roots });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 1;
+        }
+        throw exc;
+    }
+
+    const all: Finding[] = [];
+    for (const abs of scanned) {
+        const rel = path.relative(process.cwd(), abs);
+        try {
+            const content = fs.readFileSync(abs, 'utf-8');
+            const findings = /\.svg$/i.test(abs)
+                ? scanSvg(content, rel, { delivery })
+                : scanHostHtml(content, rel, { delivery });
+            all.push(...findings.filter((f) => !ignoreRules.has(f.rule.toLowerCase())));
+        } catch (err) {
+            if (!quiet) process.stderr.write(`[lint_svg_asset] error: ${abs}: ${err}\n`);
+        }
+    }
+
+    if (jsonMode) {
+        process.stdout.write(`${JSON.stringify(all, null, 2)}\n`);
+        return all.length > 0 ? 2 : 0;
+    }
+    if (!all.length) {
+        if (!quiet) {
+            process.stdout.write(
+                `✅  lint_svg_asset: clean — ${scanned.length} file(s) checked, no violations.\n`,
+            );
+        }
+        return 0;
+    }
+    const errors = all.filter((f) => f.severity === 'error');
+    const warnings = all.filter((f) => f.severity === 'warning');
+    const inert = all.filter((f) => f.severity === 'inert');
+    for (const f of all) {
+        const icon = f.severity === 'error' ? '❌' : f.severity === 'warning' ? '⚠️ ' : 'ℹ️ ';
+        process.stdout.write(`${icon} ${f.file}:${f.line} [${f.rule}] ${f.snippet}\n`);
+    }
+    process.stdout.write(
+        `\nlint_svg_asset: ${errors.length} error(s), ${warnings.length} warning(s), ${inert.length} inert. ` +
+            'Use svg-asset-disable-next-line <rule> -- reason or .svg-asset.json to suppress; ' +
+            'svg-safety-* findings yield only to .svg-asset.json, never to a marker in the file. ' +
+            'Advisory: an "inert" row is not a clean row — the same file inlined tomorrow is an error.\n',
+    );
+    return 2;
+}
+
+/* c8 ignore start — entrypoint guard, exercised by the CLI not by the tests */
+const invokedDirectly =
+    typeof process !== 'undefined' &&
+    Array.isArray(process.argv) &&
+    /lint_svg_asset\.(ts|js)$/.test(process.argv[1] ?? '');
+if (invokedDirectly) process.exit(main());
+/* c8 ignore stop */