lintcn 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -1,3 +1,59 @@
+## 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.

package/README.md

@@ -48,8 +48,7 @@ my-project/
 │   ├── no_floating_promises/
 │   │   ├── no_floating_promises.go         ← rule source (committed)
 │   │   ├── no_floating_promises_test.go    ← tests (committed)
-│   │   ├── options.go                      ← rule options struct
-│   │   └── schema.json                     ← options schema
+│   │   └── options.go                      ← rule options struct
 │   ├── await_thenable/
 │   │   ├── await_thenable.go
 │   │   └── await_thenable_test.go
@@ -141,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 `~`:

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

@@ -13,11 +13,13 @@ const require = createRequire(import.meta.url);
 const packageJson = require('../package.json');
 const cli = goke('lintcn');
 cli
-    .command('add <url>', 'Add a rule by GitHub URL. Fetches the whole folder into .lintcn/{rule}/')
-    .example('# Add a rule folder')
+    .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);
 });
@@ -35,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);
     }
@@ -56,6 +63,7 @@ cli
         rebuild: !!options.rebuild,
         tsgolintVersion,
         passthroughArgs,
+        allWarnings: !!options.allWarnings,
     });
     process.exit(exitCode);
 });

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

@@ -1 +1 @@
-{"version":3,"file":"add.d.ts","sourceRoot":"","sources":["../../src/commands/add.ts"],"names":[],"mappings":"AAwHA,wBAAsB,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA4ExD"}
+{"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"}

package/dist/commands/add.js

@@ -8,28 +8,49 @@ import { execSync } from 'node:child_process';
 import { getLintcnDir } from "../paths.js";
 import { generateEditorGoFiles } from "../codegen.js";
 import { ensureTsgolintSource, DEFAULT_TSGOLINT_VERSION } from "../cache.js";
-/** 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. */
+/** Parse any GitHub URL into components.
+ *  Supports: bare repo, /tree/ folders, /blob/ files, raw.githubusercontent.com.
+ *  Ref is the first path component after blob/tree — branch names with slashes
+ *  (e.g. feature/foo) are not supported. */
 function parseGitHubUrl(url) {
-    // 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) };
+    let hostname;
+    let segments;
+    try {
+        const u = new URL(url);
+        hostname = u.hostname;
+        segments = u.pathname.replace(/\/$/, '').split('/').filter(Boolean);
     }
-    // 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 };
+    catch {
+        return null;
     }
-    // raw.githubusercontent.com URLs
-    match = url.match(/^https?:\/\/raw\.githubusercontent\.com\/([^/]+)\/([^/]+)\/([^/]+)\/(.+)$/);
-    if (match) {
-        const [, owner, repo, ref, filePath] = match;
+    // raw.githubusercontent.com/owner/repo/ref/path/to/file
+    if (hostname === 'raw.githubusercontent.com') {
+        if (segments.length < 4)
+            return null;
+        const [owner, repo, ref, ...rest] = segments;
+        const filePath = rest.join('/');
         return { owner, repo, ref, dirPath: path.posix.dirname(filePath), fileName: path.posix.basename(filePath) };
     }
+    if (hostname !== 'github.com')
+        return null;
+    if (segments.length < 2)
+        return null;
+    const [owner, repo, kind, ref, ...rest] = segments;
+    // Bare repo URL: github.com/owner/repo
+    if (!kind) {
+        return { owner, repo, ref: undefined, dirPath: '' };
+    }
+    const subPath = rest.join('/');
+    if (kind === 'tree') {
+        if (!ref || !subPath)
+            return null;
+        return { owner, repo, ref, dirPath: subPath };
+    }
+    if (kind === 'blob') {
+        if (!ref || !subPath)
+            return null;
+        return { owner, repo, ref, dirPath: path.posix.dirname(subPath), fileName: path.posix.basename(subPath) };
+    }
     return null;
 }
 /** Get a GitHub auth token from gh CLI, GITHUB_TOKEN env, or return undefined. */
@@ -45,6 +66,28 @@ function getGitHubToken() {
         return undefined;
     }
 }
+/** Resolve the default branch for a repo (e.g. "main", "master"). */
+async function resolveDefaultBranch(owner, repo) {
+    const apiUrl = `https://api.github.com/repos/${owner}/${repo}`;
+    const headers = {
+        '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());
+    return data.default_branch;
+}
+/** Files/dirs in .lintcn/ that are generated and should not be treated as rule folders. */
+const LINTCN_GENERATED = new Set([
+    '.tsgolint', '.gitignore', 'go.work', 'go.work.sum', 'go.mod', 'go.sum',
+]);
 /** List files in a GitHub directory via the Contents API. */
 async function listGitHubFolder(owner, repo, dirPath, ref) {
     const apiUrl = `https://api.github.com/repos/${owner}/${repo}/contents/${dirPath}?ref=${ref}`;
@@ -91,53 +134,39 @@ function ensureSourceComment(content, sourceUrl) {
     lines.splice(insertIndex, 0, `// lintcn:source ${sourceUrl}`);
     return lines.join('\n');
 }
-export async function addRule(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;
+/** Download a single rule folder into .lintcn/{folderName}/.
+ *  Overwrites existing folder if present.
+ *  Returns true if the rule was added, false if skipped (no .go files). */
+async function downloadSingleRule(owner, repo, ref, dirPath, lintcnDir, sourceUrl) {
     const folderName = path.posix.basename(dirPath);
-    console.log(`Fetching ${owner}/${repo}/${dirPath}...`);
     const items = await listGitHubFolder(owner, repo, dirPath, ref);
-    // 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'));
     });
     if (filesToFetch.length === 0) {
-        throw new Error(`No .go files found in ${dirPath}. Is this a rule folder?`);
-    }
-    // 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.`);
+        console.warn(`  Skipping ${folderName}/ — no .go files found`);
+        return false;
     }
-    const lintcnDir = getLintcnDir();
     const ruleDir = path.join(lintcnDir, folderName);
-    // Clean existing rule folder if it exists
     if (fs.existsSync(ruleDir)) {
         fs.rmSync(ruleDir, { recursive: true });
-        console.log(`Overwriting existing ${folderName}/`);
+        console.log(`  Overwriting existing ${folderName}/`);
     }
     fs.mkdirSync(ruleDir, { recursive: true });
-    // 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);
+            content = ensureSourceComment(content, sourceUrl);
         }
         fs.writeFileSync(path.join(ruleDir, item.name), content);
-        console.log(`  ${item.name}`);
+        console.log(`    ${item.name}`);
     }
-    console.log(`Added ${folderName}/ (${filesToFetch.length} files)`);
-    // Ensure tsgolint source is available
+    console.log(`  Added ${folderName}/ (${filesToFetch.length} files)`);
+    return true;
+}
+/** Ensure tsgolint source, refresh symlink, regenerate go.work/go.mod. */
+async function finalizeLintcnDir(lintcnDir) {
     const tsgolintDir = await ensureTsgolintSource(DEFAULT_TSGOLINT_VERSION);
-    // Create/refresh .tsgolint symlink for gopls
     const tsgolintLink = path.join(lintcnDir, '.tsgolint');
     try {
         fs.lstatSync(tsgolintLink);
@@ -150,3 +179,89 @@ export async function addRule(url) {
     generateEditorGoFiles(lintcnDir);
     console.log('Editor support files generated (go.work, go.mod)');
 }
+/** Download all rule subfolders from a remote .lintcn/ directory.
+ *  Each subfolder is treated as a separate rule. Local rules not present
+ *  in the remote are preserved (merge, not replace). */
+async function addLintcnFolder(owner, repo, ref, lintcnPath, sourceUrl) {
+    console.log(`Fetching .lintcn/ from ${owner}/${repo}...`);
+    const items = await listGitHubFolder(owner, repo, lintcnPath, ref);
+    const ruleDirs = items.filter((item) => {
+        return item.type === 'dir' && !LINTCN_GENERATED.has(item.name) && !item.name.startsWith('.');
+    });
+    if (ruleDirs.length === 0) {
+        throw new Error(`No rule folders found in ${lintcnPath}. Is this a .lintcn/ directory?`);
+    }
+    console.log(`Found ${ruleDirs.length} rule(s)`);
+    const lintcnDir = getLintcnDir();
+    let added = 0;
+    for (const dir of ruleDirs) {
+        const ruleDirPath = lintcnPath ? `${lintcnPath}/${dir.name}` : dir.name;
+        const ok = await downloadSingleRule(owner, repo, ref, ruleDirPath, lintcnDir, sourceUrl);
+        if (ok)
+            added++;
+    }
+    if (added === 0) {
+        throw new Error(`No rule folders with .go files found in ${lintcnPath}.`);
+    }
+    await finalizeLintcnDir(lintcnDir);
+    console.log(`\nDone — added ${added} rule(s) from ${owner}/${repo}`);
+}
+export async function addRule(url) {
+    const parsed = parseGitHubUrl(url);
+    if (!parsed) {
+        throw new Error('Only GitHub URLs are supported.\n' +
+            'Examples:\n' +
+            '  lintcn add https://github.com/someone/their-project\n' +
+            '  lintcn add https://github.com/oxc-project/tsgolint/tree/main/internal/rules/no_floating_promises');
+    }
+    const { owner, repo, fileName } = parsed;
+    let { ref, dirPath } = parsed;
+    // Bare repo URL — resolve default branch and look for .lintcn/ at root
+    if (ref === undefined) {
+        ref = await resolveDefaultBranch(owner, repo);
+        console.log(`Resolved default branch: ${ref}`);
+        const rootItems = await listGitHubFolder(owner, repo, '', ref);
+        const lintcnEntry = rootItems.find((item) => item.type === 'dir' && item.name === '.lintcn');
+        if (!lintcnEntry) {
+            throw new Error(`No .lintcn/ directory found in ${owner}/${repo}.\n` +
+                'The repo needs a .lintcn/ folder with rule subfolders.');
+        }
+        await addLintcnFolder(owner, repo, ref, '.lintcn', url);
+        return;
+    }
+    // For blob/raw URLs, dirPath already points at the parent folder
+    // For tree URLs, dirPath is the folder itself — but it might be a .lintcn/ collection
+    if (!fileName) {
+        const items = await listGitHubFolder(owner, repo, dirPath, ref);
+        const hasGoFiles = items.some((i) => i.type === 'file' && i.name.endsWith('.go'));
+        const hasCandidateSubdirs = items.some((i) => {
+            return i.type === 'dir' && !LINTCN_GENERATED.has(i.name) && !i.name.startsWith('.');
+        });
+        const isLintcnDir = path.posix.basename(dirPath) === '.lintcn';
+        // Collection if: explicitly .lintcn/, or has subdirs but no .go files at root.
+        // A single rule folder with testdata/ subdirs won't be misdetected because
+        // it also has .go files at root.
+        if (isLintcnDir || (!hasGoFiles && hasCandidateSubdirs)) {
+            await addLintcnFolder(owner, repo, ref, dirPath, url);
+            return;
+        }
+    }
+    // Single rule — download one folder
+    const folderName = path.posix.basename(dirPath);
+    console.log(`Fetching ${owner}/${repo}/${dirPath}...`);
+    const lintcnDir = getLintcnDir();
+    // Warn if this doesn't look like a single-rule folder (too many main .go files)
+    const items = await listGitHubFolder(owner, repo, dirPath, ref);
+    const mainGoFiles = items.filter((f) => {
+        return f.type === 'file' && 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 ok = await downloadSingleRule(owner, repo, ref, dirPath, lintcnDir, url);
+    if (!ok) {
+        throw new Error(`No .go files found in ${dirPath}. Is this a rule folder?`);
+    }
+    await finalizeLintcnDir(lintcnDir);
+}

package/dist/commands/lint.d.ts

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

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

@@ -1 +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,CAkElB;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"}
+{"version":3,"file":"lint.d.ts","sourceRoot":"","sources":["../../src/commands/lint.ts"],"names":[],"mappings":"AAwBA,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,CAkElB;AAED,wBAAsB,IAAI,CAAC,EACzB,OAAO,EACP,eAAe,EACf,eAAe,EACf,WAAW,GACZ,EAAE;IACD,OAAO,EAAE,OAAO,CAAA;IAChB,eAAe,EAAE,MAAM,CAAA;IACvB,eAAe,EAAE,MAAM,EAAE,CAAA;IACzB,WAAW,EAAE,OAAO,CAAA;CACrB,GAAG,OAAO,CAAC,MAAM,CAAC,CAoClB"}

package/dist/commands/lint.js

@@ -1,6 +1,7 @@
 // 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 path from 'node:path';
 import { spawn } from 'node:child_process';
 import { requireLintcnDir } from "../paths.js";
 import { discoverRules } from "../discover.js";
@@ -73,11 +74,28 @@ export async function buildBinary({ rebuild, tsgolintVersion, }) {
     console.log('Build complete');
     return binaryPath;
 }
-export async function lint({ rebuild, tsgolintVersion, passthroughArgs, }) {
+export async function lint({ rebuild, tsgolintVersion, passthroughArgs, allWarnings, }) {
     const binaryPath = await buildBinary({ rebuild, tsgolintVersion });
-    // run the binary with passthrough args, inheriting stdio
+    // Discover rules to inject --warn flags for warning-severity rules.
+    // buildBinary already discovered rules for compilation, but we need the
+    // metadata here to know which rules are warnings at runtime.
+    const lintcnDir = requireLintcnDir();
+    const rules = discoverRules(lintcnDir);
+    const warnArgs = buildWarnArgs(rules);
+    // By default, limit warnings to git-changed files so they don't flood
+    // the output in large codebases. --all-warnings bypasses this filter.
+    const hasWarnRules = rules.some((r) => r.severity === 'warn');
+    let warnFileArgs = [];
+    if (hasWarnRules && allWarnings) {
+        warnFileArgs = ['--all-warnings'];
+    }
+    else if (hasWarnRules) {
+        warnFileArgs = await buildWarnFileArgs();
+    }
+    // run the binary with --warn + --warn-file/--all-warnings flags + passthrough args
+    const allArgs = [...warnArgs, ...warnFileArgs, ...passthroughArgs];
     return new Promise((resolve) => {
-        const proc = spawn(binaryPath, passthroughArgs, {
+        const proc = spawn(binaryPath, allArgs, {
             stdio: 'inherit',
         });
         proc.on('error', (err) => {
@@ -89,3 +107,56 @@ export async function lint({ rebuild, tsgolintVersion, passthroughArgs, }) {
         });
     });
 }
+/** Build --warn flags for rules with severity 'warn'.
+ *  Uses goRuleName (parsed from Go source) to match the runtime name
+ *  that tsgolint uses in diagnostics, avoiding silent mismatches. */
+function buildWarnArgs(rules) {
+    const args = [];
+    for (const rule of rules) {
+        if (rule.severity === 'warn') {
+            args.push('--warn', rule.goRuleName);
+        }
+    }
+    return args;
+}
+/** Get git-changed files and build --warn-file flags so warnings only
+ *  appear for new/modified code. Returns [] if git is unavailable or not
+ *  a git repo — the runner will then show no warnings (safe default).
+ *  Linting must never crash from this. */
+async function buildWarnFileArgs() {
+    try {
+        // Get git repo root to resolve relative paths to absolute.
+        const topLevelResult = await execAsync('git', ['rev-parse', '--show-toplevel'], { stdio: 'pipe' }).catch(() => null);
+        if (!topLevelResult)
+            return [];
+        const repoRoot = topLevelResult.stdout.trim();
+        // Changed files (staged + unstaged vs HEAD)
+        const diffResult = await execAsync('git', ['diff', '--name-only', 'HEAD'], { stdio: 'pipe' }).catch(() => null);
+        // Untracked files (new files not yet committed)
+        const untrackedResult = await execAsync('git', ['ls-files', '--others', '--exclude-standard'], { stdio: 'pipe' }).catch(() => null);
+        const files = new Set();
+        for (const result of [diffResult, untrackedResult]) {
+            if (!result)
+                continue;
+            for (const line of result.stdout.split('\n')) {
+                const trimmed = line.trim();
+                if (trimmed) {
+                    // Resolve to absolute path so it matches SourceFile.FileName() in the runner.
+                    files.add(path.resolve(repoRoot, trimmed));
+                }
+            }
+        }
+        // No changed files → no --warn-file flags → runner shows no warnings (clean tree)
+        if (files.size === 0)
+            return [];
+        const args = [];
+        for (const file of files) {
+            args.push('--warn-file', file);
+        }
+        return args;
+    }
+    catch {
+        // git not installed, not a repo, or any other failure — no warnings shown
+        return [];
+    }
+}

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

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

package/dist/commands/list.js

@@ -13,9 +13,12 @@ export function listRules() {
         return;
     }
     console.log('Installed rules:\n');
-    const maxNameLen = Math.max(...rules.map((r) => { return r.name.length; }));
+    const maxNameLen = Math.max(...rules.map((r) => {
+        return r.name.length + (r.severity === 'warn' ? 7 : 0); // ' (warn)' = 7 chars
+    }));
     for (const rule of rules) {
-        const name = rule.name.padEnd(maxNameLen + 2);
+        const suffix = rule.severity === 'warn' ? ' (warn)' : '';
+        const name = (rule.name + suffix).padEnd(maxNameLen + 2);
         const desc = rule.description || '(no description)';
         console.log(`  ${name}${desc}`);
     }

package/dist/discover.d.ts

@@ -1,10 +1,17 @@
 export interface RuleMetadata {
     /** kebab-case rule name from // lintcn:name or derived from folder name */
     name: string;
+    /** runtime rule name parsed from Go `rule.Rule{Name: "..."}`. This is
+     *  the name tsgolint uses in diagnostics and must match --warn flags.
+     *  Falls back to `name` if the Go Name field can't be parsed. */
+    goRuleName: string;
     /** one-line description from // lintcn:description */
     description: string;
     /** original source URL from // lintcn:source */
     source: string;
+    /** severity from // lintcn:severity — 'error' (default) or 'warn'.
+     *  Warnings are displayed with yellow styling and don't cause exit code 1. */
+    severity: 'error' | 'warn';
     /** exported Go variable name like NoFloatingPromisesRule */
     varName: string;
     /** Go package name (= subfolder name, e.g. no_floating_promises) */
@@ -12,5 +19,8 @@ export interface RuleMetadata {
 }
 export declare function parseMetadata(content: string): Record<string, string>;
 export declare function parseRuleVar(content: string): string | undefined;
+/** Extract the Name field from a specific rule.Rule variable's struct literal.
+ *  Scoped to varName to avoid matching Name fields in unrelated structs. */
+export declare function parseGoRuleName(content: string, varName: string): string | undefined;
 export declare function discoverRules(lintcnDir: string): RuleMetadata[];
 //# sourceMappingURL=discover.d.ts.map

package/dist/discover.d.ts.map

@@ -1 +1 @@
-{"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"}
+{"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;;qEAEiE;IACjE,UAAU,EAAE,MAAM,CAAA;IAClB,sDAAsD;IACtD,WAAW,EAAE,MAAM,CAAA;IACnB,gDAAgD;IAChD,MAAM,EAAE,MAAM,CAAA;IACd;kFAC8E;IAC9E,QAAQ,EAAE,OAAO,GAAG,MAAM,CAAA;IAC1B,4DAA4D;IAC5D,OAAO,EAAE,MAAM,CAAA;IACf,oEAAoE;IACpE,WAAW,EAAE,MAAM,CAAA;CACpB;AAaD,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;4EAC4E;AAC5E,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAGpF;AAED,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,YAAY,EAAE,CAsD/D"}

package/dist/discover.js

@@ -7,6 +7,12 @@ import path from 'node:path';
 // and optional import alias (e.g. `r.Rule{` if imported as `r "...rule"`)
 const RULE_VAR_RE = /^\s*var\s+(\w+)\s*=\s*\w*\.?Rule\s*\{/m;
 const METADATA_RE = /^\/\/\s*lintcn:(\w+)\s+(.+)$/gm;
+// buildGoRuleNameRe creates a regex scoped to a specific rule variable's
+// struct literal, e.g. `var FooRule = rule.Rule{ ... Name: "foo" ... }`.
+// This avoids matching a Name field in an unrelated struct earlier in the file.
+function buildGoRuleNameRe(varName) {
+    return new RegExp(`var\\s+${varName}\\s*=\\s*\\w*\\.?Rule\\s*\\{[\\s\\S]*?Name:\\s*"([^"]+)"`);
+}
 export function parseMetadata(content) {
     const meta = {};
     for (const match of content.matchAll(METADATA_RE)) {
@@ -18,6 +24,12 @@ export function parseRuleVar(content) {
     const match = content.match(RULE_VAR_RE);
     return match?.[1];
 }
+/** Extract the Name field from a specific rule.Rule variable's struct literal.
+ *  Scoped to varName to avoid matching Name fields in unrelated structs. */
+export function parseGoRuleName(content, varName) {
+    const match = content.match(buildGoRuleNameRe(varName));
+    return match?.[1];
+}
 export function discoverRules(lintcnDir) {
     if (!fs.existsSync(lintcnDir)) {
         return [];
@@ -47,10 +59,15 @@ export function discoverRules(lintcnDir) {
             if (!varName)
                 continue;
             const meta = parseMetadata(content);
+            const severity = meta.severity === 'warn' ? 'warn' : 'error';
+            const displayName = meta.name || entry.name.replace(/_/g, '-');
+            const goRuleName = parseGoRuleName(content, varName) || displayName;
             rules.push({
-                name: meta.name || entry.name.replace(/_/g, '-'),
-                description: meta.description || '',
-                source: meta.source || '',
+                name: displayName,
+                goRuleName,
+                description: meta.description,
+                source: meta.source,
+                severity,
                 varName,
                 packageName: entry.name,
             });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lintcn",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "type": "module",
   "description": "The shadcn for type-aware TypeScript lint rules. Browse, pick, and copy rules into your project.",
   "bin": "dist/cli.js",
@@ -60,6 +60,7 @@
     "tar": "^7.5.12"
   },
   "scripts": {
-    "build": "rm -rf dist *.tsbuildinfo && tsc && chmod +x dist/cli.js"
+    "build": "rm -rf dist *.tsbuildinfo && tsc && chmod +x dist/cli.js",
+    "cli": "tsx src/cli"
   }
 }

package/src/cache.ts

@@ -18,7 +18,7 @@ import { execAsync } from './exec.ts'
 // 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.

package/src/cli.ts

@@ -18,11 +18,13 @@ const packageJson = require('../package.json') as { version: string }
 const cli = goke('lintcn')
 
 cli
-  .command('add <url>', 'Add a rule by GitHub URL. Fetches the whole folder into .lintcn/{rule}/')
-  .example('# Add a rule folder')
+  .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)
   })
@@ -43,12 +45,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 as string) || DEFAULT_TSGOLINT_VERSION
     const passthroughArgs: string[] = []
+    if (options.fix) {
+      passthroughArgs.push('--fix')
+    }
     if (options.tsconfig) {
       passthroughArgs.push('--tsconfig', options.tsconfig as string)
     }
@@ -64,6 +71,7 @@ cli
       rebuild: !!options.rebuild,
       tsgolintVersion,
       passthroughArgs,
+      allWarnings: !!options.allWarnings,
     })
     process.exit(exitCode)
   })

package/src/commands/add.ts

@@ -13,36 +13,57 @@ import { ensureTsgolintSource, DEFAULT_TSGOLINT_VERSION } from '../cache.ts'
 interface ParsedGitHubUrl {
   owner: string
   repo: string
-  ref: string
-  /** Path to the directory containing the rule files */
+  /** Branch/tag/commit. Undefined for bare repo URLs — resolve via API. */
+  ref: string | undefined
+  /** Path to the directory containing the rule files. Empty string for repo root. */
   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. */
+/** Parse any GitHub URL into components.
+ *  Supports: bare repo, /tree/ folders, /blob/ files, raw.githubusercontent.com.
+ *  Ref is 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
+  let hostname: string
+  let segments: string[]
+  try {
+    const u = new URL(url)
+    hostname = u.hostname
+    segments = u.pathname.replace(/\/$/, '').split('/').filter(Boolean)
+  } catch {
+    return null
+  }
+
+  // raw.githubusercontent.com/owner/repo/ref/path/to/file
+  if (hostname === 'raw.githubusercontent.com') {
+    if (segments.length < 4) return null
+    const [owner, repo, ref, ...rest] = segments
+    const filePath = rest.join('/')
     return { owner, repo, ref, dirPath: path.posix.dirname(filePath), fileName: path.posix.basename(filePath) }
   }
 
-  // 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 }
+  if (hostname !== 'github.com') return null
+  if (segments.length < 2) return null
+
+  const [owner, repo, kind, ref, ...rest] = segments
+
+  // Bare repo URL: github.com/owner/repo
+  if (!kind) {
+    return { owner, repo, ref: undefined, dirPath: '' }
+  }
+
+  const subPath = rest.join('/')
+
+  if (kind === 'tree') {
+    if (!ref || !subPath) return null
+    return { owner, repo, ref, dirPath: subPath }
   }
 
-  // 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) }
+  if (kind === 'blob') {
+    if (!ref || !subPath) return null
+    return { owner, repo, ref, dirPath: path.posix.dirname(subPath), fileName: path.posix.basename(subPath) }
   }
 
   return null
@@ -67,6 +88,30 @@ function getGitHubToken(): string | undefined {
   }
 }
 
+/** Resolve the default branch for a repo (e.g. "main", "master"). */
+async function resolveDefaultBranch(owner: string, repo: string): Promise<string> {
+  const apiUrl = `https://api.github.com/repos/${owner}/${repo}`
+  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()) as { default_branch: string }
+  return data.default_branch
+}
+
+/** Files/dirs in .lintcn/ that are generated and should not be treated as rule folders. */
+const LINTCN_GENERATED = new Set([
+  '.tsgolint', '.gitignore', 'go.work', 'go.work.sum', 'go.mod', 'go.sum',
+])
+
 /** 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}`
@@ -118,71 +163,53 @@ function ensureSourceComment(content: string, sourceUrl: string): string {
   return lines.join('\n')
 }
 
-export async function addRule(url: string): Promise<void> {
-  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
+/** Download a single rule folder into .lintcn/{folderName}/.
+ *  Overwrites existing folder if present.
+ *  Returns true if the rule was added, false if skipped (no .go files). */
+async function downloadSingleRule(
+  owner: string, repo: string, ref: string, dirPath: string,
+  lintcnDir: string, sourceUrl: string,
+): Promise<boolean> {
   const folderName = path.posix.basename(dirPath)
-
-  console.log(`Fetching ${owner}/${repo}/${dirPath}...`)
   const items = await listGitHubFolder(owner, repo, dirPath, ref)
 
-  // 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'))
   })
 
   if (filesToFetch.length === 0) {
-    throw new Error(`No .go files found in ${dirPath}. Is this a rule folder?`)
-  }
-
-  // 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.`,
-    )
+    console.warn(`  Skipping ${folderName}/ — no .go files found`)
+    return false
   }
 
-  const lintcnDir = getLintcnDir()
   const ruleDir = path.join(lintcnDir, folderName)
 
-  // Clean existing rule folder if it exists
   if (fs.existsSync(ruleDir)) {
     fs.rmSync(ruleDir, { recursive: true })
-    console.log(`Overwriting existing ${folderName}/`)
+    console.log(`  Overwriting existing ${folderName}/`)
   }
 
   fs.mkdirSync(ruleDir, { recursive: true })
 
-  // 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)
+      content = ensureSourceComment(content, sourceUrl)
     }
 
     fs.writeFileSync(path.join(ruleDir, item.name), content)
-    console.log(`  ${item.name}`)
+    console.log(`    ${item.name}`)
   }
 
-  console.log(`Added ${folderName}/ (${filesToFetch.length} files)`)
+  console.log(`  Added ${folderName}/ (${filesToFetch.length} files)`)
+  return true
+}
 
-  // Ensure tsgolint source is available
+/** Ensure tsgolint source, refresh symlink, regenerate go.work/go.mod. */
+async function finalizeLintcnDir(lintcnDir: string): Promise<void> {
   const tsgolintDir = await ensureTsgolintSource(DEFAULT_TSGOLINT_VERSION)
 
-  // Create/refresh .tsgolint symlink for gopls
   const tsgolintLink = path.join(lintcnDir, '.tsgolint')
   try {
     fs.lstatSync(tsgolintLink)
@@ -195,3 +222,115 @@ export async function addRule(url: string): Promise<void> {
   generateEditorGoFiles(lintcnDir)
   console.log('Editor support files generated (go.work, go.mod)')
 }
+
+/** Download all rule subfolders from a remote .lintcn/ directory.
+ *  Each subfolder is treated as a separate rule. Local rules not present
+ *  in the remote are preserved (merge, not replace). */
+async function addLintcnFolder(
+  owner: string, repo: string, ref: string, lintcnPath: string, sourceUrl: string,
+): Promise<void> {
+  console.log(`Fetching .lintcn/ from ${owner}/${repo}...`)
+  const items = await listGitHubFolder(owner, repo, lintcnPath, ref)
+
+  const ruleDirs = items.filter((item) => {
+    return item.type === 'dir' && !LINTCN_GENERATED.has(item.name) && !item.name.startsWith('.')
+  })
+
+  if (ruleDirs.length === 0) {
+    throw new Error(`No rule folders found in ${lintcnPath}. Is this a .lintcn/ directory?`)
+  }
+
+  console.log(`Found ${ruleDirs.length} rule(s)`)
+
+  const lintcnDir = getLintcnDir()
+
+  let added = 0
+  for (const dir of ruleDirs) {
+    const ruleDirPath = lintcnPath ? `${lintcnPath}/${dir.name}` : dir.name
+    const ok = await downloadSingleRule(owner, repo, ref, ruleDirPath, lintcnDir, sourceUrl)
+    if (ok) added++
+  }
+
+  if (added === 0) {
+    throw new Error(`No rule folders with .go files found in ${lintcnPath}.`)
+  }
+
+  await finalizeLintcnDir(lintcnDir)
+  console.log(`\nDone — added ${added} rule(s) from ${owner}/${repo}`)
+}
+
+export async function addRule(url: string): Promise<void> {
+  const parsed = parseGitHubUrl(url)
+  if (!parsed) {
+    throw new Error(
+      'Only GitHub URLs are supported.\n' +
+      'Examples:\n' +
+      '  lintcn add https://github.com/someone/their-project\n' +
+      '  lintcn add https://github.com/oxc-project/tsgolint/tree/main/internal/rules/no_floating_promises',
+    )
+  }
+
+  const { owner, repo, fileName } = parsed
+  let { ref, dirPath } = parsed
+
+  // Bare repo URL — resolve default branch and look for .lintcn/ at root
+  if (ref === undefined) {
+    ref = await resolveDefaultBranch(owner, repo)
+    console.log(`Resolved default branch: ${ref}`)
+
+    const rootItems = await listGitHubFolder(owner, repo, '', ref)
+    const lintcnEntry = rootItems.find((item) => item.type === 'dir' && item.name === '.lintcn')
+    if (!lintcnEntry) {
+      throw new Error(
+        `No .lintcn/ directory found in ${owner}/${repo}.\n` +
+        'The repo needs a .lintcn/ folder with rule subfolders.',
+      )
+    }
+
+    await addLintcnFolder(owner, repo, ref, '.lintcn', url)
+    return
+  }
+
+  // For blob/raw URLs, dirPath already points at the parent folder
+  // For tree URLs, dirPath is the folder itself — but it might be a .lintcn/ collection
+  if (!fileName) {
+    const items = await listGitHubFolder(owner, repo, dirPath, ref)
+    const hasGoFiles = items.some((i) => i.type === 'file' && i.name.endsWith('.go'))
+    const hasCandidateSubdirs = items.some((i) => {
+      return i.type === 'dir' && !LINTCN_GENERATED.has(i.name) && !i.name.startsWith('.')
+    })
+    const isLintcnDir = path.posix.basename(dirPath) === '.lintcn'
+
+    // Collection if: explicitly .lintcn/, or has subdirs but no .go files at root.
+    // A single rule folder with testdata/ subdirs won't be misdetected because
+    // it also has .go files at root.
+    if (isLintcnDir || (!hasGoFiles && hasCandidateSubdirs)) {
+      await addLintcnFolder(owner, repo, ref, dirPath, url)
+      return
+    }
+  }
+
+  // Single rule — download one folder
+  const folderName = path.posix.basename(dirPath)
+
+  console.log(`Fetching ${owner}/${repo}/${dirPath}...`)
+  const lintcnDir = getLintcnDir()
+
+  // Warn if this doesn't look like a single-rule folder (too many main .go files)
+  const items = await listGitHubFolder(owner, repo, dirPath, ref)
+  const mainGoFiles = items.filter((f) => {
+    return f.type === 'file' && 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 ok = await downloadSingleRule(owner, repo, ref, dirPath, lintcnDir, url)
+  if (!ok) {
+    throw new Error(`No .go files found in ${dirPath}. Is this a rule folder?`)
+  }
+  await finalizeLintcnDir(lintcnDir)
+}

package/src/commands/lint.ts

@@ -2,9 +2,10 @@
 // Handles Go workspace generation, compilation with caching, and execution.
 
 import fs from 'node:fs'
+import path from 'node:path'
 import { spawn } from 'node:child_process'
 import { requireLintcnDir } from '../paths.ts'
-import { discoverRules } from '../discover.ts'
+import { discoverRules, type RuleMetadata } from '../discover.ts'
 import { generateBuildWorkspace, generateEditorGoFiles } from '../codegen.ts'
 import { ensureTsgolintSource, validateVersion, cachedBinaryExists, getBinaryPath, getBuildDir, getBinDir } from '../cache.ts'
 import { computeContentHash } from '../hash.ts'
@@ -99,16 +100,36 @@ export async function lint({
   rebuild,
   tsgolintVersion,
   passthroughArgs,
+  allWarnings,
 }: {
   rebuild: boolean
   tsgolintVersion: string
   passthroughArgs: string[]
+  allWarnings: boolean
 }): Promise<number> {
   const binaryPath = await buildBinary({ rebuild, tsgolintVersion })
 
-  // run the binary with passthrough args, inheriting stdio
+  // Discover rules to inject --warn flags for warning-severity rules.
+  // buildBinary already discovered rules for compilation, but we need the
+  // metadata here to know which rules are warnings at runtime.
+  const lintcnDir = requireLintcnDir()
+  const rules = discoverRules(lintcnDir)
+  const warnArgs = buildWarnArgs(rules)
+
+  // By default, limit warnings to git-changed files so they don't flood
+  // the output in large codebases. --all-warnings bypasses this filter.
+  const hasWarnRules = rules.some((r) => r.severity === 'warn')
+  let warnFileArgs: string[] = []
+  if (hasWarnRules && allWarnings) {
+    warnFileArgs = ['--all-warnings']
+  } else if (hasWarnRules) {
+    warnFileArgs = await buildWarnFileArgs()
+  }
+
+  // run the binary with --warn + --warn-file/--all-warnings flags + passthrough args
+  const allArgs = [...warnArgs, ...warnFileArgs, ...passthroughArgs]
   return new Promise((resolve) => {
-    const proc = spawn(binaryPath, passthroughArgs, {
+    const proc = spawn(binaryPath, allArgs, {
       stdio: 'inherit',
     })
 
@@ -122,3 +143,59 @@ export async function lint({
     })
   })
 }
+
+/** Build --warn flags for rules with severity 'warn'.
+ *  Uses goRuleName (parsed from Go source) to match the runtime name
+ *  that tsgolint uses in diagnostics, avoiding silent mismatches. */
+function buildWarnArgs(rules: RuleMetadata[]): string[] {
+  const args: string[] = []
+  for (const rule of rules) {
+    if (rule.severity === 'warn') {
+      args.push('--warn', rule.goRuleName)
+    }
+  }
+  return args
+}
+
+/** Get git-changed files and build --warn-file flags so warnings only
+ *  appear for new/modified code. Returns [] if git is unavailable or not
+ *  a git repo — the runner will then show no warnings (safe default).
+ *  Linting must never crash from this. */
+async function buildWarnFileArgs(): Promise<string[]> {
+  try {
+    // Get git repo root to resolve relative paths to absolute.
+    const topLevelResult = await execAsync('git', ['rev-parse', '--show-toplevel'], { stdio: 'pipe' }).catch(() => null)
+    if (!topLevelResult) return []
+    const repoRoot = topLevelResult.stdout.trim()
+
+    // Changed files (staged + unstaged vs HEAD)
+    const diffResult = await execAsync('git', ['diff', '--name-only', 'HEAD'], { stdio: 'pipe' }).catch(() => null)
+    // Untracked files (new files not yet committed)
+    const untrackedResult = await execAsync('git', ['ls-files', '--others', '--exclude-standard'], { stdio: 'pipe' }).catch(() => null)
+
+    const files = new Set<string>()
+
+    for (const result of [diffResult, untrackedResult]) {
+      if (!result) continue
+      for (const line of result.stdout.split('\n')) {
+        const trimmed = line.trim()
+        if (trimmed) {
+          // Resolve to absolute path so it matches SourceFile.FileName() in the runner.
+          files.add(path.resolve(repoRoot, trimmed))
+        }
+      }
+    }
+
+    // No changed files → no --warn-file flags → runner shows no warnings (clean tree)
+    if (files.size === 0) return []
+
+    const args: string[] = []
+    for (const file of files) {
+      args.push('--warn-file', file)
+    }
+    return args
+  } catch {
+    // git not installed, not a repo, or any other failure — no warnings shown
+    return []
+  }
+}

package/src/commands/list.ts

@@ -20,10 +20,13 @@ export function listRules(): void {
 
   console.log('Installed rules:\n')
 
-  const maxNameLen = Math.max(...rules.map((r) => { return r.name.length }))
+  const maxNameLen = Math.max(...rules.map((r) => {
+    return r.name.length + (r.severity === 'warn' ? 7 : 0) // ' (warn)' = 7 chars
+  }))
 
   for (const rule of rules) {
-    const name = rule.name.padEnd(maxNameLen + 2)
+    const suffix = rule.severity === 'warn' ? ' (warn)' : ''
+    const name = (rule.name + suffix).padEnd(maxNameLen + 2)
     const desc = rule.description || '(no description)'
     console.log(`  ${name}${desc}`)
   }

package/src/discover.ts

@@ -8,10 +8,17 @@ import path from 'node:path'
 export interface RuleMetadata {
   /** kebab-case rule name from // lintcn:name or derived from folder name */
   name: string
+  /** runtime rule name parsed from Go `rule.Rule{Name: "..."}`. This is
+   *  the name tsgolint uses in diagnostics and must match --warn flags.
+   *  Falls back to `name` if the Go Name field can't be parsed. */
+  goRuleName: string
   /** one-line description from // lintcn:description */
   description: string
   /** original source URL from // lintcn:source */
   source: string
+  /** severity from // lintcn:severity — 'error' (default) or 'warn'.
+   *  Warnings are displayed with yellow styling and don't cause exit code 1. */
+  severity: 'error' | 'warn'
   /** exported Go variable name like NoFloatingPromisesRule */
   varName: string
   /** Go package name (= subfolder name, e.g. no_floating_promises) */
@@ -22,6 +29,12 @@ export interface RuleMetadata {
 // and optional import alias (e.g. `r.Rule{` if imported as `r "...rule"`)
 const RULE_VAR_RE = /^\s*var\s+(\w+)\s*=\s*\w*\.?Rule\s*\{/m
 const METADATA_RE = /^\/\/\s*lintcn:(\w+)\s+(.+)$/gm
+// buildGoRuleNameRe creates a regex scoped to a specific rule variable's
+// struct literal, e.g. `var FooRule = rule.Rule{ ... Name: "foo" ... }`.
+// This avoids matching a Name field in an unrelated struct earlier in the file.
+function buildGoRuleNameRe(varName: string): RegExp {
+  return new RegExp(`var\\s+${varName}\\s*=\\s*\\w*\\.?Rule\\s*\\{[\\s\\S]*?Name:\\s*"([^"]+)"`)
+}
 
 export function parseMetadata(content: string): Record<string, string> {
   const meta: Record<string, string> = {}
@@ -36,6 +49,13 @@ export function parseRuleVar(content: string): string | undefined {
   return match?.[1]
 }
 
+/** Extract the Name field from a specific rule.Rule variable's struct literal.
+ *  Scoped to varName to avoid matching Name fields in unrelated structs. */
+export function parseGoRuleName(content: string, varName: string): string | undefined {
+  const match = content.match(buildGoRuleNameRe(varName))
+  return match?.[1]
+}
+
 export function discoverRules(lintcnDir: string): RuleMetadata[] {
   if (!fs.existsSync(lintcnDir)) {
     return []
@@ -73,10 +93,16 @@ export function discoverRules(lintcnDir: string): RuleMetadata[] {
 
       const meta = parseMetadata(content)
 
+      const severity = meta.severity === 'warn' ? 'warn' as const : 'error' as const
+      const displayName = meta.name || entry.name.replace(/_/g, '-')
+      const goRuleName = parseGoRuleName(content, varName) || displayName
+
       rules.push({
-        name: meta.name || entry.name.replace(/_/g, '-'),
-        description: meta.description || '',
-        source: meta.source || '',
+        name: displayName,
+        goRuleName,
+        description: meta.description,
+        source: meta.source,
+        severity,
         varName,
         packageName: entry.name,
       })