@1money/component-ui 0.0.23 → 0.0.25

package/scripts/mcp-server/tools/get-symbol.mjs

@@ -0,0 +1,232 @@
+/* eslint-disable no-undef */
+/* eslint-env node */
+/**
+ * Tool: get_symbol
+ *
+ * Resolves flat names (`ProFormItem`) AND dotted paths (`ProForm.Item`) and
+ * returns a rich record. See plan §3.3 and §4 for the exact resolution
+ * algorithm.
+ */
+
+const VALID_INCLUDES = ['props', 'examples', 'members', 'notes', 'related'];
+const DEFAULT_INCLUDE = ['props', 'members'];
+const LOCAL_PREFIX = '$local:';
+const EXAMPLES_LIMIT = 3;
+
+const ICONS_DOTTED = /^Icons\.[A-Z][A-Za-z0-9]*$/;
+const HOOK_PREFIX = /^use[A-Z]/;
+
+function validateInput(input) {
+  const args = input && typeof input === 'object' ? input : {};
+  if (typeof args.name !== 'string' || args.name.trim().length === 0) {
+    throw new Error('get_symbol: `name` must be a non-empty string');
+  }
+  let include;
+  if (args.include === undefined) {
+    include = DEFAULT_INCLUDE;
+  } else if (Array.isArray(args.include)) {
+    for (const entry of args.include) {
+      if (!VALID_INCLUDES.includes(entry)) {
+        throw new Error(
+          `get_symbol: invalid include entry '${entry}', expected one of ${VALID_INCLUDES.join(', ')}`
+        );
+      }
+    }
+    include = args.include;
+  } else {
+    throw new Error('get_symbol: `include` must be an array of strings when provided');
+  }
+  return { name: args.name.trim(), include };
+}
+
+/**
+ * Build a name -> symbol map and a reverse owner lookup that maps any flat
+ * member name back to its owner module (so we can populate namespaceAccess).
+ */
+function buildLookups(index) {
+  const byName = new Map();
+  const ownerLookup = new Map();
+  for (const sym of index.symbols) {
+    byName.set(sym.name, sym);
+  }
+  for (const sym of index.symbols) {
+    if (sym.kind === 'module' && sym.memberMap && typeof sym.memberMap === 'object') {
+      for (const [key, target] of Object.entries(sym.memberMap)) {
+        if (typeof target === 'string' && !target.startsWith(LOCAL_PREFIX)) {
+          if (!ownerLookup.has(target)) {
+            ownerLookup.set(target, { owner: sym.name, memberKey: key });
+          }
+        }
+      }
+    }
+  }
+  return { byName, ownerLookup };
+}
+
+function notExported(inputName, hint) {
+  return { kind: 'not_exported', name: inputName, inputName, hint };
+}
+
+function buildHintForMissing(name) {
+  if (ICONS_DOTTED.test(name)) {
+    return 'Icon names are string keys, not exported symbols. Use `<Icons name="chevronDown" />` (camelCase) and call `list_icons` to discover available names.';
+  }
+  if (HOOK_PREFIX.test(name)) {
+    return 'This hook may live in `@1money/hooks`, not `@1money/component-ui`. Check that package.';
+  }
+  return `No exported symbol named '${name}'. Use search_symbols to discover candidates.`;
+}
+
+function buildImports(sym, owner, ownerMemberKey) {
+  const imports = {
+    named: `import { ${sym.name} } from '@1money/component-ui';`,
+    css: "import '@1money/component-ui/index.css'; // global, covers all"
+  };
+  if (owner && ownerMemberKey) {
+    imports.namespaceAccess = `${owner}.${ownerMemberKey}`;
+  }
+  if (sym.subpathImport) {
+    imports.subpath = `import { ${sym.name} } from '${sym.subpathImport}';`;
+  }
+  return imports;
+}
+
+function buildMembers(sym) {
+  if (sym.kind !== 'module' || !sym.memberMap || typeof sym.memberMap !== 'object') {
+    return [];
+  }
+  return Object.entries(sym.memberMap).map(([key, target]) => {
+    const isLocal = typeof target === 'string' && target.startsWith(LOCAL_PREFIX);
+    const flatName = isLocal ? target.slice(LOCAL_PREFIX.length) : target;
+    return { key, flatName, isLocal };
+  });
+}
+
+function buildCanonicalUsage(sym) {
+  if (typeof sym.canonicalUsage === 'string' && sym.canonicalUsage.length > 0) {
+    return sym.canonicalUsage;
+  }
+  if (sym.kind === 'module') {
+    return `// ${sym.name} is a namespace; see members via get_symbol('${sym.name}').members`;
+  }
+  return `import { ${sym.name} } from '@1money/component-ui';`;
+}
+
+function hydrateExamples(sym, examplesIndex) {
+  if (!examplesIndex || typeof examplesIndex.examples !== 'object') return [];
+  const refs = Array.isArray(sym.examples) ? sym.examples : [];
+  const hydrated = [];
+  for (const ref of refs) {
+    if (!ref || typeof ref.hash !== 'string') continue;
+    const body = examplesIndex.examples[ref.hash];
+    if (!body) continue;
+    hydrated.push({
+      title: body.title,
+      code: body.code,
+      source: body.source,
+      compilable: body.compilable,
+    });
+    if (hydrated.length >= EXAMPLES_LIMIT) break;
+  }
+  return hydrated;
+}
+
+function buildRecord(sym, inputName, { ownerLookup, include, examplesIndex }) {
+  const ownerRef = ownerLookup.get(sym.name);
+  const imports = buildImports(
+    sym,
+    ownerRef ? ownerRef.owner : null,
+    ownerRef ? ownerRef.memberKey : null
+  );
+
+  const record = {
+    name: sym.name,
+    inputName,
+    kind: sym.kind,
+    category: sym.category ?? null,
+    summary: sym.summary ?? '',
+    imports,
+    extends: Array.isArray(sym.extends) ? sym.extends : [],
+    members: [],
+    canonicalUsage: buildCanonicalUsage(sym),
+    relatedTypes: [],
+    relatedSymbols: Array.isArray(sym.relatedSymbols) ? sym.relatedSymbols : [],
+    examples: []
+  };
+
+  if (include.includes('props')) {
+    record.props = Array.isArray(sym.props) ? sym.props : [];
+  }
+  if (include.includes('members')) {
+    record.members = buildMembers(sym);
+  }
+  if (include.includes('notes')) {
+    record.notes = sym.notes ?? [];
+  }
+  if (include.includes('related')) {
+    // already included as relatedSymbols; include relatedTypes passthrough
+    record.relatedTypes = Array.isArray(sym.relatedTypes) ? sym.relatedTypes : [];
+  }
+  if (include.includes('examples')) {
+    record.examples = hydrateExamples(sym, examplesIndex);
+  }
+
+  return record;
+}
+
+/**
+ * Resolve a dotted-path lookup.  Returns either the resolved symbol record
+ * or a not_exported object per plan §4.
+ */
+function resolveDotted(inputName, byName) {
+  const dotIdx = inputName.indexOf('.');
+  const owner = inputName.slice(0, dotIdx);
+  const member = inputName.slice(dotIdx + 1);
+  const ownerSym = byName.get(owner);
+  if (ownerSym && ownerSym.memberMap && typeof ownerSym.memberMap === 'object') {
+    const target = ownerSym.memberMap[member];
+    if (target) {
+      if (typeof target === 'string' && target.startsWith(LOCAL_PREFIX)) {
+        return {
+          kind: 'not_exported',
+          name: inputName,
+          inputName,
+          hint: `This is an internal member of ${owner}, not a separately-exported symbol.`
+        };
+      }
+      const flat = byName.get(target);
+      if (flat) {
+        return { __sym: flat };
+      }
+    }
+  }
+  return null;
+}
+
+export default function getSymbol(input, ctx) {
+  const { name, include } = validateInput(input);
+  const { index, examplesIndex } = ctx;
+  const { byName, ownerLookup } = buildLookups(index);
+  const recordCtx = { ownerLookup, include, examplesIndex };
+
+  // Step 1: dotted-path attempt.
+  if (name.includes('.')) {
+    const dotted = resolveDotted(name, byName);
+    if (dotted && dotted.__sym) {
+      return buildRecord(dotted.__sym, name, recordCtx);
+    }
+    if (dotted && dotted.kind === 'not_exported') {
+      return dotted;
+    }
+    // fall through to fallback handlers.
+    return notExported(name, buildHintForMissing(name));
+  }
+
+  // Step 2: flat lookup.
+  const flat = byName.get(name);
+  if (flat) {
+    return buildRecord(flat, name, recordCtx);
+  }
+
+  return notExported(name, buildHintForMissing(name));
+}

package/scripts/mcp-server/tools/get-token.mjs

@@ -0,0 +1,60 @@
+/* eslint-disable no-undef */
+/* eslint-env node */
+/**
+ * Tool: get_token
+ *
+ * Looks up design tokens by name, kind, or name prefix.  All filters
+ * combine with AND semantics when multiple are supplied.
+ */
+
+const VALID_KINDS = [
+  'color',
+  'spacing',
+  'radius',
+  'shadow',
+  'sizing',
+  'opacity',
+  'typography',
+  'breakpoint'
+];
+
+function validateInput(input) {
+  const args = input && typeof input === 'object' ? input : {};
+  const name = typeof args.name === 'string' ? args.name.trim() : null;
+  const prefix = typeof args.prefix === 'string' ? args.prefix.trim() : null;
+  let kind = null;
+  if (args.kind !== undefined) {
+    if (typeof args.kind !== 'string' || !VALID_KINDS.includes(args.kind)) {
+      throw new Error(
+        `get_token: invalid kind '${args.kind}', expected one of ${VALID_KINDS.join(', ')}`
+      );
+    }
+    kind = args.kind;
+  }
+  return { name, prefix, kind };
+}
+
+export default function getToken(input, ctx) {
+  const { name, prefix, kind } = validateInput(input);
+  const { index } = ctx;
+
+  const tokens = Array.isArray(index.tokens) ? index.tokens : [];
+
+  let result = tokens;
+  if (name) {
+    result = result.filter(
+      t =>
+        t.name === name ||
+        t.cssVar === name ||
+        t.scss === name
+    );
+  }
+  if (kind) {
+    result = result.filter(t => t.kind === kind);
+  }
+  if (prefix) {
+    result = result.filter(t => typeof t.name === 'string' && t.name.startsWith(prefix));
+  }
+
+  return { tokens: result };
+}

package/scripts/mcp-server/tools/list-icons.mjs

@@ -0,0 +1,38 @@
+/* eslint-disable no-undef */
+/* eslint-env node */
+/**
+ * Tool: list_icons
+ *
+ * Returns available icon names (string keys) from the generated index.
+ */
+
+function validateInput(input) {
+  const args = input && typeof input === 'object' ? input : {};
+  const query = typeof args.query === 'string' ? args.query.trim() : '';
+  const limit =
+    typeof args.limit === 'number' && Number.isFinite(args.limit) && args.limit > 0
+      ? Math.floor(args.limit)
+      : null;
+  return { query, limit };
+}
+
+export default function listIcons(input, ctx) {
+  const { query, limit } = validateInput(input);
+  const { index } = ctx;
+
+  const source = Array.isArray(index.icons) ? index.icons : [];
+  let filtered = source;
+  if (query) {
+    const lower = query.toLowerCase();
+    filtered = source.filter(entry =>
+      typeof entry?.name === 'string' && entry.name.toLowerCase().includes(lower)
+    );
+  }
+
+  const total = filtered.length;
+  const icons = (limit != null ? filtered.slice(0, limit) : filtered).map(entry => ({
+    name: entry.name
+  }));
+
+  return { total, icons };
+}

package/scripts/mcp-server/tools/list-symbols.mjs

@@ -0,0 +1,46 @@
+/* eslint-disable no-undef */
+/* eslint-env node */
+/**
+ * Tool: list_symbols
+ *
+ * Lists top-level exports from the generated index. Namespace roots (ProForm,
+ * Icons, Input) are surfaced as `kind: 'module'`.
+ */
+
+const VALID_KINDS = ['component', 'module', 'hook', 'function', 'type', 'all'];
+
+function validateInput(input) {
+  const args = input && typeof input === 'object' ? input : {};
+  const kind = args.kind ?? 'all';
+  if (!VALID_KINDS.includes(kind)) {
+    throw new Error(
+      `list_symbols: invalid kind '${kind}', expected one of ${VALID_KINDS.join(', ')}`
+    );
+  }
+  const category = typeof args.category === 'string' ? args.category : undefined;
+  return { kind, category };
+}
+
+export default function listSymbols(input, ctx) {
+  const { kind, category } = validateInput(input);
+  const { index } = ctx;
+
+  const filtered = index.symbols.filter(sym => {
+    if (kind !== 'all' && sym.kind !== kind) return false;
+    if (category && sym.category !== category) return false;
+    return true;
+  });
+
+  const symbols = filtered.map(sym => ({
+    name: sym.name,
+    kind: sym.kind,
+    category: sym.category ?? null,
+    summary: sym.summary ?? '',
+    importPath: sym.importPath ?? null
+  }));
+
+  // Stable alphabetical sort for predictable output.
+  symbols.sort((a, b) => a.name.localeCompare(b.name));
+
+  return { symbols };
+}

package/scripts/mcp-server/tools/resolve-import.mjs

@@ -0,0 +1,125 @@
+/* eslint-disable no-undef */
+/* eslint-env node */
+/**
+ * Tool: resolve_import
+ *
+ * Resolves how to import a symbol (or namespace member).  Supports flat
+ * names (`Button`), namespace roots (`Icons`), and dotted-member paths
+ * (`ProForm.Item`).  `Icons.<Name>` is explicitly rejected because icon
+ * names are string keys, not exported symbols.
+ */
+
+const LOCAL_PREFIX = '$local:';
+const ICONS_DOTTED = /^Icons\.[A-Z][A-Za-z0-9]*$/;
+
+function validateInput(input) {
+  const args = input && typeof input === 'object' ? input : {};
+  if (typeof args.symbol !== 'string' || args.symbol.trim().length === 0) {
+    throw new Error('resolve_import: `symbol` must be a non-empty string');
+  }
+  return { symbol: args.symbol.trim() };
+}
+
+function buildLookups(index) {
+  const byName = new Map();
+  const ownerLookup = new Map();
+  for (const sym of index.symbols) byName.set(sym.name, sym);
+  for (const sym of index.symbols) {
+    if (sym.kind === 'module' && sym.memberMap) {
+      for (const [key, target] of Object.entries(sym.memberMap)) {
+        if (typeof target === 'string' && !target.startsWith(LOCAL_PREFIX)) {
+          if (!ownerLookup.has(target)) {
+            ownerLookup.set(target, { owner: sym.name, memberKey: key });
+          }
+        }
+      }
+    }
+  }
+  return { byName, ownerLookup };
+}
+
+function notFound(inputSymbol, hint) {
+  return { found: false, inputSymbol, hint };
+}
+
+function buildResponse(sym, inputSymbol, { ownerLookup, drift }) {
+  const owner = ownerLookup.get(sym.name);
+  const sources = [{ specifier: '@1money/component-ui', style: 'named', preferred: true }];
+  if (sym.subpathImport) {
+    sources.push({ specifier: sym.subpathImport, style: 'named', preferred: false });
+  }
+  const response = {
+    found: true,
+    name: sym.name,
+    inputSymbol,
+    sources,
+    css: '@1money/component-ui/index.css'
+  };
+
+  const notes = [];
+  if (owner) {
+    notes.push(`Also accessible via ${owner.owner}.${owner.memberKey} namespace.`);
+  }
+
+  // Drift note: if any drift entry's subpath maps to this symbol's subpathImport.
+  if (sym.subpathImport && drift && Array.isArray(drift.orphanSubpath)) {
+    for (const orphan of drift.orphanSubpath) {
+      const orphanSpecifier = `@1money/component-ui${orphan.subpath.replace(/^\./, '')}`;
+      if (orphanSpecifier === sym.subpathImport) {
+        notes.push(`Note: subpath '${sym.subpathImport}' appears in drift report (${orphan.reason}).`);
+      }
+    }
+  }
+
+  if (notes.length > 0) response.notes = notes.join(' ');
+  return response;
+}
+
+export default function resolveImport(input, ctx) {
+  const { symbol } = validateInput(input);
+  const { index, drift } = ctx;
+
+  // Icons.<Name> short-circuit.
+  if (ICONS_DOTTED.test(symbol)) {
+    return notFound(
+      symbol,
+      'Icons.<Name> is not a valid import; icons are string keys — use list_icons to discover names and `<Icons name="chevronDown" />` (camelCase).'
+    );
+  }
+
+  const { byName, ownerLookup } = buildLookups(index);
+
+  // Dotted path: owner.member
+  if (symbol.includes('.')) {
+    const dotIdx = symbol.indexOf('.');
+    const owner = symbol.slice(0, dotIdx);
+    const member = symbol.slice(dotIdx + 1);
+    const ownerSym = byName.get(owner);
+    if (ownerSym && ownerSym.memberMap) {
+      const target = ownerSym.memberMap[member];
+      if (target && !target.startsWith(LOCAL_PREFIX)) {
+        const flat = byName.get(target);
+        if (flat) return buildResponse(flat, symbol, { ownerLookup, drift });
+      }
+      if (target && target.startsWith(LOCAL_PREFIX)) {
+        return notFound(
+          symbol,
+          `${symbol} is an internal member of ${owner}; access it via the namespace only, e.g. \`import { ${owner} } from '@1money/component-ui'; <${owner}.${member} ... />\`.`
+        );
+      }
+    }
+    return notFound(
+      symbol,
+      `No exported symbol named '${symbol}'. Use search_symbols to discover candidates.`
+    );
+  }
+
+  // Flat lookup.
+  const flat = byName.get(symbol);
+  if (flat) return buildResponse(flat, symbol, { ownerLookup, drift });
+
+  return notFound(
+    symbol,
+    `No exported symbol named '${symbol}'. Use search_symbols to discover candidates.`
+  );
+}

package/scripts/mcp-server/tools/search-symbols.mjs

@@ -0,0 +1,79 @@
+/* eslint-disable no-undef */
+/* eslint-env node */
+/**
+ * Tool: search_symbols
+ *
+ * Fuzzy search over symbol records. Simple rule-based scorer.
+ */
+
+const DEFAULT_LIMIT = 5;
+
+function validateInput(input) {
+  const args = input && typeof input === 'object' ? input : {};
+  if (typeof args.query !== 'string' || args.query.trim().length === 0) {
+    throw new Error('search_symbols: `query` must be a non-empty string');
+  }
+  const limit =
+    typeof args.limit === 'number' && Number.isFinite(args.limit) && args.limit > 0
+      ? Math.floor(args.limit)
+      : DEFAULT_LIMIT;
+  return { query: args.query.trim(), limit };
+}
+
+function scoreSymbol(sym, q) {
+  const name = sym.name ?? '';
+  const lowerName = name.toLowerCase();
+  const lowerQ = q.toLowerCase();
+  const tags = Array.isArray(sym.searchTags) ? sym.searchTags : [];
+  const summary = (sym.summary ?? '').toLowerCase();
+  const propNames = Array.isArray(sym.props)
+    ? sym.props.map(p => (p && p.name ? String(p.name).toLowerCase() : ''))
+    : [];
+
+  // Name checks (most specific first).
+  if (lowerName === lowerQ) return { score: 100, matchedOn: 'name' };
+  if (lowerName.startsWith(lowerQ)) return { score: 80, matchedOn: 'name' };
+
+  // Tag exact.
+  if (tags.some(t => String(t).toLowerCase() === lowerQ)) {
+    return { score: 70, matchedOn: 'tag' };
+  }
+
+  // Name substring.
+  if (lowerName.includes(lowerQ)) return { score: 60, matchedOn: 'name' };
+
+  // Tag substring.
+  if (tags.some(t => String(t).toLowerCase().includes(lowerQ))) {
+    return { score: 50, matchedOn: 'tag' };
+  }
+
+  // Summary substring.
+  if (summary && summary.includes(lowerQ)) return { score: 30, matchedOn: 'summary' };
+
+  // Prop name match.
+  if (propNames.some(n => n === lowerQ || n.includes(lowerQ))) {
+    return { score: 20, matchedOn: 'prop' };
+  }
+
+  return null;
+}
+
+export default function searchSymbols(input, ctx) {
+  const { query, limit } = validateInput(input);
+  const { index } = ctx;
+
+  const hits = [];
+  for (const sym of index.symbols) {
+    const result = scoreSymbol(sym, query);
+    if (result) {
+      hits.push({ name: sym.name, score: result.score, matchedOn: result.matchedOn });
+    }
+  }
+
+  hits.sort((a, b) => {
+    if (b.score !== a.score) return b.score - a.score;
+    return a.name.localeCompare(b.name);
+  });
+
+  return { hits: hits.slice(0, limit) };
+}