Preview a run without writing

Run the whole generator with control.dryrun so it reports what it would do and writes nothing.

Rendered from docs/how-to/preview-a-run.md in the generator repository — where a correction belongs, and where the test suite runs every example on this page or states why it does not.

control.dryrun guards every write while letting everything else happen. The decision tree runs, the result arrays fill in, the audit is recorded—and the filesystem is not touched, not even to create the .jostraca folder.

Set it on the generate() call. A global control is ignored, which is a defect worth knowing rather than a design.

import { existsSync } from 'node:fs'
import { Jostraca, Project, File, Content } from 'jostraca'

const jostraca = Jostraca()

const res = await jostraca.generate({
  folder: './out',
  control: { dryrun: true },
}, () => {
  Project({ folder: 'app' }, () => {
    File({ name: 'a.txt' }, () => Content('A\n'))
    File({ name: 'b.txt' }, () => Content('B\n'))
  })
})

console.log(JSON.stringify(res.files.written))
console.log('out exists:', existsSync('./out'))

["out/app/a.txt","out/app/b.txt"]
out exists: false

The report is the point: files.written names what a real run would write, so a wrapper command can print a plan and ask before doing it. The other arrays are filled in the same way, so a dry run over an existing tree shows which files would be merged and which would conflict.

For the narrower question “what changed since last time”, generate for real and read files.unchanged, which lists the files whose bytes were already correct.

Preview a run without writing

See also#