@atlashub/smartstack-cli 4.80.0 → 5.0.0

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

@@ -1,139 +0,0 @@
----
-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.

package/templates/skills/business-analyse-html/references/02-screen-format-detection.md

@@ -1,283 +0,0 @@
----
-name: 02-screen-format-detection
-description: Detection and normalization logic for screens.json format variants (A, B-CANONICAL, B-LEGACY)
----
-
-# Screen Format Detection
-
-The `screens.json` file can be produced in multiple formats depending on the BA workflow step that generated it. This reference documents the detection logic and normalization for each format variant.
-
-## Format Overview
-
-| Format | Structure | Source | Key Fields |
-|--------|-----------|--------|-----------|
-| **A** | `screens[]` (flat) | ba-003 (original BA output) | `screen`, `section`, `columns[]`, `filters[]`, `tabs[]`, `actions[]`, `kpis[]`, `charts[]` |
-| **B-CANONICAL** | `sections[].resources[]` | ba-005+ (design output) | `sectionCode`, `sectionLabel`, `resources[]` with nested structure |
-| **B-LEGACY** | `sections[]` (flat within section) | ba-004 (intermediate step) | `sections[]` with data directly on section, no resources[] nesting |
-
-## Format A: Flat screens[] Array
-
-**Detection:** `mod.screens?.screens` array exists and has length > 0.
-
-**Schema:**
-```javascript
-screens: [
-  {
-    screen: "ScreenName",
-    section: "SectionCode",
-    sectionLabel: "Section Label",
-    description: "...",
-    sectionDescription: "...",
-    componentType: "SmartTable|SmartForm|Dashboard|Kanban",
-    columns: [...],           // for table components
-    filters: [...],           // simple filters
-    tabs: [...],              // form tabs
-    actions: [...],           // action buttons
-    kpis: [...],              // dashboard KPIs
-    charts: [...],            // dashboard charts
-    options: [...],           // component options
-    permission: "...",        // ACL permission
-    mockup: "...",            // wireframe content
-    mockupFormat: "..."       // wireframe format
-  }
-]
-```
-
-**Normalization:**
-
-Group flat screens by section, then map each to a `{sectionCode, sectionLabel, resources[]}` structure:
-
-```javascript
-if (flatScr.length > 0) {
-  // FORMAT A: flat screens[] array (ba-003 style)
-  const bySec = {};
-  flatScr.forEach(s => {
-    const sec = s.section || "default";
-    if (!bySec[sec]) bySec[sec] = {
-      sectionCode: sec,
-      sectionLabel: s.sectionLabel || s.sectionDescription || sec,
-      resources: []
-    };
-    bySec[sec].resources.push({
-      code: s.screen || s.name || "",
-      label: s.sectionLabel || s.description || s.screen || "",
-      type: s.componentType || "unknown",
-      columns: (s.columns || []).map(normalizeColumn),
-      filters: (s.filters || []).map(normalizeFilter),
-      fields: [],
-      tabs: (s.tabs || []).map(t => ({
-        label: t.label || t.tabLabel || t.code || "",
-        fields: (t.fields || []).map(normalizeField)
-      })),
-      actions: (s.actions || []).map(normalizeAction),
-      kpis: (s.kpis || []).map(normalizeKpi),
-      charts: (s.charts || []).map(normalizeChart),
-      options: s.options || [],
-      permission: s.permission || "",
-      notes: s.description || s.sectionDescription || ""
-    });
-  });
-  screens = Object.values(bySec);
-}
-```
-
-**Output:** Array of `{sectionCode, sectionLabel, resources[]}` objects (equivalent to B-CANONICAL).
-
-## Format B: Detect Sub-variant (B-CANONICAL vs B-LEGACY)
-
-**Detection:** `mod.screens?.sections` array exists and has length > 0.
-
-**Decision point:** Check if any section contains `resources[]`:
-
-```javascript
-const hasNestedResources = sectionScr.some(sec => (sec.resources || []).length > 0);
-```
-
-### Format B-CANONICAL: sections[] with resources[]
-
-**Schema:**
-```javascript
-sections: [
-  {
-    sectionCode: "SectionCode",
-    sectionLabel: "Section Label",
-    displayName: "...",
-    label: "...",
-    id: "...",
-    code: "...",
-    resources: [
-      {
-        code: "ResourceCode",
-        id: "...",
-        label: "Resource Label",
-        displayName: "...",
-        type: "SmartTable|SmartForm|Dashboard|Kanban",
-        componentType: "...",
-        layout: "...",
-        columns: [...],       // normalized column definitions
-        filters: [...],       // SmartFilter-style filters
-        tabs: [...],          // form tabs
-        actions: [...],       // action buttons
-        kpis: [...],          // KPIs
-        charts: [...],        // chart definitions
-        options: [...],       // component options
-        permission: "...",    // ACL permission
-        notes: "...",         // description
-        description: "..."
-      }
-    ]
-  }
-]
-```
-
-**Normalization:**
-
-```javascript
-if (hasNestedResources) {
-  // FORMAT B-CANONICAL: sections[] with resources[] (ba-005+ style)
-  screens = sectionScr.map(sec => ({
-    sectionCode: sec.sectionCode || sec.id || sec.code || "",
-    sectionLabel: sec.sectionLabel || sec.displayName || sec.label || sec.sectionCode || "",
-    resources: (sec.resources || []).map(res => ({
-      code: res.code || res.id || "",
-      label: res.label || res.displayName || res.code || "",
-      type: res.type || res.componentType || res.layout || "unknown",
-      columns: (res.columns || []).map(normalizeColumn),
-      filters: res.type === 'SmartFilter'
-        ? (res.filters || []).map(normalizeSmartFilterField)
-        : (res.filters || []).map(normalizeFilter),
-      fields: [],
-      tabs: (res.tabs || []).map(t => ({
-        label: t.label || t.displayName || t.code || t.id || "",
-        fields: (t.fields || []).map(normalizeField)
-      })),
-      actions: (res.actions || []).map(normalizeAction),
-      kpis: (res.kpis || []).map(normalizeKpi),
-      charts: (res.charts || []).map(normalizeChart),
-      options: res.options || [],
-      permission: res.permission || "",
-      notes: res.notes || res.description || ""
-    }))
-  }));
-}
-```
-
-**Key feature:** SmartFilter type detected and uses rich filter normalization (`normalizeSmartFilterField`) instead of simple label extraction.
-
-### Format B-LEGACY: sections[] without resources[]
-
-**Schema:**
-```javascript
-sections: [
-  {
-    id: "SectionId",
-    code: "SectionCode",
-    sectionCode: "...",
-    displayName: "Section Label",
-    label: "...",
-    layout: "SmartTable|SmartForm|Dashboard",
-    componentType: "...",
-    columns: [...],       // data directly on section
-    filters: [...],       // simple filters
-    tabs: [...],          // form tabs
-    actions: [...],       // action buttons
-    kpis: [...],          // KPIs
-    charts: [...],        // chart definitions
-    options: [...],       // options
-    permissions: {view: "..."} or permission: "...",
-    description: "...",
-    // NO resources[] nesting
-  }
-]
-```
-
-**Normalization:**
-
-Group sections by ID/code, then map into `{sectionCode, sectionLabel, resources[]}` structure:
-
-```javascript
-} else {
-  // FORMAT B-LEGACY: sections[] without resources[] (ba-004 style)
-  const bySec = {};
-  sectionScr.forEach(sec => {
-    const secId = sec.id || sec.code || sec.sectionCode || "";
-    const secLabel = sec.displayName || sec.label || sec.sectionLabel || secId;
-    const componentType = sec.layout || sec.componentType || "unknown";
-    if (!bySec[secId]) bySec[secId] = {
-      sectionCode: secId,
-      sectionLabel: secLabel,
-      resources: []
-    };
-    bySec[secId].resources.push({
-      code: secId,
-      label: secLabel,
-      type: componentType,
-      columns: (sec.columns || []).map(normalizeColumn),
-      filters: (sec.filters || []).map(normalizeFilter),
-      fields: [],
-      tabs: (sec.tabs || []).map(t => ({
-        label: t.displayName || t.label || t.code || t.id || "",
-        fields: (t.fields || []).map(normalizeField)
-      })),
-      actions: (sec.actions || []).map(normalizeAction),
-      kpis: (sec.kpis || []).map(normalizeKpi),
-      charts: (sec.charts || []).map(normalizeChart),
-      options: sec.options || [],
-      permission: (typeof sec.permissions === 'object' ? sec.permissions?.view : sec.permission) || "",
-      notes: sec.description || ""
-    });
-  });
-  screens = Object.values(bySec);
-}
-```
-
-**Key differences:**
-- Sections have data directly (no `resources[]` nesting)
-- Permissions may be object `{view: "..."}` or simple string
-- One resource per section (grouped by ID)
-
-## Output Normalization
-
-All three formats normalize to a **canonical output structure**:
-
-```javascript
-screens: [
-  {
-    sectionCode: "string",
-    sectionLabel: "string",
-    resources: [
-      {
-        code: "string",
-        label: "string",
-        type: "string",
-        columns: [...],         // normalized via normalizeColumn()
-        filters: [...],         // normalized via normalizeFilter() or normalizeSmartFilterField()
-        fields: [],
-        tabs: [...],            // with normalized fields
-        actions: [...],         // normalized via normalizeAction()
-        kpis: [...],            // normalized via normalizeKpi()
-        charts: [...],          // normalized via normalizeChart()
-        options: [...],
-        permission: "string",
-        notes: "string"
-      }
-    ]
-  }
-]
-```
-
-This canonical form is then used to populate `moduleSpecs[moduleCode].screens` and render in the HTML viewer.
-
-## Detection Flow
-
-```
-mod.screens exists?
-├─ YES: Do we have mod.screens.screens[] with length > 0?
-│  └─ YES: Format A (flat) → normalize by section → canonical
-│  └─ NO: Continue to B detection
-├─ Do we have mod.screens.sections[] with length > 0?
-│  └─ YES: Check hasNestedResources (any section.resources[] exists?)
-│     ├─ YES: Format B-CANONICAL → normalize permissions → canonical
-│     └─ NO: Format B-LEGACY → group by ID → canonical
-└─ NO: screens = [] (empty)
-```

package/templates/skills/business-analyse-html/references/02-self-check-validation.md

@@ -1,199 +0,0 @@
----
-name: 02-self-check-validation
-description: Post-build self-check validation to detect data loss when building FEATURE_DATA
----
-
-# Self-Check Validation
-
-After building `FEATURE_DATA.moduleSpecs` and enriching `anticipatedSections` with section-level use cases and business rules, run this mandatory self-check to detect data loss between the source files and the built object.
-
-## Purpose
-
-Ensures that no useCases, businessRules, entities, or screens were lost during the normalization and mapping process. Data loss indicates a bug in the build logic (e.g., missing array handling, failed normalization, wrong field names).
-
-## Execution Timing
-
-**AFTER:**
-1. All `moduleSpecs[moduleCode]` entries are populated
-2. `anticipatedSections` are enriched with section-level UC/BR
-
-**BEFORE:**
-- Proceeding to step-03 (HTML rendering)
-
-## Self-Check Code
-
-```javascript
-// SELF-CHECK: compare source file counts vs FEATURE_DATA counts
-const errors = [];
-FEATURE_DATA.modules.forEach(m => {
-  const spec = FEATURE_DATA.moduleSpecs[m.code];
-  const source = collected_data.modules[m.code];
-  if (!spec) { errors.push(`MISSING moduleSpecs[${m.code}]`); return; }
-
-  // Check useCases (handle both key conventions)
-  const srcUC = (source?.usecases?.useCases || source?.usecases?.usecases || []).length;
-  const bltUC = (spec.useCases || []).length;
-  if (srcUC > 0 && bltUC === 0)
-    errors.push(`${m.code}: useCases EMPTY but source has ${srcUC}`);
-
-  // Check businessRules (handle both key conventions)
-  const srcBR = (source?.rules?.rules || source?.rules?.businessRules || []).length;
-  const bltBR = (spec.businessRules || []).length;
-  if (srcBR > 0 && bltBR === 0)
-    errors.push(`${m.code}: businessRules EMPTY but source has ${srcBR}`);
-
-  // Check entities
-  const srcEnt = (source?.entities?.entities || []).length;
-  const bltEnt = (spec.entities || []).length;
-  if (srcEnt > 0 && bltEnt === 0)
-    errors.push(`${m.code}: entities EMPTY but source has ${srcEnt}`);
-
-  // Check screens (handle both formats: screens[] and sections[])
-  const srcScreens = (source?.screens?.screens || source?.screens?.sections || []).length;
-  const bltScreenResources = (spec.screens || []).reduce(
-    (acc, s) => acc + (s.resources || []).length, 0);
-  if (srcScreens > 0 && bltScreenResources === 0)
-    errors.push(`${m.code}: screens EMPTY (0 resources) but source has ${srcScreens} screens/sections`);
-
-  // Check serialization: [object Object] in useCases steps = BUG
-  (spec.useCases || []).forEach(uc => {
-    if (uc.steps && uc.steps.includes("[object Object]"))
-      errors.push(`${m.code}: UC "${uc.name}" has [object Object] in steps — steps[] contains objects not strings`);
-  });
-});
-
-if (errors.length > 0) {
-  Display("⛔ SELF-CHECK FAILED — data loss detected:");
-  errors.forEach(e => Display("  - " + e));
-  // FIX: re-map the failing modules from collected_data before continuing
-}
-```
-
-## Validation Points
-
-### 1. moduleSpecs Structure
-
-**Check:** Every module in `FEATURE_DATA.modules` has a corresponding entry in `FEATURE_DATA.moduleSpecs[moduleCode]`.
-
-**Failure Symptom:** `MISSING moduleSpecs[${m.code}]`
-
-**Fix:** Ensure the build loop populates `moduleSpecs[moduleCode]` for ALL modules.
-
-### 2. useCases Count
-
-**Check:** If source file has useCases (`usecases.useCases` or `usecases.usecases`), the built `spec.useCases` array must not be empty.
-
-**Failure Symptom:** `${m.code}: useCases EMPTY but source has ${srcUC}`
-
-**Common Causes:**
-- Field is `usecases` but code looks for `useCases` (camelCase mismatch)
-- Nested field is `usecases` instead of `useCases` (lowercase variant)
-- Mapping function didn't handle array correctly
-
-**Fix:** Check field names in `mod.usecases?.useCases || mod.usecases?.usecases`.
-
-### 3. businessRules Count
-
-**Check:** If source file has businessRules (`rules.rules` or `rules.businessRules`), the built `spec.businessRules` array must not be empty.
-
-**Failure Symptom:** `${m.code}: businessRules EMPTY but source has ${srcBR}`
-
-**Common Causes:**
-- Field is `businessRules` but code looks for `rules` (nested field name mismatch)
-- Rules array is not being mapped correctly
-
-**Fix:** Check field names in `mod.rules?.rules || mod.rules?.businessRules`.
-
-### 4. Entities Count
-
-**Check:** If source file has entities (`entities.entities`), the built `spec.entities` array must not be empty.
-
-**Failure Symptom:** `${m.code}: entities EMPTY but source has ${srcEnt}`
-
-**Common Causes:**
-- Mapping didn't iterate over entities array
-- Fallback to `fields[]` when `attributes[]` is missing not working
-
-**Fix:** Check the entities mapping includes both `attributes[]` and `fields[]` fallback.
-
-### 5. Screens Count
-
-**Check:** If source file has screens (either `screens.screens[]` or `screens.sections[]`), the normalized `spec.screens[].resources[]` must have at least the same number of total resources.
-
-**Failure Symptom:** `${m.code}: screens EMPTY (0 resources) but source has ${srcScreens} screens/sections`
-
-**Common Causes:**
-- Format detection logic failed (neither Format A nor B found)
-- Screen format detection chose the wrong branch
-- `normalizeColumn`, `normalizeField`, `normalizeFilter` functions not applied
-
-**Fix:**
-1. Verify `mod.screens.screens` or `mod.screens.sections` exists
-2. Run format detection logic step-by-step
-3. Ensure screen resources are being pushed into the array
-
-### 6. Serialization Bug: [object Object]
-
-**Check:** useCases steps field must be a string (or converted to string via `.join()`). If it contains `[object Object]`, the steps array contains unconverted objects.
-
-**Failure Symptom:** `${m.code}: UC "${uc.name}" has [object Object] in steps — steps[] contains objects not strings`
-
-**Fix:** Ensure the mapping converts step objects to strings:
-```javascript
-steps: (uc.mainScenario || uc.steps || []).map(s =>
-  typeof s === 'string' ? s : (s.action || s.description || "")
-).join("\n")  // .join() is CRITICAL to convert array to string
-```
-
-## Resolution Workflow
-
-When self-check fails:
-
-1. **Identify failing module** from error message
-2. **Locate the source file** in `collected_data.modules[m.code]`
-3. **Compare field structure** between source and mapping code
-4. **Fix the mapping** (update field names, add fallbacks, fix type conversions)
-5. **Re-build moduleSpecs** for the failing module
-6. **Re-run self-check** to verify fix
-
-## Post-Check Actions
-
-If self-check **PASSES**:
-- Continue to step-03 (HTML rendering)
-- No further data validation needed
-
-If self-check **FAILS** with errors:
-- DO NOT proceed to rendering
-- Fix each error in the module build logic
-- Re-build affected moduleSpecs entries
-- Re-run self-check
-
-## Expected Output
-
-### Success Case
-
-No errors array or empty:
-```
-✅ Self-check PASSED — all modules have complete data
-```
-
-### Failure Case
-
-Display all errors:
-```
-⛔ SELF-CHECK FAILED — data loss detected:
-  - Employees: useCases EMPTY but source has 5
-  - Employees: UC "Create Employee" has [object Object] in steps — steps[] contains objects not strings
-  - Payroll: screens EMPTY (0 resources) but source has 3 screens/sections
-```
-
----
-
-## Design Rationale
-
-The self-check is **mandatory and blocking** because:
-
-1. **Silent data loss is worse than errors** — empty arrays are valid JavaScript but indicate a bug
-2. **Hard to debug later** — if screens/UC/BR are missing, the HTML viewer will appear empty but rendering code will work
-3. **Source of truth is always the collected files** — self-check compares against collected_data, not against user expectations
-4. **Early detection** — catch bugs in step-02 before they cascade into step-03 rendering