lintcn 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -1,3 +1,35 @@
+## 0.3.0
+
+1. **Only custom rules run by default** — previously the binary included all 44 built-in tsgolint rules, producing thousands of noisy errors. Now only your `.lintcn/` rules run. True shadcn model: explicitly add each rule you want.
+
+   Before (0.2.0): `Found 2315 errors (linted 193 files with 45 rules)`
+   After (0.3.0): `Found 8 errors (linted 193 files with 1 rule)`
+
+2. **Run `lintcn lint` from any subdirectory** — uses `find-up` to walk parent directories for `.lintcn/`. You no longer need to be at the project root:
+   ```bash
+   cd packages/my-app
+   lintcn lint   # finds .lintcn/ in parent
+   ```
+
+3. **No git required** — tsgolint source is now downloaded as a tarball from GitHub instead of cloned. Patches applied with `patch -p1`. Faster first setup, works without git installed.
+
+4. **Fixed stale binary cache** — added `CACHE_SCHEMA_VERSION` to the content hash. Upgrading lintcn now correctly invalidates cached binaries built by older versions.
+
+5. **Fixed partial download corruption** — if the tsgolint download fails midway, the partial directory is cleaned up so the next run starts fresh instead of failing repeatedly.
+
+6. **Fixed GitHub URLs with `/` in branch names** — `lintcn add` now correctly handles branch names like `feature/my-branch` in GitHub blob URLs.
+
+## 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:

package/README.md

@@ -127,6 +127,30 @@ if (user instanceof Error) return user
 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

package/dist/cache.d.ts

@@ -1,4 +1,4 @@
-export declare const DEFAULT_TSGOLINT_VERSION = "main";
+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;

package/dist/cache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"AAWA,eAAO,MAAM,wBAAwB,SAAS,CAAA;AAE9C,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,CA0D3E;AAED,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAQ/D"}
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"AAmBA,eAAO,MAAM,wBAAwB,WAAW,CAAA;AAOhD,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;AAuCD,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

@@ -1,13 +1,24 @@
-// 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
+// Manage cached tsgolint source and compiled binaries.
+// Downloads tsgolint + typescript-go as tarballs from GitHub (no git required),
+// applies patches with `patch -p1`, and copies internal/collections.
+//
+// Cache layout:
+//   ~/.cache/lintcn/tsgolint/<version>/   — extracted source (read-only)
+//   ~/.cache/lintcn/bin/<content-hash>    — compiled binaries
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { pipeline } from 'node:stream/promises';
 import { execAsync } from "./exec.js";
-// Default tsgolint version — pinned to a known-good commit
-export const DEFAULT_TSGOLINT_VERSION = 'main';
+// 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';
+// Pinned typescript-go commit that tsgolint v0.9.2 depends on.
+// Found via `git ls-tree HEAD typescript-go` in the tsgolint repo.
+// Must be updated when DEFAULT_TSGOLINT_VERSION changes.
+const TYPESCRIPT_GO_COMMIT = '2437fa43e85103d2a18e8e41e1a2a994d0708ccf';
 export function getCacheDir() {
     return path.join(os.homedir(), '.cache', 'lintcn');
 }
@@ -23,53 +34,87 @@ export function getBinaryPath(contentHash) {
 export function getBuildDir() {
     return path.join(getCacheDir(), 'build');
 }
+/** Download a tarball from URL and extract it to targetDir.
+ *  GitHub tarballs have a top-level directory like `repo-ref/`,
+ *  so we strip the first path component during extraction. */
+async function downloadAndExtract(url, targetDir) {
+    const response = await fetch(url);
+    if (!response.ok || !response.body) {
+        throw new Error(`Failed to download ${url}: ${response.status} ${response.statusText}`);
+    }
+    fs.mkdirSync(targetDir, { recursive: true });
+    // pipe through gunzip, then extract with tar (strip top-level directory)
+    const tmpTarGz = path.join(os.tmpdir(), `lintcn-${Date.now()}.tar.gz`);
+    const fileStream = fs.createWriteStream(tmpTarGz);
+    // @ts-ignore ReadableStream vs NodeJS.ReadableStream mismatch
+    await pipeline(response.body, fileStream);
+    await execAsync('tar', ['xzf', tmpTarGz, '--strip-components=1', '-C', targetDir]);
+    fs.rmSync(tmpTarGz, { force: true });
+}
+/** Apply git-format patches using `patch -p1` (no git required).
+ *  Patches are standard unified diff format, `patch` ignores the git metadata. */
+async function applyPatches(patchesDir, targetDir) {
+    const patches = fs.readdirSync(patchesDir)
+        .filter((f) => { return f.endsWith('.patch'); })
+        .sort();
+    for (const patchFile of patches) {
+        const patchPath = path.join(patchesDir, patchFile);
+        // --batch silences interactive prompts, -f forces application
+        await execAsync('patch', ['-p1', '--batch', '-i', patchPath], { cwd: targetDir });
+    }
+    return patches.length;
+}
 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
-    const cloneArgs = ['clone', '--depth', '1', '--recurse-submodules', '--shallow-submodules'];
-    if (version !== 'main') {
-        cloneArgs.push('--branch', version);
+    // clean up any partial previous attempt so we start fresh
+    if (fs.existsSync(sourceDir)) {
+        fs.rmSync(sourceDir, { recursive: true });
     }
-    cloneArgs.push('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'),
+    try {
+        // download tsgolint source tarball
+        console.log(`Downloading tsgolint@${version}...`);
+        const tsgolintUrl = `https://github.com/oxc-project/tsgolint/archive/refs/tags/${version}.tar.gz`;
+        await downloadAndExtract(tsgolintUrl, sourceDir);
+        // download typescript-go source tarball into tsgolint/typescript-go/
+        const tsGoDir = path.join(sourceDir, 'typescript-go');
+        console.log('Downloading typescript-go...');
+        const tsGoUrl = `https://github.com/microsoft/typescript-go/archive/${TYPESCRIPT_GO_COMMIT}.tar.gz`;
+        await downloadAndExtract(tsGoUrl, tsGoDir);
+        // apply patches to typescript-go
+        const patchesDir = path.join(sourceDir, 'patches');
+        if (fs.existsSync(patchesDir)) {
+            const count = await applyPatches(patchesDir, tsGoDir);
+            if (count > 0) {
+                console.log(`Applied ${count} patches`);
+            }
+        }
+        // copy internal/collections from typescript-go (required by tsgolint, done by `just init`)
+        const collectionsDir = path.join(sourceDir, 'internal', 'collections');
+        const tsGoCollections = path.join(tsGoDir, 'internal', 'collections');
+        if (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));
+            }
         }
+        // write ready marker
+        fs.writeFileSync(readyMarker, new Date().toISOString());
+        console.log('tsgolint source ready');
     }
-    // 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));
+    catch (err) {
+        // clean up partial download so next run starts fresh
+        if (fs.existsSync(sourceDir)) {
+            fs.rmSync(sourceDir, { recursive: true });
         }
-        console.log(`Copied ${files.length} collection files`);
+        throw err;
     }
-    // write ready marker
-    fs.writeFileSync(readyMarker, new Date().toISOString());
-    console.log('tsgolint source ready');
     return sourceDir;
 }
 export function cachedBinaryExists(contentHash) {

package/dist/cli.js

@@ -7,6 +7,7 @@ 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');
@@ -35,7 +36,9 @@ cli
     .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);
@@ -50,6 +53,7 @@ cli
     }
     const exitCode = await lint({
         rebuild: !!options.rebuild,
+        tsgolintVersion,
         passthroughArgs,
     });
     process.exit(exitCode);
@@ -57,8 +61,10 @@ cli
 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 binaryPath = await buildBinary({ rebuild: !!options.rebuild });
+    const tsgolintVersion = options.tsgolintVersion || DEFAULT_TSGOLINT_VERSION;
+    const binaryPath = await buildBinary({ rebuild: !!options.rebuild, tsgolintVersion });
     console.log(binaryPath);
 });
 cli.help();

package/dist/codegen.d.ts

@@ -8,11 +8,17 @@ import type { RuleMetadata } from './discover.ts';
  *    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 */
+/** Generate build workspace in cache dir for compiling the custom binary.
+ *  Instead of hardcoding the built-in rule list, we copy tsgolint's actual
+ *  main.go and inject custom rule imports + entries. This way the generated
+ *  code always matches the pinned tsgolint version. */
 export declare function generateBuildWorkspace({ buildDir, tsgolintDir, lintcnDir, rules, }: {
     buildDir: string;
     tsgolintDir: string;
     lintcnDir: string;
     rules: RuleMetadata[];
 }): void;
+/** Copy all supporting .go files from cmd/tsgolint/ into the wrapper dir.
+ *  main.go is generated separately with custom rules injected. */
+export declare function copyTsgolintCmdFiles(tsgolintDir: string, wrapperDir: string): void;
 //# sourceMappingURL=codegen.d.ts.map

package/dist/codegen.d.ts.map

@@ -1 +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"}
+{"version":3,"file":"codegen.d.ts","sourceRoot":"","sources":["../src/codegen.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AA2BjD;;;;;;;oFAOoF;AACpF,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAiC7D;AAED;;;uDAGuD;AACvD,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,CAiDP;AA8DD;kEACkE;AAClE,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,CAQlF"}