@adia-ai/web-components 0.8.40 → 0.8.41

package/bin/audit-template-children.mjs

@@ -0,0 +1,556 @@
+#!/usr/bin/env node
+/**
+ * audit-template-children.mjs — `adia-ui-audit-template-children` bin.
+ *
+ * The CONSUMABLE, installed-package twin of this repo's own
+ * `scripts/dev/audit-template-child-conflict.mjs` (gh#1446) — one shared
+ * implementation, resolved here against the SHIPPED tarball layout
+ * (`components/<name>/<name>.class.js` + `*.yaml`) rather than repo-relative paths,
+ * so a downstream consumer running `npx @adia-ai/web-components
+ * audit-template-children` (or the installed `adia-ui-audit-template-children`
+ * bin directly) gets the real gate instead of a reimplementation that can
+ * drift from it. Raised by the adiav2 SSR trial (gh#1430, gh#1435): their
+ * kit spec names this script as an admission gate, but until now it only
+ * existed as a repo-internal dev script — unreachable from an installed
+ * package — so they reimplemented it against `components/<name>/<name>.class.js` +
+ * yaml `slots:`, and that reimplementation had already drifted on the
+ * definition of "accepts consumer children" (see gh#1435: it read every
+ * `slots:` key as fillable; this repo's convention is `slots.default` +
+ * non-null template only). This file is the fix: the repo script
+ * (`scripts/dev/audit-template-child-conflict.mjs`) is now a thin wrapper
+ * around THIS implementation, pointed at repo-relative include dirs instead
+ * of the installed-package defaults below.
+ *
+ * ── The failure shape (gh#284) ──────────────────────────────────────────
+ * `UIElement.connectedCallback` runs `stamp(template(this), this)`, and
+ * `stamp()`'s first mount for a container calls `container.replaceChildren(f)`
+ * — replacing EVERY existing child with the template's own output. In a
+ * real browser this is invisible (a freshly-parsed, undefined custom
+ * element has no children yet). Under SSR (`connectedCallback` running
+ * against server-parsed DOM that already has real children — nested custom
+ * elements, or projected body text), the same call silently destroys that
+ * pre-existing content.
+ *
+ * **The definition of "accepts consumer children" this script enforces —
+ * and the one gh#1446's issue asks any reimplementation to match exactly:**
+ * a component whose `static template` is NOT the literal `() => null`
+ * no-op, AND whose yaml declares a `slots` entry named `default` (this
+ * repo's established convention for "real consumer children compose
+ * here" — see `nav.yaml` / `admin-shell.yaml`). That pairing is flagged
+ * **critical** (the CONTAINER shape — nested CE children silently wiped).
+ *
+ * A component whose `static template` is non-null AND whose own class.js
+ * top-of-file JSDoc usage example shows non-empty text content between the
+ * component's own opening/closing tags (e.g.
+ * `<text-ui variant="heading">Hello World</text-ui>`) is flagged
+ * **advisory** — a heuristic for the PROJECTED-TEXT shape, since implicit
+ * body text has no yaml `slots` entry to check. Skipped for a component
+ * already flagged critical (avoid double-reporting the same root cause).
+ *
+ * **What's NOT flagged**: a non-null template whose only children are ones
+ * the component's OWN `render()` manages via `slot=`-attributed elements it
+ * appends/removes itself (avatar-ui's `#imgEl`/`#initialsEl` pattern) —
+ * self-managed content, not consumer-provided. These components have
+ * `static template = () => null` anyway, so the non-null-template gate
+ * already excludes them.
+ *
+ * ── The `slots:` read, isolated on purpose (gh#1447) ────────────────────
+ * `declaredSlotNames()` below is the ONLY place this script reads a yaml's
+ * `slots:` block. gh#1447 (a sibling ticket, NOT this one — this script does
+ * not touch the yaml `slots:` schema) may replace the header-documented
+ * "`slots.default` = consumer children" convention with a mechanical
+ * `owned:`/`parts:` field on each slot entry. When that lands, only this one
+ * function's body needs to change — every caller keeps asking
+ * `acceptsConsumerChildrenSlot(yamlText)` and gets the right answer.
+ *
+ * ── Resolving against the INSTALLED package ──────────────────────────────
+ * With no `--include=` flag, this script scans its own installed location:
+ * `<this-package>/components/` plus, if `@adia-ai/web-modules` resolves
+ * from here too (it's an optionalDependency of `@adia-ai/web-components`),
+ * that package's whole tree — the same two roots the repo-internal wrapper
+ * passes explicitly as repo-relative paths. No `yaml` npm dependency is
+ * used or required — `declaredSlotNames()` is a minimal, self-contained
+ * scalar/mapping reader scoped to exactly the `slots:` block, the same
+ * "no external yaml dependency" convention `bin/doc.mjs` already
+ * established for this package (its `parseYaml()`); `check:packed-imports`
+ * would fail a bin script that imported an undeclared bare specifier, so
+ * staying dependency-free here is load-bearing, not just tidy.
+ *
+ * Usage:
+ *   npx adia-ui-audit-template-children
+ *   npx adia-ui-audit-template-children --json
+ *   npx adia-ui-audit-template-children --strict
+ *   npx adia-ui-audit-template-children --include=<dir> [--include=<dir> ...]
+ *   node bin/audit-template-children.mjs selftest
+ *
+ * Exit codes:
+ *   0 — no critical findings (or `selftest` passed)
+ *   1 — at least one critical finding (--strict raises to any finding),
+ *       or a `selftest` assertion failed
+ *   2 — usage error, or (selftest only) a required tool was unavailable
+ */
+
+import { readFileSync, readdirSync, statSync, existsSync, mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'node:fs';
+import { join, relative, dirname, basename, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
+import { spawnSync } from 'node:child_process';
+import { tmpdir } from 'node:os';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const PKG_ROOT = resolve(__dirname, '..'); // bin/ -> package root
+
+// ── Minimal yaml scalar reader (no external `yaml` dependency) ─────────────
+//
+// Strips a trailing YAML comment from a single raw line. A `#` only starts
+// a comment when it's at column 0 or preceded by whitespace (the YAML
+// plain-scalar rule) — a bare mid-word `#` (e.g. `gh#1253` inside a folded
+// description block) is content, not a comment marker. Quote state is
+// tracked (paired ' / ") so a `#` inside an actual quoted string is never
+// treated as a comment start either. Same fix as `bin/doc.mjs`'s
+// `stripYamlComment` (PR #1284 — the naive `/^([^#"']*)(#.*)?$/` regex cut
+// any line at its first bare `#`, silently truncating `gh#NNNN` mentions).
+function stripYamlComment(line) {
+  let inSingle = false;
+  let inDouble = false;
+  for (let i = 0; i < line.length; i++) {
+    const ch = line[i];
+    if (ch === "'" && !inDouble) inSingle = !inSingle;
+    else if (ch === '"' && !inSingle) inDouble = !inDouble;
+    else if (ch === '#' && !inSingle && !inDouble && (i === 0 || /\s/.test(line[i - 1]))) {
+      return line.slice(0, i).replace(/\s+$/, '');
+    }
+  }
+  return line.replace(/\s+$/, '');
+}
+
+/**
+ * Reads a yaml source's top-level `slots:` block and returns the set of
+ * declared slot names — nothing more. THE one helper gh#1447's own change
+ * (a mechanical `owned:`/`parts:` field) swaps out from the inside; every
+ * caller keeps asking `acceptsConsumerChildrenSlot(yamlText)`.
+ */
+export function declaredSlotNames(yamlText) {
+  const lines = yamlText.split(/\r?\n/).map(stripYamlComment);
+  const names = new Set();
+  let inSlots = false;
+  for (const line of lines) {
+    if (!inSlots) {
+      if (/^slots\s*:\s*$/.test(line)) inSlots = true;
+      continue;
+    }
+    if (line === '') continue;
+    if (/^\S/.test(line)) break; // next top-level key — block over
+    const m = line.match(/^ {2}([^:\s]+)\s*:/);
+    if (m) names.add(m[1]);
+  }
+  return names;
+}
+
+/** The header-documented definition of "accepts consumer children" (slot half). */
+export function acceptsConsumerChildrenSlot(yamlText) {
+  return declaredSlotNames(yamlText).has('default');
+}
+
+// ── `static template` extraction (verbatim from the gh#284 audit) ─────────
+//
+// Matches the three declaration shapes seen in the codebase:
+//   static template = () => null;
+//   static template = () => html`...`;
+//   static template = (el) => { ... };
+// We only need to know (a) whether the declaration exists, and (b) whether
+// its RHS is the literal no-op `() => null` — not evaluate it.
+export function extractTemplateDecl(jsText) {
+  const m = jsText.match(/static\s+template\s*=\s*/);
+  if (!m) return null;
+  const start = m.index + m[0].length;
+  let depthParen = 0, depthBrace = 0, inBacktick = false;
+  let i = start;
+  while (i < jsText.length) {
+    const c = jsText[i];
+    if (inBacktick) {
+      if (c === '\\') { i += 2; continue; }
+      if (c === '`') inBacktick = false;
+      i++;
+      continue;
+    }
+    if (c === '`') { inBacktick = true; i++; continue; }
+    if (c === '(') depthParen++;
+    else if (c === ')') depthParen--;
+    else if (c === '{') depthBrace++;
+    else if (c === '}') depthBrace--;
+    else if (c === ';' && depthParen <= 0 && depthBrace <= 0) break;
+    i++;
+  }
+  return jsText.slice(start, i).trim();
+}
+
+export function isNullTemplate(decl) {
+  if (!decl) return true; // no declaration at all — inherits base `() => null`
+  const normalized = decl.replace(/\s+/g, '');
+  return /^\(\)=>null$/.test(normalized) || /^\(\)=>\{return null;?\}$/.test(normalized);
+}
+
+// ── Projected-text heuristic (advisory) ─────────────────────────────────
+//
+// Looks for the component's own tag used in its top-of-file JSDoc usage
+// example with non-empty text content between open/close tags — the shape
+// of `<text-ui variant="heading">Hello World</text-ui>`. Attribute-only
+// examples (`<button-ui text="Save">`) and self-closing/empty-body examples
+// don't match.
+export function hasProjectedTextExample(jsText, tag) {
+  const re = new RegExp(`<${tag}\\b[^>]*>([^<]*[a-zA-Z][^<]*)</${tag}>`, 'i');
+  const m = jsText.match(re);
+  return !!(m && m[1] && m[1].trim().length > 0);
+}
+
+// ── Component enumeration ────────────────────────────────────────────────
+
+export function walkYamls(dir, out = []) {
+  let entries;
+  try {
+    entries = readdirSync(dir);
+  } catch {
+    return out;
+  }
+  for (const name of entries) {
+    if (name === 'node_modules' || name === 'dist' || name.startsWith('.')) continue;
+    const full = join(dir, name);
+    let s;
+    try {
+      s = statSync(full);
+    } catch {
+      continue;
+    }
+    if (s.isDirectory()) {
+      walkYamls(full, out);
+    } else if (name.endsWith('.yaml') && !name.endsWith('.a2ui.json.yaml')) {
+      const parentName = basename(dir);
+      if (name === `${parentName}.yaml`) out.push(full);
+    }
+  }
+  return out;
+}
+
+export function findClassJs(componentDir, name) {
+  const v2 = join(componentDir, `${name}.class.js`);
+  if (existsSync(v2)) return v2;
+  const v1 = join(componentDir, 'class.js');
+  if (existsSync(v1)) return v1;
+  return null;
+}
+
+/**
+ * Default scan roots when no `--include=` is given: this package's own
+ * `components/`, plus `@adia-ai/web-modules`'s package root IF that
+ * optionalDependency resolves from here (declared, per
+ * `check:packed-imports`'s undeclared-specifier gate, in
+ * `package.json#optionalDependencies`) — a consumer who installed it gets
+ * the same two-root scan the repo-internal wrapper passes explicitly.
+ */
+export function defaultIncludes() {
+  const includes = [resolve(PKG_ROOT, 'components')];
+  const req = createRequire(import.meta.url);
+  try {
+    const wmPkgJsonPath = req.resolve('@adia-ai/web-modules/package.json');
+    includes.push(dirname(wmPkgJsonPath));
+  } catch {
+    // Optional — not installed in this consumer. web-components-only scan.
+  }
+  return includes;
+}
+
+// ── Core scan ────────────────────────────────────────────────────────────
+
+export function runAudit(includes) {
+  const yamlPaths = [];
+  for (const inc of includes) walkYamls(inc, yamlPaths);
+
+  const findings = [];
+
+  for (const yamlPath of yamlPaths) {
+    const yamlText = readFileSync(yamlPath, 'utf8');
+    const componentDir = dirname(yamlPath);
+    const compName = basename(yamlPath, '.yaml');
+    const classPath = findClassJs(componentDir, compName);
+    if (!classPath) continue; // CSS-only component — no stamp() involved
+
+    const jsText = readFileSync(classPath, 'utf8');
+    const decl = extractTemplateDecl(jsText);
+    if (isNullTemplate(decl)) continue; // never calls stamp() — no exposure
+
+    // yaml `tag:` scalar — top-level, single-line only (matches every
+    // component in this repo; a folded/quoted tag would be unusual enough
+    // to fall back on the compName-derived default below).
+    const tagMatch = yamlText.match(/^tag\s*:\s*(.+)$/m);
+    const tag = (tagMatch ? tagMatch[1].trim() : '') || `${compName}-ui`;
+
+    if (acceptsConsumerChildrenSlot(yamlText)) {
+      findings.push({
+        component: compName,
+        tag,
+        yaml: yamlPath,
+        classJs: classPath,
+        shape: 'container',
+        severity: 'critical',
+        templateDecl: decl.length > 80 ? decl.slice(0, 80) + '…' : decl,
+      });
+      continue; // avoid double-reporting the same component below
+    }
+
+    if (hasProjectedTextExample(jsText, tag)) {
+      findings.push({
+        component: compName,
+        tag,
+        yaml: yamlPath,
+        classJs: classPath,
+        shape: 'projected-text',
+        severity: 'advisory',
+        templateDecl: decl.length > 80 ? decl.slice(0, 80) + '…' : decl,
+      });
+    }
+  }
+
+  const critical = findings.filter((f) => f.severity === 'critical');
+  const advisory = findings.filter((f) => f.severity === 'advisory');
+  return { scanned: yamlPaths.length, findings, critical, advisory };
+}
+
+// ── Output ───────────────────────────────────────────────────────────────
+
+function relPath(p) {
+  return relative(process.cwd(), p);
+}
+
+export function printReport(result, { jsonOut = false } = {}) {
+  const { scanned, findings, critical, advisory } = result;
+
+  if (jsonOut) {
+    process.stdout.write(JSON.stringify({
+      scanned,
+      findings: findings.map((f) => ({ ...f, yaml: relPath(f.yaml), classJs: relPath(f.classJs) })),
+      summary: { critical: critical.length, advisory: advisory.length },
+    }, null, 2) + '\n');
+    return;
+  }
+
+  if (critical.length) {
+    console.log('\n✗ CRITICAL — non-null template + a documented `slots.default` (gh#284 container shape):\n');
+    for (const f of critical) {
+      console.log(`  ✗  <${f.tag}>  static template = ${f.templateDecl}`);
+      console.log(`     yaml:  ${relPath(f.yaml)}`);
+      console.log(`     class: ${relPath(f.classJs)}`);
+    }
+    console.log('\n  connectedCallback\'s stamp() replaces ALL children on first mount. A');
+    console.log('  documented default slot means real consumer children can be present there');
+    console.log('  before connect (SSR, or a consumer pre-populating markup) — they will be');
+    console.log('  silently wiped. Either make the template null (compose via CSS + render()');
+    console.log('  DOM surgery), or treat this as a real regression against gh#284 / gh#1446\'s');
+    console.log('  documented contract before shipping the component.\n');
+  }
+  if (advisory.length) {
+    console.log('\n⚠  ADVISORY — non-null template + a body-text usage example (gh#284 projected-text shape):\n');
+    for (const f of advisory) {
+      console.log(`  ⚠  <${f.tag}>  static template = ${f.templateDecl}`);
+      console.log(`     yaml:  ${relPath(f.yaml)}`);
+      console.log(`     class: ${relPath(f.classJs)}`);
+    }
+    console.log('\n  No yaml `slots.default` to confirm this mechanically — the component\'s own');
+    console.log('  usage example shows plain text content between its tags, which stamp()\'s');
+    console.log('  first-mount replaceChildren would destroy under SSR. Verify manually.\n');
+  }
+  console.log(`[audit-template-children] scanned ${scanned} component yaml(s):`);
+  console.log(`  critical: ${critical.length}`);
+  console.log(`  advisory: ${advisory.length}\n`);
+}
+
+// ── CLI ──────────────────────────────────────────────────────────────────
+
+function usage(code) {
+  console.error('Usage: adia-ui-audit-template-children [--json] [--strict] [--include=<dir> ...]');
+  console.error('       adia-ui-audit-template-children selftest');
+  return code;
+}
+
+export function main(argv) {
+  if (argv[0] === 'selftest') return selftest();
+
+  for (const a of argv) {
+    if (a === '--json' || a === '--strict' || a.startsWith('--include=')) continue;
+    return usage(2);
+  }
+
+  const jsonOut = argv.includes('--json');
+  const strict = argv.includes('--strict');
+  const includeArgs = argv.filter((a) => a.startsWith('--include='));
+  const includes = includeArgs.length
+    ? includeArgs.map((a) => resolve(process.cwd(), a.slice('--include='.length)))
+    : defaultIncludes();
+
+  const result = runAudit(includes);
+  printReport(result, { jsonOut });
+
+  if (result.critical.length > 0) return 1;
+  if (strict && result.advisory.length > 0) return 1;
+  return 0;
+}
+
+// ── Selftest ─────────────────────────────────────────────────────────────
+//
+// Proves the shared implementation end to end against a scratch fixture
+// tree shaped like a real (or installed) `components/` directory —
+// deliberately spawns THIS file as a child process rather than only
+// calling `main()` in-process, so it also proves the CLI wiring (argv
+// parsing, exit codes, --json shape), not just the pure functions.
+
+function writeFixtureComponent(dir, name, { tag, template, slots, usageExample }) {
+  const compDir = join(dir, name);
+  mkdirSync(compDir, { recursive: true });
+  const yamlLines = [`name: UI${name}`, `tag: ${tag}`, `component: ${name}`];
+  if (slots && slots.length) {
+    yamlLines.push('slots:');
+    for (const s of slots) yamlLines.push(`  ${s}:\n    description: "test slot"`);
+  }
+  writeFileSync(join(compDir, `${name}.yaml`), yamlLines.join('\n') + '\n');
+  const jsLines = [
+    '/**',
+    ` * Usage: ${usageExample ?? `<${tag}></${tag}>`}`,
+    ' */',
+    `export class UI${name} {`,
+    `  static template = ${template};`,
+    '}',
+  ];
+  writeFileSync(join(compDir, `${name}.class.js`), jsLines.join('\n') + '\n');
+}
+
+function selftest() {
+  const scratch = mkdtempSync(join(tmpdir(), 'audit-template-children-selftest-'));
+  const failures = [];
+  const assert = (cond, msg) => { if (!cond) failures.push(msg); console.log(`  ${cond ? 'ok ' : 'FAIL'} ${msg}`); };
+
+  try {
+    // ── Unit: declaredSlotNames / acceptsConsumerChildrenSlot ──
+    assert(
+      declaredSlotNames('name: Foo\nslots:\n  default:\n    description: "x"\n  header:\n    description: "y"\nprops:\n  bar: {}\n').size === 2,
+      'declaredSlotNames: reads a 2-entry slots block'
+    );
+    assert(
+      acceptsConsumerChildrenSlot('name: Foo\nslots:\n  default:\n    description: "x"\n'),
+      'acceptsConsumerChildrenSlot: true when slots.default present'
+    );
+    assert(
+      !acceptsConsumerChildrenSlot('name: Foo\nslots:\n  header:\n    description: "x"\n'),
+      'acceptsConsumerChildrenSlot: false when default is absent (non-default slot only)'
+    );
+    assert(
+      !acceptsConsumerChildrenSlot('name: Foo\ndescription: "no slots block at all"\n'),
+      'acceptsConsumerChildrenSlot: false with no slots: block'
+    );
+    // PR #1284 regression: a bare `gh#NNNN` inside a description must not
+    // truncate the line as if `#` started a comment.
+    assert(
+      declaredSlotNames('slots:\n  default:\n    description: "see gh#1446 for context"\n').has('default'),
+      'declaredSlotNames: a mid-word gh#NNNN is not treated as a comment'
+    );
+
+    // ── Unit: template extraction ──
+    assert(isNullTemplate(extractTemplateDecl('static template = () => null;')), 'isNullTemplate: () => null');
+    assert(!isNullTemplate(extractTemplateDecl('static template = () => html`<span></span>`;')), 'isNullTemplate: false for a real template');
+    assert(isNullTemplate(extractTemplateDecl('no template here')), 'isNullTemplate: true when no declaration exists');
+
+    // ── End-to-end: a scratch `components/` tree + CLI invocation ──
+    const componentsDir = join(scratch, 'components');
+    // container shape — MUST be critical
+    writeFixtureComponent(componentsDir, 'leaky-container', {
+      tag: 'leaky-container-ui',
+      template: '() => html`<div></div>`',
+      slots: ['default'],
+    });
+    // projected-text shape — MUST be advisory
+    writeFixtureComponent(componentsDir, 'leaky-text', {
+      tag: 'leaky-text-ui',
+      template: '() => html`<span></span>`',
+      slots: [],
+      usageExample: '<leaky-text-ui>Hello World</leaky-text-ui>',
+    });
+    // safe: null template + slots.default — NEGATIVE CONTROL, no finding
+    writeFixtureComponent(componentsDir, 'safe-container', {
+      tag: 'safe-container-ui',
+      template: '() => null',
+      slots: ['default'],
+    });
+    // safe: non-null template, non-default slot only, attribute-only usage
+    writeFixtureComponent(componentsDir, 'safe-attrs', {
+      tag: 'safe-attrs-ui',
+      template: '() => html`<span></span>`',
+      slots: ['icon'],
+      usageExample: '<safe-attrs-ui label="Save"></safe-attrs-ui>',
+    });
+
+    const invoke = (...args) => spawnSync(process.execPath, [__filename, ...args], { cwd: scratch, encoding: 'utf8' });
+
+    const jsonRun = invoke(`--include=${componentsDir}`, '--json');
+    assert(jsonRun.status === 1, `critical finding present -> exit 1 (got ${jsonRun.status}, stderr: ${jsonRun.stderr})`);
+    let parsed = null;
+    try { parsed = JSON.parse(jsonRun.stdout); } catch (e) { failures.push(`--json produced invalid JSON: ${e.message}`); }
+    if (parsed) {
+      assert(parsed.summary.critical === 1, `exactly 1 critical finding (got ${parsed.summary?.critical})`);
+      assert(parsed.summary.advisory === 1, `exactly 1 advisory finding (got ${parsed.summary?.advisory})`);
+      assert(parsed.scanned === 4, `scanned all 4 fixture components (got ${parsed.scanned})`);
+      const criticalNames = parsed.findings.filter(f => f.severity === 'critical').map(f => f.component);
+      assert(criticalNames.includes('leaky-container') && !criticalNames.includes('safe-container'),
+        'critical finding is leaky-container only (negative control safe-container excluded)');
+    }
+
+    // --strict raises an advisory-only-would-be-0 run to 1 — but here critical
+    // is already present, so just confirm --strict doesn't LOWER the exit code.
+    const strictRun = invoke(`--include=${componentsDir}`, '--strict');
+    assert(strictRun.status === 1, `--strict with a critical present -> exit 1 (got ${strictRun.status})`);
+
+    // Advisory-only tree (drop the critical fixture) — plain run exits 0,
+    // --strict raises it to 1.
+    const advisoryOnlyDir = join(scratch, 'components-advisory-only');
+    writeFixtureComponent(advisoryOnlyDir, 'leaky-text', {
+      tag: 'leaky-text-ui',
+      template: '() => html`<span></span>`',
+      slots: [],
+      usageExample: '<leaky-text-ui>Hello World</leaky-text-ui>',
+    });
+    const plainAdvisory = invoke(`--include=${advisoryOnlyDir}`);
+    assert(plainAdvisory.status === 0, `advisory-only, no --strict -> exit 0 (got ${plainAdvisory.status})`);
+    const strictAdvisory = invoke(`--include=${advisoryOnlyDir}`, '--strict');
+    assert(strictAdvisory.status === 1, `advisory-only, --strict -> exit 1 (got ${strictAdvisory.status})`);
+
+    // Empty tree — clean exit 0, scanned 0.
+    const emptyDir = join(scratch, 'empty');
+    mkdirSync(emptyDir, { recursive: true });
+    const emptyRun = invoke(`--include=${emptyDir}`, '--json');
+    assert(emptyRun.status === 0, `empty include dir -> exit 0 (got ${emptyRun.status})`);
+
+    // Usage error.
+    const bogus = invoke('--not-a-real-flag');
+    assert(bogus.status === 2, `unknown flag -> exit 2 (got ${bogus.status})`);
+
+    // defaultIncludes() resolves without throwing even when web-modules
+    // isn't resolvable (this scratch dir has no node_modules at all).
+    let defaultsOk = true;
+    try { defaultIncludes(); } catch { defaultsOk = false; }
+    assert(defaultsOk, 'defaultIncludes() does not throw when @adia-ai/web-modules is unresolvable');
+  } finally {
+    rmSync(scratch, { recursive: true, force: true });
+  }
+
+  const pass = failures.length === 0;
+  console.log(`\n${pass ? 'ok' : 'FAIL'} — audit-template-children selftest (${failures.length} failure(s))`);
+  return pass ? 0 : 1;
+}
+
+// ── Entrypoint guard — only run the CLI when this file is the process's
+// own entry script, so importing these exports (the package's own test
+// suite) never has the side effect of running main() against the test
+// runner's own argv. ──
+const isMain = process.argv[1] && resolve(process.argv[1]) === __filename;
+if (isMain) {
+  process.exitCode = main(process.argv.slice(2));
+}

package/components/accordion/accordion-item.a2ui.json

@@ -40,6 +40,9 @@
   ],
   "unevaluatedProperties": false,
   "x-adiaui": {
+    "allowedParents": [
+      "Accordion"
+    ],
     "anti_patterns": [],
     "category": "layout",
     "composes": [],
@@ -64,6 +67,7 @@
       "section-toggle"
     ],
     "name": "UIAccordionItem",
+    "parts": {},
     "related": [
       "Accordion",
       "Card"

package/components/accordion/accordion-item.yaml

@@ -105,6 +105,8 @@ related:
   - Card
 
 a2ui:
+  allowedParents:
+    - Accordion
   rules:
     - rule: 'Child of <accordion-ui> — places one collapsible section with header + body.'
       reason: 'Cluster contract.'

package/components/accordion/accordion.a2ui.json

@@ -36,6 +36,9 @@
   ],
   "unevaluatedProperties": false,
   "x-adiaui": {
+    "allowedChildren": [
+      "AccordionItem"
+    ],
     "anti_patterns": [],
     "category": "container",
     "composes": [
@@ -76,6 +79,7 @@
       "expand"
     ],
     "name": "UIAccordion",
+    "parts": {},
     "related": [
       "accordion-item",
       "input",

package/components/accordion/accordion.yaml

@@ -57,6 +57,8 @@ tokens: {}
 requiredIcons:
   - caret-down
 a2ui:
+  allowedChildren:
+    - AccordionItem
   rules:
     - rule: 'Hosts <accordion-item-ui> children. One or more sections may be open simultaneously (set single= to enforce only-one-open).'
       reason: 'Multi-vs-single open mode.'

package/components/action-list/action-item.a2ui.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://adiaui.dev/a2ui/v0_9/components/ActionItem.json",
   "title": "ActionItem",
-  "description": "Child of <action-list-ui>. One actionable row — icon + label, forwards activation to the parent action-list.",
+  "description": "Child of <action-list-ui>. One actionable row — icon + label + optional\nsubtitle, forwards activation to the parent action-list. Row contract\nconverges on <menu-item-ui>: icon/text/subtitle/value/variant/disabled\nprops and icon/text/subtitle/trailing slot overrides (#1363 C5).",
   "type": "object",
   "allOf": [
     {
@@ -25,6 +25,11 @@
       "description": "Leading icon name (Phosphor).",
       "type": "string"
     },
+    "subtitle": {
+      "description": "Optional secondary description line rendered under the label.",
+      "type": "string",
+      "default": ""
+    },
     "text": {
       "description": "Action label.",
       "type": "string"
@@ -34,8 +39,12 @@
       "type": "string"
     },
     "variant": {
-      "description": "Visual variant (default | accent | danger).",
+      "description": "Visual variant (default | danger).",
       "type": "string",
+      "enum": [
+        "default",
+        "danger"
+      ],
       "default": "default"
     }
   },
@@ -44,6 +53,9 @@
   ],
   "unevaluatedProperties": false,
   "x-adiaui": {
+    "allowedParents": [
+      "ActionList"
+    ],
     "anti_patterns": [],
     "category": "navigation",
     "composes": [],
@@ -57,6 +69,7 @@
       "action-list-row"
     ],
     "name": "UIActionItem",
+    "parts": {},
     "related": [
       "ActionList",
       "MenuItem",
@@ -65,6 +78,15 @@
     "slots": {
       "icon": {
         "description": "Override the [icon] glyph with a custom slotted element (custom icon-ui, image, avatar). Mutually exclusive with the [icon] attribute — slot child wins."
+      },
+      "subtitle": {
+        "description": "Custom secondary-line content override; falls through to [subtitle] prop if not slotted."
+      },
+      "text": {
+        "description": "Custom label content; falls through to [text] prop if not slotted."
+      },
+      "trailing": {
+        "description": "Trailing element pinned to the far edge (shortcut hint, badge, caret). Supersedes the unnamed default slot this row previously used for trailing content — see MIGRATION GUIDE."
       }
     },
     "states": [],