A local-first multi-agent app development platform, built on PenguinHarness
/**
* The de-slop rules (K-redesign §3) as source scans, shared by the package's suite
* (`packages/ui/test/deslop.test.ts`) and the web app's (`packages/web/test/deslop.test.ts`).
*
* What a check reads:
*
* - **Class tokens**: Tailwind classes from the TypeScript AST — string literals and the literal
* text of template strings, never comments — and from `@apply` lists in stylesheets. A string is
* a class string when it sits in a `className`-like JSX attribute, or when every word in it is
* shaped like a class: `"Uppercase letters"` in a dictionary is prose, `"flex uppercase"` in a
* lookup table is classes. A word touching an interpolation (`` `h-${n}` ``) is incomplete and
* never matched.
* - **Class units**: the tokens that land on one element together — a JSX element's class
* attributes, a class string outside JSX (a `Record` entry), an `@apply` list. The co-occurrence
* rules (a tone's tint beside the same tone's line) read units.
* - **JSX elements**: tag, literal attributes, direct children (seen through `{cond && …}`,
* `.map(…)` and fragments), the enclosing element, and the component they are written in — the
* nearest enclosing PascalCase function.
* - **CSS rules** from `css.ts`: selectors, declarations, lines.
*
* A check reports hits: rule, file, line, and what it found. Homes a rule names (the one spinner
* file, the files that move a sheet) come in through a {@link DeslopPolicy}; occurrences a later
* wave removes are the suite's allowlist, counted per file and rule ({@link allowlistProblems}).
*
* Out of sight, and so review rather than guard: classes assembled at runtime (`TONE[tone]`), and
* nesting across component boundaries.
*/
import ts from "typescript";
import { parseCssRules, stripCssComments } from "./css";
import type { CssStyleRule } from "./css";
import type { SourceFile } from "./source-roots";
// ---------------------------------------------------------------------------
// Rules and policy
// ---------------------------------------------------------------------------
/** §3's rules by their number in the design, so a hit points straight at its rule. */
export const DESLOP_RULES = {
1: "transitions name their properties, never all",
2: "no hover or press transforms",
3: "state transitions take 120–200 ms",
4: "a rounded child in a padded rounded box takes the inner radius",
5: "a rounded clipping box owns the border",
6: "status marks have no halo, and pulse only where something is live",
7: "no icon in a tint of itself",
8: "no coloured left-border callouts",
9: "a filled tone box takes the neutral line",
10: "badges carry state, kind or numbers, never mood",
11: "one spinner",
12: "spacing on the rhythm steps",
13: "text sizes are rungs",
14: "uppercase only through the eyebrow, display, activity and chart hooks",
15: "numbers that align or update use tabular figures",
16: "mono is for data, not labels",
17: "one bordered surface per region",
18: "no decoration without a job",
19: "shadows are tokens",
20: "colour is tokens",
21: "no emoji in copy",
22: "a page header has no eyebrow",
} as const;
export type DeslopRule = keyof typeof DESLOP_RULES;
export const DESLOP_RULE_NUMBERS = Object.keys(DESLOP_RULES).map(Number) as DeslopRule[];
export interface DeslopHit {
readonly rule: DeslopRule;
/** Repo-relative id of the file, forward slashes. */
readonly file: string;
readonly line: number;
/** What was found: the class, the declaration, or a short description. */
readonly found: string;
}
/**
* Where a rule's named exceptions live. Entries are root-relative: ending in `/` matches a
* directory, containing `/` matches that path, and a bare file name (`chevron.tsx`) matches the
* file wherever it sits — the design names these homes by file name.
*/
export interface DeslopPolicy {
/** Rule 1: files that may transition a transform — the chevron, the sheet, launcher and drawer motion. */
readonly transformMotion: readonly string[];
/**
* Rule 1: files that may transition a size or a place — the one `data-layout-motion` rule in
* the theme foundation, which moves a sidebar's width, a disclosure's grid rows or a lifted dock
* surface's insets on the theme's layout tokens. A component never transitions geometry itself;
* it sets the attribute.
*/
readonly layoutMotion?: readonly string[];
/** Rule 3: keyframe-driven entrances that may run 300 ms or longer. */
readonly entranceMotion: readonly string[];
/** Rule 6: files that may pulse without `.ui-live` — the dot, the skeleton, the streaming caret. */
readonly pulseHomes: readonly string[];
/** Rule 11: the one file that spins. */
readonly spinnerHomes: readonly string[];
/**
* Rule 20: palette classes, `dark:` and hex literals are refused. True for the package, whose
* source reads tokens only; false for the web app, which leaves the palette wave by wave.
*/
readonly tokensOnly: boolean;
/** Rule 20: where source may spell a hex colour — the avatar palette and the contract's swatches. */
readonly hexHomes: readonly string[];
}
export function matchesPolicyPath(rel: string, entries: readonly string[]): boolean {
return entries.some((entry) =>
entry.endsWith("/")
? rel.startsWith(entry)
: entry.includes("/")
? rel === entry
: rel === entry || rel.endsWith(`/${entry}`),
);
}
// ---------------------------------------------------------------------------
// Class tokens
// ---------------------------------------------------------------------------
export interface ClassToken {
/** As written: `dark:hover:bg-gray-800`. */
readonly raw: string;
/** Variants before the utility, outermost first: `["dark", "hover"]`. */
readonly variants: readonly string[];
/** The utility, `!` stripped: `bg-gray-800`, `-translate-x-1`. */
readonly utility: string;
readonly line: number;
/** Character offset in the file. */
readonly pos: number;
}
/** Splits `md:hover:[&>svg]:size-4!` into variants and utility on its top-level colons. */
export function parseClassToken(raw: string): { variants: string[]; utility: string } {
const parts: string[] = [];
let depth = 0;
let current = "";
for (const ch of raw) {
if (ch === "[" || ch === "(") depth++;
else if ((ch === "]" || ch === ")") && depth > 0) depth--;
if (ch === ":" && depth === 0) {
parts.push(current);
current = "";
} else current += ch;
}
return { variants: parts, utility: current.replace(/^!|!$/g, "") };
}
/** Class words with no hyphen, colon or bracket. Any other bare word makes its string prose. */
const SINGLE_WORD_CLASSES = new Set(
(
"absolute antialiased block blur border capitalize collapse container contents dark filter " +
"fixed flex grayscale grid group grow hidden inline invert invisible isolate italic lowercase " +
"ordinal outline overline peer prose relative resize ring rounded sepia shadow shrink static " +
"sticky table transform transition truncate underline uppercase visible"
).split(" "),
);
/**
* Whether a word is shaped like a class. A `partial` word touches an interpolation, so an open
* bracket or a trailing hyphen is fine.
*/
export function isClassShaped(word: string, partial = false): boolean {
let depth = 0;
let letters = false;
let plain = true;
for (const ch of word) {
if (ch === "[" || ch === "(") {
depth++;
plain = false;
} else if (ch === "]" || ch === ")") {
if (depth-- === 0) return false;
} else if (depth === 0) {
if (ch >= "a" && ch <= "z") letters = true;
else if (!/[0-9\-:/.!@*%_&>+~]/.test(ch)) return false;
if ("-:/@".includes(ch)) plain = false;
}
}
if (word === "") return false;
if (partial) return true;
if (!letters || depth !== 0 || /^[.:/,]|[.:,/]$/.test(word)) return false;
return !plain || SINGLE_WORD_CLASSES.has(word.replace(/^!|!$/g, ""));
}
interface Word {
readonly text: string;
readonly offset: number;
readonly partial: boolean;
}
function splitWords(text: string, openStart: boolean, openEnd: boolean): Word[] {
return [...text.matchAll(/\S+/g)].map((match) => ({
text: match[0],
offset: match.index,
partial:
(openStart && match.index === 0) ||
(openEnd && match.index + match[0].length === text.length),
}));
}
function toTokens(words: readonly Word[], base: number, lineAt: (pos: number) => number) {
return words
.filter((word) => !word.partial && isClassShaped(word.text))
.map((word): ClassToken => {
const pos = base + word.offset;
return { raw: word.text, ...parseClassToken(word.text), line: lineAt(pos), pos };
});
}
// ---------------------------------------------------------------------------
// File analysis
// ---------------------------------------------------------------------------
export interface StringChunk {
readonly text: string;
readonly line: number;
/** The chunk runs into an interpolation: its last word continues at runtime (`h-${n}`). */
readonly openEnd: boolean;
}
/** Tokens that land on one element together. */
export interface ClassUnit {
readonly tokens: readonly ClassToken[];
readonly line: number;
}
export type JsxChild =
| { readonly kind: "element"; readonly element: JsxElementInfo }
| { readonly kind: "text"; readonly text: string }
| { readonly kind: "expression" };
export interface JsxElementInfo {
/** `div`, `Glyph`, `motion.div`. */
readonly tag: string;
readonly intrinsic: boolean;
/** Literal attribute values: the string, `true` for a bare attribute, `null` for an expression. */
readonly attributes: ReadonlyMap<string, string | true | null>;
/** Complete class tokens from the element's class attributes. */
readonly classes: readonly ClassToken[];
readonly line: number;
/** The nearest enclosing PascalCase function; `null` at module level. */
readonly component: string | null;
readonly parent: JsxElementInfo | null;
readonly children: readonly JsxChild[];
}
export interface ComponentInfo {
readonly name: string;
readonly line: number;
/** Class tokens written inside the component. */
readonly classes: readonly ClassToken[];
/** The first parameter's destructured names and declared type members. */
readonly props: readonly string[];
readonly elements: readonly JsxElementInfo[];
}
export interface FileAnalysis {
readonly file: SourceFile;
readonly surface: "markup" | "stylesheet";
readonly tokens: readonly ClassToken[];
readonly units: readonly ClassUnit[];
readonly elements: readonly JsxElementInfo[];
readonly components: readonly ComponentInfo[];
/** Children lists of every element and fragment: where sibling order is read. */
readonly siblingGroups: readonly (readonly JsxChild[])[];
/** Every string chunk in markup, class or not: hex literals and emoji are looked for here. */
readonly strings: readonly StringChunk[];
readonly cssRules: readonly CssStyleRule[];
}
/** JSX attributes that carry classes: `className`, `class`, `panelClassName`, `iconClass`. */
const CLASS_ATTRIBUTE = /^(?:class|className)$|(?:ClassName|Class)$/;
const analyses = new WeakMap<SourceFile, FileAnalysis>();
export function analyzeFile(file: SourceFile): FileAnalysis {
let analysis = analyses.get(file);
if (analysis === undefined) {
analysis = file.name.endsWith(".css") ? analyzeStylesheet(file) : analyzeMarkup(file);
analyses.set(file, analysis);
}
return analysis;
}
function analyzeStylesheet(file: SourceFile): FileAnalysis {
const css = stripCssComments(file.text);
const lineAt = (pos: number) => css.slice(0, pos).split("\n").length;
const units = [...css.matchAll(/@apply\s+([^;{}]+)/g)].map((match) => ({
tokens: toTokens(
splitWords(match[1]!, false, false),
match.index + match[0].length - match[1]!.length,
lineAt,
),
line: lineAt(match.index),
}));
return {
file,
surface: "stylesheet",
tokens: units.flatMap((unit) => unit.tokens),
units,
elements: [],
components: [],
siblingGroups: [],
strings: [],
cssRules: parseCssRules(file.text),
};
}
/** The name a function goes by: its own, or the variable, property or method holding it. */
function functionName(node: ts.Node): string | null {
if ((ts.isFunctionDeclaration(node) || ts.isFunctionExpression(node)) && node.name) {
return node.name.text;
}
if (ts.isMethodDeclaration(node) && ts.isIdentifier(node.name)) return node.name.text;
if (!ts.isArrowFunction(node) && !ts.isFunctionExpression(node)) return null;
let holder: ts.Node = node.parent;
// Through `memo(() => …)` and `forwardRef(function (…) {…})`.
while (ts.isCallExpression(holder) || ts.isParenthesizedExpression(holder))
holder = holder.parent;
if (
(ts.isVariableDeclaration(holder) || ts.isPropertyAssignment(holder)) &&
ts.isIdentifier(holder.name)
) {
return holder.name.text;
}
return null;
}
const isPascalCase = (name: string) => /^[A-Z][A-Za-z0-9]*$/.test(name);
function analyzeMarkup(file: SourceFile): FileAnalysis {
const source = ts.createSourceFile(
file.path,
file.text,
ts.ScriptTarget.Latest,
/* setParentNodes */ true,
file.name.endsWith(".tsx") ? ts.ScriptKind.TSX : ts.ScriptKind.TS,
);
const lineAt = (pos: number) => source.getLineAndCharacterOfPosition(pos).line + 1;
const strings: StringChunk[] = [];
const tokens: ClassToken[] = [];
const looseUnits: ClassUnit[] = [];
const attributeTokens = new Map<ts.Node, ClassToken[]>();
/** One literal chunk: in a class attribute (`attribute`), or `classes` false in any other. */
const chunk = (
text: string,
start: number,
open: readonly [boolean, boolean],
attribute: ts.JsxAttribute | null,
classes: boolean,
) => {
strings.push({ text, line: lineAt(start), openEnd: open[1] });
if (!classes) return;
const words = splitWords(text, open[0], open[1]);
const classString =
attribute !== null ||
(words.length > 0 && words.every((word) => isClassShaped(word.text, word.partial)));
if (!classString) return;
const found = toTokens(words, start, lineAt);
if (found.length === 0) return;
tokens.push(...found);
if (attribute === null) {
looseUnits.push({ tokens: found, line: lineAt(start) });
} else {
const owner = attribute.parent.parent;
attributeTokens.set(owner, [...(attributeTokens.get(owner) ?? []), ...found]);
}
};
const visit = (node: ts.Node, attribute: ts.JsxAttribute | null, classes: boolean): void => {
if (
ts.isImportDeclaration(node) ||
ts.isExportDeclaration(node) ||
ts.isLiteralTypeNode(node) ||
ts.isImportTypeNode(node) ||
(ts.isCallExpression(node) && node.expression.kind === ts.SyntaxKind.ImportKeyword)
) {
return;
}
if (ts.isJsxAttribute(node)) {
const isClass = CLASS_ATTRIBUTE.test(node.name.getText(source));
if (node.initializer) visit(node.initializer, isClass ? node : null, isClass);
} else if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) {
chunk(node.text, node.getStart(source) + 1, [false, false], attribute, classes);
} else if (ts.isTemplateExpression(node)) {
chunk(node.head.text, node.head.getStart(source) + 1, [false, true], attribute, classes);
for (const span of node.templateSpans) {
visit(span.expression, attribute, classes);
const open = [true, !ts.isTemplateTail(span.literal)] as const;
chunk(span.literal.text, span.literal.getStart(source) + 1, open, attribute, classes);
}
} else if (ts.isPropertyAssignment(node)) {
visit(node.initializer, attribute, classes); // the key is a name, not a value
} else {
ts.forEachChild(node, (child) => visit(child, attribute, classes));
}
};
visit(source, null, true);
// Elements.
type Element = JsxElementInfo & { parent: JsxElementInfo | null; children: JsxChild[] };
const infos = new Map<ts.Node, Element>();
const collect = (node: ts.Node): void => {
if (ts.isJsxElement(node) || ts.isJsxSelfClosingElement(node)) {
const opening = ts.isJsxElement(node) ? node.openingElement : node;
const tag = opening.tagName.getText(source);
const attributes = new Map<string, string | true | null>();
for (const attr of opening.attributes.properties) {
if (!ts.isJsxAttribute(attr)) continue;
const init = attr.initializer;
const literal =
init !== undefined && ts.isJsxExpression(init) ? init.expression : (init ?? null);
attributes.set(
attr.name.getText(source),
init === undefined
? true
: literal !== undefined &&
literal !== null &&
(ts.isStringLiteral(literal) ||
ts.isNoSubstitutionTemplateLiteral(literal) ||
ts.isNumericLiteral(literal))
? literal.text
: null,
);
}
let component: string | null = null;
for (let at: ts.Node | undefined = node.parent; at !== undefined; at = at.parent) {
const name = functionName(at);
if (name !== null && isPascalCase(name)) {
component = name;
break;
}
}
infos.set(node, {
tag,
intrinsic: /^[a-z][\w-]*$/.test(tag),
attributes,
classes: attributeTokens.get(opening) ?? [],
line: lineAt(node.getStart(source)),
component,
parent: null,
children: [],
});
}
ts.forEachChild(node, collect);
};
collect(source);
/** The elements an expression renders: JSX in it that is not inside other JSX in it. */
const rendered = (expression: ts.Node): Element[] => {
const found: Element[] = [];
const walk = (node: ts.Node): void => {
const info = infos.get(node);
if (info !== undefined) found.push(info);
else ts.forEachChild(node, walk);
};
walk(expression);
return found;
};
const childrenOf = (children: ts.NodeArray<ts.JsxChild>): JsxChild[] =>
children.flatMap((child): JsxChild[] => {
if (ts.isJsxText(child)) {
return child.text.trim() === "" ? [] : [{ kind: "text", text: child.text.trim() }];
}
if (ts.isJsxFragment(child)) return childrenOf(child.children);
if (!ts.isJsxExpression(child)) return [{ kind: "element", element: infos.get(child)! }];
const expression = child.expression;
if (expression === undefined) return [];
if (ts.isStringLiteral(expression) || ts.isNoSubstitutionTemplateLiteral(expression)) {
return [{ kind: "text", text: expression.text }];
}
const elements = rendered(expression);
return elements.length === 0
? [{ kind: "expression" }]
: elements.map((element) => ({ kind: "element", element }));
});
const siblingGroups: JsxChild[][] = [];
const fragments = (node: ts.Node): void => {
if (ts.isJsxFragment(node)) siblingGroups.push(childrenOf(node.children));
ts.forEachChild(node, fragments);
};
fragments(source);
for (const [node, info] of infos) {
if (ts.isJsxElement(node)) info.children = childrenOf(node.children);
siblingGroups.push(info.children);
for (let at: ts.Node | undefined = node.parent; at !== undefined; at = at.parent) {
const parent = infos.get(at);
if (parent !== undefined) {
info.parent = parent;
break;
}
}
}
// Components.
const membersOf = (type: ts.TypeNode | undefined): string[] => {
if (type === undefined) return [];
if (ts.isTypeLiteralNode(type))
return type.members.flatMap((m) => m.name?.getText(source) ?? []);
if (ts.isIntersectionTypeNode(type)) return type.types.flatMap(membersOf);
if (!ts.isTypeReferenceNode(type)) return [];
const name = type.typeName.getText(source);
for (const statement of source.statements) {
if (ts.isInterfaceDeclaration(statement) && statement.name.text === name) {
return statement.members.flatMap((m) => m.name?.getText(source) ?? []);
}
if (ts.isTypeAliasDeclaration(statement) && statement.name.text === name) {
return membersOf(statement.type);
}
}
return [];
};
const components: ComponentInfo[] = [];
const findComponents = (node: ts.Node): void => {
const name =
ts.isFunctionDeclaration(node) || ts.isFunctionExpression(node) || ts.isArrowFunction(node)
? functionName(node)
: null;
if (name !== null && isPascalCase(name)) {
const fn = node as ts.FunctionLikeDeclarationBase;
const [start, end] = [fn.getStart(source), fn.getEnd()];
const param = fn.parameters[0];
const props = param === undefined ? [] : membersOf(param.type);
if (param !== undefined && ts.isObjectBindingPattern(param.name)) {
props.push(...param.name.elements.map((e) => (e.propertyName ?? e.name).getText(source)));
}
components.push({
name,
line: lineAt(start),
classes: tokens.filter((token) => token.pos >= start && token.pos < end),
props,
elements: [...infos]
.filter(([element]) => element.getStart(source) >= start && element.getEnd() <= end)
.map(([, info]) => info),
});
}
ts.forEachChild(node, findComponents);
};
findComponents(source);
const elements = [...infos.values()];
return {
file,
surface: "markup",
tokens,
units: [
...elements
.filter((element) => element.classes.length > 0)
.map((element) => ({ tokens: element.classes, line: element.line })),
...looseUnits,
],
elements,
components,
siblingGroups,
strings,
cssRules: [],
};
}
// ---------------------------------------------------------------------------
// Vocabulary
// ---------------------------------------------------------------------------
const TONE_NAMES = ["success", "attention", "danger", "done", "neutral", "info"] as const;
/** Tailwind's chromatic hues: what a tone box, a callout or a halo can be painted in. */
const CHROMATIC_HUES =
"red orange amber yellow lime green emerald teal cyan sky blue indigo violet purple fuchsia pink rose".split(
" ",
);
const HUE = `(?:${[...CHROMATIC_HUES, "slate", "gray", "zinc", "neutral", "stone"].join("|")})`;
const CHROMA = `(?:${CHROMATIC_HUES.join("|")})`;
const STEP = "(?:50|[1-9]00|950)";
const ALPHA = "(?:/[\\w.%[\\]()-]+)?";
const TINT = "(?:50|100|200)";
/** Rule 20: a colour utility on Tailwind's palette, or white / black. */
const PALETTE_CLASS = new RegExp(
"^(?:bg|text|border(?:-[xytrblse])?|ring(?:-offset)?|outline|fill|stroke|from|via|to|divide|" +
`placeholder|caret|accent|decoration|shadow|inset-shadow|inset-ring|drop-shadow)-(?:${HUE}-${STEP}|white|black)${ALPHA}$`,
);
/** Rule 1: what a transition may name. The transform family only in the motion files. */
const TRANSITION_PROPERTIES = new Set(
"color background-color border-color opacity box-shadow outline-color text-decoration-color fill stroke".split(
" ",
),
);
const TRANSFORM_PROPERTIES = new Set(["transform", "translate", "scale", "rotate"]);
/**
* Rule 1: the geometry the layout-motion rule may transition, and nothing else may — the sizes,
* and the two insets a fixed box moves through when a dock surface lifts off the page column.
*/
const LAYOUT_PROPERTIES = new Set(
"width height min-width max-width flex-basis grid-template-rows grid-template-columns top left".split(
" ",
),
);
/** Rule 12: the steps a gap, a stack or an all-sides padding may take. */
const RHYTHM_STEPS = new Set(["0", "px", "1", "1.5", "2", "3", "4", "6", "10"]);
/** Rule 10: words that sell rather than state. */
const MOOD_WORDS = new Set(["new", "hot", "popular", "beta", "trending", "exclusive"]);
/** Rule 21: pictographs that render as emoji by default, or are forced into emoji by VS16. */
export const EMOJI = /\p{Emoji_Presentation}|\p{Extended_Pictographic}\uFE0F/u;
/** Rule 20: a hex colour inside a string: `#fff`, `#2563eb`, `bg-[#00000080]`. */
const HEX_COLOUR = /(?:^|[\s([,:=])(#(?:[0-9a-f]{3,4}|[0-9a-f]{6}|[0-9a-f]{8}))(?![0-9a-z])/gi;
/** A short form with no letter is a label (`#001`), unless it is one repeated digit (`#000`). */
const isHexColour = (hex: string) =>
hex.length > 5 || /[a-f]/i.test(hex) || new Set(hex.slice(1)).size === 1;
/** The components §3 names: tabular figures (15), mono-free labels (16), no eyebrow (22). */
export const TABULAR_COMPONENTS: readonly string[] = ["StatChip", "Count", "KeyValue"];
export const LABEL_COMPONENTS: readonly string[] = ["Button", "NavRow", "Heading", "MenuItem"];
export const PAGE_HEADER_COMPONENTS: readonly string[] = ["PageHeader"];
const BORDER_WIDTH = /^border(?:-(?:2|4|8))?$/;
const ROUNDED_STEP = /^rounded-(?:sm|md|lg|xl)$/;
const INNER_RADIUS =
/^rounded-(?:full|control|\[var\(--radius-inner\)\]|\(--radius-inner\)|\[var\(--ui-radius-control\)\]|\(--ui-radius-control\))$/;
const DURATION_TOKEN = /^var\(\s*--ui-dur-(fast|base|slow)\s*(?:,[^)]*)?\)$/;
/** True when a token with no variants in the unit matches. */
const has = (tokens: readonly ClassToken[], pattern: RegExp) =>
tokens.some((token) => token.variants.length === 0 && pattern.test(token.utility));
// ---------------------------------------------------------------------------
// Token predicates: what to report for one token, or null
// ---------------------------------------------------------------------------
type TokenPredicate = (token: ClassToken, file: SourceFile, policy: DeslopPolicy) => string | null;
const inPolicy = (file: SourceFile, entries: readonly string[]) =>
matchesPolicyPath(file.rel, entries);
/** The comma-separated values of `name-[a,b]` or `name-(a,b)`, or null. */
function arbitraryValues(utility: string, name: string): string[] | null {
if (!utility.startsWith(`${name}-[`) && !utility.startsWith(`${name}-(`)) return null;
return utility
.slice(name.length + 2, -1)
.split(",")
.map((part) => part.trim().replace(/_/g, " "));
}
function refusedTransitionProperties(
properties: readonly string[],
transformOk: boolean,
layoutOk = false,
) {
return properties.filter(
(p) =>
!TRANSITION_PROPERTIES.has(p) &&
!(transformOk && TRANSFORM_PROPERTIES.has(p)) &&
!(layoutOk && LAYOUT_PROPERTIES.has(p)),
);
}
/** Rule 1: `transition-all`, bare `transition`, `transition-transform` off the motion files, a `transition-[…]` list off the set. */
const transitionToken: TokenPredicate = (token, file, policy) => {
const u = token.utility;
if (u === "transition-all" || u === "transition") return token.raw;
const transformOk = inPolicy(file, policy.transformMotion);
if (u === "transition-transform") return transformOk ? null : token.raw;
const list = arbitraryValues(u, "transition");
if (list === null || list.some((p) => p.startsWith("--") || p.startsWith("var("))) return null;
const refused = refusedTransitionProperties(
list,
transformOk,
inPolicy(file, policy.layoutMotion ?? []),
);
return refused.length > 0 ? token.raw : null;
};
/** Rule 2: `scale-*` / `translate-*` under a hover, active or focus variant (group- and peer- too). */
const hoverTransformToken: TokenPredicate = (token) =>
token.variants.some((v) =>
/^(?:group-|peer-)?(?:hover|active|focus|focus-visible|focus-within)(?:\/[\w-]+)?$/.test(v),
) && /^-?(?:scale|translate)-/.test(token.utility)
? token.raw
: null;
function milliseconds(value: string): number | null {
const match = /^(\d*\.?\d+)(ms|s)$/.exec(value.trim());
return match === null ? null : Number(match[1]) * (match[2] === "s" ? 1000 : 1);
}
/**
* Rule 3 on one duration. A duration token is fine (slow only in an entrance); a literal is fine
* at 0, in `allowed`, or at 300 ms and up in an entrance. Other `var()`s are not ours to judge.
*/
function durationRefused(value: string, entrance: boolean, allowed: (ms: number) => boolean) {
const token = DURATION_TOKEN.exec(value.trim());
if (token !== null) return token[1] === "slow" && !entrance;
const ms = milliseconds(value);
return ms !== null && ms !== 0 && !allowed(ms) && !(ms >= 300 && entrance);
}
/** Utilities: `duration-150`, `duration-200` or the fast / base token — nothing in between. */
const UTILITY_DURATIONS = (ms: number) => ms === 150 || ms === 200;
/** Stylesheets: anything from 120 to 200 ms. */
const CSS_DURATIONS = (ms: number) => ms >= 120 && ms <= 200;
/** Rule 3: `duration-*` other than 150, 200 or the fast / base token; 300+ only in an entrance file. */
const durationToken: TokenPredicate = (token, file, policy) => {
const entrance = inPolicy(file, policy.entranceMotion);
const numeric = /^duration-(\d+)$/.exec(token.utility);
const values =
numeric !== null ? [`${numeric[1]}ms`] : arbitraryValues(token.utility, "duration");
if (values === null || values.length !== 1) return null;
const value = values[0]!.startsWith("--") ? `var(${values[0]})` : values[0]!;
if (value.startsWith("var(") && !DURATION_TOKEN.test(value)) return null;
return durationRefused(value, entrance, UTILITY_DURATIONS) ? token.raw : null;
};
/** Rule 11: `animate-spin` outside the Spinner file; `border-t-transparent` anywhere. */
const spinnerToken: TokenPredicate = (token, file, policy) => {
const u = token.utility;
if (u === "border-t-transparent") return token.raw;
const spins = u === "animate-spin" || /^animate-[[(]spin[_\s]/.test(u);
return spins && !inPolicy(file, policy.spinnerHomes) ? token.raw : null;
};
/** Rule 12: `gap-*`, `space-x|y-*`, `p-*` off the rhythm steps; a `var(--ui-*)` value is a step. */
const spacingToken: TokenPredicate = (token) => {
const match = /^(?:gap(?:-[xy])?|space-[xy]|p)-(.+)$/.exec(token.utility);
if (match === null || match[1] === "reverse" || RHYTHM_STEPS.has(match[1]!)) return null;
return /^(?:\[var\(--ui-[\w-]+\)\]|\(--ui-[\w-]+\))$/.test(match[1]!) ? null : token.raw;
};
/** Rule 13: a literal font size, `text-[11px]` or `text-[0.6875rem]`. */
const textSizeToken: TokenPredicate = (token) =>
/^text-\[(?:length:)?\d*\.?\d+(?:px|rem)\]$/.test(token.utility) ? token.raw : null;
/** Rule 14: `uppercase` and `tracking-wide|wider|widest`. */
const uppercaseToken: TokenPredicate = (token) =>
/^(?:uppercase|tracking-(?:wide|wider|widest))$/.test(token.utility) ? token.raw : null;
/** Rule 19: a shadow other than `shadow-sm|lg|xl|none` or `shadow-[var(--ui-shadow-*)]`; any `drop-shadow`. */
const shadowToken: TokenPredicate = (token) => {
const u = token.utility;
if (!/^(?:shadow|inset-shadow|drop-shadow)(?:-|$)/.test(u)) return null;
if (/^shadow-(?:sm|lg|xl|none)$/.test(u)) return null;
if (/^shadow-(?:\[var\(--ui-shadow-[a-z]+\)\]|\(--ui-shadow-[a-z]+\))$/.test(u)) return null;
return token.raw;
};
/** Rule 20: a palette colour class or a `dark:` variant, where the policy is tokens only. */
const paletteToken: TokenPredicate = (token, _file, policy) =>
policy.tokensOnly && (token.variants.includes("dark") || PALETTE_CLASS.test(token.utility))
? token.raw
: null;
// ---------------------------------------------------------------------------
// Unit and element checks
// ---------------------------------------------------------------------------
type Check = (analysis: FileAnalysis, policy: DeslopPolicy) => Omit<DeslopHit, "rule" | "file">[];
const tokenCheck =
(predicate: TokenPredicate): Check =>
(analysis, policy) =>
analysis.tokens.flatMap((token) => {
const found = predicate(token, analysis.file, policy);
return found === null ? [] : [{ line: token.line, found }];
});
/** Rule 6: `animate-ping`; `animate-pulse` off `.ui-live` outside the pulse homes; a halo on a dot. */
const statusMarkCheck: Check = (analysis, policy) =>
analysis.units.flatMap((unit) => {
const hits: { line: number; found: string }[] = [];
const live = unit.tokens.some((t) => t.utility === "ui-live");
for (const token of unit.tokens) {
if (
token.utility === "animate-ping" ||
(token.utility === "animate-pulse" && !live && !inPolicy(analysis.file, policy.pulseHomes))
) {
hits.push({ line: token.line, found: token.raw });
}
}
const dot =
has(unit.tokens, /^rounded-full$/) &&
(has(unit.tokens, /^size-(?:1|1\.5|2|2\.5)$/) ||
(has(unit.tokens, /^h-(?:1|1\.5|2|2\.5)$/) && has(unit.tokens, /^w-(?:1|1\.5|2|2\.5)$/)));
if (dot) {
const halo = new RegExp(`^(?:ring-(?:tone-|accent|${CHROMA}-)|shadow(?!-none$))`);
for (const token of unit.tokens) {
if (halo.test(token.utility))
hits.push({ line: token.line, found: `${token.raw} on a dot` });
}
}
return hits;
});
/** Rule 7: a tone's (or a hue's) tint and ink on an element whose only content is icons. */
const tintedIconCheck: Check = (analysis) =>
analysis.elements.flatMap((element) => {
const iconOnly =
element.children.length > 0 &&
element.children.every(
(child) =>
child.kind === "element" &&
(/^(?:svg|Glyph|GlyphIcon|Chevron)$|Icon$/.test(child.element.tag) ||
(child.element.intrinsic && child.element.children.length === 0)),
);
if (!iconOnly) return [];
const tone =
TONE_NAMES.find(
(t) =>
has(element.classes, new RegExp(`^bg-tone-${t}-bg$`)) &&
has(element.classes, new RegExp(`^text-tone-${t}-fg$`)),
) ??
CHROMATIC_HUES.find(
(h) =>
has(element.classes, new RegExp(`^bg-${h}-${TINT}${ALPHA}$`)) &&
has(element.classes, new RegExp(`^text-${h}-${STEP}${ALPHA}$`)),
);
return tone === undefined
? []
: [
{
line: element.line,
found: `<${element.tag}> holds only an icon, in ${tone} ink on ${tone} tint`,
},
];
});
/** Rule 8: a 2 or 4 px left border in a tone, the accent or a chromatic hue. */
const leftBorderCheck: Check = (analysis) => {
const colour = new RegExp(
`^border-(?:[ls]-)?(?:tone-[a-z]+-(?:line|fg|emphasis|bg)|accent(?:-[a-z]+)?|${CHROMA}-${STEP}${ALPHA})$`,
);
return analysis.units.flatMap((unit) => {
const width = unit.tokens.find((t) => /^border-[ls]-(?:2|4)$/.test(t.utility));
if (width === undefined || !unit.tokens.some((t) => colour.test(t.utility))) return [];
return [{ line: width.line, found: `${width.raw} in a colour` }];
});
};
/** Rule 9: a tone's tint beside the same tone's line, or a hue's 50–200 tint beside its border. */
const oneHueCheck: Check = (analysis) =>
analysis.units.flatMap((unit) => [
...TONE_NAMES.filter(
(t) =>
has(unit.tokens, new RegExp(`^bg-tone-${t}-bg$`)) &&
has(unit.tokens, new RegExp(`^border(?:-[xytrblse])?-tone-${t}-(?:line|fg|emphasis)$`)),
).map((t) => ({ line: unit.line, found: `${t}: tint and line on one box` })),
...CHROMATIC_HUES.filter(
(h) =>
has(unit.tokens, new RegExp(`^bg-${h}-${TINT}${ALPHA}$`)) &&
has(unit.tokens, new RegExp(`^border(?:-[xytrblse])?-${h}-${STEP}${ALPHA}$`)),
).map((h) => ({ line: unit.line, found: `${h}: tint and line on one box` })),
]);
/** Rule 4: a stepped radius on a direct child of a padded box with a stepped radius. */
const nestedRadiusCheck: Check = (analysis) =>
analysis.elements.flatMap((element) => {
if (!has(element.classes, ROUNDED_STEP) || !has(element.classes, /^p-(?!0$|px$)/)) return [];
return element.children.flatMap((child) => {
if (child.kind !== "element") return [];
const radius = child.element.classes.find(
(t) => t.variants.length === 0 && ROUNDED_STEP.test(t.utility),
);
if (radius === undefined || has(child.element.classes, INNER_RADIUS)) return [];
return [
{
line: child.element.line,
found: `<${child.element.tag}> ${radius.raw} in a padded rounded box`,
},
];
});
});
/** Rule 5: a full border on a direct child of a rounded box that clips. */
const clippedBorderCheck: Check = (analysis) =>
analysis.elements.flatMap((element) => {
if (
!has(element.classes, /^rounded(?:-(?!none$|0$).+)?$/) ||
!has(element.classes, /^overflow(?:-[xy])?-(?:hidden|clip)$/)
) {
return [];
}
return element.children.flatMap((child) => {
if (child.kind !== "element") return [];
const border = child.element.classes.find(
(t) => t.variants.length === 0 && BORDER_WIDTH.test(t.utility),
);
return border === undefined
? []
: [
{
line: child.element.line,
found: `<${child.element.tag}> ${border.raw} inside a clipping rounded box`,
},
];
});
});
/** Rule 10: a `<Badge>` whose literal text is a mood word or an emoji. */
const moodBadgeCheck: Check = (analysis) =>
analysis.elements.flatMap((element) =>
element.tag !== "Badge"
? []
: element.children.flatMap((child) => {
if (child.kind !== "text") return [];
const word = child.text.trim().toLowerCase();
const mood =
MOOD_WORDS.has(word) && !(word === "beta" && element.component === "BetaBadge");
return mood || EMOJI.test(child.text)
? [{ line: element.line, found: `<Badge>${child.text.trim()}</Badge>` }]
: [];
}),
);
const isEyebrow = (element: JsxElementInfo) =>
element.classes.some((t) => t.utility === "ui-eyebrow") ||
(element.tag === "Text" && element.attributes.get("variant") === "eyebrow");
function headingLevel(element: JsxElementInfo): number | null {
const intrinsic = /^h([1-6])$/.exec(element.tag);
if (intrinsic !== null) return Number(intrinsic[1]);
const level = element.tag === "Heading" ? element.attributes.get("level") : undefined;
return typeof level === "string" && /^[1-6]$/.test(level) ? Number(level) : null;
}
/** Rule 14: an eyebrow as the previous sibling of an h1–h4. */
const eyebrowSiblingCheck: Check = (analysis) =>
analysis.siblingGroups.flatMap((group) =>
group.flatMap((child, i) => {
const next = group[i + 1];
if (child.kind !== "element" || next?.kind !== "element") return [];
const level = headingLevel(next.element);
return isEyebrow(child.element) && level !== null && level <= 4
? [{ line: child.element.line, found: `eyebrow directly above <${next.element.tag}>` }]
: [];
}),
);
/** Rule 15: a listed component with no `tabular-nums`. */
const tabularCheck: Check = (analysis) =>
analysis.components
.filter((c) => TABULAR_COMPONENTS.includes(c.name))
.filter((c) => !c.classes.some((t) => t.utility === "tabular-nums"))
.map((c) => ({ line: c.line, found: `${c.name} has no tabular-nums` }));
/** Rule 16: `font-mono` inside a listed label component. */
const monoLabelCheck: Check = (analysis) =>
analysis.components
.filter((c) => LABEL_COMPONENTS.includes(c.name))
.flatMap((c) =>
c.classes
.filter((t) => t.utility === "font-mono")
.map((t) => ({ line: t.line, found: `${t.raw} in ${c.name}` })),
);
/** Block containers: what a card is written as. A bordered filled `<span>` or `<input>` is a control. */
const BLOCK_TAGS =
/^(?:div|section|article|aside|header|footer|main|nav|ul|ol|li|details|form|fieldset)$/;
/** Rule 17: a bordered surface nested in another bordered surface in the same file. */
const nestedSurfaceCheck: Check = (analysis) => {
const surface = (e: JsxElementInfo) =>
BLOCK_TAGS.test(e.tag) &&
has(e.classes, BORDER_WIDTH) &&
has(e.classes, /^bg-surface(?:-muted|-inset)?$/);
return analysis.elements.flatMap((element) => {
if (!surface(element)) return [];
for (let up = element.parent; up !== null; up = up.parent) {
if (surface(up)) {
return [
{
line: element.line,
found: `<${element.tag}> surface inside the surface at line ${up.line}`,
},
];
}
}
return [];
});
};
/** Rule 18: gradient backgrounds, and backdrop filters on a unit without `.ui-glass` / `.ui-scrim`. */
const decorationCheck: Check = (analysis) =>
analysis.units.flatMap((unit) => {
const glass = unit.tokens.some((t) => t.utility === "ui-glass" || t.utility === "ui-scrim");
return unit.tokens.flatMap((token) => {
const u = token.utility;
const gradient =
/^bg-(?:gradient-|linear-|radial|conic)/.test(u) ||
/^bg-\[(?:image:)?(?:repeating-)?(?:linear|radial|conic)-gradient/.test(u) ||
/^\[background(?:-image)?:[^\]]*gradient/.test(u);
const blur = /^(?:backdrop-(?:blur|saturate|filter)|\[(?:-webkit-)?backdrop-filter:)/.test(u);
return gradient || (blur && !glass) ? [{ line: token.line, found: token.raw }] : [];
});
});
/** Rule 20's hex half: hex colours in source strings outside the identity-data homes. */
const hexCheck: Check = (analysis, policy) => {
if (!policy.tokensOnly || inPolicy(analysis.file, policy.hexHomes)) return [];
return analysis.strings.flatMap((chunk) =>
[...chunk.text.matchAll(HEX_COLOUR)]
.filter((match) => isHexColour(match[1]!))
.map((match) => ({
line: chunk.line + (chunk.text.slice(0, match.index).match(/\n/g)?.length ?? 0),
found: match[1]!,
})),
);
};
/** Rule 21: emoji in a `strings*.ts` dictionary. */
const emojiCheck: Check = (analysis) => {
if (!/^strings.*\.ts$/.test(analysis.file.name)) return [];
return analysis.strings
.filter((chunk) => EMOJI.test(chunk.text))
.map((chunk) => ({ line: chunk.line, found: chunk.text.match(EMOJI)![0] }));
};
/** Rule 22: a page header that takes or renders an eyebrow. */
const pageHeaderCheck: Check = (analysis) =>
analysis.components
.filter((c) => PAGE_HEADER_COMPONENTS.includes(c.name))
.flatMap((c) => [
...(c.props.includes("eyebrow")
? [{ line: c.line, found: `${c.name} takes an eyebrow` }]
: []),
...c.elements
.filter(isEyebrow)
.map((e) => ({ line: e.line, found: `${c.name} renders an eyebrow` })),
]);
// ---------------------------------------------------------------------------
// Stylesheet checks
// ---------------------------------------------------------------------------
const fullSelector = (rule: CssStyleRule) => [...rule.parents, rule.selector].join(" ");
/**
* Transition shorthand items; a missing property is `all`, as in CSS. `discrete` marks an item
* that carries `allow-discrete`: a property that cannot interpolate, flipped at one instant.
*/
function transitionItems(
value: string,
): { property: string; duration: string | null; discrete: boolean }[] {
const items: string[] = [];
let depth = 0;
let current = "";
for (const ch of value.replace(/!important/g, "")) {
if (ch === "(") depth++;
else if (ch === ")") depth--;
if (ch === "," && depth === 0) {
items.push(current);
current = "";
} else current += ch;
}
items.push(current);
return items
.map((item) => item.trim())
.filter((item) => item !== "" && item !== "none")
.map((item) => {
let property: string | null = null;
let duration: string | null = null;
let discrete = false;
for (const part of item.match(/[\w-]+\((?:[^()]|\([^()]*\))*\)|\S+/g) ?? []) {
if (part === "allow-discrete") discrete = true;
if (DURATION_TOKEN.test(part) || milliseconds(part) !== null) duration ??= part;
else if (
property === null &&
/^[a-z-]+$/.test(part) &&
!/^(?:ease|ease-in|ease-out|ease-in-out|linear|step-start|step-end|allow-discrete|normal)$/.test(
part,
)
) {
property = part;
}
}
return { property: property ?? "all", duration, discrete };
});
}
const declarations = (analysis: FileAnalysis) =>
analysis.cssRules.flatMap((rule) => rule.declarations.map((decl) => ({ rule, decl })));
/**
* The one discrete hold rule 1 lets through: a `.ui-stream` recipe's veil keeps its gradient
* while its opacity fades out on `done`, by naming `background-image` in a shorthand item with
* `allow-discrete` (user decision, 2026-09-30). A discrete transition interpolates nothing — the
* image is swapped at one instant, and with a `step-end` timing that instant is the end of the
* fade — so the finished reply settles instead of snapping, and nothing moves that the rule
* guards. Anywhere else, or without `allow-discrete`, `background-image` is off the set as ever.
*/
const DISCRETE_HOLD = { property: "background-image", selector: /\.ui-stream\b/ } as const;
/** Rule 1: `transition` / `transition-property` naming `all` (or nothing) or a property off the set. */
const cssTransitionCheck: Check = (analysis, policy) =>
declarations(analysis).flatMap(({ rule, decl }) => {
const hold = DISCRETE_HOLD.selector.test(fullSelector(rule));
const properties =
decl.name === "transition"
? transitionItems(decl.value)
.filter((item) => !(hold && item.discrete && item.property === DISCRETE_HOLD.property))
.map((item) => item.property)
: decl.name === "transition-property"
? decl.value
.split(",")
.map((p) => p.trim())
.filter((p) => p !== "none" && !p.startsWith("var("))
: [];
const refused = refusedTransitionProperties(
properties,
inPolicy(analysis.file, policy.transformMotion),
inPolicy(analysis.file, policy.layoutMotion ?? []),
);
return refused.length > 0
? [{ line: decl.line, found: `${decl.name}: ${refused.join(", ")}` }]
: [];
});
/** Rule 2: `transform`, `translate` or `scale` declared under `:hover` or `:active`. */
const cssHoverTransformCheck: Check = (analysis) =>
declarations(analysis).flatMap(({ rule, decl }) =>
/:(?:hover|active)\b/.test(fullSelector(rule)) &&
/^(?:transform|translate|scale)$/.test(decl.name) &&
decl.value !== "none"
? [{ line: decl.line, found: `${rule.selector} { ${decl.name}: ${decl.value} }` }]
: [],
);
/** Rule 3: a transition duration outside 120–200 ms (300+ only in an entrance file). */
const cssDurationCheck: Check = (analysis, policy) => {
const entrance = inPolicy(analysis.file, policy.entranceMotion);
return declarations(analysis).flatMap(({ decl }) => {
const durations =
decl.name === "transition"
? transitionItems(decl.value).flatMap((item) => item.duration ?? [])
: decl.name === "transition-duration"
? decl.value.split(",").map((part) => part.trim())
: [];
return durations
.filter((duration) => durationRefused(duration, entrance, CSS_DURATIONS))
.map((duration) => ({ line: decl.line, found: `${decl.name}: ${duration}` }));
});
};
/** Animations named `names` outside the rules whose selector matches `except` (the live hook). */
const cssAnimationCheck =
(names: RegExp, except: RegExp): Check =>
(analysis) =>
declarations(analysis).flatMap(({ rule, decl }) =>
/^animation(?:-name)?$/.test(decl.name) &&
names.test(decl.value) &&
!except.test(fullSelector(rule))
? [{ line: decl.line, found: `${rule.selector} { ${decl.name}: ${decl.value} }` }]
: [],
);
/**
* Rule 14: `text-transform: uppercase` outside `.ui-eyebrow` / `.ui-display` rules — and the
* `.ui-activity` label, the transcript's mono capitals (user decision, 2026-09-29): a step's
* label is a group-label rung in Console, and the hook is the one door to it — and, the same
* way, a `.ui-chart` axis label, Console's tracked mono capitals on a plot.
*/
const cssUppercaseCheck: Check = (analysis) =>
declarations(analysis).flatMap(({ rule, decl }) =>
decl.name === "text-transform" &&
decl.value === "uppercase" &&
!/\.ui-(?:eyebrow|display|activity|chart)\b/.test(fullSelector(rule))
? [{ line: decl.line, found: `${rule.selector} { text-transform: uppercase }` }]
: [],
);
/**
* Marks a recipe may set in the mono face because they are technical on purpose (user decision,
* 2026-09-30, when Console's chrome moved to a sans and kept mono for these alone): a
* `.ui-activity` step's label and progress bar, the transcript's capitals and its block bar; a
* `.ui-notice` tag drawn in `::before`, a console status line's `[ OK ]`; and the text of a
* `.ui-chart`, a plot's axis labels. A detail slot, a frame's head or a notice's message is
* not one of them.
*/
const MONO_MARKS =
/\.ui-activity\b[^,]*\[data-slot="(?:label|progress)"\]|\.ui-notice\b[^,\s]*::before|\.ui-chart\b[^,]*\btext\b/;
/** Rule 16: a hook recipe (`.ui-*`) setting a mono `font-family`, off the marks above. */
const cssHookMonoCheck: Check = (analysis) =>
declarations(analysis).flatMap(({ rule, decl }) =>
/\.ui-[a-z]/.test(fullSelector(rule)) &&
!MONO_MARKS.test(fullSelector(rule)) &&
decl.name === "font-family" &&
/--ui-font-mono|monospace/.test(decl.value)
? [{ line: decl.line, found: `${rule.selector} { font-family: ${decl.value} }` }]
: [],
);
/**
* Gradients painted by a hook recipe — the atmosphere tell — and backdrop filters off the two
* hooks that may blur: `.ui-glass` (the frosted layer) and `.ui-scrim` (the dimmed backdrop
* behind a dialog, which Frost blurs; user decision, 2026-09-30).
* Two recipes may paint a gradient, each with a job: `.ui-shell`'s colour field behind the app
* window, which holds the floating sheet and the glass layers against it (user decision,
* 2026-09-19), and the RUNNING state of `.ui-activity`, whose highlight sweeping across a label
* is the signal that a step is in progress (user decision, 2026-09-29) — never the resting
* states, so a finished transcript carries no wash. A third, `.ui-chart`, may paint one as a
* MASK: a line's area fading towards the baseline — a gradient that carries the data's shape,
* not atmosphere (user decision, 2026-09-29). A fourth, the STREAMING state of `.ui-stream`,
* paints the veil a reply surfaces through while it arrives — the gradient is how its newest
* lines read as fading in (user decision, 2026-09-30) — and, like the activity row's, never on
* the finished reply: the `done` state's rule may hold the image only through its fade-out, by
* the discrete transition rule 1 allows, and never declares one. A gradient on any other hook,
* as a background or as a mask, is still the tell. A gradient in app CSS that is not a hook (the
* context bar's hatch, which carries meaning) is review.
*/
const GRADIENT_RECIPES =
/\.ui-shell\b|\.ui-activity\[data-state="running"\]|\.ui-chart\b|\.ui-stream\[data-state="streaming"\]/;
const cssDecorationCheck: Check = (analysis) =>
declarations(analysis).flatMap(({ rule, decl }) => {
const selector = fullSelector(rule);
if (
/\.ui-[a-z]/.test(selector) &&
!GRADIENT_RECIPES.test(selector) &&
/^(?:background(?:-image)?|(?:-webkit-)?mask-image)$/.test(decl.name) &&
/gradient\(/.test(decl.value)
) {
return [{ line: decl.line, found: `${rule.selector} { ${decl.name}: …gradient() }` }];
}
if (
/^(?:-webkit-)?backdrop-filter$/.test(decl.name) &&
decl.value !== "none" &&
!/\.ui-(?:glass|scrim)\b/.test(selector)
) {
return [{ line: decl.line, found: `${rule.selector} { ${decl.name}: ${decl.value} }` }];
}
return [];
});
// ---------------------------------------------------------------------------
// The check table
// ---------------------------------------------------------------------------
export interface DeslopCheck {
readonly rule: DeslopRule;
/** Which files the check reads: `.ts`/`.tsx`, or `.css`. */
readonly surface: "markup" | "stylesheet";
readonly run: Check;
}
const markup = (rule: DeslopRule, run: Check): DeslopCheck => ({ rule, surface: "markup", run });
const sheet = (rule: DeslopRule, run: Check): DeslopCheck => ({ rule, surface: "stylesheet", run });
/** A class-token check reads markup and `@apply` lists alike. */
const both = (rule: DeslopRule, run: Check) => [markup(rule, run), sheet(rule, run)];
export const DESLOP_CHECKS: readonly DeslopCheck[] = [
...both(1, tokenCheck(transitionToken)),
sheet(1, cssTransitionCheck),
...both(2, tokenCheck(hoverTransformToken)),
sheet(2, cssHoverTransformCheck),
...both(3, tokenCheck(durationToken)),
sheet(3, cssDurationCheck),
markup(4, nestedRadiusCheck),
markup(5, clippedBorderCheck),
...both(6, statusMarkCheck),
sheet(6, cssAnimationCheck(/\b(?:pulse|ping)\b/, /\.ui-live\b/)),
markup(7, tintedIconCheck),
...both(8, leftBorderCheck),
...both(9, oneHueCheck),
markup(10, moodBadgeCheck),
...both(11, tokenCheck(spinnerToken)),
sheet(11, cssAnimationCheck(/\bspin\b/, /\.ui-live\b/)),
...both(12, tokenCheck(spacingToken)),
...both(13, tokenCheck(textSizeToken)),
...both(14, tokenCheck(uppercaseToken)),
markup(14, eyebrowSiblingCheck),
sheet(14, cssUppercaseCheck),
markup(15, tabularCheck),
markup(16, monoLabelCheck),
sheet(16, cssHookMonoCheck),
markup(17, nestedSurfaceCheck),
...both(18, decorationCheck),
sheet(18, cssDecorationCheck),
...both(19, tokenCheck(shadowToken)),
...both(20, tokenCheck(paletteToken)),
markup(20, hexCheck),
markup(21, emojiCheck),
markup(22, pageHeaderCheck),
];
/**
* Every hit of one rule across the files, both surfaces unless one is named, sorted by file and
* line. Each occurrence counts once: two identical classes on one line are two hits.
*/
export function deslopHits(
files: readonly SourceFile[],
rule: DeslopRule,
policy: DeslopPolicy,
surface?: "markup" | "stylesheet",
): DeslopHit[] {
const hits: DeslopHit[] = [];
for (const file of files) {
const analysis = analyzeFile(file);
for (const check of DESLOP_CHECKS) {
if (check.rule !== rule || check.surface !== analysis.surface) continue;
if (surface !== undefined && check.surface !== surface) continue;
for (const { line, found } of check.run(analysis, policy)) {
hits.push({ rule, file: file.id, line, found });
}
}
}
return hits.sort((a, b) => (a.file === b.file ? a.line - b.line : a.file < b.file ? -1 : 1));
}
// ---------------------------------------------------------------------------
// Allowlists
// ---------------------------------------------------------------------------
/**
* Exempted occurrences, by root-relative file path, then rule: how many hits the file still holds
* and the wave that removes them — `"features/chat/foo.tsx": { 13: [4, "W6"] }`.
*/
export type DeslopAllowlist = Readonly<
Record<string, Partial<Readonly<Record<DeslopRule, readonly [count: number, wave: string]>>>>
>;
/**
* One rule's hits against an allowlist, as lines to print: empty when they agree. A file with no
* entry must hold no hits; a file with an entry must hold exactly its count — more is new slop,
* fewer means the entry shrinks in the same change, so the list only tightens.
*/
export function allowlistProblems(
hits: readonly DeslopHit[],
rule: DeslopRule,
allowlist: DeslopAllowlist,
relOf: (hit: DeslopHit) => string,
): string[] {
const byFile = new Map<string, DeslopHit[]>();
for (const found of hits) byFile.set(relOf(found), [...(byFile.get(relOf(found)) ?? []), found]);
const problems: string[] = [];
for (const [rel, list] of byFile) {
const entry = allowlist[rel]?.[rule];
const where = list.map((f) => `\n ${f.file}:${f.line} ${f.found}`).join("");
if (entry === undefined) problems.push(`${rel}: ${list.length} new${where}`);
else if (list.length > entry[0]) {
problems.push(
`${rel}: ${list.length} where ${entry[0]} are allowlisted (${entry[1]})${where}`,
);
} else if (list.length < entry[0]) {
problems.push(
`${rel}: ${list.length} left of ${entry[0]} — shrink the entry to [${list.length}, "${entry[1]}"]`,
);
}
}
for (const [rel, rules] of Object.entries(allowlist)) {
const entry = rules[rule];
if (entry !== undefined && !byFile.has(rel)) {
problems.push(`${rel}: none left of ${entry[0]} (${entry[1]}) — delete the entry`);
}
}
return problems.sort();
}