# v1.6.1.4 Format Specification Reference

## Overview

This document captures the exact format specifications from v1.6.1.4 TableFormatter implementation that must be restored in the `analyze_code_structure` tool.

## Full Format Specification

### Structure
The full format produces a Markdown document with the following structure:

1. **Header**: `# ClassName` or `# package.ClassName`
2. **Package Section**: `## Package` with backtick-wrapped package name
3. **Imports Section**: `## Imports` with code block
4. **Class Info Table**: Properties table for single class files
5. **Classes Overview Table**: For multi-class files
6. **Detailed Class Sections**: Individual class details

### Single Class Example
```markdown
# com.example.Sample

## Package
`com.example`

## Imports
```java
import java.util.List;
import java.util.Map;
```

## Class Info
| Property | Value |
|----------|-------|
| Package | com.example |
| Type | class |
| Visibility | public |
| Lines | 1-50 |
| Total Methods | 5 |
| Total Fields | 3 |

## Sample (1-50)

### Fields
| Name | Type | Vis | Modifiers | Line | Doc |
|------|------|-----|-----------|------|-----|
| name | String | - | private,final | 10 | Field documentation |
| count | int | - | private | 15 | - |

### Constructors
| Constructor | Signature | Vis | Lines | Cx | Doc |
|-------------|-----------|-----|-------|----|----|
| Sample | (name:String):void | + | 20-25 | 1 | Constructor documentation |

### Public Methods
| Method | Signature | Vis | Lines | Cx | Doc |
|--------|-----------|-----|-------|----|----|
| getName | ():String | + | 30-32 | 1 | - |
| setName | (name:String):void | + | 35-37 | 1 | - |

### Private Methods
| Method | Signature | Vis | Lines | Cx | Doc |
|--------|-----------|-----|-------|----|----|
| validate | (value:String):boolean | - | 40-45 | 2 | Validation method |
```

### Multi-Class Example
```markdown
# MultiClass.java

## Package
`com.example`

## Classes Overview
| Class | Type | Visibility | Lines | Methods | Fields |
|-------|------|------------|-------|---------|--------|
| ClassA | class | public | 1-25 | 3 | 2 |
| ClassB | class | public | 30-50 | 2 | 1 |

## ClassA (1-25)
[Individual class details...]

## ClassB (30-50)
[Individual class details...]
```

## Compact Format Specification

### Structure
The compact format produces a simplified Markdown table with complexity information:

```markdown
# com.example.Sample

## Info
| Property | Value |
|----------|-------|
| Package | com.example |
| Methods | 5 |
| Fields | 3 |

## Methods
| Method | Sig | V | L | Cx | Doc |
|--------|-----|---|---|----|----|
| getName | ():S | + | 30-32 | 1 | - |
| setName | (name:S):void | + | 35-37 | 1 | - |
| validate | (value:S):b | - | 40-45 | 2 | Validation method |
```

### Key Features
- **Complexity Column**: `Cx` column with complexity scores (REQUIRED)
- **Shortened Types**: `S` for String, `i` for int, `b` for boolean, etc.
- **Visibility Symbols**: `+` public, `-` private, `#` protected, `~` package
- **Compact Signatures**: Shortened parameter and return types

## CSV Format Specification

### Structure
Simple CSV with the following columns:
```csv
Type,Name,Signature,Visibility,Lines,Complexity,Doc
Field,name,name:String,private,10-10,,Field documentation
Method,getName,():String,public,30-32,1,-
Constructor,Sample,(name:String):void,public,20-25,1,Constructor documentation
```

### Key Features
- **Simple Structure**: No nested objects or complex parameter breakdowns
- **Full Signatures**: Complete method signatures with parameter names and types
- **Complexity Values**: Numeric complexity scores for methods
- **Empty Complexity**: Empty string for fields (no complexity)

## Format Decision Logic

### Header Generation Rules
1. **Single Class**: Use `package.ClassName` format
2. **Multiple Classes**: Use filename without extension
3. **No Classes**: Use `package.filename` or `unknown.Unknown`

### Visibility Conversion
- `public` → `+`
- `private` → `-`
- `protected` → `#`
- `package` → `~`

### Type Shortening (Compact Format)
- `String` → `S`
- `int` → `i`
- `long` → `l`
- `double` → `d`
- `boolean` → `b`
- `void` → `void`
- `Object` → `O`
- `Map<String,Object>` → `M<S,O>`
- `List<String>` → `L<S>`
- `String[]` → `S[]`

### Signature Format
- **Full Format**: `(paramName:ParamType, ...):ReturnType [modifiers]`
- **Compact Format**: `(ParamType, ...):ReturnType`
- **CSV Format**: Same as full format

### Line Range Format
- Always use `start-end` format (e.g., `30-32`)
- Single line elements: `line-line` (e.g., `10-10`)

## Critical Requirements

### Markdown Table Compliance
- All tables MUST use proper Markdown syntax with `|` separators
- Headers MUST be properly formatted with `|---|---|` separator rows
- Cell content MUST be properly escaped for Markdown

### Complexity Information
- **REQUIRED** in compact format `Cx` column
- **REQUIRED** in CSV format `Complexity` column
- Numeric values for methods, empty for fields

### Backward Compatibility
- Output MUST match v1.6.1.4 exactly for identical inputs
- Line endings MUST be consistent (LF normalized)
- No trailing whitespace or extra newlines

### Unsupported Features
- HTML formats (`html`, `html_compact`, `html_json`) are NOT part of v1.6.1.4 specification
- Complex parameter breakdowns in CSV are NOT part of original specification
- Plain text formats are NOT part of original specification

## Implementation Notes

### Platform Considerations
- Line endings normalized to LF (`\n`)
- Platform-specific newlines handled in conversion layer
- CSV output uses explicit `\n` line terminators

### Error Handling
- `FileNotFoundError` for missing files
- `ValueError` for unsupported format types
- Graceful handling of missing or malformed data

### Performance
- Format decision should be minimal overhead
- Legacy formatter should match original performance characteristics
