# Standards Profiles Reference Guide

**Location:** `dev-docs/STANDARDS_PROFILES_REFERENCE.md`  
**Status:** Canonical Reference for Developers and End Users

---

## Overview

The Acurity extension supports three predefined "standards profiles" that bundle together recommended severity levels for diagnostics. This allows users to enforce different standards depending on their needs.

---

## The Three Profiles

### 1. **default** (Recommended for Most Users)

**Use when:** Maintaining or writing typical Acurity code without strict modernization pressure.

**Severity Distribution:**
- **ERROR (Critical):** 
  - Block structure issues (IF/ENDIF mismatch)
  - Undefined variables
  - Unclosed strings
  - Type mismatches
  - Function/macro redeclaration
  - Invalid executable lines
  - INCLUDE/REQUIRE file not found

- **WARNING (Style/Best Practice):**
  - Variable capitalization mismatch
  - Function capitalization mismatch
  - Macro capitalization mismatch
  - Keyword capitalization (true vs TRUE)
  - Type keyword capitalization (string vs STRING)
  - ROBODOC issues
  - Naming conventions (prefix scope, type prefixes)
  - INDEX operation patterns
  - Legacy comment style (#NOTE vs //)

- **OFF:**
  - None in default profile

**Rationale:** Balances catching real bugs while not being overly aggressive about style. Allows legacy code to still be workable.

---

### 2. **legacy-compatible** (For Old Codebases)

**Use when:** You have large older Acurity codebases and need minimal disruption.

**Severity Distribution:**
- **ERROR (Critical):**
  - Only the most serious issues:
    - Block structure mismatches
    - Unclosed strings
    - Invalid executable lines

- **WARNING (Permissive):**
  - Everything else that default catches as error

- **OFF:**
  - Unnecessary built-in constants and advanced checks

**Rationale:** Provides minimal interference. Mostly alerts to structural problems, not style.

---

### 3. **strict-modern** (For New/Modernized Code)

**Use when:** Building new code or enforcing modern standards for a refactored codebase.

**Severity Distribution:**
- **ERROR (Strict):**
  - All critical issues from default
  - **PLUS:** Capitalization issues (keywords, types, variables)
  - **PLUS:** Naming convention violations
  - **PLUS:** Unused variables and functions
  - **PLUS:** All pattern-matching issues

- **WARNING:**
  - Minor informational issues

- **OFF:**
  - Nothing; maximum checking enabled

**Rationale:** Enforces absolute consistency and correctness. No tolerance for style drift or unused code.

---

## Rule Severity Mapping by Profile

| Rule ID | Rule Name | Default | Legacy | Strict-Modern |
|---------|-----------|---------|--------|---------------|
| **Block Structure** ||||
| ACU-BLK-001 | blockStructure | error | error | error |
| ACU-BLK-002 | blockStructure | error | error | error |
| ACU-BLK-003 | blockStructure | error | error | error |
| **String/Parsing** ||||
| ACU-SYN-003 | unclosedString | error | error | error |
| ACU-SYN-002 | invalidExecutableLine | error | error | error |
| **Variables** ||||
| ACU-VAR-001 | undefinedVariable | error | warning | error |
| ACU-VAR-002 | unsetVariable | warning | warning | error |
| ACU-VAR-003 | unclosedString | error | error | error |
| **Capitalization** ||||
| ACU-KWD-001 | keywordCapitalization | **warning** | off | **error** |
| ACU-TYPE-001 | typeKeywordCapitalization | **warning** | off | **error** |
| **Naming Conventions** ||||
| ACU-NMG-001 | databaseFieldDeclaration | error | warning | error |
| ACU-NMG-002 | namingPrefixScope | **warning** | off | **error** |
| ACU-NMG-003 | namingPrefixType | **warning** | off | **error** |
| **Functions** ||||
| ACU-FNC-001 | functionUndefined | error | warning | error |
| ACU-FNC-002 | functionOutOfScope | error | warning | error |
| ACU-FNC-003 | functionRedeclared | error | warning | error |
| ACU-FNC-007 | functionCaseMismatch | warning | off | error |
| ACU-FNC-008 | functionReturnValueUnused | error | warning | error |
| **Macros** ||||
| ACU-MAC-001 | macroRedeclared | error | error | error |
| ACU-MAC-002 | macroCaseMismatch | warning | off | error |
| ACU-MAC-003 | macroParameterCountMismatch | error | error | error |
| **Type System** ||||
| ACU-TYPE-002 | typeMismatch | error | warning | error |
| **File Resolution** ||||
| ACU-INC-003 | includeFileNotFound | error | warning | error |
| ACU-REQ-001 | requireFileNotFound | error | warning | error |
| **Patterns** ||||
| ACU-PAT-001 | indexUsageMissingClose | warning | off | warning |
| ACU-PAT-002 | indexUsageSaveRestore | warning | off | warning |

---

## How to Change Your Profile

### Via Settings UI

1. Open VS Code Settings (`Ctrl+,` on Windows/Linux, `Cmd+,` on macOS)
2. Search for "Acurity Standards Profile"
3. Choose one of the three options:
   - Default
   - Legacy-compatible
   - Strict-modern

### Via JSON Settings

Add to `.vscode/settings.json`:

```json
{
  "acurity.rules.profile": "strict-modern"
}
```

---

## How to Override Individual Rules

You can override any rule's severity regardless of profile:

```json
{
  "acurity.rules.profile": "default",
  
  // Override specific rules
  "acurity.rules.standards.keywordCapitalization.severity": "off",
  "acurity.rules.standards.namingPrefixScope.severity": "error",
  "acurity.rules.core.functionReturnValueUnused.severity": "info"
}
```

**Valid severity values:**
- `"error"` - Red squiggle, blocks in Problems panel
- `"warning"` - Yellow squiggle, appears in Problems panel
- `"info"` - Light blue squiggle, informational only
- `"off"` - Completely disabled

---

## Quick Decision Matrix

| Scenario | Recommended Profile | Rationale |
|----------|---------------------|-----------|
| Start of new project | **strict-modern** | Enforce standards from the beginning |
| Maintaining legacy code | **legacy-compatible** | Minimal disruption while catching bugs |
| Mixed new + old code | **default** | Good middle ground |
| Migrating old → new | Start with **legacy**, end with **strict-modern** | Gradual enforcement as code modernizes |
| Learning Acurity | **default** | Balanced feedback, not overwhelming |
| Production code audit | **strict-modern** | Maximum checking for quality gate |

---

## Severity Levels Explained

### Error 🔴
- Critical issues that prevent code from working correctly
- **Examples:** Wrong block nesting, undefined variables, type mismatches
- **Action:** Must fix immediately
- **Profile:** Different rules error in different profiles

### Warning ⚠️
- Style/convention issues that don't prevent function but could lead to bugs or maintainability issues
- **Examples:** Capitalization drift, missing return value assignment, unused variables
- **Action:** Consider fixing, depends on project standards
- **Profile:** Most style issues default to warning in "default" profile

### Info ℹ️
- Informational hints that may be useful but are non-blocking
- **Examples:** Suggested better patterns, informational messages
- **Action:** Optional improvement
- **Profile:** Rarely used, can be set for particular rules

### Off ⭕
- Rule completely disabled, no diagnostic shown
- **Action:** None
- **Use when:** Rule doesn't apply to your project or coding standards

---

## Common Scenarios and Configuration

### Scenario A: "I want strict rules but allow legacy comments"

```json
{
  "acurity.rules.profile": "strict-modern",
  "acurity.rules.standards.preferSlashSlashComments.severity": "off"
}
```

### Scenario B: "I want default, but be very strict about variables"

```json
{
  "acurity.rules.profile": "default",
  "acurity.rules.core.unsetVariable.severity": "error",
  "acurity.rules.core.undefinedVariable.severity": "error"
}
```

### Scenario C: "I want legacy defaults but catch naming issues"

```json
{
  "acurity.rules.profile": "legacy-compatible",
  "acurity.rules.standards.namingPrefixScope.severity": "warning",
  "acurity.rules.standards.namingPrefixType.severity": "warning"
}
```

---

## Implementation Details

**Where profiles are defined:** `src/diagnostics/diagnosticCatalog.js` (constant `DEFAULT_RULE_SEVERITY_PROFILES`)

**How profiles are applied:**
1. User selects profile in settings or config
2. Extension reads `acurity.rules.profile` config
3. Default rule severities are looked up from profile definition
4. Individual rule overrides are applied on top
5. Diagnostics are created with final severity level

**Profile resolution order:**
1. User's explicit rule override (if set)
2. User's selected profile (default if not specified)
3. Built-in default profile as fallback

---

## Future Profile Ideas

Potential new profiles for future releases:
- **educational** - Very permissive, focuses on teaching correct patterns
- **ci-strict** - Maximum strictness for CI/CD gates
- **performance** - Focuses on performance-related patterns
- **security** - Focuses on security-relevant checks

