parity-guard-test-pattern

Parity Guard Test Pattern

The Problem

When checking that all callers of a contract implement it correctly, you get false positives from wrapper delegators:

// Contract: "All files that call exec() must handle exit code 2"

// Direct caller — MUST implement contract
execFileSync('node', [script]); // Must handle exit code

// Delegator — calls wrapper that already handles contract
runMuscle(script); // runMuscle handles exit code internally

Testing both the same way creates noise.

The Solution

Split tests into DIRECT callers and DELEGATION callers.

// parity-guard.test.js

const directCallers = findFiles((content) => 
  content.includes("child_process") && 
  /exec(File)?Sync|spawn/.test(content)
);

const wrapperCallers = findFiles((content) =>
  /runMuscle|muscleAndPrompt|executeScript/.test(content)
);

describe('Contract: exit code handling', () => {
  describe('Direct callers (must implement)', () => {
    directCallers.forEach(file => {
      it(`${file} handles exit code 2`, () => {
        const content = fs.readFileSync(file, 'utf8');
        expect(content).toMatch(/exitCode|status|code.*===?\s*2/);
      });
    });
  });

  describe('Delegators (exempt — wrapper handles)', () => {
    wrapperCallers.forEach(file => {
      it(`${file} uses contract-compliant wrapper`, () => {
        const content = fs.readFileSync(file, 'utf8');
        // Just verify they use the wrapper, not raw exec
        expect(content).not.toMatch(/execFileSync|execSync/);
      });
    });
  });
});

Classification Rules

Pattern	Category	Contract Obligation
require('child_process') + exec*	Direct	Must implement
import { spawn } + spawn()	Direct	Must implement
runMuscle()	Delegator	Exempt
shellExecute() (if contract-compliant)	Delegator	Exempt

Verification

1. Direct callers all implement the contract
2. Delegators use compliant wrappers
3. No false positives from wrapper usage
4. New callers are automatically classified