Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions .changeset/doctor-one-mode-page-color.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
'@astryxdesign/cli': patch
---

[fix] `astryx doctor` now warns when the app's default theme needs its page color shown and nothing paints the page: a theme drawn for one mode (its text lands on the browser's own page color in the other OS mode), or a local theme that sets its own page color, different from its base's (the color chosen never shows). AppShell, a body background of the page color, or, for a one-mode theme, the theme's own mode on the root `Theme` paints it. Doctor warns only when it can prove nothing paints the page; anything it cannot read stays silent. A project that loads no Core reset is embedded in a page it does not own and gets no warning. The fix says to wrap the page in `AppShell`, or else to add `body { background: var(--color-background-body) }` to global CSS.

@josephfarina
21 changes: 19 additions & 2 deletions docs/specs/AST-050-app-themes/spec.md
Original file line number Diff line number Diff line change
Expand Up @@ -304,7 +304,24 @@ use` or `theme remove` on a theme that is not added MUST fail and name the
fix; the settings a file writes that says a tool generates it are one
note (info) per file instead, with their count and that tool; the
check passes only when every local theme's build check ran, and names
a local theme whose check did not run (info).
a local theme whose check did not run (info);
12. the default theme's page color is shown when the theme needs it: a
theme drawn for one mode (its page color dark in both modes, or light
in both), or a local theme that sets its own page color, different from
its base's. Doctor warns, never fails, only when it proves that nothing
paints the page: it reads the app's root `Theme` and the element it
wraps, and no `AppShell` renders, no `html`, `body` or `:root`
background and no root element background uses
`--color-background-body`, and, for a one-mode theme, the root `Theme`
takes no mode, or the other mode (its own mode, recorded or as a
literal, keeps the page readable; the other mode warns). Anything it cannot read (a class, StyleX, spread
props, a component it cannot follow, a value it cannot evaluate, a
preprocessor stylesheet, a page's own `<style>`, a CSS-in-JS global)
may paint the page, and gives no warning. The fix is to use `AppShell`; for a one-mode
theme, to give the root `Theme` the theme's mode; or to add
`body { background: var(--color-background-body) }` to global CSS.
A project that loads no Core reset is embedded in a page it does not
own, and gets no warning.

Each failure names the exact command that fixes it.

Expand Down Expand Up @@ -472,7 +489,7 @@ unchanged.
| FR7, FR8 | Integration verify and real provider-to-consumer tests | multi-theme package; single-theme package; missing export; font stylesheet missing from the tarball; stale build; a missing `.css.d.ts` stub only; a missing `.d.ts`; partial export set; a local theme sharing a package theme's slug; local themes in a project with no `src` folder; a module that loads its own styles; a theme whose name differs from its slug | A theme without a resolvable built module is imported, verify passes a stale complete pair, an unresolved export, or a module that adds more than its own stylesheet imports and a re-export of the built module, verify fails a partial export set whose exports resolve or a module that only loads its own styles, a shared slug imports the package theme without `--package`, the copying `theme add` resolves a local theme, or local themes are looked for outside `src/themes` |
| FR9 | Generated module tests | package and local themes | The module imports source |
| FR10 | List tests | added, default, bundled, package, local | A listed theme lacks its app fields |
| FR11 | Doctor tests, one planted fault per check | each of the eleven faults (the eleventh a warning, never a failure); a local theme whose build check did not run (info, never a pass); a correct app | A check passes on its fault, or passes without positive evidence |
| FR11 | Doctor tests, one planted fault per check | each of the twelve faults (the eleventh and twelfth warnings, never failures); a local theme whose build check did not run (info, never a pass); an app whose page paint doctor cannot read (no finding); a correct app | A check passes on its fault, or passes without positive evidence |
| FR11 | Provider wiring tests over a fixture integration that names its provider | a provider the app renders; one it only imports; a same-named component from another module; several themes, with and without an imported stylesheet; `theme list` text and JSON | A theme counts as wired without the app rendering its package's provider, `theme-management` offers `theme add` for a provider-wired theme, or `theme list` omits `wiredBy` |
| FR12 | Lifecycle tests against the latest stable CLI, migration tests on a project it made, and docs tests | plain `theme add`; the cleanup build; a copy made by the latest stable `theme add`; the upgrade codemod run twice; no theme module | Before the cleanup, plain `theme add` stops copying, changes its exit status, stdout, or `theme.add` fields, omits the deprecation id, or warns more than once; after it, plain `theme add` copies a theme given by its slug; a theme command or doctor fails on an unmigrated copy; the codemod changes more than the descriptor or changes anything on its second run; a copy is moved or deleted; or doctor fails a project with no theme module |
| FR13 | Docs and agent-docs tests | theme guide, integration guide, agent block, init next steps | A surface teaches copying as the way to use a theme other than a shared one (FR15), or names a different import command than the current lifecycle stage |
Expand Down
196 changes: 191 additions & 5 deletions packages/cli/api/doctor/_adapter.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -76,6 +76,7 @@ import {
} from '../../foundation/agent-docs/skill-place-files.mjs';
import {integrationSkillFiles} from '../docs/skills/skills.mjs';
import {builtinModules, createRequire} from 'node:module';
import {isOtherLanguageStylesheet} from '../../foundation/fs/stylesheet-file.mjs';
import {placeholderUses} from '../../foundation/discovery/template-icons.mjs';
import {
buttonsWithoutAction,
Expand All @@ -85,7 +86,10 @@ import {
specifierStem,
} from '../../foundation/discovery/button-actions.mjs';
import {iconImportFindings} from '../../foundation/discovery/icon-imports.mjs';
import {packageImportTarget} from '../../foundation/discovery/package-exports.mjs';
import {
conditionalExportTarget,
packageImportTarget,
} from '../../foundation/discovery/package-exports.mjs';
import {scanCoreProps} from '../../foundation/discovery/core-props.mjs';
import {readCorePropTypes} from '../../foundation/discovery/core-prop-types.mjs';
import {projectAugmentations} from '../../foundation/discovery/core-augmentation-points.mjs';
Expand All @@ -109,6 +113,8 @@ export {
} from '../../foundation/discovery/icon-set-discovery.mjs';
import {
elementPropOrigins,
outermostElements,
resolveLocalModule,
rendersElement,
} from '../../foundation/discovery/module-exports.mjs';
import {cssImports} from '../../foundation/render/embedded-imports.mjs';
Expand Down Expand Up @@ -319,16 +325,34 @@ const SOURCE_FILE_LIMIT = 5000;
* links. The doctor parses the returned bytes without executing app code.
* @param {string} root
* @param {string} generatedModule
* @param {{stylesheets?: boolean, pages?: boolean, markup?: boolean, outputAtRootsOnly?: boolean, skippedLinks?: string[]}} [options] - also list
* `.css` files, `.html` pages, and `.mdx` and `.astro` pages; with
* @param {{stylesheets?: boolean, pages?: boolean, markup?: boolean, outputAtRootsOnly?: boolean, skippedLinks?: string[], styleSources?: boolean}} [options] - also list
* `.css` files, `.html` pages, `.mdx` and `.astro` pages, and stylesheets
* a preprocessor compiles (every stylesheet language
* `foundation/fs/stylesheet-file.mjs` names besides CSS); with
* `outputAtRootsOnly`, skip a `build`, `dist` or `coverage` folder only in
* a folder with a package.json, where a build writes its output, and read
* one anywhere else (an app route named `build`); `skippedLinks` collects
* each linked folder or source file the walk does not follow
*/
export function listProjectSourceFiles(root, generatedModule, options = {}) {
return walkProjectSourceFiles(root, generatedModule, options).files;
}

/**
* The bounded app-source walk (see `listProjectSourceFiles`), with whether
* it read the whole project: `complete` is false when it stopped at its
* file limit with folders left unread.
* @param {string} root
* @param {string} generatedModule
* @param {Parameters<typeof listProjectSourceFiles>[2] & {unparsed?: RegExp}} [options]
* `unparsed`: files of a language the caller does not read, listed apart
* @returns {{files: string[], complete: boolean, unparsed: string[]}}
*/
export function walkProjectSourceFiles(root, generatedModule, options = {}) {
/** @type {string[]} */
const files = [];
/** The files `options.unparsed` matches, listed apart. @type {string[]} */
const unparsed = [];
/** @type {string[]} */
const queue = [root];
while (queue.length > 0 && files.length < SOURCE_FILE_LIMIT) {
Expand Down Expand Up @@ -370,13 +394,21 @@ export function listProjectSourceFiles(root, generatedModule, options = {}) {
path.extname(entry.name) === '.css') ||
(options.pages === true &&
/^\.html?$/u.test(path.extname(entry.name))) ||
(options.markup === true && MARKUP_PAGE.test(entry.name)))
(options.markup === true && MARKUP_PAGE.test(entry.name)) ||
(options.styleSources === true &&
isOtherLanguageStylesheet(entry.name)))
) {
files.push(file);
} else if (entry.isFile() && options.unparsed?.test(entry.name)) {
unparsed.push(file);
}
}
}
return files;
return {
files,
unparsed,
complete: queue.length === 0 && files.length < SOURCE_FILE_LIMIT,
};
}

/**
Expand Down Expand Up @@ -1196,6 +1228,75 @@ export function doctorElementPropOrigins(file, element) {
return elementPropOrigins(file, element);
}

/** @type {Promise<{parseColor: (value: unknown) => [number, number, number] | null, hex: (rgb: [number, number, number]) => string, luminance: (hex: string) => number}> | undefined} */
let colorReaders;

/**
* The shared color parser and luminance, loaded on first use: the editor's
* color module reads the bundled themes when it loads, which a plain import
* of the CLI's API must not pay for.
*/
export function doctorColorReaders() {
colorReaders ??= Promise.all([
import('../theme-edit/_color.mjs'),
import('../theme/palette/generate/color.mjs'),
]).then(([color, generate]) => ({
parseColor: /** @type {any} */ (color.parseColor),
hex: /** @type {any} */ (color.hex),
luminance: generate.luminance,
}));
return colorReaders;
}

/**
* The stylesheets an installed package ships, two folders deep, its own
* dependencies left out.
* @param {string} packageDir
* @returns {string[]}
*/
export function doctorPackageStylesheets(packageDir) {
/** @type {string[]} */
const out = [];
/** @param {string} folder @param {number} depth */
const read = (folder, depth) => {
let entries;
try {
entries = fs.readdirSync(folder, {withFileTypes: true});
} catch {
return;
}
for (const entry of entries) {
if (entry.name === 'node_modules') continue;
const file = path.join(folder, entry.name);
if (entry.isDirectory()) {
if (depth < 2) read(file, depth + 1);
} else if (entry.name.endsWith('.css')) out.push(file);
}
};
read(packageDir, 0);
return out.sort();
}

/**
* A relative import's file, as a bundler resolves it (see
* `resolveLocalModule`), or null.
* @param {string} specifier
* @param {string} fromFile
*/
export function doctorResolveLocalModule(specifier, fromFile) {
return resolveLocalModule(specifier, fromFile, {bundler: true});
}

/**
* Each outermost element a module renders, imported by name from a module,
* as its JSX element node (see `outermostElements`).
* @param {string} file
* @param {Parameters<typeof outermostElements>[1]} element
*/
export function doctorOutermostElements(file, element) {
return outermostElements(file, element);
}

/**
* The stylesheets the app's registered themes load, read from the theme
* module the CLI writes for them: an import of one is theme wiring, never
Expand Down Expand Up @@ -2045,3 +2146,88 @@ export async function readSkillPlaces(cwd) {
computerSkill: fs.existsSync(computerSkillFile()),
};
}

/**
* The file a bare package specifier resolves to from the project, as a
* bundler that reads stylesheets finds it (its exports map under the
* `style`, `import`, `default` and `require` conditions, else its `style`
* or `main` entry), or `''` when it does not resolve.
* @param {string} projectDir
* @param {string} spec
* @returns {string}
*/
export function doctorResolvePackageEntry(projectDir, spec) {
const name = /^(@[^/]+\/[^/]+|[^/]+)(.*)$/.exec(spec);
if (!name) return '';
const packageDir = findInstalledPackage(projectDir, name[1]);
if (!packageDir) return '';
/** @type {any} */
let pkg;
try {
pkg = JSON.parse(
fs.readFileSync(path.join(packageDir, 'package.json'), 'utf8'),
);
} catch {
return '';
}
const subpath = name[2] ? `.${name[2]}` : '.';
// (A bundler reads the exports map, a stylesheet's `style` condition
// first; without one, the `style` or `main` entry, or the file named.)
if (pkg?.exports !== undefined) {
const target = conditionalExportTarget(pkg.exports, subpath, [
'style',
'import',
'default',
'require',
]);
return target ? path.join(packageDir, target) : '';
}
if (subpath !== '.') return path.join(packageDir, name[2]);
return path.join(packageDir, pkg?.style ?? pkg?.main ?? 'index.js');
}

/**
* The strings of each JSON config at the project root (`angular.json`,
* `project.json`): a workspace config may list the stylesheets the build
* loads. The package manifest, its lockfile and TypeScript's configs list
* none.
* @param {string} projectDir
* @returns {Array<{file: string, strings: string[]}>}
*/
export function doctorRootConfigStrings(projectDir) {
/** @type {Array<{file: string, strings: string[]}>} */
const out = [];
let entries;
try {
entries = fs.readdirSync(projectDir, {withFileTypes: true});
} catch {
return out;
}
for (const entry of entries) {
if (!entry.isFile() || !/\.json$/i.test(entry.name)) continue;
if (
/^(?:package(?:-lock)?|tsconfig(?:\..*)?|jsconfig)\.json$/i.test(
entry.name,
)
)
continue;
const file = path.join(projectDir, entry.name);
try {
const text = fs.readFileSync(file, 'utf8');
if (text.length > 2_000_000) continue;
/** @type {string[]} */
const strings = [];
/** @param {unknown} v */
const visit = v => {
if (typeof v === 'string') strings.push(v);
else if (Array.isArray(v)) v.forEach(visit);
else if (v && typeof v === 'object') Object.values(v).forEach(visit);
};
visit(JSON.parse(text));
out.push({file, strings});
} catch {
// (Not JSON doctor can read: nothing listed.)
}
}
return out;
}
Loading
Loading