Exigences
Les commandes pour les exigences : baselines, validation, tickets, normes, spécifications et diagrammes.
Commandes : archec baseline · archec approve · archec approvals · archec issues · archec status · archec cert · archec qualify · archec polarion · archec reqif · archec doc · archec diagram
Sur cette page : En savoir plus sur ces commandes
| Commande | Ce qu’elle fait |
|---|---|
archec baseline <main.arche> [--name v1.0] [--sign [--key ~/.ssh/id_ed25519]] |
Fige les exigences (baselines/<name>.json) ; le linter marque ensuite comme suspects les liens vers une exigence reformulée. --sign : une signature SSH à côté (<name>.json.sig, ssh-keygen -Y sign, espace de noms arche-baseline) avec --key, sinon ARCHE_SIGNING_KEY, sinon le user.signingkey de git quand gpg.format vaut ssh. |
archec baseline <main.arche> --verify [name] |
La signature de chaque baseline (ou d’une seule) vérifiée par rapport à reviews/allowed_signers (le format allowed-signers de git : qa@example.com ssh-ed25519 AAAA…). Code de sortie 1 pour une signature invalide ou un signataire absent de la liste. |
archec approve [main.arche] <id…> --as <name> [--role <role>] [--code] |
La validation : enregistre dans reviews/approvals.yaml qui a approuvé chaque élément (une exigence, un cas, un plan de test, Car.brakes…), à quel titre, quand, et une empreinte de ce qu’il disait — pour une exigence, sa formulation telle qu’une baseline la garde (un changement de statut ou de responsable ne l’annule pas) ; pour un autre élément, sa déclaration sans ses commentaires ni sa mise en forme (pour une part, avec sa définition). Une ligne par approbation, triée, pour git. Approuver à nouveau remplace l’approbation de cette personne. --as prend par défaut le user.name de git ; le modèle, par défaut, est le main.arche du dossier courant. --code : le code d’une part à la place (Pump.ctrl) : une empreinte de chaque fichier que nomme sa source, périmée quand l’un d’eux change. archec debt compte les fichiers encore tels qu’ils ont été approuvés comme validés (dette de compréhension). |
archec approvals [main.arche] [--stale] [--json] |
Les approbations, chacune à jour, périmée (l’élément a changé depuis : approuvez-le à nouveau) ou disparue. --stale : seulement celles-là, code de sortie 1 s’il y en a une. archec cert montre qui a approuvé chaque exigence (une approbation périmée est un manque) et les signatures des baselines ; archec ci --require-approval échoue tant qu’une exigence n’a pas d’approbation à jour. |
archec changes <main.arche> [--since v1.0] [--json] |
Les exigences ajoutées, supprimées et modifiées depuis une baseline (la plus récente par défaut), et les liens suspects. |
archec issues sync [main.arche] [-o arche-out | --results test-results.json] [--only cases|requirements] [--dry-run] |
Un ticket dans Jira (REST v3), GitHub ou GitLab pour chaque cas que la dernière exécution donne en échec (.archec/test-results.json, tel que l’écrit archec test) et pour chaque exigence non vérifiée — rien ne la vérifie, ses cas ont échoué, ou aucun n’a tourné. La clé du ticket est écrite sur l’élément, à sa place parmi les propriétés : issue "CAR-128" (acme/car#7 sur GitHub et GitLab). Un élément qui en a déjà une voit son ticket mis à jour ; un élément dont le problème a disparu reçoit un commentaire et, sur GitHub et GitLab, son ticket est fermé (un workflow Jira appartient au projet). Le gestionnaire de tickets est défini dans issues.yaml à côté du modèle — tracker: jira|github|gitlab, url, project (la clé Jira, owner/repo, le chemin GitLab), issue-type, labels — ou par --tracker, --url, --project ; le jeton vient de l’environnement : JIRA_EMAIL + JIRA_API_TOKEN ou JIRA_TOKEN, GITHUB_TOKEN, GITLAB_TOKEN. Cette commande envoie du texte du modèle à l’extérieur (les identifiants, noms et textes de ces éléments), et seulement quand elle tourne ; --dry-run affiche les requêtes (sans le jeton), n’envoie rien et n’écrit rien. Hors ligne par défaut : archec config allow issues l’autorise à joindre le gestionnaire de tickets (ai-engineering.md). |
archec issues list [main.arche] [--json] |
Chaque exigence, plan et cas qui a un issue. |
archec polarion <workitems.json> [--project main.arche] [-o out.arche] [--config polarion.yaml] [--document "Name=ID"…] [--module text…] [--id puid] |
Les work items d’un projet Polarion, tirés d’un export JSON de son API REST, sous forme d’exigences — n’importe quel projet : les champs standard sont connus, un champ personnalisé est reconnu à son nom ou déclaré dans polarion.yaml, tout le reste est gardé en attr. Un lien entre eux dans un rôle de dérivation (parent, satisfies, refines…) devient derives, les autres attr polarion-links. Importer. |
archec polarion pull [main.arche] [-o out.arche] [--save workitems.json] [--url u] [--polarion-project P] [--query q] [--dry-run] |
La même chose, lue sur le serveur indiqué dans polarion.yaml (toutes les pages de la requête), avec le jeton POLARION_TOKEN de l’environnement ; les exigences sont écrites dans out: — une nouvelle récupération les réécrit. --dry-run : la requête, sans l’envoyer. Hors ligne par défaut : archec config allow polarion l’autorise à joindre le serveur (ai-engineering.md). |
archec reqif <main.arche> [-o out.reqif] [--document D] |
Les exigences en ReqIF 1.2 (DOORS, Polarion, Jama…). |
archec reqif <in.reqif> [-o out.arche] |
Les exigences d’un fichier ReqIF en arche-lang. |
archec doc <main.arche> [-o spec.tex|spec.html|spec.md] [--html|--md] [--no-diagrams] |
La spécification : en LaTeX, en une page web autonome, ou en Markdown. La page dessine chaque vue (un viewpoint avec des lignes include) et joue chaque scénario sur les blocs de son système (SVG, sans script) ; le Markdown les donne en Mermaid. --no-diagrams les omet. --provenance ajoute un chapitre sur qui a écrit le code (voir provenance). |
archec doc <main.arche> --template <file.docx|file.odt> [-o out.docx] |
Votre propre document Word (.docx, .dotx) ou LibreOffice (.odt, .ott), ses champs remplis à partir du modèle : {{ requirement REQ-1 .text }}, des boucles qui répètent des lignes de tableau ({{#each requirements where tag=safety}}…{{/each}}), {{#if}}, {{ count … }}, et {{ diagram Car }} pour le schéma de blocs d’un système (en SVG, avec un PNG pour les anciennes versions de Word). Un champ que Word a découpé en morceaux est lu en entier. Un champ qui ne peut pas être rempli est marqué dans le document et affiché ; le code de sortie est alors 1. Voir documents modèles ; la sortie est par défaut <template>-filled.docx. |
archec diagram <main.arche> [view] [--format mermaid|d2|svg] [-o file] [--md] [--auto] [--list] [--all -o dir] [--max-links N] |
Un diagramme sous forme de texte que d’autres outils dessinent, ou sous forme d’image : un système ou un composant (Car, Car.adcu) en organigramme, une machine à états (Car.adcu.states) en diagramme d’états, un scénario (emergency-stop, ou une seule séquence : emergency-stop.detect) en diagramme de séquence, une vue (braking, un viewpoint avec des lignes include) avec les blocs qu’elle retient. Mermaid par défaut (GitHub le dessine dans un README ou une pull request ; --md l’entoure de balises de code), D2, ou SVG disposé par ELK comme le dispose l’éditeur — un bloc garde la place qui lui a été donnée (at, une ligne canvas, ou main.layout.json à côté du modèle, où l’éditeur garde les places choisies à la souris dans une vue), --auto dispose tout. Le format suit aussi l’extension de -o (.mmd, .d2, .svg). --play (avec SVG) joue un scénario sur le schéma de blocs de son système : chaque étape éclaire ses deux blocs et le lien qui les relie, le message se déplaçant le long du lien, une étape toutes les 1,6 s, en SMIL — sans script, donc il se joue partout où une image s’affiche. --list liste les diagrammes, --all -o dir les écrit tous. --overlay provenance colore chaque bloc selon qui a écrit son code, --overlay debt selon sa dette de compréhension (voir provenance). --max-links N : un schéma de blocs dessine ses N liens les plus lourds, parmi ceux dont le libellé indique un poids (« 12 imports », « 3 calls » ; les autres sont tous dessinés) — le plus lourd de chaque bloc d’abord, pour qu’aucun ne reste isolé — et indique « +K weaker links not drawn » ; 30 par défaut pour un modèle écrit par archec recover (le prop recovered de son système), aucune limite sinon ; --max-links 0 les dessine tous. Code de sortie 2 quand le diagramme n’existe pas. |
archec qualify [--use check,gen-c|all] [--config qualify.yaml] [--asil A-D] [--dal A-E] [--standard iso26262|do330|both] [--results results.json | --no-run] [-o dir] [--html] [--repo dir] [--strict] [--list] |
Le dossier de qualification d’outil pour les fonctions d’archec sur lesquelles s’appuie un projet de sûreté. Il est tiré de l’auto-modèle (examples/arche-lang : les cas d’utilisation, les exigences sur archec qui les raffinent, les cas de test qui les vérifient), d’une exécution de ces tests (le résultat de chaque test, la version, le commit git, les empreintes de dist/, l’environnement) et des limites connues indiquées dans la documentation. Il contient la classification d’outil de l’ISO 26262-8 §11 (TI, TD, TCL par cas d’utilisation) et le rapport de qualification, les Tool Operational Requirements de la DO-330 avec leurs cas de vérification et leurs résultats, un index de configuration et les problèmes connus ; en Markdown, et aussi en HTML avec --html. --list liste les cas d’utilisation. TI2 et TD3, sauf si la configuration dit autre chose, avec vos justifications. Code de sortie 1 quand un test a échoué (--strict : ou quand une exigence n’est pas démontrée). Il appuie une qualification ; il ne certifie pas archec. Voir qualification. |
archec status [main.arche] [--req <ID>]… [--json] [--lenient] |
Chaque exigence : son texte, ce qui la satisfait (parts, fonctions, états, chaînes), où elle est construite (les genmaps d’archec gen : fichiers et plages de lignes), et chaque preuve qu’archec test, verify, timing, replay et live ont enregistrée dans .arche/evidence/ — son verdict, son type, son lieu et son âge, ou out of date avec ce qui a changé depuis (Thermostat.update changed, fw.bin changed). Une exigence sans preuve : rien ne la prouve. Une ligne de bilan à la fin. Code de sortie 1 quand une exigence échoue, est périmée ou n’est pas prouvée ; avec --lenient, seulement quand une exigence échoue. --json : le rapport. Au-dessus des preuves, l’échelon le plus haut de l’échelle de test qu’elle a atteint (highest rung renode (sim ✓, renode ✓, board –)), dès qu’un échelon au-dessus du simulateur a une preuve ; une ligne fix pour un cas qui prouve un correctif. Voir ce qui prouve chaque exigence. |
archec status [main.arche] --build [<trace>…] [--json] |
Le build que fait tourner une carte. Seule, la commande donne le build du modèle, build <fingerprint> <commit> — ce que dit un firmware généré avec --trace dans sa première ligne de trace (arche-trace 0 build <fingerprint> <commit>). Avec des traces : si le firmware qui les a écrites est le build de ce modèle. Code de sortie 0 si oui, 1 quand la carte fait tourner un build plus ancien (rebuild and flash), 2 quand une trace ne le dit pas. |
archec cert <main.arche> [--standard iso26262|do178c] [-o file.md] [--strict] |
La matrice de traçabilité qu’exige une norme de sûreté, en Markdown : les objectifs de sûreté avec leur ASIL (tiré de leurs dangers), les exigences avec leur ASIL ou leur DAL, ce dont elles dérivent, ce qui les satisfait et les vérifie, les éléments et le niveau qu’il leur faut ; puis les manques. archec check vérifie aussi les niveaux : une exigence garde le niveau de ce dont elle dérive, ou le décompose (asil "B(D)", dont la somme redonne celui du parent sur des éléments indépendants), et un élément est au niveau de ce qu’il satisfait. --strict : code de sortie 1 au premier manque. |
En savoir plus sur ces commandes#
La validation est gardée dans le dépôt : archec approve REQ-1 Car.brakes --as "A. Martin" --role safety
écrit une ligne par approbation dans reviews/approvals.yaml — l’élément, une empreinte de ce qu’il dit,
qui, quand. Quand l’élément change, son approbation est périmée (archec approvals --stale) ; archec cert
montre qui a approuvé chaque exigence, et archec ci --require-approval échoue tant qu’il en manque une.
archec baseline --sign signe une baseline avec une clé SSH (ssh-keygen -Y sign, comme le fait git),
et archec baseline --verify la vérifie par rapport à reviews/allowed_signers.
archec issues sync ouvre un ticket dans Jira, GitHub ou GitLab pour chaque cas en échec et chaque exigence
non vérifiée, et écrit sa clé sur l’élément (issue "CAR-128") ; l’exécution suivante le met à jour, ou le
commente et le ferme une fois le problème disparu. Le gestionnaire de tickets est indiqué dans issues.yaml,
le jeton vient de l’environnement, et --dry-run affiche les requêtes sans les envoyer.
archec diagram main.arche <view> écrit n’importe quel diagramme que montre l’éditeur — un système, un composant,
une machine à états, un scénario, une vue — en Mermaid (--md l’entoure de balises de code, pour un README ou une
pull request, où GitHub le dessine), en D2, ou en SVG disposé par ELK. Un viewpoint avec des lignes include/exclude
est une vue à part entière, une requête sur le modèle (include * -> adcu, exclude kind sensor) : le diagramme
reste juste quand le modèle change, et un terme qui ne correspond à rien donne un avertissement. --all -o docs/diagrams
les écrit tous. archec diagram main.arche emergency-stop --format svg --play joue un scénario sur les blocs de son
système, étape par étape, dans un SVG sans script ; archec doc --html met dans la page chaque vue et chaque scénario joué.