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

7. 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

Related Documentation

• Coding Standards - Official standards

• Code Review Standards - Review process

• Brownfield Analyzer - Project analysis

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