@event4u/agent-config 7.3.0 → 7.5.0

package/src/scripts/lint_design_slop.ts

@@ -0,0 +1,245 @@
+#!/usr/bin/env node
+/**
+ * lint_design_slop — deterministic anti-slop DETECTOR for consumer projects.
+ *
+ * The aesthetic-PROVENANCE layer that `lint_design_quality` deliberately omits.
+ * It scans HTML/CSS/JSX/Markdown for the "AI tells" catalogued in
+ * `docs/guidelines/design-antipatterns.md` and emits structured findings
+ * (rule-id + catalog-id + severity P0–P3 + file:line). The rule registry lives
+ * in `design_slop_rules.ts`.
+ *
+ * FLAGS, NEVER A HARD BLOCK. Default exit is 0 regardless of findings — slop
+ * tells are rebuttable presumptions, not failures. CI opts into failing with
+ * `--fail-on <P0|P1|P2|P3>` (fails when any finding at or above that severity
+ * remains). This honours the council 2026-06-28 "flags not blocks" verdict.
+ *
+ * Zero runtime token cost: this runs in Node (CI / pre-commit / optional hook),
+ * never in the model's context. `design-review` cites the structured `--json`
+ * output instead of reloading the 12 KB prose catalog.
+ *
+ * Dependency-free pattern analysis (no postcss/@babel) — see the design note in
+ * design_slop_rules.ts. Same posture as lint_design_quality.
+ *
+ * Usage:
+ *   npx tsx lint_design_slop.ts --dir src/ [--json] [--fail-on P1] [--quiet]
+ *
+ * Context gate: a consumer DESIGN.md (project root or scan dir) that declares a
+ * pattern as intentional suppresses the matching rule (e.g. "warm-neutral" →
+ * C5 cream-palette is not flagged). Inline-ignore (eslint-style):
+ *   design-slop-disable <rule-id>            (file scope, top of file)
+ *   design-slop-disable-next-line <rule-id>
+ *   design-slop-disable-line <rule-id>
+ * Per-project config (.design-quality.json, shared with lint_design_quality):
+ *   { "ignoreRules": ["slop-c5-cream-palette"], "ignoreFiles": ["src/legacy/**"] }
+ *
+ * Exit codes: 0 = clean OR findings-below-threshold, 2 = findings at/above
+ * --fail-on threshold, 1 = internal error.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import {
+  SLOP_RULES,
+  type DesignContext,
+  type Engine,
+  type Severity,
+} from "./design_slop_rules.js";
+
+interface Finding {
+  rule: string;
+  catalogId: string;
+  severity: Severity;
+  file: string;
+  line: number;
+  snippet: string;
+  message: string;
+}
+
+interface ProjectConfig {
+  ignoreRules?: string[];
+  ignoreFiles?: string[];
+}
+
+const SEVERITY_ORDER: Severity[] = ["P3", "P2", "P1", "P0"];
+const sevRank = (s: Severity): number => SEVERITY_ORDER.indexOf(s);
+
+// ext → which engine-classes a file of that type can contain
+function enginesForExt(ext: string): Set<Engine> {
+  if (/\.(css|scss|sass|less)$/i.test(ext)) return new Set<Engine>(["css"]);
+  if (/\.(html|htm|vue|svelte|astro)$/i.test(ext)) return new Set<Engine>(["css", "html", "copy"]);
+  if (/\.(jsx|tsx)$/i.test(ext)) return new Set<Engine>(["css", "jsx", "copy"]);
+  if (/\.(md|mdx)$/i.test(ext)) return new Set<Engine>(["copy"]);
+  return new Set<Engine>();
+}
+
+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;
+  }
+}
+
+function loadConfig(dir: string): ProjectConfig {
+  const p = path.join(dir, ".design-quality.json");
+  if (!fs.existsSync(p)) return {};
+  try {
+    return JSON.parse(fs.readFileSync(p, "utf-8")) as ProjectConfig;
+  } catch {
+    return {};
+  }
+}
+
+/** Read DESIGN.md (scan dir, then project root) as the context-gate source. */
+export function loadDesignContext(scanDir: string): DesignContext {
+  const candidates = [
+    path.join(scanDir, "DESIGN.md"),
+    path.join(process.cwd(), "DESIGN.md"),
+    path.join(scanDir, "..", "DESIGN.md"),
+  ];
+  let raw = "";
+  for (const c of candidates) {
+    if (fs.existsSync(c)) {
+      raw = fs.readFileSync(c, "utf-8").toLowerCase();
+      break;
+    }
+  }
+  return {
+    raw,
+    has: (...keywords: string[]) => keywords.some((k) => raw.includes(k.toLowerCase())),
+  };
+}
+
+function parseIgnores(lines: string[]): Map<string, Set<number>> {
+  const ignores = new Map<string, Set<number>>();
+  const add = (rule: string, line: number) => {
+    const set = ignores.get(rule) ?? new Set<number>();
+    set.add(line);
+    ignores.set(rule, set);
+  };
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i] ?? "";
+    const file = /design-slop-disable\s+([\w-]+)/i.exec(line);
+    if (file && file[1] && !/-line|-next-line/.test(line)) {
+      ignores.set(file[1].toLowerCase(), new Set([...Array(99999).keys()].map((n) => n + 1)));
+    }
+    const next = /design-slop-disable-next-line\s+([\w-]+)/i.exec(line);
+    if (next && next[1]) add(next[1].toLowerCase(), i + 2);
+    const cur = /design-slop-disable-line\s+([\w-]+)/i.exec(line);
+    if (cur && cur[1]) add(cur[1].toLowerCase(), i + 1);
+  }
+  return ignores;
+}
+
+export function scanFile(
+  content: string,
+  relPath: string,
+  ctx: DesignContext,
+): Finding[] {
+  const lines = content.split("\n");
+  const ext = path.extname(relPath).toLowerCase();
+  const fileEngines = enginesForExt(ext);
+  if (fileEngines.size === 0) return [];
+  const ignores = parseIgnores(lines);
+
+  const out: Finding[] = [];
+  for (const rule of SLOP_RULES) {
+    if (!rule.engines.some((e) => fileEngines.has(e))) continue;
+    if (rule.gated && rule.gated(ctx)) continue; // DESIGN.md declares intent → suppress
+    let hits;
+    try {
+      hits = rule.detect({ content, lines, ext, ctx });
+    } catch {
+      continue; // a single rule throwing never kills the scan
+    }
+    for (const h of hits) {
+      const ruleIgnore = ignores.get(rule.id.toLowerCase());
+      if (ruleIgnore && ruleIgnore.has(h.line)) continue;
+      out.push({
+        rule: rule.id,
+        catalogId: rule.catalogId,
+        severity: rule.severity,
+        file: relPath,
+        line: h.line,
+        snippet: h.snippet,
+        message: rule.message,
+      });
+    }
+  }
+  return out;
+}
+
+function main(): void {
+  const args = process.argv.slice(2);
+  const jsonMode = args.includes("--json");
+  const quiet = args.includes("--quiet");
+  const dirIdx = args.indexOf("--dir");
+  const scanDir = dirIdx >= 0 && args[dirIdx + 1] ? path.resolve(args[dirIdx + 1]!) : path.resolve(process.cwd(), "src");
+  const failIdx = args.indexOf("--fail-on");
+  const failOn = (failIdx >= 0 ? args[failIdx + 1] : undefined) as Severity | undefined;
+
+  if (!fs.existsSync(scanDir)) {
+    if (!quiet) {
+      process.stderr.write(`[lint_design_slop] scan directory not found: ${scanDir}\n`);
+      process.stderr.write("Opt-in for consumer projects. Run with --dir <path> at your UI source.\n");
+    }
+    process.exit(0);
+  }
+
+  const ctx = loadDesignContext(scanDir);
+  const config = loadConfig(process.cwd());
+  const ignoreRules = new Set((config.ignoreRules ?? []).map((r) => r.toLowerCase()));
+  const ignoreGlobs = config.ignoreFiles ?? [];
+
+  const files: string[] = [];
+  for (const f of walkDir(scanDir, /\.(html|htm|css|scss|sass|less|vue|svelte|astro|jsx|tsx|md|mdx)$/i)) {
+    if (!ignoreGlobs.some((g) => f.includes(g.replace("**", "")))) files.push(f);
+  }
+
+  const findings: Finding[] = [];
+  for (const fp of files) {
+    const rel = path.relative(process.cwd(), fp);
+    try {
+      const fileFindings = scanFile(fs.readFileSync(fp, "utf-8"), rel, ctx).filter(
+        (f) => !ignoreRules.has(f.rule.toLowerCase()),
+      );
+      findings.push(...fileFindings);
+    } catch (err) {
+      if (!quiet) process.stderr.write(`[lint_design_slop] error: ${fp}: ${err}\n`);
+    }
+  }
+
+  findings.sort((a, b) => sevRank(b.severity) - sevRank(a.severity));
+
+  const overThreshold = failOn
+    ? findings.filter((f) => sevRank(f.severity) >= sevRank(failOn))
+    : [];
+
+  if (jsonMode) {
+    process.stdout.write(JSON.stringify({ findings, failOn: failOn ?? null, overThreshold: overThreshold.length }, null, 2) + "\n");
+    process.exit(overThreshold.length > 0 ? 2 : 0);
+  }
+
+  if (findings.length === 0) {
+    if (!quiet) process.stdout.write(`✅  lint_design_slop: no anti-slop tells in ${files.length} file(s).\n`);
+    process.exit(0);
+  }
+
+  for (const f of findings) {
+    const icon = f.severity === "P0" || f.severity === "P1" ? "⚠️ " : "•";
+    process.stdout.write(`${icon} [${f.severity} ${f.catalogId}] ${f.file}:${f.line} (${f.rule}) — ${f.message}\n     ${f.snippet}\n`);
+  }
+  process.stdout.write(
+    `\nlint_design_slop: ${findings.length} tell(s) flagged (rebuttable — declare intent in DESIGN.md, ` +
+      `design-slop-disable-next-line <rule>, or .design-quality.json).` +
+      (failOn ? ` ${overThreshold.length} at/above ${failOn}.` : " Flags only; no CI failure (pass --fail-on to gate).") +
+      "\n",
+  );
+  process.exit(overThreshold.length > 0 ? 2 : 0);
+}
+
+// Run only when invoked directly (not when imported by the test guard).
+const invokedDirectly =
+  process.argv[1] !== undefined && /lint_design_slop\.ts$/.test(process.argv[1]);
+if (invokedDirectly) main();

package/src/scripts/probe_host_compliance.ts

@@ -0,0 +1,145 @@
+#!/usr/bin/env tsx
+/**
+ * Host-compliance probe for thin projection (token-saving Phase 0).
+ *
+ * Thin projection is a CONTRACT WITH THE HOST: a non-kernel rule body is
+ * demoted to a router pointer, and the host is trusted to load the body only
+ * on trigger-match. On a host that reconstructs rule bodies internally (e.g. a
+ * plugin loader that re-inlines everything), thin projection is a silent no-op
+ * — so it must be falsified per host before the thin flip ships.
+ *
+ * This probe has two halves:
+ *
+ *   MECHANICAL (here, automated): run the real thin projector (`thin_entry`)
+ *   on a canary rule fixture and assert the body is replaced by a pointer that
+ *   still carries the trigger hint (so the router can select it). This proves
+ *   the projector demotes correctly — the prerequisite for any host test.
+ *
+ *   LIVE (operator gate): install the thin-projected canary into each host,
+ *   invoke its keyword, and confirm the host shows the POINTER, not the body.
+ *   This is a human-run step (live trigger-eval is a human gate) — the probe
+ *   prints the checklist + a results table to fill in.
+ *
+ * CLI:
+ *   ./scripts-run src/scripts/probe_host_compliance           # mechanical check + checklist
+ *   ./scripts-run src/scripts/probe_host_compliance --json
+ *
+ * Exit codes: 0 demotion verified · 1 file error · 2 projector failed to demote.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { thin_entry } from './project_thin_rules.js';
+
+const _HERE = fileURLToPath(import.meta.url);
+const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
+const CANARY = path.join(
+  REPO_ROOT,
+  'tests/fixtures/host-compliance/host-compliance-canary.md',
+);
+const CANARY_ID = 'host-compliance-canary';
+const SENTINEL = 'CANARY_BODY_SENTINEL_DO_NOT_INLINE';
+const KEYWORD = 'xyzzy-canary-probe';
+const POINTER_MARKER = 'Routed rule — load the body on trigger-match';
+
+// The supported hosts whose live thin-compliance must be falsified.
+const HOSTS = ['claude-code', 'cursor', 'augment'];
+
+export interface DemotionResult {
+  ok: boolean;
+  pointer_present: boolean;
+  body_removed: boolean;
+  trigger_hint_preserved: boolean;
+  link_present: boolean;
+}
+
+/** Assert a thinned canary is a valid pointer (body gone, still selectable). */
+export function evaluate_demotion(
+  thinned: string,
+  opts: { sentinel: string; keyword: string } = { sentinel: SENTINEL, keyword: KEYWORD },
+): DemotionResult {
+  const pointer_present = thinned.includes(POINTER_MARKER);
+  const body_removed = !thinned.includes(opts.sentinel);
+  const trigger_hint_preserved = thinned.includes(opts.keyword);
+  const link_present = /Body: \[`[^`]+`\]\(/.test(thinned);
+  return {
+    ok: pointer_present && body_removed && trigger_hint_preserved && link_present,
+    pointer_present,
+    body_removed,
+    trigger_hint_preserved,
+    link_present,
+  };
+}
+
+function operator_checklist(): string {
+  const rows = HOSTS.map(
+    (h) => `  - [ ] ${h}: fires on \`${KEYWORD}\` AND shows the pointer, NOT the body sentinel`,
+  ).join('\n');
+  return (
+    'LIVE host-compliance step (operator gate — live trigger-eval is human-run):\n' +
+    '  1. Set `lean_projection.mode: thin` and run `task generate-tools && task sync`.\n' +
+    '  2. Install the projected canary into each host.\n' +
+    `  3. Invoke the keyword \`${KEYWORD}\` in a session on each host.\n` +
+    '  4. PASS = the rule fires AND the host surfaces the router pointer;\n' +
+    `     FAIL = the host surfaces the body sentinel (\`${SENTINEL}\`) → thin\n` +
+    '     projection is a no-op there; escalate to the host vendor.\n' +
+    'Results:\n' +
+    rows +
+    '\n'
+  );
+}
+
+function main(argv: string[]): number {
+  const asJson = argv.includes('--json');
+  for (const a of argv) {
+    if (!['--json', '-h', '--help'].includes(a)) {
+      process.stderr.write(`error: unknown argument: ${a}\n`);
+      return 1;
+    }
+    if (a === '-h' || a === '--help') {
+      process.stdout.write('usage: probe_host_compliance [--json]\n');
+      return 0;
+    }
+  }
+
+  let text: string;
+  try {
+    text = fs.readFileSync(CANARY, 'utf-8');
+  } catch {
+    process.stderr.write(`error: cannot read canary fixture ${path.relative(REPO_ROOT, CANARY)}\n`);
+    return 1;
+  }
+  const thinned = thin_entry(CANARY_ID, text);
+  const result = evaluate_demotion(thinned);
+
+  if (asJson) {
+    process.stdout.write(
+      JSON.stringify({ ...result, hosts: HOSTS, keyword: KEYWORD, sentinel: SENTINEL }, null, 2) + '\n',
+    );
+    return result.ok ? 0 : 2;
+  }
+
+  process.stdout.write(
+    `${result.ok ? '✅' : '❌'}  mechanical demotion: ` +
+      `pointer=${result.pointer_present} body-removed=${result.body_removed} ` +
+      `hint=${result.trigger_hint_preserved} link=${result.link_present}\n`,
+  );
+  if (!result.ok) {
+    process.stdout.write('❌  the thin projector did NOT demote the canary correctly.\n');
+    return 2;
+  }
+  process.stdout.write('\n' + operator_checklist());
+  return 0;
+}
+
+const _IS_MAIN =
+  process.argv[1] !== undefined &&
+  import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href;
+
+if (_IS_MAIN) {
+  process.exit(main(process.argv.slice(2)));
+}
+
+export { main };