From 2afea627c94f01ffc227b6f8203970396651b009 Mon Sep 17 00:00:00 2001 From: joshunrau Date: Wed, 18 Nov 2026 20:02:12 -0500 Subject: [PATCH 1/8] chore: add turbo skill --- .agents/skills/turborepo/SKILL.md | 26 ++++++++++++++++++++++++++ .claude/skills/turborepo | 1 + skills-lock.json | 7 +++++++ 3 files changed, 34 insertions(+) create mode 100644 .agents/skills/turborepo/SKILL.md create mode 120000 .claude/skills/turborepo diff --git a/.agents/skills/turborepo/SKILL.md b/.agents/skills/turborepo/SKILL.md new file mode 100644 index 000000000..15eaeb96a --- /dev/null +++ b/.agents/skills/turborepo/SKILL.md @@ -0,0 +1,26 @@ +--- +name: turborepo +description: Configure and troubleshoot Turborepo repositories. Use when working with turbo.json, task pipelines, caching, Remote Cache, the turbo CLI, filtering, environment variables, package boundaries, monorepo structure, or CI workflows. +--- + +# Turborepo + +The complete Turborepo documentation ships inside the installed `turbo` package. Do not rely on this skill for framework guidance. Always read the bundled docs, which match the installed version exactly. + +Start with: + +```text +node_modules/turbo/docs/README.md +``` + +Use that task index to choose the smallest relevant documentation page. Read it before changing Turborepo configuration, package scripts, or CI workflows. + +If the package manager uses a non-flat `node_modules` layout or a workspace link, resolve the package location first: + +```sh +node -p "require.resolve('turbo/package.json')" +``` + +Then read `docs/README.md` relative to the resolved package directory. + +If `turbo` is not installed, inspect the repository's package manager and existing version constraints before adding it. After installation, use the bundled docs rather than guidance for a different release. diff --git a/.claude/skills/turborepo b/.claude/skills/turborepo new file mode 120000 index 000000000..b69a7d9eb --- /dev/null +++ b/.claude/skills/turborepo @@ -0,0 +1 @@ +../../.agents/skills/turborepo \ No newline at end of file diff --git a/skills-lock.json b/skills-lock.json index 75495c9c4..67dba5db4 100644 --- a/skills-lock.json +++ b/skills-lock.json @@ -19,6 +19,13 @@ "skillPath": "skills/interview/SKILL.md", "computedHash": "92f32340ae3ac0f6b7f345ed07279c60306138b5d12005b2aa2186f8fd1d97f6" }, + "turborepo": { + "source": "vercel/turborepo", + "commit": "d4dfbcf3824133ccbb467ccbac38b125964b3ad0", + "sourceType": "github", + "skillPath": "skills/turborepo/SKILL.md", + "computedHash": "49bb6427015253ce5d93f15dfa6c9ade3f8528f0fbe54769b6da1e1458f058d4" + }, "writing-normative-prose": { "source": "joshunrau/skills", "sourceType": "github", From 73eb33d2f19d7d0dc5b8bee4a998ccc69c09d566 Mon Sep 17 00:00:00 2001 From: joshunrau Date: Wed, 18 Nov 2026 20:25:44 -0500 Subject: [PATCH 2/8] build: rework the turbo task graph and lint the repo in one pass Caching was defeated by how tasks were keyed, and lint paid for 28 separate type-checks. Cache keys: - .env is no longer a global dependency. It is generated with random secrets per clone, so no cache entry was ever valid in another checkout, and every edit to it reran every task. A task still sees a variable only through its `env` key. - NODE_ENV leaves globalEnv and NODE_OPTIONS becomes pass-through, and the build `env` list moves to the two apps that read it, so the library builds hash the same under `pnpm lint`, `pnpm build` and `pnpm dev` instead of three different ways. - TURBO_CACHE_DIR leaves .env.template. It reached turbo only through env-cmd, which split the cache across two directories and switched off the cache sharing turbo does between git worktrees. - runtime-core's build declares `lib/**` as an output. A cache hit restored `dist` alone, leaving the `./constants` export unresolved. - `build` hashes neither `*.md` nor `__tests__/`, `db:generate` hashes the schema alone, and outreach hashes the /docs and /blog trees its content links to, which turbo saw only as symlinks. Graph: - `lint` no longer depends on `db:push`, and nothing depends on the never-matching `^db:generate`. `db:push` is defined in the gateway, the one workspace that has it, and its build no longer runs it. - `//#generated` names what a whole-repo tool reads that source control does not hold. `test:e2e` depends on it explicitly, so the task is correct under `--filter` rather than only when every workspace is in scope. - `pnpm test` and `pnpm test:coverage` build the packages that export only build output first, instead of reading whatever `dist` is on disk. - `start` depends on its own `build`, and persistent tasks are uncached. Lint: - `pnpm lint` runs one `oxlint --type-check --fix` over the repo in place of `tsc && oxlint --fix src` in each workspace; outreach keeps `astro check`. A cold run drops from 22-25s to 12s on 11 cores. - That pass also covers the files the per-package scripts skipped (vite configs, build scripts, runtime/v1's tests), whose findings are fixed here. - `pnpm format` is one `oxfmt` run rather than 26 turbo tasks. Co-Authored-By: Claude Fable 5.2 --- .env.template | 2 - apps/api/libnest.config.ts | 6 +- apps/api/package.json | 2 - apps/api/turbo.json | 10 ++++ apps/api/vitest.config.ts | 2 +- apps/gateway/package.json | 2 - apps/gateway/scripts/build.ts | 4 +- apps/gateway/scripts/dev.ts | 6 +- apps/gateway/turbo.json | 17 ++++++ apps/gateway/vite.config.ts | 6 +- apps/gateway/vitest.config.ts | 2 +- apps/outreach/astro.config.ts | 10 ++-- apps/outreach/package.json | 3 +- apps/outreach/turbo.json | 14 +++++ apps/playground/package.json | 2 - apps/playground/turbo.json | 9 +++ apps/playground/vite.config.ts | 12 ++-- apps/web/package.json | 2 - apps/web/turbo.json | 9 +++ apps/web/vite.config.ts | 6 +- oxlint.config.ts | 2 + package.json | 9 +-- packages/demo/package.json | 4 -- packages/instrument-bundler/package.json | 2 - packages/instrument-guidelines/package.json | 4 -- packages/instrument-interpreter/package.json | 2 - packages/instrument-library/package.json | 2 - .../instrument-library/scripts/available.ts | 6 +- packages/instrument-stubs/package.json | 2 - packages/instrument-utils/package.json | 2 - packages/licenses/package.json | 4 -- packages/oxlint-config/package.json | 2 - packages/playground-url/package.json | 2 - packages/react-core/package.json | 2 - packages/release-info/package.json | 2 - packages/runtime-bundler/package.json | 2 - packages/runtime-bundler/test/e2e.test.ts | 8 +-- packages/runtime-core/package.json | 2 - packages/runtime-core/turbo.json | 9 +++ packages/runtime-internal/package.json | 2 - packages/runtime-meta/package.json | 2 - packages/schemas/package.json | 2 - packages/serve-instrument/package.json | 2 - packages/serve-instrument/scripts/build.js | 6 +- packages/subject-utils/package.json | 2 - packages/vite-plugin-runtime/package.json | 2 - runtime/v1/global.d.ts | 2 +- runtime/v1/test/vendor-pairing.test.ts | 6 +- runtime/v1/tsconfig.json | 2 +- storybook/package.json | 2 - testing/package.json | 1 - testing/turbo.json | 10 ++++ turbo.json | 60 +++++++++---------- 53 files changed, 155 insertions(+), 140 deletions(-) create mode 100644 apps/api/turbo.json create mode 100644 apps/gateway/turbo.json create mode 100644 apps/outreach/turbo.json create mode 100644 apps/playground/turbo.json create mode 100644 apps/web/turbo.json create mode 100644 packages/runtime-core/turbo.json create mode 100644 testing/turbo.json diff --git a/.env.template b/.env.template index 12291da0a..5b334cdd1 100644 --- a/.env.template +++ b/.env.template @@ -151,5 +151,3 @@ VITE_DEV_DISABLE_TUTORIAL=false # Plausable analytics config (optional, set both to an empty string to disable) PLAUSIBLE_BASE_URL= PLAUSIBLE_WEB_DATA_DOMAIN= - -TURBO_CACHE_DIR=".turbo" diff --git a/apps/api/libnest.config.ts b/apps/api/libnest.config.ts index 8e607deda..8c5b046e3 100644 --- a/apps/api/libnest.config.ts +++ b/apps/api/libnest.config.ts @@ -1,6 +1,6 @@ -/* eslint-disable @typescript-eslint/no-empty-object-type */ -/* eslint-disable @typescript-eslint/consistent-type-definitions */ -/* eslint-disable @typescript-eslint/no-namespace */ +/* eslint-disable @typescript-eslint/no-empty-object-type -- Env and PrismaClient only inherit, and must be interfaces to merge into libnest's UserTypes */ +/* eslint-disable @typescript-eslint/consistent-type-definitions -- libnest's UserTypes members are augmented by declaration merging, which a type alias cannot do */ +/* eslint-disable @typescript-eslint/no-namespace -- libnest exports UserTypes as a namespace, and augmenting a namespace requires redeclaring it */ import * as fs from 'node:fs/promises'; import * as path from 'node:path'; diff --git a/apps/api/package.json b/apps/api/package.json index 9e3d601dc..a1c624ce4 100644 --- a/apps/api/package.json +++ b/apps/api/package.json @@ -15,8 +15,6 @@ "db:generate": "prisma generate --no-hints", "dev": "NODE_ENV=development NODE_OPTIONS='--conditions=development' env-cmd -f ../../.env libnest dev -c libnest.config.ts", "dev:test": "NODE_ENV=test env-cmd -f ../../.env env STORAGE_ENABLED=true libnest dev -c libnest.config.ts --no-watch", - "format": "oxfmt src test", - "lint": "tsc && oxlint --fix src test", "start": "NODE_ENV=production env-cmd -f ../../.env node dist/app.js", "test": "env-cmd -f ../../.env vitest" }, diff --git a/apps/api/turbo.json b/apps/api/turbo.json new file mode 100644 index 000000000..cf86a7b56 --- /dev/null +++ b/apps/api/turbo.json @@ -0,0 +1,10 @@ +{ + "$schema": "https://turbo.build/schema.json", + "extends": ["//"], + "tasks": { + // prisma/schema.prisma sets no output, so the client lands in pnpm's store, outside what turbo can restore + "db:generate": { + "cache": false + } + } +} diff --git a/apps/api/vitest.config.ts b/apps/api/vitest.config.ts index 36464b388..18cfef3f7 100644 --- a/apps/api/vitest.config.ts +++ b/apps/api/vitest.config.ts @@ -1,4 +1,4 @@ -import path from 'path'; +import path from 'node:path'; import libnest from '@douglasneuroinformatics/libnest/testing/plugin'; import { defineProject, mergeConfig } from 'vitest/config'; diff --git a/apps/gateway/package.json b/apps/gateway/package.json index e76af064e..372b3dbec 100644 --- a/apps/gateway/package.json +++ b/apps/gateway/package.json @@ -12,8 +12,6 @@ "db:push": "env-cmd --silent -f ../../.env prisma db push --skip-generate", "dev": "NODE_ENV=development env-cmd -f ../../.env tsx scripts/dev.ts && env-cmd -f ../../.env node dist/main.js", "dev:test": "NODE_ENV=test env-cmd -f ../../.env tsx scripts/dev.ts && env-cmd -f ../../.env node dist/main.js", - "format": "oxfmt src", - "lint": "tsc && oxlint --fix src", "test": "env-cmd -f ../../.env vitest", "start": "NODE_ENV=production env-cmd -f ../../.env node dist/main.js" }, diff --git a/apps/gateway/scripts/build.ts b/apps/gateway/scripts/build.ts index 05edba8dd..6717b18dc 100644 --- a/apps/gateway/scripts/build.ts +++ b/apps/gateway/scripts/build.ts @@ -1,6 +1,6 @@ #!/usr/bin/env tsx -import path from 'path'; +import path from 'node:path'; import { prismaPlugin } from '@douglasneuroinformatics/esbuild-plugin-prisma'; import { getReleaseInfo } from '@opendatacapture/release-info'; @@ -35,5 +35,5 @@ await esbuild.build({ tsconfig }); -// eslint-disable-next-line no-console +// eslint-disable-next-line no-console -- a build script reports that it finished console.log('Done!'); diff --git a/apps/gateway/scripts/dev.ts b/apps/gateway/scripts/dev.ts index c815a4d2a..fe9516914 100644 --- a/apps/gateway/scripts/dev.ts +++ b/apps/gateway/scripts/dev.ts @@ -1,9 +1,9 @@ #!/usr/bin/env tsx -/* eslint-disable no-console */ +/* eslint-disable no-console -- a dev script reports each build to the terminal */ -import fs from 'fs'; -import path from 'path'; +import fs from 'node:fs'; +import path from 'node:path'; import { getReleaseInfo } from '@opendatacapture/release-info'; import esbuild from 'esbuild'; diff --git a/apps/gateway/turbo.json b/apps/gateway/turbo.json new file mode 100644 index 000000000..ef513d6d7 --- /dev/null +++ b/apps/gateway/turbo.json @@ -0,0 +1,17 @@ +{ + "$schema": "https://turbo.build/schema.json", + "extends": ["//"], + "tasks": { + "db:push": { + "cache": false, + "dependsOn": ["db:generate"], + "env": ["GATEWAY_DATABASE_URL"] + }, + "dev": { + "dependsOn": ["$TURBO_EXTENDS$", "db:push"] + }, + "dev:test": { + "dependsOn": ["$TURBO_EXTENDS$", "db:push"] + } + } +} diff --git a/apps/gateway/vite.config.ts b/apps/gateway/vite.config.ts index b860ad626..e1615a9fd 100644 --- a/apps/gateway/vite.config.ts +++ b/apps/gateway/vite.config.ts @@ -1,4 +1,4 @@ -import path from 'path'; +import path from 'node:path'; import runtime from '@opendatacapture/vite-plugin-runtime'; import tailwindcss from '@tailwindcss/vite'; @@ -13,12 +13,12 @@ export default defineConfig(({ mode }) => ({ target: 'es2022' }, optimizeDeps: { + include: ['react/*', 'react-dom/*'], rolldownOptions: { transform: { target: 'es2022' } - }, - include: ['react/*', 'react-dom/*'] + } }, plugins: [ react(), diff --git a/apps/gateway/vitest.config.ts b/apps/gateway/vitest.config.ts index ef65e1631..4f6d17f6d 100644 --- a/apps/gateway/vitest.config.ts +++ b/apps/gateway/vitest.config.ts @@ -1,4 +1,4 @@ -import path from 'path'; +import path from 'node:path'; import { defineProject, mergeConfig } from 'vitest/config'; diff --git a/apps/outreach/astro.config.ts b/apps/outreach/astro.config.ts index 95d707793..b4a8d5a58 100644 --- a/apps/outreach/astro.config.ts +++ b/apps/outreach/astro.config.ts @@ -1,6 +1,6 @@ -import fs from 'fs'; -import module from 'module'; -import path from 'path'; +import fs from 'node:fs'; +import module from 'node:module'; +import path from 'node:path'; import sitemap from '@astrojs/sitemap'; import starlight from '@astrojs/starlight'; @@ -126,7 +126,7 @@ export default defineConfig({ return function (tree, { data }) { const textOnPage = toString(tree); const readingTime = getReadingTime(textOnPage); - // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access + // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access -- remark types `data` as an open record, and Astro documents `astro.frontmatter` without typing it (data.astro as any).frontmatter.readingTime = readingTime.minutes; }; } @@ -140,7 +140,7 @@ export default defineConfig({ '/fr/docs': '/fr/docs/introduction/home' }, server: { - port: parseInt(process.env.OUTREACH_DEV_SERVER_PORT ?? '4000') + port: parseInt(process.env.OUTREACH_DEV_SERVER_PORT ?? '4000', 10) }, site: 'https://opendatacapture.org', vite: { diff --git a/apps/outreach/package.json b/apps/outreach/package.json index abf2ee452..513875cb4 100644 --- a/apps/outreach/package.json +++ b/apps/outreach/package.json @@ -6,9 +6,8 @@ "astro": "astro", "build": "astro build", "dev": "astro dev", - "format": "oxfmt src", "format:translations": "find src/i18n/translations -name '*.json' -exec pnpm exec sort-json {} \\;", - "lint": "astro check && oxlint --fix src" + "lint": "astro check" }, "dependencies": { "@douglasneuroinformatics/libui": "catalog:", diff --git a/apps/outreach/turbo.json b/apps/outreach/turbo.json new file mode 100644 index 000000000..3fbee9a89 --- /dev/null +++ b/apps/outreach/turbo.json @@ -0,0 +1,14 @@ +{ + "$schema": "https://turbo.build/schema.json", + "extends": ["//"], + "tasks": { + // src/content links to /docs and /blog, and turbo hashes a link rather than what it points to + "build": { + "inputs": ["$TURBO_DEFAULT$", "$TURBO_ROOT$/blog/**", "$TURBO_ROOT$/docs/**"] + }, + "lint": { + "dependsOn": ["^build"], + "inputs": ["$TURBO_DEFAULT$", "$TURBO_ROOT$/blog/**", "$TURBO_ROOT$/docs/**"] + } + } +} diff --git a/apps/playground/package.json b/apps/playground/package.json index efe18672c..4768359ed 100644 --- a/apps/playground/package.json +++ b/apps/playground/package.json @@ -8,8 +8,6 @@ "build": "tsc && pnpm exec vite build", "deploy": "rsync -r dist/* unrjos@cloud1.douglasneuroinformatics.ca:/home/unrjos/www/playground.opendatacapture.org", "dev": "NODE_ENV=development pnpm exec vite", - "format": "oxfmt src", - "lint": "tsc && oxlint --fix src", "test": "env-cmd -f ../../.env vitest" }, "dependencies": { diff --git a/apps/playground/turbo.json b/apps/playground/turbo.json new file mode 100644 index 000000000..fb1c9c40b --- /dev/null +++ b/apps/playground/turbo.json @@ -0,0 +1,9 @@ +{ + "$schema": "https://turbo.build/schema.json", + "extends": ["//"], + "tasks": { + "build": { + "env": ["GITHUB_REPO_URL"] + } + } +} diff --git a/apps/playground/vite.config.ts b/apps/playground/vite.config.ts index 60c229308..0f49645cb 100644 --- a/apps/playground/vite.config.ts +++ b/apps/playground/vite.config.ts @@ -1,5 +1,5 @@ -import fs from 'fs'; -import path from 'path'; +import fs from 'node:fs'; +import path from 'node:path'; import runtime from '@opendatacapture/vite-plugin-runtime'; import tailwindcss from '@tailwindcss/vite'; @@ -47,13 +47,13 @@ export default defineConfig(({ mode }) => ({ __GITHUB_REPO_URL__: `'${process.env.GITHUB_REPO_URL ?? '#'}'` }, optimizeDeps: { + exclude: ['@swc/wasm-web'], + include: ['react/*', 'react-dom/*'], rolldownOptions: { transform: { target: 'es2022' } - }, - exclude: ['@swc/wasm-web'], - include: ['react/*', 'react-dom/*'] + } }, plugins: [ playgroundConfig(), @@ -75,6 +75,6 @@ export default defineConfig(({ mode }) => ({ // connect. Browsers try both addresses for `localhost`, so this serves both names without // opening the server to the network the way `host: true` would. host: '127.0.0.1', - port: parseInt(process.env.PLAYGROUND_DEV_SERVER_PORT ?? '3750') + port: parseInt(process.env.PLAYGROUND_DEV_SERVER_PORT ?? '3750', 10) } })); diff --git a/apps/web/package.json b/apps/web/package.json index 85f3e3440..794651e85 100644 --- a/apps/web/package.json +++ b/apps/web/package.json @@ -8,9 +8,7 @@ "build": "tsc && NODE_ENV=production NODE_OPTIONS='--import=tsx' pnpm exec vite build", "dev": "NODE_ENV=development NODE_OPTIONS='--import=tsx' env-cmd -f ../../.env pnpm exec vite", "dev:test": "NODE_ENV=test NODE_OPTIONS='--import=tsx' env-cmd -f ../../.env pnpm exec vite --mode test", - "format": "oxfmt src", "format:translations": "find src/translations -name '*.json' -exec pnpm exec sort-json {} \\;", - "lint": "tsc && oxlint --fix src", "start": "NODE_ENV=production env-cmd -f ../../.env -- pnpm exec import-meta-env -x .env.public -p dist/index.html && python -m http.server -d dist 3000", "test": "env-cmd -f ../../.env vitest" }, diff --git a/apps/web/turbo.json b/apps/web/turbo.json new file mode 100644 index 000000000..5f6870e84 --- /dev/null +++ b/apps/web/turbo.json @@ -0,0 +1,9 @@ +{ + "$schema": "https://turbo.build/schema.json", + "extends": ["//"], + "tasks": { + "build": { + "env": ["API_BASE_URL", "CONTACT_EMAIL", "DOCS_URL", "GATEWAY_ENABLED", "GITHUB_REPO_URL", "LICENSE_URL"] + } + } +} diff --git a/apps/web/vite.config.ts b/apps/web/vite.config.ts index 63fd1bbc4..6719ad35c 100644 --- a/apps/web/vite.config.ts +++ b/apps/web/vite.config.ts @@ -1,4 +1,4 @@ -import path from 'path'; +import path from 'node:path'; import { parseNumber } from '@douglasneuroinformatics/libjs'; import importMetaEnv from '@import-meta-env/unplugin'; @@ -36,12 +36,12 @@ export default defineConfig(async ({ command }) => { __RELEASE__: JSON.stringify(await getReleaseInfo()) }, optimizeDeps: { + include: ['react/*', 'react-dom/*'], rolldownOptions: { transform: { target: 'es2022' } - }, - include: ['react/*', 'react-dom/*'] + } }, plugins: [ tanstackRouter({ diff --git a/oxlint.config.ts b/oxlint.config.ts index cdc6e26da..91626995b 100644 --- a/oxlint.config.ts +++ b/oxlint.config.ts @@ -65,6 +65,8 @@ export default defineConfig({ 'apps/playground/src/instruments/examples/interactive/Interactive-With-Legacy-Script/legacy.js', // Generated by the TanStack Router plugin, which writes a bare `eslint-disable` at its top. 'apps/web/src/route-tree.ts', + // Stand-ins for published packages, written in the module formats the bundler has to accept. + 'packages/runtime-bundler/test/fixtures/**', 'testing/.playwright/**', 'vendor/**/*' ], diff --git a/package.json b/package.json index c622f46c3..ae9b0ca49 100644 --- a/package.json +++ b/package.json @@ -14,6 +14,7 @@ "type": "module", "scripts": { "build": "env-cmd turbo run build", + "build:exports": "turbo run build --filter=@opendatacapture/instrument-library... --output-logs=errors-only", "check": "pnpm lint && pnpm test:coverage && pnpm test:e2e", "clean": "find . -type d '(' -name '.turbo' -o -name 'dist' -o -name 'node_modules' ')' -prune -exec rm -rf {} \\;", "clean:workflows": "./scripts/clean-workflows.sh", @@ -24,16 +25,16 @@ "dev:core": "NODE_ENV=development env-cmd pnpm exec turbo run dev --filter=@opendatacapture/api --filter=@opendatacapture/gateway --filter=@opendatacapture/web", "dev:test": "NODE_ENV=test env-cmd turbo run dev:test", "force-reinstall": "pnpm clean && pnpm install", - "format": "turbo run format", + "format": "oxfmt", "generate:env": "./scripts/generate-env.sh", "knip": "NODE_ENV=development env-cmd knip", "lint": "turbo run lint lint:root", - "lint:root": "tsc --noEmit && oxlint --fix .github/scripts .github/vitest.config.ts commitlint.config.ts knip.ts oxfmt.config.ts oxlint.config.ts scripts vitest.config.ts", + "lint:root": "oxlint --type-check --fix", "postinstall": "turbo telemetry disable", "prepare": "husky", "start": "turbo run start", - "test": "env-cmd vitest", - "test:coverage": "env-cmd vitest --coverage", + "test": "pnpm build:exports && env-cmd vitest", + "test:coverage": "pnpm build:exports && env-cmd vitest --coverage", "test:e2e": "env-cmd turbo run test:e2e", "ws": "./scripts/workspace.sh $@" }, diff --git a/packages/demo/package.json b/packages/demo/package.json index 51391ebf9..dcbe1a5e1 100644 --- a/packages/demo/package.json +++ b/packages/demo/package.json @@ -7,10 +7,6 @@ "exports": { ".": "./src/index.ts" }, - "scripts": { - "format": "oxfmt src", - "lint": "tsc && oxlint --fix src" - }, "dependencies": { "@douglasneuroinformatics/libjs": "catalog:", "@opendatacapture/schemas": "workspace:*" diff --git a/packages/instrument-bundler/package.json b/packages/instrument-bundler/package.json index 3e1dae6fb..dd237c05a 100644 --- a/packages/instrument-bundler/package.json +++ b/packages/instrument-bundler/package.json @@ -25,8 +25,6 @@ "access": "public" }, "scripts": { - "format": "oxfmt src", - "lint": "tsc && oxlint --fix src", "test": "vitest" }, "dependencies": { diff --git a/packages/instrument-guidelines/package.json b/packages/instrument-guidelines/package.json index cbd3e5944..139e30a6a 100644 --- a/packages/instrument-guidelines/package.json +++ b/packages/instrument-guidelines/package.json @@ -29,9 +29,5 @@ }, "publishConfig": { "access": "public" - }, - "scripts": { - "format": "oxfmt bin", - "lint": "oxlint --fix bin" } } diff --git a/packages/instrument-interpreter/package.json b/packages/instrument-interpreter/package.json index c412c25f8..22870d292 100644 --- a/packages/instrument-interpreter/package.json +++ b/packages/instrument-interpreter/package.json @@ -8,8 +8,6 @@ ".": "./src/index.ts" }, "scripts": { - "format": "oxfmt src", - "lint": "tsc && oxlint --fix src", "test": "vitest" }, "dependencies": { diff --git a/packages/instrument-library/package.json b/packages/instrument-library/package.json index 7cbb65409..964abd4ca 100644 --- a/packages/instrument-library/package.json +++ b/packages/instrument-library/package.json @@ -15,8 +15,6 @@ "scripts": { "available": "tsx scripts/available.ts", "build": "tsx ../instrument-bundler/src/cli.ts --clean --declaration --outdir dist src", - "format": "oxfmt src", - "lint": "tsc && oxlint --fix src", "test": "vitest" }, "dependencies": { diff --git a/packages/instrument-library/scripts/available.ts b/packages/instrument-library/scripts/available.ts index b50097cfe..70251a900 100644 --- a/packages/instrument-library/scripts/available.ts +++ b/packages/instrument-library/scripts/available.ts @@ -1,9 +1,9 @@ #!/usr/bin/env tsx -/* eslint-disable no-console */ +/* eslint-disable no-console -- a CLI whose output is the list it prints */ -import fs from 'fs/promises'; -import path from 'path'; +import fs from 'node:fs/promises'; +import path from 'node:path'; import type { AnyInstrument, InstrumentKind } from '@opendatacapture/runtime-v1/@opendatacapture/runtime-core/index.js'; diff --git a/packages/instrument-stubs/package.json b/packages/instrument-stubs/package.json index ded893153..4cbc2b79f 100644 --- a/packages/instrument-stubs/package.json +++ b/packages/instrument-stubs/package.json @@ -11,8 +11,6 @@ "./series": "./src/series.js" }, "scripts": { - "format": "oxfmt src", - "lint": "oxlint --fix src", "test": "vitest" }, "dependencies": { diff --git a/packages/instrument-utils/package.json b/packages/instrument-utils/package.json index 5fac198f8..77d593896 100644 --- a/packages/instrument-utils/package.json +++ b/packages/instrument-utils/package.json @@ -8,8 +8,6 @@ ".": "./src/index.ts" }, "scripts": { - "format": "oxfmt src", - "lint": "tsc && oxlint --fix src", "test": "vitest" }, "dependencies": { diff --git a/packages/licenses/package.json b/packages/licenses/package.json index 54388b7e9..285ca5dc6 100644 --- a/packages/licenses/package.json +++ b/packages/licenses/package.json @@ -11,9 +11,5 @@ "import": "./src/index.js" }, "./package.json": "./package.json" - }, - "scripts": { - "format": "oxfmt src", - "lint": "tsc && oxlint --fix src" } } diff --git a/packages/oxlint-config/package.json b/packages/oxlint-config/package.json index cefc1ab40..3cfdf5906 100644 --- a/packages/oxlint-config/package.json +++ b/packages/oxlint-config/package.json @@ -7,8 +7,6 @@ ".": "./src/index.js" }, "scripts": { - "format": "oxfmt src", - "lint": "tsc && oxlint --fix src", "test": "vitest" }, "dependencies": { diff --git a/packages/playground-url/package.json b/packages/playground-url/package.json index 73de78e28..52c8d2168 100644 --- a/packages/playground-url/package.json +++ b/packages/playground-url/package.json @@ -27,8 +27,6 @@ }, "scripts": { "build": "node scripts/build.js", - "format": "oxfmt src", - "lint": "tsc && oxlint --fix src", "test": "vitest" }, "dependencies": { diff --git a/packages/react-core/package.json b/packages/react-core/package.json index 85f9b3dae..d0986135a 100644 --- a/packages/react-core/package.json +++ b/packages/react-core/package.json @@ -10,8 +10,6 @@ "./globals.css": "./src/globals.css" }, "scripts": { - "format": "oxfmt src", - "lint": "tsc && oxlint --fix src", "test": "vitest" }, "dependencies": { diff --git a/packages/release-info/package.json b/packages/release-info/package.json index be92e9785..ea883970e 100644 --- a/packages/release-info/package.json +++ b/packages/release-info/package.json @@ -8,8 +8,6 @@ ".": "./src/index.ts" }, "scripts": { - "format": "oxfmt src", - "lint": "tsc && oxlint --fix src", "test": "vitest" }, "dependencies": { diff --git a/packages/runtime-bundler/package.json b/packages/runtime-bundler/package.json index 08ae2c1b3..3e00f10c4 100644 --- a/packages/runtime-bundler/package.json +++ b/packages/runtime-bundler/package.json @@ -11,8 +11,6 @@ ".": "./src/index.ts" }, "scripts": { - "format": "oxfmt src", - "lint": "tsc && oxlint --fix src", "test": "vitest" }, "dependencies": { diff --git a/packages/runtime-bundler/test/e2e.test.ts b/packages/runtime-bundler/test/e2e.test.ts index 2ad147179..f1dd49535 100644 --- a/packages/runtime-bundler/test/e2e.test.ts +++ b/packages/runtime-bundler/test/e2e.test.ts @@ -1,7 +1,7 @@ -import * as fs from 'fs/promises'; -import * as os from 'os'; -import * as path from 'path'; -import { pathToFileURL } from 'url'; +import * as fs from 'node:fs/promises'; +import * as os from 'node:os'; +import * as path from 'node:path'; +import { pathToFileURL } from 'node:url'; import { afterAll, beforeAll, describe, expect, it } from 'vitest'; diff --git a/packages/runtime-core/package.json b/packages/runtime-core/package.json index 837e1150e..10eabf5c2 100644 --- a/packages/runtime-core/package.json +++ b/packages/runtime-core/package.json @@ -20,8 +20,6 @@ "build": "rm -rf dist lib && pnpm build:lib && pnpm build:dist", "build:dist": "pnpm exec esbuild --bundle --format=esm --target=es2020 --outfile=dist/index.js --platform=browser lib/index.js && api-extractor run -c config/api-extractor.json", "build:lib": "tsc -b tsconfig.build.json", - "format": "oxfmt src", - "lint": "tsc --noEmit && oxlint --fix src", "test": "vitest" }, "dependencies": { diff --git a/packages/runtime-core/turbo.json b/packages/runtime-core/turbo.json new file mode 100644 index 000000000..78494379c --- /dev/null +++ b/packages/runtime-core/turbo.json @@ -0,0 +1,9 @@ +{ + "$schema": "https://turbo.build/schema.json", + "extends": ["//"], + "tasks": { + "build": { + "outputs": ["$TURBO_EXTENDS$", "lib/**"] + } + } +} diff --git a/packages/runtime-internal/package.json b/packages/runtime-internal/package.json index 42511d8ee..2a33d1769 100644 --- a/packages/runtime-internal/package.json +++ b/packages/runtime-internal/package.json @@ -18,8 +18,6 @@ "./package.json": "./package.json" }, "scripts": { - "format": "oxfmt src", - "lint": "tsc && oxlint --fix src", "test": "vitest" }, "devDependencies": { diff --git a/packages/runtime-meta/package.json b/packages/runtime-meta/package.json index fa0014f22..582fa138b 100644 --- a/packages/runtime-meta/package.json +++ b/packages/runtime-meta/package.json @@ -12,8 +12,6 @@ } }, "scripts": { - "format": "oxfmt src", - "lint": "tsc && oxlint --fix src", "test": "vitest" } } diff --git a/packages/schemas/package.json b/packages/schemas/package.json index 4f476b13b..23b394def 100644 --- a/packages/schemas/package.json +++ b/packages/schemas/package.json @@ -24,8 +24,6 @@ "./user": "./src/user/user.ts" }, "scripts": { - "format": "oxfmt src", - "lint": "tsc && oxlint --fix src", "test": "vitest" }, "dependencies": { diff --git a/packages/serve-instrument/package.json b/packages/serve-instrument/package.json index 2404d17a8..dad970d40 100644 --- a/packages/serve-instrument/package.json +++ b/packages/serve-instrument/package.json @@ -16,8 +16,6 @@ }, "scripts": { "build": "node scripts/build.js", - "format": "oxfmt src", - "lint": "tsc && oxlint --fix src", "test": "vitest" }, "dependencies": { diff --git a/packages/serve-instrument/scripts/build.js b/packages/serve-instrument/scripts/build.js index b6b346482..aab9a63b0 100644 --- a/packages/serve-instrument/scripts/build.js +++ b/packages/serve-instrument/scripts/build.js @@ -1,6 +1,6 @@ -import * as fs from 'fs'; -import * as path from 'path'; -import * as url from 'url'; +import * as fs from 'node:fs'; +import * as path from 'node:path'; +import * as url from 'node:url'; import tailwind from '@tailwindcss/postcss'; import * as esbuild from 'esbuild'; diff --git a/packages/subject-utils/package.json b/packages/subject-utils/package.json index b88829e22..d2940ee6b 100644 --- a/packages/subject-utils/package.json +++ b/packages/subject-utils/package.json @@ -8,8 +8,6 @@ ".": "./src/index.ts" }, "scripts": { - "format": "oxfmt src", - "lint": "tsc && oxlint --fix src", "test": "vitest" }, "dependencies": { diff --git a/packages/vite-plugin-runtime/package.json b/packages/vite-plugin-runtime/package.json index f0618b85c..cc7b86d58 100644 --- a/packages/vite-plugin-runtime/package.json +++ b/packages/vite-plugin-runtime/package.json @@ -8,8 +8,6 @@ ".": "./src/index.js" }, "scripts": { - "format": "oxfmt src", - "lint": "tsc && oxlint --fix src", "test": "vitest" }, "dependencies": { diff --git a/runtime/v1/global.d.ts b/runtime/v1/global.d.ts index 06fafcd6e..0090ee8ef 100644 --- a/runtime/v1/global.d.ts +++ b/runtime/v1/global.d.ts @@ -1,4 +1,4 @@ -// eslint-disable-next-line @typescript-eslint/consistent-type-definitions +// eslint-disable-next-line @typescript-eslint/consistent-type-definitions -- a consuming repo extends this global by declaration merging, which needs an interface declare interface OpenDataCaptureContext { isRepo: typeof import('../../package.json') extends { __isODCRepo: NonNullable } ? true : false; } diff --git a/runtime/v1/test/vendor-pairing.test.ts b/runtime/v1/test/vendor-pairing.test.ts index 6202fa27d..18ba8a76c 100644 --- a/runtime/v1/test/vendor-pairing.test.ts +++ b/runtime/v1/test/vendor-pairing.test.ts @@ -1,6 +1,6 @@ -import * as fs from 'fs'; -import * as module from 'module'; -import * as path from 'path'; +import * as fs from 'node:fs'; +import * as module from 'node:module'; +import * as path from 'node:path'; import { describe, expect, it } from 'vitest'; diff --git a/runtime/v1/tsconfig.json b/runtime/v1/tsconfig.json index e7a75d9e3..6e6882f12 100644 --- a/runtime/v1/tsconfig.json +++ b/runtime/v1/tsconfig.json @@ -5,5 +5,5 @@ "lib": ["DOM", "DOM.Iterable", "ESNext"], "rootDir": "../.." }, - "include": ["*.js", "env.d.ts", "global.d.ts"] + "include": ["*.js", "env.d.ts", "global.d.ts", "test/**/*", "vitest.config.ts"] } diff --git a/storybook/package.json b/storybook/package.json index 513479b1d..65f8ac6a1 100644 --- a/storybook/package.json +++ b/storybook/package.json @@ -5,8 +5,6 @@ "license": "Apache-2.0", "type": "module", "scripts": { - "format": "oxfmt config package.json tsconfig.json vite.config.js", - "lint": "tsc && oxlint --fix config vite.config.js", "storybook": "NODE_OPTIONS='--import=tsx' env-cmd -f ../.env storybook dev -c config --no-open -p 6006" }, "dependencies": { diff --git a/testing/package.json b/testing/package.json index 7576daafe..30b0eb318 100644 --- a/testing/package.json +++ b/testing/package.json @@ -5,7 +5,6 @@ "type": "module", "scripts": { "gen:routes": "tsx scripts/gen-routes.ts", - "lint": "pnpm gen:routes && tsc && oxlint --fix .", "postinstall": "pnpm gen:routes", "test:dev": "pnpm gen:routes && env-cmd -f ../.env playwright test --ui", "test:e2e": "pnpm gen:routes && env-cmd -f ../.env playwright test" diff --git a/testing/turbo.json b/testing/turbo.json new file mode 100644 index 000000000..8b93ad7ad --- /dev/null +++ b/testing/turbo.json @@ -0,0 +1,10 @@ +{ + "$schema": "https://turbo.build/schema.json", + "extends": ["//"], + "tasks": { + "gen:routes": { + "inputs": ["scripts/gen-routes.ts", "$TURBO_ROOT$/apps/web/src/route-tree.ts"], + "outputs": ["src/generated/route.d.ts"] + } + } +} diff --git a/turbo.json b/turbo.json index cfa9c4fda..e6dabf7cf 100644 --- a/turbo.json +++ b/turbo.json @@ -1,56 +1,50 @@ { "$schema": "https://turbo.build/schema.json", "agentGuidance": false, - "globalDependencies": [ - ".env", - "oxfmt.config.ts", - "oxlint.config.ts", - "packages/oxlint-config/src/**", - "tsconfig.json" - ], - "globalEnv": ["NODE_ENV", "NODE_OPTIONS", "RELEASE_VERSION"], + "globalDependencies": ["tsconfig.json"], + "globalEnv": ["RELEASE_VERSION"], + "globalPassThroughEnv": ["NODE_OPTIONS"], "tasks": { - // A package-scoped task replaces the generic one rather than merging with it, - // so anything the generic build declares must be repeated here. - "@opendatacapture/gateway#build": { - "dependsOn": ["^build", "db:push"], - "outputs": ["dist/**"] - }, "build": { "dependsOn": ["^build", "db:generate"], - "env": ["API_BASE_URL", "CONTACT_EMAIL", "DOCS_URL", "GITHUB_REPO_URL", "LICENSE_URL", "GATEWAY_ENABLED"], + "inputs": ["$TURBO_DEFAULT$", "!**/*.md", "!**/__tests__/**"], "outputs": ["dist/**"] }, "db:generate": { + "inputs": ["prisma/schema.prisma"], "outputs": ["node_modules/@prisma/generated-client/**"] }, - "@opendatacapture/api#db:generate": { - "cache": false - }, - "db:push": { - "cache": false, - "env": ["GATEWAY_DATABASE_URL"], - "dependsOn": ["db:generate"] - }, "dev": { - "dependsOn": ["^build", "^db:generate", "db:push"], + "cache": false, + "dependsOn": ["^build", "db:generate"], "persistent": true }, "dev:test": { - "dependsOn": ["^build", "^db:generate", "db:push"], + "cache": false, + "dependsOn": ["^build", "db:generate"], "persistent": true }, - "format": {}, - "lint": { - "dependsOn": ["^build", "^db:generate", "db:push"] + // What a tool run over the whole repo reads that source control does not hold. The library builds + // reach runtime-core and runtime-v1 through ^build. + "//#generated": { + "dependsOn": [ + "@opendatacapture/api#db:generate", + "@opendatacapture/gateway#db:generate", + "@opendatacapture/instrument-library#build", + "@opendatacapture/testing#gen:routes" + ] }, - "//#lint:root": {}, - "test:e2e": { - "cache": false, - "dependsOn": ["^build", "^db:generate", "db:push"] + "//#lint:root": { + "dependsOn": ["//#generated"], + "inputs": ["$TURBO_DEFAULT$", "!**/*.md", "!**/*.mdx"] }, "start": { - "dependsOn": ["^build"] + "cache": false, + "dependsOn": ["build"] + }, + "@opendatacapture/testing#test:e2e": { + "cache": false, + "dependsOn": ["//#generated", "@opendatacapture/gateway#db:push"] } } } From e9e386e4c483b38fcc93d1d3ceba6592119e0efb Mon Sep 17 00:00:00 2001 From: joshunrau Date: Wed, 18 Nov 2026 20:26:50 -0500 Subject: [PATCH 3/8] ci: keep turbo's cache between the runs of a pull request Every CI run started from an empty cache, and until .env left turbo's global hash a saved one could not have matched anyway. A follow-up push now reruns only the tasks whose inputs it changed. The release workflow's lint no longer invents a GATEWAY_DATABASE_URL: lint stopped running the gateway's `db:push`. Co-Authored-By: Claude Fable 5.2 --- .github/workflows/ci.yaml | 9 +++++++++ .github/workflows/release.yaml | 2 +- 2 files changed, 10 insertions(+), 1 deletion(-) diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml index 22752ca1c..1cfe859b7 100644 --- a/.github/workflows/ci.yaml +++ b/.github/workflows/ci.yaml @@ -26,6 +26,15 @@ jobs: git config --global --add safe.directory /__w/OpenDataCapture/OpenDataCapture - name: Install Dependencies run: pnpm install --frozen-lockfile + # A pull request reads the caches of its own earlier runs, so a follow-up push reruns only the + # turbo tasks whose inputs it changed. + - name: Restore Turbo Cache + uses: actions/cache@v6 + with: + path: .turbo/cache + key: turbo-${{ runner.os }}-${{ github.sha }} + restore-keys: | + turbo-${{ runner.os }}- # Run lint and unit tests before the (occasionally flaky) Playwright install so those results # aren't blocked by a hung browser download. - name: Lint diff --git a/.github/workflows/release.yaml b/.github/workflows/release.yaml index da185469e..979bb6e33 100644 --- a/.github/workflows/release.yaml +++ b/.github/workflows/release.yaml @@ -58,7 +58,7 @@ jobs: - name: Install Dependencies run: pnpm install --frozen-lockfile - name: Validate - run: GATEWAY_DATABASE_URL=file:${TMPDIR}tmp.db pnpm lint + run: pnpm lint build: runs-on: ubuntu-latest needs: [configure, validate] From ac55d34499623b6a4f55fdf2cecc224a04598d2b Mon Sep 17 00:00:00 2001 From: joshunrau Date: Wed, 18 Nov 2026 20:42:34 -0500 Subject: [PATCH 4/8] fix(release-info): build for production without RELEASE_VERSION A production build read its version from RELEASE_VERSION alone, which only the Dockerfiles set, so root `pnpm build` failed at the api build on every development machine. It now takes the root package.json version when the variable is unset, which is the value the release workflow passes anyway. A malformed value still fails the build. Co-Authored-By: Claude Fable 5.2 --- packages/release-info/src/__tests__/index.test.ts | 11 ++++++++--- packages/release-info/src/index.ts | 13 ++++++++----- 2 files changed, 16 insertions(+), 8 deletions(-) diff --git a/packages/release-info/src/__tests__/index.test.ts b/packages/release-info/src/__tests__/index.test.ts index c04a5f54e..fef72f197 100644 --- a/packages/release-info/src/__tests__/index.test.ts +++ b/packages/release-info/src/__tests__/index.test.ts @@ -16,6 +16,7 @@ const { execMock, gitResult } = vi.hoisted(() => { vi.mock('child_process', () => ({ default: { exec: execMock } })); +import rootPackage from '../../../../package.json' with { type: 'json' }; import { getReleaseInfo } from '../index'; function mockGit(branch: { stderr: string; stdout: string }, commit: { stderr: string; stdout: string }) { @@ -54,12 +55,16 @@ describe('getReleaseInfo', () => { vi.stubEnv('NODE_ENV', 'production'); vi.spyOn(console, 'error').mockImplementation(() => undefined); }); + it("should take the root package.json version if 'RELEASE_VERSION' is unset, so a production build works outside the release pipeline", async () => { + vi.stubEnv('RELEASE_VERSION', undefined); + await expect(getReleaseInfo()).resolves.toMatchObject({ + type: 'production', + version: rootPackage.version + }); + }); // A schema failure must surface as the caller-facing "Failed to parse release info" error, not // as a raw ZodError: `getReleaseInfo` only converts it if the rejection is awaited inside its // own try block, so asserting on the message is what pins the conversion in place. - it("should throw a parse error naming the environment if 'RELEASE_VERSION' is undefined", async () => { - await expect(getReleaseInfo()).rejects.toThrow("Failed to parse release info for environment 'production'"); - }); it("should throw a parse error naming the environment if 'RELEASE_VERSION' is invalid", async () => { vi.stubEnv('RELEASE_VERSION', 'foo'); await expect(getReleaseInfo()).rejects.toThrow("Failed to parse release info for environment 'production'"); diff --git a/packages/release-info/src/index.ts b/packages/release-info/src/index.ts index 4d9d656a0..154890179 100644 --- a/packages/release-info/src/index.ts +++ b/packages/release-info/src/index.ts @@ -28,6 +28,12 @@ async function getGitCommit() { return stdout.trim(); } +async function getRootPackageVersion() { + const content = await fs.readFile(path.resolve(import.meta.dirname, '../../../package.json'), 'utf-8'); + const { version } = JSON.parse(content) as PackageJson; + return version!; +} + export async function getReleaseInfo(): Promise { try { if (process.env.NODE_ENV === 'development' || process.env.NODE_ENV === 'test') { @@ -36,16 +42,13 @@ export async function getReleaseInfo(): Promise { buildTime: Date.now(), commit: await getGitCommit(), type: process.env.NODE_ENV, - version: await fs - .readFile(path.resolve(import.meta.dirname, '../../../package.json'), 'utf-8') - .then((content) => JSON.parse(content) as PackageJson) - .then(({ version }) => version!) + version: await getRootPackageVersion() } satisfies DevelopmentReleaseInfo); } else if (process.env.NODE_ENV === 'production') { return await $ProductionReleaseInfo.parseAsync({ buildTime: Date.now(), type: 'production', - version: process.env.RELEASE_VERSION! + version: process.env.RELEASE_VERSION ?? (await getRootPackageVersion()) } satisfies ProductionReleaseInfo); } else { throw new Error(`Unexpected value for process.env.NODE_ENV: ${process.env.NODE_ENV}`); From d07bc42d2a9014665f9034f41b218ae969288568 Mon Sep 17 00:00:00 2001 From: joshunrau Date: Wed, 18 Nov 2026 20:42:37 -0500 Subject: [PATCH 5/8] ci: give a pull request's first run the cache saved on main CI runs only on pull requests, and a pull request can read a cache saved on its base branch but not one saved by another pull request, so the first run of each started cold. The release workflow's lint job now saves turbo's cache on every push to main. Each run saves what it restored plus its own entries, so both jobs cap the age of an entry at seven days. Co-Authored-By: Claude Fable 5.2 --- .github/workflows/ci.yaml | 7 +++++-- .github/workflows/release.yaml | 12 ++++++++++++ 2 files changed, 17 insertions(+), 2 deletions(-) diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml index 1cfe859b7..e14b72520 100644 --- a/.github/workflows/ci.yaml +++ b/.github/workflows/ci.yaml @@ -8,6 +8,9 @@ permissions: jobs: lint-and-test: runs-on: ubuntu-latest + env: + # Each run saves the entries it restored plus its own, so without a limit the cache only grows. + TURBO_CACHE_MAX_AGE: 7d steps: - name: Checkout Code uses: actions/checkout@v7 @@ -26,8 +29,8 @@ jobs: git config --global --add safe.directory /__w/OpenDataCapture/OpenDataCapture - name: Install Dependencies run: pnpm install --frozen-lockfile - # A pull request reads the caches of its own earlier runs, so a follow-up push reruns only the - # turbo tasks whose inputs it changed. + # A pull request reads the caches of its own earlier runs and the one the Release workflow last + # saved on its base branch, so a run repeats only the turbo tasks whose inputs changed. - name: Restore Turbo Cache uses: actions/cache@v6 with: diff --git a/.github/workflows/release.yaml b/.github/workflows/release.yaml index 979bb6e33..535df765a 100644 --- a/.github/workflows/release.yaml +++ b/.github/workflows/release.yaml @@ -45,6 +45,9 @@ jobs: run: node scripts/plan-release.ts validate: runs-on: ubuntu-latest + env: + # Each run saves the entries it restored plus its own, so without a limit the cache only grows. + TURBO_CACHE_MAX_AGE: 7d steps: - name: Checkout Repository uses: actions/checkout@v7 @@ -57,6 +60,15 @@ jobs: node-version-file: '.nvmrc' - name: Install Dependencies run: pnpm install --frozen-lockfile + # A pull request can read a cache saved on its base branch, so this is what gives the first CI run + # of each one a warm start. + - name: Restore Turbo Cache + uses: actions/cache@v6 + with: + path: .turbo/cache + key: turbo-${{ runner.os }}-${{ github.sha }} + restore-keys: | + turbo-${{ runner.os }}- - name: Validate run: pnpm lint build: From c826f30f36feb496c2a3bdaf9e8c611bafaaba33 Mon Sep 17 00:00:00 2001 From: joshunrau Date: Wed, 18 Nov 2026 20:42:42 -0500 Subject: [PATCH 6/8] docs: describe the reworked task graph and the single lint pass The playbooks and AGENTS.md files still named per-package `lint` scripts, a `lint` that ran the gateway's `db:push`, a runtime-core `lib/` that turbo did not restore, and `.env` as a global dependency. Co-Authored-By: Claude Fable 5.2 --- .agents/docs/architecture/testing-strategy.md | 51 ++++++++++++------- .agents/docs/playbooks/add-e2e-test.md | 2 +- .agents/docs/playbooks/add-env-var.md | 5 +- .agents/docs/playbooks/add-instrument.md | 3 +- .agents/docs/playbooks/add-vitest-project.md | 5 +- .agents/docs/playbooks/add-web-route.md | 4 +- .agents/docs/playbooks/cut-a-release.md | 3 +- .../docs/playbooks/promote-to-react-core.md | 5 +- .agents/docs/playbooks/run-locally.md | 12 ++--- .agents/docs/workspace-map.md | 6 +-- .agents/skills/finishing-changes/SKILL.md | 12 ++--- .agents/skills/review-pr/REVIEW.md | 2 +- AGENTS.md | 4 +- apps/api/AGENTS.md | 3 +- apps/gateway/AGENTS.md | 4 +- apps/outreach/AGENTS.md | 4 +- apps/playground/AGENTS.md | 2 +- packages/instrument-library/AGENTS.md | 4 +- packages/instrument-stubs/AGENTS.md | 4 +- packages/react-core/AGENTS.md | 2 +- packages/release-info/AGENTS.md | 8 +-- packages/runtime-core/AGENTS.md | 9 ++-- runtime/v1/AGENTS.md | 6 +-- storybook/AGENTS.md | 2 +- testing/AGENTS.md | 8 +-- 25 files changed, 88 insertions(+), 82 deletions(-) diff --git a/.agents/docs/architecture/testing-strategy.md b/.agents/docs/architecture/testing-strategy.md index 0a0552a0d..7780c08e3 100644 --- a/.agents/docs/architecture/testing-strategy.md +++ b/.agents/docs/architecture/testing-strategy.md @@ -10,7 +10,7 @@ What is tested where, and what CI blocks a merge on. Writing an e2e test is | ---------- | ---------- | --------------------------------------------------------------------- | -------------------- | | Unit | vitest | `__tests__/.test.ts` beside `.ts`, or a package's `test/` | `pnpm test:coverage` | | End-to-end | Playwright | `testing/src/specs/` | `pnpm test:e2e` | -| Type-check | `tsc` | code that fails to compile if the type breaks, e.g. `*.test-d.ts` | `pnpm lint` | +| Type-check | oxlint | code that fails to compile if the type breaks, e.g. `*.test-d.ts` | `pnpm lint` | **There is no integration tier.** `apps/api` unit tests mock the Prisma layer entirely, so Playwright is the only code path that touches a real database: a permissions or row-scoping change is untested @@ -92,24 +92,37 @@ outside the project globs by design. ## `pnpm lint` is the type-check, and it edits files -Per-package `lint` is `tsc && oxlint --fix src`; there is no separate `typecheck` script, so a type -error surfaces as a lint failure and every run may rewrite the working tree. Exceptions: +Root `lint:root` is `oxlint --type-check --fix`: one process lints every file in the repo and reports +TypeScript's diagnostics for it, each file under its nearest `tsconfig.json`. No workspace has a `lint` +script except `apps/outreach`, and there is no separate `typecheck` script, so a type error surfaces as +a lint failure and every run may rewrite the working tree. To check part of the repo, pass a path: +`pnpm exec oxlint --type-check apps/web`. What that pass does not cover: -| Package | `lint` | -| ------------------------------------------------------------- | ------------------------------------------ | -| `apps/outreach` | `astro check && oxlint --fix src` | -| `packages/runtime-core` | `tsc --noEmit && oxlint --fix src` | -| `packages/instrument-stubs`, `packages/instrument-guidelines` | oxlint only — **no `tsc`** | -| `testing` | `pnpm gen:routes && tsc && oxlint --fix .` | -| `runtime/v1` | **none**, so never type-checked | +| Files | Checked by | +| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------ | +| `.astro` templates | `apps/outreach`'s `lint`, which is `astro check` | +| `vendor/**`, `packages/runtime-bundler/test/fixtures/**` | nothing: `ignorePatterns` in `oxlint.config.ts` | +| `packages/instrument-stubs`, `packages/instrument-guidelines/bin` | linted, but neither has a `tsconfig.json`, so the repo's strict options do not apply | ## Turbo task graph -`lint`, `dev`, `dev:test` and `test:e2e` depend on `["^build", "^db:generate", "db:push"]`; `build` -on `["^build", "db:generate"]`. `test:e2e` is `cache: false`. **`test` is not a turbo task**: root -`pnpm test` is `env-cmd vitest`, with no build and no database. `globalDependencies` (`.env`, -`oxfmt.config.ts`, `oxlint.config.ts`, `packages/oxlint-config/src/**`, `tsconfig.json`) invalidate -every cached task when touched. +`pnpm lint` is `turbo run lint lint:root`. `//#lint:root` depends on `//#generated`, a task with no +script that names what a tool run over the whole repo reads and source control does not hold: both +Prisma clients, `testing`'s route types, and `instrument-library`'s build, which reaches `runtime-v1` +and `runtime-core` through `^build`. `test:e2e` depends on the same task plus the gateway's `db:push`. +`dev` and `dev:test` depend on `["^build", "db:generate"]`, to which `apps/gateway/turbo.json` adds +`db:push`; `build` depends on `["^build", "db:generate"]` and `start` on `build`. `dev`, `dev:test`, +`start`, `test:e2e` and `db:push` are `cache: false`. A workspace whose task differs from the root +definition says so in its own `turbo.json` (`git ls-files '*turbo.json'` lists them). + +**`test` is not a turbo task**: root `pnpm test` runs `pnpm build:exports`, which builds the packages +that export only build output, and then `env-cmd vitest`, with no database. + +**A task sees a variable only through `env`.** `.env` is not a `globalDependency`, so editing it +invalidates nothing; `pnpm build` loads it with `env-cmd` and turbo passes on the keys a task declares. +Root `tsconfig.json` is the one `globalDependency`, and turbo adds `packages/oxlint-config` to every +task's hash because the root `package.json` depends on it. `build` hashes neither `*.md` nor +`__tests__/`, so editing an `AGENTS.md` or a unit test rebuilds nothing downstream. ## Coverage scope @@ -124,7 +137,9 @@ counts their functions twice in the merged report. `.github/workflows/ci.yaml`, one job, on `pull_request` to `main` or a `release/**` branch and `workflow_dispatch` only — a push alone runs nothing. In order: `./scripts/generate-env.sh`, `pnpm install --frozen-lockfile`, `pnpm lint`, `pnpm test:coverage`, Playwright install (chromium + firefox, capped at 10 minutes, after -lint and unit tests so a hung download cannot hide them), `pnpm test:e2e`. +lint and unit tests so a hung download cannot hide them), `pnpm test:e2e`. `actions/cache` restores +`.turbo/cache` before the first of them: a pull request reads the caches its own earlier runs saved +and the one the Release workflow's `validate` job last saved on its base branch. Not gated: knip (`pnpm knip` exists), and formatting — oxfmt runs only in the `.husky/pre-commit` hook, which formats rather than verifies. @@ -147,5 +162,5 @@ Flag these rather than fixing them in passing; each is load-bearing somewhere. - `turbo.json` declares `db:generate` `outputs: ["node_modules/@prisma/generated-client/**"]`, which matches only `apps/gateway`'s schema; `apps/api/prisma/schema.prisma` has its `output` commented - out, so `@opendatacapture/api#db:generate` is `cache: false` to stop a cache hit restoring nothing. - Changing either half changes what `db:generate` produces. + out, so `apps/api/turbo.json` sets its `db:generate` to `cache: false` to stop a cache hit restoring + nothing. Changing either half changes what `db:generate` produces. diff --git a/.agents/docs/playbooks/add-e2e-test.md b/.agents/docs/playbooks/add-e2e-test.md index 0bbf1b561..19849eaea 100644 --- a/.agents/docs/playbooks/add-e2e-test.md +++ b/.agents/docs/playbooks/add-e2e-test.md @@ -44,7 +44,7 @@ starting — `playwright.config.ts` boots api, gateway, web and playground itsel ## Verify ```sh -pnpm --filter @opendatacapture/testing lint # gen:routes, tsc, oxlint . +pnpm lint # gen:routes, then the whole-repo type-check and lint pnpm --filter @opendatacapture/testing test:e2e --list src/specs/.spec.ts # your titles, under [chromium] pnpm --filter @opendatacapture/testing test:e2e src/specs/.spec.ts # one spec; setup still runs pnpm test:e2e # whole suite, from repo root diff --git a/.agents/docs/playbooks/add-env-var.md b/.agents/docs/playbooks/add-env-var.md index 84ebb9503..f098e377a 100644 --- a/.agents/docs/playbooks/add-env-var.md +++ b/.agents/docs/playbooks/add-env-var.md @@ -40,7 +40,8 @@ 6. **If the gateway reads it, add it to `apps/gateway/src/config.ts`.** That is a separate Zod schema parsing `process.env` at import time; `$Env` never reaches the gateway. -7. **If a build reads it, add it to that task's `env` array in `turbo.json`.** Turbo runs in strict +7. **If a build reads it, add it to the `env` array of that workspace's `build` task, in its own + `turbo.json`** (`apps/web/turbo.json` is the shape). Turbo runs in strict env mode: a task sees only `globalEnv` plus its own `env`, so the variable is `undefined` during `pnpm build` even though `env-cmd` loaded `.env` before turbo started. `dev`/`start`/`test` scripts load `.env` themselves (`env-cmd -f ../../.env`), so only build-time reads need this. @@ -63,7 +64,7 @@ ```sh grep -n YOUR_KEY .env # present pnpm dev # $Env is validated at boot; an invalid value crashes here. Ctrl-C once up -pnpm lint # tsc + the no-process.env rule +pnpm lint # the type-check + the no-process.env rule pnpm test:coverage pnpm build # only this catches a missing turbo.json `env` entry ``` diff --git a/.agents/docs/playbooks/add-instrument.md b/.agents/docs/playbooks/add-instrument.md index a0d1fe7d2..92d72ab7e 100644 --- a/.agents/docs/playbooks/add-instrument.md +++ b/.agents/docs/playbooks/add-instrument.md @@ -65,5 +65,4 @@ pnpm test:e2e ``` `available` listing your title under the right kind proves only that it built; it reaches a demo -instance only through step 4. `pnpm lint` (`tsc`) needs `runtime/v1/dist`, which is why the build -comes first. +instance only through step 4. diff --git a/.agents/docs/playbooks/add-vitest-project.md b/.agents/docs/playbooks/add-vitest-project.md index a5b6e5010..e3615ef34 100644 --- a/.agents/docs/playbooks/add-vitest-project.md +++ b/.agents/docs/playbooks/add-vitest-project.md @@ -75,9 +75,6 @@ project, so its test files are collected by nothing and CI stays green. The loud ```sh pnpm exec vitest list --filesOnly --project # your file, prefixed [], nothing from outside pnpm exec vitest --project -pnpm lint # from the root; tsc now checks vitest.config.ts +pnpm lint # now type-checks vitest.config.ts pnpm test # the repo-wide file count rises by yours ``` - -Run `pnpm lint` from the root: a package-scoped `lint` skips turbo's `^build` ordering and fails on -unbuilt dependencies rather than on your config. diff --git a/.agents/docs/playbooks/add-web-route.md b/.agents/docs/playbooks/add-web-route.md index 55c4132f6..4835fad60 100644 --- a/.agents/docs/playbooks/add-web-route.md +++ b/.agents/docs/playbooks/add-web-route.md @@ -56,7 +56,7 @@ run the generator. Until then `pnpm lint` fails in two workspaces: TS2345 in `apps/web`, and in `testing`, whose `gen:routes` derives the `RouteTo` union from that tree, so your literal is not yet a valid `pageModels` key. `gen:routes` reads `route-tree.ts` and never writes it, so it is yours to run - (`pnpm --filter @opendatacapture/testing gen:routes`); `testing`'s `lint` and `test:e2e` also run + (`pnpm --filter @opendatacapture/testing gen:routes`); `pnpm lint` and `testing`'s `test:e2e` also run it first. 10. **Add the tests.** A unit test named after the route file, in a `__tests__/` folder beside it @@ -66,7 +66,7 @@ run the generator. ## Verify ```sh -pnpm --filter @opendatacapture/web lint # TS2345 on your literal alone means the tree is not regenerated yet +pnpm lint # TS2345 on your literal alone means the tree is not regenerated yet pnpm exec vitest --project web pnpm test:e2e ``` diff --git a/.agents/docs/playbooks/cut-a-release.md b/.agents/docs/playbooks/cut-a-release.md index d36949655..ca0dc42cd 100644 --- a/.agents/docs/playbooks/cut-a-release.md +++ b/.agents/docs/playbooks/cut-a-release.md @@ -19,8 +19,7 @@ them. Never hand-edit a version field. 1. **Get the branch green before you bump.** Nothing after the PR runs a test against this code: the release's `validate` job runs `pnpm lint` only. Run `pnpm check` - (`.agents/skills/finishing-changes/SKILL.md`); root `pnpm test` has no turbo `^build` behind it, so - run `pnpm build` once first. `pnpm lint` rewrites files, so commit any churn on its own before the + (`.agents/skills/finishing-changes/SKILL.md`). `pnpm lint` rewrites files, so commit any churn on its own before the bump. Also confirm `gh run list --workflow=Release --limit 1` is green on `main`: nothing local builds the Docker images, and `build` gates both publishes. diff --git a/.agents/docs/playbooks/promote-to-react-core.md b/.agents/docs/playbooks/promote-to-react-core.md index 6cffd9cd5..ccb1ba71c 100644 --- a/.agents/docs/playbooks/promote-to-react-core.md +++ b/.agents/docs/playbooks/promote-to-react-core.md @@ -64,10 +64,7 @@ done; `apps/web`'s until step 9. ## Verify ```sh -pnpm --filter @opendatacapture/react-core lint # an unresolved `@/…` here means step 6 is unfinished -pnpm --filter @opendatacapture/web lint -pnpm --filter @opendatacapture/gateway lint # meaningful only once step 9 wired the consumer -pnpm lint && pnpm test:coverage +pnpm lint && pnpm test:coverage # an unresolved `@/…` in packages/react-core means step 6 is unfinished pnpm test:e2e pnpm --filter @opendatacapture/storybook storybook # listed under React Core; prerequisites in storybook/AGENTS.md ``` diff --git a/.agents/docs/playbooks/run-locally.md b/.agents/docs/playbooks/run-locally.md index 50a9a2891..16e032502 100644 --- a/.agents/docs/playbooks/run-locally.md +++ b/.agents/docs/playbooks/run-locally.md @@ -53,18 +53,18 @@ one. 6. **`pnpm install`.** It also installs the husky pre-commit hook, which formats staged files with oxfmt and runs neither lint nor tests. -7. **Run `pnpm build` once.** `runtime/v1/dist` is gitignored and read while Vite configs load, so a +7. **Run `pnpm build:exports` once.** It builds the packages that export only build output. `runtime/v1/dist` is gitignored and read while Vite configs load, so a dev server started without it dies with `ENOENT: no such file or directory, scandir '/runtime/v1/dist'` from `generateManifest` (`packages/runtime-meta`), raised inside a plugin factory so it looks like a Vite configuration - error. Turbo's `dev`, `dev:test`, `lint` and `test:e2e` depend on `^build` and repair it; storybook, - outreach, root `pnpm test` and any bare `tsc` or `vitest` do not. + error. Root `pnpm dev`, `pnpm lint`, `pnpm test` and `pnpm test:e2e` build it first and so repair it; + storybook, outreach and any bare `tsc`, `oxlint` or `vitest` do not. Done when `runtime/v1/dist` exists. 8. **`pnpm dev`** starts api, gateway and web only (`dev:core`); the gateway's sqlite `db:push` runs as - a dependency. The first run, and the first after any `.env` edit (`.env` is a turbo - `globalDependency`), spends minutes building before anything listens. + a dependency. A first run that skipped step 7 builds before anything listens; an `.env` edit rebuilds + nothing. | App | Variable | Default | | ------- | ------------------------- | ------- | @@ -90,7 +90,7 @@ one. ## The apps `pnpm dev` does not start -Turbo hashes `.env` but never loads it, and `astro dev` does not read it either, hence the `env-cmd` +Turbo never loads `.env`, and `astro dev` does not read it either, hence the `env-cmd` prefix. | App | Command | Port | diff --git a/.agents/docs/workspace-map.md b/.agents/docs/workspace-map.md index efa0a47bc..02fc697f9 100644 --- a/.agents/docs/workspace-map.md +++ b/.agents/docs/workspace-map.md @@ -52,9 +52,9 @@ and a change is visible immediately. The exceptions: - **`playground-url` and `serve-instrument`** build only their `bin`. `playground-url`'s library export is still source. `serve-instrument` has no `exports` at all. -Turbo's `build`, `lint`, `dev` and `test:e2e` tasks depend on `^build`, so `pnpm build` and -`pnpm lint` from the root are always correct. Running `tsc` inside one package after a clean -checkout is not, and `pnpm test` builds nothing. +Root `pnpm build`, `pnpm lint`, `pnpm dev`, `pnpm test` and `pnpm test:e2e` build these first +(`.agents/docs/architecture/testing-strategy.md` §Turbo task graph), so they are always correct. A +bare `tsc`, `oxlint --type-check` or `vitest` after a clean checkout is not. ## Published to npm diff --git a/.agents/skills/finishing-changes/SKILL.md b/.agents/skills/finishing-changes/SKILL.md index bc87b00c7..a5d986c26 100644 --- a/.agents/skills/finishing-changes/SKILL.md +++ b/.agents/skills/finishing-changes/SKILL.md @@ -11,12 +11,12 @@ with `.agents/skills/opening-issues/SKILL.md` and name the issue in your reply. **A diff confined to these rows runs the row's checks in place of step 1**, then continues from step 7 (step 3 for unit tests). A diff spanning rows runs each row's checks; any other file means the full list. -| Files | Checks | -| ------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | -| `AGENTS.md`, `.agents/`, `.claude/`, `.vscode/`, `.editorconfig`, READMEs | None: nothing reads them | -| `.github/workflows/` | None locally: the pull request's CI run is the check | -| `/docs`, `/blog`, `apps/outreach` | `pnpm --filter @opendatacapture/outreach lint`, then `build`; no e2e reaches it | -| Unit tests (`__tests__/`, a package's `test/`) | `pnpm lint` and `pnpm test:coverage`; the apps never load them | +| Files | Checks | +| ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | +| `AGENTS.md`, `.agents/`, `.claude/`, `.vscode/`, `.editorconfig`, READMEs | None: nothing reads them | +| `.github/workflows/` | None locally: the pull request's CI run is the check | +| `/docs`, `/blog`, `apps/outreach` | `pnpm lint`, then `pnpm --filter @opendatacapture/outreach build`; no e2e reaches it | +| Unit tests (`__tests__/`, a package's `test/`) | `pnpm lint` and `pnpm test:coverage`; the apps never load them | 1. **Run `pnpm check` from the repo root** and fix every failure, a coverage shortfall included. It runs `pnpm lint`, `pnpm test:coverage` and `pnpm test:e2e` in sequence, so a lint failure hides the rest until it diff --git a/.agents/skills/review-pr/REVIEW.md b/.agents/skills/review-pr/REVIEW.md index e29980d7f..f36f016aa 100644 --- a/.agents/skills/review-pr/REVIEW.md +++ b/.agents/skills/review-pr/REVIEW.md @@ -13,7 +13,7 @@ pnpm generate:env TURBO_CONCURRENCY=2 pnpm lint ``` -Review the merge result. PR refs exist only on the upstream repository, not on a fork, hence the URL rather than a remote name. If `refs/pull//merge` is missing, use `refs/pull//head` and say so in the evidence. Run `generate:env` inside the worktree and never copy the repo's `.env`, so `db:push` cannot touch the user's dev database. Keep `TURBO_CONCURRENCY=2`: three reviews share the user's machine. +Review the merge result. PR refs exist only on the upstream repository, not on a fork, hence the URL rather than a remote name. If `refs/pull//merge` is missing, use `refs/pull//head` and say so in the evidence. Run `generate:env` inside the worktree and never copy the repo's `.env`, so the `db:push` that turbo's `dev`, `dev:test` and `test:e2e` run cannot touch the user's dev database. Keep `TURBO_CONCURRENCY=2`: three reviews share the user's machine. - `install` or `generate:env` fails → return BLOCKED (machine) and write nothing. - `lint` fails → return BLOCKED (PR) with the errors, and write a reply body to the scratchpad asking the author to update their branch against `main`, ending with `Reviewed at commit .` diff --git a/AGENTS.md b/AGENTS.md index f3c36e8c4..e3dbf7312 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -18,8 +18,8 @@ pnpm install # install deps pnpm generate:env # create .env from .env.template — required before anything else runs pnpm dev # run core apps (api, gateway, web) via turbo pnpm build # turbo build (all packages/apps) -pnpm lint # turbo lint — `tsc && oxlint --fix src` per package, plus lint:root for root-level scripts and configs -pnpm format # turbo format (oxfmt per package) +pnpm lint # turbo lint — one `oxlint --type-check --fix` over the whole repo (lint:root), plus `astro check` in apps/outreach +pnpm format # oxfmt over the whole repo pnpm test # vitest across the workspace pnpm test:coverage # vitest with coverage — fails below 100%, the gate CI runs pnpm test:e2e # playwright, in testing/ diff --git a/apps/api/AGENTS.md b/apps/api/AGENTS.md index 1609cd81e..50586c597 100644 --- a/apps/api/AGENTS.md +++ b/apps/api/AGENTS.md @@ -184,8 +184,7 @@ or `ValidObjectIdPipe` explicitly — see `src/audit/audit.controller.ts` and Provider is **MongoDB, so there are no migrations**. Nothing is checked in after a schema change beyond `schema.prisma` itself, and **nothing in this app runs `prisma db push`**. This workspace -defines no `db:push` script, so the `db:push` that `dev`, `dev:test`, `lint` and `test:e2e` depend on -resolves to nothing here; the only workspace that owns one is `apps/gateway`, whose datasource is +defines no `db:push` script; the only workspace that owns one is `apps/gateway`, whose datasource is SQLite. The Dockerfile only builds. **Indexes are created at startup instead**, by `ensureDatabaseIndexes` in `src/core/prisma.ts`, diff --git a/apps/gateway/AGENTS.md b/apps/gateway/AGENTS.md index 14a99da26..9e1200cf9 100644 --- a/apps/gateway/AGENTS.md +++ b/apps/gateway/AGENTS.md @@ -79,8 +79,8 @@ Neither is a record of something that happened here — one is a short-lived gat state `apps/api` owns — so persisting either would only add a second copy that can disagree. `GATEWAY_DATABASE_URL` is an absolute `file:` URL written by `pnpm generate:env`. Turbo runs -`db:push` before `dev`, `lint`, `test:e2e` and — via the `@opendatacapture/gateway#build` key in -`turbo.json` — before `build`, so a gateway build needs `GATEWAY_DATABASE_URL` set. +`db:push` before `dev`, `dev:test` and `test:e2e` (`apps/gateway/turbo.json`). `build` and `pnpm lint` +need only the generated client, so neither reads `GATEWAY_DATABASE_URL`. **A deployed gateway applies this schema on every start.** `scripts/run.sh` runs `prisma db push` before the server, with a Prisma CLI the `Dockerfile` installs at the version the lockfile resolved. diff --git a/apps/outreach/AGENTS.md b/apps/outreach/AGENTS.md index a32ceb12b..d0b5e1cf3 100644 --- a/apps/outreach/AGENTS.md +++ b/apps/outreach/AGENTS.md @@ -110,8 +110,8 @@ Every component is `.astro`; there are no React islands and no client framework configured. Do not introduce one without asking. There is **no `vitest.config.ts` and no test suite in this package** — `pnpm test` does not cover it. -`pnpm --filter @opendatacapture/outreach lint` runs `astro check && oxlint --fix src`, and `astro check` -is the only thing type-checking `.astro` files, so run it after any change here. +`pnpm --filter @opendatacapture/outreach lint` runs `astro check`, the only thing type-checking `.astro` +files, so run it after any change here. Root `pnpm lint` runs it too, beside the repo-wide oxlint pass. `astro check` and typedoc run on this package's own `typescript` 6.0.x devDependency: neither supports TypeScript 7, which every other workspace uses. diff --git a/apps/playground/AGENTS.md b/apps/playground/AGENTS.md index b0a06e79e..2e6a4fd15 100644 --- a/apps/playground/AGENTS.md +++ b/apps/playground/AGENTS.md @@ -178,7 +178,7 @@ The editor/preview split in `src/components/MainContent/MainContent.tsx` gives e `__APP_VERSION__` and `__GITHUB_REPO_URL__` are the build-time defines, declared in `src/vite-env.d.ts` and supplied in `vite.config.ts`; `GITHUB_REPO_URL` must be listed under the -`build` task's `env` in `turbo.json` or turbo's strict env mode hides it from the build. Anything +`build` task's `env` in `apps/playground/turbo.json` or turbo's strict env mode hides it from the build. Anything that differs between deployments belongs in `/config.json` instead. ## Tests diff --git a/packages/instrument-library/AGENTS.md b/packages/instrument-library/AGENTS.md index 645009d61..19f652cae 100644 --- a/packages/instrument-library/AGENTS.md +++ b/packages/instrument-library/AGENTS.md @@ -55,8 +55,8 @@ artifact** written for users outside this repo, so its instruction to put files - **Relative imports need their file extension** (`./styles.css`, `./Component.tsx`); esbuild will not resolve `./Component`. `allowImportingTsExtensions` is on for this reason. - Runtime imports use the absolute `/runtime/v1/...` specifier, resolved by the `paths` mapping in - `tsconfig.json` to `runtime/v1/dist/*`. **`runtime/v1` must be built or `pnpm lint` (`tsc`) fails** - — turbo handles this via `^build`. Background: `.agents/docs/architecture/runtime-and-vendor.md`. + `tsconfig.json` to `runtime/v1/dist/*`. **`runtime/v1` must be built or the type-check fails** + — root `pnpm lint` builds it first. Background: `.agents/docs/architecture/runtime-and-vendor.md`. - The directory name matches `internal.name` in every instrument. `SERIES` instruments have no `internal` field at all. - **`perfectionist/sort-objects` is off for this package**, as it is for the playground's examples diff --git a/packages/instrument-stubs/AGENTS.md b/packages/instrument-stubs/AGENTS.md index 6050cb346..e90085490 100644 --- a/packages/instrument-stubs/AGENTS.md +++ b/packages/instrument-stubs/AGENTS.md @@ -31,8 +31,8 @@ oxlint error repo-wide. ## Types -There is **no `tsconfig.json`** and `lint` is `oxlint --fix src` with no `tsc`. Shapes are asserted -with JSDoc `@type` annotations that nothing in this package checks — a wrong stub surfaces as a +There is **no `tsconfig.json`**, so root `pnpm lint` lints this package without type-checking it. +Shapes are asserted with JSDoc `@type` annotations that nothing in this package checks — a wrong stub surfaces as a failing `packages/schemas` test or a consumer's `tsc` error. ## Tests diff --git a/packages/react-core/AGENTS.md b/packages/react-core/AGENTS.md index d93b554c0..ecdb4f5be 100644 --- a/packages/react-core/AGENTS.md +++ b/packages/react-core/AGENTS.md @@ -153,4 +153,4 @@ libui's `t()` needs an initialised i18n, which no app supplies here — call `@testing-library/user-event` are **not** installed: assert with `toBeTruthy()`, interact with `fireEvent`. -`pnpm --filter @opendatacapture/react-core lint` runs `tsc` then oxlint. +Root `pnpm lint` type-checks and lints this package; it has no `lint` script of its own. diff --git a/packages/release-info/AGENTS.md b/packages/release-info/AGENTS.md index 902a8f470..ed76578e9 100644 --- a/packages/release-info/AGENTS.md +++ b/packages/release-info/AGENTS.md @@ -11,8 +11,8 @@ Read the root `AGENTS.md` first for the rules that apply everywhere. **It branches on `NODE_ENV` and hard-fails on anything else.** `development` and `test` shell out to `git rev-parse` for the branch and short commit and read `version` from the repo-root -`package.json`; `production` reads `process.env.RELEASE_VERSION` and never touches git. Any other -value throws. +`package.json`; `production` reads `process.env.RELEASE_VERSION`, falls back to that same +`package.json` version when it is unset, and never touches git. Any other value throws. **The dev/test path needs a git checkout the current user owns.** `.github/workflows/ci.yaml` runs `git config --global --add safe.directory ...` before installing, specifically for this. In a @@ -21,7 +21,7 @@ error surfaced as "Failed to get current git branch". **`RELEASE_VERSION` must match `/^[0-9]+\.[0-9]+\.[0-9]+$/`** (`$ReleaseVersion`). The api, gateway and web Dockerfiles take it as a build arg (playground's does not) and the release workflow supplies -it; a missing or `v`-prefixed value fails the build. +it; a `v`-prefixed value fails the build, and a missing one builds as the root `package.json` version. The root `package.json` is located as `../../../package.json` relative to `src/`, so this package only works from its current path inside the workspace. @@ -29,7 +29,7 @@ only works from its current path inside the workspace. **Both `parseAsync` calls must be `return await`, not `return`.** A bare `return` hands the promise back to the caller before it rejects, so the `catch` never runs and a raw `ZodError` escapes instead of the `Failed to parse release info for environment ''` message that names the misconfigured -variable. The two production tests assert on that message specifically, to keep the `await` there. +variable. The invalid-version production test asserts on that message specifically, to keep the `await` there. ## Tests diff --git a/packages/runtime-core/AGENTS.md b/packages/runtime-core/AGENTS.md index fc18ad61d..49fa6215a 100644 --- a/packages/runtime-core/AGENTS.md +++ b/packages/runtime-core/AGENTS.md @@ -27,8 +27,8 @@ testing a change anywhere else. `lib/constants.js`, not `dist/`**, and is the only way to reach `FILE_TYPES`, which `src/index.ts` does not re-export (`packages/schemas/src/instrument/instrument.file.ts` imports it), and `apps/outreach` points typedoc at `lib/index.d.ts` in `astro.config.ts`. Do not delete `lib/` -from the build, and do not assume a turbo cache hit restores it — `turbo.json` declares -`outputs: ["dist/**"]` only. +from the build, or `lib/**` from the `outputs` in `packages/runtime-core/turbo.json`, which is what +makes a turbo cache hit restore it. api-extractor reads TSDoc release tags, so a new export needs `/** @public */` (or `@internal` / `@alpha`) like its neighbours. @@ -104,6 +104,5 @@ Two tiers, run by different tools. runtime-core source needs it in its `plugins`, as `packages/instrument-library` has. - **Types: `src/__tests__/define.test-d.ts` and `src/types/__tests__/instrument.form.test-d.ts`**, written with `expectTypeOf` from `expect-type` (a root devDependency). vitest does not collect - them; the `tsc --noEmit` half of `pnpm --filter @opendatacapture/runtime-core lint` checks them, - because `tsconfig.json` includes all of `src/`. A type change that breaks an assertion is a tsc - error — add type cases here rather than a runtime test. + them; the type-check in root `pnpm lint` checks them, because `tsconfig.json` includes all of + `src/`. A type change that breaks an assertion is a type error — add type cases here rather than a runtime test. diff --git a/runtime/v1/AGENTS.md b/runtime/v1/AGENTS.md index 406f410e9..94ae709ca 100644 --- a/runtime/v1/AGENTS.md +++ b/runtime/v1/AGENTS.md @@ -20,8 +20,8 @@ not mention this directory: | `apps/api` | the `#runtime/v1/*` subpath import declared in `apps/api/package.json` resolves to nothing | | `instrument-bundler`, `instrument-library`, `playground`, `react-core`, `serve-instrument`, `gateway`, `web` | their tsconfig `paths` map `/runtime/v1/*` → `../../runtime/v1/dist/*`, so every instrument import is an unresolved module | -Turbo covers this for `build` and `lint` (both depend on `^build`) but not for a bare `tsc` or -`vitest` run. The build `rm -rf`s `outdir` before writing, so nothing hand-placed in `dist/` survives. +Root `pnpm build`, `pnpm lint`, `pnpm dev`, `pnpm test` and `pnpm test:e2e` build it first; a bare +`tsc` or `vitest` run does not. The build `rm -rf`s `outdir` before writing, so nothing hand-placed in `dist/` survives. ## Adding a library to the runtime @@ -61,7 +61,7 @@ Export-shape rules and the `.d.ts` import constraint are in `packages/runtime-bu `version` is bumped repo-wide by `scripts/increment-version.ts`; the release workflow publishes any package with a `publishConfig` whose version is not yet on npm. Do not hand-edit it. -There is **no `lint` or `format` script here**, so `pnpm lint` never type-checks this directory. +Root `pnpm lint` type-checks what `tsconfig.json` includes: the config, the declarations and `test/`. ## Tests diff --git a/storybook/AGENTS.md b/storybook/AGENTS.md index c7a8c7aec..4a03dd195 100644 --- a/storybook/AGENTS.md +++ b/storybook/AGENTS.md @@ -89,6 +89,6 @@ boots with web's i18n resources and a live `esbuild-wasm`. That is what lets the ## No tests, no build There is no `vitest.config.ts` and no `build` script here, so `pnpm test` and `pnpm build` do not -cover this workspace and neither does CI. `lint` is `tsc && oxlint --fix config vite.config.js`, and +cover this workspace and neither does CI. Root `pnpm lint` checks it, and `tsconfig.json` includes only `config/*` and `vite.config.js` — **stories are type-checked by their owning package, never by this one.** diff --git a/testing/AGENTS.md b/testing/AGENTS.md index e81f4f1de..ec26c056c 100644 --- a/testing/AGENTS.md +++ b/testing/AGENTS.md @@ -17,8 +17,8 @@ is `.agents/docs/playbooks/add-e2e-test.md`; the tier-by-tier picture is - **Route literals come from a generated file.** `src/generated/route.d.ts` is git-ignored and written by `scripts/gen-routes.ts`, which parses `FileRouteTypes['to']` out of `apps/web/src/route-tree.ts`. A route added in `apps/web` does not exist here until - `pnpm --filter @opendatacapture/testing gen:routes` runs (it is also wired into `postinstall`, - `lint` and the `test:*` scripts). Never hand-edit that file. + `pnpm --filter @opendatacapture/testing gen:routes` runs (`postinstall`, the `test:*` scripts + and root `pnpm lint` run it too). Never hand-edit that file. - **Selectors are `data-testid` attributes owned by `apps/web`.** A new spec usually means adding a testid over there in the same change. Roles and labels are used only where no testid exists. - **One database, shared by every worker.** `setup` seeds it once through the UI and `teardown` @@ -126,5 +126,5 @@ tag to a critical flow, leave it off everything else. There is **no `vitest.config.ts` here and no unit tier**; `pnpm test` never looks at this directory. -`lint` is `pnpm gen:routes && tsc && oxlint --fix .` — note the `.`, not `src`, so the config and -scripts are checked too. +There is no `lint` script: root `pnpm lint` runs `gen:routes`, then type-checks and lints this whole +directory, config and scripts included. From bfc9345b80417e3a3e8967bace1add934641c319 Mon Sep 17 00:00:00 2001 From: joshunrau Date: Wed, 18 Nov 2026 20:50:30 -0500 Subject: [PATCH 7/8] build: hash the root manifest into the builds that embed its version A production build of the api, the gateway or the web app now reads its version from the root package.json when RELEASE_VERSION is unset, and nothing in their cache keys named that file. A version bump made by the release script changed the keys only because it also rewrites a package those builds depend on. Co-Authored-By: Claude Fable 5.2 --- apps/api/turbo.json | 4 ++++ apps/gateway/turbo.json | 4 ++++ apps/web/turbo.json | 2 ++ 3 files changed, 10 insertions(+) diff --git a/apps/api/turbo.json b/apps/api/turbo.json index cf86a7b56..dda5533b4 100644 --- a/apps/api/turbo.json +++ b/apps/api/turbo.json @@ -2,6 +2,10 @@ "$schema": "https://turbo.build/schema.json", "extends": ["//"], "tasks": { + // release-info reads the version a production build embeds from the root package.json + "build": { + "inputs": ["$TURBO_EXTENDS$", "$TURBO_ROOT$/package.json"] + }, // prisma/schema.prisma sets no output, so the client lands in pnpm's store, outside what turbo can restore "db:generate": { "cache": false diff --git a/apps/gateway/turbo.json b/apps/gateway/turbo.json index ef513d6d7..d6dd451e0 100644 --- a/apps/gateway/turbo.json +++ b/apps/gateway/turbo.json @@ -2,6 +2,10 @@ "$schema": "https://turbo.build/schema.json", "extends": ["//"], "tasks": { + // release-info reads the version a production build embeds from the root package.json + "build": { + "inputs": ["$TURBO_EXTENDS$", "$TURBO_ROOT$/package.json"] + }, "db:push": { "cache": false, "dependsOn": ["db:generate"], diff --git a/apps/web/turbo.json b/apps/web/turbo.json index 5f6870e84..a5b5e49d6 100644 --- a/apps/web/turbo.json +++ b/apps/web/turbo.json @@ -2,7 +2,9 @@ "$schema": "https://turbo.build/schema.json", "extends": ["//"], "tasks": { + // release-info reads the version a production build embeds from the root package.json "build": { + "inputs": ["$TURBO_EXTENDS$", "$TURBO_ROOT$/package.json"], "env": ["API_BASE_URL", "CONTACT_EMAIL", "DOCS_URL", "GATEWAY_ENABLED", "GITHUB_REPO_URL", "LICENSE_URL"] } } From 0c62e69c2dbc9b72328acdf8a73fbda7cc8769cc Mon Sep 17 00:00:00 2001 From: joshunrau Date: Wed, 18 Nov 2026 22:00:43 -0500 Subject: [PATCH 8/8] build: build the playground-url CLI before the end-to-end suite Naming the suite's prerequisites explicitly dropped `^build`, which was what built packages/playground-url/dist/cli.js, and one playground spec runs that file. The suite passed on a machine that had built the CLI before and failed in CI, which had not. Co-Authored-By: Claude Fable 5.2 --- .agents/docs/architecture/testing-strategy.md | 3 ++- turbo.json | 2 +- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/.agents/docs/architecture/testing-strategy.md b/.agents/docs/architecture/testing-strategy.md index 7780c08e3..7a0725ffd 100644 --- a/.agents/docs/architecture/testing-strategy.md +++ b/.agents/docs/architecture/testing-strategy.md @@ -109,7 +109,8 @@ a lint failure and every run may rewrite the working tree. To check part of the `pnpm lint` is `turbo run lint lint:root`. `//#lint:root` depends on `//#generated`, a task with no script that names what a tool run over the whole repo reads and source control does not hold: both Prisma clients, `testing`'s route types, and `instrument-library`'s build, which reaches `runtime-v1` -and `runtime-core` through `^build`. `test:e2e` depends on the same task plus the gateway's `db:push`. +and `runtime-core` through `^build`. `test:e2e` depends on the same task, the gateway's `db:push`, and +`^build`, which builds the `playground-url` CLI that `testing/src/specs/playground.spec.ts` runs. `dev` and `dev:test` depend on `["^build", "db:generate"]`, to which `apps/gateway/turbo.json` adds `db:push`; `build` depends on `["^build", "db:generate"]` and `start` on `build`. `dev`, `dev:test`, `start`, `test:e2e` and `db:push` are `cache: false`. A workspace whose task differs from the root diff --git a/turbo.json b/turbo.json index e6dabf7cf..faae7407a 100644 --- a/turbo.json +++ b/turbo.json @@ -44,7 +44,7 @@ }, "@opendatacapture/testing#test:e2e": { "cache": false, - "dependsOn": ["//#generated", "@opendatacapture/gateway#db:push"] + "dependsOn": ["^build", "//#generated", "@opendatacapture/gateway#db:push"] } } }