@jacob-z/oxlint-gate 1.0.0

package/README.md

@@ -0,0 +1,127 @@
+# oxlint-gate
+
+Real-time type assertion gate for [oh-my-pi](https://github.com/JacobZyy/oh-my-pi).
+
+Intercepts Edit/Write tool calls and checks the target file with oxlint before allowing the edit to proceed. Blocks if type laziness assertions (e.g., `as any`, `as unknown as X`) are detected.
+
+## Features
+
+- **Real-time blocking**: Checks files before they're saved, not after
+- **oxlint integration**: Uses the same rules as your CLI workflow
+- **Configurable**: Reads ignore patterns from `~/.config/oxlint/oxlintrc.json`
+- **Fail-open**: If oxlint is not installed or crashes, edits are allowed (won't block your workflow)
+- **Local logs**: Writes detailed logs to `~/.omp/logs/oxlint-gate.log` for debugging
+
+## Prerequisites
+
+1. **oxlint** installed globally:
+
+   ```bash
+   npm install -g oxlint
+   ```
+
+2. **oxlint config** at `~/.config/oxlint/oxlintrc.json`:
+   ```json
+   {
+     "rules": {
+       "typescript/no-explicit-any": "error",
+       "typescript/no-unnecessary-type-assertion": "error"
+     },
+     "ignorePatterns": ["*.test.ts", "*.config.ts"]
+   }
+   ```
+
+## Installation
+
+### Via OMP marketplace
+
+```bash
+omp plugin install @jacob-z/oxlint-gate
+```
+
+### Manual installation
+
+1. Clone this repository
+2. Link the package:
+   ```bash
+   cd packages/oxlint-gate
+   bun link
+   ```
+3. Add to your OMP config (`~/.omp/agent/config.yml`):
+   ```yaml
+   extensions:
+    - /path/to/jacob-z/packages/oxlint-gate/src/index.ts
+   ```
+
+## How it works
+
+1. When you use Edit/Write tools in OMP, the extension intercepts the tool call
+2. It extracts the target file path from the tool input
+3. If the file is a TypeScript/Vue file, it runs oxlint with your config
+4. If type assertion violations are found, the edit is blocked with a detailed error message
+5. The error message includes the violations and suggests how to fix them
+
+## Configuration
+
+The extension reads from `~/.config/oxlint/oxlintrc.json`:
+
+- `rules`: oxlint rules to check
+- `ignorePatterns`: glob patterns for files to skip (e.g., `*.test.ts`, `*.config.ts`)
+
+## Logs
+
+Logs are written to `~/.omp/logs/oxlint-gate.log`.
+
+```bash
+# View logs in real-time
+tail -f ~/.omp/logs/oxlint-gate.log
+
+# Search for blocked edits
+grep "BLOCKED" ~/.omp/logs/oxlint-gate.log
+
+# View today's checks
+grep "$(date +%Y-%m-%d)" ~/.omp/logs/oxlint-gate.log
+```
+
+Log format:
+
+```
+[2026-05-30T10:15:30.123Z] [INFO] extension loaded
+[2026-05-30T10:15:35.456Z] [INFO] checking: /path/to/file.ts
+[2026-05-30T10:15:35.789Z] [WARN] BLOCKED: /path/to/file.ts
+Found 2 errors.
+...
+[2026-05-30T10:16:00.123Z] [INFO] passed: /path/to/other.ts
+```
+
+## Error message format
+
+When violations are found, you'll see:
+
+```
+❌ [oxlint-gate] 检测到类型偷懒断言 — Found 2 errors.
+
+/path/to/file.ts
+  10:5  error  Unexpected any, use a specific type  @typescript-eslint/no-explicit-any
+  15:10 error  Unnecessary type assertion            @typescript-eslint/no-unnecessary-type-assertion
+
+按 ts-type-discipline 协议处理：
+  1) 优先用泛型 / 条件类型 / 类型守卫消除断言，禁止 as any / as unknown as X
+  2) 类型体操无效 → 追溯并修复底层类型声明（接口/DTO/类型定义）
+  3) 若是后端接口少返回字段 → 用 AskUserQuestion 与用户确认方案
+```
+
+## Differences from Claude Code hook
+
+This is an OMP extension ported from the Claude Code hook in [jacob-skills-collection](https://github.com/JacobZyy/jacob-skills-collection).
+
+| Feature     | Claude Code hook       | OMP extension               |
+| ----------- | ---------------------- | --------------------------- |
+| Timing      | End of session         | Real-time (before save)     |
+| Blocking    | Blocks session         | Blocks tool call            |
+| Transcript  | Reads JSONL transcript | Intercepts tool_call events |
+| Performance | Batch check at end     | Single file check per edit  |
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@jacob-z/oxlint-gate",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "Real-time type assertion gate using oxlint — blocks `as any` and other type laziness before files are saved",
+  "license": "MIT",
+  "author": { "name": "Jacob" },
+  "repository": { "type": "git", "url": "https://github.com/JacobZyy/jacob-omp-collections", "directory": "packages/oxlint-gate" },
+  "omp": {
+    "extensions": ["./src/index.ts"]
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./src/index.ts"
+    }
+  },
+  "main": "./src/index.ts",
+  "files": ["src"],
+  "scripts": {
+    "build": "tsc --build",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.1"
+  }
+}

package/src/index.test.ts

@@ -0,0 +1,39 @@
+import { describe, expect, it } from 'vitest'
+import { extractFilePath } from './index'
+
+describe('extractFilePath', () => {
+  it('should extract path from direct path field', () => {
+    const input = { path: '/foo/bar.ts' }
+    expect(extractFilePath(input)).toBe('/foo/bar.ts')
+  })
+
+  it('should extract path from hashline input', () => {
+    const input = { input: '¶/foo/bar.ts#abc123\nreplace 1..1:\n+new line' }
+    expect(extractFilePath(input)).toBe('/foo/bar.ts')
+  })
+
+  it('should extract path from apply-patch input', () => {
+    const input = { input: '*** Add File: /foo/bar.ts\n+content' }
+    expect(extractFilePath(input)).toBe('/foo/bar.ts')
+  })
+
+  it('should return undefined for missing path', () => {
+    const input = { content: 'some content' }
+    expect(extractFilePath(input)).toBeUndefined()
+  })
+
+  it('should return undefined for empty path', () => {
+    const input = { path: '' }
+    expect(extractFilePath(input)).toBeUndefined()
+  })
+
+  it('should handle Update File in apply-patch', () => {
+    const input = { input: '*** Update File: /foo/bar.ts\n-old\n+new' }
+    expect(extractFilePath(input)).toBe('/foo/bar.ts')
+  })
+
+  it('should handle Delete File in apply-patch', () => {
+    const input = { input: '*** Delete File: /foo/bar.ts' }
+    expect(extractFilePath(input)).toBe('/foo/bar.ts')
+  })
+})

package/src/index.ts

@@ -0,0 +1,311 @@
+/**
+ * oxlint-gate: Real-time type assertion gate for OMP.
+ *
+ * Intercepts Edit/Write tool calls and checks the target file with oxlint
+ * before allowing the edit to proceed. Blocks if type laziness assertions
+ * (e.g., `as any`, `as unknown as X`) are detected.
+ *
+ * Configuration: reads rules from `~/.config/oxlint/oxlintrc.json`
+ * Logs: writes to `~/.omp/logs/oxlint-gate.log`
+ */
+
+import type { ExtensionAPI, ExtensionFactory } from './omp-types'
+import { spawnSync } from 'node:child_process'
+import { appendFileSync, existsSync, mkdirSync, readFileSync, statSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { isAbsolute, join, relative, resolve } from 'node:path'
+import process from 'node:process'
+
+const TS_EXTENSIONS = /\.(?:ts|tsx|mts|cts|vue)$/
+const OXLINT_CFG = join(homedir(), '.config', 'oxlint', 'oxlintrc.json')
+const LOG_DIR = join(homedir(), '.omp', 'logs')
+const LOG_FILE = join(LOG_DIR, 'oxlint-gate.log')
+const HOME = homedir()
+
+// Tools that modify files
+const WRITE_TOOLS = new Set(['edit', 'write'])
+
+/** Max auto-fix attempts per file per turn. */
+const MAX_FIX_ATTEMPTS = 3
+
+/** Max lines of oxlint output to keep. */
+const MAX_OUTPUT_LINES = 20
+
+// ── Types ──────────────────────────────────────────────────────────────────
+
+interface OxlintConfig {
+  ignorePatterns?: string[]
+}
+
+// ── Local Logger ───────────────────────────────────────────────────────────
+
+function ensureLogDir(): void {
+  if (!existsSync(LOG_DIR)) {
+    mkdirSync(LOG_DIR, { recursive: true })
+  }
+}
+
+function writeLog(level: 'INFO' | 'WARN' | 'DEBUG', msg: string): void {
+  try {
+    ensureLogDir()
+    const ts = new Date().toISOString()
+    appendFileSync(LOG_FILE, `[${ts}] [${level}] ${msg}\n`)
+  }
+  catch {
+    // Silently ignore log write failures
+  }
+}
+
+// ── Helpers ────────────────────────────────────────────────────────────────
+
+/**
+ * Expand ~ to home directory
+ */
+function expandTilde(p: string): string {
+  if (p === '~' || p.startsWith('~/')) {
+    return join(HOME, p.slice(1))
+  }
+  return p
+}
+
+export function extractFilePath(input: Record<string, unknown>): string | undefined {
+  // Direct `path` field (replace/patch modes of edit, and write tool)
+  const directPath = input.path
+  if (typeof directPath === 'string' && directPath)
+    return directPath
+
+  // Hashline / apply-patch modes: `input` is a raw string containing the path
+  const rawInput = input.input
+  if (typeof rawInput !== 'string' || !rawInput)
+    return undefined
+
+  // Hashline: ¶path#hash or §path#hash or @path#hash
+  const hashlineMatch = /^[¶§@]([^\s#]+)/m.exec(rawInput)
+  if (hashlineMatch?.[1])
+    return hashlineMatch[1]
+
+  // Apply-patch: *** Add/Update/Delete File: path
+  const applyPatchMatch = /^\*\*\* (?:Add|Update|Delete) File:\s*(.+)/m.exec(rawInput)
+  if (applyPatchMatch?.[1])
+    return applyPatchMatch[1].trim()
+
+  return undefined
+}
+
+function isExistingFile(p: string): boolean {
+  try {
+    return statSync(p).isFile()
+  }
+  catch {
+    return false
+  }
+}
+
+function loadIgnorePatterns(cfgPath: string): string[] {
+  try {
+    const raw = readFileSync(cfgPath, 'utf8')
+    const cfg = JSON.parse(raw) as OxlintConfig
+    if (!Array.isArray(cfg.ignorePatterns))
+      return []
+    return cfg.ignorePatterns.filter((p): p is string => typeof p === 'string')
+  }
+  catch {
+    return []
+  }
+}
+
+function matchesIgnorePattern(filePath: string, patterns: string[]): boolean {
+  if (patterns.length === 0)
+    return false
+
+  const rel = relative(process.cwd(), filePath)
+  const candidates = [filePath, rel, `./${rel}`]
+
+  // Simple glob matching without Bun.Glob (for Node.js compatibility)
+  for (const pattern of patterns) {
+    const regex = globToRegex(pattern)
+    if (regex) {
+      for (const c of candidates) {
+        if (regex.test(c))
+          return true
+      }
+    }
+  }
+  return false
+}
+
+function globToRegex(glob: string): RegExp | null {
+  try {
+    // Convert glob to regex
+    const regexStr = glob
+      .replace(/[.+^${}()|[\]\\]/g, '\\$&') // Escape special regex chars except * and ?
+      .replace(/\*\*/g, '{{DOUBLE_STAR}}') // Temporarily replace **
+      .replace(/\*/g, '[^/]*') // * matches anything except /
+      .replace(/\?/g, '[^/]') // ? matches single char except /
+      .replace(/\{\{DOUBLE_STAR\}\}/g, '.*') // ** matches everything
+
+    return new RegExp(`^${regexStr}$`)
+  }
+  catch {
+    return null
+  }
+}
+
+function runOxlint(filePath: string, cfgPath: string): { passed: boolean, output: string } {
+  const result = spawnSync('oxlint', ['-c', cfgPath, filePath], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+    timeout: 5000, // 5 second timeout
+  })
+
+  if (result.error) {
+    // oxlint not found or spawn error — treat as pass (fail-open)
+    return { passed: true, output: `oxlint error: ${result.error.message}` }
+  }
+
+  const exitCode = result.status ?? -1
+  const output = `${result.stdout ?? ''}${result.stderr ?? ''}`.trim()
+
+  // exit 0 = pass, exit 1 = violations found, other = tool error (fail-open)
+  return { passed: exitCode !== 1, output }
+}
+
+function runOxlintFix(filePath: string, cfgPath: string): { fixed: boolean, remaining: number, output: string } {
+  const result = spawnSync('oxlint', ['--fix', '-c', cfgPath, filePath], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+    timeout: 10000,
+  })
+
+  if (result.error) {
+    return { fixed: false, remaining: -1, output: `oxlint error: ${result.error.message}` }
+  }
+
+  const exitCode = result.status ?? -1
+  const output = `${result.stdout ?? ''}${result.stderr ?? ''}`.trim()
+
+  // exit 0 = all fixed, exit 1 = remaining violations
+  return { fixed: exitCode === 0, remaining: exitCode === 1 ? 1 : 0, output }
+}
+
+function truncateOutput(output: string, maxLines: number = MAX_OUTPUT_LINES): string {
+  const lines = output.split('\n')
+  if (lines.length <= maxLines)
+    return output
+  const head = lines.slice(0, 10).join('\n')
+  const summary = lines.slice(-5).join('\n')
+  return `${head}\n\n... (${lines.length - 15} lines truncated) ...\n\n${summary}`
+}
+
+const pendingPaths = new Map<string, { toolName: string, timestamp: number }>()
+const fixCounters = new Map<string, number>()
+
+const oxlintGate: ExtensionFactory = (pi: ExtensionAPI): void => {
+  const log = pi.logger
+
+  log.info('[oxlint-gate] extension loaded (auto-fix mode)')
+  writeLog('INFO', 'extension loaded (auto-fix mode)')
+
+  // ── tool_call: record file path, don't block ────────────────────────
+  pi.on('tool_call', async (event, ctx) => {
+    if (!WRITE_TOOLS.has(event.toolName))
+      return
+
+    const extractedPath = extractFilePath(event.input as Record<string, unknown>)
+    if (!extractedPath)
+      return
+
+    const expandedPath = expandTilde(extractedPath)
+    const filePath = isAbsolute(expandedPath) ? expandedPath : resolve(ctx.cwd, expandedPath)
+
+    if (!TS_EXTENSIONS.test(filePath))
+      return
+    if (!isExistingFile(filePath))
+      return
+
+    pendingPaths.set(filePath, { toolName: event.toolName, timestamp: Date.now() })
+    return undefined
+  })
+
+  // ── tool_result: check & auto-fix ───────────────────────────────────
+  pi.on('tool_result', async (event, ctx) => {
+    if (!WRITE_TOOLS.has(event.toolName))
+      return
+
+    const extractedPath = extractFilePath(event.input as Record<string, unknown>)
+    if (!extractedPath)
+      return
+
+    const expandedPath = expandTilde(extractedPath)
+    const filePath = isAbsolute(expandedPath) ? expandedPath : resolve(ctx.cwd, expandedPath)
+
+    const pending = pendingPaths.get(filePath)
+    pendingPaths.delete(filePath)
+    if (!pending)
+      return
+
+    if (!TS_EXTENSIONS.test(filePath))
+      return
+    if (!isExistingFile(filePath))
+      return
+    if (!existsSync(OXLINT_CFG))
+      return
+
+    const ignorePatterns = loadIgnorePatterns(OXLINT_CFG)
+    if (matchesIgnorePattern(filePath, ignorePatterns))
+      return
+
+    const fixCount = fixCounters.get(filePath) ?? 0
+    if (fixCount >= MAX_FIX_ATTEMPTS) {
+      log.debug(`[oxlint-gate] max fix attempts (${MAX_FIX_ATTEMPTS}) reached for ${filePath}`)
+      return
+    }
+
+    // 1. Check for violations
+    const { passed } = runOxlint(filePath, OXLINT_CFG)
+    if (passed) {
+      log.info(`[oxlint-gate] passed: ${filePath}`)
+      writeLog('INFO', `passed: ${filePath}`)
+      fixCounters.delete(filePath) // reset counter on clean pass
+      return
+    }
+
+    log.warn(`[oxlint-gate] violations in ${filePath}, attempting auto-fix`)
+    writeLog('WARN', `violations in ${filePath}, attempting auto-fix`)
+
+    // 2. Try auto-fix
+    const fixResult = runOxlintFix(filePath, OXLINT_CFG)
+    fixCounters.set(filePath, fixCount + 1)
+
+    if (fixResult.fixed) {
+      log.info(`[oxlint-gate] auto-fixed: ${filePath}`)
+      writeLog('INFO', `auto-fixed: ${filePath}`)
+      return {
+        content: [{ type: 'text', text: `✅ [oxlint-gate] auto-fixed lint issues in ${filePath}` }],
+      }
+    }
+
+    // 3. Some violations remain — report to LLM
+    const remaining = truncateOutput(fixResult.output)
+    log.warn(`[oxlint-gate] partial fix in ${filePath}, remaining issues`)
+    writeLog('WARN', `partial fix in ${filePath}`)
+
+    pi.sendMessage(
+      {
+        customType: 'oxlint-gate',
+        content: `⚠️ [oxlint-gate] ${filePath} has remaining lint issues after auto-fix:\n\n${remaining}`,
+        display: true,
+        attribution: 'agent',
+      },
+      { triggerTurn: false },
+    )
+    return undefined
+  })
+
+  // ── turn_end: clear pending paths only (keep fixCounters to prevent loops) ──
+  pi.on('turn_end', async () => {
+    pendingPaths.clear()
+  })
+}
+
+export default oxlintGate

package/src/omp-types.ts

@@ -0,0 +1,129 @@
+/**
+ * OMP Extension type bridge.
+ *
+ * Re-exports the subset of extension types needed by this plugin.
+ * At runtime these resolve via OMP's package exports.
+ * For type-checking outside OMP, types are inlined below as a fallback.
+ */
+
+// ── OMP runtime types (resolved when loaded inside OMP) ────────────────
+// The extension factory receives ExtensionAPI; we only need the event shapes
+// and the handler signature for type-safe `pi.on()` calls.
+
+/** Fired on initial session load */
+export interface SessionStartEvent {
+  type: 'session_start'
+}
+
+/**
+ * Fired before a tool executes. Discriminated union by toolName.
+ * For the `edit` tool, input is Record<string, unknown> because
+ * the edit tool accepts 4 different schema modes (replace, patch,
+ * hashline, apply-patch).
+ */
+export interface EditToolCallEvent {
+  type: 'tool_call'
+  toolName: 'edit'
+  toolCallId: string
+  input: Record<string, unknown>
+}
+
+export interface WriteToolCallEvent {
+  type: 'tool_call'
+  toolName: 'write'
+  toolCallId: string
+  input: { path: string, content: string }
+}
+
+export interface ReadToolCallEvent {
+  type: 'tool_call'
+  toolName: 'read'
+  toolCallId: string
+  input: { path: string }
+}
+
+export interface BashToolCallEvent {
+  type: 'tool_call'
+  toolName: 'bash'
+  toolCallId: string
+  input: { command: string, env?: Record<string, string>, timeout?: number, cwd?: string }
+}
+
+export interface SearchToolCallEvent {
+  type: 'tool_call'
+  toolName: 'search'
+  toolCallId: string
+  input: { pattern: string, paths: string | string[], i?: boolean, gitignore?: boolean }
+}
+
+export interface FindToolCallEvent {
+  type: 'tool_call'
+  toolName: 'find'
+  toolCallId: string
+  input: { paths: string[], hidden?: boolean, gitignore?: boolean }
+}
+
+export interface CustomToolCallEvent {
+  type: 'tool_call'
+  toolName: string
+  toolCallId: string
+  input: Record<string, unknown>
+}
+
+export type ToolCallEvent
+  = | BashToolCallEvent
+    | ReadToolCallEvent
+    | EditToolCallEvent
+    | WriteToolCallEvent
+    | SearchToolCallEvent
+    | FindToolCallEvent
+    | CustomToolCallEvent
+
+/** Fired after a tool executes. */
+export interface ToolResultEvent {
+  type: 'tool_result'
+  toolName: string
+  toolCallId: string
+  input: Record<string, unknown>
+  content: ({ type: 'text', text: string } | { type: 'image', data: string, mimeType: string })[]
+  isError: boolean
+}
+
+/**
+ * Context passed to extension event handlers.
+ * We only need `cwd` from it.
+ */
+export interface ExtensionContext {
+  cwd: string
+}
+
+/** Handler function type */
+export type ExtensionHandler<E, R = undefined> = (
+  event: E,
+  ctx: ExtensionContext,
+) => Promise<R | void> | R | void
+
+/** Extension factory function type */
+export type ExtensionFactory = (pi: ExtensionAPI) => void | Promise<void>
+
+/**
+ * ExtensionAPI — the `pi` object passed to the factory.
+ * We only declare the subset we use (on, logger).
+ */
+export interface ExtensionAPI {
+  on: ((event: 'session_start', handler: ExtensionHandler<SessionStartEvent>) => void) & ((event: 'tool_call', handler: ExtensionHandler<ToolCallEvent, ToolCallEventResult | undefined>) => void) & ((event: 'tool_result', handler: ExtensionHandler<ToolResultEvent, ToolResultEventResult | undefined>) => void) & ((event: 'turn_end', handler: ExtensionHandler<{ type: 'turn_end' }>) => void)
+  logger: { debug: (msg: string) => void, info: (msg: string) => void, warn: (msg: string) => void, error: (msg: string) => void }
+  sendMessage: (message: { customType: string, content: string, display: boolean, attribution: string }, options?: { triggerTurn?: boolean }) => void
+}
+
+/** Return type for tool_call handlers (can block) */
+export interface ToolCallEventResult {
+  block?: boolean
+  reason?: string
+}
+
+/** Return type for tool_result handlers (can modify result) */
+export interface ToolResultEventResult {
+  content?: ({ type: 'text', text: string } | { type: 'image', data: string, mimeType: string })[]
+  isError?: boolean
+}