bend-lint 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,23 @@
+SPDX-License-Identifier: MIT
+
+MIT License
+
+Copyright (c) 2026 Mathews Fernando
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,127 @@
-# Temporary Holding Version
+# bend-lint
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A linter and formatter for Bend 2, with rules written in Bend.
+
+## Install
+
+Install bend-lint in each project, never globally:
+
+```sh
+bun add -D --trust bend-lint
+```
+
+The install writes `bend-lint.json` and `bend-lint-rules/format.bend`, which turns on the formatter,
+and downloads Bend. Without `--trust`, Bun skips that: run `bunx bend-lint init`.
+
+> **Why per project:** a Bend limitation. Bend imports a file only by a relative path of plain names
+> (or from BendHub), so bend-lint can reach your rules only inside your project. bend-lint refuses
+> to run from anywhere else.
+
+Needs Bun 1.4.3. bend-lint downloads the Bend it is tested with, once. With clang 14 or newer, it
+builds your rules natively; without clang, it builds them to JavaScript, about 3 to 8 times slower,
+and says so on each run.
+
+> **On Windows, bend-lint uses a fork of Bend**,
+> [MattCozendey/bend](https://github.com/MattCozendey/bend/tree/feature/cuda-and-windows), because
+> Bend's releases do not run on Windows. bend-lint says so on each run.
+
+## Run
+
+```sh
+bunx bend-lint [<file or glob>...] [--fix | --fix-dangerously] [--show-suppressed] [--json]
+               [--jobs <number or max>]
+```
+
+| Flag                | Does                                                                               |
+| ------------------- | ---------------------------------------------------------------------------------- |
+| `--fix`             | makes no fix until Bend's checker in Bend can prove that a fix keeps the program   |
+| `--fix-dangerously` | applies every fix. These can change what the program does, or break it             |
+| `--show-suppressed` | also prints the findings that a directive covers                                   |
+| `--json`            | prints one JSON object on stdout, with every fix. The summary goes to stderr       |
+| `--jobs`            | how many files to lint at once: a number, or `max` (default: half the CPU threads) |
+
+- With no files, it lints the `.bend` files in the folder you run it in: those git lists (so none
+  that `.gitignore` lists), and none in `node_modules` or a hidden folder.
+- Quote globs, and use `/` in paths.
+- bend-lint builds your rules on its first run (about 40 s), and keeps the build until a rule or
+  Bend changes.
+- A fix that touches an earlier fix's edits waits for the next run.
+- bend-lint runs at low priority: a long run slows down, not your computer.
+- bend-lint does not report Bend's own errors: `bend <file> --check-only` does. If Bend's check of a
+  file fails, the rules that need its types do not run on it, and bend-lint names them on stderr.
+- Exit code: 0 no errors (warnings do not count), 1 an error, 2 a usage or config error.
+- The downloaded Bend, builds and cached checks go to `~/.cache/bend-lint/`. You can delete it at
+  any time.
+
+## Config
+
+`bend-lint.json` is the only place that picks the rules: a rule runs only if `rules` names it.
+bend-lint reads the nearest `bend-lint.json` above the folder it runs in.
+
+```json
+{
+  "entries": ["src/main.bend"],
+  "imports": true,
+  "packages": { "jane-rules": "1.0.0.0" },
+  "rules": {
+    "format": { "tabWidth": 4, "severity": "hint" },
+    "style/no-foo": "error",
+    "style/no-bar": "off",
+    "jane-rules/no-baz": "warning"
+  }
+}
+```
+
+- `rules`: each rule to run, by its id: its path in `bend-lint-rules/`, without `.bend`
+  (`bend-lint-rules/style/no-foo.bend` is `style/no-foo`). Give it `"off"`, a severity (`error`,
+  `warning`, `information`, `hint`), or an object of its options and a `"severity"`.
+- `packages`: BendHub packages of rules, names to versions. A rule whose id starts with a package's
+  name, then `/`, is that package's file at the rest of the id: `jane-rules/no-baz` is `no-baz.bend`
+  in `jane-rules@1.0.0.0`.
+- `entries`: your program's entry files, as paths from the folder of `bend-lint.json`. A rule that
+  reads the whole program ("this def is never used") then sees it, even when you lint one file.
+- `imports`: also lint every file the named file imports (not Base, nor hub packages).
+
+bend-lint's own rules are on BendHub, as the package `bend-lint-rules` at bend-lint's version, with
+`.0` added. Name it in `packages`, then turn a rule on by its id, like
+`bend-lint-rules/layout/case`. Each file's header in [bend-lint-rules/](bend-lint-rules/) says what
+the rule reports, what its fix does, and its options.
+
+## Suppress findings
+
+```
+# bend-lint: disable-next my/rule -- <reason> not-expected-because: <why>
+# bend-lint: expect-next my/rule@hint -- <reason>
+```
+
+Form: `# bend-lint: <disable|expect>-<scope> <rule>[@severity] -- <reason>`.
+
+| Scope           | Covers                                       |
+| --------------- | -------------------------------------------- |
+| `file`          | the whole file                               |
+| `begin` … `end` | the lines between them (`end` has no reason) |
+| `next`          | the next line with code                      |
+| `line`          | its own line, after code                     |
+
+- A finding is covered when it starts on a covered line.
+- `bend-lint/...` findings cannot be suppressed.
+- bend-lint reports a wrong directive and an unmet `expect` as errors, and a `disable` that covers
+  nothing as a warning.
+
+## Write a rule
+
+A rule is a file in `bend-lint-rules/`. It imports bend-lint's rule API from BendHub,
+[lint.bend](src/linter/lint.bend), whose comments are the API, and defines `rule()`:
+
+```
+import Base
+import bend-lint-api@0.1.0.0/linter/lint.bend as Lint
+
+def rule() -> Lint.Rule:
+  ...
+```
+
+Then name it in `bend-lint.json`. The version is your bend-lint's, with `.0` added. After you update
+bend-lint, change it if Bend's check of your rule fails.
+
+To share rules, publish them to BendHub. A project then names your package in `packages`.

package/package.json

@@ -1,6 +1,18 @@
 {
   "name": "bend-lint",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Diagnostics for Bend 2 from rules outside the language: source text, and the checker's types",
+  "license": "MIT",
+  "bin": {
+    "bend-lint": "src/linter/seam.ts"
+  },
+  "type": "module",
+  "engines": {
+    "bun": "1.4.3"
+  },
+  "bendRelease": "bendlang/bend/v2.0.37",
+  "bendWindows": "MattCozendey/bend/4113803537dd07a7c45101476d9e895fcde06703",
+  "scripts": {
+    "postinstall": "bun ./src/linter/seam.ts postinstall"
+  }
+}

package/src/files/effs/files.c

@@ -0,0 +1,150 @@
+// Files
+// =====
+// The C twins of files.js. A path crosses as UTF-8: Windows reads it so, as
+// every Bend binary has a UTF-8 manifest.
+
+#include <sys/stat.h>
+#ifndef _WIN32
+#include <dirent.h>
+#endif
+
+// The names a folder listing collects, each ended by a NUL.
+typedef struct {
+  char* text;
+  u64   len;
+  u64   cap;
+} FilesNames;
+
+#ifdef _WIN32
+// The errno of a failed Win32 call.
+static int files_errno(DWORD code) {
+  return code == ERROR_FILE_NOT_FOUND || code == ERROR_PATH_NOT_FOUND ? ENOENT
+    : code == ERROR_ACCESS_DENIED ? EACCES
+    : code == ERROR_DIRECTORY ? ENOTDIR
+    : EIO;
+}
+#endif
+
+static void files_put(FilesNames* names, const char* name) {
+  u64 k = strlen(name);
+  if (strcmp(name, ".") == 0 || strcmp(name, "..") == 0) {
+    return;
+  }
+  while (names->len + k + 1 > names->cap) {
+    names->cap *= 2;
+    names->text = realloc(names->text, names->cap);
+  }
+  memcpy(names->text + names->len, name, k + 1);
+  names->len += k + 1;
+}
+
+// Puts the names in the folder at `path` (`n` bytes) into `names`. Gives 0,
+// or the errno.
+static int files_list_into(FilesNames* names, const char* path, u64 n) {
+#ifdef _WIN32
+  char* all = malloc(n + 3);
+  memcpy(all, path, n);
+  memcpy(all + n, "/*", 3);
+  WIN32_FIND_DATAA found;
+  HANDLE           h = FindFirstFileA(all, &found);
+  free(all);
+  if (h == INVALID_HANDLE_VALUE) {
+    return files_errno(GetLastError());
+  }
+  do {
+    files_put(names, found.cFileName);
+  } while (FindNextFileA(h, &found));
+  FindClose(h);
+  return 0;
+#else
+  DIR* d = opendir(path);
+  if (d == NULL) {
+    return errno;
+  }
+  for (struct dirent* de = readdir(d); de != NULL; de = readdir(d)) {
+    files_put(names, de->d_name);
+  }
+  closedir(d);
+  return 0;
+#endif
+}
+
+// The names in a folder, but "." and "..", each ended by a NUL, in the
+// order the OS gives them.
+Term files_list_run(Env e, Term* f, IoWork* w) {
+  u64        n     = 0;
+  char*      path  = io_cstr(e, f[0], &n);
+  FilesNames names = { malloc(256), 0, 256 };
+  int        code  = io_nul(path, n) ? EINVAL : files_list_into(&names, path, n);
+  free(path);
+  Term r = code != 0 ? io_fail(e, code, NULL) : io_done(e, io_str(e, names.text, names.len));
+  free(names.text);
+  return r;
+}
+
+// What is at a path, links followed: 0 nothing, 1 a file, 2 a folder, 3
+// something else.
+Term files_kind_run(Env e, Term* f, IoWork* w) {
+  u64         n    = 0;
+  char*       path = io_cstr(e, f[0], &n);
+  struct stat st;
+  u32         kind = io_nul(path, n) || stat(path, &st) != 0 ? 0
+    : (st.st_mode & S_IFMT) == S_IFREG ? 1
+    : (st.st_mode & S_IFMT) == S_IFDIR ? 2
+    : 3;
+  free(path);
+  return (Term)kind;
+}
+
+// A path's real path: absolute, links resolved, "/" between its parts.
+Term files_real_run(Env e, Term* f, IoWork* w) {
+  u64   n    = 0;
+  char* path = io_cstr(e, f[0], &n);
+  if (io_nul(path, n)) {
+    free(path);
+    return io_fail(e, EINVAL, NULL);
+  }
+#ifdef _WIN32
+  HANDLE h = CreateFileA(path, 0, FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE,
+    NULL, OPEN_EXISTING, FILE_FLAG_BACKUP_SEMANTICS, NULL);
+  free(path);
+  if (h == INVALID_HANDLE_VALUE) {
+    return io_fail(e, files_errno(GetLastError()), NULL);
+  }
+  char  buf[32768];
+  DWORD k   = GetFinalPathNameByHandleA(h, buf, sizeof buf, FILE_NAME_NORMALIZED | VOLUME_NAME_DOS);
+  DWORD why = GetLastError();
+  CloseHandle(h);
+  if (k == 0 || k >= sizeof buf) {
+    return io_fail(e, k == 0 ? files_errno(why) : ENAMETOOLONG, NULL);
+  }
+  // \\?\C:\a is C:\a, and \\?\UNC\host\a is \\host\a.
+  char* real = buf;
+  if (strncmp(buf, "\\\\?\\UNC\\", 8) == 0) {
+    real    = buf + 6;
+    real[0] = '\\';
+  } else if (strncmp(buf, "\\\\?\\", 4) == 0) {
+    real = buf + 4;
+  }
+  for (char* c = real; *c != 0; c += 1) {
+    *c = *c == '\\' ? '/' : *c;
+  }
+  return io_done(e, io_str(e, real, strlen(real)));
+#else
+  char* real = realpath(path, NULL);
+  int   code = errno;
+  free(path);
+  if (real == NULL) {
+    return io_fail(e, code, NULL);
+  }
+  Term r = io_done(e, io_str(e, real, strlen(real)));
+  free(real);
+  return r;
+#endif
+}
+
+static void __attribute__((constructor)) files_use(void) {
+  io_eff(CID(list.raw), files_list_run);
+  io_eff(CID(kind), files_kind_run);
+  io_eff(CID(real), files_real_run);
+}

package/src/files/effs/files.js

@@ -0,0 +1,40 @@
+// Files
+// =====
+// The JS twins of files.c.
+
+function files_list(path) {
+  if (path.includes("\0")) return io_fail(22);
+  try {
+    return io_done(
+      require("fs")
+        .readdirSync(path)
+        .map((name) => name + "\0")
+        .join(""),
+    );
+  } catch (e) {
+    return io_fail(io_code(e));
+  }
+}
+
+function files_kind(path) {
+  if (path.includes("\0")) return 0;
+  try {
+    const st = require("fs").statSync(path);
+    return st.isFile() ? 1 : st.isDirectory() ? 2 : 3;
+  } catch {
+    return 0;
+  }
+}
+
+function files_real(path) {
+  if (path.includes("\0")) return io_fail(22);
+  try {
+    return io_done(require("fs").realpathSync.native(path).replaceAll("\\", "/"));
+  } catch (e) {
+    return io_fail(io_code(e));
+  }
+}
+
+io_eff(CID(list.raw), files_list);
+io_eff(CID(kind), files_kind);
+io_eff(CID(real), files_real);