Enhance Excel parsing: update constraints structure and add CLI for parsing Excel files

Author: m-houston

package-lock.json

@@ -10,7 +10,80 @@ A package for parsing and generating Excel files for NHS Notify supplier configu
 
 ## Usage
 
-### Parsing an Excel file
+### CLI Commands
+
+#### Parse Excel to JSON
+
+Parse an Excel file and output the parsed JSON data:
+
+```bash
+# Parse and output to stdout
+npm run parse -- config.xlsx
+
+# Parse and pretty-print to stdout
+npm run parse -- config.xlsx --pretty
+
+# Parse and save to file
+npm run parse -- config.xlsx -o output.json
+
+# Parse with pretty formatting and save to file
+npm run parse -- config.xlsx --pretty --output output.json
+
+# Show help
+npm run parse -- --help
+```
+
+**Options:**
+
+- `-o, --output <file>` - Write output to a file instead of stdout
+- `-p, --pretty` - Pretty-print the JSON output
+- `-h, --help` - Show help message
+
+**Output format:**
+
+The JSON output contains the following top-level keys:
+
+- `packs` - Record of PackSpecification objects keyed by ID
+- `variants` - Record of LetterVariant objects keyed by ID
+- `volumeGroups` - Record of VolumeGroup objects keyed by ID
+- `suppliers` - Record of Supplier objects keyed by ID
+- `allocations` - Record of SupplierAllocation objects keyed by ID
+- `supplierPacks` - Record of SupplierPack objects keyed by ID
+
+#### Generate Template
+
+Generate a template Excel file with the correct sheet structure and column headers:
+
+```bash
+# Generate a new template
+npm run template -- output.xlsx
+
+# Overwrite existing template
+npm run template -- output.xlsx --force
+
+# Show help
+npm run template -- --help
+```
+
+**Options:**
+
+- `-f, --force` - Overwrite existing file if it exists
+- `-h, --help` - Show help message
+
+**Generated sheets:**
+
+The template includes the following sheets with proper column headers:
+
+- `PackSpecification` - Pack specification definitions
+- `LetterVariant` - Letter variant configurations
+- `VolumeGroup` - Volume group definitions
+- `Supplier` - Supplier information
+- `SupplierAllocation` - Supplier allocation percentages
+- `SupplierPack` - Supplier-pack mappings
+
+### Programmatic Usage
+
+#### Parsing an Excel file
 
 ```typescript
 import { parseExcelFile } from "@nhs-notify/excel-parser";

packages/excel-parser/README.md

@@ -1,12 +1,53 @@
 import type { Config } from "jest";
 
 const config: Config = {
+  preset: "ts-jest",
+
+  // Automatically clear mock calls, instances, contexts and results before every test
+  clearMocks: true,
+
+  // Indicates whether the coverage information should be collected while executing the test
+  collectCoverage: true,
+
+  // The directory where Jest should output its coverage files
+  coverageDirectory: "./.reports/unit/coverage",
+
+  // Indicates which provider should be used to instrument code for coverage
+  coverageProvider: "v8",
+
+  coverageThreshold: {
+    global: {
+      branches: 100,
+      functions: 100,
+      lines: 100,
+      statements: -10,
+    },
+  },
+
+  coveragePathIgnorePatterns: ["/__tests__/"],
+
+  // Use this configuration option to add custom reporters to Jest
+  reporters: [
+    "default",
+    [
+      "jest-html-reporter",
+      {
+        pageTitle: "Test Report",
+        outputPath: "./.reports/unit/test-report.html",
+        includeFailureMsg: true,
+      },
+    ],
+  ],
+
   moduleNameMapper: {
     "^@supplier-config/excel-parser/(.*)$": "<rootDir>/src/$1",
   },
-  preset: "ts-jest",
+
   testEnvironment: "node",
   testPathIgnorePatterns: ["/node_modules/", "/dist/"],
+  testMatch: ["**/__tests__/**/*.ts", "**/?(*.)+(spec|test).ts"],
+  moduleFileExtensions: ["ts", "js", "json", "node"],
+
   transform: {
     "^.+\\.tsx?$": [
       "@swc/jest",

packages/excel-parser/jest.config.ts

@@ -2,6 +2,7 @@
   "dependencies": {
     "@nhsdigital/nhs-notify-event-schemas-supplier-config": "*",
     "xlsx": "^0.18.5",
+    "yargs": "^17.7.2",
     "zod": "^4.1.12"
   },
   "devDependencies": {
@@ -10,7 +11,9 @@
     "@tsconfig/node22": "^22.0.2",
     "@types/jest": "^29.5.14",
     "@types/xlsx": "^0.0.35",
+    "@types/yargs": "^17.0.33",
     "jest": "^29.7.0",
+    "jest-html-reporter": "^3.10.2",
     "jest-mock-extended": "^3.0.7",
     "typescript": "^5.9.3"
   },
@@ -20,6 +23,8 @@
     "build": "tsc",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
+    "parse": "tsx src/cli-parse.ts",
+    "template": "tsx src/cli-template.ts",
     "test": "jest",
     "test:unit": "jest",
     "typecheck": "tsc --noEmit"