Documentation API

Vue d'ensemble

Cette documentation couvre l'ensemble des interfaces publiques de Coclico. La version actuelle est 1.0.4. Les interfaces préfixées par I sont enregistrées dans le DI et peuvent être injectées dans n'importe quel service ou ViewModel.

• Namespace principal : Coclico.Services
• Modèles : Coclico.Models
• ViewModels : Coclico.ViewModels
• Framework : .NET 10, C# preview, WPF-UI 4.2

ICacheService

Cache in-memory thread-safe avec TTL par entrée. Implémenté par CacheService (singleton).

public interface ICacheService
{
    /// Récupère une valeur. Retourne null si absente ou expirée.
    T? Get<T>(string key);

    /// Stocke une valeur. ttl=null = pas d'expiration.
    void Set<T>(string key, T value, TimeSpan? ttl = null);

    /// Pattern TryGet pour éviter la double lookup.
    bool TryGet<T>(string key, out T? value);

    /// Invalide une entrée spécifique.
    void Invalidate(string key);

    /// Vide le cache entièrement.
    void InvalidateAll();
}

IDynamicTracer

Service de télémétrie temps-réel. Collecte CPU, RAM, réseau, disque. Implémenté par DynamicTracerService (singleton).

public interface IDynamicTracer
{
    /// Snapshot ponctuel de la télémétrie système.
    Task<TelemetrySnapshot> GetSnapshotAsync(CancellationToken ct = default);

    /// Remplit un buffer de télémétrie (évite les allocations — pour OptimizationEngine).
    Task FillTelemetryBufferAsync(Memory<byte> buffer, CancellationToken ct = default);

    /// Historique glissant (60 derniers snapshots).
    IReadOnlyList<TelemetrySnapshot> History { get; }
}

public record TelemetrySnapshot(
    DateTimeOffset Timestamp,
    double CpuPercent,       // 0.0 – 100.0
    long RamUsedMb,
    long RamTotalMb,
    double NetworkInKbps,
    double NetworkOutKbps
);

IRollbackService

Gestion des snapshots pour rollback des patches IA. Implémenté par RollbackService (singleton).

public interface IRollbackService
{
    /// Crée un snapshot du fichier avant modification. Retourne l'ID du snapshot.
    Task<Guid> CreateSnapshotAsync(string filePath, CancellationToken ct = default);

    /// Restaure un fichier depuis son snapshot.
    Task RestoreAsync(Guid snapshotId, CancellationToken ct = default);

    /// Liste tous les snapshots disponibles.
    IReadOnlyList<SnapshotInfo> GetSnapshots();

    /// Supprime les snapshots plus vieux que maxAge.
    Task PruneAsync(TimeSpan maxAge);
}

IOptimizationEngine

Moteur d'optimisation autonome (Phase 2). Exécute un cycle analyse/action toutes les 30 secondes. Implémenté par OptimizationEngineService.

public interface IOptimizationEngine
{
    /// Démarre la boucle d'optimisation en arrière-plan.
    Task StartAsync(CancellationToken ct);

    /// Arrête proprement la boucle.
    Task StopAsync();

    /// Résultat du dernier cycle d'optimisation.
    OptimizationResult? LastResult { get; }

    /// Événement déclenché après chaque cycle.
    event Action<OptimizationResult>? CycleCompleted;
}

IResourceAllocator

Allocation et libération des ressources système (threads, handles, mémoire poolée). Implémenté par ResourceAllocatorService.

public interface IResourceAllocator
{
    Task<ResourceHandle> AcquireAsync(ResourceType type, CancellationToken ct = default);
    void Release(ResourceHandle handle);
    ResourceUsageReport GetUsageReport();
}

ISourceAnalyzer

Analyse AST Roslyn du code source C# (Phase 3.3). Calcule complexité cyclomatique, métriques Halstead et Maintainability Index.

public interface ISourceAnalyzer
{
    /// Analyse complète d'un fichier C#.
    Task<AnalysisReport> AnalyzeFileAsync(string filePath, CancellationToken ct = default);

    /// Métriques d'une méthode spécifique.
    Task<MethodMetrics> GetMethodMetricsAsync(string filePath, string methodName);
}

public record MethodMetrics(
    string MethodName,
    int CyclomaticComplexity,   // CC — seuil d'alerte : > 10
    double HalsteadVolume,       // V = N × log2(n)
    double HalsteadDifficulty,   // D = (n1/2) × (N2/n2)
    double HalsteadEffort,       // E = D × V
    double MaintainabilityIndex  // MI = 171 - 5.2×ln(V) - 0.23×CC - 16.2×ln(LOC)
);

IAuditLog

Journal d'audit append-only en format NDJSON. Inclut le contexte de chaque décision IA. Implémenté par AuditLogService.

public interface IAuditLog
{
    /// Enregistre une entrée d'audit.
    Task WriteAsync(AuditEntry entry, CancellationToken ct = default);

    /// Écrit une décision IA avec son contexte complet.
    Task WriteAiDecisionAsync(AiDecisionContext ctx, CancellationToken ct = default);

    /// Supprime les entrées plus vieilles que retentionDays.
    Task PruneAsync(int retentionDays);
}

ISecurityPolicy

Politique de sécurité qui contrôle quelles opérations sont autorisées dans les Flow Chains. Les defaults hardcodés ne peuvent pas être supprimés par la configuration JSON.

public interface ISecurityPolicy
{
    /// Retourne true si le type de nœud est autorisé.
    bool IsNodeAllowed(NodeType nodeType);

    /// Retourne true si la clé de registre cible est autorisée.
    bool IsRegistryPathAllowed(string registryPath);

    /// Retourne true si le chemin de fichier est dans une zone autorisée.
    bool IsFilePathAllowed(string filePath);
}

AppSettings

Modèle de configuration principale. Géré par SettingsService, persisté dans %APPDATA%\Coclico\settings.json.

public class AppSettings
{
    // Général
    public string Language { get; set; } = "fr";
    public string Theme { get; set; } = "Dark";          // "Light" | "Dark" | "System"
    public string AccentColor { get; set; } = "#6366F1";   // Indigo par défaut
    public LaunchMode LaunchMode { get; set; } = LaunchMode.Manual;
    public bool MinimizeToTray { get; set; } = true;

    // Nettoyage
    public bool CleanWindowsTemp { get; set; } = true;
    public bool CleanBrowserCache { get; set; } = true;
    public bool CleanSystemLogs { get; set; } = false;
    public bool CleanRecycleBin { get; set; } = true;
    public bool CleanPrefetch { get; set; } = false;
    public bool CleanThumbnailCache { get; set; } = true;
    public bool CleanErrorReports { get; set; } = true;
    public bool CleanOldInstallers { get; set; } = false;
    public bool FlushDns { get; set; } = true;

    // IA & Audit
    public bool AutoPatcherAuditOnly { get; set; } = true;  // Défaut enterprise
    public int AuditRetentionDays { get; set; } = 90;
    public string AiModelPath { get; set; } = "";            // Vide = chemin par défaut
    public bool UseVulkanAcceleration { get; set; } = true;
}

public enum LaunchMode
{
    Manual,         // Lancement manuel uniquement
    WithWindows,    // Démarrage automatique avec Windows
    MinimizedTray   // Démarrage minimisé dans le tray
}

security-policy.json

Fichier de politique de sécurité chargé au démarrage. Les valeurs ci-dessous sont les défauts hardcodés (non-suppressibles) :

{
  "blockedNodeTypes": ["DeleteRegistryKey"],
  "blockedRegistryPaths": [
    "HKLM\\SYSTEM\\CurrentControlSet",
    "HKLM\\SOFTWARE\\Microsoft\\Windows NT\\CurrentVersion"
  ],
  "allowedFileWriteZones": [
    "%APPDATA%\\Coclico\\",
    "%TEMP%\\"
  ],
  "maxPipelineNodesPerRun": 200,
  "requireApprovalForRegistryWrite": true
}

NodeType — 28 types de nœuds

Enumération complète des types de nœuds disponibles dans les WorkflowPipeline :

ConditionOperator — 10 opérateurs

Opérateurs disponibles pour les conditions de nœuds (NodeCondition.Operator) :

OnErrorAction

Comportement d'un nœud en cas d'échec :

• ContinueNext (valeur par défaut) — L'erreur est loguée, l'exécution continue avec le nœud suivant.
• StopChain — L'exécution s'arrête immédiatement. Aucun nœud suivant ne s'exécute.
• SkipToEnd — Tous les nœuds intermédiaires sont ignorés. Seul le dernier nœud de la chaîne s'exécute.

Catégories Deep Clean — 10 catégories

Sources Applications — 8 sources

Structure des fichiers

Tous les fichiers de Coclico résident dans %APPDATA%\Coclico\ :

%APPDATA%\Coclico\
├── settings.json              # AppSettings sérialisées (JSON)
├── security-policy.json       # Politique de sécurité personnalisée
├── flow-chains\               # Définitions WorkflowPipeline
│   ├── {guid}.json            # Une chaîne par fichier
│   └── ...
├── audit\                     # Journal d'audit (IAuditLog)
│   ├── audit-2024-01.ndjson
│   └── ...
├── logs\                      # Logs Serilog (rolling daily, 14 jours)
│   ├── coclico-20240101.log
│   └── ...
├── rollback\                  # Snapshots IRollbackService
│   ├── {snapshotId}\
│   │   ├── metadata.json
│   │   └── original_file.bak
│   └── ...
└── resource\
    └── model\
        └── IA-support-chat.gguf  # Modèle LLM GGUF local

Format d'audit NDJSON

Chaque ligne du fichier d'audit est un objet JSON indépendant. Exemple d'entrée de décision IA :

{
  "timestamp": "2024-01-15T14:32:00.000Z",
  "type": "AiDecision",
  "level": "Info",
  "action": "PatchProposal",
  "userId": "local",
  "aiContext": {
    "model": "IA-support-chat.gguf",
    "promptHash": "sha256:a3f...",
    "responseTokens": 312,
    "latencyMs": 4820,
    "approved": false
  },
  "patch": {
    "proposalId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "targetFile": "Services/OptimizationEngineService.cs",
    "originalCC": 8,
    "patchedCC": 7,
    "validatedByDigitalTwin": true
  }
}