agentic-api 1.0.5 → 2.0.26

package/dist/src/rules/types.helpers.d.ts

@@ -0,0 +1,132 @@
+import { SimpleGit } from "simple-git";
+import { ConcurrencyOptions, GitCommitHistory, PRInfo, PRMergeResult, PRMetadata, RetryResult, RulesGitConfig, RuleUser } from "./types";
+/**
+ * Interface pour les opérations Git de base
+ * Permet de mocker facilement les opérations Git pour les tests
+ */
+export interface IGitOperations {
+    /**
+     * Récupère le contenu d'un fichier depuis Git
+     */
+    getFileContent(filePath: string, branch?: string): Promise<GitCommitHistory | null>;
+    /**
+     * Liste tous les fichiers d'un type donné dans une branche
+     */
+    listFilesInBranch(branch: string, pattern?: string): Promise<string[]>;
+    /**
+     * Vérifie si un fichier existe dans une branche donnée
+     */
+    fileExistsInBranch(filePath: string, branch: string): Promise<boolean>;
+    /**
+     * Vérifie si la dernière version du fichier a été mergée
+     */
+    isFileMerged(filePath: string, from: string, target?: string): Promise<boolean>;
+    /**
+     * Récupère la liste de toutes les branches
+     */
+    getAllBranches(): Promise<string[]>;
+    /**
+     * Valide la configuration Git
+     */
+    validateConfiguration(): Promise<boolean>;
+}
+/**
+ * Interface pour les opérations de gestion des Pull Requests
+ */
+export interface IPROperations {
+    /**
+     * Vérifie si une branche PR est fermée (version legacy)
+     */
+    isPRClosed(branch: string): Promise<boolean>;
+    /**
+     * Vérifie si une branche PR est fermée (version robuste avec Git Notes)
+     */
+    isPRClosedRobust(branch: string, config?: RulesGitConfig): Promise<boolean>;
+    /**
+     * Ferme un PR (version legacy)
+     */
+    closePR(branch: string, author: RuleUser, message?: string, config?: RulesGitConfig): Promise<PRMergeResult>;
+    /**
+     * Ferme un PR (version robuste avec Git Notes)
+     */
+    closePRRobust(branch: string, closedBy: RuleUser, message?: string, config?: RulesGitConfig): Promise<PRMergeResult>;
+    /**
+     * Récupère tous les pull requests avec leur statut
+     */
+    getAllPR(options?: {
+        open?: boolean;
+        validationPrefix?: string;
+    }): Promise<PRInfo[]>;
+    /**
+     * Trouve le prochain numéro de PR disponible
+     */
+    getNextPRNumber(validationPrefix: string): Promise<number>;
+    /**
+     * Crée un nouveau PR avec incrémentation automatique du numéro
+     */
+    newPR(files: string[], description: string, author: RuleUser, options?: {
+        editorBranch?: string;
+        validationPrefix?: string;
+    }): Promise<PRInfo>;
+}
+/**
+ * Interface pour la gestion de la concurrence
+ */
+export interface IConcurrencyManager {
+    /**
+     * Exécute une fonction avec retry automatique
+     */
+    withRetry<T>(operation: () => Promise<T>, options: ConcurrencyOptions, operationName?: string): Promise<RetryResult<T>>;
+}
+/**
+ * Interface pour les opérations Git Notes
+ */
+export interface IGitNotesOperations {
+    /**
+     * Lit une note Git pour une branche donnée
+     */
+    readNote(branch: string, namespace: string): Promise<PRMetadata | null>;
+    /**
+     * Écrit une note Git pour une branche donnée
+     */
+    writeNote(branch: string, content: PRMetadata, namespace: string): Promise<void>;
+    /**
+     * Supprime une note Git pour une branche donnée
+     */
+    deleteNote(branch: string, author: RuleUser, namespace: string): Promise<void>;
+}
+/**
+ * Interface pour la configuration Git
+ */
+export interface IGitConfigLoader {
+    /**
+     * Charge la configuration Git depuis les variables d'environnement
+     */
+    load(): RulesGitConfig;
+    /**
+     * Valide la configuration chargée
+     */
+    validate(config: RulesGitConfig): boolean;
+}
+/**
+ * Interface principale qui combine toutes les opérations Git
+ * Parfaite pour les tests d'intégration et le mocking complet
+ */
+export interface IGitRepository extends IGitOperations, IPROperations {
+    /**
+     * Instance Git sous-jacente
+     */
+    readonly git: SimpleGit;
+    /**
+     * Configuration Git actuelle
+     */
+    readonly config: RulesGitConfig;
+    /**
+     * Gestionnaire de concurrence
+     */
+    readonly concurrency: IConcurrencyManager;
+    /**
+     * Opérations Git Notes
+     */
+    readonly notes: IGitNotesOperations;
+}

package/dist/src/rules/types.helpers.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/src/rules/types.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RuleStatus = void 0;
+/**
+ * @fileoverview Types et interfaces pour le système de gestion des règles métier
+ *
+ * Ce fichier définit tous les types TypeScript utilisés dans le workflow de gestion
+ * des règles, depuis les types de haut niveau (Rules, PR) jusqu'aux types Git de bas niveau.
+ */
+// ===== TYPES DE HAUT NIVEAU POUR LE WORKFLOW =====
+/**
+ * Énumération des statuts possibles d'une règle dans le workflow
+ *
+ * Le statut d'une règle reflète sa position dans le processus de validation
+ * et de publication, basé sur la branche Git où elle se trouve.
+ *
+ * @enum {string}
+ */
+var RuleStatus;
+(function (RuleStatus) {
+    /** Règle publiée et officielle (branche main) */
+    RuleStatus["PUBLISHED"] = "published";
+    /** Règle en cours d'édition (branche editor/draft) */
+    RuleStatus["EDITING"] = "editing";
+    /** Règle en cours de validation via pull request (branche validation) */
+    RuleStatus["PULLREQUEST"] = "pullrequest";
+    /** Règle candidate pour une release (branche release) */
+    RuleStatus["RELEASE_CANDIDATE"] = "candidate";
+    /** Règle en correction urgente (branche hotfix) */
+    RuleStatus["HOTFIX"] = "hotfix";
+    /** Nouvelle règle non encore trackée par Git (fichier local) */
+    RuleStatus["NEW"] = "new";
+})(RuleStatus || (exports.RuleStatus = RuleStatus = {}));

package/dist/src/rules/user.mapper.d.ts

@@ -0,0 +1,61 @@
+import { UserMSAL } from '../microsoft/profile';
+import { RuleUser } from './types';
+/**
+ * Rôles disponibles pour les règles
+ */
+export declare enum RuleRole {
+    READER = "reader",
+    EDITOR = "editor",
+    VALIDATOR = "validator",
+    PUBLISHER = "publisher"
+}
+/**
+ * Configuration des permissions par rôle
+ */
+export interface RolePermissions {
+    canRead: boolean;
+    canDelete: boolean;
+    canEdit: boolean;
+    canValidate: boolean;
+    canPublish: boolean;
+}
+/**
+ * Permissions par rôle
+ */
+export declare const ROLE_PERMISSIONS: Record<RuleRole, RolePermissions>;
+/**
+ * Mapper pour convertir UserMSAL en RuleUser
+ */
+export declare class UserRoleMapper {
+    /**
+     * Convertit un UserMSAL en RuleUser
+     * @param userMSAL L'utilisateur MSAL
+     * @param overrideRole Rôle à forcer (optionnel)
+     */
+    static toRuleUser(userMSAL: UserMSAL, overrideRole?: RuleRole): RuleUser;
+    /**
+     * Détermine le rôle d'un utilisateur basé sur ses propriétés MSAL
+     * @param userMSAL L'utilisateur MSAL
+     */
+    private static determineRoleFromMSAL;
+    /**
+     * Vérifie si un utilisateur a une permission spécifique
+     * @param userMSAL L'utilisateur MSAL
+     * @param permission La permission à vérifier
+     * @param overrideRole Rôle à forcer (optionnel)
+     */
+    static hasPermission(userMSAL: UserMSAL, permission: keyof RolePermissions, overrideRole?: RuleRole): boolean;
+    /**
+     * Obtient toutes les permissions d'un utilisateur
+     * @param userMSAL L'utilisateur MSAL
+     * @param overrideRole Rôle à forcer (optionnel)
+     */
+    static getPermissions(userMSAL: UserMSAL, overrideRole?: RuleRole): RolePermissions;
+    /**
+     * Vérifie si un utilisateur peut effectuer une action sur une branche donnée
+     * @param userMSAL L'utilisateur MSAL
+     * @param action L'action à effectuer
+     * @param branch La branche concernée
+     */
+    static canPerformAction(userMSAL: UserMSAL, action: 'read' | 'edit' | 'validate' | 'publish' | 'delete', branch: string): boolean;
+}

package/dist/src/rules/user.mapper.js

@@ -0,0 +1,160 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UserRoleMapper = exports.ROLE_PERMISSIONS = exports.RuleRole = void 0;
+/**
+ * Rôles disponibles pour les règles
+ */
+var RuleRole;
+(function (RuleRole) {
+    RuleRole["READER"] = "reader";
+    RuleRole["EDITOR"] = "editor";
+    RuleRole["VALIDATOR"] = "validator";
+    RuleRole["PUBLISHER"] = "publisher";
+})(RuleRole || (exports.RuleRole = RuleRole = {}));
+/**
+ * Permissions par rôle
+ */
+exports.ROLE_PERMISSIONS = {
+    [RuleRole.READER]: {
+        canRead: true,
+        canDelete: false,
+        canEdit: false,
+        canValidate: false,
+        canPublish: false
+    },
+    [RuleRole.EDITOR]: {
+        canRead: true,
+        canDelete: true,
+        canEdit: true,
+        canValidate: false,
+        canPublish: false
+    },
+    [RuleRole.VALIDATOR]: {
+        canRead: true,
+        canDelete: true,
+        canEdit: true,
+        canValidate: true,
+        canPublish: false
+    },
+    [RuleRole.PUBLISHER]: {
+        canRead: true,
+        canDelete: true,
+        canEdit: true,
+        canValidate: true,
+        canPublish: true
+    }
+};
+/**
+ * Mapper pour convertir UserMSAL en RuleUser
+ */
+class UserRoleMapper {
+    /**
+     * Convertit un UserMSAL en RuleUser
+     * @param userMSAL L'utilisateur MSAL
+     * @param overrideRole Rôle à forcer (optionnel)
+     */
+    static toRuleUser(userMSAL, overrideRole) {
+        // Déterminer le rôle
+        let role = overrideRole;
+        if (!role) {
+            // Déterminer le rôle basé sur les propriétés de l'utilisateur MSAL
+            role = this.determineRoleFromMSAL(userMSAL);
+        }
+        return {
+            name: userMSAL.displayName || userMSAL.id,
+            email: userMSAL.mail || `${userMSAL.id}@placeholder.local`,
+            role: role
+        };
+    }
+    /**
+     * Détermine le rôle d'un utilisateur basé sur ses propriétés MSAL
+     * @param userMSAL L'utilisateur MSAL
+     */
+    static determineRoleFromMSAL(userMSAL) {
+        // Logique de détermination du rôle basée sur les propriétés MSAL
+        // Cette logique peut être personnalisée selon les besoins de l'organisation
+        // Par défaut, utiliser hasRole() si disponible
+        const userRole = userMSAL.role;
+        // Mapper les rôles MSAL vers les rôles de règles
+        switch (userRole?.toLowerCase()) {
+            case 'admin':
+            case 'administrator':
+            case 'director':
+            case 'publisher':
+                return RuleRole.PUBLISHER;
+            case 'manager':
+            case 'chef':
+            case 'validator':
+            case 'reviewer':
+                return RuleRole.VALIDATOR;
+            case 'editor':
+            case 'contributor':
+            case 'writer':
+                return RuleRole.EDITOR;
+            case 'reader':
+            case 'viewer':
+            case 'anonymous':
+            default:
+                return RuleRole.READER;
+        }
+    }
+    /**
+     * Vérifie si un utilisateur a une permission spécifique
+     * @param userMSAL L'utilisateur MSAL
+     * @param permission La permission à vérifier
+     * @param overrideRole Rôle à forcer (optionnel)
+     */
+    static hasPermission(userMSAL, permission, overrideRole) {
+        const ruleUser = this.toRuleUser(userMSAL, overrideRole);
+        const role = ruleUser.role || RuleRole.READER;
+        return exports.ROLE_PERMISSIONS[role][permission];
+    }
+    /**
+     * Obtient toutes les permissions d'un utilisateur
+     * @param userMSAL L'utilisateur MSAL
+     * @param overrideRole Rôle à forcer (optionnel)
+     */
+    static getPermissions(userMSAL, overrideRole) {
+        const ruleUser = this.toRuleUser(userMSAL, overrideRole);
+        const role = ruleUser.role || RuleRole.READER;
+        return exports.ROLE_PERMISSIONS[role];
+    }
+    /**
+     * Vérifie si un utilisateur peut effectuer une action sur une branche donnée
+     * @param userMSAL L'utilisateur MSAL
+     * @param action L'action à effectuer
+     * @param branch La branche concernée
+     */
+    static canPerformAction(userMSAL, action, branch) {
+        // Déterminer le rôle requis selon l'action et la branche
+        const isValidationBranch = branch.startsWith('rule-validation-');
+        const isMainBranch = branch === 'main';
+        switch (action) {
+            case 'delete':
+                return this.hasPermission(userMSAL, 'canDelete');
+            case 'read':
+                return this.hasPermission(userMSAL, 'canRead');
+            case 'edit':
+                // L'édition n'est autorisée que sur la branche d'édition
+                if (branch !== 'rule-editor' && !isValidationBranch) {
+                    return false;
+                }
+                return this.hasPermission(userMSAL, 'canEdit');
+            case 'validate':
+                // La validation n'est autorisée que sur les branches de validation
+                if (!isValidationBranch) {
+                    return false;
+                }
+                return this.hasPermission(userMSAL, 'canValidate');
+            case 'publish':
+                // La publication n'est autorisée que depuis les branches de validation vers main
+                if (!isValidationBranch) {
+                    return false;
+                }
+                return this.hasPermission(userMSAL, 'canPublish');
+            default:
+                return false;
+        }
+    }
+}
+exports.UserRoleMapper = UserRoleMapper;

package/dist/src/rules/utils/slug.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Utility functions for handling slugs in the rules system
+ */
+/**
+ * Extracts a slug from a file path
+ * @param filePath The file path to extract the slug from
+ * @returns The slug extracted from the file path
+ */
+export declare const slugFromFile: (filePath: string, ext?: string) => string;
+/**
+ * Converts a slug back to a file path
+ * @param slug The slug to convert to a file path
+ * @param ext The file extension to append (default: '.md')
+ * @returns The file path created from the slug
+ */
+export declare const fileFromSlug: (slug: string, ext?: string) => string;
+/**
+ * Validates if a string is a valid slug
+ * @param slug The slug to validate
+ * @returns True if the slug is valid, false otherwise
+ */
+export declare const isValidSlug: (slug: string) => boolean;

package/dist/src/rules/utils/slug.js

@@ -0,0 +1,35 @@
+"use strict";
+/**
+ * Utility functions for handling slugs in the rules system
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isValidSlug = exports.fileFromSlug = exports.slugFromFile = void 0;
+const utils_1 = require("../../utils");
+/**
+ * Extracts a slug from a file path
+ * @param filePath The file path to extract the slug from
+ * @returns The slug extracted from the file path
+ */
+const slugFromFile = (filePath, ext = '.md') => {
+    return (0, utils_1.toSlug)(filePath.replace(ext, ''));
+};
+exports.slugFromFile = slugFromFile;
+/**
+ * Converts a slug back to a file path
+ * @param slug The slug to convert to a file path
+ * @param ext The file extension to append (default: '.md')
+ * @returns The file path created from the slug
+ */
+const fileFromSlug = (slug, ext = '.md') => {
+    return `${slug}${ext}`;
+};
+exports.fileFromSlug = fileFromSlug;
+/**
+ * Validates if a string is a valid slug
+ * @param slug The slug to validate
+ * @returns True if the slug is valid, false otherwise
+ */
+const isValidSlug = (slug) => {
+    return /^[a-z0-9-]+$/.test(slug);
+};
+exports.isValidSlug = isValidSlug;

package/dist/src/rules/utils.matter.d.ts

@@ -0,0 +1,66 @@
+import { FrontMatter, Rule } from "./types";
+/**
+ * Parse le front-matter YAML et le contenu Markdown d'un document
+ *
+ * Cette fonction extrait et parse le front-matter YAML délimité par '---'
+ * au début d'un document Markdown. Elle gère automatiquement :
+ * - La conversion des types (nombres, booléens, chaînes)
+ * - Le parsing des arrays JSON dans le YAML
+ * - La normalisation des champs `slugs` et `tags` en arrays
+ * - La suppression des guillemets de délimitation
+ *
+ * @param markdown - Texte Markdown brut avec front-matter optionnel
+ * @returns Objet contenant le front-matter parsé et le contenu
+ *
+ * @example
+ * ```typescript
+ * const doc = `---
+ * title: Ma Procédure
+ * tags: ["urgent", "finance"]
+ * version: 1.2
+ * active: true
+ * ---
+ * # Contenu de la procédure
+ *
+ * Instructions détaillées...`;
+ *
+ * const { matter, content } = matterParse(doc);
+ * // matter: { title: 'Ma Procédure', tags: ['urgent', 'finance'], version: 1.2, active: true }
+ * // content: '# Contenu de la procédure\n\nInstructions détaillées...'
+ * ```
+ */
+export declare function matterParse(markdown: string): {
+    matter: {};
+    content: string;
+    data?: undefined;
+} | {
+    data: any;
+    content: string;
+    matter: any;
+};
+/**
+ * Sérialise une Rule en format Markdown avec front-matter
+ * ✅ NOUVELLE FONCTION pour reconstruire le contenu complet
+*/
+export declare function matterSerializeFromRule(rule: Rule): string;
+export declare function matterSerialize(content: string, matter: FrontMatter | any): string;
+/**
+ * Extrait le front-matter (entre les deux premiers '---') et le contenu Markdown.
+ * Fonction 100% vanilla : aucun paquet externe requis.
+ * PROS:
+ * Code plus propre et maintenable
+ *  - Typage TypeScript strict
+ *  - Plus robuste (ignore lignes indentées)
+ *  - Séparation des responsabilités
+ *  - Meilleure architecture (parsing pur)
+ * CONS:
+ *  - Perte de fonctionnalité (slugs/tags)
+ *
+ * @param markdown Texte Markdown brut
+ * @returns Objet avec matter, content et data
+ */
+export declare function matterParse_OTHER(markdown: string): {
+    matter: Record<string, any>;
+    content: string;
+    data: Record<string, any>;
+};