@wingsbutterfly/dsh-rtk 0.1.0

package/src/compact/index.ts

@@ -0,0 +1,284 @@
+import { homedir } from 'node:os'
+import { resolve } from 'node:path'
+
+import type { OutputCompactionConfig, RtkConfig } from '../config.js'
+import { aggregateLinterOutput } from './linter.js'
+import { filterBuildOutput } from './build.js'
+import { aggregateTestOutput } from './test-output.js'
+import { compactGitOutput } from './git.js'
+import { groupSearchResults } from './search.js'
+import { detectLanguage, filterSourceCode, smartTruncate } from './source.js'
+import { NO_OUTPUT_PLACEHOLDER, parseBashResult, renderBashResult } from './dsh-result.js'
+import { countLines, stripAnsi, truncate } from './text.js'
+
+/** Techniques whose effect cannot be undone by re-reading a smaller range. */
+const LOSSY_TECHNIQUES = ['build', 'test', 'git', 'linter', 'search', 'truncate', 'smart-truncate', 'source:'] as const
+
+/** Reads at or below this many lines are always left exact. */
+const READ_EXACT_LINE_THRESHOLD = 80
+
+/** Banner prefixed to a `read` result that lost information. */
+export const READ_COMPACTION_BANNER_PREFIX = '[rtk compacted output:'
+
+/** The tool-result projection compaction reads and writes. */
+export interface CompactionInput {
+  toolName: string
+  args: unknown
+  content: unknown
+}
+
+/** What one compaction pass did, for the session metrics. */
+export interface CompactionMetadata {
+  applied: boolean
+  techniques: string[]
+  truncated: boolean
+  originalCharCount: number
+  compactedCharCount: number
+  originalLineCount: number
+  compactedLineCount: number
+}
+
+/** The pipeline's verdict for one tool result. */
+export interface CompactionOutcome {
+  changed: boolean
+  content?: unknown[]
+  techniques: string[]
+  metadata?: CompactionMetadata
+}
+
+interface TextTransform {
+  text: string
+  techniques: string[]
+}
+
+function asRecord(value: unknown): Record<string, unknown> {
+  return typeof value === 'object' && value !== null ? (value as Record<string, unknown>) : {}
+}
+
+function asArray(value: unknown): unknown[] {
+  return Array.isArray(value) ? value : []
+}
+
+function isTextBlock(block: unknown): block is { type: 'text'; text: string } {
+  const record = asRecord(block)
+  return record.type === 'text' && typeof record.text === 'string'
+}
+
+function hasLossyTechnique(techniques: readonly string[]): boolean {
+  return techniques.some((technique) =>
+    LOSSY_TECHNIQUES.some((prefix) => (prefix.endsWith(':') ? technique.startsWith(prefix) : technique === prefix)),
+  )
+}
+
+/** Apply one nullable technique, recording it only when it changed the text. */
+function applyNullable(state: TextTransform, result: string | null, technique: string): void {
+  if (result === null || result === state.text) return
+  state.text = result
+  state.techniques.push(technique)
+}
+
+function applyAnsi(state: TextTransform, compaction: OutputCompactionConfig): void {
+  if (!compaction.stripAnsi) return
+  const stripped = stripAnsi(state.text)
+  if (stripped !== state.text) {
+    state.text = stripped
+    state.techniques.push('ansi')
+  }
+}
+
+/**
+ * Compact a bash result without disturbing its status markers.
+ *
+ * stdout is summarized by whichever technique recognizes the command; stderr is
+ * only stripped of escape codes, because an error message's exact wording is
+ * what the reader acts on. The trailing markers are re-attached verbatim, and
+ * a final budget check truncates the bodies while never cutting a marker.
+ */
+function compactBashText(text: string, command: string | undefined, compaction: OutputCompactionConfig): TextTransform {
+  const parts = parseBashResult(text)
+  if (parts.empty) return { text, techniques: [] }
+
+  const state: TextTransform = { text: parts.stdout, techniques: [] }
+  applyAnsi(state, compaction)
+
+  if (compaction.filterBuildOutput) applyNullable(state, filterBuildOutput(state.text, command), 'build')
+  if (compaction.aggregateTestOutput) applyNullable(state, aggregateTestOutput(state.text, command), 'test')
+  if (compaction.compactGitOutput) applyNullable(state, compactGitOutput(state.text, command), 'git')
+  if (compaction.aggregateLinterOutput) applyNullable(state, aggregateLinterOutput(state.text, command), 'linter')
+
+  let stdout = state.text
+  let stderr = parts.stderr
+  if (stderr !== undefined && compaction.stripAnsi) stderr = stripAnsi(stderr)
+
+  const render = (): string =>
+    renderBashResult({
+      empty: false,
+      stdout,
+      ...(stderr === undefined ? {} : { stderr }),
+      markers: parts.markers,
+    })
+
+  let rendered = render()
+  if (compaction.truncate.enabled && rendered.length > compaction.truncate.maxChars) {
+    const markerOverhead = renderBashResult({ empty: false, stdout: '', markers: parts.markers }).length
+    const budget = Math.max(1, compaction.truncate.maxChars - markerOverhead - 8)
+    // stderr keeps the smaller share: it is usually short, and when it is not,
+    // its head is still the diagnostic while its tail is usually a stack dump.
+    const stderrBudget = stderr === undefined ? 0 : Math.min(stderr.length, Math.floor(budget * 0.4))
+    const stdoutBudget = Math.max(1, budget - stderrBudget)
+    if (stdout.length > stdoutBudget) stdout = truncate(stdout, stdoutBudget)
+    if (stderr !== undefined && stderr.length > stderrBudget) stderr = truncate(stderr, stderrBudget)
+    rendered = render()
+    state.techniques.push('truncate')
+  }
+
+  // Compaction must never make a result bigger than the text it replaced.
+  if (rendered.length >= text.length) return { text, techniques: [] }
+  return { text: rendered, techniques: state.techniques }
+}
+
+/**
+ * Whether a `read` result must stay byte-exact.
+ *
+ * Three cases: the caller asked for a narrow range (the tool already bounded
+ * it, and the caller will edit against what it sees), the file is short enough
+ * that filtering saves nothing worth the risk, or the path lives under a skill
+ * directory — skills are instructions the agent follows verbatim.
+ */
+function shouldPreserveExactRead(text: string, args: Record<string, unknown>, compaction: OutputCompactionConfig): boolean {
+  if (!compaction.readCompaction.enabled) return true
+  if (args.offset !== undefined || args.limit !== undefined) return true
+  if (countLines(text) <= READ_EXACT_LINE_THRESHOLD) return true
+
+  if (compaction.preserveExactSkillReads && typeof args.path === 'string') {
+    const target = resolve(args.path)
+    const roots = [resolve(homedir(), '.agents', 'skills'), resolve(homedir(), '.dsh', 'skills')]
+    let cursor = process.cwd()
+    for (;;) {
+      roots.push(resolve(cursor, '.agents', 'skills'))
+      const parent = resolve(cursor, '..')
+      if (parent === cursor) break
+      cursor = parent
+    }
+    if (roots.some((root) => target === root || target.startsWith(`${root}/`))) return true
+  }
+
+  return false
+}
+
+function compactReadText(
+  text: string,
+  args: Record<string, unknown>,
+  compaction: OutputCompactionConfig,
+): TextTransform {
+  if (shouldPreserveExactRead(text, args, compaction)) return { text, techniques: [] }
+
+  const state: TextTransform = { text, techniques: [] }
+  applyAnsi(state, compaction)
+
+  const filePath = typeof args.path === 'string' ? args.path : ''
+  const language = detectLanguage(filePath)
+
+  if (compaction.sourceCodeFilteringEnabled && compaction.sourceCodeFiltering !== 'none') {
+    applyNullable(state, filterSourceCode(state.text, language, compaction.sourceCodeFiltering), `source:${compaction.sourceCodeFiltering}`)
+  }
+
+  if (compaction.smartTruncate.enabled && countLines(state.text) > compaction.smartTruncate.maxLines) {
+    applyNullable(state, smartTruncate(state.text, compaction.smartTruncate.maxLines), 'smart-truncate')
+  }
+
+  if (compaction.truncate.enabled && state.text.length > compaction.truncate.maxChars) {
+    applyNullable(state, truncate(state.text, compaction.truncate.maxChars), 'truncate')
+  }
+
+  if (state.techniques.length === 0) return { text, techniques: [] }
+
+  // The banner is part of the returned result, so the size guard must weigh it.
+  // Filtering one comment line out of a short file saves less than the banner
+  // costs, and without this the result would come back longer than the text it
+  // replaced — the exact invariant the guard exists to hold.
+  const banner = `${READ_COMPACTION_BANNER_PREFIX} ${state.techniques.join(', ')}]`
+  const rendered = `${banner}\n${state.text}`
+  if (rendered.length >= text.length) return { text, techniques: [] }
+  return { text: rendered, techniques: state.techniques }
+}
+
+function compactGrepText(text: string, compaction: OutputCompactionConfig): TextTransform {
+  const state: TextTransform = { text, techniques: [] }
+  applyAnsi(state, compaction)
+
+  if (compaction.groupSearchOutput) applyNullable(state, groupSearchResults(state.text), 'search')
+
+  if (compaction.truncate.enabled && state.text.length > compaction.truncate.maxChars) {
+    applyNullable(state, truncate(state.text, compaction.truncate.maxChars), 'truncate')
+  }
+
+  if (state.text.length >= text.length) return { text, techniques: [] }
+  return state
+}
+
+/**
+ * Run every enabled technique over one tool result.
+ *
+ * Returns `changed: false` whenever the result would not actually shrink, so a
+ * caller can treat "no outcome" and "no improvement" identically and the model
+ * never pays for a rewrite that saved nothing.
+ *
+ * @param input - the tool name, its parsed arguments, and the content blocks.
+ * @param config - the resolved plugin configuration.
+ * @returns the replacement content and the techniques that fired.
+ */
+export function compactToolResult(input: CompactionInput, config: RtkConfig): CompactionOutcome {
+  const compaction = config.outputCompaction
+  if (!config.enabled || !compaction.enabled) return { changed: false, techniques: [] }
+  if (!config.compactedTools.includes(input.toolName)) return { changed: false, techniques: [] }
+
+  const sourceContent = asArray(input.content)
+  if (sourceContent.length === 0) return { changed: false, techniques: [] }
+
+  const args = asRecord(input.args)
+  const command = typeof args.command === 'string' ? args.command : undefined
+  const techniques = new Set<string>()
+  const originalChunks: string[] = []
+  const compactedChunks: string[] = []
+  let changed = false
+
+  const nextContent = sourceContent.map((block) => {
+    if (!isTextBlock(block)) return block
+
+    let transformed: TextTransform = { text: block.text, techniques: [] }
+    if (input.toolName === 'bash') transformed = compactBashText(block.text, command, compaction)
+    else if (input.toolName === 'read') transformed = compactReadText(block.text, args, compaction)
+    else if (input.toolName === 'grep') transformed = compactGrepText(block.text, compaction)
+
+    for (const technique of transformed.techniques) techniques.add(technique)
+    originalChunks.push(block.text)
+    compactedChunks.push(transformed.text)
+
+    if (transformed.text === block.text) return block
+    changed = true
+    return { ...(block as Record<string, unknown>), text: transformed.text }
+  })
+
+  if (!changed) return { changed: false, techniques: [] }
+  if (originalChunks.join('\n') === NO_OUTPUT_PLACEHOLDER) return { changed: false, techniques: [] }
+
+  const originalText = originalChunks.join('\n')
+  const compactedText = compactedChunks.join('\n')
+  const applied = Array.from(techniques)
+
+  return {
+    changed: true,
+    content: nextContent,
+    techniques: applied,
+    metadata: {
+      applied: true,
+      techniques: applied,
+      truncated: hasLossyTechnique(applied),
+      originalCharCount: originalText.length,
+      compactedCharCount: compactedText.length,
+      originalLineCount: countLines(originalText),
+      compactedLineCount: countLines(compactedText),
+    },
+  }
+}

package/src/compact/linter.ts

@@ -0,0 +1,126 @@
+import { matchesCommandPatterns, normalizeCommandForDetection } from './detect.js'
+import { compactPath } from './text.js'
+
+const LINTER_COMMAND_PATTERNS = [
+  /^(?:pnpm\s+)?(?:npx\s+)?eslint\b/,
+  /^(?:npx\s+)?prettier\b/,
+  /^ruff\b/,
+  /^pylint\b/,
+  /^mypy\b/,
+  /^flake8\b/,
+  /^black\b/,
+  /^cargo\s+clippy\b/,
+  /^golangci-lint\b/,
+] as const
+
+interface Issue {
+  severity: 'ERROR' | 'WARNING'
+  rule: string
+  file: string
+  line?: number
+  message: string
+}
+
+const MAX_RULES = 10
+const MAX_FILES = 10
+const MAX_RULES_PER_FILE = 3
+
+/** Whether the command is a linter this module understands. */
+export function isLinterCommand(command: string | undefined | null): boolean {
+  return matchesCommandPatterns(command, LINTER_COMMAND_PATTERNS)
+}
+
+function parseIssueLine(line: string): Issue | null {
+  const fileLineMatch = line.match(/^(.+):(\d+):(\d+):\s*(.+)$/)
+  if (fileLineMatch) {
+    const lineNumber = Number.parseInt(fileLineMatch[2] ?? '0', 10)
+    const content = fileLineMatch[4] ?? line
+    return {
+      severity: /warning/i.test(content) ? 'WARNING' : 'ERROR',
+      rule: content.match(/\[(.+?)\]$/)?.[1] ?? 'unknown',
+      file: fileLineMatch[1] ?? 'unknown',
+      ...(Number.isNaN(lineNumber) ? {} : { line: lineNumber }),
+      message: content,
+    }
+  }
+
+  const rustMatch = line.match(/^(error|warning):\s*(.+?)\s+at\s+(.+):(\d+):(\d+)$/)
+  if (rustMatch) {
+    const lineNumber = Number.parseInt(rustMatch[4] ?? '0', 10)
+    return {
+      severity: (rustMatch[1]?.toUpperCase() ?? 'ERROR') as 'ERROR' | 'WARNING',
+      rule: 'unknown',
+      file: rustMatch[3] ?? 'unknown',
+      ...(Number.isNaN(lineNumber) ? {} : { line: lineNumber }),
+      message: rustMatch[2] ?? line,
+    }
+  }
+
+  return null
+}
+
+function detectLinterType(command: string | undefined | null): string {
+  const normalized = normalizeCommandForDetection(command)
+  if (!normalized) return 'Linter'
+  if (/(?:^|\s)eslint\b/.test(normalized)) return 'ESLint'
+  if (/^ruff\b/.test(normalized)) return 'Ruff'
+  if (/^pylint\b/.test(normalized)) return 'Pylint'
+  if (/^mypy\b/.test(normalized)) return 'MyPy'
+  if (/^flake8\b/.test(normalized)) return 'Flake8'
+  if (/clippy\b/.test(normalized)) return 'Clippy'
+  if (/^golangci-lint\b/.test(normalized)) return 'GolangCI-Lint'
+  if (/prettier\b/.test(normalized)) return 'Prettier'
+  return 'Linter'
+}
+
+/**
+ * Reduce linter output to counts plus the rules and files that dominate.
+ *
+ * The full issue list is usually thousands of near-identical lines; the
+ * distribution is what a reader acts on. Individual messages are dropped in
+ * favor of counts, which is lossy by design — the reader re-runs on the file
+ * they choose to fix.
+ */
+export function aggregateLinterOutput(output: string, command: string | undefined | null): string | null {
+  if (!isLinterCommand(command)) return null
+
+  const linterType = detectLinterType(command)
+  const issues: Issue[] = []
+  for (const line of output.split('\n')) {
+    const issue = parseIssueLine(line)
+    if (issue) issues.push(issue)
+  }
+
+  if (issues.length === 0) return `[OK] ${linterType}: No issues found`
+
+  const errors = issues.filter((issue) => issue.severity === 'ERROR').length
+  const warnings = issues.filter((issue) => issue.severity === 'WARNING').length
+
+  const byRule = new Map<string, number>()
+  const byFile = new Map<string, Issue[]>()
+  for (const issue of issues) {
+    byRule.set(issue.rule, (byRule.get(issue.rule) ?? 0) + 1)
+    const existing = byFile.get(issue.file) ?? []
+    existing.push(issue)
+    byFile.set(issue.file, existing)
+  }
+
+  let result = `${linterType}: ${errors} errors, ${warnings} warnings in ${byFile.size} files\n`
+  result += '═══════════════════════════════════════\n'
+  result += 'Top rules:\n'
+  for (const [rule, count] of Array.from(byRule.entries()).sort((left, right) => right[1] - left[1]).slice(0, MAX_RULES)) {
+    result += `  ${rule} (${count}x)\n`
+  }
+
+  result += '\nTop files:\n'
+  const sortedFiles = Array.from(byFile.entries()).sort((left, right) => right[1].length - left[1].length).slice(0, MAX_FILES)
+  for (const [file, fileIssues] of sortedFiles) {
+    result += `  ${compactPath(file, 40)} (${fileIssues.length} issues)\n`
+    const fileRules = new Map<string, number>()
+    for (const issue of fileIssues) fileRules.set(issue.rule, (fileRules.get(issue.rule) ?? 0) + 1)
+    const topRules = Array.from(fileRules.entries()).sort((left, right) => right[1] - left[1]).slice(0, MAX_RULES_PER_FILE)
+    for (const [rule, count] of topRules) result += `    ${rule} (${count})\n`
+  }
+
+  return result
+}

package/src/compact/search.ts

@@ -0,0 +1,73 @@
+import { compactPath } from './text.js'
+
+interface SearchResult {
+  file: string
+  lineNumber: string
+  content: string
+}
+
+/** Minimum share of non-blank lines that must parse as `file:line:content`. */
+const MIN_MATCH_RATIO = 0.6
+
+/**
+ * Group `grep`-style matches by file.
+ *
+ * Returns `null` when the output is not recognizably a match list. The format
+ * check is what keeps this safe across search tools: ripgrep, GNU grep, and the
+ * harness's own `grep` all print `path:line:text`, but a command whose name
+ * merely resembles a search may print anything at all, and summarizing that
+ * would silently discard real output. Erring toward `null` leaves the text
+ * untouched, which is always correct.
+ *
+ * @param output - raw search output.
+ * @param maxResults - cap on rendered match lines across all files.
+ * @returns the grouped summary, or `null` when the shape does not match.
+ */
+export function groupSearchResults(output: string, maxResults = 50): string | null {
+  const lines = output.split('\n').filter((line) => line.trim().length > 0)
+  if (lines.length === 0) return null
+
+  const results: SearchResult[] = []
+  let parseable = 0
+
+  for (const line of lines) {
+    const match = line.match(/^(.+?):(\d+)?:(.*)$/)
+    if (!match) continue
+    parseable++
+    results.push({
+      file: match[1] ?? 'unknown',
+      lineNumber: match[2] ?? '?',
+      content: match[3] ?? '',
+    })
+  }
+
+  if (results.length === 0) return null
+  if (parseable / lines.length < MIN_MATCH_RATIO) return null
+
+  const byFile = new Map<string, SearchResult[]>()
+  for (const result of results) {
+    const existing = byFile.get(result.file) ?? []
+    existing.push(result)
+    byFile.set(result.file, existing)
+  }
+
+  let outputText = `${results.length} matches in ${byFile.size} files:\n\n`
+  const sortedFiles = Array.from(byFile.entries()).sort((left, right) => left[0].localeCompare(right[0]))
+
+  let shown = 0
+  for (const [file, matches] of sortedFiles) {
+    if (shown >= maxResults) break
+    outputText += `> ${compactPath(file, 50)} (${matches.length} matches):\n`
+    for (const match of matches.slice(0, 10)) {
+      let cleaned = match.content.trim()
+      if (cleaned.length > 70) cleaned = `${cleaned.slice(0, 67)}...`
+      outputText += `    ${match.lineNumber}: ${cleaned}\n`
+      shown++
+    }
+    if (matches.length > 10) outputText += `  +${matches.length - 10} more\n`
+    outputText += '\n'
+  }
+
+  if (results.length > shown) outputText += `... +${results.length - shown} more\n`
+  return outputText
+}