@laitszkin/apollo-toolkit 4.0.11 → 4.1.1

package/packages/tools/codegraph/lib/cmd-status.ts

@@ -0,0 +1,53 @@
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+import { closeIndex, getCodeGraphModule } from './cg-instance.js';
+import { formatSummary, formatOutput } from './formatter.js';
+
+export interface StatusOptions {
+  json?: boolean;
+}
+
+export async function handleStatus(projectRoot: string, options: StatusOptions = {}): Promise<number> {
+  if (!getCodeGraphModule().CodeGraph.isInitialized(projectRoot)) {
+    process.stderr.write('CodeGraph is not initialized. Run `apltk codegraph init` first.\n');
+    return 1;
+  }
+  const cg = await getCodeGraphModule().CodeGraph.open(projectRoot, { sync: false, readOnly: true });
+  const stats = cg.getStats();
+  closeIndex(cg);
+
+  if (options.json) {
+    process.stdout.write(formatOutput(stats, { json: true }) + '\n');
+  } else {
+    // Summarize nodes by kind (skip zero entries)
+    const kindEntries = Object.entries(stats.nodesByKind).filter(([, v]) => (v as number) > 0);
+    const nodeKindSummary = kindEntries.map(([kind, count]) => `    ${kind.padEnd(14)} ${count}`).join('\n');
+
+    const edgeKindEntries = Object.entries(stats.edgesByKind).filter(([, v]) => (v as number) > 0);
+    const edgeKindSummary = edgeKindEntries.map(([kind, count]) => `    ${kind.padEnd(14)} ${count}`).join('\n');
+
+    const langEntries = Object.entries(stats.filesByLanguage || {}).filter(([, v]) => (v as number) > 0);
+    const langSummary = langEntries.length > 0
+      ? langEntries.map(([lang, count]) => `    ${lang.padEnd(14)} ${count}`).join('\n')
+      : '    (no files indexed)';
+
+    const summary: [string, string | number][] = [
+      ['Project:', projectRoot],
+      ['Files:', stats.fileCount],
+      ['Nodes:', stats.nodeCount],
+      ['Edges:', stats.edgeCount],
+      ['DB size:', `${(stats.dbSizeBytes / 1024).toFixed(1)} KB`],
+      ['Last updated:', new Date(stats.lastUpdated).toISOString()],
+      ['', ''],
+      ['Nodes by kind:', ''],
+    ];
+    process.stdout.write(formatSummary(summary) + '\n');
+    process.stdout.write(nodeKindSummary + '\n');
+    process.stdout.write('\nEdges by kind:\n');
+    process.stdout.write(edgeKindSummary + '\n');
+    process.stdout.write('\nLanguages:\n');
+    process.stdout.write(langSummary + '\n');
+  }
+
+  return 0;
+}

package/packages/tools/codegraph/lib/cmd-survey.test.ts

@@ -0,0 +1,161 @@
+import { describe, it, before, beforeEach, afterEach, mock } from 'node:test';
+import assert from 'node:assert/strict';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+
+describe('cmd-survey', () => {
+  let handleSurvey: (...args: any[]) => Promise<number>;
+
+  // Mock CodeGraph instance shared across tests:
+  // - Symbol A in src/feature/a.ts calls symbol B in src/lib/b.ts (cross-boundary)
+  // - Symbol X in src/feature/a.ts is exported but only called internally
+  const mockCg = {
+    getFiles: () => [{ path: 'src/feature/a.ts', language: 'typescript' }],
+    getNodesInFile: () => [
+      {
+        id: 'node-a',
+        name: 'A',
+        kind: 'function',
+        qualifiedName: 'A',
+        startLine: 1,
+        endLine: 10,
+        isExported: true,
+      },
+      {
+        id: 'node-x',
+        name: 'X',
+        kind: 'function',
+        qualifiedName: 'X',
+        startLine: 20,
+        endLine: 30,
+        isExported: true,
+      },
+    ],
+    getNodesByName: (name: string) => {
+      if (name === 'A') {
+        return [{ id: 'node-a', filePath: 'src/feature/a.ts', name: 'A' }];
+      }
+      if (name === 'X') {
+        return [{ id: 'node-x', filePath: 'src/feature/a.ts', name: 'X' }];
+      }
+      return [];
+    },
+    getCallees: (_id: string) => {
+      if (_id === 'node-a') {
+        return [{ node: { name: 'B', filePath: 'src/lib/b.ts' } }];
+      }
+      return [];
+    },
+    getCallers: (_id: string) => {
+      if (_id === 'node-x') {
+        return [{ node: { name: 'internal', filePath: 'src/feature/a.ts' } }];
+      }
+      return [];
+    },
+    close: () => {},
+  };
+
+  before(async () => {
+    // Module-level mocks (only need to be set up once):
+    mock.module('./survey/scanner.js', {
+      namedExports: {
+        scanDirectory: async () => ({
+          directory: 'src/feature',
+          files: [
+            {
+              filePath: 'src/feature/a.ts',
+              language: 'typescript',
+              symbols: [
+                { name: 'A', kind: 'function', qualifiedName: 'A', startLine: 1, endLine: 10, isExported: true, signature: undefined },
+                { name: 'X', kind: 'function', qualifiedName: 'X', startLine: 20, endLine: 30, isExported: true, signature: undefined },
+              ],
+            },
+          ],
+          allSymbols: [
+            { name: 'A', kind: 'function', filePath: 'src/feature/a.ts', qualifiedName: 'A', startLine: 1, isExported: true },
+            { name: 'X', kind: 'function', filePath: 'src/feature/a.ts', qualifiedName: 'X', startLine: 20, isExported: true },
+          ],
+          totalFiles: 1,
+          totalSymbols: 2,
+        }),
+      },
+    });
+    mock.module('./survey/grouper.js', {
+      namedExports: { groupIntoSubmodules: () => [] },
+    });
+    mock.module('./cg-instance.js', {
+      namedExports: { closeIndex: () => {} },
+    });
+
+    // Import the compiled module (dist/lib/cmd-survey.js has the fixed code)
+    const mod = await import('./cmd-survey.js');
+    handleSurvey = mod.handleSurvey;
+  });
+
+  beforeEach(() => {
+    // Re-apply CodeGraph.open mock before each test (mock.reset() in afterEach clears it).
+    // Must use manual mock.method instead of mock.module because lazy CJS require()
+    // inside handlers bypasses mock.module interception.
+    const { CodeGraph } = require('@colbymchenry/codegraph');
+    mock.method(CodeGraph, 'open', async () => mockCg);
+  });
+
+  afterEach(() => {
+    mock.reset();
+  });
+
+  it('REGTEST-10: Cross-boundary edges point outside the scanned directory', async () => {
+    const stdoutChunks: string[] = [];
+    mock.method(process.stdout, 'write', (chunk: unknown) => {
+      stdoutChunks.push(String(chunk));
+      return true;
+    });
+
+    // Use a real directory for projectRoot so existsSync returns true naturally
+    const exitCode = await handleSurvey(process.cwd(), 'packages');
+
+    assert.equal(exitCode, 0);
+    const output = stdoutChunks.join('');
+    assert.ok(
+      output.includes('src/feature/a.ts -> src/lib/b.ts'),
+      `Expected cross-boundary edge label in output, got:\n${output}`,
+    );
+  });
+
+  it('REGTEST-11: Exported symbol called only from within the directory is not an entry point', async () => {
+    const stdoutChunks: string[] = [];
+    mock.method(process.stdout, 'write', (chunk: unknown) => {
+      stdoutChunks.push(String(chunk));
+      return true;
+    });
+
+    // Use a real directory for projectRoot so existsSync returns true naturally
+    const exitCode = await handleSurvey(process.cwd(), 'packages');
+
+    assert.equal(exitCode, 0);
+    const output = stdoutChunks.join('');
+    // X has only internal callers, so "(none)" should appear for entry points
+    assert.ok(
+      output.includes('(none)'),
+      `Expected "(none)" for entry points, got:\n${output}`,
+    );
+  });
+
+  it('REGTEST-12: Non-existent directory returns exit code 1 with error message', async () => {
+    const stderrChunks: string[] = [];
+    mock.method(process.stderr, 'write', (chunk: unknown) => {
+      stderrChunks.push(String(chunk));
+      return true;
+    });
+
+    // Use a path that does not exist on disk
+    const exitCode = await handleSurvey('/tmp', 'nonexistent-' + process.hrtime.bigint().toString());
+
+    assert.equal(exitCode, 1);
+    assert.ok(
+      stderrChunks.join('').includes('Directory not found'),
+      `Expected "Directory not found" error, got: ${stderrChunks.join('')}`,
+    );
+  });
+});

package/packages/tools/codegraph/lib/cmd-survey.ts

@@ -0,0 +1,199 @@
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { closeIndex } from './cg-instance.js';
+import { formatOutput } from './formatter.js';
+import { scanDirectory } from './survey/scanner.js';
+import { groupIntoSubmodules } from './survey/grouper.js';
+
+export interface SurveyOptions {
+  feature?: string;
+  json?: boolean;
+}
+
+export interface SurveyReport {
+  directory: string;
+  feature?: string;
+  totalFiles: number;
+  totalSymbols: number;
+  files: Array<{
+    filePath: string;
+    language: string;
+    symbolCount: number;
+  }>;
+  entryPoints: Array<{
+    name: string;
+    kind: string;
+    filePath: string;
+    startLine: number;
+    isExported: boolean;
+  }>;
+  suggestedSubmodules: Array<{
+    slug: string;
+    kind: string;
+    role: string;
+    memberFunctions: string[];
+    memberFiles: string[];
+  }>;
+  suggestedEdges: Array<{
+    source: string;
+    target: string;
+    kind: string;
+    label: string;
+  }>;
+}
+
+export async function handleSurvey(
+  projectRoot: string,
+  dirPath: string,
+  options: SurveyOptions = {},
+): Promise<number> {
+  // Check that the target directory exists
+  const targetPath = path.resolve(projectRoot, dirPath);
+  if (!existsSync(targetPath)) {
+    process.stderr.write(`Error: Directory not found: ${dirPath}\n`);
+    return 1;
+  }
+
+  const { CodeGraph } = require('@colbymchenry/codegraph');
+  const cg = await CodeGraph.open(projectRoot, { sync: false, readOnly: true });
+
+  // Scan the directory
+  const scan = await scanDirectory(cg, dirPath);
+
+  const fileSet = new Set(scan.files.map((f) => f.filePath));
+
+  // Group into submodule suggestions
+  const suggestions = groupIntoSubmodules(scan, cg);
+
+  // Build edge suggestions from cross-file call relationships
+  const edgeSuggestions = buildEdgeSuggestions(scan, cg, fileSet);
+
+  // Determine entry points: exported symbols called from outside the scanned directory
+  const entryPoints = scan.allSymbols.filter(s => {
+    if (!s.isExported) return false;
+    const nodes = cg.getNodesByName(s.name);
+    for (const node of nodes) {
+      if (node.filePath !== s.filePath) continue;
+      const callers = cg.getCallers(node.id);
+      for (const caller of callers) {
+        if (!fileSet.has(caller.node.filePath)) {
+          return true;
+        }
+      }
+    }
+    return false;
+  });
+
+  closeIndex(cg);
+
+  const report: SurveyReport = {
+    directory: dirPath,
+    feature: options.feature,
+    totalFiles: scan.totalFiles,
+    totalSymbols: scan.totalSymbols,
+    files: scan.files.map((f) => ({
+      filePath: f.filePath,
+      language: f.language,
+      symbolCount: f.symbols.length,
+    })),
+    entryPoints,
+    suggestedSubmodules: suggestions.map((s) => ({
+      slug: s.slug,
+      kind: s.kind,
+      role: s.role,
+      memberFunctions: s.memberFunctions,
+      memberFiles: s.memberFiles,
+    })),
+    suggestedEdges: edgeSuggestions,
+  };
+
+  if (options.json) {
+    process.stdout.write(formatOutput(report, { json: true }) + '\n');
+  } else {
+    // Human-readable output
+    process.stdout.write(`\n=== Survey: ${dirPath} ===\n`);
+    if (report.feature) {
+      process.stdout.write(`Feature: ${report.feature}\n`);
+    }
+    process.stdout.write('\n');
+
+    process.stdout.write(`Files: ${report.totalFiles}  Symbols: ${report.totalSymbols}\n\n`);
+
+    process.stdout.write('Files:\n');
+    for (const f of report.files) {
+      process.stdout.write(`  ${f.filePath}  [${f.language}]  (${f.symbolCount} symbols)\n`);
+    }
+
+    process.stdout.write('\nEntry Points:\n');
+    if (report.entryPoints.length === 0) {
+      process.stdout.write('  (none)\n');
+    } else {
+      for (const ep of report.entryPoints) {
+        process.stdout.write(`  ${ep.name}  [${ep.kind}]  ${ep.filePath}:${ep.startLine}\n`);
+      }
+    }
+
+    process.stdout.write('\nSuggested Submodules:\n');
+    if (report.suggestedSubmodules.length === 0) {
+      process.stdout.write('  (none)\n');
+    } else {
+      for (const sub of report.suggestedSubmodules) {
+        process.stdout.write(`  ${sub.slug}  [${sub.kind}]  ${sub.role}\n`);
+        process.stdout.write(`    Functions: ${sub.memberFunctions.join(', ')}\n`);
+        process.stdout.write(`    Files: ${sub.memberFiles.join(', ')}\n\n`);
+      }
+    }
+
+    process.stdout.write('Suggested Edges:\n');
+    if (report.suggestedEdges.length === 0) {
+      process.stdout.write('  (none)\n');
+    } else {
+      for (const edge of report.suggestedEdges) {
+        process.stdout.write(`  ${edge.source} --[${edge.kind}]--> ${edge.target}  (${edge.label})\n`);
+      }
+    }
+
+    process.stdout.write('\n');
+  }
+
+  return 0;
+}
+
+/**
+ * Build suggested edges from cross-file call relationships in the scanned directory.
+ */
+function buildEdgeSuggestions(
+  scan: Awaited<ReturnType<typeof scanDirectory>>,
+  cg: any,
+  fileSet: Set<string>,
+): SurveyReport['suggestedEdges'] {
+  const edges: SurveyReport['suggestedEdges'] = [];
+  const dedup = new Set<string>();
+
+  // For each symbol in the scan, check if it calls symbols outside the scanned directory
+  for (const sym of scan.allSymbols) {
+    const nodes = cg.getNodesByName(sym.name);
+    for (const node of nodes) {
+      if (node.filePath !== sym.filePath) continue;
+      const callees = cg.getCallees(node.id);
+      for (const callee of callees) {
+        // Only consider callees OUTSIDE the scanned directory (cross-boundary edges)
+        if (!fileSet.has(callee.node.filePath)) {
+          const edgeKey = `${sym.name}::${callee.node.name}`;
+          if (dedup.has(edgeKey)) continue;
+          dedup.add(edgeKey);
+          edges.push({
+            source: sym.name,
+            target: callee.node.name,
+            kind: 'call',
+            label: `${sym.filePath} -> ${callee.node.filePath}`,
+          });
+        }
+      }
+    }
+  }
+
+  return edges;
+}

package/packages/tools/codegraph/lib/cmd-sync.test.ts

@@ -0,0 +1,41 @@
+import { describe, it, mock } from 'node:test';
+import assert from 'node:assert/strict';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+
+describe('cmd-sync handleSync', () => {
+  it('should return exit code 1 when CodeGraph is not initialized', async () => {
+    // Pre-load CodeGraph via CJS require (same mechanism used by cmd-sync.ts)
+    // and mock isInitialized BEFORE the module under test is evaluated, so
+    // the mock is in place when cmd-sync.ts runs its own require().
+    const { CodeGraph } = require('@colbymchenry/codegraph');
+    const isInitializedMock = mock.method(CodeGraph, 'isInitialized', () => false);
+
+    // Capture stderr output
+    const stderrWriteMock = mock.method(process.stderr, 'write', () => true);
+
+    // Import the module under test after mocks are set up
+    const { handleSync } = await import('./cmd-sync.js');
+
+    // Call the handler with an uninitialized project
+    const exitCode = await handleSync('/tmp/fake-project', { json: false });
+
+    // Verify exit code is 1 (error)
+    assert.strictEqual(exitCode, 1);
+
+    // Verify stderr mentions "init"
+    assert.strictEqual(stderrWriteMock.mock.calls.length, 1);
+    const callArg = stderrWriteMock.mock.calls[0].arguments[0];
+    assert.ok(callArg !== undefined, 'Expected stderr write argument to be defined');
+    const stderrOutput = typeof callArg === 'string' ? callArg : Buffer.from(callArg).toString('utf8');
+    assert.ok(
+      stderrOutput.toLowerCase().includes('init'),
+      `Expected stderr to mention "init", got: ${JSON.stringify(stderrOutput)}`,
+    );
+
+    // Cleanup mocks
+    isInitializedMock.mock.restore();
+    stderrWriteMock.mock.restore();
+  });
+});

package/packages/tools/codegraph/lib/cmd-sync.ts

@@ -0,0 +1,62 @@
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+import { closeIndex } from './cg-instance.js';
+import { formatSummary, formatOutput } from './formatter.js';
+
+export interface SyncOptions {
+  json?: boolean;
+}
+
+export async function handleSync(projectRoot: string, options: SyncOptions = {}): Promise<number> {
+  const { CodeGraph } = require('@colbymchenry/codegraph');
+  if (!CodeGraph.isInitialized(projectRoot)) {
+    process.stderr.write('CodeGraph is not initialized. Run `apltk codegraph init` first.\n');
+    return 1;
+  }
+
+  const cg = await CodeGraph.open(projectRoot, { sync: false, readOnly: false });
+
+  let progressEvents: Array<{ phase: string; current: number; total: number }> = [];
+  const result = await cg.sync({
+    onProgress: (p: any) => {
+      progressEvents.push({ phase: p.phase, current: p.current, total: p.total });
+      if (process.stdout.isTTY) {
+        process.stdout.write(`\r  Indexing: ${p.phase} ${p.current}/${p.total}`);
+      }
+    },
+  });
+
+  if (process.stdout.isTTY) {
+    process.stdout.write('\n');
+  }
+
+  closeIndex(cg);
+
+  const output = {
+    projectRoot,
+    filesChecked: result.filesChecked,
+    filesAdded: result.filesAdded,
+    filesModified: result.filesModified,
+    filesRemoved: result.filesRemoved,
+    nodesUpdated: result.nodesUpdated,
+    durationMs: result.durationMs,
+    progress: progressEvents.length > 0 ? progressEvents : undefined,
+  };
+
+  if (options.json) {
+    process.stdout.write(formatOutput(output, { json: true }) + '\n');
+  } else {
+    const summary: [string, string | number][] = [
+      ['Project:', projectRoot],
+      ['Checked:', result.filesChecked],
+      ['Added:', result.filesAdded],
+      ['Modified:', result.filesModified],
+      ['Removed:', result.filesRemoved],
+      ['Nodes updated:', result.nodesUpdated],
+      ['Duration:', `${result.durationMs}ms`],
+    ];
+    process.stdout.write(formatSummary(summary) + '\n');
+  }
+
+  return 0;
+}

package/packages/tools/codegraph/lib/cmd-verify.test.ts

@@ -0,0 +1,162 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import yaml from 'js-yaml';
+
+/**
+ * REGTEST-1: Verify that the js-yaml based parser (used in `loadOverlay`)
+ * correctly parses object-format YAML function declarations.
+ *
+ * The fix replaced a custom YAML parser with `js-yaml`. The old parser
+ * incorrectly produced raw string fragments like `"name: init"` when
+ * encountering object-format functions:
+ *
+ *   functions:
+ *     - name: init
+ *       in: string
+ *       out: void
+ *
+ * With `js-yaml`, the parser produces actual objects:
+ *   `{ name: "init", in: "string", out: "void" }`
+ *
+ * This test exercises the same parsing path as `loadOverlay`: reading a YAML
+ * file from disk with `fs.readFileSync`, then parsing with `yaml.load`.
+ */
+describe('REGTEST-1: loadOverlay YAML parser', () => {
+  it('should parse object-format functions and correctly extract .name', () => {
+    const yamlStr = [
+      'slug: test-feature',
+      'submodules:',
+      '  - slug: module-a',
+      '    functions:',
+      '      - name: init',
+      '        in: string',
+      '        out: void',
+      'edges:',
+      '  - from: funcA',
+      '    to: funcB',
+      '    kind: call',
+    ].join('\n');
+
+    // Parse with js-yaml (same library used by loadOverlay)
+    const data = yaml.load(yamlStr) as any;
+
+    // Verify object-format function parsing
+    const fn = data.submodules[0].functions[0];
+    assert.strictEqual(typeof fn, 'object', 'object-format function should be parsed as object, not string');
+    assert.strictEqual(fn.name, 'init', 'parsed function .name should be "init"');
+
+    // Verify the old bug is fixed: no raw "name: init" string
+    assert.notStrictEqual(fn, 'name: init', 'function should NOT be a raw string fragment');
+    assert.notStrictEqual(typeof fn, 'string', 'object-format function should not be a string');
+
+    // Verify additional fields are preserved
+    assert.strictEqual(fn.in, 'string', 'function "in" field should be preserved');
+    assert.strictEqual(fn.out, 'void', 'function "out" field should be preserved');
+
+    // Verify string-format functions still work
+    // Note: the YAML above only has object-format functions; string format is tested separately
+  });
+
+  it('should parse string-format functions correctly', () => {
+    const yamlStr = [
+      'slug: test-feature',
+      'submodules:',
+      '  - slug: module-a',
+      '    functions:',
+      '      - init',
+      '      - process',
+    ].join('\n');
+
+    const data = yaml.load(yamlStr) as any;
+
+    const functions = data.submodules[0].functions;
+    assert.strictEqual(functions.length, 2, 'should have 2 string-format functions');
+    assert.strictEqual(typeof functions[0], 'string', 'string-format function should be a string');
+    assert.strictEqual(functions[0], 'init', 'string function name should be "init"');
+    assert.strictEqual(functions[1], 'process', 'string function name should be "process"');
+  });
+
+  it('should parse mixed object and string format functions', () => {
+    const yamlStr = [
+      'slug: test-feature',
+      'submodules:',
+      '  - slug: module-a',
+      '    functions:',
+      '      - name: init',
+      '        in: string',
+      '        out: void',
+      '      - process',
+      '      - name: render',
+      '        in: string',
+      '        out: void',
+      '      - cleanup',
+    ].join('\n');
+
+    const data = yaml.load(yamlStr) as any;
+    const functions = data.submodules[0].functions;
+
+    assert.strictEqual(functions.length, 4, 'should have 4 functions total');
+
+    // Index 0: object-format
+    assert.strictEqual(typeof functions[0], 'object', 'functions[0] should be object');
+    assert.strictEqual(functions[0].name, 'init');
+
+    // Index 1: string-format
+    assert.strictEqual(typeof functions[1], 'string', 'functions[1] should be string');
+    assert.strictEqual(functions[1], 'process');
+
+    // Index 2: object-format
+    assert.strictEqual(typeof functions[2], 'object', 'functions[2] should be object');
+    assert.strictEqual(functions[2].name, 'render');
+
+    // Index 3: string-format
+    assert.strictEqual(typeof functions[3], 'string', 'functions[3] should be string');
+    assert.strictEqual(functions[3], 'cleanup');
+  });
+
+  it('should parse feature YAML from disk (same path as loadOverlay)', async () => {
+    // Create a temp directory matching the loadOverlay structure
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'codegraph-verify-test-'));
+    try {
+      const featuresDir = path.join(tmpDir, 'architecture_diff', 'atlas', 'features');
+      fs.mkdirSync(featuresDir, { recursive: true });
+
+      const yamlPath = path.join(featuresDir, 'test-feature.yaml');
+      fs.writeFileSync(
+        yamlPath,
+        [
+          'slug: test-feature',
+          'submodules:',
+          '  - slug: module-a',
+          '    functions:',
+          '      - name: init',
+          '        in: string',
+          '        out: void',
+          '    edges:',
+          '      - from: funcA',
+          '        to: funcB',
+          '        kind: call',
+        ].join('\n') + '\n',
+      );
+
+      // Read file and parse (same as loadOverlay)
+      const raw = fs.readFileSync(yamlPath, 'utf8');
+      const data = yaml.load(raw) as any;
+
+      assert.ok(data, 'parsed data should be truthy');
+      assert.strictEqual(typeof data, 'object', 'parsed data should be an object');
+      assert.strictEqual(data.slug, 'test-feature', 'feature slug should be preserved');
+
+      const fn = data.submodules[0].functions[0];
+      assert.strictEqual(typeof fn, 'object', 'object-format function parsed from file should be object');
+      assert.strictEqual(fn.name, 'init', 'function .name should be "init"');
+      assert.strictEqual(fn.in, 'string', 'function .in should be "string"');
+      assert.strictEqual(fn.out, 'void', 'function .out should be "void"');
+    } finally {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+  });
+});