plugin-eco 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vincent Guiberteau
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,193 @@
+# plugin-eco
+
+Extension VSCode qui note la sobriété énergétique du code **Java, JavaScript et
+TypeScript**, avec une étiquette **A → E** empruntée au DPE des logements.
+
+L'analyse est statique et locale : le fichier est parsé à la frappe, les
+patterns énergivores connus sont signalés en annotations inline, et le score du
+fichier s'affiche dans la barre de statut.
+
+```
+┌─ éditeur ────────────────────────┐   ┌─ panneau ───────────────┐
+│ for (int i..) {                  │   │                         │
+│   for (int j..) {   <- imbriquée │   │         ┌───┐           │
+│     s += row[j];    <- String += │   │         │ E │  28/100   │
+│   }                              │   │         └───┘           │
+│ }                                │   │  4 hautes, 3 moyennes   │
+│                                  │   │  détail par ligne...    │
+└──────────────────────────────────┘   └─────────────────────────┘
+   barre de statut :  Éco: E
+```
+
+## Utilisation
+
+Ouvrir un fichier `.java` : l'analyse démarre seule. Trois commandes dans la
+palette (`Ctrl+Shift+P`) :
+
+| Commande | Effet |
+|---|---|
+| `Greencoding: Analyser le fichier` | relance l'analyse du fichier actif |
+| `Greencoding: Ouvrir le rapport détaillé` | ouvre le panneau, score + détail par ligne |
+| `Greencoding: Analyser tout le workspace` | scanne tous les `.java`, classe les fichiers du pire au meilleur |
+
+## Ce qui est détecté
+
+**Partout**, quel que soit le langage et l'endroit où le code s'exécute :
+
+| Pattern | Sévérité | Pénalité |
+|---|---|---|
+| Boucle imbriquée (complexité ≥ O(n²)) | haute | 15 |
+| Requête SQL sans `LIMIT` | haute | 12 |
+| `await` dans une boucle (appels enchaînés) | haute | 12 |
+| Regex recompilée en boucle | haute | 12 |
+
+**Côté serveur** — le coût est payé une fois, par le processus :
+
+| Pattern | Sévérité | Pénalité |
+|---|---|---|
+| I/O synchrone dans une fonction (`readFileSync`, `execSync`…) | haute | 12 |
+| I/O bloquant en boucle *(Java)* | haute | 12 |
+
+**Côté navigateur** — le coût est payé par l'appareil de chaque visiteur :
+
+| Pattern | Sévérité | Pénalité |
+|---|---|---|
+| `setInterval` de moins d'une seconde | haute | 12 |
+| `setInterval` plus espacé | moyenne | 7 |
+| Gestionnaire `scroll`/`resize`/`mousemove` sans limitation de débit | moyenne | 7 |
+| Import global d'une bibliothèque lourde (`lodash`, `moment`…) | moyenne | 7 |
+
+**Java seulement** : concaténation `+=` en boucle et `new` en boucle (moyenne, 7
+chacune). Ces deux règles ne s'appliquent **pas** à JavaScript, et c'est
+délibéré : V8 représente les concaténations par des *ropes*, et son
+ramasse-miettes générationnel rend l'allocation à courte durée de vie bon
+marché. Les signaler reviendrait à crier au loup sur du code sain.
+
+Une règle restreinte à un côté ne se déclenche **jamais** sur un fichier dont le
+contexte est indéterminé : sans certitude, le plugin se tait.
+
+Le score part de 100, chaque détection retranche sa pénalité, et le reste donne
+la lettre : **A** ≥ 90, **B** ≥ 75, **C** ≥ 55, **D** ≥ 35, **E** en dessous.
+
+Sur un scan de projet, la note globale est la moyenne des **seuls fichiers qui
+présentent au moins une alerte**. Les fichiers sains n'y entrent pas : sans
+cela, une poignée de modules utilitaires vides suffisait à ramener un projet à
+**A** en noyant le fichier qui pose réellement problème. Le nombre de fichiers
+concernés est affiché à côté de la lettre, et le pire d'entre eux est mis en
+avant — une lettre unique ne peut pas désigner un endroit.
+
+## Développement
+
+```bash
+npm install
+npm test
+```
+
+Puis `F5` dans VSCode pour lancer une fenêtre de test, et ouvrir un des exemples
+de `samples/` : `Example.java` déclenche les six règles Java, `example.ts` montre
+ce qui s'applique hors contexte connu, `example-web.tsx` déclenche les règles
+navigateur.
+
+Les tests utilisent `node:test`, sans dépendance supplémentaire, et s'exécutent
+sur le code compilé — donc sur ce qui part réellement dans l'extension. Ils
+couvrent chaque règle (déclenchement et non-déclenchement), les seuils de
+l'étiquette, et le résultat attendu sur `samples/Example.java`.
+
+Pour produire l'extension installable :
+
+```bash
+npm run package
+```
+
+## En intégration continue
+
+Le même moteur s'utilise en ligne de commande, pour bloquer une pipeline sous un
+seuil :
+
+```bash
+npx plugin-eco --min C src/
+```
+
+| | |
+|---|---|
+| `--format <text\|json>` | sortie lisible ou exploitable par un script |
+| `--min <A..E>` | note minimale acceptée |
+| code de sortie | `0` conforme · `1` sous le seuil · `2` erreur d'utilisation |
+
+Les positions sont rendues au format `fichier:ligne:colonne`, reconnu par la
+plupart des annotateurs de CI et cliquable dans un terminal.
+
+```yaml
+- name: Green check
+  run: npx plugin-eco --min C src/
+```
+
+L'analyse est strictement la même que dans l'éditeur : le CLI et l'extension
+partagent le parseur, les règles, l'inférence de contexte et le calcul de score.
+Un verdict qui différerait entre l'IDE et la pipeline ruinerait la confiance dans
+les deux.
+
+Le moteur s'utilise aussi comme bibliothèque, pour bâtir un rapport sur mesure :
+
+```js
+const { initParser, parse, collectFindings, computeScore, specFor } = require('plugin-eco');
+
+await initParser();
+const findings = collectFindings(parse(source, 'java').rootNode, specFor('java'));
+console.log(computeScore(findings).letter); // 'A' … 'E'
+```
+
+Ce point d'entrée n'expose que le moteur : le code d'intégration VSCode en est
+absent, et rien n'y importe `vscode`.
+
+## Choix techniques
+
+**Analyse statique d'abord, mesure à l'exécution ensuite.** Un profileur donne
+des watts réels mais impose de compiler et d'exécuter le code ; l'analyse
+statique tient sous la seconde et tourne pendant la frappe. C'est la condition
+pour que l'information arrive au moment où le développeur peut encore agir.
+
+**Une lettre plutôt que des watt-heures.** Une estimation en Wh sur du code non
+exécuté serait une fausse précision. La lettre assume ce qu'elle est — un
+classement relatif — et parle immédiatement. Les Wh et le CO₂ viendront avec la
+mesure à l'exécution, où ils seront mesurés plutôt que devinés.
+
+**tree-sitter plutôt qu'une analyse par expressions régulières.** Distinguer une
+boucle imbriquée d'une boucle voisine, ou un `new` dans une boucle d'un `new`
+juste après, demande un arbre syntaxique. tree-sitter le fournit pour de
+nombreux langages avec un seul parseur — Python reste à ajouter.
+
+**Un descripteur de langage, pas des conditions dispersées.** Tout ce qui varie
+d'un langage à l'autre — grammaire, noms de nœuds tree-sitter, règles
+applicables — est déclaré dans `src/languages.ts`. Les autres modules n'y font
+aucune référence. Ajouter Python revient à ajouter une entrée.
+
+**Le contexte d'exécution se déduit du code, pas des chemins.** Un `setInterval`
+de *polling* coûte une fois sur un serveur et autant de fois qu'il y a de
+visiteurs dans un navigateur : le plugin doit savoir où tourne le fichier. Il le
+lit dans l'arbre déjà parsé — imports de modules Node d'un côté, globales du
+navigateur et JSX de l'autre — plutôt que d'imposer une convention de dossiers,
+qui diffère à chaque framework. Seuls les indices francs comptent, et des
+indices contradictoires donnent « indéterminé » : en rendu côté serveur, un
+fichier tourne réellement des deux côtés.
+
+**Deux grammaires pour JS/TS, pas trois.** `tsx` est un sur-ensemble de
+`javascript` et couvre `.js`, `.jsx` et `.tsx`. Mais elle ne peut pas remplacer
+`typescript` pour les `.ts` : elle lit l'assertion `<Type>valeur` comme une
+ouverture JSX et perd la suite du fichier. Mesuré plutôt que supposé — un `.ts`
+contenant une telle assertion voyait ses trois boucles disparaître.
+
+**Les grammaires WASM sont copiées dans `out/` au build.** Une extension
+installée n'a pas les `node_modules` de développement sous la main : le script
+`scripts/copy-wasm.js` place le runtime tree-sitter et la grammaire Java dans
+`out/wasm/`, que l'extension résout depuis sa propre racine.
+
+## État
+
+Analyse statique de Java, JavaScript et TypeScript, avec un jeu de règles web
+qui distingue le code serveur du code navigateur. Python, la mesure à
+l'exécution (Wh et CO₂) et un portage IntelliJ sont les étapes suivantes.
+
+## Licence
+
+MIT — voir [LICENSE](LICENSE).

package/out/cli.d.ts

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+/**
+ * Point d'entrée en ligne de commande — le « green-check » de pipeline.
+ *
+ * Ce module n'importe **jamais** `vscode`, ni `extension.ts`, ni `webview.ts` :
+ * il partage avec l'extension le parseur, les règles, l'inférence de contexte
+ * et le calcul de score, rien d'autre. C'est cette frontière qui garantit que
+ * l'IDE et la CI rendent le même verdict sur le même fichier — deux moteurs
+ * divergents seraient pires que pas de CI du tout.
+ */
+import { Score, WorkspaceReport } from './types';
+export interface CliOptions {
+    paths: string[];
+    format: 'text' | 'json';
+    /** Note minimale acceptée ; en dessous, le processus sort en échec. */
+    min?: Score['letter'];
+    help: boolean;
+}
+export declare const USAGE: string;
+export declare function parseArgs(argv: string[]): CliOptions;
+/** La note atteint-elle le seuil ? 'A' est la meilleure. */
+export declare function meetsThreshold(letter: Score['letter'], min: Score['letter']): boolean;
+/** Parcourt récursivement un chemin et retourne les fichiers analysables. */
+export declare function collectPaths(target: string): string[];
+export declare function analyze(files: string[], baseDir: string): Promise<WorkspaceReport>;
+export declare function renderText(report: WorkspaceReport): string;
+export declare function renderJson(report: WorkspaceReport): string;
+export declare function main(argv: string[]): Promise<number>;

package/out/cli.js

@@ -0,0 +1,254 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * Point d'entrée en ligne de commande — le « green-check » de pipeline.
+ *
+ * Ce module n'importe **jamais** `vscode`, ni `extension.ts`, ni `webview.ts` :
+ * il partage avec l'extension le parseur, les règles, l'inférence de contexte
+ * et le calcul de score, rien d'autre. C'est cette frontière qui garantit que
+ * l'IDE et la CI rendent le même verdict sur le même fichier — deux moteurs
+ * divergents seraient pires que pas de CI du tout.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.USAGE = void 0;
+exports.parseArgs = parseArgs;
+exports.meetsThreshold = meetsThreshold;
+exports.collectPaths = collectPaths;
+exports.analyze = analyze;
+exports.renderText = renderText;
+exports.renderJson = renderJson;
+exports.main = main;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const parser_1 = require("./parser");
+const rules_1 = require("./rules");
+const scoring_1 = require("./scoring");
+const context_1 = require("./context");
+const languages_1 = require("./languages");
+const LETTERS = ['A', 'B', 'C', 'D', 'E'];
+exports.USAGE = `Usage : plugin-eco [options] [chemins...]
+
+Analyse la consommation énergétique estimée du code Java, JavaScript et
+TypeScript, et rend une étiquette A–E inspirée du DPE.
+
+Options
+  --format <text|json>   Format de sortie (défaut : text)
+  --min <A|B|C|D|E>      Note minimale acceptée ; en dessous, sortie en échec
+  -h, --help             Affiche cette aide
+
+Chemins
+  Fichiers ou dossiers à analyser. Défaut : le dossier courant.
+  Ignorés : ${languages_1.EXCLUDED_DIRS.join(', ')}
+
+Codes de sortie
+  0  analyse effectuée, note au-dessus du seuil (ou aucun seuil demandé)
+  1  note en dessous du seuil passé à --min
+  2  erreur d'utilisation ou d'exécution
+
+Exemple
+  plugin-eco --min C --format json src/ > rapport.json`;
+// ---------------------------------------------------------------------------
+// Analyse des arguments
+// ---------------------------------------------------------------------------
+function parseArgs(argv) {
+    const options = { paths: [], format: 'text', help: false };
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === '-h' || arg === '--help') {
+            options.help = true;
+        }
+        else if (arg === '--format') {
+            const value = argv[++i];
+            if (value !== 'text' && value !== 'json') {
+                throw new Error(`Format inconnu : ${value ?? '(manquant)'}. Attendu : text ou json.`);
+            }
+            options.format = value;
+        }
+        else if (arg === '--min') {
+            const value = (argv[++i] ?? '').toUpperCase();
+            if (!LETTERS.includes(value)) {
+                throw new Error(`Note minimale invalide : ${argv[i] ?? '(manquante)'}. Attendu : A, B, C, D ou E.`);
+            }
+            options.min = value;
+        }
+        else if (arg.startsWith('-')) {
+            throw new Error(`Option inconnue : ${arg}`);
+        }
+        else {
+            options.paths.push(arg);
+        }
+    }
+    if (options.paths.length === 0)
+        options.paths.push('.');
+    return options;
+}
+/** La note atteint-elle le seuil ? 'A' est la meilleure. */
+function meetsThreshold(letter, min) {
+    return LETTERS.indexOf(letter) <= LETTERS.indexOf(min);
+}
+// ---------------------------------------------------------------------------
+// Découverte des fichiers
+// ---------------------------------------------------------------------------
+/** Parcourt récursivement un chemin et retourne les fichiers analysables. */
+function collectPaths(target) {
+    let stat;
+    try {
+        stat = fs.statSync(target);
+    }
+    catch {
+        throw new Error(`Chemin introuvable : ${target}`);
+    }
+    if (stat.isFile())
+        return (0, languages_1.specForPath)(target) ? [target] : [];
+    return fs.readdirSync(target, { withFileTypes: true }).flatMap(entry => {
+        if (entry.isDirectory()) {
+            return languages_1.EXCLUDED_DIRS.includes(entry.name)
+                ? []
+                : collectPaths(path.join(target, entry.name));
+        }
+        const full = path.join(target, entry.name);
+        return (0, languages_1.specForPath)(full) ? [full] : [];
+    });
+}
+// ---------------------------------------------------------------------------
+// Analyse
+// ---------------------------------------------------------------------------
+async function analyze(files, baseDir) {
+    // La racine de l'extension contient out/wasm/, où vivent les grammaires.
+    await (0, parser_1.initParser)(path.join(__dirname, '..'));
+    const results = [];
+    for (const file of files) {
+        const spec = (0, languages_1.specForPath)(file);
+        if (!spec)
+            continue;
+        const code = fs.readFileSync(file, 'utf8');
+        const tree = (0, parser_1.parseWith)(code, spec);
+        const { context } = (0, context_1.inferContext)(tree.rootNode, spec);
+        const findings = (0, rules_1.collectFindings)(tree.rootNode, spec, context);
+        results.push({
+            uri: file,
+            fileName: path.relative(baseDir, file).split(path.sep).join('/') || path.basename(file),
+            score: (0, scoring_1.computeScore)(findings),
+            findings,
+        });
+    }
+    results.sort((a, b) => a.score.value - b.score.value);
+    return {
+        files: results,
+        global: (0, scoring_1.aggregateScore)(results.map(r => r.score)),
+        filesWithFindings: results.filter(r => r.findings.length > 0).length,
+        scannedAt: new Date().toISOString(),
+    };
+}
+// ---------------------------------------------------------------------------
+// Rendu
+// ---------------------------------------------------------------------------
+function renderText(report) {
+    const { global, files, filesWithFindings } = report;
+    const lines = [];
+    lines.push(`Éco : ${global.letter} ${global.value}/100`);
+    lines.push(`${global.findingCount.high} alerte(s) haute(s), ${global.findingCount.medium} moyenne(s) — ` +
+        `${filesWithFindings} fichier(s) concerné(s) sur ${files.length} analysé(s)`);
+    const concerned = files.filter(f => f.findings.length > 0);
+    if (concerned.length === 0) {
+        lines.push('\nAucune alerte.');
+        return lines.join('\n');
+    }
+    lines.push('\nFichiers, du pire au meilleur :');
+    for (const file of concerned) {
+        lines.push(`\n  ${file.score.letter} ${String(file.score.value).padStart(3)}  ${file.fileName}`);
+        for (const finding of file.findings) {
+            // Format « fichier:ligne:colonne », cliquable dans la plupart des terminaux
+            // et reconnu par les annotateurs de CI.
+            lines.push(`        ${file.fileName}:${finding.startLine + 1}:${finding.startChar + 1}  ` +
+                `[${finding.severity}] ${finding.message.split(' — ')[0]}`);
+        }
+    }
+    return lines.join('\n');
+}
+function renderJson(report) {
+    return JSON.stringify(report, null, 2);
+}
+// ---------------------------------------------------------------------------
+// Point d'entrée
+// ---------------------------------------------------------------------------
+async function main(argv) {
+    let options;
+    try {
+        options = parseArgs(argv);
+    }
+    catch (err) {
+        process.stderr.write(`${err.message}\n\n${exports.USAGE}\n`);
+        return 2;
+    }
+    if (options.help) {
+        process.stdout.write(`${exports.USAGE}\n`);
+        return 0;
+    }
+    let files;
+    try {
+        files = options.paths.flatMap(collectPaths);
+    }
+    catch (err) {
+        process.stderr.write(`${err.message}\n`);
+        return 2;
+    }
+    if (files.length === 0) {
+        // Sortie en succès : il n'y a rien à reprocher. Mais l'avertissement part
+        // sur stderr, car en CI c'est presque toujours une erreur de configuration.
+        process.stderr.write('Aucun fichier analysable trouvé.\n');
+        return 0;
+    }
+    let report;
+    try {
+        report = await analyze(files, process.cwd());
+    }
+    catch (err) {
+        process.stderr.write(`Échec de l'analyse : ${err.message}\n`);
+        return 2;
+    }
+    process.stdout.write((options.format === 'json' ? renderJson(report) : renderText(report)) + '\n');
+    if (options.min && !meetsThreshold(report.global.letter, options.min)) {
+        process.stderr.write(`\nNote ${report.global.letter} en dessous du seuil ${options.min}.\n`);
+        return 1;
+    }
+    return 0;
+}
+// Exécution directe uniquement : l'import depuis les tests ne déclenche rien.
+if (require.main === module) {
+    main(process.argv.slice(2)).then(code => { process.exitCode = code; }, err => { process.stderr.write(`Erreur inattendue : ${err}\n`); process.exitCode = 2; });
+}
+//# sourceMappingURL=cli.js.map

package/out/context.d.ts

@@ -0,0 +1,31 @@
+import Parser from 'web-tree-sitter';
+import { ExecutionContext } from './types';
+import { LanguageSpec } from './languages';
+/**
+ * Inférence du contexte d'exécution d'un fichier JavaScript / TypeScript.
+ *
+ * Le code se dénonce lui-même : un fichier qui importe `fs` tourne sur un
+ * serveur, un fichier qui touche `document` tourne dans un navigateur. On lit
+ * ces indices dans l'arbre déjà parsé — pas de convention de chemins, pas de
+ * configuration, pas de second moteur d'analyse.
+ *
+ * Deux principes :
+ *
+ *  - **Seuls les indices francs comptent.** `process.env` est injecté par les
+ *    bundlers côté client, `Buffer` est polyfillé : ils ne prouvent rien et sont
+ *    ignorés. Mieux vaut répondre « je ne sais pas » que se tromper.
+ *  - **Un conflit donne `unknown`.** Un composant qui lit `fs` *et* rend du JSX
+ *    tourne des deux côtés (rendu côté serveur). C'est un fait, pas une
+ *    ambiguïté à trancher au hasard.
+ */
+export interface ContextResult {
+    context: ExecutionContext;
+    /** Indices relevés, pour les tests et l'affichage. */
+    clientSignals: string[];
+    serverSignals: string[];
+}
+/**
+ * @param root racine de l'arbre syntaxique
+ * @param spec descripteur du langage ; un `fixedContext` court-circuite l'analyse
+ */
+export declare function inferContext(root: Parser.SyntaxNode, spec: LanguageSpec): ContextResult;