Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
TypeScript agentaiai-agentsall-in-onecrmcrm-systememaillinearmcpmessagingnotesnotionofficerustslackslack-alternativestartupstartup-toolstypescriptworkspace
#!/usr/bin/env bun
/**
* Adoption audit for the `@ui` component library.
*
* Answers three questions across `apps/web/src`:
* 1. How much is each component actually used?
* 2. How often is a usage reskinned with utility classes? Layout classes are
* expected; classes that repaint or resize a component mean its own API
* did not cover the need, and that is the signal worth chasing.
* 3. How many primitives are still hand-rolled (`<button>`) instead of taken
* from the library (`<Button>`)?
*
* Parses with the TypeScript compiler rather than matching text: JSX is
* routinely formatted across several lines and imports get renamed
* (`Calendar as MiniCalendar`), both of which quietly wreck regex counts.
*
* Raw Tailwind palette classes are deliberately not checked here — the
* repository's FE-25 ast-grep convention is the enforcement point.
*
* bun run ui-audit # ranked report
* bun run ui-audit --sites Button # call sites for one component
* bun run ui-audit --explain # unclassified class-token frequencies
*/
import { readdirSync, readFileSync } from 'node:fs';
import { join, relative } from 'node:path';
import ts from 'typescript';
const SRC = 'src';
/** The library's own source: usage inside it is implementation, not adoption. */
const LIBRARY_DIR = join('src', 'components', 'ui');
/**
* Intrinsic elements the library either covers or ought to. `component: null`
* means no library primitive exists yet, which is a gap in the library rather
* than call sites ignoring it — the report says so instead of implying 100%
* non-adoption.
*/
const HAND_ROLLED: Record<string, string | null> = {
button: 'Button',
input: null,
textarea: null,
select: 'Select',
};
/**
* Utility prefixes that change a component's own appearance or control size.
* A component carrying these is being reskinned at the call site.
*/
const OVERRIDE = [
/^bg-/, /^text-/, /^font-/, /^border(-|$)/, /^rounded(-|$)/, /^ring(-|$)/,
/^shadow(-|$)/, /^divide-/, /^outline(-|$)/, /^opacity-/,
/^p[xytblr]?-/, /^gap(-|$)/, /^h-/, /^size-/, /^leading-/, /^tracking-/,
];
/**
* Utility prefixes that position a component within its parent. These are the
* call site's business, not the component's, so they are not misfit signals.
*/
const LAYOUT = [
/^(flex|grid|block|inline|inline-flex|inline-block|contents|hidden|table)$/,
/^(absolute|relative|fixed|sticky|static)$/,
/^(items|justify|self|place|content|order|col|row|basis|grow|shrink)(-|$)/,
/^m[xytblr]?-/, /^-m[xytblr]?-/, /^(top|left|right|bottom|inset)-/,
/^-?(top|left|right|bottom|inset)-/, /^z-/, /^w-/, /^(min|max)-[wh]-/,
/^(overflow|whitespace|break|truncate)(-|$)/, /^aspect-/,
/^(translate|rotate|scale|transform|transition|duration|ease|delay|animate)(-|$)/,
/^-?(translate|rotate|scale)-/,
/^(pointer-events|select|cursor|touch)-/, /^(group|peer)(-|$)/,
/^sr-only$/, /^(space)-[xy]-/, /^flex-/, /^(float|clear)-/, /^(list|align)-/,
];
type Site = { file: string; line: number; classes: string };
type ComponentStat = {
name: string;
files: Set<string>;
usages: number;
withClass: number;
withOverride: number;
overrideTokens: Map<string, number>;
sites: Site[];
};
type HandRolledStat = {
element: string;
suggested: string | null;
usages: number;
files: Set<string>;
sites: Site[];
};
const components = new Map<string, ComponentStat>();
const handRolled = new Map<string, HandRolledStat>();
const unclassified = new Map<string, number>();
let scannedFiles = 0;
function statFor(name: string): ComponentStat {
let stat = components.get(name);
if (!stat) {
stat = {
name,
files: new Set(),
usages: 0,
withClass: 0,
withOverride: 0,
overrideTokens: new Map(),
sites: [],
};
components.set(name, stat);
}
return stat;
}
/** Collects every `.tsx` worth scanning, skipping the library and test/doc files. */
function collectFiles(dir: string, out: string[] = []): string[] {
for (const entry of readdirSync(dir, { withFileTypes: true })) {
const path = join(dir, entry.name);
if (entry.isDirectory()) {
if (entry.name === 'node_modules') continue;
collectFiles(path, out);
} else if (
entry.name.endsWith('.tsx') &&
!entry.name.endsWith('.test.tsx') &&
!entry.name.endsWith('.spec.tsx') &&
!entry.name.endsWith('.docs.tsx') &&
!path.startsWith(LIBRARY_DIR)
) {
out.push(path);
}
}
return out;
}
/**
* Strips Tailwind variant prefixes to get the underlying utility, respecting
* brackets so an arbitrary variant like `[&:hover]:bg-x` is not split inside
* its own selector.
*/
export function baseUtility(token: string): string {
let depth = 0;
let lastColon = -1;
for (let i = 0; i < token.length; i++) {
const char = token[i]!;
if (char === '[' || char === '(') depth++;
else if (char === ']' || char === ')') depth--;
else if (char === ':' && depth === 0) lastColon = i;
}
return token.slice(lastColon + 1).replace(/^!/, '');
}
export type ClassKind = 'override' | 'layout' | 'unknown';
export function classifyToken(token: string): ClassKind {
const base = baseUtility(token);
if (!base) return 'unknown';
// Layout is checked first: `w-` and `max-h-` would otherwise be caught by
// the `h-` override rule.
if (LAYOUT.some((pattern) => pattern.test(base))) return 'layout';
if (OVERRIDE.some((pattern) => pattern.test(base))) return 'override';
return 'unknown';
}
/**
* The leftmost identifier of a tag name (`Panel.Body` -> `Panel`), used to
* resolve the import, plus the full path used as the reported name. Slots are
* reported separately because the same class means different things on each:
* `rounded-xl` on `Panel` is a reskin, `p-3` on `Panel.Body` is content
* spacing the caller owns.
*/
function tagNames(
tag: ts.JsxTagNameExpression
): { root: string; full: string } | undefined {
if (ts.isIdentifier(tag)) return { root: tag.text, full: tag.text };
if (ts.isPropertyAccessExpression(tag)) {
const parts: string[] = [];
let current: ts.Expression = tag;
while (ts.isPropertyAccessExpression(current)) {
parts.unshift(current.name.text);
current = current.expression;
}
if (!ts.isIdentifier(current)) return undefined;
parts.unshift(current.text);
return { root: current.text, full: parts.join('.') };
}
return undefined;
}
/** Every string literal reachable from a class attribute, so `cn('a', x && 'b')` is covered. */
function classStrings(attributes: ts.JsxAttributes): string[] {
const found: string[] = [];
for (const attribute of attributes.properties) {
if (!ts.isJsxAttribute(attribute)) continue;
const name = ts.isIdentifier(attribute.name)
? attribute.name.text
: attribute.name.getText();
if (name !== 'class' && name !== 'className') continue;
const initializer = attribute.initializer;
if (!initializer) continue;
if (ts.isStringLiteral(initializer)) {
found.push(initializer.text);
continue;
}
if (ts.isJsxExpression(initializer) && initializer.expression) {
const visit = (node: ts.Node) => {
if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) {
found.push(node.text);
} else if (ts.isTemplateExpression(node)) {
found.push(node.head.text);
for (const span of node.templateSpans) found.push(span.literal.text);
}
ts.forEachChild(node, visit);
};
visit(initializer.expression);
}
}
return found;
}
function scan(file: string) {
const text = readFileSync(file, 'utf8');
const source = ts.createSourceFile(
file,
text,
ts.ScriptTarget.Latest,
true,
ts.ScriptKind.TSX
);
scannedFiles++;
/** Local binding name -> canonical `@ui` export. */
const localToCanonical = new Map<string, string>();
const collectImports = (node: ts.Node) => {
if (
ts.isImportDeclaration(node) &&
ts.isStringLiteral(node.moduleSpecifier)
) {
const module = node.moduleSpecifier.text;
if (module === '@ui' || module.startsWith('@ui/components/')) {
const bindings = node.importClause?.namedBindings;
if (bindings && ts.isNamedImports(bindings)) {
for (const element of bindings.elements) {
const canonical = (element.propertyName ?? element.name).text;
localToCanonical.set(element.name.text, canonical);
}
}
}
}
ts.forEachChild(node, collectImports);
};
collectImports(source);
// `cn` and friends are utilities, not components.
for (const helper of ['cn', 'buttonClasses', 'badgeClasses', 'badgeTriggerClasses']) {
localToCanonical.delete(helper);
}
const lineOf = (node: ts.Node) =>
source.getLineAndCharacterOfPosition(node.getStart(source)).line + 1;
const record = (
tag: { root: string; full: string },
attributes: ts.JsxAttributes,
node: ts.Node
) => {
const line = lineOf(node);
if (tag.root === tag.root.toLowerCase() && tag.root in HAND_ROLLED) {
let stat = handRolled.get(tag.root);
if (!stat) {
stat = {
element: tag.root,
suggested: HAND_ROLLED[tag.root] ?? null,
usages: 0,
files: new Set(),
sites: [],
};
handRolled.set(tag.root, stat);
}
stat.usages++;
stat.files.add(file);
stat.sites.push({ file, line, classes: classStrings(attributes).join(' ') });
return;
}
const canonical = localToCanonical.get(tag.root);
if (!canonical) return;
// Report under the slot actually used, with the import's canonical name as
// the root so a renamed import still lands on the right component.
const reported =
tag.full === tag.root
? canonical
: `${canonical}.${tag.full.split('.').slice(1).join('.')}`;
const stat = statFor(reported);
stat.usages++;
stat.files.add(file);
const classes = classStrings(attributes).join(' ').trim();
if (!classes) return;
stat.withClass++;
const tokens = classes.split(/\s+/).filter(Boolean);
const overrides: string[] = [];
for (const token of tokens) {
const kind = classifyToken(token);
if (kind === 'override') overrides.push(baseUtility(token));
else if (kind === 'unknown') {
unclassified.set(
baseUtility(token),
(unclassified.get(baseUtility(token)) ?? 0) + 1
);
}
}
if (overrides.length > 0) {
stat.withOverride++;
stat.sites.push({ file, line, classes });
for (const token of overrides) {
stat.overrideTokens.set(token, (stat.overrideTokens.get(token) ?? 0) + 1);
}
}
};
const visit = (node: ts.Node) => {
if (ts.isJsxOpeningElement(node) || ts.isJsxSelfClosingElement(node)) {
const tag = tagNames(node.tagName);
if (tag) record(tag, node.attributes, node);
}
ts.forEachChild(node, visit);
};
visit(source);
}
// --- report -----------------------------------------------------------------
/** Plain text throughout: the report is meant to be piped to a file, diffed,
* and pasted into a PR, so no ANSI escapes anywhere. */
const pad = (value: string | number, width: number) =>
String(value).padEnd(width);
const padStart = (value: string | number, width: number) =>
String(value).padStart(width);
const RULE = '-'.repeat(78);
/** Inline meter. The percentage is printed beside it, so the bar is a scanning
* aid rather than the only reading of the number. */
function meter(rate: number, width = 10): string {
const filled = Math.min(width, Math.round(rate * width));
return '#'.repeat(filled) + '.'.repeat(width - filled);
}
function heading(text: string): string {
return `\n${text}\n${RULE}`;
}
function percent(rate: number): string {
return `${Math.round(rate * 100)}%`;
}
if (import.meta.main) {
const args = process.argv.slice(2);
const explain = args.includes('--explain');
const sitesIndex = args.indexOf('--sites');
const sitesFor = sitesIndex >= 0 ? args[sitesIndex + 1] : undefined;
for (const file of collectFiles(SRC)) scan(file);
const ranked = [...components.values()].sort((a, b) => b.usages - a.usages);
const rateOf = (stat: ComponentStat) =>
stat.usages === 0 ? 0 : stat.withOverride / stat.usages;
// --sites turns the report into the call-site list for one component, which
// is what you actually want open while fixing them.
if (sitesFor) {
const stat = components.get(sitesFor);
if (!stat) {
console.error(
`No usages recorded for "${sitesFor}". Run without --sites to see the list.`
);
process.exit(1);
}
console.log(
heading(`${sitesFor} - ${stat.sites.length} call sites overriding visuals`)
);
for (const site of stat.sites) {
console.log(`${relative(SRC, site.file)}:${site.line}`);
console.log(` ${site.classes}`);
}
console.log();
process.exit(0);
}
const totalUsages = ranked.reduce((sum, stat) => sum + stat.usages, 0);
const totalOverride = ranked.reduce((sum, stat) => sum + stat.withOverride, 0);
const overallRate = totalOverride / Math.max(totalUsages, 1);
console.log(heading('@ui adoption'));
console.log(`scanned ${scannedFiles} files under apps/web/${SRC}, library excluded`);
console.log(`usages ${totalUsages} across ${ranked.length} components and slots`);
console.log(
`restyled ${percent(overallRate)} (${totalOverride} usages carry classes that repaint or resize the component)`
);
console.log(heading('By component'));
console.log(
pad('COMPONENT', 24) +
padStart('files', 6) +
padStart('uses', 6) +
' ' +
pad('RESTYLED', 12) +
padStart('', 5) +
' TOP OVERRIDES'
);
for (const stat of ranked) {
const rate = rateOf(stat);
const top = [...stat.overrideTokens.entries()]
.sort((a, b) => b[1] - a[1])
.slice(0, 3)
.map(([token, count]) => `${token} (${count})`)
.join(', ');
console.log(
pad(stat.name, 24) +
padStart(stat.files.size, 6) +
padStart(stat.usages, 6) +
' ' +
meter(rate) +
padStart(percent(rate), 6) +
' ' +
top
);
}
console.log(heading('Hand-rolled primitives'));
for (const stat of [...handRolled.values()].sort(
(a, b) => b.usages - a.usages
)) {
const label = pad(`<${stat.element}>`, 24) + padStart(stat.usages, 6);
if (!stat.suggested) {
console.log(
`${label} ${pad('', 10)}${padStart('', 6)} no library component exists yet, ${stat.files.size} files`
);
continue;
}
const libraryUses = components.get(stat.suggested)?.usages ?? 0;
const share = stat.usages / Math.max(stat.usages + libraryUses, 1);
console.log(
`${label} ${meter(share)}${padStart(percent(share), 6)}` +
` hand-rolled vs ${libraryUses} <${stat.suggested}>, ${stat.files.size} files`
);
}
if (explain) {
console.log(heading('Unclassified class tokens'));
console.log('Neither layout nor override - tune the rule lists with these.\n');
for (const [token, count] of [...unclassified.entries()]
.sort((a, b) => b[1] - a[1])
.slice(0, 40)) {
console.log(pad(token, 36) + padStart(count, 5));
}
}
console.log(
`\n${RULE}\n` +
'bun run ui-audit --sites <Component> list the call sites for one component\n' +
'bun run ui-audit --explain show unclassified class tokens\n'
);
}