@tscircuit/schematic-trace-solver 0.0.86 → 0.0.88

package/lib/testing/PipelineStageDebugRunner.ts

@@ -0,0 +1,344 @@
+import { mkdir, writeFile } from "node:fs/promises"
+import path from "node:path"
+import {
+  getPngBufferFromGraphicsObject,
+  getSvgFromGraphicsObject,
+} from "graphics-debug"
+import type { GraphicsObject } from "graphics-debug"
+import { BaseSolver } from "lib/solvers/BaseSolver/BaseSolver"
+import { SchematicTracePipelineSolver } from "lib/solvers/SchematicTracePipelineSolver/SchematicTracePipelineSolver"
+
+type PipelineStepLike = {
+  solverName: string
+}
+
+type VisualizingSolver = {
+  visualize: () => GraphicsObject
+  iterations?: number
+  error?: string | null
+  solved?: boolean
+  failed?: boolean
+}
+
+export type PipelineStageArtifact = {
+  stageName: string
+  stageNumber: number
+  pngPath?: string
+  svgPath?: string
+  graphicsJsonPath?: string
+  stepPngPaths: string[]
+}
+
+export type PipelineStageDebugRunnerResult = {
+  outputDir: string
+  logsPath: string
+  stageArtifacts: PipelineStageArtifact[]
+  solved: boolean
+  failed: boolean
+  error: string | null
+  stoppedAfterStage: string | null
+}
+
+export class PipelineStageDebugRunner {
+  readonly pipelineSolver: SchematicTracePipelineSolver
+  readonly outputDir: string
+  readonly logsPath: string
+  readonly pngWidth: number
+  readonly pngHeight: number
+  readonly writePng: boolean
+  readonly writeSvg: boolean
+  readonly writeGraphicsJson: boolean
+  readonly writeStepPngs: boolean
+  readonly stopAfterStage?: string
+  readonly context: Record<string, string | number | boolean | null | undefined>
+  readonly onLog?: (line: string) => void
+
+  private readonly stageArtifacts: PipelineStageArtifact[] = []
+  private readonly capturedStageNumbers = new Set<number>()
+
+  constructor(opts: {
+    pipelineSolver: SchematicTracePipelineSolver
+    outputDir: string
+    pngWidth?: number
+    pngHeight?: number
+    writePng?: boolean
+    writeSvg?: boolean
+    writeGraphicsJson?: boolean
+    writeStepPngs?: boolean
+    stopAfterStage?: string
+    context?: Record<string, string | number | boolean | null | undefined>
+    onLog?: (line: string) => void
+  }) {
+    this.pipelineSolver = opts.pipelineSolver
+    this.outputDir = opts.outputDir
+    this.logsPath = path.join(this.outputDir, "logs.txt")
+    this.pngWidth = opts.pngWidth ?? 1536
+    this.pngHeight = opts.pngHeight ?? 1536
+    this.writePng = opts.writePng ?? true
+    this.writeSvg = opts.writeSvg ?? false
+    this.writeGraphicsJson = opts.writeGraphicsJson ?? true
+    this.writeStepPngs = opts.writeStepPngs ?? false
+    this.stopAfterStage = opts.stopAfterStage
+    this.context = opts.context ?? {}
+    this.onLog = opts.onLog
+  }
+
+  async run(): Promise<PipelineStageDebugRunnerResult> {
+    await mkdir(this.outputDir, { recursive: true })
+    await writeFile(this.logsPath, "")
+
+    await this.log(`startedAt=${new Date().toISOString()}`)
+    await this.log(`outputDir=${this.toDisplayPath(this.outputDir)}`)
+    await this.log(
+      `artifacts png=${this.writePng} svg=${this.writeSvg} graphicsJson=${this.writeGraphicsJson} stepPngs=${this.writeStepPngs} pngSize=${this.pngWidth}x${this.pngHeight}`,
+    )
+    for (const [key, value] of Object.entries(this.context)) {
+      await this.log(`${key}=${value ?? ""}`)
+    }
+
+    let stoppedAfterStage: string | null = null
+    let thrownError: unknown = null
+
+    await this.log(
+      this.getStageEnterLogLine(this.pipelineSolver.getCurrentPhase(), 0),
+    )
+
+    while (!this.pipelineSolver.solved && !this.pipelineSolver.failed) {
+      const previousStageNumber = this.pipelineSolver.currentPipelineStepIndex
+      const previousStageName = this.pipelineSolver.getCurrentPhase()
+
+      try {
+        this.pipelineSolver.step()
+      } catch (error) {
+        thrownError = error
+      }
+
+      const currentStageNumber = this.pipelineSolver.currentPipelineStepIndex
+      const currentStageName = this.pipelineSolver.getCurrentPhase()
+
+      if (
+        currentStageNumber !== previousStageNumber &&
+        previousStageName !== "none"
+      ) {
+        await this.captureStage(previousStageNumber)
+        if (
+          previousStageName === this.stopAfterStage ||
+          String(previousStageNumber + 1) === this.stopAfterStage
+        ) {
+          stoppedAfterStage = previousStageName
+          break
+        }
+      }
+
+      if (
+        currentStageNumber !== previousStageNumber &&
+        currentStageName !== "none"
+      ) {
+        await this.log(
+          this.getStageEnterLogLine(currentStageName, currentStageNumber),
+        )
+      }
+
+      if (thrownError) break
+    }
+
+    if (this.pipelineSolver.failed) {
+      await this.captureActiveStage()
+    }
+
+    if (thrownError) {
+      await this.log(`thrownError=${this.formatError(thrownError)}`)
+    }
+
+    const status = stoppedAfterStage
+      ? "stopped"
+      : this.pipelineSolver.solved
+        ? "solved"
+        : this.pipelineSolver.failed
+          ? "failed"
+          : "incomplete"
+
+    await this.log(
+      `completed status=${status} iterations=${this.pipelineSolver.iterations} error=${this.pipelineSolver.error ?? ""}`,
+    )
+
+    return {
+      outputDir: this.outputDir,
+      logsPath: this.logsPath,
+      stageArtifacts: [...this.stageArtifacts],
+      solved: this.pipelineSolver.solved,
+      failed: this.pipelineSolver.failed,
+      error:
+        this.pipelineSolver.error ??
+        (thrownError ? this.formatError(thrownError) : null),
+      stoppedAfterStage,
+    }
+  }
+
+  private async captureActiveStage() {
+    const stageNumber = this.pipelineSolver.currentPipelineStepIndex
+    if (this.pipelineSolver.getCurrentPhase() === "none") return
+    if (this.capturedStageNumbers.has(stageNumber)) return
+
+    await this.captureStage(stageNumber, this.pipelineSolver.activeSubSolver)
+  }
+
+  private async captureStage(stageNumber: number, solver?: BaseSolver | null) {
+    if (this.capturedStageNumbers.has(stageNumber)) return
+
+    const stageDef = this.getStageDef(stageNumber)
+    if (!stageDef) return
+
+    const stageSolver = solver ?? this.getStageSolver(stageDef.solverName)
+    if (!stageSolver) {
+      throw new Error(
+        `Unable to resolve solver for stage ${stageNumber + 1} "${stageDef.solverName}"`,
+      )
+    }
+
+    const basePath = path.join(
+      this.outputDir,
+      `stage${String(stageNumber + 1).padStart(2, "0")}-${this.getSafeStageName(stageDef.solverName)}`,
+    )
+    const pngPath = this.writePng ? `${basePath}.png` : undefined
+    const svgPath = this.writeSvg ? `${basePath}.svg` : undefined
+    const graphicsJsonPath = this.writeGraphicsJson
+      ? `${basePath}.graphics.json`
+      : undefined
+    const graphics = stageSolver.visualize()
+    const svg = getSvgFromGraphicsObject(graphics, { backgroundColor: "white" })
+
+    if (pngPath) {
+      await writeFile(pngPath, await this.renderGraphicsToPng(graphics))
+    }
+
+    const stepPngPaths =
+      this.writeStepPngs && this.writePng
+        ? await this.writeStepPngsForGraphics(basePath, graphics)
+        : []
+
+    if (svgPath) {
+      await writeFile(svgPath, svg)
+    }
+
+    if (graphicsJsonPath) {
+      await writeFile(graphicsJsonPath, JSON.stringify(graphics, null, 2))
+    }
+
+    this.capturedStageNumbers.add(stageNumber)
+    const artifact = {
+      stageName: stageDef.solverName,
+      stageNumber: stageNumber + 1,
+      pngPath,
+      svgPath,
+      graphicsJsonPath,
+      stepPngPaths,
+    } satisfies PipelineStageArtifact
+    this.stageArtifacts.push(artifact)
+
+    await this.log(
+      `captured stage=${artifact.stageNumber} name=${artifact.stageName} iterations=${stageSolver.iterations ?? 0} png=${pngPath ? this.toDisplayPath(pngPath) : ""} svg=${svgPath ? this.toDisplayPath(svgPath) : ""} steps=${stepPngPaths.length}`,
+    )
+  }
+
+  private async writeStepPngsForGraphics(
+    basePath: string,
+    graphics: GraphicsObject,
+  ): Promise<string[]> {
+    const stepPngPaths: string[] = []
+
+    for (const step of this.getObjectSteps(graphics)) {
+      const stepPngPath = `${basePath}.step-${step}.png`
+      await writeFile(
+        stepPngPath,
+        await this.renderGraphicsToPng(
+          this.filterGraphicsByStep(graphics, step),
+        ),
+      )
+      stepPngPaths.push(stepPngPath)
+    }
+
+    return stepPngPaths
+  }
+
+  private renderGraphicsToPng(graphics: GraphicsObject): Promise<Uint8Array> {
+    return getPngBufferFromGraphicsObject(graphics, {
+      backgroundColor: "white",
+      pngWidth: this.pngWidth,
+      pngHeight: this.pngHeight,
+    })
+  }
+
+  private getObjectSteps(graphics: GraphicsObject): number[] {
+    const steps = new Set<number>()
+    for (const objects of this.getGraphicsObjectArrays(graphics)) {
+      for (const object of objects) {
+        if (typeof object.step === "number") steps.add(object.step)
+      }
+    }
+
+    return [...steps].sort((a, b) => a - b)
+  }
+
+  private filterGraphicsByStep(
+    graphics: GraphicsObject,
+    step: number,
+  ): GraphicsObject {
+    const filtered: Record<string, unknown[]> = {}
+
+    for (const key of Object.keys(graphics)) {
+      const value = (graphics as Record<string, unknown>)[key]
+      filtered[key] = Array.isArray(value)
+        ? value.filter((object) => {
+            return (
+              typeof object === "object" &&
+              object !== null &&
+              (object as { step?: number }).step === step
+            )
+          })
+        : []
+    }
+
+    return filtered as GraphicsObject
+  }
+
+  private getGraphicsObjectArrays(
+    graphics: GraphicsObject,
+  ): Array<Array<{ step?: number }>> {
+    return Object.values(graphics).filter(Array.isArray) as Array<
+      Array<{ step?: number }>
+    >
+  }
+
+  private getStageDef(stageNumber: number): PipelineStepLike | undefined {
+    return this.pipelineSolver.pipelineDef[stageNumber]
+  }
+
+  private getStageSolver(stageName: string): VisualizingSolver | undefined {
+    return (
+      this.pipelineSolver as unknown as Record<string, VisualizingSolver>
+    )[stageName]
+  }
+
+  private getSafeStageName(stageName: string): string {
+    return stageName.replace(/[^a-zA-Z0-9._-]/g, "_")
+  }
+
+  private getStageEnterLogLine(stageName: string, stageNumber: number) {
+    return `enter stage=${stageNumber + 1} name=${stageName}`
+  }
+
+  private async log(line: string) {
+    await writeFile(this.logsPath, `${line}\n`, { flag: "a" })
+    this.onLog?.(line)
+  }
+
+  private toDisplayPath(filePath: string): string {
+    return path.relative(process.cwd(), filePath) || "."
+  }
+
+  private formatError(error: unknown) {
+    if (error instanceof Error) return `${error.name}: ${error.message}`
+    return String(error)
+  }
+}

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@tscircuit/schematic-trace-solver",
   "main": "dist/index.js",
-  "version": "0.0.86",
+  "version": "0.0.88",
   "type": "module",
   "scripts": {
     "start": "cosmos",
+    "debug:pipeline": "bun scripts/debug-pipeline-stages.ts",
     "build": "tsup-node lib/index.ts --format esm --dts",
     "format": "biome format --write .",
     "format:check": "biome format ."
@@ -18,7 +19,7 @@
     "calculate-elbow": "^0.0.12",
     "connectivity-map": "^1.0.0",
     "flatbush": "^4.5.0",
-    "graphics-debug": "^0.0.62",
+    "graphics-debug": "^0.0.96",
     "react": "^19.1.1",
     "react-cosmos": "^7.0.0",
     "react-cosmos-plugin-vite": "^7.0.0",

package/scripts/debug-pipeline-stages.ts

@@ -0,0 +1,146 @@
+import path from "node:path"
+import { readFile } from "node:fs/promises"
+import { SchematicTracePipelineSolver } from "lib/solvers/SchematicTracePipelineSolver/SchematicTracePipelineSolver"
+import { PipelineStageDebugRunner } from "lib/testing/PipelineStageDebugRunner"
+import type { InputProblem } from "lib/types/InputProblem"
+
+type Options = {
+  inputPath: string
+  outDir?: string
+  stopAfterStage?: string
+  pngSize: number
+  writePng: boolean
+  writeSvg: boolean
+  writeGraphicsJson: boolean
+  writeStepPngs: boolean
+}
+
+function printUsage() {
+  console.log(`Usage: bun run debug:pipeline <input.json> [options]
+
+Options:
+  --out <dir>              Output directory
+  --stop-after <stage|n>   Stop after a stage name or 1-based stage number
+  --png-size <px>          PNG width and height, default 1536
+  --no-png                 Do not write .png files
+  --svg                    Also write .svg files
+  --no-json                Do not write .graphics.json files
+  --step-pngs              Also write one PNG per graphics step when step values exist
+
+Example:
+  bun run debug:pipeline tests/assets/example01.json
+`)
+}
+
+function parseArgs(argv: string[]): Options {
+  const args = [...argv]
+  const inputPath = args.shift()
+  if (!inputPath || inputPath === "--help" || inputPath === "-h") {
+    printUsage()
+    process.exit(inputPath ? 0 : 1)
+  }
+
+  const options: Options = {
+    inputPath,
+    pngSize: 1536,
+    writePng: true,
+    writeSvg: false,
+    writeGraphicsJson: true,
+    writeStepPngs: false,
+  }
+
+  while (args.length > 0) {
+    const arg = args.shift()
+    if (arg === "--out") {
+      options.outDir = args.shift()
+      if (!options.outDir) throw new Error("--out requires a directory")
+      continue
+    }
+    if (arg === "--stop-after") {
+      options.stopAfterStage = args.shift()
+      if (!options.stopAfterStage) {
+        throw new Error("--stop-after requires a stage name or number")
+      }
+      continue
+    }
+    if (arg === "--png-size") {
+      const pngSize = Number(args.shift())
+      if (!Number.isFinite(pngSize) || pngSize <= 0) {
+        throw new Error("--png-size requires a positive number")
+      }
+      options.pngSize = pngSize
+      continue
+    }
+    if (arg === "--no-png") {
+      options.writePng = false
+      continue
+    }
+    if (arg === "--svg") {
+      options.writeSvg = true
+      continue
+    }
+    if (arg === "--no-json") {
+      options.writeGraphicsJson = false
+      continue
+    }
+    if (arg === "--step-pngs") {
+      options.writeStepPngs = true
+      continue
+    }
+    throw new Error(`Unknown argument: ${arg}`)
+  }
+
+  return options
+}
+
+function getDefaultOutputDir(inputPath: string) {
+  const basename = path.basename(inputPath).replace(/\.json$/i, "")
+  const timestamp = new Date().toISOString().replace(/[:.]/g, "-")
+  return path.resolve(
+    process.cwd(),
+    "tmp",
+    "schematic-trace-debug",
+    `${basename}-${timestamp}`,
+  )
+}
+
+const options = parseArgs(process.argv.slice(2))
+const inputPath = path.resolve(process.cwd(), options.inputPath)
+const inputProblem = JSON.parse(
+  await readFile(inputPath, "utf8"),
+) as InputProblem
+const outputDir = options.outDir
+  ? path.resolve(process.cwd(), options.outDir)
+  : getDefaultOutputDir(inputPath)
+const solver = new SchematicTracePipelineSolver(inputProblem)
+
+const runner = new PipelineStageDebugRunner({
+  pipelineSolver: solver,
+  outputDir,
+  writeGraphicsJson: options.writeGraphicsJson,
+  writePng: options.writePng,
+  writeSvg: options.writeSvg,
+  pngWidth: options.pngSize,
+  pngHeight: options.pngSize,
+  writeStepPngs: options.writeStepPngs,
+  stopAfterStage: options.stopAfterStage,
+  context: {
+    inputPath: path.relative(process.cwd(), inputPath),
+    stopAfterStage: options.stopAfterStage ?? "",
+    writePng: options.writePng,
+    writeSvg: options.writeSvg,
+    writeGraphicsJson: options.writeGraphicsJson,
+    writeStepPngs: options.writeStepPngs,
+    pngSize: options.pngSize,
+  },
+  onLog: (line) => console.log(line),
+})
+
+const result = await runner.run()
+
+console.log(`\nWrote ${result.stageArtifacts.length} stage artifact(s).`)
+console.log(`Output: ${path.relative(process.cwd(), result.outputDir)}`)
+
+if (result.error) {
+  process.exitCode = 1
+}

package/site/bug-reports/bug-report-20260706T220324Z.page.tsx

@@ -0,0 +1,4 @@
+import { PipelineDebugger } from "site/components/PipelineDebugger"
+import inputProblem from "../../tests/bug-reports/bug-report-20260706T220324Z/bug-report-20260706T220324Z.json"
+
+export default () => <PipelineDebugger inputProblem={inputProblem as any} />

package/site/bug-reports/bug-report-20260707T020342Z.page.tsx

@@ -0,0 +1,4 @@
+import { PipelineDebugger } from "site/components/PipelineDebugger"
+import inputProblem from "../../tests/bug-reports/bug-report-20260707T020342Z/bug-report-20260707T020342Z.json"
+
+export default () => <PipelineDebugger inputProblem={inputProblem as any} />

package/site/bug-reports/bug-report-20260707T092615Z.page.tsx

@@ -0,0 +1,4 @@
+import { PipelineDebugger } from "site/components/PipelineDebugger"
+import inputProblem from "../../tests/bug-reports/bug-report-20260707T092615Z/bug-report-20260707T092615Z.json"
+
+export default () => <PipelineDebugger inputProblem={inputProblem as any} />

package/site/bug-reports/bug-report-20260707T134549Z.page.tsx

@@ -0,0 +1,4 @@
+import { PipelineDebugger } from "site/components/PipelineDebugger"
+import inputProblem from "../../tests/bug-reports/bug-report-20260707T134549Z/bug-report-20260707T134549Z.json"
+
+export default () => <PipelineDebugger inputProblem={inputProblem as any} />

package/site/bug-reports/bug-report-20260707T134722Z.page.tsx

@@ -0,0 +1,4 @@
+import { PipelineDebugger } from "site/components/PipelineDebugger"
+import inputProblem from "../../tests/bug-reports/bug-report-20260707T134722Z/bug-report-20260707T134722Z.json"
+
+export default () => <PipelineDebugger inputProblem={inputProblem as any} />

package/site/bug-reports/bug-report-20260707T140410Z.page.tsx

@@ -0,0 +1,4 @@
+import { PipelineDebugger } from "site/components/PipelineDebugger"
+import inputProblem from "../../tests/bug-reports/bug-report-20260707T140410Z/bug-report-20260707T140410Z.json"
+
+export default () => <PipelineDebugger inputProblem={inputProblem as any} />

package/site/bug-reports/bug-report-20260707T141025Z.page.tsx

@@ -0,0 +1,4 @@
+import { PipelineDebugger } from "site/components/PipelineDebugger"
+import inputProblem from "../../tests/bug-reports/bug-report-20260707T141025Z/bug-report-20260707T141025Z.json"
+
+export default () => <PipelineDebugger inputProblem={inputProblem as any} />

package/site/bug-reports/bug-report-20260707T141421Z.page.tsx

@@ -0,0 +1,4 @@
+import { PipelineDebugger } from "site/components/PipelineDebugger"
+import inputProblem from "../../tests/bug-reports/bug-report-20260707T141421Z/bug-report-20260707T141421Z.json"
+
+export default () => <PipelineDebugger inputProblem={inputProblem as any} />