Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions .agents/docs/architecture/auth-and-permissions.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,8 +15,8 @@ that they may read _some_ subject; the `where` decides whether they may read _th

## Layer 1: `@RouteAccess`

`REQUIRE_ROUTE_ACCESS` in the root `eslint.config.js` flags a handler without one; the guard turns a
missing one into a 500. Nothing checks the value. Routes whose declaration is not the ordinary
`opendatacapture/require-route-access` (`packages/oxlint-config/src/rules/`) flags a handler without
one; the guard turns a missing one into a 500. Nothing checks the value. Routes whose declaration is not the ordinary
`{ action, subject }` on the model they serve:

| Route | Declaration | Why it is safe |
Expand Down
18 changes: 10 additions & 8 deletions .agents/docs/architecture/testing-strategy.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@ project. Before trusting a new test, see it listed and watch it fail on purpose.

## Vitest projects

Twenty-two, each named after its directory except `runtime/v1` (`runtime-v1`) and `.github` (`github`). Quirks of each live in
Twenty-three, each named after its directory except `runtime/v1` (`runtime-v1`) and `.github` (`github`). Quirks of each live in
that package's `AGENTS.md` §Tests. Three run under happy-dom; the rest run in node, where one file
opts into a DOM with a first-line `// @vitest-environment happy-dom` docblock.

Expand All @@ -50,6 +50,7 @@ opts into a DOM with a first-line `// @vitest-environment happy-dom` docblock.
| `instrument-library` | `packages/instrument-library` | happy-dom; aliases `/runtime/v1/…` to sources, no build |
| `instrument-stubs` | `packages/instrument-stubs` | tests are `.test.js` |
| `instrument-utils` | `packages/instrument-utils` | |
| `oxlint-config` | `packages/oxlint-config` | `RuleTester` from `oxlint/plugins-dev` |
| `playground-url` | `packages/playground-url` | |
| `react-core` | `packages/react-core` | happy-dom |
| `release-info` | `packages/release-info` | |
Expand Down Expand Up @@ -91,23 +92,24 @@ outside the project globs by design.

## `pnpm lint` is the type-check, and it edits files

Per-package `lint` is `tsc && eslint --fix src`; there is no separate `typecheck` script, so a type
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:

| Package | `lint` |
| ------------------------------------------------------------- | ------------------------------------------ |
| `apps/outreach` | `astro check && eslint --fix src` |
| `packages/runtime-core` | `tsc --noEmit && eslint --fix src` |
| `packages/instrument-stubs`, `packages/instrument-guidelines` | eslint only — **no `tsc`** |
| `testing` | `pnpm gen:routes && tsc && eslint --fix .` |
| `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 |

## 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`,
`eslint.config.js`, `tsconfig.json`, `prettier.config.js`) invalidate every cached task when touched.
`oxfmt.config.ts`, `oxlint.config.ts`, `packages/oxlint-config/src/**`, `tsconfig.json`) invalidate
every cached task when touched.

## Coverage scope

Expand All @@ -124,7 +126,7 @@ counts their functions twice in the merged report.
`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`.

Not gated: knip (`pnpm knip` exists), and formatting — prettier runs only in the `.husky/pre-commit`
Not gated: knip (`pnpm knip` exists), and formatting — oxfmt runs only in the `.husky/pre-commit`
hook, which formats rather than verifies.

`.github/workflows/release.yaml` (push to `main`, dispatch on `release/<major>`) validates with `pnpm lint` only — **no unit or e2e
Expand Down
3 changes: 2 additions & 1 deletion .agents/docs/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,7 @@ Read the `AGENTS.md` in the directory you are editing; each covers only that wor
| Building the library catalog instruments import | `packages/runtime-bundler/AGENTS.md` |
| The `defineInstrument` public API | `packages/runtime-core/AGENTS.md` |
| Adding or editing a built-in instrument | `packages/instrument-library/AGENTS.md` |
| Lint rules and the custom oxlint plugin | `packages/oxlint-config/AGENTS.md` |
| Pinned library wrappers instruments import | `vendor/AGENTS.md` |
| The published runtime artifact | `runtime/v1/AGENTS.md` |
| End-to-end tests | `testing/AGENTS.md` |
Expand All @@ -33,7 +34,7 @@ isn't one.
| Topic | Path |
| --------------------------------------------------------------- | --------------------------------------------------- |
| Which workspace depends on which, what is built, what publishes | `.agents/docs/workspace-map.md` |
| The 11 `@douglasneuroinformatics/*` packages this repo consumes | `.agents/docs/packages/index.md` |
| The 9 `@douglasneuroinformatics/*` packages this repo consumes | `.agents/docs/packages/index.md` |
| Instrument source → bundle → store → interpret → render | `.agents/docs/architecture/instrument-pipeline.md` |
| The six similarly-named `runtime-*` things, and `vendor/` | `.agents/docs/architecture/runtime-and-vendor.md` |
| CASL, `@RouteAccess`, and group scoping | `.agents/docs/architecture/auth-and-permissions.md` |
Expand Down
12 changes: 5 additions & 7 deletions .agents/docs/packages/index.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Internal DNP packages

The 11 `@douglasneuroinformatics/*` packages, maintained in separate repos. Use this file to find
The 9 `@douglasneuroinformatics/*` packages, maintained in separate repos. Use this file to find
which one already does what you need, then read that package's source for the API. This file does
not copy APIs, because copies drift.

Expand All @@ -13,21 +13,19 @@ not copy APIs, because copies drift.
| `libui-form-types` | the `FormTypes` declarative-form types. Instrument code uses runtime-core's `FormInstrument` types, which wrap these | runtime-core, and libui's `Form` |
| `libnest` | the Nest layer of `apps/api`: bootstrap, config, Prisma models, validation pipes, logging, crypto, virtualization, test doubles (`./testing`). `apps/api/AGENTS.md` covers how the app uses it | api |
| `libui` | React/Tailwind components, hooks (`useTranslation`, `useNotificationsStore`, …), `cn`, i18n, `CoreProvider`. It has no root export: import `./components`, `./hooks`, `./utils`, `./i18n`, `./providers` or `./tailwind/globals.css` | web, gateway, playground, outreach, react-core, serve-instrument |
| `eslint-config` | the `config()` factory behind the root `eslint.config.js` | root |
| `prettier-config` | `createConfig()` behind the root `prettier.config.js`, and the `prettier-pre-commit` bin that `.husky/pre-commit` runs | root |
| `tsconfig` | the base that the root `tsconfig.json` extends. It sets `noEmit: true`, so the `tsc` in every `lint` script only typechecks | root |
| `esbuild-plugin-prisma` | `prismaPlugin({ outdir })`, which copies Prisma's query engine next to an esbuild bundle | gateway's `scripts/build.ts` |

## Reading the source

Resolve a package through a workspace in its "Used in" column. Only `eslint-config`,
`prettier-config` and `tsconfig` are linked at the repo root. For example:
Resolve a package through a workspace in its "Used in" column. Only `tsconfig` is
linked at the repo root. For example:
`apps/api/node_modules/@douglasneuroinformatics/libnest/src/index.ts`.

- `libnest`, `libui`, `libcrypto`, `libpasswd`: original TypeScript under `src/`.
- `prettier-config`, `esbuild-plugin-prisma`: JSDoc-typed `.js` under `src/`, plus a hand-written
- `esbuild-plugin-prisma`: JSDoc-typed `.js` under `src/`, plus a hand-written
`.d.ts`.
- `libjs`, `eslint-config`: `dist/` only, but unbundled and unminified with JSDoc intact, one file
- `libjs`: `dist/` only, but unbundled and unminified with JSDoc intact, one file
per module.
- `libui-form-types`, `tsconfig`: the published file is the whole package (`lib/index.d.ts`,
`tsconfig.json`).
Expand Down
4 changes: 2 additions & 2 deletions .agents/docs/playbooks/add-e2e-test.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ starting — `playwright.config.ts` boots api, gateway, web and playground itsel

4. **Register it in `pageModels` in `testing/src/support/fixtures.ts`** if the spec navigates to it with
`getPageModel`, keyed by the route literal — `'/datahub/subjects/$subjectId/assignments':
SubjectAssignmentsPage`. A page reached by clicking through needs no entry; use `new XPage(page)`.
SubjectAssignmentsPage`. A page reached by clicking through needs no entry; use `new XPage(page)`.

5. **Write the spec** at `testing/src/specs/<flow>.spec.ts`, importing
`import { expect, test } from '../support/fixtures';`. With the raw `@playwright/test` import, a
Expand All @@ -44,7 +44,7 @@ SubjectAssignmentsPage`. A page reached by clicking through needs no entry; use
## Verify

```sh
pnpm --filter @opendatacapture/testing lint # gen:routes, tsc, eslint .
pnpm --filter @opendatacapture/testing lint # gen:routes, tsc, oxlint .
pnpm --filter @opendatacapture/testing test:e2e --list src/specs/<flow>.spec.ts # your titles, under [chromium]
pnpm --filter @opendatacapture/testing test:e2e src/specs/<flow>.spec.ts # one spec; setup still runs
pnpm test:e2e # whole suite, from repo root
Expand Down
2 changes: 1 addition & 1 deletion .agents/docs/playbooks/add-env-var.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@
or give it a `.default()`. A cross-field requirement goes in the `.transform((env, ctx) => ...)` at
the bottom of `$Env` via `ctx.addIssue`; the `STORAGE_ENABLED` block is the pattern.

5. **Read it as `this.configService.get('YOUR_KEY')`.** `process.env` is an eslint error in
5. **Read it as `this.configService.get('YOUR_KEY')`.** `process.env` is an oxlint error in
`apps/api/src`; do not add a second exception to
`src/core/decorators/throttle-login-request.decorator.ts`. To gate a whole module on a boolean, use
`{ module: XModule, when: 'YOUR_KEY' }` in the `imports` array of `apps/api/src/main.ts`.
Expand Down
2 changes: 1 addition & 1 deletion .agents/docs/playbooks/add-vitest-project.md
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,7 @@ project, so its test files are collected by nothing and CI stays green. The loud
devDependency — ask first per the root rule, then `pnpm install`. Redeclare under `resolve.alias`
any alias the source imports; `vite.config.ts` is not loaded during tests.

5. **Add `vitest.config.ts` to the package's `tsconfig.json` `include`.** Package eslint runs on `src`
5. **Add `vitest.config.ts` to the package's `tsconfig.json` `include`.** Package oxlint runs on `src`
only, so `tsc` is the config's only check. Tests in `test/` rather than `src/` need `test/**/*.ts`
there too (`packages/runtime-bundler`), or nothing type-checks them.

Expand Down
2 changes: 1 addition & 1 deletion .agents/docs/playbooks/promote-to-react-core.md
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@ done; `apps/web`'s until step 9.
6. **Repoint every `@/…` import.** react-core has no `@` alias, and neither does Storybook for files
here. `@/components/*` becomes a relative sibling import; `@/store`, `@/hooks/*`, `@/config`,
`@/services/*` and `@/utils/*` become props per step 5. A relative path climbing into
`apps/web/src` typechecks and no eslint rule forbids it — nothing under `src/` may resolve outside
`apps/web/src` typechecks and no oxlint rule forbids it — nothing under `src/` may resolve outside
the package.

7. **Declare every remaining bare import in `packages/react-core/package.json`** (`@heroicons/react`,
Expand Down
2 changes: 1 addition & 1 deletion .agents/docs/playbooks/run-locally.md
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,7 @@ one.
Done when `rs.status().ok` returns 1.

6. **`pnpm install`.** It also installs the husky pre-commit hook, which formats staged files with
prettier and runs neither lint nor tests.
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
dev server started without it dies with
Expand Down
1 change: 1 addition & 0 deletions .agents/docs/workspace-map.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,7 @@ The five `apps/*`, `storybook` and `testing` are leaves: no workspace depends on
| `instrument-stubs` | Minimal stub instruments for tests | react-core, schemas, web |
| `instrument-utils` | Helpers for working with instrument definitions | api, react-core, web |
| `licenses` | SPDX and custom license metadata | outreach, runtime-core, runtime-v1, schemas, web |
| `oxlint-config` | The base oxlint config and the repo's custom-rule plugin (`opendatacapture/*`) | root `oxlint.config.ts` |
| `playground-url` | Encodes and decodes shareable playground URLs | playground, testing |
| `react-core` | Components and hooks shared by more than one frontend | gateway, playground, serve-instrument, storybook, web |
| `release-info` | Resolves version, branch and commit at build time | api, gateway, web |
Expand Down
2 changes: 1 addition & 1 deletion .agents/skills/finishing-changes/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ for unit tests). A diff spanning rows runs each row's checks; any other file mea
`pnpm lint`, `pnpm test:coverage` and `pnpm test:e2e` in sequence, so a lint failure hides the rest until it
is fixed. `pnpm test:e2e` needs its browsers installed once per machine
(`.agents/docs/playbooks/add-e2e-test.md`).
2. **After it, read `git status`.** `eslint --fix` rewrites as it checks; the rewrites are your own code being
2. **After it, read `git status`.** `oxlint --fix` rewrites as it checks; the rewrites are your own code being
sorted, so keep them. TS2345 on a route literal you added is an exception until the user regenerates
`route-tree.ts` (`.agents/docs/playbooks/add-web-route.md`); revert any `route-tree.ts` diff. Because that
failure stops `pnpm check` at lint, run `pnpm test:coverage` directly and leave `pnpm test:e2e` for after
Expand Down
2 changes: 1 addition & 1 deletion .agents/skills/troubleshooting/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ that is deliberately left alone is recorded in the owning workspace's `AGENTS.md
- **TS2345 on a route literal you just added** is expected until the user regenerates `route-tree.ts`
(`.agents/docs/playbooks/add-web-route.md`). Every Vite run in `apps/web` (`dev`, `dev:test`, the Playwright
webServer, `vite build`) rewrites that tracked file; if `git status` shows it after a debugging run, revert it.
- **`pnpm lint` passed and the tree changed**: `eslint --fix` sorted your new code. Keep the rewrite.
- **`pnpm lint` passed and the tree changed**: `oxlint --fix` sorted your new code. Keep the rewrite.
- **`Failed to find .env file at default paths`**: run `pnpm generate:env` (root `AGENTS.md`).
- **ENOENT while a Vite config resolves, or `/runtime/v1/*` unresolved**: `runtime/v1/dist` is unbuilt. Turbo
builds it; a bare `tsc`, `vitest` or storybook does not (`.agents/docs/playbooks/run-locally.md`).
Expand Down
17 changes: 0 additions & 17 deletions .eslint/rules/index.js

This file was deleted.

13 changes: 12 additions & 1 deletion .husky/pre-commit
Original file line number Diff line number Diff line change
@@ -1 +1,12 @@
prettier-pre-commit
STAGED_FILES=$(mktemp)
trap 'rm -f "$STAGED_FILES"' EXIT

git diff --cached --name-only --diff-filter=ACMR -z > "$STAGED_FILES"

# Given no path, oxfmt formats the whole working directory
[ -s "$STAGED_FILES" ] || exit 0

xargs -0 pnpm exec oxfmt --no-error-on-unmatched-pattern < "$STAGED_FILES"

# Add the formatted files back to staging
xargs -0 git add < "$STAGED_FILES"
8 changes: 0 additions & 8 deletions .prettierignore

This file was deleted.

Loading