Merge pull request #790 from NordicSemiconductor/enhance/check_package_json_with_zod

Check `package.json` with zod

Author: datenreisender

Changelog.md

@@ -7,6 +7,22 @@ This project does _not_ adhere to
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html) but contrary to it
 every new version is a new major version.
 
+## 118 - 2023-10-13
+
+### Added
+
+-   Option to configure external React to support legacy apps in the launcher.
+
+### Changed
+
+-   Checking whether the `package.json` contains all required fields is now also
+    down before building.
+-   Use `zod` for the `package.json` schema for apps. This is used verify that
+    apps have the right fields in `package.json` and also generates the right
+    TypeScript type for it.
+-   `nrfConnectForDesktop.html` is not optional anymore, it must always be
+    specified in `package.json`.
+
 ## 117 - 2023-10-04
 
 ### Fixed
@@ -394,7 +410,7 @@ declare module '!!@svgr!*.svg' {
 ### Steps to upgrade when using this package
 
 -   Following this step will make the app incompatible with the currently
-    released launcher (v4.1.2): Add an `index`-property to package.json. The
+    released launcher (v4.1.2): Add an `html`-property to package.json. The
     following example will use the index bundled with shared that works with our
     apps, but apps can also make their own instead if needed.
 

ipc/MetaFiles.ts

@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: LicenseRef-Nordic-4-Clause
  */
 
-import { DevicePCA } from '../src/Device/deviceInfo/deviceInfo';
+import { z } from 'zod';
 
 export type UrlString = string;
 
@@ -40,49 +40,21 @@ export interface AppInfo {
     };
 }
 
-interface ObjectContainingOptionalStrings {
-    [index: string]: string | undefined;
-}
+export const semver = z.string().regex(
+    // From https://semver.org
+    /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$/,
+    'Is not a valid string for a semantic version'
+);
 
-interface NrfConnectForDesktop {
-    supportedDevices?: DevicePCA[];
-    nrfutil?: NrfutilModules;
-    html?: string;
-}
+const nrfutilModuleName = z.string();
+const nrfutilModuleVersion = semver;
 
-type SemverString = string;
+export type NrfutilModuleName = z.infer<typeof nrfutilModuleName>;
+export type NrfutilModuleVersion = z.infer<typeof nrfutilModuleVersion>;
 
-export type NrfutilModuleName = string;
-export type NrfutilModuleVersion = SemverString;
+export const nrfModules = z.record(
+    nrfutilModuleName,
+    nrfutilModuleVersion.array().nonempty()
+);
 
-export interface NrfutilModules {
-    [name: NrfutilModuleName]: [
-        NrfutilModuleVersion,
-        ...NrfutilModuleVersion[]
-    ];
-}
-
-export interface PackageJson {
-    name: string;
-    version: SemverString;
-
-    // Several optional properties
-    author?: string;
-    bin?: ObjectContainingOptionalStrings | string;
-    dependencies?: ObjectContainingOptionalStrings;
-    description?: string;
-    homepage?: UrlString;
-    devDependencies?: ObjectContainingOptionalStrings;
-    displayName?: string;
-    engines?: ObjectContainingOptionalStrings;
-    nrfConnectForDesktop?: NrfConnectForDesktop;
-    files?: readonly string[];
-    license?: string;
-    main?: string;
-    peerDependencies?: ObjectContainingOptionalStrings;
-    repository?: {
-        type: string;
-        url: UrlString;
-    };
-    scripts?: ObjectContainingOptionalStrings;
-}
+export type NrfutilModules = z.infer<typeof nrfModules>;

ipc/device.ts

@@ -0,0 +1,25 @@
+/*
+ * Copyright (c) 2023 Nordic Semiconductor ASA
+ *
+ * SPDX-License-Identifier: LicenseRef-Nordic-4-Clause
+ */
+
+export const knownDevicePcas = [
+    'PCA10028',
+    'PCA10031',
+    'PCA10040',
+    'PCA10056',
+    'PCA10059',
+    'PCA10090',
+    'PCA10095',
+    'PCA10100',
+    'PCA10121',
+    'PCA20020',
+    'PCA20035',
+    'PCA10143',
+    'PCA10152',
+    'PCA10153',
+    'PCA20049',
+] as const;
+
+export type KnownDevicePCA = (typeof knownDevicePcas)[number];

ipc/schema/packageJson.ts

@@ -0,0 +1,69 @@
+/*
+ * Copyright (c) 2023 Nordic Semiconductor ASA
+ *
+ * SPDX-License-Identifier: LicenseRef-Nordic-4-Clause
+ */
+
+import { z } from 'zod';
+
+import { knownDevicePcas } from '../device';
+import { nrfModules, semver } from '../MetaFiles';
+import { parseWithPrettifiedErrorMessage } from './parseJson';
+
+const nrfConnectForDesktop = z.object({
+    supportedDevices: z.enum(knownDevicePcas).array().nonempty().optional(),
+    nrfutil: nrfModules.optional(),
+    html: z.string(),
+});
+
+const recordOfOptionalStrings = z.record(z.string().optional());
+
+const engines = recordOfOptionalStrings.and(
+    z.object({ nrfconnect: z.string() })
+);
+
+const packageJson = z.object({
+    name: z.string(),
+    version: semver,
+
+    author: z.string().optional(),
+    bin: z.string().or(recordOfOptionalStrings).optional(),
+    dependencies: recordOfOptionalStrings.optional(),
+    description: z.string(),
+    homepage: z.string().url().optional(),
+    devDependencies: recordOfOptionalStrings.optional(),
+    displayName: z.string(),
+    engines,
+    nrfConnectForDesktop,
+    files: z.string().array().optional(),
+    license: z.string().optional(),
+    main: z.string().optional(),
+    peerDependencies: recordOfOptionalStrings.optional(),
+    repository: z
+        .object({
+            type: z.string(),
+            url: z.string().url(),
+        })
+        .optional(),
+    scripts: recordOfOptionalStrings.optional(),
+});
+
+export type PackageJson = z.infer<typeof packageJson>;
+
+export const parsePackageJson =
+    parseWithPrettifiedErrorMessage<PackageJson>(packageJson);
+
+// In the launcher we want to handle that the whole nrfConnectForDesktop may be missing
+// and the html in it can also be undefined, so there we need to use this legacy variant
+const legacyPackageJson = packageJson.merge(
+    z.object({
+        nrfConnectForDesktop: nrfConnectForDesktop
+            .partial({ html: true })
+            .optional(),
+    })
+);
+
+export type LegacyPackageJson = z.infer<typeof legacyPackageJson>;
+
+export const parseLegacyPackageJson =
+    parseWithPrettifiedErrorMessage<LegacyPackageJson>(legacyPackageJson);

ipc/schema/parseJson.ts

@@ -0,0 +1,27 @@
+/*
+ * Copyright (c) 2023 Nordic Semiconductor ASA
+ *
+ * SPDX-License-Identifier: LicenseRef-Nordic-4-Clause
+ */
+
+import { z } from 'zod';
+import { fromZodError } from 'zod-validation-error';
+
+export const parseWithPrettifiedErrorMessage =
+    <Out, T extends z.ZodType<Out> = z.ZodTypeAny>(schema: T) =>
+    (content: string) => {
+        const result = schema.safeParse(JSON.parse(content));
+
+        if (result.success) {
+            return result;
+        }
+
+        return {
+            ...result,
+            error: fromZodError(result.error, {
+                prefix: 'Error in package.json',
+                prefixSeparator: ':\n- ',
+                issueSeparator: '\n- ',
+            }),
+        };
+    };

main/index.ts

@@ -28,7 +28,20 @@ export const serialPort = {
     forRenderer: forRendererSerialPort,
 };
 
-export * from '../ipc/MetaFiles';
+export {
+    type AppInfo,
+    type NrfutilModuleName,
+    type NrfutilModules,
+    type NrfutilModuleVersion,
+    type SourceJson,
+    type WithdrawnJson,
+} from '../ipc/MetaFiles';
+export {
+    type LegacyPackageJson,
+    type PackageJson,
+    parseLegacyPackageJson,
+    parsePackageJson,
+} from '../ipc/schema/packageJson';
 
 export { type OverwriteOptions } from '../ipc/serialPort';
 export { type OpenAppOptions } from '../ipc/openWindow';

package-lock.json

@@ -1,6 +1,6 @@
 {
     "name": "@nordicsemiconductor/pc-nrfconnect-shared",
-    "version": "117.0.0",
+    "version": "118.0.0",
     "description": "Shared commodities for developing pc-nrfconnect-* packages",
     "repository": {
         "type": "git",
@@ -12,7 +12,7 @@
         "check-for-typescript": "./scripts/check-for-typescript.ts",
         "check-app-properties": "./scripts/check-app-properties.ts",
         "nrfconnect-license": "./scripts/nrfconnect-license.ts",
-        "run-esbuild": "./scripts/esbuild.js"
+        "run-esbuild": "./scripts/esbuild.ts"
     },
     "main": "src",
     "scripts": {
@@ -119,7 +119,9 @@
         "util": "0.12.5",
         "uuid": "8.3.2",
         "winston": "3.8.2",
-        "xterm-headless": "^5.3.0"
+        "xterm-headless": "^5.3.0",
+        "zod": "^3.22.2",
+        "zod-validation-error": "^1.5.0"
     },
     "typings": "./typings/generated/src/index.d.ts",
     "eslintConfig": {