codemap_audit

Check for architecture violations based on .codemap/audit-rules.json. Supports file-location, forbidden-import, text-pattern, required-annotation, and script rules with exemptions via @codemap.audit.exempt annotations.

sessionauditpolicyarchitecturevalidationrules

Parameters

Name	Type	Required	Description
`verbose`	`boolean`	❌ Optional	Show all files checked, not just violations (default: false)
`ruleId`	`string`	❌ Optional	Only run specific rule by ID (e.g., 'no-backend-in-frontend')

Usage Examples

MCP Usage (for AI Agents like Claude)

json

{
  "name": "codemap_audit",
  "arguments": {}
}

Example Output

JSON Response

json

{
  "success": true,
  "rulesRun": 3,
  "filesChecked": 305,
  "violationCount": 7,
  "errorCount": 3,
  "warningCount": 4,
  "infoCount": 0,
  "violations": [
    {
      "ruleId": "no-backend-in-frontend",
      "ruleName": "Backend imports forbidden in frontend",
      "file": "src/components/UserList.tsx",
      "line": 5,
      "severity": "error",
      "message": "Frontend file imports backend module: '../backend/database'"
    },
    {
      "ruleId": "no-backend-in-frontend",
      "ruleName": "Backend imports forbidden in frontend",
      "file": "src/components/Dashboard.tsx",
      "line": 12,
      "severity": "error",
      "message": "Frontend file imports backend module: '../backend/auth'"
    },
    {
      "ruleId": "required-tests",
      "ruleName": "All services must have tests",
      "file": "src/services/PaymentService.ts",
      "severity": "warning",
      "message": "Service file missing corresponding test file"
    }
  ],
  "clean": false,
  "summary": "❌ 7 violation(s): 3 errors, 4 warnings, 0 info"
}

ℹ️When to Use This Tool

codemap_audit

Enforce architecture boundaries (frontend/backend separation)
Validate project structure rules
Check for forbidden imports or patterns
Verify required annotations exist
Run custom validation scripts
Quality gate before committing or closing sessions

💡Common Patterns

Pre-Commit Quality Gate

1. Make changes
2. codemap_audit()
3. Fix violations
4. Commit when clean

Enforce architecture rules before commit.

Session Close Checklist

1. Complete work
2. codemap_audit() - check violations
3. codemap_execute_shell({ cmd: "npm test" })
4. If both pass, codemap_close()

Ensure quality before ending session.

Focused Rule Debugging

1. codemap_audit({ ruleId: "specific-rule" })
2. Review violations for that rule only
3. Fix issues
4. Re-run to verify

Debug specific architecture rules.

💡Pro Tips

Rules in .codemap/audit-rules.json: Define custom rules for your project
Severities matter: Errors should block commits, warnings are advisory
Exemptions via annotations: Use @codemap.audit.exempt to exempt specific files
Rule types available: file-location, forbidden-import, text-pattern, required-annotation, script
verbose mode for debugging: Use verbose: true to see all files checked
Run specific rules: Use ruleId to debug individual rule issues

✅Best Practices

Run audit before closing sessions
Integrate into pre-commit hooks
Use error severity for critical violations
Use warning severity for best practices
Document rules clearly in rule definitions
Create exemptions sparingly with good reasons
Run full audit in CI/CD pipelines

⚠️Common Mistakes

❌ Mistake: Not creating audit-rules.json
✅ Instead: Create .codemap/audit-rules.json with project-specific rules

❌ Mistake: Ignoring warnings
✅ Instead: Treat warnings as important - fix or document why they're acceptable

❌ Mistake: Overusing exemptions
✅ Instead: Fix violations rather than exempting files

❌ Mistake: Not running audit before commits
✅ Instead: Make audit part of pre-commit workflow

❌ Mistake: Using only error severity
✅ Instead: Use warnings for soft rules, errors for hard boundaries

❌ Mistake: Complex rules that are slow
✅ Instead: Keep rules focused and performant

Parameters

Usage Examples

MCP Usage (for AI Agents like Claude)

Example Output

JSON Response

Related Tools

codemap_session_close

codemap_session_execute-shell

codemap_annotations_add