fix(brand): detect token sources under unlisted CSS filenames (#523)

The overwrite guard added in #501 scans a hardcoded list of CSS entry points
for `:root` custom properties and Tailwind v4 `@theme` blocks. The list only
held the plural `globals.css` spellings, so a project whose entry point is
`src/styles/global.css` — one letter apart — was never scanned. The guard
silently passed and `assets/design-tokens.{json,css}` was generated alongside
an existing palette, leaving two competing token systems and no warning.

Copying the same file to `src/index.css` made the guard fire correctly, which
confirms the detection logic was fine and only its candidate set was too narrow.

Widen the list with the singular spellings and `main.css` / `app.css`, then
shallow-scan a set of conventional style directories for any `*.css` so the
guard no longer depends on an exact filename. Detection itself is unchanged, so
the existing false-positive behaviour still holds: stylesheets with no custom
properties, commented-out `:root` blocks, and properties outside `:root` do not
block a sync.

Co-authored-by: Varrunan Projects <200937066+Varrunan-bit@users.noreply.github.com>
Co-authored-by: Claude <noreply@anthropic.com>
This commit is contained in:
Varrunan Projects 2026-10-11 07:05:22 +08:00 committed by GitHub
parent 50d8a7de09
commit 67803eac81
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
4 changed files with 182 additions and 2 deletions

View File

@ -20,14 +20,37 @@ const DESIGN_TOKENS_JSON = 'assets/design-tokens.json';
const DESIGN_TOKENS_CSS = 'assets/design-tokens.css';
const CSS_TOKEN_SOURCES = [
'src/index.css',
'src/main.css',
'src/app.css',
'src/global.css',
'src/globals.css',
'src/styles/global.css',
'src/styles/globals.css',
'src/styles/index.css',
'src/styles/main.css',
'src/styles/tokens.css',
'src/app/global.css',
'src/app/globals.css',
'app/global.css',
'app/globals.css',
'styles/global.css',
'styles/globals.css',
'styles/tokens.css'
];
// Directories shallow-scanned for any *.css that already declares tokens.
// A hardcoded filename list alone misses real projects by a single letter
// (e.g. styles/global.css vs styles/globals.css), which silently defeats the
// overwrite guard.
const CSS_SCAN_DIRS = [
'src',
'src/styles',
'src/css',
'src/assets/styles',
'app',
'app/styles',
'styles',
'css'
];
const TAILWIND_CONFIGS = [
'tailwind.config.js',
'tailwind.config.cjs',
@ -89,7 +112,23 @@ function findExistingTokenSources(projectRoot) {
addIfPresent(DESIGN_TOKENS_JSON);
addIfPresent(DESIGN_TOKENS_CSS);
for (const relativePath of CSS_TOKEN_SOURCES) {
const candidates = new Set(CSS_TOKEN_SOURCES);
for (const dir of CSS_SCAN_DIRS) {
const absoluteDir = path.resolve(projectRoot, dir);
let entries;
try {
entries = fs.readdirSync(absoluteDir, { withFileTypes: true });
} catch {
continue;
}
for (const entry of entries) {
if (entry.isFile() && entry.name.toLowerCase().endsWith('.css')) {
candidates.add(`${dir}/${entry.name}`);
}
}
}
for (const relativePath of candidates) {
const absolutePath = path.resolve(projectRoot, relativePath);
scanCssSource(absolutePath);
}

View File

@ -315,3 +315,54 @@ def test_force_allows_sync_with_existing_css_token_source(tmp_path):
assert result.returncode == 0, result.stderr + result.stdout
assert (tmp_path / "assets" / "design-tokens.json").exists()
@pytest.mark.parametrize(
"relative_path",
[
"src/styles/global.css",
"src/global.css",
"src/main.css",
"src/styles/theme.css",
"styles/variables.css",
],
)
def test_refuses_token_source_under_unlisted_css_filename(tmp_path, relative_path):
"""Token detection must not hinge on an exact filename.
The candidate list only held the plural `globals.css` spellings, so a
project whose entry point is `src/styles/global.css` — one letter apart —
was never scanned and the guard silently passed, leaving the generated
`assets/design-tokens.*` to compete with an existing palette.
"""
(tmp_path / "docs").mkdir()
shutil.copy(BRAND_STARTER, tmp_path / "docs" / "brand-guidelines.md")
css = tmp_path / relative_path
css.parent.mkdir(parents=True, exist_ok=True)
css.write_text(":root {\n --dawn: #f5a524;\n --ink: #1c1626;\n}\n")
result = _run(tmp_path)
assert result.returncode == 1, result.stdout + result.stderr
assert relative_path in result.stderr
assert "--force" in result.stderr
assert not (tmp_path / "assets" / "design-tokens.json").exists()
def test_discovered_css_without_tokens_does_not_block_sync(tmp_path):
"""Scanning extra CSS files must not introduce false positives.
Plain stylesheets carry no custom properties, so they are not token
sources and must leave the sync path alone.
"""
(tmp_path / "docs").mkdir()
shutil.copy(BRAND_STARTER, tmp_path / "docs" / "brand-guidelines.md")
styles = tmp_path / "src" / "styles"
styles.mkdir(parents=True)
(styles / "global.css").write_text(".btn {\n color: red;\n}\n")
(styles / "reset.css").write_text("* {\n margin: 0;\n}\n")
result = _run(tmp_path)
assert result.returncode == 0, result.stderr + result.stdout
assert (tmp_path / "assets" / "design-tokens.json").exists()

View File

@ -20,14 +20,37 @@ const DESIGN_TOKENS_JSON = 'assets/design-tokens.json';
const DESIGN_TOKENS_CSS = 'assets/design-tokens.css';
const CSS_TOKEN_SOURCES = [
'src/index.css',
'src/main.css',
'src/app.css',
'src/global.css',
'src/globals.css',
'src/styles/global.css',
'src/styles/globals.css',
'src/styles/index.css',
'src/styles/main.css',
'src/styles/tokens.css',
'src/app/global.css',
'src/app/globals.css',
'app/global.css',
'app/globals.css',
'styles/global.css',
'styles/globals.css',
'styles/tokens.css'
];
// Directories shallow-scanned for any *.css that already declares tokens.
// A hardcoded filename list alone misses real projects by a single letter
// (e.g. styles/global.css vs styles/globals.css), which silently defeats the
// overwrite guard.
const CSS_SCAN_DIRS = [
'src',
'src/styles',
'src/css',
'src/assets/styles',
'app',
'app/styles',
'styles',
'css'
];
const TAILWIND_CONFIGS = [
'tailwind.config.js',
'tailwind.config.cjs',
@ -89,7 +112,23 @@ function findExistingTokenSources(projectRoot) {
addIfPresent(DESIGN_TOKENS_JSON);
addIfPresent(DESIGN_TOKENS_CSS);
for (const relativePath of CSS_TOKEN_SOURCES) {
const candidates = new Set(CSS_TOKEN_SOURCES);
for (const dir of CSS_SCAN_DIRS) {
const absoluteDir = path.resolve(projectRoot, dir);
let entries;
try {
entries = fs.readdirSync(absoluteDir, { withFileTypes: true });
} catch {
continue;
}
for (const entry of entries) {
if (entry.isFile() && entry.name.toLowerCase().endsWith('.css')) {
candidates.add(`${dir}/${entry.name}`);
}
}
}
for (const relativePath of candidates) {
const absolutePath = path.resolve(projectRoot, relativePath);
scanCssSource(absolutePath);
}

View File

@ -315,3 +315,54 @@ def test_force_allows_sync_with_existing_css_token_source(tmp_path):
assert result.returncode == 0, result.stderr + result.stdout
assert (tmp_path / "assets" / "design-tokens.json").exists()
@pytest.mark.parametrize(
"relative_path",
[
"src/styles/global.css",
"src/global.css",
"src/main.css",
"src/styles/theme.css",
"styles/variables.css",
],
)
def test_refuses_token_source_under_unlisted_css_filename(tmp_path, relative_path):
"""Token detection must not hinge on an exact filename.
The candidate list only held the plural `globals.css` spellings, so a
project whose entry point is `src/styles/global.css` — one letter apart —
was never scanned and the guard silently passed, leaving the generated
`assets/design-tokens.*` to compete with an existing palette.
"""
(tmp_path / "docs").mkdir()
shutil.copy(BRAND_STARTER, tmp_path / "docs" / "brand-guidelines.md")
css = tmp_path / relative_path
css.parent.mkdir(parents=True, exist_ok=True)
css.write_text(":root {\n --dawn: #f5a524;\n --ink: #1c1626;\n}\n")
result = _run(tmp_path)
assert result.returncode == 1, result.stdout + result.stderr
assert relative_path in result.stderr
assert "--force" in result.stderr
assert not (tmp_path / "assets" / "design-tokens.json").exists()
def test_discovered_css_without_tokens_does_not_block_sync(tmp_path):
"""Scanning extra CSS files must not introduce false positives.
Plain stylesheets carry no custom properties, so they are not token
sources and must leave the sync path alone.
"""
(tmp_path / "docs").mkdir()
shutil.copy(BRAND_STARTER, tmp_path / "docs" / "brand-guidelines.md")
styles = tmp_path / "src" / "styles"
styles.mkdir(parents=True)
(styles / "global.css").write_text(".btn {\n color: red;\n}\n")
(styles / "reset.css").write_text("* {\n margin: 0;\n}\n")
result = _run(tmp_path)
assert result.returncode == 0, result.stderr + result.stdout
assert (tmp_path / "assets" / "design-tokens.json").exists()