chore: harden governance health CLI args

web/scripts/__tests__/check-governance-health.test.ts

@@ -1,4 +1,4 @@
-import { describe, it, expect } from 'vitest';
+import { afterEach, describe, expect, it, vi } from 'vitest';
 import type {
   ActivityData,
   Comment,
@@ -20,6 +20,7 @@ import {
   extractRole,
   hadQuorumFailure,
   inferEligibleVoterCount,
+  parseArgs,
   percentile,
   resolveActivityFile,
 } from '../check-governance-health';
@@ -87,6 +88,52 @@ function minimalData(overrides: Partial<ActivityData> = {}): ActivityData {
   };
 }
 
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+function stubProcessExit(): ReturnType<typeof vi.spyOn> {
+  return vi.spyOn(process, 'exit').mockImplementation(((code?: number) => {
+    throw new Error(`process.exit:${code ?? 0}`);
+  }) as typeof process.exit);
+}
+
+// ──────────────────────────────────────────────
+// parseArgs
+// ──────────────────────────────────────────────
+
+describe('parseArgs', () => {
+  it('defaults to text output', () => {
+    expect(parseArgs([])).toEqual({ json: false });
+  });
+
+  it('enables json output with --json', () => {
+    expect(parseArgs(['--json'])).toEqual({ json: true });
+  });
+
+  it('prints help and exits 0 for --help', () => {
+    const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+    const exitSpy = stubProcessExit();
+
+    expect(() => parseArgs(['--help'])).toThrow('process.exit:0');
+    expect(logSpy).toHaveBeenCalledWith(
+      'Usage: npm run check-governance-health -- [--json]'
+    );
+    expect(exitSpy).toHaveBeenCalledWith(0);
+  });
+
+  it('rejects unknown flags', () => {
+    const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+    const exitSpy = stubProcessExit();
+
+    expect(() => parseArgs(['--jsom'])).toThrow('process.exit:1');
+    expect(errorSpy).toHaveBeenCalledWith(
+      'Unknown argument "--jsom". Expected --json or --help.'
+    );
+    expect(exitSpy).toHaveBeenCalledWith(1);
+  });
+});
+
 // ──────────────────────────────────────────────
 // extractRole
 // ──────────────────────────────────────────────

web/scripts/check-governance-health.ts

@@ -37,6 +37,10 @@ const DEFAULT_ACTIVITY_FILE = join(
   'activity.json'
 );
 
+interface CliOptions {
+  json: boolean;
+}
+
 // ──────────────────────────────────────────────
 // Types
 // ──────────────────────────────────────────────
@@ -708,14 +712,41 @@ export function resolveActivityFile(
   return env.ACTIVITY_FILE ?? DEFAULT_ACTIVITY_FILE;
 }
 
+function printHelp(): void {
+  console.log('Usage: npm run check-governance-health -- [--json]');
+}
+
+export function parseArgs(argv: string[]): CliOptions {
+  const options: CliOptions = {
+    json: false,
+  };
+
+  for (const arg of argv) {
+    if (arg === '--json') {
+      options.json = true;
+      continue;
+    }
+
+    if (arg === '--help') {
+      printHelp();
+      process.exit(0);
+    }
+
+    console.error(`Unknown argument "${arg}". Expected --json or --help.`);
+    process.exit(1);
+  }
+
+  return options;
+}
+
 function isDirectExecution(): boolean {
   if (!process.argv[1]) return false;
   return resolve(process.argv[1]) === resolve(fileURLToPath(import.meta.url));
 }
 
 async function main(): Promise<void> {
   const activityFile = resolveActivityFile();
-  const isJson = process.argv.includes('--json');
+  const { json } = parseArgs(process.argv.slice(2));
 
   if (!existsSync(activityFile)) {
     console.error(`Activity file not found: ${activityFile}`);
@@ -728,7 +759,7 @@ async function main(): Promise<void> {
   const data = JSON.parse(readFileSync(activityFile, 'utf-8')) as ActivityData;
   const report = buildHealthReport(data);
 
-  if (isJson) {
+  if (json) {
     console.log(JSON.stringify(report, null, 2));
   } else {
     printReport(report);