Skip to content

See how your app actually fits together. An interactive, plain-English map of your codebase, drawn by Claude or Codex.

6.5 KB
Raw Blame
// Shared helpers for the tests: build a throwaway project on disk, run the skill's scripts on it,
// and read what they wrote. Every project lives in the OS temp folder and is removed afterwards.
import fs from 'node:fs';
import os from 'node:os';
import path from 'node:path';
import { execFileSync } from 'node:child_process';
import { fileURLToPath } from 'node:url';

export const REPO = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
export const SKILL = path.join(REPO, 'skills', 'floorplan');
export const lib = (name) => import(new URL(`../skills/floorplan/scripts/lib/${name}`, import.meta.url));

/**
 * Writes `files` ({ 'relative/path': 'contents' }) into a new temp folder. Each folder in `repos`
 * becomes its own git repo, like a frontend and backend side by side. Returns the folder.
 */
export function makeProject(files, { repos = [], arch } = {}) {
  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'floorplan-test-'));
  for (const [p, src] of Object.entries(files)) {
    fs.mkdirSync(path.dirname(path.join(root, p)), { recursive: true });
    fs.writeFileSync(path.join(root, p), src);
  }
  for (const r of repos) execFileSync('git', ['init', '-q', path.join(root, r)]);
  if (arch) writeJson(path.join(root, 'floorplan', 'architecture.json'), arch);
  return root;
}

/** Runs one of the skill's scripts (scan.mjs, build.mjs, …) on a project and returns what it printed. */
export function run(script, root, ...args) {
  return execFileSync(process.execPath, [path.join(SKILL, 'scripts', script), root, ...args], { encoding: 'utf8', stdio: 'pipe' });
}

/** scan + build, the way the skill does a first map (without touching CLAUDE.local.md). */
export function scanAndBuild(root) {
  return run('scan.mjs', root) + run('build.mjs', root, '--no-claude-md');
}

export const readJson = (file) => JSON.parse(fs.readFileSync(file, 'utf8'));
export const writeJson = (file, data) => { fs.mkdirSync(path.dirname(file), { recursive: true }); fs.writeFileSync(file, JSON.stringify(data, null, 2)); };
export const readGraph = (root) => readJson(path.join(root, 'floorplan', 'graph.json'));
export const cleanup = (root) => fs.rmSync(root, { recursive: true, force: true });

/** Every file under a folder, as { path, text }. */
export function allFiles(dir) {
  return fs.readdirSync(dir, { recursive: true, withFileTypes: true })
    .filter((e) => e.isFile())
    .map((e) => { const p = path.join(e.parentPath ?? e.path, e.name); return { path: p, text: fs.readFileSync(p, 'utf8') }; });
}

/** "METHOD /path" for every endpoint on the map. */
export const routeKeys = (graph) => graph.routes.map((r) => `${r.m} ${r.p}`).sort();

/** "METHOD /path" for every endpoint Health reports as callable by anyone. */
export function openEndpoints(graph) {
  return graph.health.issues
    .filter((i) => i.kind === 'unprotected-endpoint')
    .flatMap((i) => i.items.filter((id) => id.startsWith('r:')).map((id) => graph.routes[+id.slice(2)]))
    .map((r) => `${r.m} ${r.p}`)
    .sort();
}

// A fake password for the sample app. It's assembled at runtime so no secret-looking string is
// ever committed to this repo, and the tests can check it never reaches anything Floorplan writes.
export const FAKE_PASSWORD = ['correct', 'horse', 'battery', 'staple', '42'].join('-');

/**
 * A small shop: an Express API and a web app in two repos. It has endpoints protected three ways
 * (middleware on the route, a check where the router is mounted, none at all), cross-repo web
 * requests, and a hard-coded password.
 */
export function shopApp() {
  const files = {
    'shop-api/package.json': JSON.stringify({ name: 'shop-api', type: 'module', dependencies: { express: '^4.19.0' } }),
    'shop-api/server.js': [
      `import express from 'express';`,
      `import orders from './routes/orders.js';`,
      `import admin from './routes/admin.js';`,
      `import notes from './routes/notes.js';`,
      `import { requireStaff } from './auth.js';`,
      ``,
      `const app = express();`,
      `app.use('/api', orders);`,
      `app.use('/admin', requireStaff, admin);`,
      `app.use('/api', notes);`,
      `app.listen(3000);`,
    ].join('\n'),
    'shop-api/auth.js': [
      `/** Rejects requests without a signed-in customer. */`,
      `export function requireAuth(req, res, next) { if (!req.headers.authorization) return res.status(401).end(); next(); }`,
      `/** Rejects requests that aren't from staff. */`,
      `export function requireStaff(req, res, next) { if (!req.user?.staff) return res.status(403).end(); next(); }`,
    ].join('\n'),
    'shop-api/config.js': `export const DB_PASSWORD = "${FAKE_PASSWORD}";\nexport const PORT = 3000;\n`,
    'shop-api/routes/orders.js': [
      `import { Router } from 'express';`,
      `import { requireAuth } from '../auth.js';`,
      `import { DB_PASSWORD } from '../config.js';`,
      ``,
      `const router = Router();`,
      `/** Every order for the signed-in customer. */`,
      `router.get('/orders', requireAuth, async (req, res) => { res.json([]); });`,
      `router.post('/orders/:id/refund', requireAuth, async (req, res) => { res.json({ ok: !!DB_PASSWORD }); });`,
      `export default router;`,
    ].join('\n'),
    'shop-api/routes/admin.js': [
      `import { Router } from 'express';`,
      `const router = Router();`,
      `router.delete('/users/:id', async (req, res) => { res.status(204).end(); });`,
      `export default router;`,
    ].join('\n'),
    'shop-api/routes/notes.js': [
      `import { Router } from 'express';`,
      `const router = Router();`,
      `router.post('/notes', async (req, res) => { res.json({ saved: true }); });`,
      `export default router;`,
    ].join('\n'),
    'shop-web/package.json': JSON.stringify({ name: 'shop-web', type: 'module', dependencies: { react: '^18.3.0' } }),
    'shop-web/src/api.js': [
      `export const listOrders = () => fetch('/api/orders').then((r) => r.json());`,
      'export const refund = (id) => fetch(`/api/orders/${id}/refund`, { method: \'POST\' });',
    ].join('\n'),
    'shop-web/src/App.jsx': [
      `import { listOrders, refund } from './api.js';`,
      `export default function App() { return <button onClick={() => listOrders().then((o) => refund(o[0].id))}>Refund</button>; }`,
    ].join('\n'),
  };
  const arch = {
    project: { name: 'Shop', summary: 'A sample shop.' },
    nodes: [
      { id: 'api', label: 'Server', kind: 'service', summary: 'The shop server.', paths: ['shop-api/**'] },
      { id: 'web', label: 'Website', kind: 'ui', summary: 'The shop website.', paths: ['shop-web/**'] },
    ],
  };
  return makeProject(files, { repos: ['shop-api', 'shop-web'], arch });
}