Skip to content

Turn any idea, plan, or codebase into a beautiful interactive diagram. An agent skill for Claude Code, Codex, and more.

fix(cli): fail inspect arguments closed with truthful diagnostics (#789)

robll-v1b6650d5eb85a
diff --git a/archify.zip b/archify.zip
index e78edcd1..59b52548 100644
Binary files a/archify.zip and b/archify.zip differ
diff --git a/archify/bin/archify.mjs b/archify/bin/archify.mjs
index 8cc30c12..62c9bfe9 100755
--- a/archify/bin/archify.mjs
+++ b/archify/bin/archify.mjs
@@ -6814,7 +6814,10 @@ async function commandMigrate(args) {
}
}
-async function commandValidate(args) {
+// `inspect` delegates here in layout-JSON mode, so argument failures must be
+// attributed to the command the caller actually invoked.
+async function commandValidate(args, invocation = {}) {
+ const invokingCommand = invocation.command || 'validate';
const qualityArgs = extractQualityArgs(args);
const repoArgs = extractRepoRootArgs(qualityArgs.rest);
args = repoArgs.rest;
@@ -6822,7 +6825,7 @@ async function commandValidate(args) {
const repoRoot = repoArgs.repoRoot;
const knownOptions = new Set(['--json', '--layout-json']);
const unknown = args.filter((arg) => arg.startsWith('--') && !knownOptions.has(arg));
- if (unknown.length) rejectCliArgument(`Unknown validate option "${unknown[0]}".`, {
+ if (unknown.length) rejectCliArgument(`Unknown ${invokingCommand} option "${unknown[0]}".`, {
code: 'cli/unknown-option',
subject: { option: unknown[0] },
supportedFixes: ['remove the unknown option and retry'],
@@ -6833,7 +6836,7 @@ async function commandValidate(args) {
const [type, input] = rest;
if (!type || !input || rest.length !== 2) rejectCliArgument(usage(), {
code: 'cli/usage',
- supportedFixes: ['use: archify validate <type> <input.json> [options]'],
+ supportedFixes: [`use: archify ${invokingCommand} <type> <input.json> [options]`],
});
const renderer = rendererPath(type);
@@ -7077,9 +7080,13 @@ try {
break;
case 'inspect':
if (args[0] !== 'architecture') {
- fail('inspect is currently supported for architecture diagrams only.');
+ rejectCliArgument('inspect is currently supported for architecture diagrams only.', {
+ code: 'cli/unsupported-option',
+ subject: { command: 'inspect', type: args[0] },
+ supportedFixes: ['use an architecture diagram', 'use validate <type> <input.json> --layout-json for workflow diagrams'],
+ });
}
- commandValidate([...args, '--layout-json']);
+ await commandValidate([...args, '--layout-json'], { command: 'inspect' });
break;
case 'check':
await commandCheck(args);
@@ -7110,7 +7117,7 @@ try {
}
} catch (error) {
if (!error.archifyArgument) throw error;
- if (['validate', 'deliver', 'finalize'].includes(command) && args.includes('--json')) {
+ if (['validate', 'deliver', 'finalize', 'inspect'].includes(command) && args.includes('--json')) {
reportArtifactArgumentFailure(command, error);
} else {
fail(error.message);
diff --git a/test/cli.test.mjs b/test/cli.test.mjs
index 8872ee4d..12330680 100644
--- a/test/cli.test.mjs
+++ b/test/cli.test.mjs
@@ -4415,9 +4415,10 @@ test('cli: validate rejects unknown flags, layout-json assignment typos, and ext
}
});
-test('cli: validate and deliver keep argument failures machine-readable with --json', () => {
+test('cli: validate, deliver, and inspect keep argument failures machine-readable with --json', () => {
const workflow = path.join(skillRoot, 'examples/agent-tool-call.workflow.json');
const sequence = path.join(skillRoot, 'examples/cache-miss-request.sequence.json');
+ const architecture = path.join(skillRoot, 'examples/web-app.architecture.json');
const cases = [
{
args: ['validate', '--json'],
@@ -4505,6 +4506,30 @@ test('cli: validate and deliver keep argument failures machine-readable with --j
command: 'deliver',
code: 'cli/usage',
},
+ {
+ args: ['inspect', 'architecture', architecture, '--json', '--bogus'],
+ command: 'inspect',
+ code: 'cli/unknown-option',
+ subject: { option: '--bogus' },
+ },
+ {
+ args: ['inspect', 'architecture', '--json'],
+ command: 'inspect',
+ code: 'cli/usage',
+ },
+ {
+ args: ['inspect', 'architecture', architecture, 'extra.json', '--json'],
+ command: 'inspect',
+ code: 'cli/usage',
+ },
+ {
+ // The architecture-only selector guard runs before the delegate, so it
+ // must raise a rejectable argument failure rather than fail() early.
+ args: ['inspect', 'workflow', workflow, '--json'],
+ command: 'inspect',
+ code: 'cli/unsupported-option',
+ subject: { type: 'workflow' },
+ },
];
for (const { args, command, code, subject = {} } of cases) {
@@ -4528,6 +4553,31 @@ test('cli: validate and deliver keep argument failures machine-readable with --j
}
});
+test('cli: inspect argument failures exit 2 with a clean, truthful diagnostic', () => {
+ const architecture = path.join(skillRoot, 'examples/web-app.architecture.json');
+
+ // Without `await`, the delegated async validate call rejects past the
+ // top-level catch: exit 1, a raw Node stack trace, and a "validate" message.
+ const unknown = run(['inspect', 'architecture', architecture, '--bogus']);
+ assert.equal(unknown.status, 2, unknown.stderr);
+ assert.equal(unknown.stdout, '');
+ assert.equal(unknown.stderr.trim(), 'Unknown inspect option "--bogus".');
+ assert.doesNotMatch(unknown.stderr, /^\s+at /m);
+ assert.equal(unknown.stderr.includes('Node.js v'), false);
+
+ for (const args of [
+ ['inspect', 'architecture'],
+ ['inspect', 'architecture', architecture, 'extra.json'],
+ ]) {
+ const result = run(args);
+ assert.equal(result.status, 2, `${args.join(' ')}\n${result.stderr}\n${result.stdout}`);
+ assert.equal(result.stdout, '');
+ assert.match(result.stderr, /^Usage:/m);
+ assert.doesNotMatch(result.stderr, /^\s+at /m);
+ assert.equal(result.stderr.includes('Node.js v'), false);
+ }
+});
+
test('cli: inspect emits architecture layout json', () => {
const input = path.resolve(skillRoot, '../examples/archify-repo-grid.architecture.json');
const result = run(['inspect', 'architecture', input]);
@@ -4546,6 +4596,21 @@ test('cli: inspect remains architecture-only while workflow uses validate --layo
assert.equal(result.status, 2);
assert.match(result.stderr, /inspect is currently supported for architecture diagrams only/);
assert.equal(result.stdout, '');
+ assert.doesNotMatch(result.stderr, /^\s+at /m);
+
+ // `--json` must reach the same machine-readable argument receipt as every
+ // other rejected `inspect` invocation instead of exiting before it.
+ const json = run(['inspect', 'workflow', input, '--json']);
+ assert.equal(json.status, 2, json.stderr || json.stdout);
+ assert.equal(json.stderr, '');
+ const failure = JSON.parse(json.stdout);
+ assert.equal(failure.ok, false);
+ assert.equal(failure.command, 'inspect');
+ assert.equal(failure.stage, 'arguments');
+ assert.equal(failure.diagnostics[0].code, 'cli/unsupported-option');
+ assert.deepEqual(failure.diagnostics[0].subject, { command: 'inspect', type: 'workflow' });
+ assert.ok(failure.diagnostics[0].supportedFixes.length > 0);
+ assert.equal('stack' in failure, false);
});
test('cli: validate returns renderer errors for bad input', () => {