lintcn 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -1,3 +1,111 @@
+## 0.7.0
+
+1. **`lintcn lint --fix`** — automatically apply fixes in-place. Collects diagnostics per file, applies fixes via the Go runner, and only reports what couldn't be auto-fixed:
+
+   ```bash
+   lintcn lint --fix
+   ```
+
+2. **Warning severity system** — rules can now declare `// lintcn:severity warn`. Warnings don't fail CI (exit 0) and are filtered to git-changed files by default so they don't flood large codebases:
+
+   ```go
+   // lintcn:severity warn
+   ```
+
+   Two new flags:
+   - `--all-warnings` — show warnings for all files, not just changed ones
+   - `lintcn list` now shows a `(warn)` suffix on warning-severity rules
+
+3. **New rule: `no-type-assertion` (warn)** — flags every `as X` / `<X>expr` and includes the actual expression type so agents know what they're working with:
+
+   ```
+   warning: Type assertion to `User ({ name: string; age: number })` from `unknown`
+   ```
+
+   User-defined types show their structural form in parentheses. Standard library types (Array, Map, Promise, etc.) are not expanded. Assertion chains (`x as unknown as Foo`) walk back to the original source type. Casting from `any` is silently allowed (standard untyped-API pattern).
+
+4. **New rule: `no-in-operator` (warn)** — warns on every `in` expression and shows the expanded type of the right-hand operand. When the right side is a union and the property exists in some members but not others, it names which members have it and suggests using a discriminant property instead:
+
+   ```
+   warning: Avoid the `in` operator on `Cat | Dog`. Property `meow` exists in Cat but not Dog.
+   Consider using a discriminant property (e.g. `kind`) instead of `in`.
+   ```
+
+5. **New rule: `no-redundant-in-check` (error)** — flags `"y" in x` when the type already has `y` as a required non-optional property in all union members. The check can never be false — it's dead code:
+
+   ```ts
+   interface User { name: string; age: number }
+   if ('name' in user) { ... }  // error: redundant — User always has 'name'
+   ```
+
+6. **New built-in rules**: `jsx-no-leaked-render`, `no-unhandled-error`, `no-useless-coalescing` — available via `lintcn add` or by pointing at the `.lintcn/` folder URL.
+
+7. **`lintcn add` with whole repo URL** — download all rules from a repo's `.lintcn/` folder in one shot. Merge semantics: remote rule folders overwrite local ones; local-only rules are preserved:
+
+   ```bash
+   # bare repo URL — fetches all rules from .lintcn/ at repo root
+   lintcn add https://github.com/remorses/lintcn
+
+   # tree URL pointing at a .lintcn collection
+   lintcn add https://github.com/remorses/lintcn/tree/main/.lintcn
+   ```
+
+8. **Fixed `await-thenable` false positive on overloaded functions** — when a function has multiple call signatures (overloads or intersection-of-callable-types), the rule now checks if any overload returns a thenable before reporting. Fixes false positives like `await extract({...})` from the `tar` package.
+
+9. **Brighter error underline** — error highlights changed from ANSI 256-color 160 (muted red) to 196 (pure bright red). Run `lintcn clean` to clear the old cached binary.
+
+## 0.6.0
+
+1. **Rules now live in subfolders** — each rule is its own Go package under `.lintcn/{rule_name}/`, replacing the old flat `.lintcn/*.go` layout. This eliminates the need to rename `options.go` and `schema.json` companions — they stay in the subfolder with their original names, and the Go package name matches the folder. `lintcn add` now fetches the entire rule folder automatically.
+
+   ```
+   .lintcn/
+       no_floating_promises/
+           no_floating_promises.go
+           no_floating_promises_test.go
+           options.go      ← original name, no renaming
+           schema.json
+       my_custom_rule/
+           my_custom_rule.go
+   ```
+
+2. **`lintcn add` fetches whole folders** — both folder URLs (`/tree/`) and file URLs (`/blob/`) now fetch every `.go` and `.json` file in the rule's directory. Passing a file URL auto-detects the parent folder:
+
+   ```bash
+   # folder URL
+   lintcn add https://github.com/oxc-project/tsgolint/tree/main/internal/rules/no_floating_promises
+
+   # file URL — auto-fetches the whole folder
+   lintcn add https://github.com/oxc-project/tsgolint/blob/main/internal/rules/await_thenable/await_thenable.go
+   ```
+
+3. **Error for flat `.go` files in `.lintcn/`** — if leftover flat files from older versions are detected, lintcn now prints a clear migration error with instructions instead of silently ignoring them.
+
+4. **Reproducible builds with `-trimpath`** — the Go binary is now built with `-trimpath`, stripping absolute paths from the output. Binaries are identical across machines for the same rule content + tsgolint version + platform.
+
+5. **Faster cache hits** — Go version removed from the content hash. The compiled binary is a standalone executable with no Go runtime dependency, so the Go version used to build it doesn't affect correctness. Also excludes `_test.go` files from the hash since tests don't affect the binary.
+
+6. **Go compilation output is live** — `go build` now inherits stdio, so compilation progress and errors stream directly to the terminal instead of being silently captured.
+
+7. **First-build guidance** — on first compile (cold Go cache), lintcn explains the one-time 30s cost and shows which directories to cache in CI:
+   ```
+   Compiling custom tsgolint binary (first build — may take 30s+ to compile dependencies)...
+   Subsequent builds will be fast (~1s). In CI, cache ~/.cache/lintcn/ and GOCACHE (run `go env GOCACHE`).
+   ```
+
+8. **GitHub Actions example** — README now includes a copy-paste workflow that caches the compiled binary. Subsequent CI runs take ~12s (vs ~4min cold):
+
+   ```yaml
+   - name: Cache lintcn binary + Go build cache
+     uses: actions/cache@v4
+     with:
+       path: |
+         ~/.cache/lintcn
+         ~/go/pkg
+       key: lintcn-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('.lintcn/**/*.go') }}
+       restore-keys: lintcn-${{ runner.os }}-${{ runner.arch }}-
+   ```
+
 ## 0.5.0
 
 1. **Security fix — path traversal in `--tsgolint-version`** — the version flag is now validated against a strict pattern. Previously a value like `../../etc` could escape the cache directory.

package/README.md

@@ -13,8 +13,11 @@ npm install -D lintcn
 ## Usage
 
 ```bash
-# Add a rule by URL
-npx lintcn add https://github.com/user/repo/blob/main/rules/no_unhandled_error.go
+# Add a rule folder from tsgolint
+npx lintcn add https://github.com/oxc-project/tsgolint/tree/main/internal/rules/no_floating_promises
+
+# Add by file URL (auto-fetches the whole folder)
+npx lintcn add https://github.com/oxc-project/tsgolint/blob/main/internal/rules/await_thenable/await_thenable.go
 
 # Lint your project
 npx lintcn lint
@@ -26,21 +29,32 @@ npx lintcn lint --tsconfig tsconfig.build.json
 npx lintcn list
 
 # Remove a rule
-npx lintcn remove no-unhandled-error
+npx lintcn remove no-floating-promises
+
+# Clean cached tsgolint source + binaries
+npx lintcn clean
 ```
 
+Browse all 50+ available built-in rules in the [tsgolint rules directory](https://github.com/oxc-project/tsgolint/tree/main/internal/rules).
+
 ## How it works
 
-Rules live as `.go` files in `.lintcn/` at your project root. You own the source — edit, customize, delete.
+Each rule lives in its own subfolder under `.lintcn/`. You own the source — edit, customize, delete.
 
 ```
 my-project/
 ├── .lintcn/
-│   ├── .gitignore                      ← ignores generated Go files
-│   ├── no_unhandled_error.go           ← your rule (committed)
-│   └── no_unhandled_error_test.go      ← its tests (committed)
+│   ├── .gitignore                          ← ignores generated Go files
+│   ├── no_floating_promises/
+│   │   ├── no_floating_promises.go         ← rule source (committed)
+│   │   ├── no_floating_promises_test.go    ← tests (committed)
+│   │   └── options.go                      ← rule options struct
+│   ├── await_thenable/
+│   │   ├── await_thenable.go
+│   │   └── await_thenable_test.go
+│   └── my_custom_rule/
+│       └── my_custom_rule.go
 ├── src/
-│   ├── index.ts
 │   └── ...
 ├── tsconfig.json
 └── package.json
@@ -48,24 +62,32 @@ my-project/
 
 When you run `npx lintcn lint`, the CLI:
 
-1. Scans `.lintcn/*.go` for rule definitions
+1. Scans `.lintcn/*/` subfolders for rule definitions
 2. Generates a Go workspace with your custom rules
 3. Compiles a custom binary (cached — rebuilds only when rules change)
 4. Runs the binary against your project
 
 You can run `lintcn lint` from any subdirectory — it walks up to find `.lintcn/` and lints the cwd project.
 
-## Writing a rule
+## Writing custom rules
 
-Every rule is a Go file with `package lintcn` that exports a `rule.Rule` variable.
+To help AI agents write and modify rules, install the lintcn skill:
 
-Here's a rule that errors when you discard the return value of a function that returns `Error | T` — enforcing the [errore](https://errore.org) pattern:
+```bash
+npx skills add remorses/lintcn
+```
+
+This gives your AI agent the full tsgolint rule API reference — AST visitors, type checker, reporting, fixes, and testing patterns.
+
+Every rule lives in a subfolder under `.lintcn/` with the package name matching the folder:
 
 ```go
+// .lintcn/no_unhandled_error/no_unhandled_error.go
+
 // lintcn:name no-unhandled-error
 // lintcn:description Disallow discarding Error-typed return values
 
-package lintcn
+package no_unhandled_error
 
 import (
     "github.com/microsoft/typescript-go/shim/ast"
@@ -118,17 +140,66 @@ This catches code like:
 
 ```typescript
 // error — result discarded, Error not handled
-getUser("id")           // returns Error | User
-await fetchData("/api") // returns Promise<Error | Data>
+getUser("id"); // returns Error | User
+await fetchData("/api"); // returns Promise<Error | Data>
 
 // ok — result is checked
-const user = getUser("id")
-if (user instanceof Error) return user
+const user = getUser("id");
+if (user instanceof Error) return user;
 
 // ok — explicitly discarded
-void getUser("id")
+void getUser("id");
 ```
 
+## Warning severity
+
+Rules can be configured as **warnings** instead of errors:
+
+- **Don't fail CI** — warnings produce exit code 0
+- **Only shown for git-changed files** — warnings for unchanged files are silently skipped
+
+This lets you adopt new rules gradually. In a large codebase, enabling a rule as an error means hundreds of violations at once. As a warning, you only see violations in files you're actively changing — fixing issues in new code without blocking the build.
+
+### Configuring a rule as a warning
+
+Add `// lintcn:severity warn` to the rule's Go file:
+
+```go
+// lintcn:name no-unhandled-error
+// lintcn:severity warn
+// lintcn:description Disallow discarding Error-typed return values
+```
+
+Rules without `// lintcn:severity` default to `error`.
+
+### When warnings are shown
+
+By default, `lintcn lint` runs `git diff` to find changed and untracked files. Warnings are only printed for files in that list:
+
+```bash
+# Warnings only for files in git diff (default)
+npx lintcn lint
+
+# Warnings for ALL files, ignoring git diff
+npx lintcn lint --all-warnings
+```
+
+| Scenario                           | Warnings shown?   |
+| ---------------------------------- | ----------------- |
+| File is in `git diff` or untracked | Yes               |
+| File is committed and unchanged    | No                |
+| `--all-warnings` flag is passed    | Yes, all files    |
+| Git is not installed or not a repo | No warnings shown |
+| Clean git tree (no changes)        | No warnings shown |
+
+### Workflow
+
+1. Add a new rule with `lintcn add`
+2. Set it to `// lintcn:severity warn` in the Go source
+3. Run `lintcn lint` — only see warnings in files you're currently editing
+4. Fix warnings as you touch files naturally
+5. Once the codebase is clean, change to `// lintcn:severity error` (or remove the directive) to enforce it
+
 ## Version pinning
 
 **Pin lintcn in your `package.json`** — do not use `^` or `~`:
@@ -136,7 +207,7 @@ void getUser("id")
 ```json
 {
   "devDependencies": {
-    "lintcn": "0.4.0"
+    "lintcn": "0.5.0"
   }
 }
 ```
@@ -147,12 +218,41 @@ Each lintcn release bundles a specific tsgolint version. Updating lintcn can cha
 2. Run `npx lintcn build` after updating to verify your rules still compile
 3. Fix any compilation errors before committing
 
-You can test against an unreleased tsgolint version without updating lintcn:
-
-```bash
-npx lintcn lint --tsgolint-version v0.10.0
+## CI Setup
+
+The first `lintcn lint` compiles a custom Go binary (~30s). Subsequent runs use the cached binary (<1s). Cache `~/.cache/lintcn/` and Go's build cache to keep CI fast.
+
+```yaml
+# .github/workflows/lint.yml
+name: Lint
+on: [push, pull_request]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - name: Cache lintcn binary + Go build cache
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cache/lintcn
+            ~/go/pkg
+          key: lintcn-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('.lintcn/**/*.go') }}
+          restore-keys: |
+            lintcn-${{ runner.os }}-${{ runner.arch }}-
+
+      - run: npm ci
+      - run: npx lintcn lint
 ```
 
+The cache key includes a hash of your rule files — when rules change, the binary is recompiled. The `restore-keys` fallback ensures Go's build cache is still used even when rules change, so recompilation takes ~1s instead of 30s.
+
 ## Prerequisites
 
 - **Node.js** — for the CLI

package/dist/cache.d.ts

@@ -1,4 +1,4 @@
-export declare const DEFAULT_TSGOLINT_VERSION = "e945641eabec22993eda3e7c101692e80417e0ea";
+export declare const DEFAULT_TSGOLINT_VERSION = "23190a08a6315eba8ef11818fc1c38d7b01c9e10";
 /** Validate version string to prevent path traversal attacks.
  *  Only allows alphanumeric chars, dots, underscores, and hyphens. */
 export declare function validateVersion(version: string): void;

package/dist/cache.js

@@ -16,7 +16,7 @@ import { execAsync } from "./exec.js";
 // Pinned tsgolint fork commit — updated with each lintcn release.
 // Uses remorses/tsgolint fork which adds internal/runner.Run().
 // Only 1 commit on top of upstream — zero modifications to existing files.
-export const DEFAULT_TSGOLINT_VERSION = 'e945641eabec22993eda3e7c101692e80417e0ea';
+export const DEFAULT_TSGOLINT_VERSION = '23190a08a6315eba8ef11818fc1c38d7b01c9e10';
 // Pinned typescript-go base commit from microsoft/typescript-go (before patches).
 // Patches from tsgolint/patches/ are applied on top during setup.
 // Must be updated when DEFAULT_TSGOLINT_VERSION changes.

package/dist/cli.js

@@ -7,16 +7,19 @@ import { addRule } from "./commands/add.js";
 import { lint, buildBinary } from "./commands/lint.js";
 import { listRules } from "./commands/list.js";
 import { removeRule } from "./commands/remove.js";
+import { clean } from "./commands/clean.js";
 import { DEFAULT_TSGOLINT_VERSION } from "./cache.js";
 const require = createRequire(import.meta.url);
 const packageJson = require('../package.json');
 const cli = goke('lintcn');
 cli
-    .command('add <url>', 'Add a rule by URL. Fetches the .go file and copies it into .lintcn/')
-    .example('# Add a rule from GitHub')
-    .example('lintcn add https://github.com/user/repo/blob/main/rules/no_floating_promises.go')
-    .example('# Add from raw URL')
-    .example('lintcn add https://raw.githubusercontent.com/user/repo/main/rules/no_unused_result.go')
+    .command('add <url>', 'Add rules by GitHub URL. Supports single rule folders, .lintcn/ directories, or full repo URLs.')
+    .example('# Add a single rule folder')
+    .example('lintcn add https://github.com/oxc-project/tsgolint/tree/main/internal/rules/no_floating_promises')
+    .example('# Add by file URL (auto-fetches the whole folder)')
+    .example('lintcn add https://github.com/oxc-project/tsgolint/blob/main/internal/rules/await_thenable/await_thenable.go')
+    .example('# Add all rules from a repo (downloads .lintcn/ folder)')
+    .example('lintcn add https://github.com/someone/their-project')
     .action(async (url) => {
     await addRule(url);
 });
@@ -34,12 +37,17 @@ cli
 cli
     .command('lint', 'Build custom tsgolint binary and run it against the project')
     .option('--rebuild', 'Force rebuild even if cached binary exists')
+    .option('--fix', 'Automatically fix violations')
     .option('--tsconfig <path>', 'Path to tsconfig.json')
     .option('--list-files', 'List matched files')
+    .option('--all-warnings', 'Show warnings for all files, not just git-changed ones')
     .option('--tsgolint-version [version]', 'Override the pinned tsgolint version (tag or commit). For testing unreleased tsgolint versions.')
     .action(async (options) => {
     const tsgolintVersion = options.tsgolintVersion || DEFAULT_TSGOLINT_VERSION;
     const passthroughArgs = [];
+    if (options.fix) {
+        passthroughArgs.push('--fix');
+    }
     if (options.tsconfig) {
         passthroughArgs.push('--tsconfig', options.tsconfig);
     }
@@ -55,6 +63,7 @@ cli
         rebuild: !!options.rebuild,
         tsgolintVersion,
         passthroughArgs,
+        allWarnings: !!options.allWarnings,
     });
     process.exit(exitCode);
 });
@@ -67,6 +76,11 @@ cli
     const binaryPath = await buildBinary({ rebuild: !!options.rebuild, tsgolintVersion });
     console.log(binaryPath);
 });
+cli
+    .command('clean', 'Remove cached tsgolint source and compiled binaries to free disk space')
+    .action(() => {
+    clean();
+});
 cli.help();
 cli.version(packageJson.version);
 cli.parse();

package/dist/codegen.js

@@ -102,10 +102,27 @@ go 1.26
     const mainGo = generateMainGo(rules);
     fs.writeFileSync(path.join(buildDir, 'wrapper', 'main.go'), mainGo);
 }
-/** Generate main.go that imports user rules and calls internal/runner.Run(). */
+/** Sanitize a package name into a valid Go identifier for use as an import alias.
+ *  Replaces hyphens/dots with underscores, prepends _ if starts with a digit. */
+function toGoAlias(pkg) {
+    let alias = pkg.replace(/[^a-zA-Z0-9_]/g, '_');
+    if (/^[0-9]/.test(alias)) {
+        alias = '_' + alias;
+    }
+    return alias;
+}
+/** Generate main.go that imports user rules and calls internal/runner.Run().
+ *  Each rule subfolder is its own Go package, imported by package name. */
 function generateMainGo(rules) {
+    // Deduplicate imports by package name (in case a subfolder has multiple rules)
+    const uniquePackages = [...new Set(rules.map((r) => { return r.packageName; }))];
+    const imports = uniquePackages.map((pkg) => {
+        const alias = toGoAlias(pkg);
+        return `\t${alias} "${TSGOLINT_MODULE}/lintcn-rules/${pkg}"`;
+    }).join('\n');
     const ruleEntries = rules.map((r) => {
-        return `\t\tlintcn.${r.varName},`;
+        const alias = toGoAlias(r.packageName);
+        return `\t\t${alias}.${r.varName},`;
     }).join('\n');
     return `// Code generated by lintcn. DO NOT EDIT.
 package main
@@ -115,7 +132,7 @@ import (
 
 \t"${TSGOLINT_MODULE}/internal/rule"
 \t"${TSGOLINT_MODULE}/internal/runner"
-\tlintcn "${TSGOLINT_MODULE}/lintcn-rules"
+${imports}
 )
 
 func main() {

package/dist/commands/add.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"add.d.ts","sourceRoot":"","sources":["../../src/commands/add.ts"],"names":[],"mappings":"AA+EA,wBAAsB,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA2DxD"}
+{"version":3,"file":"add.d.ts","sourceRoot":"","sources":["../../src/commands/add.ts"],"names":[],"mappings":"AAqQA,wBAAsB,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA0ExD"}