Add support for static template generation control (#1674)

* Add support for static template generation control

- Add 'static' boolean flag to individual templates to mark them as static content
- Add 'generateStaticTemplates' generator option to control default behavior
- Static templates are skipped when generateStaticTemplates is false for the session
- Session-level .zap file settings can override the generator default

* Apply suggestions from code review

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
Co-authored-by: Copilot <[email protected]>

---------

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
Co-authored-by: Copilot <[email protected]>

Author: 3 people

apack.json

@@ -4,7 +4,7 @@
   "description": "Graphical configuration tool for application and libraries based on Zigbee Cluster Library.",
   "path": [".", "node_modules/.bin/", "ZAP.app/Contents/MacOS"],
   "requiredFeatureLevel": "apack.core:9",
-  "featureLevel": 108,
+  "featureLevel": 109,
   "uc.triggerExtension": "zap",
   "uc.sdkProvidedProperties": "zcl.matterZclJsonFile,zcl.matterTemplateJsonFile,zcl.zigbeeZclJsonFile,zcl.zigbeeTemplateJsonFile",
   "executable": {

docs/sdk-integration.md

@@ -79,6 +79,7 @@ The `templates` key contained in the `gen-templates.json` file above, is an arra
 | name     | string     | Human readable name of the template. Mostly used in logging and menu items.                                                                                                                                           |
 | output   | string     | Name of the output file generated. May contain replacement patterns (see below).                                                                                                                                      |
 | iterator | string     | If this template produces multiple files, iterating over certain object, then this field will be present. Possible values are `availableCluster`, `selectedCluster`,`selectedClientCluster`, `selectedServerCluster`. |
+| static   | string     | If set to the string 'true', marks this template as a static template. Static templates will not generate if `generateStaticTemplates` is false for the session.                                                                   |
 
 The _replacement pattern_ inside the output key, comes handy when iterator key is used and defines how each generated file will be named. Replacement patterns are in a format of `{key}` or `{key:modifier}`. The `key` can be any usual key that the iterated object provides. For example, if you iterate over cluster, these can be `code`, `name`, `description`, `define` and all the usual keys that a cluster supports. So if your output contains `{code}` then this pattern will be replaced by the actual cluster code.
 
@@ -105,6 +106,7 @@ Following table lists generator options supported by the template generator cate
 | postProcessSingle          | a string, representing a command to execute for each individual file appended in a single command line. This would be typically used by commands or scripts that clean up the generated files, and can only take one file name at a time as an argument.               |
 | postProcessConditionalFile | a path, representing a file. If this file does not exist, then a specified post-process action will not get executed.                                                                                                                                                  |
 | routeErrToOut              | a boolean flag. If it's set to true, then any stderr from the post-process will be routed to stdout. This is due that a driving process sometimes has trouble dealing with both stdout and stderr, so this flag might help you preserve the logs.                      |
+| generateStaticTemplates    | string     | A string flag ('true'/'false'). The default for whether static templates are generated. If 'false', they are not. A session-key in the .zap file can override this default.                                                                                        |
 
 ## Template key: override
 

src-electron/generator/generation-engine.js

@@ -204,19 +204,42 @@ async function recordTemplatesPackage(context, isTopLevelPackageInSync) {
           template.name
         ).then((id) => {
           // We loaded the individual file, now we add options
+          let optionPromises = []
+          // Handle iterator option
           if (template.iterator) {
-            return queryPackage.insertOptionsKeyValues(
-              context.db,
-              id,
-              dbEnum.packageOptionCategory.outputOptions,
-              [
-                {
-                  code: 'iterator',
-                  label: template.iterator
-                }
-              ]
+            optionPromises.push(
+              queryPackage.insertOptionsKeyValues(
+                context.db,
+                id,
+                dbEnum.packageOptionCategory.outputOptions,
+                [
+                  {
+                    code: 'iterator',
+                    label: template.iterator
+                  }
+                ]
+              )
+            )
+          }
+          // Handle static option
+          // If static is defined and true, then this template is only generated when generateStaticTemplates is true
+          // If static doesn't exist, we treat it as false
+          if (template.static) {
+            optionPromises.push(
+              queryPackage.insertOptionsKeyValues(
+                context.db,
+                id,
+                dbEnum.packageOptionCategory.generator,
+                [
+                  {
+                    code: 'static',
+                    label: template.static
+                  }
+                ]
+              )
             )
           }
+          return Promise.all(optionPromises)
         })
       )
     }
@@ -718,6 +741,19 @@ async function generateAllTemplates(
   let generationTemplates = []
   let overridePath = null
 
+  // generateStaticTemplates can be a session-key, if it exists then use it from session key otherwise use it from generatorOptions
+  let generateStaticTemplates = await querySession.getSessionKeyValue(
+    genResult.db,
+    genResult.sessionId,
+    dbEnum.sessionKey.generateStaticTemplates
+  )
+  if (generateStaticTemplates == null) {
+    generateStaticTemplates = genResult.generatorOptions.generateStaticTemplates
+  }
+  // Convert string values to proper boolean - generateStaticTemplates defaults to true unless explicitly set to false
+  generateStaticTemplates =
+    generateStaticTemplates !== 'false' && generateStaticTemplates !== false
+
   let hb = templateEngine.hbInstance()
   let context = {
     db: genResult.db,
@@ -736,8 +772,17 @@ async function generateAllTemplates(
         pkg.iterator = opt.optionLabel
       }
     })
+    let generatorOptions = await queryPackage.selectAllOptionsValues(
+      genResult.db,
+      pkg.id,
+      dbEnum.packageOptionCategory.generator
+    )
+    generatorOptions.forEach((opt) => {
+      if (opt.optionCode == 'static') {
+        pkg.static = opt.optionLabel
+      }
+    })
   }
-
   // First extract overridePath if one exists, as we need to
   // pass it to the generation.
   packages.forEach((singlePkg) => {
@@ -778,6 +823,10 @@ async function generateAllTemplates(
   // Next prepare the templates
   packages.forEach((singlePkg) => {
     if (singlePkg.type == dbEnum.packageType.genSingleTemplate) {
+      // Skip static templates if generateStaticTemplates is false
+      if (!generateStaticTemplates && singlePkg.static === 'true') {
+        return
+      }
       if (options.generateOnly == null) {
         generationTemplates.push(singlePkg)
       } else if (

src-shared/db-enum.js

@@ -105,7 +105,8 @@ exports.sessionKey = {
   filePath: 'filePath',
   ideProjectPath: 'ideProjectPath',
   informationText: 'informationText',
-  disableComponentToggling: 'disableComponentToggling'
+  disableComponentToggling: 'disableComponentToggling',
+  generateStaticTemplates: 'generateStaticTemplates'
 }
 
 exports.pathRelativity = {
@@ -145,7 +146,8 @@ exports.generatorOptions = {
   postProcessConditionalFile: 'postProcessConditionalFile',
   enabled: 'enabled',
   shareClusterStatesAcrossEndpoints: 'shareClusterStatesAcrossEndpoints',
-  disableUcComponentOnZclClusterUpdate: 'disableUcComponentOnZclClusterUpdate'
+  disableUcComponentOnZclClusterUpdate: 'disableUcComponentOnZclClusterUpdate',
+  generateStaticTemplates: 'generateStaticTemplates'
 }
 
 exports.sessionOption = {

test/gen-matter-1.test.js

@@ -184,7 +184,7 @@ test(
         queryPackage
           .selectAllOptionsValues(db, pkgId, 'generator')
           .then((generatorConfigurations) => {
-            expect(generatorConfigurations.length).toBe(1)
+            expect(generatorConfigurations.length).toBe(2)
             expect(generatorConfigurations[0].optionCode).toBe(
               'disableUcComponentOnZclClusterUpdate'
             )
@@ -355,3 +355,136 @@ test(
   },
   testUtil.timeout.long()
 )
+
+test(
+  'Zap file generation when generateStaticTemplates is false in zap file',
+  async () => {
+    let sessionId = await querySession.createBlankSession(db)
+
+    await importJs.importDataFromFile(
+      db,
+      testUtil.matterTestFile.matterTestNoStatic,
+      {
+        sessionId: sessionId
+      }
+    )
+
+    // Verify that the generateStaticTemplates session-key is actually false
+    let generateStaticTemplates = await querySession.getSessionKeyValue(
+      db,
+      sessionId,
+      'generateStaticTemplates'
+    )
+    expect(generateStaticTemplates).toBe('false')
+
+    let genResult = await genEngine.generate(
+      db,
+      sessionId,
+      templateContext.packageId,
+      {},
+      { disableDeprecationWarnings: true }
+    )
+
+    expect(genResult).not.toBeNull()
+    expect(genResult.partial).toBeFalsy()
+    expect(genResult.content).not.toBeNull()
+
+    // Verify that only non-static templates are generated
+    let contentKeys = Object.keys(genResult.content)
+    expect(contentKeys).toHaveLength(2)
+    expect(contentKeys).toContain('endpoints.out')
+    expect(contentKeys).toContain('endpoint-config.c')
+  },
+  testUtil.timeout.long()
+)
+
+test(
+  'Zap file generation when generateStaticTemplates is true in zap file but false in generator options',
+  async () => {
+    let sessionId = await querySession.createBlankSession(db)
+
+    await importJs.importDataFromFile(
+      db,
+      testUtil.matterTestFile.matterTestWithStatic,
+      {
+        sessionId: sessionId
+      }
+    )
+
+    // Verify that the generateStaticTemplates session-key is true
+    let generateStaticTemplates = await querySession.getSessionKeyValue(
+      db,
+      sessionId,
+      'generateStaticTemplates'
+    )
+    expect(generateStaticTemplates).toBe('true')
+
+    let genResult = await genEngine.generate(
+      db,
+      sessionId,
+      templateContext.packageId,
+      {},
+      { disableDeprecationWarnings: true }
+    )
+
+    expect(genResult).not.toBeNull()
+    expect(genResult.partial).toBeFalsy()
+    expect(genResult.content).not.toBeNull()
+
+    // Verify that all templates are generated
+    let contentKeys = Object.keys(genResult.content)
+    expect(contentKeys).toHaveLength(8)
+  },
+  testUtil.timeout.long()
+)
+
+test(
+  'Zap file generation with blank session with gen-template having generateStaticTemplates as false',
+  async () => {
+    // Load the matterNoStatic template context
+    let noStaticTemplateContext = await genEngine.loadTemplates(
+      db,
+      testUtil.testTemplate.matterNoStatic
+    )
+
+    expect(noStaticTemplateContext.crc).not.toBeNull()
+    expect(noStaticTemplateContext.templateData).not.toBeNull()
+    expect(noStaticTemplateContext.packageId).not.toBeNull()
+
+    // Create a blank session
+    let sessionId = await querySession.createBlankSession(db)
+
+    // Query generator options from the noStatic template
+    let genOptions = await queryPackage.selectAllOptionsValues(
+      db,
+      noStaticTemplateContext.packageId,
+      dbEnum.packageOptionCategory.generator
+    )
+
+    // Reduce the long array from query into a single object
+    let templateGeneratorOptions = genOptions.reduce((acc, current) => {
+      acc[current.optionCode] = current.optionLabel
+      return acc
+    }, {})
+
+    // Generate using the matterNoStatic template context
+    let genResult = await genEngine.generate(
+      db,
+      sessionId,
+      noStaticTemplateContext.packageId,
+      templateGeneratorOptions,
+      { disableDeprecationWarnings: true }
+    )
+
+    expect(genResult).not.toBeNull()
+    expect(genResult.partial).toBeFalsy()
+    expect(genResult.content).not.toBeNull()
+
+    // Verify that only non-static templates are generated
+    let contentKeys = Object.keys(genResult.content)
+    expect(contentKeys).toHaveLength(2)
+    expect(contentKeys).toContain('endpoints.out')
+    expect(contentKeys).toContain('endpoint-config.c')
+  },
+  testUtil.timeout.long()
+)

test/gen-template/matter/gen-test-no-static.json

@@ -0,0 +1,86 @@
+{
+  "name": "Matter test template",
+  "version": "test-matter",
+  "category": "matter",
+  "options": {
+    "testOption": {
+      "code1": "label1",
+      "code2": "label2",
+      "code3": "label3",
+      "code4": "label4",
+      "code5": "label5"
+    },
+    "externalOption": "externalOptions.json",
+    "cli": "cli.json",
+    "generator": {
+      "disableUcComponentOnZclClusterUpdate": "true",
+      "generateStaticTemplates": "false"
+    }
+  },
+  "zcl": {
+    "event": {
+      "testEventExtension1": {
+        "type": "text",
+        "configurability": "hidden",
+        "globalDefault": "defGlob",
+        "label": "Test event extensions",
+        "defaults": [
+          {
+            "clusterCode": "0x9999",
+            "eventCode": "0x0001",
+            "value": "defHello"
+          }
+        ]
+      }
+    }
+  },
+  "helpers": ["helper-chip.js", "external-addon-helper.js"],
+  "templates": [
+    {
+      "path": "simple-test.zapt",
+      "name": "Simple test template",
+      "output": "simple-test.h",
+      "static": "true"
+    },
+    {
+      "path": "sdk-ext.zapt",
+      "name": "SDK extension test",
+      "output": "sdk-ext.txt",
+      "static": "true"
+    },
+    {
+      "path": "feature-map.zapt",
+      "name": "Feature map test template",
+      "output": "feature-map.h",
+      "static": "true"
+    },
+    {
+      "path": "device-types.zapt",
+      "name": "Device types",
+      "output": "device-types.txt",
+      "static": "true"
+    },
+    {
+      "path": "endpoint-config.zapt",
+      "name": "Endpoint Configuration",
+      "output": "endpoint-config.c"
+    },
+    {
+      "path": "events.zapt",
+      "name": "Events",
+      "output": "events.out",
+      "static": "true"
+    },
+    {
+      "path": "endpoints.zapt",
+      "name": "Endpoints",
+      "output": "endpoints.out"
+    },
+    {
+      "path": "chip-tool-helpers.zapt",
+      "name": "Helpers in chip-tool",
+      "output": "chip-tool-helpers.txt",
+      "static": "true"
+    }
+  ]
+}