lintcn 0.0.1 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,31 @@
+## 0.2.0
+
+1. **Pinned tsgolint version** — each lintcn release bundles a specific tsgolint version (`v0.9.2`). Builds are now reproducible: everyone on the same lintcn version compiles against the same tsgolint API. Previously used `main` branch which was non-deterministic.
+
+2. **`--tsgolint-version` flag** — override the pinned version for testing unreleased tsgolint:
+   ```bash
+   npx lintcn lint --tsgolint-version v0.10.0
+   ```
+
+3. **Version pinning docs** — README now explains why you should pin lintcn in `package.json` (no `^` or `~`) and how to update safely.
+
+## 0.1.0
+
+1. **Initial release** — CLI for adding type-aware TypeScript lint rules as Go files to your project:
+
+   ```bash
+   npx lintcn add https://github.com/user/repo/blob/main/rules/no_unhandled_error.go
+   npx lintcn lint
+   ```
+
+2. **`lintcn add <url>`** — fetch a `.go` rule file by URL into `.lintcn/`. Normalizes GitHub blob URLs to raw URLs automatically. Also fetches the matching `_test.go` if present. Rewrites the package declaration to `package lintcn` and injects a `// lintcn:source` comment.
+
+3. **`lintcn lint`** — builds a custom tsgolint binary (all 50+ built-in rules + your custom rules) and runs it against the project. Binary is cached by SHA-256 content hash — rebuilds only when rules change.
+
+4. **`lintcn build`** — build the custom binary without running it. Prints the binary path.
+
+5. **`lintcn list`** — list installed rules with descriptions parsed from `// lintcn:` metadata comments.
+
+6. **`lintcn remove <name>`** — delete a rule and its test file from `.lintcn/`.
+
+7. **Editor/LSP support** — generates `go.work` and `go.mod` inside `.lintcn/` so gopls provides full autocomplete, go-to-definition, and type checking on tsgolint APIs while writing rules.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Kimaki
+
+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,12 +1,164 @@
 # lintcn
 
-The [shadcn](https://ui.shadcn.com) for type-aware TypeScript lint rules.
+The [shadcn](https://ui.shadcn.com) for type-aware TypeScript lint rules. Powered by [tsgolint](https://github.com/oxc-project/tsgolint).
 
-Browse rules, pick the ones you need, copy them into your project. You own the code.
+Add rules by URL, own the source, customize freely. Rules are Go files that use the TypeScript type checker for deep analysis — things ESLint can't do.
 
-## Coming soon
+## Install
 
 ```bash
-npx lintcn add no-floating-promises
-npx lintcn add no-unused-result
+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
+
+# Lint your project
+npx lintcn lint
+
+# Lint with a specific tsconfig
+npx lintcn lint --tsconfig tsconfig.build.json
+
+# List installed rules
+npx lintcn list
+
+# Remove a rule
+npx lintcn remove no-unhandled-error
+```
+
+## How it works
+
+Rules live as `.go` files in `.lintcn/` at your project root. 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)
+├── src/
+│   ├── index.ts
+│   └── ...
+├── tsconfig.json
+└── package.json
+```
+
+When you run `npx lintcn lint`, the CLI:
+
+1. Scans `.lintcn/*.go` for rule definitions
+2. Generates a Go workspace with all 50+ built-in tsgolint rules + your custom rules
+3. Compiles a custom binary (cached — rebuilds only when rules change)
+4. Runs the binary against your project
+
+## Writing a rule
+
+Every rule is a Go file with `package lintcn` that exports a `rule.Rule` variable.
+
+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:
+
+```go
+// lintcn:name no-unhandled-error
+// lintcn:description Disallow discarding Error-typed return values
+
+package lintcn
+
+import (
+    "github.com/microsoft/typescript-go/shim/ast"
+    "github.com/microsoft/typescript-go/shim/checker"
+    "github.com/typescript-eslint/tsgolint/internal/rule"
+    "github.com/typescript-eslint/tsgolint/internal/utils"
+)
+
+var NoUnhandledErrorRule = rule.Rule{
+    Name: "no-unhandled-error",
+    Run: func(ctx rule.RuleContext, options any) rule.RuleListeners {
+        return rule.RuleListeners{
+            ast.KindExpressionStatement: func(node *ast.Node) {
+                expression := ast.SkipParentheses(node.AsExpressionStatement().Expression)
+
+                if ast.IsVoidExpression(expression) {
+                    return // void = intentional discard
+                }
+
+                innerExpr := expression
+                if ast.IsAwaitExpression(innerExpr) {
+                    innerExpr = ast.SkipParentheses(innerExpr.Expression())
+                }
+                if !ast.IsCallExpression(innerExpr) {
+                    return
+                }
+
+                t := ctx.TypeChecker.GetTypeAtLocation(expression)
+
+                if utils.IsTypeFlagSet(t, checker.TypeFlagsVoid|checker.TypeFlagsUndefined|checker.TypeFlagsNever) {
+                    return
+                }
+
+                for _, part := range utils.UnionTypeParts(t) {
+                    if utils.IsErrorLike(ctx.Program, ctx.TypeChecker, part) {
+                        ctx.ReportNode(node, rule.RuleMessage{
+                            Id:          "noUnhandledError",
+                            Description: "Error-typed return value is not handled.",
+                        })
+                        return
+                    }
+                }
+            },
+        }
+    },
+}
+```
+
+This catches code like:
+
+```typescript
+// error — result discarded, Error not handled
+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
+
+// ok — explicitly discarded
+void getUser("id")
+```
+
+## Version pinning
+
+**Pin lintcn in your `package.json`** — do not use `^` or `~`:
+
+```json
+{
+  "devDependencies": {
+    "lintcn": "0.1.0"
+  }
+}
+```
+
+Each lintcn release bundles a specific tsgolint version. Updating lintcn can change the underlying tsgolint API, which may cause your rules to no longer compile. Always update consciously:
+
+1. Check the [changelog](./CHANGELOG.md) for tsgolint version changes
+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
+```
+
+## Prerequisites
+
+- **Node.js** — for the CLI
+- **Go 1.26+** — for compiling rules (`go.dev/dl`)
+- **Git** — for cloning tsgolint source on first build
+
+Go is only needed for `lintcn lint` / `lintcn build`. Adding and listing rules works without Go.
+
+## License
+
+MIT

package/dist/cache.d.ts

@@ -0,0 +1,9 @@
+export declare const DEFAULT_TSGOLINT_VERSION = "v0.9.2";
+export declare function getCacheDir(): string;
+export declare function getTsgolintSourceDir(version: string): string;
+export declare function getBinDir(): string;
+export declare function getBinaryPath(contentHash: string): string;
+export declare function getBuildDir(): string;
+export declare function ensureTsgolintSource(version: string): Promise<string>;
+export declare function cachedBinaryExists(contentHash: string): boolean;
+//# sourceMappingURL=cache.d.ts.map

package/dist/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"AAcA,eAAO,MAAM,wBAAwB,WAAW,CAAA;AAEhD,wBAAgB,WAAW,IAAI,MAAM,CAEpC;AAED,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAE5D;AAED,wBAAgB,SAAS,IAAI,MAAM,CAElC;AAED,wBAAgB,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAEzD;AAED,wBAAgB,WAAW,IAAI,MAAM,CAEpC;AAED,wBAAsB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CA2D3E;AAED,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAQ/D"}

package/dist/cache.js

@@ -0,0 +1,88 @@
+// Manage cached tsgolint source clone and compiled binaries.
+// Cache lives in ~/.cache/lintcn/ with structure:
+//   tsgolint/<version>/   — cloned tsgolint source (read-only)
+//   bin/<content-hash>    — compiled binaries
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { execAsync } from "./exec.js";
+// Pinned tsgolint version — updated with each lintcn release.
+// This ensures reproducible builds: every user on the same lintcn version
+// compiles rules against the same tsgolint API. Changing this is a conscious
+// decision — tsgolint API changes can break user rules.
+export const DEFAULT_TSGOLINT_VERSION = 'v0.9.2';
+export function getCacheDir() {
+    return path.join(os.homedir(), '.cache', 'lintcn');
+}
+export function getTsgolintSourceDir(version) {
+    return path.join(getCacheDir(), 'tsgolint', version);
+}
+export function getBinDir() {
+    return path.join(getCacheDir(), 'bin');
+}
+export function getBinaryPath(contentHash) {
+    return path.join(getBinDir(), contentHash);
+}
+export function getBuildDir() {
+    return path.join(getCacheDir(), 'build');
+}
+export async function ensureTsgolintSource(version) {
+    const sourceDir = getTsgolintSourceDir(version);
+    const readyMarker = path.join(sourceDir, '.lintcn-ready');
+    if (fs.existsSync(readyMarker)) {
+        return sourceDir;
+    }
+    console.log(`Cloning tsgolint@${version}...`);
+    fs.mkdirSync(sourceDir, { recursive: true });
+    // clone with depth 1 for speed — --branch works with tags and branches
+    const cloneArgs = [
+        'clone', '--depth', '1',
+        '--branch', version,
+        '--recurse-submodules', '--shallow-submodules',
+        'https://github.com/oxc-project/tsgolint.git', sourceDir,
+    ];
+    await execAsync('git', cloneArgs);
+    // apply patches if they exist
+    const patchesDir = path.join(sourceDir, 'patches');
+    if (fs.existsSync(patchesDir)) {
+        const patches = fs.readdirSync(patchesDir).filter((f) => {
+            return f.endsWith('.patch');
+        }).sort();
+        if (patches.length > 0) {
+            console.log(`Applying ${patches.length} patches...`);
+            const patchPaths = patches.map((p) => {
+                return path.join('..', 'patches', p);
+            });
+            await execAsync('git', ['am', '--3way', '--no-gpg-sign', ...patchPaths], {
+                cwd: path.join(sourceDir, 'typescript-go'),
+            });
+        }
+    }
+    // copy internal/collections from typescript-go (required by tsgolint, done by `just init`)
+    const collectionsDir = path.join(sourceDir, 'internal', 'collections');
+    const tsGoCollections = path.join(sourceDir, 'typescript-go', 'internal', 'collections');
+    if (!fs.existsSync(collectionsDir) && fs.existsSync(tsGoCollections)) {
+        fs.mkdirSync(collectionsDir, { recursive: true });
+        const files = fs.readdirSync(tsGoCollections).filter((f) => {
+            return f.endsWith('.go') && !f.endsWith('_test.go');
+        });
+        for (const file of files) {
+            fs.copyFileSync(path.join(tsGoCollections, file), path.join(collectionsDir, file));
+        }
+        console.log(`Copied ${files.length} collection files`);
+    }
+    // write ready marker
+    fs.writeFileSync(readyMarker, new Date().toISOString());
+    console.log('tsgolint source ready');
+    return sourceDir;
+}
+export function cachedBinaryExists(contentHash) {
+    const binPath = getBinaryPath(contentHash);
+    try {
+        fs.accessSync(binPath, fs.constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/cli.js

@@ -1,4 +1,72 @@
 #!/usr/bin/env node
-console.log('lintcn - the shadcn for type-aware TypeScript lint rules');
-console.log('coming soon: npx lintcn add <rule-name>');
-export {};
+// lintcn — the shadcn for type-aware TypeScript lint rules.
+// Add rules by URL, compile, and run them via tsgolint.
+import { goke } from 'goke';
+import { createRequire } from 'node:module';
+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 { 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')
+    .action(async (url) => {
+    await addRule(url);
+});
+cli
+    .command('remove <name>', 'Remove an installed rule from .lintcn/')
+    .example('lintcn remove no-floating-promises')
+    .action((name) => {
+    removeRule(name);
+});
+cli
+    .command('list', 'List all installed rules')
+    .action(() => {
+    listRules();
+});
+cli
+    .command('lint', 'Build custom tsgolint binary and run it against the project')
+    .option('--rebuild', 'Force rebuild even if cached binary exists')
+    .option('--tsconfig <path>', 'Path to tsconfig.json')
+    .option('--list-files', 'List matched files')
+    .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.tsconfig) {
+        passthroughArgs.push('--tsconfig', options.tsconfig);
+    }
+    if (options.listFiles) {
+        passthroughArgs.push('--list-files');
+    }
+    // pass through anything after --
+    const doubleDash = options['--'];
+    if (doubleDash && Array.isArray(doubleDash)) {
+        passthroughArgs.push(...doubleDash);
+    }
+    const exitCode = await lint({
+        rebuild: !!options.rebuild,
+        tsgolintVersion,
+        passthroughArgs,
+    });
+    process.exit(exitCode);
+});
+cli
+    .command('build', 'Build the custom tsgolint binary without running it')
+    .option('--rebuild', 'Force rebuild even if cached binary exists')
+    .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 binaryPath = await buildBinary({ rebuild: !!options.rebuild, tsgolintVersion });
+    console.log(binaryPath);
+});
+cli.help();
+cli.version(packageJson.version);
+cli.parse();

package/dist/codegen.d.ts

@@ -0,0 +1,18 @@
+import type { RuleMetadata } from './discover.ts';
+/** Generate .lintcn/go.work and .lintcn/go.mod for editor/gopls support.
+ *
+ *  Key learnings from testing:
+ *  - Module name MUST be a child path of github.com/typescript-eslint/tsgolint
+ *    so Go allows importing internal/ packages across the module boundary.
+ *  - go.work must `use` both .tsgolint AND .tsgolint/typescript-go since
+ *    tsgolint's own go.work (which does this) is ignored by the outer workspace.
+ *  - go.mod should be minimal (no requires) — the workspace resolves everything. */
+export declare function generateEditorGoFiles(lintcnDir: string): void;
+/** Generate build workspace in cache dir for compiling the custom binary */
+export declare function generateBuildWorkspace({ buildDir, tsgolintDir, lintcnDir, rules, }: {
+    buildDir: string;
+    tsgolintDir: string;
+    lintcnDir: string;
+    rules: RuleMetadata[];
+}): void;
+//# sourceMappingURL=codegen.d.ts.map

package/dist/codegen.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codegen.d.ts","sourceRoot":"","sources":["../src/codegen.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAiGjD;;;;;;;oFAOoF;AACpF,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAiC7D;AAED,4EAA4E;AAC5E,wBAAgB,sBAAsB,CAAC,EACrC,QAAQ,EACR,WAAW,EACX,SAAS,EACT,KAAK,GACN,EAAE;IACD,QAAQ,EAAE,MAAM,CAAA;IAChB,WAAW,EAAE,MAAM,CAAA;IACnB,SAAS,EAAE,MAAM,CAAA;IACjB,KAAK,EAAE,YAAY,EAAE,CAAA;CACtB,GAAG,IAAI,CAgDP"}