lintcn 0.5.0 → 0.6.0

package/dist/commands/remove.js

@@ -1,28 +1,20 @@
-// lintcn remove <name> — delete a rule and its test file from .lintcn/
+// lintcn remove <name> — delete a rule subfolder from .lintcn/
 import fs from 'node:fs';
 import path from 'node:path';
 import { requireLintcnDir } from "../paths.js";
 import { discoverRules } from "../discover.js";
 export function removeRule(name) {
     const lintcnDir = requireLintcnDir();
-    // 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;
+        return r.name === name || r.packageName === 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}`);
-    }
+    // Remove the entire subfolder
+    const ruleDir = path.join(lintcnDir, match.packageName);
+    fs.rmSync(ruleDir, { recursive: true });
+    console.log(`Removed ${match.packageName}/`);
 }

package/dist/discover.d.ts

@@ -1,5 +1,5 @@
 export interface RuleMetadata {
-    /** kebab-case rule name from // lintcn:name or derived from filename */
+    /** kebab-case rule name from // lintcn:name or derived from folder name */
     name: string;
     /** one-line description from // lintcn:description */
     description: string;
@@ -7,8 +7,8 @@ export interface RuleMetadata {
     source: string;
     /** exported Go variable name like NoFloatingPromisesRule */
     varName: string;
-    /** filename relative to .lintcn/ */
-    fileName: string;
+    /** Go package name (= subfolder name, e.g. no_floating_promises) */
+    packageName: string;
 }
 export declare function parseMetadata(content: string): Record<string, string>;
 export declare function parseRuleVar(content: string): string | undefined;

package/dist/discover.d.ts.map

@@ -1 +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;AAOD,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,CAwC/D"}
+{"version":3,"file":"discover.d.ts","sourceRoot":"","sources":["../src/discover.ts"],"names":[],"mappings":"AAOA,MAAM,WAAW,YAAY;IAC3B,2EAA2E;IAC3E,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,oEAAoE;IACpE,WAAW,EAAE,MAAM,CAAA;CACpB;AAOD,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,CAgD/D"}

package/dist/discover.js

@@ -1,4 +1,5 @@
-// Scan .lintcn/*.go files for rule.Rule variables and lintcn: metadata comments.
+// Scan .lintcn/*/ subfolders for rule.Rule variables and lintcn: metadata comments.
+// Each subfolder is a Go package containing one rule with its companions.
 // Returns structured info about each discovered rule for codegen and list display.
 import fs from 'node:fs';
 import path from 'node:path';
@@ -21,31 +22,39 @@ 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) {
-            // warn if file contains rule.Rule but we couldn't parse the var name
-            if (content.includes('rule.Rule')) {
-                console.warn(`Warning: ${fileName} contains rule.Rule but no exported var was found. ` +
-                    `Expected pattern: var XxxRule = rule.Rule{`);
-            }
+    const entries = fs.readdirSync(lintcnDir, { withFileTypes: true });
+    // Warn about flat .go files that should be in subfolders
+    const flatGoFiles = entries.filter((e) => {
+        return e.isFile() && e.name.endsWith('.go');
+    });
+    for (const file of flatGoFiles) {
+        const baseName = file.name.replace(/(_test)?\.go$/, '');
+        console.error(`Error: ${file.name} is a flat file in .lintcn/ — rules must be in subfolders.\n` +
+            `  Move it to .lintcn/${baseName}/${file.name} and change the package to "${baseName}".\n`);
+    }
+    for (const entry of entries) {
+        if (!entry.isDirectory() || entry.name.startsWith('.'))
             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,
+        const subDir = path.join(lintcnDir, entry.name);
+        const goFiles = fs.readdirSync(subDir).filter((f) => {
+            return f.endsWith('.go') && !f.endsWith('_test.go');
         });
+        for (const fileName of goFiles) {
+            const filePath = path.join(subDir, fileName);
+            const content = fs.readFileSync(filePath, 'utf-8');
+            const varName = parseRuleVar(content);
+            if (!varName)
+                continue;
+            const meta = parseMetadata(content);
+            rules.push({
+                name: meta.name || entry.name.replace(/_/g, '-'),
+                description: meta.description || '',
+                source: meta.source || '',
+                varName,
+                packageName: entry.name,
+            });
+        }
     }
     return rules;
 }

package/dist/hash.d.ts

@@ -1,5 +1,11 @@
+/** Compute a deterministic content hash for binary caching.
+ *  Returns: { short: "a1b2c3d4..." (16 hex), full: "a1b2c3d4..." (64 hex) }
+ *  The short hash is used for local cache paths, the full hash for remote cache keys. */
 export declare function computeContentHash({ lintcnDir, tsgolintVersion, }: {
     lintcnDir: string;
     tsgolintVersion: string;
-}): Promise<string>;
+}): Promise<{
+    short: string;
+    full: string;
+}>;
 //# sourceMappingURL=hash.d.ts.map

package/dist/hash.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hash.d.ts","sourceRoot":"","sources":["../src/hash.ts"],"names":[],"mappings":"AAaA,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,CA8BlB"}
+{"version":3,"file":"hash.d.ts","sourceRoot":"","sources":["../src/hash.ts"],"names":[],"mappings":"AAiBA;;yFAEyF;AACzF,wBAAsB,kBAAkB,CAAC,EACvC,SAAS,EACT,eAAe,GAChB,EAAE;IACD,SAAS,EAAE,MAAM,CAAA;IACjB,eAAe,EAAE,MAAM,CAAA;CACxB,GAAG,OAAO,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CA2B3C"}

package/dist/hash.js

@@ -1,37 +1,40 @@
-// Content hash for binary caching.
-// Combines cache schema version, tsgolint version, rule file contents,
-// Go version, and platform into a single SHA-256 hash.
+// Content hash for binary caching (local + remote).
+// Combines cache schema version, tsgolint version, platform triplet,
+// and non-test rule file contents into a SHA-256 hash.
+//
+// The hash is deterministic across machines — same rules + same tsgolint
+// version + same platform = same hash. Go version is NOT included because
+// the compiled binary is standalone (no Go runtime dependency).
+//
 // Bump CACHE_SCHEMA_VERSION when codegen logic changes to invalidate
 // stale binaries built by older lintcn versions.
 import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
-import { execAsync } from "./exec.js";
-const CACHE_SCHEMA_VERSION = '2';
+const CACHE_SCHEMA_VERSION = '4';
+/** Compute a deterministic content hash for binary caching.
+ *  Returns: { short: "a1b2c3d4..." (16 hex), full: "a1b2c3d4..." (64 hex) }
+ *  The short hash is used for local cache paths, the full hash for remote cache keys. */
 export async function computeContentHash({ lintcnDir, tsgolintVersion, }) {
     const hash = crypto.createHash('sha256');
     hash.update(`cache-schema:${CACHE_SCHEMA_VERSION}\n`);
     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`);
+    // walk rule subfolders for non-test .go files in sorted order
+    const entries = fs.readdirSync(lintcnDir, { withFileTypes: true })
+        .filter((e) => { return e.isDirectory() && !e.name.startsWith('.'); })
+        .sort((a, b) => { return a.name.localeCompare(b.name); });
+    for (const entry of entries) {
+        const subDir = path.join(lintcnDir, entry.name);
+        const goFiles = fs.readdirSync(subDir)
+            .filter((f) => { return f.endsWith('.go') && !f.endsWith('_test.go'); })
+            .sort();
+        for (const file of goFiles) {
+            const content = fs.readFileSync(path.join(subDir, file), 'utf-8');
+            hash.update(`file:${entry.name}/${file}\n`);
+            hash.update(content);
+        }
     }
-    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);
+    const full = hash.digest('hex');
+    return { short: full.slice(0, 16), full };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lintcn",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "type": "module",
   "description": "The shadcn for type-aware TypeScript lint rules. Browse, pick, and copy rules into your project.",
   "bin": "dist/cli.js",

package/src/cli.ts

@@ -9,6 +9,7 @@ import { addRule } from './commands/add.ts'
 import { lint, buildBinary } from './commands/lint.ts'
 import { listRules } from './commands/list.ts'
 import { removeRule } from './commands/remove.ts'
+import { clean } from './commands/clean.ts'
 import { DEFAULT_TSGOLINT_VERSION } from './cache.ts'
 
 const require = createRequire(import.meta.url)
@@ -17,11 +18,11 @@ const packageJson = require('../package.json') as { version: string }
 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 a rule by GitHub URL. Fetches the whole folder into .lintcn/{rule}/')
+  .example('# Add a 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')
   .action(async (url) => {
     await addRule(url)
   })
@@ -77,6 +78,12 @@ cli
     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/src/codegen.ts

@@ -129,10 +129,29 @@ go 1.26
   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: string): string {
+  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: RuleMetadata[]): string {
+  // 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.
@@ -143,7 +162,7 @@ import (
 
 \t"${TSGOLINT_MODULE}/internal/rule"
 \t"${TSGOLINT_MODULE}/internal/runner"
-\tlintcn "${TSGOLINT_MODULE}/lintcn-rules"
+${imports}
 )
 
 func main() {

package/src/commands/add.ts

@@ -1,69 +1,110 @@
-// 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.
+// lintcn add <url> — fetch a rule folder by URL and copy into .lintcn/{rule_name}/
+// Supports GitHub folder URLs (/tree/) and file URLs (/blob/).
+// For file URLs, auto-detects the parent folder and fetches all sibling files.
+// Uses GitHub API to list folder contents.
 
 import fs from 'node:fs'
 import path from 'node:path'
+import { execSync } from 'node:child_process'
 import { getLintcnDir } from '../paths.ts'
 import { generateEditorGoFiles } from '../codegen.ts'
 import { ensureTsgolintSource, DEFAULT_TSGOLINT_VERSION } from '../cache.ts'
 
-/** Convert GitHub blob URLs to raw.githubusercontent.com.
- *  Handles branch names containing slashes (e.g. feature/x) by splitting
- *  on /blob/ then finding the file path from the end (must end in .go). */
-function normalizeGithubUrl(url: string): string {
-  const blobSplit = url.match(/^(https?:\/\/github\.com\/[^/]+\/[^/]+)\/blob\/(.+)$/)
-  if (!blobSplit) {
-    return url
+interface ParsedGitHubUrl {
+  owner: string
+  repo: string
+  ref: string
+  /** Path to the directory containing the rule files */
+  dirPath: string
+  /** Set when URL points to a specific file (not a folder) */
+  fileName?: string
+}
+
+/** Parse GitHub blob/tree/raw URLs into components.
+ *  Ref is assumed to be the first path component after blob/tree —
+ *  branch names with slashes (e.g. feature/foo) are not supported. */
+function parseGitHubUrl(url: string): ParsedGitHubUrl | null {
+  // GitHub blob URLs: github.com/owner/repo/blob/ref/path/to/file.go
+  let match = url.match(/^https?:\/\/github\.com\/([^/]+)\/([^/]+)\/blob\/([^/]+)\/(.+)$/)
+  if (match) {
+    const [, owner, repo, ref, filePath] = match
+    return { owner, repo, ref, dirPath: path.posix.dirname(filePath), fileName: path.posix.basename(filePath) }
   }
 
-  const [, repoUrl, refAndPath] = blobSplit
-  // repoUrl = "https://github.com/owner/repo"
-  // refAndPath = "feature/x/rules/my_rule.go" or "main/rules/my_rule.go"
+  // GitHub tree URLs: github.com/owner/repo/tree/ref/path/to/folder
+  match = url.match(/^https?:\/\/github\.com\/([^/]+)\/([^/]+)\/tree\/([^/]+)\/(.+)$/)
+  if (match) {
+    const [, owner, repo, ref, dirPath] = match
+    return { owner, repo, ref, dirPath }
+  }
 
-  // Extract owner/repo from repoUrl
-  const repoMatch = repoUrl.match(/github\.com\/([^/]+)\/([^/]+)$/)
-  if (!repoMatch) {
-    return url
+  // raw.githubusercontent.com URLs
+  match = url.match(/^https?:\/\/raw\.githubusercontent\.com\/([^/]+)\/([^/]+)\/([^/]+)\/(.+)$/)
+  if (match) {
+    const [, owner, repo, ref, filePath] = match
+    return { owner, repo, ref, dirPath: path.posix.dirname(filePath), fileName: path.posix.basename(filePath) }
   }
-  const [, owner, repo] = repoMatch
 
-  // For raw.githubusercontent.com, the format is owner/repo/ref/path.
-  // We can pass refAndPath directly since GitHub resolves it.
-  return `https://raw.githubusercontent.com/${owner}/${repo}/${refAndPath}`
+  return null
 }
 
-function deriveTestUrl(rawUrl: string): string {
-  return rawUrl.replace(/\.go$/, '_test.go')
+interface GitHubContentItem {
+  name: string
+  download_url: string | null
+  type: 'file' | 'dir'
 }
 
-async function fetchFile(url: string): Promise<string> {
-  const response = await fetch(url)
-  if (!response.ok) {
-    throw new Error(`Failed to fetch ${url}: ${response.status} ${response.statusText}`)
+/** Get a GitHub auth token from gh CLI, GITHUB_TOKEN env, or return undefined. */
+function getGitHubToken(): string | undefined {
+  if (process.env.GITHUB_TOKEN) {
+    return process.env.GITHUB_TOKEN
   }
-  return response.text()
-}
-
-async function tryFetchFile(url: string): Promise<string | null> {
+  // Try gh CLI token (synchronous to keep it simple)
   try {
-    return await fetchFile(url)
+    return execSync('gh auth token', { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }).trim() || undefined
   } catch {
-    return null
+    return undefined
   }
 }
 
-function rewritePackageName(content: string): string {
-  // Rewrite first package declaration to package lintcn.
-  // Only matches before the first import or func to avoid touching comments.
-  return content.replace(/^package\s+\w+/m, 'package lintcn')
+/** List files in a GitHub directory via the Contents API. */
+async function listGitHubFolder(owner: string, repo: string, dirPath: string, ref: string): Promise<GitHubContentItem[]> {
+  const apiUrl = `https://api.github.com/repos/${owner}/${repo}/contents/${dirPath}?ref=${ref}`
+  const headers: Record<string, string> = {
+    'Accept': 'application/vnd.github.v3+json',
+    'User-Agent': 'lintcn',
+  }
+  const token = getGitHubToken()
+  if (token) {
+    headers['Authorization'] = `Bearer ${token}`
+  }
+  const response = await fetch(apiUrl, { headers })
+
+  if (!response.ok) {
+    throw new Error(`GitHub API error: ${response.status} ${response.statusText}\n  ${apiUrl}`)
+  }
+
+  const data = await response.json()
+  if (!Array.isArray(data)) {
+    throw new Error(`Expected a directory listing from GitHub API but got a single file.\n  ${apiUrl}`)
+  }
+
+  return data as GitHubContentItem[]
+}
+
+async function fetchFile(url: string): Promise<string> {
+  const response = await fetch(url)
+  if (!response.ok) {
+    throw new Error(`Failed to fetch ${url}: ${response.status} ${response.statusText}`)
+  }
+  return response.text()
 }
 
 function ensureSourceComment(content: string, sourceUrl: string): string {
   if (content.includes('// lintcn:source')) {
     return content
   }
-  // Insert source comment after the first lintcn: comment block, or at the very top
+  // Insert source comment after any existing lintcn: comment block, or at the very top
   const lines = content.split('\n')
   let insertIndex = 0
   for (let i = 0; i < lines.length; i++) {
@@ -78,59 +119,76 @@ function ensureSourceComment(content: string, sourceUrl: string): string {
 }
 
 export async function addRule(url: string): Promise<void> {
-  const rawUrl = normalizeGithubUrl(url)
+  const parsed = parseGitHubUrl(url)
+  if (!parsed) {
+    throw new Error(
+      'Only GitHub URLs are supported. Pass a /blob/ (file) or /tree/ (folder) URL.\n' +
+      'Example: lintcn add https://github.com/oxc-project/tsgolint/tree/main/internal/rules/no_floating_promises',
+    )
+  }
+
+  const { owner, repo, ref, dirPath } = parsed
+  const folderName = path.posix.basename(dirPath)
+
+  console.log(`Fetching ${owner}/${repo}/${dirPath}...`)
+  const items = await listGitHubFolder(owner, repo, dirPath, ref)
 
-  console.log(`Fetching ${rawUrl}...`)
-  const content = await fetchFile(rawUrl)
+  // Filter for .go and .json files
+  const filesToFetch = items.filter((item) => {
+    return item.type === 'file' && item.download_url && (item.name.endsWith('.go') || item.name.endsWith('.json'))
+  })
 
-  // 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?')
+  if (filesToFetch.length === 0) {
+    throw new Error(`No .go files found in ${dirPath}. Is this a rule folder?`)
   }
 
-  // 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}`)
+  // Warn if this doesn't look like a single-rule folder (too many main .go files)
+  const mainGoFiles = filesToFetch.filter((f) => {
+    return f.name.endsWith('.go') && !f.name.endsWith('_test.go') && f.name !== 'options.go'
+  })
+  if (mainGoFiles.length > 3) {
+    console.warn(
+      `Warning: folder has ${mainGoFiles.length} non-test .go files. ` +
+      `This may be a directory of multiple rules — consider using a more specific URL.`,
+    )
   }
 
   const lintcnDir = getLintcnDir()
-  fs.mkdirSync(lintcnDir, { recursive: true })
+  const ruleDir = path.join(lintcnDir, folderName)
 
-  // write the rule file
-  const filePath = path.join(lintcnDir, fileName)
-  if (fs.existsSync(filePath)) {
-    console.log(`Overwriting existing ${fileName}`)
+  // Clean existing rule folder if it exists
+  if (fs.existsSync(ruleDir)) {
+    fs.rmSync(ruleDir, { recursive: true })
+    console.log(`Overwriting existing ${folderName}/`)
   }
 
-  let processed = rewritePackageName(content)
-  processed = ensureSourceComment(processed, url)
-  fs.writeFileSync(filePath, processed)
-  console.log(`Added ${fileName}`)
+  fs.mkdirSync(ruleDir, { recursive: true })
 
-  // try to fetch matching test file
-  const testUrl = deriveTestUrl(rawUrl)
-  const testContent = await tryFetchFile(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}`)
+  // Fetch and write all files
+  for (const item of filesToFetch) {
+    let content = await fetchFile(item.download_url!)
+
+    // Add lintcn:source comment to the main rule file (same name as folder)
+    if (item.name === `${folderName}.go`) {
+      content = ensureSourceComment(content, url)
+    }
+
+    fs.writeFileSync(path.join(ruleDir, item.name), content)
+    console.log(`  ${item.name}`)
   }
 
-  // ensure .tsgolint source is available and generate editor support files
+  console.log(`Added ${folderName}/ (${filesToFetch.length} files)`)
+
+  // Ensure tsgolint source is available
   const tsgolintDir = await ensureTsgolintSource(DEFAULT_TSGOLINT_VERSION)
 
-  // create .tsgolint symlink inside .lintcn for gopls.
-  // Use lstatSync to detect broken symlinks (existsSync returns false for broken links)
+  // Create/refresh .tsgolint symlink for gopls
   const tsgolintLink = path.join(lintcnDir, '.tsgolint')
   try {
     fs.lstatSync(tsgolintLink)
-    // exists (possibly broken) — remove and recreate
     fs.rmSync(tsgolintLink, { force: true })
   } catch {
-    // doesn't exist at all
+    // doesn't exist
   }
   fs.symlinkSync(tsgolintDir, tsgolintLink)
 

package/src/commands/clean.ts

@@ -0,0 +1,48 @@
+// lintcn clean — remove cached tsgolint source and compiled binaries.
+// Frees disk space from old versions that accumulate over time.
+
+import fs from 'node:fs'
+import { getCacheDir } from '../cache.ts'
+
+export function clean(): void {
+  const cacheDir = getCacheDir()
+
+  if (!fs.existsSync(cacheDir)) {
+    console.log('No cache to clean')
+    return
+  }
+
+  const stats = getCacheStats(cacheDir)
+  fs.rmSync(cacheDir, { recursive: true })
+  console.log(`Removed ${cacheDir} (${formatBytes(stats.totalBytes)})`)
+}
+
+function getCacheStats(dir: string): { totalBytes: number } {
+  let totalBytes = 0
+  const walk = (d: string): void => {
+    for (const entry of fs.readdirSync(d, { withFileTypes: true })) {
+      const fullPath = `${d}/${entry.name}`
+      if (entry.isDirectory()) {
+        walk(fullPath)
+      } else {
+        totalBytes += fs.statSync(fullPath).size
+      }
+    }
+  }
+  try {
+    walk(dir)
+  } catch {
+    // ignore errors during stat
+  }
+  return { totalBytes }
+}
+
+function formatBytes(bytes: number): string {
+  if (bytes < 1024) {
+    return `${bytes}B`
+  }
+  if (bytes < 1024 * 1024) {
+    return `${(bytes / 1024).toFixed(0)}KB`
+  }
+  return `${(bytes / (1024 * 1024)).toFixed(0)}MB`
+}