@atlashub/smartstack-cli 4.74.0 → 4.76.0

package/templates/skills/business-analyse-html/references/02-mapping-tables.md

@@ -0,0 +1,442 @@
+---
+name: 02-mapping-tables
+description: Complete mapping tables for FEATURE_DATA object fields from master and collected_data sources
+---
+
+# Mapping Tables
+
+This reference documents all field mappings used when constructing the FEATURE_DATA object from collected BA data sources.
+
+---
+
+## Metadata Mapping
+
+**Source:** `master.metadata` and root `master` fields
+
+**Mapping:**
+```javascript
+metadata: {
+  applicationName: master.metadata.application,      // application name
+  applicationId: master.id,                           // application unique ID
+  version: master.version,                            // version string
+  createdAt: master.metadata.createdAt,              // ISO timestamp
+  lastModified: master.metadata.updatedAt,           // ISO timestamp
+  analysisMode: master.metadata.analysisMode || "interactive"  // default: interactive
+}
+```
+
+---
+
+## Cadrage Context Mapping
+
+**Source:** `master.cadrage` object
+
+**Mapping:**
+```javascript
+cadrage.context: {
+  problem: master.cadrage.problem || "",              // problem statement
+  trigger: master.cadrage.trigger || "",              // what triggered the project
+  currentSituation: master.cadrage.asIs || "",        // current state (AS-IS)
+  desiredSituation: master.cadrage.toBe || "",        // desired state (TO-BE)
+  painPoints: (master.cadrage.stakeholders || [])     // extracted from stakeholders
+    .flatMap(s => s.painPoints || [])
+    .join("\n"),
+  acceptanceCriteria: (master.cadrage.acceptanceCriteria || [])  // AC list
+    .map(ac => ac.criterion)
+    .join("\n")
+}
+```
+
+**Validation:** Warn if `problem` or `currentSituation/desiredSituation` are empty — these are MANDATORY for the HTML viewer.
+
+---
+
+## Cadrage Stakeholders Mapping
+
+**Source:** `master.cadrage.stakeholders[]`
+
+**Mapping:**
+```javascript
+cadrage.stakeholders: master.cadrage.stakeholders.map(s => ({
+  role: s.role,                                        // role name
+  function: s.function || "",                          // job function
+  tasks: Array.isArray(s.tasks)
+    ? s.tasks                                          // already an array
+    : typeof s.tasks === 'string'
+      ? s.tasks.split(',').map(t => t.trim()).filter(Boolean)  // parse CSV string
+      : [],
+  frequency: mapFrequency(s.frequency),               // frequency conversion
+  access: mapAccess(s.involvement),                   // involvement → access level conversion
+  frustrations: (s.painPoints || []).join("\n")       // stakeholder pain points
+}))
+```
+
+**Helper: `mapFrequency(freq)`**
+
+Maps user frequency to standardized values:
+```
+"Quotidien" | "Journalière" | "daily" → "daily"
+"Hebdomadaire" | "weekly" → "weekly"
+"Mensuel" | "monthly" → "monthly"
+"Trimestriel" | "quarterly" → "quarterly"
+"Annuel" | "yearly" → "yearly"
+default → freq (as-is)
+```
+
+**Helper: `mapAccess(involvement)`**
+
+Maps user involvement/role to access level:
+```
+"decision-maker" | "approver" | "responsable" → "admin"
+"end-user" | "user" | "utilisateur" → "contributor"
+"observer" | "lecteur" | "stakeholder" → "viewer"
+default → "viewer"
+```
+
+---
+
+## Cadrage Scope Mapping
+
+**Source:** `master.cadrage.globalScope` and fallback `master.cadrage.coverageMatrix`
+
+**Key Challenge:** Scope items can be strings, simple objects `{name, description}`, or complex objects `{feature, priority, module, app}`.
+
+**Normalization Helper:**
+```javascript
+function normalizeScopeItem(item) {
+  // Case 1: string value
+  if (typeof item === 'string') return { name: item, description: "" };
+
+  // Case 2: already in {name, description} format
+  if (item.name) return { name: item.name, description: item.description || "" };
+
+  // Case 3: {feature, priority, module, app} format (from globalScope)
+  var name = item.feature || item.label || item.title || JSON.stringify(item);
+  var parts = [];
+  if (item.priority) parts.push(item.priority.toUpperCase());      // priority → upper
+  if (item.module) parts.push("Module: " + item.module);           // module reference
+  if (item.app) parts.push("App: " + item.app);                    // app reference
+  return { name: name, description: parts.join(" — ") };           // parts → description
+}
+```
+
+**Mapping:**
+```javascript
+cadrage.scope: {
+  inscope: (master.cadrage.globalScope?.inScope || [])
+    .map(normalizeScopeItem),
+  outofscope: (master.cadrage.globalScope?.outOfScope || [])
+    .map(normalizeScopeItem)
+}
+```
+
+**Fallback:** If `globalScope` is missing/empty but `coverageMatrix` exists, build `inscope` from coverageMatrix entries.
+
+---
+
+## Cadrage Criteria Mapping
+
+**Source:** `master.cadrage.acceptanceCriteria[]` with fallback to `collected_data.master.validation.acceptanceCriteria[]`
+
+**Primary Mapping:**
+```javascript
+let criteria = (master.cadrage.acceptanceCriteria || []).map(ac => ({
+  text: ac.criterion || ac.text || "",
+  validated: false
+}));
+```
+
+**Fallback (if criteria is empty):**
+```javascript
+if (criteria.length === 0 && collected_data.master.validation) {
+  const valAC = collected_data.master.validation.acceptanceCriteria || [];
+  criteria = valAC.map(ac => ({
+    text: (ac.module ? '[' + ac.module + '] ' : '') + (ac.criteria || ac.criterion || ac.text || ""),
+    validated: false,
+    module: ac.module || null,
+    type: ac.type || null
+  }));
+}
+```
+
+---
+
+## Modules and Applications Mapping
+
+**Source:** `master.modules[]` and `master.applications[]` (with fallback to `collected_data.navigation?.applications`)
+
+**Applications Mapping:**
+```javascript
+applications: (collected_data.navigation?.applications || master.applications || []).map(app => ({
+  code: app.code,                    // unique application code
+  name: app.name || app.code,        // display name (fallback to code)
+  icon: app.icon || ""               // icon reference
+}))
+```
+
+**Modules Mapping:**
+```javascript
+modules: master.modules.map(m => ({
+  code: m.code,                      // unique module code
+  name: m.name || m.code,            // display name (MANDATORY)
+  applicationCode: m.applicationCode || "",  // multi-app grouping
+  description: m.description || "",
+  featureType: m.featureType || "data-centric",  // component type
+  entities: m.entities || [],        // entity references
+  anticipatedSections: (m.anticipatedSections || []).map(s =>
+    typeof s === 'string'
+      ? { code: s, name: s, description: "", resources: [] }
+      : {
+          code: s.code || s.name || "",
+          name: s.label || s.name || s.code || "",
+          description: s.description || "",
+          resources: s.resources || [],
+          route: s.route || "",
+          permission: s.permission || ""
+        }
+  ),
+  dependencies: m.dependencies || [],     // module dependencies
+  dependents: m.dependents || [],         // dependent modules
+  estimatedComplexity: m.estimatedComplexity || "medium",
+  status: m.status || "handed-off"       // handoff status
+}))
+```
+
+---
+
+## Dependencies Mapping (Top-Level)
+
+**Source:** `master.consolidation?.crossModuleInteractions` or `master.dependencyGraph?.edges`
+
+**CRITICAL:** This array is used by HTML sidebar navigation, module rendering, consolidation views, handoff summary, and export. If missing, the HTML page crashes with a TypeError.
+
+**Mapping:**
+```javascript
+dependencies: (master.consolidation?.crossModuleInteractions || master.dependencyGraph?.edges || []).map(i => ({
+  from: i.fromModule || i.from || "",
+  to: i.toModule || i.to || "",
+  description: i.description || ""
+}))
+```
+
+**Always include**, even if empty: `dependencies: []`
+
+---
+
+## Consolidation Mapping
+
+**Source:** `master.consolidation` object
+
+**Mapping:**
+```javascript
+consolidation: {
+  interactions: (master.consolidation?.crossModuleInteractions || []).map(i => ({
+    from: i.fromModule,
+    to: i.toModule,
+    description: i.description || ""
+  })),
+  sharedEntities: master.consolidation?.sharedEntities || [],
+  e2eFlows: (master.consolidation?.e2eFlows || []).map(f => ({
+    name: f.name,
+    steps: (f.steps || []).map(s => ({ module: s.module, action: s.action })),
+    actors: (f.steps || []).map(s => s.permission).join(", ")
+  }))
+}
+```
+
+---
+
+## Handoff Mapping
+
+**Source:** `master.handoff` object
+
+**Mapping:**
+```javascript
+handoff: {
+  complexity: master.handoff?.complexity,
+  implementationStrategy: master.handoff?.implementationStrategy,
+  moduleOrder: master.handoff?.moduleOrder,
+  filesToCreate: master.handoff?.filesToCreate,
+  brToCodeMapping: master.handoff?.brToCodeMapping,
+  apiEndpointSummary: master.handoff?.apiEndpointSummary
+}
+```
+
+---
+
+## Module Specifications: useCases Mapping
+
+**Source:** `collected_data.modules[moduleCode].usecases`
+
+**Normalization Notes:**
+- Field may be `useCases` (camelCase) or `usecases` (lowercase)
+- Steps may be strings[] or objects[] with `{step, action}` structure
+- Alternative flows may be `alternativeScenarios` or `alternativeFlows`
+
+**Mapping:**
+```javascript
+const rawUCs = mod.usecases?.useCases || mod.usecases?.usecases || [];
+
+useCases: rawUCs.map(uc => ({
+  name: uc.name || uc.title || uc.id || "",
+  sectionCode: uc.sectionCode || "",
+  actor: uc.primaryActor || uc.actor || "",
+  steps: (uc.mainScenario || uc.steps || []).map(s =>
+    typeof s === 'string' ? s : (s.action || s.description || "")
+  ).join("\n"),
+  alternative: (uc.alternativeScenarios || uc.alternativeFlows || []).map(a =>
+    (a.name || a.trigger || "") + ": " + (a.steps || a.actions || []).map(s =>
+      typeof s === 'string' ? s : (s.action || s.description || "")
+    ).join(", ")
+  ).join("\n")
+}))
+```
+
+---
+
+## Module Specifications: businessRules Mapping
+
+**Source:** `collected_data.modules[moduleCode].rules`
+
+**Normalization Notes:**
+- Field may be `rules` or `businessRules`
+
+**Mapping:**
+```javascript
+const rawBRs = mod.rules?.rules || mod.rules?.businessRules || [];
+
+businessRules: rawBRs.map(br => ({
+  name: br.name || br.id || "",
+  sectionCode: br.sectionCode || "",
+  category: br.category || "",
+  statement: br.statement || br.description || "",
+  example: (br.examples || []).map(e =>
+    typeof e === 'string' ? e : ((e.input || "") + " → " + (e.expected || ""))
+  ).join("; ")
+}))
+```
+
+---
+
+## Module Specifications: Entities Mapping
+
+**Source:** `collected_data.modules[moduleCode].entities`
+
+**Normalization Notes:**
+- Attributes may be `attributes[]` or `fields[]` (fallback if attributes missing)
+
+**Mapping:**
+```javascript
+entities: (mod.entities?.entities || []).map(ent => ({
+  name: ent.name,
+  description: ent.description || "",
+  attributes: (ent.attributes || []).length > 0
+    ? ent.attributes.map(a => ({
+        name: a.name,
+        type: a.type || "string",
+        required: a.required || false,
+        description: a.description || ""
+      }))
+    : (ent.fields || []).map(f => ({           // fallback to fields[]
+        name: f.name,
+        type: f.type || "string",
+        required: f.required || false,
+        description: f.description || ""
+      })),
+  relationships: (ent.relationships || []).map(r =>
+    typeof r === 'string' ? r : r.target + " (" + r.type + ") - " + (r.description || "")
+  )
+}))
+```
+
+---
+
+## Wireframes Mapping
+
+**Source:** `collected_data.modules[moduleCode].screens` with wireframe data
+
+**Field Rename CRITICAL:** Module JSON uses `mockupFormat`/`mockup`. HTML reads `format`/`content`.
+
+**Mapping:**
+```javascript
+wireframes: {
+  [moduleCode]: rawWireframes.map(wf => ({
+    screen: wf.screen || wf.name || wf.title || wf.id || "",
+    section: wf.section || "",
+    format: wf.mockupFormat || "ascii",                   // RENAME: mockupFormat → format
+    content: wf.mockup || wf.ascii || wf.content || "",   // RENAME: mockup → content
+    svgContent: null,                                      // populated later if SVG generated
+    description: wf.description || "",
+    elements: wf.elements || [],
+    actions: wf.actions || [],
+    componentMapping: Array.isArray(wf.componentMapping)
+      ? wf.componentMapping.map(entry => ...)   // see below
+      : typeof wf.componentMapping === 'object' && wf.componentMapping !== null
+        ? Object.entries(wf.componentMapping).map(([k, v]) => ({ wireframeElement: k, reactComponent: v }))
+        : [],
+    layout: typeof wf.layout === 'object' ? wf.layout : null,
+    permissionsRequired: wf.permissionsRequired || []
+  }))
+}
+```
+
+**componentMapping Normalization:**
+
+Handles three formats:
+```javascript
+// Format 1: Array of canonical entries {wireframeElement, reactComponent}
+[{wireframeElement: "Button1", reactComponent: "Button"}]
+
+// Format 2: Shorthand [{key: value}]
+[{"Button1": "Button"}] → {wireframeElement: "Button1", reactComponent: "Button"}
+
+// Format 3: Object {key: value}
+{"Button1": "Button"} → [{wireframeElement: "Button1", reactComponent: "Button"}]
+```
+
+---
+
+## E2E Flows Mapping
+
+**Source:** `master.consolidation?.e2eFlows`
+
+**Mapping:**
+```javascript
+e2eFlows: (master.consolidation?.e2eFlows || []).map(flow => ({
+  name: flow.name,
+  diagram: flow.steps.map(s => s.action + "(" + s.module + ")").join(" ──→ "),
+  steps: flow.steps || [],
+  actors: [...new Set(flow.steps.map(s => s.permission?.split(".")[0]).filter(Boolean))].join(", "),
+  modules: [...new Set(flow.steps.map(s => s.module))].join(" → ")
+}))
+```
+
+---
+
+## Dependency Graph Mapping
+
+**Source:** `master.modules[]` and `master.dependencyGraph?.edges`
+
+**Mapping:**
+```javascript
+dependencyGraph: {
+  nodes: (master.modules || []).map(m => ({
+    id: m.code,
+    label: m.code,
+    type: m.featureType || "data-centric"
+  })),
+  edges: (master.dependencyGraph?.edges || []).map(e => ({
+    from: e.from,
+    to: e.to,
+    description: e.description || ""
+  }))
+}
+```
+
+---
+
+## Permission Keys Helper
+
+**Source:** `collected_data.modules[moduleCode].permissions`
+
+**Implementation:** See `references/data-mapping.md` for `buildPermissionKeys()` function implementation.

package/templates/skills/business-analyse-html/references/02-normalization-helpers.md

@@ -0,0 +1,139 @@
+---
+name: 02-normalization-helpers
+description: Helper functions for normalizing field definitions, columns, filters, actions, charts, and KPIs across various JSON schema formats
+---
+
+# Normalization Helpers
+
+These helper functions normalize field definitions, columns, filters, actions, charts, and KPIs from various JSON schema conventions into a standard format used by the HTML renderer.
+
+## Column Normalization
+
+```javascript
+// Helper: normalize a column definition regardless of field naming convention
+function normalizeColumn(c) {
+  return {
+    field: c.code || c.name || c.id || c.field || c.fieldCode || "",
+    label: c.label || c.displayName || c.code || c.name || "",
+    type: c.renderAs === "badge" ? "badge" : (c.type || c.dataType || "text"),
+    sortable: !!c.sortable
+  };
+}
+```
+
+**Handles:** `code`, `name`, `id`, `field`, `fieldCode` for field reference; `label`, `displayName` for display; `renderAs`, `type`, `dataType` for type detection; `sortable` flag.
+
+## Form Field Normalization
+
+```javascript
+// Helper: normalize a form field
+function normalizeField(f) {
+  return {
+    field: f.code || f.name || f.id || f.fieldCode || f.field || "",
+    label: f.label || f.displayName || f.code || f.name || "",
+    type: f.type || f.fieldType || f.dataType || "text",
+    required: !!f.required
+  };
+}
+```
+
+**Handles:** Field reference via `code`, `name`, `id`, `fieldCode`, `field`; display via `label`, `displayName`; type via `type`, `fieldType`, `dataType`; required flag.
+
+## Filter Normalization (Simple)
+
+```javascript
+// Helper: normalize a filter (for SmartTable inline filters — label only)
+function normalizeFilter(f) {
+  if (typeof f === 'string') return f;
+  return f.label || f.displayName || f.filterLabel || f.name || f.code || f.filterCode || "";
+}
+```
+
+**Handles:** String filters (direct label) or objects with `label`, `displayName`, `filterLabel`, `name`, `code`, or `filterCode`.
+
+## SmartFilter Field Normalization
+
+```javascript
+// Helper: normalize a SmartFilter field (preserves type/options/entity for rich rendering)
+function normalizeSmartFilterField(f) {
+  if (typeof f === 'string') return { label: f, type: 'text', field: '' };
+  return {
+    field: f.field || f.code || f.name || "",
+    label: f.label || f.displayName || f.field || "",
+    type: f.type || "text",
+    options: f.options || [],
+    entity: f.entity || ""
+  };
+}
+```
+
+**Handles:** String filters or rich objects with field reference, label, type, options array, and entity linkage for dropdown/select filters.
+
+## Action Normalization
+
+```javascript
+// Helper: normalize an action
+function normalizeAction(a) {
+  if (typeof a === 'string') return a;
+  return a.code || a.id || a.label || a.actionCode || "";
+}
+```
+
+**Handles:** String actions (direct code/label) or objects with `code`, `id`, `label`, or `actionCode`.
+
+## Chart Normalization
+
+```javascript
+// Helper: normalize a chart definition
+function normalizeChart(c) {
+  if (typeof c === 'string') return { type: 'bar', label: c };
+  return {
+    type: c.type || c.chartType || 'bar',
+    label: c.label || c.displayName || c.title || 'Graphique'
+  };
+}
+```
+
+**Handles:** String charts (default to bar type with label) or objects with `type`/`chartType` and `label`/`displayName`/`title`.
+
+## KPI Normalization
+
+```javascript
+// Helper: normalize a KPI — replace formula values with sample display values
+function normalizeKpi(k) {
+  if (typeof k !== 'object') return { label: String(k), value: "0" };
+  const label = k.label || k.displayName || "";
+  const rawValue = k.value || k.metric || "0";
+  let displayValue = rawValue;
+  // Detect formula patterns (e.g., count(...), sum(...), ratio(...), avg(...))
+  if (typeof rawValue === 'string' && rawValue.includes('(')) {
+    const lbl = label.toLowerCase();
+    if (rawValue.includes('ratio') || rawValue.includes('%') || lbl.includes('taux') || lbl.includes('rate'))
+      displayValue = "87.5%";
+    else if (rawValue.includes('avg') || lbl.includes('moyen') || lbl.includes('average'))
+      displayValue = "12.4";
+    else if (rawValue.includes('sum'))
+      displayValue = (lbl.includes('jour') || lbl.includes('day') || lbl.includes('heure') || lbl.includes('hour')) ? "156" : "45,678";
+    else
+      displayValue = "1,234";
+  }
+  // Also handle format hint from the KPI definition
+  if (k.format === 'percentage' && displayValue === rawValue) displayValue = "80%";
+  return { label: label, value: displayValue };
+}
+```
+
+**Handles:** Non-object KPIs (converted to `{label, value}`); label via `label` or `displayName`; value via `value` or `metric`; formula pattern detection (ratio/avg/sum) to generate representative display values; percentage format hints.
+
+---
+
+## Usage Pattern
+
+All helpers follow this pattern:
+
+1. **Handle multiple naming conventions** for the same field (e.g., `code`, `name`, `id`)
+2. **Preserve data** when already in canonical form
+3. **Generate reasonable defaults** for optional fields
+4. **Convert internal formats** to HTML-renderable values (e.g., formula → sample number)
+
+Use these helpers when building `moduleSpecs[moduleCode].screens` arrays to normalize columns, fields, filters, actions, charts, and KPIs from heterogeneous BA JSON outputs.