feat(cli): add orgscript check combined quality command

Author: DKFuH

CHANGELOG.md

@@ -8,6 +8,7 @@ The format is based on Keep a Changelog, and this project follows Semantic Versi
 
 - Added `orgscript format <file> --check` for canonical formatting checks without rewriting files.
 - Added `npm run format:check:all` and integrated formatting checks into CI.
+- Added `orgscript check <file>` as the combined quality command for validation, linting, and formatting checks.
 
 ## [0.3.0] - 2026-03-29
 

README.md

@@ -145,6 +145,7 @@ See the full example in [`examples/craft-business-lead-to-order.orgs`](examples/
 - AST-backed formatting: `orgscript format <file>`
 - Canonical format checks: `orgscript format <file> --check`
 - AST-backed linting: `orgscript lint <file>`
+- Combined quality checks: `orgscript check <file>`
 - Canonical JSON export: `orgscript export json <file>`
 - Machine-readable diagnostics: `orgscript validate <file> --json`, `orgscript lint <file> --json`
 - Golden snapshot tests for AST, canonical model, and formatter output
@@ -167,6 +168,7 @@ Exit codes are CI-friendly:
 
 - `validate` returns `0` for valid files and `1` for invalid files.
 - `lint` returns `0` when findings contain only `warning` and `info`, and `1` when findings contain at least one `error`.
+- `check` returns `0` only when validation passes, lint has no `error`, and formatting is canonical. Warnings and info findings alone do not fail `check`.
 
 ## Guides
 
@@ -176,11 +178,11 @@ Exit codes are CI-friendly:
 
 ## Near-term plan
 
-1. Add `format --check` for CI and pre-commit workflows.
-2. Show real JSON diagnostics examples in the README and diagnostics spec.
-3. Add `orgscript check` as a combined quality command.
-4. Improve diagnostics consistency across CLI commands.
-5. Add an initial VS Code syntax highlighting scaffold.
+1. Show real JSON diagnostics examples in the README and diagnostics spec.
+2. Improve diagnostics consistency across CLI commands.
+3. Add `orgscript check --json` for machine-readable combined quality output.
+4. Add an initial VS Code syntax highlighting scaffold.
+5. Add a first editor integration path that contributors can install locally.
 
 See [`docs/roadmaps/v0.4.0.md`](docs/roadmaps/v0.4.0.md) for the current milestone plan.
 
@@ -196,8 +198,11 @@ orgscript format file.orgs --check
 orgscript lint file.orgs
 orgscript lint file.orgs --json
 orgscript export json file.orgs
+orgscript check file.orgs
 ```
 
+`orgscript check` runs `validate`, `lint`, and `format --check` in that order and fails on validation errors, lint errors, or formatting drift. Warnings and info findings alone do not fail the command.
+
 See [`docs/cli-v0.1-plan.md`](docs/cli-v0.1-plan.md) for the implementation plan.
 
 ## Testing

docs/cli-v0.1-plan.md

@@ -17,6 +17,7 @@ Implemented:
 - `export json`
 - `validate --json`
 - `lint --json`
+- `check`
 
 Planned next:
 
@@ -76,6 +77,26 @@ Output model:
 - one stable line per finding using severity, code, line, and message
 - optional machine-readable diagnostics via `--json`
 
+### `orgscript check <file>`
+
+Runs the quality pipeline in one command:
+
+- `validate`
+- `lint`
+- `format --check`
+
+Output:
+
+- compact pass/fail summary for each stage
+- clear indication of which stage failed
+- stable text output suitable for CI logs
+
+Exit behavior:
+
+- `0` when validation passes, lint has no `error`, and formatting is canonical
+- `1` when validation fails, lint finds at least one `error`, or formatting drift is detected
+- warnings and info findings alone do not fail the command
+
 Initial lint rules:
 
 - duplicate state names
@@ -126,6 +147,7 @@ TypeScript is the fastest start:
 - One can run `orgscript validate --json` and `orgscript lint --json` for downstream tooling.
 - One can run `orgscript format` on example files without changing canonical files.
 - One can run `orgscript format --check` in CI or pre-commit workflows.
+- One can run `orgscript check` to combine validation, linting, and format checks.
 - One can run `orgscript lint` on valid but suspicious models and get stable findings.
 - Lint exit codes are safe for CI use with advisory warnings.
 - Invalid files produce useful errors with line references.

src/cli.js

@@ -15,6 +15,7 @@ function printUsage() {
 
 Usage:
   orgscript validate <file> [--json]
+  orgscript check <file>
   orgscript format <file> [--check]
   orgscript lint <file> [--json]
   orgscript export json <file>
@@ -51,6 +52,15 @@ function run(args) {
     process.exit(0);
   }
 
+  if (command === "check") {
+    const absolutePath = resolveFile("check", maybeSubcommand);
+    const result = runCheck(absolutePath);
+    const lines = renderCheckReport(absolutePath, result);
+    const stream = result.ok ? console.log : console.error;
+    stream(lines.join("\n"));
+    process.exit(result.ok ? 0 : 1);
+  }
+
   if (command === "export" && maybeSubcommand === "json") {
     const absolutePath = resolveFile("export", maybeFile);
     const result = buildModel(absolutePath);
@@ -204,4 +214,93 @@ function printIssues(header, issues) {
   }
 }
 
+function runCheck(filePath) {
+  const validation = validateFile(filePath);
+
+  if (!validation.ok) {
+    return {
+      ok: false,
+      validate: {
+        ok: false,
+        issues: validation.issues,
+      },
+      lint: {
+        ok: false,
+        skipped: true,
+        findings: [],
+        summary: { error: 0, warning: 0, info: 0 },
+      },
+      format: {
+        ok: false,
+        skipped: true,
+        requiresChanges: false,
+      },
+    };
+  }
+
+  const findings = lintDocument(validation.ast);
+  const lintSummary = summarizeFindings(findings);
+  const current = fs.readFileSync(filePath, "utf8");
+  const formatted = formatDocument(validation.ast);
+  const requiresChanges = current !== formatted;
+  const lintOk = lintSummary.error === 0;
+  const formatOk = !requiresChanges;
+
+  return {
+    ok: lintOk && formatOk,
+    validate: {
+      ok: true,
+      issues: [],
+    },
+    lint: {
+      ok: lintOk,
+      skipped: false,
+      findings,
+      summary: lintSummary,
+    },
+    format: {
+      ok: formatOk,
+      skipped: false,
+      requiresChanges,
+    },
+  };
+}
+
+function renderCheckReport(filePath, result) {
+  const lines = [`CHECK ${toDisplayPath(filePath)}`];
+
+  if (result.validate.ok) {
+    lines.push("  validate: ok");
+  } else {
+    lines.push("  validate: failed");
+    for (const issue of result.validate.issues) {
+      lines.push(`    line ${issue.line}: ${issue.message}`);
+    }
+  }
+
+  if (result.lint.skipped) {
+    lines.push("  lint: skipped");
+  } else {
+    const { error, warning, info } = result.lint.summary;
+    const status = result.lint.ok ? "ok" : "failed";
+    lines.push(`  lint: ${status} (${error} error(s), ${warning} warning(s), ${info} info)`);
+  }
+
+  if (result.format.skipped) {
+    lines.push("  format: skipped");
+  } else if (result.format.ok) {
+    lines.push("  format: ok");
+  } else {
+    lines.push("  format: failed (canonical formatting changes required)");
+  }
+
+  lines.push(`Result: ${result.ok ? "PASS" : "FAIL"}`);
+  return lines;
+}
+
+function toDisplayPath(filePath) {
+  const relative = path.relative(process.cwd(), filePath).replace(/\\/g, "/");
+  return relative || path.basename(filePath);
+}
+
 module.exports = { run };

tests/run.js

@@ -25,6 +25,7 @@ function run() {
   testFormatterStability();
   testCliDiagnosticsAndExitCodes();
   testFormatCheckMode();
+  testCheckCommand();
   console.log("All tests passed.");
 }
 
@@ -318,6 +319,80 @@ function testFormatCheckMode() {
   );
 }
 
+function testCheckCommand() {
+  const cliPath = path.join(repoRoot, "bin", "orgscript.js");
+  const canonicalSourcePath = path.join(examplesDir, "craft-business-lead-to-order.orgs");
+  const canonicalSource = fs.readFileSync(canonicalSourcePath, "utf8");
+
+  const checkOk = runCli([cliPath, "check", "./examples/craft-business-lead-to-order.orgs"]);
+  assert.strictEqual(checkOk.status, 0, "Expected check to pass for canonical example");
+  assert.ok(
+    checkOk.stdout.includes("CHECK examples/craft-business-lead-to-order.orgs"),
+    "Expected check header in check output"
+  );
+  assert.ok(checkOk.stdout.includes("validate: ok"), "Expected validate pass in check output");
+  assert.ok(checkOk.stdout.includes("lint: ok (0 error(s), 0 warning(s), 0 info)"), "Expected lint pass in check output");
+  assert.ok(checkOk.stdout.includes("format: ok"), "Expected format pass in check output");
+  assert.ok(checkOk.stdout.includes("Result: PASS"), "Expected passing summary in check output");
+
+  const checkWarning = runCli([cliPath, "check", "./tests/lint/process-missing-trigger.orgs"]);
+  assert.strictEqual(checkWarning.status, 0, "Expected warning-only check to stay non-failing");
+  assert.ok(
+    checkWarning.stdout.includes("lint: ok (0 error(s), 1 warning(s), 0 info)"),
+    "Expected warning summary in check output"
+  );
+  assert.ok(
+    checkWarning.stdout.includes("Result: PASS"),
+    "Expected overall pass for warning-only check"
+  );
+
+  const checkLintError = runCli([cliPath, "check", "./tests/lint/process-multiple-triggers.orgs"]);
+  assert.strictEqual(checkLintError.status, 1, "Expected check to fail on lint errors");
+  assert.ok(
+    checkLintError.stderr.includes("lint: failed"),
+    "Expected lint failure in check output"
+  );
+  assert.ok(
+    checkLintError.stderr.includes("Result: FAIL"),
+    "Expected failed summary for lint-error check"
+  );
+
+  const nonCanonicalPath = path.join(repoRoot, "tests", ".tmp-check-noncanonical.orgs");
+  const nonCanonicalSource = canonicalSource.replace("\n\n  when lead.created", "\n  when lead.created");
+  fs.writeFileSync(nonCanonicalPath, nonCanonicalSource, "utf8");
+
+  try {
+    const checkFormatFailure = runCli([cliPath, "check", "./tests/.tmp-check-noncanonical.orgs"]);
+    assert.strictEqual(checkFormatFailure.status, 1, "Expected check to fail on format drift");
+    assert.ok(
+      checkFormatFailure.stderr.includes("format: failed"),
+      "Expected format failure in check output"
+    );
+    assert.strictEqual(
+      fs.readFileSync(nonCanonicalPath, "utf8"),
+      nonCanonicalSource,
+      "Expected check to leave non-canonical file unchanged"
+    );
+  } finally {
+    if (fs.existsSync(nonCanonicalPath)) {
+      fs.unlinkSync(nonCanonicalPath);
+    }
+  }
+
+  const checkInvalid = runCli([cliPath, "check", "./tests/invalid/unknown-top-level.orgs"]);
+  assert.strictEqual(checkInvalid.status, 1, "Expected check to fail for invalid file");
+  assert.ok(
+    checkInvalid.stderr.includes("validate: failed"),
+    "Expected validate failure in check output"
+  );
+  assert.ok(checkInvalid.stderr.includes("lint: skipped"), "Expected skipped lint in check output");
+  assert.ok(
+    checkInvalid.stderr.includes("format: skipped"),
+    "Expected skipped format in check output"
+  );
+  assert.ok(checkInvalid.stderr.includes("Result: FAIL"), "Expected failed summary for invalid file");
+}
+
 function runCli(args) {
   const result = spawnSync(process.execPath, args, {
     cwd: repoRoot,