fix(vba): strip a UTF-8 BOM before parsing Dysflow JSON artifacts

`.json` is not in VBA_FAMILY_RE, so test manifests and test sequences are
read with a plain utf-8 readFile and never pass through readVbaSource,
which is what strips the BOM for the rest of the VBA family. Node keeps
the mark as a leading \uFEFF and JSON.parse rejects it, so a
BOM-carrying manifest produced no file node and no vba-test-manifest
references at all — only a warning-severity parse error. PowerShell 5.1
writes that BOM by default for -Encoding UTF8, so hand-edited manifests
hit this routinely on Windows.

Add stripJsonBom in a dedicated json-source module and apply it in both
extractors. It is deliberately not folded into vba-source.ts: JSON is
UTF-8 by specification, so the CP1252 fallback there would accept a
mis-encoded manifest as silently wrong data instead of failing loudly.

Malformed JSON still reports the same warning-severity parse_error, and
a BOM does not carry a wrong-shaped document past the content gates.

Refs #316

Author: ardelperal

CHANGELOG.md

@@ -13,6 +13,7 @@ and adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 - Fork documentation now describes v1.17.1 capabilities and pins the integrated upstream v1.4.1 lineage, replacing stale version, feature-parity, and implementation-plan claims. (#312)
 - Dysflow exports are no longer read twice. Every form and report layout, test manifest and test sequence was being parsed once by the VBA dispatcher and again by the Dysflow framework hook, which made a full index do double the work on those files and left duplicate pending references behind. Turning Dysflow expansion off with `vba.dysflowExport: false` is also honoured again in every case. (#314)
+- A test manifest or test sequence saved with a UTF-8 byte-order mark is read correctly again. Until now such a file was rejected outright, so every test it registered quietly vanished from the graph with nothing but a warning to show for it — and on Windows that mark is what PowerShell writes by default. (#316)
 
 ## [1.17.1] - 2026-09-12
 

__tests__/extraction-vba-test-manifest.test.ts

@@ -139,3 +139,43 @@ describe('VbaTestManifestExtractor — manifest references (SUB-2)', () => {
     expect(refs.map((u) => u.referenceName)).toEqual(['Test_Ok']);
   });
 });
+
+describe('issue #316 — a UTF-8 BOM must not discard a manifest', () => {
+  // `.json` is not in VBA_FAMILY_RE, so manifests are read as plain UTF-8 and
+  // Node keeps the BOM as a leading . `JSON.parse` rejects it, which used
+  // to turn a valid manifest into a warning and zero references. PowerShell 5.1
+  // writes that BOM by default for `-Encoding UTF8`.
+  const MANIFEST = JSON.stringify({
+    tests: [{ procedure: 'Test_Bom_RunAll', name: 'bom', tags: ['smoke'] }],
+  });
+
+  it('emits the same nodes and references as the same manifest without a BOM', () => {
+    const plain = extract('tests/tests.vba.bom.json', MANIFEST);
+    const withBom = extract('tests/tests.vba.bom.json', '' + MANIFEST);
+
+    expect(withBom.errors).toEqual([]);
+    expect(withBom.nodes.map((n) => n.id)).toEqual(plain.nodes.map((n) => n.id));
+    expect(withBom.unresolvedReferences).toEqual(plain.unresolvedReferences);
+    expect(
+      withBom.unresolvedReferences.map((u) => u.referenceName),
+    ).toEqual(['Test_Bom_RunAll']);
+  });
+
+  it('still reports genuinely malformed JSON as a warning with no nodes', () => {
+    const r = extract('tests/tests.vba.broken.json', '{ "tests": [');
+    expect(r.nodes).toEqual([]);
+    expect(r.errors).toHaveLength(1);
+    expect(r.errors[0]?.severity).toBe('warning');
+    expect(r.errors[0]?.code).toBe('parse_error');
+  });
+
+  it('does not let a BOM sneak a wrong-shaped JSON past the content gate', () => {
+    const r = extract(
+      'tests/tests.vba.notamanifest.json',
+      '' + JSON.stringify({ slices: [{ submanifests: [] }] }),
+    );
+    expect(r.nodes).toEqual([]);
+    expect(r.unresolvedReferences).toEqual([]);
+    expect(r.errors).toEqual([]);
+  });
+});

__tests__/extraction-vba-test-sequence.test.ts

@@ -312,4 +312,44 @@ describe('VbaTestSequenceExtractor — resolver integration', () => {
 
     await cg.destroy();
   });
-});
+});
+
+describe('issue #316 — a UTF-8 BOM must not discard a sequence', () => {
+  // Same failure mode as the test manifests: `sequences/*.json` is read as
+  // plain UTF-8, Node keeps the leading , and `JSON.parse` rejects it.
+  const SEQUENCE = JSON.stringify({
+    description: 'bom',
+    runnerPolicy: { tool: 'dysflow', sequential: true },
+    procedures: ['Test_Bom_RunSlice', 'Test_Bom_Reset'],
+  });
+
+  it('emits the same nodes and references as the same sequence without a BOM', () => {
+    const plain = extract('tests/sequences/bom.json', SEQUENCE);
+    const withBom = extract('tests/sequences/bom.json', '' + SEQUENCE);
+
+    expect(withBom.errors).toEqual([]);
+    expect(withBom.nodes.map((n) => n.id)).toEqual(plain.nodes.map((n) => n.id));
+    expect(withBom.unresolvedReferences).toEqual(plain.unresolvedReferences);
+    expect(
+      withBom.unresolvedReferences.map((u) => u.referenceName),
+    ).toEqual(['Test_Bom_RunSlice', 'Test_Bom_Reset']);
+  });
+
+  it('still reports genuinely malformed JSON as a warning with no nodes', () => {
+    const r = extract('tests/sequences/broken.json', '{ "procedures": [');
+    expect(r.nodes).toEqual([]);
+    expect(r.errors).toHaveLength(1);
+    expect(r.errors[0]?.severity).toBe('warning');
+    expect(r.errors[0]?.code).toBe('parse_error');
+  });
+
+  it('does not let a BOM sneak the strict-sequence shape past the content gate', () => {
+    const r = extract(
+      'tests/sequences/strict.json',
+      '' + JSON.stringify({ executionUnits: ['tests/tests.vba.json'] }),
+    );
+    expect(r.nodes).toEqual([]);
+    expect(r.unresolvedReferences).toEqual([]);
+    expect(r.errors).toEqual([]);
+  });
+});

src/extraction/json-source.ts

@@ -0,0 +1,29 @@
+/**
+ * Decoding helpers for the JSON artifacts Dysflow writes beside a VBA export
+ * (`tests(.<slice>)*.json` test manifests, `sequences/*.json` test sequences).
+ *
+ * These are the only indexed files that are parsed as JSON rather than scanned
+ * as text, and they are deliberately NOT part of `isVbaFamilyFile` — JSON is
+ * UTF-8 by specification, so the CP1252 fallback in `readVbaSource` would turn
+ * a mis-encoded manifest into silently wrong data instead of a loud parse
+ * error. What they do share with the rest of the VBA family is the byte-order
+ * mark.
+ */
+
+/**
+ * Strip a leading UTF-8 BOM from already-decoded JSON text.
+ *
+ * A `.json` is read with a plain `fs.readFile(path, 'utf-8')`, and Node keeps
+ * the BOM as a leading `\uFEFF` rather than consuming it. `JSON.parse` rejects
+ * that character outright, so a BOM-carrying manifest used to contribute
+ * nothing to the graph but a `warning`-severity parse error — every `Test_*`
+ * link it declared silently vanished (issue #316). On Windows this is the
+ * common case, not an exotic one: PowerShell 5.1 writes the BOM by default for
+ * `-Encoding UTF8` in both `Set-Content` and `Out-File`.
+ *
+ * Only a BOM at position 0 is removed; a `\uFEFF` anywhere else is data and is
+ * left for `JSON.parse` to judge.
+ */
+export function stripJsonBom(text: string): string {
+  return text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+}

src/extraction/vba-test-manifest-extractor.ts

@@ -24,6 +24,7 @@
 import * as path from 'path';
 import { Node, ExtractionResult, ExtractionError, UnresolvedReference } from '../types';
 import { generateNodeId } from './tree-sitter-helpers';
+import { stripJsonBom } from './json-source';
 
 /** One `tests[]` entry that carries a string `procedure`. */
 interface ManifestTestEntry {
@@ -66,7 +67,10 @@ export class VbaTestManifestExtractor {
 
     let parsed: unknown;
     try {
-      parsed = JSON.parse(this.source);
+      // A leading UTF-8 BOM makes `JSON.parse` throw, which would turn a
+      // perfectly valid manifest into a warning and zero references (#316).
+      // PowerShell 5.1 writes that BOM by default for `-Encoding UTF8`.
+      parsed = JSON.parse(stripJsonBom(this.source));
     } catch (error) {
       // Malformed manifest — low-severity so it never breaks the index.
       this.errors.push({

src/extraction/vba-test-sequence-extractor.ts

@@ -34,6 +34,7 @@
 import * as path from 'path';
 import { Node, ExtractionResult, ExtractionError, UnresolvedReference } from '../types';
 import { generateNodeId } from './tree-sitter-helpers';
+import { stripJsonBom } from './json-source';
 
 /**
  * Content-shape gate: is `parsed` a Dysflow VBA test sequence — a top-level
@@ -74,7 +75,10 @@ export class VbaTestSequenceExtractor {
 
     let parsed: unknown;
     try {
-      parsed = JSON.parse(this.source);
+      // A leading UTF-8 BOM makes `JSON.parse` throw, which would turn a
+      // perfectly valid sequence into a warning and zero references (#316).
+      // PowerShell 5.1 writes that BOM by default for `-Encoding UTF8`.
+      parsed = JSON.parse(stripJsonBom(this.source));
     } catch (error) {
       this.errors.push({
         message: `VBA test sequence parse error: ${