@evandam93/dev-env 0.0.0-stage → 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +282 -2
- package/bin/dev-env.js +3 -0
- package/dist/abandoned.d.ts +2 -0
- package/dist/abandoned.js +66 -0
- package/dist/affected/graph.d.ts +43 -0
- package/dist/affected/graph.js +220 -0
- package/dist/affected/index.d.ts +5 -0
- package/dist/affected/index.js +3 -0
- package/dist/affected/layout.d.ts +11 -0
- package/dist/affected/layout.js +34 -0
- package/dist/affected/run.d.ts +10 -0
- package/dist/affected/run.js +96 -0
- package/dist/affected/select.d.ts +27 -0
- package/dist/affected/select.js +79 -0
- package/dist/checkout.d.ts +13 -0
- package/dist/checkout.js +40 -0
- package/dist/cli.d.ts +1 -0
- package/dist/cli.js +98 -0
- package/dist/compose.d.ts +18 -0
- package/dist/compose.js +119 -0
- package/dist/environment.d.ts +33 -0
- package/dist/environment.js +387 -0
- package/dist/errors.d.ts +4 -0
- package/dist/errors.js +4 -0
- package/dist/index.d.ts +4 -0
- package/dist/index.js +2 -0
- package/dist/machine.d.ts +3 -0
- package/dist/machine.js +17 -0
- package/dist/manifest.d.ts +95 -0
- package/dist/manifest.js +91 -0
- package/dist/ports.d.ts +6 -0
- package/dist/ports.js +92 -0
- package/dist/processes.d.ts +13 -0
- package/dist/processes.js +116 -0
- package/dist/readiness.d.ts +6 -0
- package/dist/readiness.js +31 -0
- package/dist/shared.d.ts +9 -0
- package/dist/shared.js +81 -0
- package/dist/slots.d.ts +21 -0
- package/dist/slots.js +165 -0
- package/dist/state.d.ts +21 -0
- package/dist/state.js +36 -0
- package/dist/test-environment.d.ts +36 -0
- package/dist/test-environment.js +67 -0
- package/dist/workspace.d.ts +31 -0
- package/dist/workspace.js +140 -0
- package/package.json +75 -4
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Erik van Dam
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,283 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @evandam93/dev-env
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
One development environment per checkout and target, so git worktrees can run side by side with no ports pinned anywhere.
|
|
4
|
+
|
|
5
|
+
You describe a target's services in a `dev-env.ts` beside its code: containers from its `compose.yaml`, and processes such as a dev server.
|
|
6
|
+
`dev-env start` gives each service a free port of its own, starts them in order, and returns once every one answers.
|
|
7
|
+
A second worktree of the same repository gets its own containers, ports and data, so two branches, or two agents, never fight over port 5432.
|
|
8
|
+
Integration tests get the same environment in a test mode of their own, with empty data for every file, and lanes so files can run side by side.
|
|
9
|
+
|
|
10
|
+
```bash
|
|
11
|
+
dev-env start <target>... [--test]
|
|
12
|
+
dev-env stop [target]... [--test]
|
|
13
|
+
dev-env info [--json]
|
|
14
|
+
dev-env reset <target>... [--test]
|
|
15
|
+
dev-env affected <target> [--base <ref>] [--list]
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
## Requirements
|
|
19
|
+
|
|
20
|
+
- Node.js 22.17 or later.
|
|
21
|
+
- Docker with Compose v2, as `docker compose`.
|
|
22
|
+
- git: the repository must be a git checkout, since an environment belongs to its checkout.
|
|
23
|
+
- A workspace: `pnpm-workspace.yaml`, or `workspaces` in the root `package.json` for npm and Yarn.
|
|
24
|
+
- Vitest, for `startTestEnvironment` lanes and for `dev-env affected`.
|
|
25
|
+
|
|
26
|
+
## Install
|
|
27
|
+
|
|
28
|
+
```bash
|
|
29
|
+
pnpm add --save-dev @evandam93/dev-env
|
|
30
|
+
# or: npm install --save-dev @evandam93/dev-env
|
|
31
|
+
# or: yarn add --dev @evandam93/dev-env
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
Then run it through your package manager, such as `pnpm dev-env start api`, or from a script in your root `package.json`.
|
|
35
|
+
|
|
36
|
+
## A minimal target
|
|
37
|
+
|
|
38
|
+
A target is any workspace directory with a `dev-env.ts`, named after its directory.
|
|
39
|
+
dev-env reads the workspace globs from `pnpm-workspace.yaml`, or else from the root `package.json`'s `workspaces`.
|
|
40
|
+
Two targets with one directory name are refused, since the name is all a command gives.
|
|
41
|
+
|
|
42
|
+
```ts
|
|
43
|
+
// apps/api/dev-env.ts
|
|
44
|
+
import { defineManifest } from '@evandam93/dev-env'
|
|
45
|
+
|
|
46
|
+
export default defineManifest({
|
|
47
|
+
services: {
|
|
48
|
+
postgres: { kind: 'compose' },
|
|
49
|
+
api: {
|
|
50
|
+
kind: 'process',
|
|
51
|
+
command: ({ port, ports }) => [
|
|
52
|
+
'node',
|
|
53
|
+
'server.js',
|
|
54
|
+
'--port',
|
|
55
|
+
String(port),
|
|
56
|
+
'--database',
|
|
57
|
+
`postgres://postgres:local@127.0.0.1:${ports.postgres}/postgres`,
|
|
58
|
+
],
|
|
59
|
+
sources: ['src'],
|
|
60
|
+
readinessPath: '/health',
|
|
61
|
+
},
|
|
62
|
+
},
|
|
63
|
+
})
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
```yaml
|
|
67
|
+
# apps/api/compose.yaml
|
|
68
|
+
services:
|
|
69
|
+
postgres:
|
|
70
|
+
image: postgres:17
|
|
71
|
+
environment:
|
|
72
|
+
POSTGRES_PASSWORD: local
|
|
73
|
+
ports:
|
|
74
|
+
- '127.0.0.1:${POSTGRES_PORT:?allocated by dev-env}:5432'
|
|
75
|
+
healthcheck:
|
|
76
|
+
test: ['CMD', 'pg_isready', '-U', 'postgres']
|
|
77
|
+
interval: 1s
|
|
78
|
+
retries: 30
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
```bash
|
|
82
|
+
dev-env start api
|
|
83
|
+
dev-env info --json # every service's port and address
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
The manifest is TypeScript.
|
|
87
|
+
dev-env loads it with tsx, so it may import more of your code, without extensions and through the `paths` of the `tsconfig.json` nearest it.
|
|
88
|
+
|
|
89
|
+
## The manifest
|
|
90
|
+
|
|
91
|
+
A `compose` service is the service of that name in `compose.yaml` beside the manifest.
|
|
92
|
+
It must have a healthcheck and publish on loopback, or `dev-env start` refuses it.
|
|
93
|
+
Its port reaches Compose as `<NAME>_PORT`, upper-cased with every other character as `_`, as above.
|
|
94
|
+
|
|
95
|
+
A `process` service gets its port as `PORT`, and every service in the target is available as `<NAME>_PORT`.
|
|
96
|
+
Its `command` receives the same ports, and a `dataDirectory` for whatever the process persists itself.
|
|
97
|
+
That directory survives `dev-env stop` and goes on `dev-env reset`, like a container's volume.
|
|
98
|
+
Its `readinessPath` is the path that answers below 400 once it is usable.
|
|
99
|
+
Its `sources` name the directories, relative to the target, that hold the code it runs, which `dev-env affected` reads.
|
|
100
|
+
Each service may set `timeoutMs` for how long it may take to become ready.
|
|
101
|
+
|
|
102
|
+
Compose services start first.
|
|
103
|
+
A manifest's optional `setup` then runs with every service's port, before any process starts, such as migrations a process needs before it can log in.
|
|
104
|
+
It runs on every dev start, so it must be safe to run again, and a failure stops the start with its reason.
|
|
105
|
+
Test environments skip it, because each test file sets up its own data.
|
|
106
|
+
Processes then start one at a time, each ready before the next, since processes that share local state can fail when they open it at the same moment.
|
|
107
|
+
A manifest's optional `afterStart` runs once every process is ready, with the same ports, for data only a running process can make, such as users a local stand-in for an identity provider holds.
|
|
108
|
+
Like `setup`, it runs on every dev start, must be safe to run again, stops the start with its reason when it fails, and is skipped by test environments.
|
|
109
|
+
|
|
110
|
+
The other fields are optional too:
|
|
111
|
+
|
|
112
|
+
- `testSettings`: settings every test environment of the target starts with, which a command reads from its context's `settings`.
|
|
113
|
+
- `shared`: globs for what every integration spec is built from without importing it, for `dev-env affected`.
|
|
114
|
+
- `specs.always` and `specs.beforeRelease`: integration specs `dev-env affected` always runs, and those it leaves to the full suite.
|
|
115
|
+
|
|
116
|
+
## Identity
|
|
117
|
+
|
|
118
|
+
The environment id is the first eight hex characters of a SHA-256 of the checkout's real path.
|
|
119
|
+
Each target has its own compose project, `<directory>-<id>-<target>`, with `-test` added in test mode, and `-test-<lane>` for a lane after the first.
|
|
120
|
+
That project name is also the environment's `name`, unique on the machine, which a process's command receives as `environmentName` and a test reads from its `TestEnvironment`.
|
|
121
|
+
|
|
122
|
+
## Ports
|
|
123
|
+
|
|
124
|
+
A service's preferred port comes from a hash of the checkout, target, mode and service, in the range 20000 to 29999.
|
|
125
|
+
|
|
126
|
+
A preferred port is never trusted on its own.
|
|
127
|
+
Allocation skips ports recorded by any other environment in any worktree of the repository, and ports something else is listening on.
|
|
128
|
+
It reads and writes those records under a lock in the git common directory, because a probe cannot see a sibling's container between a remove and a create.
|
|
129
|
+
|
|
130
|
+
A port stays with its environment across restarts, and `dev-env reset` gives it up.
|
|
131
|
+
Nothing is ever freed by stopping whatever holds it.
|
|
132
|
+
`dev-env info --json` is the only source of an address, so never assume a port.
|
|
133
|
+
|
|
134
|
+
## State
|
|
135
|
+
|
|
136
|
+
`.dev-env/<target>/` inside the checkout holds `state.json`, one log per process, and `data/` for the processes' own data.
|
|
137
|
+
Add `.dev-env/` to your `.gitignore`.
|
|
138
|
+
A state file written under another environment id is ignored, because a moved or copied checkout never owned those ports and pids.
|
|
139
|
+
|
|
140
|
+
## Readiness and stopping
|
|
141
|
+
|
|
142
|
+
`dev-env start` exits 0 only once every service answers, and otherwise fails naming the service and showing its log.
|
|
143
|
+
|
|
144
|
+
`dev-env stop` keeps ports, containers and volumes, so the next start resumes where it left off.
|
|
145
|
+
It signals a process only if its pid and start time still match the record, so a recycled pid is never signalled.
|
|
146
|
+
If that process died and left children running, as when a package manager is killed and its server is not, a child counts as ours only if it is in the recorded process group and holds the process's log open.
|
|
147
|
+
`dev-env stop` stops those children, and `dev-env start` replaces them on the same port.
|
|
148
|
+
`dev-env reset` also removes the target's containers, volumes, process data and state.
|
|
149
|
+
|
|
150
|
+
Stop what you started before you remove a worktree, with `dev-env reset <target>` for each target.
|
|
151
|
+
A worktree deleted without it leaves its containers, volumes and network behind, and Docker runs out of network addresses at about thirty.
|
|
152
|
+
So every start first removes each compose project whose recorded working directory is gone and whose name dev-env gave it for that checkout, and never a project of another tool or a shared one.
|
|
153
|
+
It cannot reach a deleted worktree's processes.
|
|
154
|
+
Compose commands are scoped to the target's project, so they cannot reach another environment.
|
|
155
|
+
|
|
156
|
+
## Test mode
|
|
157
|
+
|
|
158
|
+
`--test` is a separate environment for the same target, with its own project, ports, data and state.
|
|
159
|
+
Integration tests use it through `startTestEnvironment`:
|
|
160
|
+
|
|
161
|
+
```ts
|
|
162
|
+
import { startTestEnvironment, type TestEnvironment } from '@evandam93/dev-env'
|
|
163
|
+
import { beforeAll, it } from 'vitest'
|
|
164
|
+
|
|
165
|
+
let environment: TestEnvironment
|
|
166
|
+
|
|
167
|
+
beforeAll(async () => {
|
|
168
|
+
environment = await startTestEnvironment('api')
|
|
169
|
+
})
|
|
170
|
+
|
|
171
|
+
it('answers', async () => {
|
|
172
|
+
const { url } = environment.services.api ?? {}
|
|
173
|
+
// ...
|
|
174
|
+
})
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
Each service in `services` has its `port`, `address`, `running` and, for a process, its `url`.
|
|
178
|
+
|
|
179
|
+
A test environment has lanes, so test files can run side by side without sharing data.
|
|
180
|
+
Each lane has its own project, ports, data and state, and lane 1 is the plain `--test` environment.
|
|
181
|
+
`startTestEnvironment` uses Vitest's worker number as the lane, so each worker keeps one lane for every file it runs, and `lane` sets it instead.
|
|
182
|
+
|
|
183
|
+
Every file starts with empty data.
|
|
184
|
+
A lane that is fully running keeps its containers and ports, and only its data is thrown away: each compose service is removed with its volumes and started again, and each process starts again on an empty data directory.
|
|
185
|
+
Starting containers is most of what a fresh environment costs, which is why the lane stays up.
|
|
186
|
+
A lane that is not fully running is reset and started from nothing, so a run that died leaves nothing behind for the next.
|
|
187
|
+
|
|
188
|
+
A test file must not assume what ran before it in its lane.
|
|
189
|
+
Its data is empty, but a service marked `shared` holds every environment's data on the machine, so read it by your environment's `name`, your own IDs and from your own start.
|
|
190
|
+
|
|
191
|
+
`without` names processes a test does not need, which stay stopped.
|
|
192
|
+
|
|
193
|
+
`settings` passes test-only values to the manifest's commands, such as raised limits.
|
|
194
|
+
A manifest's `testSettings` are every test environment's defaults, and a spec's own `settings` win over them.
|
|
195
|
+
A dev environment gets neither.
|
|
196
|
+
|
|
197
|
+
A target can add `compose.test.yaml` beside its `compose.yaml`, which Compose merges over it in test mode only.
|
|
198
|
+
It suits settings that trade durability for speed, since test data is thrown away after every file.
|
|
199
|
+
|
|
200
|
+
Files leave their lane running for the next, so the run removes every lane at its end with `resetTestEnvironments`, from a Vitest global setup:
|
|
201
|
+
|
|
202
|
+
```ts
|
|
203
|
+
// vitest.integration.ts
|
|
204
|
+
import { defineConfig } from 'vitest/config'
|
|
205
|
+
|
|
206
|
+
export default defineConfig({
|
|
207
|
+
test: {
|
|
208
|
+
include: ['src/**/*.integration.spec.ts'],
|
|
209
|
+
globalSetup: ['./reset-lanes.ts'],
|
|
210
|
+
},
|
|
211
|
+
})
|
|
212
|
+
```
|
|
213
|
+
|
|
214
|
+
```ts
|
|
215
|
+
// reset-lanes.ts
|
|
216
|
+
import { resetTestEnvironments } from '@evandam93/dev-env'
|
|
217
|
+
|
|
218
|
+
export const teardown = () => resetTestEnvironments({ target: 'api' })
|
|
219
|
+
```
|
|
220
|
+
|
|
221
|
+
`dev-env reset <target> --test` removes every lane of the target, and `dev-env stop --test` stops them.
|
|
222
|
+
|
|
223
|
+
`stopService` and `startService` on that environment trigger a failure, keeping the service's port and data, for any service that is not shared:
|
|
224
|
+
|
|
225
|
+
```ts
|
|
226
|
+
const environment = await startTestEnvironment('api')
|
|
227
|
+
await environment.stopService('postgres')
|
|
228
|
+
// Place orders while the database is down.
|
|
229
|
+
await environment.startService('postgres')
|
|
230
|
+
```
|
|
231
|
+
|
|
232
|
+
## Lane slots
|
|
233
|
+
|
|
234
|
+
Each test file holds one of the machine's lane slots from `startTestEnvironment` until its process exits, so runs from several worktrees can go at once without slowing each other until tests time out.
|
|
235
|
+
A file that finds every slot held waits, and prints which environments hold them.
|
|
236
|
+
The number of slots is what Docker's memory holds after the shared services, at about 384 MB a lane, and no more than one for every 3 of the host's cores, since each lane's processes run on the host.
|
|
237
|
+
`DEV_ENV_LANE_SLOTS` sets it instead.
|
|
238
|
+
|
|
239
|
+
A file whose results depend on timing passes `exclusive: true`, or runs with `DEV_ENV_EXCLUSIVE=1`, and holds every slot.
|
|
240
|
+
While it waits for the files already running, no other file takes a slot, and a file that waits holds nothing, so two exclusive files take turns.
|
|
241
|
+
|
|
242
|
+
A slot is a file under `lanes/` in the machine directory, holding its process's pid and start time.
|
|
243
|
+
A process that exits releases its slots, also on `SIGINT` and `SIGTERM`, and a waiter removes the slot of a process that died or whose pid now belongs to another process, so a killed run never keeps one.
|
|
244
|
+
The machine directory is `~/.cache/dev-env`, or `$XDG_CACHE_HOME/dev-env`, and `DEV_ENV_HOME` moves it.
|
|
245
|
+
|
|
246
|
+
## Shared services
|
|
247
|
+
|
|
248
|
+
A compose service marked `shared: true` runs once on the machine, for every checkout, lane and mode of its target, in a compose project of its own, `dev-env-shared-<machine>-<target>`.
|
|
249
|
+
It suits a heavy service whose data a reader can tell apart, such as a telemetry stack each environment writes to under its own `name`.
|
|
250
|
+
The first start that needs it starts it, from that checkout's `compose.yaml`, and it is never recreated while it runs, because other runs are using it.
|
|
251
|
+
Its ports are recorded in the machine directory and taken by no environment.
|
|
252
|
+
`dev-env stop` and `dev-env reset` leave it running, and `docker compose --project-name <project> down --volumes` removes it.
|
|
253
|
+
|
|
254
|
+
## Affected integration specs
|
|
255
|
+
|
|
256
|
+
`dev-env affected <target> [--base <ref>] [--list]` runs only the target's integration specs that the checkout's changes since the base reach, and says which it chose and why; `--list` only says.
|
|
257
|
+
Without `--base`, the base is where the checkout left the remote's default branch: `origin/HEAD`, or else `origin/main` or `origin/master`.
|
|
258
|
+
It runs Vitest through the repository's package manager with the target's `vitest.integration.ts`, on the specs named `*.integration.spec.ts`.
|
|
259
|
+
The package manager is the one the root `package.json`'s `packageManager` names, or else the one whose lockfile the repository holds: `pnpm-lock.yaml`, `yarn.lock` or `package-lock.json`.
|
|
260
|
+
|
|
261
|
+
It reads each fact where it already lives, so nothing is kept by hand:
|
|
262
|
+
|
|
263
|
+
- The processes a spec starts are the ones its single `startTestEnvironment` call does not leave out, so `without` must be a written-out list of names.
|
|
264
|
+
- A process reaches the directories its `sources` name, and every file their code imports, following relative imports and the `paths` of the nearest `tsconfig.json`.
|
|
265
|
+
- A spec reaches every file it imports, and a workspace package it imports, by the name its `package.json` gives it, as a whole.
|
|
266
|
+
- A shared path runs every spec.
|
|
267
|
+
The target's are `dev-env.ts`, `compose.yaml`, `compose.test.yaml`, `package.json`, `tsconfig.json`, `tsconfig.*.json` and `vitest.integration.ts`.
|
|
268
|
+
The repository's are its root `package.json`, `tsconfig.json`, `.nvmrc`, `.node-version`, and its package manager's lockfile and configuration, such as `pnpm-workspace.yaml` or `.yarnrc.yml`.
|
|
269
|
+
The manifest's `shared` adds its own, relative to the target or from the repository with a leading `/`, such as migrations or a task runner's configuration.
|
|
270
|
+
- Tests, stories and docs run nowhere, and a path no spec reaches runs nothing.
|
|
271
|
+
|
|
272
|
+
`specs.always` names specs every run holds, such as the product's own scenarios, and `specs.beforeRelease` those it never holds, such as a slow paced replay, which only the full suite runs.
|
|
273
|
+
Bindings between processes are not followed: in a test environment a process answers only when the spec starts it.
|
|
274
|
+
|
|
275
|
+
`@evandam93/dev-env/affected` exports the same selection, `layoutOf`, `graphOf`, `selectSpecs` and `forPullRequest`, for a test that pins which specs a change chooses.
|
|
276
|
+
|
|
277
|
+
## What it does not do
|
|
278
|
+
|
|
279
|
+
It holds no credentials: a target's local passwords are constants in its own compose file.
|
|
280
|
+
|
|
281
|
+
## License
|
|
282
|
+
|
|
283
|
+
MIT
|
package/bin/dev-env.js
ADDED
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
import { execFile } from 'node:child_process';
|
|
2
|
+
import { existsSync } from 'node:fs';
|
|
3
|
+
import { basename, dirname } from 'node:path';
|
|
4
|
+
import { promisify } from 'node:util';
|
|
5
|
+
import { composeProjectOf, environmentIdOf } from './checkout.js';
|
|
6
|
+
const run = promisify(execFile);
|
|
7
|
+
const PROJECT_LABEL = 'com.docker.compose.project';
|
|
8
|
+
const escaped = (text) => text.replaceAll(/[.*+?^${}()|[\]\\]/g, '\\$&');
|
|
9
|
+
/*
|
|
10
|
+
* A project dev-env made is named for its checkout, by the checkout's
|
|
11
|
+
* directory name and id, the hash of its root. The checkout is one of the
|
|
12
|
+
* directories above the working directory Compose recorded, the target's, at
|
|
13
|
+
* whatever depth its workspace was. A name no such directory gives is someone
|
|
14
|
+
* else's project, or a shared one, and is never touched.
|
|
15
|
+
*/
|
|
16
|
+
export const isAbandonedProject = (project, workingDirectory, exists = existsSync) => {
|
|
17
|
+
if (exists(workingDirectory))
|
|
18
|
+
return false;
|
|
19
|
+
const target = basename(workingDirectory);
|
|
20
|
+
for (let root = dirname(workingDirectory); root !== dirname(root); root = dirname(root)) {
|
|
21
|
+
const name = composeProjectOf({ root, id: environmentIdOf(root) }, target, 'dev');
|
|
22
|
+
if (new RegExp(`^${escaped(name)}(-test(-\\d+)?)?$`).test(project))
|
|
23
|
+
return true;
|
|
24
|
+
}
|
|
25
|
+
return false;
|
|
26
|
+
};
|
|
27
|
+
const lines = async (args) => {
|
|
28
|
+
const { stdout } = await run('docker', [...args]);
|
|
29
|
+
return stdout.split('\n').filter((line) => line !== '');
|
|
30
|
+
};
|
|
31
|
+
const removeProject = async (project) => {
|
|
32
|
+
const filter = ['--filter', `label=${PROJECT_LABEL}=${project}`];
|
|
33
|
+
const containers = await lines(['ps', '--all', '--quiet', ...filter]);
|
|
34
|
+
if (containers.length > 0)
|
|
35
|
+
await run('docker', ['rm', '--force', '--volumes', ...containers]);
|
|
36
|
+
const networks = await lines(['network', 'ls', '--quiet', ...filter]);
|
|
37
|
+
if (networks.length > 0)
|
|
38
|
+
await run('docker', ['network', 'rm', ...networks]);
|
|
39
|
+
const volumes = await lines(['volume', 'ls', '--quiet', ...filter]);
|
|
40
|
+
if (volumes.length > 0)
|
|
41
|
+
await run('docker', ['volume', 'rm', '--force', ...volumes]);
|
|
42
|
+
};
|
|
43
|
+
let swept;
|
|
44
|
+
/*
|
|
45
|
+
* A worktree deleted without `env:reset` leaves its containers, volumes and
|
|
46
|
+
* network behind, and Docker runs out of network addresses at about thirty.
|
|
47
|
+
* Its compose file is gone with it, so the project is removed by its labels.
|
|
48
|
+
* Once per process; a removal another process already made is not an error.
|
|
49
|
+
*/
|
|
50
|
+
export const removeAbandonedProjects = () => {
|
|
51
|
+
swept ??= (async () => {
|
|
52
|
+
const recorded = await lines([
|
|
53
|
+
'ps',
|
|
54
|
+
'--all',
|
|
55
|
+
'--format',
|
|
56
|
+
`{{.Label "${PROJECT_LABEL}"}}\t{{.Label "${PROJECT_LABEL}.working_dir"}}`,
|
|
57
|
+
]);
|
|
58
|
+
const projects = new Map(recorded.map((line) => line.split('\t')));
|
|
59
|
+
for (const [project, workingDirectory] of projects)
|
|
60
|
+
if (project &&
|
|
61
|
+
workingDirectory &&
|
|
62
|
+
isAbandonedProject(project, workingDirectory))
|
|
63
|
+
await removeProject(project).catch(() => undefined);
|
|
64
|
+
})();
|
|
65
|
+
return swept;
|
|
66
|
+
};
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
export interface Layout {
|
|
2
|
+
/** The target's directory. */
|
|
3
|
+
readonly target: string;
|
|
4
|
+
/** The repository's directory. */
|
|
5
|
+
readonly repository: string;
|
|
6
|
+
/** Each process the target can start, by the name a spec's `without` uses, with its `sources`. */
|
|
7
|
+
readonly processes: ReadonlyMap<string, readonly string[]>;
|
|
8
|
+
/** Each workspace package of the repository by its name, with its directory, as `/libs/ui/`. */
|
|
9
|
+
readonly packages: ReadonlyMap<string, string>;
|
|
10
|
+
/** Globs for paths every spec is built from without importing them, such as the lockfile. */
|
|
11
|
+
readonly shared: readonly string[];
|
|
12
|
+
}
|
|
13
|
+
/** Where a path reaches a spec from: the spec's own imports, or a process it starts. */
|
|
14
|
+
export type Route = {
|
|
15
|
+
readonly kind: 'imports';
|
|
16
|
+
} | {
|
|
17
|
+
readonly kind: 'process';
|
|
18
|
+
readonly process: string;
|
|
19
|
+
};
|
|
20
|
+
export interface Reach {
|
|
21
|
+
/** Every file the spec reaches, with the route it reaches it by. */
|
|
22
|
+
readonly files: ReadonlyMap<string, Route>;
|
|
23
|
+
/** Directories the spec reaches as a whole, such as a process's sources or a package. */
|
|
24
|
+
readonly directories: ReadonlyMap<string, Route>;
|
|
25
|
+
}
|
|
26
|
+
/** Files that never run in a test environment, even inside a process's sources. */
|
|
27
|
+
export declare const NOT_RUNTIME: readonly RegExp[];
|
|
28
|
+
export declare const isRuntime: (path: string) => boolean;
|
|
29
|
+
export declare const pathIn: (layout: Layout, absolute: string) => string;
|
|
30
|
+
/**
|
|
31
|
+
* The processes a spec starts: every process of the target, less the ones its
|
|
32
|
+
* one `startTestEnvironment` call leaves out. A spec that does not call it
|
|
33
|
+
* starts none. The list must be written out, so it can be read without
|
|
34
|
+
* running the spec.
|
|
35
|
+
*/
|
|
36
|
+
export declare const startedBy: (layout: Layout, spec: string) => string[];
|
|
37
|
+
export interface Graph {
|
|
38
|
+
readonly specs: ReadonlyMap<string, Reach>;
|
|
39
|
+
/** The layout's shared globs, a change to any of which reaches every spec. */
|
|
40
|
+
readonly shared: readonly string[];
|
|
41
|
+
}
|
|
42
|
+
export declare const specsIn: (layout: Layout) => string[];
|
|
43
|
+
export declare const graphOf: (layout: Layout) => Graph;
|
|
@@ -0,0 +1,220 @@
|
|
|
1
|
+
/*
|
|
2
|
+
* What each integration spec of a target reaches, read from the code rather
|
|
3
|
+
* than kept by hand: the files a spec imports, the processes its
|
|
4
|
+
* `startTestEnvironment` call leaves in, and the files under each process's
|
|
5
|
+
* `sources` with what they import. A new spec or process needs no edit here.
|
|
6
|
+
*
|
|
7
|
+
* Bindings between processes add nothing: in a test environment a process
|
|
8
|
+
* answers only when the spec starts it.
|
|
9
|
+
*
|
|
10
|
+
* Paths are relative to the target, and a path that starts with `/` is
|
|
11
|
+
* relative to the repository.
|
|
12
|
+
*/
|
|
13
|
+
import { existsSync, globSync, readFileSync, statSync } from 'node:fs';
|
|
14
|
+
import { dirname, join, relative, resolve } from 'node:path';
|
|
15
|
+
import { createPathsMatcher, getTsconfig } from 'get-tsconfig';
|
|
16
|
+
import { parseSync } from 'oxc-parser';
|
|
17
|
+
/** Files that never run in a test environment, even inside a process's sources. */
|
|
18
|
+
export const NOT_RUNTIME = [
|
|
19
|
+
/\.md$/,
|
|
20
|
+
/\.spec\.tsx?$/,
|
|
21
|
+
/\.stories\.tsx$/,
|
|
22
|
+
/(^|\/)\.storybook\//,
|
|
23
|
+
/(^|\/)\.oxlintrc\.json$/,
|
|
24
|
+
];
|
|
25
|
+
export const isRuntime = (path) => !NOT_RUNTIME.some((pattern) => pattern.test(path));
|
|
26
|
+
const isNode = (value) => typeof value === 'object' &&
|
|
27
|
+
value !== null &&
|
|
28
|
+
typeof value.type === 'string';
|
|
29
|
+
/** Every node under `root`, depth first. */
|
|
30
|
+
function* nodesOf(root) {
|
|
31
|
+
if (Array.isArray(root)) {
|
|
32
|
+
for (const item of root)
|
|
33
|
+
yield* nodesOf(item);
|
|
34
|
+
return;
|
|
35
|
+
}
|
|
36
|
+
if (!isNode(root))
|
|
37
|
+
return;
|
|
38
|
+
yield root;
|
|
39
|
+
for (const value of Object.values(root))
|
|
40
|
+
yield* nodesOf(value);
|
|
41
|
+
}
|
|
42
|
+
const keyOf = (property) => {
|
|
43
|
+
const key = property.key;
|
|
44
|
+
if (!isNode(key))
|
|
45
|
+
return undefined;
|
|
46
|
+
if (key.type === 'Identifier')
|
|
47
|
+
return key.name;
|
|
48
|
+
return typeof key.value === 'string' ? key.value : undefined;
|
|
49
|
+
};
|
|
50
|
+
const stringOf = (node) => isNode(node) && node.type === 'Literal' && typeof node.value === 'string'
|
|
51
|
+
? node.value
|
|
52
|
+
: undefined;
|
|
53
|
+
const parse = (file, text) => {
|
|
54
|
+
const result = parseSync(file, text);
|
|
55
|
+
if (result.errors.length > 0)
|
|
56
|
+
throw new Error(`${file} does not parse: ${result.errors.map((error) => error.message).join('; ')}`);
|
|
57
|
+
return result;
|
|
58
|
+
};
|
|
59
|
+
export const pathIn = (layout, absolute) => {
|
|
60
|
+
const inside = relative(layout.target, absolute);
|
|
61
|
+
return inside.startsWith('..')
|
|
62
|
+
? `/${relative(layout.repository, absolute)}`
|
|
63
|
+
: inside;
|
|
64
|
+
};
|
|
65
|
+
const absoluteOf = (layout, path) => path.startsWith('/')
|
|
66
|
+
? join(layout.repository, path)
|
|
67
|
+
: join(layout.target, path);
|
|
68
|
+
const fileAt = (base) => ['', '.ts', '.tsx', '/index.ts', '/index.tsx']
|
|
69
|
+
.map((suffix) => base + suffix)
|
|
70
|
+
.find((path) => existsSync(path) && statSync(path).isFile());
|
|
71
|
+
const requestsOf = (file) => {
|
|
72
|
+
const text = readFileSync(file, 'utf8');
|
|
73
|
+
const { module } = parse(file, text);
|
|
74
|
+
return [
|
|
75
|
+
...module.staticImports.map((entry) => entry.moduleRequest.value),
|
|
76
|
+
...module.staticExports.flatMap((entry) => entry.entries.flatMap((exported) => exported.moduleRequest === null ? [] : [exported.moduleRequest.value])),
|
|
77
|
+
...module.dynamicImports.map(({ moduleRequest }) => text.slice(moduleRequest.start + 1, moduleRequest.end - 1)),
|
|
78
|
+
];
|
|
79
|
+
};
|
|
80
|
+
/*
|
|
81
|
+
* Where a request may point by the `paths` of the tsconfig.json nearest the
|
|
82
|
+
* importing file, such as `@/src/db/connection`, the way TypeScript and Vite
|
|
83
|
+
* read them.
|
|
84
|
+
*/
|
|
85
|
+
const aliasesNear = () => {
|
|
86
|
+
const cache = new Map();
|
|
87
|
+
const byDirectory = new Map();
|
|
88
|
+
return (file, request) => {
|
|
89
|
+
const directory = dirname(file);
|
|
90
|
+
if (!byDirectory.has(directory)) {
|
|
91
|
+
const tsconfig = getTsconfig(directory, 'tsconfig.json', cache);
|
|
92
|
+
byDirectory.set(directory, tsconfig === null ? null : createPathsMatcher(tsconfig));
|
|
93
|
+
}
|
|
94
|
+
return byDirectory.get(directory)?.(request) ?? [];
|
|
95
|
+
};
|
|
96
|
+
};
|
|
97
|
+
/** The package a bare request names, as `@acme/ui` for `@acme/ui/button`. */
|
|
98
|
+
const packageNameOf = (request) => request
|
|
99
|
+
.split('/')
|
|
100
|
+
.slice(0, request.startsWith('@') ? 2 : 1)
|
|
101
|
+
.join('/');
|
|
102
|
+
/*
|
|
103
|
+
* Every file the given files import, following relative and aliased imports,
|
|
104
|
+
* and the repository's workspace packages they import, each as its directory.
|
|
105
|
+
*/
|
|
106
|
+
const importedFrom = (layout, starts) => {
|
|
107
|
+
const aliased = aliasesNear();
|
|
108
|
+
const seen = new Set();
|
|
109
|
+
const files = new Set();
|
|
110
|
+
const packages = new Set();
|
|
111
|
+
const queue = [...starts];
|
|
112
|
+
for (let file = queue.pop(); file !== undefined; file = queue.pop()) {
|
|
113
|
+
if (seen.has(file))
|
|
114
|
+
continue;
|
|
115
|
+
seen.add(file);
|
|
116
|
+
files.add(pathIn(layout, file));
|
|
117
|
+
// A JSON or CSS file is reached, but imports nothing itself.
|
|
118
|
+
if (!/\.[cm]?[jt]sx?$/.test(file))
|
|
119
|
+
continue;
|
|
120
|
+
for (const request of requestsOf(file)) {
|
|
121
|
+
const workspace = layout.packages.get(packageNameOf(request));
|
|
122
|
+
if (workspace !== undefined)
|
|
123
|
+
packages.add(workspace);
|
|
124
|
+
const candidates = request.startsWith('.')
|
|
125
|
+
? [resolve(dirname(file), request)]
|
|
126
|
+
: aliased(file, request);
|
|
127
|
+
const target = candidates.map(fileAt).find((path) => path !== undefined);
|
|
128
|
+
if (target !== undefined)
|
|
129
|
+
queue.push(target);
|
|
130
|
+
}
|
|
131
|
+
}
|
|
132
|
+
return { files, packages };
|
|
133
|
+
};
|
|
134
|
+
/**
|
|
135
|
+
* The processes a spec starts: every process of the target, less the ones its
|
|
136
|
+
* one `startTestEnvironment` call leaves out. A spec that does not call it
|
|
137
|
+
* starts none. The list must be written out, so it can be read without
|
|
138
|
+
* running the spec.
|
|
139
|
+
*/
|
|
140
|
+
export const startedBy = (layout, spec) => {
|
|
141
|
+
const file = absoluteOf(layout, spec);
|
|
142
|
+
const { program } = parse(file, readFileSync(file, 'utf8'));
|
|
143
|
+
const calls = [...nodesOf(program)].filter((node) => node.type === 'CallExpression' &&
|
|
144
|
+
isNode(node.callee) &&
|
|
145
|
+
node.callee.type === 'Identifier' &&
|
|
146
|
+
node.callee.name === 'startTestEnvironment');
|
|
147
|
+
if (calls.length === 0)
|
|
148
|
+
return [];
|
|
149
|
+
if (calls.length > 1)
|
|
150
|
+
throw new Error(`${spec} calls startTestEnvironment ${calls.length} times; the selection reads one call.`);
|
|
151
|
+
const [, options] = (calls[0]?.arguments ?? []);
|
|
152
|
+
const all = [...layout.processes.keys()];
|
|
153
|
+
if (options === undefined)
|
|
154
|
+
return all;
|
|
155
|
+
const without = isNode(options)
|
|
156
|
+
? options.properties?.find((property) => keyOf(property) === 'without')
|
|
157
|
+
: undefined;
|
|
158
|
+
if (isNode(options) &&
|
|
159
|
+
options.type === 'ObjectExpression' &&
|
|
160
|
+
without === undefined)
|
|
161
|
+
return all;
|
|
162
|
+
const list = without?.value;
|
|
163
|
+
const names = isNode(list) && list.type === 'ArrayExpression'
|
|
164
|
+
? list.elements.map(stringOf)
|
|
165
|
+
: undefined;
|
|
166
|
+
if (names === undefined || names.some((name) => name === undefined))
|
|
167
|
+
throw new Error(`${spec} passes startTestEnvironment a \`without\` that is not a written-out list of names, so the selection cannot read which processes it starts.`);
|
|
168
|
+
const unknown = names.filter((name) => !all.includes(name ?? ''));
|
|
169
|
+
if (unknown.length > 0)
|
|
170
|
+
throw new Error(`${spec} leaves out ${unknown.join(', ')}, which its target's manifest does not start.`);
|
|
171
|
+
return all.filter((name) => !names.includes(name));
|
|
172
|
+
};
|
|
173
|
+
export const specsIn = (layout) => globSync('**/*.integration.spec.ts', {
|
|
174
|
+
cwd: layout.target,
|
|
175
|
+
exclude: (path) => /(^|\/)node_modules(\/|$)/.test(path),
|
|
176
|
+
}).sort();
|
|
177
|
+
export const graphOf = (layout) => {
|
|
178
|
+
const sourcesImports = new Map();
|
|
179
|
+
const importsUnder = (source) => {
|
|
180
|
+
const known = sourcesImports.get(source);
|
|
181
|
+
if (known !== undefined)
|
|
182
|
+
return known;
|
|
183
|
+
const files = globSync(`${source}/**/*.{ts,tsx,js,mjs}`, {
|
|
184
|
+
cwd: layout.target,
|
|
185
|
+
exclude: (path) => /(^|\/)node_modules(\/|$)/.test(path),
|
|
186
|
+
})
|
|
187
|
+
.filter(isRuntime)
|
|
188
|
+
.map((path) => join(layout.target, path));
|
|
189
|
+
const found = importedFrom(layout, files);
|
|
190
|
+
sourcesImports.set(source, found);
|
|
191
|
+
return found;
|
|
192
|
+
};
|
|
193
|
+
const specs = new Map();
|
|
194
|
+
for (const spec of specsIn(layout)) {
|
|
195
|
+
const files = new Map();
|
|
196
|
+
const directories = new Map();
|
|
197
|
+
const own = importedFrom(layout, [absoluteOf(layout, spec)]);
|
|
198
|
+
for (const file of own.files)
|
|
199
|
+
files.set(file, { kind: 'imports' });
|
|
200
|
+
for (const directory of own.packages)
|
|
201
|
+
directories.set(directory, { kind: 'imports' });
|
|
202
|
+
for (const started of startedBy(layout, spec)) {
|
|
203
|
+
const route = { kind: 'process', process: started };
|
|
204
|
+
for (const source of layout.processes.get(started) ?? []) {
|
|
205
|
+
const directory = `${source.replace(/\/$/, '')}/`;
|
|
206
|
+
if (!directories.has(directory))
|
|
207
|
+
directories.set(directory, route);
|
|
208
|
+
const reached = importsUnder(source);
|
|
209
|
+
for (const file of reached.files)
|
|
210
|
+
if (!files.has(file))
|
|
211
|
+
files.set(file, route);
|
|
212
|
+
for (const pkg of reached.packages)
|
|
213
|
+
if (!directories.has(pkg))
|
|
214
|
+
directories.set(pkg, route);
|
|
215
|
+
}
|
|
216
|
+
}
|
|
217
|
+
specs.set(spec, { files, directories });
|
|
218
|
+
}
|
|
219
|
+
return { specs, shared: layout.shared };
|
|
220
|
+
};
|
|
@@ -0,0 +1,5 @@
|
|
|
1
|
+
export type { Graph, Layout, Reach, Route } from './graph.ts';
|
|
2
|
+
export { graphOf, specsIn, startedBy } from './graph.ts';
|
|
3
|
+
export { layoutOf, TARGET_SHARED } from './layout.ts';
|
|
4
|
+
export type { Selection, SpecLists } from './select.ts';
|
|
5
|
+
export { forPullRequest, selectSpecs } from './select.ts';
|