@smoothbricks/nx-plugin 0.4.10 → 0.4.12

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.
@@ -0,0 +1,199 @@
1
+ import { describe, expect, it } from 'bun:test';
2
+ import { createHash } from 'node:crypto';
3
+ import { mkdir, mkdtemp, rename, rm, writeFile } from 'node:fs/promises';
4
+ import { tmpdir } from 'node:os';
5
+ import { dirname, join } from 'node:path';
6
+
7
+ import { hashVersionlessCrateManifests, updateVersionlessCrateManifest } from './manifest-hash.js';
8
+
9
+ const CRATE_MANIFEST = `[package]
10
+ name = "acme-core"
11
+ version = "1.2.3"
12
+ edition = "2024"
13
+
14
+ [dependencies]
15
+ serde = { version = "1.0.200", features = ["derive"] }
16
+ acme-sibling = { path = "../sibling", version = "1.2.3" }
17
+ `;
18
+
19
+ /**
20
+ * The line a form writes the crate's own version on, and the manifest it sits
21
+ * in. Dropping it must leave the digest exactly where hashing the manifest
22
+ * with it leaves it: that is what "the release cannot move this digest" means.
23
+ */
24
+ const OWN_VERSION_FORMS: Record<string, [manifest: string, line: string]> = {
25
+ plain: ['[package]\nname = "acme-core"\n@\nedition = "2024"\n', 'version = "1.2.3"'],
26
+ padded: ['[package]\nname = "acme-core"\n@\nedition = "2024"\n', ' version\t= "1.2.3" '],
27
+ commented: ['[package]\nname = "acme-core"\n@\nedition = "2024"\n', 'version = "1.2.3" # bumped by the release'],
28
+ inherited: ['[package]\nname = "acme-core"\n@\nedition = "2024"\n', 'version.workspace = true'],
29
+ 'inherited, spaced': ['[package]\nname = "acme-core"\n@\n', 'version . workspace = true'],
30
+ 'quoted key': ['[package]\nname = "acme-core"\n@\n', '"version" = "1.2.3"'],
31
+ 'literal-quoted key': ['[package]\nname = "acme-core"\n@\n', "'version' = '1.2.3'"],
32
+ 'literal-quoted value': ['[package]\nname = "acme-core"\n@\n', "version = '1.2.3'"],
33
+ 'padded header': ['[ package ]\nname = "acme-core"\n@\n', 'version = "1.2.3"'],
34
+ 'commented header': ['[package] # the crate itself\nname = "acme-core"\n@\n', 'version = "1.2.3"'],
35
+ 'quoted header': ['["package"]\nname = "acme-core"\n@\n', 'version = "1.2.3"'],
36
+ 'workspace package': [
37
+ '[workspace]\nmembers = ["crates/*"]\n\n[workspace.package]\n@\nedition = "2024"\n',
38
+ 'version = "0.0.1"',
39
+ ],
40
+ 'workspace package, spaced header': ['[workspace . package]\n@\nedition = "2024"\n', 'version = "0.0.1"'],
41
+ 'after a multi-line array': [
42
+ '[package]\nname = "acme-core"\nkeywords = [\n "build",\n "cache",\n]\n@\n',
43
+ 'version = "1.2.3"',
44
+ ],
45
+ crlf: ['[package]\r\nname = "acme-core"\r\n@\r\nedition = "2024"\r\n', 'version = "1.2.3"'],
46
+ };
47
+
48
+ /**
49
+ * A `version` that names a DIFFERENT crate. Dropping one of these lines must
50
+ * move the digest, or a dependency change serves a stale result.
51
+ */
52
+ const FOREIGN_VERSION_FORMS: Record<string, [manifest: string, line: string]> = {
53
+ 'dependency table': [
54
+ '[package]\nname = "acme-core"\nversion = "1.2.3"\n\n[dependencies.serde]\n@\n',
55
+ 'version = "1.0.200"',
56
+ ],
57
+ 'dev-dependency table': ['[package]\nname = "acme-core"\n\n[dev-dependencies.insta]\n@\n', 'version = "1.39"'],
58
+ 'build-dependency table': ['[package]\nname = "acme-core"\n\n[build-dependencies.cc]\n@\n', 'version = "1.0"'],
59
+ 'workspace dependency table': ['[workspace]\n\n[workspace.dependencies.serde]\n@\n', 'version = "1.0.200"'],
60
+ 'target cfg dependency table': [
61
+ '[package]\nname = "acme-core"\n\n[target.\'cfg(unix)\'.dependencies.libc]\n@\n',
62
+ 'version = "0.2.155"',
63
+ ],
64
+ 'inline table': ['[package]\nname = "acme-core"\n\n[dependencies]\n@\n', 'serde = { version = "1.0.200" }'],
65
+ 'package metadata table': ['[package]\nname = "acme-core"\n\n[package.metadata.acme]\n@\n', 'version = "7"'],
66
+ };
67
+
68
+ function digest(manifest: string): string {
69
+ const hash = createHash('sha256');
70
+ updateVersionlessCrateManifest(hash, Buffer.from(manifest));
71
+ return hash.digest('hex');
72
+ }
73
+
74
+ /**
75
+ * Whether each form's version line contributes nothing at all to the digest:
76
+ * the manifest carrying it hashes to what the manifest without it hashes to.
77
+ */
78
+ function elided(forms: Record<string, [manifest: string, line: string]>): Record<string, boolean> {
79
+ const result: Record<string, boolean> = {};
80
+ for (const [name, [manifest, line]] of Object.entries(forms)) {
81
+ result[name] = digest(manifest.replace('@', line)) === digest(manifest.replace(/@\r?\n/, ''));
82
+ }
83
+ return result;
84
+ }
85
+
86
+ describe('versionless crate manifest hashing', () => {
87
+ it('drops the version a crate declares for itself, in every form a manifest writes it', () => {
88
+ expect(elided(OWN_VERSION_FORMS)).toEqual(Object.fromEntries(Object.keys(OWN_VERSION_FORMS).map((n) => [n, true])));
89
+ });
90
+
91
+ it('keeps every version that names a different crate', () => {
92
+ expect(elided(FOREIGN_VERSION_FORMS)).toEqual(
93
+ Object.fromEntries(Object.keys(FOREIGN_VERSION_FORMS).map((n) => [n, false])),
94
+ );
95
+ });
96
+
97
+ it("separates the tables it left, so a later version is not read as the crate's own", () => {
98
+ const own = '[package]\nname = "acme-core"\nversion = "1.2.3"\n';
99
+ // The same bytes under a dependency table must not collapse onto the same
100
+ // digest as the crate's own version: the scanner has to know which table
101
+ // it is standing in, not just which line it is looking at.
102
+ expect(digest(`${own}\n[dependencies.serde]\nversion = "1.0.200"\n`)).not.toBe(
103
+ digest(`${own}\n[dependencies.serde]\nversion = "1.0.201"\n`),
104
+ );
105
+ });
106
+
107
+ it('hashes verbatim from the first construct a line scan cannot read', () => {
108
+ // A multi-line string can spell out a `[package]` header and a version
109
+ // line, and no line scan can tell that text from the document. Everything
110
+ // after one is hashed as written, so the release moves this digest — a
111
+ // miss, never a wrong hit.
112
+ const withNote = (version: string) =>
113
+ `[package]\nname = "acme-core"\ndescription = """\n[package]\nversion = "0.0.0"\n"""\nversion = "${version}"\n`;
114
+ expect(digest(withNote('1.2.3'))).not.toBe(digest(withNote('2.0.0')));
115
+
116
+ // A version the scanner reached BEFORE the string is still dropped.
117
+ const beforeNote = (version: string) =>
118
+ `[package]\nname = "acme-core"\nversion = "${version}"\ndescription = """\nany text\n"""\n`;
119
+ expect(digest(beforeNote('1.2.3'))).toBe(digest(beforeNote('2.0.0')));
120
+ });
121
+
122
+ it('ignores the version a crate declares for itself and nothing else', async () => {
123
+ await withProject(async (project) => {
124
+ const baseline = await hashVersionlessCrateManifests(project.root, project.workspaceRoot);
125
+
126
+ await project.write('crates/core/Cargo.toml', CRATE_MANIFEST.replace('version = "1.2.3"', 'version = "2.0.0"'));
127
+ expect(await hashVersionlessCrateManifests(project.root, project.workspaceRoot)).toBe(baseline);
128
+
129
+ // Same release, one real change alongside it: the digest must move again.
130
+ await project.write('crates/core/Cargo.toml', CRATE_MANIFEST.replace('1.0.200', '1.0.201'));
131
+ expect(await hashVersionlessCrateManifests(project.root, project.workspaceRoot)).not.toBe(baseline);
132
+ });
133
+ });
134
+
135
+ it('reports a moved crate manifest', async () => {
136
+ await withProject(async (project) => {
137
+ const baseline = await hashVersionlessCrateManifests(project.root, project.workspaceRoot);
138
+ await project.move('crates/core/Cargo.toml', 'crates/renamed/Cargo.toml');
139
+
140
+ expect(await hashVersionlessCrateManifests(project.root, project.workspaceRoot)).not.toBe(baseline);
141
+ });
142
+ });
143
+
144
+ it('hashes a manifest it cannot read instead of dropping it', async () => {
145
+ await withProject(async (project) => {
146
+ await project.write('crates/core/Cargo.toml', 'this is not toml [[[');
147
+ const broken = await hashVersionlessCrateManifests(project.root, project.workspaceRoot);
148
+ expect(await hashVersionlessCrateManifests(project.root, project.workspaceRoot)).toBe(broken);
149
+
150
+ // An unreadable manifest still contributes its bytes, so a change inside
151
+ // it invalidates. Dropping it would leave a stale cache hit instead.
152
+ await project.write('crates/core/Cargo.toml', 'this is not toml either ]]]');
153
+ expect(await hashVersionlessCrateManifests(project.root, project.workspaceRoot)).not.toBe(broken);
154
+ });
155
+ });
156
+
157
+ it('hashes the same tree the same way twice', async () => {
158
+ await withProject(async (project) => {
159
+ expect(await hashVersionlessCrateManifests(project.root, project.workspaceRoot)).toMatch(/^[0-9a-f]{64}$/);
160
+ expect(await hashVersionlessCrateManifests(project.root, project.workspaceRoot)).toBe(
161
+ await hashVersionlessCrateManifests(project.root, project.workspaceRoot),
162
+ );
163
+ });
164
+ });
165
+ });
166
+
167
+ interface ProjectFixture {
168
+ workspaceRoot: string;
169
+ root: string;
170
+ write(path: string, contents: string): Promise<void>;
171
+ move(from: string, to: string): Promise<void>;
172
+ }
173
+
174
+ async function withProject(body: (project: ProjectFixture) => Promise<void>): Promise<void> {
175
+ const workspaceRoot = await mkdtemp(join(tmpdir(), 'smoothbricks-manifest-hash-'));
176
+ const root = 'packages/app';
177
+ const write = async (path: string, contents: string): Promise<void> => {
178
+ const absolute = join(workspaceRoot, path);
179
+ await mkdir(dirname(absolute), { recursive: true });
180
+ await writeFile(absolute, contents);
181
+ };
182
+ try {
183
+ await write(join(root, 'package.json'), JSON.stringify({ name: '@acme/app', version: '1.2.3' }));
184
+ await write(join(root, 'crates/core/Cargo.toml'), CRATE_MANIFEST);
185
+ await write(join(root, 'src/index.ts'), 'export const answer = 42;\n');
186
+ await body({
187
+ workspaceRoot,
188
+ root,
189
+ write: async (path, contents) => write(join(root, path), contents),
190
+ move: async (from, to) => {
191
+ const target = join(workspaceRoot, root, to);
192
+ await mkdir(dirname(target), { recursive: true });
193
+ await rename(join(workspaceRoot, root, from), target);
194
+ },
195
+ });
196
+ } finally {
197
+ await rm(workspaceRoot, { recursive: true, force: true });
198
+ }
199
+ }
@@ -0,0 +1,335 @@
1
+ import { createHash, type Hash } from 'node:crypto';
2
+ import { readdir, readFile } from 'node:fs/promises';
3
+ import { join, sep } from 'node:path';
4
+
5
+ import { isNonSourceDirectory } from './source-directories.js';
6
+
7
+ /**
8
+ * A release rewrites `version` in every manifest it publishes. Those manifests
9
+ * are inputs of the validation targets, so a publish run misses the cache for
10
+ * the whole gate set over a change that alters no code.
11
+ *
12
+ * Nx hashes JSON manifests with the version removed natively, through a `json`
13
+ * input with `excludeFields` — no process, and the file hashing stays in the
14
+ * native hasher. TOML has no such input, so crate manifests are the one
15
+ * remaining case the plugin computes itself, and this module is only that
16
+ * case. It runs inside `createNodes`, which already reads these manifests, and
17
+ * the digest it returns rides into the project's named inputs as a literal —
18
+ * Nx hashes a project's `namedInputs` definitions as part of the project
19
+ * configuration, so no process and no `runtime` carrier is needed to get the
20
+ * value into the task hash.
21
+ *
22
+ * This treatment belongs to checks that READ source, never to a target that
23
+ * produces a shipped artifact. A crate embeds its version at compile time
24
+ * through `env!("CARGO_PKG_VERSION")`, so a version-insensitive build hash
25
+ * would let a post-bump build hit a pre-bump artifact and ship a binary
26
+ * reporting the previous version — silent, and worse than the cache miss it
27
+ * saves.
28
+ *
29
+ * Every fallback here over-invalidates rather than under-invalidates. A
30
+ * manifest excluded from a fileset with no digest replacing it serves stale
31
+ * results in silence, so nothing in this module drops bytes it is unsure
32
+ * about: what it cannot read line by line, it hashes verbatim.
33
+ */
34
+ const DIGEST_TAG = 'versionless-crate-manifests-v2';
35
+
36
+ const CARGO_MANIFEST = 'Cargo.toml';
37
+
38
+ /** Frames the parts of the digest, so no path can spell out another part's content. */
39
+ const SEPARATOR = Buffer.of(0);
40
+
41
+ /** The ASCII the scanner steers by. Cargo manifests are UTF-8, whose non-ASCII bytes are all >= 0x80. */
42
+ const TAB = 0x09;
43
+ const LINE_FEED = 0x0a;
44
+ const CARRIAGE_RETURN = 0x0d;
45
+ const SPACE = 0x20;
46
+ const QUOTATION_MARK = 0x22;
47
+ const NUMBER_SIGN = 0x23;
48
+ const HYPHEN = 0x2d;
49
+ const FULL_STOP = 0x2e;
50
+ const DIGIT_ZERO = 0x30;
51
+ const DIGIT_NINE = 0x39;
52
+ const EQUALS_SIGN = 0x3d;
53
+ const UPPER_A = 0x41;
54
+ const UPPER_Z = 0x5a;
55
+ const LEFT_SQUARE_BRACKET = 0x5b;
56
+ const REVERSE_SOLIDUS = 0x5c;
57
+ const RIGHT_SQUARE_BRACKET = 0x5d;
58
+ const LOW_LINE = 0x5f;
59
+ const LOWER_A = 0x61;
60
+ const LOWER_Z = 0x7a;
61
+ const LEFT_CURLY_BRACKET = 0x7b;
62
+ const RIGHT_CURLY_BRACKET = 0x7d;
63
+ const APOSTROPHE = 0x27;
64
+
65
+ const PACKAGE = 'package';
66
+ const WORKSPACE = 'workspace';
67
+ const VERSION = 'version';
68
+
69
+ /**
70
+ * Feed one crate manifest to `hash` without the versions the crate declares
71
+ * for itself.
72
+ *
73
+ * A forward scan over the bytes that hands the runs it keeps straight to the
74
+ * hasher as views: the manifest is never parsed into objects, never
75
+ * re-serialised, and never copied. `[package].version` and the
76
+ * `[workspace.package].version` that members inherit are the crate's own and
77
+ * go whole — trailing comment and newline included. A `version` under a
78
+ * dependency table, a `[target.'cfg(…)'.dependencies]` table or an inline
79
+ * table names a DIFFERENT crate and stays: dropping it would let a genuinely
80
+ * different dependency serve a stale result.
81
+ *
82
+ * Some of TOML is out of reach of a line-oriented scan. A multi-line basic or
83
+ * literal string can hold anything at all, a `[package]` header and a
84
+ * `version = "…"` line included, and no scan that has not lexed the whole
85
+ * document can tell that text from the document. So from the first `"""` or
86
+ * `'''`, from an unterminated value, and from any line it cannot classify,
87
+ * this elides nothing more and hashes the rest of the manifest verbatim. That
88
+ * direction is the safe one: hashing too much costs a cache miss on release,
89
+ * hashing too little serves a wrong result.
90
+ */
91
+ export function updateVersionlessCrateManifest(hash: Hash, manifest: Buffer): void {
92
+ const end = manifest.length;
93
+ // Bytes scanned but not yet handed over. Only an elision advances this past
94
+ // a line, so a manifest with no version at all is fed as one whole view.
95
+ let kept = 0;
96
+ // Whether the keys being read belong to a table whose `version` is the
97
+ // crate's own rather than some dependency's.
98
+ let ownVersionTable = false;
99
+ // Brackets left open by a value that spans lines: `keywords = [` and the
100
+ // lines under it are value, not statements.
101
+ let depth = 0;
102
+ let line = 0;
103
+ while (line < end) {
104
+ const lineFeed = manifest.indexOf(LINE_FEED, line);
105
+ const lineEnd = lineFeed < 0 ? end : lineFeed;
106
+ const nextLine = lineFeed < 0 ? end : lineFeed + 1;
107
+ if (depth > 0) {
108
+ depth = readDepth(manifest, line, lineEnd, depth);
109
+ if (depth < 0) break;
110
+ line = nextLine;
111
+ continue;
112
+ }
113
+ const at = skipBlanks(manifest, line, lineEnd);
114
+ if (at === lineEnd || manifest[at] === NUMBER_SIGN) {
115
+ line = nextLine;
116
+ continue;
117
+ }
118
+ if (manifest[at] === LEFT_SQUARE_BRACKET) {
119
+ // Only a comment may follow a header, so the rest of the line is not
120
+ // scanned: a `"""` inside that comment is not a multi-line string.
121
+ ownVersionTable = isOwnVersionTable(manifest, at + 1, lineEnd);
122
+ line = nextLine;
123
+ continue;
124
+ }
125
+ const equals = readKeyEnd(manifest, at, lineEnd);
126
+ if (equals < 0) break;
127
+ const own = ownVersionTable && isOwnVersionKey(manifest, at, equals);
128
+ depth = readDepth(manifest, equals + 1, lineEnd, 0);
129
+ if (depth < 0) break;
130
+ if (own && depth === 0) {
131
+ hash.update(manifest.subarray(kept, line));
132
+ kept = nextLine;
133
+ }
134
+ line = nextLine;
135
+ }
136
+ hash.update(manifest.subarray(kept, end));
137
+ }
138
+
139
+ /**
140
+ * The digest of every crate manifest under a project, with the versions the
141
+ * crates declare for themselves removed.
142
+ *
143
+ * This is exactly what the validation targets exclude from their filesets.
144
+ * Paths are part of the digest, so moving a crate is a change even when no
145
+ * manifest body differs. A project with no crate manifest never declares this
146
+ * input at all, so the empty digest is not a case that reaches Nx.
147
+ *
148
+ * A crate that pins a workspace sibling by `path` + `version` still carries
149
+ * that sibling's version, so a release does invalidate it. That is the honest
150
+ * answer: the dependency the digest describes really did change.
151
+ */
152
+ export async function hashVersionlessCrateManifests(projectRoot: string, workspaceRoot: string): Promise<string> {
153
+ const root = join(workspaceRoot, projectRoot);
154
+ const paths: string[] = [];
155
+ await collectCrateManifests(root, '', paths);
156
+ paths.sort();
157
+ const manifests = await Promise.all(paths.map((path) => readFile(join(root, path))));
158
+ const hash = createHash('sha256');
159
+ hash.update(DIGEST_TAG);
160
+ hash.update(SEPARATOR);
161
+ for (let index = 0; index < paths.length; index++) {
162
+ hash.update(paths[index] as string);
163
+ hash.update(SEPARATOR);
164
+ updateVersionlessCrateManifest(hash, manifests[index] as Buffer);
165
+ hash.update(SEPARATOR);
166
+ }
167
+ return hash.digest('hex');
168
+ }
169
+
170
+ /** Collects manifest paths relative to the project root, `/`-separated so the digest is platform-independent. */
171
+ async function collectCrateManifests(directory: string, prefix: string, found: string[]): Promise<void> {
172
+ // No `catch`: an unreadable directory would otherwise hash as an empty
173
+ // manifest set, which is the silent-staleness failure this module exists to
174
+ // avoid. The caller degrades to the raw manifests instead. Symlinked
175
+ // directories are not entries `isDirectory` reports, so the walk cannot loop
176
+ // and matches what Nx keeps in its file map.
177
+ for (const entry of await readdir(directory, { withFileTypes: true })) {
178
+ if (entry.isDirectory()) {
179
+ // The exclusions every source walk in this plugin uses, so the digest
180
+ // covers the same files Nx keeps in its file map.
181
+ if (!isNonSourceDirectory(entry.name)) {
182
+ await collectCrateManifests(`${directory}${sep}${entry.name}`, `${prefix}${entry.name}/`, found);
183
+ }
184
+ } else if (entry.name === CARGO_MANIFEST) {
185
+ found.push(`${prefix}${entry.name}`);
186
+ }
187
+ }
188
+ }
189
+
190
+ /** `from` is just past the `[`. */
191
+ function isOwnVersionTable(manifest: Buffer, from: number, to: number): boolean {
192
+ // `[[bin]]` and every other array of tables: a crate's own version is never
193
+ // declared in one.
194
+ if (manifest[from] === LEFT_SQUARE_BRACKET) return false;
195
+ let after = readWord(manifest, from, to, PACKAGE);
196
+ if (after < 0) {
197
+ const afterWorkspace = readWord(manifest, from, to, WORKSPACE);
198
+ if (afterWorkspace < 0) return false;
199
+ const dot = skipBlanks(manifest, afterWorkspace, to);
200
+ if (dot >= to || manifest[dot] !== FULL_STOP) return false;
201
+ after = readWord(manifest, dot + 1, to, PACKAGE);
202
+ if (after < 0) return false;
203
+ }
204
+ // The path has to END here: `[package.metadata]` is a different table, and
205
+ // the version under it is not the crate's.
206
+ const close = skipBlanks(manifest, after, to);
207
+ return close < to && manifest[close] === RIGHT_SQUARE_BRACKET;
208
+ }
209
+
210
+ /** `to` is the offset of the `=`, so the key path must end exactly there. */
211
+ function isOwnVersionKey(manifest: Buffer, from: number, to: number): boolean {
212
+ const afterVersion = readWord(manifest, from, to, VERSION);
213
+ if (afterVersion < 0) return false;
214
+ const dot = skipBlanks(manifest, afterVersion, to);
215
+ if (dot === to) return true;
216
+ if (manifest[dot] !== FULL_STOP) return false;
217
+ // `version.workspace = true` inherits the version, so it is the same field.
218
+ const afterWorkspace = readWord(manifest, dot + 1, to, WORKSPACE);
219
+ return afterWorkspace >= 0 && skipBlanks(manifest, afterWorkspace, to) === to;
220
+ }
221
+
222
+ /**
223
+ * Offset just past `word` written bare, `"quoted"` or `'quoted'`, or -1.
224
+ *
225
+ * A quoted key that spells the word with an escape (`"pack\u0061ge"`) does not
226
+ * match: decoding it would mean carrying a decoder, and not matching only
227
+ * keeps bytes the digest could have dropped.
228
+ */
229
+ function readWord(manifest: Buffer, from: number, to: number, word: string): number {
230
+ const at = skipBlanks(manifest, from, to);
231
+ const quote = manifest[at] as number;
232
+ const quoted = quote === QUOTATION_MARK || quote === APOSTROPHE;
233
+ const start = quoted ? at + 1 : at;
234
+ const stop = start + word.length;
235
+ if (stop > to) return -1;
236
+ for (let index = 0; index < word.length; index++) {
237
+ if (manifest[start + index] !== word.charCodeAt(index)) return -1;
238
+ }
239
+ if (quoted) return manifest[stop] === quote ? stop + 1 : -1;
240
+ // A bare key runs on: `versioning` is not `version`.
241
+ return stop === to || !isBareKeyByte(manifest[stop] as number) ? stop : -1;
242
+ }
243
+
244
+ /** Offset of the `=` that closes this line's key path, or -1 when the line is not one. */
245
+ function readKeyEnd(manifest: Buffer, from: number, to: number): number {
246
+ let at = from;
247
+ for (;;) {
248
+ at = readKeySegment(manifest, at, to);
249
+ if (at < 0) return -1;
250
+ at = skipBlanks(manifest, at, to);
251
+ if (at >= to) return -1;
252
+ const byte = manifest[at];
253
+ if (byte === EQUALS_SIGN) return at;
254
+ if (byte !== FULL_STOP) return -1;
255
+ at++;
256
+ }
257
+ }
258
+
259
+ /** Offset just past one key segment — bare, `"quoted"` or `'quoted'` — or -1. */
260
+ function readKeySegment(manifest: Buffer, from: number, to: number): number {
261
+ const at = skipBlanks(manifest, from, to);
262
+ if (at >= to) return -1;
263
+ const byte = manifest[at];
264
+ if (byte === QUOTATION_MARK || byte === APOSTROPHE) return readStringEnd(manifest, at, to);
265
+ let stop = at;
266
+ while (stop < to && isBareKeyByte(manifest[stop] as number)) stop++;
267
+ return stop === at ? -1 : stop;
268
+ }
269
+
270
+ /**
271
+ * Bracket depth still open at the end of a value or of the line continuing
272
+ * one, or -1 when the scan must stop: a multi-line string opens, a string
273
+ * never closes, or a bracket closes one that never opened.
274
+ */
275
+ function readDepth(manifest: Buffer, from: number, to: number, depth: number): number {
276
+ let open = depth;
277
+ let at = from;
278
+ while (at < to) {
279
+ const byte = manifest[at] as number;
280
+ // A comment runs to the end of the line and cannot open anything.
281
+ if (byte === NUMBER_SIGN) return open;
282
+ if (byte === QUOTATION_MARK || byte === APOSTROPHE) {
283
+ if (manifest[at + 1] === byte && manifest[at + 2] === byte) return -1;
284
+ at = readStringEnd(manifest, at, to);
285
+ if (at < 0) return -1;
286
+ continue;
287
+ }
288
+ if (byte === LEFT_SQUARE_BRACKET || byte === LEFT_CURLY_BRACKET) {
289
+ open++;
290
+ } else if (byte === RIGHT_SQUARE_BRACKET || byte === RIGHT_CURLY_BRACKET) {
291
+ open--;
292
+ if (open < 0) return -1;
293
+ }
294
+ at++;
295
+ }
296
+ return open;
297
+ }
298
+
299
+ /** `from` is the opening quote. Offset just past the closing one, or -1 when the line ends first. */
300
+ function readStringEnd(manifest: Buffer, from: number, to: number): number {
301
+ const quote = manifest[from];
302
+ let at = from + 1;
303
+ while (at < to) {
304
+ const byte = manifest[at];
305
+ // A literal string has no escapes: `'a\'` closes at that quote.
306
+ if (byte === REVERSE_SOLIDUS && quote === QUOTATION_MARK) {
307
+ at += 2;
308
+ continue;
309
+ }
310
+ if (byte === quote) return at + 1;
311
+ at++;
312
+ }
313
+ return -1;
314
+ }
315
+
316
+ /** Whitespace between tokens. A `\r` only ever precedes the `\n` a line was split on. */
317
+ function skipBlanks(manifest: Buffer, from: number, to: number): number {
318
+ let at = from;
319
+ while (at < to) {
320
+ const byte = manifest[at];
321
+ if (byte !== SPACE && byte !== TAB && byte !== CARRIAGE_RETURN) break;
322
+ at++;
323
+ }
324
+ return at;
325
+ }
326
+
327
+ function isBareKeyByte(byte: number): boolean {
328
+ return (
329
+ (byte >= LOWER_A && byte <= LOWER_Z) ||
330
+ (byte >= UPPER_A && byte <= UPPER_Z) ||
331
+ (byte >= DIGIT_ZERO && byte <= DIGIT_NINE) ||
332
+ byte === LOW_LINE ||
333
+ byte === HYPHEN
334
+ );
335
+ }
@@ -518,6 +518,42 @@ describe('typecheck test policy (Tree)', () => {
518
518
  // ---------------------------------------------------------------------------
519
519
 
520
520
  describe('typecheck test policy', () => {
521
+ it('reads a documented tsconfig.test.json instead of treating it as absent', async () => {
522
+ // tsconfig files are JSONC: TypeScript permits comments. A plain
523
+ // JSON.parse failed, the reader answered "absent", and the policy
524
+ // regenerated the file — deleting a declared `lib`, an `exclude`, extra
525
+ // `include` globs and every comment explaining them. That is how a
526
+ // Bun-only test program loses es2023 and `toSorted` becomes a type error.
527
+ const root = await mkdtemp(join(tmpdir(), 'smoo-typecheck-test-jsonc-'));
528
+ try {
529
+ await writeJsonFs(join(root, 'package.json'), { workspaces: ['packages/*'] });
530
+ await writeJsonFs(join(root, 'packages/app/package.json'), {
531
+ name: '@scope/app',
532
+ scripts: { test: 'bun test' },
533
+ });
534
+ await mkdir(join(root, 'packages/app'), { recursive: true });
535
+ const documented = [
536
+ '{',
537
+ ' "extends": "../../tsconfig.base.json",',
538
+ ' // WHY es2023: this program is Bun-only and JSC has change-array-by-copy.',
539
+ ' "compilerOptions": { "lib": ["es2023"], "types": ["bun"], "noEmit": true, "composite": false,',
540
+ ' "declaration": false, "declarationMap": false, "emitDeclarationOnly": false },',
541
+ ' "include": ["src/**/*.test.ts", "src/**/*.spec.ts", "src/**/__tests__/**/*.ts",',
542
+ ' "src/**/__tests__/**/*.tsx", "src/test-suite-tracer.ts", "tests/**/*.ts"],',
543
+ ' "exclude": ["src/lib/ts-plugin.ts"]',
544
+ '}',
545
+ '',
546
+ ].join('\n');
547
+ await writeFile(join(root, 'packages/app/tsconfig.test.json'), documented);
548
+
549
+ // Nothing the policy wants is missing, so it must not rewrite the file.
550
+ expect(applyTypecheckTestPolicy(root)).toBe(false);
551
+ expect(await readFile(join(root, 'packages/app/tsconfig.test.json'), 'utf8')).toBe(documented);
552
+ } finally {
553
+ await rm(root, { recursive: true, force: true });
554
+ }
555
+ });
556
+
521
557
  it('creates tsconfig.test.json for bun test package', async () => {
522
558
  const root = await mkdtemp(join(tmpdir(), 'smoo-typecheck-test-policy-'));
523
559
  try {
@@ -459,6 +459,16 @@ export function applyTypecheckTestPolicy(root: string): boolean {
459
459
  }) || fileChanged;
460
460
 
461
461
  if (fileChanged) {
462
+ // A documented tsconfig cannot survive JSON.stringify, so the policy says
463
+ // what it wants instead of quietly deleting the reasoning. The check
464
+ // half (checkTypecheckTestPolicy) reports the same drift, so CI still
465
+ // fails until a human applies it.
466
+ if (existsSync(tsconfigTestPath) && hasJsonComments(readFileSync(tsconfigTestPath, 'utf8'))) {
467
+ console.error(
468
+ `refused ${packagePath}/tsconfig.test.json carries comments a rewrite would delete; apply the policy by hand`,
469
+ );
470
+ continue;
471
+ }
462
472
  writeJsonObjectFs(tsconfigTestPath, tsconfigTest);
463
473
  changed = true;
464
474
  }
@@ -688,16 +698,80 @@ function collectTsconfigTestReferencePaths(
688
698
  return paths;
689
699
  }
690
700
 
701
+ /**
702
+ * Read a tsconfig or package.json. tsconfig files are JSONC — TypeScript
703
+ * permits comments and trailing commas — so a plain `JSON.parse` fails on a
704
+ * documented one. Returning null there meant "file absent", and the caller
705
+ * regenerated it from scratch: a `lib` the test program declared, an
706
+ * `exclude`, an extra `include` glob and every comment explaining them
707
+ * disappeared on the next `smoo monorepo update`. Comments are stripped for
708
+ * parsing only; a caller that intends to write back must decide what to do
709
+ * about them (see writeJsonObjectFs's caller).
710
+ */
691
711
  function readJsonObject(path: string): Record<string, unknown> | null {
692
712
  if (!existsSync(path)) {
693
713
  return null;
694
714
  }
715
+ const text = readFileSync(path, 'utf8');
695
716
  try {
696
- const parsed: unknown = JSON.parse(readFileSync(path, 'utf8'));
717
+ const parsed: unknown = JSON.parse(stripJsonComments(text));
697
718
  return isRecord(parsed) ? parsed : null;
698
- } catch {
699
- return null;
719
+ } catch (error) {
720
+ // A file that exists but cannot be parsed is a configuration error, not an
721
+ // invitation to overwrite it.
722
+ throw new Error(`${path} is not valid JSON/JSONC: ${error instanceof Error ? error.message : String(error)}`);
723
+ }
724
+ }
725
+
726
+ /** Whether the file carries comments a rewrite would destroy. */
727
+ function hasJsonComments(text: string): boolean {
728
+ return stripJsonComments(text) !== text;
729
+ }
730
+
731
+ /**
732
+ * Remove `//` and block comments outside string literals, and trailing commas.
733
+ * Small on purpose: the alternative is a JSONC dependency in a plugin whose
734
+ * only JSONC inputs are tsconfig files.
735
+ */
736
+ function stripJsonComments(text: string): string {
737
+ let output = '';
738
+ let inString = false;
739
+ let escaped = false;
740
+ let index = 0;
741
+ while (index < text.length) {
742
+ const char = text[index];
743
+ if (inString) {
744
+ output += char;
745
+ if (escaped) {
746
+ escaped = false;
747
+ } else if (char === '\\') {
748
+ escaped = true;
749
+ } else if (char === '"') {
750
+ inString = false;
751
+ }
752
+ index += 1;
753
+ continue;
754
+ }
755
+ if (char === '"') {
756
+ inString = true;
757
+ output += char;
758
+ index += 1;
759
+ continue;
760
+ }
761
+ if (char === '/' && text[index + 1] === '/') {
762
+ while (index < text.length && text[index] !== '\n') index += 1;
763
+ continue;
764
+ }
765
+ if (char === '/' && text[index + 1] === '*') {
766
+ index += 2;
767
+ while (index < text.length && !(text[index] === '*' && text[index + 1] === '/')) index += 1;
768
+ index += 2;
769
+ continue;
770
+ }
771
+ output += char;
772
+ index += 1;
700
773
  }
774
+ return output.replace(/,(\s*[}\]])/g, '$1');
701
775
  }
702
776
 
703
777
  function writeJsonObjectFs(path: string, value: Record<string, unknown>): void {