Lintorn

Sommaire

• Guide Rapide
• C'est quoi ?
• À quoi ça sert ?
• Pour quel projet ?
• Comment l'installer ?
• Comment s'en servir ?
• Les règles
• Ajouter ses outils
• Les commandes

C'est quoi ?

ATTENTION : Lintorn n'est pas encore stable à 100 % : il est jeune et n'a pas pu être testé sur tous les projets.

Lintorn n'est pas invasif : il ne lance rien dans ton projet sans ton accord.

Lintorn n'est pas qu'un linter. Avec ton accord, il installe aussi les outils d'audit utiles à ton projet (lintorn outils).

Il vérifie que la mémoire de ton agent IA dit encore la vérité sur ton code : les fichiers d'instructions à la racine du projet (CLAUDE.md, AGENTS.md, GEMINI.md, CONVENTIONS.md, .cursorrules… et tu peux en ajouter d'autres) et la mémoire que l'IA garde sur ta machine. Il les compare à la doc et au code du projet.

Un hook est à installer : il lance un scan rapide à chaque git push, et bloque le push si un contrôle bloquant est au rouge.

Il crée deux rapports, rapport.md et rapport.html. Ce sont les mêmes, mais le HTML est plus agréable à lire que le Markdown.

À quoi ça sert ?

Il te fait gagner du temps sur un gros projet. Comment, tu vas me dire ?

Il vérifie que ton agent IA ne code pas à partir d'une mémoire obsolète. Ton agent voit tout de suite qu'il fait une erreur et peut rectifier le tir. Tu liras souvent de ton agent : « Lintorn m'a rattrapé… donc je corrige… »

Si tu ne bosses pas avec une IA, il t'évite de te perdre dans ton projet : tu peux tenir ta documentation à jour sans revérifier toutes tes notes à la main.

Le rapport de Lintorn te dit où regarder et te donne les liens. Au passage, il vérifie que ton code respecte ce que dit ta doc, pour éviter les contradictions : ton code reste cohérent partout.

Lintorn te sert de béquille et de garde-fou au moment des git push, c'est là que le danger est le plus grand. Mais rassure-toi, tu peux aussi lancer un scan complet quand tu veux avec lintorn (voir Les commandes).

Pour quel projet ?

Pour l'instant, Lintorn a été testé en conditions réelles sur un projet Python avec Django, et TypeScript avec React et Vite. Des tests ont été faits sur d'autres langages, mais pas en conditions réelles.

Langages testés en conditions réelles :

• Python / Django
• TypeScript / React / Vite

Langages testés hors conditions réelles :

• Rust
• Go
• Ruby
• Elixir
• Java
• JavaScript
• PHP
• C# / .NET

À vous de jouer ! Tous les retours sont bons à prendre.

Comment l'installer ?

1. pipx install lintorn (pipx est recommandé !)
2. lintorn init ▶ Voir l'animation

Lintorn scanne ton projet, détecte les langages utilisés et écrit sa configuration. lintorn outils installe ensuite les bons outils pour ces langages. Et voilà : Lintorn est installé à la racine de ton projet, dans .lintorn/. Maintenant, il faut l'activer ! Comment s'en servir ?

Comment s'en servir ?

lintorn init a créé un dossier .lintorn/ (▶ voir l'animation).

1. config.toml : la configuration. Les contrôles qui lancent ton code, ouvrent ta base de données ou sortent sur internet sont sur false : à toi de les activer ou non (▶ voir l'exemple).
2. Active les contrôles que tu veux en remplaçant false par true. Tu peux aussi ajouter tes propres outils (voir Ajouter ses outils).
3. regles.toml : c'est là que tu mets tes règles maison (aide-toi d'un LLM pour gagner du temps). C'est le cœur de Lintorn : c'est ce fichier qui t'empêche de reculer dans ton projet. Va voir Les règles pour plus de détails.
4. Le hook : active-le avec lintorn hook. À chaque git push, il lancera lintorn rapide.
5. L'accord : lance lintorn une fois dans un terminal et réponds o à sa question (ou tape lintorn confiance). Sans cet accord, le hook ne lance aucun outil, et il te le dit : « Push autorisé SANS vérification complète ».

lintorn rapide : lance un scan sans les outils lents (vulture, pip-audit, npm audit, OSV-Scanner). C'est lui que le hook lance à chaque git push.

lintorn : lance tous les outils. Ça peut prendre un peu de temps, mais il est recommandé de le lancer de temps en temps. Le rapport de lintorn rapide t'indique depuis combien de temps le scan complet n'a pas été fait.

Les règles, le cœur de Lintorn

C'est ici que ça devient cool ! Tu y mets tes propres règles pour que Lintorn suive le bon chemin, car aucun outil n'est capable de deviner à ta place ce que tu veux. Je te recommande fortement l'aide d'une IA à ce moment-là : c'est assez long à écrire, et un LLM te le fera en quelques minutes. À toi de vérifier ensuite que ton LLM ne s'est pas trompé. Une fois tes règles en place, plus aucune erreur n'est muette : Lintorn te le dira au prochain git push ou au prochain lintorn.

Exemple de règle, dans .lintorn/regles.toml :

[[regles]]
nom = "Pas de print() oublie"
regle = "on n'imprime pas de debogage dans le code livre"
racine = "src"
suffixes = [".py"]
motif = '^\s*print\('
bloquant = true

Ajouter ses outils

Dans config.toml, une section [[commandes]] te permet d'ajouter tes propres outils : un outil que ton projet utilise déjà (mypy, eslint…) ou un petit script à toi. Tu y écris la commande, le dossier d'où la lancer, et si le contrôle est bloquant ou non (▶ voir l'animation). Tu enregistres, et au prochain lintorn, ton outil tourne avec les autres et affiche sa ligne dans le rapport.

La première fois, Lintorn te demande ton accord avant de le lancer. Et si le script de ton outil change ensuite, il te le redemande, en te disant quel fichier a été modifié.

Exemple dans .lintorn/config.toml :

[[commandes]]
cle      = "mypy"
titre    = "Types (mypy)"
cmd      = ["{python}", "-m", "mypy", "."]
cwd      = "."
bloquant = false

{python} désigne le Python de ton projet (son venv). Écris-le plutôt que python tout court : sinon, quand le hook est lancé depuis VS Code sans ton venv activé, l'outil serait introuvable. Et l'outil (ici mypy) doit être installé dans ce venv.

---

Pour l'anecdote : le projet Lintorn est surveillé par Lintorn lui-même.

---

Les commandes

USAGE
    lintorn                      audit complet
    lintorn rapide               sans les outils lents (ce que lance le hook)
    lintorn doc                  uniquement : la documentation ment-elle ?
    lintorn --fichiers a.py b.ts + un focus sur ces fichiers

MISE EN PLACE
    lintorn init                 génère .lintorn/config.toml pour ce projet
    lintorn regles               prépare un [[regles]] par règle de ta doc
                                 qui n'a pas encore de contrôle
    lintorn hook                 installe le hook pre-push
    lintorn confiance            autorise Lintorn à lancer ses outils dans ce
                                 projet (il le demande de lui-même, une fois)
    lintorn outils               regarde ce que contient le projet, installe
                                 les outils qui s'y appliquent et propose
                                 d'activer ses audits, un par un

SÉCURITÉ
    lintorn pip-audit               ce que pip-audit propose (simulation)
    lintorn pip-audit --appliquer   installe et repingle vraiment

DIVERS
    lintorn guide                la notice : à quoi ça sert, comment lire
                                 un rapport, quels fichiers
    lintorn version              la version installée
    lintorn help                 cette aide, dans le terminal

Guide Rapide

Chaque étape en animation. Clique sur celle qui t'intéresse dans le texte, ou regarde-les dans l'ordre.

0. Lintorn avant lintorn init

Tape lintorn : il lance son audit même sans configuration, et te propose de lancer lintorn init.

1. Installer

lintorn init crée le dossier .lintorn/.

2. Le dossier .lintorn/

Ce que lintorn init a créé, dans VS Code.

3. Activer un contrôle

Passer un contrôle de false à true dans config.toml, puis relancer.

4. Installer les outils selon le langage

lintorn outils scanne ton projet et installe les bons outils d'audit selon ses langages.

5. Ajouter ton outil (optionnel)

Un bloc [[commandes]], et ton outil apparaît dans le rapport.

6. Écrire une règle (le cœur)

Une règle dans regles.toml, et Lintorn trouve ce qui l'enfreint. L'IA est parfaite pour écrire les règles.

7. Un git push vérifié

Un push propre passe, un push qui enfreint une règle est arrêté.

7.1 Un git push validé

7.2 Un git push bloqué

8. Premier lancement

Tape lintorn pour la première fois : il te demande ton accord avant de lancer ses outils.

9. Les rapports (.md et .html)

9.1 .lintorn/rapport.md : le rapport en Markdown, identique au HTML

9.2 .lintorn/rapport.html : à ouvrir dans le navigateur, plus agréable à lire

---

C'est la fin !

J'espère que ce guide est assez clair.

Une question, un bug ? Ouvre un ticket sur GitLab.

Tu ne seras plus jamais pris de court sur ton projet. Lintorn est une aide précieuse, mais attention : il peut avoir des bugs ! Sois attentif.

Je suis seul sur ce projet. Sois indulgent.