@atlashub/smartstack-cli 4.74.0 → 4.76.0

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

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

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

package/templates/skills/business-analyse-html/references/data-build.md

@@ -94,7 +94,8 @@ const FEATURE_DATA = {
   consolidation: {
     integrations: master.consolidation.crossModuleInteractions || [],
     sharedEntities: master.consolidation.sharedEntities || [],
-    sequenceDiagrams: master.consolidation.e2eFlows || []
+    sequenceDiagrams: master.consolidation.e2eFlows || [],
+    mermaidDiagrams: master.consolidation.mermaidDiagrams || {}
   },
   handoff: {
     complexity: master.handoff.complexity,
@@ -122,6 +123,28 @@ const FEATURE_DATA = {
 6. Extract consolidation data (integrations, shared entities, E2E flows)
 7. Extract handoff section (complexity, strategy, module order, file counts)
 
+### consolidation.mermaidDiagrams (Mermaid diagrams)
+
+Source: `consolidation.json`.mermaidDiagrams
+
+Generated by step-04-consolidate section 5b. Contains pre-built Mermaid diagram definitions
+for rendering in the HTML viewer.
+
+```javascript
+mermaidDiagrams: {
+  erd: consolidation.mermaidDiagrams?.erd || null,           // ERD string or null
+  mcd: consolidation.mermaidDiagrams?.mcd || null,           // MCD string or null
+  useCases: consolidation.mermaidDiagrams?.useCases || {},   // {moduleCode: mermaid_def}
+  stateMachines: consolidation.mermaidDiagrams?.stateMachines || {},  // {entity: mermaid_def}
+  sequences: consolidation.mermaidDiagrams?.sequences || {}          // {flowName: mermaid_def}
+}
+```
+
+Rendered by `12-render-diagrams.js`:
+- `erd` → inserted in `#dataModelContainer` (consol-datamodel section)
+- `stateMachines` → appended to `#dataModelContainer` per entity
+- `sequences` → appended to consol-flows section
+
 ## EMBEDDED_ARTIFACTS Object
 
 > **CRITICAL:** The wireframes object is keyed by moduleCode (NOT a flat array).