pict-cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Takeshi Kishi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,109 @@
+# pict-cli
+
+`pict-cli` is a Node.js-friendly command-line tool for running PICT-style
+combinatorial test generation from npm, CI, or ad hoc shell usage.
+
+This is an independent project by the package author and is not affiliated with
+Microsoft. It is inspired by Microsoft PICT and is intended to make similar
+workflows available in a Node.js environment, but it does not claim full
+command-line compatibility with the original `pict` executable.
+
+## Requirements
+
+- Node.js `^22 || ^24`
+
+## Installation
+
+Install `pict-cli` globally if you want a persistent local command:
+
+```bash
+npm install --global pict-cli
+```
+
+Run it without a global install for one-off usage or CI steps:
+
+```bash
+npx pict-cli <model-file>
+```
+
+Use `npx` for ad hoc runs and CI jobs. Use a global install when you expect to
+run the command repeatedly on the same machine.
+
+## Quick Start
+
+Create a model file such as `model.txt`:
+
+```txt
+OS: Windows, Linux
+Browser: Edge, Chrome, Firefox
+```
+
+Generate combinations with either a global install or `npx`:
+
+```bash
+pict-cli model.txt
+npx pict-cli model.txt
+```
+
+Example output:
+
+```text
+OS	Browser
+Windows	Edge
+Windows	Chrome
+Windows	Firefox
+Linux	Edge
+Linux	Chrome
+Linux	Firefox
+```
+
+The generated result is written as tab-separated text. If you pass `-s`, the
+command prints model statistics instead of generated cases.
+
+## CLI Usage
+
+```text
+Usage: pict-cli model [options]
+```
+
+`model` must be exactly one model file path.
+
+| Option      | Description                                       |
+| ----------- | ------------------------------------------------- |
+| `-o N\|max` | Order of combinations. Default: `2`.              |
+| `-d C`      | Separator for values. Default: `,`.               |
+| `-a C`      | Separator for aliases. Default: `\`.              |
+| `-n C`      | Negative value prefix. Default: `~`.              |
+| `-e file`   | File with seeding rows.                           |
+| `-r N`      | Randomize generation with seed `N`.               |
+| `-c`        | Enable case-sensitive model evaluation.           |
+| `-s`        | Show model statistics instead of generated cases. |
+
+Examples:
+
+```bash
+pict-cli model.txt -o 3 -c
+pict-cli model.txt -r 42
+pict-cli model.txt -e seed.tsv
+npx pict-cli model.txt -s
+```
+
+## Compatibility and Limitations
+
+- Only short options are supported.
+- Slash-style syntax such as `/o:3` is not supported.
+- Exactly one model file path is required.
+
+## Relationship to Microsoft PICT
+
+Microsoft PICT is the original combinatorial testing tool that inspired this
+package. `pict-cli` brings a similar workflow to Node.js through npm
+distribution and a JavaScript runtime, but it is not an official Microsoft
+package and is not endorsed or supported by Microsoft.
+
+## Project Links
+
+- Issues: [github.com/takeyaqa/pict-cli/issues](https://github.com/takeyaqa/pict-cli/issues)
+- License: [MIT](https://github.com/takeyaqa/pict-cli/blob/main/LICENSE)
+
+Bug reports and compatibility gaps are welcome.

package/bin/cli.js

@@ -0,0 +1,289 @@
+#!/usr/bin/env node
+
+import { readFile } from "node:fs/promises";
+import { argv, exit, stderr, stdout } from "node:process";
+import { parseArgs } from "node:util";
+import { PictError, PictErrorCode, PictRunner } from "@takeyaqa/pict-wasm";
+
+const USAGE = `Pairwise Independent Combinatorial Testing
+
+Usage: pict-cli model [options]
+
+Options:
+  -o N|max  Order of combinations (default: 2)
+  -d C      Separator for values (default: ,)
+  -a C      Separator for aliases (default: |)
+  -n C      Negative value prefix (default: ~)
+  -e file   File with seeding rows
+  -r N      Randomize generation with seed N
+  -c        Case-sensitive model evaluation
+  -s        Show model statistics`;
+
+const OPTIONS = {
+  o: { type: "string", short: "o" },
+  d: { type: "string", short: "d" },
+  a: { type: "string", short: "a" },
+  n: { type: "string", short: "n" },
+  e: { type: "string", short: "e" },
+  r: { type: "string", short: "r" },
+  c: { type: "boolean", short: "c" },
+  s: { type: "boolean", short: "s" },
+};
+
+class CliError extends Error {
+  constructor(code, message, stream = "stderr") {
+    super(message);
+    this.name = "CliError";
+    this.code = code;
+    this.stream = stream;
+  }
+}
+
+function writeLine(stream, text) {
+  if (!text) {
+    return;
+  }
+  stream.write(text.endsWith("\n") ? text : `${text}\n`);
+}
+
+function usageError() {
+  return new CliError(PictErrorCode.BadOption, USAGE, "stdout");
+}
+
+function inputError(message) {
+  return new CliError(PictErrorCode.BadOption, `Input Error: ${message}`);
+}
+
+function rejectUnsupportedSyntax(rawArgs) {
+  for (const arg of rawArgs) {
+    if (/^--[^-]/.test(arg)) {
+      throw inputError(`Unknown option: ${arg}`);
+    }
+
+    if (/^\/[A-Za-z](?::.*)?$/.test(arg) || arg === "/?") {
+      throw inputError(`Unknown option: ${arg}`);
+    }
+
+    if (/^-[A-Za-z]=/.test(arg)) {
+      throw inputError(`Unknown option: ${arg}`);
+    }
+
+    if (/^-[A-Za-z]:/.test(arg)) {
+      throw inputError(`Unknown option: ${arg}`);
+    }
+
+    if (/^-[A-Za-z]{2,}$/.test(arg)) {
+      throw inputError(`Unknown option: ${arg}`);
+    }
+  }
+}
+
+function getOptionSource(token, rawArgs) {
+  return rawArgs[token.index] ?? token.rawName;
+}
+
+function validateTokens(parsed, rawArgs) {
+  const seenOptions = new Set();
+  const optionSources = new Map();
+
+  for (const token of parsed.tokens) {
+    if (token.kind !== "option") {
+      continue;
+    }
+
+    if (!(token.name in OPTIONS)) {
+      throw inputError(`Unknown option: ${getOptionSource(token, rawArgs)}`);
+    }
+
+    if (seenOptions.has(token.name)) {
+      throw inputError(`Option '${token.name}' was provided more than once`);
+    }
+
+    seenOptions.add(token.name);
+    optionSources.set(token.name, getOptionSource(token, rawArgs));
+  }
+
+  return optionSources;
+}
+
+function getRequiredString(values, optionName, optionSources) {
+  const value = values[optionName];
+  if (value === undefined) {
+    return undefined;
+  }
+
+  if (typeof value !== "string") {
+    throw inputError(`Unknown option: ${optionSources.get(optionName)}`);
+  }
+
+  return value;
+}
+
+function getSingleCharacterValue(values, optionName, optionSources) {
+  const value = getRequiredString(values, optionName, optionSources);
+  if (value === undefined) {
+    return undefined;
+  }
+
+  if (value.length !== 1) {
+    throw inputError(`Unknown option: ${optionSources.get(optionName)}`);
+  }
+
+  return value;
+}
+
+function buildRunConfig(rawArgs) {
+  if (rawArgs.length === 0) {
+    throw usageError();
+  }
+
+  rejectUnsupportedSyntax(rawArgs);
+
+  const parsed = parseArgs({
+    args: rawArgs,
+    options: OPTIONS,
+    allowPositionals: true,
+    strict: false,
+    tokens: true,
+  });
+  const optionSources = validateTokens(parsed, rawArgs);
+
+  if (parsed.positionals.length !== 1) {
+    if (parsed.positionals.length === 0) {
+      throw usageError();
+    }
+    throw inputError("Exactly one model file path is required");
+  }
+
+  const orderOfCombinations = getRequiredString(
+    parsed.values,
+    "o",
+    optionSources,
+  );
+  if (
+    orderOfCombinations !== undefined &&
+    !(
+      orderOfCombinations === "max" ||
+      (/^\d+$/.test(orderOfCombinations) &&
+        Number.parseInt(orderOfCombinations, 10) > 0)
+    )
+  ) {
+    throw inputError(`Unknown option: ${optionSources.get("o")}`);
+  }
+
+  const randomizeSeed = getRequiredString(parsed.values, "r", optionSources);
+  if (randomizeSeed !== undefined && !/^\d+$/.test(randomizeSeed)) {
+    throw inputError(`Unknown option: ${optionSources.get("r")}`);
+  }
+
+  const valueSeparator = getSingleCharacterValue(
+    parsed.values,
+    "d",
+    optionSources,
+  );
+  const aliasSeparator = getSingleCharacterValue(
+    parsed.values,
+    "a",
+    optionSources,
+  );
+  const negativeValuePrefix = getSingleCharacterValue(
+    parsed.values,
+    "n",
+    optionSources,
+  );
+
+  return {
+    modelPath: parsed.positionals[0],
+    seedFilePath: getRequiredString(parsed.values, "e", optionSources),
+    options: {
+      ...(orderOfCombinations !== undefined
+        ? {
+            orderOfCombinations:
+              orderOfCombinations === "max"
+                ? "max"
+                : Number.parseInt(orderOfCombinations, 10),
+          }
+        : {}),
+      ...(valueSeparator !== undefined ? { valueSeparator } : {}),
+      ...(aliasSeparator !== undefined ? { aliasSeparator } : {}),
+      ...(negativeValuePrefix !== undefined ? { negativeValuePrefix } : {}),
+      ...(randomizeSeed !== undefined
+        ? {
+            randomizeGeneration: true,
+            randomizeSeed: Number.parseInt(randomizeSeed, 10),
+          }
+        : {}),
+      ...(parsed.values.c ? { caseSensitive: true } : {}),
+      ...(parsed.values.s ? { showModelStatistics: true } : {}),
+    },
+  };
+}
+
+async function readHostFile(filePath, errorCode) {
+  try {
+    return await readFile(filePath, "utf8");
+  } catch {
+    throw new CliError(
+      errorCode,
+      `Input Error: Couldn't open file: ${filePath}`,
+    );
+  }
+}
+
+function formatResult(result) {
+  return [result.header, ...result.body]
+    .map((row) => row.join("\t"))
+    .join("\n");
+}
+
+async function main(rawArgs) {
+  const config = buildRunConfig(rawArgs);
+  const modelText = await readHostFile(
+    config.modelPath,
+    PictErrorCode.BadModel,
+  );
+
+  if (config.seedFilePath !== undefined) {
+    config.options.seedRowsText = await readHostFile(
+      config.seedFilePath,
+      PictErrorCode.BadRowSeedFile,
+    );
+  }
+
+  const runner = await PictRunner.create();
+  const output = runner.runModel(modelText, { options: config.options });
+
+  if (output.message) {
+    writeLine(stderr, output.message);
+  }
+
+  if (config.options.showModelStatistics) {
+    writeLine(stdout, output.modelStatistics ?? "");
+    return PictErrorCode.Success;
+  }
+
+  writeLine(stdout, formatResult(output.result));
+  return PictErrorCode.Success;
+}
+
+try {
+  const exitCode = await main(argv.slice(2));
+  exit(exitCode);
+} catch (error) {
+  if (error instanceof CliError) {
+    writeLine(error.stream === "stdout" ? stdout : stderr, error.message);
+    exit(error.code);
+  }
+
+  if (error instanceof PictError) {
+    writeLine(stderr, error.message);
+    exit(error.code);
+  }
+
+  if (error instanceof Error) {
+    writeLine(stderr, `Fatal error: ${error.message}`);
+  } else {
+    writeLine(stderr, "Fatal error: Unknown error");
+  }
+  exit(1);
+}

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "pict-cli",
+  "version": "0.1.0",
+  "description": "A CLI tool for PICT, a combinatorial testing tool developed by Microsoft. This project provides a command-line interface to generate test cases using PICT's algorithms, making it easier for developers to create comprehensive test suites for their applications.",
+  "keywords": [
+    "pict",
+    "testing",
+    "testing-tools",
+    "test-case-generation",
+    "combinatorial-testing",
+    "pairwise",
+    "pairwise-testing"
+  ],
+  "homepage": "https://github.com/takeyaqa/pict-cli#readme",
+  "bugs": {
+    "url": "https://github.com/takeyaqa/pict-cli/issues"
+  },
+  "license": "MIT",
+  "author": "Takeshi Kishi",
+  "files": [
+    "bin"
+  ],
+  "bin": {
+    "pict-cli": "bin/cli.js"
+  },
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/takeyaqa/pict-cli.git"
+  },
+  "dependencies": {
+    "@takeyaqa/pict-wasm": "3.7.4-wasm.17"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "eslint": "^10.0.3",
+    "eslint-config-prettier": "^10.1.8",
+    "prettier": "^3.8.1"
+  },
+  "engines": {
+    "node": "^22 || ^24"
+  },
+  "devEngines": {
+    "runtime": {
+      "name": "node",
+      "version": "^22"
+    },
+    "packageManager": [
+      {
+        "name": "pnpm",
+        "version": "^10"
+      }
+    ]
+  },
+  "scripts": {
+    "fmt": "prettier --write .",
+    "fmt:check": "prettier --check .",
+    "lint": "eslint .",
+    "lint:fix": "eslint --fix .",
+    "test": "node --test tests/e2e.spec.js"
+  }
+}