lintcn 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -1,3 +1,70 @@
+## 0.8.0
+
+1. **Diagnostic output now shows `warning` / `error` prefix** — each diagnostic header now includes an explicit severity label so warnings are clear in non-color terminals and CI logs:
+
+   ```
+   warning prefer-object-params — function `createUser` has 3 positional parameters. Use one object parameter instead.
+   error no-unhandled-error — Error-typed return value is not handled.
+   ```
+
+2. **New rule: `no-unsafe-unknown` (warn)** — warns when `unknown` appears in function parameter types or type assertions. Agents often reach for `unknown` when hitting TypeScript friction rather than reading the real types:
+
+   ```ts
+   function run(input: unknown) {}      // warned — use the real type
+   const v = input as unknown as User  // warned — narrow or validate instead
+   ```
+
+3. **New rule: `no-tiny-wrapper-function` (warn)** — warns on functions and methods whose entire body is a direct forwarding call. Keeps the codebase direct instead of building throwaway delegation layers:
+
+   ```ts
+   const save = (file: string) => write(file)   // warned — inline at use site
+   function persist(v: string) { return db.save(v) }  // warned
+   ```
+
+   Computed arguments (`write(normalize(value))`) are allowed — those add real behavior.
+
+4. **New rule: `no-single-use-top-level-function` (warn)** — warns on short top-level functions that are only called once. Suggests inlining at the call site to reduce indirection:
+
+   ```ts
+   function buildQuery(id: string) {
+     return `SELECT * FROM users WHERE id = '${id}'`
+   }
+   // called only once — inline it
+   ```
+
+5. **New rule: `no-single-use-top-level-type` (warn)** — warns on short root-level interfaces and type aliases that are only referenced once. The type just adds an extra name; inlining it at the use site is cleaner:
+
+   ```ts
+   type User = { name: string }   // warned — only used once below
+   const user: User = { name: 'a' }
+   ```
+
+   Exported types, recursive types, and longer declarations are allowed.
+
+6. **New rule: `no-unused-top-level-function` (warn)** — warns on top-level functions with zero callers in the program. Either inline, delete, or promote to a proper exported API.
+
+7. **New rule: `prefer-object-params` (warn)** — warns on reusable function definitions with 3 or more positional parameters. Object parameters are easier to read, easier to evolve, and harder to call in the wrong order:
+
+   ```ts
+   // warned
+   function createUser(name: string, email: string, role: string) {}
+
+   // preferred
+   function createUser(options: { name: string; email: string; role: string }) {}
+   ```
+
+   Inline callbacks passed directly at the call site are exempt.
+
+8. **Clearer error when no rules found** — the "no rules" error message now shows the resolved absolute path to the `.lintcn/` directory it searched, making misconfigured project roots easy to spot.
+
+9. **Fixed UTF-16 code frame rendering** — diagnostic code frames now render correctly for files containing non-ASCII characters or emoji.
+
+## 0.7.1
+
+1. **`lintcn lint` / `lintcn build` exit 0 when `.lintcn/` not found** — instead of throwing and exiting 1, they now print a helpful message and exit cleanly. Useful when running lintcn in CI on repos that haven't set up rules yet.
+
+2. **Snapshot files land in `.lintcn/<rule>/__snapshots__/`** — bumped tsgolint to `518fa0d`. Rule tests now write snapshots relative to the test package directory instead of the cached tsgolint source, so they're committed alongside your rule and survive `lintcn clean`. Set `TSGOLINT_SNAPSHOT_CWD=true` when running `go test` to get this behavior.
+
 ## 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:

package/README.md

@@ -22,6 +22,9 @@ npx lintcn add https://github.com/oxc-project/tsgolint/blob/main/internal/rules/
 # Lint your project
 npx lintcn lint
 
+# Show warning rules for all files, not just updated/added files
+npx lintcn lint --all-warnings
+
 # Lint with a specific tsconfig
 npx lintcn lint --tsconfig tsconfig.build.json
 
@@ -156,9 +159,9 @@ void getUser("id");
 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
+- **Only shown for updated/added files by default** — warning rules are limited to files in `git diff` plus untracked files, so 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.
+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 or adding — fixing issues in new code without blocking the build.
 
 ### Configuring a rule as a warning
 
@@ -174,29 +177,30 @@ 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:
+By default, `lintcn lint` runs `git diff` to find updated files and also includes untracked files you just added. Warning rules are only printed for files in that set:
 
 ```bash
-# Warnings only for files in git diff (default)
+# Warnings only for updated files plus newly added untracked files (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 |
+| Scenario                                  | Warnings shown?   |
+| ----------------------------------------- | ----------------- |
+| File is updated in `git diff`             | Yes               |
+| File is newly added and 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 new files) | 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
+3. Run `lintcn lint` — only see warnings in files you're currently editing or adding
 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
 

package/dist/cache.d.ts

@@ -1,4 +1,4 @@
-export declare const DEFAULT_TSGOLINT_VERSION = "23190a08a6315eba8ef11818fc1c38d7b01c9e10";
+export declare const DEFAULT_TSGOLINT_VERSION = "4e4666c284d3b5cf7fa082523a369ef507e4360c";
 /** 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

@@ -14,13 +14,13 @@ import { pipeline } from 'node:stream/promises';
 import { extract } from 'tar';
 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 = '23190a08a6315eba8ef11818fc1c38d7b01c9e10';
+// Uses remorses/tsgolint fork which adds internal/runner.Run() and
+// TSGOLINT_SNAPSHOT_CWD env var for cwd-relative test snapshots.
+export const DEFAULT_TSGOLINT_VERSION = '4e4666c284d3b5cf7fa082523a369ef507e4360c';
 // 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.
-const TYPESCRIPT_GO_COMMIT = '1b7eabe122e1575a0df9c77eccdf4e063c623224';
+const TYPESCRIPT_GO_COMMIT = 'c0703e66b68b826eedadce353d63fe9f4ea21fb6';
 // Strict pattern for version strings — prevents path traversal via ../
 const VERSION_PATTERN = /^[a-zA-Z0-9._-]+$/;
 /** Validate version string to prevent path traversal attacks.

package/dist/cli.js

@@ -9,6 +9,7 @@ import { listRules } from "./commands/list.js";
 import { removeRule } from "./commands/remove.js";
 import { clean } from "./commands/clean.js";
 import { DEFAULT_TSGOLINT_VERSION } from "./cache.js";
+import { findLintcnDir } from "./paths.js";
 const require = createRequire(import.meta.url);
 const packageJson = require('../package.json');
 const cli = goke('lintcn');
@@ -20,20 +21,14 @@ cli
     .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);
-});
+    .action(addRule);
 cli
     .command('remove <name>', 'Remove an installed rule from .lintcn/')
     .example('lintcn remove no-floating-promises')
-    .action((name) => {
-    removeRule(name);
-});
+    .action(removeRule);
 cli
     .command('list', 'List all installed rules')
-    .action(() => {
-    listRules();
-});
+    .action(listRules);
 cli
     .command('lint', 'Build custom tsgolint binary and run it against the project')
     .option('--rebuild', 'Force rebuild even if cached binary exists')
@@ -72,15 +67,17 @@ cli
     .option('--rebuild', 'Force rebuild even if cached binary exists')
     .option('--tsgolint-version [version]', 'Override the pinned tsgolint version (tag or commit). For testing unreleased tsgolint versions.')
     .action(async (options) => {
+    if (!findLintcnDir()) {
+        console.log('No .lintcn/ directory found. Run `lintcn add <url>` to add rules.');
+        return;
+    }
     const tsgolintVersion = options.tsgolintVersion || DEFAULT_TSGOLINT_VERSION;
     const binaryPath = await buildBinary({ rebuild: !!options.rebuild, tsgolintVersion });
     console.log(binaryPath);
 });
 cli
     .command('clean', 'Remove cached tsgolint source and compiled binaries to free disk space')
-    .action(() => {
-    clean();
-});
+    .action(clean);
 cli.help();
 cli.version(packageJson.version);
 cli.parse();

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

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

package/dist/commands/add.js

@@ -53,6 +53,17 @@ function parseGitHubUrl(url) {
     }
     return null;
 }
+function isGitHubContentItem(value) {
+    if (!value) {
+        return false;
+    }
+    const name = value.name;
+    const downloadUrl = value.download_url;
+    const itemType = value.type;
+    return typeof name === 'string'
+        && (downloadUrl === null || typeof downloadUrl === 'string')
+        && (itemType === 'file' || itemType === 'dir');
+}
 /** Get a GitHub auth token from gh CLI, GITHUB_TOKEN env, or return undefined. */
 function getGitHubToken() {
     if (process.env.GITHUB_TOKEN) {
@@ -107,6 +118,9 @@ async function listGitHubFolder(owner, repo, dirPath, ref) {
     if (!Array.isArray(data)) {
         throw new Error(`Expected a directory listing from GitHub API but got a single file.\n  ${apiUrl}`);
     }
+    if (!data.every(isGitHubContentItem)) {
+        throw new Error(`Unexpected GitHub directory listing shape.\n  ${apiUrl}`);
+    }
     return data;
 }
 async function fetchFile(url) {

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

@@ -1 +1 @@
-{"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"}
+{"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,CAyClB"}

package/dist/commands/lint.js

@@ -3,7 +3,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { spawn } from 'node:child_process';
-import { requireLintcnDir } from "../paths.js";
+import { requireLintcnDir, findLintcnDir } from "../paths.js";
 import { discoverRules } from "../discover.js";
 import { generateBuildWorkspace, generateEditorGoFiles } from "../codegen.js";
 import { ensureTsgolintSource, validateVersion, cachedBinaryExists, getBinaryPath, getBuildDir, getBinDir } from "../cache.js";
@@ -24,7 +24,7 @@ export async function buildBinary({ rebuild, tsgolintVersion, }) {
     const lintcnDir = requireLintcnDir();
     const rules = discoverRules(lintcnDir);
     if (rules.length === 0) {
-        throw new Error('No rules found in .lintcn/. Run `lintcn add <url>` to add rules.');
+        throw new Error(`No rules found in ${lintcnDir}. Run \`lintcn add <url>\` to add rules.`);
     }
     console.log(`Found ${rules.length} custom rule${rules.length === 1 ? '' : 's'} (tsgolint ${tsgolintVersion.slice(0, 8)})`);
     // ensure tsgolint source
@@ -75,6 +75,10 @@ export async function buildBinary({ rebuild, tsgolintVersion, }) {
     return binaryPath;
 }
 export async function lint({ rebuild, tsgolintVersion, passthroughArgs, allWarnings, }) {
+    if (!findLintcnDir()) {
+        console.log('No .lintcn/ directory found. Run `lintcn add <url>` to add rules.');
+        return 0;
+    }
     const binaryPath = await buildBinary({ rebuild, tsgolintVersion });
     // Discover rules to inject --warn flags for warning-severity rules.
     // buildBinary already discovered rules for compilation, but we need the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lintcn",
-  "version": "0.7.0",
+  "version": "0.8.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/cache.ts

@@ -16,14 +16,14 @@ import { extract } from 'tar'
 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 = '23190a08a6315eba8ef11818fc1c38d7b01c9e10'
+// Uses remorses/tsgolint fork which adds internal/runner.Run() and
+// TSGOLINT_SNAPSHOT_CWD env var for cwd-relative test snapshots.
+export const DEFAULT_TSGOLINT_VERSION = '4e4666c284d3b5cf7fa082523a369ef507e4360c'
 
 // 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.
-const TYPESCRIPT_GO_COMMIT = '1b7eabe122e1575a0df9c77eccdf4e063c623224'
+const TYPESCRIPT_GO_COMMIT = 'c0703e66b68b826eedadce353d63fe9f4ea21fb6'
 
 // Strict pattern for version strings — prevents path traversal via ../
 const VERSION_PATTERN = /^[a-zA-Z0-9._-]+$/

package/src/cli.ts

@@ -11,6 +11,7 @@ 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'
+import { findLintcnDir } from './paths.ts'
 
 const require = createRequire(import.meta.url)
 const packageJson = require('../package.json') as { version: string }
@@ -25,22 +26,16 @@ cli
   .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)
-  })
+  .action(addRule)
 
 cli
   .command('remove <name>', 'Remove an installed rule from .lintcn/')
   .example('lintcn remove no-floating-promises')
-  .action((name) => {
-    removeRule(name)
-  })
+  .action(removeRule)
 
 cli
   .command('list', 'List all installed rules')
-  .action(() => {
-    listRules()
-  })
+  .action(listRules)
 
 cli
   .command('lint', 'Build custom tsgolint binary and run it against the project')
@@ -81,6 +76,10 @@ cli
   .option('--rebuild', 'Force rebuild even if cached binary exists')
   .option('--tsgolint-version [version]', 'Override the pinned tsgolint version (tag or commit). For testing unreleased tsgolint versions.')
   .action(async (options) => {
+    if (!findLintcnDir()) {
+      console.log('No .lintcn/ directory found. Run `lintcn add <url>` to add rules.')
+      return
+    }
     const tsgolintVersion = (options.tsgolintVersion as string) || DEFAULT_TSGOLINT_VERSION
     const binaryPath = await buildBinary({ rebuild: !!options.rebuild, tsgolintVersion })
     console.log(binaryPath)
@@ -88,9 +87,7 @@ cli
 
 cli
   .command('clean', 'Remove cached tsgolint source and compiled binaries to free disk space')
-  .action(() => {
-    clean()
-  })
+  .action(clean)
 
 cli.help()
 cli.version(packageJson.version)

package/src/commands/add.ts

@@ -75,6 +75,26 @@ interface GitHubContentItem {
   type: 'file' | 'dir'
 }
 
+type GitHubContentItemCandidate = {
+  name?: string | null
+  download_url?: string | null
+  type?: string | null
+} | null
+
+function isGitHubContentItem(value: GitHubContentItemCandidate): value is GitHubContentItem {
+  if (!value) {
+    return false
+  }
+
+  const name = value.name
+  const downloadUrl = value.download_url
+  const itemType = value.type
+
+  return typeof name === 'string'
+    && (downloadUrl === null || typeof downloadUrl === 'string')
+    && (itemType === 'file' || itemType === 'dir')
+}
+
 /** Get a GitHub auth token from gh CLI, GITHUB_TOKEN env, or return undefined. */
 function getGitHubToken(): string | undefined {
   if (process.env.GITHUB_TOKEN) {
@@ -134,7 +154,11 @@ async function listGitHubFolder(owner: string, repo: string, dirPath: string, re
     throw new Error(`Expected a directory listing from GitHub API but got a single file.\n  ${apiUrl}`)
   }
 
-  return data as GitHubContentItem[]
+  if (!data.every(isGitHubContentItem)) {
+    throw new Error(`Unexpected GitHub directory listing shape.\n  ${apiUrl}`)
+  }
+
+  return data
 }
 
 async function fetchFile(url: string): Promise<string> {

package/src/commands/lint.ts

@@ -4,7 +4,7 @@
 import fs from 'node:fs'
 import path from 'node:path'
 import { spawn } from 'node:child_process'
-import { requireLintcnDir } from '../paths.ts'
+import { requireLintcnDir, findLintcnDir } from '../paths.ts'
 import { discoverRules, type RuleMetadata } from '../discover.ts'
 import { generateBuildWorkspace, generateEditorGoFiles } from '../codegen.ts'
 import { ensureTsgolintSource, validateVersion, cachedBinaryExists, getBinaryPath, getBuildDir, getBinDir } from '../cache.ts'
@@ -36,7 +36,7 @@ export async function buildBinary({
 
   const rules = discoverRules(lintcnDir)
   if (rules.length === 0) {
-    throw new Error('No rules found in .lintcn/. Run `lintcn add <url>` to add rules.')
+    throw new Error(`No rules found in ${lintcnDir}. Run \`lintcn add <url>\` to add rules.`)
   }
 
   console.log(`Found ${rules.length} custom rule${rules.length === 1 ? '' : 's'} (tsgolint ${tsgolintVersion.slice(0, 8)})`)
@@ -107,6 +107,11 @@ export async function lint({
   passthroughArgs: string[]
   allWarnings: boolean
 }): Promise<number> {
+  if (!findLintcnDir()) {
+    console.log('No .lintcn/ directory found. Run `lintcn add <url>` to add rules.')
+    return 0
+  }
+
   const binaryPath = await buildBinary({ rebuild, tsgolintVersion })
 
   // Discover rules to inject --warn flags for warning-severity rules.

package/src/hash.ts

@@ -52,5 +52,3 @@ export async function computeContentHash({
   const full = hash.digest('hex')
   return { short: full.slice(0, 16), full }
 }
-
-