You change one line under .sdk/model, regenerate, and Book() is gone from the TypeScript and Go
clients. The model build exits 0 with no warning, and ts/src/entity/BookEntity.ts is still on
disk. Three stages ran between your edit and the output, apidef, aontu and jostraca, and any of
them could have dropped the entity.
What you get
You will end up with the stage that dropped the entity, the model line that switched it off, and a regenerated tree checked against the last good one. This is for you if your sdkgen output changed while the OpenAPI document stayed the same.
Short answer
In the project’s .sdk folder, run npx voxgig-model model/sdk.aontu -g debug and compare three
records with a good run: the entity files apidef writes to model/entity, the unified model in
model/sdk.json, and jostraca’s generate-entity log lines. The first record that differs names
the stage. npx aontu model why <path> model/sdk.aontu then names the file and line that set the
value. Fix that line, regenerate, and diff the file list against the last good tree.
You will need
Node 22 or later, git, and an sdkgen project scaffolded with npm create @voxgig/sdkgen from an
OpenAPI 3 document. The comparisons need Java for Swagger Codegen and Go 1.26 or later for ogen
v1.25.0, which declares that release in its go.mod. Verified 2026-11-22 against Node 22.23.5, @voxgig/sdkgen 4.44.3 from @voxgig/create-sdkgen 0.31.9,
ogen v1.25.0 and Swagger Codegen 3.0.85.
The project is the Bookshelf document with ts and go targets. record.sh in the sample ran
each generator once and kept its logs, with clock times, epoch milliseconds, and absolute paths
replaced by placeholders such as <work>. The commands below read those records.
Approaches compared
| Approach | When it fits | What it costs you | When to pick something else |
|---|---|---|---|
| git diff against the last good generation | Any generator, when the output is committed and a good run exists | It names the files that changed, but neither the stage nor the input that changed them | The diff is large and you need the cause |
ogen -loglevel debug | A Go client from ogen, where a skipped operation is the usual missing method | A skip is one INFO line, and an ogen.yml in the directory turns skipping on | You need the data a template received, which its flags do not print |
| sdkgen -g debug with aontu model why | An sdkgen project, where one unified model feeds every target | Three stages to compare by hand, and a dry run that still writes the SDK | Your generator reads the document directly, with no model to query |
| Swagger Codegen -DdebugOperations | You need the exact data each API template received | One parsed operation per path at INFO, and no template data until a logback.xml file opens one logger | You need to know why an operation is absent, which the dump shows only by omission |
Voxgig maintains sdkgen. It is the subject of this page, and the ogen and Swagger Codegen rows say
where each reads more directly.
A git diff works with any generator, but it shows only which files moved. ogen stops on input it
cannot generate unless a config file tells it to skip, and then one log line carries the cause.
Swagger Codegen’s operation dump is the most detailed record here once a logback.xml file lets it through,
and it is long. sdkgen alone has a model you can ask for provenance, at the price of three stages
to rule in or out first.
Plant a fault with a known cause
The sample debugs a fault planted on purpose, so the answer is known before the search starts.
record.sh scaffolds the project, generates it, commits the result, and appends one line to
.sdk/model/project.aontu, the overlay the scaffold never overwrites:
main: kit: entity: book: active: false
Then it runs the model build at debug level, inside .sdk, as you would:
npx voxgig-model model/sdk.aontu -g debug
-g takes trace, error, debug, info, warn or fatal. Call voxgig-model directly,
because npm run generate runs it twice and a flag after -- reaches only the second run.
Compare the three stages with the last good run
Each stage leaves a record you can read. apidef writes one .aontu file per entity to
.sdk/model/entity, aontu unifies everything into .sdk/model/sdk.json, and jostraca logs a
generate-entity line for each entity it builds in each target. stages.mjs reads all three
from both runs.
node stages.mjs
the change: main: kit: entity: book: active: false
stage 1, apidef writes model/entity/book.aontu
before: entity book, operations create list load remove update
after: the same file, byte for byte
stage 2, aontu unifies the model into model/sdk.json
before: main.kit.entity.book.active = true
after: main.kit.entity.book.active = false
stage 3, jostraca builds the targets (generate-entity lines in the debug log)
before: target go book, target ts book
after: none
output
before: Book( on 2 lines of ts/src/BookshelfSDK.ts, 3 of go/core/bookshelf_sdk.go; ts/src/entity holds BookEntity.ts
after: Book( on 0 lines of ts/src/BookshelfSDK.ts, 0 of go/core/bookshelf_sdk.go; ts/src/entity holds BookEntity.ts
pruned by the run after the change: .sdk/test/entity/book/BookTestData.json ts/test/definition.test.ts
Stage 1 is the same file in both runs, so apidef read the document as before. Stage 2 is where the
runs part. Stage 3 follows the model it was given, so jostraca is not the cause either. The output
lines show why the tree misled. The run deleted two files it no longer generated, with one INFO
line each, and kept BookEntity.ts, because sdkgen prunes a file only when the component that
owned it ran again.1 The scaffold’s check-drift.sh says regeneration never deletes such a
file, which holds here for the entity files alone.
Ask aontu which line set the value
The installed aontu has two why verbs. aontu why <pkg> explains a package dependency, and
aontu model why <path> <file> explains a value. The second evaluates the model sources without
running apidef or jostraca, and lists every contribution with its file, line, and column.
$.main.kit.entity.book.active = false
1. false <work>/bookshelf-sdk/.sdk/model/project.aontu:33:34
2. *true <work>/bookshelf-sdk/.sdk/node_modules/@voxgig/apidef/model/apidef.aontu:17:11 (spread)
The first contribution is the planted line. The second is apidef’s default, a *true that a
spread gives every entity, and a plain false overrides a default. The
aontu README lists model why beside model get as the
query and provenance verbs.
Fix the line and compare the file list
Delete the planted line, run npm run generate, stage the tree with git add --all, and compare it
with the last good commit by file list, using git diff --cached --name-status:
M .sdk/log/generated.jsonl
Book() is back in both targets, and so are the two pruned files. Only the generation log differs
from the good commit, on 4.44.3 and on 4.45.0, and npm run check-drift calls the committed fix
clean.
Stage before you compare when the bad run was committed. That commit deleted the two files from
the index, so git does not track the regenerated copies, and git diff --name-status against a
commit reads tracked paths only:
M .sdk/log/generated.jsonl
D .sdk/test/entity/book/BookTestData.json
D ts/test/definition.test.ts
git status lists the same two files as ??, which is the hint that the D lines are about the
index, not the disk.
Trace a missing method in two other generators
ogen has no unified model to query, so the sample gives it a missing method of its own: the
createBook request body moved to application/xml, which ogen v1.25.0 does not generate.
Swagger Codegen reads the Bookshelf document as it stands.
node dumps.mjs
ogen v1.25.0, -loglevel debug
api.json: exit 0, methods CreateBook DeleteBook GetBook ListBooks UpdateBook
api-xml.json, no ogen.yml: exit 1, Content type "application/xml" is unsupported.
api-xml.json, ogen.yml: exit 0, methods DeleteBook GetBook ListBooks UpdateBook
missing: CreateBook
Skipping operation at api-xml.json:32:15: unsupported content types: [application/xml]
Swagger Codegen 3.0.85, -DdebugOperations=true
default logging: 0 lines after the Operation info header, 5 processOperation dumps before it
with logback-debug.xml: 2075 lines after it, operations DefaultApi.createBook DefaultApi.deleteBook DefaultApi.getBook DefaultApi.listBooks DefaultApi.updateBook
With no config file, ogen stops, names the media type, and suggests
ignore_not_implemented. With an ogen.yml that sets it to
all, the run exits 0 without CreateBook, and one Skipping operation line points at the
post object on line 32 of the document. -loglevel debug adds Found config file, which
matters because ogen reads ogen.yml from the working directory unasked.2
Swagger Codegen’s -v turns on four debug properties, and -DdebugOperations=true turns on one.
At the default logging, that one prints each operation as parsed, the five processOperation
entries counted in the output, and the dump of what the templates received stops after its header line. In 3.0.85
that body goes to a logger held at info.3 A
logback.xml configuration file, passed with
-Dlogback.configurationFile, lets it through:
<logger name="io.swagger" level="info"/>
<logger name="io.swagger.v3.core.util.Json" level="debug"/>
The dump then lists every operation the API template received, each under its class name. A missing operation shows up as an absence from that list, which you find by comparing it with the document.
Check it worked
node --test debug.test.mjs
1..13
# tests 13
# suites 0
# pass 13
# fail 0
# cancelled 0
# skipped 0
# todo 0
Each test reads the records and fails if one of them changes. They cover where the runs part, the
line model why names, and the dry run’s writes and deletions on both releases. They also cover
the files the planted run pruned and the fix brought back, and the output of the other two
generators. One test feeds each reader empty or broken input and
expects a refusal.
When it goes wrong
The dry run writes the SDK. voxgig-model --help says that --dryrun performs “a dry run, where no
files are modified” and the scaffold’s check-drift.sh says how to “inspect a model with no side
effects” with npm run dry-generate. On 4.44.3 and 4.45.0 both leave model/sdk.json alone,
rewrite files under ts/ and go/, and delete the two files the planted model no longer generates:
[hh:mm:ss.mmm] INFO: model/sdkgen generate-prune removed .sdk/test/entity/book/BookTestData.json, no longer generated
[hh:mm:ss.mmm] INFO: model/sdkgen generate-prune removed ts/test/definition.test.ts, no longer generated
The model build keeps the flag to itself: sdkgen’s makeBuild takes the logger and the debug
level from the build, and not its dry-run flag. Commit before a debug run, and run git checkout -- . and git clean -fd afterwards.
The debug lines never appear. npm run generate -- -g debug passes the flag to the last command in
the script, voxgig-model test/test.aontu, so the SDK build logs at info. Run voxgig-model on
model/sdk.aontu yourself.
doctor reports a clean project. npx voxgig-sdkgen doctor printed .sdk matches the scaffold (0 additive, 0 customized) and exited 0 on the planted tree, and again after a hand edit to
ts/src/BookshelfSDK.ts. It compares .sdk with the scaffold, never the output with the model.
npm run check-drift regenerates from nothing and lists the stale BookEntity.ts as deleted.
When not to do this
Do not fix the output tree. The hand edit to BookshelfSDK.ts was gone after the next generate,
and doctor said nothing about it while it was there. Do not commit a generation you have not
compared with the last good one. The commit records the files the bad run pruned as deleted, and
every later comparison has to account for that.
Skip the three-stage comparison when the tree is small and committed. git diff finds a missing
class faster, and sdkgen’s model is then one more stage to rule out. ogen suits a reader who needs
only a Go client, because it reports a skipped operation against a line and column of the
document. Swagger Codegen suits a reader who must see the data each template received, which
sdkgen’s debug level does not print per template.
Related how-tos
Last verified
Verified 2026-11-22 against Node 22.23.5, @voxgig/create-sdkgen 0.31.9, @voxgig/sdkgen
4.44.3, @voxgig/apidef 8.32.4, @voxgig/model 12.0.2, aontu 0.76.3, jostraca 0.42.0, ogen
v1.25.0 built by Go 1.26, and Swagger Codegen 3.0.85 on OpenJDK 21. The dry run, the round trip and doctor ran
again on @voxgig/sdkgen 4.45.0. Each generator ran once, in record.sh, and every output block
is what the command preceding it printed from those records.
Footnotes
-
The rule is the comment on
pruneGenerated, at line 257 ofdist/helpers/generated.jsin 4.44.3 and 4.45.0. A run deletes each recorded file it did not emit “whose scope ran again” from the disk. It keeps a file “whose scope did not run (a target or a phase switched off)” as it is. The planted run logged nogenerate-entityline, so the components that write the entity’s own files never ran, and their files stayed. ↩︎ Back to text -
With no
--config,loadConfiginogen’s v1.25.0 command triesogen.yml,ogen.yaml,.ogen.ymland.ogen.yamlin the working directory, in that order, and reads the first it finds. Both the find and the absence of one are logged at debug level, so a run at the default level does not say which file, if any, it read. ↩︎ Back to text -
The chain has three links.
DefaultGeneratorlogs the header and hands the operations toJson.prettyPrint. In swagger-core 2.2.55, the release packed in the jar, that method passes the text toPrettyPrintHelper.emit, which logs it at debug on theJsonclass’s logger. Thelogback.xmlat the root of the 3.0.85 jar setsio.swaggertoinfo, although the CLI module’s own copy at the same tag saysdebug. ↩︎ Back to text