Hi !

Last week I introduced you quickly to the project on which I have been working for several years SlimIO ❤️.

This time I'm going to tell you about a tool that we created with my team: PSP (Project Struct Policy). The goal of this project is to accurately verify the elements (files and directories) of a Node.js project by following a bunch of policies (Think ESLint for project structure and config checking).

Github: https://github.com/SlimIO/psp

Why ?

On SlimIO we are managing a lot of git repositories (105 repositories right now on the github organization and we didn't even start playing seriously 😏).

But very quickly several observations had to be drawn up:

• It was complicated to avoid mistakes (and even harder to identify them quickly).
• It is painful to maintain consistent and similar configurations across all "similar" projects kind.
• Hard to get back on old configuration choices and re-work/update them.
• Hard to transfer the responsibilities of updating the projects to less experimented developer (This is one of the hardest work... trust me.).

Over time, I therefore thought about creating a tool to respond to these issues. At the start I wanted to create a tool with editable/extendable policies to allow everybody to use the tool (but I never really managed to find an idea that suited me entirely.).

One day Nicolas MARTEAU started a internship with us 😘. I just decided to work with him to make a first prototype for SlimIO.. This is how the current psp project was born.

The story begin!

So to start the project i writted a complete Specification of what should be covered and what should not (sorry this is a french document) and Nicolas started a v1 implementation of the tool.

To summarize the Specification it separates projects in different "kinds":

• Addon (SlimIO addon project).
• N-API (Node.js N-API project).
• CLI (CLI project).
• Package (A classical npm/Node.js package).
• Service (API and things like that).
• Degraded (¯_(ツ)_/¯)

And depending on the kind the tool may check some given rules (or not). For example N-API projects has binding.gyp and given related dependencies and configurations to (pre-)build native code.

Everything else is about checking files and directories. The tool implement a little AST analysis to detect unused and/or missing dependencies too!

Then the tool throw warnings with different severities when something do not match what we expect:

• information (just highlight things and sometimes give recommandations).
• warning (It means that something is not matching our policies and the tool is requesting our attention on it... do not mean we have to absolutely fix it either).
• critical (psp exit the process with code 1. We must fix the issue).

Note: We run psp on our CI before running the project tests. So we get alerted if something goes wrong.

A real example

In SlimIO we updated all our projects to use a whitelist in package.json instead of the classical blacklist managed with the .npmignore file. At the time one of my junior co-worker helped me to handle all the project in the org.

While doing review of his work, I detected a typo, so I decided to update PSP to detect that kind of error automatically and throw a critical error (a critical error because here this means that there is missing files in published the npm tarball).

So i updated PSP and greenkeeper started to run every Travis CI. 🙈

At least 3-4 projects has been detected with typo in the "files" field of the package.json file.

What the CLI look like!

Because we have no more warnings on our projects (no joke ^^) i need to fuck up a project to generate warnings! 😆

Each warning can be completed with a description (only show when the --description or -d flag is set). Information warning are by default hidden (not that much useful right now^^).

API Mode

PSP is available as a package and can be executed with Node.js!

const psp = require("@slimio/psp");

async function main() {
    const { warn, crit } = await psp({
        forceMode: true, // <-- stay to true (else it will exit the process on CRIT).
        CWD: "./dir",
        isCLI: false, // <-- stay to false (else it will work as it was executed as a CLI).
        verbose: false
    });
    console.log(`warn => ${warn}, crit => ${crit}`);
}
main().catch(console.error);

We use this in a another SlimIO tool to be able to pull warnings stats of all local repositories (i will write an article on this tool soon too ^^).

Note that we are analyzing 82 projects in 800 milliseconds with no fucking code optimization 🚀!

Conclusion

This tool has brought us a lot, and I can say without hesitation that it allows us today to iterate and update our repositories with confidence (and I'm not worried of giving maintenance tasks to less experimented workers.).

This is by no mean a "perfect tool" but i'm confident on the fact that he is covering a lot of surface for us.

I am a little disappointed because the tool is currently only restricted to the SlimIO org (because we use a SlimIO manifest file).

And I just want to thank Nicolas for his amazing work and investment too. Even if he was only here for a stage, he did an incredible job!

What's next ?

The tool brought me a lot of experience, and vision on what should be done to improve the current implementation. This is why I want to refactor step by step the project to be able to use it outside of SlimIO (for summer 2021).

So don't hesitate to follow me... I will give an update on the tool before the end of 2020!

I really think that this tool will bring a lot to teams facing similar situations.

Thanks for reading me.

Best Regards,
Thomas