@upgraide/ui-notes-cli 0.1.2 → 0.1.3

package/formatters/ai-context.ts

@@ -0,0 +1,236 @@
+import type { ResolvedNote, FileMatch } from '../resolvers/file-resolver.js';
+
+interface Note {
+  id: string;
+  type: string;
+  body: string;
+  url: string;
+  component: string | null;
+  selector: string | null;
+  tag: string | null;
+  text_content: string | null;
+  created_at: string;
+}
+
+interface FormatOptions {
+  format: 'markdown' | 'xml' | 'json';
+  componentFilter?: string;
+  projectName: string;
+  resolvedNotes?: Map<string, ResolvedNote>;
+}
+
+export function formatNotesForAI(notes: Note[], opts: FormatOptions): string {
+  // Filter by component if specified
+  let filtered = notes;
+  if (opts.componentFilter) {
+    filtered = notes.filter(n =>
+      n.component?.toLowerCase().includes(opts.componentFilter!.toLowerCase())
+    );
+  }
+
+  // Group by component
+  const grouped = new Map<string, Note[]>();
+  for (const note of filtered) {
+    const key = note.component || '_unresolved';
+    if (!grouped.has(key)) grouped.set(key, []);
+    grouped.get(key)!.push(note);
+  }
+
+  const date = new Date().toISOString().split('T')[0];
+
+  if (opts.format === 'xml') {
+    return formatAsXML(grouped, filtered.length, opts.projectName, date, opts.resolvedNotes);
+  }
+  if (opts.format === 'json') {
+    return formatAsJSON(grouped, filtered.length, opts.projectName, date, opts.resolvedNotes);
+  }
+  return formatAsMarkdown(grouped, filtered.length, opts.projectName, date, opts.resolvedNotes);
+}
+
+function formatFileMatch(file: FileMatch): string {
+  const loc = file.lineNumber ? `${file.filePath}:${file.lineNumber}` : file.filePath;
+  return `\`${loc}\` (${file.confidence} confidence, matched on ${file.matchedOn})`;
+}
+
+function formatAsMarkdown(
+  grouped: Map<string, Note[]>,
+  total: number,
+  projectName: string,
+  date: string,
+  resolvedNotes?: Map<string, ResolvedNote>,
+): string {
+  const lines: string[] = [];
+
+  lines.push(`# UI Notes: ${projectName}`);
+
+  if (total === 0) {
+    lines.push('> No open notes.');
+    return lines.join('\n') + '\n';
+  }
+
+  const resolveInfo = resolvedNotes ? ' | File resolution: enabled' : '';
+  lines.push(`> ${total} open note${total === 1 ? '' : 's'} as of ${date}${resolveInfo}`);
+  lines.push('');
+
+  for (const [component, notes] of grouped) {
+    if (component === '_unresolved') {
+      lines.push(`## _Unresolved (${notes.length} note${notes.length === 1 ? '' : 's'})`);
+    } else {
+      lines.push(`## Component: ${component} (${notes.length} note${notes.length === 1 ? '' : 's'})`);
+    }
+    lines.push('');
+
+    for (const note of notes) {
+      const typeLabel = (note.type || 'note').toUpperCase();
+      const firstLine = note.body?.split('\n')[0] || '(no body)';
+      lines.push(`### [${typeLabel}] ${firstLine}`);
+
+      // File resolution output
+      if (resolvedNotes) {
+        const resolved = resolvedNotes.get(note.id);
+        if (resolved && resolved.files.length > 0) {
+          for (const file of resolved.files) {
+            lines.push(`- **File**: ${formatFileMatch(file)}`);
+          }
+        } else {
+          lines.push(`- **File**: _(no match found)_`);
+        }
+      }
+
+      if (note.selector) {
+        lines.push(`- **Selector**: \`${note.selector}\``);
+      }
+      if (note.url) {
+        lines.push(`- **URL**: ${note.url}`);
+      }
+      if (note.tag || note.text_content) {
+        const parts: string[] = [];
+        if (note.tag) parts.push(`<${note.tag}>`);
+        if (note.text_content) parts.push(`"${note.text_content}"`);
+        lines.push(`- **Element**: ${parts.join(' ')}`);
+      }
+      if (note.created_at) {
+        const reported = note.created_at.split('T')[0];
+        lines.push(`- **Reported**: ${reported}`);
+      }
+
+      // Full body as blockquote
+      if (note.body) {
+        const bodyLines = note.body.split('\n').map(l => `> ${l}`);
+        lines.push(bodyLines.join('\n'));
+      }
+
+      lines.push('');
+    }
+  }
+
+  return lines.join('\n');
+}
+
+function formatAsXML(
+  grouped: Map<string, Note[]>,
+  total: number,
+  projectName: string,
+  date: string,
+  resolvedNotes?: Map<string, ResolvedNote>,
+): string {
+  const lines: string[] = [];
+
+  lines.push(`<ui-notes project="${escapeXml(projectName)}" count="${total}" date="${date}">`);
+
+  for (const [component, notes] of grouped) {
+    const compName = component === '_unresolved' ? '_unresolved' : component;
+    lines.push(`  <component name="${escapeXml(compName)}" count="${notes.length}">`);
+
+    for (const note of notes) {
+      const typeAttr = (note.type || 'note').toLowerCase();
+      lines.push(`    <note type="${escapeXml(typeAttr)}" id="${escapeXml(note.id)}">`);
+      lines.push(`      <body>${escapeXml(note.body || '')}</body>`);
+
+      // File resolution output
+      if (resolvedNotes) {
+        const resolved = resolvedNotes.get(note.id);
+        if (resolved && resolved.files.length > 0) {
+          lines.push(`      <resolved-files>`);
+          for (const file of resolved.files) {
+            const loc = file.lineNumber ? `${file.filePath}:${file.lineNumber}` : file.filePath;
+            lines.push(`        <file path="${escapeXml(loc)}" confidence="${file.confidence}" match-type="${file.matchType}" matched-on="${escapeXml(file.matchedOn)}" />`);
+          }
+          lines.push(`      </resolved-files>`);
+        }
+      }
+
+      if (note.selector) {
+        lines.push(`      <selector>${escapeXml(note.selector)}</selector>`);
+      }
+      if (note.url) {
+        lines.push(`      <url>${escapeXml(note.url)}</url>`);
+      }
+      if (note.tag) {
+        lines.push(`      <tag>${escapeXml(note.tag)}</tag>`);
+      }
+      if (note.text_content) {
+        lines.push(`      <text-content>${escapeXml(note.text_content)}</text-content>`);
+      }
+      if (note.created_at) {
+        lines.push(`      <created>${note.created_at.split('T')[0]}</created>`);
+      }
+      lines.push(`    </note>`);
+    }
+
+    lines.push(`  </component>`);
+  }
+
+  lines.push(`</ui-notes>`);
+  return lines.join('\n') + '\n';
+}
+
+function formatAsJSON(
+  grouped: Map<string, Note[]>,
+  total: number,
+  projectName: string,
+  date: string,
+  resolvedNotes?: Map<string, ResolvedNote>,
+): string {
+  const components: Record<string, unknown[]> = {};
+
+  for (const [component, notes] of grouped) {
+    components[component] = notes.map(n => {
+      const entry: Record<string, unknown> = {
+        id: n.id,
+        type: n.type,
+        body: n.body,
+        selector: n.selector || undefined,
+        url: n.url || undefined,
+        tag: n.tag || undefined,
+        text_content: n.text_content || undefined,
+        created_at: n.created_at,
+      };
+
+      if (resolvedNotes) {
+        const resolved = resolvedNotes.get(n.id);
+        entry.resolved_files = resolved?.files || [];
+      }
+
+      return entry;
+    });
+  }
+
+  const output = {
+    project: projectName,
+    total,
+    date,
+    components,
+  };
+
+  return JSON.stringify(output, null, 2) + '\n';
+}
+
+function escapeXml(str: string): string {
+  return str
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&apos;');
+}

package/index.ts

@@ -1,4 +1,4 @@
-#!/usr/bin/env bun
+#!/usr/bin/env bun
 
 import { getConfig } from './config.js';
 import { configShow, configSet } from './commands/config.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@upgraide/ui-notes-cli",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "CLI for UI Notes - pull and manage UI feedback notes",
   "license": "MIT",
   "keywords": ["cli", "ui", "notes", "feedback", "ui-notes"],
@@ -9,7 +9,9 @@
   },
   "files": [
     "*.ts",
-    "commands/*.ts"
+    "commands/*.ts",
+    "formatters/*.ts",
+    "resolvers/*.ts"
   ],
   "engines": {
     "bun": ">=1.0.0"

package/resolvers/file-resolver.ts

@@ -0,0 +1,477 @@
+/**
+ * File resolver: maps UI note metadata (component names, CSS selectors) to source files.
+ *
+ * Resolution strategies in priority order:
+ *  1. data-testid / data-component attribute match  (very high confidence)
+ *  2. Component name -> filename match              (high confidence)
+ *  3. Component name -> export/function declaration  (high confidence)
+ *  4. Semantic class name search (non-Tailwind)      (high confidence)
+ *  5. ID attribute search                            (high confidence)
+ */
+
+import { readdir, readFile, stat } from 'fs/promises';
+import { join, relative, basename, extname } from 'path';
+import { existsSync } from 'fs';
+import {
+  parseSelector,
+  filterSemanticClasses,
+  type SelectorTokens,
+} from './selector-parser.js';
+
+export interface FileMatch {
+  filePath: string;
+  lineNumber: number | null;
+  matchType: 'data-attr' | 'component' | 'selector' | 'id' | 'tag';
+  confidence: 'high' | 'medium' | 'low';
+  matchedOn: string;
+}
+
+export interface ResolvedNote {
+  noteId: string;
+  files: FileMatch[];
+}
+
+export interface ResolveOptions {
+  rootDir: string;
+  extensions?: string[];
+  excludeDirs?: string[];
+}
+
+const DEFAULT_EXTENSIONS = ['.tsx', '.jsx', '.ts', '.js', '.vue', '.svelte'];
+const DEFAULT_EXCLUDE_DIRS = [
+  'node_modules',
+  '.next',
+  'dist',
+  'build',
+  '.git',
+  'coverage',
+];
+
+interface NoteForResolution {
+  id: string;
+  component?: string | null;
+  selector?: string | null;
+  tag?: string | null;
+}
+
+/**
+ * Check whether the project uses Tailwind CSS by looking for config files.
+ */
+function detectTailwind(rootDir: string): boolean {
+  const configFiles = [
+    'tailwind.config.js',
+    'tailwind.config.ts',
+    'tailwind.config.mjs',
+    'tailwind.config.cjs',
+  ];
+  return configFiles.some((f) => existsSync(join(rootDir, f)));
+}
+
+/**
+ * Recursively collect source files under rootDir, respecting extension and exclusion filters.
+ */
+async function collectSourceFiles(
+  dir: string,
+  extensions: string[],
+  excludeDirs: string[],
+): Promise<string[]> {
+  const results: string[] = [];
+
+  let entries;
+  try {
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch {
+    return results;
+  }
+
+  for (const entry of entries) {
+    const fullPath = join(dir, entry.name);
+
+    if (entry.isDirectory()) {
+      if (!excludeDirs.includes(entry.name)) {
+        const sub = await collectSourceFiles(fullPath, extensions, excludeDirs);
+        results.push(...sub);
+      }
+    } else if (entry.isFile()) {
+      const ext = extname(entry.name);
+      if (extensions.includes(ext)) {
+        results.push(fullPath);
+      }
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Escape special regex characters in a string.
+ */
+function escapeRegex(str: string): string {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Find the 1-based line number of the first occurrence of `pattern` in `content`.
+ */
+function findLineNumber(content: string, pattern: RegExp): number | null {
+  const match = content.match(pattern);
+  if (!match || match.index === undefined) return null;
+  return content.slice(0, match.index).split('\n').length;
+}
+
+// ── Strategy: data-attribute match ───────────────────────────────────────
+
+async function resolveByDataAttribute(
+  attrs: SelectorTokens['dataAttributes'],
+  sourceFiles: string[],
+  rootDir: string,
+  fileContents: Map<string, string>,
+): Promise<FileMatch[]> {
+  const matches: FileMatch[] = [];
+
+  for (const attr of attrs) {
+    if (!attr.value) continue;
+    const searchPattern = new RegExp(
+      `${escapeRegex(attr.name)}\\s*=\\s*["']${escapeRegex(attr.value)}["']`,
+    );
+
+    for (const filePath of sourceFiles) {
+      const content = await getFileContent(filePath, fileContents);
+      if (!content) continue;
+
+      const lineNumber = findLineNumber(content, searchPattern);
+      if (lineNumber !== null) {
+        matches.push({
+          filePath: relative(rootDir, filePath),
+          lineNumber,
+          matchType: 'data-attr',
+          confidence: 'high',
+          matchedOn: `${attr.name}="${attr.value}"`,
+        });
+      }
+    }
+
+    // data-testid is very high confidence; return immediately if found
+    if (matches.length > 0) return matches;
+  }
+
+  return matches;
+}
+
+// ── Strategy: Component name -> filename match ───────────────────────────
+
+async function resolveByComponentFilename(
+  componentName: string,
+  sourceFiles: string[],
+  rootDir: string,
+  fileContents: Map<string, string>,
+): Promise<FileMatch[]> {
+  const matches: FileMatch[] = [];
+  const normalizedName = componentName.toLowerCase();
+
+  for (const filePath of sourceFiles) {
+    const fileName = basename(filePath)
+      .replace(/\.[^.]+$/, '')
+      .toLowerCase();
+
+    if (fileName === normalizedName) {
+      // Try to find the exact component declaration for a line number
+      const content = await getFileContent(filePath, fileContents);
+      let lineNumber: number | null = null;
+      if (content) {
+        lineNumber = findComponentDeclarationLine(content, componentName);
+      }
+
+      matches.push({
+        filePath: relative(rootDir, filePath),
+        lineNumber,
+        matchType: 'component',
+        confidence: 'high',
+        matchedOn: componentName,
+      });
+    }
+  }
+
+  return matches;
+}
+
+// ── Strategy: Component name -> export/function search ───────────────────
+
+async function resolveByComponentDeclaration(
+  componentName: string,
+  sourceFiles: string[],
+  rootDir: string,
+  fileContents: Map<string, string>,
+): Promise<FileMatch[]> {
+  const matches: FileMatch[] = [];
+  const escaped = escapeRegex(componentName);
+
+  const patterns = [
+    new RegExp(`(?:export\\s+)?function\\s+${escaped}\\b`),
+    new RegExp(`(?:export\\s+)?const\\s+${escaped}\\s*[=:]`),
+    new RegExp(`(?:export\\s+)?class\\s+${escaped}\\b`),
+    new RegExp(`export\\s+default\\s+${escaped}\\b`),
+    new RegExp(`displayName\\s*=\\s*['"]${escaped}['"]`),
+  ];
+
+  for (const filePath of sourceFiles) {
+    const content = await getFileContent(filePath, fileContents);
+    if (!content) continue;
+
+    for (const pattern of patterns) {
+      const lineNumber = findLineNumber(content, pattern);
+      if (lineNumber !== null) {
+        matches.push({
+          filePath: relative(rootDir, filePath),
+          lineNumber,
+          matchType: 'component',
+          confidence: 'high',
+          matchedOn: componentName,
+        });
+        break; // One match per file is enough
+      }
+    }
+  }
+
+  return matches;
+}
+
+// ── Strategy: Semantic class name search ─────────────────────────────────
+
+async function resolveBySemanticClasses(
+  classNames: string[],
+  sourceFiles: string[],
+  rootDir: string,
+  fileContents: Map<string, string>,
+): Promise<FileMatch[]> {
+  const matches: FileMatch[] = [];
+
+  for (const cls of classNames) {
+    const pattern = new RegExp(escapeRegex(cls));
+
+    for (const filePath of sourceFiles) {
+      const content = await getFileContent(filePath, fileContents);
+      if (!content) continue;
+
+      const lineNumber = findLineNumber(content, pattern);
+      if (lineNumber !== null) {
+        matches.push({
+          filePath: relative(rootDir, filePath),
+          lineNumber,
+          matchType: 'selector',
+          confidence: 'high',
+          matchedOn: `.${cls}`,
+        });
+      }
+    }
+  }
+
+  return matches;
+}
+
+// ── Strategy: ID attribute search ────────────────────────────────────────
+
+async function resolveByIds(
+  ids: string[],
+  sourceFiles: string[],
+  rootDir: string,
+  fileContents: Map<string, string>,
+): Promise<FileMatch[]> {
+  const matches: FileMatch[] = [];
+
+  for (const id of ids) {
+    const pattern = new RegExp(`id\\s*=\\s*["']${escapeRegex(id)}["']`);
+
+    for (const filePath of sourceFiles) {
+      const content = await getFileContent(filePath, fileContents);
+      if (!content) continue;
+
+      const lineNumber = findLineNumber(content, pattern);
+      if (lineNumber !== null) {
+        matches.push({
+          filePath: relative(rootDir, filePath),
+          lineNumber,
+          matchType: 'id',
+          confidence: 'high',
+          matchedOn: `#${id}`,
+        });
+      }
+    }
+  }
+
+  return matches;
+}
+
+// ── Helpers ──────────────────────────────────────────────────────────────
+
+/**
+ * Read file content with caching within a single invocation.
+ */
+async function getFileContent(
+  filePath: string,
+  cache: Map<string, string>,
+): Promise<string | null> {
+  if (cache.has(filePath)) return cache.get(filePath)!;
+  try {
+    const content = await readFile(filePath, 'utf-8');
+    cache.set(filePath, content);
+    return content;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Find the line number of a component function/const declaration.
+ */
+function findComponentDeclarationLine(
+  content: string,
+  componentName: string,
+): number | null {
+  const escaped = escapeRegex(componentName);
+  const patterns = [
+    new RegExp(`(?:export\\s+)?function\\s+${escaped}\\b`),
+    new RegExp(`(?:export\\s+)?const\\s+${escaped}\\s*[=:]`),
+    new RegExp(`(?:export\\s+)?class\\s+${escaped}\\b`),
+    new RegExp(`export\\s+default\\s+${escaped}\\b`),
+  ];
+  for (const p of patterns) {
+    const line = findLineNumber(content, p);
+    if (line !== null) return line;
+  }
+  return null;
+}
+
+/**
+ * Deduplicate file matches, keeping the highest-confidence match per file.
+ */
+function deduplicateMatches(matches: FileMatch[]): FileMatch[] {
+  const byFile = new Map<string, FileMatch>();
+  const confidenceRank = { high: 3, medium: 2, low: 1 };
+
+  for (const m of matches) {
+    const existing = byFile.get(m.filePath);
+    if (
+      !existing ||
+      confidenceRank[m.confidence] > confidenceRank[existing.confidence]
+    ) {
+      byFile.set(m.filePath, m);
+    }
+  }
+
+  return Array.from(byFile.values());
+}
+
+// ── Main entry point ─────────────────────────────────────────────────────
+
+/**
+ * Resolve a single note to source files.
+ */
+export async function resolveNoteToFiles(
+  note: NoteForResolution,
+  opts: ResolveOptions,
+): Promise<ResolvedNote> {
+  const extensions = opts.extensions || DEFAULT_EXTENSIONS;
+  const excludeDirs = opts.excludeDirs || DEFAULT_EXCLUDE_DIRS;
+  const rootDir = opts.rootDir;
+
+  const sourceFiles = await collectSourceFiles(rootDir, extensions, excludeDirs);
+  const fileContents = new Map<string, string>();
+  const hasTailwind = detectTailwind(rootDir);
+
+  if (sourceFiles.length === 0) {
+    console.error(
+      `Warning: No source files found in ${rootDir}. Check --root-dir or resolve.rootDir in config.`,
+    );
+    return { noteId: note.id, files: [] };
+  }
+
+  let allMatches: FileMatch[] = [];
+
+  // Parse selector tokens if we have a selector
+  let tokens: SelectorTokens | null = null;
+  if (note.selector) {
+    tokens = parseSelector(note.selector);
+  }
+
+  // Strategy 1: data-attribute match (very high confidence, short-circuits)
+  if (tokens && tokens.dataAttributes.length > 0) {
+    const dataMatches = await resolveByDataAttribute(
+      tokens.dataAttributes,
+      sourceFiles,
+      rootDir,
+      fileContents,
+    );
+    if (dataMatches.length > 0) {
+      return { noteId: note.id, files: deduplicateMatches(dataMatches) };
+    }
+  }
+
+  // Strategy 2: Component name -> filename match
+  if (note.component) {
+    const filenameMatches = await resolveByComponentFilename(
+      note.component,
+      sourceFiles,
+      rootDir,
+      fileContents,
+    );
+    allMatches.push(...filenameMatches);
+  }
+
+  // Strategy 3: Component name -> export/function search (only if no filename match)
+  if (note.component && allMatches.length === 0) {
+    const declMatches = await resolveByComponentDeclaration(
+      note.component,
+      sourceFiles,
+      rootDir,
+      fileContents,
+    );
+    allMatches.push(...declMatches);
+  }
+
+  // If we already have high-confidence component matches, return early
+  if (allMatches.length > 0) {
+    return { noteId: note.id, files: deduplicateMatches(allMatches) };
+  }
+
+  // Strategy 4: Semantic class name search
+  if (tokens && tokens.classNames.length > 0) {
+    const semanticClasses = filterSemanticClasses(tokens.classNames);
+    if (semanticClasses.length > 0) {
+      const classMatches = await resolveBySemanticClasses(
+        semanticClasses,
+        sourceFiles,
+        rootDir,
+        fileContents,
+      );
+      allMatches.push(...classMatches);
+    }
+  }
+
+  // Strategy 5: ID attribute search
+  if (tokens && tokens.ids.length > 0) {
+    const idMatches = await resolveByIds(
+      tokens.ids,
+      sourceFiles,
+      rootDir,
+      fileContents,
+    );
+    allMatches.push(...idMatches);
+  }
+
+  return { noteId: note.id, files: deduplicateMatches(allMatches) };
+}
+
+/**
+ * Resolve multiple notes in batch, sharing the file cache.
+ */
+export async function resolveNotesToFiles(
+  notes: NoteForResolution[],
+  opts: ResolveOptions,
+): Promise<ResolvedNote[]> {
+  const results: ResolvedNote[] = [];
+  for (const note of notes) {
+    results.push(await resolveNoteToFiles(note, opts));
+  }
+  return results;
+}

package/resolvers/selector-parser.ts

@@ -0,0 +1,80 @@
+/**
+ * CSS selector parser and Tailwind utility class filter.
+ * Extracts searchable tokens from CSS selectors captured by the UI Notes React package.
+ */
+
+export interface SelectorTokens {
+  classNames: string[];
+  ids: string[];
+  tags: string[];
+  dataAttributes: Array<{ name: string; value: string | null }>;
+}
+
+/**
+ * Regex matching common Tailwind CSS utility class prefixes.
+ * Classes matching this pattern carry no semantic meaning for file resolution.
+ */
+const TAILWIND_UTILITY_RE =
+  /^(flex|grid|block|inline|hidden|visible|static|fixed|absolute|relative|sticky|p[xytblr]?-|m[xytblr]?-|text-|bg-|border-|rounded|w-|h-|min-w-|max-w-|gap-|space-|font-|leading-|tracking-|shadow-|opacity-|z-|overflow-|cursor-|transition-|duration-|ease-|animate-|ring-|outline-|placeholder-|divide-|sr-only|not-sr-only|items-|justify-|self-|place-|order-|col-|row-|float-|clear-|object-|aspect-|container|prose|truncate|break-|whitespace-|decoration-|underline|overline|line-through|no-underline|uppercase|lowercase|capitalize|normal-case|italic|not-italic|tabular-nums|oldstyle-nums|lining-nums|proportional-nums|ordinal|slashed-zero|diagonal-fractions|stacked-fractions|list-|align-|table-|border-collapse|border-separate|origin-|scale-|rotate-|translate-|skew-|transform|accent-|appearance-|caret-|scroll-|snap-|touch-|select-|will-change-|fill-|stroke-)/;
+
+/**
+ * Check if a class name looks like a Tailwind utility class.
+ */
+export function isTailwindUtility(className: string): boolean {
+  return TAILWIND_UTILITY_RE.test(className);
+}
+
+/**
+ * Filter out Tailwind utility classes, returning only semantic class names.
+ */
+export function filterSemanticClasses(classNames: string[]): string[] {
+  return classNames.filter((c) => !isTailwindUtility(c));
+}
+
+/**
+ * Parse a CSS selector string into searchable tokens.
+ *
+ * Handles selectors like:
+ *   [data-testid="sidebar"]
+ *   #checkout-form
+ *   nav.sidebar-nav > ul.nav-list
+ *   div.flex > button.submit-btn
+ */
+export function parseSelector(selector: string): SelectorTokens {
+  const classNames: string[] = [];
+  const ids: string[] = [];
+  const tags: string[] = [];
+  const dataAttributes: Array<{ name: string; value: string | null }> = [];
+
+  // Extract data-* attribute selectors: [data-testid="value"] or [data-component="value"]
+  const dataMatches = selector.matchAll(
+    /\[(data-[\w-]+)(?:="([^"]*)")?\]/g,
+  );
+  for (const m of dataMatches) {
+    dataAttributes.push({ name: m[1], value: m[2] ?? null });
+  }
+
+  // Extract .class-names (handling CSS-escaped chars like \.)
+  const classMatches = selector.matchAll(/\.([a-zA-Z_][\w-]*)/g);
+  for (const m of classMatches) {
+    classNames.push(m[1]);
+  }
+
+  // Extract #ids
+  const idMatches = selector.matchAll(/#([a-zA-Z_][\w-]*)/g);
+  for (const m of idMatches) {
+    ids.push(m[1]);
+  }
+
+  // Extract tag names: bare words at start of selector or after combinators (>, +, ~, space)
+  const tagMatches = selector.matchAll(/(?:^|[\s>+~])([a-z][a-z0-9]*)\b/gi);
+  for (const m of tagMatches) {
+    const tag = m[1].toLowerCase();
+    // Exclude common non-tag tokens
+    if (tag !== 'data' && tag !== 'not') {
+      tags.push(tag);
+    }
+  }
+
+  return { classNames, ids, tags, dataAttributes };
+}