@mostajs/compta-budget 0.1.0

package/README.md

@@ -0,0 +1,19 @@
+# @mostajs/compta-budget
+
+**Auteur** : Dr Hamid MADANI <drmdh@msn.com> · **Licence** : AGPL-3.0-or-later
+
+Comptabilité **budgétaire** (couche logique) — suit chaque ligne de budget sur 4 temps :
+**alloué → engagé → réalisé → écart**, et détecte le **surengagement**. **Compose** des sources
+injectées (DEVRULES §10) ; ne réimplémente ni `aid-grants` ni `compta`.
+
+```js
+import { createComptaBudget } from '@mostajs/compta-budget';
+const cb = createComptaBudget({ sources: {
+  budgetLines: () => repos.aidGrants.budgets.find(),
+  aids:        () => repos.aidGrants.aids.find(),
+}});
+await cb.status('aide-mensuelle'); // { allocated, engaged, realized, available, outstanding, variance, overcommitted }
+await cb.summary();
+```
+
+Tests & exemple (§11.1 / §12) : `npm install && npm test`. Proposition & livrables : `docs/`. Fiche LLM : `llms.txt`.

package/llms.txt

@@ -0,0 +1,34 @@
+# @mostajs/compta-budget — fiche LLM
+> Comptabilité budgétaire : allocation → engagement → réalisation → écart, par composition (DB-agnostique).
+
+- Version: 0.1.0 · Licence: AGPL-3.0-or-later · Auteur: Dr Hamid MADANI <drmdh@msn.com>
+- Stack: mosta-gestion-stack · Voisins: @mostajs/compta, @mostajs/compta-analytique
+
+## RÔLE
+Suit chaque ligne de budget sur 4 temps : ALLOUÉ → ENGAGÉ (aides approuvées+versées) →
+RÉALISÉ (versées) → ÉCART. Détecte le surengagement. Compose des SOURCES injectées (§10) ;
+ne réimplémente ni aid-grants ni compta.
+
+## EXPORTS
+- createComptaBudget({ sources, now? }) -> { all, status, summary }
+
+## API
+- all() -> Ligne[]   Ligne = { line, allocated, engaged, realized, available, outstanding, variance, consumptionRate, overcommitted }
+- status(line) -> Ligne | null
+- summary() -> { allocated, engaged, realized, available, outstanding, variance, consumptionRate, lines }
+
+## DÉFINITIONS
+- engaged  = somme des aides au statut 'approved' OU 'paid'
+- realized = somme des aides 'paid'
+- available = allocated - engaged ; outstanding = engaged - realized ; variance = allocated - realized
+- overcommitted = engaged > allocated
+
+## SOURCES injectées
+- budgetLines() -> { line, allocated }[]
+- aids() -> { budgetLine, amount, status }[]   (toutes aides)
+
+## COMPOSITION (Salsabil)
+createComptaBudget({ sources: {
+  budgetLines: () => repos.aidGrants.budgets.find(),
+  aids: () => repos.aidGrants.aids.find(),
+}})

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@mostajs/compta-budget",
+  "version": "0.1.0",
+  "description": "Comptabilité budgétaire — allocation → engagement → réalisation → écart, par composition de sources (DB-agnostique).",
+  "author": "Dr Hamid MADANI <drmdh@msn.com>",
+  "license": "AGPL-3.0-or-later",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "llms.txt"
+  ],
+  "keywords": [
+    "comptabilite",
+    "budget",
+    "engagement",
+    "mostajs"
+  ],
+  "devDependencies": {
+    "@mostajs/mjs-unit": "^0.3.0"
+  },
+  "scripts": {
+    "test": "node test-scripts/unit/compta-budget.test.mjs && node examples/run.mjs"
+  }
+}

package/src/index.js

@@ -0,0 +1,62 @@
+// @mostajs/compta-budget — comptabilité BUDGÉTAIRE (couche logique). MVP.
+// Au-delà du simple « alloué/consommé » : suit ALLOCATION → ENGAGEMENT → RÉALISATION → ÉCART.
+// COMPOSE par INJECTION (DEVRULES §10) : reçoit des SOURCES (lignes de budget + aides) ;
+// DB-agnostique, ne réimplémente ni aid-grants ni compta.
+// @author Dr Hamid MADANI <drmdh@msn.com> · AGPL-3.0-or-later
+
+const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : 0);
+const ENGAGED = new Set(['approved', 'paid']);   // engagé = approuvé OU versé
+const REALIZED = 'paid';                          // réalisé = versé
+
+/**
+ * @param {object} opts
+ * @param {object} opts.sources
+ *   - budgetLines() -> { line, allocated }[]
+ *   - aids()        -> { budgetLine, amount, status }[]   (toutes aides, tous statuts)
+ * @param {() => Date} [opts.now]
+ */
+export function createComptaBudget({ sources = {}, now = () => new Date() } = {}) {
+  const budgetLines = sources.budgetLines || (async () => []);
+  const aids = sources.aids || (async () => []);
+
+  /** Situation budgétaire de toutes les lignes. */
+  async function all() {
+    const lines = await budgetLines();
+    const allAids = await aids();
+    return lines.map((b) => {
+      const onLine = allAids.filter((a) => a.budgetLine === b.line);
+      const engaged = onLine.filter((a) => ENGAGED.has(a.status)).reduce((s, a) => s + num(a.amount), 0);
+      const realized = onLine.filter((a) => a.status === REALIZED).reduce((s, a) => s + num(a.amount), 0);
+      const allocated = num(b.allocated);
+      return {
+        line: b.line,
+        allocated,
+        engaged,                                   // engagé (approuvé + versé)
+        realized,                                  // réalisé (versé)
+        available: allocated - engaged,            // disponible (non engagé)
+        outstanding: engaged - realized,           // engagé non décaissé
+        variance: allocated - realized,            // écart allocation ↔ réalisation
+        consumptionRate: allocated ? realized / allocated : 0,
+        overcommitted: engaged > allocated,        // dépassement d'engagement
+      };
+    });
+  }
+
+  /** Situation d'une ligne. */
+  async function status(line) { return (await all()).find((x) => x.line === line) || null; }
+
+  /** Totaux consolidés. */
+  async function summary() {
+    const rows = await all();
+    const t = rows.reduce((acc, x) => ({
+      allocated: acc.allocated + x.allocated, engaged: acc.engaged + x.engaged,
+      realized: acc.realized + x.realized, available: acc.available + x.available,
+      outstanding: acc.outstanding + x.outstanding,
+    }), { allocated: 0, engaged: 0, realized: 0, available: 0, outstanding: 0 });
+    return { ...t, variance: t.allocated - t.realized, consumptionRate: t.allocated ? t.realized / t.allocated : 0, lines: rows.length };
+  }
+
+  return { now, all, status, summary };
+}
+
+export default createComptaBudget;