A local-first multi-agent app development platform, built on PenguinHarness
/**
* Guard: the form-control size scale (the UI package's `sizeTextClass`, in
* packages/ui/src/components/forms/input/input.tsx).
*
* - No control call site spells a font size in its own className (checked on known shapes too,
* so the check itself cannot go blind).
* - A Modal footer's Buttons, and the Buttons of a module that is only ever dialog content, sit
* on the fields' sm rung.
* - The control family spells a font size in its two records and nowhere else.
*
* A control's font size comes from its `size` prop and nowhere else. A `text-*` in a caller's
* `className` does not reliably override the component's own — both are single-class font-size
* utilities of equal specificity, so which one wins is decided by the order Tailwind generated
* the stylesheet in, not by the order of classes in the string. The built sheet emits `.text-base`
* before `.text-sm` before `.text-xs`, which means a caller asking for `text-sm` on an `sm` control
* silently loses, while a `text-[13px]` wins and freezes the control against the font-size tier the
* user chose in settings.
*
* That is invisible in review — the class is right there in the diff, and it simply does nothing —
* so it is checked rather than remembered. The check parses the real JSX with the TypeScript
* parser: whether a class sits on a control or on the `<div>` wrapping it is a question about which
* element owns the attribute, and a regex over the file cannot tell those apart.
*/
import { describe, expect, it } from "vitest";
import ts from "typescript";
import { expectEveryRootScanned, expectSingleHome, scanSources, sourceFile } from "./helpers/roots";
import type { SourceFile } from "./helpers/roots";
/** Web and the shared UI package: a control that moves keeps its call sites under this check. */
const SCAN = scanSources();
/** The controls that carry a `size` tier. A `className` on one of these may not set a font size. */
const CONTROLS = new Set([
"Input",
"Textarea",
"Select",
"OptionMenu",
"PasswordInput",
"FormPicker",
"SearchInput",
"Checkbox",
"Radio",
"RadioGroup",
]);
/**
* The control family's modules by file name, each at the repo-relative id of its home. A module
* that moves changes its own entry here and nothing else in this file.
*/
const FAMILY: Record<string, string> = {
"input.tsx": "packages/ui/src/components/forms/input/input.tsx",
"select.tsx": "packages/ui/src/components/forms/select/select.tsx",
"option-menu.tsx": "packages/ui/src/components/forms/select/option-menu.tsx",
"form-picker.tsx": "packages/ui/src/components/forms/select/form-picker.tsx",
"search-input.tsx": "packages/ui/src/components/forms/search-input/search-input.tsx",
};
/**
* Font-size utilities only. `text-gray-500`, `text-left` and `text-red-600` are colour and
* alignment and stay a caller's business; the bracket form is included because it is the one that
* silently opts a control out of the user's font-size setting.
*/
const FONT_SIZE_CLASS = /\btext-(?:xs|sm|base|lg|xl|\d?xl|\[[^\]]+])(?![\w-])/;
const tsxFiles = (): SourceFile[] => SCAN.files.filter((file) => file.name.endsWith(".tsx"));
const parsed = new Map<string, ts.SourceFile>();
/** A file's syntax tree, parsed once however many checks walk it. */
const parse = (file: SourceFile): ts.SourceFile => {
let tree = parsed.get(file.id);
if (tree === undefined) {
tree = ts.createSourceFile(
file.path,
file.text,
ts.ScriptTarget.Latest,
/* setParentNodes */ true,
ts.ScriptKind.TSX,
);
parsed.set(file.id, tree);
}
return tree;
};
const jsxTag = (node: ts.Node): string | null => {
if (ts.isJsxSelfClosingElement(node)) return node.tagName.getText();
if (ts.isJsxOpeningElement(node)) return node.tagName.getText();
return null;
};
/**
* Every literal chunk of a `className` value. A template literal's interpolations are skipped on
* purpose: `${sizeTextClass[size]}` is exactly the sanctioned way to reach a rung, so only the text
* typed around it is the caller's own spelling.
*/
function literalChunks(node: ts.Node, out: string[] = []): string[] {
if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) out.push(node.text);
else if (ts.isTemplateExpression(node)) {
out.push(node.head.text);
for (const span of node.templateSpans) out.push(span.literal.text);
} else {
// The callback must return nothing: forEachChild stops at the first truthy result, so
// returning the accumulator here would visit one child and quietly skip the rest.
ts.forEachChild(node, (child) => {
literalChunks(child, out);
});
}
return out;
}
/**
* `<Button>`s inside a `Modal`'s `footer={…}` that do not ask for the `sm` rung. `Modal` renders
* only the footer's wrapper — the buttons come from each caller as an opaque node — so there is no
* single place to set this and the rule has to be checked instead.
*
* The reach is what a parser can see without types: Buttons written inline in the `footer={…}`
* attribute. A footer handed over as a component (`footer={<Footer …/>}`) or built in a variable
* is on the same rule but out of this check's sight. A Button in a dialog *body* is covered by
* `findLooseDialogBodyButtons` instead, for the modules that are only ever dialog content.
*/
function findLooseFooterButtons(): string[] {
const loose: string[] = [];
for (const file of tsxFiles()) {
const source = parse(file);
const visit = (node: ts.Node): void => {
if (ts.isJsxAttribute(node) && node.name.getText() === "footer" && node.initializer) {
const walk = (inner: ts.Node): void => {
if (jsxTag(inner) === "Button") {
const attrs = (inner as ts.JsxSelfClosingElement | ts.JsxOpeningElement).attributes
.properties;
const size = attrs.find(
(attr) => ts.isJsxAttribute(attr) && attr.name.getText() === "size",
);
// The rung has to be `sm`, not merely stated: `size="md"` in a footer is the
// very drift this check exists for, and a missing prop takes Button's md default.
const rung =
size !== undefined && ts.isJsxAttribute(size) && size.initializer !== undefined
? size.initializer.getText()
: "<none>";
if (rung !== '"sm"') {
const line = source.getLineAndCharacterOfPosition(inner.getStart(source)).line + 1;
loose.push(`${file.id}:${line} ${rung}`);
}
}
ts.forEachChild(inner, walk);
};
walk(node.initializer);
}
ts.forEachChild(node, visit);
};
visit(source);
}
return loose.sort();
}
/**
* Modules that are only ever rendered as a dialog's body. The settings dialog is a `PagedDialog`,
* which is a `Modal`, and each of these is one of its pages — so every Button in them belongs with
* the fields beside it on the `sm` rung, exactly as a footer button does. A parser cannot infer
* that from the file alone (nothing in a section module says it renders in a dialog), so the fact
* is declared here. Add a module when it becomes settings-dialog content; drop one when it stops.
*/
const DIALOG_BODY_MODULES = new Set([
"features/settings/account-section.tsx",
"features/settings/agent-api-section.tsx",
"features/settings/profile-section.tsx",
"features/settings/appearance-section.tsx",
"features/settings/credits-section.tsx",
"features/settings/general-section.tsx",
"features/settings/proxy-section.tsx",
"features/settings/shortcut-recorder.tsx",
"features/settings/shortcuts-section.tsx",
"features/settings/trace-import-row.tsx",
"features/settings/uploads-section.tsx",
"features/admin/admin-users-page.tsx",
]);
/**
* Buttons in a dialog-body module that do not ask for `sm`, as "relative/path:line rung". `icon`
* passes: a square glyph button carries no text and so sits on no font rung.
*/
function findLooseDialogBodyButtons(): string[] {
const loose: string[] = [];
for (const file of tsxFiles()) {
if (file.root !== "web" || !DIALOG_BODY_MODULES.has(file.rel)) continue;
const source = parse(file);
const visit = (node: ts.Node): void => {
if (jsxTag(node) === "Button") {
const attrs = (node as ts.JsxSelfClosingElement | ts.JsxOpeningElement).attributes
.properties;
const size = attrs.find(
(attr) => ts.isJsxAttribute(attr) && attr.name.getText() === "size",
);
const rung =
size !== undefined && ts.isJsxAttribute(size) && size.initializer !== undefined
? size.initializer.getText()
: "<none>";
if (rung !== '"sm"' && rung !== '"icon"') {
const line = source.getLineAndCharacterOfPosition(node.getStart(source)).line + 1;
loose.push(`${file.rel}:${line} ${rung}`);
}
}
ts.forEachChild(node, visit);
};
visit(source);
}
return loose.sort();
}
/** Control call sites whose own `className` spells a font size, as "relative/path:line — class". */
function findSpelledSizes(): string[] {
const strays: string[] = [];
for (const file of tsxFiles()) {
const source = parse(file);
const visit = (node: ts.Node): void => {
const tag = jsxTag(node);
if (tag !== null && CONTROLS.has(tag)) {
const attrs = (node as ts.JsxSelfClosingElement | ts.JsxOpeningElement).attributes
.properties;
for (const attr of attrs) {
if (!ts.isJsxAttribute(attr) || attr.name.getText() !== "className") continue;
if (attr.initializer === undefined) continue;
for (const chunk of literalChunks(attr.initializer)) {
const hit = FONT_SIZE_CLASS.exec(chunk);
if (hit === null) continue;
const line = source.getLineAndCharacterOfPosition(node.getStart(source)).line + 1;
strays.push(`${file.id}:${line} <${tag}> ${hit[0]}`);
}
}
}
ts.forEachChild(node, visit);
};
visit(source);
}
return strays.sort();
}
describe("control font size", () => {
it("scans every source root, and finds the control family and its dialog bodies", () => {
expectEveryRootScanned(SCAN);
for (const id of Object.values(FAMILY)) expectSingleHome(SCAN, id);
// A listed module that was renamed or moved would silently drop out of the dialog-body rule.
for (const rel of DIALOG_BODY_MODULES) sourceFile(SCAN, `packages/web/src/${rel}`);
});
it("is never spelled on a call site's className", () => {
expect(
findSpelledSizes(),
"A control's font size comes from its `size` prop (sm for a form field, base for a " +
"standalone page like login). A text-* class beside it either does nothing or freezes " +
"the control against the user's font-size setting — see the UI package's forms/input/input.tsx.",
).toEqual([]);
});
it("actually reads the control's own attribute — the check is exercised on known shapes", () => {
// Guards the guard: without this, the assertion above would pass just as happily on a
// `literalChunks` that had stopped seeing template text.
const found = (jsx: string): string[] => {
const source = ts.createSourceFile(
"t.tsx",
`const x = ${jsx};`,
ts.ScriptTarget.Latest,
true,
ts.ScriptKind.TSX,
);
const hits: string[] = [];
const visit = (node: ts.Node): void => {
const tag = jsxTag(node);
if (tag !== null && CONTROLS.has(tag)) {
for (const attr of (node as ts.JsxSelfClosingElement).attributes.properties) {
if (!ts.isJsxAttribute(attr) || attr.name.getText() !== "className") continue;
if (attr.initializer === undefined) continue;
for (const chunk of literalChunks(attr.initializer)) {
const hit = FONT_SIZE_CLASS.exec(chunk);
if (hit !== null) hits.push(hit[0]);
}
}
}
ts.forEachChild(node, visit);
};
visit(source);
return hits;
};
// A plain string, and inside a template around an interpolation.
expect(found('<Input className="w-full text-sm" />')).toEqual(["text-sm"]);
expect(found("<Textarea className={`w-full ${x} text-[13px]`} />")).toEqual(["text-[13px]"]);
// Colour, alignment and a same-prefixed utility are the caller's business, not a font size.
expect(found('<Select className="text-left text-gray-500 text-red-600" />')).toEqual([]);
// The sanctioned route: the rung arrives as an expression, never as typed text.
expect(found("<OptionMenu className={sizeTextClass[size]} />")).toEqual([]);
// The class is only a problem on the control itself.
expect(found('<div className="text-sm"><Input /></div>')).toEqual([]);
});
it("puts a dialog's buttons on the same rung as its fields", () => {
// A Modal footer's Buttons default to md (`text-sm px-3 py-1.5`) while the fields above them
// are sm (`text-xs px-2 py-1`), which is how the two dialog families drifted apart —
// ConfirmModal already passed sm by hand. `Modal` cannot impose it: it owns the footer's
// wrapper, not the buttons in it.
expect(
findLooseFooterButtons(),
'A Button in a Modal footer passes size="sm", so the dialog\'s buttons read at the same ' +
"size as its fields (compare the UI package's ConfirmModal).",
).toEqual([]);
});
it("keeps a dialog body's buttons on the fields' rung", () => {
// Same rule as the footer, one layer in. The settings dialog's pages are separate modules, so
// the drift hides from review twice over: nothing in a section file says it renders inside a
// Modal, and the footer check above cannot see this far. Four of them had taken Button's md
// default and stood a rung above the fields they sat beside.
expect(
findLooseDialogBodyButtons(),
'A Button in a dialog body passes size="sm", the rung the fields beside it are on. ' +
"If a module in DIALOG_BODY_MODULES has stopped being dialog content, drop it from the set.",
).toEqual([]);
});
it("spells a font size in the two records and nowhere else in the family", () => {
// The point of the refactor, stated as the only thing a reader has to check: every font-size
// class the control modules contain belongs to one of two records. `select.tsx` and
// `form-picker.tsx` name none at all — before this scale they each kept a private copy of the
// same two rungs, which is how they drifted.
//
// text-[Npx] is fixed px: it ignores the root font size theme.tsx sets per tier, so a control
// carrying one stops responding to the user's font-size setting. There is no exception: an
// OptionMenu row's description at the sm tier shares the text-xs rung with its title (there is
// no rung below it) and stands apart by its muted ink.
// String literals only: a comment naming the shape it forbids must not trip its own guard.
const spelled = (name: string): string[] => {
const source = parse(sourceFile(SCAN, FAMILY[name]!));
const found = new Set<string>();
for (const chunk of literalChunks(source)) {
for (const hit of chunk.matchAll(new RegExp(FONT_SIZE_CLASS, "g"))) found.add(hit[0]);
}
return [...found].sort();
};
expect(
Object.fromEntries(Object.keys(FAMILY).map((name) => [name, spelled(name)])),
"A font size inside the control family lives in input.tsx's `sizeTextClass` or " +
"option-menu.tsx's `rowDescClass`; a third copy is how the rungs drifted apart before.",
).toEqual({
"input.tsx": ["text-base", "text-xs"], // sizeTextClass
"option-menu.tsx": ["text-xs"], // rowDescClass
"select.tsx": [],
"form-picker.tsx": [],
"search-input.tsx": [],
});
});
});