@antelopejs/tooling-configs 0.2.2 → 0.2.4

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/README.md CHANGED
@@ -173,7 +173,7 @@ pnpm install
173
173
  ```
174
174
 
175
175
  - A rule listed under `rules` is off for `oxlint`, so editors, hooks and `lint` stay green. `antelopejs-ratchet` counts it with every rule on, and fails when a count rises. It prints the findings in the files the change touched.
176
- - A file listed under `oversizeFiles` may exceed 20,000 bytes and `max-lines`, up to its recorded size. Any other file over either limit fails.
176
+ - A file listed under `oversizeFiles` may exceed 20,000 bytes and `max-lines`, up to its recorded size. Any other file over either limit fails. When git sees a listed file renamed (`git mv`, or a staged delete and add), the allowance moves to the new path and never exceeds the old one; a copy or a new file inherits nothing. `antelopejs-ratchet --base <ref>` detects renames against that revision instead of `HEAD`, for a rename that was committed before the file was updated.
177
177
  - `antelopejs-ratchet --update` lowers each number to the current count and removes what reached zero. It never raises a number or adds an entry. Commit the lowered file.
178
178
 
179
179
  When every rule count is zero and `oversizeFiles` is empty, the ratchet is retired. `antelopejs-ratchet --update` deletes the file and asks you to run `antelopejs-sync`. Sync then removes `ratchet`, `ratchet:update`, the ratchet hook and the Debt instructions. Commit those changes together. An empty baseline on first adoption creates no file. Later syncs never recreate it because the `sync:check` script marks adoption.
@@ -182,16 +182,22 @@ When every rule count is zero and `oversizeFiles` is empty, the ratchet is retir
182
182
 
183
183
  ### Size
184
184
 
185
- `antelopejs-check-size` fails on an authored file over 20,000 bytes, tests included. Generated code, fixtures, lockfiles, `CHANGELOG.md`, Markdown and binary assets are excluded. Data JSON under `locales/` or `i18n/`, `blocks.json`, `schema.json`, and `evals/**/cases.json` are excluded too. Files over the limit with a NUL byte in their first 8,000 bytes are binary even without a known extension. Staged checks inspect the index blob. Excluded files are also removed from recorded size allowances on ratchet update.
185
+ `antelopejs-check-size` fails on an authored file over 20,000 bytes, tests included. Generated code (`dist`, `coverage`, `.nuxt`, `.output`, and `build` or `output` at the repository root or a package root, never under `src/` or `test/`), fixtures, lockfiles, `CHANGELOG.md`, Markdown and binary assets are excluded. Data JSON under `locales/` or `i18n/`, `blocks.json`, `schema.json`, and `evals/**/cases.json` are excluded too. Files over the limit with a NUL byte in their first 8,000 bytes are binary even without a known extension. Staged checks inspect the index blob. Excluded files are also removed from recorded size allowances on ratchet update.
186
186
 
187
187
  Pass paths to check only those files, as the pre-commit hook does. The command also fails on an `oxlint-disable` or `eslint-disable` directive (line, next-line or file form) that names no rule: oxlint applies such a directive before any rule runs, so `no-comments` cannot report it.
188
188
 
189
189
  ### Cleanup proof
190
190
 
191
- A behaviour-preserving cleanup PR shows `antelopejs-api-diff <base-ref>` passing. It checks each tracked, non-private package with a `tsconfig.json`, using that package's installed TypeScript. It emits declarations without comments, resolves published entries from `exports` (preferring `types`), `main`, `types`/`typings` and `typesVersions`, and bundles each entry's local declaration closure. External packages stay external. Stable top-level ordering ignores declaration moves between internal files while preserving overload order. Compiler errors fail the proof.
191
+ A behaviour-preserving cleanup PR shows `antelopejs-api-diff <base-ref>` passing. It checks each tracked package with a `tsconfig.json` that publishes something (not private, and declaring `exports`, `main`, `types`, `typings` or `typesVersions`) and lists the others as `API: skipped <directory>, <reason>.`. Each package is analysed and bundled with its own installed TypeScript, falling back to the one `dts-bundle-generator` brings when the package has none; a TypeScript without the programmatic compiler API (7 and later) is reported as an execution error naming the package, and the other packages are still analysed. Large packages are bundled by several worker processes (up to 8, bounded by cpus and free memory); the output is the same as a single process. It emits declarations without comments, resolves published entries from `exports` (preferring `types`), `main`, `types`/`typings` and `typesVersions`, and bundles each entry's local declaration closure. External packages stay external. Stable top-level ordering ignores declaration moves between internal files while preserving overload order. Compiler errors fail the proof.
192
192
 
193
193
  A comment-only PR shows `antelopejs-comment-proof <base-ref>` passing instead of a verifier. It includes private packages, ignores type diagnostics and compares comment-free JavaScript emit byte for byte. Both commands exclude test sources, fail on added or removed outputs, and print unified diffs for changes.
194
194
 
195
+ Pass `--allow-added <glob>` (repeatable) to `antelopejs-api-diff` when a refactor adds helper files that a wildcard export publishes, such as an `internal/` directory under `"./*"`. An added entry passes, in both the declaration and the runtime half, when its published subpath matches a glob (for example `--allow-added '**/internal/**'`, matched against `base/table-view/internal/helper` for `./base/table-view/internal/helper`) and its source module is marked `@internal`: a leading `/** @internal @packageDocumentation */` comment on the module (`@module` and `@fileoverview` also qualify), or an `@internal` tag on every exported declaration. Allowed entries are printed under `Added (allowed): <count>`. An added entry that matches but is not marked `@internal` fails with the file and the fix. Added entries matching no glob, removed entries and changed entries still fail, matching or not. Without the flag nothing changes.
196
+
197
+ ```bash
198
+ pnpm exec antelopejs-api-diff origin/main --allow-added '**/internal/**'
199
+ ```
200
+
195
201
  Both commands compare **committed HEAD**, not staged or working-tree edits. They check out the base and HEAD in temporary detached worktrees, reuse the current checkout's root and package `node_modules`, and remove the worktrees afterwards. Install the consumer's dependencies before running them.
196
202
 
197
203
  ```bash
@@ -1,9 +1,297 @@
1
1
  #!/usr/bin/env node
2
- import { a as runCli, i as repositoryRoot } from "../files-DAD5OtfV.mjs";
3
- import { i as compareRevisions, n as isTestSource, r as packagesAt, t as emitPackage } from "../typescript-CHOlkIXa.mjs";
4
- import { copyFileSync, existsSync, mkdirSync, readFileSync, symlinkSync, writeFileSync } from "node:fs";
5
- import { dirname, join, relative, resolve } from "node:path";
6
- import { generateDtsBundle } from "dts-bundle-generator";
2
+ import { c as revisionCounts, d as createAddedPolicy, f as describeAllowance, h as runCli, i as repositoryRoot, m as recordVerdict, o as DIRECTORY_LINK, p as fillStars, s as compareRevisions, u as allowedByGlob } from "../files-CaMy-5ne.mjs";
3
+ import { i as parseManifest, r as packageManager } from "../package-Ckd7e4tA.mjs";
4
+ import { a as unpublishedAt, i as packagesAt, n as isTestSource, r as outputRoot, t as emitPackage } from "../typescript-BlNlyAhQ.mjs";
5
+ import { createRequire } from "node:module";
6
+ import { copyFileSync, cpSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
7
+ import { basename, dirname, join, relative, resolve } from "node:path";
8
+ import { execFileSync, spawnSync } from "node:child_process";
9
+ import { parseArgs } from "node:util";
10
+ import { availableParallelism, freemem } from "node:os";
11
+ //#region src/guardrails/declaration-bundle.ts
12
+ const ENTRIES_PER_WORKER = 16;
13
+ const MAX_WORKERS = 8;
14
+ const WORKER_MEMORY = 1.5 * 1024 ** 3;
15
+ const WORKER = `
16
+ const { readFileSync, writeFileSync } = require("node:fs");
17
+ const { createRequire } = require("node:module");
18
+ try {
19
+ const job = JSON.parse(readFileSync(process.argv[2], "utf8"));
20
+ const generate = createRequire(job.loader)("dts-bundle-generator").generateDtsBundle;
21
+ writeFileSync(job.result, JSON.stringify(generate(job.entries, job.options)));
22
+ } catch (error) {
23
+ process.stderr.write(String(error instanceof Error ? error.message : error));
24
+ process.exit(1);
25
+ }
26
+ `;
27
+ const DRIVER = `
28
+ const { spawn } = require("node:child_process");
29
+ const [worker, ...jobs] = process.argv.slice(1);
30
+ let failed = false;
31
+ let pending = jobs.length;
32
+ for (const job of jobs) {
33
+ spawn(process.execPath, [worker, job], { stdio: ["ignore", "inherit", "inherit"] }).on("exit", (code) => {
34
+ failed ||= code !== 0;
35
+ pending -= 1;
36
+ if (pending === 0) process.exit(failed ? 1 : 0);
37
+ });
38
+ }
39
+ `;
40
+ /** Places a copy of `dts-bundle-generator` beside a `typescript` link to the package at `compilerRoot`, the compiler the target repository builds with. The generator requires `typescript` by name, so this makes it drive that compiler instead of the one it was installed with. Returns a path to require the copy from. */
41
+ function installGenerator(compilerRoot, scratch) {
42
+ const source = dirname(createRequire(import.meta.url).resolve("dts-bundle-generator/package.json"));
43
+ const modules = join(scratch, "generator", "node_modules");
44
+ mkdirSync(modules, { recursive: true });
45
+ cpSync(source, join(modules, "dts-bundle-generator"), {
46
+ recursive: true,
47
+ filter: (path) => basename(path) !== "node_modules"
48
+ });
49
+ symlinkSync(compilerRoot, join(modules, "typescript"), DIRECTORY_LINK);
50
+ return join(modules, "index.js");
51
+ }
52
+ /** Workers for `count` entries: each builds its own program, so a worker needs enough entries to repay that, and the bound keeps their combined heap inside the memory that is free. */
53
+ function workerCount(count, cpus = availableParallelism(), free = freemem()) {
54
+ return Math.max(1, Math.min(Math.floor(count / ENTRIES_PER_WORKER), cpus, MAX_WORKERS, Math.floor(free / WORKER_MEMORY)));
55
+ }
56
+ function generateInWorkers(loader, directory, entries, options, workers) {
57
+ const jobs = Array.from({ length: workers }, (_, worker) => ({
58
+ indices: entries.flatMap((_entry, index) => index % workers === worker ? [index] : []),
59
+ file: join(directory, `job-${worker}.json`),
60
+ result: join(directory, `result-${worker}.json`)
61
+ }));
62
+ for (const { indices, file, result } of jobs) writeFileSync(file, JSON.stringify({
63
+ loader,
64
+ result,
65
+ options,
66
+ entries: indices.map((index) => entries[index])
67
+ }));
68
+ const worker = join(directory, "worker.cjs");
69
+ writeFileSync(worker, WORKER);
70
+ const run = spawnSync(process.execPath, [
71
+ "-e",
72
+ DRIVER,
73
+ worker,
74
+ ...jobs.map(({ file }) => file)
75
+ ], {
76
+ encoding: "utf8",
77
+ stdio: [
78
+ "ignore",
79
+ "ignore",
80
+ "pipe"
81
+ ]
82
+ });
83
+ if (run.error) throw run.error;
84
+ if (run.status !== 0) throw new Error(run.stderr || "A declaration bundling worker failed.");
85
+ const bundles = [];
86
+ for (const { indices, result } of jobs) for (const [position, bundle] of JSON.parse(readFileSync(result, "utf8")).entries()) bundles[indices[position]] = bundle;
87
+ return bundles;
88
+ }
89
+ /** Bundles every entry's declarations with the compiler at `compilerRoot`. Large packages are split across worker processes by entry; each bundle depends only on its own entry, so the output is the same as one sequential call. */
90
+ function bundleDeclarations(compilerRoot, scratch, entries, options, workers = workerCount(entries.length)) {
91
+ const loader = installGenerator(compilerRoot, scratch);
92
+ if (workers > 1) return generateInWorkers(loader, join(scratch, "generator"), entries, options, workers);
93
+ const generate = createRequire(loader)("dts-bundle-generator").generateDtsBundle;
94
+ return generate(entries, options);
95
+ }
96
+ //#endregion
97
+ //#region src/guardrails/runtime-diff.ts
98
+ const DESCRIBE = `
99
+ const { readFileSync, existsSync } = require("node:fs");
100
+ const { dirname, join, extname } = require("node:path");
101
+ const { pathToFileURL } = require("node:url");
102
+ const file = process.argv[1];
103
+ let directory = dirname(file);
104
+ while (!existsSync(join(directory, "package.json")) && dirname(directory) !== directory) directory = dirname(directory);
105
+ const manifest = existsSync(join(directory, "package.json")) ? JSON.parse(readFileSync(join(directory, "package.json"), "utf8")) : {};
106
+ const esm = extname(file) === ".mjs" || (extname(file) === ".js" && manifest.type === "module");
107
+ const seen = new Map();
108
+ function functionInfo(fn) {
109
+ let constructible = true;
110
+ try { Reflect.construct(Object, [], fn); } catch { constructible = false; }
111
+ return { name: fn.name, length: fn.length, async: Object.getPrototypeOf(fn) === Object.getPrototypeOf(async function() {}), constructible };
112
+ }
113
+ function valueInfo(value) {
114
+ if (typeof value !== "function") return { kind: value === null ? "null" : typeof value };
115
+ if (seen.has(value)) return { kind: "reference", id: seen.get(value) };
116
+ const id = seen.size;
117
+ seen.set(value, id);
118
+ return { kind: "function", id, function: functionInfo(value), static: properties(value, false), prototype: value.prototype ? properties(value.prototype, false) : [] };
119
+ }
120
+ function properties(object, observe) {
121
+ if (object === null || !["object", "function"].includes(typeof object)) return [];
122
+ return Reflect.ownKeys(object).map(key => {
123
+ const d = Object.getOwnPropertyDescriptor(object, key);
124
+ const common = { key: typeof key === "symbol" ? { symbol: String(key) } : key, enumerable: d.enumerable, configurable: d.configurable };
125
+ return "value" in d
126
+ ? { ...common, kind: "data", writable: d.writable, value: valueInfo(d.value) }
127
+ : { ...common, kind: "accessor", get: d.get ? functionInfo(d.get) : null, set: d.set ? functionInfo(d.set) : null, observed: observe ? valueInfo(Reflect.get(object, key)) : null };
128
+ });
129
+ }
130
+ (async () => {
131
+ const value = esm ? await import(pathToFileURL(file).href) : require(file);
132
+ process.stdout.write(JSON.stringify({ kind: esm ? "esm" : "cjs", value: valueInfo(value), properties: typeof value === "function" ? [] : properties(value, true) }));
133
+ })().catch(error => { process.stderr.write(String(error.stack)); process.exitCode = 1; });
134
+ `;
135
+ function runtimeTargets(target, entry = "exports", subpath = ".") {
136
+ if (target == null) return [];
137
+ if (Array.isArray(target)) return target.flatMap((value, index) => runtimeTargets(value, `${entry}/${index}`, subpath));
138
+ if (target.constructor === String) return [{
139
+ entry,
140
+ target: String(target),
141
+ subpath
142
+ }];
143
+ return Object.entries(target).flatMap(([key, value]) => {
144
+ if (key === "types") return [];
145
+ if ([
146
+ "browser",
147
+ "deno",
148
+ "react-native"
149
+ ].includes(key)) throw new Error(`${entry}/${key}: unsupported runtime environment.`);
150
+ return runtimeTargets(value, `${entry}/${key}`, key.startsWith(".") ? key.slice(2) || "." : subpath);
151
+ });
152
+ }
153
+ function builtEntries(directory, manifest) {
154
+ const targets = runtimeTargets(manifest.exports);
155
+ if (manifest.main) targets.push({
156
+ entry: "main",
157
+ target: manifest.main,
158
+ subpath: "main"
159
+ });
160
+ if (!targets.length) throw new Error(`${directory}: no published runtime entry.`);
161
+ return targets.filter(({ target }) => !target.endsWith(".json")).flatMap(({ entry, target, subpath }) => {
162
+ if (!target.includes("*")) {
163
+ const file = resolve(directory, target);
164
+ if (!existsSync(file)) throw new Error(`${directory}: missing built runtime entry ${target}.`);
165
+ return [{
166
+ entry,
167
+ file,
168
+ subpath
169
+ }];
170
+ }
171
+ const prefix = resolve(directory, target.slice(0, target.indexOf("*")));
172
+ const parent = dirname(prefix);
173
+ const pattern = new RegExp(`^${resolve(directory, target).split("*").map((part) => part.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&")).join("(.*)")}$`, "u");
174
+ if (!existsSync(parent)) throw new Error(`${directory}: missing build output for ${target}.`);
175
+ const output = outputRoot(directory);
176
+ const matches = readdirSync(parent, {
177
+ recursive: true,
178
+ withFileTypes: true
179
+ }).filter((file) => file.isFile()).map((file) => join(file.parentPath, file.name)).filter((file) => pattern.test(file) && !isTestSource(output, file));
180
+ if (!matches.length) throw new Error(`${directory}: missing built runtime entry ${target}.`);
181
+ return matches.sort().map((file) => {
182
+ const capture = pattern.exec(file)?.[1] ?? relative(directory, file);
183
+ return {
184
+ entry: entry.replaceAll("*", capture),
185
+ file,
186
+ subpath: fillStars(subpath, [capture])
187
+ };
188
+ });
189
+ });
190
+ }
191
+ function childJson(args, cwd) {
192
+ const result = spawnSync(process.execPath, args, {
193
+ cwd,
194
+ encoding: "utf8",
195
+ timeout: 1e4,
196
+ maxBuffer: 16777216,
197
+ stdio: [
198
+ "ignore",
199
+ "pipe",
200
+ "pipe"
201
+ ]
202
+ });
203
+ if (result.error) throw result.error;
204
+ if (result.status !== 0) throw new Error(result.stderr || `Runtime child exited with ${result.status ?? result.signal}.`);
205
+ return `${JSON.stringify(JSON.parse(result.stdout), null, 2)}\n`;
206
+ }
207
+ function buildPackage(directory, output, manifest) {
208
+ const buildManifest = parseManifest(readFileSync(join(directory, "package.json"), "utf8"));
209
+ if (buildManifest.scripts?.build) execFileSync(packageManager(buildManifest), ["run", "build"], {
210
+ cwd: directory,
211
+ encoding: "utf8",
212
+ shell: process.platform === "win32",
213
+ env: {
214
+ ...process.env,
215
+ pnpm_config_verify_deps_before_run: "false"
216
+ },
217
+ timeout: 12e4,
218
+ stdio: [
219
+ "ignore",
220
+ "pipe",
221
+ "pipe"
222
+ ]
223
+ });
224
+ let entries;
225
+ try {
226
+ entries = builtEntries(directory, manifest);
227
+ } catch (error) {
228
+ if (buildManifest.scripts?.build) throw error;
229
+ return;
230
+ }
231
+ for (const { entry, file } of entries) {
232
+ const destination = join(output, `${encodeURIComponent(entry)}.json`);
233
+ const metadata = childJson([
234
+ "-e",
235
+ DESCRIBE,
236
+ file
237
+ ], directory);
238
+ mkdirSync(dirname(destination), { recursive: true });
239
+ writeFileSync(destination, metadata);
240
+ }
241
+ return {
242
+ count: entries.length,
243
+ entries
244
+ };
245
+ }
246
+ /** Builds both committed revisions and compares published runtime metadata and one captured optional probe. */
247
+ function runtimeDiff(root, baseRef, probe, policy) {
248
+ const errors = [];
249
+ const failedPackages = /* @__PURE__ */ new Set();
250
+ const skippedPackages = /* @__PURE__ */ new Set();
251
+ const result = compareRevisions(root, baseRef, "Runtime API", (worktree, output, scratch) => {
252
+ const packages = packagesAt(worktree, true);
253
+ const published = [];
254
+ let entries = 0;
255
+ for (const { directory, manifest } of packages) {
256
+ const folder = encodeURIComponent(directory).replaceAll(".", "%2E");
257
+ try {
258
+ const built = buildPackage(join(worktree, directory), join(output, folder), manifest);
259
+ if (built === void 0) skippedPackages.add(directory);
260
+ else {
261
+ entries += built.count;
262
+ published.push(...built.entries.map(({ entry, subpath }) => ({
263
+ path: `${folder}/${encodeURIComponent(entry)}.json`,
264
+ directory,
265
+ subpath
266
+ })));
267
+ }
268
+ } catch (error) {
269
+ failedPackages.add(directory);
270
+ errors.push(`Execution error: ${directory}: ${error instanceof Error ? error.message : String(error)}\n`);
271
+ }
272
+ }
273
+ for (const directory of failedPackages) for (const side of ["base", "head"]) rmSync(join(dirname(output), side, encodeURIComponent(directory).replaceAll(".", "%2E")), {
274
+ recursive: true,
275
+ force: true
276
+ });
277
+ if (probe !== void 0) {
278
+ mkdirSync(scratch, { recursive: true });
279
+ const script = join(scratch, "probe.cjs");
280
+ writeFileSync(script, probe);
281
+ writeFileSync(join(output, "probe.json"), childJson([script, worktree], worktree));
282
+ }
283
+ return {
284
+ packages: packages.map(({ directory }) => directory),
285
+ entries,
286
+ published
287
+ };
288
+ }, policy);
289
+ return {
290
+ different: result.different || errors.length > 0,
291
+ output: (errors.length && !result.different ? result.output.replace(/^Runtime API:[^\n]*\n/u, "Runtime API: comparison incomplete due to execution errors.\n") : result.output) + [...skippedPackages].map((directory) => `Runtime API: skipped ${directory}, which has no build script and no committed runtime entry.\n`).join("") + errors.join("")
292
+ };
293
+ }
294
+ //#endregion
7
295
  //#region src/guardrails/api-diff.ts
8
296
  function entrySegment(value) {
9
297
  return encodeURIComponent(value).replaceAll(".", "%2E").replaceAll("*", "%2A");
@@ -11,16 +299,17 @@ function entrySegment(value) {
11
299
  function entryPattern(value) {
12
300
  return value.split("*").map(entrySegment).join("*");
13
301
  }
14
- function exportTargets(target, entry = "exports/root") {
302
+ function exportTargets(target, entry = "exports/root", subpath = ".") {
15
303
  if (typeof target === "string") return [{
16
304
  entry,
17
- target
305
+ target,
306
+ subpath
18
307
  }];
19
308
  if (target == null) return [];
20
- if (Array.isArray(target)) return target.flatMap((value, index) => exportTargets(value, `${entry}/fallback/${index}`));
21
- if (target.types !== void 0) return exportTargets(target.types, entry);
309
+ if (Array.isArray(target)) return target.flatMap((value, index) => exportTargets(value, `${entry}/fallback/${index}`, subpath));
310
+ if (target.types !== void 0) return exportTargets(target.types, entry, subpath);
22
311
  return Object.entries(target).flatMap(([key, value]) => {
23
- return exportTargets(value, key.startsWith(".") ? key === "." ? "exports/root" : `exports/subpath/${entryPattern(key.slice(2))}` : `${entry}/condition/${entrySegment(key)}`);
312
+ return exportTargets(value, key.startsWith(".") ? key === "." ? "exports/root" : `exports/subpath/${entryPattern(key.slice(2))}` : `${entry}/condition/${entrySegment(key)}`, key.startsWith(".") ? key.slice(2) || "." : subpath);
24
313
  });
25
314
  }
26
315
  function declarationTarget(target) {
@@ -40,16 +329,18 @@ function entryPatterns(manifest) {
40
329
  const target = manifest[key];
41
330
  if (target !== void 0) targets.push({
42
331
  entry: key,
43
- target
332
+ target,
333
+ subpath: key
44
334
  });
45
335
  }
46
336
  for (const [version, mappings] of Object.entries(manifest.typesVersions ?? {})) for (const [entry, paths] of Object.entries(mappings)) for (const [index, target] of paths.entries()) targets.push({
47
337
  entry: `typesVersions/${entrySegment(version)}/${entryPattern(entry)}/${index}`,
48
- target
338
+ target,
339
+ subpath: entry
49
340
  });
50
- return targets.map(({ entry, target }) => ({
51
- entry,
52
- target: declarationTarget(target)
341
+ return targets.map((published) => ({
342
+ ...published,
343
+ target: declarationTarget(published.target)
53
344
  })).filter(({ target }) => /\.d\.[cm]?ts$/u.test(target) || target.includes("*"));
54
345
  }
55
346
  /** Export stars are substitutions rather than path globs and can span directory separators. */
@@ -60,7 +351,7 @@ function publishedEntries(directory, manifest, emitted, scratch) {
60
351
  const outputRoot = resolve(directory, emitted.options.outDir ?? ".");
61
352
  const files = emitted.files.map((file) => relative(scratch, file).split("\\").join("/"));
62
353
  const entries = [];
63
- for (const { entry, target } of entryPatterns(manifest)) {
354
+ for (const { entry, target, subpath } of entryPatterns(manifest)) {
64
355
  if (isTestSource(outputRoot, resolve(directory, target))) continue;
65
356
  const path = relative(outputRoot, resolve(directory, target)).split("\\").join("/");
66
357
  const pattern = targetPattern(path);
@@ -68,11 +359,11 @@ function publishedEntries(directory, manifest, emitted, scratch) {
68
359
  if (!matches.length && !path.includes("*")) throw new Error(`${directory}: published target ${target} has no emitted declaration.`);
69
360
  for (const file of matches) {
70
361
  const captures = pattern.exec(file)?.slice(1) ?? [];
71
- let index = 0;
72
- const name = entry.includes("*") ? entry.replaceAll("*", () => entrySegment(captures[index++] ?? captures[0] ?? "")) : `${entry}${captures.length ? `/file/${entrySegment(file)}` : ""}`;
362
+ const name = entry.includes("*") ? fillStars(entry, captures, entrySegment) : `${entry}${captures.length ? `/file/${entrySegment(file)}` : ""}`;
73
363
  entries.push({
74
364
  entry: `${name}.d.ts`,
75
- file
365
+ file,
366
+ subpath: subpath.includes("*") ? fillStars(subpath, captures) : captures.length ? `${subpath}/${captures[0]}` : subpath
76
367
  });
77
368
  }
78
369
  }
@@ -99,7 +390,7 @@ function bundleDependencies(directory, scratch) {
99
390
  if (parent === current) return;
100
391
  current = parent;
101
392
  }
102
- symlinkSync(join(current, "node_modules"), join(scratch, "node_modules"), "dir");
393
+ symlinkSync(join(current, "node_modules"), join(scratch, "node_modules"), DIRECTORY_LINK);
103
394
  }
104
395
  /** dts-bundle-generator 9 remaps a .d.mts/.d.cts root twice; a source-named copy preserves its declaration text. */
105
396
  function generatorEntry(file) {
@@ -107,10 +398,14 @@ function generatorEntry(file) {
107
398
  if (alias !== file) copyFileSync(file, alias);
108
399
  return alias;
109
400
  }
110
- function bundlePackage(directory, output, scratch, manifest) {
401
+ function bundlePackage(paths, manifest, policy) {
402
+ const { directory, output, scratch } = paths;
111
403
  const emitted = emitPackage(directory, scratch, true);
112
404
  const entries = publishedEntries(directory, manifest, emitted, scratch);
113
- if (!entries.length) return 0;
405
+ if (!entries.length) return {
406
+ count: 0,
407
+ published: []
408
+ };
114
409
  bundleDependencies(directory, scratch);
115
410
  writeFileSync(join(scratch, "package.json"), readFileSync(join(directory, "package.json")));
116
411
  const config = join(scratch, "tsconfig.json");
@@ -125,7 +420,7 @@ function bundlePackage(directory, output, scratch, manifest) {
125
420
  files: entries.map(({ file }) => join(scratch, file)),
126
421
  include: []
127
422
  }));
128
- const bundles = generateDtsBundle(entries.map(({ file }) => ({
423
+ const bundles = bundleDeclarations(emitted.compilerRoot, scratch, entries.map(({ file }) => ({
129
424
  filePath: generatorEntry(join(scratch, file)),
130
425
  output: {
131
426
  exportReferencedTypes: false,
@@ -138,26 +433,111 @@ function bundlePackage(directory, output, scratch, manifest) {
138
433
  mkdirSync(dirname(path), { recursive: true });
139
434
  writeFileSync(path, normalizeBundle(emitted.compiler, bundles[index]));
140
435
  }
141
- return entries.length;
436
+ if (policy !== void 0) for (const { file, subpath } of entries) {
437
+ if (!allowedByGlob(policy, subpath)) continue;
438
+ const emittedFile = join(scratch, file);
439
+ const module = emitted.modules.get(resolve(emittedFile)) ?? emittedFile;
440
+ recordVerdict(policy, emitted.compiler, {
441
+ directory: paths.name,
442
+ subpath,
443
+ module,
444
+ label: relative(paths.root, module).split("\\").join("/")
445
+ });
446
+ }
447
+ return {
448
+ count: entries.length,
449
+ published: entries.map(({ entry, subpath }) => ({
450
+ path: `${paths.name === "." ? "_root" : paths.name}/${entry}`,
451
+ directory: paths.name,
452
+ subpath
453
+ }))
454
+ };
142
455
  }
143
- /** Proves published declarations match between a base commit and committed HEAD. */
144
- function apiDiff(root, baseRef) {
145
- return compareRevisions(root, baseRef, "API", (worktree, output, scratch) => {
456
+ function declarationDiff(root, baseRef, policy) {
457
+ const errors = /* @__PURE__ */ new Set();
458
+ const failedPackages = /* @__PURE__ */ new Set();
459
+ const unpublished = /* @__PURE__ */ new Map();
460
+ const result = compareRevisions(root, baseRef, "API", (worktree, output, scratch) => {
146
461
  const packages = packagesAt(worktree, true);
462
+ for (const { directory, reason } of unpublishedAt(worktree)) unpublished.set(directory, reason);
463
+ const published = [];
147
464
  let entries = 0;
148
- for (const { directory, manifest } of packages) entries += bundlePackage(join(worktree, directory), join(output, directory === "." ? "_root" : directory), join(scratch, directory === "." ? "_root" : directory), manifest);
465
+ for (const { directory, manifest } of packages) {
466
+ const key = directory === "." ? "_root" : directory;
467
+ try {
468
+ const bundled = bundlePackage({
469
+ root: worktree,
470
+ name: directory,
471
+ directory: join(worktree, directory),
472
+ output: join(output, key),
473
+ scratch: join(scratch, key)
474
+ }, manifest, policy);
475
+ entries += bundled.count;
476
+ published.push(...bundled.published);
477
+ } catch (error) {
478
+ failedPackages.add(directory);
479
+ errors.add(`Execution error: ${directory}${manifest.name === void 0 ? "" : ` (${manifest.name})`}: ${error instanceof Error ? error.message : String(error)}\n`);
480
+ }
481
+ }
482
+ for (const directory of failedPackages) for (const side of ["base", "head"]) rmSync(join(dirname(output), side, directory === "." ? "_root" : directory), {
483
+ recursive: true,
484
+ force: true
485
+ });
149
486
  return {
150
487
  packages: packages.map(({ directory }) => directory),
151
- entries
488
+ entries,
489
+ published
152
490
  };
153
- });
491
+ }, policy);
492
+ return {
493
+ different: result.different || errors.size > 0,
494
+ output: (errors.size > 0 && !result.different ? result.output.replace(/^API:[^\n]*\n/u, "API: comparison incomplete due to execution errors.\n") : result.output) + [...unpublished].sort(([a], [b]) => a.localeCompare(b)).map(([directory, reason]) => `API: skipped ${directory}, ${reason}.\n`).join("") + [...errors].join("")
495
+ };
496
+ }
497
+ /** Compares declarations and built runtime exports, with an optional behavioral probe captured before either build. Added entries whose subpath matches an `allowAdded` glob pass when their module is `@internal`. */
498
+ function apiDiff(root, baseRef, probeFile, allowAdded = []) {
499
+ const policy = allowAdded.length ? createAddedPolicy(allowAdded) : void 0;
500
+ const probe = probeFile === void 0 ? void 0 : readFileSync(resolve(root, probeFile));
501
+ const results = [];
502
+ const errors = [];
503
+ for (const compare of [() => declarationDiff(root, baseRef, policy), () => runtimeDiff(root, baseRef, probe, policy)]) try {
504
+ results.push(compare());
505
+ } catch (error) {
506
+ errors.push(`Execution error: ${error instanceof Error ? error.message : String(error)}\n`);
507
+ }
508
+ return {
509
+ different: errors.length > 0 || results.some((result) => result.different) || (policy?.problems.size ?? 0) > 0,
510
+ output: results.map((result) => result.output).join("") + (policy === void 0 ? "" : describeAllowance(policy)) + errors.join("") + (probe === void 0 ? "No behavioural probe ran.\n" : "Behavioural probe supplied.\n") + revisionCounts(root, baseRef)
511
+ };
154
512
  }
155
513
  //#endregion
156
514
  //#region src/bin/api-diff.ts
515
+ const USAGE = "Usage: antelopejs-api-diff <base-ref> [--probe <file.cjs>] [--allow-added <glob>]...";
516
+ function parse(args) {
517
+ try {
518
+ const { positionals, values } = parseArgs({
519
+ args,
520
+ allowPositionals: true,
521
+ options: {
522
+ probe: { type: "string" },
523
+ "allow-added": {
524
+ type: "string",
525
+ multiple: true
526
+ }
527
+ }
528
+ });
529
+ if (positionals.length !== 1) throw new Error(USAGE);
530
+ return {
531
+ baseRef: positionals[0],
532
+ ...values
533
+ };
534
+ } catch {
535
+ throw new Error(USAGE);
536
+ }
537
+ }
157
538
  runCli(() => {
158
- const args = process.argv.slice(2);
159
- if (args.length !== 1) throw new Error("Usage: antelopejs-api-diff <base-ref>");
160
- const result = apiDiff(repositoryRoot(), args[0]);
539
+ const { baseRef, probe, "allow-added": allowAdded } = parse(process.argv.slice(2));
540
+ const result = apiDiff(repositoryRoot(), baseRef, probe, allowAdded);
161
541
  process.stdout.write(result.output);
162
542
  return result.different ? 1 : 0;
163
543
  });
@@ -1,6 +1,6 @@
1
1
  #!/usr/bin/env node
2
- import { a as runCli, i as repositoryRoot, r as repositoryPath, t as authoredSizes } from "../files-DAD5OtfV.mjs";
3
- import { t as checkSize } from "../size-D7JJp_W4.mjs";
2
+ import { h as runCli, i as repositoryRoot, r as repositoryPath, t as authoredSizes } from "../files-CaMy-5ne.mjs";
3
+ import { t as checkSize } from "../size-DYVe2pXo.mjs";
4
4
  import { existsSync, readFileSync } from "node:fs";
5
5
  import { join, resolve } from "node:path";
6
6
  import { spawnSync } from "node:child_process";
@@ -1,6 +1,6 @@
1
1
  #!/usr/bin/env node
2
2
  import "../ceilings-BSw9p4YB.mjs";
3
- import { a as runCli, i as repositoryRoot } from "../files-DAD5OtfV.mjs";
3
+ import { h as runCli, i as repositoryRoot } from "../files-CaMy-5ne.mjs";
4
4
  import { i as parseManifest, r as packageManager } from "../package-Ckd7e4tA.mjs";
5
5
  import { existsSync, readFileSync } from "node:fs";
6
6
  import { join } from "node:path";
@@ -29,6 +29,7 @@ function runChecks(root) {
29
29
  const result = spawnSync(manager, ["run", step], {
30
30
  cwd: root,
31
31
  encoding: "utf8",
32
+ shell: process.platform === "win32",
32
33
  env: {
33
34
  ...process.env,
34
35
  CI: "1"
@@ -1,12 +1,12 @@
1
1
  #!/usr/bin/env node
2
- import { a as runCli, i as repositoryRoot } from "../files-DAD5OtfV.mjs";
3
- import { i as compareRevisions, r as packagesAt, t as emitPackage } from "../typescript-CHOlkIXa.mjs";
2
+ import { c as revisionCounts, h as runCli, i as repositoryRoot, s as compareRevisions } from "../files-CaMy-5ne.mjs";
3
+ import { i as packagesAt, t as emitPackage } from "../typescript-BlNlyAhQ.mjs";
4
4
  import { copyFileSync, mkdirSync } from "node:fs";
5
5
  import { dirname, join, relative } from "node:path";
6
6
  //#region src/guardrails/comment-proof.ts
7
7
  /** Proves comment-free JavaScript emit matches, including private packages and excluding tests. */
8
8
  function commentProof(root, baseRef) {
9
- return compareRevisions(root, baseRef, "Comment proof", (worktree, output, scratch) => {
9
+ const result = compareRevisions(root, baseRef, "Comment proof", (worktree, output, scratch) => {
10
10
  const packages = packagesAt(worktree, false);
11
11
  let entries = 0;
12
12
  for (const { directory } of packages) {
@@ -25,6 +25,10 @@ function commentProof(root, baseRef) {
25
25
  entries
26
26
  };
27
27
  });
28
+ return {
29
+ ...result,
30
+ output: result.output + revisionCounts(root, baseRef)
31
+ };
28
32
  }
29
33
  //#endregion
30
34
  //#region src/bin/comment-proof.ts