beast-devtools 0.0.1

package/devtools/server/diff.ts

@@ -0,0 +1,82 @@
+import type { DiffHunk, DiffLine } from '../shared/types.js'
+
+export interface LineDiff {
+  added: number
+  removed: number
+  hunks: DiffHunk[]
+}
+
+/**
+ * Line diff for refactor previews. Edits are localized, so the common prefix
+ * and suffix are trimmed before an LCS pass over the changed middle.
+ */
+export function diffLines(before: readonly string[], after: readonly string[], context = 2): LineDiff {
+  let prefix = 0
+  while (prefix < before.length && prefix < after.length && before[prefix] === after[prefix]) prefix++
+  let suffix = 0
+  while (
+    suffix < before.length - prefix &&
+    suffix < after.length - prefix &&
+    before[before.length - 1 - suffix] === after[after.length - 1 - suffix]
+  ) suffix++
+
+  const a = before.slice(prefix, before.length - suffix)
+  const b = after.slice(prefix, after.length - suffix)
+  const table = Array.from({ length: a.length + 1 }, () => new Uint32Array(b.length + 1))
+  for (let i = a.length - 1; i >= 0; i--) {
+    for (let j = b.length - 1; j >= 0; j--) {
+      table[i]![j] = a[i] === b[j] ? table[i + 1]![j + 1]! + 1 : Math.max(table[i + 1]![j]!, table[i]![j + 1]!)
+    }
+  }
+
+  // Every line of both files, tagged, with 1-based positions for hunk headers.
+  const ops: Array<DiffLine & { oldLine: number; newLine: number }> = []
+  for (let k = 0; k < prefix; k++) ops.push({ type: 'context', text: before[k]!, oldLine: k + 1, newLine: k + 1 })
+  let i = 0
+  let j = 0
+  while (i < a.length || j < b.length) {
+    if (i < a.length && j < b.length && a[i] === b[j]) {
+      ops.push({ type: 'context', text: a[i]!, oldLine: prefix + i + 1, newLine: prefix + j + 1 })
+      i++
+      j++
+    } else if (j < b.length && (i === a.length || table[i]![j + 1]! > table[i + 1]![j]!)) {
+      ops.push({ type: 'add', text: b[j]!, oldLine: prefix + i + 1, newLine: prefix + j + 1 })
+      j++
+    } else {
+      ops.push({ type: 'remove', text: a[i]!, oldLine: prefix + i + 1, newLine: prefix + j + 1 })
+      i++
+    }
+  }
+  for (let k = 0; k < suffix; k++) {
+    ops.push({
+      type: 'context',
+      text: before[before.length - suffix + k]!,
+      oldLine: before.length - suffix + k + 1,
+      newLine: after.length - suffix + k + 1,
+    })
+  }
+
+  // Group changes separated by at most 2 × context unchanged lines, then pad each group.
+  const changes = ops.flatMap((op, index) => (op.type === 'context' ? [] : [index]))
+  const groups: Array<[number, number]> = []
+  for (const index of changes) {
+    const last = groups.at(-1)
+    if (last !== undefined && index - last[1] <= context * 2 + 1) last[1] = index
+    else groups.push([index, index])
+  }
+  const hunks: DiffHunk[] = groups.map(([first, last]) => {
+    const from = Math.max(0, first - context)
+    const to = Math.min(ops.length - 1, last + context)
+    return {
+      oldStart: ops[from]!.oldLine,
+      newStart: ops[from]!.newLine,
+      lines: ops.slice(from, to + 1).map(({ type, text }) => ({ type, text })),
+    }
+  })
+
+  return {
+    added: ops.filter((op) => op.type === 'add').length,
+    removed: ops.filter((op) => op.type === 'remove').length,
+    hunks,
+  }
+}

package/devtools/server/line-map.ts

@@ -0,0 +1,63 @@
+import type { BeastSourceMap } from 'beast-tsrx'
+
+const BASE64 = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/'
+const DIGITS = new Map([...BASE64].map((char, index) => [char, index]))
+
+export interface LineMap {
+  tsrxToBtsx: Array<number | null>
+  btsxToTsrx: number[][]
+}
+
+/**
+ * Collapse Beast's node-level v3 source map into 1-based line correspondences
+ * in both directions. Beast emits a single source per map, so the source index
+ * is tracked only to keep the VLQ state machine correct.
+ */
+export function buildLineMap(map: BeastSourceMap, generatedLineCount: number, sourceLineCount: number): LineMap {
+  const tsrxToBtsx: Array<number | null> = Array.from({ length: generatedLineCount }, () => null)
+  const btsxToTsrx: number[][] = Array.from({ length: sourceLineCount }, () => [])
+
+  let sourceIndex = 0
+  let sourceLine = 0
+  let sourceColumn = 0
+  const lines = map.mappings.split(';')
+
+  for (let generated = 0; generated < lines.length; generated++) {
+    const line = lines[generated]
+    if (line === undefined || line === '') continue
+    for (const segment of line.split(',')) {
+      const fields = decodeVlq(segment)
+      if (fields.length < 4) continue
+      sourceIndex += fields[1]!
+      sourceLine += fields[2]!
+      sourceColumn += fields[3]!
+      if (sourceIndex !== 0 || generated >= generatedLineCount) continue
+      const btsxLine = sourceLine + 1
+      tsrxToBtsx[generated] ??= btsxLine
+      const targets = btsxToTsrx[sourceLine]
+      if (targets !== undefined && targets.at(-1) !== generated + 1) targets.push(generated + 1)
+    }
+  }
+
+  void sourceColumn
+  return { tsrxToBtsx, btsxToTsrx }
+}
+
+function decodeVlq(segment: string): number[] {
+  const values: number[] = []
+  let value = 0
+  let shift = 0
+  for (const char of segment) {
+    const digit = DIGITS.get(char)
+    if (digit === undefined) return values
+    value += (digit & 31) << shift
+    if (digit & 32) {
+      shift += 5
+      continue
+    }
+    values.push(value & 1 ? -(value >>> 1) : value >>> 1)
+    value = 0
+    shift = 0
+  }
+  return values
+}

package/devtools/server/octane-bundler.d.ts

@@ -0,0 +1,17 @@
+// `octane/compiler/bundler` ships without typings; this covers the subset the
+// devtools use to validate refactored sources.
+declare module 'octane/compiler/bundler' {
+  export interface OctaneTransformOptions {
+    environment?: 'client' | 'server'
+    hmr?: false | 'vite'
+    dev?: boolean
+    profile?: boolean
+    strong?: boolean
+  }
+
+  export interface OctaneBundlerCompiler {
+    transform(code: string, id: string, options?: OctaneTransformOptions): { code: string; map: unknown } | null
+  }
+
+  export function createOctaneCompiler(options?: OctaneTransformOptions & { root?: string }): OctaneBundlerCompiler
+}

package/devtools/server/project.ts

@@ -0,0 +1,369 @@
+import { createHash, randomUUID } from 'node:crypto'
+import { existsSync, readdirSync, readFileSync, statSync, unlinkSync, writeFileSync } from 'node:fs'
+import { join, relative, resolve, sep } from 'node:path'
+import {
+  BeastCompileError,
+  compileBeastResult,
+  componentNameFromPath,
+  formatDiagnostic,
+  type BeastDiagnostic,
+  type BeastDocument,
+  type SetupDeclaration,
+} from 'beast-tsrx'
+import { createOctaneCompiler } from 'octane/compiler/bundler'
+import type {
+  AnalyzerSettings,
+  ApplyRequest,
+  ApplyResult,
+  ComponentLocation,
+  DiagnosticInfo,
+  FileReport,
+  FileSummary,
+  HookBinding,
+  ProjectReport,
+  UndoResult,
+} from '../shared/types.js'
+import { analyzeDocument } from './analyze.js'
+import { diffLines } from './diff.js'
+import { buildLineMap } from './line-map.js'
+import { planRefactor, RefactorError, type FileChange } from './refactor.js'
+import { hookCall, topLevelDeclarations } from './source-scan.js'
+
+const IGNORED_DIRECTORIES = new Set(['.git', '.beast', 'node_modules', 'dist', 'build', 'coverage'])
+
+export interface ProjectOptions {
+  root: string
+  /** Directories, relative to root, searched recursively for `.btsx` files. */
+  include: readonly string[]
+  /** Absolute directories never listed (the overlay's own sources). */
+  exclude: readonly string[]
+}
+
+interface CompiledEntry {
+  mtimeMs: number
+  source: string
+  result: ReturnType<typeof compileBeastResult> | null
+  error: BeastDiagnostic | null
+}
+
+interface AppliedRefactor {
+  summary: string
+  changes: FileChange[]
+}
+
+/** How many applied refactors can still be undone. */
+const UNDO_LIMIT = 20
+
+/**
+ * Compiles project `.btsx` sources on demand for the overlay. Results are
+ * cached by modification time, so polling the API stays cheap.
+ */
+export class BeastProject {
+  readonly #options: ProjectOptions
+  readonly #cache = new Map<string, CompiledEntry>()
+  readonly #applied = new Map<string, AppliedRefactor>()
+  #octane: ReturnType<typeof createOctaneCompiler> | null = null
+
+  constructor(options: ProjectOptions) {
+    this.#options = options
+  }
+
+  report(settings: AnalyzerSettings): ProjectReport {
+    const files: FileSummary[] = []
+    const components: ComponentLocation[] = []
+    for (const absolutePath of this.#discover()) {
+      const path = this.#relative(absolutePath)
+      const entry = this.#compile(absolutePath)
+      const lines = entry.source.split('\n').length
+      if (entry.result === null) {
+        files.push({ path, lines, maxDepth: null, deepLines: 0, suggestions: 0, error: entry.error?.message ?? 'Compile failed' })
+        continue
+      }
+      const analysis = analyzeDocument(entry.result.ast, entry.source, componentNameFromPath(absolutePath), settings)
+      files.push({
+        path,
+        lines,
+        maxDepth: analysis.maxDepth,
+        deepLines: analysis.deepLines,
+        suggestions: analysis.suggestions.length,
+        error: null,
+      })
+      components.push(...componentLocations(entry.result.ast, absolutePath, path))
+    }
+    return { root: this.#options.root, settings, files, components }
+  }
+
+  file(path: string, settings: AnalyzerSettings): FileReport | null {
+    const absolutePath = this.resolve(path)
+    if (absolutePath === null) return null
+    const entry = this.#compile(absolutePath)
+    const relativePath = this.#relative(absolutePath)
+
+    if (entry.result === null) {
+      return {
+        path: relativePath,
+        absolutePath,
+        hash: contentHash(entry.source),
+        source: entry.source,
+        compiled: { ok: false, error: diagnosticInfo(entry.error!, entry.source) },
+        analysis: null,
+      }
+    }
+
+    const { code, map, ast, diagnostics } = entry.result
+    const sourceLines = entry.source.split('\n')
+    const lineMap = buildLineMap(map, code.split('\n').length, sourceLines.length)
+    // `~` continuation lines belong to the node header above them.
+    sourceLines.forEach((line, index) => {
+      if (index > 0 && line.trimStart().startsWith('~') && lineMap.btsxToTsrx[index]!.length === 0) {
+        lineMap.btsxToTsrx[index] = lineMap.btsxToTsrx[index - 1]!
+      }
+    })
+    return {
+      path: relativePath,
+      absolutePath,
+      hash: contentHash(entry.source),
+      source: entry.source,
+      compiled: {
+        ok: true,
+        tsrx: code,
+        ...lineMap,
+        diagnostics: diagnostics.map((diagnostic) => diagnosticInfo(diagnostic, entry.source)),
+      },
+      analysis: analyzeDocument(ast, entry.source, componentNameFromPath(absolutePath), settings),
+    }
+  }
+
+  /**
+   * Plan a refactor suggestion and, unless `dryRun`, write it. The suggestion
+   * is recomputed from the file on disk: the client names it but never supplies
+   * code, and every resulting file must compile through Beast and Octane
+   * before anything is written.
+   */
+  apply(request: ApplyRequest): ApplyResult {
+    const absolutePath = this.resolve(request.path)
+    if (absolutePath === null) throw new RefactorError('Unknown .btsx file.', 422)
+    this.invalidate(absolutePath)
+    const entry = this.#compile(absolutePath)
+    if (contentHash(entry.source) !== request.hash) {
+      throw new RefactorError('The file changed since it was analyzed. Review the refreshed suggestions and try again.', 409)
+    }
+    if (entry.result === null) throw new RefactorError('The file does not compile.', 422)
+
+    const analysis = analyzeDocument(entry.result.ast, entry.source, componentNameFromPath(absolutePath), request.settings)
+    const suggestion = analysis.suggestions.find((candidate) => candidate.id === request.suggestionId)
+    if (suggestion === undefined) throw new RefactorError('That suggestion no longer applies.', 409)
+
+    const plan = planRefactor({
+      absolutePath,
+      source: entry.source,
+      document: entry.result.ast,
+      suggestion,
+      target: request.target,
+      exists: existsSync,
+    })
+    for (const change of plan.changes) this.#validate(change)
+
+    const files = plan.changes.map((change) => ({
+      path: this.#relative(change.absolutePath),
+      action: change.before === null ? ('create' as const) : ('edit' as const),
+      ...diffLines(change.before === null ? [] : change.before.split('\n'), change.after.split('\n')),
+    }))
+    if (request.dryRun) return { undoId: null, component: plan.component, summary: plan.summary, files }
+
+    this.#write(plan.changes)
+    const undoId = randomUUID()
+    this.#applied.set(undoId, { summary: plan.summary, changes: plan.changes })
+    if (this.#applied.size > UNDO_LIMIT) this.#applied.delete(this.#applied.keys().next().value!)
+    return { undoId, component: plan.component, summary: plan.summary, files }
+  }
+
+  /** Restore the files an applied refactor touched, if nobody has edited them since. */
+  undo(id: string): UndoResult {
+    const applied = this.#applied.get(id)
+    if (applied === undefined) throw new RefactorError('Nothing to undo for that refactor.', 409)
+    for (const change of applied.changes) {
+      const current = existsSync(change.absolutePath) ? readFileSync(change.absolutePath, 'utf8') : null
+      if (current !== change.after) {
+        throw new RefactorError(`${this.#relative(change.absolutePath)} was edited after the refactor, so it was not undone.`, 409)
+      }
+    }
+    // Restore edited files first so nothing imports a file about to be removed.
+    const ordered = [...applied.changes].sort((a, b) => Number(a.before === null) - Number(b.before === null))
+    for (const change of ordered) {
+      if (change.before === null) unlinkSync(change.absolutePath)
+      else writeFileSync(change.absolutePath, change.before)
+      this.invalidate(change.absolutePath)
+    }
+    this.#applied.delete(id)
+    return { summary: `Undid: ${applied.summary}` }
+  }
+
+  #validate(change: FileChange): void {
+    const filename = change.absolutePath
+    const { code } = (() => {
+      try {
+        return compileBeastResult(change.after, { filename, componentName: componentNameFromPath(filename) })
+      } catch (error) {
+        const detail = error instanceof BeastCompileError ? formatDiagnostic(error.diagnostic, change.after) : String(error)
+        throw new RefactorError(`The refactored ${this.#relative(filename)} would not compile:\n${detail}`, 422)
+      }
+    })()
+    this.#octane ??= createOctaneCompiler({ root: this.#options.root, environment: 'client', hmr: false, dev: true })
+    try {
+      this.#octane.transform(code, filename.replace(/\.btsx$/, '.tsrx'), { environment: 'client', dev: true })
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error)
+      throw new RefactorError(`Octane rejected the refactored ${this.#relative(filename)}: ${message}`, 422)
+    }
+  }
+
+  #write(changes: readonly FileChange[]): void {
+    for (const change of changes) {
+      const current = existsSync(change.absolutePath) ? readFileSync(change.absolutePath, 'utf8') : null
+      if (current !== change.before) {
+        throw new RefactorError(`${this.#relative(change.absolutePath)} changed while the refactor was prepared.`, 409)
+      }
+    }
+    // New files first, so the edited importer never points at a missing module.
+    const ordered = [...changes].sort((a, b) => Number(b.before === null) - Number(a.before === null))
+    const written: FileChange[] = []
+    try {
+      for (const change of ordered) {
+        writeFileSync(change.absolutePath, change.after, change.before === null ? { flag: 'wx' } : {})
+        written.push(change)
+        this.invalidate(change.absolutePath)
+      }
+    } catch (error) {
+      for (const change of written.reverse()) {
+        if (change.before === null) unlinkSync(change.absolutePath)
+        else writeFileSync(change.absolutePath, change.before)
+      }
+      throw error
+    }
+  }
+
+  /** Resolve a client-supplied path to a project `.btsx` file, refusing anything else. */
+  resolve(path: string): string | null {
+    const absolutePath = resolve(this.#options.root, path)
+    const inRoot = absolutePath.startsWith(this.#options.root + sep)
+    const listed = this.#options.include.some((dir) => absolutePath.startsWith(resolve(this.#options.root, dir) + sep))
+    if (!inRoot || !listed || !absolutePath.endsWith('.btsx') || absolutePath.split(sep).includes('node_modules')) return null
+    try {
+      return statSync(absolutePath).isFile() ? absolutePath : null
+    } catch {
+      return null
+    }
+  }
+
+  invalidate(absolutePath: string): void {
+    this.#cache.delete(absolutePath)
+  }
+
+  #discover(): string[] {
+    const found: string[] = []
+    const walk = (dir: string) => {
+      let entries
+      try {
+        entries = readdirSync(dir, { withFileTypes: true })
+      } catch {
+        return
+      }
+      for (const entry of entries) {
+        const full = join(dir, entry.name)
+        if (entry.isDirectory()) {
+          if (!IGNORED_DIRECTORIES.has(entry.name) && !this.#options.exclude.includes(full)) walk(full)
+        } else if (entry.name.endsWith('.btsx')) {
+          found.push(full)
+        }
+      }
+    }
+    for (const dir of this.#options.include) walk(resolve(this.#options.root, dir))
+    return found.sort()
+  }
+
+  #compile(absolutePath: string): CompiledEntry {
+    const mtimeMs = statSync(absolutePath).mtimeMs
+    const cached = this.#cache.get(absolutePath)
+    if (cached !== undefined && cached.mtimeMs === mtimeMs) return cached
+
+    const source = readFileSync(absolutePath, 'utf8')
+    let entry: CompiledEntry
+    try {
+      const result = compileBeastResult(source, {
+        filename: this.#relative(absolutePath),
+        componentName: componentNameFromPath(absolutePath),
+      })
+      entry = { mtimeMs, source, result, error: null }
+    } catch (error) {
+      if (!(error instanceof BeastCompileError)) throw error
+      entry = { mtimeMs, source, result: null, error: error.diagnostic }
+    }
+    this.#cache.set(absolutePath, entry)
+    return entry
+  }
+
+  #relative(absolutePath: string): string {
+    return relative(this.#options.root, absolutePath).split(sep).join('/')
+  }
+}
+
+function contentHash(source: string): string {
+  return createHash('sha1').update(source).digest('hex').slice(0, 16)
+}
+
+function diagnosticInfo(diagnostic: BeastDiagnostic, source: string): DiagnosticInfo {
+  return {
+    code: diagnostic.code,
+    severity: diagnostic.severity,
+    message: diagnostic.message,
+    line: diagnostic.span.start.line,
+    column: diagnostic.span.start.column,
+    endLine: diagnostic.span.end.line,
+    endColumn: diagnostic.span.end.column,
+    ...(diagnostic.hint === undefined ? {} : { hint: diagnostic.hint }),
+    formatted: formatDiagnostic(diagnostic, source),
+  }
+}
+
+/** Where each component of a file is declared, plus its value hooks in call order. */
+function componentLocations(document: BeastDocument, absolutePath: string, path: string): ComponentLocation[] {
+  const locations: ComponentLocation[] = []
+  for (const declaration of document.declarations) {
+    if (declaration.kind !== 'component') continue
+    locations.push({
+      name: declaration.name,
+      path,
+      absolutePath,
+      line: declaration.span.start.line,
+      column: declaration.span.start.column,
+      local: true,
+      hooks: hookBindings(declaration.setup),
+    })
+  }
+  const root = document.children[0]
+  const topSetup = document.declarations.filter((d): d is SetupDeclaration => d.kind === 'setup')
+  locations.push({
+    name: componentNameFromPath(absolutePath),
+    path,
+    absolutePath,
+    line: root?.span.start.line ?? 1,
+    column: root?.span.start.column ?? 1,
+    local: false,
+    hooks: hookBindings(topSetup),
+  })
+  return locations
+}
+
+function hookBindings(setup: readonly SetupDeclaration[]): HookBinding[] {
+  const bindings: HookBinding[] = []
+  for (const declaration of setup) {
+    for (const { names, init, offset } of topLevelDeclarations(declaration.code)) {
+      const call = hookCall(init)
+      if (call === null) continue
+      const line = declaration.codeStart.line + declaration.code.slice(0, offset).split('\n').length - 1
+      bindings.push({ hook: call.hook, names, line })
+    }
+  }
+  return bindings
+}