ruddle/README.md

# Ruddle

## wishlist

- Plugin architecture
- Recursive inheritance
- LSP integration via. yamlls


### Plugins

Using a plugins tag

```yaml
plugins:
  ruddle/some-domain@some-branch/commit/tag:
    some-specific-yaml-setting
  github.com/other_github_user/repo@latest: #for HEAD
    some-other-setting:
      - bla 
      - blabla
```

This should at runtime of ruddle `ruddle ls/x` do a fetch of these version, and if a latest try to see if there is a never commit available.

These will all live in a .ruddle/plugins directory in the root of the project beside the ruddle.yaml file.

### Recursive inheritance

These will be placed in a .ruddle in the parent directory, because of the recursive nature of these, it may have a structure like so

```
- .ruddle/
  - based/
    - ruddle-rust-plan/
      - ruddle.yaml
      - .ruddle/
        - based/
          - ruddle-base-plan/
            - ruddle.yaml
```

A maximum depth is specified as 5, but can be changed via the env variable `RUDDLE_MAX_DEPTH=10`, this is because we may or may not have a base case, if you still aren't done, we will throw an error, so that you're not missing some of your scripts.

We don't recommend going too overboard with this. Instead. The proposed setup is:

```
(service/lib/docs/cli) <- language specific plan <- organisation wide base plan
```

As such even if the examples above show a set of plan, these are meant to be forked and replaced with your specific repos. We don't expect your organisation to use our base plan, or even language plan. Instead we propose using plugins that is meant to be shared.

### LSP integration

LSP integration will in the beginning be controlled using yaml tags. Such that `# yaml-language-server: $schema=.ruddle/schema.json` these will be generated first time a new plugin is updated/added or downloaded. This should provide the best ease of use. It may also be possible in the future, combine these in a registry to get the full syntax of the curated plugins.

The LSP will be split into two parts.

- static
- dynamic

This is because the base file 'ruddle.yaml' will both contain static, and variable pulled from the internet.

I.e

Base variables such as:

- version
- name
- implicitProvider
- plugins

Will always be required.

Plugins items on the other hand can have user defined syntax, with a few required values.

The required values are 

- path
- dependsOn
- file
- etc.

The rest of the items will be based on syntax specified in the repository the file should be placed in `.schema/schema.json` from the root of the directory, this location cannot be modified.

The schema will be stitched like so:

```
{
  "$id": "https://example.com/schemas/plugins",
  "$schema": "https://json-schema.org/draft/2020-12/schema",

  "type": "object",
  "properties": {
    "ruddle/shell@latest": { "$ref": "/schemas/ruddle/shell@latest" },
    "ruddle/vars@main": { "$ref": "/schemas/ruddle/vars@main" }
  }
}
```

As seen from the above diagram, this can become quite extensive. However, because of the recursive nature of the program, the first run to generate the files, may take a small while, especially while cloning the repos and merging the sometimes, quite large files. At least the first time, the cli will also rebuild any plugins not already found on your system for use in the parsing procedure.

Each plugin will be executed given a parsed yaml tree of the plugin. A cli command will automatically be registered, and any of the commands sent after the primary command will be sent to the subcommand. 

I.e. 

`ruddle -h` will be handled by ruddle (also called ruddle core)
`ruddle actions build_server --arg 1 --arg 2 some` will be initially handle by ruddle, then forwarded to the registered subcommand for actions (registered by ruddle/actions), which now can take advantage of the full cli.

All plugins will be merged, recursively (left fold), but the top levels take precedence. If there is a version mismatch, it will choose the most specific version. 

`commit > tag > branch > main/head/latest`, you will get a warning if the versions with a mismatch

```
root            language     organisation
shell:abc123 <- shell:dev <- shell:latest
```

Now you will get a warning saying that dependencies aren't aligned.

### Todos

- [x] Proof of concepts
  - [x] Split rust bins, interfacing
  - [x] Plugins json schema
    - [x] Schema generation