auditing-registry-consistency

name	auditing-registry-consistency
description	Use when auditing the shuip registry for accumulated drift, silent failures, or convention violations — before a release, after a refactor or merge, when a newly added item doesn't appear in the build, or when a consumer reports `shadcn add` fetching incomplete files.

Auditing Registry Consistency

Overview

The shuip registry has many implicit conventions (folder layout, import paths, per-category doc flow, catalog pinning) that the generator enforces only loosely. Several failure modes are silent — items skipped without errors, dead symlinks fumadocs doesn't read, path mappings that work in IDE but not at build, deps silently dropped from registryDependencies. This skill is a systematic audit pass that catches them.

CLAUDE.md has the layout reference; the creating-registry-item skill has the procedure for creating items. This one catches drift in what already exists.

Do not auto-fix during the audit. Surface findings grouped by severity, let the human triage. Auto-fixing conflates discovery with remediation and may erase context the human needs.

When to Use

• Before tagging a release
• After a merge that touched the registry, the generator, or path mappings
• When a new item silently fails to appear in registry.json or on the docs site
• When a consumer reports a broken install (shadcn add fetches incomplete files)
• After bulk renames, category moves, or workspace restructures
• Periodic hygiene pass

Procedure

Run each check, capture findings, report at the end. Don't fix mid-audit — the act of running bun registry:generate mid-pass cleans up some inconsistencies before you've recorded them.

1. Items missing component.tsx — silent skip

Generator logs [generate] skipping <cat>/<name>: no component.tsx and the item never reaches registry.json. Catches wrong-case (Component.tsx), missing file, or stub-only folders.

find packages/registry/items -mindepth 2 -maxdepth 2 -type d \
  ! -exec test -e {}/component.tsx \; -print

2. Blocks with stray index.mdx — wrong fumadocs collection

Block items should not contain index.mdx. Their docs are hand-written in apps/docs/content/blocks/<name>.mdx (separate fumadocs collection). A stray index.mdx makes the generator symlink to apps/docs/content/docs/blocks/, which then shows as a duplicate page under /docs/blocks/<name> while the canonical /blocks/<name> keeps the real version.

ls packages/registry/items/blocks/*/index.mdx 2>/dev/null

3. component.tsx shuip-internal imports that silently drop

parseShuipDeps (packages/registry/scripts/generate.ts) auto-detects @/components/ui/shuip/<...> imports into registryDependencies:

• One segment (side-dialog) → the bare components-category item.
• Two segments (tanstack-form/form-context) → the prefixed item (tsf-form-context), only if the first segment is a real category (isCategory).

So a stub import does not need a meta.shuip.json — it resolves automatically. meta.shuip.json with dependsOn is only for a dependency that is not expressed as a stub import (a transitive/runtime dep). The actual silent-failure modes to look for:

• a two-segment import whose category segment isn't one of components / blocks / react-hook-form / tanstack-form / tanstack-query → silently dropped, consumer install missing the dep;
• a one-segment import to a components item that doesn't exist → dangling registryDependency.

# List shuip-internal imports; eyeball each category segment + target item against items/
grep -rn "from '@/components/ui/shuip/" packages/registry/items/*/*/component.tsx

responsive-dialog (dependsOn: ["side-dialog"]) is the canonical meta.shuip.json example — note its dependsOn is now redundant with the single-segment auto-detection, but harmless (the generator dedups). Reach for dependsOn only when the dep isn't an import.

4. Examples with relative ./component imports

Examples must import via the stub alias (@/components/ui/shuip/<cat-subdir>/<name>) so the preview exercises the same path consumers will use after shadcn add. Relative imports compile locally but never test the install path.

grep -rn "from '\./component'" packages/registry/items/

5. Folder names with rhf- / tsf- / tsq- prefix

The generator adds the prefix from the CATEGORIES map (packages/registry/scripts/generate.ts). Manual prefixing produces rhf-rhf-foo.

ls packages/registry/items/react-hook-form/ | grep '^rhf-' || echo OK
ls packages/registry/items/tanstack-form/ | grep '^tsf-' || echo OK
ls packages/registry/items/tanstack-query/ | grep '^tsq-' || echo OK

6. tsconfig path-mapping hygiene

Two checks. (a) Mappings present in packages/registry/tsconfig.json but missing from apps/docs/tsconfig.json (or vice versa) break either IDE resolution or the docs build. (b) Mapping targets pointing to files that no longer exist.

# (a) Drift between the two tsconfigs (ignore the docs-only @/* and fumadocs-mdx aliases)
diff <(jq -r '.compilerOptions.paths | keys[]' apps/docs/tsconfig.json | sort) \
     <(jq -r '.compilerOptions.paths | keys[]' packages/registry/tsconfig.json | sort)

# (b) Targets that don't exist (run from packages/registry/)
# Note: alias targets omit the file extension (e.g. @/lib/utils -> ../ui/src/lib/utils,
# the real file is utils.ts), so match both the bare path and any extension variant.
cd packages/registry && \
  jq -r '.compilerOptions.paths | to_entries[] | "\(.key)\t\(.value[0])"' tsconfig.json | \
  while IFS=$'\t' read -r alias target; do
    base="${target%/\*}"
    [ -e "$base" ] || ls "$base".* >/dev/null 2>&1 || echo "stale: $alias -> $target"
  done

7. Broken / stale symlinks in apps/docs/content/docs/

After a rename or category move, the old symlink isn't auto-removed. Symlink targets that no longer exist cause fumadocs to render an empty doc or a build failure depending on collection wiring.

find apps/docs/content/docs -type l ! -exec test -e {} \; -print

8. 'use client' missing where required

Components using useState/useEffect/useRef/useCallback/useMemo/any use<X> hook (including useTheme, useFormContext) must declare 'use client' or they break in Server Component contexts (the App Router default). This check needs manual triage — many client hooks come from Radix transitively where the directive isn't needed.

for f in $(find packages/registry/items -name component.tsx); do
  if grep -q "useState\|useEffect\|useRef\|useCallback\|useMemo\|useTheme\|useFormContext" "$f"; then
    head -1 "$f" | grep -q "'use client'" || echo "missing 'use client': $f"
  fi
done

9. Item completeness

For each item: should have default.example.tsx, should have at least one variant example, and should have index.mdx (unless it's a block, in which case the doc lives in apps/docs/content/blocks/).

# Missing default.example.tsx
find packages/registry/items -mindepth 2 -maxdepth 2 -type d \
  ! -exec test -e {}/default.example.tsx \; -print

# Non-block items missing index.mdx
find packages/registry/items -mindepth 2 -maxdepth 2 -type d \
  ! -path '*/blocks/*' ! -exec test -e {}/index.mdx \; -print

# Items with only one example (default, no variant)
for d in $(find packages/registry/items -mindepth 2 -maxdepth 2 -type d); do
  count=$(ls "$d"/*.example.tsx 2>/dev/null | wc -l)
  [ "$count" -le 1 ] && echo "single example: $d"
done

10. MDX prose using the wrong stub path

The creating-registry-item skill says examples must use the stub alias matching the item's category subdir (react-hook-form/, tanstack-form/, tanstack-query/, or none for components). MDX prose snippets often copy-paste the bare @/components/ui/shuip/<name> and miss the subdir — leading copy-paste users to module-not-found.

# RHF / TSF / TSQ items whose MDX uses the bare path
for f in $(find packages/registry/items/react-hook-form packages/registry/items/tanstack-form packages/registry/items/tanstack-query -name index.mdx 2>/dev/null); do
  cat=$(echo "$f" | sed 's|.*items/\([^/]*\)/.*|\1|')
  grep "from '@/components/ui/shuip/" "$f" | grep -v "$cat" \
    && echo "  ^ in $f (should include /$cat/)"
done

11. Workspace deps not pinned through catalogs

Catalog drift between workspaces breaks reproducibility and may cause subtle version mismatches at consumer end. Every shared external dep should be "catalog:" or "catalog:<name>".

for pkg in apps/*/package.json packages/*/package.json; do
  jq -r '. as $p | (.dependencies // {}) + (.devDependencies // {}) | to_entries[] | "\($p.name)\t\(.key)\t\(.value)"' "$pkg"
done | grep -v 'catalog:\|workspace:\|^[^\t]*\t[^\t]*\t[0-9]' | grep -v 'biome\|husky\|knip\|portless\|rimraf\|turbo\|typescript\|@types/node\|@vercel\|shadcn' || echo OK

(Some root-tools — biome, husky, knip, turbo, typescript, etc. — are intentionally not in catalogs because they're devtools, not shared libs. Adjust the exclusion list to taste.)

12. turbo.json task outputs cover all generator side effects

generate.ts writes to packages/registry/{registry.json,__index__.ts,stubs/**} AND to apps/docs/content/docs/<cat>/<name>.mdx (symlinks) AND to apps/docs/content/docs/<cat>/.gitignore. Turbo's registry:generate task declares only the first set in its outputs, so a cache hit on this task leaves the cross-workspace side effects unrestored — on a fresh checkout, fumadocs may see no MDX in per-category folders and 404 docs pages.

jq '.tasks["registry:generate"].outputs' turbo.json

Expected: every path the generator writes is either declared as an output OR the task has "cache": false. Today the cross-workspace symlinks/.gitignore are not declared. Cross-workspace outputs is awkward in turbo; setting "cache": false on the task is the smaller honest fix.

13. index.mdx registryName frontmatter matches the prefixed folder name

Each non-block item's index.mdx has frontmatter registryName: <prefixed-name>. The value must match what the generator produces for that folder (i.e., <prefix>-<folder-name> for react-hook-form / tanstack-form / tanstack-query, or the bare folder name for components). A mismatch means <ItemExamples registryName={...}/> looks up the wrong key in REGISTRY_INDEX and renders an empty preview.

for f in $(find packages/registry/items -name index.mdx); do
  declared=$(grep -m1 '^registryName:' "$f" | sed 's/^registryName:[[:space:]]*//; s/[[:space:]]*$//')
  folder=$(echo "$f" | sed 's|.*items/\([^/]*\)/\([^/]*\)/index.mdx|\1\t\2|')
  cat=$(echo "$folder" | cut -f1); name=$(echo "$folder" | cut -f2)
  case "$cat" in
    react-hook-form) expected="rhf-$name" ;;
    tanstack-form) expected="tsf-$name" ;;
    tanstack-query) expected="tsq-$name" ;;
    *) expected="$name" ;;
  esac
  [ "$declared" = "$expected" ] || echo "mismatch: $f declared=$declared expected=$expected"
done

Reporting

Group findings by severity. For each:

• File path or pattern
• What's wrong, what it silently breaks
• Suggested fix (don't apply it — surface only)

Sample shape:

CRITICAL
  packages/registry/items/components/foo/Component.tsx
    Generator skips the folder (filename must be lowercase).
    Fix: rename to component.tsx.

WARNING
  packages/registry/items/components/bar/
    Missing default.example.tsx; docs page renders empty <ItemExamples>.
    Fix: add default.example.tsx importing via the stub alias.

Common Mistakes During the Audit

Mistake	Why it matters
Running bun registry:generate before recording findings	Generator may rewrite the .gitignore lists or clear stale stubs before you've inspected them. Inspect first, regen after.
Treating [generate] skipping ... as benign	That warning means an item is invisible. Always investigate.
Trusting git status to surface drift in generated files	registry.json, __index__.ts, stubs/ are gitignored. Read the file contents directly.
Auto-fixing during the audit	Conflates discovery with triage. Many "findings" turn out to be intentional once context is added.
Reporting only the file path	Include the silent-failure mode (what breaks, not just "X is wrong"). Pelavo triages by impact.

Red Flags

If any of these are true during a build / dev session, run this audit:

• [generate] N items processed returned a smaller N than expected after adding files
• A consumer reports a missing file after shadcn add
• A docs page renders blank previews or 404s the preview iframe
• A merge / rebase touched packages/registry/items/, packages/registry/scripts/generate.ts, turbo.json, or any tsconfig
• A new category was added but only one of apps/docs/tsconfig.json and packages/registry/tsconfig.json got the new mapping