Merge pull request #74 from eviltester/52-pairwise-support-in-cli-api-and-mcp

added pairwise to cli, api and mcp

closes #52

Author: eviltester

README.md

@@ -235,11 +235,16 @@ Supported options:
 
 - `-i, --inputfile` path to the input text spec (required)
 - `-n, --numberOfLines` number of rows to generate (default `1`)
+- `--pairwise` generate pairwise combinations for enum fields (requires at least 2 enum rules)
 - `-f, --format` output format (default `csv`)
 - `-o, --outputfile` write output to file instead of stdout
 - `-t, --testMode` enable diagnostics mode and generate one row
 - `--unsafe-faker-expressions` allow expression-style faker args (disabled by default)
 
+Pairwise note:
+
+- when `--pairwise` is enabled, `--numberOfLines` is accepted but ignored (the pairwise engine determines row count)
+
 ## REST API Quick Start
 
 Start the API:
@@ -295,7 +300,8 @@ Raw multiline schema/spec endpoint:
 
 - `Content-Type` must be `text/plain`
 - request body is the full multiline spec
-- query params: `rowCount` (required), `outputFormat` (optional), `seed` (optional), `responseFormat` (optional: `rows|rendered|all|raw`)
+- query params: `rowCount` (required), `outputFormat` (optional), `seed` (optional), `pairwise` (optional), `responseFormat` (optional: `rows|rendered|all|raw`)
+- pairwise note: when `pairwise=true`, `rowCount` is accepted for compatibility but ignored (pairwise output size is computed automatically)
 
 Set format default options:
 
@@ -411,6 +417,7 @@ Inputs:
 
 - `textSpec` (required string)
 - `rowCount` (required integer, >= 0)
+- `pairwise` (optional boolean, default `false`; when `true`, `rowCount` is ignored)
 - `outputFormat` (required string e.g. `csv`, `json`, `jsonl`, `xml`, `sql`)
 - `options` (optional object)
 - `seed` (optional number)

apps/api/src/fromschema.route.test.js

@@ -156,3 +156,23 @@ test('/v1/generate/fromschema applies unit-test defaults for includeSetup', asyn
     expect(resetDefaults.status).toBe(200);
   }
 });
+
+test('/v1/generate/fromschema supports pairwise query flag', async () => {
+  const response = await fetch(url('/v1/generate/fromschema?rowCount=50&pairwise=true&outputFormat=json'), {
+    method: 'POST',
+    headers: { 'content-type': 'text/plain' },
+    body: 'Browser\nChrome,Firefox,Safari\nTheme\nLight,Dark',
+  });
+
+  expect(response.status).toBe(200);
+  const body = await response.json();
+  expect(body.headers).toEqual(['Browser', 'Theme']);
+  expect(body.rows).toEqual([
+    ['Chrome', 'Light'],
+    ['Chrome', 'Dark'],
+    ['Firefox', 'Light'],
+    ['Firefox', 'Dark'],
+    ['Safari', 'Light'],
+    ['Safari', 'Dark'],
+  ]);
+});

apps/api/src/generate.route.test.js

@@ -135,3 +135,54 @@ test('/v1/generate parity: REST rendered matches core for all unit-test framewor
     expect(body.rendered).toBe(coreResult.rendered);
   }
 });
+
+test('/v1/generate supports pairwise mode', async () => {
+  const response = await fetch(url('/v1/generate'), {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({
+      textSpec: 'Browser\nChrome,Firefox,Safari\nTheme\nLight,Dark',
+      rowCount: 99,
+      outputFormat: 'json',
+      pairwise: true,
+    }),
+  });
+
+  expect(response.status).toBe(200);
+  const body = await response.json();
+  expect(body.headers).toEqual(['Browser', 'Theme']);
+  expect(body.rows).toEqual([
+    ['Chrome', 'Light'],
+    ['Chrome', 'Dark'],
+    ['Firefox', 'Light'],
+    ['Firefox', 'Dark'],
+    ['Safari', 'Light'],
+    ['Safari', 'Dark'],
+  ]);
+});
+
+test('/v1/generate supports pairwise for x-www-form-urlencoded payloads', async () => {
+  const form = new URLSearchParams();
+  form.set('textSpec', 'Browser\nChrome,Firefox,Safari\nTheme\nLight,Dark');
+  form.set('rowCount', '99');
+  form.set('outputFormat', 'json');
+  form.set('pairwise', 'true');
+
+  const response = await fetch(url('/v1/generate'), {
+    method: 'POST',
+    headers: { 'content-type': 'application/x-www-form-urlencoded' },
+    body: form.toString(),
+  });
+
+  expect(response.status).toBe(200);
+  const body = await response.json();
+  expect(body.headers).toEqual(['Browser', 'Theme']);
+  expect(body.rows).toEqual([
+    ['Chrome', 'Light'],
+    ['Chrome', 'Dark'],
+    ['Firefox', 'Light'],
+    ['Firefox', 'Dark'],
+    ['Safari', 'Light'],
+    ['Safari', 'Dark'],
+  ]);
+});

apps/api/src/index.js

@@ -361,7 +361,7 @@ function resetDefaultOptionsForFormat(format) {
 }
 
 function runGeneration(payload = {}) {
-  const { textSpec, rowCount, outputFormat = 'csv', options, seed, unsafeFakerExpressions } = payload;
+  const { textSpec, rowCount, outputFormat = 'csv', options, seed, pairwise, unsafeFakerExpressions } = payload;
   const concreteOutputFormat = String(outputFormat || 'csv').toLowerCase();
 
   if (!SUPPORTED_FORMATS.includes(String(outputFormat).toLowerCase())) {
@@ -403,6 +403,7 @@ function runGeneration(payload = {}) {
       outputFormat: concreteOutputFormat,
       options: effectiveOptions,
       seed: parsedSeed.seed,
+      pairwise: parseBooleanFlag(pairwise),
       unsafeFakerExpressions: unsafeFakerExpressions || false,
     });
     if (!result?.ok) {
@@ -494,6 +495,7 @@ function buildFromSchemaPayload(req) {
     rowCount,
     outputFormat: outputFormat || 'csv',
     seed,
+    pairwise: req.query?.pairwise === 'true',
     responseFormat,
     unsafeFakerExpressions: unsafeFakerExpressions === 'true',
   };

apps/api/src/openapi.js

@@ -41,7 +41,11 @@ const openApiDocument = {
                 required: ['textSpec', 'rowCount'],
                 properties: {
                   textSpec: { type: 'string' },
-                  rowCount: { type: 'integer', minimum: 0 },
+                  rowCount: {
+                    type: 'integer',
+                    minimum: 0,
+                    description: 'Requested row count. Ignored when pairwise is true.',
+                  },
                   outputFormat: {
                     type: 'string',
                     enum: [
@@ -86,6 +90,11 @@ const openApiDocument = {
                   },
                   options: { type: 'object' },
                   seed: { type: 'number' },
+                  pairwise: {
+                    type: 'boolean',
+                    default: false,
+                    description: 'Generate pairwise combinations for ENUM fields (requires at least 2 ENUM rules).',
+                  },
                   unsafeFakerExpressions: {
                     type: 'boolean',
                     default: false,
@@ -101,7 +110,11 @@ const openApiDocument = {
                 required: ['textSpec', 'rowCount'],
                 properties: {
                   textSpec: { type: 'string' },
-                  rowCount: { type: 'integer', minimum: 0 },
+                  rowCount: {
+                    type: 'integer',
+                    minimum: 0,
+                    description: 'Requested row count. Ignored when pairwise is true.',
+                  },
                   outputFormat: {
                     type: 'string',
                     enum: [
@@ -145,6 +158,11 @@ const openApiDocument = {
                     default: 'csv',
                   },
                   seed: { type: 'number' },
+                  pairwise: {
+                    type: 'boolean',
+                    default: false,
+                    description: 'Generate pairwise combinations for ENUM fields (requires at least 2 ENUM rules).',
+                  },
                   unsafeFakerExpressions: {
                     type: 'boolean',
                     default: false,
@@ -223,7 +241,7 @@ const openApiDocument = {
             name: 'rowCount',
             required: true,
             schema: { type: 'integer', minimum: 0 },
-            description: 'Number of rows to generate',
+            description: 'Number of rows to generate. Ignored when pairwise=true.',
           },
           {
             in: 'query',
@@ -278,6 +296,17 @@ const openApiDocument = {
             required: false,
             schema: { type: 'number' },
           },
+          {
+            in: 'query',
+            name: 'pairwise',
+            required: false,
+            schema: {
+              type: 'boolean',
+              default: false,
+            },
+            description:
+              'Generate pairwise combinations for ENUM fields (requires at least 2 ENUM rules). When true, rowCount is ignored.',
+          },
           {
             in: 'query',
             name: 'unsafeFakerExpressions',

apps/cli/src/cli-options.js

@@ -47,6 +47,11 @@ export function parseCliOptions(argvInput = process.argv) {
       default: false,
       describe: 'Allow expression-style faker arguments (unsafe for untrusted input)',
     })
+    .option('pairwise', {
+      type: 'boolean',
+      default: false,
+      describe: 'Generate pairwise combinations for ENUM fields (requires at least 2 ENUM rules)',
+    })
     .help('h')
     .alias('h', 'help')
     .parseSync();
@@ -66,5 +71,6 @@ export function parseCliOptions(argvInput = process.argv) {
     showProgress,
     shouldStream,
     unsafeFakerExpressions: parsed['unsafe-faker-expressions'] === true,
+    pairwise: parsed.pairwise === true,
   };
 }

apps/cli/src/run-cli.js

@@ -28,8 +28,14 @@ export async function runCliCommand({ options, platform }) {
   if (options.testMode) {
     progress('> Operating in Test Mode - generating 1 entry');
   }
+  const useStreamMode = options.shouldStream && !options.pairwise;
+  if (options.pairwise && options.shouldStream) {
+    if (options.testMode) {
+      progress('WARNING: Streaming is ignored when pairwise generation is enabled; using buffered mode.');
+    }
+  }
 
-  if (options.shouldStream && (options.format === 'csv' || options.format === 'jsonl')) {
+  if (useStreamMode && (options.format === 'csv' || options.format === 'jsonl')) {
     const streamedLines = [];
     const writer = options.outputFile ? platform.createLineWriter(options.outputFile) : null;
     let writerClosed = false;
@@ -38,6 +44,7 @@ export async function runCliCommand({ options, platform }) {
         textSpec,
         rowCount: options.rowCount,
         outputFormat: options.format,
+        pairwise: options.pairwise,
         unsafeFakerExpressions: options.unsafeFakerExpressions,
         onChunk: async (chunk) => {
           if (writer) {
@@ -86,6 +93,7 @@ export async function runCliCommand({ options, platform }) {
     textSpec,
     rowCount: options.rowCount,
     outputFormat: options.format,
+    pairwise: options.pairwise,
     unsafeFakerExpressions: options.unsafeFakerExpressions,
   });
 
@@ -95,6 +103,11 @@ export async function runCliCommand({ options, platform }) {
   }
 
   progress(result.diagnostics.report);
+  if (Array.isArray(result.diagnostics.warnings)) {
+    for (const warning of result.diagnostics.warnings) {
+      progress(`WARNING: ${warning}`);
+    }
+  }
   if (options.testMode && result.rows.length > 0) {
     progress('e.g.');
     progress(JSON.stringify(result.rows[0]));

apps/cli/src/tests/cli-options.test.js

@@ -35,3 +35,8 @@ test('stream auto-enabled for large file outputs', () => {
   ]);
   expect(opts.shouldStream).toBe(true);
 });
+
+test('pairwise flag is parsed', () => {
+  const opts = parseCliOptions(['node', 'cli', 'generate', '-i', 'spec.txt', '-n', '5', '--pairwise']);
+  expect(opts.pairwise).toBe(true);
+});

apps/cli/src/tests/run-cli.test.js

@@ -50,6 +50,7 @@ test('returns error when input file cannot be read', async () => {
       showProgress: false,
       shouldStream: false,
       unsafeFakerExpressions: false,
+      pairwise: false,
     },
   });
   expect(code).toBe(1);
@@ -69,6 +70,7 @@ test('writes output file in buffered mode', async () => {
       showProgress: false,
       shouldStream: false,
       unsafeFakerExpressions: false,
+      pairwise: false,
     },
   });
   expect(code).toBe(0);
@@ -96,9 +98,82 @@ test('returns error when stream writer fails', async () => {
       showProgress: false,
       shouldStream: true,
       unsafeFakerExpressions: false,
+      pairwise: false,
     },
   });
 
   expect(code).toBe(1);
   expect(platform.err.join('')).toContain('Streaming generation failed');
 });
+
+test('ignores stream mode when pairwise is requested', async () => {
+  const platform = makePlatform({ textSpec: 'Browser\nChrome,Firefox,Safari\nTheme\nLight,Dark' });
+  const code = await runCliCommand({
+    platform,
+    options: {
+      inputFile: 'spec.txt',
+      outputFile: 'out.csv',
+      format: 'csv',
+      rowCount: 2,
+      testMode: false,
+      showProgress: false,
+      shouldStream: true,
+      unsafeFakerExpressions: false,
+      pairwise: true,
+    },
+  });
+  expect(code).toBe(0);
+  expect(platform.err.join('')).toBe('');
+  expect(platform.writes.length).toBe(1);
+  expect(platform.writes[0].path).toBe('out.csv');
+});
+
+test('reports warning in test mode when stream mode is ignored for pairwise', async () => {
+  const platform = makePlatform({ textSpec: 'Browser\nChrome,Firefox,Safari\nTheme\nLight,Dark' });
+  const code = await runCliCommand({
+    platform,
+    options: {
+      inputFile: 'spec.txt',
+      outputFile: 'out.csv',
+      format: 'csv',
+      rowCount: 2,
+      testMode: true,
+      showProgress: true,
+      shouldStream: true,
+      unsafeFakerExpressions: false,
+      pairwise: true,
+    },
+  });
+  expect(code).toBe(0);
+  expect(platform.out.join('')).toContain('WARNING: Streaming is ignored when pairwise generation is enabled');
+  expect(platform.out.join('')).toContain('WARNING: rowCount is ignored when pairwise generation is enabled.');
+});
+
+test('generates deterministic pairwise output in buffered mode', async () => {
+  const platform = makePlatform({ textSpec: 'Browser\nChrome,Firefox,Safari\nTheme\nLight,Dark' });
+  const code = await runCliCommand({
+    platform,
+    options: {
+      inputFile: 'spec.txt',
+      outputFile: null,
+      format: 'json',
+      rowCount: 100,
+      testMode: false,
+      showProgress: false,
+      shouldStream: false,
+      unsafeFakerExpressions: false,
+      pairwise: true,
+    },
+  });
+
+  expect(code).toBe(0);
+  const rendered = platform.out.join('').trim();
+  expect(JSON.parse(rendered)).toEqual([
+    { Browser: 'Chrome', Theme: 'Light' },
+    { Browser: 'Chrome', Theme: 'Dark' },
+    { Browser: 'Firefox', Theme: 'Light' },
+    { Browser: 'Firefox', Theme: 'Dark' },
+    { Browser: 'Safari', Theme: 'Light' },
+    { Browser: 'Safari', Theme: 'Dark' },
+  ]);
+});

apps/mcp/src/index.js

@@ -384,6 +384,10 @@ function handleRequest(request) {
                 outputFormat: { type: 'string', enum: SUPPORTED_FORMATS },
                 options: GENERATE_OPTIONS_SCHEMA,
                 seed: { type: 'number' },
+                pairwise: {
+                  type: 'boolean',
+                  description: 'Generate pairwise combinations for ENUM fields (requires at least 2 ENUM rules).',
+                },
               },
               required: ['textSpec', 'rowCount', 'outputFormat'],
             },