lintcn 0.7.1 → 0.9.0

package/CHANGELOG.md

@@ -1,3 +1,104 @@
+## 0.9.0
+
+1. **New rule: `no-redundant-exported-return-type` (warn)** — warns when exported APIs keep spelling `ReturnType<typeof ...>` even though the function already returns a public named type. This keeps public types direct and easier to read:
+
+   ```ts
+   export interface User {
+     id: string
+   }
+
+   export function getUser(): User {
+     return { id: '1' }
+   }
+
+   export type UserResult = ReturnType<typeof getUser> // warned
+   ```
+
+   Use the named type directly instead:
+
+   ```ts
+   export type UserResult = User
+   ```
+
+2. **New rule: `no-redundant-contextual-parameter-type` (error)** — errors when an inline callback repeats a parameter type that TypeScript already knows from the surrounding API. This removes annotation noise without losing type safety:
+
+   ```ts
+   declare function useRunner(fn: (ctx: { command: string }) => void): void
+
+   useRunner((ctx: { command: string }) => {
+     ctx.command
+   })
+   ```
+
+   Preferred:
+
+   ```ts
+   useRunner((ctx) => {
+     ctx.command
+   })
+   ```
+
+## 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.

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 = "518fa0d395effb07a45070643a0cb1a9cf202ce9";
+export declare const DEFAULT_TSGOLINT_VERSION = "427f872946bb413f0e21cff585b6139c986c89d3";
 /** 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,11 +16,11 @@ import { execAsync } from "./exec.js";
 // Pinned tsgolint fork commit — updated with each lintcn release.
 // 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 = '518fa0d395effb07a45070643a0cb1a9cf202ce9';
+export const DEFAULT_TSGOLINT_VERSION = '427f872946bb413f0e21cff585b6139c986c89d3';
 // 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

@@ -21,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')
@@ -55,10 +49,9 @@ cli
     if (options.listFiles) {
         passthroughArgs.push('--list-files');
     }
-    // pass through anything after --
-    const doubleDash = options['--'];
-    if (doubleDash && Array.isArray(doubleDash)) {
-        passthroughArgs.push(...doubleDash);
+    // pass through anything after -- (goke 6.6.0 always types this as string[])
+    if (options['--'].length > 0) {
+        passthroughArgs.push(...options['--']);
     }
     const exitCode = await lint({
         rebuild: !!options.rebuild,
@@ -83,9 +76,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);
 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.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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lintcn",
-  "version": "0.7.1",
+  "version": "0.9.0",
   "type": "module",
   "description": "The shadcn for type-aware TypeScript lint rules. Browse, pick, and copy rules into your project.",
   "bin": "dist/cli.js",
@@ -56,7 +56,7 @@
   },
   "dependencies": {
     "find-up": "^8.0.0",
-    "goke": "^6.3.0",
+    "goke": "^6.6.0",
     "tar": "^7.5.12"
   },
   "scripts": {

package/src/cache.ts

@@ -18,12 +18,12 @@ import { execAsync } from './exec.ts'
 // Pinned tsgolint fork commit — updated with each lintcn release.
 // 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 = '518fa0d395effb07a45070643a0cb1a9cf202ce9'
+export const DEFAULT_TSGOLINT_VERSION = '427f872946bb413f0e21cff585b6139c986c89d3'
 
 // 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

@@ -26,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')
@@ -52,21 +46,20 @@ cli
   .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 tsgolintVersion = options.tsgolintVersion || DEFAULT_TSGOLINT_VERSION
     const passthroughArgs: string[] = []
     if (options.fix) {
       passthroughArgs.push('--fix')
     }
     if (options.tsconfig) {
-      passthroughArgs.push('--tsconfig', options.tsconfig as string)
+      passthroughArgs.push('--tsconfig', options.tsconfig)
     }
     if (options.listFiles) {
       passthroughArgs.push('--list-files')
     }
-    // pass through anything after --
-    const doubleDash = options['--']
-    if (doubleDash && Array.isArray(doubleDash)) {
-      passthroughArgs.push(...doubleDash)
+    // pass through anything after -- (goke 6.6.0 always types this as string[])
+    if (options['--'].length > 0) {
+      passthroughArgs.push(...options['--'])
     }
     const exitCode = await lint({
       rebuild: !!options.rebuild,
@@ -86,16 +79,14 @@ cli
       console.log('No .lintcn/ directory found. Run `lintcn add <url>` to add rules.')
       return
     }
-    const tsgolintVersion = (options.tsgolintVersion as string) || DEFAULT_TSGOLINT_VERSION
+    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)

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

@@ -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)})`)

package/src/hash.ts

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