Code Standards Analyzer

Purpose: Discover, document, and maintain coding standards from existing codebases using evidence-based analysis.

Philosophy: Standards should reflect REALITY (what the code actually does) not ASPIRATIONS (what we wish it did). Measure, then document.

When to Use

Primary Use Cases:

Brownfield Onboarding - "What are this project's coding conventions?"
Standards Audit - "Are we following our declared standards?"
New Contributor Onboarding - "Teach me the project patterns"
Living Documentation - "Keep standards in sync with codebase"
Greenfield Setup - "Initialize standards from best practices"

Activation Triggers

Keywords: analyze coding standards, discover conventions, code style, detect patterns, coding guidelines, what are the standards, naming conventions, best practices, code quality, standards audit, anti-patterns

User Requests:

"What are the coding standards for this project?"
"Analyze the codebase and document our conventions"
"Check if we're following our declared standards"
"Find anti-patterns in the code"
"Generate coding standards documentation"
"What naming conventions does this project use?"

Capabilities

1. Explicit Standards Discovery (Fast - 5 seconds)

✅ Detect existing .specweave/docs/internal/governance/coding-standards.md
✅ Parse ESLint configuration (.eslintrc.json, .eslintrc.js)
✅ Parse Prettier configuration (.prettierrc, .prettierrc.json)
✅ Parse TypeScript configuration (tsconfig.json)
✅ Parse EditorConfig (.editorconfig)
✅ Extract standards from CLAUDE.md, CONTRIBUTING.md

2. Implicit Standards Detection (Medium - 30 seconds)

✅ Naming convention analysis (variables, functions, classes, constants)
✅ Import pattern detection (extensions, ordering, aliasing)
✅ Function characteristics (avg length, max length, arrow vs regular)
✅ Type safety analysis (any usage, interface vs type preference)
✅ Error handling patterns (try/catch usage, custom errors)
✅ Comment style analysis
✅ File organization patterns

3. Anti-Pattern Detection (Fast - 15 seconds)

🚨 console.* usage in production code
🚨 Hardcoded secrets (API keys, passwords)
🚨 any type overuse
🚨 Large files (>500 lines)
🚨 Long functions (>100 lines)
🚨 Missing error handling
🚨 N+1 query patterns
🚨 Security vulnerabilities

4. Documentation Generation (Fast - 10 seconds)

✅ Generate standards document with examples
✅ Include statistical confidence levels
✅ Extract real code examples from codebase
✅ Highlight inconsistencies and conflicts
✅ Provide actionable recommendations
✅ Link to violating files

Analysis Process

Phase 1: Explicit Standards (5 seconds)

Sources Checked:

.specweave/docs/internal/governance/coding-standards.md (HIGH confidence)
CLAUDE.md (HIGH confidence - AI instructions)
.eslintrc.json (ENFORCED by tooling)
.prettierrc (ENFORCED by tooling)
tsconfig.json (ENFORCED by compiler)
.editorconfig (ENFORCED by editor)
CONTRIBUTING.md (MEDIUM confidence - may be outdated)

Output:

## Explicit Standards Found

✅ .eslintrc.json (ENFORCED - ESLint active)
✅ .prettierrc (ENFORCED - Prettier active)
✅ tsconfig.json (ENFORCED - TypeScript compiler)
✅ CLAUDE.md (HIGH - AI development rules)
⚠️  CONTRIBUTING.md (MEDIUM - human guidelines)
❌ No .specweave/docs/internal/governance/coding-standards.md

Phase 2: Implicit Standards (30 seconds)

Analysis Performed:

Scan src/**/*.{ts,js,tsx,jsx} files
Parse Abstract Syntax Trees (AST)
Calculate statistical patterns
Identify dominant conventions

Example Output:

## Detected Patterns

### Naming Conventions (Confidence: 95%)
- Variables: camelCase (1,234 samples, 98% compliance)
- Functions: camelCase (567 samples, 100% compliance)
- Classes: PascalCase (89 samples, 100% compliance)
- Constants: UPPER_SNAKE_CASE (234 samples, 92% compliance)
  ⚠️ 8% use camelCase (inconsistency detected)

### Import Patterns (Confidence: 100%)
- Extensions: .js suffix required (100% compliance)
- Order: external → internal → types (87% compliance)

### Function Characteristics
- Average length: 35 lines
- Max length: 156 lines (src/core/analyzer.ts:45)
- Style: Arrow functions (78%), Regular (22%)

### Type Safety (Confidence: 85%)
- any usage: 12 instances (REVIEW NEEDED)
- Preference: Interfaces (89%) over Types (11%)

Phase 3: Anti-Pattern Detection (15 seconds)

Checks Performed:

Security: Hardcoded secrets, SQL injection risks
Maintainability: Large files, complex functions
Performance: N+1 queries, missing caching
Robustness: Missing error handling

Example Output:

## Issues Found

### 🔴 CRITICAL (2 issues)
- Hardcoded Secrets: 2 instances
  - src/config/api.ts:12
  - src/utils/auth.ts:45
  Fix: Use process.env variables

### 🟠 HIGH (5 issues)
- console.* Usage: 5 instances in src/
  - src/core/analyzer.ts:67
  Fix: Use logger abstraction

### 🟡 MEDIUM (12 issues)
- Large Files: 3 files > 500 lines
  - src/core/orchestrator.ts (678 lines)
  Fix: Split into modules

Phase 4: Documentation Generation (10 seconds)

Merge Strategy:

Explicit standards = source of truth
Implicit standards = fill gaps
Anti-patterns = warnings + recommendations

Output: .specweave/docs/internal/governance/coding-standards-analysis.md

Integration Points

1. Brownfield Analyzer Integration

Automatic: Runs as part of brownfield analysis

User: "Analyze this brownfield project"

Workflow:
1. Scan project structure
2. Classify documents
3. Detect external tools
4. → RUN code-standards-detective agent
5. → GENERATE coding-standards.md
6. Generate migration plan

2. Increment Planning

Reference: Standards included in technical constraints

## Technical Constraints

Coding Standards: .specweave/docs/internal/governance/coding-standards.md
- Naming: camelCase (vars), PascalCase (classes)
- Functions: < 50 lines target
- No console.* - use logger

3. Increment Completion

Optional: Re-analyze on increment done

/sw:done 0046 --update-standards

Usage Examples

Example 1: First-Time Analysis

User: "What are the coding standards for this project?"

Skill: code-standards-analyzer

Actions:
1. Check for existing standards (none found)
2. Parse .eslintrc.json, .prettierrc
3. Analyze 1,234 TypeScript files
4. Detect patterns with 95% confidence
5. Generate standards document

Output:
"✅ Analysis complete! Generated coding standards at:
.specweave/docs/internal/governance/coding-standards-analysis.md

Key findings:
- Naming: 98% camelCase compliance
- Imports: 100% use .js extensions
- Issues: 5 console.* usages, 2 hardcoded secrets
- Recommendation: Formalize detected patterns as official standards"

Example 2: Standards Audit

User: "Check if we're following our declared standards"

Skill: code-standards-analyzer

Actions:
1. Read existing coding-standards.md
2. Analyze current codebase
3. Compare declared vs actual
4. Report violations

Output:
"📊 Standards Compliance: 87%

✅ Passing:
- Naming conventions: 98% compliant
- Import patterns: 100% compliant

⚠️ Violations:
- console.* usage: 12 instances (should be 0)
- Large files: 3 files > 500 lines (should be 0)

Recommendation: Fix violations or update standards to reflect reality"

Example 3: New Contributor Onboarding

User: "I'm new to this codebase. What conventions should I follow?"

Skill: code-standards-analyzer

Actions:
1. Load existing coding-standards.md
2. Extract key rules with examples
3. Highlight SpecWeave-specific patterns

Output:
"📚 Coding Standards Summary

1. Naming:
   - Variables: camelCase (e.g., `userId`, `isActive`)
   - Functions: camelCase (e.g., `getUserById()`)
   - Classes: PascalCase (e.g., `UserService`)

2. Imports:
   - Always use .js extensions
   - Example: import { foo } from './bar.js'

3. Error Handling:
   - Use custom error types
   - Example: throw new UserNotFoundError(id)

4. Logging:
   - NEVER use console.*
   - Use logger abstraction instead

Full standards: .specweave/docs/internal/governance/coding-standards.md"

Commands

Manual Analysis

# Full analysis
/sw:analyze-standards

# Drift detection only
/sw:analyze-standards --drift

# Update existing standards
/sw:analyze-standards --update

Output Files

1. `coding-standards-analysis.md` (Auto-Generated)

Location: .specweave/docs/internal/governance/coding-standards-analysis.md

Purpose: Latest analysis report (gitignored, temporary)

Contents:

Detected patterns with confidence levels
Real code examples
Statistical evidence
Violation warnings
Recommendations

2. `coding-standards.md` (Source of Truth)

Location: .specweave/docs/internal/governance/coding-standards.md

Purpose: Official coding standards (git-tracked, manual + auto)

Contents:

Naming conventions
Import patterns
Function guidelines
Type safety rules
Error handling
Security practices
Performance guidelines

3. `coding-standards-history.md` (Change Log)

Location: .specweave/docs/internal/governance/coding-standards-history.md

Purpose: Track standard evolution over time

Contents:

Timestamp of each analysis
Changes detected
Migration guides
Rationale for updates

Best Practices

1. Run During Onboarding

Analyze standards as part of brownfield analysis
Generate baseline documentation
Establish project context

2. Periodic Re-Analysis

Quarterly reviews
After major refactors
On team onboarding

3. Team Review Required

Don't auto-commit changes
Review generated standards
Discuss inconsistencies
Formalize decisions

4. Living Documentation

Keep standards in sync with code
Update when patterns change
Track evolution in history

5. Enforcement Through Tooling

Most standards → ESLint/Prettier
This skill → document what tools can't catch
Focus on SpecWeave-specific patterns

Technical Details

Supported Languages

✅ TypeScript (primary)
✅ JavaScript (ES6+)
✅ Python (pyproject.toml, .pylintrc, ruff.toml, .flake8, mypy.ini)
✅ Java/Kotlin (checkstyle.xml, pmd.xml, spotbugs.xml, detekt.yml)
✅ Go (go.mod, .golangci.yml, staticcheck.conf)
✅ C#/.NET (.editorconfig, StyleCop.json, Directory.Build.props)
✅ Rust (rustfmt.toml, clippy.toml, Cargo.toml)
✅ React (package.json, ESLint plugin:react/*)
✅ Angular (angular.json, ESLint @angular-eslint)
✅ Vue (package.json, ESLint plugin:vue/*)
✅ Svelte (package.json, svelte.config.js)

Detection Algorithms

Naming Convention Detection:

Regex pattern matching
Statistical frequency analysis
AST node analysis
Confidence scoring (samples / total)

Anti-Pattern Detection:

Static analysis (grep, AST parsing)
Rule-based checks
Security scanning
Complexity metrics

Confidence Levels:

ENFORCED: Linter/compiler enforced (100%)
HIGH: 90%+ compliance in codebase
MEDIUM: 70-89% compliance
LOW: 50-69% compliance
CONFLICT: <50% compliance (inconsistent)

Limitations

Implicit Standards: Requires representative codebase sample
False Positives: Anti-pattern detection may flag intentional code
Context: Can't understand business rationale for patterns

Multi-Technology Support

Status: ✅ Implemented (increment 0122-multi-technology-governance)

Technology	Config Files	Status
TypeScript/JavaScript	`.eslintrc.*`, `.prettierrc`, `tsconfig.json`	✅ Implemented
Python	`pyproject.toml`, `.pylintrc`, `ruff.toml`, `.flake8`, `mypy.ini`	✅ Implemented
Go	`go.mod`, `.golangci.yml`, `staticcheck.conf`	✅ Implemented
Java/Kotlin	`checkstyle.xml`, `pmd.xml`, `spotbugs.xml`, `detekt.yml`	✅ Implemented
C#/.NET	`.editorconfig`, `StyleCop.json`, `Directory.Build.props`	✅ Implemented
Rust	`rustfmt.toml`, `clippy.toml`, `Cargo.toml`	✅ Implemented
React	ESLint + `plugin:react/*`, `package.json`	✅ Implemented
Angular	`angular.json`, `.eslintrc`	✅ Implemented
Vue	ESLint + `plugin:vue/`, `vite.config.`	✅ Implemented
Svelte	`svelte.config.js`, `package.json`	✅ Implemented

Output Structure:

.specweave/docs/internal/governance/
├── coding-standards.md          # Unified summary of ALL technologies
├── shared-conventions.md        # EditorConfig, Git conventions
└── standards/
    ├── typescript.md
    ├── python.md
    ├── golang.md
    ├── java.md
    ├── react.md
    ├── angular.md
    ├── vue.md
    └── svelte.md

Usage:

import {
  detectEcosystems,
  parsePythonStandards,
  parseGoStandards,
  parseJavaStandards,
  parseFrontendStandards,
  generateStandardsMarkdown,
  generateUnifiedSummary
} from 'src/core/living-docs/governance/index.js';

Future Enhancements

Auto-generate ESLint rules from detected patterns
AI-powered suggestions from top OSS projects
Team-specific standards in multi-project mode
Pre-commit hook integration for enforcement
Real-time drift alerts
Standards comparison across projects

code-standards-analyzer

Code Standards Analyzer

When to Use

Primary Use Cases:

Activation Triggers

Capabilities

1. Explicit Standards Discovery (Fast - 5 seconds)

2. Implicit Standards Detection (Medium - 30 seconds)

3. Anti-Pattern Detection (Fast - 15 seconds)

4. Documentation Generation (Fast - 10 seconds)

Analysis Process

Phase 1: Explicit Standards (5 seconds)

Phase 2: Implicit Standards (30 seconds)

Phase 3: Anti-Pattern Detection (15 seconds)

Phase 4: Documentation Generation (10 seconds)

Integration Points

1. Brownfield Analyzer Integration

2. Increment Planning

3. Increment Completion

Usage Examples

Example 1: First-Time Analysis

Example 2: Standards Audit

Example 3: New Contributor Onboarding

Commands

Manual Analysis

Output Files

1. coding-standards-analysis.md (Auto-Generated)

2. coding-standards.md (Source of Truth)

3. coding-standards-history.md (Change Log)

Best Practices

1. Run During Onboarding

2. Periodic Re-Analysis

3. Team Review Required

4. Living Documentation

5. Enforcement Through Tooling

Related Documentation

Technical Details

Supported Languages

Detection Algorithms

Limitations

Multi-Technology Support

Future Enhancements

1. `coding-standards-analysis.md` (Auto-Generated)

2. `coding-standards.md` (Source of Truth)

3. `coding-standards-history.md` (Change Log)