@sshkeda/check 0.0.0-stage → 1.0.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.
Files changed (167) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +156 -2
  3. package/docs/how-to-make-check-pass.md +71 -0
  4. package/package.json +51 -4
  5. package/src/index.ts +8 -0
  6. package/src/internal/ban-abbreviated-words-in-declared-names.ts +165 -0
  7. package/src/internal/ban-checked-members-outside-calls.ts +151 -0
  8. package/src/internal/ban-comments.ts +23 -0
  9. package/src/internal/ban-comparing-or-switching-on-tag.ts +114 -0
  10. package/src/internal/ban-deadlines-inside-tests.ts +41 -0
  11. package/src/internal/ban-declared-values.ts +70 -0
  12. package/src/internal/ban-dropped-failures-detached-fibers-sleeps-and-untraced-functions.ts +67 -0
  13. package/src/internal/ban-failures-collected-as-results.ts +57 -0
  14. package/src/internal/ban-fallbacks-of-named-recoveries.ts +118 -0
  15. package/src/internal/ban-function-overloads.ts +107 -0
  16. package/src/internal/ban-global-error-in-failure-types.ts +146 -0
  17. package/src/internal/ban-instanceof-in-effect-recovery-callbacks.ts +63 -0
  18. package/src/internal/ban-let-and-effect-mutable-ref.ts +79 -0
  19. package/src/internal/ban-logic-in-index-files.ts +178 -0
  20. package/src/internal/ban-namespaces-used-without-a-member.ts +176 -0
  21. package/src/internal/ban-node-builtins-that-effect-replaces.ts +42 -0
  22. package/src/internal/ban-parsing-outside-data-without-a-schema.ts +299 -0
  23. package/src/internal/ban-re-exports.ts +172 -0
  24. package/src/internal/ban-reading-the-clock-and-sleeping-outside-effect.ts +239 -0
  25. package/src/internal/ban-retired-words-in-names.ts +49 -0
  26. package/src/internal/ban-scanning-directories-with-bun-glob.ts +79 -0
  27. package/src/internal/ban-shebang-lines.ts +26 -0
  28. package/src/internal/ban-timer-globals-and-the-global-object.ts +34 -0
  29. package/src/internal/ban-timer-schedules-without-deadlines.ts +240 -0
  30. package/src/internal/ban-type-and-interface-declarations.ts +48 -0
  31. package/src/internal/ban-type-predicates.ts +82 -0
  32. package/src/internal/ban-unknown-in-function-signatures.ts +143 -0
  33. package/src/internal/ban-vague-error-class-names.ts +28 -0
  34. package/src/internal/ban-vague-file-names.ts +51 -0
  35. package/src/internal/ban-what-a-file-is-not-granted.ts +512 -0
  36. package/src/internal/ban-while-do-while-and-for-loops.ts +27 -0
  37. package/src/internal/confine-service-declarations-to-granted-files.ts +116 -0
  38. package/src/internal/confine-the-stdio-service-to-terminal-output.ts +190 -0
  39. package/src/internal/define-the-lint-plugin-and-configs.ts +361 -0
  40. package/src/internal/describe-and-decode-rule-options.ts +22 -0
  41. package/src/internal/keep-assertions-in-the-test-home-and-ban-test-runners.ts +128 -0
  42. package/src/internal/keep-effect-testing-helpers-in-test-files.ts +157 -0
  43. package/src/internal/match-banned-modules-and-globals.ts +71 -0
  44. package/src/internal/match-effect-service-factories.ts +20 -0
  45. package/src/internal/require-a-named-const-for-compound-conditions.ts +44 -0
  46. package/src/internal/require-capital-snake-case-and-as-const-on-literal-constants.ts +141 -0
  47. package/src/internal/require-service-keys-to-end-with-their-class-name.ts +64 -0
  48. package/src/internal/resolve-what-an-expression-imports.ts +295 -0
  49. package/src/internal/sort-type-constituents.ts +82 -0
  50. package/src/internal/split-names-into-words.ts +12 -0
  51. package/src/internal/visit-every-declared-name.ts +264 -0
  52. package/src/lib/tasks/index.ts +1 -0
  53. package/src/lib/tasks/internal/declare-the-check-task.ts +29 -0
  54. package/src/lib/tasks/internal/declare-the-checker-queries-task.ts +41 -0
  55. package/src/lib/tasks/internal/declare-the-typed-checks-task.ts +25 -0
  56. package/src/lib/tasks/internal/run-checks-over-one-typescript-project.ts +68 -0
  57. package/src/lib/tasks/lib/check-effect-diagnostics-with-effect-tsgo/index.ts +15 -0
  58. package/src/lib/tasks/lib/check-effect-diagnostics-with-effect-tsgo/internal/check-effect-diagnostics-with-effect-tsgo.ts +211 -0
  59. package/src/lib/tasks/lib/check-effect-diagnostics-with-effect-tsgo/internal/read-effect-tsgo-json-report.ts +39 -0
  60. package/src/lib/tasks/lib/check-import-boundaries/index.ts +1 -0
  61. package/src/lib/tasks/lib/check-import-boundaries/internal/find-import-boundary-violations.ts +415 -0
  62. package/src/lib/tasks/lib/check-import-boundaries/internal/find-subpath-import-targets.ts +117 -0
  63. package/src/lib/tasks/lib/check-import-boundaries/internal/find-what-hides-an-import.ts +65 -0
  64. package/src/lib/tasks/lib/check-import-boundaries/internal/import-boundary-errors.ts +176 -0
  65. package/src/lib/tasks/lib/check-uses-by-their-declarations/index.ts +1 -0
  66. package/src/lib/tasks/lib/check-uses-by-their-declarations/internal/declared-use-errors.ts +32 -0
  67. package/src/lib/tasks/lib/check-uses-by-their-declarations/internal/find-declared-use-violations.ts +38 -0
  68. package/src/lib/tasks/lib/check-uses-by-their-declarations/internal/find-sync-calls.ts +23 -0
  69. package/src/lib/tasks/lib/check-uses-by-their-declarations/internal/find-type-only-schemas.ts +375 -0
  70. package/src/lib/tasks/lib/confine-layer-provides-to-program-starts/index.ts +1 -0
  71. package/src/lib/tasks/lib/confine-layer-provides-to-program-starts/internal/find-layer-provides-outside-program-starts.ts +648 -0
  72. package/src/lib/tasks/lib/confine-layer-provides-to-program-starts/internal/layer-provide-errors.ts +27 -0
  73. package/src/lib/tasks/lib/confine-layer-provides-to-program-starts/internal/resolve-imported-package-apis.ts +262 -0
  74. package/src/lib/tasks/lib/confine-stdio-to-granted-files/index.ts +1 -0
  75. package/src/lib/tasks/lib/confine-stdio-to-granted-files/internal/find-ungranted-stdio-uses.ts +219 -0
  76. package/src/lib/tasks/lib/confine-stdio-to-granted-files/internal/stdio-use-errors.ts +31 -0
  77. package/src/lib/tasks/lib/detect-inferrable-annotations/index.ts +1 -0
  78. package/src/lib/tasks/lib/detect-inferrable-annotations/internal/find-inferrable-annotations.ts +357 -0
  79. package/src/lib/tasks/lib/detect-inferrable-annotations/internal/inferrable-annotation-errors.ts +33 -0
  80. package/src/lib/tasks/lib/detect-repeated-service-yields/index.ts +1 -0
  81. package/src/lib/tasks/lib/detect-repeated-service-yields/internal/find-repeated-service-yields.ts +162 -0
  82. package/src/lib/tasks/lib/detect-repeated-service-yields/internal/repeated-service-yield-errors.ts +25 -0
  83. package/src/lib/tasks/lib/enforce-file-layout/index.ts +5 -0
  84. package/src/lib/tasks/lib/enforce-file-layout/internal/check-the-layout-of-each-package.ts +9 -0
  85. package/src/lib/tasks/lib/enforce-file-layout/internal/file-layout-errors.ts +417 -0
  86. package/src/lib/tasks/lib/enforce-file-layout/internal/find-export-path-mismatches.ts +83 -0
  87. package/src/lib/tasks/lib/enforce-file-layout/internal/find-file-layout-violations.ts +827 -0
  88. package/src/lib/tasks/lib/enforce-file-layout/internal/find-module-layout-violations.ts +82 -0
  89. package/src/lib/tasks/lib/enforce-file-layout/internal/resolve-task-imports.ts +178 -0
  90. package/src/lib/tasks/lib/enforce-file-types/index.ts +5 -0
  91. package/src/lib/tasks/lib/enforce-file-types/internal/file-type-errors.ts +21 -0
  92. package/src/lib/tasks/lib/enforce-file-types/internal/find-file-type-violations.ts +78 -0
  93. package/src/lib/tasks/lib/format-with-bun-fmt/index.ts +1 -0
  94. package/src/lib/tasks/lib/format-with-bun-fmt/internal/check-formatting-with-bun-fmt.ts +157 -0
  95. package/src/lib/tasks/lib/format-with-bun-fmt/internal/declare-the-formatting-task.ts +66 -0
  96. package/src/lib/tasks/lib/format-with-bun-fmt/internal/find-format-config-violations.ts +16 -0
  97. package/src/lib/tasks/lib/format-with-bun-fmt/internal/find-format-input-violations.ts +74 -0
  98. package/src/lib/tasks/lib/format-with-bun-fmt/internal/find-symbolic-links.ts +14 -0
  99. package/src/lib/tasks/lib/format-with-bun-fmt/internal/unformatted-file-errors.ts +12 -0
  100. package/src/lib/tasks/lib/judge-index-re-exports/index.ts +1 -0
  101. package/src/lib/tasks/lib/judge-index-re-exports/internal/find-index-re-export-violations.ts +353 -0
  102. package/src/lib/tasks/lib/judge-index-re-exports/internal/index-re-export-errors.ts +21 -0
  103. package/src/lib/tasks/lib/lint-with-oxlint/index.ts +15 -0
  104. package/src/lib/tasks/lib/lint-with-oxlint/internal/check-lint-rules-with-oxlint.ts +123 -0
  105. package/src/lib/tasks/lib/lint-with-oxlint/internal/check-unsafe-enum-assignments.ts +152 -0
  106. package/src/lib/tasks/lib/lint-with-oxlint/internal/find-tsgolint-executable.ts +21 -0
  107. package/src/lib/tasks/lib/lint-with-oxlint/internal/read-oxlint-json-report.ts +82 -0
  108. package/src/lib/tasks/lib/lint-with-oxlint/internal/read-tsgolint-rule-messages.ts +68 -0
  109. package/src/lib/tasks/lib/place-exports-in-the-narrowest-directory/index.ts +1 -0
  110. package/src/lib/tasks/lib/place-exports-in-the-narrowest-directory/internal/export-placement-errors.ts +135 -0
  111. package/src/lib/tasks/lib/place-exports-in-the-narrowest-directory/internal/find-export-placement-violations.ts +507 -0
  112. package/src/lib/tasks/lib/place-exports-in-the-narrowest-directory/internal/find-misplaced-files.ts +116 -0
  113. package/src/lib/tasks/lib/place-exports-in-the-narrowest-directory/internal/find-subdivided-directories.ts +29 -0
  114. package/src/lib/tasks/lib/place-exports-in-the-narrowest-directory/internal/find-the-importer-graph.ts +451 -0
  115. package/src/lib/tasks/lib/place-exports-in-the-narrowest-directory/internal/list-binding-names.ts +49 -0
  116. package/src/lib/tasks/lib/refuse-disable-directives/index.ts +15 -0
  117. package/src/lib/tasks/lib/refuse-disable-directives/internal/disable-directive-errors.ts +45 -0
  118. package/src/lib/tasks/lib/refuse-disable-directives/internal/find-disable-directives.ts +66 -0
  119. package/src/lib/tasks/lib/refuse-error-mappings-that-end-streams/index.ts +1 -0
  120. package/src/lib/tasks/lib/refuse-error-mappings-that-end-streams/internal/error-mapping-errors.ts +21 -0
  121. package/src/lib/tasks/lib/refuse-error-mappings-that-end-streams/internal/find-error-mappings-to-done.ts +135 -0
  122. package/src/lib/tasks/lib/require-separate-service-layers/index.ts +1 -0
  123. package/src/lib/tasks/lib/require-separate-service-layers/internal/find-service-layer-violations.ts +170 -0
  124. package/src/lib/tasks/lib/require-separate-service-layers/internal/service-layer-errors.ts +21 -0
  125. package/src/lib/tasks/lib/require-type-checking-every-linted-file/index.ts +14 -0
  126. package/src/lib/tasks/lib/require-type-checking-every-linted-file/internal/find-linted-files-not-type-checked.ts +117 -0
  127. package/src/lib/tasks/lib/require-type-checking-every-linted-file/internal/linted-file-errors.ts +51 -0
  128. package/src/lib/tasks/lib/type-check-with-bun-check/index.ts +11 -0
  129. package/src/lib/tasks/lib/type-check-with-bun-check/internal/check-types-with-bun-check.ts +54 -0
  130. package/src/lib/tasks/lib/type-check-with-bun-check/internal/read-bun-check-output.ts +73 -0
  131. package/src/lib/tasks/lib/type-check-with-bun-check/internal/type-check-errors.ts +10 -0
  132. package/src/lib/tasks/shared/check-each-nested-package.ts +79 -0
  133. package/src/lib/tasks/shared/classify-files-by-role.ts +115 -0
  134. package/src/lib/tasks/shared/count-the-line-of-an-offset.ts +2 -0
  135. package/src/lib/tasks/shared/create-the-module-resolver.ts +38 -0
  136. package/src/lib/tasks/shared/declare-lint-config-task.ts +13 -0
  137. package/src/lib/tasks/shared/declare-typescript-config-task.ts +18 -0
  138. package/src/lib/tasks/shared/encode-compact-json.ts +5 -0
  139. package/src/lib/tasks/shared/find-installed-package-binaries.ts +62 -0
  140. package/src/lib/tasks/shared/find-module-requests.ts +482 -0
  141. package/src/lib/tasks/shared/find-named-package-manifests.ts +94 -0
  142. package/src/lib/tasks/shared/find-unmet-typescript-config-requirements.ts +60 -0
  143. package/src/lib/tasks/shared/list-ignored-files-imported-by-source.ts +79 -0
  144. package/src/lib/tasks/shared/list-linted-files.ts +28 -0
  145. package/src/lib/tasks/shared/list-owned-files.ts +13 -0
  146. package/src/lib/tasks/shared/list-package-files.ts +66 -0
  147. package/src/lib/tasks/shared/load-the-lint-config.ts +176 -0
  148. package/src/lib/tasks/shared/match-granted-patch-files.ts +88 -0
  149. package/src/lib/tasks/shared/parse-config-files-that-import-from-check.ts +310 -0
  150. package/src/lib/tasks/shared/print-failures-and-keep-detail-in-the-trace.ts +99 -0
  151. package/src/lib/tasks/shared/project-config-and-tool-errors.ts +485 -0
  152. package/src/lib/tasks/shared/query-the-typescript-project.ts +635 -0
  153. package/src/lib/tasks/shared/read-named-package-manifests.ts +53 -0
  154. package/src/lib/tasks/shared/read-package-manifest-object.ts +28 -0
  155. package/src/lib/tasks/shared/resolve-absolute-paths.ts +4 -0
  156. package/src/lib/tasks/shared/resolve-module-requests.ts +121 -0
  157. package/src/lib/tasks/shared/run-tools-and-decode-their-reports.ts +98 -0
  158. package/src/lib/tasks/shared/tool-file-locations.ts +38 -0
  159. package/src/shared/bans-each-permission-lifts.ts +454 -0
  160. package/src/shared/config-file-names.ts +3 -0
  161. package/src/shared/find-retired-words.ts +17 -0
  162. package/src/shared/format-reported-failures.ts +31 -0
  163. package/src/shared/lint-rule-messages-and-patterns.ts +104 -0
  164. package/src/shared/match-file-names-and-path-prefixes.ts +18 -0
  165. package/src/shared/permission-grant-errors.ts +42 -0
  166. package/src/shared/record-and-grant-permissions-by-path.ts +419 -0
  167. package/src/shared/test-home-directories.ts +4 -0
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Stephen Shkeda
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,157 @@
1
- # Temporary Holding Version
1
+ # Check
2
2
 
3
- 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.
3
+ Check sends your AI slop code back to the kitchen!
4
+
5
+ Check holds your TypeScript code to a strict standard built around Effect and Bun, so the code stays type-safe, observable and predictable.
6
+
7
+ It runs a handpicked set of oxfmt, oxlint and Effect diagnostic rules, plus `bun check` and about 30 rules of its own. Your agent keeps fixing what it reports until the slop is gone.
8
+
9
+ No comment or setting turns a rule off everywhere. A small set of rules was picked to allow an override, and you grant each one to a single file in `oxlint.config.ts`. See [Grant a permission](docs/how-to-make-check-pass.md#grant-a-permission).
10
+
11
+ Check is built on [Task](https://github.com/sshkeda/task), a task runner for Bun.
12
+
13
+ ## See it catch slop
14
+
15
+ Here's a typical agent-written function in `src/index.ts`.
16
+
17
+ ```ts
18
+ export const loadUser = async (id: string) => {
19
+ try {
20
+ const response = await fetch(`/users/${id}`);
21
+ return (await response.json()) as any;
22
+ } catch (error) {
23
+ // TODO: handle this properly
24
+ console.log(error);
25
+ return null;
26
+ }
27
+ };
28
+ ```
29
+
30
+ TypeScript accepts it. Check doesn't.
31
+
32
+ Here's what Check prints when it runs on that code:
33
+
34
+ ```
35
+ [check] started
36
+ ...
37
+ [effect-tsgo] src/index.ts:1:25: error effect(asyncFunction): This code declares an async function, consider representing this async control flow with Effect values and `Effect.gen`.
38
+ [effect-tsgo] src/index.ts:3:28: error effect(globalFetch): This code uses the global `fetch` function, HTTP requests are represented through `HttpClient` from `effect/http`.
39
+ [effect-tsgo] error ToolExited: effect-tsgo exited with code 1
40
+ [oxlint] src/index.ts:4:12: error typescript(consistent-type-assertions): Do not use any type assertions.
41
+ [oxlint] src/index.ts:4:39: error typescript(no-explicit-any): Unexpected `any`. Specify a different type.
42
+ [oxlint] src/index.ts:7:5: error eslint(no-console): Unexpected console statement.
43
+ [oxlint] src/index.ts:1:25: error sshkeda(no-index-logic): index file holds an arrow function expression
44
+ [oxlint] src/index.ts:4:19: error sshkeda(no-unchecked-parsing): json() parses JSON without a Schema
45
+ [oxlint] src/index.ts:6:5: error sshkeda(no-comments): comment in code
46
+ [oxlint] src/index.ts:4:5: error typescript(no-unsafe-return): Unsafe return of a value of type `any`.
47
+ [oxlint] error ToolExited: oxlint exited with code 1
48
+ [typed-checks] error SettledTasksFailed: 2 of 6 tasks failed: oxlint, effect-tsgo
49
+ [check] read node_modules/@sshkeda/check/docs/how-to-make-check-pass.md before you change the code
50
+ [check] error SettledTasksFailed: 1 of 6 tasks failed: typed-checks
51
+ failed: effect-tsgo, oxlint (2 of 16 tasks), 1.0s
52
+ ```
53
+
54
+ Here's what each error catches:
55
+
56
+ - The `any` and the type assertion switch off type checking.
57
+ - The JSON is never validated.
58
+ - The async function and the bare `fetch` hide their errors from Effect.
59
+ - The comment and the `console.log` are leftovers.
60
+
61
+ Check points your agent to [How to Make Check Pass](docs/how-to-make-check-pass.md), which explains how to write code that passes.
62
+
63
+ Here's the same function after your agent fixes it. The code now lives in `src/internal/load-user.ts`:
64
+
65
+ ```ts
66
+ import { Effect, Schema } from "effect";
67
+ import { HttpClient, HttpClientResponse } from "effect/http";
68
+
69
+ const User = Schema.Struct({ id: Schema.String, name: Schema.String });
70
+
71
+ export const loadUser = (id: string) =>
72
+ HttpClient.get(`/users/${id}`).pipe(Effect.flatMap(HttpClientResponse.schemaBodyJson(User)));
73
+ ```
74
+
75
+ `src/index.ts` only exports it:
76
+
77
+ ```ts
78
+ export { loadUser } from "./internal/load-user.ts";
79
+ ```
80
+
81
+ Check passes.
82
+
83
+ ## Why these rules
84
+
85
+ - **No comments.** When code is hard to follow, the fix is better names and simpler code, which stay true as the code changes. Comments drift out of date, and agents fill them with noise. When you need more explanation, ask your agent to explain the code.
86
+ - **No `type` or `interface` declarations.** Types are inferred from the code that produces each value, so every type has one source of truth and nothing to keep in sync.
87
+ - **No `let` and no loops.** Values don't change after they're made, which leaves an agent fewer ways to get state wrong.
88
+ - **Modules with `internal/`, `shared/` and `lib/`.** Each module exposes its public code in `index.ts`, keeps private code in `internal/`, which only that module may import, puts code its parts share in `shared/` and holds its child modules in `lib/`. Code stays easy to organize and hard to tangle.
89
+ - **No abbreviations.** `imABigFanWhenVariablesAreLongBecauseThenItsEasierToUnderstandWhatTheCodeDoes`. Full words read the same to every person and every agent.
90
+ - **No unchecked data.** JSON and other input pass through a Schema before the code trusts them, because a type assertion or a hand-written type guard proves nothing.
91
+ - **No dead exports.** Check reports any export that nothing uses, or that only tests use, so unused code doesn't pile up.
92
+ - **Effect in place of Node's built-ins.** File, path and process work goes through Effect, so its errors stay typed.
93
+ - **Tests are tasks.** Check bans Vitest and Jest. Each test is a task in Task, so tests run in parallel and clean up after themselves.
94
+ - **Each service in its own layer.** Services are declared only in files you grant, which keeps their wiring in one place.
95
+ - **No polling.** Code waits for an event or a signal instead of checking on a timer, so it reacts right away. When there's nothing to listen to, such as a server that's still starting, polling needs a grant and a time limit.
96
+ - **No dropped failures.** Every error is handled or passed on, so nothing fails silently.
97
+ - **Risky access only where you grant it.** Reading environment variables, starting commands and printing to the terminal each need a grant on the exact file that does it.
98
+
99
+ ## Get started
100
+
101
+ Check needs Bun 1.4.4 or newer and a Git repository.
102
+
103
+ 1. Install Check, Task, Effect and Bun's types.
104
+
105
+ ```bash
106
+ bun add @sshkeda/check @sshkeda/task effect
107
+ bun add -d @types/bun
108
+ ```
109
+
110
+ 2. Add these options to `compilerOptions` in `tsconfig.json`.
111
+
112
+ ```json
113
+ "strict": true,
114
+ "noUncheckedIndexedAccess": true,
115
+ "exactOptionalPropertyTypes": true,
116
+ "allowImportingTsExtensions": true,
117
+ "types": ["bun"]
118
+ ```
119
+
120
+ 3. Create `oxlint.config.ts`, where you grant overrides to single files.
121
+
122
+ ```ts
123
+ import { lintConfig } from "@sshkeda/check";
124
+
125
+ export default lintConfig({});
126
+ ```
127
+
128
+ 4. Create `oxfmt.config.ts`.
129
+
130
+ ```ts
131
+ import { FORMAT_CONFIG } from "@sshkeda/check";
132
+
133
+ export default FORMAT_CONFIG;
134
+ ```
135
+
136
+ 5. Create `scripts/ci.ts` to run Check.
137
+
138
+ ```ts
139
+ import { check } from "@sshkeda/check/tasks";
140
+ import { Task } from "@sshkeda/task";
141
+
142
+ if (import.meta.main) {
143
+ Task.main(check);
144
+ }
145
+ ```
146
+
147
+ 6. Run it, and have your agent fix what it reports.
148
+
149
+ ```bash
150
+ bun scripts/ci.ts
151
+ ```
152
+
153
+ ## Development
154
+
155
+ To run its checks and tests, run `bun scripts/ci.ts`. Check checks itself!
156
+
157
+ [MIT](LICENSE)
@@ -0,0 +1,71 @@
1
+ # How to Make Check Pass
2
+
3
+ Fix the cause of each failure, keep the code simple, make program output clear and prevent mistakes from happening again.
4
+
5
+ Check may not catch every violation of these principles. Review your code against this guide.
6
+
7
+ ## Meet the requirement behind the error
8
+
9
+ - Use a grant only for an unavoidable exception.
10
+ - Design for the current requirement as if you were starting fresh. Delete code the new design doesn't need.
11
+ - Grant `isGeneratedByATool` only to a file a tool generates, and name the tool in its reason.
12
+
13
+ ## Grant a permission
14
+
15
+ Grant a permission to one file or directory in `oxlint.config.ts`. The key is the path from the folder that holds `oxlint.config.ts`, with no glob. Each name in `allow` lifts one ban for that path only.
16
+
17
+ ```ts
18
+ export default lintConfig({
19
+ "src/config.ts": { allow: ["readsConfig"] },
20
+ "src/internal/run-all-checks.ts": {
21
+ allow: [
22
+ { handlesEveryFailure: "reports every check's failures together, so none hides another" },
23
+ ],
24
+ },
25
+ });
26
+ ```
27
+
28
+ These names need no reason:
29
+
30
+ - `readsConfig`: Allows Effect `Config`, `process.env` and `process.argv`.
31
+ - `spawnsCommands`: Allows Effect `ChildProcess`, `Bun.spawn` and `spawn` from `node:child_process`.
32
+ - `locksFiles`: Allows `open` from `node:fs/promises` and `constants` from `node:fs`.
33
+ - `importsDynamically`: Allows `import()` and `createRequire(…).resolve`.
34
+ - `exitsTheProcess`: Allows `process.exit`.
35
+ - `usesSqlDatabases`: Allows Effect SQL.
36
+ - `writesToTheTerminal`: Allows Effect `Stdio`.
37
+ - `usesAbbreviations`: Allows abbreviations in variable, function, type and other declared names.
38
+ - `pollsWithADeadline`: Allows `Effect.repeat` with `Schedule.spaced`, under a deadline.
39
+ - `hasAnUnlistedFileType`: Allows a file type Check doesn't list, such as Markdown.
40
+ - `isAnUnlistedDirectory`: Allows a directory Check doesn't list, such as `vendor`.
41
+ - `patchesADependency`: Allows a patch file from `bun patch`.
42
+
43
+ These names need a reason, written as `{ name: "reason" }`:
44
+
45
+ - `trustsUnverifiedTypes`: Allows trusting a value's type without checking it, through `Schema.declare`.
46
+ - `handlesEveryFailure`: Allows catching every error, through `Effect.catch`, `Effect.exit`, a forked fiber or `Effect.runPromise`.
47
+ - `isGeneratedByATool`: Check skips this path, so it can't have any other permission.
48
+
49
+ A reason can't be blank.
50
+
51
+ ## Make the code explain itself
52
+
53
+ - Use what Effect, Bun or a dependency already provides.
54
+ - Write each fact or decision once and derive the rest from it.
55
+ - Give each value a name that says what it holds.
56
+ - Let TypeScript infer types, or derive them from values and schemas you already use. Don't create a schema only to name a type.
57
+ - Validate unchecked data with a Schema before treating it as a typed value. A type assertion doesn't validate data.
58
+ - Name errors so they say what went wrong.
59
+ - Keep code near the files that use it. Extract shared code when other files need it.
60
+
61
+ ## Make program output clear
62
+
63
+ - Follow Git and uv's style. Say what failed, name the affected file or value and explain the cause.
64
+ - Give the reader enough context to choose a fix. In a CLI people run by hand, add a hint only for a known command they can paste and run.
65
+ - Report each cause once. Put the main failure first, supporting details below it and internal debugging details in the trace.
66
+ - Preserve useful messages from underlying tools, including error codes and exact names.
67
+ - Write short, full sentences. Use periods instead of semicolons between sentences.
68
+
69
+ ## Prevent the same mistake
70
+
71
+ When the user corrects a mistake, consider adding a lint rule or test to prevent it, or changing an existing rule if it enforces the wrong requirement.
package/package.json CHANGED
@@ -1,6 +1,53 @@
1
1
  {
2
2
  "name": "@sshkeda/check",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "1.0.0",
4
+ "homepage": "https://github.com/sshkeda/check#readme",
5
+ "bugs": {
6
+ "url": "https://github.com/sshkeda/check/issues"
7
+ },
8
+ "license": "MIT",
9
+ "repository": {
10
+ "type": "git",
11
+ "url": "git+https://github.com/sshkeda/check.git"
12
+ },
13
+ "files": [
14
+ "docs",
15
+ "src"
16
+ ],
17
+ "type": "module",
18
+ "exports": {
19
+ ".": "./src/index.ts",
20
+ "./tasks": "./src/lib/tasks/index.ts"
21
+ },
22
+ "publishConfig": {
23
+ "access": "public",
24
+ "registry": "https://registry.npmjs.org"
25
+ },
26
+ "dependencies": {
27
+ "@effect/platform-bun": "4.1.0",
28
+ "@effect/tsgo": "0.55.0",
29
+ "@oxlint/plugins": "1.87.0",
30
+ "oxc-parser": "0.153.0",
31
+ "oxc-resolver": "11.24.2",
32
+ "oxlint": "1.87.0",
33
+ "oxlint-tsgolint": "7.0.2005",
34
+ "typescript": "7.0.2"
35
+ },
36
+ "devDependencies": {
37
+ "@sshkeda/task": "^1.0.0",
38
+ "@types/bun": "1.4.3",
39
+ "effect": "4.1.0"
40
+ },
41
+ "peerDependencies": {
42
+ "@sshkeda/task": "^1.0.0",
43
+ "effect": "^4.1.0"
44
+ },
45
+ "peerDependenciesMeta": {
46
+ "@sshkeda/task": {
47
+ "optional": true
48
+ }
49
+ },
50
+ "engines": {
51
+ "bun": ">=1.4.4"
52
+ }
53
+ }
package/src/index.ts ADDED
@@ -0,0 +1,8 @@
1
+ export {
2
+ default,
3
+ FORMAT_CONFIG,
4
+ lintConfig,
5
+ RESTRICTED_IMPORT_PATHS,
6
+ RESTRICTED_PROPERTIES,
7
+ RESTRICTED_TYPES,
8
+ } from "./internal/define-the-lint-plugin-and-configs.ts";
@@ -0,0 +1,165 @@
1
+ import { defineRule } from "@oxlint/plugins";
2
+ import type { ESTree } from "@oxlint/plugins";
3
+ import { Schema } from "effect";
4
+
5
+ import { decodeRuleOptions, ruleOptionsJsonSchema } from "./describe-and-decode-rule-options.ts";
6
+ import { identifierWords } from "./split-names-into-words.ts";
7
+ import { declaredNameListeners } from "./visit-every-declared-name.ts";
8
+
9
+ const TWO_WORDS = 2;
10
+
11
+ const ABBREVIATIONS: ReadonlyMap<string, string> = new Map([
12
+ ["arg", "argument"],
13
+ ["args", "arguments"],
14
+ ["arr", "array"],
15
+ ["attr", "attribute"],
16
+ ["btn", "button"],
17
+ ["calc", "calculate"],
18
+ ["cb", "callback"],
19
+ ["cfg", "config"],
20
+ ["cnt", "count"],
21
+ ["col", "column"],
22
+ ["conf", "config"],
23
+ ["coord", "coordinate"],
24
+ ["ctx", "context"],
25
+ ["cur", "current"],
26
+ ["curr", "current"],
27
+ ["cwd", "workingDirectory"],
28
+ ["db", "database"],
29
+ ["decl", "declaration"],
30
+ ["def", "definition"],
31
+ ["dep", "dependency"],
32
+ ["dest", "destination"],
33
+ ["dir", "directory"],
34
+ ["dst", "destination"],
35
+ ["el", "element"],
36
+ ["elem", "element"],
37
+ ["env", "environment"],
38
+ ["err", "error"],
39
+ ["evt", "event"],
40
+ ["expr", "expression"],
41
+ ["fmt", "format"],
42
+ ["fn", "function"],
43
+ ["fs", "fileSystem"],
44
+ ["idx", "index"],
45
+ ["img", "image"],
46
+ ["impl", "implementation"],
47
+ ["info", "information"],
48
+ ["init", "initialize"],
49
+ ["len", "length"],
50
+ ["lib", "library"],
51
+ ["mgr", "manager"],
52
+ ["msg", "message"],
53
+ ["num", "number"],
54
+ ["obj", "object"],
55
+ ["opt", "option"],
56
+ ["opts", "options"],
57
+ ["param", "parameter"],
58
+ ["params", "parameters"],
59
+ ["pkg", "package"],
60
+ ["pos", "position"],
61
+ ["prev", "previous"],
62
+ ["prop", "property"],
63
+ ["props", "properties"],
64
+ ["pt", "point"],
65
+ ["rect", "rectangle"],
66
+ ["repo", "repository"],
67
+ ["req", "request"],
68
+ ["res", "response"],
69
+ ["resp", "response"],
70
+ ["ret", "result"],
71
+ ["src", "source"],
72
+ ["stderr", "standardError"],
73
+ ["stdin", "standardInput"],
74
+ ["stdout", "standardOutput"],
75
+ ["str", "string"],
76
+ ["temp", "temporary"],
77
+ ["tmp", "temporary"],
78
+ ["util", "utility"],
79
+ ["utils", "utilities"],
80
+ ["val", "value"],
81
+ ]);
82
+
83
+ const plural = (word: string) => (word.endsWith("y") ? `${word.slice(0, -1)}ies` : `${word}s`);
84
+
85
+ const expand = (word: string, allowed: ReadonlySet<string>) => {
86
+ const lower = word.toLowerCase();
87
+ if (allowed.has(lower)) {
88
+ return null;
89
+ }
90
+ const direct = ABBREVIATIONS.get(lower);
91
+ if (direct !== undefined) {
92
+ return direct;
93
+ }
94
+ const singular = lower.endsWith("s") ? ABBREVIATIONS.get(lower.slice(0, -1)) : undefined;
95
+ return singular === undefined ? null : plural(singular);
96
+ };
97
+
98
+ const spaced = (camel: string) =>
99
+ camel.replaceAll(/[A-Z]/gu, (letter) => ` ${letter.toLowerCase()}`);
100
+
101
+ export const inEnglish = (fullWords: readonly string[]) =>
102
+ fullWords.length < TWO_WORDS
103
+ ? fullWords.join("")
104
+ : `${fullWords.slice(0, -1).join(", ")} and ${fullWords.at(-1)}`;
105
+
106
+ const abbreviatedWordsIn = (name: string, allowed: ReadonlySet<string>) => {
107
+ const found = identifierWords(name).flatMap((word) => {
108
+ const full = expand(word.text, allowed);
109
+ return full === null ? [] : [{ ...word, full }];
110
+ });
111
+ if (found.length === 0) {
112
+ return null;
113
+ }
114
+ return {
115
+ fullWords: inEnglish(found.map((word) => spaced(word.full))),
116
+ abbreviations: found.length === 1 ? "an abbreviation" : "abbreviations",
117
+ };
118
+ };
119
+
120
+ const ABBREVIATION_OPTIONS = Schema.Struct({
121
+ allow: Schema.optionalKey(Schema.Array(Schema.String)),
122
+ });
123
+
124
+ const allowList = (options: readonly unknown[]): ReadonlySet<string> =>
125
+ new Set(
126
+ (decodeRuleOptions(ABBREVIATION_OPTIONS, options)?.allow ?? []).map((word) =>
127
+ word.toLowerCase(),
128
+ ),
129
+ );
130
+
131
+ export const noAbbreviations = defineRule({
132
+ meta: {
133
+ type: "suggestion",
134
+ docs: {
135
+ description:
136
+ "Disallow abbreviated words in the names a file declares, in camelCase, PascalCase and snake_case.",
137
+ },
138
+ messages: {
139
+ abbreviation: "`{{name}}` contains {{abbreviations}} of {{fullWords}}",
140
+ },
141
+ schema: ruleOptionsJsonSchema(ABBREVIATION_OPTIONS),
142
+ },
143
+ create(context) {
144
+ const allowed = allowList(context.options);
145
+
146
+ const check = (node: ESTree.Node) => {
147
+ const isIdentifierOrPrivateIdentifier =
148
+ node.type === "Identifier" || node.type === "PrivateIdentifier";
149
+ if (!isIdentifierOrPrivateIdentifier) {
150
+ return;
151
+ }
152
+ const found = abbreviatedWordsIn(node.name, allowed);
153
+ if (found === null) {
154
+ return;
155
+ }
156
+ context.report({
157
+ node,
158
+ messageId: "abbreviation",
159
+ data: { name: node.name, ...found },
160
+ });
161
+ };
162
+
163
+ return declaredNameListeners(check);
164
+ },
165
+ });
@@ -0,0 +1,151 @@
1
+ import { defineRule } from "@oxlint/plugins";
2
+ import type { ESTree, SourceCode } from "@oxlint/plugins";
3
+
4
+ import { OPERATIONS_THAT_HANDLE_UNNAMED_FAILURES } from "../shared/bans-each-permission-lifts.ts";
5
+ import { NUMBER_PARSERS } from "./ban-parsing-outside-data-without-a-schema.ts";
6
+ import {
7
+ DATE_TIME_FORMAT,
8
+ TIMED_WAITS,
9
+ } from "./ban-reading-the-clock-and-sleeping-outside-effect.ts";
10
+ import {
11
+ DEADLINE_OPERATIONS,
12
+ POLLING_OPERATIONS,
13
+ } from "./ban-timer-schedules-without-deadlines.ts";
14
+ import { SERVICE_FACTORIES } from "./match-effect-service-factories.ts";
15
+ import {
16
+ effectModuleOperation,
17
+ isGlobalReference,
18
+ isImportBinding,
19
+ isValueOperandOfTypeScriptOrExport,
20
+ memberName,
21
+ } from "./resolve-what-an-expression-imports.ts";
22
+
23
+ const RECOVERY_PREFIX = "catch";
24
+ const ERROR_MAPPING = "mapError";
25
+
26
+ const COLLECTING_OPERATION = "all";
27
+
28
+ const isBannedRecovery = (moduleName: "Channel" | "Effect" | "Stream", operation: string) =>
29
+ OPERATIONS_THAT_HANDLE_UNNAMED_FAILURES[moduleName].some(
30
+ (banned: string) => banned === operation,
31
+ );
32
+
33
+ const isRecoveryCheckedAtItsCall = (
34
+ moduleName: "Channel" | "Effect" | "Stream",
35
+ operation: string,
36
+ ) =>
37
+ (operation.startsWith(RECOVERY_PREFIX) || operation === ERROR_MAPPING) &&
38
+ !isBannedRecovery(moduleName, operation);
39
+
40
+ const EFFECT_MEMBERS_CHECKED_AT_THEIR_CALLS: ReadonlyMap<string, (operation: string) => boolean> =
41
+ new Map([
42
+ [
43
+ "Effect",
44
+ (operation: string) =>
45
+ isRecoveryCheckedAtItsCall("Effect", operation) ||
46
+ operation === COLLECTING_OPERATION ||
47
+ POLLING_OPERATIONS.has(operation) ||
48
+ DEADLINE_OPERATIONS.has(operation),
49
+ ],
50
+ ["Stream", (operation: string) => isRecoveryCheckedAtItsCall("Stream", operation)],
51
+ ["Channel", (operation: string) => isRecoveryCheckedAtItsCall("Channel", operation)],
52
+ ["Context", (operation: string) => SERVICE_FACTORIES.has(operation)],
53
+ ["PlatformError", (operation: string) => operation === "systemError"],
54
+ ]);
55
+
56
+ const GLOBAL_MEMBERS_CHECKED_AT_THEIR_CALLS: ReadonlyMap<string, ReadonlySet<string>> = new Map([
57
+ ["Atomics", TIMED_WAITS],
58
+ ["Intl", new Set([DATE_TIME_FORMAT])],
59
+ ["Number", NUMBER_PARSERS],
60
+ ]);
61
+
62
+ const rootOf = (node: ESTree.Node): ESTree.Node =>
63
+ node.type === "MemberExpression" ? rootOf(node.object) : node;
64
+
65
+ const effectMemberNamed = (node: ESTree.Node, sourceCode: SourceCode) => {
66
+ if (!isImportBinding(rootOf(node), sourceCode)) {
67
+ return;
68
+ }
69
+ return [...EFFECT_MEMBERS_CHECKED_AT_THEIR_CALLS]
70
+ .map(([moduleName, isCheckedAtItsCall]) => {
71
+ const operation = effectModuleOperation(node, sourceCode, moduleName);
72
+ const isChecked = operation !== undefined && isCheckedAtItsCall(operation);
73
+ return isChecked ? `${moduleName}.${operation}` : undefined;
74
+ })
75
+ .find((member) => member !== undefined);
76
+ };
77
+
78
+ const globalMemberNamed = (node: ESTree.MemberExpression, sourceCode: SourceCode) => {
79
+ const member = memberName(node);
80
+ const objectName = node.object.type === "Identifier" ? node.object.name : undefined;
81
+ const members =
82
+ objectName === undefined ? undefined : GLOBAL_MEMBERS_CHECKED_AT_THEIR_CALLS.get(objectName);
83
+ const isCheckedGlobalMember =
84
+ objectName !== undefined &&
85
+ member !== undefined &&
86
+ members?.has(member) === true &&
87
+ isGlobalReference(node.object, sourceCode, objectName);
88
+ return isCheckedGlobalMember ? `${objectName}.${member}` : undefined;
89
+ };
90
+
91
+ const isCalledWhereNamed = (node: ESTree.Node) => {
92
+ const { parent } = node;
93
+ const isCallOrConstruction =
94
+ parent?.type === "CallExpression" || parent?.type === "NewExpression";
95
+ return isCallOrConstruction && parent.callee === node;
96
+ };
97
+
98
+ const isValueReference = (node: ESTree.Node) => {
99
+ const { parent } = node;
100
+ if (parent === null) {
101
+ return false;
102
+ }
103
+ if (isValueOperandOfTypeScriptOrExport(node, parent)) {
104
+ return true;
105
+ }
106
+ const isMemberProperty =
107
+ parent.type === "MemberExpression" && parent.property === node && !parent.computed;
108
+ const isPropertyKey =
109
+ parent.type === "Property" &&
110
+ parent.key === node &&
111
+ (!parent.shorthand || parent.value !== node);
112
+ return (
113
+ !isMemberProperty &&
114
+ !isPropertyKey &&
115
+ !parent.type.startsWith("Import") &&
116
+ !parent.type.startsWith("Export") &&
117
+ !parent.type.startsWith("TS")
118
+ );
119
+ };
120
+
121
+ export const noUncalledMembers = defineRule({
122
+ meta: {
123
+ type: "problem",
124
+ docs: {
125
+ description:
126
+ "Call a member whose ban is checked at its call, such as Stream.catchTag or Effect.retry, where it is named, so no value carries it past the check.",
127
+ },
128
+ messages: {
129
+ uncalled: "{{member}} is used as a value instead of being called where it is named",
130
+ },
131
+ },
132
+ create(context) {
133
+ const { sourceCode } = context;
134
+ const report = (node: ESTree.Node, member: string | undefined) => {
135
+ const isUncalledCheckedMember = member !== undefined && !isCalledWhereNamed(node);
136
+ if (isUncalledCheckedMember) {
137
+ context.report({ node, messageId: "uncalled", data: { member } });
138
+ }
139
+ };
140
+ return {
141
+ Identifier(node) {
142
+ if (isValueReference(node)) {
143
+ report(node, effectMemberNamed(node, sourceCode));
144
+ }
145
+ },
146
+ MemberExpression(node) {
147
+ report(node, effectMemberNamed(node, sourceCode) ?? globalMemberNamed(node, sourceCode));
148
+ },
149
+ };
150
+ },
151
+ });
@@ -0,0 +1,23 @@
1
+ import { defineRule } from "@oxlint/plugins";
2
+
3
+ import { isDirective } from "../shared/lint-rule-messages-and-patterns.ts";
4
+
5
+ export const noComments = defineRule({
6
+ meta: {
7
+ type: "suggestion",
8
+ docs: { description: "Disallow comments in code." },
9
+ messages: { comment: "comment in code" },
10
+ },
11
+ create(context) {
12
+ return {
13
+ "Program:exit"() {
14
+ for (const comment of context.sourceCode.getAllComments()) {
15
+ const isCodeComment = comment.type !== "Shebang" && !isDirective(comment.value);
16
+ if (isCodeComment) {
17
+ context.report({ loc: comment.loc, messageId: "comment" });
18
+ }
19
+ }
20
+ },
21
+ };
22
+ },
23
+ });