Dredd: Accept API Elements as input to avoid parsing

[XVincentX]

I'm working on a super secret integration of Dredd. Given I'm already parsing the ADF on my own, it would be really useful to reuse the current AST instead of make the library reparse the document again.

[XVincentX]

Given I hit a round issue number (600), this one will have top priority on the to do list.

[kylef]

This should be relatively easy to implement. Some pointers if anyone is interested in contributing a PR (providing the maintainers would accept).

• You can detect that it is a parse result JSON object (https://github.com/apiaryio/dredd-transactions/blob/7f6f62e65f562b2f4cdc737001ee526a29ab1d08/src/parse.coffee#L14) decardcain already returns for API Elements.

• When parse result, get the parse result using following:

  const result = fury.load(JSON.parse(source))
  

• This would replace the code at https://github.com/apiaryio/dredd-transactions/blob/7f6f62e65f562b2f4cdc737001ee526a29ab1d08/src/parse.coffee#L26 for API Elements.

[honzajavorek]

There are two things the Dredd Transactions library does. It parses the API description document and it compiles HTTP transactions from the parse result.

With time I'm filling with doubts whether it's the correct approach. It began with https://github.com/apiaryio/dredd-transactions/issues/27, continued with @netmilk's thoughts about Dredd being used also in other then CLI runtimes (such as browser, see also #704), and it boils down also to this particular issue.

Basically, I think it would be nice to have dredd-core (the closest current representation would be the Dredd class), which takes API Elements (parse result) and configuration as an input. The dredd CLI package (the closest current representation would be the DreddCommand class) or a wrapper for any other environment would be responsible for providing the inputs (parsing CLI arguments, parsing the API description document).

But that would mean parsing is responsibility of a different package then compilation of the HTTP transactions. That would mean current Dredd Transactions should be split. They should do just one "simple" thing. Take API Elements and compile the list of HTTP transactions.

What do you folks think of this? @XVincentX @kylef @michalholasek @netmilk

[michalholasek]

As @honzajavorek said, I think we could divide Dredd "ecosystem" to at least 5 modules / packages:

dredd-core - test runner
dredd-parser - description document parsing
dredd-transactions - transaction "compiler"
dredd-cli - command line interface
dredd-reporters - base, HTML, nyan, ...

[honzajavorek]

I'd remove most reporters in favor of TAP, actually: https://github.com/apiaryio/dredd/issues/341#issuecomment-293890205 So I'm not sure about the reporters package. I'd do dredd-hooks to contain the whole hook-handling beast. Also, for backward compatibility, I think it makes sense to keep Dredd's CLI as just dredd.

The parsing is just a couple of lines. I don't know if it even deserves it's own package. Honestly, it does three things:

1. Defaults unrecognizable API description formats to API Blueprint, with a warning (could this be a part of Fury.js, by an option? at the same time - it's quite specific to Dredd and its history)
2. Makes sure source maps are available - that's something the compilation can assert later (throwing error if source maps are not available in given API Elements) and ideally it wouldn't be needed at all after #227
3. Freezes the API Elements tree - that's something the compilation can do itself as a first thing

I think the parsing can be just part of the CLI package. If any other environment needs the parsing, it won't need the 1 and they can just call Fury.js with the source maps option (2).

[michalholasek]

I don't necessarily mean that dredd-core, dredd-parser, dredd-transactions etc. have to be individual repos and/or npm packages, on the contrary - I would like Dredd to be a monorepo.

[honzajavorek]

I would like Dredd to be a monorepo.

That's happening now. I'll perhaps bring attention of @artem-zakharchenko and @kylef to this issue as it documents our past musing on the topic.

Dredd Transactions should eventually become two packages within the monorepo (parsing and compilation), and with some additional decoupling Dredd, or pieces of Dredd, should be then able to consume API Elements directly.

[XVincentX]

👋

I'm still getting notifications on these :)