@milkenjoyer/toolchain 0.17.1 → 0.18.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/README.md CHANGED
@@ -48,7 +48,9 @@ In the PR job, set `permissions: contents: read` and `GH_TOKEN: ${{ github.token
48
48
 
49
49
  `vp exec formal` checks every tracked TLA+ module and arithmetic proof against the standard in agent-kit#276. Run it from anywhere in the repository with no arguments. It exits 0 when every check passes. Each finding goes to stderr as `<file>: <check>: <message>`, sorted by file and then by check order, and the command exits 1. Each passing step logs one line to stdout.
50
50
 
51
- It needs Java 17 on `PATH`. In CI, add `actions/setup-java` with `distribution: temurin` and `java-version: "17"` before the step that runs it. The first run downloads TLC 1.8.0 (`tla2tools-1.8.0.jar`) and CommunityModules 202611060952 (`CommunityModules-deps-202611060952.jar`) into `$XDG_CACHE_HOME/tla`, or `~/.cache/tla`. Each jar falls back to its GitHub REST API asset URL when its release download fails, with the same SHA-256 check. Every run checks both jars against their pinned SHA-256 digests. A cached jar with the wrong digest stops the run, and deleting it makes the next run fetch it again.
51
+ It needs Java 17 on `PATH`. In CI, add `actions/setup-java` with `distribution: temurin` and `java-version: "17"` before the step that runs it. The package contains TLC 1.8.0 (`tla2tools-1.8.0.jar`). The first run verifies its pinned SHA-256 digest and copies it into `$XDG_CACHE_HOME/tla`, or `~/.cache/tla`, without downloading TLC. CommunityModules 202611060952 (`CommunityModules-deps-202611060952.jar`) retains its pinned release download and REST asset fallback. Every run checks both cached JARs against their existing digests. A cached JAR with the wrong digest stops the run. Delete it to restore the verified source on the next run. Immutable CommunityModules distribution is tracked in agent-kit#471.
52
+
53
+ In an agent-kit source checkout, run `bun scripts/hydrate-formal-tools.ts` with `GH_TOKEN` set to a token with contents access before formal tests or packing. The build helper verifies the fixed private archive and TLC JAR before writing generated package files. `ready` and `release` run it automatically with their workflow token.
52
54
 
53
55
  ### `specs.json`
54
56
 
package/STARTS.md CHANGED
@@ -14,4 +14,4 @@ Repo CI history counts a Boat job without `runStartedAt` as starting now unless
14
14
 
15
15
  Import `boatJobFindings` from `@milkenjoyer/toolchain/starts`. Add its findings to the existing workflow policy, with every workflow as a `[path, text]` pair. It bounds each closure to `BOAT_JOBS_PER_RUN = 2`, including literal matrices, repeated local reusable calls and `workflow_run` descendants. Each descendant counts once per distinct activity type, or three times when `types` is absent. Dynamic and unresolved graphs produce findings. Keep runner, timeout and concurrency checks.
16
16
 
17
- PR and main workflow triggers stay unchanged until the request controller ships. Workflows start without admission, bounded only by `BOAT_JOBS_PER_RUN`. Product repos adopt the published pin instead of copying files. Boat reports no start spend, so nothing here proves zero paid starts.
17
+ `boatJobFindings` also reports a workflow whose Boat jobs start on a `pull_request`, `pull_request_target` or PR-branch push. A `pull_request` trigger with a non-empty `types` list containing only `labeled` is exempt. Every other PR trigger stays flagged. A product repo moves PR `ready` to `pull_request` `labeled` with the pin move that brings this rule. Product repos adopt the published pin instead of copying files. Boat reports no start spend, so nothing here proves zero paid starts.
package/dist/formal.mjs CHANGED
@@ -17,11 +17,11 @@ import * as Stream from "effect/Stream";
17
17
  import { FileSystem } from "effect/FileSystem";
18
18
  import { fileURLToPath } from "node:url";
19
19
  import * as Result from "effect/Result";
20
- import { createHash } from "node:crypto";
21
20
  import * as Clock from "effect/Clock";
22
21
  import * as Context from "effect/Context";
23
22
  import { FetchHttpClient, HttpClient } from "effect/http";
24
23
  import { Path } from "effect/Path";
24
+ import { createHash } from "node:crypto";
25
25
  import * as Cache from "effect/Cache";
26
26
  // src/formal/proof-run.ts
27
27
  const Edit = Schema.Struct({
@@ -237,19 +237,21 @@ const fromXml = (xml) => {
237
237
  typeOK: typeOK && new Set(body ? typed(body, /* @__PURE__ */ new Set()) : [])
238
238
  };
239
239
  };
240
- // src/formal/tla.ts
241
- var FormalError = class extends Data.TaggedError("FormalError") {};
242
- const pins = [{
240
+ // src/formal/tools.ts
241
+ const pins$1 = [{
243
242
  file: "tla2tools-1.8.0.jar",
244
- urls: ["https://github.com/tlaplus/tlaplus/releases/download/v1.8.0/tla2tools.jar", "https://api.github.com/repos/tlaplus/tlaplus/releases/assets/718777374"],
245
243
  sha256: "e1f11b75c4b5bc4478ba0ac5cb6ae28e40a01b0016bc33e0aa97da22dfdbcd7f"
246
- }, {
244
+ }];
245
+ const packagedTools = fileURLToPath(new URL("../../formal-tools/", import.meta.url));
246
+ const digest = (bytes) => createHash("sha256").update(bytes).digest("hex");
247
+ // src/formal/tla.ts
248
+ var FormalError = class extends Data.TaggedError("FormalError") {};
249
+ const pins = [...pins$1, {
247
250
  file: "CommunityModules-deps-202611060952.jar",
248
251
  urls: ["https://github.com/tlaplus/CommunityModules/releases/download/202611060952/CommunityModules-deps-202611060952.jar", "https://api.github.com/repos/tlaplus/CommunityModules/releases/assets/716678698"],
249
252
  sha256: "a3b27c40f1fb5085f30c6ead37e918457f8cfc62c1e50a1dc668ef592ad2b5fb"
250
253
  }];
251
254
  const error = (cause) => new FormalError({ message: cause instanceof Error ? cause.message : String(cause) });
252
- const digest = (bytes) => createHash("sha256").update(bytes).digest("hex");
253
255
  const messages = (output) => [...output.matchAll(/@!@!@STARTMSG (\d+):([0-4]) @!@!@([\s\S]*?)@!@!@ENDMSG \1 @!@!@/gu)].map((match) => ({
254
256
  code: Number(match[1]),
255
257
  severity: Number(match[2]),
@@ -269,28 +271,35 @@ const make$1 = Effect.gen(function* () {
269
271
  const file = path.join(cache, pin.file);
270
272
  if (yield* fs.exists(file)) {
271
273
  const actual = digest(yield* fs.readFile(file));
272
- if (actual !== pin.sha256) return yield* new FormalError({ message: `${file} has sha256 ${actual}, expected ${pin.sha256}; delete it to refetch` });
274
+ if (actual !== pin.sha256) return yield* new FormalError({ message: `${file} has sha256 ${actual}, expected ${pin.sha256}; delete it to restore the pinned JAR` });
273
275
  } else yield* Effect.scoped(Effect.gen(function* () {
274
276
  const temp = yield* fs.makeTempFileScoped({
275
277
  directory: cache,
276
278
  prefix: `.${pin.file}.`,
277
279
  suffix: ".part"
278
280
  });
279
- const { url, bytes } = yield* Effect.gen(function* () {
281
+ const { source, bytes } = yield* Effect.gen(function* () {
282
+ if (!("urls" in pin)) {
283
+ const source = path.join(packagedTools, pin.file);
284
+ return {
285
+ source,
286
+ bytes: yield* fs.readFile(source)
287
+ };
288
+ }
280
289
  const failures = [];
281
- for (const url of pin.urls) {
282
- const result = yield* HttpClient.get(url, { headers: { Accept: "application/octet-stream" } }).pipe(Effect.flatMap((response) => response.status === 200 ? response.arrayBuffer.pipe(Effect.mapError(error)) : Effect.fail(new FormalError({ message: `HTTP ${response.status}` }))), Effect.map((buffer) => new Uint8Array(buffer)), Effect.timeout("120 seconds"), Effect.provide(FetchHttpClient.layer), Effect.result);
290
+ for (const source of pin.urls) {
291
+ const result = yield* HttpClient.get(source, { headers: { Accept: "application/octet-stream" } }).pipe(Effect.flatMap((response) => response.status === 200 ? response.arrayBuffer.pipe(Effect.mapError(error)) : Effect.fail(new FormalError({ message: `HTTP ${response.status}` }))), Effect.map((buffer) => new Uint8Array(buffer)), Effect.timeout("120 seconds"), Effect.provide(FetchHttpClient.layer), Effect.result);
283
292
  if (Result.isSuccess(result)) return {
284
- url,
293
+ source,
285
294
  bytes: result.success
286
295
  };
287
- failures.push(`${url}: ${error(result.failure).message}`);
296
+ failures.push(`${source}: ${error(result.failure).message}`);
288
297
  }
289
298
  return yield* new FormalError({ message: failures.join("; ") });
290
299
  });
291
- yield* fs.writeFile(temp, bytes);
292
300
  const actual = digest(bytes);
293
- if (actual !== pin.sha256) return yield* new FormalError({ message: `${url} has sha256 ${actual}, expected ${pin.sha256}` });
301
+ if (actual !== pin.sha256) return yield* new FormalError({ message: `${source} has sha256 ${actual}, expected ${pin.sha256}` });
302
+ yield* fs.writeFile(temp, bytes);
294
303
  return yield* fs.rename(temp, file);
295
304
  }));
296
305
  jars.push(file);
package/dist/starts.mjs CHANGED
@@ -325,6 +325,7 @@ const Descendant = Schema.Struct({ workflow_run: Schema.Struct({
325
325
  workflows: Schema.Union([Schema.String, Schema.Array(Schema.String)]),
326
326
  types: Schema.optionalKey(Schema.Union([Schema.String, Schema.Array(Schema.String)]))
327
327
  }) });
328
+ const LabelRequest = Schema.Struct({ types: Schema.NonEmptyArray(Schema.Literal("labeled")) });
328
329
  const dynamic = (value) => {
329
330
  try {
330
331
  return JSON.stringify(value).includes("${{");
@@ -332,6 +333,23 @@ const dynamic = (value) => {
332
333
  return true;
333
334
  }
334
335
  };
336
+ const startsOnPr = (events) => {
337
+ if (typeof events === "string") return [
338
+ "pull_request",
339
+ "pull_request_target",
340
+ "push"
341
+ ].includes(events);
342
+ if (Array.isArray(events)) return events.some((event) => startsOnPr(event));
343
+ if (events === void 0) return false;
344
+ if ("pull_request_target" in events) return true;
345
+ if ("pull_request" in events && !Schema.is(LabelRequest)(events.pull_request)) return true;
346
+ if (!("push" in events)) return false;
347
+ const push = events.push;
348
+ if (typeof push !== "object" || push === null) return true;
349
+ if ("branches-ignore" in push) return true;
350
+ if ("branches" in push) return !Array.isArray(push.branches) || push.branches.some((branch) => branch !== "main");
351
+ return !("tags" in push || "tags-ignore" in push);
352
+ };
335
353
  const boatJobFindings = (files) => {
336
354
  const findings = [];
337
355
  const workflows = [];
@@ -409,6 +427,7 @@ const boatJobFindings = (files) => {
409
427
  };
410
428
  for (const entry of workflows) {
411
429
  const total = count(entry, [], true);
430
+ if (total > 0 && startsOnPr(entry.workflow.on)) findings.push(`${entry.path}: a pull_request or PR-branch push starts ${total} Boat jobs; PR ready starts on request`);
412
431
  if (total > 2) findings.push(`${entry.path}: closure starts ${total} Boat jobs, limit 2`);
413
432
  }
414
433
  return [...new Set(findings)];
Binary file
@@ -0,0 +1,24 @@
1
+ MIT License
2
+
3
+ Copyright (c) 199? HP Corporation
4
+ Copyright (c) 2003 Microsoft Corporation
5
+ Copyright (c) 2023 Linux Foundation
6
+
7
+ Permission is hereby granted, free of charge, to any person obtaining a copy
8
+ of this software and associated documentation files (the "Software"), to deal
9
+ in the Software without restriction, including without limitation the rights
10
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
11
+ copies of the Software, and to permit persons to whom the Software is
12
+ furnished to do so, subject to the following conditions:
13
+
14
+ The above copyright notice and this permission notice shall be included in all
15
+ copies or substantial portions of the Software.
16
+
17
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
18
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
19
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
20
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
21
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
22
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
23
+ SOFTWARE.
24
+
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@milkenjoyer/toolchain",
3
- "version": "0.17.1",
3
+ "version": "0.18.0",
4
4
  "repository": {
5
5
  "type": "git",
6
6
  "url": "git+https://github.com/birbprophet/agent-kit.git",
@@ -16,6 +16,7 @@
16
16
  "files": [
17
17
  "dist",
18
18
  "STARTS.md",
19
+ "formal-tools/tla2tools-1.8.0.jar",
19
20
  "licenses",
20
21
  "node-version",
21
22
  "renovate.json",
package/src/formal/tla.ts CHANGED
@@ -1,5 +1,3 @@
1
- import { createHash } from "node:crypto";
2
-
3
1
  import * as Clock from "effect/Clock";
4
2
  import * as Config from "effect/Config";
5
3
  import * as Context from "effect/Context";
@@ -16,6 +14,7 @@ import * as Stream from "effect/Stream";
16
14
 
17
15
  import { fromXml } from "./semantics.ts";
18
16
  import type { Analysis } from "./specs.ts";
17
+ import { digest, packagedTools, pins as packagedPins } from "./tools.ts";
19
18
 
20
19
  export class FormalError extends Data.TaggedError("FormalError")<{
21
20
  readonly message: string;
@@ -51,14 +50,7 @@ type Formatted =
51
50
  | { readonly _tag: "Failed"; readonly output: string };
52
51
 
53
52
  const pins = [
54
- {
55
- file: "tla2tools-1.8.0.jar",
56
- urls: [
57
- "https://github.com/tlaplus/tlaplus/releases/download/v1.8.0/tla2tools.jar",
58
- "https://api.github.com/repos/tlaplus/tlaplus/releases/assets/718777374",
59
- ],
60
- sha256: "e1f11b75c4b5bc4478ba0ac5cb6ae28e40a01b0016bc33e0aa97da22dfdbcd7f",
61
- },
53
+ ...packagedPins,
62
54
  {
63
55
  file: "CommunityModules-deps-202611060952.jar",
64
56
  urls: [
@@ -68,12 +60,11 @@ const pins = [
68
60
  sha256: "a3b27c40f1fb5085f30c6ead37e918457f8cfc62c1e50a1dc668ef592ad2b5fb",
69
61
  },
70
62
  ];
63
+
71
64
  const error = (cause: unknown) =>
72
65
  new FormalError({
73
66
  message: cause instanceof Error ? cause.message : String(cause),
74
67
  });
75
- const digest = (bytes: Uint8Array) =>
76
- createHash("sha256").update(bytes).digest("hex");
77
68
  const messages = (output: string): ToolMessage[] =>
78
69
  [
79
70
  ...output.matchAll(
@@ -116,7 +107,7 @@ const make = Effect.gen(function* () {
116
107
  const actual = digest(yield* fs.readFile(file));
117
108
  if (actual !== pin.sha256)
118
109
  return yield* new FormalError({
119
- message: `${file} has sha256 ${actual}, expected ${pin.sha256}; delete it to refetch`,
110
+ message: `${file} has sha256 ${actual}, expected ${pin.sha256}; delete it to restore the pinned JAR`,
120
111
  });
121
112
  } else {
122
113
  yield* Effect.scoped(
@@ -126,19 +117,21 @@ const make = Effect.gen(function* () {
126
117
  prefix: `.${pin.file}.`,
127
118
  suffix: ".part",
128
119
  });
129
- const { url, bytes } = yield* Effect.gen(function* () {
120
+ const { source, bytes } = yield* Effect.gen(function* () {
121
+ if (!("urls" in pin)) {
122
+ const source = path.join(packagedTools, pin.file);
123
+ return { source, bytes: yield* fs.readFile(source) };
124
+ }
130
125
  const failures: string[] = [];
131
- for (const url of pin.urls) {
132
- const result = yield* HttpClient.get(url, {
126
+ for (const source of pin.urls) {
127
+ const result = yield* HttpClient.get(source, {
133
128
  headers: { Accept: "application/octet-stream" },
134
129
  }).pipe(
135
130
  Effect.flatMap((response) =>
136
131
  response.status === 200
137
132
  ? response.arrayBuffer.pipe(Effect.mapError(error))
138
133
  : Effect.fail(
139
- new FormalError({
140
- message: `HTTP ${response.status}`,
141
- })
134
+ new FormalError({ message: `HTTP ${response.status}` })
142
135
  )
143
136
  ),
144
137
  Effect.map((buffer) => new Uint8Array(buffer)),
@@ -147,17 +140,17 @@ const make = Effect.gen(function* () {
147
140
  Effect.result
148
141
  );
149
142
  if (Result.isSuccess(result))
150
- return { url, bytes: result.success };
151
- failures.push(`${url}: ${error(result.failure).message}`);
143
+ return { source, bytes: result.success };
144
+ failures.push(`${source}: ${error(result.failure).message}`);
152
145
  }
153
146
  return yield* new FormalError({ message: failures.join("; ") });
154
147
  });
155
- yield* fs.writeFile(temp, bytes);
156
148
  const actual = digest(bytes);
157
149
  if (actual !== pin.sha256)
158
150
  return yield* new FormalError({
159
- message: `${url} has sha256 ${actual}, expected ${pin.sha256}`,
151
+ message: `${source} has sha256 ${actual}, expected ${pin.sha256}`,
160
152
  });
153
+ yield* fs.writeFile(temp, bytes);
161
154
  return yield* fs.rename(temp, file);
162
155
  })
163
156
  );
@@ -0,0 +1,16 @@
1
+ import { createHash } from "node:crypto";
2
+ import { fileURLToPath } from "node:url";
3
+
4
+ export const pins = [
5
+ {
6
+ file: "tla2tools-1.8.0.jar",
7
+ sha256: "e1f11b75c4b5bc4478ba0ac5cb6ae28e40a01b0016bc33e0aa97da22dfdbcd7f",
8
+ },
9
+ ];
10
+
11
+ export const packagedTools = fileURLToPath(
12
+ new URL("../../formal-tools/", import.meta.url)
13
+ );
14
+
15
+ export const digest = (bytes: Uint8Array): string =>
16
+ createHash("sha256").update(bytes).digest("hex");
@@ -36,6 +36,9 @@ const Descendant = Schema.Struct({
36
36
  ),
37
37
  }),
38
38
  });
39
+ const LabelRequest = Schema.Struct({
40
+ types: Schema.NonEmptyArray(Schema.Literal("labeled")),
41
+ });
39
42
  type WorkflowFile = readonly [path: string, text: string];
40
43
  type Parsed = {
41
44
  readonly path: string;
@@ -50,6 +53,27 @@ const dynamic = (value: unknown): boolean => {
50
53
  }
51
54
  };
52
55
 
56
+ const startsOnPr = (events: typeof Workflow.Type.on): boolean => {
57
+ if (typeof events === "string")
58
+ return ["pull_request", "pull_request_target", "push"].includes(events);
59
+ if (Array.isArray(events))
60
+ return events.some((event: string) => startsOnPr(event));
61
+ if (events === undefined) return false;
62
+ if ("pull_request_target" in events) return true;
63
+ if ("pull_request" in events && !Schema.is(LabelRequest)(events.pull_request))
64
+ return true;
65
+ if (!("push" in events)) return false;
66
+ const push = events.push;
67
+ if (typeof push !== "object" || push === null) return true;
68
+ if ("branches-ignore" in push) return true;
69
+ if ("branches" in push)
70
+ return (
71
+ !Array.isArray(push.branches) ||
72
+ push.branches.some((branch: unknown) => branch !== "main")
73
+ );
74
+ return !("tags" in push || "tags-ignore" in push);
75
+ };
76
+
53
77
  export const boatJobFindings = (
54
78
  files: ReadonlyArray<WorkflowFile>
55
79
  ): ReadonlyArray<string> => {
@@ -162,6 +186,10 @@ export const boatJobFindings = (
162
186
  };
163
187
  for (const entry of workflows) {
164
188
  const total = count(entry, [], true);
189
+ if (total > 0 && startsOnPr(entry.workflow.on))
190
+ findings.push(
191
+ `${entry.path}: a pull_request or PR-branch push starts ${total} Boat jobs; PR ready starts on request`
192
+ );
165
193
  if (total > BOAT_JOBS_PER_RUN)
166
194
  findings.push(
167
195
  `${entry.path}: closure starts ${total} Boat jobs, limit ${BOAT_JOBS_PER_RUN}`