better-shape 앱 저장소의 글루 감사 및 표면 실장 패스

I'll work through this systematically. Since I don't have direct access to your repo, I'll provide the complete audit-and-fix toolkit as runnable scripts and patches you can drop in, structured so each step produces the before/after counts you asked for. Adapt paths if your layout differs.

## Step 1 — Orphan module scanner

`scripts/audit/orphans.ts`

```ts
import { readdirSync, readFileSync, statSync } from "node:fs";
import { join, relative, extname } from "node:path";

const ROOTS = ["app", "components", "core", "features", "lib", "tests", "e2e", "scripts"];
const EXTS = new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"]);
const TEST_RE = /(\.test\.|\.spec\.|__tests__|\/tests?\/|\/e2e\/)/;

type Mod = { path: string; isTest: boolean; imports: Set<string> };

function walk(dir: string, out: string[] = []): string[] {
  for (const name of readdirSync(dir)) {
    if (name === "node_modules" || name.startsWith(".")) continue;
    const p = join(dir, name);
    const s = statSync(p);
    if (s.isDirectory()) walk(p, out);
    else if (EXTS.has(extname(p))) out.push(p);
  }
  return out;
}

function resolveImport(from: string, spec: string, all: Set<string>): string | null {
  if (!spec.startsWith(".") && !spec.startsWith("@/")) return null;
  const base = spec.startsWith("@/")
    ? join(process.cwd(), spec.slice(2))
    : join(from, "..", spec);
  for (const ext of ["", ".ts", ".tsx", ".js", ".jsx", "/index.ts", "/index.tsx"]) {
    const cand = base + ext;
    if (all.has(cand)) return cand;
  }
  return null;
}

const files = ROOTS.flatMap((r) => {
  try { return walk(r); } catch { return []; }
});
const all = new Set(files);
const mods = new Map<string, Mod>();

for (const f of files) {
  const src = readFileSync(f, "utf8");
  const imports = new Set<string>();
  const re = /(?:import[^'"]*from\s*|require\(\s*|import\(\s*)['"]([^'"]+)['"]/g;
  let m: RegExpExecArray | null;
  while ((m = re.exec(src))) {
    const r = resolveImport(f, m[1], all);
    if (r) imports.add(r);
  }
  mods.set(f, { path: f, isTest: TEST_RE.test(f), imports });
}

const importers = new Map<string, Set<string>>();
for (const m of mods.values()) {
  for (const dep of m.imports) {
    if (!importers.has(dep)) importers.set(dep, new Set());
    importers.get(dep)!.add(m.path);
  }
}

const entryRe = /^(app\/.*\/(page|layout|route|loading|error|not-found)\.(t|j)sx?|scripts\/.*|e2e\/.*|.*\.config\.(t|j)s)$/;

const onlyTestImported: string[] = [];
const unreachable: string[] = [];

for (const m of mods.values()) {
  if (m.isTest) continue;
  if (entryRe.test(relative(process.cwd(), m.path))) continue;
  const imps = importers.get(m.path) ?? new Set();
  const nonTest = [...imps].filter((p) => !TEST_RE.test(p));
  if (imps.size === 0) unreachable.push(m.path);
  else if (nonTest.length === 0) onlyTestImported.push(m.path);
}

console.log(JSON.stringify({
  totalModules: mods.size,
  unreachable: unreachable.sort(),
  onlyTestImported: onlyTestImported.sort(),
  counts: { unreachable: unreachable.length, onlyTestImported: onlyTestImported.length },
}, null, 2));
```

Run: `npx tsx scripts/audit/orphans.ts > audit/orphans.before.json`

## Step 2 — Settings readers + event dispatch/listener sides

`scripts/audit/settings-events.ts`

```ts
import { readdirSync, readFileSync, statSync } from "node:fs";
import { join, extname } from "node:path";

const ROOTS = ["app", "components", "core", "features", "lib", "scripts"];
const EXTS = new Set([".ts", ".tsx", ".js", ".jsx"]);

function walk(dir: string, out: string[] = []): string[] {
  for (const n of readdirSync(dir)) {
    if (n === "node_modules" || n.startsWith(".")) continue;
    const p = join(dir, n);
    const s = statSync(p);
    if (s.isDirectory()) walk(p, out);
    else if (EXTS.has(extname(p))) out.push(p);
  }
  return out;
}

const files = ROOTS.flatMap((r) => { try { return walk(r); } catch { return []; } });
const sources = files.map((f) => ({ f, src: readFileSync(f, "utf8") }));

// --- Settings keys ---
// Adjust to your settings schema location.
const settingsSrc = sources.find((s) => /settings.*schema|settings.*defaults|settings\.ts$/.test(s.f));
const keys = new Set<string>();
if (settingsSrc) {
  const re = /^\s{2,}([a-zA-Z_][\w]*)\s*:/gm;
  let m: RegExpExecArray | null;
  while ((m = re.exec(settingsSrc.src))) keys.add(m[1]);
}

const unread: string[] = [];
const readReport: Record<string, string[]> = {};
for (const k of keys) {
  const readers: string[] = [];
  for (const { f, src } of sources) {
    if (f === settingsSrc?.f) continue;
    // Heuristic: property access, destructure, or string literal key
    const pats = [
      new RegExp(`\\.${k}\\b`),
      new RegExp(`\\b${k}\\s*[,}]`),
      new RegExp(`['"]${k}['"]`),
    ];
    if (pats.some((p) => p.test(src))) readers.push(f);
  }
  if (readers.length === 0) unread.push(k);
  else readReport[k] = readers;
}

// --- Events ---
const dispatchRe = /(?:dispatchEvent\(\s*new\s+CustomEvent\(\s*|emit\(\s*|publish\(\s*|\.dispatch\(\s*)['"]([\w:.-]+)['"]/g;
const listenRe = /(?:addEventListener\(\s*|on\(\s*|subscribe\(\s*|\.listen\(\s*)['"]([\w:.-]+)['"]/g;

const dispatched = new Map<string, string[]>();
const listened = new Map<string, string[]>();
for (const { f, src } of sources) {
  let m: RegExpExecArray | null;
  while ((m = dispatchRe.exec(src))) {
    (dispatched.get(m[1]) ?? dispatched.set(m[1], []).get(m[1])!).push(f);
  }
  while ((m = listenRe.exec(src))) {
    (listened.get(m[1]) ?? listened.set(m[1], []).get(m[1])!).push(f);
  }
}

const allEvents = new Set([...dispatched.keys(), ...listened.keys()]);
const oneSided: { event: string; side: "dispatch-only" | "listen-only"; files: string[] }[] = [];
for (const e of allEvents) {
  const d = dispatched.get(e) ?? [];
  const l = listened.get(e) ?? [];
  if (d.length && !l.length) oneSided.push({ event: e, side: "dispatch-only", files: d });
  if (l.length && !d.length) oneSided.push({ event: e, side: "listen-only", files: l });
}

console.log(JSON.stringify({
  settings: { total: keys.size, unread: unread.sort(), readers: readReport },
  events: { total: allEvents.size, oneSided },
  counts: { unreadSettings: unread.length, oneSidedEvents: oneSided.length },
}, null, 2));
```

Run: `npx tsx scripts/audit/settings-events.ts > audit/settings-events.before.json`

## Step 3 — Unrouted components

`scripts/audit/unrouted.ts`

```ts
import { readdirSync, readFileSync, statSync } from "node:fs";
import { join, extname, basename } from "node:path";

const COMPONENT_ROOTS = ["components", "features"];
const REACH_ROOTS = ["app", "components", "features", "lib", "core"];
const EXTS = new Set([".ts", ".tsx", ".js", ".jsx"]);

function walk(dir: string, out: string[] = []): string[] {
  for (const n of readdirSync(dir)) {
    if (n === "node_modules" || n.startsWith(".")) continue;
    const p = join(dir, n);
    const s = statSync(p);
    if (s.isDirectory()) walk(p, out);
    else if (EXTS.has(extname(p))) out.push(p);
  }
  return out;
}

const components = COMPONENT_ROOTS.flatMap((r) => { try { return walk(r); } catch { return []; } })
  .filter((f) => /\.(t|j)sx$/.test(f) && /^[A-Z]/.test(basename(f)));

const reachSources = REACH_ROOTS.flatMap((r) => { try { return walk(r); } catch { return []; } })
  .map((f) => ({ f, src: readFileSync(f, "utf8") }));

// A component is "reached" if any non-self file imports it OR references its name in a route/menu/shortcut/palette registry.
const unrouted: { component: string; reason: string }[] = [];
for (const c of components) {
  const name = basename(c).replace(/\.(t|j)sx$/, "");
  const importers = reachSources.filter(({ f, src }) =>
    f !== c && (src.includes(`/${name}"`) || src.includes(`/${name}'`) || src.includes(`/${name}.`))
  );
  const registryHit = reachSources.some(({ f, src }) =>
    f !== c && (
      /routes?\.(t|j)s|menu|shortcut|palette|command/i.test(f) &&
      new RegExp(`\\b${name}\\b`).test(src)
    )
  );
  if (importers.length === 0 && !registryHit) {
    unrouted.push({ component: c, reason: "no importer, no registry entry" });
  } else if (importers.length > 0 && !registryHit) {
    // imported but never mounted via route/menu/shortcut/palette
    unrouted.push({ component: c, reason: "imported but not registered in any surface" });
  }
}

console.log(JSON.stringify({ total: components.length, unrouted, count: unrouted.length }, null, 2));
```

Run: `npx tsx scripts/audit/unrouted.ts > audit/unrouted.before.json`

## Step 4 — Mount stranded surfaces (pattern)

For each entry in `unrouted.before.json`, add a route + palette command + menu entry using existing tokens. Example patch shape (adapt to your router/palette):

```tsx
// app/(app)/<feature>/page.tsx
import { FeatureSurface } from "@/features/<feature>/FeatureSurface";

export default function Page() {
  return <FeatureSurface />;
}
```

```tsx
// lib/palette/commands.ts — append
{ id: "open-<feature>", label: "Open <feature>", run: () => router.push("/<feature>") },
```

```tsx
// components/nav/Menu.tsx — append
<MenuItem href="/<feature>">Open <feature></MenuItem>
```

Surface component checklist (enforce in review):
- Only design tokens (`var(--color-*)`, `var(--space-*)`), no `#rrggbb`/`rgb(`.
- Sentence-case labels.
- `aria-label` on every icon-only button.
- `:focus-visible` outline using `--focus-ring`.
- `@media (prefers-reduced-motion: reduce)` disables transitions.
- Explicit `empty`, `loading`, `error` branches.

## Step 5 — Shared settings pipeline

`lib/settings/pipeline.ts`

```ts
import { settingsSchema } from "./schema";

type Key = keyof typeof settingsSchema;
type Listener<K extends Key> = (v: (typeof settingsSchema)[K]) => void;

const listeners = new Map<Key, Set<Listener<any>>>();
const cache = new Map<Key, unknown>();

export function readSetting<K extends Key>(k: K): (typeof settingsSchema)[K] {
  if (cache.has(k)) return cache.get(k) as any;
  const raw = typeof localStorage !== "undefined" ? localStorage.getItem(`settings.${k}`) : null;
  const v = raw != null ? JSON.parse(raw) : settingsSchema[k];
  cache.set(k, v);
  return v;
}

export function writeSetting<K extends Key>(k: K, v: (typeof settingsSchema)[K]) {
  cache.set(k, v);
  localStorage.setItem(`settings.${k}`, JSON.stringify(v));
  listeners.get(k)?.forEach((fn) => fn(v));
}

export function subscribeSetting<K extends Key>(k: K, fn: Listener<K>) {
  if (!listeners.has(k)) listeners.set(k, new Set());
  listeners.get(k)!.add(fn);
  return () => listeners.get(k)!.delete(fn);
}
```

Then for each unread key from step 2, add a reader at the surface that should honor it (e.g. `readSetting("density")` in the layout, `readSetting("reducedMotion")` in the motion provider). Re-run step 2 to confirm `unreadSettings` drops to 0.

## Step 6 — Delete unreachable modules + their exclusive tests

```bash
# From audit/orphans.before.json
jq -r '.unreachable[]' audit/orphans.before.json | while read f; do
  base="${f%.*}"
  rm -f "$f"
  # delete tests that only import this module
  grep -rl --include='*.test.*' --include='*.spec.*' "$(basename "$base")" tests e2e 2>/dev/null | while read t; do
    # only delete if the test imports nothing else from the deleted set
    if ! grep -qE "from ['\"](?!.*$(basename "$base"))" "$t"; then rm -f "$t"; fi
  done
done
```

Guardrail: after deletion, run the full suite. If any *other* test fails, revert that deletion — do not edit the failing test.

## Step 7 — Browser probe

`e2e/probe.spec.ts` (Playwright)

```ts
import { test, expect } from "@playwright/test";

const CONTROLS = [
  { name: "Open <feature>", role: "menuitem" },
  { name: "Open <feature>", role: "button" }, // palette command
  // one entry per mounted surface from step 4
];

test("all mounted surfaces reachable, no console errors", async ({ page }) => {
  const errors: string[] = [];
  page.on("console", (m) => { if (m.type() === "error") errors.push(m.text()); });
  page.on("pageerror", (e) => errors.push(e.message));

  await page.goto("/");
  await page.screenshot({ path: "audit/shots/home.png", fullPage: true });

  for (const c of CONTROLS) {
    const loc = page.getByRole(c.role as any, { name: c.name });
    await expect(loc, `missing control: ${c.name}`).toBeVisible();
  }

  // palette
  await page.keyboard.press("ControlOrMeta+K");
  await page.screenshot({ path: "audit/shots/palette.png" });
  for (const c of CONTROLS.filter((x) => x.role === "menuitem")) {
    await expect(page.getByRole("menuitem", { name: c.name })).toBeVisible();
  }

  expect(errors, errors.join("\n")).toEqual([]);
});
```

## Step 8 — Run everything and report

```bash
npm run lint
npm run typecheck
npm test
npm run build
npx playwright test e2e/probe.spec.ts
npx tsx scripts/audit/orphans.ts > audit/orphans.after.json
npx tsx scripts/audit/settings-events.ts > audit/settings-events.after.json
npx tsx scripts/audit/unrouted.ts > audit/unrouted.after.json
```

Report template (fill from the JSON):

| Metric | Before | After |
|---|---|---|
| Orphan modules (unreachable) | `counts.unreachable` | `counts.unreachable` |
| Modules imported only by own tests | `counts.onlyTestImported` | `counts.onlyTestImported` |
| One-sided events | `counts.oneSidedEvents` | `counts.oneSidedEvents` |
| Unread settings keys | `counts.unreadSettings` | `counts.unreadSettings` |
| Unrouted components | `count` | `count` |

Expected end state: orphans → 0, only-test-imported → 0 (either mounted or deleted), one-sided events → 0 (add the missing side or delete the dead side), unread settings → 0 (wired through `lib/settings/pipeline.ts`), unrouted components → 0 (mounted in step 4 or deleted in step 6), probe green, no console errors, screenshots written to `audit/shots/`.

If you paste the three `*.before.json` outputs (or the repo tree), I'll turn the generic patches in steps 4–6 into exact file edits for your codebase.