logo

Nástroj SlimIO #1 – psp

Ahoj!

Minulý týden jsem vám v rychlosti představil projekt, na kterém pracuji již několik let SlimIO ❤️.

Tentokrát vám povím o nástroji, který jsme vytvořili s mým týmem:PSP (Project Struct Policy). Cílem tohoto projektu je přesně ověřit prvky (soubory a adresáře) projektu Node.js pomocí řady zásad (Think ESLint pro kontrolu struktury projektu a konfigurace).

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

Proč?

Na SlimIO spravujeme spoustu git repozitářů (105 repozitářů právě teď na organizaci github a ani jsme nezačali hrát vážně 😏).

Ale velmi rychle muselo být vypracováno několik pozorování:

  • Bylo složité vyhnout se chybám (a ještě těžší je rychle identifikovat).
  • Je bolestivé udržovat konzistentní a podobné konfigurace u všech typů „podobných“ projektů.
  • Je těžké se vrátit ke starým konfiguračním volbám a přepracovat je/aktualizovat.
  • Těžko přenést odpovědnost za aktualizaci projektů na méně zkušené vývojáře (toto je jedna z nejtěžších prací... věřte mi).

Postupem času jsem proto přemýšlel o vytvoření nástroje, jak na tyto problémy reagovat. Na začátku jsem chtěl vytvořit nástroj s upravitelnými/rozšiřitelnými politikami, které by umožnily používat tento nástroj každému (ale nikdy se mi nepodařilo najít nápad, který by mi úplně vyhovoval).

Jednoho dne u nás nastoupil na stáž Nicolas MARTEAU 😘. Právě jsem se rozhodl s ním spolupracovat na vytvoření prvního prototypu pro SlimIO. Tak se zrodil současný projekt psp.

Příběh začíná!

Abych mohl začít s projektem, napsal jsem úplnou specifikaci toho, co by mělo být pokryto a co by nemělo být (omlouvám se, že je to francouzský dokument) a Nicolas zahájil implementaci nástroje v1.

Abychom shrnuli specifikaci, rozděluje projekty na různé "druhy":

  • Addon (projekt doplňku SlimIO).
  • N-API (projekt N-API Node.js).
  • CLI (projekt CLI).
  • Balík (klasický balíček npm/Node.js).
  • Služba (API a podobné věci).
  • Degradováno (¯_(ツ)_/¯)

A v závislosti na druhu může nástroj zkontrolovat některá daná pravidla (nebo ne). Například projekty N-API mají bind.gyp a dané související závislosti a konfigurace pro (před)sestavení nativního kódu.

Vše ostatní je o kontrole souborů a adresářů. Nástroj implementuje malou analýzu AST, která také odhalí nepoužívané a/nebo chybějící závislosti!

Poté nástroj zobrazí varování s různou závažností, když něco neodpovídá tomu, co očekáváme:

  • informace (jen zvýrazněte věci a někdy dejte doporučení).
  • varování (Znamená to, že něco neodpovídá našim zásadám a nástroj si žádá naši pozornost... neznamená to, že to musíme absolutně opravit buď).
  • kritické (psp ukončí proces s kódem 1. Problém musíme vyřešit).

Skutečný příklad

Ve SlimIO jsme aktualizovali všechny naše projekty tak, aby používaly whitelist v package.json místo klasického blacklistu spravovaného pomocí .npmignore souboru . V té době mi jeden z mých mladších spolupracovníků pomohl zvládnout celý projekt v org.

Při kontrole jeho práce jsem zjistil překlep, a tak jsem se rozhodl aktualizovat PSP, aby tento druh chyby detekovalo automaticky a vyvolalo kritickou chybu (kritická chyba, protože zde to znamená, že v publikovaném tarballu npm chybí soubory).

Tak jsem aktualizoval PSP a greenkeeper začal spouštět každý Travis CI. 🙈

Byly zjištěny nejméně 3–4 projekty s překlepem v poli „files“ souboru package.json.

Jak vypadá CLI!

Protože na našich projektech už žádná varování nemáme (bez legrace ^^), musím projekt posrat, aby generoval varování! 😆

Každé varování může být doplněno popisem (zobrazí se pouze v případě, že je nastaven parametr --description nebo -d). Informační varování jsou ve výchozím nastavení skrytá (momentálně nejsou příliš užitečné^^).

Režim API

PSP je k dispozici jako balíček a lze jej spustit pomocí 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);

Používáme to v dalším nástroji SlimIO, abychom mohli stahovat statistiky varování všech místních úložišť (brzy o tomto nástroji napíšu článek ^^).

Závěr

Tento nástroj nám přinesl hodně a mohu bez váhání říci, že nám dnes umožňuje s jistotou iterovat a aktualizovat naše úložiště (a nebojím se, že bych úkoly údržby zadával méně experimentovaným pracovníkům).

V žádném případě to není "dokonalý nástroj", ale jsem si jistý, že pro nás pokrývá hodně povrchu.

Jsem trochu zklamaný, protože tento nástroj je v současné době omezen pouze na SlimIO org (protože používáme soubor manifestu SlimIO).

A také chci poděkovat Nicolasovi za jeho úžasnou práci a investici. I když tu byl jen na pódiu, odvedl neuvěřitelnou práci!

Co bude dál?

Tento nástroj mi přinesl mnoho zkušeností a vizi toho, co by se mělo udělat pro zlepšení současné implementace. To je důvod, proč chci projekt krok za krokem refaktorovat, abych jej mohl používat mimo SlimIO (pro léto 2021).

Neváhejte mě tedy sledovat... Do konce roku 2020 podám aktualizaci o nástroji!

Opravdu si myslím, že tento nástroj přinese hodně týmům, které čelí podobným situacím.

Děkuji, že jste si mě přečetli.

S pozdravem,
Tomáš