lintcn 0.0.1 → 0.2.0

package/src/commands/add.ts

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

package/src/commands/lint.ts

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

package/src/commands/list.ts

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

package/src/commands/remove.ts

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

package/src/discover.ts

@@ -0,0 +1,69 @@
+// Scan .lintcn/*.go files for rule.Rule variables and lintcn: metadata comments.
+// Returns structured info about each discovered rule for codegen and list display.
+
+import fs from 'node:fs'
+import path from 'node:path'
+
+export interface RuleMetadata {
+  /** kebab-case rule name from // lintcn:name or derived from filename */
+  name: string
+  /** one-line description from // lintcn:description */
+  description: string
+  /** original source URL from // lintcn:source */
+  source: string
+  /** exported Go variable name like NoFloatingPromisesRule */
+  varName: string
+  /** filename relative to .lintcn/ */
+  fileName: string
+}
+
+const RULE_VAR_RE = /^var\s+(\w+)\s*=\s*rule\.Rule\s*\{/m
+const METADATA_RE = /^\/\/\s*lintcn:(\w+)\s+(.+)$/gm
+
+export function parseMetadata(content: string): Record<string, string> {
+  const meta: Record<string, string> = {}
+  for (const match of content.matchAll(METADATA_RE)) {
+    meta[match[1]] = match[2].trim()
+  }
+  return meta
+}
+
+export function parseRuleVar(content: string): string | undefined {
+  const match = content.match(RULE_VAR_RE)
+  return match?.[1]
+}
+
+export function discoverRules(lintcnDir: string): RuleMetadata[] {
+  if (!fs.existsSync(lintcnDir)) {
+    return []
+  }
+
+  const files = fs.readdirSync(lintcnDir).filter((f) => {
+    return f.endsWith('.go') && !f.endsWith('_test.go')
+  })
+
+  const rules: RuleMetadata[] = []
+
+  for (const fileName of files) {
+    const filePath = path.join(lintcnDir, fileName)
+    const content = fs.readFileSync(filePath, 'utf-8')
+
+    const varName = parseRuleVar(content)
+    if (!varName) {
+      continue
+    }
+
+    const meta = parseMetadata(content)
+    const baseName = fileName.replace(/\.go$/, '')
+
+    rules.push({
+      name: meta.name || baseName.replace(/_/g, '-'),
+      description: meta.description || '',
+      source: meta.source || '',
+      varName,
+      fileName,
+    })
+  }
+
+  return rules
+}

package/src/exec.ts

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

package/src/hash.ts

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

package/src/index.ts

@@ -1 +1,7 @@
-export const version = '0.0.1'
+export { discoverRules, parseMetadata, parseRuleVar } from './discover.ts'
+export type { RuleMetadata } from './discover.ts'
+export { addRule } from './commands/add.ts'
+export { lint, buildBinary } from './commands/lint.ts'
+export { listRules } from './commands/list.ts'
+export { removeRule } from './commands/remove.ts'
+export { DEFAULT_TSGOLINT_VERSION } from './cache.ts'

package/src/paths.ts

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