@actioneer/ads-manifest 0.1.0

package/README.md

@@ -0,0 +1,39 @@
+# `@actioneer/ads-manifest` — the ADS catalog toolkit
+
+Pure, dependency-free cores that turn the Actioneer Design System's component
+barrel + tokens + design principles into the two machine-readable artifacts the
+distribution layer ships, and that answer queries against them:
+
+- **`ads-manifest.json`** — one entry per public barrel export (name, family,
+  kind, import path, variants/props, showcase URL) + semantic tokens + the
+  **design principles** (each flagged `enforcedByLint`).
+- **`llms.txt`** — the LLM-facing family → component index, token roles, and a
+  `## Design principles` section, plus the consumer-setup contract.
+
+Every core is a pure function (source strings in, data out) with **no filesystem
+access**, so the whole toolkit is unit-tested against fixture strings. The repo's
+`scripts/gen-ads-manifest.mjs` is the thin IO wrapper that reads files and writes
+the artifacts; the ADS MCP server (`@actioneer/ads-mcp`) is a thin adapter over
+the query core.
+
+## Exports
+
+| Subpath | What it is |
+|---|---|
+| `.` | Barrel re-exporting the build + query cores. |
+| `@actioneer/ads-manifest/build` | `buildManifest(...)`, `normalizePrinciples(...)`, `validateManifest(...)`. |
+| `@actioneer/ads-manifest/llms` | `renderLlmsTxt(manifest)` → the `llms.txt` string. |
+| `@actioneer/ads-manifest/query` | `searchComponents`, `getComponent`, `getToken`, `getPrinciples`. |
+| `@actioneer/ads-manifest/parse` | The low-level barrel/CVA/prop/token parsers. |
+
+## Determinism
+
+`buildManifest` is deterministic — no timestamps, stable sort — so regenerating
+produces no diff. `prebuild` / `build:lib` regenerate the artifacts and a
+malformed or incomplete manifest exits non-zero rather than shipping.
+
+## Development
+
+```bash
+npm run test:manifest   # from the ADS repo root — build + query + llms cores
+```

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@actioneer/ads-manifest",
+  "version": "0.1.0",
+  "description": "Pure ADS catalog toolkit — builds ads-manifest.json + llms.txt from the component barrel and answers manifest queries. Backs the generation script and the ADS MCP server.",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.mjs",
+    "./build": "./src/build.mjs",
+    "./llms": "./src/llms.mjs",
+    "./query": "./src/query.mjs",
+    "./parse": "./src/parse.mjs"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test"
+  },
+  "peerDependencies": {
+    "typescript": ">=5"
+  },
+  "peerDependenciesMeta": {
+    "typescript": { "optional": true }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/build.mjs

@@ -0,0 +1,379 @@
+// Pure manifest builder: (barrel + module sources + guidance + nav + tokens)
+// → a schema-valid `ads-manifest.json` object. No filesystem access — the IO
+// wrapper (scripts/gen-ads-manifest.mjs) reads files and hands sources in, so
+// this whole core runs under node:test against fixture strings.
+
+import { posix } from "node:path";
+import {
+  parseModuleExports,
+  parseCvaBlocks,
+  parsePropInterfaces,
+  parseSemanticTokens,
+  classifyValue,
+} from "./parse.mjs";
+
+const KINDS = ["component", "type", "hook", "util"];
+
+/** Section-comment text → clean family name ("Form controls", "Chat (…)" → "Chat"). */
+function normalizeFamily(section) {
+  return section
+    .replace(/\(.*$/, "") // drop parenthetical
+    .replace(/[—–-].*$/, "") // drop trailing dash-clause
+    .trim();
+}
+
+/** Kebab/scoped module id → its basename ("components/ai-elements/task" → "task"). */
+const baseOf = (id) => id.split("/").filter(Boolean).pop() ?? id;
+
+/** Resolve a relative spec against the importing module's id (POSIX, no ext). */
+function resolveSpec(fromId, spec) {
+  if (!spec.startsWith(".")) return null; // bare / alias — not walkable here
+  return posix.normalize(posix.join(posix.dirname(fromId), spec)).replace(/\/index$/, "/index");
+}
+
+/**
+ * Walk the main barrel and every module it re-exports, yielding one record per
+ * public name with provenance.
+ *
+ * @returns {Array<{name:string, kind:string, family:string, leaf:string}>}
+ */
+// Star walks into these leaf modules are skipped — mirrors gen-ads-meta's
+// `ui/` + `assistant-ui/` exclusions (the vendored chat internals). Explicit
+// NAMED re-exports (e.g. `export { TooltipProvider } from "./ui/tooltip"`) are
+// sanctioned public names and are kept.
+export const DEFAULT_EXCLUDE = [/(^|\/)assistant-ui(\/|$)/, /(^|\/)ui(\/|$)/];
+
+export function resolveExports({ barrelSource, barrelId, readModule, exclude = DEFAULT_EXCLUDE }) {
+  const records = [];
+  const seen = new Set();
+  const isExcluded = (id) => exclude.some((re) => re.test(id));
+
+  // Line-scan the barrel for section headers + top-level export statements. The
+  // barrel is hand-maintained, one export per line — the FIRST line of the
+  // comment group above a group of exports is its family (the barrel is the
+  // single source of inclusion + family). Continuation lines and the file title
+  // are ignored; a blank line starts a new comment group.
+  let section = "General";
+  let prevWasComment = false;
+  const lines = barrelSource.split("\n");
+  for (const raw of lines) {
+    const line = raw.trim();
+    if (line === "") {
+      prevWasComment = false;
+      continue;
+    }
+    const cm = line.match(/^\/\/\s*(.+)$/);
+    if (cm) {
+      // Only the first comment line of a group is the section header.
+      if (!prevWasComment && !/^ADS 1\.0/.test(cm[1])) section = cm[1];
+      prevWasComment = true;
+      continue;
+    }
+    prevWasComment = false;
+    const family = normalizeFamily(section);
+
+    // `export { A, type B, C as D } from "spec";`
+    const named = line.match(/^export\s+\{([^}]*)\}\s+from\s+["']([^"']+)["']/);
+    if (named) {
+      const spec = named[2];
+      const leaf = resolveSpec(barrelId, spec) ?? spec;
+      for (const piece of named[1].split(",").map((s) => s.trim()).filter(Boolean)) {
+        const isType = /^type\s+/.test(piece);
+        const nameTok = piece.replace(/^type\s+/, "").split(/\s+as\s+/);
+        const name = (nameTok[1] ?? nameTok[0]).trim();
+        const kind = isType ? "type" : classifyValue(name);
+        addRecord(records, seen, { name, kind, family, leaf });
+      }
+      continue;
+    }
+
+    // `export * from "spec";`
+    const star = line.match(/^export\s+\*\s+from\s+["']([^"']+)["']/);
+    if (star) {
+      const spec = star[1];
+      const modId = resolveSpec(barrelId, spec);
+      if (modId && !isExcluded(modId)) walkStar(modId, family, { readModule, records, seen, isExcluded });
+      continue;
+    }
+  }
+  return records;
+}
+
+/** Recursively collect the export names a `export * from module` brings in. */
+function walkStar(modId, family, ctx, guard = new Set()) {
+  if (guard.has(modId)) return;
+  guard.add(modId);
+  const source = readResolved(modId, ctx.readModule);
+  if (source == null) return;
+  // Parse with the module's REAL extension in the filename: parseModuleExports
+  // keys TSX vs TS off the filename, and a .tsx module parsed as plain TS
+  // misreads its JSX — leaking phantom exports (className, …) and dropping real
+  // ones. `source.id` is extensionless (it's also the leaf id), so append ext.
+  const { stars, reExports, locals } = parseModuleExports(source.text, `${source.id}${source.ext}`);
+
+  for (const l of locals) {
+    const kind = l.kind === "unknown" ? classifyValue(l.name) : l.kind;
+    addRecord(ctx.records, ctx.seen, { name: l.name, kind, family, leaf: source.id });
+  }
+  for (const r of reExports) {
+    const childId = resolveSpec(source.id, r.spec);
+    const leaf = childId ?? source.id;
+    const kind = r.isType ? "type" : classifyValue(r.name);
+    addRecord(ctx.records, ctx.seen, { name: r.name, kind, family, leaf });
+  }
+  for (const s of stars) {
+    const childId = resolveSpec(source.id, s);
+    if (childId && !ctx.isExcluded(childId)) walkStar(childId, family, ctx, guard);
+  }
+}
+
+function addRecord(records, seen, rec) {
+  if (seen.has(rec.name)) return; // first occurrence wins (stable across families)
+  seen.add(rec.name);
+  records.push(rec);
+}
+
+/**
+ * Read a module trying index resolution; returns {id, text, ext} with the
+ * resolved (extensionless) id and the source's real extension.
+ *
+ * `readModule` may return a bare string (ext defaults to ".tsx" — the dominant
+ * component case, and TSX safely parses plain TS) or `{text, ext}` when the IO
+ * layer knows the real extension (so a walked `.ts` module isn't parsed as TSX).
+ */
+function readResolved(modId, readModule) {
+  const direct = readModule(modId);
+  if (direct != null) return { id: modId, ...normalizeModule(direct) };
+  const idxId = posix.join(modId, "index");
+  const idx = readModule(idxId);
+  if (idx != null) return { id: idxId, ...normalizeModule(idx) };
+  return null;
+}
+
+function normalizeModule(read) {
+  return typeof read === "string" ? { text: read, ext: ".tsx" } : { text: read.text, ext: read.ext ?? ".tsx" };
+}
+
+/**
+ * Build the full manifest object from resolved records + enrichment sources.
+ * Deterministic: no timestamps, stable sort.
+ */
+export function buildManifest({
+  barrelSource,
+  barrelId = "components/index",
+  readModule,
+  guidance = {},
+  navPaths = [],
+  themeCss = "",
+  principles = [],
+  packageName = "@actioneer/ads",
+  showcaseBase = "https://ads.actioneer.dev",
+  version = "0.0.0",
+  exclude = DEFAULT_EXCLUDE,
+}) {
+  const records = resolveExports({ barrelSource, barrelId, readModule, exclude });
+
+  // basename → nav path ("/ai/answer" indexed under "answer"; "/button" under "button")
+  const navByBase = new Map();
+  for (const p of navPaths) navByBase.set(baseOf(p), p);
+
+  // Cache module sources so cva/prop parsing reads each leaf once.
+  const modCache = new Map();
+  const leafSource = (id) => {
+    if (modCache.has(id)) return modCache.get(id);
+    const r = readResolved(id, readModule);
+    modCache.set(id, r?.text ?? null);
+    return r?.text ?? null;
+  };
+
+  const families = [];
+  const familySeen = new Set();
+  const exportsOut = records.map((rec) => {
+    if (!familySeen.has(rec.family)) {
+      familySeen.add(rec.family);
+      families.push(rec.family);
+    }
+    const entry = {
+      name: rec.name,
+      family: rec.family,
+      kind: rec.kind,
+      importPath: packageName,
+      module: baseOf(rec.leaf),
+    };
+
+    const g = guidance[rec.name];
+    if (g?.whenToUse) entry.description = g.whenToUse;
+
+    if (rec.kind === "component") {
+      const navPath = navByBase.get(baseOf(rec.leaf));
+      entry.showcaseUrl = `${showcaseBase.replace(/\/$/, "")}/#${navPath ?? `/${baseOf(rec.leaf)}`}`;
+
+      const src = leafSource(rec.leaf);
+      if (src) {
+        const variants = variantVocabulary(rec.name, src, g);
+        if (Object.keys(variants).length) entry.variants = variants;
+        const propsByIface = parsePropInterfaces(src, `${baseOf(rec.leaf)}.tsx`);
+        const props = propsByIface[`${rec.name}Props`];
+        if (props && props.length) entry.props = props;
+      }
+    }
+    return entry;
+  });
+
+  // Stable order: family (barrel order) → kind order → name.
+  const famIdx = new Map(families.map((f, i) => [f, i]));
+  const kindIdx = new Map(KINDS.map((k, i) => [k, i]));
+  exportsOut.sort(
+    (a, b) =>
+      (famIdx.get(a.family) - famIdx.get(b.family)) ||
+      (kindIdx.get(a.kind) - kindIdx.get(b.kind)) ||
+      a.name.localeCompare(b.name)
+  );
+
+  const counts = { total: exportsOut.length };
+  for (const k of KINDS) counts[k] = exportsOut.filter((e) => e.kind === k).length;
+
+  const tokens = parseSemanticTokens(themeCss).map((t) => ({
+    name: t.name,
+    role: t.role,
+    utilities: utilitiesFor(t.role),
+    description: t.description || "",
+  }));
+
+  const manifest = {
+    name: packageName,
+    version,
+    importPath: packageName,
+    styleImport: `@import "${packageName}/styles.css";`,
+    families,
+    counts,
+    tokens,
+    exports: exportsOut,
+  };
+  const normalizedPrinciples = normalizePrinciples(principles);
+  if (normalizedPrinciples.length) manifest.principles = normalizedPrinciples;
+  return manifest;
+}
+
+/**
+ * Normalize the structured design-principles source into the manifest block:
+ * a stable-ordered array of {id, number, title, rule, do, dont, enforcedByLint,
+ * lintRules}. Deterministic (sorted by `number`); tolerant of extra fields.
+ */
+export function normalizePrinciples(principles = []) {
+  return [...principles]
+    .filter((p) => p && p.id && p.title)
+    .sort((a, b) => (a.number ?? 0) - (b.number ?? 0) || String(a.id).localeCompare(String(b.id)))
+    .map((p) => {
+      const out = {
+        id: p.id,
+        number: p.number ?? 0,
+        title: p.title,
+        rule: p.rule ?? "",
+        do: Array.isArray(p.do) ? p.do : [],
+        dont: Array.isArray(p.dont) ? p.dont : [],
+        enforcedByLint: Boolean(p.enforcedByLint),
+      };
+      if (Array.isArray(p.lintRules) && p.lintRules.length) out.lintRules = p.lintRules;
+      return out;
+    });
+}
+
+/** Merge CVA axis values with guidance per-value descriptions for one component. */
+function variantVocabulary(componentName, source, guidance) {
+  const cva = parseCvaBlocks(source);
+  // Prefer the block whose id matches the component (buttonVariants ↔ Button);
+  // else fold every axis found in the module (covers single-cva components).
+  const wanted = `${componentName[0].toLowerCase()}${componentName.slice(1)}variants`;
+  const match = cva.find((b) => b.id.toLowerCase() === wanted);
+  const blocks = match ? [match] : cva;
+
+  const out = {};
+  for (const b of blocks) {
+    for (const [axis, spec] of Object.entries(b.axes)) {
+      const options = {};
+      const descSource = axis === "size" ? guidance?.sizes : axis === "variant" ? guidance?.variants : undefined;
+      for (const v of spec.values) {
+        if (descSource?.[v]) options[v] = descSource[v];
+      }
+      out[axis] = { values: spec.values };
+      if (spec.default) out[axis].default = spec.default;
+      if (Object.keys(options).length) out[axis].options = options;
+    }
+  }
+  return out;
+}
+
+/** The Tailwind utilities a semantic color role produces. */
+function utilitiesFor(role) {
+  const u = [`bg-${role}`, `text-${role}`, `border-${role}`];
+  if (role === "ring") return [`ring-${role}`];
+  if (role.endsWith("-foreground")) return [`text-${role}`, `bg-${role}`];
+  return u;
+}
+
+// ── schema + validation ──────────────────────────────────────────────────────
+
+export const MANIFEST_SCHEMA = {
+  requiredTop: ["name", "version", "importPath", "families", "counts", "exports"],
+  entryRequired: ["name", "family", "kind", "importPath", "module"],
+  kinds: KINDS,
+};
+
+/**
+ * Validate a manifest object. Returns {ok, errors}. A malformed OR incomplete
+ * manifest (missing fields, bad kind, wrong importPath, count mismatch, empty
+ * catalog, duplicate names) yields errors so the build can fail on it.
+ *
+ * @param {object} manifest
+ * @param {{expectedNames?: string[], packageName?: string}} [opts]
+ */
+export function validateManifest(manifest, opts = {}) {
+  const errors = [];
+  const packageName = opts.packageName ?? "@actioneer/ads";
+
+  for (const key of MANIFEST_SCHEMA.requiredTop) {
+    if (manifest?.[key] == null) errors.push(`manifest missing top-level "${key}"`);
+  }
+  if (!Array.isArray(manifest?.exports) || manifest.exports.length === 0) {
+    errors.push("manifest.exports must be a non-empty array");
+    return { ok: false, errors };
+  }
+  if (manifest.importPath !== packageName) {
+    errors.push(`manifest.importPath must be "${packageName}", got "${manifest.importPath}"`);
+  }
+
+  const names = new Set();
+  for (const e of manifest.exports) {
+    const label = e?.name ? `export "${e.name}"` : "an export";
+    for (const key of MANIFEST_SCHEMA.entryRequired) {
+      if (e?.[key] == null || e[key] === "") errors.push(`${label} missing "${key}"`);
+    }
+    if (e?.kind && !MANIFEST_SCHEMA.kinds.includes(e.kind)) {
+      errors.push(`${label} has invalid kind "${e.kind}"`);
+    }
+    if (e?.importPath && e.importPath !== packageName) {
+      errors.push(`${label} importPath must be "${packageName}", got "${e.importPath}"`);
+    }
+    if (e?.kind === "component" && !e.showcaseUrl) {
+      errors.push(`component ${label} missing showcaseUrl`);
+    }
+    if (e?.name) {
+      if (names.has(e.name)) errors.push(`duplicate export name "${e.name}"`);
+      names.add(e.name);
+    }
+  }
+
+  if (manifest.counts?.total != null && manifest.counts.total !== manifest.exports.length) {
+    errors.push(`counts.total (${manifest.counts.total}) != exports.length (${manifest.exports.length})`);
+  }
+
+  // Completeness: every independently-enumerated barrel export must be present.
+  if (opts.expectedNames) {
+    for (const n of opts.expectedNames) {
+      if (!names.has(n)) errors.push(`manifest is incomplete — barrel export "${n}" is absent`);
+    }
+  }
+
+  return { ok: errors.length === 0, errors };
+}

package/src/index.mjs

@@ -0,0 +1,19 @@
+// @actioneer/ads-manifest — the pure ADS catalog toolkit.
+//
+// Three pure cores, no filesystem/transport dependency:
+//   • build   — (barrel + sources) → schema-valid ads-manifest object
+//   • llms    — manifest → llms.txt
+//   • query   — (manifest, query) → results  (the ADS MCP server adapts these)
+//
+// The IO wrappers live outside: scripts/gen-ads-manifest.mjs (generation) and
+// tools/ads-mcp (the MCP server).
+
+export { buildManifest, resolveExports, validateManifest, MANIFEST_SCHEMA } from "./build.mjs";
+export { renderLlmsTxt } from "./llms.mjs";
+export { searchComponents, getComponent, getToken } from "./query.mjs";
+export {
+  parseModuleExports,
+  parseCvaBlocks,
+  parsePropInterfaces,
+  parseSemanticTokens,
+} from "./parse.mjs";

package/src/llms.mjs

@@ -0,0 +1,118 @@
+// Pure llms.txt renderer: manifest → the LLM-facing index shadcn ships at
+// /llms.txt. A hierarchical family → component index (one `[Name] — desc` line
+// each) plus the consumer-setup contract. No IO — string in, string out.
+
+const REQUIRED_PROVIDERS = [
+  "`TooltipProvider` (from `@actioneer/ads`) — wrap the app; the vendored tooltip/attachment chips crash without an ancestor provider",
+  "`ToastProvider` (from `@actioneer/ads`) — required to render toasts",
+  '`<MotionConfig reducedMotion="user">` (from `motion/react`) — honor the OS reduced-motion setting',
+];
+
+/**
+ * @param {object} manifest  the ads-manifest object
+ * @returns {string} llms.txt content
+ */
+export function renderLlmsTxt(manifest) {
+  const pkg = manifest.name ?? "@actioneer/ads";
+  const lines = [];
+
+  lines.push(`# ${pkg}`);
+  lines.push("");
+  lines.push(
+    "> The Actioneer Design System (ADS 1.0) — a React 19 + Tailwind v4 component library. " +
+      "Build UI only from the exact named exports below; every value flows from a token. " +
+      "Never fork, alias, deep-import, or hand-roll a copy of a component — import the named export " +
+      `from \`${pkg}\`. \`@actioneer/ads-lint\` enforces this.`
+  );
+  lines.push("");
+
+  // Setup contract (the human twin lives in CONSUMING.md).
+  lines.push("## Setup");
+  lines.push("");
+  lines.push(`1. Install: \`npm install ${pkg}\` (or run \`npx ${pkg} init\`).`);
+  lines.push(
+    `2. In your global stylesheet, after \`@import "tailwindcss";\`, add \`${manifest.styleImport ?? `@import "${pkg}/styles.css";`}\` — ` +
+      "it carries the `@theme` tokens, the Aribau `@font-face`, and the `@source` that makes Tailwind scan ADS classes. " +
+      "Imported standalone (not into the tailwindcss graph) its `@theme` is inert and no tokens emit."
+  );
+  lines.push("3. Wrap the app root with the required providers:");
+  for (const p of REQUIRED_PROVIDERS) lines.push(`   - ${p}`);
+  lines.push(
+    `4. Import contract: \`import { Button } from "${pkg}";\` — the exact named export, never \`${pkg}/button\`, ` +
+      "never an alias, never a local copy."
+  );
+  lines.push("");
+
+  // Tokens pointer (roles, not literals).
+  if (Array.isArray(manifest.tokens) && manifest.tokens.length) {
+    lines.push("## Tokens");
+    lines.push("");
+    lines.push(
+      "Reference semantic roles, never raw color/dimension literals (ads-lint rejects literals). " +
+        "Each role produces `bg-/text-/border-<role>` utilities:"
+    );
+    for (const t of manifest.tokens) {
+      const desc = t.description ? ` — ${t.description}` : "";
+      lines.push(`- \`${t.role}\`${desc}`);
+    }
+    lines.push("");
+  }
+
+  // Design principles — the positive UX conventions the lint/manifest layer
+  // can't fully mechanize (a stray `border` utility isn't a literal). Each flags
+  // whether ads-lint auto-checks it, so the agent knows teach-vs-enforce.
+  if (Array.isArray(manifest.principles) && manifest.principles.length) {
+    lines.push("## Design principles");
+    lines.push("");
+    lines.push(
+      "The house rules for every ADS UI. `[lint]` = `@actioneer/ads-lint` auto-checks it " +
+        "(pair with `lint_snippet`); `[judgment]` = you must self-apply it — the linter can't."
+    );
+    lines.push("");
+    for (const p of manifest.principles) {
+      const tag = p.enforcedByLint
+        ? `[lint${p.lintRules?.length ? `: ${p.lintRules.join(", ")}` : ""}]`
+        : "[judgment]";
+      lines.push(`### ${p.number}. ${p.title} ${tag}`);
+      lines.push("");
+      if (p.rule) lines.push(p.rule);
+      lines.push("");
+      for (const d of p.do ?? []) lines.push(`- Do: ${d}`);
+      for (const d of p.dont ?? []) lines.push(`- Don't: ${d}`);
+      lines.push("");
+    }
+  }
+
+  // Component index, grouped by family in manifest order.
+  lines.push("## Components");
+  lines.push("");
+  const byFamily = new Map();
+  for (const f of manifest.families ?? []) byFamily.set(f, []);
+  for (const e of manifest.exports ?? []) {
+    if (!byFamily.has(e.family)) byFamily.set(e.family, []);
+    byFamily.get(e.family).push(e);
+  }
+
+  for (const [family, entries] of byFamily) {
+    if (!entries.length) continue;
+    lines.push(`### ${family}`);
+    lines.push("");
+    for (const e of entries) {
+      const desc = e.description ? ` — ${e.description}` : ` — ${kindLabel(e.kind)}`;
+      const variantHint = e.variants
+        ? ` (variants: ${Object.entries(e.variants)
+            .map(([axis, spec]) => `${axis}: ${spec.values.join("|")}`)
+            .join("; ")})`
+        : "";
+      const url = e.showcaseUrl ? ` [docs](${e.showcaseUrl})` : "";
+      lines.push(`- [${e.name}]${desc}${variantHint}${url}`);
+    }
+    lines.push("");
+  }
+
+  return lines.join("\n").replace(/\n{3,}/g, "\n\n").trimEnd() + "\n";
+}
+
+function kindLabel(kind) {
+  return { type: "TypeScript type", hook: "React hook", util: "utility" }[kind] ?? "component";
+}

package/src/parse.mjs

@@ -0,0 +1,281 @@
+// Pure source-parsing layer for the ADS manifest builder.
+//
+// Every function here is (source string → data) with no filesystem or transport
+// dependency, so the manifest builder and its node:test suite exercise the exact
+// same code. TypeScript's compiler API does the heavy lifting (exact handling of
+// multi-line specifiers, `export type`, aliasing); a small regex tier backs the
+// CVA / token extraction where an AST buys nothing.
+
+let ts = null;
+try {
+  ts = (await import("typescript")).default;
+} catch {
+  ts = null;
+}
+
+export const hasTypeScript = () => ts != null;
+
+const scriptKind = (filename) =>
+  filename.endsWith(".tsx") ? ts.ScriptKind.TSX : ts.ScriptKind.TS;
+
+/**
+ * Parse one module's top-level export surface.
+ *
+ * @returns {{
+ *   stars: string[],                                  // `export * from "spec"`
+ *   reExports: Array<{name:string, spec:string, isType:boolean}>, // `export { A as B } from "spec"`
+ *   locals: Array<{name:string, kind:"component"|"type"|"hook"|"util"}>, // local `export const/function/class/interface/type`
+ * }}
+ */
+export function parseModuleExports(source, filename = "mod.tsx") {
+  if (!ts) throw new Error("ads-manifest: the `typescript` package is required to parse exports");
+  const sf = ts.createSourceFile(filename, source, ts.ScriptTarget.Latest, true, scriptKind(filename));
+  const stars = [];
+  const reExports = [];
+  const locals = [];
+
+  sf.forEachChild((node) => {
+    // `export * from "..."` and `export { A, B as C } from "..."`
+    if (ts.isExportDeclaration(node) && node.moduleSpecifier && ts.isStringLiteral(node.moduleSpecifier)) {
+      const spec = node.moduleSpecifier.text;
+      if (!node.exportClause) {
+        stars.push(spec);
+      } else if (ts.isNamedExports(node.exportClause)) {
+        for (const el of node.exportClause.elements) {
+          reExports.push({
+            name: el.name.text, // the EXPORTED (aliased) name
+            spec,
+            isType: Boolean(node.isTypeOnly || el.isTypeOnly),
+          });
+        }
+      }
+      return;
+    }
+
+    // Local `export { A, type B }` (no module specifier) — treat as local names.
+    if (ts.isExportDeclaration(node) && !node.moduleSpecifier && node.exportClause && ts.isNamedExports(node.exportClause)) {
+      for (const el of node.exportClause.elements) {
+        locals.push({ name: el.name.text, kind: node.isTypeOnly || el.isTypeOnly ? "type" : "unknown" });
+      }
+      return;
+    }
+
+    const isExported =
+      ts.canHaveModifiers?.(node) &&
+      ts.getModifiers(node)?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword);
+    if (!isExported) return;
+
+    if (ts.isInterfaceDeclaration(node)) {
+      locals.push({ name: node.name.text, kind: "type" });
+    } else if (ts.isTypeAliasDeclaration(node)) {
+      locals.push({ name: node.name.text, kind: "type" });
+    } else if (ts.isFunctionDeclaration(node) && node.name) {
+      locals.push({ name: node.name.text, kind: classifyValue(node.name.text) });
+    } else if (ts.isClassDeclaration(node) && node.name) {
+      locals.push({ name: node.name.text, kind: classifyValue(node.name.text) });
+    } else if (ts.isVariableStatement(node)) {
+      for (const decl of node.declarationList.declarations) {
+        if (ts.isIdentifier(decl.name)) {
+          locals.push({ name: decl.name.text, kind: classifyValue(decl.name.text) });
+        }
+      }
+    }
+  });
+
+  return { stars, reExports, locals };
+}
+
+/**
+ * Classify a value export into component | hook | util by NAME (types are handled
+ * by the caller). Heuristics, in order:
+ *   • `use[A-Z]…`                    → hook
+ *   • lowercase first letter         → util   (cn, interactive, buttonVariants, answerTool)
+ *   • name ends Schema/Tool/Config/… → util   (AnswerSpecSchema, a zod object)
+ *   • otherwise Uppercase-first      → component (Button, TooltipProvider, AnswerRenderer)
+ */
+export function classifyValue(name) {
+  if (/^use[A-Z]/.test(name)) return "hook";
+  if (/^[a-z]/.test(name)) return "util";
+  if (/(Schema|Tool|Config|Options|Context|Adapter|Map|Variants|Registry|Store)$/.test(name)) return "util";
+  return "component";
+}
+
+const CVA_RE = /(?:export\s+)?const\s+([A-Za-z_$][\w$]*)\s*=\s*cva\s*\(/g;
+
+/**
+ * Extract every `const xVariants = cva(...)` block's variant axes.
+ * @returns {Array<{id:string, axes: Record<string, {values:string[], default?:string}>}>}
+ */
+export function parseCvaBlocks(source) {
+  const out = [];
+  for (const m of source.matchAll(CVA_RE)) {
+    const id = m[1];
+    const body = sliceBalanced(source, m.index + m[0].length - 1); // from the "("
+    if (body == null) continue;
+    out.push({ id, axes: parseVariantAxes(body) });
+  }
+  return out;
+}
+
+/** Given the text inside cva(...), pull the `variants: { axis: { value: … } }`
+ *  axis→values map and the `defaultVariants` selections. */
+function parseVariantAxes(cvaBody) {
+  const axes = {};
+  const vIdx = cvaBody.search(/\bvariants\s*:/);
+  if (vIdx !== -1) {
+    const braceStart = cvaBody.indexOf("{", vIdx);
+    const variantsBlock = sliceBalancedBrace(cvaBody, braceStart);
+    if (variantsBlock != null) {
+      // Each top-level `axisName: { … }` inside the variants block.
+      for (const am of variantsBlock.matchAll(/([A-Za-z_$][\w$]*)\s*:\s*\{/g)) {
+        const axisName = am[1];
+        const axisBlock = sliceBalancedBrace(variantsBlock, variantsBlock.indexOf("{", am.index + am[0].length - 1));
+        if (axisBlock == null) continue;
+        const values = [];
+        // Top-level keys of the axis block are the allowed values.
+        for (const km of axisBlock.matchAll(/(?:^|,|\{)\s*(?:"([^"]+)"|'([^']+)'|([A-Za-z_$][\w$-]*))\s*:/g)) {
+          const key = km[1] ?? km[2] ?? km[3];
+          if (key && !values.includes(key)) values.push(key);
+        }
+        if (values.length) axes[axisName] = { values };
+      }
+    }
+  }
+  // defaultVariants: { axis: "value" }
+  const dIdx = cvaBody.search(/\bdefaultVariants\s*:/);
+  if (dIdx !== -1) {
+    const dBlock = sliceBalancedBrace(cvaBody, cvaBody.indexOf("{", dIdx));
+    if (dBlock != null) {
+      for (const dm of dBlock.matchAll(/([A-Za-z_$][\w$]*)\s*:\s*(?:"([^"]+)"|'([^']+)')/g)) {
+        const axis = dm[1];
+        const value = dm[2] ?? dm[3];
+        if (axes[axis]) axes[axis].default = value;
+      }
+    }
+  }
+  return axes;
+}
+
+/**
+ * Names of the members of an `export interface <Name> …` (the prop vocabulary).
+ * Ignores index signatures. Includes extended-from names as a hint list.
+ * @returns {Record<string, string[]>} interfaceName → member names
+ */
+export function parsePropInterfaces(source, filename = "mod.tsx") {
+  if (!ts) return {};
+  const sf = ts.createSourceFile(filename, source, ts.ScriptTarget.Latest, true, scriptKind(filename));
+  const out = {};
+  sf.forEachChild((node) => {
+    if (!ts.isInterfaceDeclaration(node)) return;
+    const members = [];
+    for (const m of node.members) {
+      if ((ts.isPropertySignature(m) || ts.isMethodSignature(m)) && m.name && ts.isIdentifier(m.name)) {
+        members.push(m.name.text);
+      }
+    }
+    out[node.name.text] = members;
+  });
+  return out;
+}
+
+/**
+ * Semantic role tokens from a theme.css `@theme inline { --color-role: … }`
+ * block. The utility a role produces is its bare name (bg-/text-/border-<role>).
+ * The nearest preceding `/* comment *​/` seeds a human description.
+ * @returns {Array<{name:string, role:string, description:string}>}
+ */
+export function parseSemanticTokens(css) {
+  const out = [];
+  const inlineIdx = css.indexOf("@theme inline");
+  if (inlineIdx === -1) return out;
+  const block = sliceBalancedBrace(css, css.indexOf("{", inlineIdx));
+  if (block == null) return out;
+
+  const lines = block.split("\n");
+  let comment = ""; // the active group comment (a comment on its own line above a group)
+  for (const raw of lines) {
+    let line = raw.trim();
+    // A blank line ends a token group — the comment must not bleed onto the
+    // next, unrelated group (surface/muted have no comment of their own).
+    if (line === "") {
+      comment = "";
+      continue;
+    }
+    // The shadcn-compat aliases below this marker are internal (consumed only by
+    // the vendored chat components; ADS UI never uses them) — stop collecting so
+    // they never surface as consumer-facing tokens.
+    if (/shadcn-compat/i.test(line)) break;
+
+    // Pull a closed inline `/* … */` comment out of the line; whatever it
+    // documents (a trailing note or a whole-line group header) is captured.
+    let inline = "";
+    const cm = line.match(/\/\*\s*(.*?)\s*\*\//);
+    if (cm) {
+      inline = cm[1];
+      line = line.replace(cm[0], "").trim();
+    }
+
+    const tm = line.match(/^--color-([a-z0-9-]+)\s*:/i);
+    if (tm) {
+      const role = tm[1];
+      out.push({ name: `--color-${role}`, role, description: inline || comment });
+      continue;
+    }
+    // A comment that stands alone on its line becomes the group header.
+    if (cm && line === "") {
+      comment = inline;
+      continue;
+    }
+    if (line.startsWith("/*") || line.startsWith("*")) {
+      const t = line.replace(/^\/\*|^\*\/?|\*\/$/g, "").trim();
+      if (t) comment = t;
+    }
+  }
+  return out;
+}
+
+// ── balanced-delimiter helpers ───────────────────────────────────────────────
+
+/** From an opening "(" at `open`, return the substring inside the matching ")". */
+function sliceBalanced(src, open) {
+  return sliceBetween(src, open, "(", ")");
+}
+/** From an opening "{" at `open`, return the substring inside the matching "}". */
+function sliceBalancedBrace(src, open) {
+  return sliceBetween(src, open, "{", "}");
+}
+function sliceBetween(src, open, o, c) {
+  if (open < 0 || src[open] !== o) return null;
+  let depth = 0;
+  let inStr = null;
+  for (let i = open; i < src.length; i++) {
+    const ch = src[i];
+    const next = src[i + 1];
+    if (inStr) {
+      if (ch === inStr && src[i - 1] !== "\\") inStr = null;
+      continue;
+    }
+    // Skip comments so delimiters/quotes inside them (e.g. `shadcn's`, a `)` in
+    // prose) never throw off the brace/paren balance.
+    if (ch === "/" && next === "*") {
+      const end = src.indexOf("*/", i + 2);
+      i = end === -1 ? src.length : end + 1;
+      continue;
+    }
+    if (ch === "/" && next === "/") {
+      const nl = src.indexOf("\n", i + 2);
+      i = nl === -1 ? src.length : nl;
+      continue;
+    }
+    if (ch === '"' || ch === "'" || ch === "`") {
+      inStr = ch;
+      continue;
+    }
+    if (ch === o) depth++;
+    else if (ch === c) {
+      depth--;
+      if (depth === 0) return src.slice(open + 1, i);
+    }
+  }
+  return null;
+}

package/src/query.mjs

@@ -0,0 +1,138 @@
+// Pure manifest-query core: (manifest, query) → results. No MCP/transport
+// dependency, so it is directly unit-testable and the ADS MCP server (L3) is a
+// thin adapter over these functions.
+
+/** Lowercased haystack for one export entry. */
+function haystack(e) {
+  return [
+    e.name,
+    e.family,
+    e.kind,
+    e.description ?? "",
+    ...(e.props ?? []),
+    ...Object.entries(e.variants ?? {}).flatMap(([axis, s]) => [axis, ...(s.values ?? [])]),
+  ]
+    .join(" ")
+    .toLowerCase();
+}
+
+/**
+ * Search the catalog by name or purpose. Ranks exact/prefix name matches above
+ * substring, above description/keyword hits.
+ *
+ * @returns {Array<{name, family, kind, importPath, description?, score}>}
+ */
+export function searchComponents(manifest, query, { limit = 25, kind } = {}) {
+  const q = String(query ?? "").trim().toLowerCase();
+  const pool = (manifest.exports ?? []).filter((e) => !kind || e.kind === kind);
+  if (!q) {
+    return pool.slice(0, limit).map((e) => ({ ...summary(e), score: 0 }));
+  }
+  const scored = [];
+  for (const e of pool) {
+    const name = e.name.toLowerCase();
+    let score = 0;
+    if (name === q) score = 100;
+    else if (name.startsWith(q)) score = 80;
+    else if (name.includes(q)) score = 60;
+    else if (haystack(e).includes(q)) score = 30;
+    if (score > 0) scored.push({ ...summary(e), score });
+  }
+  scored.sort((a, b) => b.score - a.score || a.name.localeCompare(b.name));
+  return scored.slice(0, limit);
+}
+
+/**
+ * Full record for one export by EXACT name, with a copy-paste usage example.
+ * @returns {object|null}
+ */
+export function getComponent(manifest, name) {
+  const e = (manifest.exports ?? []).find((x) => x.name === name);
+  if (!e) return null;
+  return {
+    ...e,
+    import: `import { ${e.name} } from "${e.importPath}";`,
+    example: usageExample(e),
+  };
+}
+
+/**
+ * The semantic token(s) for a role. Accepts a role name ("brand"), a utility
+ * ("bg-brand"), or a fuzzy purpose ("primary text"); returns exact-role matches
+ * first, then fuzzy description hits.
+ * @returns {Array<{name, role, utilities, description}>}
+ */
+export function getToken(manifest, role) {
+  const tokens = manifest.tokens ?? [];
+  const q = String(role ?? "").trim().toLowerCase().replace(/^(bg|text|border|ring)-/, "");
+  if (!q) return tokens.slice();
+  const exact = tokens.filter((t) => t.role === q);
+  if (exact.length) return exact;
+  const prefix = tokens.filter((t) => t.role.startsWith(q));
+  if (prefix.length) return prefix;
+  const substr = tokens.filter(
+    (t) => t.role.includes(q) || (t.description ?? "").toLowerCase().includes(q)
+  );
+  if (substr.length) return substr;
+  // Multi-word purpose ("primary text", "muted body copy") — match any word
+  // against a role segment or the description.
+  const words = q.split(/[^a-z0-9]+/).filter(Boolean);
+  if (words.length > 1) {
+    return tokens.filter((t) => {
+      const roleWords = t.role.split("-");
+      const desc = (t.description ?? "").toLowerCase();
+      return words.some((w) => roleWords.includes(w) || desc.includes(w));
+    });
+  }
+  return [];
+}
+
+/**
+ * The design principles from the manifest, optionally filtered.
+ *
+ * @param {object} manifest
+ * @param {{ id?: string, enforcedByLint?: boolean }} [opts]
+ *   - id: return only the principle with this exact id (or its number as string).
+ *   - enforcedByLint: keep only lint-enforced (true) or judgment-call (false) rules.
+ * @returns {Array<object>}
+ */
+export function getPrinciples(manifest, { id, enforcedByLint } = {}) {
+  let out = manifest.principles ?? [];
+  if (id != null && String(id).trim() !== "") {
+    const q = String(id).trim().toLowerCase();
+    out = out.filter((p) => p.id.toLowerCase() === q || String(p.number) === q);
+  }
+  if (typeof enforcedByLint === "boolean") {
+    out = out.filter((p) => Boolean(p.enforcedByLint) === enforcedByLint);
+  }
+  return out;
+}
+
+function summary(e) {
+  return {
+    name: e.name,
+    family: e.family,
+    kind: e.kind,
+    importPath: e.importPath,
+    description: e.description,
+  };
+}
+
+/** A minimal, correct usage snippet. Components with a `variant` axis show the
+ *  default; everything else shows a bare element/import reference. */
+function usageExample(e) {
+  if (e.kind !== "component") {
+    return `import { ${e.name} } from "${e.importPath}";`;
+  }
+  const attrs = [];
+  const variant = e.variants?.variant;
+  const size = e.variants?.size;
+  if (variant) attrs.push(`variant="${variant.default ?? variant.values[0]}"`);
+  if (size) attrs.push(`size="${size.default ?? size.values[0]}"`);
+  const attrStr = attrs.length ? ` ${attrs.join(" ")}` : "";
+  return [
+    `import { ${e.name} } from "${e.importPath}";`,
+    "",
+    `<${e.name}${attrStr}>…</${e.name}>`,
+  ].join("\n");
+}