@cometchat/skills 4.4.1 → 5.0.0

package/test-suite/scripts/verify-family-agnostic.mjs

@@ -0,0 +1,130 @@
+#!/usr/bin/env node
+/**
+ * verify-family-agnostic.mjs — the machine guard for RULES.md §22.
+ *
+ * The pack's tools are documented as "family-agnostic — copy them; a new family adds only
+ * its typecheck/<family>/ + a --discover needle". Nothing enforced that claim, and eleven
+ * separate tools drifted into hardcoding `web-v7` (AUDIT-091/087/088/090/091). Three of them
+ * reported green while checking nothing.
+ *
+ * This fails the build when a family key appears as a literal in a tool that does not resolve
+ * it from families.json. Allowed: a default read from families.json's own `default`, and the
+ * families.json file itself.
+ */
+import { readFileSync, existsSync, readdirSync } from "node:fs";
+import { join, dirname, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), "../..");
+const FAMILIES = join(ROOT, ".claude/skills/cometchat-skill-reviewer/tools/families.json");
+if (!existsSync(FAMILIES)) { console.log("❌ families.json missing — cannot verify"); process.exit(2); }
+
+const fams = JSON.parse(readFileSync(FAMILIES, "utf8")).families;
+// Both the family keys and the registry/catalog basenames they imply are family identifiers.
+const KEYS = [...new Set(Object.entries(fams).flatMap(([k, v]) =>
+  [k, (v.catalog || "").replace(/^catalog\//, "").replace(/\.json$/, "")].filter(Boolean)))];
+
+const TOOLS = [
+  ...readdirSync(join(ROOT, "test-suite/scripts")).filter((f) => f.endsWith(".mjs")).map((f) => `test-suite/scripts/${f}`),
+  ...(existsSync(join(ROOT, "bin")) ? readdirSync(join(ROOT, "bin")).filter((f) => f.endsWith(".mjs")).map((f) => `bin/${f}`) : []),
+];
+
+const SELF = "verify-family-agnostic.mjs";
+const violations = [];
+for (const rel of TOOLS) {
+  if (rel.endsWith(SELF)) continue;
+  const src = readFileSync(join(ROOT, rel), "utf8");
+  const readsFamilies = src.includes("families.json");
+  src.split("\n").forEach((line, i) => {
+    if (/^\s*(\/\/|\*|\/\*)/.test(line)) return;              // comments may name families freely
+    for (const k of KEYS) {
+      if (!new RegExp(`["'\`]${k.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}["'\`]`).test(line)) continue;
+      // a default sourced from families.json is legitimate
+      if (readsFamilies && /families?\.default|DEFAULT_FAMILY/.test(line)) continue;
+      violations.push({ rel, line: i + 1, key: k, text: line.trim().slice(0, 96), readsFamilies });
+    }
+  });
+}
+
+// ── §22b: PLATFORM-NEUTRAL surfaces must not name one family ────────────────
+// The key-literal scan above passed while bin/ hardcoded "React v7 UI Kit" as the
+// AGENTS.md title and the entry router sent every request to `cometchat-react-v7-*`
+// — neither is a family KEY, so neither was seen. A React Native project got a
+// router claiming it was React web, and the agent stopped trusting it (AUDIT-101).
+// These files are read by EVERY family, so a family-specific literal is a defect.
+const NEUTRAL = [
+  ...(existsSync(join(ROOT, "bin")) ? readdirSync(join(ROOT, "bin")).filter((f) => f.endsWith(".mjs")).map((f) => `bin/${f}`) : []),
+  "RULES.md",
+  ...["cometchat", "cometchat-onboarding"].flatMap((d) => {
+    const dir = join(ROOT, "skills", d);
+    if (!existsSync(dir)) return [];
+    const out = [`skills/${d}/SKILL.md`];
+    const refs = join(dir, "references");
+    if (existsSync(refs)) out.push(...readdirSync(refs).filter((f) => f.endsWith(".md")).map((f) => `skills/${d}/references/${f}`));
+    return out.filter((f) => existsSync(join(ROOT, f)));
+  }),
+];
+// Family identifiers that are NOT keys: the skill-dir prefix and the kit package.
+const peersYaml = existsSync(join(ROOT, "peers.yaml")) ? readFileSync(join(ROOT, "peers.yaml"), "utf8") : "";
+const MARKS = [...new Set([
+  ...[...peersYaml.matchAll(/dir_prefix:\s*"([^"]+)"/g)].map((m) => m[1]),
+  ...[...peersYaml.matchAll(/kit_package:\s*"([^"]+)"/g)].map((m) => m[1]),
+])].filter(Boolean);
+const FAMILY_NAMES = [...new Set([...peersYaml.matchAll(/dir_prefix:\s*"cometchat-([^"]+?)-?"/g)].map((m) => m[1]))].filter(Boolean);
+
+// §22c: a reference that is PER-PLATFORM BY DESIGN may DECLARE itself.
+// `skills/cometchat-onboarding/references/platforms.md` is a per-platform table/list whose whole
+// job is one entry per shipped family — `lint-skills.mjs` GATE R (gateSharedSkillsCoverShippedFamilies)
+// FAILS it when a shipped family has no column. So the two gates contradict on that file: one demands
+// per-family content, the other forbids naming a single family. The escape is a DECLARED marker the
+// file itself carries — never a filename hardcoded here — so the exemption is auditable, is printed
+// on every run, and cannot be silently inherited by the next reference dropped into `references/`.
+// It is not a blanket pass: a declaring file must name TWO OR MORE families overall, otherwise the
+// marker is being used to smuggle a single-family document onto a platform-neutral surface.
+const PER_PLATFORM_MARKER = /^\s*<!--\s*family-agnostic:\s*per-platform-by-design\b/m;
+const declaredExempt = [];
+
+for (const rel of NEUTRAL) {
+  const src = readFileSync(join(ROOT, rel), "utf8");
+  if (PER_PLATFORM_MARKER.test(src)) {
+    const namedInFile = FAMILY_NAMES.filter((f) => src.includes(f));
+    if (namedInFile.length >= 2) { declaredExempt.push({ rel, families: namedInFile.length }); continue; }
+    violations.push({
+      rel, line: src.split("\n").findIndex((l) => PER_PLATFORM_MARKER.test(l)) + 1,
+      key: "per-platform-by-design", readsFamilies: true, neutral: true,
+      text: `declares the per-platform exemption but names ${namedInFile.length} family/families — the marker is for MULTI-family references only`,
+    });
+    continue;
+  }
+  src.split("\n").forEach((line, i) => {
+    if (/^\s*(\/\/|\*|\/\*|>)/.test(line)) return;        // comments/quotes may name families
+    if (/<family>/.test(line)) return;                      // already parameterised
+    // Naming ONE family in a neutral file is the defect. A line that names TWO or more is
+    // an explicit per-family branch ("react-v7: X; react-native: Y") — that is how a neutral
+    // file legitimately documents a divergence, so allow it.
+    const named = FAMILY_NAMES.filter((f) => line.includes(f));
+    if (named.length >= 2) return;
+    for (const mark of MARKS) {
+      if (!line.includes(mark)) continue;
+      violations.push({ rel, line: i + 1, key: mark, text: line.trim().slice(0, 96), readsFamilies: true, neutral: true });
+    }
+  });
+}
+
+// Declared exemptions PRINT on every run (pass or fail) so they cannot rot into silence.
+for (const e of declaredExempt) {
+  console.log(`ℹ️  per-platform-by-design (declared): ${e.rel} — exempt from the neutral scan; names ${e.families} families. GATE R (lint-skills) enforces its per-family coverage.`);
+}
+
+if (!violations.length) {
+  console.log(`✅ family-agnostic: ${TOOLS.length} tool(s) scanned; no hardcoded family keys; ${NEUTRAL.length - declaredExempt.length} platform-neutral file(s) clean; ${declaredExempt.length} declared per-platform reference(s).`);
+  process.exit(0);
+}
+console.log(`❌ family-agnostic: ${violations.length} hardcoded family key(s) — RULES.md §22.`);
+console.log("   Every family-scoped path must come from families.json; a literal here means the");
+console.log("   tool silently skips (or mis-attributes) every other family.\n");
+for (const v of violations) {
+  console.log(`   ${v.rel}:${v.line}  "${v.key}"${v.readsFamilies ? "" : "   (does not read families.json at all)"}`);
+  console.log(`      ${v.text}`);
+}
+process.exit(1);

package/test-suite/scripts/verify-golden-path.mjs

@@ -0,0 +1,138 @@
+#!/usr/bin/env node
+/**
+ * verify-golden-path.mjs — compile a skill's RECIPE as a real Angular component.
+ *
+ * The gap this closes: `verify:fences` type-checks ts fences in isolation, and
+ * `verify:templates` checks that a template's selectors/bindings EXIST. Neither ever
+ * type-checks an html fence's bindings AGAINST the ts fence that backs it. So a recipe
+ * could declare `selectedUser: CometChat.User | null` and bind it to the kit's
+ * `user?: CometChat.User`, and every gate stayed green while the recipe failed
+ * `ng build` with 8× TS2322 in any stock Angular app (strictTemplates is on by default).
+ * That shipped in the always-loaded core golden path — the first thing a new user runs.
+ *
+ * It pairs a `templateUrl:`-bearing ts fence with the html fence that follows it (plus an
+ * optional css fence), writes them as a component into the review app, and runs the real
+ * Angular compiler over the whole app.
+ *
+ * Usage: node test-suite/scripts/verify-golden-path.mjs [--family angular-v5] [--json]
+ * Exit:  0 clean (or skipped — app absent) · 1 a recipe does not compile · 2 bad usage.
+ */
+import { readFileSync, existsSync, mkdirSync, rmSync, writeFileSync, readdirSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawnSync } from "node:child_process";
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
+
+// RULES.md §22 — every family-scoped path comes from families.json; a literal family key
+// here means the tool silently skips (or mis-attributes) every other family.
+const FAMILIES = JSON.parse(readFileSync(
+  join(ROOT, ".claude/skills/cometchat-skill-reviewer/tools/families.json"), "utf8")).families;
+// families.json is keyed by review key (web-angular-v5); tools take the catalog key
+// (angular-v5). Resolve either, so --family angular-v5 and --family web-angular-v5 both work.
+function resolveFamily(key) {
+  const byCatalog = Object.values(FAMILIES).find(
+    (f) => (f.catalog || "").replace(/^catalog\//, "").replace(/\.json$/, "") === key);
+  return FAMILIES[key] || byCatalog || null;
+}
+const arg = (n, d) => { const i = process.argv.indexOf(n); return i >= 0 ? process.argv[i + 1] : d; };
+const JSON_OUT = process.argv.includes("--json");
+// RULES.md §22: no literal family key, not even as a default — the caller names the family
+const FAMILY = arg("--family");
+if (!FAMILY) { console.error("--family is required (see families.json)"); process.exit(2); }
+
+const _f = resolveFamily(FAMILY);
+if (!_f) { console.error(`unknown --family: ${FAMILY} (known: ${Object.keys(FAMILIES).join(", ")})`); process.exit(2); }
+if (!_f.appDir || !_f.skillDirPattern) {
+  console.log(`⏭  verify-golden-path [${FAMILY}]: family declares no appDir/skillDirPattern — skipped`);
+  process.exit(0);
+}
+const FAM = { app: _f.appDir, skillDir: new RegExp(_f.skillDirPattern) };
+
+const app = join(ROOT, FAM.app);
+if (!existsSync(join(app, "node_modules", "@cometchat"))) {
+  console.log(`⏭  verify-golden-path [${FAMILY}]: review app not provisioned — skipped (not a failure)`);
+  process.exit(0);
+}
+
+// Collect (ts, html, css?) recipe triples from every skill markdown.
+function recipes() {
+  const out = [];
+  const skills = join(ROOT, "skills");
+  const walk = (d, skill) => {
+    for (const e of readdirSync(d, { withFileTypes: true })) {
+      const p = join(d, e.name);
+      if (e.isDirectory()) { walk(p, skill); continue; }
+      if (!e.name.endsWith(".md")) continue;
+      const txt = readFileSync(p, "utf8");
+      // Fences in document order, so an html fence can be matched to the ts fence above it.
+      const fences = [...txt.matchAll(/```(ts|html|css)\n([\s\S]*?)```/g)]
+        .map((m) => ({ lang: m[1], body: m[2] }));
+      for (let i = 0; i < fences.length; i++) {
+        if (fences[i].lang !== "ts" || !/templateUrl:/.test(fences[i].body)) continue;
+        const html = fences.slice(i + 1).find((f) => f.lang === "html");
+        if (!html) continue;
+        const css = fences.slice(i + 1).find((f) => f.lang === "css");
+        out.push({ file: `${skill}/${e.name}`, ts: fences[i].body, html: html.body, css: css ? css.body : "" });
+      }
+    }
+  };
+  for (const d of readdirSync(join(skills), { withFileTypes: true })) {
+    if (d.isDirectory() && FAM.skillDir.test(d.name)) walk(join(skills, d.name), d.name);
+  }
+  return out;
+}
+
+const found = recipes();
+const stage = join(app, "src", "app", "__goldenpath__");
+rmSync(stage, { recursive: true, force: true });
+mkdirSync(stage, { recursive: true });
+
+const written = [];
+found.forEach((r, n) => {
+  const dir = join(stage, `r${n}`);
+  mkdirSync(dir, { recursive: true });
+  // Point the component at the files we write beside it, whatever the recipe named them.
+  const ts = r.ts
+    .replace(/templateUrl:\s*'[^']*'/, "templateUrl: './tpl.html'")
+    .replace(/styleUrls?:\s*\[[^\]]*\]/, "styleUrl: './tpl.css'")
+    .replace(/styleUrl:\s*'[^']*'/, "styleUrl: './tpl.css'");
+  writeFileSync(join(dir, "cmp.ts"), ts);
+  writeFileSync(join(dir, "tpl.html"), r.html);
+  writeFileSync(join(dir, "tpl.css"), r.css);
+  written.push({ index: n, file: r.file });
+});
+
+const res = spawnSync("npx", ["ng", "build", "--configuration", "development"], { cwd: app, encoding: "utf8" });
+const out = (res.stdout || "") + (res.stderr || "");
+rmSync(stage, { recursive: true, force: true });
+
+// Attribute each error block back to the recipe whose staged dir it names.
+const lines = out.split("\n");
+const isHead = (l) => /error TS\d+/.test(l) || /\[ERROR\]/.test(l);
+const blocks = [];
+for (let i = 0; i < lines.length; i++) {
+  if (!isHead(lines[i])) continue;
+  const parts = [lines[i].trim()];
+  for (let j = i + 1; j < lines.length && !isHead(lines[j]); j++) {
+    if (!lines[j].trim()) { if (j + 1 < lines.length && /^\s+\S/.test(lines[j + 1])) continue; break; }
+    if (!/^\s+\S/.test(lines[j])) break;
+    parts.push(lines[j].trim());
+  }
+  blocks.push(parts.join(" "));
+}
+const mine = blocks.filter((b) => b.includes("__goldenpath__"));
+const attributed = mine.map((b) => {
+  const m = b.match(/__goldenpath__\/r(\d+)\//);
+  const rec = m ? written.find((w) => w.index === Number(m[1])) : null;
+  return { recipe: rec ? rec.file : "(unknown)", error: b.slice(0, 240) };
+});
+
+if (JSON_OUT) { console.log(JSON.stringify({ ok: !attributed.length, recipes: written.length, errors: attributed }, null, 0)); process.exit(attributed.length ? 1 : 0); }
+if (!attributed.length) {
+  console.log(`✅ verify-golden-path [${FAMILY}]: ${written.length} recipe(s) compile as real components (template bindings type-checked against their own class).`);
+  process.exit(0);
+}
+console.log(`❌ verify-golden-path [${FAMILY}]: ${attributed.length} error(s) — a documented recipe does not compile:`);
+for (const a of attributed) console.log(`  [${a.recipe}] ${a.error}`);
+process.exit(1);

package/test-suite/scripts/verify-oracle-components.mjs

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+/**
+ * verify-oracle-components.mjs — features.<family>.json `ui_components` must list only
+ * components a HOST imports and writes in a template.
+ *
+ * `ui_components` drives the reviewer's G1 `mustUseComponents`, so a KIT-INTERNAL child
+ * (a *-item inside its list, a singular *-bubble inside cometchat-message-bubble, a
+ * keyboard/dialog inside the composer) makes the gate demand an import a CORRECT emit
+ * must not have. That shipped in six features and cost a review tick each time.
+ *
+ * A component is kit-internal when BOTH hold:
+ *   1. some OTHER kit component lists it in its own standalone `imports: []`, and
+ *   2. no skill RECIPE writes its selector (catalog.md is excluded — that file is the
+ *      complete EXISTENCE list, not a list of things a host emits).
+ * Condition 2 is what keeps host-facing components that merely happen to be reused
+ * inside another kit component (cometchat-message-list inside cometchat-ai-assistant-chat)
+ * from being flagged.
+ *
+ * Usage: node test-suite/scripts/verify-oracle-components.mjs [--family angular-v5] [--json]
+ * Exit:  0 clean · 1 kit-internal entries found · 2 bad invocation (kit not installed).
+ */
+import { readFileSync, existsSync, readdirSync, statSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
+
+// RULES.md §22 — every family-scoped path comes from families.json; a literal family key
+// here means the tool silently skips (or mis-attributes) every other family.
+const FAMILIES = JSON.parse(readFileSync(
+  join(ROOT, ".claude/skills/cometchat-skill-reviewer/tools/families.json"), "utf8")).families;
+// families.json is keyed by review key (web-angular-v5); tools take the catalog key
+// (angular-v5). Resolve either, so --family angular-v5 and --family web-angular-v5 both work.
+function resolveFamily(key) {
+  const byCatalog = Object.values(FAMILIES).find(
+    (f) => (f.catalog || "").replace(/^catalog\//, "").replace(/\.json$/, "") === key);
+  return FAMILIES[key] || byCatalog || null;
+}
+const arg = (n, d) => { const i = process.argv.indexOf(n); return i >= 0 ? process.argv[i + 1] : d; };
+const JSON_OUT = process.argv.includes("--json");
+// RULES.md §22: no literal family key, not even as a default — the caller names the family
+const FAMILY = arg("--family");
+if (!FAMILY) { console.error("--family is required (see families.json)"); process.exit(2); }
+
+const _f = resolveFamily(FAMILY);
+if (!_f) { console.error(`unknown --family: ${FAMILY}`); process.exit(2); }
+const _kitDir = (_f.catalog_build?.dirs || []).find((d) => /chat-uikit-/.test(d));
+if (!_kitDir || !_f.features || !_f.skillDirPattern) {
+  console.log(`⏭  verify-oracle-components [${FAMILY}]: family declares no kit dir / features / skillDirPattern — skipped`);
+  process.exit(0);
+}
+const FAM = {
+  features: _f.features,
+  bundle: `${_kitDir}/fesm2022/${_f.kitPackage.replace(/^@/, "").replace("/", "-")}.mjs`,
+  skillGlob: new RegExp(_f.skillDirPattern),
+};
+
+const bundlePath = join(ROOT, FAM.bundle);
+if (!existsSync(bundlePath)) {
+  // The review app is git-ignored, so this gate is a no-op in a clean checkout rather
+  // than a false failure. It runs wherever the kit is installed (locally, and in CI once
+  // the app is provisioned).
+  console.log(`⏭  verify-oracle-components [${FAMILY}]: kit bundle not installed — skipped (not a failure)`);
+  process.exit(0);
+}
+const bundle = readFileSync(bundlePath, "utf8");
+
+const selectorOf = (c) =>
+  (bundle.match(new RegExp(`type: ${c}, isStandalone: true, selector: "([a-z-]+)"`)) || [])[1] || null;
+
+function kitParents(c) {
+  const own = selectorOf(c);
+  const re = /args: \[\{ selector: .([a-z-]+)., standalone: true, [^]{0,700}?imports: \[([^\]]*)\]/g;
+  const out = new Set();
+  let m;
+  while ((m = re.exec(bundle))) {
+    if (m[1] !== own && new RegExp(`\\b${c}\\b`).test(m[2])) out.add(m[1]);
+  }
+  return [...out];
+}
+
+// Every selector written in a skill RECIPE (catalog.md excluded).
+function recipeSelectors() {
+  const found = new Set();
+  const skills = join(ROOT, "skills");
+  const walk = (d) => {
+    for (const e of readdirSync(d, { withFileTypes: true })) {
+      const p = join(d, e.name);
+      if (e.isDirectory()) { walk(p); continue; }
+      if (!e.name.endsWith(".md") || e.name === "catalog.md") continue;
+      // Only selectors inside a CODE FENCE count as "a recipe emits this". A prose
+      // enumeration ("**Search** `<cometchat-search>` · `<cometchat-search-bar>` · …") is a
+      // listing, like catalog.md, and counting it let three kit-internal search components
+      // pass this gate — a false negative that then cost a review tick at G1.
+      const txt = readFileSync(p, "utf8");
+      for (const f of txt.matchAll(/```(?:html|ts|tsx|typescript)\n([\s\S]*?)```/g)) {
+        for (const m of f[1].matchAll(/<(cometchat-[a-z-]+)\b/g)) found.add(m[1]);
+      }
+    }
+  };
+  for (const d of readdirSync(skills, { withFileTypes: true })) {
+    if (d.isDirectory() && FAM.skillGlob.test(d.name)) walk(join(skills, d.name));
+  }
+  return found;
+}
+
+const recipes = recipeSelectors();
+const features = JSON.parse(readFileSync(join(ROOT, FAM.features), "utf8")).features || [];
+const offenders = [];
+for (const f of features) {
+  // `auto_rendered_ui: true` already tells compile-expect to demand NOTHING (the kit
+  // renders it all), so listing the bubbles there is harmless documentation of what the
+  // kit draws. The defect only bites when the entries are actually demanded.
+  if (f.auto_rendered_ui) continue;
+  for (const c of f.ui_components || []) {
+    const sel = selectorOf(c);
+    if (!sel) continue;                       // not a component (a formatter class etc.)
+    if (recipes.has(sel)) continue;           // a recipe emits it → host-facing
+    const parents = kitParents(c);
+    if (parents.length) offenders.push({ feature: f.id, component: c, selector: sel, renderedBy: parents });
+  }
+}
+
+if (JSON_OUT) { console.log(JSON.stringify({ ok: !offenders.length, offenders }, null, 0)); process.exit(offenders.length ? 1 : 0); }
+if (!offenders.length) {
+  console.log(`✅ verify-oracle-components [${FAMILY}]: every ui_components entry is host-facing.`);
+  process.exit(0);
+}
+console.log(`❌ verify-oracle-components [${FAMILY}]: ${offenders.length} kit-internal component(s) listed as host imports:`);
+for (const o of offenders) {
+  console.log(`  - ${o.feature}: ${o.component} <${o.selector}> is rendered by ${o.renderedBy.join(", ")} — G1 will demand an import a correct emit must not have`);
+}
+process.exit(1);

package/test-suite/scripts/verify-template-bindings.mjs

@@ -0,0 +1,148 @@
+#!/usr/bin/env node
+/**
+ * verify-template-bindings.mjs — Tier-2b: validate Angular TEMPLATE bindings in
+ * ```html skill fences against the installed kit's component declarations.
+ *
+ *   node test-suite/scripts/verify-template-bindings.mjs --family angular-v5 \
+ *     --project test-suite/typecheck/angular-v5
+ *
+ * WHY THIS EXISTS
+ * typecheck-fences.mjs only extracts ```ts/```tsx fences, because that is all
+ * `tsc` can check. In React that is sufficient — component usage lives in .tsx
+ * and bad props fail the compile. In ANGULAR component usage lives in the
+ * TEMPLATE, so the half of the surface most likely to be wrong was checked by
+ * nothing at all.
+ *
+ * Concretely: `<cometchat-conversations (ccConversationClicked)="...">` shipped
+ * in cometchat-angular-v5-core and passed lint + catalog + fences, all green.
+ * The real output is `itemClick`; `ccConversationClicked` is a React-ism. An
+ * unknown output binding in Angular fails SILENTLY — no error, the handler just
+ * never fires — so this is exactly the class of defect a human review misses.
+ *
+ * Validating a template properly needs Angular's own compiler (ngtsc with
+ * strictTemplates), which needs a real component + imports[] + a build — far too
+ * heavy for illustrative fragments. This does the targeted 90%: every
+ * <cometchat-*> element's selector must exist, and every [input] / (output)
+ * bound on it must be declared by that component.
+ *
+ * Reads the kit's ɵɵComponentDeclaration entries (selector + input/output maps),
+ * so it is always in sync with the installed version — no committed artifact to
+ * drift. Needs the pinned kit installed (same precondition as verify:fences);
+ * hard-exits 2 when absent so it can never pass vacuously.
+ *
+ * Exit: 0 clean · 1 unknown selector/binding · 2 bad invocation or kit missing.
+ */
+import { readFileSync, readdirSync, existsSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
+const arg = (n, d) => { const i = process.argv.indexOf(n); return i >= 0 ? process.argv[i + 1] : d; };
+
+// RULES.md §22 — no literal family key; resolve from families.json (by review key OR
+// catalog key, so --family angular-v5 and --family web-angular-v5 both work).
+const FAM_DATA = JSON.parse(readFileSync(
+  join(ROOT, ".claude/skills/cometchat-skill-reviewer/tools/families.json"), "utf8")).families;
+// RULES.md §22: no literal family key, not even as a default — the caller names the family
+const FAMILY = arg("--family");
+if (!FAMILY) { console.error("--family is required (see families.json)"); process.exit(2); }
+const PROJECT = arg("--project", `test-suite/typecheck/${FAMILY}`);
+const _f = FAM_DATA[FAMILY] || Object.values(FAM_DATA).find(
+  (f) => (f.catalog || "").replace(/^catalog\//, "").replace(/\.json$/, "") === FAMILY);
+if (!_f) { console.error(`unknown --family: ${FAMILY}`); process.exit(2); }
+if (!_f.kitPackage || !_f.skillDirPattern) {
+  console.log(`⏭  verify-template-bindings [${FAMILY}]: family declares no kitPackage/skillDirPattern — skipped`);
+  process.exit(0);
+}
+const fam = {
+  skillDir: new RegExp(_f.skillDirPattern),
+  kit: `node_modules/${_f.kitPackage}`,
+  // @cometchat/chat-uikit-angular -> types/cometchat-chat-uikit-angular.d.ts
+  dts: `types/${_f.kitPackage.replace(/^@/, "").replace("/", "-")}.d.ts`,
+};
+
+const dtsPath = join(ROOT, PROJECT, fam.kit, fam.dts);
+if (!existsSync(dtsPath)) {
+  console.error(`kit not installed: ${dtsPath}`);
+  console.error(`run: npm run verify:fences:${FAMILY}:setup`);
+  process.exit(2);
+}
+
+// ── the oracle: selector → { inputs, outputs } from ɵɵComponentDeclaration ────
+const dts = readFileSync(dtsPath, "utf8");
+const DECL = /ɵɵComponentDeclaration<\s*(\w+),\s*"([^"]+)",\s*[^,]+,\s*\{([\s\S]*?)\},\s*\{([\s\S]*?)\},\s*never/g;
+const bySelector = new Map();
+for (const m of dts.matchAll(DECL)) {
+  const inputs = new Set([...m[3].matchAll(/"([\w$]+)"\s*:/g)].map((x) => x[1]));
+  // outputs are  "prop": "publicAlias"  — the ALIAS is what a template binds
+  const outputs = new Set([...m[4].matchAll(/"([\w$]+)"\s*:\s*"([\w$]+)"/g)].map((x) => x[2]));
+  bySelector.set(m[2], { cls: m[1], inputs, outputs });
+}
+if (bySelector.size === 0) { console.error("parsed 0 component declarations — the .d.ts shape changed; fix DECL"); process.exit(2); }
+
+// ── collect ```html fences from this family's skills ──────────────────────────
+const SKILLS_DIR = join(ROOT, "skills");
+const files = [];
+const walk = (d) => {
+  for (const e of readdirSync(d, { withFileTypes: true })) {
+    const p = join(d, e.name);
+    if (e.isDirectory()) walk(p);
+    else if (e.name.endsWith(".md")) files.push(p);
+  }
+};
+for (const d of readdirSync(SKILLS_DIR, { withFileTypes: true })) {
+  if (d.isDirectory() && fam.skillDir.test(d.name)) walk(join(SKILLS_DIR, d.name));
+}
+
+// Angular syntax that is NOT a component binding — structural directives, refs,
+// two-way sugar, animations, and plain HTML attributes.
+const SKIP_ATTR = /^(\*|#|@|\[\(|class$|style$|id$|hidden$|title$|role$|aria-|data-|ng)/;
+
+let unknownSelector = 0, unknownBinding = 0, checkedEls = 0, checkedBindings = 0;
+const problems = [];
+
+for (const f of files) {
+  const src = readFileSync(f, "utf8");
+  for (const fence of src.matchAll(/```html\n([\s\S]*?)```/g)) {
+    for (const el of fence[1].matchAll(/<(cometchat-[a-z0-9-]+)([^>]*)>/g)) {
+      const [, selector, attrsRaw] = el;
+      const decl = bySelector.get(selector);
+      checkedEls++;
+      if (!decl) {
+        unknownSelector++;
+        problems.push(`${f.replace(ROOT + "/", "")}: <${selector}> is not a component in the installed kit`);
+        continue;
+      }
+      for (const a of attrsRaw.matchAll(/(\[?\(?[\w$.-]+\)?\]?)\s*=\s*"/g)) {
+        const raw = a[1];
+        if (SKIP_ATTR.test(raw)) continue;
+        const isOut = raw.startsWith("(") && raw.endsWith(")");
+        const isIn = raw.startsWith("[") && raw.endsWith("]");
+        if (!isOut && !isIn) continue;             // plain static attribute
+        const name = raw.slice(1, -1);
+        checkedBindings++;
+        const ok = isOut ? decl.outputs.has(name) : decl.inputs.has(name);
+        if (!ok) {
+          unknownBinding++;
+          const kind = isOut ? "output" : "input";
+          const near = [...(isOut ? decl.outputs : decl.inputs)]
+            .filter((n) => n.toLowerCase().includes(name.toLowerCase().replace(/^cc/, "").slice(0, 5)))
+            .slice(0, 4);
+          problems.push(
+            `${f.replace(ROOT + "/", "")}: <${selector}> has no ${kind} "${name}"` +
+            (near.length ? `  — did you mean: ${near.join(", ")}?` : "")
+          );
+        }
+      }
+    }
+  }
+}
+
+console.log(`verify-template-bindings [${FAMILY}]: ${bySelector.size} component declaration(s) · ${files.length} skill file(s) · ${checkedEls} element(s) · ${checkedBindings} binding(s) checked`);
+if (problems.length === 0) {
+  console.log(`\n✅ Tier-2b: every <cometchat-*> selector exists and every [input]/(output) is declared by that component.`);
+  process.exit(0);
+}
+console.log(`\n❌ ${problems.length} template-binding problem(s) — these fail SILENTLY at runtime in Angular:`);
+for (const p of problems) console.log(`  ${p}`);
+process.exit(1);

package/test-suite/typecheck/angular-v5/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "cometchat-skills-typecheck-angular-v5",
+  "private": true,
+  "description": "Tier-2 fence type-check sandbox — pins the Angular v5 UI Kit + JS SDK v4 so skill code fences compile against the real published API in CI. Angular is pinned to 21: the kit's peer range is >=17.0.0 <22.0.0, so 22 hard-fails ERESOLVE. Keep these pins in sync with peers.yaml (angular) and cometchat-angular-app/package.json.",
+  "version": "1.0.0",
+  "dependencies": {
+    "@cometchat/chat-uikit-angular": "^5.1.0",
+    "@cometchat/chat-sdk-javascript": "^4.1.13",
+    "@cometchat/cards-angular": "^1.0.0",
+    "@cometchat/calls-sdk-javascript": "^5.0.3",
+    "@angular/core": "^21.0.0",
+    "@angular/common": "^21.0.0",
+    "@angular/platform-browser": "^21.0.0",
+    "dompurify": "^3.0.0",
+    "rxjs": "^7.8.0",
+    "zone.js": "^0.15.0"
+  },
+  "devDependencies": {
+    "typescript": "~5.9.2"
+  }
+}

package/test-suite/typecheck/angular-v5/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "//": "Mirrors the Angular CLI 21 strict template the skills target. experimentalDecorators + useDefineForClassFields:false are required for @Component/@Input to type-check. noUnusedLocals/Parameters are OFF on purpose: fences are illustrative fragments, so unused-symbol noise (TS6133) would mask real kit-API drift.",
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2023", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true,
+    "useDefineForClassFields": false,
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "resolveJsonModule": true,
+    "verbatimModuleSyntax": false,
+    "noUnusedLocals": false,
+    "noUnusedParameters": false
+  },
+  "include": ["src"]
+}

package/test-suite/typecheck/flutter-v6/analysis_options.yaml

@@ -0,0 +1,25 @@
+# Mirrors a default `flutter create` app's analysis setup, with fragment-noise rules
+# OFF on purpose: fences are ILLUSTRATIVE snippets, so unused-import/local and style
+# lints would mask real kit-API drift. Only ERROR-severity diagnostics (the analyzer's
+# resolution/type errors) are what the Tier-2 gate reads — see typecheck-fences-dart.mjs.
+# The strict unused-import check is enforced on FULL emits by the reviewer, not fragments.
+include: package:flutter_lints/flutter.yaml
+
+analyzer:
+  errors:
+    unused_import: ignore
+    unused_local_variable: ignore
+    unused_element: ignore
+    unused_field: ignore
+    depend_on_referenced_packages: ignore
+    avoid_print: ignore
+    prefer_const_constructors: ignore
+    prefer_const_literals_to_create_immutables: ignore
+    use_build_context_synchronously: ignore
+    dead_code: ignore
+
+linter:
+  rules:
+    prefer_const_constructors: false
+    prefer_const_declarations: false
+    avoid_print: false

package/test-suite/typecheck/flutter-v6/pubspec.yaml

@@ -0,0 +1,21 @@
+name: cometchat_skills_typecheck_flutter_v6
+description: >
+  Tier-2 fence analyze sandbox — pins the Flutter UI Kit v6 + Chat SDK v5 + Calls SDK v5
+  so skill code fences analyze against the real published API in CI. Keep these pins in
+  sync with peers.yaml (flutter-v6) and test-suite/catalogs/flutter-v6.json (kitVersion).
+publish_to: none
+version: 1.0.0
+
+environment:
+  sdk: ">=3.10.1 <4.0.0"
+  flutter: ">=3.19.0"
+
+dependencies:
+  flutter:
+    sdk: flutter
+  cometchat_chat_uikit: ^6.1.0
+  cometchat_sdk: ^5.0.6
+  cometchat_calls_sdk: ^5.0.4
+
+dev_dependencies:
+  flutter_lints: ^6.0.0

package/test-suite/typecheck/web-v7/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "cometchat-skills-typecheck-web-v7",
+  "private": true,
+  "description": "Tier-2 fence type-check sandbox — pins the React v7 UI Kit + JS SDK v4 so skill code fences compile against the real published API in CI. Keep these pins in sync with peers.yaml (web-v7) and cometchat-react-app/package.json.",
+  "version": "1.0.0",
+  "dependencies": {
+    "@cometchat/chat-uikit-react": "^7.1.0",
+    "@cometchat/chat-sdk-javascript": "^4.1.13",
+    "@cometchat/calls-sdk-javascript": "^5.0.3",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8"
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3",
+    "typescript": "~6.0.2"
+  }
+}