fixdevcontainer 1.3.132 → 1.3.134
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/CLAUDE.md +77 -0
- package/package.json +1 -1
package/CLAUDE.md
ADDED
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
# CLAUDE.md
|
|
2
|
+
|
|
3
|
+
## Overview
|
|
4
|
+
|
|
5
|
+
`fixdevcontainer` is a zero-dependency CLI that sorts the top-level keys of a
|
|
6
|
+
`devcontainer.json` file into a fixed, human-friendly category order (basic info,
|
|
7
|
+
container image, operational settings, ports, features, lifecycle commands, etc.).
|
|
8
|
+
It is published to npm and typically run with `npx fixdevcontainer`. Unknown keys
|
|
9
|
+
are preserved and appended alphabetically at the end with a warning.
|
|
10
|
+
|
|
11
|
+
## Development commands
|
|
12
|
+
|
|
13
|
+
- `pnpm test`: run the Jest test suite (`fixdevcontainer.test.js`). This is the
|
|
14
|
+
only npm script defined; there is no build step and no lint/format tool
|
|
15
|
+
configured. CI (the reusable `book000/templates` Node CI workflow) runs this
|
|
16
|
+
test plus `npx depcheck`, which is why `.depcheckrc.json` exists (it ignores
|
|
17
|
+
`jest`, which is only referenced via config). Keep dependencies clean so
|
|
18
|
+
`depcheck` stays green.
|
|
19
|
+
- `npx fixdevcontainer [file]`: run the tool. Defaults to
|
|
20
|
+
`.devcontainer/devcontainer.json` when no path is given.
|
|
21
|
+
|
|
22
|
+
Use pnpm (see `packageManager` in `package.json`). Node version is pinned in
|
|
23
|
+
`.node-version`.
|
|
24
|
+
|
|
25
|
+
## Architecture / key files
|
|
26
|
+
|
|
27
|
+
- `fixdevcontainer.js`: the entire implementation. CommonJS, `"use strict"`, with
|
|
28
|
+
a `#!/usr/bin/env node` shebang; it is the package `bin` and `main`.
|
|
29
|
+
- `predefinedOrder`: the ordered array of known keys, grouped by category with
|
|
30
|
+
comments. This array is the heart of the tool.
|
|
31
|
+
- `loadJson(filename)`: reads and parses the file, returning `null` on any error
|
|
32
|
+
(missing file, read error, parse error).
|
|
33
|
+
- `formatter(filename)`: reorders keys per `predefinedOrder`, appends unknown
|
|
34
|
+
keys alphabetically, and writes the result back with `JSON.stringify(obj, null, 2)`.
|
|
35
|
+
Exported via `exports.formatter` for tests; also invoked at module load using
|
|
36
|
+
`process.argv[2]`.
|
|
37
|
+
- `fixdevcontainer.test.js`: Jest tests that mock `node:fs` and the `console`
|
|
38
|
+
methods.
|
|
39
|
+
- `.github/workflows/`: CI (`nodejs-ci-pnpm.yml`) and reviewer assignment
|
|
40
|
+
(`add-reviewer.yml`) reuse `book000/templates` workflows. npm publish
|
|
41
|
+
(`release.yml`) is a standalone workflow that defines its steps inline
|
|
42
|
+
(tag bump via `mathieudutour/github-tag-action`, then `pnpm publish`).
|
|
43
|
+
|
|
44
|
+
## Coding conventions
|
|
45
|
+
|
|
46
|
+
- CommonJS (`require`/`exports`), not ESM. Import Node builtins with the `node:`
|
|
47
|
+
prefix (e.g. `require("node:fs")`).
|
|
48
|
+
- 2-space indentation, double-quoted strings, semicolons — match the existing file.
|
|
49
|
+
- User-facing output uses raw ANSI escape codes: red (`[31m`) for errors via
|
|
50
|
+
`console.error`, yellow (`[33m`) for warnings via `console.warn`, green
|
|
51
|
+
(`[32m`) for success via `console.log`. The tests assert these exact
|
|
52
|
+
strings, so keep the escape sequences and message wording in sync with the tests.
|
|
53
|
+
- On errors, log a message and return early (return `null`/`undefined`); do not
|
|
54
|
+
throw out of `formatter`/`loadJson`.
|
|
55
|
+
|
|
56
|
+
## Adding or changing sorted keys
|
|
57
|
+
|
|
58
|
+
When adding support for a new `devcontainer.json` property, insert it into
|
|
59
|
+
`predefinedOrder` in the appropriate category (keep the section comments accurate).
|
|
60
|
+
Note that `formatter` copies only keys present in `predefinedOrder` into the sorted
|
|
61
|
+
object; any key not listed there is treated as "undefined" and appended
|
|
62
|
+
alphabetically. Update `fixdevcontainer.test.js` to cover the new ordering.
|
|
63
|
+
|
|
64
|
+
## Testing approach
|
|
65
|
+
|
|
66
|
+
Tests mock `node:fs` (`existsSync`/`readFileSync`/`writeFileSync`) and stub
|
|
67
|
+
`console.log`/`warn`/`error`, then assert the arguments passed to `writeFileSync`
|
|
68
|
+
and the console output. There is no real filesystem I/O in tests. Add a case for
|
|
69
|
+
every new behavior rather than relying on manual runs.
|
|
70
|
+
|
|
71
|
+
## Commit / release rules
|
|
72
|
+
|
|
73
|
+
- Commits follow Conventional Commits; descriptions are written in Japanese by
|
|
74
|
+
default (matching the existing history).
|
|
75
|
+
- `release.yml` parses commit prefixes to bump the version and publish to npm:
|
|
76
|
+
`feat` → minor, `fix`/`chore`/`docs`/`refactor`/etc. → patch, `release` → major.
|
|
77
|
+
Choose the prefix deliberately since it drives the released version.
|