@oxog/codeguardian

Zero-dependency TypeScript codebase guardian that enforces architecture, security, performance, and quality rules as a pre-commit hook.

Unlike traditional linters that check syntax, codeguardian builds a knowledge graph of your codebase and evaluates every change against that graph. It understands your project's architectural patterns, detects security anti-patterns, catches performance pitfalls, and blocks or warns based on severity.

Features

• Codebase Knowledge Graph — Maps all files, symbols, imports, and dependencies
• ESM & CommonJS Support — Correctly resolves .js/.ts import extensions
• Incremental Analysis — Only re-parses changed files (< 2s pre-commit)
• 29 Built-in Rules — Architecture, security, performance, and quality checks
• Plugin System — Extend with custom rules and plugins
• Zero Dependencies — Only TypeScript as a peer dependency
• Pre-commit Hook — Blocks commits with critical/error findings
• Multiple Output Formats — Terminal, JSON, SARIF (GitHub Code Scanning)

Quick Start

npm install @oxog/codeguardian --save-dev
npx codeguardian init

That's it. codeguardian will now run on every commit.

Programmatic Usage

import { createGuardian } from '@oxog/codeguardian';

const guardian = createGuardian({
  rootDir: process.cwd(),
  tsconfig: './tsconfig.json',
});

// Full scan
const graph = await guardian.scan();
console.log(`${graph.files.size} files, ${graph.symbols.size} symbols`);

// Run analysis
const result = await guardian.run({ staged: true });
if (result.blocked) {
  console.error('Commit blocked!');
  process.exit(1);
}

CLI

codeguardian init                      # Setup project
codeguardian run                       # Analyze all files
codeguardian run --staged              # Analyze staged files (pre-commit)
codeguardian run --format json         # JSON output
codeguardian run --format sarif        # SARIF for GitHub
codeguardian run --plugin security     # Run specific plugin
codeguardian run --verbose             # Include info findings
codeguardian stats                     # Show graph statistics
codeguardian rules                     # List all rules
codeguardian conventions               # Show detected conventions
codeguardian scan --full               # Force full re-scan
codeguardian uninstall                 # Remove hook

Configuration

Create .codeguardian.json in your project root:

{
  "include": ["src/**/*.ts"],
  "exclude": ["**/*.test.ts"],
  "severity": {
    "blockOn": ["critical", "error"],
    "warnOn": ["warning"]
  },
  "plugins": {
    "architecture": {
      "enabled": true,
      "layers": ["controller", "service", "repository", "util"],
      "enforceDirection": true,
      "maxFileLines": 300,
      "maxFunctionLines": 50
    },
    "security": {
      "enabled": true,
      "checkInjection": true,
      "checkSecrets": true,
      "checkXSS": true
    },
    "performance": {
      "enabled": true,
      "checkN1Queries": true,
      "checkMemoryLeaks": true
    },
    "quality": {
      "enabled": true,
      "maxCyclomaticComplexity": 15
    }
  }
}

Core Plugins & Rules

Architecture (6 rules)

Rule	Severity	Description
architecture/layer-violation	error	Lower layer importing from higher layer
architecture/circular-dependency	error	Circular import chains (A -> B -> C -> A)
architecture/file-role-mismatch	warning	File content doesn't match directory role
architecture/god-file	warning	File exceeds max line count
architecture/god-function	warning	Function exceeds max line count
architecture/barrel-explosion	info	Barrel files re-exporting too many symbols

Security (8 rules)

Rule	Severity	Description
security/sql-injection	critical	String concatenation in SQL queries
security/hardcoded-secret	critical	API keys, tokens, passwords in code
security/eval-usage	critical	eval(), Function(), setTimeout(string)
security/prototype-pollution	error	Direct prototype assignment
security/xss-risk	error	innerHTML, document.write
security/missing-auth-check	warning	Controllers without auth references
security/insecure-random	warning	Math.random() in security contexts
security/path-traversal	error	Dynamic paths in file operations

Performance (7 rules)

Rule	Severity	Description
performance/n1-query	warning	Database calls (find, query, execute) inside loops
performance/sync-in-async	warning	readFileSync in async functions
performance/memory-leak-risk	warning	addEventListener without cleanup
performance/unbounded-query	warning	Queries without LIMIT
performance/missing-index-hint	info	Queries needing indexes
performance/heavy-import	info	Full library imports
performance/blocking-operation	warning	CPU-heavy ops in handlers

Quality (8 rules)

Rule	Severity	Description
quality/cyclomatic-complexity	warning	Functions exceeding complexity limit
quality/dead-code	warning	Exported symbols never imported (supports ESM .js imports)
quality/any-type	warning	Usage of any type
quality/no-error-handling	warning	Async functions without try-catch
quality/inconsistent-naming	info	Non-camelCase function names
quality/magic-number	info	Numeric literals without constants
quality/empty-catch	warning	Empty catch blocks
quality/nested-callbacks	warning	Deeply nested callbacks (> 3 levels)

Custom Rules

import { defineRule, type Finding } from '@oxog/codeguardian';

const noConsole = defineRule({
  name: 'custom/no-console',
  severity: 'warning',
  description: 'No console.log in production',
  category: 'quality',
  check: (context) => {
    const findings: Finding[] = [];
    context.walk(context.ast, {
      CallExpression(node) {
        if (context.isConsoleCall(node as any, 'log')) {
          findings.push({
            message: 'Remove console.log',
            file: context.file.path,
            line: 1,
            column: 1,
          });
        }
      },
    });
    return findings;
  },
});

Custom Plugins

import { definePlugin, defineRule } from '@oxog/codeguardian';

const myPlugin = definePlugin({
  name: 'my-team-rules',
  version: '1.0.0',
  install: (kernel) => {
    kernel.registerRule(noConsole);
    kernel.registerRule(anotherRule);
  },
});

guardian.use(myPlugin);

Inline Suppression

// codeguardian-disable-next-line security/sql-injection
const query = `SELECT * FROM users WHERE id = ${id}`;

// codeguardian-disable security/hardcoded-secret -- legacy code
const key = 'secret_live_abc123xyz';
// codeguardian-enable security/hardcoded-secret

Severity Levels

Level	Blocks Commit	When Shown
critical	Yes	Always
error	Yes	Always
warning	No	Always
info	No	Only with --verbose

Requirements

• Node.js >= 18
• TypeScript >= 5.0 (peer dependency)

Documentation

Document	Description
API Reference	Complete API reference for all public functions, types, and plugins
Contributing	Development setup, testing, writing rules/plugins, PR process
Troubleshooting	Common issues and solutions
Security Policy	Vulnerability reporting and disclosure policy
Changelog	Version history and release notes
Specification	Package specification and design decisions
Implementation	Architecture decisions and implementation guide

Links

• Documentation
• GitHub
• npm

License

MIT - Ersin Koc