Stockpot

Architectural linter for TypeScript codebases. Define import boundaries, enforce structural patterns, and automatically discover architectural rules from your code.

Install

npm install @thecodingsoup/stockpot

Quick Start

# Generate a config file by scanning your project
npx stockpot init

# Check your codebase against the rules
npx stockpot check

# Discover architectural patterns automatically
npx stockpot infer

# Get a full architecture report
npx stockpot report

Configuration

Stockpot uses a stockpot.config.ts file at your project root. Run stockpot init to generate one, or create it manually:

import { defineConfig } from '@thecodingsoup/stockpot';

export default defineConfig({
  rootDir: '.',
  include: ['src/**/*.ts', 'src/**/*.tsx'],
  exclude: ['**/*.test.ts', '**/*.spec.ts'],

  boundaries: {
    'api-no-repos': {
      files: 'src/api/**/*.ts',
      cannotImport: ['src/repositories/**'],
      reason: 'API layer should use services, not repositories directly',
    },
    'components-no-server': {
      files: 'src/components/**/*.tsx',
      cannotImport: ['src/server/**', 'src/api/**'],
      reason: 'Components should not import server-side code',
    },
  },

  patterns: {
    'api-auth-wrapper': {
      in: 'src/api/**/*.ts',
      require: 'exports-wrapped-with:withAuth',
      exceptions: ['src/api/health.ts'],
      severity: 'error',
    },
  },

  naming: {
    'hooks-use-prefix': {
      filePattern: '^use[A-Z]',
    },
  },

  infer: {
    enabled: true,
    confidenceThreshold: 0.85,
  },
});

CLI Commands

stockpot check

Check your codebase against configured and inferred rules.

stockpot check
stockpot check --format json
stockpot check --severity error        # only show errors
stockpot check --max-warnings 10       # fail if >10 warnings
stockpot check --verbose
stockpot check --quiet                 # errors only

stockpot init

Scan your project and generate a stockpot.config.ts with discovered patterns.

stockpot init
stockpot init --root ./packages/app

stockpot infer

Discover architectural patterns in your codebase without enforcing them.

stockpot infer
stockpot infer --threshold 0.9         # only high-confidence patterns
stockpot infer --categories imports,naming
stockpot infer --format json

stockpot report

Generate an architecture health report with scores.

stockpot report
stockpot report --format json

Rules

Boundaries

Control which files can import from which modules:

boundaries: {
  'rule-name': {
    files: 'src/api/**/*.ts',          // files this rule applies to
    canImport: ['src/services/**'],     // allowlist (optional)
    cannotImport: ['src/repositories/**'], // blocklist (optional)
    reason: 'Explanation shown in violations',
  },
}

Patterns

Enforce structural patterns across files:

patterns: {
  'rule-name': {
    in: 'src/api/**/*.ts',             // files this rule applies to
    require: 'exports-wrapped-with:withAuth', // required pattern
    forbid: 'default-export',          // forbidden pattern (optional)
    exceptions: ['src/api/health.ts'], // excluded files (optional)
    severity: 'error',                 // error | warning | info
  },
}

Naming

Enforce file and export naming conventions:

naming: {
  'rule-name': {
    filePattern: '^use[A-Z]',          // regex for file names
    exportPattern: '^use[A-Z]',        // regex for export names
  },
}

Inference

Stockpot can automatically discover patterns from your codebase using statistical analysis:

• Import patterns — detects commonly shared imports across directories
• Wrapper patterns — finds functions that consistently wrap exports
• Naming patterns — identifies naming conventions per directory
• Structure patterns — detects dominant export shapes
• Duplication — flags reimplemented utilities
• Negative patterns — discovers architectural boundaries by absence
• Composite patterns — fuses co-located rules into contracts

Inferred rules appear as warnings in stockpot check output with a confidence score.

Architecture Score

Stockpot calculates a 0-100 architecture health score based on four categories:

| Category | Weight | What it measures | |---|---|---| | Boundaries | 30% | Import rule compliance | | Patterns | 30% | Structural pattern adherence | | Naming | 20% | Naming convention consistency | | Duplication | 20% | Utility reuse vs reimplementation |

Programmatic API

import { defineConfig, loadConfig } from '@thecodingsoup/stockpot';

// Type-safe config helper
const config = defineConfig({
  rootDir: '.',
  boundaries: { /* ... */ },
});

// Load config from file
const result = await loadConfig();
if (result.ok) {
  console.log(result.value);
}

Requirements

• Node.js >= 18
• TypeScript codebase

License

MIT