@webpresso/agent-kit 0.21.0

package/dist/esm/audit/audit-tph-detect.js

@@ -0,0 +1,248 @@
+/**
+ * Pure detection logic for Testing Philosophy Helper (TPH) audit.
+ * Zero I/O — accepts pre-read file contents, returns structured results.
+ */
+export const DEFAULT_MAX_MOCKS = 3;
+/**
+ * Infrastructure/leaf packages that are OK to mock in unit tests.
+ * Mocking these is INFO (advisory), not ERROR.
+ * Service/business logic mocks remain ERROR.
+ */
+export const INFRA_MOCK_ALLOWLIST = new Set([
+    '@myorg/types',
+    '@myorg/utils',
+    '@myorg/urls',
+    '@myorg/i18n',
+    '@myorg/ui',
+    '@myorg/ui/icons', // Icon component subpath — pure UI primitives, same infra tier as @myorg/ui
+    '@myorg/observability',
+    '@myorg/config',
+    '@myorg/config/browser-env',
+    '@myorg/graphql-subscriptions/react',
+    '@myorg/platform-web/graphql-client',
+    '@myorg/neon', // External API client (Neon DB) — boundary mock is OK
+    '@myorg/ai-agent', // External AI service boundary (needs API keys for real calls)
+    '@myorg/git-storage', // External file storage service boundary
+    '@myorg/git-storage/git-core', // Git operations boundary
+    '@myorg/blueprint/local', // File-based service (integration tests available for some)
+    '@myorg/blueprint', // Blueprint utilities
+    // Cloudflare Workers runtime infrastructure (not available in unit tests)
+    '@sentry/cloudflare', // Sentry error tracking for Workers
+    'cloudflare:workers', // Cloudflare Workers runtime (DurableObject, etc.)
+    '@cloudflare/containers', // Cloudflare Container API
+    // FullCalendar ecosystem (calendar component tests, heavy DOM APIs unavoidable in JSDOM)
+    '@fullcalendar/react',
+    '@fullcalendar/core',
+    '@fullcalendar/daygrid',
+    '@fullcalendar/timegrid',
+    '@fullcalendar/interaction',
+    // Remix/React SSR framework (entry.server, root tests, SSR context unavailable in unit tests)
+    'isbot', // User agent detection for SSR
+    '@react-router/node', // React Router SSR node APIs
+    'react-dom/server', // React SSR rendering
+    'react-router', // React Router core (when mocked for SSR entry.server tests)
+    // GraphiQL ecosystem (GraphiQL modal tests, heavy Editor/CodeMirror unavoidable in JSDOM)
+    'graphiql',
+    '@graphiql/toolkit',
+]);
+/**
+ * Package prefixes where all subpaths are treated as infrastructure.
+ * Matches any import starting with these prefixes.
+ */
+const INFRA_MOCK_PREFIXES = [
+    '@myorg/worker-api/', // Worker infrastructure (auth, database middleware)
+    '@myorg/schema-engine/', // Build-time tooling (commands, runtime, loaders)
+    '@myorg/app-core/', // App-core subpath exports (graphql-client, etc.)
+    '@myorg/cli-utils/', // CLI infrastructure utilities (port management, wrangler, repo root)
+    '@codemirror/', // CodeMirror ecosystem - unavoidable in JSDOM (document as 1 mock when consolidated)
+    '@dnd-kit/', // Drag and drop library (sprint component tests, DOM APIs unavoidable in JSDOM)
+];
+/**
+ * External dependencies that must be mocked due to environment constraints.
+ * These are treated as infrastructure when properly documented/consolidated.
+ */
+const EXTERNAL_INFRA_DEPS = new Set([
+    'rainbowbrackets', // CodeMirror plugin (JSDOM incompatible)
+    '@replit/codemirror-minimap', // CodeMirror plugin (JSDOM incompatible)
+    '@uiw/codemirror-theme-vscode', // CodeMirror theme (JSDOM incompatible)
+]);
+/**
+ * External package prefixes treated as infrastructure.
+ * Matches any import starting with these prefixes.
+ */
+const EXTERNAL_INFRA_PREFIXES = [
+    '@opentelemetry/', // OpenTelemetry SDK - external observability boundary
+    '@modelcontextprotocol/', // MCP SDK - external protocol boundary
+    '@tanstack/', // TanStack ecosystem (react-query, etc.) - framework boundary
+    'nuqs/', // URL state management - framework boundary
+];
+export function isInfraMock(mockPath) {
+    // [TPH-INFRA] tagged mocks are always infrastructure
+    if (mockPath.startsWith('[INFRA]')) {
+        return true;
+    }
+    if (INFRA_MOCK_ALLOWLIST.has(mockPath)) {
+        return true;
+    }
+    if (EXTERNAL_INFRA_DEPS.has(mockPath)) {
+        return true;
+    }
+    if (INFRA_MOCK_PREFIXES.some((prefix) => mockPath.startsWith(prefix))) {
+        return true;
+    }
+    if (EXTERNAL_INFRA_PREFIXES.some((prefix) => mockPath.startsWith(prefix))) {
+        return true;
+    }
+    // Generated code (hooks, frontend nav) is infrastructure
+    return mockPath.includes('/generated/');
+}
+/**
+ * Check if a mock has [TPH-INFRA] tag in comment above it.
+ * This allows marking relative-path mocks as infrastructure.
+ */
+function hasInfraTag(content, matchIndex) {
+    // Look at previous 300 chars for [TPH-INFRA] tag (allows for longer JSDoc comments)
+    const before = content.slice(Math.max(0, matchIndex - 300), matchIndex);
+    return /\[TPH-INFRA\]/.test(before);
+}
+/**
+ * Check if a mock factory replaces behavior (vi.fn, class, spy patterns)
+ * vs. returning only pure data/constants.
+ */
+function mockHasBehavior(content, matchIndex) {
+    const rest = content.slice(matchIndex);
+    const factoryMatch = rest.match(/vi\.mock\([^,]+,\s*(?:async\s*)?\(\)\s*=>\s*/);
+    if (!factoryMatch) {
+        return true; // No factory = auto-mock, replaces everything
+    }
+    const bodyStart = (factoryMatch.index ?? 0) + factoryMatch[0].length;
+    const bodySlice = rest.slice(bodyStart, bodyStart + 500);
+    return /vi\.fn|mockResolvedValue|mockReturnValue|mockImplementation|\bclass\b/.test(bodySlice);
+}
+/**
+ * Check if a mock path is a local/relative path (same-package mock).
+ * Local mocks (./  ../  #) are excluded from over-mocking counts
+ * because they mock within the same package, not across boundaries.
+ */
+export function isLocalMock(mockPath) {
+    return (mockPath.startsWith('./') ||
+        mockPath.startsWith('../') ||
+        mockPath.startsWith('#') ||
+        mockPath.endsWith('?url') // CSS/asset imports (e.g., './globals.css?url')
+    );
+}
+function classifyMockPath(mockPath, hasBehavior, isTaggedInfra, result) {
+    if (isTaggedInfra) {
+        result.externalMocks.push({ path: `[INFRA] ${mockPath}`, hasBehavior });
+    }
+    else if (isLocalMock(mockPath)) {
+        result.localMocks.push({ path: mockPath, hasBehavior });
+    }
+    else if (mockPath.startsWith('@myorg/')) {
+        result.internalMocks.push({ path: mockPath, hasBehavior });
+    }
+    else {
+        result.externalMocks.push({ path: mockPath, hasBehavior });
+    }
+}
+function countMocks(content) {
+    const matches = [...content.matchAll(/vi\.mock\(\s*['"`]([^'"`]+)['"`]/g)];
+    const result = { internalMocks: [], externalMocks: [], localMocks: [] };
+    for (const m of matches) {
+        const path = m[1];
+        const matchIndex = m.index ?? 0;
+        classifyMockPath(path, mockHasBehavior(content, matchIndex), hasInfraTag(content, matchIndex), result);
+    }
+    return { total: matches.length, ...result };
+}
+export function isUnitTestFile(filePath) {
+    return ((filePath.endsWith('.test.ts') || filePath.endsWith('.test.tsx')) &&
+        !filePath.includes('.integration.') &&
+        !filePath.includes('.workers.') &&
+        !filePath.includes('.e2e.'));
+}
+function addMockViolation(violations, rel, severity, rule, mocks, suffix) {
+    if (!mocks.length) {
+        return;
+    }
+    const paths = mocks.map((m) => m.path).join(', ');
+    violations.push({ file: rel, severity, rule, message: `${paths}. ${suffix}` });
+}
+function classifyMocks(internalMocks) {
+    return {
+        serviceBehavior: internalMocks.filter((m) => !isInfraMock(m.path) && m.hasBehavior),
+        serviceData: internalMocks.filter((m) => !isInfraMock(m.path) && !m.hasBehavior),
+        infra: internalMocks.filter((m) => isInfraMock(m.path)),
+    };
+}
+function detectInlineYaml(content, filePath) {
+    const inlineYamlMatches = [
+        ...content.matchAll(/(?:writeFileSync|writeFile)\s*\([^,]+\.yaml['"`]\s*,\s*[`'"]/g),
+    ];
+    for (const match of inlineYamlMatches) {
+        const matchIndex = match.index ?? 0;
+        const rest = content.slice(matchIndex, matchIndex + 500);
+        // Skip 1-line strings (intentionally malformed YAML for error tests)
+        const hasNewlines = rest.includes('\\n') ||
+            (rest.includes('`') && rest.indexOf('\n') < rest.indexOf('`', rest.indexOf('`') + 1));
+        if (hasNewlines) {
+            return {
+                file: filePath,
+                severity: 'ERROR',
+                rule: 'inline-yaml',
+                message: 'Inline YAML string literal detected. Use __fixtures__/*.yaml files with cpSync instead.',
+            };
+        }
+    }
+    return undefined;
+}
+function auditFileContents(filePath, contents, maxMocks) {
+    const violations = [];
+    const { total, internalMocks, externalMocks, localMocks } = countMocks(contents);
+    // Classify mocks to distinguish infra from service/external mocks
+    const { serviceBehavior, serviceData } = classifyMocks(internalMocks);
+    // Also classify external mocks (e.g., @sentry/cloudflare, cloudflare:workers are infra)
+    const externalInfra = externalMocks.filter((m) => isInfraMock(m.path));
+    const externalNonInfra = externalMocks.filter((m) => !isInfraMock(m.path));
+    // Local mocks (./  ../  #) and infra mocks are excluded from over-mocking count
+    const problematicCount = serviceBehavior.length + serviceData.length + externalNonInfra.length;
+    // Count only non-infra, non-local mocks for the over-mocking threshold
+    if (problematicCount > maxMocks) {
+        const excluded = localMocks.length + externalInfra.length;
+        violations.push({
+            file: filePath,
+            severity: 'WARNING',
+            rule: 'over-mocking',
+            message: `${problematicCount} non-infra mocks (${total} total, ${excluded} local/infra excluded). Reduce service/external mocking.`,
+        });
+    }
+    const inlineYamlViolation = detectInlineYaml(contents, filePath);
+    if (inlineYamlViolation) {
+        violations.push(inlineYamlViolation);
+    }
+    if (isUnitTestFile(filePath) && internalMocks.length > 0) {
+        addMockViolation(violations, filePath, 'ERROR', 'service-mock-in-unit-test', serviceBehavior, 'Rename to .integration.test.ts or use real dependencies.');
+        addMockViolation(violations, filePath, 'WARNING', 'service-data-mock-in-unit-test', serviceData, 'Consider importing real constants.');
+        // Infra mocks in unit tests are acknowledged as OK — no need to report
+    }
+    return violations;
+}
+/**
+ * Pure detection function. Takes pre-read file contents, returns structured result.
+ * No readFileSync, no glob, no runShell, no root param needed.
+ */
+export function detectTphViolations(files, options) {
+    const maxMocks = options?.maxMocks ?? DEFAULT_MAX_MOCKS;
+    const violations = [];
+    for (const file of files) {
+        violations.push(...auditFileContents(file.path, file.contents, maxMocks));
+    }
+    return {
+        filesChecked: files.length,
+        violations,
+        errorCount: violations.filter((v) => v.severity === 'ERROR').length,
+        warningCount: violations.filter((v) => v.severity === 'WARNING').length,
+        infoCount: violations.filter((v) => v.severity === 'INFO').length,
+    };
+}
+//# sourceMappingURL=audit-tph-detect.js.map

package/dist/esm/audit/audit-tph-e2e-detect.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Pure detection logic for TPH E2E audit.
+ * Zero I/O — accepts pre-read file contents, returns structured results.
+ */
+export interface Violation {
+    file: string;
+    severity: 'ERROR' | 'WARNING' | 'INFO';
+    rule: string;
+    message: string;
+}
+export interface AuditResult {
+    filesChecked: number;
+    violations: Violation[];
+    errorCount: number;
+    warningCount: number;
+    infoCount: number;
+}
+export interface FileInput {
+    path: string;
+    contents: string;
+}
+/**
+ * Pure detection function for E2E audit.
+ * Takes pre-read file contents, returns structured result. No I/O.
+ */
+export declare function detectTphE2eViolations(files: FileInput[]): AuditResult;
+//# sourceMappingURL=audit-tph-e2e-detect.d.ts.map

package/dist/esm/audit/audit-tph-e2e-detect.js

@@ -0,0 +1,84 @@
+/**
+ * Pure detection logic for TPH E2E audit.
+ * Zero I/O — accepts pre-read file contents, returns structured results.
+ */
+const INTERNAL_API_PATTERN = /\b(?:app|router|server|auth|handler)\.(?:handle|fetch|dispatch)\(/g;
+const INTERNAL_HANDLER_PATTERN = /\b[a-zA-Z0-9_]+\.handler\(/g;
+const MOCK_PATTERN = /\b(?:vi|jest)\.mock\(|mockResolvedValue|mockReturnValue/g;
+const DRY_RUN_PATTERN = /dryRun\s*:\s*true|dry-run\s*.*true/g;
+const ERROR_TITLE_PATTERN = /(error|invalid|reject|fail|unauthorized)/i;
+const MIXED_TITLE_PATTERN = /(mixed|partial|graceful|degradation)/i;
+function hasTitlePattern(content, pattern) {
+    const titleMatches = content.match(/\b(?:it|test)\s*\(\s*['"`][^'"`]+['"`]/g);
+    if (!titleMatches) {
+        return false;
+    }
+    return titleMatches.some((title) => pattern.test(title));
+}
+function auditFileContents(filePath, contents) {
+    const violations = [];
+    // Reset lastIndex on global regexes before use
+    INTERNAL_API_PATTERN.lastIndex = 0;
+    INTERNAL_HANDLER_PATTERN.lastIndex = 0;
+    MOCK_PATTERN.lastIndex = 0;
+    DRY_RUN_PATTERN.lastIndex = 0;
+    if (INTERNAL_API_PATTERN.test(contents) || INTERNAL_HANDLER_PATTERN.test(contents)) {
+        violations.push({
+            file: filePath,
+            severity: 'ERROR',
+            rule: 'internal-api-call',
+            message: 'E2E tests must not call internal handlers or routers. Use real HTTP/browser flow.',
+        });
+    }
+    if (MOCK_PATTERN.test(contents)) {
+        violations.push({
+            file: filePath,
+            severity: 'ERROR',
+            rule: 'e2e-mocking',
+            message: 'E2E tests must not mock. Use real dependencies and boundaries.',
+        });
+    }
+    if (DRY_RUN_PATTERN.test(contents)) {
+        violations.push({
+            file: filePath,
+            severity: 'ERROR',
+            rule: 'e2e-dry-run',
+            message: 'E2E tests must execute real behavior (no dry-run).',
+        });
+    }
+    if (!hasTitlePattern(contents, ERROR_TITLE_PATTERN)) {
+        violations.push({
+            file: filePath,
+            severity: 'INFO',
+            rule: 'missing-error-coverage',
+            message: 'No E2E test title indicates error/invalid/reject coverage.',
+        });
+    }
+    if (!hasTitlePattern(contents, MIXED_TITLE_PATTERN)) {
+        violations.push({
+            file: filePath,
+            severity: 'INFO',
+            rule: 'missing-mixed-coverage',
+            message: 'No E2E test title indicates mixed/partial/graceful coverage.',
+        });
+    }
+    return violations;
+}
+/**
+ * Pure detection function for E2E audit.
+ * Takes pre-read file contents, returns structured result. No I/O.
+ */
+export function detectTphE2eViolations(files) {
+    const violations = [];
+    for (const file of files) {
+        violations.push(...auditFileContents(file.path, file.contents));
+    }
+    return {
+        filesChecked: files.length,
+        violations,
+        errorCount: violations.filter((v) => v.severity === 'ERROR').length,
+        warningCount: violations.filter((v) => v.severity === 'WARNING').length,
+        infoCount: violations.filter((v) => v.severity === 'INFO').length,
+    };
+}
+//# sourceMappingURL=audit-tph-e2e-detect.js.map

package/dist/esm/audit/audit-tph-e2e-runner.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Runner for the TPH E2E audit — thin I/O layer.
+ * Finds e2e test files, reads contents, calls detectTphE2eViolations, prints + exits.
+ */
+import { type AuditResult } from './audit-tph-e2e-detect.js';
+export declare function printResults(result: AuditResult): void;
+export declare function runTphE2eAudit(root: string): Promise<void>;
+//# sourceMappingURL=audit-tph-e2e-runner.d.ts.map

package/dist/esm/audit/audit-tph-e2e-runner.js

@@ -0,0 +1,106 @@
+/**
+ * Runner for the TPH E2E audit — thin I/O layer.
+ * Finds e2e test files, reads contents, calls detectTphE2eViolations, prints + exits.
+ */
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { detectTphE2eViolations } from './audit-tph-e2e-detect.js';
+import { runShell } from './shell.js';
+const SEVERITY_ICONS = {
+    ERROR: '❌',
+    WARNING: '⚠️ ',
+    INFO: 'ℹ️ ',
+};
+function groupBySeverity(violations) {
+    const grouped = new Map();
+    for (const v of violations) {
+        const existing = grouped.get(v.severity) ?? [];
+        existing.push(v);
+        grouped.set(v.severity, existing);
+    }
+    return grouped;
+}
+function printSeverityGroup(severity, items) {
+    const icon = SEVERITY_ICONS[severity] ?? '?';
+    console.log(`${icon} ${severity} (${items.length}):`);
+    for (const v of items) {
+        console.log(`  ${v.file}`);
+        console.log(`    [${v.rule}] ${v.message}`);
+    }
+    console.log();
+}
+export function printResults(result) {
+    console.log('🧪 Testing Philosophy Audit (TPH) - E2E');
+    console.log('═'.repeat(60));
+    console.log(`Files checked: ${result.filesChecked}`);
+    console.log();
+    if (!result.violations.length) {
+        console.log('✅ No violations found!');
+        return;
+    }
+    const grouped = groupBySeverity(result.violations);
+    for (const severity of ['ERROR', 'WARNING', 'INFO']) {
+        const items = grouped.get(severity);
+        if (items && items.length > 0) {
+            printSeverityGroup(severity, items);
+        }
+    }
+    console.log('─'.repeat(60));
+    console.log(`Summary: ${result.errorCount} errors, ${result.warningCount} warnings, ${result.infoCount} info`);
+    if (result.errorCount > 0) {
+        console.log('\n❌ Fix ERROR violations before merging.');
+    }
+}
+async function findE2eTestFiles(root) {
+    const result = await runShell({
+        command: 'find',
+        args: [
+            '.',
+            '-type',
+            'f',
+            '(',
+            '-name',
+            '*.e2e.test.ts',
+            '-o',
+            '-name',
+            '*.e2e.test.tsx',
+            ')',
+            '-not',
+            '-path',
+            '*/node_modules/*',
+            '-not',
+            '-path',
+            './.claude/worktrees/*',
+            '-not',
+            '-path',
+            './.tmp/*',
+            '-not',
+            '-path',
+            '*/.generated/*',
+            '-not',
+            '-path',
+            '*/dist/*',
+            '-not',
+            '-path',
+            '*/.stryker-tmp/*',
+        ],
+        cwd: root,
+    });
+    return result.stdout
+        .trim()
+        .split('\n')
+        .filter((f) => f.length > 0);
+}
+export async function runTphE2eAudit(root) {
+    const relativePaths = await findE2eTestFiles(root);
+    const files = relativePaths.map((relPath) => ({
+        path: relPath,
+        contents: readFileSync(join(root, relPath), 'utf-8'),
+    }));
+    const result = detectTphE2eViolations(files);
+    printResults(result);
+    if (result.errorCount > 0) {
+        process.exit(1);
+    }
+}
+//# sourceMappingURL=audit-tph-e2e-runner.js.map

package/dist/esm/audit/audit-tph-e2e.d.ts

@@ -0,0 +1,16 @@
+#!/usr/bin/env bun
+/**
+ * Audit: Testing Philosophy Helper (TPH) - E2E
+ *
+ * Detects E2E testing guideline violations:
+ * - Internal API/handler calls inside E2E tests
+ * - Mocks in E2E tests
+ * - Dry-run usage in E2E tests
+ * - Missing error/edge/mixed-data coverage heuristics
+ *
+ * Usage:
+ *   just audit-tph-e2e
+ *   bun apps/scripts/src/audit/audit-tph-e2e.ts
+ */
+export {};
+//# sourceMappingURL=audit-tph-e2e.d.ts.map

package/dist/esm/audit/audit-tph-e2e.js

@@ -0,0 +1,17 @@
+#!/usr/bin/env bun
+/**
+ * Audit: Testing Philosophy Helper (TPH) - E2E
+ *
+ * Detects E2E testing guideline violations:
+ * - Internal API/handler calls inside E2E tests
+ * - Mocks in E2E tests
+ * - Dry-run usage in E2E tests
+ * - Missing error/edge/mixed-data coverage heuristics
+ *
+ * Usage:
+ *   just audit-tph-e2e
+ *   bun apps/scripts/src/audit/audit-tph-e2e.ts
+ */
+import { runTphE2eAudit } from './audit-tph-e2e-runner.js';
+await runTphE2eAudit(process.cwd());
+//# sourceMappingURL=audit-tph-e2e.js.map

package/dist/esm/audit/audit-tph-runner.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Runner for the TPH audit — thin I/O layer.
+ * Finds test files, reads contents, calls detectTphViolations, prints + exits.
+ */
+import { type AuditResult } from './audit-tph-detect.js';
+export declare function printResults(result: AuditResult): void;
+export declare function runTphAudit(root: string, options?: {
+    maxMocks?: number;
+}): Promise<void>;
+//# sourceMappingURL=audit-tph-runner.d.ts.map

package/dist/esm/audit/audit-tph-runner.js

@@ -0,0 +1,115 @@
+/**
+ * Runner for the TPH audit — thin I/O layer.
+ * Finds test files, reads contents, calls detectTphViolations, prints + exits.
+ */
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { detectTphViolations } from './audit-tph-detect.js';
+import { runShell } from './shell.js';
+const SEVERITY_ICONS = {
+    ERROR: '❌',
+    WARNING: '⚠️ ',
+    INFO: 'ℹ️ ',
+};
+function groupBySeverity(violations) {
+    const grouped = new Map();
+    for (const v of violations) {
+        const existing = grouped.get(v.severity) ?? [];
+        existing.push(v);
+        grouped.set(v.severity, existing);
+    }
+    return grouped;
+}
+function printSeverityGroup(severity, items) {
+    const icon = SEVERITY_ICONS[severity] ?? '?';
+    console.log(`${icon} ${severity} (${items.length}):`);
+    for (const v of items) {
+        console.log(`  ${v.file}`);
+        console.log(`    [${v.rule}] ${v.message}`);
+    }
+    console.log();
+}
+export function printResults(result) {
+    console.log('🧪 Testing Philosophy Audit (TPH)');
+    console.log('═'.repeat(60));
+    console.log(`Files checked: ${result.filesChecked}`);
+    console.log();
+    if (!result.violations.length) {
+        console.log('✅ No violations found!');
+        return;
+    }
+    const grouped = groupBySeverity(result.violations);
+    for (const severity of ['ERROR', 'WARNING', 'INFO']) {
+        const items = grouped.get(severity);
+        if (items && items.length > 0) {
+            printSeverityGroup(severity, items);
+        }
+    }
+    console.log('─'.repeat(60));
+    console.log(`Summary: ${result.errorCount} errors, ${result.warningCount} warnings, ${result.infoCount} info`);
+    if (result.errorCount > 0) {
+        console.log('\n❌ Fix ERROR violations before merging.');
+    }
+}
+async function findTestFiles(root) {
+    const result = await runShell({
+        command: 'find',
+        args: [
+            '.',
+            '-type',
+            'f',
+            '(',
+            '-name',
+            '*.test.ts',
+            '-o',
+            '-name',
+            '*.test.tsx',
+            '-o',
+            '-name',
+            '*.integration.test.ts',
+            '-o',
+            '-name',
+            '*.integration.test.tsx',
+            ')',
+            '-not',
+            '-path',
+            '*/node_modules/*',
+            '-not',
+            '-path',
+            './.claude/worktrees/*',
+            '-not',
+            '-path',
+            './.tmp/*',
+            '-not',
+            '-path',
+            '*/.generated/*',
+            '-not',
+            '-path',
+            '*/dist/*',
+            '-not',
+            '-path',
+            '*/.stryker-tmp/*',
+            '-not',
+            '-name',
+            'audit-tph-detect.test.ts',
+        ],
+        cwd: root,
+    });
+    return result.stdout
+        .trim()
+        .split('\n')
+        .filter((f) => f.length > 0);
+}
+export async function runTphAudit(root, options) {
+    const relativePaths = await findTestFiles(root);
+    const files = relativePaths.map((relPath) => ({
+        path: relPath,
+        contents: readFileSync(join(root, relPath), 'utf-8'),
+    }));
+    const result = detectTphViolations(files, options);
+    printResults(result);
+    if (result.errorCount > 0) {
+        process.exit(1);
+    }
+}
+//# sourceMappingURL=audit-tph-runner.js.map

package/dist/esm/audit/audit-tph.d.ts

@@ -0,0 +1,17 @@
+#!/usr/bin/env bun
+/**
+ * Audit: Testing Philosophy Helper (TPH)
+ *
+ * Detects testing philosophy violations that GritQL patterns cannot express:
+ * - Files with >3 vi.mock() calls (over-mocking)
+ * - .test.ts files that mock internal @myorg/* packages (should be .integration.test.ts)
+ *
+ * GritQL handles: toBeTruthy/toBeFalsy, toBeDefined/toBeUndefined, bare toHaveBeenCalled,
+ *                 vi.mock('@myorg/*') detection.
+ *
+ * Usage:
+ *   just audit-tph
+ *   bun apps/scripts/src/audit/audit-tph.ts [--max-mocks N]
+ */
+export {};
+//# sourceMappingURL=audit-tph.d.ts.map