feat: add CI sync check for bash/TS shared library parity (kaizen qwibitai#347) (#269)

aviadr1 · claude · web-flow · commit 0597c11cd89d · 2026-03-21T13:33:37.000Z
Adds a vitest test that parses function names from both bash and TS
shared libraries (state-utils, parse-command) and flags any functions
present in one but not the other. Explicit exclusions with reasons are
required for intentionally asymmetric functions.

Also ports 3 missing parse-command functions to TS:
- extractGitCPath: extract -C path from git commands
- detectGhRepo: detect GitHub repo from remote URL
- getPrChangedFiles: get changed files for PR commands

batch-260321-1108-3ef8/run-12

Co-authored-by: Claude Opus 4.6 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/src/hooks/bash-ts-parity.test.ts b/src/hooks/bash-ts-parity.test.ts
@@ -0,0 +1,192 @@
+/**
+ * bash-ts-parity.test.ts — CI sync check for bash/TS shared library parity.
+ *
+ * Ensures that functions in the bash shared libraries (state-utils.sh,
+ * parse-command.sh) have corresponding TypeScript implementations, and
+ * vice versa. Drift between the two was undetected until manual comparison
+ * (kaizen #347).
+ *
+ * Naming convention: bash uses snake_case, TS uses camelCase.
+ * The test normalizes both to compare.
+ */
+
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { describe, expect, it } from 'vitest';
+
+const HOOKS_LIB_DIR = join(__dirname, '../../.claude/kaizen/hooks/lib');
+const HOOKS_TS_DIR = __dirname;
+
+// Functions intentionally present in only one version.
+// Each entry must have a comment explaining WHY it's excluded.
+const EXCLUSIONS: Record<string, string> = {
+  // Requires `gh` CLI calls — intentionally stays bash-only (shell orchestration)
+  auto_close_kaizen_issues: 'bash-only: requires gh CLI for PR state checks',
+  // Requires `gh` CLI for PR state lookup + auto-clear — bash-only orchestration
+  find_needs_review_state:
+    'bash-only: requires gh CLI for merged/closed PR auto-clear',
+
+  // TS internal helpers with no bash equivalent (TS uses structured objects)
+  parseStateFile: 'ts-only: internal helper, bash uses grep/cut inline',
+  serializeStateFile: 'ts-only: internal helper, bash uses printf inline',
+  ensureStateDir: 'ts-only: internal helper, bash uses mkdir -p inline',
+  writeStateFile: 'ts-only: internal helper for atomic writes',
+
+  // TS splits extractPrUrl from reconstructPrUrl; bash inlines the grep
+  extractPrUrl:
+    'ts-only: extracted helper, bash inlines grep in reconstruct_pr_url',
+};
+
+/** Extract function names from a bash script (matches `function_name() {`). */
+function extractBashFunctions(filePath: string): string[] {
+  const content = readFileSync(filePath, 'utf-8');
+  const pattern = /^([a-z_][a-z0-9_]*)\s*\(\)/gm;
+  const functions: string[] = [];
+  let match;
+  while ((match = pattern.exec(content)) !== null) {
+    functions.push(match[1]);
+  }
+  return functions;
+}
+
+/** Extract exported function names from a TypeScript file. */
+function extractTsFunctions(filePath: string): string[] {
+  const content = readFileSync(filePath, 'utf-8');
+  const pattern = /^export\s+function\s+([a-zA-Z_][a-zA-Z0-9_]*)/gm;
+  const functions: string[] = [];
+  let match;
+  while ((match = pattern.exec(content)) !== null) {
+    functions.push(match[1]);
+  }
+  return functions;
+}
+
+/** Convert snake_case to camelCase for comparison. */
+function snakeToCamel(name: string): string {
+  return name.replace(/_([a-z])/g, (_, c) => c.toUpperCase());
+}
+
+/** Convert camelCase to snake_case for comparison. */
+function camelToSnake(name: string): string {
+  return name.replace(/[A-Z]/g, (c) => `_${c.toLowerCase()}`);
+}
+
+function checkParity(bashFile: string, tsFile: string) {
+  const bashFns = extractBashFunctions(join(HOOKS_LIB_DIR, bashFile));
+  const tsFns = extractTsFunctions(join(HOOKS_TS_DIR, tsFile));
+
+  // Normalize bash names to camelCase for comparison
+  const bashCamel = new Map(bashFns.map((fn) => [snakeToCamel(fn), fn]));
+
+  // Normalize TS names to snake_case for comparison
+  const tsSnake = new Map(tsFns.map((fn) => [camelToSnake(fn), fn]));
+
+  // Find bash functions missing from TS
+  const missingInTs: string[] = [];
+  for (const [camelName, bashName] of bashCamel) {
+    if (!tsFns.includes(camelName) && !EXCLUSIONS[bashName]) {
+      missingInTs.push(bashName);
+    }
+  }
+
+  // Find TS functions missing from bash
+  const missingInBash: string[] = [];
+  for (const [snakeName, tsName] of tsSnake) {
+    if (!bashFns.includes(snakeName) && !EXCLUSIONS[tsName]) {
+      missingInBash.push(tsName);
+    }
+  }
+
+  return { bashFns, tsFns, missingInTs, missingInBash };
+}
+
+describe('bash/TS shared library parity', () => {
+  describe('state-utils', () => {
+    it('all bash functions have TS equivalents (or are excluded)', () => {
+      const { missingInTs } = checkParity('state-utils.sh', 'state-utils.ts');
+      expect(
+        missingInTs,
+        `Bash functions missing TS equivalent: ${missingInTs.join(', ')}. Either port them or add to EXCLUSIONS with a reason.`,
+      ).toEqual([]);
+    });
+
+    it('all TS functions have bash equivalents (or are excluded)', () => {
+      const { missingInBash } = checkParity('state-utils.sh', 'state-utils.ts');
+      expect(
+        missingInBash,
+        `TS functions missing bash equivalent: ${missingInBash.join(', ')}. Either port them or add to EXCLUSIONS with a reason.`,
+      ).toEqual([]);
+    });
+
+    it('extracts functions from both files', () => {
+      const { bashFns, tsFns } = checkParity(
+        'state-utils.sh',
+        'state-utils.ts',
+      );
+      expect(bashFns.length).toBeGreaterThan(5);
+      expect(tsFns.length).toBeGreaterThan(5);
+    });
+  });
+
+  describe('parse-command', () => {
+    it('all bash functions have TS equivalents (or are excluded)', () => {
+      const { missingInTs } = checkParity(
+        'parse-command.sh',
+        'parse-command.ts',
+      );
+      expect(
+        missingInTs,
+        `Bash functions missing TS equivalent: ${missingInTs.join(', ')}. Either port them or add to EXCLUSIONS with a reason.`,
+      ).toEqual([]);
+    });
+
+    it('all TS functions have bash equivalents (or are excluded)', () => {
+      const { missingInBash } = checkParity(
+        'parse-command.sh',
+        'parse-command.ts',
+      );
+      expect(
+        missingInBash,
+        `TS functions missing bash equivalent: ${missingInBash.join(', ')}. Either port them or add to EXCLUSIONS with a reason.`,
+      ).toEqual([]);
+    });
+
+    it('extracts functions from both files', () => {
+      const { bashFns, tsFns } = checkParity(
+        'parse-command.sh',
+        'parse-command.ts',
+      );
+      expect(bashFns.length).toBeGreaterThan(3);
+      expect(tsFns.length).toBeGreaterThan(3);
+    });
+  });
+
+  describe('exclusions are valid', () => {
+    it('all excluded functions actually exist in their source', () => {
+      const stateUtilsBash = extractBashFunctions(
+        join(HOOKS_LIB_DIR, 'state-utils.sh'),
+      );
+      const parseCommandBash = extractBashFunctions(
+        join(HOOKS_LIB_DIR, 'parse-command.sh'),
+      );
+      const allBash = [...stateUtilsBash, ...parseCommandBash];
+
+      const stateUtilsTs = extractTsFunctions(
+        join(HOOKS_TS_DIR, 'state-utils.ts'),
+      );
+      const parseCommandTs = extractTsFunctions(
+        join(HOOKS_TS_DIR, 'parse-command.ts'),
+      );
+      const allTs = [...stateUtilsTs, ...parseCommandTs];
+
+      for (const excluded of Object.keys(EXCLUSIONS)) {
+        const existsInBash = allBash.includes(excluded);
+        const existsInTs = allTs.includes(excluded);
+        expect(
+          existsInBash || existsInTs,
+          `Exclusion '${excluded}' doesn't exist in either bash or TS — remove stale exclusion`,
+        ).toBe(true);
+      }
+    });
+  });
+});
diff --git a/src/hooks/parse-command.test.ts b/src/hooks/parse-command.test.ts
@@ -1,8 +1,11 @@
 import { describe, expect, it } from 'vitest';
 import {
+  detectGhRepo,
+  extractGitCPath,
   extractPrNumber,
   extractPrUrl,
   extractRepoFlag,
+  getPrChangedFiles,
   isGhPrCommand,
   isGitCommand,
   reconstructPrUrl,
@@ -129,6 +132,78 @@ describe('extractPrUrl', () => {
   });
 });
 
+describe('extractGitCPath', () => {
+  it('extracts -C path from git command', () => {
+    expect(extractGitCPath('git -C /some/path push origin main')).toBe(
+      '/some/path',
+    );
+  });
+
+  it('returns undefined when no -C flag', () => {
+    expect(extractGitCPath('git push origin main')).toBeUndefined();
+  });
+
+  it('handles piped commands', () => {
+    expect(extractGitCPath('echo test | git -C /foo status')).toBe('/foo');
+  });
+});
+
+describe('detectGhRepo', () => {
+  it('detects repo from HTTPS URL', () => {
+    expect(detectGhRepo('https://github.com/Garsson-io/nanoclaw.git')).toBe(
+      'Garsson-io/nanoclaw',
+    );
+  });
+
+  it('detects repo from SSH URL', () => {
+    expect(detectGhRepo('git@github.com:Garsson-io/nanoclaw.git')).toBe(
+      'Garsson-io/nanoclaw',
+    );
+  });
+
+  it('returns undefined for non-GitHub URL', () => {
+    expect(detectGhRepo('https://gitlab.com/foo/bar.git')).toBeUndefined();
+  });
+});
+
+describe('getPrChangedFiles', () => {
+  it('uses gh pr diff for merge commands', () => {
+    const executor = (cmd: string) => {
+      if (cmd.includes('gh pr diff')) return 'file1.ts\nfile2.ts\n';
+      return '';
+    };
+    const files = getPrChangedFiles(
+      'gh pr merge 42 --repo Garsson-io/nanoclaw',
+      true,
+      executor,
+    );
+    expect(files).toEqual(['file1.ts', 'file2.ts']);
+  });
+
+  it('falls back to git diff when gh pr diff returns empty', () => {
+    const executor = (cmd: string) => {
+      if (cmd.includes('gh pr diff')) return '';
+      if (cmd.includes('git diff')) return 'fallback.ts\n';
+      return '';
+    };
+    const files = getPrChangedFiles('gh pr merge 42', true, executor);
+    expect(files).toEqual(['fallback.ts']);
+  });
+
+  it('uses git diff for create commands', () => {
+    const executor = (cmd: string) => {
+      if (cmd.includes('git diff')) return 'new-file.ts\n';
+      return '';
+    };
+    const files = getPrChangedFiles(
+      'gh pr create --title test',
+      false,
+      executor,
+    );
+    expect(files).toEqual(['new-file.ts']);
+  });
+});
+
 describe('reconstructPrUrl', () => {
   it('extracts from stdout first', () => {
     expect(
diff --git a/src/hooks/parse-command.ts b/src/hooks/parse-command.ts
@@ -69,6 +69,19 @@ export function extractPrNumber(
   return match?.[1];
 }
 
+/**
+ * Extract the -C <path> argument from a git command, if present.
+ * Bash equivalent: extract_git_c_path()
+ */
+export function extractGitCPath(cmdLine: string): string | undefined {
+  const segments = splitCommandSegments(cmdLine);
+  for (const seg of segments) {
+    const match = seg.match(/^git\s+-C\s+(\S+)/);
+    if (match) return match[1];
+  }
+  return undefined;
+}
+
 /**
  * Extract --repo flag value from a command line.
  */
@@ -77,6 +90,51 @@ export function extractRepoFlag(cmdLine: string): string | undefined {
   return match?.[1];
 }
 
+/**
+ * Detect the GitHub repo (owner/name) from a git remote URL string.
+ * Handles both HTTPS and SSH URLs.
+ * Bash equivalent: detect_gh_repo() — but takes a URL string instead of
+ * calling git directly, to keep this module pure (no child_process).
+ */
+export function detectGhRepo(remoteUrl: string): string | undefined {
+  const match = remoteUrl.match(/github\.com[:/]([^/]+\/[^/.]+)/);
+  return match?.[1];
+}
+
+/**
+ * Get changed files for a PR command.
+ * For merge: returns files from `gh pr diff --name-only`.
+ * For create: returns files from `git diff --name-only main...HEAD`.
+ *
+ * Bash equivalent: get_pr_changed_files() — but takes an executor function
+ * instead of calling shell commands directly.
+ */
+export function getPrChangedFiles(
+  cmdLine: string,
+  isMerge: boolean,
+  executor: (cmd: string) => string,
+): string[] {
+  if (isMerge) {
+    const prNum = extractPrNumber(cmdLine, 'merge');
+    const repo = extractRepoFlag(cmdLine);
+    const repoFlag = repo ? `--repo ${repo}` : '';
+    const prArg = prNum ?? '';
+
+    let result = executor(`gh pr diff ${prArg} --name-only ${repoFlag}`.trim());
+    if (!result) {
+      result = executor('git diff --name-only main...HEAD');
+    }
+    return result
+      .split('\n')
+      .map((l) => l.trim())
+      .filter(Boolean);
+  }
+  return executor('git diff --name-only main...HEAD')
+    .split('\n')
+    .map((l) => l.trim())
+    .filter(Boolean);
+}
+
 /**
  * Extract a GitHub PR URL from text (stdout, stderr, or command args).
  */
