# `appmap-ruby` architecture

## Official documentation

The official documentation for `appmap-ruby` is at [appland.com/docs](https://appland.com/docs/reference/appmap-ruby.html).

## Integration with appmap-js

Most of the analytics functionality for AppMap JSON is implemented in [appmap-js](https://github.com/applandinc/appmap-js/). In particular, `packages/cli`. `appmap-ruby` includes the source code and dependencies of `@appland/cli`. Check the [Rakefile](./Rakefile) for references to npm and/or yarn to see how the packaging works.

`appmap-ruby` executes command-line programs provdied by `@appland/cli`; it doesn't attempt to load a Node.js library in-process. `@appland/cli` commands are designed to produce clean output on stdout, which is obtained and processed by `appmap-ruby`.

## Swagger (OpenAPI) generation

`appmap-ruby` provides a [Rake task](./lib/appmap/swagger/rake_tasks.rb) to generate Swagger files from AppMaps. The majority of the Swagger is generated by calling out to `appmap-js swagger`. `appmap-ruby` makes it Ruby-friendly by wrapping it with Rake, and by adding doc strings to the Swagger by converting RDoc to HTML. It also post-processes the Swagger to remove volatile parameter examples, producing `openapi_stable.yml`. 

**Configuration**

The Swagger task supports [configuration settings](./lib/appmap/swagger/configuration.rb) via appmap.yml. Put the settings under the `swagger` key. 

The API version can also be specified explicitly in Ruby code, when the Rake task is defined:

```ruby
AppMap.configuration.swagger_config.project_version = \
  [ 
    'v',
    File.read(File.join(Rails.root, 'VERSION')).strip,
    '_',
    `git rev-parse --short HEAD`.strip
  ].join
```

**Note** From experience, it seems like almost all of the value of the Swagger gen is provided by openapi_stable. Therefore, in the future this may become the only output from the Rake task, and the RDoc to HTML functionality may be removed.

The package `appmap/swagger` is loaded automatically by `appmap`, when Rake is available in the bundle.

**Blogs and videos**

* [How to auto-generate detailed Swagger/OpenAPI for all your Rails routes (Dev.to)](https://dev.to/appland/how-to-auto-generate-swagger-openapi-doc-for-your-web-services-3npn)
* [Generate Swagger for your Rails project, with no code changes, in 2 ¹/₂ minutes](https://dev.to/appland/generate-swagger-for-your-rails-project-with-no-code-changes-in-2-minutes-3abj)

## Depends (incremental testing)

`appmap-ruby` provides a [Rake task](./lib/appmap/depends/rake_tasks.rb) to automatically run tests and update AppMaps as local source files and test files are modified. It leans heavily on the `depends` command provided by `@appland/cli`. To understand how the Rake tasks work, consider running `appmap-js depends` on your local AppMaps - you can `touch` source files to see the dependency detection in action.

However, computing which AppMaps need updating as a result of source files changes is only part of the story. `depends` also has to:

* Detect added, changed, and removed test files.
* Run the tests which are determined to be out of date.
* Update the AppMap index after updating the AppMaps.
* Remove any AppMaps which refer to tests that have been deleted.

Because `depends` has some complexity, there is an [API](./lib/appmap/depends/api.rb) module that implements key commands. To understand `depends` in further detail, after trying out the `@appland/cli` command, read this API.

The package `appmap/depends` is loaded automatically by `appmap`, when Rake is available in the bundle.

**Configuration**

The Depends task supports [configuration settings](./lib/appmap/depends/configuration.rb) via appmap.yml. Put the settings under the `depends` key. Some configuration settings for Depends are specified as fully-qualified method names (e.g. `Class::Name.method_name`). The Rake task definition code should ensure that the code for any customized methods is loaded and available. At the time of this writing, the primary reasons for overridding the default Depends behavior are:

* Inject custom environment variables into the test command.
* Override the default test command string.

There are separate settings for `rspec` and `minitest`.

**Blogs and videos**

* [July 2021 Roadmap](https://appland.com/videos/2021/07/01/appmap-july-2021-roadmap/)