Add headless .zap validation, UI panel, and CLI improvements (#1704)

- Add validate-all session orchestration and GET /validate REST support
- Wire main-process startValidate: merged report, optional file or stdout
- CLI: register logToStdout; support multiple .zap paths (positionals, repeat
  -i, comma-separated for validate)
- Conformance: optional skip writing SESSION_NOTICE during bulk validate so that it does not go into session notifications on every run
- Validation: Matter root endpoint 0, session-wide duplicate check fix,
  external storage attribute skip; validate-all null endpoint pre-check
- UI: Validate in ZCL toolbar, side panel (ValidationPanelPage), layout/store
- Docs: add docs/validating-zap-files.md; trim README to link developer docs
- Tests: extend arg and validation tests; fix duplicate-endpoint test data

- Fixing float type attribute validation, float bounds from ZCL size, type-range fallback, and IEEE hex literals

- Add exit code error for the CLI option when validation fails

- For cli, when a .zap file is not mentioned give user the options that need to be speecified
- Github: ZAP #1678

Author: brdandu

README.md

@@ -37,6 +37,7 @@ This software is licensed under [Apache 2.0 license](LICENSE.txt).
 
 ## Detailed Developer Documentation
 
+- [Validating `.zap` files](docs/validating-zap-files.md)
 - [ZAP Template Helpers](docs/helpers.md)
 - [ZAP External Template Helpers](docs/external-helpers.md)
 - [ZAP file Extensions](docs/zap-file-extensions.md)

docs/api.md

@@ -0,0 +1,80 @@
+# Validating `.zap` files
+
+You can validate ZCL and data-model configuration in one or more `.zap` files without opening the UI. The same checks are available from the ZAP UI toolbar (**Validate**), which opens results in the side panel.
+
+## CLI
+
+### Synopsis
+
+```bash
+zap validate -i path/to/config.zap [-z zcl.json] [-g gen-templates.json] [-o report.json]
+```
+
+You can pass **more than one** `.zap` file in three ways:
+
+- **Space-separated** after `validate` (no `-i` per file): `validate first.zap second.zap`
+- **Comma-separated** in one argument: `validate -i first.zap,second.zap` (also works for a single `-i` value)
+- **Repeat** `-i` / `--in` / `--zap` for each file: `validate -i first.zap -i second.zap`
+
+One merged JSON (or YAML) report is written; it has a `zapFiles` array and one `results[]` entry per file.
+
+```bash
+node src-script/zap-start.js validate first.zap second.zap -o report.json
+# or
+node src-script/zap-start.js validate -i first.zap,second.zap -o report.json
+# or
+node src-script/zap-start.js validate -i first.zap -i second.zap -o report.json
+```
+
+### Options
+
+| Flag                                  | Meaning                                                                                                                                                                                                                                                                            |
+| ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `-i`, `--in`, `--zap`                 | Input `.zap` file. For `validate`, you may pass several paths: space-separated after the command, comma-separated in one `-i` value (e.g. `-i a.zap,b.zap`), or repeat this flag.                                                                                                  |
+| `-z`, `--zcl`, `--zclProperties`      | ZCL metafile(s), for example `./zcl-builtin/matter/zcl.json` or `./zcl-builtin/silabs/zcl.json`. Use these to validate against a specific ZCL definition instead of only the built-in default or whatever `zcl.properties` paths are embedded in the `.zap` file. May be repeated. |
+| `-g`, `--gen`, `--generationTemplate` | Generation template metafile(s), for example `./test/gen-template/matter/gen-test.json`. Overrides the built-in default and template references inside the `.zap` file for validation context. May be repeated.                                                                    |
+| `-o`, `--output`, `--validateOutput`  | Write the structured validation report to a file. Use a `.yaml` or `.yml` extension for YAML output. For the `validate` command, `-o` / `--output` is treated as the report path (not the generation output directory).                                                            |
+
+When **no** output path is given, the JSON report is printed to **stdout**. Progress and status messages go to **stderr** so you can redirect stdout to a file safely:
+
+```bash
+node src-script/zap-start.js validate -i path/to/config.zap > report.json
+```
+
+Exit code is **non-zero** when the report contains validation errors.
+
+### Running from this repository
+
+Use the start script so flags are passed straight through (avoiding `npm run` swallowing leading `-` flags):
+
+```bash
+node src-script/zap-start.js validate \
+  -i path/to/config.zap \
+  -z ./zcl-builtin/matter/zcl.json \
+  -g ./test/gen-template/matter/gen-test.json \
+  -o report.json
+```
+
+If you use `npm run zap-validate`, put **`--`** before script arguments so npm forwards `-i`, `-z`, `-g`, and `-o`:
+
+```bash
+npm run zap-validate -- -i path/to/config.zap -z path/to/zcl.json -g path/to/templates.json -o ./report.json
+```
+
+### Example: Matter / connectedhomeip
+
+When validating an app from [connectedhomeip](https://github.com/project-chip/connectedhomeip), point `-z` and `-g` at that tree’s ZCL and template metafiles so validation matches the SDK your app targets:
+
+```bash
+node src-script/zap-start.js validate \
+  -i examples/your-app/your-app.zap \
+  -z src/app/zap-templates/zcl/zcl.json \
+  -g src/app/zap-templates/app-templates.json \
+  -o ./report.json
+```
+
+Paths above are relative to the connectedhomeip repository root; adjust for your checkout.
+
+## Report format
+
+The report is JSON (or YAML if the output path ends in `.yaml` / `.yml`). It aggregates per-file results, summaries (error counts, endpoint/cluster/attribute counts), and detailed findings for endpoints, attributes, and conformance.

docs/validating-zap-files.md

@@ -69,6 +69,7 @@
     "zapmatter": "node src-script/zap-start.js --logToStdout --zcl ./zcl-builtin/matter/zcl.json --gen ./test/gen-template/matter/gen-test.json",
     "zapmeta": "node src-script/zap-start.js --logToStdout --zcl ./test/resource/meta/zcl.json --gen ./test/resource/meta/gen-test.json --in ./test/resource/test-meta.zap",
     "zaphelp": "node src-script/zap-start.js --help",
+    "zap-validate": "node src-script/zap-start.js validate",
     "zap-dotdot": "node src-script/zap-start.js --logToStdout --zcl ./zcl-builtin/dotdot/library.xml -g ./test/gen-template/dotdot/dotdot-templates.json",
     "zap-devserver": "node src-script/zap-start.js server --stateDirectory ~/.zap/zigbee-server/ --allowCors --logToStdout --gen ./test/gen-template/zigbee/gen-templates.json --reuseZapInstance",
     "zigbeezap-devserver": "node src-script/zap-start.js server --stateDirectory ~/.zap/zigbee-server/ --allowCors --logToStdout --gen ./test/gen-template/zigbee/gen-templates.json --reuseZapInstance",

package.json

@@ -42,6 +42,7 @@ const queryPackage = require('../db/query-package.js')
 const util = require('../util/util.js')
 const importJs = require('../importexport/import.js')
 const exportJs = require('../importexport/export.js')
+const validateAll = require('../validation/validate-all.js')
 const watchdog = require('./watchdog')
 const sdkUtil = require('../util/sdk-util')
 
@@ -629,6 +630,141 @@ async function startAnalyze(argv, options) {
   if (options.quitFunction != null) options.quitFunction()
 }
 
+/**
+ * Validate ZCL / data-model elements for one or more .zap files (headless).
+ *
+ * @param {*} argv
+ * @param {*} options
+ * @returns exit code 0 or 1 (1 if any attribute/endpoint validation errors)
+ */
+async function startValidate(argv, options) {
+  let paths = argv.zapFiles
+  options.logger(env.formatEmojiMessage('🤖', `Starting validation: ${paths}`))
+  let dbFile = env.sqliteFile('validate')
+  if (options.cleanDb && fs.existsSync(dbFile)) {
+    options.logger(env.formatEmojiMessage('🔧', 'remove old database file'))
+    fs.unlinkSync(dbFile)
+  }
+  let db = await dbApi.initDatabaseAndLoadSchema(
+    dbFile,
+    env.schemaFile(),
+    env.zapVersion()
+  )
+  options.logger(
+    env.formatEmojiMessage('🐝', 'database and schema initialized')
+  )
+  await zclLoader.loadZclMetafiles(db, argv.zclProperties, {
+    failOnLoadingError: !argv.noLoadingFailure
+  })
+  if (argv.generationTemplate != null) {
+    let ctx = await generatorEngine.loadTemplates(db, argv.generationTemplate, {
+      failOnLoadingError: !argv.noLoadingFailure
+    })
+    if (ctx.error) {
+      throw ctx.error
+    }
+  }
+
+  let exitCode = 0
+  const mergedReport = {
+    zapFiles: paths,
+    results: [],
+    summary: {
+      errors: 0,
+      warnings: 0,
+      attributes: 0,
+      endpoints: 0,
+      clusters: 0
+    }
+  }
+
+  await util.executePromisesSequentially(paths, async (singlePath) => {
+    let importResult = await importJs.importDataFromFile(db, singlePath, {
+      defaultZclMetafile: argv.zclProperties,
+      postImportScript: argv.postImportScript,
+      packageMatch: argv.packageMatch
+    })
+    let sessionId = importResult.sessionId
+    await util.ensurePackagesAndPopulateSessionOptions(db, sessionId, {
+      zcl: argv.zclProperties,
+      template: argv.generationTemplate
+    })
+    if (argv.postImportScript) {
+      await importJs.executePostImportScript(
+        db,
+        sessionId,
+        argv.postImportScript
+      )
+    }
+    const report = await validateAll.validateAll(db, sessionId, {
+      persistConformanceNotifications: false
+    })
+    const tagged = {
+      ...report,
+      zapFile: singlePath,
+      endpoints: report.endpoints.map((row) => ({
+        ...row,
+        zapFile: singlePath
+      })),
+      attributes: report.attributes.map((row) => ({
+        ...row,
+        zapFile: singlePath
+      })),
+      conformance: report.conformance.map((row) => ({
+        ...row,
+        zapFile: singlePath
+      }))
+    }
+    mergedReport.results.push(tagged)
+    mergedReport.summary.errors += report.summary.errors
+    mergedReport.summary.warnings += report.summary.warnings
+    mergedReport.summary.attributes += report.summary.attributes
+    mergedReport.summary.endpoints += report.summary.endpoints
+    mergedReport.summary.clusters += report.summary.clusters
+    if (report.summary.errors > 0) {
+      exitCode = 1
+    }
+
+    options.logger(
+      env.formatEmojiMessage(
+        '🔍',
+        `${singlePath}: errors=${report.summary.errors} warnings=${report.summary.warnings}`
+      )
+    )
+  })
+
+  options.logger(
+    env.formatEmojiMessage(
+      '🔧',
+      `Validation totals: errors=${mergedReport.summary.errors} warnings=${mergedReport.summary.warnings}`
+    )
+  )
+
+  if (argv.validateOutput != null) {
+    let outPath = argv.validateOutput
+    let ext = path.extname(outPath).toLowerCase()
+    let body =
+      ext === '.yaml' || ext === '.yml'
+        ? YAML.stringify(mergedReport)
+        : JSON.stringify(mergedReport, null, 2)
+    let parent = path.dirname(outPath)
+    if (!fs.existsSync(parent)) {
+      fs.mkdirSync(parent, { recursive: true })
+    }
+    await fsp.writeFile(outPath, body)
+    options.logger(
+      env.formatEmojiMessage('👉', `Wrote validation report: ${outPath}`)
+    )
+  } else {
+    process.stdout.write(JSON.stringify(mergedReport, null, 2) + '\n')
+  }
+
+  await dbApi.closeDatabase(db)
+  options.logger(env.formatEmojiMessage('🔧', 'Validation done!'))
+  if (options.quitFunction != null) options.quitFunction()
+  return exitCode
+}
+
 /**
  * Starts zap in a server mode.
  *
@@ -1197,13 +1333,62 @@ async function startUpMainInstance(argv, callbacks) {
     }
     return startSelfCheck(argv, options)
   } else if (argv._.includes('analyze')) {
-    if (argv.zapFiles.length < 1)
-      throw 'You need to specify at least one zap file.'
+    if (argv.zapFiles.length < 1) {
+      console.error(
+        'Error: You need to specify at least one zap file.\n\n' +
+          'Usage:\n' +
+          '  npm run zap-analyze -- [options] <file.zap> [<file.zap> ...]\n\n' +
+          'Options:\n' +
+          '  -i, --in, --zap          Input .zap file(s). May be repeated or comma-separated.\n' +
+          '  -z, --zcl                ZCL metafile (e.g. zcl-builtin/silabs/zcl.json). May be repeated.\n' +
+          '  -g, --gen                Generation template metafile (e.g. gen-templates.json). May be repeated.\n'
+      )
+      cleanExit(argv.cleanupDelay, 1)
+      return
+    }
     let options = {
       quitFunction: quitFunction,
       logger: console.log
     }
     return startAnalyze(argv, options)
+  } else if (argv._.includes('validate')) {
+    if (argv.zapFiles.length < 1) {
+      console.error(
+        'Error: You need to specify at least one zap file.\n\n' +
+          'Usage:\n' +
+          '  npm run zap-validate -- [options] <file.zap> [<file.zap> ...]\n\n' +
+          'Options:\n' +
+          '  -i, --in, --zap          Input .zap file(s). May be repeated or comma-separated.\n' +
+          '  -z, --zcl                ZCL metafile (e.g. zcl-builtin/silabs/zcl.json). May be repeated.\n' +
+          '  -g, --gen                Generation template metafile (e.g. gen-templates.json). May be repeated.\n' +
+          '  -o, --validateOutput     Write validation report to a file (.json or .yaml). Defaults to stdout.\n'
+      )
+      cleanExit(argv.cleanupDelay, 1)
+      return
+    }
+    // When no report file is given, the JSON report goes to stdout, so route
+    // status messages to stderr to keep stdout clean and pipe-friendly.
+    // quitFunction is intentionally omitted here so that startValidate returns
+    // the numeric exit code rather than calling process.exit(0) prematurely.
+    // cleanExit below propagates the code to CI callers.
+    let options = {
+      quitFunction: null,
+      logger: argv.validateOutput == null ? console.error : console.log
+    }
+    return startValidate(argv, options)
+      .then((code) => {
+        if (code !== 0) {
+          env.printToStderr(
+            `Validation completed with errors (exit code ${code}). Check the report for details.`
+          )
+        }
+        cleanExit(argv.cleanupDelay, code)
+      })
+      .catch((err) => {
+        console.log(err)
+        env.printToStderr(`Zap validation error: ${err}`)
+        cleanExit(argv.cleanupDelay, 1)
+      })
   } else if (argv._.includes('server')) {
     return startServer(argv, quitFunction)
   } else if (argv._.includes('convert')) {
@@ -1289,6 +1474,7 @@ exports.startSelfCheck = startSelfCheck
 exports.clearDatabaseFile = clearDatabaseFile
 exports.startConvert = startConvert
 exports.startAnalyze = startAnalyze
+exports.startValidate = startValidate
 exports.startUpMainInstance = startUpMainInstance
 exports.startUpSecondaryInstance = startUpSecondaryInstance
 exports.shutdown = shutdown

src-electron/main-process/startup.js

@@ -37,6 +37,7 @@ const querySession = require('../db/query-session.js')
 const queryPackage = require('../db/query-package.js')
 const asyncValidation = require('../validation/async-validation.js')
 const validation = require('../validation/validation.js')
+const validateAll = require('../validation/validate-all.js')
 const restApi = require('../../src-shared/rest-api.js')
 const zclLoader = require('../zcl/zcl-loader.js')
 const dbEnum = require('../../src-shared/db-enum.js')
@@ -1136,6 +1137,28 @@ function httpGetConformDataExists(db) {
   }
 }
 
+/**
+ * HTTP GET: validate entire session (all endpoints, attribute defaults, conformance).
+ *
+ * @param {*} db
+ * @returns callback for the express uri registration
+ */
+function httpGetValidateAll(db) {
+  return async (request, response) => {
+    try {
+      const report = await validateAll.validateAll(db, request.zapSessionId, {
+        persistConformanceNotifications: false
+      })
+      response.status(StatusCodes.OK).json(report)
+    } catch (err) {
+      env.logError(err)
+      response.status(StatusCodes.INTERNAL_SERVER_ERROR).json({
+        error: err.message || String(err)
+      })
+    }
+  }
+}
+
 /**
  * Set warning for the required element, and delete its existing warning if any.
  *
@@ -1332,6 +1355,10 @@ exports.get = [
     uri: restApi.uri.conformDataExists,
     callback: httpGetConformDataExists
   },
+  {
+    uri: restApi.uri.validate,
+    callback: httpGetValidateAll
+  },
   {
     uri: restApi.uri.featureMapAttribute,
     callback: httpGetFeatureMapAttribute