An open source design system that's fully customizable and agent ready
TypeScript
fix(cli): the unloaded-font advisory is a notice, not a warning (#5090)
Cindy Zhangda6ea6710bd9
diff --git a/.changeset/font-advisory-is-a-notice.md b/.changeset/font-advisory-is-a-notice.mdnew file mode 100644index 0000000000..cc46ec3bff--- /dev/null+++ b/.changeset/font-advisory-is-a-notice.md@@ -0,0 +1,11 @@+---+'@astryxdesign/cli': patch+---++[fix] The unloaded-font advisory is a notice, not a warning. A theme file cannot load a font — Astryx sets `--font-family-*` and loading is the app's job — so #5045's advisory fires on any theme naming a webfont, including a perfectly correct one. As a warning that made a clean build read as defective, and it put the shipped template permanently in violation of its own "compiles with no warnings" guard (#5079 had to allowlist the template's two font names in that assertion).++The `theme.build` receipt now separates the two: `warnings` are defects the author should fix, `notices` are advisories about a correct theme. The font advisory moves to `notices` and to stdout with the rest of the build's progress; stderr stays for defects. The template guard is back to `warnings` being empty, and no longer needs to know which fonts the template names.++Programmatic callers reading `data.warnings` for font advisories should read `data.notices`; the message text is unchanged.++@cixzhangdiff --git a/packages/cli/api/theme/build/build.font-warning.test.mjs b/packages/cli/api/theme/build/build.font-warning.test.mjsindex ae925b4562..148419ac41 100644--- a/packages/cli/api/theme/build/build.font-warning.test.mjs+++ b/packages/cli/api/theme/build/build.font-warning.test.mjs@@ -1,13 +1,18 @@// Copyright (c) Meta Platforms, Inc. and affiliates./**- * API-contract tests for the font-loading warning in `themeBuild()` (#5015):+ * API-contract tests for the font-loading advisory in `themeBuild()` (#5015):* a theme that names font families it does not load gets one entry per family- * in the `theme.build` receipt's `warnings` array, on BOTH load paths — a raw+ * in the `theme.build` receipt's `notices` array, on BOTH load paths — a raw* typography config (resolved through core's defineTheme) and an* already-resolved theme that sets `--font-family-*` tokens directly. Themes- * that only name generics or known system families warn about nothing, and- * the warning never breaks the API's silence contract (default noopLogger).+ * that only name generics or known system families say nothing, and the+ * advisory never breaks the API's silence contract (default noopLogger).+ *+ * `notices`, not `warnings`: a theme file cannot load a font — that is the+ * app's job by design — so this fires on correct themes and is context, not a+ * defect to fix. Every assertion here also pins it OUT of `warnings`, since+ * the whole point is that a good theme builds warning-free.** Needs a built core — the `node` project's globalSetup* (vitest.global-setup.node.mjs) builds it once before workers fork.@@ -45,15 +50,16 @@ describe('themeBuild() — font-loading warnings in the receipt', () => {const result = await themeBuild('fonty.mjs', {}, {cwd: tmpDir});expect(result?.type).toBe('theme.build');- const warnings = result?.data.warnings ?? [];- expect(warnings).toEqual(+ const notices = result?.data.notices ?? [];+ expect(notices).toEqual(expect.arrayContaining([expect.stringContaining('Font "Space Grotesk"'),expect.stringContaining('Font "JetBrains Mono"'),]),);- // Heading inherits body's family; the shared family warns exactly once.- expect(warnings.filter(w => w.includes('Space Grotesk'))).toHaveLength(1);+ // Heading inherits body's family; the shared family is named exactly once.+ expect(notices.filter(w => w.includes('Space Grotesk'))).toHaveLength(1);+ expect(result?.data.warnings).toEqual([]);});it('warns for an already-resolved theme: font-family tokens and component overrides, nothing else', async () => {@@ -74,13 +80,14 @@ describe('themeBuild() — font-loading warnings in the receipt', () => {// Exactly the two named families — a non-family --font-* token must not// produce a bogus "Font \\"1rem\\"" entry, and the components half of the// feature must survive the real themeBuild path, not just the unit helper.- const fontWarnings = (result?.data.warnings ?? []).filter(w =>+ const fontNotices = (result?.data.notices ?? []).filter(w =>w.startsWith('Font "'),);- expect(fontWarnings).toEqual([+ expect(fontNotices).toEqual([expect.stringContaining('Font "Bungee"'),expect.stringContaining('Font "Orbitron"'),]);+ expect(result?.data.warnings).toEqual([]);});it('warns for a family named only inside a pseudo-class component override (defineTheme path)', async () => {@@ -102,13 +109,14 @@ describe('themeBuild() — font-loading warnings in the receipt', () => {const result = await themeBuild('pseudo.mjs', {}, {cwd: tmpDir});- const fontWarnings = (result?.data.warnings ?? []).filter(w =>+ const fontNotices = (result?.data.notices ?? []).filter(w =>w.startsWith('Font "'),);// Exactly the hidden family — Helvetica/Arial are system fonts.- expect(fontWarnings).toEqual([+ expect(fontNotices).toEqual([expect.stringContaining('Font "Rubik Doodle"'),]);+ expect(result?.data.warnings).toEqual([]);});it('warns about nothing when every named family is a generic or known system font', async () => {@@ -126,10 +134,11 @@ describe('themeBuild() — font-loading warnings in the receipt', () => {const result = await themeBuild('sys.mjs', {}, {cwd: tmpDir});expect(result?.type).toBe('theme.build');+ expect(result?.data.notices).toEqual([]);expect(result?.data.warnings).toEqual([]);});- it('stays silent under the default noopLogger even when font warnings fire', async () => {+ it('stays silent under the default noopLogger even when font notices fire', async () => {fs.writeFileSync(path.join(tmpDir, 'loud.mjs'),`export default { name: 'loud', tokens: { '--font-family-body': '"Orbitron", sans-serif' } };\n`,@@ -144,7 +153,7 @@ describe('themeBuild() — font-loading warnings in the receipt', () => {try {const result = await themeBuild('loud.mjs', {}, {cwd: tmpDir});- expect(result?.data.warnings).toEqual(+ expect(result?.data.notices).toEqual(expect.arrayContaining([expect.stringContaining('Font "Orbitron"')]),);expect(logSpy).not.toHaveBeenCalled();diff --git a/packages/cli/api/theme/build/build.mjs b/packages/cli/api/theme/build/build.mjsindex b2991d1a77..1933163f95 100644--- a/packages/cli/api/theme/build/build.mjs+++ b/packages/cli/api/theme/build/build.mjs@@ -1114,6 +1114,8 @@ export async function themeBuild(// Validate component overridesconst warnings = await validateComponentOverrides(themeDef);const warningMessages = [];+ /** Advisories about a correct theme — see the `notices` note on the receipt. */+ const noticeMessages = [];for (const w of warnings) {warningMessages.push(w);logger.warn(` ⚠ ${w}`);@@ -1412,11 +1414,18 @@ Or with a <link> tag:// Fonts the theme names but nothing loads (#5015). Resolved tokens and// component overrides carry the final font-family values on both load// paths, so this sees jiti-resolved and legacy themes alike.+ //+ // A NOTICE, not a warning: naming a font a theme file cannot load is how+ // the API is meant to be used — Astryx sets `--font-family-*` and loading+ // is the app's job, which no theme can do for it. So this fires on any+ // theme with a webfont, including a perfect one, and as a warning it made+ // every such build read as defective (it also put the shipped template+ // permanently in violation of its own "compiles with no warnings" guard).const unloadedFonts = collectUnloadedFonts(resolvedTheme);for (const family of unloadedFonts) {const msg = `Font "${family}" is named by this theme but not loaded — add a <link> or @font-face in your app (recipe: astryx docs typography)`;- warningMessages.push(msg);- logger.warn(` ⚠ ${msg}`);+ noticeMessages.push(msg);+ logger.log(` note: ${msg}`);}if (unloadedFonts.length > 0) {logger.log(formatFontLoadingHelp(themeDef.name, unloadedFonts));@@ -1438,6 +1447,7 @@ Or with a <link> tag:: {}),},warnings: warningMessages,+ notices: noticeMessages,},};}diff --git a/packages/cli/api/theme/build/build.test.mjs b/packages/cli/api/theme/build/build.test.mjsindex 47b469d20f..3cb722c2f4 100644--- a/packages/cli/api/theme/build/build.test.mjs+++ b/packages/cli/api/theme/build/build.test.mjs@@ -299,11 +299,10 @@ describe('themeBuild() — component override validation', () => {describe('themeBuild() — the shipped theme template', () => {// `assets/theme.template.ts` is what `astryx theme template` puts in a// consumer's project. It is the one theme file we hand out, so it has to- // compile as shipped — and cleanly apart from the font warnings it earns on- // purpose: a template that greets its first reader with warnings teaches them- // to ignore warnings. The claims its comments make are checked separately by- // scripts/check-theme-template.test.mjs.- it('compiles as shipped, warning only about the fonts it deliberately names', async () => {+ // compile as shipped — and cleanly: a template that greets its first reader+ // with warnings teaches them to ignore warnings. The claims its comments make+ // are checked separately by scripts/check-theme-template.test.mjs.+ it('compiles as shipped, with no warnings', async () => {const src = path.resolve(import.meta.dirname,'../../../assets/theme.template.ts',@@ -312,14 +311,12 @@ describe('themeBuild() — the shipped theme template', () => {const result = await themeBuild('theme.template.ts', {}, {cwd: tmpDir});- // The template names Inter and Geist Mono to teach "SHIP THE FONTS YOU- // NAME", and loads neither — so the unloaded-font warning firing here is- // the lesson landing, not a defect. Any OTHER warning still fails.- const unexpected = (result?.data.warnings ?? []).filter(- w => !/^Font "(Inter|Geist Mono)" is named by this theme but not loaded/.test(w),- );- expect(unexpected).toEqual([]);- expect(result?.data.warnings).toHaveLength(2);+ expect(result?.data.warnings).toEqual([]);+ // It DOES name Inter and Geist Mono without loading them, to teach "SHIP+ // THE FONTS YOU NAME" — advisories about a correct file, which is why they+ // are notices. Asserted here so moving them out of `warnings` cannot+ // quietly become dropping them.+ expect(result?.data.notices).toHaveLength(2);expect(fs.existsSync(path.join(tmpDir, 'my-theme.css'))).toBe(true);// The template teaches custom variants; the augmentation it promises the// reader has to actually be generated.diff --git a/packages/cli/api/theme/theme.type.mjs b/packages/cli/api/theme/theme.type.mjsindex 5b2f9b71d3..fd84d60232 100644--- a/packages/cli/api/theme/theme.type.mjs+++ b/packages/cli/api/theme/theme.type.mjs@@ -22,7 +22,10 @@* xds --json theme build <file>* @typedef {object} ThemeBuildResponse* @property {'theme.build'} type- * @property {{name: string, tokenCount: number, componentCount: number, sizeKB: number, outputs: {css: string, js: string, dts: string, variantsDts?: string}, warnings: string[]}} data+ * `warnings` are defects the theme author should fix. `notices` are advisories+ * about a correct theme — most of them cannot be fixed in a theme file at all,+ * so folding them into `warnings` makes a clean build look dirty.+ * @property {{name: string, tokenCount: number, componentCount: number, sizeKB: number, outputs: {css: string, js: string, dts: string, variantsDts?: string}, warnings: string[], notices: string[]}} data*//**diff --git a/packages/cli/clients/cli/commands/build-theme.font-warning.test.mjs b/packages/cli/clients/cli/commands/build-theme.font-warning.test.mjsindex 0b60c29799..042afe4980 100644--- a/packages/cli/clients/cli/commands/build-theme.font-warning.test.mjs+++ b/packages/cli/clients/cli/commands/build-theme.font-warning.test.mjs@@ -75,13 +75,16 @@ describe('theme build font-loading warning', () => {expect(result.stdout).toContain('@font-face');expect(result.stdout).toContain('font-display: swap');expect(result.stdout).toContain('astryx docs typography');- // The one-line summaries follow the CLI's stream contract: warnings on- // stderr, like the override-validation warnings in the same build.- expect(result.stderr).toContain('Font "Space Grotesk"');- expect(result.stderr).toContain('Font "JetBrains Mono"');+ // The one-line summaries follow the CLI's stream contract. These are+ // NOTICES about a correct theme, not warnings, so they go to stdout with+ // the rest of the build's progress — stderr stays for the defects an+ // author has to fix.+ expect(result.stdout).toContain('note: Font "Space Grotesk"');+ expect(result.stdout).toContain('note: Font "JetBrains Mono"');+ expect(result.stderr).not.toContain('Font "');});- it('keeps --json stdout one valid envelope: warnings inside, snippet suppressed', async () => {+ it('keeps --json stdout one valid envelope: notices inside, snippet suppressed', async () => {const project = path.join(tmpDir, 'project');const themeFile = writeTheme(project,@@ -100,7 +103,7 @@ describe('theme build font-loading warning', () => {// contract, not just substring presence.const envelope = JSON.parse(result.stdout);expect(envelope.type).toBe('theme.build');- expect(envelope.data.warnings).toEqual(+ expect(envelope.data.notices).toEqual(expect.arrayContaining([expect.stringContaining('Font "Space Grotesk"')]),);expect(result.stdout).not.toContain('fonts.googleapis.com');