bend-lint 0.2.1 → 0.3.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.
@@ -0,0 +1,82 @@
1
+ # Directives: the `# bend-lint:` comments that disable or expect findings.
2
+ import Base
3
+ import bend-lint-api@0.3.0.0/linter/api/spec.bend as Lint
4
+
5
+ # A comment: where it is (code points), its line (from 0), whether code comes before it on its line, and its text
6
+ # after the #.
7
+ type Comment is Data:
8
+ Comment{beg: U32, end: U32, line: U32, trailing: Bool, body: String}
9
+
10
+ # A text's comments, in order, and, for each of its lines, whether it holds code.
11
+ type Scanned is Data:
12
+ Scanned{comments: List<&2, Comment>, lines: List<&2, Bool>}
13
+
14
+ # What a directive does: disable findings, or expect them.
15
+ law Action:
16
+ Data
17
+
18
+ # How far a directive reaches: the whole file, from a begin to its end, the next line with code, or its own line.
19
+ law Scope:
20
+ Data
21
+
22
+ # A directive's word: what it does, and how far (`disable-next`).
23
+ type Keyword is Data:
24
+ Keyword{action: Action, scope: Scope}
25
+
26
+ # What a directive names: a rule, and the severity it pins, as written.
27
+ type Target is Data:
28
+ Target{rule: String, pinned: Maybe<&2, String>}
29
+
30
+ # A directive as written, before its severity and rule are checked: its reasons are the texts after each `--`.
31
+ type Draft is Data:
32
+ Draft{keyword: Keyword, target: Target, reasons: List<&2, String>}
33
+
34
+ # A file's findings after its directives: those that stay, then the findings about its directives, and those a
35
+ # directive covers.
36
+ type Suppressed is Data:
37
+ Suppressed{kept: List<&2, Lint.Found>, suppressed: List<&2, Lint.Found>}
38
+
39
+ # A linted file.
40
+ law Linted:
41
+ Data
42
+
43
+ # The file at `path`, whose text is `text`, linted: `known` holds the ids of the rules there are, and `ran` those of
44
+ # the rules that ran on it. A rule turned off did not run, so its directives are never unused.
45
+ law Linted.of:
46
+ for path: String
47
+ for text: String
48
+ for known: List<&2, String>
49
+ for ran: List<&2, String>
50
+ Linted
51
+
52
+ # The comments of `text`, and which of its lines hold code.
53
+ law Scan.of:
54
+ for text: String
55
+ Scanned
56
+
57
+ # How `a` is written in a directive.
58
+ law Action.show:
59
+ for a: Action
60
+ String
61
+
62
+ # How `s` is written in a directive, after the dash.
63
+ law Scope.show:
64
+ for s: Scope
65
+ String
66
+
67
+ # What a comment's text says, if it says bend-lint:: a directive's draft, if it is one.
68
+ law Draft.read:
69
+ for +body: String
70
+ Maybe<&2, Maybe<&2, Draft>>
71
+
72
+ # Whether `text` has a directive's mark, "bend-lint:". Only a 'b' starts a comparison, so it is one pass.
73
+ law has_mark:
74
+ for text: String
75
+ for found: Bool
76
+ Bool
77
+
78
+ # The findings `founds` of the file `linted`, after its directives; a file with none keeps them all.
79
+ law apply:
80
+ for +linted: Linted
81
+ for founds: List<&2, Lint.Found>
82
+ Suppressed
@@ -4,20 +4,20 @@
4
4
  // about Bend files over local TCP until the program exits (Seam in cli.bend sends them, and reads
5
5
  // the answers). A check's answer is the linter's program, as Bend's parser and checker give it:
6
6
  // each file's syntax tree, and, for facts, what the checker found on its nodes (Lint.Source, in
7
- // lint.bend). When Bend's checker is Bend, glue in Bend makes the same program, and the code here
7
+ // the rule API's spec). When Bend's checker is Bend, glue in Bend makes the same program, and the code here
8
8
  // that knows bend.ts goes, so mutation and any optimization are fair here. Node 24.2 or later runs
9
9
  // a built program too, but a large program needs --max-old-space-size=8192.
10
10
  //
11
11
  // It loads a copy of bend.ts in which each TRACED function reports its calls: the parser's give
12
12
  // each file's syntax before lowering; the checker's judgments, on each def's elaborated body, give
13
- // the facts. What a rule sees is lint.bend's contract, not Bend's: when the checker is Bend, its
13
+ // the facts. What a rule sees is the rule API's contract, not Bend's: when the checker is Bend, its
14
14
  // glue makes each part from what that checker gives, or bend-lint computes it.
15
15
  //
16
16
  // | What a rule sees | Now, from | Risk |
17
17
  // | ------------------------------ | --------------------------------- | ------ |
18
18
  // | spans, names, binders, targets | the parser | low |
19
19
  // | types: show, same, normal | term_show, term_compare, term_snf | low |
20
- // | declarations and their uses | lint.bend, our own code | none |
20
+ // | declarations and their uses | the rule API, our own code | none |
21
21
  // | syntax before lowering | the parser's calls (KEPT) | medium |
22
22
  // | quantity, used | the judgments (JUDGED) | high |
23
23
  // | which node a fact is on | span values (`isNodeOf`) | medium |
@@ -31,7 +31,8 @@
31
31
  // Imports
32
32
  // =======
33
33
 
34
- import { spawn } from "node:child_process";
34
+ import { execFile, spawn, spawnSync } from "node:child_process";
35
+ import { createHash } from "node:crypto";
35
36
  import { once } from "node:events";
36
37
  import * as nodeFs from "node:fs";
37
38
  import * as net from "node:net";
@@ -44,31 +45,28 @@ import type { Ann, Body, Book, Ctx, HTerm, LTerm, Patt, Quant, Span, TLD } from
44
45
  import type * as BendModule from "bend2/bend.ts";
45
46
 
46
47
  import pkg from "../../package.json" with { type: "json" };
47
- import {
48
- getBendCli,
49
- getBendLintCacheDir,
50
- getBendVersionNote,
51
- getClang,
52
- JAVASCRIPT_NOTE,
53
- PINNED_BEND_NOTE,
54
- tryGetBend2SourceUrl,
55
- } from "../shared/bend2.ts";
56
- import { unwrap } from "../shared/result.ts";
57
- import {
58
- getCommandOutcome,
59
- getErrorMessageFromUnknown,
60
- getPathWithForwardSlashes,
61
- getSha256Hex,
62
- tryGet,
63
- tryGetJson,
64
- tryWriteJsonAtomically,
65
- writeFileAtomically,
66
- writeNewFileAtomically,
67
- } from "../shared/utils.ts";
68
48
 
69
49
  // Types
70
50
  // =====
71
51
 
52
+ // A value under OK, or an error under ERROR, for callers that would rather
53
+ // branch than catch. From iara's src/utils/result.ts, trimmed to what
54
+ // bend-lint uses.
55
+
56
+ type ErrorShape<
57
+ T extends string = string,
58
+ U extends Record<string, unknown> = Record<string, unknown>,
59
+ > = string | Error | { type: T; [ERROR_METADATA]?: U };
60
+
61
+ type ResultOk<T> = Readonly<{ readonly [OK]: T }>;
62
+
63
+ type ResultErr<E extends ErrorShape = ErrorShape> = Readonly<{ readonly [ERROR]: E }>;
64
+
65
+ type Result<T, E extends ErrorShape = ErrorShape> = ResultOk<T> | ResultErr<E>;
66
+
67
+ // How a command ended: its exit code, and what it printed.
68
+ type Outcome = { code: number; out: string; err: string };
69
+
72
70
  type Bend = typeof BendModule;
73
71
 
74
72
  type Loaded = { Bend: Bend; base: Book };
@@ -207,6 +205,54 @@ type Rules = { ids: string[]; packages: Map<string, string> };
207
205
  // Constants
208
206
  // =========
209
207
 
208
+ const OK = "OK" as const;
209
+
210
+ const ERROR = "ERROR" as const;
211
+
212
+ const ERROR_METADATA = "ERROR_METADATA" as const;
213
+
214
+ // The Bend bend-lint checks and builds with, bend2: a pinned commit on GitHub,
215
+ // downloaded once, whatever bend is installed. Bend's releases do not run on
216
+ // Windows, so there it is a commit of a fork that does, and bend-lint says so
217
+ // on each run.
218
+
219
+ // The Bend bend-lint uses, as `<owner>/<repo>/<ref>` on GitHub: Bend's newest
220
+ // release this repo's checks passed with (src/meta/sync-bend.ts moves it), or,
221
+ // on Windows, a commit of a fork that runs there.
222
+ const PINNED_BEND: string = process.platform === "win32" ? pkg.bendWindows : pkg.bendRelease;
223
+
224
+ // What bend-lint says on each run on Windows, where it uses the fork.
225
+ const PINNED_BEND_NOTE: string | undefined =
226
+ process.platform === "win32"
227
+ ? "bend-lint: on Windows, bend-lint uses a fork of Bend, as Bend's releases do not run there: https://github.com/" +
228
+ pkg.bendWindows.replace(/^([^/]+\/[^/]+)\//, "$1/tree/")
229
+ : undefined;
230
+
231
+ // bend-lint's cache: the downloaded Bend, and what the server keeps.
232
+ const getBendLintCacheDir = (): URL =>
233
+ url.pathToFileURL(
234
+ nodePath.join(
235
+ process.env.XDG_CACHE_HOME ??
236
+ (process.platform === "win32"
237
+ ? (process.env.LOCALAPPDATA ?? nodePath.join(os.homedir(), "AppData", "Local"))
238
+ : nodePath.join(os.homedir(), ".cache")),
239
+ "bend-lint",
240
+ ) + nodePath.sep,
241
+ );
242
+
243
+ // What bend-lint says on each run whose rules it built as JavaScript, as it
244
+ // found no clang (see getClang).
245
+ const JAVASCRIPT_NOTE =
246
+ "bend-lint: found no clang 14 or newer, so the rules run as JavaScript, about 3 to 8 times slower; install clang to speed them up";
247
+
248
+ // What bend-lint says on a run whose rules it built as JavaScript while clang builds them in the
249
+ // background (see getBuiltProgram).
250
+ const BUILDING_NOTE =
251
+ "bend-lint: the rules run as JavaScript this time, about 3 to 8 times slower, while clang builds them in the background";
252
+
253
+ // How the line starts that says the installed bend is another version.
254
+ const VERSION_NOTE = "bend-lint: your bend is ";
255
+
210
256
  const ESCAPES: Record<string, string> = { "\\": "\\\\", "\t": "\\t", "\n": "\\n" };
211
257
 
212
258
  const SERVER_CACHE_DIR = new URL("server/", getBendLintCacheDir());
@@ -217,7 +263,7 @@ const PROGRAMS_DIR = url.fileURLToPath(new URL("programs/", SERVER_CACHE_DIR));
217
263
 
218
264
  // Where the programs bend-lint writes (one per list of rules) live: Bend imports only relative
219
265
  // paths of plain names, so they live beside cli.bend, which they import.
220
- export const BUILD = url.fileURLToPath(new URL("build/", import.meta.url));
266
+ const BUILD = url.fileURLToPath(new URL("build/", import.meta.url));
221
267
 
222
268
  // The config, and the folder of rules beside it.
223
269
  const CONFIG = "bend-lint.json";
@@ -226,7 +272,7 @@ const RULES = "bend-lint-rules";
226
272
  // bend-lint's version, as its BendHub packages have it: with `.0` added.
227
273
  const HUB_VERSION = `${pkg.version}.0`;
228
274
 
229
- // The rule API, as rules import it from BendHub: src/linter/lint.bend and the files it imports, at
275
+ // The rule API, as rules import it from BendHub: src/linter/api/ and the files it imports, at
230
276
  // their paths from src/, in the package bend-lint-api, at bend-lint's version (see ship.ts).
231
277
  export const API = `bend-lint-api@${HUB_VERSION}`;
232
278
 
@@ -237,9 +283,10 @@ export const DEFAULTS = `${DEFAULTS_NAME}@${HUB_VERSION}`;
237
283
 
238
284
  // The ids of bend-lint's own rules in DEFAULTS, as the npm package lists them (see ship.ts); none
239
285
  // in this repo, which runs them from bend-lint-rules/.
240
- const DEFAULT_IDS = tryGetJson(url.fileURLToPath(new URL("defaults.json", import.meta.url))) as
241
- | string[]
242
- | undefined;
286
+ const DEFAULT_IDS_FILE = url.fileURLToPath(new URL("defaults.json", import.meta.url));
287
+ const DEFAULT_IDS = nodeFs.existsSync(DEFAULT_IDS_FILE)
288
+ ? (JSON.parse(nodeFs.readFileSync(DEFAULT_IDS_FILE, "utf8")) as string[])
289
+ : undefined;
243
290
 
244
291
  // A path Bend imports: up, then names (letters, digits, _ and -).
245
292
  const PLAIN = /^(\.\.\/)*([A-Za-z_][\w-]*\/)*[A-Za-z_][\w-]*\.bend$/;
@@ -263,8 +310,10 @@ const INIT_CONFIG =
263
310
  2,
264
311
  ) + "\n";
265
312
 
266
- // An import by a relative path: of a .bend file, or, quoted, of an effect's.
267
- export const IMPORT = /^\s*import\s+"?(\.\.?\/[^\s"]+)/gm;
313
+ // An import of a local file, by any path Bend takes (relative, bare or absolute): of a .bend file,
314
+ // or, quoted, of an effect's; but not Base, nor a file from BendHub (`name@version/...`,
315
+ // `0x<hash>/...`).
316
+ export const IMPORT = /^\s*import\s+"?(?!Base(?![\w./]))(?![^\s"/]*@)(?!0x[0-9a-f]+\/)([^\s"]+)/gm;
268
317
 
269
318
  // A drive letter that starts a path with `/`.
270
319
  const DRIVE = /^[A-Za-z]:(?=\/)/;
@@ -439,9 +488,227 @@ const USED = 24 * 60 * 60 * 1000;
439
488
  // A prune stats each entry of its folder (about 0.1 s for 9000 entries), so not on every run.
440
489
  const PRUNE_EVERY = 24 * 60 * 60 * 1000;
441
490
 
491
+ // How long a native build that a run started in the background may take before another run starts
492
+ // it again (as when the first one stopped).
493
+ const BUILDING = 10 * 60 * 1000;
494
+
442
495
  // Functions
443
496
  // =========
444
497
 
498
+ const ok = <T>(value: T): ResultOk<T> => ({ [OK]: value });
499
+
500
+ export const error = <E extends ErrorShape>(value: E): ResultErr<E> => ({ [ERROR]: value });
501
+
502
+ // The value, or a throw: an Error as it is, a string as an Error's message,
503
+ // and a typed error as an Error with its metadata's message (else its
504
+ // type), caused by the typed error.
505
+ export const unwrap = <T, E extends ErrorShape>(res: Result<T, E>): T => {
506
+ if (OK in res) {
507
+ return res[OK];
508
+ }
509
+ const e = res[ERROR];
510
+ if (e instanceof Error) {
511
+ throw e;
512
+ }
513
+ if (typeof e === "string") {
514
+ throw new Error(e);
515
+ }
516
+ const said = e[ERROR_METADATA]?.message;
517
+ throw new Error(typeof said === "string" ? said : e.type, { cause: e });
518
+ };
519
+
520
+ // How `cmd` ends, run in `cwd`, with `env` added to this process's environment.
521
+ const getCommandOutcome = async (
522
+ cmd: string[],
523
+ cwd: string,
524
+ env: Record<string, string> = {},
525
+ input?: string,
526
+ ): Promise<Outcome> => {
527
+ const child = Bun.spawn(cmd, {
528
+ cwd,
529
+ env: { ...process.env, ...env },
530
+ stdin: input === undefined ? "ignore" : new TextEncoder().encode(input),
531
+ stdout: "pipe",
532
+ stderr: "pipe",
533
+ });
534
+ const [code, out, err] = await Promise.all([
535
+ child.exited,
536
+ new Response(child.stdout).text(),
537
+ new Response(child.stderr).text(),
538
+ ]);
539
+ return { code, out, err };
540
+ };
541
+
542
+ const getErrorMessageFromUnknown = (e: unknown): string =>
543
+ e instanceof Error ? e.message : String(e);
544
+
545
+ export const getPathWithForwardSlashes = (p: string): string => p.split(nodePath.sep).join("/");
546
+
547
+ // f's value, or undefined if it throws.
548
+ const tryGet = <T>(f: () => T): T | undefined => {
549
+ try {
550
+ return f();
551
+ } catch {
552
+ return undefined;
553
+ }
554
+ };
555
+
556
+ export const getSha256Hex = (text: string): string =>
557
+ createHash("sha256").update(text).digest("hex");
558
+
559
+ // Writes `text` to `file` whole or not at all: to a file beside it, in the
560
+ // file's folder, made if need be, then renamed over it.
561
+ export const writeFileAtomically = (file: string, text: string): void => {
562
+ nodeFs.mkdirSync(nodePath.dirname(file), { recursive: true });
563
+ const temp = `${file}.${process.pid}.${Date.now()}`;
564
+ nodeFs.writeFileSync(temp, text);
565
+ try {
566
+ nodeFs.renameSync(temp, file);
567
+ } catch (e) {
568
+ nodeFs.rmSync(temp, { force: true });
569
+ throw e;
570
+ }
571
+ };
572
+
573
+ // Writes `text` to `file` whole, unless `file` is there: a file that runs at once may each write,
574
+ // with the same text. On Windows, a rename over a file that another process has open fails; a run
575
+ // that loses that race keeps the file it found.
576
+ const writeNewFileAtomically = (file: string, text: string): void => {
577
+ try {
578
+ if (!nodeFs.existsSync(file)) {
579
+ writeFileAtomically(file, text);
580
+ }
581
+ } catch (e) {
582
+ if (!nodeFs.existsSync(file)) {
583
+ throw e;
584
+ }
585
+ }
586
+ };
587
+
588
+ // The JSON value in `file`, or undefined if it cannot be read.
589
+ const tryGetJson = (file: string): unknown =>
590
+ tryGet(() => JSON.parse(nodeFs.readFileSync(file, "utf8")) as unknown);
591
+
592
+ // Writes `value` to `file` as JSON, whole or not at all; a write that fails is skipped.
593
+ const tryWriteJsonAtomically = (file: string, value: unknown): void => {
594
+ tryGet(() => writeFileAtomically(file, JSON.stringify(value)));
595
+ };
596
+
597
+ // The folder at its real path, as a file: URL that ends in `/`, so
598
+ // `new URL("file", folder)` finds a file in it. An error if `dir` cannot be
599
+ // resolved.
600
+ const tryGetUrlFromFolderPathOrUrl = (dir: string | URL): Result<URL, string> => {
601
+ try {
602
+ return ok(url.pathToFileURL(nodeFs.realpathSync(dir) + nodePath.sep));
603
+ } catch (e) {
604
+ return error(getErrorMessageFromUnknown(e));
605
+ }
606
+ };
607
+
608
+ // The clang Bend builds native programs with, if there is one, as Bend's
609
+ // cc_find picks it (main.ts): the first of $CC, clang, each clang-NN on PATH
610
+ // (the newest first), and on Windows where LLVM's installer puts it, that is
611
+ // clang 14 or newer.
612
+ export const getClang = (): string | undefined => {
613
+ const getFileNames = (dir: string): string[] => tryGet(() => nodeFs.readdirSync(dir)) ?? [];
614
+ const numbered = [
615
+ ...new Set(
616
+ (process.env.PATH ?? "")
617
+ .split(nodePath.delimiter)
618
+ .flatMap(getFileNames)
619
+ .filter((f) => /^clang-\d+$/.test(f)),
620
+ ),
621
+ ].sort((a, b) => Number(b.slice(6)) - Number(a.slice(6)));
622
+ return [
623
+ ...(process.env.CC === undefined ? [] : [process.env.CC]),
624
+ "clang",
625
+ ...numbered,
626
+ ...(process.platform === "win32"
627
+ ? [nodePath.join(process.env.ProgramFiles ?? "C:\\Program Files", "LLVM", "bin", "clang.exe")]
628
+ : []),
629
+ ].find((cc) => {
630
+ const version = /^(?:Apple )?(?:\w+ )?clang version (\d+)/m.exec(
631
+ spawnSync(cc, ["--version"], { encoding: "utf8" }).stdout ?? "",
632
+ )?.[1];
633
+ return version !== undefined && Number(version) >= 14;
634
+ });
635
+ };
636
+
637
+ // The line bend-lint prints when the `bend` on PATH is another version than
638
+ // the Bend in the bend2 folder `dir`, which bend-lint checks and builds with;
639
+ // undefined if it is the same, or if none is installed or `bend version` names
640
+ // no version. It asks `bend version` on each run, as the `bend` on PATH can be
641
+ // a script that runs a checkout, whose version changes while the script does
642
+ // not. It runs by name: Windows runs a bend.cmd only that way.
643
+ const getBendVersionNote = async (dir: URL): Promise<string | undefined> => {
644
+ const version = await new Promise<string | undefined>((resolve) => {
645
+ const resolveVersion = (e: Error | null, stdout: string): void =>
646
+ resolve(/^bend (\d+\.\d+\.\d+)(?:\r?\n|$)/.exec(e === null ? stdout : "")?.[1]);
647
+ try {
648
+ execFile("bend", ["version"], { encoding: "utf8", timeout: 10_000 }, resolveVersion);
649
+ } catch (e) {
650
+ resolveVersion(e as Error, "");
651
+ }
652
+ });
653
+ const pinned = /^const VERSION = "([^"]+)";$/m.exec(
654
+ nodeFs.readFileSync(new URL("main.ts", dir), "utf8"),
655
+ )?.[1];
656
+ return version === undefined || pinned === undefined || version === pinned
657
+ ? undefined
658
+ : `${VERSION_NOTE}${version}, and bend-lint checks with Bend ${pinned}; the two can disagree on a few files`;
659
+ };
660
+
661
+ // How to run the Bend in the bend2 folder `dir`: its CLI (main.ts) on this Bun,
662
+ // in an environment that keeps it from asking bend-lang.com, once a day, for a
663
+ // newer release (see main.ts).
664
+ export const getBendCli = (dir: URL): { cmd: string[]; env: Record<string, string> } => ({
665
+ cmd: [process.execPath, url.fileURLToPath(new URL("main.ts", dir))],
666
+ env: { BEND_NO_TELEMETRY: "1" },
667
+ });
668
+
669
+ // bend2 at `pin` (`<owner>/<repo>/<ref>` on GitHub), kept in <cache>/<pin>/bend2.
670
+ // Each file goes in whole, base.bend last, and none is ever replaced (see
671
+ // writeNewFileAtomically): runs at once may each download, while others read
672
+ // the files.
673
+ const getDownloadedBend = async (pin: string): Promise<URL> => {
674
+ if (!/^[\w.-]+\/[\w.-]+\/[\w.-]+$/.test(pin)) {
675
+ throw new Error("not a GitHub <owner>/<repo>/<ref>: " + pin);
676
+ }
677
+ const dir = new URL(pin + "/bend2/", getBendLintCacheDir());
678
+ // What a download holds besides base.bend and the effs/ files Base imports.
679
+ const FILES = ["bend.ts", "comp.ts", "main.ts", "safe.ts"];
680
+ const isMissing = (file: string): boolean => !nodeFs.existsSync(new URL(file, dir));
681
+ if (![...FILES, "base.bend"].some(isMissing)) {
682
+ return dir;
683
+ }
684
+ const getFetchedFile = async (file: string): Promise<[string, string]> => {
685
+ const res = await fetch(`https://raw.githubusercontent.com/${pin}/bend2/${file}`, {
686
+ signal: AbortSignal.timeout(30_000),
687
+ });
688
+ if (!res.ok) {
689
+ throw new Error(`GitHub answered ${res.status} for bend2/${file}`);
690
+ }
691
+ return [file, await res.text()];
692
+ };
693
+ const base = await getFetchedFile("base.bend");
694
+ const effs = new Set([...base[1].matchAll(/^\s*import "\.\/(effs\/[^"]+)"/gm)].map((m) => m[1]));
695
+ const odd = [...effs].find((f) => !/^effs\/[\w.-]+$/.test(f));
696
+ if (odd !== undefined) {
697
+ throw new Error("base.bend imports " + odd + ", which is not a plain file in effs/");
698
+ }
699
+ [...(await Promise.all([...effs, ...FILES].map(getFetchedFile))), base].forEach(([file, body]) =>
700
+ writeNewFileAtomically(url.fileURLToPath(new URL(file, dir)), body),
701
+ );
702
+ console.error("bend-lint: downloaded bend " + pin + " to " + url.fileURLToPath(dir));
703
+ return dir;
704
+ };
705
+
706
+ // The bend2 folder to load: the pinned Bend's, downloaded if it is not yet.
707
+ export const tryGetBend2SourceUrl = async (): Promise<Result<URL, string>> =>
708
+ getDownloadedBend(PINNED_BEND).then(tryGetUrlFromFolderPathOrUrl, (e: unknown) =>
709
+ error(`could not download bend ${PINNED_BEND} (${getErrorMessageFromUnknown(e)})`),
710
+ );
711
+
445
712
  const getEscapedField = (text: string): string => text.replace(/[\\\t\n]/g, (c) => ESCAPES[c]);
446
713
 
447
714
  const getUnescapedField = (text: string): string =>
@@ -1057,7 +1324,7 @@ const getDeclarationTrees = (b: Builder, [head, ...frames]: Frame[]): Tree[] =>
1057
1324
  : [getDeclarationAt(b, "Definition", name, getDeclarationParts(b, head.kids))];
1058
1325
  }
1059
1326
  const syntax: Syntax =
1060
- head.name === "parse_fresh" && head.args[2] === b.book.ctrs
1327
+ head.name === "parse_fresh" && head.args[2] === "ctrs"
1061
1328
  ? "Constructor"
1062
1329
  : b.book.tlds[head.out as string]?.$ === "ADT"
1063
1330
  ? "Datatype"
@@ -1734,19 +2001,13 @@ export const getNativePath = (source: string, dir: URL): string => {
1734
2001
  return nodePath.join(PROGRAMS_DIR, name + (process.platform === "win32" ? ".exe" : ""));
1735
2002
  };
1736
2003
 
1737
- // The program the rules program `source` builds to, with the Bend in the bend2 folder `dir`:
1738
- // native, if clang can build it, else JavaScript, until clang can. A build is kept, and used
1739
- // again until a file the program imports, or the Bend that builds it, changes; its use keeps it
1740
- // from prune (see USED). It goes to a folder of its own first, so a kept build is never partial,
1741
- // and runs that build one program at once share one build.
1742
- export const getBuiltProgram = async (source: string, dir: URL): Promise<string> => {
1743
- const file = nodePath.resolve(source);
2004
+ // The build at `exe` (native, or JavaScript if it ends in .js) of the rules program at `file`, with
2005
+ // the Bend in the bend2 folder `dir`. A build is kept, and used again until a file the program
2006
+ // imports, or the Bend that builds it, changes; its use keeps it from prune (see USED). It goes to
2007
+ // a folder of its own first, so a kept build is never partial, and runs that build one program at
2008
+ // once share one build.
2009
+ const getBuild = async (file: string, exe: string, dir: URL): Promise<string> => {
1744
2010
  const from = nodePath.dirname(file);
1745
- const native = getNativePath(source, dir);
1746
- const exe =
1747
- nodeFs.existsSync(native) || getClang() !== undefined
1748
- ? native
1749
- : native.replace(/(\.exe)?$/, ".js");
1750
2011
  const kept = nodeFs.statSync(exe, { throwIfNoEntry: false });
1751
2012
  if (kept !== undefined) {
1752
2013
  if (Date.now() - kept.mtimeMs > USED) {
@@ -1762,7 +2023,7 @@ export const getBuiltProgram = async (source: string, dir: URL): Promise<string>
1762
2023
  const bend = getBendCli(dir);
1763
2024
  const ran = await getCommandOutcome([...bend.cmd, file, "-o", out], from, bend.env);
1764
2025
  if (ran.code !== 0) {
1765
- throw new Error(`could not build ${source}:\n${ran.out}${ran.err}`);
2026
+ throw new Error(`could not build ${file}:\n${ran.out}${ran.err}`);
1766
2027
  }
1767
2028
  try {
1768
2029
  nodeFs.renameSync(out, exe);
@@ -1777,6 +2038,41 @@ export const getBuiltProgram = async (source: string, dir: URL): Promise<string>
1777
2038
  return exe;
1778
2039
  };
1779
2040
 
2041
+ // Starts the native build of the rules program at `file` (its kept path `native`) in a process of
2042
+ // its own, which outlives this run, unless one started it in the last BUILDING.
2043
+ const startNativeBuild = (file: string, native: string): void => {
2044
+ const marker = native + ".building";
2045
+ const started = nodeFs.statSync(marker, { throwIfNoEntry: false })?.mtimeMs ?? 0;
2046
+ if (Date.now() - started < BUILDING) {
2047
+ return;
2048
+ }
2049
+ nodeFs.mkdirSync(PROGRAMS_DIR, { recursive: true });
2050
+ tryGet(() => nodeFs.writeFileSync(marker, String(process.pid)));
2051
+ spawn(process.execPath, [url.fileURLToPath(import.meta.url), "build", file], {
2052
+ detached: true,
2053
+ stdio: "ignore",
2054
+ windowsHide: true,
2055
+ }).unref();
2056
+ };
2057
+
2058
+ // The program the rules program `source` builds to, with the Bend in the bend2 folder `dir`:
2059
+ // native, if clang can build it, else JavaScript, until clang can. A native build takes clang a
2060
+ // while, so, unless `waits`, a run that finds none kept runs the JavaScript build (made in about a
2061
+ // second) and leaves the native one to a process of its own, for the runs after it: both builds
2062
+ // are of one program, so they find the same.
2063
+ const getBuiltProgram = async (source: string, dir: URL, waits: boolean): Promise<string> => {
2064
+ const file = nodePath.resolve(source);
2065
+ const native = getNativePath(source, dir);
2066
+ const js = native.replace(/(\.exe)?$/, ".js");
2067
+ if (nodeFs.existsSync(native) || (getClang() !== undefined && waits)) {
2068
+ return getBuild(file, native, dir);
2069
+ }
2070
+ if (getClang() !== undefined) {
2071
+ startNativeBuild(file, native);
2072
+ }
2073
+ return getBuild(file, js, dir);
2074
+ };
2075
+
1780
2076
  // The answer to `check <path> <facts|syntax> <paths...>`: from the cache, if each file the check
1781
2077
  // read is unchanged, else from Bend, and a passed check goes to the cache (whole or not at all; a
1782
2078
  // cache that cannot be written is skipped). A passed check is numbered as before in this server,
@@ -1918,14 +2214,18 @@ const serve = async (
1918
2214
 
1919
2215
  // The checker, the rules program `named`, built first, and what to say first of the Bend bend-lint
1920
2216
  // uses (see bend2.ts). The checker comes first, so a drift stops the run before a build.
1921
- const getRunSetup = async (named: string): Promise<[Checker, string, string[]]> => {
2217
+ const getRunSetup = async (named: string, waits: boolean): Promise<[Checker, string, string[]]> => {
1922
2218
  const dir = unwrap(await tryGetBend2SourceUrl());
1923
2219
  const checker = getChecker(dir);
1924
2220
  const [program, version] = await Promise.all([
1925
- getBuiltProgram(named, dir),
2221
+ getBuiltProgram(named, dir, waits),
1926
2222
  getBendVersionNote(dir),
1927
2223
  ]);
1928
- const javascript = program.endsWith(".js") ? JAVASCRIPT_NOTE : undefined;
2224
+ const javascript = !program.endsWith(".js")
2225
+ ? undefined
2226
+ : getClang() === undefined
2227
+ ? JAVASCRIPT_NOTE
2228
+ : BUILDING_NOTE;
1929
2229
  return [checker, program, [PINNED_BEND_NOTE, version, javascript].filter((n) => n !== undefined)];
1930
2230
  };
1931
2231
 
@@ -1939,6 +2239,28 @@ export const getProject = (dir: string): string | undefined => {
1939
2239
  : getProject(up);
1940
2240
  };
1941
2241
 
2242
+ // The folder a run looks up its config from: that of the first file, glob or folder it names (a
2243
+ // folder is its own), past the value of `--jobs`; else the working folder.
2244
+ const getStart = (args: string[]): string => {
2245
+ const named = args.find((arg, n) => !arg.startsWith("--") && args[n - 1] !== "--jobs");
2246
+ const resolved = nodePath.resolve(named ?? ".");
2247
+ return named === undefined ||
2248
+ nodeFs.statSync(resolved, { throwIfNoEntry: false })?.isDirectory() === true
2249
+ ? resolved
2250
+ : nodePath.dirname(resolved);
2251
+ };
2252
+
2253
+ // The rules folder of the project in `project`: the nearest bend-lint-rules up from it, or, if
2254
+ // there is none, the one beside its config.
2255
+ const getRulesFolder = (project: string, dir: string = project): string => {
2256
+ const up = nodePath.dirname(dir);
2257
+ return nodeFs.existsSync(nodePath.join(dir, RULES))
2258
+ ? nodePath.join(dir, RULES)
2259
+ : up === dir
2260
+ ? nodePath.join(project, RULES)
2261
+ : getRulesFolder(project, up);
2262
+ };
2263
+
1942
2264
  // The entries of `value`, if it is a JSON object.
1943
2265
  const getObjectEntries = (value: unknown): Array<[string, unknown]> | undefined =>
1944
2266
  typeof value === "object" && value !== null && !Array.isArray(value)
@@ -2040,7 +2362,7 @@ export const getRulesProgram = (project: string, { ids, packages }: Rules): stri
2040
2362
  return `import ${name}@${version}/${rest.join("/")}.bend as Rule${n}`;
2041
2363
  }
2042
2364
  const real = tryGet(() =>
2043
- nodeFs.realpathSync(nodePath.join(project, RULES, ...id.split("/")) + ".bend"),
2365
+ nodeFs.realpathSync(nodePath.join(getRulesFolder(project), ...id.split("/")) + ".bend"),
2044
2366
  );
2045
2367
  if (real === undefined) {
2046
2368
  throw new Error(`there is no rule ${id}: ${RULES}/${id}.bend does not exist`);
@@ -2106,6 +2428,15 @@ if (import.meta.main) {
2106
2428
  // down, not the machine.
2107
2429
  tryGet(() => os.setPriority(os.constants.priority.PRIORITY_BELOW_NORMAL));
2108
2430
  const args = process.argv.slice(2);
2431
+ // `bend-lint build <program>`: the native build a run started in the background (see
2432
+ // getBuiltProgram), which says nothing.
2433
+ if (args[0] === "build" && args[1] !== undefined) {
2434
+ const dir = unwrap(await tryGetBend2SourceUrl());
2435
+ const native = getNativePath(args[1], dir);
2436
+ await getBuild(nodePath.resolve(args[1]), native, dir).catch(() => undefined);
2437
+ tryGet(() => nodeFs.rmSync(native + ".building", { force: true }));
2438
+ process.exit(0);
2439
+ }
2109
2440
  if (args[0] === "init") {
2110
2441
  try {
2111
2442
  const { wrote, kept } = getInitFiles(process.cwd());
@@ -2134,7 +2465,7 @@ if (import.meta.main) {
2134
2465
  if (!relative.startsWith("..") && !nodePath.isAbsolute(relative)) {
2135
2466
  getInitFiles(project).wrote.forEach((file) => console.log("bend-lint: wrote " + file));
2136
2467
  console.log(PREPARING);
2137
- await getRunSetup(getProjectProgram(project));
2468
+ await getRunSetup(getProjectProgram(project), true);
2138
2469
  }
2139
2470
  } catch (e) {
2140
2471
  console.error("bend-lint: " + getErrorMessageFromUnknown(e) + "; its first run tries again");
@@ -2164,10 +2495,12 @@ if (import.meta.main) {
2164
2495
  )
2165
2496
  .map((a) => (getOverlay(a) === undefined ? a : getOverlayKey(a)));
2166
2497
  const project =
2167
- getProject(process.cwd()) ??
2498
+ getProject(getStart(runArgs)) ??
2168
2499
  endWithError(
2169
2500
  json,
2170
- "no " + CONFIG + " in this folder or above it; `bunx bend-lint init` makes one",
2501
+ "no " +
2502
+ CONFIG +
2503
+ " in the folder of the first file named, or above it; `bunx bend-lint init` makes one",
2171
2504
  );
2172
2505
 
2173
2506
  // `bend-lint prepare` makes what a run needs, Bend and the build of its rules, and lints nothing:
@@ -2181,7 +2514,7 @@ if (import.meta.main) {
2181
2514
  .catch((e: unknown) =>
2182
2515
  endWithError(json, getErrorMessageFromUnknown(e), nodePath.join(project, CONFIG)),
2183
2516
  );
2184
- const [checker, program, notes] = await getRunSetup(named).catch((e: unknown) =>
2517
+ const [checker, program, notes] = await getRunSetup(named, preparing).catch((e: unknown) =>
2185
2518
  endWithError(json, getErrorMessageFromUnknown(e)),
2186
2519
  );
2187
2520
  const setupMs = performance.now() - started;