@mostajs/reporting 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog — @mostajs/reporting
+
+## [0.1.0] — 2026-06-18
+### Added
+- Agrégateurs purs (`count/sum/avg/min/max/distinctCount/rate/groupBy`) — GENERALIZE de MostaGare `metrics-calculator`.
+- Périodes (`periodRange` jour/mois/trimestre/an, `previousRange`, `inRange`).
+- `createReporting`/`defineReport` : rapports déclaratifs sur sources injectées, `run` (métriques + count + groups), comparaison période précédente (delta), sucres `daily/monthly/quarterly/annual`, `export` (compose `@mostajs/file-export`).
+- Tests `test-scripts/unit` (8 verts) + exemple §12 (`examples/kpis` : KPIs réels sur @mostajs/users + @mostajs/allocations).
+
+### Notes
+- EXTRACTION du patron MostaGare `AnalyticsReportService`. DB-agnostique (sources injectées). Consommateurs : P1/P2/P3.

package/README.md

@@ -0,0 +1,26 @@
+# @mostajs/reporting
+
+**Auteur** : Dr Hamid MADANI <drmdh@msn.com> · **Licence** : AGPL-3.0-or-later · **Statut** : 0.1.0 (8 tests verts)
+
+> Moteur de reporting **générique** : KPIs + rapports périodiques + comparaison période précédente + export.
+> **DB-agnostique** (sources injectées). Consommé par P1 Hadhinat, P2 ATC, P3 ASSO-SEL. Compose `@mostajs/file-export`.
+
+## Exemple
+```js
+import { createReporting, defineReport, count, rate } from '@mostajs/reporting';
+const reporting = createReporting({
+  sources: { units: () => db.units.all() },
+  reports: [defineReport({ name:'occupancy', source:'units', metrics:{
+    total: count(), occupes: count(u=>u.status==='assigned'), taux: rate(u=>u.status==='assigned')
+  }})],
+});
+const r = await reporting.monthly('occupancy', { comparePrevious:true });
+// → { period, count, metrics:{total,occupes,taux}, comparison:{ delta } }
+```
+
+## Lancer
+```bash
+node examples/kpis/run.mjs
+node test-scripts/unit/reporting.test.mjs
+```
+API & types : `llms.txt`. Proposition/plan : `docs/`.

package/docs/00-PROPOSITION-PLAN-REPORTING-18062026.md

@@ -0,0 +1,34 @@
+# @mostajs/reporting — Proposition §4 + Plan de dev (EXTRACTION)
+
+**Auteur** : Dr Hamid MADANI <drmdh@msn.com>
+**Date** : 2026-06-18
+**Statut** : proposition à discuter (cas C — DEVRULES §4/§9 #3).
+**Priorité** : **P0** — module générique le plus rentable (consommateurs **P1 Hadhinat, P2 ATC, P3 ASSO-SEL** + tout back-office).
+**Principe** : **EXTRACTION, NE PAS REDÉVELOPPER** — généralise la couche analytics de `SolutionCh/MostaGare`.
+
+## 4.1 Besoin
+Agréger des données métier en **KPIs** + **rapports périodiques** (jour/mois/trimestre/an) + **comparaison à la période précédente** + **export** (PDF/CSV/Excel). Besoin **transverse** réclamé par les 3 projets ; aujourd'hui réimplémenté (MostaGare `AnalyticsReportService`/`metrics-calculator`).
+
+## 4.2 Règle d'or
+`@mostajs/mjs-metrics` = test de charge (≠ KPI métier) ; `@mostajs/audit` = source d'événements (pas l'agrégation) ; `file-export` = export (pas le calcul). → **cas C** : moteur d'agrégation générique, **DB-agnostique** (sources injectées), composant `file-export` pour l'export.
+
+## 4.3 Périmètre
+Moteur : **agrégateurs** (count/sum/avg/rate/distinct/min/max/groupBy), **périodes** (ranges + période précédente), **rapports** déclaratifs (`defineReport`), **comparaison**, **export** (délégué `@mostajs/file-export`). Pas de stockage : lit via **sources injectées** (`@mostajs/data-plug`/`audit`/`users`/`allocations`…). Pas d'UI (dashboards = couche app/`reporting-ui` ultérieure).
+
+## Carte d'extraction (source MostaGare → cible)
+| Source | Cible `src/` | Action |
+|---|---|---|
+| `metrics-calculator.ts` ($sum/$avg/$group, errorRate/successRate) | `aggregators.js` | GENERALIZE en fns pures `count/sum/avg/rate/distinct/min/max/groupBy` |
+| `AnalyticsReportService.ts` (generateXReport(start,end,filters), period, comparaison période précédente, insights) | `reporting.js` (`createReporting`, `defineReport`, `run`) | EXTRACT le patron rapport+période+comparaison |
+| `AgentDailyMetrics.ts` (totalActions/rate/period) | exemples de métriques | PATTERN |
+| `file-export` `exportDoc(format, doc)` | `export()` | COMPOSE |
+
+## Plan de dev (jalons)
+| v | Contenu |
+|---|---|
+| 0.1.0 | `aggregators` + `periods` + `createReporting`/`defineReport`/`run` (sources mémoire) + tests + exemple |
+| 0.2.0 | comparaison période précédente + `groupBy` multi-niveaux + helpers daily/monthly/quarterly/annual |
+| 0.3.0 | `export()` (compose `@mostajs/file-export`) + adaptateurs `@mostajs/data-plug` |
+| 1.0.0 | 14 livrables §9 + portes §11 + exemple §12 + article #17 |
+
+**Composition (§10)** : `data-plug`/`audit`/`users`/`allocations` (sources) · `file-export` (export). **Portes** : §11.1 (bloquante) ; §11.2/§11.3 informatives (données agrégées → minimisation).

package/examples/kpis/run.mjs

@@ -0,0 +1,60 @@
+// Exemple §12 — KPIs réels : reporting agrège les données @mostajs/users + @mostajs/allocations.
+// node examples/kpis/run.mjs
+import assert from 'node:assert/strict';
+import { createReporting, defineReport, count, rate, sum } from '../../src/index.js';
+import { inRange } from '../../src/periods.js';
+import { createUsers, createMemoryRepositories as userRepos } from '../../../mosta-users-stack/mosta-users/src/index.js';
+import { createAllocations, createMemoryRepositories as allocRepos } from '../../../mosta-allocations/src/index.js';
+
+// --- données via les vrais modules ---
+const users = createUsers({ repositories: userRepos() });
+const gym = createAllocations({ repositories: allocRepos() });
+const a = await users.create({ firstName: 'Inès' }); await users.enrollFace(a.id, [1, 2, 3]);
+const b = await users.create({ firstName: 'Karim' });
+const c = await users.create({ firstName: 'Sami' }); await users.disable(c.id);
+const u1 = await gym.units.create({ code: 'V1', resourceType: 'gym-locker' });
+await gym.units.create({ code: 'V2', resourceType: 'gym-locker' });
+await gym.alloc.assign(u1.id, a.id);
+
+// --- reporting : sources injectées + rapports déclaratifs ---
+const reporting = createReporting({
+  sources: {
+    members: async () => users.repositories.users.find(),
+    units: async () => gym.repositories.units.find(),
+    events: async ({ from, to }) => (await gym.repositories.events.find())
+      .filter(from && to ? inRange('at', { from, to }) : () => true),
+  },
+  reports: [
+    defineReport({ name: 'members', source: 'members', metrics: {
+      total: count(),
+      actifs: count((m) => m.status === 'active'),
+      avecVisage: count((m) => Array.isArray(m.faceDescriptor) && m.faceDescriptor.length),
+    } }),
+    defineReport({ name: 'occupancy', source: 'units', metrics: {
+      total: count(),
+      occupes: count((u) => u.status === 'assigned'),
+      tauxOccupation: rate((u) => u.status === 'assigned'),
+    } }),
+    defineReport({ name: 'checkins', source: 'events', groupBy: 'action', metrics: { total: count() } }),
+  ],
+});
+
+// KPIs membres
+const m = await reporting.run('members');
+assert.equal(m.metrics.total, 3);
+assert.equal(m.metrics.actifs, 2);
+assert.equal(m.metrics.avecVisage, 1);
+
+// Occupation
+const o = await reporting.run('occupancy');
+assert.equal(o.metrics.occupes, 1);
+assert.equal(o.metrics.tauxOccupation, 0.5, 'taux occupation 1/2');
+
+// Check-ins groupés par action + rapport mensuel
+const ck = await reporting.run('checkins', { groupBy: 'action' });
+assert.equal(ck.groups.assigned.total, 1, 'un assigned');
+const monthly = await reporting.monthly('checkins');
+assert.ok(monthly.period.from && monthly.period.to, 'période mensuelle calculée');
+
+console.log('✅ reporting — KPIs OK (members %o · occupancy taux %s · checkins %o)',
+  m.metrics, o.metrics.tauxOccupation, ck.groups);

package/llms.txt

@@ -0,0 +1,24 @@
+# @mostajs/reporting — fiche LLM
+
+RÔLE
+  Moteur de reporting générique : KPIs + rapports périodiques (jour/mois/trimestre/an) + comparaison
+  période précédente + export. DB-agnostique : lit via SOURCES injectées. Pas d'UI, pas de stockage.
+  GENERALIZE de MostaGare (metrics-calculator / AnalyticsReportService). Compose @mostajs/file-export (export).
+
+EXPORTS
+  createReporting({ sources, reports, now?, exporter? }) -> api
+  defineReport({ name, source, metrics:{clé:fn(rows)->valeur}, groupBy? })
+  agrégateurs: count(pred?) sum(field) avg(field) min(field) max(field) distinctCount(field) rate(numPred,denomPred?) groupBy(rows,key,compute)
+  périodes: periodRange(period,ref) previousRange({from,to}) startOfDay endOfDay inRange(field,{from,to})
+
+API (createReporting)
+  registerSource(name, fetch({from,to,filters})->rows[])  registerReport(def)
+  run(name,{from,to|period,groupBy?,comparePrevious?,filters?}) -> { report, period, count, metrics, groups?, comparison? }
+  daily/monthly/quarterly/annual(name, opts)   export(result, format) -> via exporter (@mostajs/file-export)
+
+PIÈGES
+  - Sources injectées (aucune DB en dur). metrics = fns pures rows->valeur (composer les agrégateurs).
+  - rate() renvoie 0..1. comparePrevious calcule delta vs période précédente de même durée.
+  - export exige `exporter` injecté (ex. @mostajs/file-export exportDoc). Dashboards = couche app (hors module).
+
+CONSOMMATEURS : P1 Hadhinat, P2 ATC, P3 ASSO-SEL (KPIs/rapports). Sources typiques : users, allocations, audit, data-plug.

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@mostajs/reporting",
+  "version": "0.1.0",
+  "description": "Moteur de reporting générique : KPIs, rapports périodiques (jour/mois/trimestre/an), comparaison période précédente, export (compose @mostajs/file-export). DB-agnostique (sources injectées).",
+  "license": "AGPL-3.0-or-later",
+  "author": "Dr Hamid MADANI <drmdh@msn.com>",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./aggregators": "./src/aggregators.js",
+    "./periods": "./src/periods.js"
+  },
+  "keywords": [
+    "mostajs",
+    "reporting",
+    "kpi",
+    "analytics",
+    "dashboard"
+  ],
+  "scripts": {
+    "test": "node test-scripts/unit/reporting.test.mjs",
+    "example": "node examples/kpis/run.mjs"
+  }
+}

package/src/aggregators.js

@@ -0,0 +1,23 @@
+// @mostajs/reporting — agrégateurs purs (fns rows[] -> valeur). Author: Dr Hamid MADANI <drmdh@msn.com>
+// GENERALIZE de MostaGare metrics-calculator ($sum/$avg/$group, errorRate/successRate).
+const num = (v) => (Number.isFinite(+v) ? +v : 0);
+
+export const count = (pred) => (rows) => (pred ? rows.filter(pred).length : rows.length);
+export const sum = (field) => (rows) => rows.reduce((s, r) => s + num(typeof field === 'function' ? field(r) : r[field]), 0);
+export const avg = (field) => (rows) => (rows.length ? sum(field)(rows) / rows.length : 0);
+export const min = (field) => (rows) => rows.reduce((m, r) => Math.min(m, num(r[field])), Infinity);
+export const max = (field) => (rows) => rows.reduce((m, r) => Math.max(m, num(r[field])), -Infinity);
+export const distinctCount = (field) => (rows) => new Set(rows.map((r) => (typeof field === 'function' ? field(r) : r[field]))).size;
+
+/** Taux = #(num) / #(denom). denom par défaut = toutes les lignes. Retourne 0..1. */
+export const rate = (numPred, denomPred) => (rows) => {
+  const d = (denomPred ? rows.filter(denomPred) : rows).length;
+  return d ? rows.filter(numPred).length / d : 0;
+};
+
+/** Regroupe rows par clé (champ ou fn) puis applique `compute(rows)` à chaque groupe. */
+export function groupBy(rows, key, compute) {
+  const groups = {};
+  for (const r of rows) { const k = typeof key === 'function' ? key(r) : r[key]; (groups[k] ||= []).push(r); }
+  return Object.fromEntries(Object.entries(groups).map(([k, rs]) => [k, compute(rs)]));
+}

package/src/index.js

@@ -0,0 +1,4 @@
+// @mostajs/reporting — point d'entrée. Author: Dr Hamid MADANI <drmdh@msn.com>
+export { createReporting, defineReport } from './reporting.js';
+export { count, sum, avg, min, max, distinctCount, rate, groupBy } from './aggregators.js';
+export { periodRange, previousRange, startOfDay, endOfDay, inRange } from './periods.js';

package/src/periods.js

@@ -0,0 +1,28 @@
+// @mostajs/reporting — helpers de périodes. Author: Dr Hamid MADANI <drmdh@msn.com>
+const d = (x) => new Date(x);
+export const startOfDay = (x) => { const r = d(x); r.setHours(0, 0, 0, 0); return r; };
+export const endOfDay = (x) => { const r = d(x); r.setHours(23, 59, 59, 999); return r; };
+
+/** Range {from,to} pour une période ('day'|'month'|'quarter'|'year') autour de `ref`. */
+export function periodRange(period, ref = new Date()) {
+  const r = d(ref);
+  switch (period) {
+    case 'day': return { from: startOfDay(r), to: endOfDay(r), period };
+    case 'month': return { from: new Date(r.getFullYear(), r.getMonth(), 1), to: endOfDay(new Date(r.getFullYear(), r.getMonth() + 1, 0)), period };
+    case 'quarter': { const q = Math.floor(r.getMonth() / 3); return { from: new Date(r.getFullYear(), q * 3, 1), to: endOfDay(new Date(r.getFullYear(), q * 3 + 3, 0)), period }; }
+    case 'year': return { from: new Date(r.getFullYear(), 0, 1), to: endOfDay(new Date(r.getFullYear(), 11, 31)), period };
+    default: throw new Error(`période inconnue: ${period} (day|month|quarter|year)`);
+  }
+}
+
+/** Période précédente de même durée. */
+export function previousRange({ from, to }) {
+  const dur = d(to).getTime() - d(from).getTime();
+  return { from: new Date(d(from).getTime() - dur - 1), to: new Date(d(from).getTime() - 1) };
+}
+
+/** Filtre des lignes sur un champ date dans [from,to]. */
+export const inRange = (field, { from, to }) => (r) => {
+  const t = d(r[field]).getTime();
+  return t >= d(from).getTime() && t <= d(to).getTime();
+};

package/src/reporting.js

@@ -0,0 +1,73 @@
+// @mostajs/reporting — moteur de rapports. Author: Dr Hamid MADANI <drmdh@msn.com>
+// EXTRACT du patron MostaGare AnalyticsReportService (rapport + période + comparaison période précédente).
+import { groupBy as groupRows } from './aggregators.js';
+import { periodRange, previousRange } from './periods.js';
+
+/** Déclare un rapport : source (nom), métriques {clé: fn(rows)->valeur}, groupBy optionnel. */
+export function defineReport({ name, source, metrics = {}, groupBy = null }) {
+  if (!name || !source) throw new Error('defineReport: name et source requis');
+  return { name, source, metrics, groupBy };
+}
+
+/**
+ * @param {object} opts
+ * @param {Record<string,(q)=>Promise<any[]>|any[]>} [opts.sources]  source(name) -> fetch({from,to,filters}) -> rows[]
+ * @param {object[]|Record<string,object>} [opts.reports]  rapports (defineReport)
+ * @param {()=>Date} [opts.now]
+ * @param {(format:string, doc:object)=>Promise<any>} [opts.exporter]  ex. @mostajs/file-export exportDoc
+ */
+export function createReporting({ sources = {}, reports = {}, now = () => new Date(), exporter } = {}) {
+  const srcMap = { ...sources };
+  const repMap = {};
+  for (const r of (Array.isArray(reports) ? reports : Object.values(reports))) repMap[r.name] = r;
+
+  const compute = (def, rows) =>
+    Object.fromEntries(Object.entries(def.metrics).map(([k, fn]) => [k, fn(rows)]));
+
+  const api = {
+    registerSource(name, fetchFn) { srcMap[name] = fetchFn; return api; },
+    registerReport(def) { repMap[def.name] = def; return api; },
+
+    async run(name, { from, to, period, groupBy, comparePrevious = false, filters } = {}) {
+      const def = repMap[name];
+      if (!def) throw new Error(`rapport inconnu: ${name}`);
+      const fetch = srcMap[def.source];
+      if (!fetch) throw new Error(`source inconnue: ${def.source}`);
+      const range = period ? periodRange(period, now()) : { from, to };
+      const rows = await fetch({ ...range, filters });
+      const result = { report: name, period: range, count: rows.length, metrics: compute(def, rows) };
+
+      const gb = groupBy || def.groupBy;
+      if (gb) result.groups = groupRows(rows, gb, (rs) => compute(def, rs));
+
+      if (comparePrevious) {
+        const prev = previousRange(range);
+        const prows = await fetch({ ...prev, filters });
+        const prevMetrics = compute(def, prows);
+        result.comparison = {
+          period: prev,
+          metrics: prevMetrics,
+          delta: Object.fromEntries(Object.keys(result.metrics).map((k) => [k, (result.metrics[k] ?? 0) - (prevMetrics[k] ?? 0)])),
+        };
+      }
+      return result;
+    },
+
+    // sucres périodiques
+    daily(name, o) { return api.run(name, { ...o, period: 'day' }); },
+    monthly(name, o) { return api.run(name, { ...o, period: 'month' }); },
+    quarterly(name, o) { return api.run(name, { ...o, period: 'quarter' }); },
+    annual(name, o) { return api.run(name, { ...o, period: 'year' }); },
+
+    /** Export via @mostajs/file-export (exporter injecté). doc = {title, items}. */
+    async export(result, format = 'csv') {
+      if (!exporter) throw new Error('export: exporter (@mostajs/file-export) requis');
+      const items = Object.entries(result.metrics).map(([k, v]) => ({ title: k, fields: { valeur: v } }));
+      return exporter(format, { title: `${result.report} — ${fmt(result.period)}`, items });
+    },
+  };
+  return api;
+}
+
+const iso = (x) => { const t = new Date(x).getTime(); return Number.isFinite(t) ? new Date(t).toISOString().slice(0, 10) : '∅'; };
+const fmt = (p = {}) => `${iso(p.from)}→${iso(p.to)}`;

package/test-scripts/unit/reporting.test.mjs

@@ -0,0 +1,70 @@
+// @mostajs/reporting — tests unitaires (DEVRULES §5). node test-scripts/unit/reporting.test.mjs
+import assert from 'node:assert/strict';
+import { createReporting, defineReport, count, sum, avg, rate, distinctCount, groupBy } from '../../src/index.js';
+import { periodRange, previousRange } from '../../src/periods.js';
+
+let pass = 0; const test = async (n, fn) => { await fn(); pass++; console.log('  ✓', n); };
+const rows = [
+  { type: 'a', amount: 10, status: 'ok', day: '2026-06-01' },
+  { type: 'a', amount: 20, status: 'ko', day: '2026-06-01' },
+  { type: 'b', amount: 30, status: 'ok', day: '2026-06-02' },
+];
+
+await test('agrégateurs purs', () => {
+  assert.equal(count()(rows), 3);
+  assert.equal(count((r) => r.type === 'a')(rows), 2);
+  assert.equal(sum('amount')(rows), 60);
+  assert.equal(avg('amount')(rows), 20);
+  assert.equal(distinctCount('type')(rows), 2);
+  assert.equal(rate((r) => r.status === 'ok')(rows).toFixed(3), (2 / 3).toFixed(3));
+});
+await test('groupBy', () => {
+  const g = groupBy(rows, 'type', (rs) => count()(rs));
+  assert.equal(g.a, 2); assert.equal(g.b, 1);
+});
+await test('periodRange month + previousRange', () => {
+  const r = periodRange('month', new Date('2026-06-15T12:00:00Z'));
+  assert.equal(r.from.getMonth(), 5); assert.equal(r.to.getMonth(), 5);
+  const p = previousRange(r);
+  assert.ok(p.to.getTime() < r.from.getTime());
+});
+await test('run: métriques + count', async () => {
+  const rep = createReporting({
+    sources: { s: () => rows },
+    reports: [defineReport({ name: 'r', source: 's', metrics: { total: count(), ca: sum('amount') } })],
+  });
+  const out = await rep.run('r');
+  assert.equal(out.count, 3); assert.equal(out.metrics.total, 3); assert.equal(out.metrics.ca, 60);
+});
+await test('run: groupBy', async () => {
+  const rep = createReporting({ sources: { s: () => rows }, reports: [defineReport({ name: 'r', source: 's', groupBy: 'type', metrics: { n: count() } })] });
+  const out = await rep.run('r');
+  assert.equal(out.groups.a.n, 2);
+});
+await test('run: comparaison période précédente (delta)', async () => {
+  const data = { cur: [{ x: 1 }, { x: 1 }], prev: [{ x: 1 }] };
+  const rep = createReporting({
+    now: () => new Date('2026-06-15'),
+    sources: { s: ({ from }) => (new Date(from).getMonth() === 5 ? data.cur : data.prev) },
+    reports: [defineReport({ name: 'r', source: 's', metrics: { total: count() } })],
+  });
+  const out = await rep.run('r', { period: 'month', comparePrevious: true });
+  assert.equal(out.metrics.total, 2);
+  assert.equal(out.comparison.metrics.total, 1);
+  assert.equal(out.comparison.delta.total, 1);
+});
+await test('export: exige un exporter', async () => {
+  const rep = createReporting({ sources: { s: () => rows }, reports: [defineReport({ name: 'r', source: 's', metrics: { total: count() } })] });
+  const out = await rep.run('r');
+  await assert.rejects(() => rep.export(out), /exporter.*requis/);
+  const captured = [];
+  const rep2 = createReporting({ sources: { s: () => rows }, reports: [defineReport({ name: 'r', source: 's', metrics: { total: count() } })], exporter: (fmt, doc) => { captured.push({ fmt, doc }); return 'ok'; } });
+  await rep2.export(await rep2.run('r'), 'csv');
+  assert.equal(captured[0].fmt, 'csv'); assert.equal(captured[0].doc.items[0].title, 'total');
+});
+await test('erreurs : rapport/source inconnus', async () => {
+  const rep = createReporting({});
+  await assert.rejects(() => rep.run('nope'), /rapport inconnu/);
+});
+
+console.log(`\n✅ @mostajs/reporting — ${pass} tests OK`);