niyogilabs/SkillSpectorWeb

Méthodologie de portage et de mise à niveau de SkillSpector vers le navigateur

Ce skill fournit des instructions pas à pas pour porter une nouvelle version du scanner de sécurité Python SkillSpector en une application web SkillSpectorWeb exécutée à 100 % dans le navigateur (WebAssembly / JavaScript).

---

🎯 Principes architecturaux

1. Exécution 100 % côté client dans le navigateur :

   • Le scanner doit s’exécuter entièrement dans le navigateur de l’utilisateur sans nécessiter de serveur backend.
   • Tout le contenu du dépôt GitHub est récupéré via les API REST de GitHub (api.github.com et raw.githubusercontent.com).

2. Isolation stricte des modules :

   • Moteur de scan principal (docs/js/skillspector-engine.js) : règles d’analyse statique traduites pures, correspondant à nodes/analyzers/ de Python.
   • Filtre de dépôt isolé (docs/js/repo-filter.js) : conserve le filtrage personnalisé des fichiers non liés au skill (README.md, CHANGELOG.md, .git/, etc.) séparé du code du scanner traduit.
   • Récupérateur GitHub (docs/js/github-fetcher.js) : gère l’analyse des URL, l’expansion des arborescences et le téléchargement par lots.

3. Support des dépôts multi-skills :

   • Doit refléter src/skillspector/multi_skill.py pour découvrir tous les skills imbriqués dans un dépôt (resources/skills/*.md, skills/*.md, agents/*.md).

4. Parité de licence et de version :

   • Conserver les numéros de version exacts (vX.Y.Z) correspondant à la version amont du SkillSpector Python.
   • Préserver le fichier LICENSE amont non modifié (Apache 2.0).

---

📋 Workflow de portage étape par étape

Phase 1 : Extraction des règles et de l’analyse AST

1. Inspecter les nouvelles règles d’analyse dans src/skillspector/nodes/analyzers/ en amont :
   • pattern_defaults.py (IDs de règles : P1-P8, E1-E5, PE1-PE3, SC1-SC7, EA1-EA4, OH1-OH3, MP1-MP3, TM1-TM4, RA1-RA2, TR1-TR3, MCP1).
2. Traduire les nouvelles regex Python et les vérifications AST en motifs JavaScript RegExp dans docs/js/skillspector-engine.js.
3. Mettre à jour les listes de catégories, les descriptions de règles, les explications et les guides de correction.

Phase 2 : Récupérateur GitHub et expansion de l’arborescence

1. S’assurer que docs/js/github-fetcher.js récupère les structures d’arborescence récursives via https://api.github.com/repos/{owner}/{repo}/git/trees/{branch}?recursive=1.
2. NE PAS limiter la récupération à de petites limites arbitraires de fichiers (utiliser un seuil élevé, jusqu’à 250 fichiers, pour supporter les grands dépôts multi-skills).
3. Utiliser le téléchargement par lots en parallèle (par exemple 10 fichiers par lot) avec des rappels de progression UI en direct (onProgress(current, total, filename)).

Phase 3 : Moteur de découverte multi-skills

1. Implémenter discoverSkills(filesMap) dans skillspector-engine.js.
2. Analyser le frontmatter YAML du Markdown (--- name: ... description: ... ---) pour tous les fichiers .md du dépôt.
3. Afficher une barre de sélection multi-skills dans index.html permettant aux utilisateurs de filtrer les résultats par skill découvert individuel ou d’inspecter le contexte complet du dépôt.

Phase 4 : Filtrage isolé des fichiers du dépôt

1. Garder docs/js/repo-filter.js complètement séparé du moteur de scan principal.
2. Fournir des cases à cocher dans index.html :
   • Omettre les documents standard du dépôt (README, CHANGELOG, LICENSE)
   • Omettre les métadonnées système (.git/, .github/, dotfiles)
3. Enregistrer les fichiers omis dans le Registre d’inspection en tant qu’éléments skipped avec des raisons explicites.

Phase 5 : Empaquetage GitHub Pages (docs/)

1. S’assurer que tous les actifs statiques du site web se trouvent dans SkillSpectorWeb/docs/ :
   • docs/index.html
   • docs/css/styles.css
   • docs/js/*.js
   • docs/CNAME (skillspector.niyogilabs.com)
   • docs/sitemap.xml
   • docs/robots.txt
   • docs/.nojekyll
   • docs/LICENSE
2. S’assurer que server.py sert le répertoire docs/ par défaut.

---

🧪 Liste de vérification

• python3 server.py 8090 se lance et sert proprement depuis docs/.
• L’analyse d’un dépôt multi-skills (par exemple Bhanunamikaze/Agentic-SEO-Skill) découvre tous les skills imbriqués.
• Le thème clair est défini par défaut ; le basculement vers le thème sombre fonctionne et persiste dans localStorage.
• Les points d’accès SEO (/sitemap.xml, /robots.txt, /CNAME) renvoient 200 OK.
• Les fonctions d’export SARIF 2.1.0, JSON et Markdown s’exécutent correctement.
• Le fichier LICENSE racine non modifié est intact.