You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Updates the `lint`, `build`, and `lifecycle` skills to match current `bsh` behavior
6
+
7
+
The lint skill no longer claims publint runs in `pnpm run lint` (it gates `pnpm run build`), documents `--strict`, `--warnings`, and `--format json`, and adds a remedies table mapping common violations to their sanctioned fixes. The lifecycle skill moves the knip dead-code gate (`lint --strict`) to the PR handoff step.
Copy file name to clipboardExpand all lines: skills/lint/SKILL.md
+61-20Lines changed: 61 additions & 20 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,15 +1,16 @@
1
1
---
2
2
name: lint
3
3
description: >
4
-
Multi-tool linting pipeline: oxlint, publint, knip, tsgo run in parallel via
5
-
pnpm run lint. Covers Bombshell conventions: URL over node:path, max 2 params
6
-
with options bag, named exports only, import type, prefer node builtins, no
7
-
console.log, no generic Error. Use when checking code quality or understanding
8
-
lint violations.
4
+
Multi-tool linting pipeline: oxlint, knip, and tsgo run in parallel via
5
+
pnpm run lint (publint gates pnpm run build instead). Covers Bombshell
6
+
conventions: URL over node:path, max 2 params with options bag, named
7
+
exports only, import type, prefer node builtins, no console.log, no
8
+
generic Error. Use when checking code quality or understanding lint
9
+
violations.
9
10
metadata:
10
11
type: core
11
12
library: '@bomb.sh/tools'
12
-
library_version: '0.3.1'
13
+
library_version: '0.6.0'
13
14
requires:
14
15
- lifecycle
15
16
sources:
@@ -20,32 +21,63 @@ metadata:
20
21
21
22
# Lint
22
23
23
-
Multi-tool linting pipeline. All four tools run in parallel with unified output.
24
+
Multi-tool linting pipeline. oxlint, knip, and tsgo run in parallel with unified output.
24
25
25
26
## Setup
26
27
27
28
```sh
28
-
pnpm run lint # Report violations
29
-
pnpm run lint -- --fix # Auto-fix (oxlint only), then report remaining
30
-
pnpm run lint -- src/foo.ts # Target specific files (default: ./src)
29
+
pnpm run lint # Report errors (warnings collapsed to counts)
30
+
pnpm run lint -- --warnings # Show warnings in full
31
+
pnpm run lint -- --strict # Include knip dead-code checks (pre-commit gate)
32
+
pnpm run lint -- --fix # Auto-fix (oxlint only), then report remaining
33
+
pnpm run lint -- src/foo.ts # Target specific files (default: whole project)
34
+
pnpm -s run lint -- --format json # Machine-readable report for agents/CI
31
35
```
32
36
33
-
Do not run oxlint, publint, knip, or tsgo directly. Always use `pnpm run lint`.
37
+
Do not run oxlint, knip, or tsgo directly. Always use `pnpm run lint`.
38
+
(`--format json` needs `pnpm -s` to keep pnpm's banner out of stdout.)
34
39
35
-
See [lifecycle/SKILL.md](../lifecycle/SKILL.md) for where lint fits in the development workflow (step 5: after tests pass, before format).
40
+
See [lifecycle/SKILL.md](../lifecycle/SKILL.md) for where lint fits in the development workflow (step 3: after tests pass, before format). Run `--strict` at PR handoff, not during the TDD loop.
36
41
37
42
## How It Works
38
43
39
-
`pnpm run lint` runs `bsh lint`, which executes four tools via `Promise.allSettled`:
44
+
`pnpm run lint` runs `bsh lint`, which executes three tools via `Promise.allSettled`:
40
45
41
46
| Tool | What It Checks | Fix Support |
42
47
|------|---------------|-------------|
43
48
|**oxlint**| JS/TS linting via Rust-based engine with Bombshell config | Yes (`--fix`) |
44
-
|**publint**|`package.json` exports, types, and field correctness (strict mode) | No |
45
-
|**knip**| Unused dependencies, devDependencies, exports, types, files | No |
46
-
|**tsgo**| TypeScript type errors (`--noEmit`, native Go compiler) | No |
|**tsgo**| TypeScript type errors (`--noEmit`, project mode) | No |
47
51
48
-
Results merge into a single report grouped by file. Exit code 1 if any errors exist.
52
+
Results merge into a single report grouped by file. **Errors print in full;
53
+
warnings collapse to a per-rule count** (they never affect the exit code —
54
+
pass `--warnings` to expand them). Exit code 1 if any errors exist.
55
+
56
+
publint is deliberately not part of lint: its file-existence checks need
57
+
`dist/`, so it runs as a publish gate in `pnpm run build` (see
58
+
[build/SKILL.md](../build/SKILL.md)) and standalone via `pnpm run publint`.
59
+
60
+
## Remedies
61
+
62
+
The sanctioned fix for the most common violations. Do not improvise
63
+
alternatives (e.g. sprinkling disable comments).
64
+
65
+
| Violation | Fix |
66
+
|-----------|-----|
67
+
|`tsc/TS2688` — Cannot find type definition file for 'node' |`pnpm add -D @types/node`|
68
+
|`tsc/TS2591` — Cannot find name 'process'/'Buffer' |`pnpm add -D @types/node`|
69
+
|`oxlint/eslint(no-restricted-imports)`| Use the `URL` API; `fileURLToPath()` only at third-party boundaries |
70
+
|`oxlint/eslint(max-params)` / `bombshell-dev(max-params)`| Options bag with a typed interface. If conforming to a platform interface, say so with `override`/`implements` — the rule exempts those |
71
+
|`oxlint/import(no-default-export)`| Use a named export |
72
+
|`oxlint/bombshell-dev(no-generic-error)`| Define a project error class with a `code`; throw that |
73
+
|`oxlint/bombshell-dev(exported-function-async)`| Only fires on public entry files: make it `async`, or move the export out of the public surface |
74
+
|`oxlint/bombshell-dev(require-export-jsdoc)`| Only fires on public entry files: add a one-line `/** ... */`|
75
+
|`knip/unused-dependency`| Remove it from `package.json`|
76
+
|`knip/unused-export` (`--strict`) | Un-export it, or delete it if nothing consumes it |
77
+
78
+
Inline `// oxlint-disable` comments are a last resort for genuinely
79
+
exceptional cases, never a workflow. If a rule is wrong for your project
80
+
shape, raise it — the fix belongs upstream in `oxlintrc.json`.
-**Prototyping speed vs lint strictness**: During early prototyping (see [lifecycle](../lifecycle/SKILL.md)), you may want to move fast. The lint rules still apply -- write correct code from the start rather than fixing lint after the fact.
318
+
-**Prototyping speed vs lint strictness**: During early prototyping (see [lifecycle](../lifecycle/SKILL.md)), you may want to move fast. The lint rules still apply -- write correct code from the start rather than fixing lint after the fact. Dead-code checks (knip unused exports/types/files) are deferred to `--strict` at PR handoff precisely so they don't fire mid-implementation.
278
319
-**Opinionated defaults vs explicit config**: The lint config is intentionally strict and not configurable per-project. If a rule is wrong, change it in `oxlintrc.json` upstream.
Defined in `rules/plugin.js`, registered as the `bombshell-dev` plugin.
24
25
25
26
| Rule | Severity | Description |
26
27
|------|----------|-------------|
27
28
|`bombshell-dev/no-generic-error`| error | No `throw new Error(...)` or other builtin error constructors. Use project-specific error classes. |
28
-
|`bombshell-dev/require-export-jsdoc`| warn | Exported functions and classes must have a `/** ... */` JSDoc comment. |
29
-
|`bombshell-dev/exported-function-async`| warn | Exported functions must use `async`. Adding async later is a breaking change. |
29
+
|`bombshell-dev/max-params`| error | Max 2 parameters in authored signatures — use an options bag. Exempt: `override` methods, members of classes that `extends`/`implements`, inline callbacks. |
30
+
|`bombshell-dev/require-export-jsdoc`| warn | Exported functions and classes must have a `/** ... */` JSDoc comment. **Public API surface only** (see below). |
31
+
|`bombshell-dev/exported-function-async`| warn | Exported functions must use `async`. Adding async later is a breaking change. **Public API surface only** (see below). |
32
+
33
+
## Public API Surface Scoping
34
+
35
+
`require-export-jsdoc` and `exported-function-async` encode conventions that
36
+
exist to prevent breaking changes for consumers — so they only apply to files
37
+
consumers can import. `bsh lint` derives the public surface from
38
+
`package.json` (`exports`, `bin`, `main`/`module`, mapping `dist/` paths back
39
+
to `src/`), including conventional `packages/*/` workspace members, and scopes
40
+
these rules to those files via oxlint `overrides`. Internal modules, packages
41
+
without a publish surface (apps, examples), and wildcard passthrough exports
42
+
(`"./*": "./dist/*"`) are exempt.
30
43
31
44
## oxlint Categories
32
45
@@ -41,12 +54,13 @@ These apply in addition to individual rules:
41
54
42
55
`unicorn`, `typescript`, `oxc`, `import`, `node`, plus the custom `bombshell-dev` JS plugin.
0 commit comments