Skip to content

ccch1mneyyy/dsh-TUI / .agents/skills/review

review

Verified

Review or de-slop concrete changes in ccch1mneyyy/dsh-TUI at maintainer level: PR numbers or URLs, branches, commit ranges, patch files, staged or unstaged worktrees, and scoped repository-hygiene requests. Use for evidence-first correctness, contract, repository-rule, process, and behavior-preserving cleanup review, including debug residue, dead or duplicate code, speculative abstractions, stale comments or tests, and unrelated diff churn. Do not use for abstract designs with no concrete repository artifact; use audit for repository-wide assessments and vuln-check for security-only checks.

FileKindSize
SKILL.mdskill md10.5 KB
references/contract-gates.mdmarkdown5.0 KB
references/deslop-gates.mdmarkdown5.9 KB
references/evidence-base.mdmarkdown7.2 KB
references/redlines.mdmarkdown4.8 KB
references/report-contract.mdmarkdown3.1 KB
references/verification-map.mdmarkdown5.1 KB
scripts/contract-snapshot.mjsexecutablescript15.6 KB
scripts/scan-diff-hygiene.mjsexecutablescript9.6 KB

scripts/contract-snapshot.mjs

View on GitHub
#!/usr/bin/env node

import { execFileSync } from 'node:child_process'
import { createHash } from 'node:crypto'
import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
import { basename, dirname, join, resolve } from 'node:path'
import { tmpdir } from 'node:os'
import process from 'node:process'

const SCHEMA_VERSION = 1

const CONTRACT_FILES = [
  'package.json',
  'AGENTS.md',
  'ADAPTER.md',
  'docs/contributing.md',
  'src/dsh-adapter/contract.ts',
  'src/plugin-host.ts',
  'cordis.patch.yml',
  'patch-surface.snapshot.json',
  'tui-profile/protocols/tui-channel.js',
  '.github/workflows/ci.yml',
]

const SUBMODULE_PATHS = [
  // `dsh-auth` only exists in the self-test fixture's synthetic repo; the real
  // repository no longer mounts it (and never has a directory of that name), so
  // the WORKTREE probe simply finds nothing and falls back to the gitlink.
  'dsh-auth',
  // `tui-profile` used to be mounted here too; it is now plain in-tree files, so
  // it must NOT be probed as a submodule — `git -C tui-profile rev-parse HEAD`
  // would silently report the outer repository's HEAD.
  'vendor/dsh-std',
]

function fail(message, code = 2) {
  console.error(`contract-snapshot: ${message}`)
  process.exit(code)
}

function git(repo, args, { allowFailure = false } = {}) {
  try {
    return execFileSync('git', ['-C', repo, ...args], {
      encoding: 'utf8',
      stdio: ['ignore', 'pipe', 'pipe'],
      maxBuffer: 32 * 1024 * 1024,
    })
  } catch (error) {
    if (allowFailure) return null
    const stderr = error?.stderr?.toString?.().trim()
    throw new Error(stderr || error.message)
  }
}

function sha256(text) {
  return createHash('sha256').update(text).digest('hex')
}

function stable(value) {
  if (Array.isArray(value)) return value.map(stable)
  if (value && typeof value === 'object') {
    return Object.fromEntries(
      Object.keys(value).sort().map(key => [key, stable(value[key])]),
    )
  }
  return value
}

function readAtRevision(repo, revision, path) {
  if (revision === 'WORKTREE') {
    try {
      return readFileSync(join(repo, path), 'utf8')
    } catch {
      return null
    }
  }

  if (revision === 'INDEX') {
    return git(repo, ['show', `:${path}`], { allowFailure: true })
  }

  return git(repo, ['show', `${revision}:${path}`], { allowFailure: true })
}

function resolvedRevision(repo, revision) {
  if (revision === 'WORKTREE') {
    const head = git(repo, ['rev-parse', 'HEAD'], { allowFailure: true })?.trim()
    return head ? `WORKTREE@${head}` : 'WORKTREE'
  }
  if (revision === 'INDEX') {
    const head = git(repo, ['rev-parse', 'HEAD'], { allowFailure: true })?.trim()
    return head ? `INDEX@${head}` : 'INDEX'
  }
  return git(repo, ['rev-parse', revision]).trim()
}

function parsePackage(text) {
  if (text == null) return { present: false }
  try {
    const pkg = JSON.parse(text)
    return stable({
      present: true,
      name: pkg.name ?? null,
      version: pkg.version ?? null,
      packageManager: pkg.packageManager ?? null,
      engines: pkg.engines ?? {},
      imports: pkg.imports ?? {},
      bin: pkg.bin ?? {},
      exports: pkg.exports ?? {},
      dependencies: pkg.dependencies ?? {},
      peerDependencies: pkg.peerDependencies ?? {},
      peerDependenciesMeta: pkg.peerDependenciesMeta ?? {},
      devDependencies: pkg.devDependencies ?? {},
      scripts: pkg.scripts ?? {},
      files: pkg.files ?? [],
    })
  } catch (error) {
    return {
      present: true,
      parseError: error.message,
      sha256: sha256(text),
    }
  }
}

function normalizeStatement(statement) {
  return statement
    .replace(/\/\*[\s\S]*?\*\//g, ' ')
    .replace(/\/\/[^\n]*/g, ' ')
    .replace(/\s+/g, ' ')
    .trim()
}

function extractExportStatements(text) {
  if (!text) return []
  const statements = []

  const reExports = /(^|\n)\s*export\s+(?:type\s+)?\{[\s\S]*?\}\s+from\s+['"][^'"]+['"]\s*;?/g
  for (const match of text.matchAll(reExports)) {
    statements.push(normalizeStatement(match[0]))
  }

  const exportAll = /(^|\n)\s*export\s+\*\s+from\s+['"][^'"]+['"]\s*;?/g
  for (const match of text.matchAll(exportAll)) {
    statements.push(normalizeStatement(match[0]))
  }

  const declarations = /(^|\n)\s*export\s+(?:declare\s+)?(?:async\s+)?(?:const|let|var|function|class|enum|interface|type)\s+([A-Za-z_$][\w$]*)/g
  for (const match of text.matchAll(declarations)) {
    statements.push(`export declaration ${match[2]}`)
  }

  return [...new Set(statements)].sort()
}

function extractQuotedList(text, symbol) {
  if (!text) return []
  const escaped = symbol.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
  const pattern = new RegExp(`${escaped}\\s*=\\s*(?:Object\\.freeze\\s*\\()?\\s*\\[([\\s\\S]*?)\\]`, 'm')
  const match = text.match(pattern)
  if (!match) return []
  return [...match[1].matchAll(/['"]([^'"]+)['"]/g)].map(item => item[1]).sort()
}

function extractProtocol(text) {
  if (!text) return { present: false }
  const apiVersion =
    text.match(/TUI_CHANNEL_API_VERSION\s*=\s*['"]([^'"]+)['"]/)?.[1] ??
    text.match(/apiVersion\s*:\s*['"]([^'"]+)['"]/)?.[1] ??
    null
  const wireRevisionRaw = text.match(/TUI_CHANNEL_WIRE_REVISION\s*=\s*(\d+)/)?.[1]
  const features = extractQuotedList(text, 'TUI_CHANNEL_FEATURES')
  return {
    present: true,
    apiVersion,
    wireRevision: wireRevisionRaw == null ? null : Number(wireRevisionRaw),
    features,
  }
}

function readSubmodulePointers(repo, revision) {
  if (revision === 'WORKTREE') {
    // The worktree revision is what is checked out on disk, so read each
    // submodule's own HEAD: a staged switch and an unstaged `git submodule
    // update` both move it, while `git ls-tree HEAD` keeps reporting the
    // committed gitlink for either.
    const recorded = parseSubmoduleOutput(git(repo, ['ls-tree', 'HEAD', '--', ...SUBMODULE_PATHS], { allowFailure: true }) ?? '')
    const result = {}
    for (const path of SUBMODULE_PATHS) {
      const head = git(repo, ['-C', path, 'rev-parse', 'HEAD'], { allowFailure: true })?.trim()
      // Uninitialized submodule: keep the recorded gitlink instead of dropping
      // the key, so a missing checkout does not read as contract drift.
      if (head) result[path] = head
      else if (recorded[path]) result[path] = recorded[path]
    }
    return stable(result)
  }

  if (revision === 'INDEX') {
    const output = git(repo, ['ls-files', '--stage', '--', ...SUBMODULE_PATHS], { allowFailure: true }) ?? ''
    return parseSubmoduleOutput(output)
  }

  const output = git(repo, ['ls-tree', revision, '--', ...SUBMODULE_PATHS], { allowFailure: true }) ?? ''
  return parseSubmoduleOutput(output)
}

function parseSubmoduleOutput(output) {
  const result = {}
  for (const line of output.split('\n')) {
    if (!line.trim()) continue
    const match = line.match(/^160000\s+(?:commit\s+)?([0-9a-f]{40})\s+\d?\s*\t?(.+)$/)
    if (match) result[match[2]] = match[1]
  }
  return stable(result)
}

function buildSnapshot(repoInput, revisionInput) {
  const repo = resolve(repoInput)
  const revision = revisionInput || 'HEAD'
  const resolved = resolvedRevision(repo, revision)
  const contents = Object.fromEntries(
    CONTRACT_FILES.map(path => [path, readAtRevision(repo, revision, path)]),
  )

  const files = stable(Object.fromEntries(
    CONTRACT_FILES.map(path => {
      const text = contents[path]
      return [path, text == null
        ? { present: false }
        : { present: true, bytes: Buffer.byteLength(text), sha256: sha256(text) }]
    }),
  ))

  return stable({
    schemaVersion: SCHEMA_VERSION,
    repository: basename(repo),
    requestedRevision: revision,
    resolvedRevision: resolved,
    package: parsePackage(contents['package.json']),
    pluginHost: {
      present: contents['src/plugin-host.ts'] != null,
      exportStatements: extractExportStatements(contents['src/plugin-host.ts']),
    },
    protocol: extractProtocol(contents['tui-profile/protocols/tui-channel.js']),
    submodules: readSubmodulePointers(repo, revision),
    files,
  })
}

function comparable(snapshot) {
  const {
    requestedRevision: _requestedRevision,
    resolvedRevision: _resolvedRevision,
    repository: _repository,
    ...rest
  } = snapshot
  return rest
}

function jsonPointerToken(token) {
  return String(token).replace(/~/g, '~0').replace(/\//g, '~1')
}

function diffValues(base, head, path = '') {
  if (Object.is(base, head)) return []

  const baseIsObject = base && typeof base === 'object'
  const headIsObject = head && typeof head === 'object'
  const bothPlainObjects = baseIsObject && headIsObject && !Array.isArray(base) && !Array.isArray(head)

  if (bothPlainObjects) {
    const keys = [...new Set([...Object.keys(base), ...Object.keys(head)])].sort()
    return keys.flatMap(key => diffValues(
      base[key],
      head[key],
      `${path}/${jsonPointerToken(key)}`,
    ))
  }

  if (Array.isArray(base) && Array.isArray(head)) {
    if (JSON.stringify(base) === JSON.stringify(head)) return []
    return [{ path: path || '/', base, head }]
  }

  return [{ path: path || '/', base: base ?? null, head: head ?? null }]
}

function compareSnapshots(baseSnapshot, headSnapshot) {
  return {
    schemaVersion: SCHEMA_VERSION,
    baseRevision: baseSnapshot.resolvedRevision,
    headRevision: headSnapshot.resolvedRevision,
    differences: diffValues(comparable(baseSnapshot), comparable(headSnapshot)),
    base: baseSnapshot,
    head: headSnapshot,
  }
}

function writeFixture(root, version, exportTarget, wireRevision) {
  const files = {
    'package.json': JSON.stringify({
      name: 'fixture',
      version,
      packageManager: 'pnpm@11.0.0',
      exports: { '.': { import: exportTarget, types: './lib/index.d.ts' } },
      bin: { fixture: './bin.js' },
      peerDependencies: { '@deepseek-ai/example': '^1.0.0' },
      devDependencies: { '@deepseek-ai/example': '^1.0.0' },
      scripts: { build: 'echo build' },
    }, null, 2),
    'AGENTS.md': '# fixture\n',
    'ADAPTER.md': '# adapter\n',
    'docs/contributing.md': '# contributing\n',
    'src/dsh-adapter/contract.ts': `export const VERSION = '${version}'\n`,
    'src/plugin-host.ts': "export { alpha, beta } from './impl.js'\nexport type { Gamma } from './types.js'\n",
    'cordis.patch.yml': 'version: 1\n',
    'patch-surface.snapshot.json': '{"version":1}\n',
    'tui-profile/protocols/tui-channel.js': `export const TUI_CHANNEL_API_VERSION = 'tui.dsh/v1alpha1'\nexport const TUI_CHANNEL_WIRE_REVISION = ${wireRevision}\nexport const TUI_CHANNEL_FEATURES = ['commands', 'skills']\n`,
    '.github/workflows/ci.yml': 'name: ci\n',
  }
  for (const [path, content] of Object.entries(files)) {
    const destination = join(root, path)
    mkdirSync(dirname(destination), { recursive: true })
    writeFileSync(destination, content)
  }
}

function selfTest() {
  const root = mkdtempSync(join(tmpdir(), 'contract snapshot-'))
  try {
    git(root, ['init', '-q'])
    git(root, ['config', 'user.email', 'fixture@example.invalid'])
    git(root, ['config', 'user.name', 'Fixture'])

    writeFixture(root, '1.0.0', './lib/index.js', 1)
    git(root, ['add', '.'])
    git(root, ['commit', '-qm', 'base'])
    const base = git(root, ['rev-parse', 'HEAD']).trim()

    writeFixture(root, '1.1.0', './lib/index-v2.js', 2)
    writeFileSync(join(root, 'src/plugin-host.ts'), "export { alpha, beta, delta } from './impl.js'\n")
    git(root, ['add', '.'])
    git(root, ['commit', '-qm', 'head'])
    const head = git(root, ['rev-parse', 'HEAD']).trim()

    const result = compareSnapshots(buildSnapshot(root, base), buildSnapshot(root, head))
    const paths = result.differences.map(item => item.path)
    const expected = [
      '/package/version',
      '/package/exports/./import',
      '/protocol/wireRevision',
      '/pluginHost/exportStatements',
    ]
    for (const path of expected) {
      if (!paths.includes(path)) throw new Error(`missing expected diff: ${path}`)
    }

    writeFixture(root, '1.2.0', './lib/index-v3.js', 3)
    const worktree = buildSnapshot(root, 'WORKTREE')
    if (worktree.package.version !== '1.2.0') throw new Error('WORKTREE snapshot did not read filesystem')

    git(root, ['add', 'package.json'])
    const index = buildSnapshot(root, 'INDEX')
    if (index.package.version !== '1.2.0') throw new Error('INDEX snapshot did not read staged content')

    // Submodule pointers: WORKTREE reads each submodule's own HEAD, so both a
    // staged and an unstaged pointer switch are visible (ls-tree HEAD reports
    // the committed gitlink for either).
    const subUpstream = mkdtempSync(join(tmpdir(), 'contract submodule-'))
    try {
      git(subUpstream, ['init', '-q'])
      git(subUpstream, ['config', 'user.email', 'fixture@example.invalid'])
      git(subUpstream, ['config', 'user.name', 'Fixture'])
      writeFileSync(join(subUpstream, 'file.txt'), 'one\n')
      git(subUpstream, ['add', '.'])
      git(subUpstream, ['commit', '-qm', 'sub base'])
      const subBase = git(subUpstream, ['rev-parse', 'HEAD']).trim()
      writeFileSync(join(subUpstream, 'file.txt'), 'two\n')
      git(subUpstream, ['commit', '-qam', 'sub head'])
      const subHead = git(subUpstream, ['rev-parse', 'HEAD']).trim()

      git(root, ['clone', '-q', subUpstream, 'dsh-auth'])
      git(join(root, 'dsh-auth'), ['checkout', '-q', subBase])
      git(root, ['update-index', '--add', '--cacheinfo', `160000,${subBase},dsh-auth`])
      git(root, ['commit', '-qm', 'submodule pointer'])
      if (buildSnapshot(root, 'HEAD').submodules['dsh-auth'] !== subBase) {
        throw new Error('HEAD snapshot must report the committed submodule gitlink')
      }

      // Unstaged switch: only the submodule's own HEAD moves.
      git(join(root, 'dsh-auth'), ['checkout', '-q', subHead])
      if (buildSnapshot(root, 'WORKTREE').submodules['dsh-auth'] !== subHead) {
        throw new Error('WORKTREE snapshot must read the submodule HEAD, not the committed gitlink')
      }

      // Staged switch: the index moves as well.
      git(root, ['add', 'dsh-auth'])
      if (buildSnapshot(root, 'INDEX').submodules['dsh-auth'] !== subHead) {
        throw new Error('INDEX snapshot must read the staged submodule gitlink')
      }
    } finally {
      rmSync(subUpstream, { recursive: true, force: true })
    }

    console.log(`contract-snapshot self-test: OK (${result.differences.length} differences)`)
  } finally {
    rmSync(root, { recursive: true, force: true })
  }
}

function parseArgs(argv) {
  const args = { repo: '.', revision: 'HEAD', compare: null, selfTest: false }
  for (let i = 0; i < argv.length; i += 1) {
    const arg = argv[i]
    if (arg === '--repo') args.repo = argv[++i]
    else if (arg === '--rev') args.revision = argv[++i]
    else if (arg === '--compare') args.compare = [argv[++i], argv[++i]]
    else if (arg === '--self-test') args.selfTest = true
    else if (arg === '--help' || arg === '-h') {
      console.log(`Usage:
  node contract-snapshot.mjs --repo <path> --rev <revision|WORKTREE|INDEX>
  node contract-snapshot.mjs --repo <path> --compare <base> <head>
  node contract-snapshot.mjs --self-test

The output is evidence for review, not an automatic compatibility verdict.`)
      process.exit(0)
    } else fail(`unknown argument: ${arg}`)
  }
  if (!args.repo) fail('--repo requires a path')
  if (args.compare?.some(value => !value)) fail('--compare requires two revisions')
  return args
}

function main() {
  const args = parseArgs(process.argv.slice(2))
  if (args.selfTest) return selfTest()

  try {
    const output = args.compare
      ? compareSnapshots(
          buildSnapshot(args.repo, args.compare[0]),
          buildSnapshot(args.repo, args.compare[1]),
        )
      : buildSnapshot(args.repo, args.revision)
    console.log(JSON.stringify(output, null, 2))
  } catch (error) {
    fail(error.message, 1)
  }
}

main()
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall