lintcn 0.0.1 → 0.2.0

package/dist/commands/add.js

@@ -0,0 +1,101 @@
+// lintcn add <url> — fetch a .go rule file by URL and copy into .lintcn/
+// Also tries to fetch matching _test.go file from the same directory.
+// Normalizes GitHub blob URLs to raw URLs automatically.
+import fs from 'node:fs';
+import path from 'node:path';
+import { getLintcnDir } from "../paths.js";
+import { generateEditorGoFiles } from "../codegen.js";
+import { ensureTsgolintSource, DEFAULT_TSGOLINT_VERSION } from "../cache.js";
+function normalizeGithubUrl(url) {
+    // Convert github.com/user/repo/blob/branch/path to raw.githubusercontent.com
+    const blobMatch = url.match(/^https?:\/\/github\.com\/([^/]+)\/([^/]+)\/blob\/([^/]+)\/(.+)$/);
+    if (blobMatch) {
+        const [, owner, repo, branch, filePath] = blobMatch;
+        return `https://raw.githubusercontent.com/${owner}/${repo}/${branch}/${filePath}`;
+    }
+    return url;
+}
+function deriveTestUrl(rawUrl) {
+    return rawUrl.replace(/\.go$/, '_test.go');
+}
+async function fetchFile(url) {
+    try {
+        const response = await fetch(url);
+        if (!response.ok) {
+            return null;
+        }
+        return await response.text();
+    }
+    catch {
+        return null;
+    }
+}
+function rewritePackageName(content) {
+    // Rewrite first package declaration to package lintcn
+    return content.replace(/^package\s+\w+/m, 'package lintcn');
+}
+function ensureSourceComment(content, sourceUrl) {
+    if (content.includes('// lintcn:source')) {
+        return content;
+    }
+    // Insert source comment after the first lintcn: comment block, or at the very top
+    const lines = content.split('\n');
+    let insertIndex = 0;
+    for (let i = 0; i < lines.length; i++) {
+        if (lines[i].startsWith('// lintcn:')) {
+            insertIndex = i + 1;
+        }
+        else if (insertIndex > 0) {
+            break;
+        }
+    }
+    lines.splice(insertIndex, 0, `// lintcn:source ${sourceUrl}`);
+    return lines.join('\n');
+}
+export async function addRule(url) {
+    const rawUrl = normalizeGithubUrl(url);
+    console.log(`Fetching ${rawUrl}...`);
+    const content = await fetchFile(rawUrl);
+    if (!content) {
+        throw new Error(`Could not fetch rule from ${rawUrl}`);
+    }
+    // validate it looks like a Go file with a rule
+    if (!content.includes('rule.Rule')) {
+        console.warn('Warning: no rule.Rule reference found in this file. Are you sure this is a tsgolint rule?');
+    }
+    // derive filename from URL
+    const urlPath = new URL(rawUrl).pathname;
+    const fileName = path.basename(urlPath);
+    if (!fileName.endsWith('.go')) {
+        throw new Error(`URL must point to a .go file, got: ${fileName}`);
+    }
+    const lintcnDir = getLintcnDir();
+    fs.mkdirSync(lintcnDir, { recursive: true });
+    // write the rule file
+    const filePath = path.join(lintcnDir, fileName);
+    if (fs.existsSync(filePath)) {
+        console.log(`Overwriting existing ${fileName}`);
+    }
+    let processed = rewritePackageName(content);
+    processed = ensureSourceComment(processed, url);
+    fs.writeFileSync(filePath, processed);
+    console.log(`Added ${fileName}`);
+    // try to fetch matching test file
+    const testUrl = deriveTestUrl(rawUrl);
+    const testContent = await fetchFile(testUrl);
+    if (testContent) {
+        const testFileName = fileName.replace(/\.go$/, '_test.go');
+        const testProcessed = rewritePackageName(testContent);
+        fs.writeFileSync(path.join(lintcnDir, testFileName), testProcessed);
+        console.log(`Added ${testFileName}`);
+    }
+    // ensure .tsgolint source is available and generate editor support files
+    const tsgolintDir = await ensureTsgolintSource(DEFAULT_TSGOLINT_VERSION);
+    // create .tsgolint symlink inside .lintcn for gopls
+    const tsgolintLink = path.join(lintcnDir, '.tsgolint');
+    if (!fs.existsSync(tsgolintLink)) {
+        fs.symlinkSync(tsgolintDir, tsgolintLink);
+    }
+    generateEditorGoFiles(lintcnDir);
+    console.log('Editor support files generated (go.work, go.mod)');
+}

package/dist/commands/lint.d.ts

@@ -0,0 +1,10 @@
+export declare function buildBinary({ rebuild, tsgolintVersion, }: {
+    rebuild: boolean;
+    tsgolintVersion: string;
+}): Promise<string>;
+export declare function lint({ rebuild, tsgolintVersion, passthroughArgs, }: {
+    rebuild: boolean;
+    tsgolintVersion: string;
+    passthroughArgs: string[];
+}): Promise<number>;
+//# sourceMappingURL=lint.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"lint.d.ts","sourceRoot":"","sources":["../../src/commands/lint.ts"],"names":[],"mappings":"AAuBA,wBAAsB,WAAW,CAAC,EAChC,OAAO,EACP,eAAe,GAChB,EAAE;IACD,OAAO,EAAE,OAAO,CAAA;IAChB,eAAe,EAAE,MAAM,CAAA;CACxB,GAAG,OAAO,CAAC,MAAM,CAAC,CAoDlB;AAED,wBAAsB,IAAI,CAAC,EACzB,OAAO,EACP,eAAe,EACf,eAAe,GAChB,EAAE;IACD,OAAO,EAAE,OAAO,CAAA;IAChB,eAAe,EAAE,MAAM,CAAA;IACvB,eAAe,EAAE,MAAM,EAAE,CAAA;CAC1B,GAAG,OAAO,CAAC,MAAM,CAAC,CAkBlB"}

package/dist/commands/lint.js

@@ -0,0 +1,78 @@
+// lintcn lint — build a custom tsgolint binary and run it against the project.
+// Handles Go workspace generation, compilation with caching, and execution.
+import fs from 'node:fs';
+import { spawn } from 'node:child_process';
+import { getLintcnDir } from "../paths.js";
+import { discoverRules } from "../discover.js";
+import { generateBuildWorkspace } from "../codegen.js";
+import { ensureTsgolintSource, cachedBinaryExists, getBinaryPath, getBuildDir, getBinDir } from "../cache.js";
+import { computeContentHash } from "../hash.js";
+import { execAsync } from "../exec.js";
+async function checkGoInstalled() {
+    try {
+        await execAsync('go', ['version']);
+    }
+    catch {
+        throw new Error('Go 1.26+ is required to build rules.\n' +
+            'Install from https://go.dev/dl/');
+    }
+}
+export async function buildBinary({ rebuild, tsgolintVersion, }) {
+    await checkGoInstalled();
+    const lintcnDir = getLintcnDir();
+    if (!fs.existsSync(lintcnDir)) {
+        throw new Error('No .lintcn/ directory found. Run `lintcn add <url>` first.');
+    }
+    const rules = discoverRules(lintcnDir);
+    if (rules.length === 0) {
+        throw new Error('No rules found in .lintcn/. Run `lintcn add <url>` to add rules.');
+    }
+    console.log(`Found ${rules.length} custom rule${rules.length === 1 ? '' : 's'} (tsgolint ${tsgolintVersion})`);
+    // ensure tsgolint source
+    const tsgolintDir = await ensureTsgolintSource(tsgolintVersion);
+    // compute content hash
+    const contentHash = await computeContentHash({
+        lintcnDir,
+        tsgolintVersion,
+    });
+    // check cache
+    if (!rebuild && cachedBinaryExists(contentHash)) {
+        console.log('Using cached binary');
+        return getBinaryPath(contentHash);
+    }
+    // generate build workspace
+    const buildDir = getBuildDir();
+    console.log('Generating build workspace...');
+    generateBuildWorkspace({
+        buildDir,
+        tsgolintDir,
+        lintcnDir,
+        rules,
+    });
+    // compile
+    const binDir = getBinDir();
+    fs.mkdirSync(binDir, { recursive: true });
+    const binaryPath = getBinaryPath(contentHash);
+    console.log('Compiling custom tsgolint binary...');
+    await execAsync('go', ['build', '-o', binaryPath, './wrapper'], {
+        cwd: buildDir,
+    });
+    console.log('Build complete');
+    return binaryPath;
+}
+export async function lint({ rebuild, tsgolintVersion, passthroughArgs, }) {
+    const binaryPath = await buildBinary({ rebuild, tsgolintVersion });
+    // run the binary with passthrough args, inheriting stdio
+    return new Promise((resolve) => {
+        const proc = spawn(binaryPath, passthroughArgs, {
+            stdio: 'inherit',
+        });
+        proc.on('error', (err) => {
+            console.error(`Failed to run binary: ${err.message}`);
+            resolve(1);
+        });
+        proc.on('close', (code) => {
+            resolve(code ?? 1);
+        });
+    });
+}

package/dist/commands/list.d.ts

@@ -0,0 +1,2 @@
+export declare function listRules(): void;
+//# sourceMappingURL=list.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"list.d.ts","sourceRoot":"","sources":["../../src/commands/list.ts"],"names":[],"mappings":"AAMA,wBAAgB,SAAS,IAAI,IAAI,CA0BhC"}

package/dist/commands/list.js

@@ -0,0 +1,24 @@
+// lintcn list — list installed rules with metadata from .lintcn/
+import fs from 'node:fs';
+import { getLintcnDir } from "../paths.js";
+import { discoverRules } from "../discover.js";
+export function listRules() {
+    const lintcnDir = getLintcnDir();
+    if (!fs.existsSync(lintcnDir)) {
+        console.log('No .lintcn/ directory found. Run `lintcn add <url>` to add rules.');
+        return;
+    }
+    const rules = discoverRules(lintcnDir);
+    if (rules.length === 0) {
+        console.log('No rules installed. Run `lintcn add <url>` to add rules.');
+        return;
+    }
+    console.log('Installed rules:\n');
+    const maxNameLen = Math.max(...rules.map((r) => { return r.name.length; }));
+    for (const rule of rules) {
+        const name = rule.name.padEnd(maxNameLen + 2);
+        const desc = rule.description || '(no description)';
+        console.log(`  ${name}${desc}`);
+    }
+    console.log(`\n${rules.length} rule${rules.length === 1 ? '' : 's'} installed`);
+}

package/dist/commands/remove.d.ts

@@ -0,0 +1,2 @@
+export declare function removeRule(name: string): void;
+//# sourceMappingURL=remove.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"remove.d.ts","sourceRoot":"","sources":["../../src/commands/remove.ts"],"names":[],"mappings":"AAOA,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAiC7C"}

package/dist/commands/remove.js

@@ -0,0 +1,31 @@
+// lintcn remove <name> — delete a rule and its test file from .lintcn/
+import fs from 'node:fs';
+import path from 'node:path';
+import { getLintcnDir } from "../paths.js";
+import { discoverRules } from "../discover.js";
+export function removeRule(name) {
+    const lintcnDir = getLintcnDir();
+    if (!fs.existsSync(lintcnDir)) {
+        throw new Error('No .lintcn/ directory found.');
+    }
+    // match by lintcn:name metadata or by filename
+    const rules = discoverRules(lintcnDir);
+    const normalizedName = name.replace(/-/g, '_');
+    const match = rules.find((r) => {
+        return r.name === name || r.fileName.replace(/\.go$/, '') === normalizedName;
+    });
+    if (!match) {
+        throw new Error(`Rule "${name}" not found. Run \`lintcn list\` to see installed rules.`);
+    }
+    // delete rule file
+    const rulePath = path.join(lintcnDir, match.fileName);
+    fs.rmSync(rulePath);
+    console.log(`Removed ${match.fileName}`);
+    // delete test file if exists
+    const testFileName = match.fileName.replace(/\.go$/, '_test.go');
+    const testPath = path.join(lintcnDir, testFileName);
+    if (fs.existsSync(testPath)) {
+        fs.rmSync(testPath);
+        console.log(`Removed ${testFileName}`);
+    }
+}

package/dist/discover.d.ts

@@ -0,0 +1,16 @@
+export interface RuleMetadata {
+    /** kebab-case rule name from // lintcn:name or derived from filename */
+    name: string;
+    /** one-line description from // lintcn:description */
+    description: string;
+    /** original source URL from // lintcn:source */
+    source: string;
+    /** exported Go variable name like NoFloatingPromisesRule */
+    varName: string;
+    /** filename relative to .lintcn/ */
+    fileName: string;
+}
+export declare function parseMetadata(content: string): Record<string, string>;
+export declare function parseRuleVar(content: string): string | undefined;
+export declare function discoverRules(lintcnDir: string): RuleMetadata[];
+//# sourceMappingURL=discover.d.ts.map

package/dist/discover.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"discover.d.ts","sourceRoot":"","sources":["../src/discover.ts"],"names":[],"mappings":"AAMA,MAAM,WAAW,YAAY;IAC3B,wEAAwE;IACxE,IAAI,EAAE,MAAM,CAAA;IACZ,sDAAsD;IACtD,WAAW,EAAE,MAAM,CAAA;IACnB,gDAAgD;IAChD,MAAM,EAAE,MAAM,CAAA;IACd,4DAA4D;IAC5D,OAAO,EAAE,MAAM,CAAA;IACf,oCAAoC;IACpC,QAAQ,EAAE,MAAM,CAAA;CACjB;AAKD,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAMrE;AAED,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAGhE;AAED,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,YAAY,EAAE,CAiC/D"}

package/dist/discover.js

@@ -0,0 +1,44 @@
+// Scan .lintcn/*.go files for rule.Rule variables and lintcn: metadata comments.
+// Returns structured info about each discovered rule for codegen and list display.
+import fs from 'node:fs';
+import path from 'node:path';
+const RULE_VAR_RE = /^var\s+(\w+)\s*=\s*rule\.Rule\s*\{/m;
+const METADATA_RE = /^\/\/\s*lintcn:(\w+)\s+(.+)$/gm;
+export function parseMetadata(content) {
+    const meta = {};
+    for (const match of content.matchAll(METADATA_RE)) {
+        meta[match[1]] = match[2].trim();
+    }
+    return meta;
+}
+export function parseRuleVar(content) {
+    const match = content.match(RULE_VAR_RE);
+    return match?.[1];
+}
+export function discoverRules(lintcnDir) {
+    if (!fs.existsSync(lintcnDir)) {
+        return [];
+    }
+    const files = fs.readdirSync(lintcnDir).filter((f) => {
+        return f.endsWith('.go') && !f.endsWith('_test.go');
+    });
+    const rules = [];
+    for (const fileName of files) {
+        const filePath = path.join(lintcnDir, fileName);
+        const content = fs.readFileSync(filePath, 'utf-8');
+        const varName = parseRuleVar(content);
+        if (!varName) {
+            continue;
+        }
+        const meta = parseMetadata(content);
+        const baseName = fileName.replace(/\.go$/, '');
+        rules.push({
+            name: meta.name || baseName.replace(/_/g, '-'),
+            description: meta.description || '',
+            source: meta.source || '',
+            varName,
+            fileName,
+        });
+    }
+    return rules;
+}

package/dist/exec.d.ts

@@ -0,0 +1,10 @@
+export interface ExecResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+}
+export declare function execAsync(command: string, args: string[], options?: {
+    cwd?: string;
+    stdio?: 'pipe' | 'inherit';
+}): Promise<ExecResult>;
+//# sourceMappingURL=exec.d.ts.map

package/dist/exec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exec.d.ts","sourceRoot":"","sources":["../src/exec.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,MAAM,CAAA;CACjB;AAED,wBAAgB,SAAS,CACvB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,CAAC,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,GACrD,OAAO,CAAC,UAAU,CAAC,CAkCrB"}

package/dist/exec.js

@@ -0,0 +1,34 @@
+// Async process execution utility using spawn.
+// Returns stdout/stderr as strings, rejects on non-zero exit code.
+import { spawn } from 'node:child_process';
+export function execAsync(command, args, options) {
+    return new Promise((resolve, reject) => {
+        const proc = spawn(command, args, {
+            cwd: options?.cwd,
+            stdio: options?.stdio === 'inherit' ? 'inherit' : 'pipe',
+        });
+        let stdout = '';
+        let stderr = '';
+        if (proc.stdout) {
+            proc.stdout.on('data', (data) => {
+                stdout += data.toString();
+            });
+        }
+        if (proc.stderr) {
+            proc.stderr.on('data', (data) => {
+                stderr += data.toString();
+            });
+        }
+        proc.on('error', (err) => {
+            reject(new Error(`Failed to execute ${command}: ${err.message}`, { cause: err }));
+        });
+        proc.on('close', (code) => {
+            const exitCode = code ?? 1;
+            if (exitCode !== 0 && options?.stdio !== 'inherit') {
+                reject(new Error(`${command} exited with code ${exitCode}\n${stderr}`));
+                return;
+            }
+            resolve({ stdout, stderr, exitCode });
+        });
+    });
+}

package/dist/hash.d.ts

@@ -0,0 +1,5 @@
+export declare function computeContentHash({ lintcnDir, tsgolintVersion, }: {
+    lintcnDir: string;
+    tsgolintVersion: string;
+}): Promise<string>;
+//# sourceMappingURL=hash.d.ts.map

package/dist/hash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hash.d.ts","sourceRoot":"","sources":["../src/hash.ts"],"names":[],"mappings":"AASA,wBAAsB,kBAAkB,CAAC,EACvC,SAAS,EACT,eAAe,GAChB,EAAE;IACD,SAAS,EAAE,MAAM,CAAA;IACjB,eAAe,EAAE,MAAM,CAAA;CACxB,GAAG,OAAO,CAAC,MAAM,CAAC,CA6BlB"}

package/dist/hash.js

@@ -0,0 +1,33 @@
+// Content hash for binary caching.
+// Combines tsgolint version, rule file contents, Go version, and platform
+// into a single SHA-256 hash used as the cached binary filename.
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { execAsync } from "./exec.js";
+export async function computeContentHash({ lintcnDir, tsgolintVersion, }) {
+    const hash = crypto.createHash('sha256');
+    hash.update(`tsgolint:${tsgolintVersion}\n`);
+    hash.update(`platform:${process.platform}-${process.arch}\n`);
+    // add Go version
+    try {
+        const { stdout } = await execAsync('go', ['version']);
+        hash.update(`go:${stdout.trim()}\n`);
+    }
+    catch {
+        hash.update('go:unknown\n');
+    }
+    // add all rule file contents in sorted order
+    const files = fs
+        .readdirSync(lintcnDir)
+        .filter((f) => {
+        return f.endsWith('.go');
+    })
+        .sort();
+    for (const file of files) {
+        const content = fs.readFileSync(path.join(lintcnDir, file), 'utf-8');
+        hash.update(`file:${file}\n`);
+        hash.update(content);
+    }
+    return hash.digest('hex').slice(0, 16);
+}

package/dist/index.d.ts

@@ -1,2 +1,8 @@
-export declare const version = "0.0.1";
+export { discoverRules, parseMetadata, parseRuleVar } from './discover.ts';
+export type { RuleMetadata } from './discover.ts';
+export { addRule } from './commands/add.ts';
+export { lint, buildBinary } from './commands/lint.ts';
+export { listRules } from './commands/list.ts';
+export { removeRule } from './commands/remove.ts';
+export { DEFAULT_TSGOLINT_VERSION } from './cache.ts';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,OAAO,UAAU,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAC1E,YAAY,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AACjD,OAAO,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAA;AAC3C,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AACtD,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAA;AAC9C,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AACjD,OAAO,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAA"}

package/dist/index.js

@@ -1 +1,6 @@
-export const version = '0.0.1';
+export { discoverRules, parseMetadata, parseRuleVar } from "./discover.js";
+export { addRule } from "./commands/add.js";
+export { lint, buildBinary } from "./commands/lint.js";
+export { listRules } from "./commands/list.js";
+export { removeRule } from "./commands/remove.js";
+export { DEFAULT_TSGOLINT_VERSION } from "./cache.js";

package/dist/paths.d.ts

@@ -0,0 +1,2 @@
+export declare function getLintcnDir(): string;
+//# sourceMappingURL=paths.d.ts.map

package/dist/paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../src/paths.ts"],"names":[],"mappings":"AAIA,wBAAgB,YAAY,IAAI,MAAM,CAErC"}

package/dist/paths.js

@@ -0,0 +1,5 @@
+// Resolve the .lintcn/ directory path relative to cwd.
+import path from 'node:path';
+export function getLintcnDir() {
+    return path.resolve(process.cwd(), '.lintcn');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lintcn",
-  "version": "0.0.1",
+  "version": "0.2.0",
   "type": "module",
   "description": "The shadcn for type-aware TypeScript lint rules. Browse, pick, and copy rules into your project.",
   "bin": "dist/cli.js",
@@ -24,12 +24,9 @@
   "files": [
     "src",
     "dist",
-    "README.md"
+    "README.md",
+    "CHANGELOG.md"
   ],
-  "scripts": {
-    "build": "rm -rf dist *.tsbuildinfo && tsc && chmod +x dist/cli.js",
-    "prepublishOnly": "pnpm build"
-  },
   "keywords": [
     "lint",
     "linter",
@@ -53,7 +50,13 @@
   },
   "license": "MIT",
   "devDependencies": {
-    "typescript": "5.8.2",
-    "@types/node": "^22.0.0"
+    "@types/node": "^22.0.0",
+    "typescript": "5.8.2"
+  },
+  "dependencies": {
+    "goke": "^6.3.0"
+  },
+  "scripts": {
+    "build": "rm -rf dist *.tsbuildinfo && tsc && chmod +x dist/cli.js"
   }
-}
+}

package/src/cache.ts

@@ -0,0 +1,106 @@
+// 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.ts'
+
+// 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(): string {
+  return path.join(os.homedir(), '.cache', 'lintcn')
+}
+
+export function getTsgolintSourceDir(version: string): string {
+  return path.join(getCacheDir(), 'tsgolint', version)
+}
+
+export function getBinDir(): string {
+  return path.join(getCacheDir(), 'bin')
+}
+
+export function getBinaryPath(contentHash: string): string {
+  return path.join(getBinDir(), contentHash)
+}
+
+export function getBuildDir(): string {
+  return path.join(getCacheDir(), 'build')
+}
+
+export async function ensureTsgolintSource(version: string): Promise<string> {
+  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: string): boolean {
+  const binPath = getBinaryPath(contentHash)
+  try {
+    fs.accessSync(binPath, fs.constants.X_OK)
+    return true
+  } catch {
+    return false
+  }
+}