@skyf0xx/hedgehog 4.1.0 → 4.2.2

package/src/db/status.mjs

@@ -11,7 +11,10 @@
 // every task meeting that condition, not just the one `hedgehog next`
 // would pick.
 
+import { listDebt } from './debt.mjs';
 import { detectDrift, formatDrift } from './drift.mjs';
+import { listFriction } from './friction.mjs';
+import { orphanedOverrides } from './overrides.mjs';
 import { formatMissingRequirements } from './requires.mjs';
 import { readyTasks, heldBackReason } from './ready.mjs';
 
@@ -82,16 +85,49 @@ function loadAttentionTasks(db) {
   return db.prepare(ATTENTION_TASKS_SQL).all();
 }
 
-// Returns { counts, ready, heldBack, inFlight, attention, drift, total } —
-// counts keyed by every status in the tasks CHECK constraint (present even
-// at zero), ready the full list of currently-pickable tasks, heldBack the
-// subset of those that `hedgehog claim` would skip over right now because
-// they conflict with in-flight work or another ready task ahead of them
-// (ready.mjs's own simulation, reused rather than reimplemented — without
-// this a task can sit in READY indefinitely with no visible reason, the
-// same invisible-stall shape blocked tasks had before `attention` existed),
-// inFlight the tasks currently leased (building or verifying), attention
-// the stalled tasks needing a fix, total the sum across all statuses.
+// Collapses every debt row to one entry per declaring task: { taskId, n }
+// in task-id order. The notes themselves stay out — a status overview
+// that reprints them is `debt list` with extra steps, and the note only
+// becomes actionable in the packet of a task that inherits it, where
+// next.mjs already renders it in full. The task id is the part that has
+// to be here, because it is the argument `debt list <task>` needs and
+// the thing an operator has no other way to guess.
+function loadDebtByTask(db) {
+  const byTask = new Map();
+  for (const { taskId } of listDebt(db)) {
+    byTask.set(taskId, (byTask.get(taskId) ?? 0) + 1);
+  }
+  return [...byTask.entries()]
+    .map(([taskId, n]) => ({ taskId, n }))
+    .sort((a, b) => a.taskId.localeCompare(b.taskId));
+}
+
+// The friction row count, or 0. `listFriction` reads the table
+// unguarded, so a build graph predating it throws here where `listDebt`
+// would return [] — caught rather than propagated for the same reason
+// the CLI tolerates an unparseable core.yaml: status is the command
+// every session starts with, and one absent table must not cost the
+// operator the whole overview. Every other section is still true.
+function countFriction(db) {
+  try {
+    return listFriction(db).length;
+  } catch {
+    return 0;
+  }
+}
+
+// Returns { counts, ready, heldBack, inFlight, attention, drift,
+// orphanedOverrides, debt, frictionCount, total } — counts keyed by
+// every status in the tasks CHECK constraint (present even at zero),
+// ready the full list of currently-pickable tasks, heldBack the subset
+// of those that `hedgehog claim` would skip over right now because they
+// conflict with in-flight work or another ready task ahead of them
+// (ready.mjs's own simulation, reused rather than reimplemented —
+// without this a task can sit in READY indefinitely with no visible
+// reason, the same invisible-stall shape blocked tasks had before
+// `attention` existed), inFlight the tasks currently leased (building or
+// verifying), attention the stalled tasks needing a fix, total the sum
+// across all statuses.
 //
 // `core` is optional and, when given, adds `drift`: the tasks whose
 // layer-derived fields no longer match core.yaml (drift.mjs). It's a
@@ -103,6 +139,26 @@ function loadAttentionTasks(db) {
 // resolve and pass in — detectDrift needs it composed against `core` or
 // every task widened by `.hedgehog/overrides/*.json` reports permanent,
 // spurious drift here.
+//
+// `orphanedOverrides` (overrides.mjs) is the override ids matching no
+// task row. It rides on `status` rather than on `override list` alone
+// because a dead override is invisible by construction — composeScope
+// missing a key is a no-op, so the file widens nothing and raises
+// nothing, and `override list` is a command an operator only runs once
+// they already suspect something. It reads only `tasks`, not core.yaml,
+// so it is computed unconditionally: an override id is stale or it
+// isn't, whether or not a core definition is loadable.
+//
+// `debt` (per declaring task) and `frictionCount` are counts, not
+// listings: both tables are append-only with no resolved column, so
+// there is no "open" subset to filter to and this can only ever report
+// what has been declared. That is the honest reading and also the
+// useful one — a debt note is consumed by whichever downstream task
+// inherits it, and friction is reviewed in a batch by tweaker, so
+// neither is a queue `status` could burn down. What was missing was
+// only the existence signal: `debt list` needs a task id the operator
+// has no way to guess, and `friction list` needs the operator to
+// already suspect there is something to read.
 export function graphStatus(db, { core = null, overrides = new Map() } = {}) {
   const counts = countTasksByStatus(db);
   const ready = loadReadyTasks(db);
@@ -110,8 +166,22 @@ export function graphStatus(db, { core = null, overrides = new Map() } = {}) {
   const inFlight = loadInFlightTasks(db);
   const attention = loadAttentionTasks(db);
   const drift = core ? detectDrift(db, core, { overrides }) : [];
+  const orphaned = orphanedOverrides(db, overrides);
+  const debt = loadDebtByTask(db);
+  const frictionCount = countFriction(db);
   const total = Object.values(counts).reduce((a, b) => a + b, 0);
-  return { counts, ready, heldBack, inFlight, attention, drift, total };
+  return {
+    counts,
+    ready,
+    heldBack,
+    inFlight,
+    attention,
+    drift,
+    orphanedOverrides: orphaned,
+    debt,
+    frictionCount,
+    total,
+  };
 }
 
 const BLOCKED_REASON_LABELS = {
@@ -123,7 +193,9 @@ const BLOCKED_REASON_LABELS = {
 // Renders a graphStatus() result into a plain-text overview: counts by
 // status (only non-zero ones, in lifecycle order), any declared binary
 // this environment can't resolve, the ready list, tasks currently in
-// flight, anything needing attention, and core.yaml drift.
+// flight, anything needing attention, core.yaml drift, overrides
+// pointing at no task, and what has been recorded in the two
+// append-only side channels (declared debt, logged friction).
 //
 // `missingRequirements` comes from the core definition rather than the
 // database (src/db/requires.mjs#coreMissingRequirements), so the caller
@@ -138,6 +210,9 @@ export function formatStatus({
   inFlight,
   attention,
   drift,
+  orphanedOverrides = [],
+  debt = [],
+  frictionCount = 0,
   total,
   missingRequirements,
 }) {
@@ -191,13 +266,63 @@ export function formatStatus({
     lines.push('  Fix the work, then: hedgehog retry <task-id> && hedgehog claim <task-id> --owner <owner>');
   }
 
-  // Last, because it's a condition of the graph as a whole rather than
-  // of any one task, and because an operator reading top-down should
-  // reach it after knowing what's ready and what's stuck.
+  // Last two, because both are conditions of the graph as a whole rather
+  // than of any one task, and because an operator reading top-down should
+  // reach them after knowing what's ready and what's stuck.
   if (drift && drift.length > 0) {
     lines.push('');
     lines.push(formatDrift(drift));
   }
 
+  // Below drift because it's the rarer of the two and never blocks the
+  // build: an orphaned override is work the operator asked for that isn't
+  // happening, not work the graph is getting wrong. `hedgehog override
+  // list` carries the full explanation of how an id goes stale; here the
+  // consequence is the whole point, since this is the only place an
+  // operator who doesn't already suspect it will ever see it.
+  if (orphanedOverrides.length > 0) {
+    lines.push('');
+    lines.push('ORPHANED OVERRIDES');
+    for (const taskId of orphanedOverrides) {
+      lines.push(`  ${taskId}   no task with this id in the build graph`);
+    }
+    lines.push('');
+    lines.push('  Each widens nothing until the id matches a real task. See: hedgehog override list');
+  }
+
+  // Bottom, below every condition above, and two sections rather than
+  // one. Everything above is something wrong — work stalled, a graph
+  // that disagrees with its core, an override doing nothing. These two
+  // are neither wrong nor actionable here: both tables are append-only,
+  // so nothing printed can be cleared by acting on it, and an operator
+  // scanning top-down should hit what needs a decision first.
+  //
+  // Kept apart because they are read by different people at different
+  // times through different commands. Debt is in-build traffic between
+  // two tasks — it arrives on its own in the inheriting task's packet,
+  // and naming the declaring tasks here is only so `debt list <task>`
+  // is reachable without guessing the id. Friction is about Hedgehog
+  // itself, batch-reviewed by tweaker at the end of a build, and has no
+  // per-task reading at all (a row's task_id is nullable). Merging them
+  // into one "notes" count would imply a single follow-up action where
+  // there are two unrelated ones.
+  if (debt.length > 0) {
+    const rows = debt.reduce((sum, { n }) => sum + n, 0);
+    lines.push('');
+    lines.push(`DECLARED DEBT  ${rows}`);
+    for (const { taskId, n } of debt) {
+      lines.push(`  ${taskId}   ${n} note${n === 1 ? '' : 's'}`);
+    }
+    lines.push('');
+    lines.push('  Reaches each dependent task\'s packet on its own. See: hedgehog debt list <task-id>');
+  }
+
+  if (frictionCount > 0) {
+    lines.push('');
+    lines.push(`FRICTION LOGGED  ${frictionCount}`);
+    lines.push('');
+    lines.push('  Reviewed as a batch at the end of a build. See: hedgehog friction list');
+  }
+
   return lines.join('\n');
 }

package/src/golden-cores/full-stack-app/.env.example

@@ -2,3 +2,4 @@
 # service — no edits needed unless you've changed those credentials.
 DATABASE_URL=postgresql://postgres:postgres@localhost:5432/app
 NODE_ENV=development
+WEB_ORIGIN=http://localhost:3000

package/src/golden-cores/full-stack-app/apps/api/package.json

@@ -4,8 +4,25 @@
   "private": true,
   "nx": {
     "targets": {
+      "generate-feature-modules": {
+        "executor": "nx:run-commands",
+        "cache": true,
+        "inputs": [
+          "{projectRoot}/src/app/*/*.module.ts"
+        ],
+        "outputs": [
+          "{projectRoot}/src/app/feature-modules.ts"
+        ],
+        "options": {
+          "command": "node tools/generate-feature-modules.cjs",
+          "cwd": "{workspaceRoot}"
+        }
+      },
       "build": {
         "executor": "nx:run-commands",
+        "dependsOn": [
+          "generate-feature-modules"
+        ],
         "options": {
           "command": "webpack-cli build",
           "env": {
@@ -91,7 +108,8 @@
     "tslib": "^2.3.0",
     "nestjs-pino": "^4.6.1",
     "pino-http": "^11.0.0",
-    "config": "workspace:*"
+    "config": "workspace:*",
+    "db": "workspace:*"
   },
   "devDependencies": {
     "@nestjs/testing": "^11.0.0"

package/src/golden-cores/full-stack-app/apps/api/src/app/app.module.spec.ts

@@ -0,0 +1,15 @@
+import { Test } from '@nestjs/testing';
+import { describe, expect, it } from 'vitest';
+import { AppModule } from './app.module';
+
+describe('AppModule', () => {
+  it('compiles with the health check controller wired', async () => {
+    const moduleRef = await Test.createTestingModule({
+      imports: [AppModule],
+    }).compile();
+
+    expect(moduleRef).toBeDefined();
+
+    await moduleRef.close();
+  });
+});

package/src/golden-cores/full-stack-app/apps/api/src/app/app.module.ts

@@ -1,9 +1,14 @@
 import { Module } from '@nestjs/common';
 import { LoggerModule } from 'nestjs-pino';
 import { HealthController } from './health.controller';
+// Generated by tools/generate-feature-modules.cjs (see that file's header)
+// from every apps/api/src/app/*/*.module.ts on disk — never hand-edited,
+// so no domain module's controller task ever edits this file or
+// app.module.ts itself to register.
+import { featureModules } from './feature-modules';
 
 @Module({
-  imports: [LoggerModule.forRoot()],
+  imports: [LoggerModule.forRoot(), ...featureModules],
   controllers: [HealthController],
   providers: [],
 })

package/src/golden-cores/full-stack-app/apps/api/src/app/feature-modules.ts

@@ -0,0 +1,8 @@
+// GENERATED FILE — do not hand-edit. Regenerated by
+// tools/generate-feature-modules.cjs (the generate-feature-modules Nx
+// target, which test and build depend on) from every
+// apps/api/src/app/*/*.module.ts file on disk. A module directory's
+// controller layer only ever creates its own *.module.ts inside its own
+// directory — never edits this file.
+
+export const featureModules = [];

package/src/golden-cores/full-stack-app/apps/api/src/main.ts

@@ -3,11 +3,20 @@ import { Logger } from 'nestjs-pino';
 import { NestFactory } from '@nestjs/core';
 import { AppModule } from './app/app.module';
 
-loadEnv();
+const env = loadEnv();
 
 async function bootstrap() {
   const app = await NestFactory.create(AppModule, { bufferLogs: true });
   app.useLogger(app.get(Logger));
+  // apps/web runs on its own origin in local dev (see the port comment
+  // below), so the browser's fetches to this api are cross-origin by
+  // default — enable CORS for that origin rather than rediscovering this
+  // per project.
+  app.enableCors({ origin: env.WEB_ORIGIN });
+  // Every route lives under /api. apps/web's NEXT_PUBLIC_API_BASE_URL
+  // (apps/web/.env.example) has to carry the same suffix or every request
+  // from the browser lands one path segment short of a route that exists —
+  // change one and change the other.
   const globalPrefix = 'api';
   app.setGlobalPrefix(globalPrefix);
   // Defaults to 3333, not 3000 — `apps/web`'s `next dev` also defaults to

package/src/golden-cores/full-stack-app/apps/api/tsconfig.app.json

@@ -14,6 +14,9 @@
   "references": [
     {
       "path": "../../packages/config/tsconfig.lib.json"
+    },
+    {
+      "path": "../../packages/db/tsconfig.lib.json"
     }
   ]
 }

package/src/golden-cores/full-stack-app/apps/api/tsconfig.json

@@ -5,6 +5,9 @@
   "references": [
     {
       "path": "./tsconfig.app.json"
+    },
+    {
+      "path": "./tsconfig.spec.json"
     }
   ]
 }

package/src/golden-cores/full-stack-app/apps/api/tsconfig.spec.json

@@ -0,0 +1,36 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "./out-tsc/vitest",
+    "types": [
+      "vitest/globals",
+      "vitest/importMeta",
+      "vite/client",
+      "node",
+      "vitest"
+    ],
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": [
+    "vite.config.ts",
+    "vite.config.mts",
+    "vitest.config.ts",
+    "vitest.config.mts",
+    "src/**/*.test.ts",
+    "src/**/*.spec.ts",
+    "src/**/*.test.tsx",
+    "src/**/*.spec.tsx",
+    "src/**/*.test.js",
+    "src/**/*.spec.js",
+    "src/**/*.test.jsx",
+    "src/**/*.spec.jsx",
+    "src/**/*.d.ts"
+  ],
+  "references": [
+    {
+      "path": "./tsconfig.app.json"
+    }
+  ]
+}

package/src/golden-cores/full-stack-app/apps/api/vitest.config.mts

@@ -0,0 +1,18 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig(() => ({
+  root: __dirname,
+  cacheDir: '../../node_modules/.vite/apps/api',
+  test: {
+    name: 'api',
+    watch: false,
+    globals: true,
+    environment: 'node',
+    include: ['{src,tests}/**/*.{test,spec}.{js,mjs,cjs,ts,mts,cts,jsx,tsx}'],
+    reporters: ['default'],
+    coverage: {
+      reportsDirectory: './test-output/vitest/coverage',
+      provider: 'v8' as const,
+    },
+  },
+}));

package/src/golden-cores/full-stack-app/apps/web/.env.example

@@ -0,0 +1,12 @@
+# Copy to apps/web/.env.local for local dev. Next.js loads env files from
+# the app directory, not the workspace root — the root .env.example is
+# apps/api's, and nothing in this file reaches the server.
+#
+# The /api suffix is apps/api's global route prefix (app.setGlobalPrefix in
+# apps/api/src/main.ts). Without it every request lands one path segment
+# short and 404s against a route that plainly exists. 3333 is apps/api's
+# dev port; apps/web itself runs on 3000.
+#
+# NEXT_PUBLIC_ is required: this value is read in the browser, so Next has
+# to inline it at build time.
+NEXT_PUBLIC_API_BASE_URL=http://localhost:3333/api

package/src/golden-cores/full-stack-app/apps/web/package.json

@@ -19,5 +19,8 @@
   },
   "devDependencies": {
     "prettier-plugin-tailwindcss": "^0.7.4"
+  },
+  "nx": {
+    "tags": ["scope:web"]
   }
 }

package/src/golden-cores/full-stack-app/apps/web/src/components/theme-toggle.spec.tsx

@@ -0,0 +1,20 @@
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { describe, expect, it } from 'vitest';
+import { ThemeToggle } from './theme-toggle';
+
+describe('ThemeToggle', () => {
+  it('renders a toggle button and flips the document theme class on click', async () => {
+    const user = userEvent.setup();
+    render(<ThemeToggle />);
+
+    const toggle = screen.getByRole('button', { name: /toggle theme/i });
+    expect(toggle).toBeInTheDocument();
+
+    await user.click(toggle);
+    expect(document.documentElement.classList.contains('dark')).toBe(true);
+
+    await user.click(toggle);
+    expect(document.documentElement.classList.contains('dark')).toBe(false);
+  });
+});

package/src/golden-cores/full-stack-app/apps/web/src/test-setup.ts

@@ -0,0 +1 @@
+import '@testing-library/jest-dom/vitest';

package/src/golden-cores/full-stack-app/apps/web/tsconfig.json

@@ -41,8 +41,11 @@
     "node_modules",
     "jest.config.ts",
     "jest.config.cts",
+    "src/test-setup.ts",
     "src/**/*.spec.ts",
     "src/**/*.test.ts",
+    "src/**/*.spec.tsx",
+    "src/**/*.test.tsx",
     ".next",
     "eslint.config.js",
     "eslint.config.cjs",
@@ -51,6 +54,9 @@
   "references": [
     {
       "path": "../../packages/config"
+    },
+    {
+      "path": "./tsconfig.spec.json"
     }
   ]
 }

package/src/golden-cores/full-stack-app/apps/web/tsconfig.spec.json

@@ -0,0 +1,37 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "./out-tsc/vitest",
+    "jsx": "preserve",
+    "types": [
+      "vitest/globals",
+      "vitest/importMeta",
+      "vite/client",
+      "node",
+      "vitest",
+      "@testing-library/jest-dom"
+    ],
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": [
+    "vite.config.ts",
+    "vite.config.mts",
+    "vitest.config.ts",
+    "vitest.config.mts",
+    "src/test-setup.ts",
+    "src/**/*.test.ts",
+    "src/**/*.spec.ts",
+    "src/**/*.test.tsx",
+    "src/**/*.spec.tsx",
+    "src/**/*.test.js",
+    "src/**/*.spec.js",
+    "src/**/*.test.jsx",
+    "src/**/*.spec.jsx",
+    "src/**/*.d.ts"
+  ],
+  "references": [
+    {
+      "path": "../../packages/config"
+    }
+  ]
+}

package/src/golden-cores/full-stack-app/apps/web/vitest.config.mts

@@ -0,0 +1,27 @@
+import { defineConfig } from 'vitest/config';
+import react from '@vitejs/plugin-react';
+import { fileURLToPath } from 'node:url';
+
+export default defineConfig(() => ({
+  root: __dirname,
+  cacheDir: '../../node_modules/.vite/apps/web',
+  plugins: [react()],
+  resolve: {
+    alias: {
+      '@': fileURLToPath(new URL('./src', import.meta.url)),
+    },
+  },
+  test: {
+    name: 'web',
+    watch: false,
+    globals: true,
+    environment: 'jsdom',
+    setupFiles: ['./src/test-setup.ts'],
+    include: ['{src,tests}/**/*.{test,spec}.{js,mjs,cjs,ts,mts,cts,jsx,tsx}'],
+    reporters: ['default'],
+    coverage: {
+      reportsDirectory: './test-output/vitest/coverage',
+      provider: 'v8' as const,
+    },
+  },
+}));

package/src/golden-cores/full-stack-app/core.yaml

@@ -19,7 +19,7 @@
 id: full-stack-app
 layers:
   - id: schema
-    scope: ["packages/db/src/schema/{module}/**"]
+    scope: ["packages/db/src/schema/{module}/**", "packages/db/src/schema/index.ts"]
     verify: "pnpm nx test db -- src/schema/{module}/"
     commit: "feat({module}): schema"
   - id: contract
@@ -47,11 +47,19 @@ layers:
     scope: ["packages/hooks/src/{module}/**"]
     verify: "pnpm nx test hooks -- src/{module}/"
     commit: "feat({module}): hooks"
+  # Web only, because apps/mobile only exists when the Mobile add-on is
+  # on. A layer scoped to a project that was never scaffolded fails its
+  # own verify on every module, so the Mobile clause is added by
+  # hedgehog-bootstrap's Expo step — which is also what creates the Nx
+  # project the extra verify target needs — rather than shipped here and
+  # broken by default.
   - id: screen
     depends_on: hook
-    scope: ["apps/web/src/app/{module}/**", "apps/mobile/src/{module}/**"]
-    verify: "pnpm nx test web -- src/app/{module}/ && pnpm nx test mobile -- src/{module}/"
+    scope: ["apps/web/src/app/{module}/**"]
+    verify: "pnpm nx test web -- src/app/{module}/"
     commit: "feat({module}): screen-web"
+  # Workspace-wide by design: the only gate that can see cross-module
+  # breakage, since every layer above is parallel and module-scoped.
   - id: join
     depends_on: screen
     scope: ["**"]

package/src/golden-cores/full-stack-app/nx.json

@@ -6,7 +6,10 @@
     },
     "test": {
       "cache": true,
-      "dependsOn": ["^build"]
+      "dependsOn": ["^build", "generate-feature-modules"]
+    },
+    "typecheck": {
+      "dependsOn": ["generate-feature-modules"]
     },
     "lint": {
       "cache": true

package/src/golden-cores/full-stack-app/package.json

@@ -29,12 +29,16 @@
     "@swc/cli": "~0.8.1",
     "@swc/core": "~1.15.5",
     "@swc/helpers": "~0.5.18",
+    "@testing-library/jest-dom": "^7.0.1",
+    "@testing-library/react": "^16.3.2",
+    "@testing-library/user-event": "^14.6.4",
     "@types/node": "^22.0.0",
     "@types/pg": "^8.20.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "@typescript-eslint/eslint-plugin": "^8.65.0",
     "@typescript-eslint/parser": "^8.65.0",
+    "@vitejs/plugin-react": "^6.0.5",
     "@vitest/coverage-v8": "~4.1.0",
     "drizzle-kit": "^0.31.10",
     "drizzle-zod": "^0.8.3",
@@ -45,6 +49,7 @@
     "eslint-plugin-playwright": "^1.6.2",
     "eslint-plugin-react": "^7.35.0",
     "eslint-plugin-react-hooks": "5.0.0",
+    "jsdom": "^30.0.1",
     "lefthook": "^2.1.10",
     "nx": "23.1.0",
     "prettier": "~3.6.2",
@@ -74,6 +79,9 @@
     "zod": "^4.4.3"
   },
   "pnpm": {
+    "onlyBuiltDependencies": [
+      "lefthook"
+    ],
     "overrides": {
       "esbuild": "0.25.12",
       "axios": "^1.18.0",