From 891c2b78872c32ccc236b6bc49002cc7ebad0136 Mon Sep 17 00:00:00 2001 From: Ethan Arrowood Date: Tue, 20 Oct 2026 13:20:34 -0600 Subject: [PATCH] feat(dev): synthetic fixtures and a LOCAL_SEED loader Local development and tests need data in every state without any real event data in the repo. fixtures/ holds a synthetic set: 19 tasks covering every status (open, claimed self-serve and by an organizer, completed, flagged, removed), three themes, every difficulty, and both import shapes; one guide per theme; six users (an admin, attendees, a banned and a timed-out user); and the announcement and pool settings. The states are consistent with each other. Every login contains an underscore, which GitHub usernames can't, so a fixture account never matches a real user. LOCAL_SEED= loads such a set with each task's state intact (unlike LOCAL_DATA_FILE, which opens every task) plus users and settings. Like the other loaders it never overwrites an existing record, so restarts keep local edits. It runs only on a local instance (shared/local.ts: OAUTH_REDIRECT_URI unset or a loopback host) and logs why it skipped otherwise. LOCAL_DATA_FILE and LOCAL_GUIDES_FILE are unchanged. Co-Authored-By: Claude Opus 5.5 --- .env.example | 4 + README.md | 4 + fixtures/README.md | 27 ++++ fixtures/guides.json | 22 ++++ fixtures/settings.json | 14 +++ fixtures/tasks.json | 253 ++++++++++++++++++++++++++++++++++++++ fixtures/users.json | 23 ++++ resources/bootstrap.ts | 133 +++++++++++++++++++- resources/shared/local.ts | 21 ++++ 9 files changed, 500 insertions(+), 1 deletion(-) create mode 100644 fixtures/README.md create mode 100644 fixtures/guides.json create mode 100644 fixtures/settings.json create mode 100644 fixtures/tasks.json create mode 100644 fixtures/users.json create mode 100644 resources/shared/local.ts diff --git a/.env.example b/.env.example index ec059c1..f665193 100644 --- a/.env.example +++ b/.env.example @@ -17,6 +17,10 @@ ADMIN_GITHUB_LOGINS= # --- Local development only ------------------------------------------------- +# The synthetic fixture set (fixtures/): tasks in every state, guides, users, +# and settings. Local instances only; existing records are left untouched. +#LOCAL_SEED=fixtures + # One or more JSON task files (comma-separated) loaded as the starting pool — # the curated event lists or the admin bulk-import shape. # Idempotent: entries already loaded are left untouched. diff --git a/README.md b/README.md index 5c66b21..4d5e543 100644 --- a/README.md +++ b/README.md @@ -66,6 +66,10 @@ Both run in CI on every push and pull request, alongside `vite build`. Useful env vars for local dev (in `.env`): +- `LOCAL_SEED=fixtures` — loads the synthetic fixture set in [`fixtures/`](fixtures/README.md): + tasks in every state (claimed, completed, flagged…), guides, users (an admin, attendees, a + banned and a timed-out user), and settings. Idempotent across restarts, and runs on local + instances only. - `LOCAL_DATA_FILE=data/contribution-tasks.json` — loads a JSON task file (the curated event list, or the bulk-import shape) as the starting pool. Idempotent across restarts; entries may pin their own `id`. diff --git a/fixtures/README.md b/fixtures/README.md new file mode 100644 index 0000000..ccd9e40 --- /dev/null +++ b/fixtures/README.md @@ -0,0 +1,27 @@ +# Fixtures + +Synthetic data for local development and tests. Nothing here is a real event, task, or person. +Real event data never goes in this repository; it lives in the production database. + +| File | What | +| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `tasks.json` | 19 tasks: every status (open, claimed, completed, flagged, removed), three themes, every difficulty, and both import shapes (the app shape and the curated `detail`/`tier` shape) | +| `guides.json` | one guide per theme: `example-refactor`, `example-tests`, `example-docs` | +| `users.json` | `fx_ada` (admin), `fx_alice`, `fx_bob`, `fx_erin` (attendees), `fx_carol` (banned), `fx_dave` (timed out) | +| `settings.json` | the announcement banner and an open pool | + +The states are consistent with each other: `fx_alice` holds `fx-refactor-03`, `fx_erin` holds +`fx-tests-03` (assigned by `fx_ada`), and the banned and timed-out users hold nothing. + +Every login contains an underscore, which GitHub doesn't allow in usernames, so a fixture account +can never match a real GitHub user. + +## Loading + +Set `LOCAL_SEED=fixtures` (in `.env` or your shell) and start the app. Everything loads with its +state intact, and existing records are never overwritten, so restarts keep your changes. Seeding +only runs on a local instance: if `OAUTH_REDIRECT_URI` points anywhere but localhost, it is +skipped with an error in the log. + +`tasks.json` and `guides.json` also paste into **Admin → Bulk import** (guides first), for example +on staging. Imported tasks start open, and users and settings aren't imported that way. diff --git a/fixtures/guides.json b/fixtures/guides.json new file mode 100644 index 0000000..f5883df --- /dev/null +++ b/fixtures/guides.json @@ -0,0 +1,22 @@ +{ + "guides": [ + { + "id": "example-refactor", + "title": "Refactoring a fixture file", + "summary": "How to make a small, behavior-preserving change to one file.", + "body": "Each task in this theme names one file. Make the change it describes and nothing else.\n\n1. Read the file and the task's notes.\n2. Make the change.\n3. Run the file's check:\n\n```bash\nnpm test -- path/to/example-file.test.js\n```\n\nKeep the change small; reviewers merge small diffs faster." + }, + { + "id": "example-tests", + "title": "Improving a fixture test", + "summary": "How to tighten or split a test without changing what it checks.", + "body": "Tests in this theme check the right thing but report failures poorly, or bundle too much.\n\n- Preserve what each test asserts.\n- Prefer one scenario per test.\n\n```js\nimport { test } from 'node:test';\nimport assert from 'node:assert';\n\ntest('example scenario', () => {\n assert.strictEqual(1 + 1, 2);\n});\n```" + }, + { + "id": "example-docs", + "title": "Fixing a fixture doc page", + "summary": "How to correct a documentation page and check the rendered result.", + "body": "Doc tasks point at one page and list what is wrong with it.\n\n1. Fix each listed item.\n2. Render the page locally and check it reads correctly.\n\nDocs changes use the `doc:` commit prefix." + } + ] +} diff --git a/fixtures/settings.json b/fixtures/settings.json new file mode 100644 index 0000000..cbac442 --- /dev/null +++ b/fixtures/settings.json @@ -0,0 +1,14 @@ +{ + "settings": [ + { + "id": "announcement", + "value": { + "enabled": true, + "level": "info", + "title": "Fixture data", + "body": "You're looking at synthetic fixtures, not a real event." + } + }, + { "id": "claims", "value": { "paused": false, "hidden": false, "message": "" } } + ] +} diff --git a/fixtures/tasks.json b/fixtures/tasks.json new file mode 100644 index 0000000..9407871 --- /dev/null +++ b/fixtures/tasks.json @@ -0,0 +1,253 @@ +{ + "tasks": [ + { + "id": "fx-refactor-01", + "title": "Replace a manual loop in example/refactor-one.js", + "summary": "Swap an index-based loop for for...of.", + "description": "`example/refactor-one.js` walks an array with an index-based `for` loop. Replace it with `for...of`.", + "theme": "example-refactor", + "difficulty": "beginner", + "area": "example", + "skills": ["javascript"], + "estimatedMinutes": 20, + "links": [{ "label": "Example file", "url": "https://example.com/refactor-one.js" }] + }, + { + "id": "fx-refactor-02", + "title": "Remove an unused variable in example/refactor-two.js", + "summary": "Delete a variable that is assigned but never read.", + "description": "`example/refactor-two.js` declares `unused` and never reads it. Remove it.", + "theme": "example-refactor", + "difficulty": "beginner", + "area": "example", + "skills": ["javascript"], + "estimatedMinutes": 15, + "links": [] + }, + { + "id": "fx-refactor-03", + "title": "Inline a one-line helper in example/refactor-three.js", + "summary": "Inline a helper that is only called once.", + "description": "`formatName()` in `example/refactor-three.js` is called once. Inline it.", + "theme": "example-refactor", + "difficulty": "beginner", + "area": "example", + "skills": ["javascript"], + "estimatedMinutes": 20, + "links": [], + "status": "claimed", + "assignedTo": "fx_alice", + "assignedName": "Alice (fixture attendee)", + "assignedAt": 1767229200000 + }, + { + "id": "fx-refactor-04", + "title": "Use optional chaining in example/refactor-four.js", + "summary": "Collapse a nested null check.", + "description": "Replace `a && a.b && a.b.c` in `example/refactor-four.js` with `a?.b?.c`.", + "theme": "example-refactor", + "difficulty": "beginner", + "area": "example", + "skills": ["javascript"], + "estimatedMinutes": 15, + "links": [], + "status": "completed", + "completedBy": "fx_bob", + "completedAt": 1767232800000, + "evidenceUrl": "https://github.com/example/example/pull/1" + }, + { + "id": "fx-refactor-05", + "title": "Convert callbacks to async/await in example/refactor-five.js", + "summary": "Rewrite one callback chain with async/await.", + "description": "`readConfig()` in `example/refactor-five.js` nests three callbacks. Rewrite it with `async`/`await`, keeping the same error handling.", + "theme": "example-refactor", + "difficulty": "intermediate", + "area": "example", + "skills": ["javascript", "async"], + "estimatedMinutes": 45, + "links": [] + }, + { + "id": "fx-tests-01", + "title": "Split example/test-big.js into focused tests", + "summary": "Break one large test file into one file per scenario.", + "description": "`example/test-big.js` covers four unrelated scenarios. Split it into four files and delete the original.", + "theme": "example-tests", + "difficulty": "intermediate", + "area": "test", + "skills": ["testing"], + "estimatedMinutes": 60, + "links": [] + }, + { + "id": "fx-tests-02", + "title": "Assert on output in example/test-output.js", + "summary": "Check the child's output, not just its exit code.", + "description": "`example/test-output.js` only checks the exit code. Also assert on stdout.", + "theme": "example-tests", + "difficulty": "intermediate", + "area": "test", + "skills": ["testing", "child_process"], + "estimatedMinutes": 45, + "links": [] + }, + { + "id": "fx-tests-03", + "title": "Use strict assertions in example/test-strict.js", + "summary": "Swap loose equality assertions for strict ones.", + "description": "Replace `assert.equal` with `assert.strictEqual` in `example/test-strict.js`.", + "theme": "example-tests", + "difficulty": "beginner", + "area": "test", + "skills": ["testing"], + "estimatedMinutes": 20, + "links": [], + "status": "claimed", + "assignedTo": "fx_erin", + "assignedName": "Erin (fixture attendee)", + "assignedAt": 1767229800000, + "assignedBy": "fx_ada" + }, + { + "id": "fx-tests-04", + "title": "Remove a timing dependency in example/test-timing.js", + "summary": "Replace a fixed sleep with an event wait.", + "description": "`example/test-timing.js` sleeps 500 ms before asserting. Wait for the `ready` event instead.", + "theme": "example-tests", + "difficulty": "advanced", + "area": "test", + "skills": ["testing", "events"], + "estimatedMinutes": 90, + "links": [], + "status": "flagged", + "uncompletableReason": "Fixture: the file was already changed upstream", + "uncompletableBy": "fx_bob", + "uncompletableAt": 1767236400000 + }, + { + "id": "fx-tests-05", + "title": "Name the anonymous tests in example/test-names.js", + "summary": "Give every test a descriptive name.", + "description": "Three tests in `example/test-names.js` have no name. Name each after what it checks.", + "theme": "example-tests", + "difficulty": "beginner", + "area": "test", + "skills": ["testing"], + "estimatedMinutes": 15, + "links": [] + }, + { + "id": "fx-docs-01", + "title": "Fix return types in example/docs-api.md", + "summary": "Correct two functions documented as returning undefined.", + "description": "In `example/docs-api.md`:\n\n- `parse()` returns `{Object}`, not `undefined`.\n- `format()` returns `{string}`, not `undefined`.", + "theme": "example-docs", + "difficulty": "beginner", + "area": "docs", + "skills": ["markdown"], + "estimatedMinutes": 20, + "links": [] + }, + { + "id": "fx-docs-02", + "title": "Add a missing example to example/docs-guide.md", + "summary": "Add a short usage example to one section.", + "description": "The \"Getting started\" section of `example/docs-guide.md` has no code example. Add one.", + "theme": "example-docs", + "difficulty": "beginner", + "area": "docs", + "skills": ["markdown"], + "estimatedMinutes": 25, + "links": [], + "status": "completed", + "completedBy": "fx_alice", + "completedAt": 1767226500000, + "evidenceUrl": "https://github.com/example/example/pull/2" + }, + { + "id": "fx-docs-03", + "title": "Document a removed option in example/docs-options.md", + "summary": "Note that an option was removed.", + "description": "`--legacy` was removed. Note the removal in `example/docs-options.md`.", + "theme": "example-docs", + "difficulty": "beginner", + "area": "docs", + "skills": ["markdown"], + "estimatedMinutes": 15, + "links": [], + "status": "uncompletable", + "uncompletableReason": "Removed by an organizer.", + "uncompletableBy": "fx_ada", + "uncompletableAt": 1767238200000 + }, + { + "id": "fx-docs-04", + "title": "Fix broken links in example/docs-links.md", + "summary": "Repair two links that point at moved pages.", + "description": "Two links in `example/docs-links.md` point at pages that moved. Update them.", + "theme": "example-docs", + "difficulty": "beginner", + "area": "docs", + "skills": ["markdown"], + "estimatedMinutes": 15, + "links": [] + }, + { + "id": "fx-manual-01", + "title": "Profile a slow example endpoint", + "summary": "Find and fix the slowest step in an example request handler.", + "description": "The `/example` endpoint takes 2 s. Profile it, find the slowest step, and fix it.\n\nNo theme guide: this task stands on its own.", + "difficulty": "advanced", + "area": "core", + "skills": ["performance", "profiling"], + "estimatedMinutes": 120, + "links": [{ "label": "Example issue", "url": "https://example.com/issues/1" }] + }, + { + "id": "fx-manual-02", + "title": "Add a dark-mode screenshot to the example site", + "summary": "Capture and add one screenshot.", + "description": "The example site's README shows only light mode. Add a dark-mode screenshot.", + "difficulty": "beginner", + "area": "website", + "skills": ["design"], + "estimatedMinutes": 30, + "links": [{ "label": "Example site", "url": "https://example.com/" }] + }, + { + "id": "fx-manual-03", + "title": "Add a progress message to the example CLI", + "summary": "Print progress while a long command runs.", + "description": "`example-cli build` prints nothing for 30 s. Print a progress line for each step.", + "difficulty": "intermediate", + "area": "tooling", + "skills": ["javascript", "cli"], + "estimatedMinutes": 60, + "links": [] + }, + { + "id": "fx-curated-01", + "theme": "example-tests", + "tier": "easy", + "subsystem": "fixtures", + "title": "Use node:test in example/test-legacy.js", + "commitPrefix": "test:", + "files": ["example/test-legacy.js"], + "detail": "`example/test-legacy.js` uses a hand-rolled test harness. Port it to `node:test`.", + "verifyCommand": "node --test example/test-legacy.js" + }, + { + "id": "fx-curated-02", + "theme": "example-refactor", + "tier": "medium", + "subsystem": "fixtures", + "title": "Remove a deprecated API call in example/legacy-api.js", + "commitPrefix": "lib:", + "files": ["example/legacy-api.js", "example/legacy-api.test.js"], + "detail": "`example/legacy-api.js` calls the deprecated `oldParse()`. Switch it to `parse()` and update its test.", + "verifyCommand": "node --test example/legacy-api.test.js", + "gotcha": "`parse()` throws on empty input where `oldParse()` returned null." + } + ] +} diff --git a/fixtures/users.json b/fixtures/users.json new file mode 100644 index 0000000..1d9b703 --- /dev/null +++ b/fixtures/users.json @@ -0,0 +1,23 @@ +{ + "users": [ + { "id": "fx_ada", "name": "Ada (fixture admin)", "avatarUrl": null, "isAdmin": true }, + { "id": "fx_alice", "name": "Alice (fixture attendee)", "avatarUrl": null, "isAdmin": false }, + { "id": "fx_bob", "name": "Bob (fixture attendee)", "avatarUrl": null, "isAdmin": false }, + { + "id": "fx_carol", + "name": "Carol (fixture, banned)", + "avatarUrl": null, + "isAdmin": false, + "bannedAt": 1767225600000, + "banReason": "Fixture: opened spam pull requests" + }, + { + "id": "fx_dave", + "name": "Dave (fixture, timed out)", + "avatarUrl": null, + "isAdmin": false, + "timeoutUntil": 4102444800000 + }, + { "id": "fx_erin", "name": "Erin (fixture attendee)", "avatarUrl": null, "isAdmin": false } + ] +} diff --git a/resources/bootstrap.ts b/resources/bootstrap.ts index ab72116..1943ca2 100644 --- a/resources/bootstrap.ts +++ b/resources/bootstrap.ts @@ -5,8 +5,12 @@ * data/contribution-tasks.json,data/manual.json — any * admin bulk-import shape) as the starting pool. * LOCAL_GUIDES_FILE= loads the per-theme guides (data/contribution-guides.json). + * LOCAL_SEED= loads a fixture set (fixtures/): tasks with their + * live state (claims, completions, flags), guides, + * users (including moderation), and settings. Local + * instances only; see shared/local.ts. * - * Deterministic ids keep both loads idempotent across Harper's worker threads + * Deterministic ids keep every load idempotent across Harper's worker threads * and restarts — existing records are never overwritten, so admin edits stick. * Real deployments leave these unset and import the curated files from /admin. */ @@ -20,10 +24,13 @@ import { SYSTEM, Task, User, + Setting, type GuideRecord, type TaskRecord, + type TaskStatus, } from './shared/harper.ts'; import { LOCAL_DEV_LOGIN, LOCAL_DEV_USER } from './shared/auth.ts'; +import { isLocalInstance } from './shared/local.ts'; import { validateTaskInput } from './shared/tasks.ts'; import { validateGuideInput } from './Guides.ts'; import { renderMarkdown } from './shared/render.ts'; @@ -114,6 +121,130 @@ if (process.env.LOCAL_GUIDES_FILE) { })().catch((error) => console.error('LOCAL_GUIDES_FILE load failed:', error)); } +// A fixture set keeps each task's live state, unlike LOCAL_DATA_FILE (which +// opens every task), and adds users and settings, so every claim, completion, +// flag, and moderation state is there to work with from the first boot. +const TASK_STATUSES: TaskStatus[] = [ + 'available', + 'claimed', + 'completed', + 'flagged', + 'uncompletable', +]; +const TASK_STATE_FIELDS = [ + 'assignedTo', + 'assignedName', + 'assignedAt', + 'assignedBy', + 'completedBy', + 'completedAt', + 'evidenceUrl', + 'uncompletableReason', + 'uncompletableBy', + 'uncompletableAt', +]; +const USER_FIELDS = ['name', 'avatarUrl', 'isAdmin', 'bannedAt', 'banReason', 'timeoutUntil']; + +function pick(input: Record, fields: string[]): Record { + const out: Record = {}; + for (const field of fields) if (input[field] !== undefined) out[field] = input[field]; + return out; +} + +// Reads `/.json` as { [name]: [...] } (or a bare array); a missing +// file is an empty list, so a fixture set can leave parts out. +async function readSeedList(dir: string, name: string): Promise[]> { + let parsed: unknown; + try { + parsed = await readJson(join(dir, `${name}.json`)); + } catch (error) { + if ((error as NodeJS.ErrnoException).code === 'ENOENT') return []; + throw error; + } + const list = Array.isArray(parsed) ? parsed : (parsed as Record)[name]; + if (!Array.isArray(list)) throw new Error(`${dir}/${name}.json has no "${name}" array`); + return list as Record[]; +} + +if (process.env.LOCAL_SEED) { + (async () => { + const dir = process.env.LOCAL_SEED as string; + if (!isLocalInstance()) { + console.error( + `LOCAL_SEED ignored: OAUTH_REDIRECT_URI (${process.env.OAUTH_REDIRECT_URI}) is not a local origin. Fixtures load on local instances only.`, + ); + return; + } + const counts = { guides: 0, users: 0, settings: 0, tasks: 0, existing: 0 }; + + for (const [index, input] of (await readSeedList(dir, 'guides')).entries()) { + const { guide, problem } = validateGuideInput(input); + if (problem) { + console.warn(`LOCAL_SEED guides entry ${index + 1} skipped: ${problem}`); + continue; + } + if (await Guide.get(guide!.id, SYSTEM)) { + counts.existing++; + } else { + await Guide.put(record(guide!), SYSTEM); + counts.guides++; + } + } + + for (const [index, input] of (await readSeedList(dir, 'users')).entries()) { + const id = String(input.id ?? '') + .trim() + .toLowerCase(); + if (!id) { + console.warn(`LOCAL_SEED users entry ${index + 1} skipped: id is required`); + continue; + } + if (await User.get(id, SYSTEM)) { + counts.existing++; + } else { + await User.put(record({ id, ...pick(input, USER_FIELDS) }), SYSTEM); + counts.users++; + } + } + + for (const [index, input] of (await readSeedList(dir, 'settings')).entries()) { + const id = String(input.id ?? '').trim(); + if (!id) { + console.warn(`LOCAL_SEED settings entry ${index + 1} skipped: id is required`); + continue; + } + if (await Setting.get(id, SYSTEM)) { + counts.existing++; + } else { + await Setting.put(record({ id, value: input.value }), SYSTEM); + counts.settings++; + } + } + + for (const [index, input] of (await readSeedList(dir, 'tasks')).entries()) { + const id = String(input.id ?? '').trim(); + const { task, problem } = validateTaskInput(input); + if (problem || !id) { + console.warn(`LOCAL_SEED tasks entry ${index + 1} skipped: ${problem ?? 'id is required'}`); + continue; + } + const status = TASK_STATUSES.includes(input.status as TaskStatus) + ? (input.status as TaskStatus) + : 'available'; + if (await Task.get(id, SYSTEM)) { + counts.existing++; + } else { + await Task.put(record({ ...task, ...pick(input, TASK_STATE_FIELDS), id, status }), SYSTEM); + counts.tasks++; + } + } + + console.log( + `LOCAL_SEED ${dir}: added ${counts.tasks} tasks, ${counts.guides} guides, ${counts.users} users, ${counts.settings} settings (${counts.existing} already present)`, + ); + })().catch((error) => console.error('LOCAL_SEED load failed:', error)); +} + if (LOCAL_DEV_LOGIN) { (async () => { if (!(await User.get(LOCAL_DEV_USER, SYSTEM))) { diff --git a/resources/shared/local.ts b/resources/shared/local.ts new file mode 100644 index 0000000..0f81ad0 --- /dev/null +++ b/resources/shared/local.ts @@ -0,0 +1,21 @@ +/** + * Whether this instance is a local development one. Dev-only features + * (fixture seeding, and anything else that must never run against real + * users) gate on it. + * + * Every deployed environment sets OAUTH_REDIRECT_URI to its public origin; + * locally it is unset (the OAuth plugin then defaults to localhost) or points + * at a loopback host. + */ +const LOOPBACK_HOSTS = new Set(['localhost', '127.0.0.1', '[::1]']); + +export function isLocalInstance(): boolean { + const redirect = process.env.OAUTH_REDIRECT_URI; + if (!redirect) return true; + try { + const { hostname } = new URL(redirect); + return LOOPBACK_HOSTS.has(hostname) || hostname.endsWith('.localhost'); + } catch { + return false; + } +}