Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

fix(cli): resolve component and hook names case-exactly on case-insensitive filesystems (#5478)

Cindy Zhang553b07f126c1
diff --git a/.changeset/cli-case-exact-name-resolution.md b/.changeset/cli-case-exact-name-resolution.md
new file mode 100644
index 0000000000..b9825a7b48
--- /dev/null
+++ b/.changeset/cli-case-exact-name-resolution.md
@@ -0,0 +1,19 @@
+---
+'@astryxdesign/cli': patch
+---
+
+[fix] Component and hook names resolve case-exactly on macOS and Windows, matching Linux
+
+`findComponentReadme`, `findComponentSource` and `findHookDoc` probed candidate
+paths with `fs.existsSync`, which answers through the filesystem's own case
+folding. On a case-insensitive filesystem `astryx component button` resolved to
+`Button` instead of reporting an unknown component with suggestions, and
+`findHookDoc(core, 'mediaquery')` returned `.../hooks/useMediaquery.doc.mjs` — a
+spelling that exists nowhere, and that breaks any consumer reading it on Linux.
+The probes now verify each path segment against its parent's real directory
+listing, so these component and hook lookups resolve the same names to the
+same real paths on every host. The
+deliberate case-insensitive hook lookup is unchanged; it now returns the file's
+true casing.
+
+@cixzhang
diff --git a/packages/cli/foundation/discovery/component-discovery.mjs b/packages/cli/foundation/discovery/component-discovery.mjs
index caf99d8e80..0cf9e832ba 100644
--- a/packages/cli/foundation/discovery/component-discovery.mjs
+++ b/packages/cli/foundation/discovery/component-discovery.mjs
@@ -6,6 +6,7 @@
import * as fs from 'node:fs';
import * as path from 'node:path';
+import {existsCaseExact} from '../fs/paths.mjs';
const SKIP_DIRS = new Set(['hooks', 'utils', '__tests__', 'node_modules']);
@@ -243,27 +244,27 @@ export function findComponentReadme(coreDir, name) {
// Direct match: src/{name}/{Name}.doc.mjs or src/{name}/Astryx{Name}.doc.mjs
const direct = path.join(srcDir, name, exactDoc);
- if (fs.existsSync(direct)) return direct;
+ if (existsCaseExact(direct, srcDir)) return direct;
const directXds = path.join(srcDir, name, xdsDoc);
- if (fs.existsSync(directXds)) return directXds;
+ if (existsCaseExact(directXds, srcDir)) return directXds;
// Nested match: src/*/{name}/{Name}.doc.mjs or src/*/{name}/Astryx{Name}.doc.mjs
const entries = fs.readdirSync(srcDir, {withFileTypes: true});
for (const entry of entries) {
if (!entry.isDirectory()) continue;
const nested = path.join(srcDir, entry.name, name, exactDoc);
- if (fs.existsSync(nested)) return nested;
+ if (existsCaseExact(nested, srcDir)) return nested;
const nestedXds = path.join(srcDir, entry.name, name, xdsDoc);
- if (fs.existsSync(nestedXds)) return nestedXds;
+ if (existsCaseExact(nestedXds, srcDir)) return nestedXds;
}
// Per-component doc in a parent directory: src/*/{Name}.doc.mjs or src/*/Astryx{Name}.doc.mjs
for (const entry of entries) {
if (!entry.isDirectory()) continue;
const perComp = path.join(srcDir, entry.name, exactDoc);
- if (fs.existsSync(perComp)) return perComp;
+ if (existsCaseExact(perComp, srcDir)) return perComp;
const perCompXds = path.join(srcDir, entry.name, xdsDoc);
- if (fs.existsSync(perCompXds)) return perCompXds;
+ if (existsCaseExact(perCompXds, srcDir)) return perCompXds;
}
// Sub-component fallback: find the source file, then walk up
@@ -321,7 +322,7 @@ export function findComponentSource(coreDir, name) {
// Check for an exact match (prefixed or bare) first
for (const candidate of candidateFiles) {
const exact = path.join(dirPath, candidate);
- if (fs.existsSync(exact)) return exact;
+ if (existsCaseExact(exact, dirPath)) return exact;
}
// Recurse into subdirectories
@@ -336,7 +337,7 @@ export function findComponentSource(coreDir, name) {
// Search in the component's directory
const directDir = path.join(srcDir, name);
- if (fs.existsSync(directDir)) {
+ if (existsCaseExact(directDir, srcDir)) {
const found = searchDir(directDir);
if (found) return found;
}
@@ -346,7 +347,7 @@ export function findComponentSource(coreDir, name) {
for (const entry of entries) {
if (!entry.isDirectory()) continue;
const nestedDir = path.join(srcDir, entry.name, name);
- if (fs.existsSync(nestedDir)) {
+ if (existsCaseExact(nestedDir, srcDir)) {
const found = searchDir(nestedDir);
if (found) return found;
}
diff --git a/packages/cli/foundation/discovery/hook-discovery.mjs b/packages/cli/foundation/discovery/hook-discovery.mjs
index f5ef1b3626..e3f02dc13e 100644
--- a/packages/cli/foundation/discovery/hook-discovery.mjs
+++ b/packages/cli/foundation/discovery/hook-discovery.mjs
@@ -6,6 +6,7 @@
import * as fs from 'node:fs';
import * as path from 'node:path';
+import {existsCaseExact} from '../fs/paths.mjs';
import {levenshteinDistance} from '../text/string-utils.mjs';
const SKIP_DIRS = new Set(['utils', '__tests__', 'node_modules']);
@@ -157,7 +158,7 @@ export function findHookDoc(coreDir, name) {
// 1. Check src/hooks/{name}.doc.mjs first
for (const candidate of uniqueCandidates) {
const direct = path.join(hooksDir, `${candidate}.doc.mjs`);
- if (fs.existsSync(direct)) return direct;
+ if (existsCaseExact(direct, hooksDir)) return direct;
}
// 2. Case-insensitive search in hooks directory
diff --git a/packages/cli/foundation/fs/paths.mjs b/packages/cli/foundation/fs/paths.mjs
index fa1a510bec..1f1c604ccc 100644
--- a/packages/cli/foundation/fs/paths.mjs
+++ b/packages/cli/foundation/fs/paths.mjs
@@ -160,3 +160,39 @@ export function listComponents(coreDir) {
.map(e => e.name)
.sort();
}
+
+/**
+ * Does `targetPath` exist with EXACTLY this spelling?
+ *
+ * `fs.existsSync` answers through the filesystem's own case folding, so on
+ * macOS and Windows a probe for `src/button/Button.doc.mjs` succeeds against
+ * the real `src/Button/Button.doc.mjs`. Name resolvers built on that probe
+ * then resolve a component or hook the caller never named, and hand back a
+ * path spelled the way the caller typed it — a path that does not exist on
+ * Linux, where the same lookup correctly misses. Every segment below
+ * `rootDir` is checked against its parent's real directory listing.
+ *
+ * @param {string} targetPath - Path to probe; must be inside `rootDir`.
+ * @param {string} rootDir - Already-real path; it and its parents are not checked.
+ * @returns {boolean}
+ */
+export function existsCaseExact(targetPath, rootDir) {
+ if (!fs.existsSync(targetPath)) return false;
+
+ const rel = path.relative(rootDir, targetPath);
+ if (rel === '') return true;
+ if (path.isAbsolute(rel) || rel === '..' || rel.startsWith(`..${path.sep}`)) return false;
+
+ let dir = rootDir;
+ for (const segment of rel.split(path.sep)) {
+ let entries;
+ try {
+ entries = fs.readdirSync(dir);
+ } catch {
+ return false;
+ }
+ if (!entries.includes(segment)) return false;
+ dir = path.join(dir, segment);
+ }
+ return true;
+}
diff --git a/packages/cli/foundation/fs/paths.test.mjs b/packages/cli/foundation/fs/paths.test.mjs
index f1ba130268..cf7a55574f 100644
--- a/packages/cli/foundation/fs/paths.test.mjs
+++ b/packages/cli/foundation/fs/paths.test.mjs
@@ -4,7 +4,7 @@ import {describe, it, expect, beforeEach, afterEach} from 'vitest';
import * as fs from 'node:fs';
import * as path from 'node:path';
import * as os from 'node:os';
-import {findCoreDir, findProjectRoot, listComponents, discoverExternalPackages} from './paths.mjs';
+import {findCoreDir, findProjectRoot, listComponents, discoverExternalPackages, existsCaseExact} from './paths.mjs';
let tmpDir;
@@ -209,3 +209,31 @@ describe('listComponents', () => {
expect(listComponents(tmpDir)).toEqual([]);
});
});
+
+describe('existsCaseExact', () => {
+ it('accepts the real spelling and rejects a case variant of the file', () => {
+ fs.writeFileSync(path.join(tmpDir, 'Button.doc.mjs'), '');
+
+ expect(existsCaseExact(path.join(tmpDir, 'Button.doc.mjs'), tmpDir)).toBe(true);
+ expect(existsCaseExact(path.join(tmpDir, 'button.doc.mjs'), tmpDir)).toBe(false);
+ expect(existsCaseExact(path.join(tmpDir, 'BUTTON.DOC.MJS'), tmpDir)).toBe(false);
+ });
+
+ it('checks every segment below the root, not just the basename', () => {
+ const dir = path.join(tmpDir, 'src', 'Button');
+ fs.mkdirSync(dir, {recursive: true});
+ fs.writeFileSync(path.join(dir, 'Button.doc.mjs'), '');
+
+ expect(existsCaseExact(path.join(tmpDir, 'src', 'Button', 'Button.doc.mjs'), tmpDir)).toBe(true);
+ expect(existsCaseExact(path.join(tmpDir, 'src', 'button', 'Button.doc.mjs'), tmpDir)).toBe(false);
+ });
+
+ it('returns false for a missing path, and true for the root itself', () => {
+ expect(existsCaseExact(path.join(tmpDir, 'nope.mjs'), tmpDir)).toBe(false);
+ expect(existsCaseExact(tmpDir, tmpDir)).toBe(true);
+ });
+
+ it('refuses a target outside the root', () => {
+ expect(existsCaseExact(os.tmpdir(), tmpDir)).toBe(false);
+ });
+});