Fix readSettingsFile to handle the keyed-object stages shape

Discovered while validating PR #170 against the real Citizens portal site
(C:\Projects\Citizens portal). The site's deployment-settings.json uses
the Microsoft-standard 2024 schema shape:

  {
    "$schema": "https://schemas.microsoft.com/power-platform/deployment-settings/2024",
    "stages": {
      "Deploy to Staging": {
        "EnvironmentVariables": [...]
      }
    }
  }

— a keyed OBJECT of stages. readSettingsFile only handled two shapes:
1. Top-level `EnvironmentVariables: []` (single-stage)
2. `Stages: []` array with `{ Name, EnvironmentVariables }` entries

The keyed-object shape returned 0 entries, which meant
validate-deployment-settings.js silently passed even on known-broken
values like `@KeyVault(vaultName=...;secretName=...)`.

Real-world evidence: the Citizens portal's docs/alm/last-deploy.json
records a failed deploy attempt (2026-05-21) where deployment-settings.json
contained `@KeyVault(...)` for c311_api_secret. The pre-deploy validator
"validation passed (validation does not check Secret reference format)"
— because the parser couldn't read the file. The deploy then waited ~4h
in the host queue before failing with `ImportAsHolding failed: The value
provided as a secret reference does not match a valid secret reference
format`. This is exactly what the v3 deploy-pipeline:7.6.4.strip-secret-
values gate is supposed to prevent — but the gate's underlying validator
was broken.

Changes:

- readSettingsFile now handles all three shapes. Each returned entry
  now carries `stageLabel` (null for shape 1, the stage name for shapes
  2 and 3), so downstream consumers can attribute findings to the right
  stage without re-parsing the file.

- validate-deployment-settings.js had a duplicated read-settings parser
  (readEntriesPreservingStage) with the same bug. Deleted — it now
  uses readSettingsFile directly.

- Tests:
  - Existing readSettingsFile tests updated to expect the new stageLabel
    field on entries.
  - New test: keyed-object shape (Microsoft 2024 schema). Validates the
    real-world fix against a fixture matching the Citizens portal file.
  - validate-deployment-settings.test.js renamed readEntriesPreservingStage
    references to readSettingsFile.

Verified end-to-end against the real Citizens portal file:

  node validate-deployment-settings.js --settingsFile <citizens-portal>
  → summary { invalid: 1 }, one finding flagging the @KeyVault(...) value
    on c311_api_secret as 'kv-placeholder' / 'invalid'.

Plugin tests: 993/993 (was 992; +1 new shape-3 test).
Lint: 0 findings.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: tyaginidhi

plugins/power-pages/scripts/lib/validate-deployment-settings.js

@@ -326,45 +326,13 @@ function parseArgs(argv) {
   return out;
 }
 
-// Read entries from the settings file, preserving stage attribution so
-// findings can report which stage a bad value lives in (matters in
-// multi-stage files where the same schema may be valid for one stage
-// and broken for another).
-function readEntriesPreservingStage(filePath, stageLabel) {
-  // verify-env-var-values.js exports readSettingsFile, which returns
-  // `[{ schemaName, value }]` after filtering by stageLabel — but loses
-  // the stage attribution. Re-read here so we can tag each finding with
-  // its stage when it came from a Stages[]-shaped file without a filter.
-  const fs = require('fs');
-  let parsed;
-  try {
-    parsed = JSON.parse(fs.readFileSync(filePath, 'utf8'));
-  } catch (err) {
-    throw new Error(`could not read --settingsFile ${filePath}: ${err.message}`);
-  }
-  const out = [];
-  if (Array.isArray(parsed.Stages)) {
-    for (const stage of parsed.Stages) {
-      if (stageLabel && (stage.Name || '').toLowerCase() !== stageLabel.toLowerCase()) continue;
-      if (!Array.isArray(stage.EnvironmentVariables)) continue;
-      for (const ev of stage.EnvironmentVariables) {
-        out.push({ schemaName: ev.SchemaName, value: ev.Value, stageLabel: stage.Name || null });
-      }
-    }
-    return out;
-  }
-  if (Array.isArray(parsed.EnvironmentVariables)) {
-    for (const ev of parsed.EnvironmentVariables) {
-      out.push({ schemaName: ev.SchemaName, value: ev.Value, stageLabel: null });
-    }
-    return out;
-  }
-  return [];
-}
-
+// Entry reader: delegates to verify-env-var-values.js#readSettingsFile,
+// which handles all three deployment-settings.json shapes and now returns
+// `{ schemaName, value, stageLabel }` on each entry (so we don't need a
+// duplicate parser to preserve stage attribution).
 async function validateSettings({ settingsFile, envUrl, stageLabel, token }) {
   if (!settingsFile) throw new Error('--settingsFile is required');
-  const entries = readEntriesPreservingStage(settingsFile, stageLabel);
+  const entries = readSettingsFile(settingsFile, stageLabel);
 
   // Collect unique schema names for the type lookup pass.
   const uniqueSchemas = Array.from(new Set(entries.map((e) => e.schemaName).filter(Boolean)));
@@ -452,7 +420,6 @@ module.exports = {
   classifyEntry,
   classifyValueFormat,
   lookupTypes,
-  readEntriesPreservingStage,
   KV_URI_PATTERN,
   KV_RESOURCE_ID_PATTERN,
   KV_PLACEHOLDER_PATTERNS,

plugins/power-pages/scripts/lib/verify-env-var-values.js

@@ -87,10 +87,17 @@ function parseArgs(argv) {
 }
 
 // Read EnvironmentVariables[] from a Microsoft-standard deployment-settings.json.
-// Supports two shapes that appear in the wild:
-//   - Top-level `EnvironmentVariables: [{ SchemaName, Value }, ...]` (single-stage file)
-//   - Per-stage `Stages: [{ Name, EnvironmentVariables: [...] }, ...]` (multi-stage file)
-// Returns `[{ schemaName, value }]` filtered to stageLabel when provided.
+// Supports three shapes that appear in the wild:
+//   1. Top-level `EnvironmentVariables: [{ SchemaName, Value }, ...]` (single-stage file)
+//   2. Per-stage array: `Stages: [{ Name, EnvironmentVariables: [...] }, ...]`
+//      (capital-S, used by some hand-authored files)
+//   3. Per-stage keyed object: `stages: { "<stage name>": { EnvironmentVariables: [...] } }`
+//      (lowercase-s, the actual schema emitted by configure-env-variables and
+//      consumed by Power Platform Pipelines — see schemas.microsoft.com/
+//      power-platform/deployment-settings/2024. Discovered as a real-world gap
+//      against the Citizens portal site, 2026-05-26.)
+// Returns `[{ schemaName, value, stageLabel }]` filtered to stageLabel when provided.
+// stageLabel is included on each entry for shape 2/3; shape 1 sets stageLabel: null.
 function readSettingsFile(filePath, stageLabel) {
   let raw;
   try {
@@ -105,35 +112,81 @@ function readSettingsFile(filePath, stageLabel) {
     throw new Error(`--settingsFile ${filePath} is not valid JSON: ${err.message}`);
   }
 
-  // Per-stage shape
+  const lowerLabel = stageLabel ? stageLabel.toLowerCase() : null;
+
+  // Shape 2: per-stage array (`Stages: []`)
   if (Array.isArray(parsed.Stages)) {
-    if (!stageLabel) {
-      // No filter — flatten all stages
+    if (!lowerLabel) {
       const all = [];
       for (const stage of parsed.Stages) {
         if (Array.isArray(stage.EnvironmentVariables)) {
           for (const ev of stage.EnvironmentVariables) {
-            all.push({ schemaName: ev.SchemaName, value: ev.Value });
+            all.push({
+              schemaName: ev.SchemaName,
+              value: ev.Value,
+              stageLabel: stage.Name || null,
+            });
           }
         }
       }
       return dedupeBySchemaName(all);
     }
     const stage = parsed.Stages.find(
-      (s) => (s.Name || '').toLowerCase() === stageLabel.toLowerCase()
+      (s) => (s.Name || '').toLowerCase() === lowerLabel
+    );
+    if (!stage || !Array.isArray(stage.EnvironmentVariables)) return [];
+    return stage.EnvironmentVariables.map((ev) => ({
+      schemaName: ev.SchemaName,
+      value: ev.Value,
+      stageLabel: stage.Name || null,
+    }));
+  }
+
+  // Shape 3: per-stage keyed object (`stages: { "<name>": {...} }`).
+  // This is the schema emitted by configure-env-variables and the one
+  // Power Platform Pipelines actually accepts. Accept either casing of
+  // the `stages`/`Stages` key + match stage labels case-insensitively.
+  const stagesObj = parsed.stages || parsed.STAGES;
+  if (
+    stagesObj &&
+    typeof stagesObj === 'object' &&
+    !Array.isArray(stagesObj)
+  ) {
+    if (!lowerLabel) {
+      const all = [];
+      for (const [name, stage] of Object.entries(stagesObj)) {
+        if (stage && Array.isArray(stage.EnvironmentVariables)) {
+          for (const ev of stage.EnvironmentVariables) {
+            all.push({
+              schemaName: ev.SchemaName,
+              value: ev.Value,
+              stageLabel: name,
+            });
+          }
+        }
+      }
+      return dedupeBySchemaName(all);
+    }
+    // Case-insensitive key match
+    const matchKey = Object.keys(stagesObj).find(
+      (k) => k.toLowerCase() === lowerLabel
     );
+    if (!matchKey) return [];
+    const stage = stagesObj[matchKey];
     if (!stage || !Array.isArray(stage.EnvironmentVariables)) return [];
     return stage.EnvironmentVariables.map((ev) => ({
       schemaName: ev.SchemaName,
       value: ev.Value,
+      stageLabel: matchKey,
     }));
   }
 
-  // Top-level shape
+  // Shape 1: top-level `EnvironmentVariables: []` (single-stage file)
   if (Array.isArray(parsed.EnvironmentVariables)) {
     return parsed.EnvironmentVariables.map((ev) => ({
       schemaName: ev.SchemaName,
       value: ev.Value,
+      stageLabel: null,
     }));
   }
   return [];

plugins/power-pages/scripts/tests/validate-deployment-settings.test.js

@@ -11,10 +11,13 @@ const {
   validateSettings,
   classifyEntry,
   classifyValueFormat,
-  readEntriesPreservingStage,
   KV_URI_PATTERN,
   KV_RESOURCE_ID_PATTERN,
 } = require('../lib/validate-deployment-settings');
+// The duplicated readSettingsFile was removed in favor of
+// verify-env-var-values#readSettingsFile, which now returns stageLabel on
+// each entry. Tests below exercise the unified parser via its new home.
+const { readSettingsFile } = require('../lib/verify-env-var-values');
 
 function withTempDir(t) {
   const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'validate-settings-'));
@@ -229,42 +232,42 @@ test('classifyEntry: unknown type with regular value falls back to unknown-type'
 // File parsing — preserving stage attribution
 // ────────────────────────────────────────────────────────────────────────────
 
-test('readEntriesPreservingStage handles top-level shape (no stages)', (t) => {
+test('readSettingsFile handles top-level shape (no stages)', (t) => {
   const dir = withTempDir(t);
   const file = writeSettings(dir, {
     EnvironmentVariables: [
       { SchemaName: 'a', Value: 'va' },
       { SchemaName: 'b', Value: 'vb' },
     ],
   });
-  const entries = readEntriesPreservingStage(file);
+  const entries = readSettingsFile(file);
   assert.equal(entries.length, 2);
   assert.equal(entries[0].stageLabel, null);
 });
 
-test('readEntriesPreservingStage preserves stage names in Stages[] shape', (t) => {
+test('readSettingsFile preserves stage names in Stages[] shape', (t) => {
   const dir = withTempDir(t);
   const file = writeSettings(dir, {
     Stages: [
       { Name: 'Staging', EnvironmentVariables: [{ SchemaName: 'a', Value: 'sa' }] },
       { Name: 'Production', EnvironmentVariables: [{ SchemaName: 'b', Value: 'pb' }] },
     ],
   });
-  const entries = readEntriesPreservingStage(file);
+  const entries = readSettingsFile(file);
   assert.equal(entries.length, 2);
   assert.equal(entries[0].stageLabel, 'Staging');
   assert.equal(entries[1].stageLabel, 'Production');
 });
 
-test('readEntriesPreservingStage filters by stageLabel (case-insensitive)', (t) => {
+test('readSettingsFile filters by stageLabel (case-insensitive)', (t) => {
   const dir = withTempDir(t);
   const file = writeSettings(dir, {
     Stages: [
       { Name: 'Staging', EnvironmentVariables: [{ SchemaName: 'a', Value: 'sa' }] },
       { Name: 'Production', EnvironmentVariables: [{ SchemaName: 'b', Value: 'pb' }] },
     ],
   });
-  const entries = readEntriesPreservingStage(file, 'production');
+  const entries = readSettingsFile(file, 'production');
   assert.equal(entries.length, 1);
   assert.equal(entries[0].schemaName, 'b');
 });

plugins/power-pages/scripts/tests/verify-env-var-values.test.js

@@ -97,8 +97,8 @@ test('readSettingsFile reads top-level EnvironmentVariables shape', async (t) =>
   );
   const entries = readSettingsFile(file);
   assert.deepEqual(entries, [
-    { schemaName: 'foo_a', value: 'a-value' },
-    { schemaName: 'foo_b', value: 'b-value' },
+    { schemaName: 'foo_a', value: 'a-value', stageLabel: null },
+    { schemaName: 'foo_b', value: 'b-value', stageLabel: null },
   ]);
 });
 
@@ -125,7 +125,9 @@ test('readSettingsFile filters Stages[] by stageLabel (case-insensitive)', async
     })
   );
   const stagingEntries = readSettingsFile(file, 'staging');
-  assert.deepEqual(stagingEntries, [{ schemaName: 'foo_a', value: 'staging-a' }]);
+  assert.deepEqual(stagingEntries, [
+    { schemaName: 'foo_a', value: 'staging-a', stageLabel: 'Staging' },
+  ]);
   const prodEntries = readSettingsFile(file, 'Production');
   assert.equal(prodEntries.length, 2);
   assert.equal(prodEntries[1].value, 'prod-b');
@@ -151,6 +153,47 @@ test('readSettingsFile with no stageLabel flattens Stages[]', async (t) => {
   assert.equal(entries[1].schemaName, 'foo_b');
 });
 
+test('readSettingsFile reads keyed-object Stages shape (Microsoft schema 2024)', async (t) => {
+  // The Microsoft-standard `deployment-settings/2024` schema and the file
+  // configure-env-variables emits use a KEYED OBJECT for stages, not an
+  // array. Real-world discovery against C:/Projects/Citizens portal — pre-fix,
+  // readSettingsFile returned 0 entries for this shape, which made
+  // validate-deployment-settings.js silently pass even for known-broken
+  // values like `@KeyVault(...)`.
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'verify-env-'));
+  t.after(() => fs.rmSync(dir, { recursive: true, force: true }));
+  const file = path.join(dir, 'deployment-settings.json');
+  fs.writeFileSync(
+    file,
+    JSON.stringify({
+      $schema: 'https://schemas.microsoft.com/power-platform/deployment-settings/2024',
+      stages: {
+        'Deploy to Staging': {
+          EnvironmentVariables: [
+            { SchemaName: 'c311_label', Value: 'Staging' },
+            {
+              SchemaName: 'c311_api_secret',
+              Value: '@KeyVault(vaultName=lakeshore-staging-kv;secretName=api-secret)',
+            },
+          ],
+          ConnectionReferences: [],
+        },
+      },
+    })
+  );
+  const all = readSettingsFile(file);
+  assert.equal(all.length, 2);
+  assert.equal(all[0].schemaName, 'c311_label');
+  assert.equal(all[0].stageLabel, 'Deploy to Staging');
+  assert.equal(all[1].schemaName, 'c311_api_secret');
+  // stageLabel filter (case-insensitive on the stage-name key)
+  const filtered = readSettingsFile(file, 'deploy to staging');
+  assert.equal(filtered.length, 2);
+  assert.equal(filtered[0].stageLabel, 'Deploy to Staging');
+  // Unknown stage label → empty
+  assert.equal(readSettingsFile(file, 'nope').length, 0);
+});
+
 test('readSettingsFile throws on missing file', () => {
   assert.throws(() => readSettingsFile('/tmp/nonexistent-deployment-settings.json'));
 });