Oratrix v0.2 rfc

[aalykiot]

This discussion is about the v0.2 RFC of oratrix regarding the support for the reference architecture repo.

This RFC currently implements 3 commads.

init: creates a new oratrix config in the current directory

✨ Config file successfully initialized.

add: adds a new package (aka ref-arch module) to the oratrix config for monitoring

$ oratrix add express
✅ Oratrix config found.
✔ Category for the 'express' package? … web-framework
✔ NPM link for the 'express' package? … https://www.npmjs.com/package/express
📦 Adding new package express to config.
🎉 Updating config successfully.

verify: starts a pipeline of tests/validations on each oratrix package

✅ Oratrix config found.
🎉 No deprecated packages found.
🎉 All packages contain required fields.
🎉 All packages fields include allowed values.

An oratrix config example (.oratrixrc.json)

{
  "version": 1,
  "name": "ref-arch",
  "required": ["name", "description", "author", "license"],
  "allowed": {
    "license:": ["ISC", "Apache-2.0"]
  },
  "packages": [
    {
      "name": "express",
      "category": "web-framework",
      "npm": "https://www.npmjs.com/package/express"
    }
  ]
}

Given the above config, when you run the verify command oratrix will:

1. check if express is deprecated
2. check if the following fields ["name", "description", "author", "license"] are defined in express' package.json
3. check if the license specified is ISC or Apache-2.0

Output (looks better on terminal)

✅ Oratrix config found.
🎉 No deprecated packages found.
🎉 All packages contain required fields.
🚫 Some packages include non-allowed field values.
   ▶ package express includes non-allowed license: MIT

[aalykiot]

@helio-frota above is a small description of the v0.2 rfc

[aalykiot]

Yes, it comes as a blank object (when initialized) and the user has to specify the licenses that he/she wants to be allowed.

[helio-frota]

cool in that case it doesn't look confusing to me anymore, but will need docs to show how to config the file , makes sense ?

[aalykiot]

Yes, docs it's something we need to create when the features get stable

[helio-frota]

Can you please add more hints about the version: 1 sorry I don't remember the meaning.

[aalykiot]

That was introduced by wtrocki's PR and I left it there because in the future we may add features that require config "structure" updates, so with the version, we can keep track of that.

[helio-frota]

Separating here a new thread for the add command.

[helio-frota]

@alexalikiotis the add command seems to be pretty straightforward to me.

[helio-frota]

One thing that can be optimized in therms of usability is to have an online "database" for the category and npmjs urls
so that when adding a new package, oratrix can grab those information online.

But that probably needs to be a thing related to ref-architecture. What do you think ?

Because for example I added yargs and the category I added was CLI .

[helio-frota]

So that, oratrix will be tight with ref-architecture since it will grab those information from there.
But that is something we need the input from the others.

[aalykiot]

Yes, I agree, input from the others should help on this.

[helio-frota]

/cc @nodeshift/reference-architecture ^

[helio-frota]

About the verify command it seems to be working as expected.
I tested on license-reporter locally by making reference on the local oratrix branch:

✔ ~/code/nodeshift/license-reporter [eslint L|…1] 
10:50 $ node ../oratrix/dist/cli.js verify
✅ Oratrix config found.
🎉 No deprecated packages found.
🚫 Some packages missing required fields.
   ▶ package yargs is missing: author
🎉 All packages fields include allowed values.

(yeah I double checked, yargs is missing the author field)

[helio-frota]

@alexalikiotis we can consider that a non-breaking-CI right ? since we don't have control over 3rd dependencies.

[aalykiot]

It works!! 😂

[aalykiot]

I haven't decided yet what should / shouldn't break the CI yet. I guess this is why we have this discussion thread and RFC.

[helio-frota]

I think I don't have much to talk about the verify command. And I know that to add the licenses check on this pipeline of checks will be a good thing.

[mhdawson]

@lholmquist had added this file https://github.com/nodeshift/nodejs-reference-architecture/blob/master/modules-list.json which we keep updated with all of the modules recommended in the reference architecture. I guess that should likely be updated and renamed .oratrixrc.json.

I assume the ci would then just do a checkout and then run oratrix validate. right?

I terms of what to fail, I'm wondering if it should be configurable for each element to be warn, fail, ignore in terms of how each of the fields is treated. For example we might want to say to just warn if there is no name, but fail if there is no licence or it is not one of the ones that we've allowed.

In terms of the licences at some point later on we'll probably also want to override the default on a per module basis. If a module has a different licence we may decide that is ok for that one module but not necessarily include it as one of the acceptable licences.