Code Quality

Automated enforcement of architectural standards, documentation requirements, and coding patterns.

Code Quality Tests (__tests__/code-quality/)

Automated enforcement of architectural standards, documentation requirements, and coding patterns.

Purpose

Ensures codebase maintains:

1. Consistent Documentation: Every directory has a README
2. Performance Standards: No dynamic imports (bundle optimization)
3. Documentation Quality: READMEs meet minimum content requirements
4. Architectural Compliance: Dependencies flow in correct direction

Tests

README Coverage (readme-coverage.test.ts)

Enforces that every directory contains a README.md file.

Why This Matters:

• Developers can understand any module without searching elsewhere
• New contributors have context for every directory
• Documentation stays current (lives with the code)
• Prevents undocumented "mystery folders"

Test Implementation:

test("all directories should have README.md", () => {
  const directories = findAllDirectories("src");
  const missing = directories.filter((dir) => !hasReadme(dir));

  expect(missing).toEqual([]); // No directories without README
});

What Gets Checked:

• All directories under src/
• Excludes: node_modules, .git, build output
• Recursively checks subdirectories

Failure Example:

❌ Missing README.md in these directories:
  - src/app/new-feature
  - src/components/experimental

No Dynamic Imports (no-dynamic-imports.test.ts)

Prevents usage of import() statements (dynamic imports).

Why This Matters:

• Bundle Optimization: Dynamic imports create code-splitting points that may not be desired
• Type Safety: Static imports provide better TypeScript checking
• Performance: Dynamic imports add runtime overhead
• Security: Static imports are analyzed at build time

Test Implementation:

test("should not use dynamic imports", () => {
  const files = glob("src/**/*.{ts,tsx}");
  const violations = [];

  for (const file of files) {
    const content = readFileSync(file, "utf-8");
    const matches = content.matchAll(/\bimport\s*\(/g);

    for (const match of matches) {
      violations.push({ file, line: getLineNumber(content, match.index) });
    }
  }

  expect(violations).toEqual([]);
});

Allowed Alternative:

Use top-level static imports instead:

// ❌ Bad - Dynamic import
const { createCache } = await import("./cache");

// ✅ Good - Static import
import { createCache } from "./cache";

Exception Handling:

If dynamic imports are genuinely needed (e.g., Next.js next/dynamic), use explicit allowlist in test.

Documentation Quality (documentation-quality.test.ts)

Validates that README files contain meaningful content.

Why This Matters:

• Prevents placeholder READMEs ("TODO: Add documentation")
• Ensures minimum documentation standards
• Validates README structure (headings, sections)

Test Implementation:

test("README files should meet quality standards", () => {
  const readmes = glob("src/**/README.md");
  const issues = [];

  for (const readme of readmes) {
    const content = readFileSync(readme, "utf-8");

    // Check minimum length (50 characters)
    if (content.length < 50) {
      issues.push({ file: readme, issue: "Too short" });
    }

    // Check for required sections
    if (!content.includes("## Purpose") && !content.includes("# ")) {
      issues.push({ file: readme, issue: "Missing purpose section" });
    }

    // Check for placeholder content
    if (content.includes("TODO") || content.includes("Coming soon")) {
      issues.push({ file: readme, issue: "Contains placeholder" });
    }
  }

  expect(issues).toEqual([]);
});

Quality Requirements:

• Minimum Length: 50 characters (ensures meaningful content)
• Purpose Section: Explains what the module does
• No Placeholders: No "TODO" or "Coming soon" text
• Proper Formatting: Valid markdown with headings

Running Code Quality Tests

# Run all code quality tests
bun run test code-quality/

# Run specific test
bun run test readme-coverage.test.ts

# Run in watch mode (re-run on file changes)
bun run test --watch code-quality/

# Verbose output
bun run test --verbose code-quality/

Fixing Violations

Missing README

# Create README for missing directory
touch src/app/new-feature/README.md

# Add minimum content
echo "# New Feature\n\nDescription of the feature..." > src/app/new-feature/README.md

Dynamic Import

Replace with static import:

// Before (violation)
async function loadCache() {
  const { createCache } = await import("./cache");
  return createCache();
}

// After (compliant)
import { createCache } from "./cache";

function loadCache() {
  return createCache();
}

Low Quality README

Expand content to meet standards:

# Module Name

## Purpose

Clear explanation of what this module does and why it exists.

## Features

- Feature 1: Description
- Feature 2: Description

## Usage

```typescript
import { feature } from "./module";

const result = feature();
```

Related Documentation

• Other Module

## CI/CD Integration

Code quality tests run in CI pipeline:

```yaml
# .github/workflows/test.yml
- name: Code quality checks
  run: bun run test code-quality/

- name: Fail on violations
  if: failure()
  run: |
    echo "Code quality violations found. See test output above."
    exit 1

Benefits

For Developers

• Clear Expectations: Standards are automated, not manual
• Quick Feedback: Violations caught immediately during development
• Consistent Quality: Same standards enforced across entire codebase

For Maintainers

• Self-Documenting Code: Every module has explanation
• Easier Onboarding: New contributors can navigate codebase
• Reduced Tech Debt: Standards enforced from day one

For Teams

• Code Reviews: Focus on logic, not documentation presence
• Knowledge Sharing: Documentation is mandatory, not optional
• Architectural Integrity: Patterns enforced automatically

Future Enhancements

Potential additional code quality tests:

• Dependency Direction: Verify clean architecture layers (domain → adapters, not reverse)
• Import Conventions: Enforce alias usage (@/ for src/)
• File Naming: Consistent kebab-case or camelCase
• Function Complexity: Cyclomatic complexity limits
• Test Coverage: Per-file coverage thresholds
• Bundle Size: Prevent bloat from large dependencies

Related Documentation

• Test Suite Overview - All test types
• E2E Tests - Browser-based tests
• Test Helpers - Testing utilities
• Architecture - Clean architecture principles