ifc-language-server/README.md

# IFC Language Server for VSCode/VSCodium

A Visual Studio Code extension providing comprehensive language support for Industry Foundation Classes (IFC) files.

## Features

### 🔍 **Go to Definition** (F12)
Jump directly to the definition of any IFC entity reference.
- Click on an entity reference like `#123` and press **F12**
- Navigate instantly to where that entity is defined
- Works across the entire IFC file

### 🔎 **Find All References** (Shift+F12)
Find all locations where an IFC entity is used.
- Right-click on an entity definition or reference
- Select "Find All References" or press **Shift+F12**
- See all references in the References panel
- Click any reference to jump to that location

### 💡 **Hover Information**
View detailed information about IFC entities on hover.
- Hover over any entity reference (e.g., `#123`)
- See the complete entity definition
- View hierarchical dependency tree showing all referenced entities
- Understand relationships at a glance

### 📖 **Documentation Links** (Ctrl+Click)
Quick access to official buildingSMART documentation.
- **Ctrl+Click** (or **Cmd+Click** on Mac) on any IFC entity type name
- Automatically opens the correct documentation page in your browser
- Supports all schema versions:
  - **IFC2X3**: 653 entities with package-based URLs
  - **IFC4**: Standard entity URLs
  - **IFC4X3**: 876 entities with proper PascalCase URLs
- Schema version automatically detected from `FILE_SCHEMA` line

### 🌲 **IFC Entity Hierarchy View**
Visual tree view of entity structure.
- Open the "IFC Entity Hierarchy" view in the Explorer sidebar
- See hierarchical relationships between entities
- Expand/collapse entity branches
- Click any entity to jump to its definition
- Refresh to update after file changes

### 🔗 **IFC Entity References View**
Browse all entity references in your IFC file.
- Open the "IFC Entity References" view in the Explorer sidebar
- See a list of all entities and their references
- Shows reference count for each entity
- Click to navigate to definitions or references
- Refresh to update after file changes

### 📝 **Document Symbols** (Ctrl+Shift+O)
Quick navigation through IFC entities.
- Press **Ctrl+Shift+O** (or **Cmd+Shift+O** on Mac)
- See an outline of all IFC entities in the file
- Type to filter entities
- Click to jump to any entity definition
- Also visible in the "Outline" view

### 🎨 **Syntax Highlighting**
Enhanced syntax coloring for IFC files.
- Entity references (`#123`) highlighted distinctly
- Entity types (`IFCPROJECT`, `IFCWALL`) color-coded
- String values and numbers styled appropriately
- Comments clearly distinguished
- Improved readability for large IFC files

### 🖱️ **Context Menu Actions**
Right-click context menu for common operations.
- **Show in Hierarchy**: Reveal entity in the hierarchy tree view
- **Show References**: Display all references in the references view
- **Go to Definition**: Jump to entity definition
- **Find All References**: Find all usages
- Quick access to frequently used features

## Installation

### From VSIX File

1. **Download** the `.vsix` file from the releases page
2. **Open VSCode/VSCodium**
3. Go to **Extensions** view (`Ctrl+Shift+X`)
4. Click the **"..."** menu at the top of the Extensions view
5. Select **"Install from VSIX..."**
6. Browse to and select the downloaded `.vsix` file
7. Click **"Install"**
8. Reload VSCode/VSCodium when prompted

### From Source

1. **Clone the repository**
   ```bash
   git clone https://github.com/yourusername/ifc-language-server.git
   cd ifc-language-server
   ```

2. **Install dependencies**
   ```bash
   npm install
   ```

3. **Compile the extension**
   ```bash
   npm run compile
   ```

4. **Run in development mode**
   - Press **F5** in VSCode/VSCodium
   - A new "Extension Development Host" window will open
   - Open any `.ifc` file to test the extension

5. **Package as VSIX** (optional)
   ```bash
   npm install -g vsce
   vsce package
   ```
   This creates a `.vsix` file you can install or distribute.

## Usage

### Opening IFC Files

1. Open any `.ifc` file in VSCode/VSCodium
2. The extension automatically activates for files with `.ifc` extension
3. All features are immediately available

### Keyboard Shortcuts

| Feature | Windows/Linux | macOS |
|---------|---------------|-------|
| Go to Definition | `F12` | `F12` |
| Find All References | `Shift+F12` | `Shift+F12` |
| Document Symbols | `Ctrl+Shift+O` | `Cmd+Shift+O` |
| Open Documentation | `Ctrl+Click` | `Cmd+Click` |
| Hover Information | Hover mouse | Hover mouse |

### Tree Views

The extension adds two tree views to the Explorer sidebar:

**IFC Entity Hierarchy**
- Shows parent-child relationships between entities
- Useful for understanding spatial structure
- Example: `IFCPROJECT` → `IFCSITE` → `IFCBUILDING` → `IFCBUILDINGSTOREY`

**IFC Entity References**
- Lists all entities with their reference counts
- Helps identify heavily-used entities
- Useful for quality checking

Both views include:
- 🔄 **Refresh** button to update after file changes
- Click to navigate to entity definitions
- Expand/collapse for better organization

### Documentation Links

When you **Ctrl+Click** on an entity type, the extension:

1. **Detects the schema version** from your IFC file's `FILE_SCHEMA` line
2. **Finds the correct documentation URL**:
   - IFC2X3: Uses entity-to-package mapping (e.g., `IFCWALL` → `ifcsharedbldgelements`)
   - IFC4: Standard link URLs
   - IFC4X3: Proper PascalCase entity names (e.g., `IfcMeasureWithUnit`)
3. **Opens your browser** to the official buildingSMART documentation

Example URLs:
- IFC2X3: `https://standards.buildingsmart.org/IFC/RELEASE/IFC2x3/TC1/HTML/ifcsharedbldgelements/lexical/ifcwall.htm`
- IFC4: `https://standards.buildingsmart.org/IFC/RELEASE/IFC4/ADD2_TC1/HTML/link/ifcwall.htm`
- IFC4X3: `https://ifc43-docs.standards.buildingsmart.org/IFC/RELEASE/IFC4x3/HTML/lexical/IfcWall.htm`

## Configuration

Currently, the extension works out-of-the-box with no configuration required. All IFC schema versions (IFC2X3, IFC4, IFC4X3) are automatically detected and supported.

## Development

### Project Structure

```
ifc-language-server/
├── client/
│   └── src/
│       ├── extension.ts                      # Main extension entry point
│       ├── ifcDefinitionProvider.ts          # Go to Definition (F12)
│       ├── ifcReferenceProvider.ts           # Find References (Shift+F12)
│       ├── ifcHoverProvider.ts               # Hover information
│       ├── ifcDocumentationLinkProvider.ts   # Ctrl+Click documentation
│       ├── ifcEntityHierarchyProvider.ts     # Hierarchy tree view
│       ├── ifcEntityReferencesProvider.ts    # References tree view
│       ├── ifcDocumentSymbolProvider.ts      # Document outline
│       ├── ifc2x3-mappings.txt              # IFC2X3 entity→package mapping
│       ├── ifc4x3-mappings.txt              # IFC4X3 entity→PascalCase mapping
│       └── generate-ifc-provider-FINAL.py   # Regenerate doc provider
├── syntaxes/
│   └── ifc.tmLanguage.json                  # TextMate syntax highlighting
├── package.json                              # Extension manifest
└── README.md                                 # This file
```

### Updating Documentation Mappings

If buildingSMART updates their documentation structure, regenerate the mappings:

```bash
cd client/src

# For IFC2X3 (if URL structure changes)
curl -s "https://standards.buildingsmart.org/IFC/RELEASE/IFC2x3/TC1/HTML/alphabeticalorder_entities.htm" > ifc2x3-page.html
grep -E 'HREF="[^"]+/lexical/[^"]+"' ifc2x3-page.html | \
  sed 's/.*HREF="\([^/]*\)\/lexical\/\([^"]*\)\.htm".*/\1 \2/' | \
  awk '{print toupper($2), $1}' | \
  sort -u > ifc2x3-mappings.txt

# For IFC4X3 (if entities are added)
curl -s "https://ifc43-docs.standards.buildingsmart.org/IFC/RELEASE/IFC4x3/HTML/annex-b1.html" > annex-b1.html
grep -oE 'href="[^"]*lexical/Ifc[^"]*\.htm"' annex-b1.html | \
  sed 's/.*lexical\///' | \
  sed 's/\.htm.*//' | \
  sort -u > ifc4x3-entities.txt
awk '{print toupper($0), $0}' ifc4x3-entities.txt > ifc4x3-mappings.txt

# Regenerate the TypeScript provider
python3 generate-ifc-provider-FINAL.py ifc2x3-mappings.txt ifc4x3-mappings.txt > ifcDocumentationLinkProvider.ts

# Recompile
cd ../..
npm run compile
```

### Building for Distribution

```bash
# Install VSCE (once)
npm install -g vsce

# Package the extension
vsce package

# This creates: ifc-language-server-X.Y.Z.vsix
```

### Testing

1. Press **F5** to launch Extension Development Host
2. Open a test IFC file (e.g., `test.ifc`)
3. Test each feature:
   - Hover over entity references
   - F12 on references
   - Shift+F12 for references
   - Ctrl+Click on entity types
   - Open tree views
   - Check syntax highlighting

## Supported IFC Schemas

- ✅ **IFC2X3** - Full support (653 entities)
- ✅ **IFC4** - Full support
- ✅ **IFC4X3** - Full support (876 entities)

The extension automatically detects the schema version from the `FILE_SCHEMA` line in your IFC file.

## Known Limitations

- Large IFC files (>10MB) may experience slower hover/navigation performance
- The extension reads the entire file into memory - very large files (>100MB) may impact VSCode/VSCodium performance
- Documentation links require an internet connection to open buildingSMART pages

## Troubleshooting

### Extension not activating
- Ensure the file has `.ifc` extension
- Check VSCode/VSCodium's Output panel (select "IFC Language Server" from dropdown) for errors
- Try reloading VSCode/VSCodium: `Ctrl+Shift+P` → "Reload Window"

### Go to Definition not working
- Ensure the entity reference format is correct: `#123`
- Check that the referenced entity exists in the file
- The entity definition must be in the format: `#123 = IFCENTITYTYPE(...)`

### Documentation links opening wrong pages
- Verify your IFC file has a valid `FILE_SCHEMA` line
- Check that the entity type is spelled correctly
- Some rare entities may not have documentation pages

### Tree views not updating
- Click the 🔄 Refresh button at the top of the tree view
- If still not updating, close and reopen the IFC file

## Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

### Areas for Contribution
- Support for additional IFC schemas (IFC4.1, IFC4.2, etc.)
- Performance optimizations for large files
- Additional language features (auto-completion, validation, etc.)
- Better syntax highlighting rules
- Internationalization/localization

## Acknowledgments

This extension was inspired by and builds upon concepts from [ifc-developer-tools](https://github.com/AlanRynne/ifc-developer-tools) by [Alan Rynne](https://github.com/AlanRynne).

Special thanks to:
- **Alan Rynne** for the foundational IFC parsing and VSCode extension concepts
- **buildingSMART International** for IFC schema documentation and standards
- The open-source community supporting IFC tooling development

## License

MIT License - see [LICENSE](LICENSE) file for details.

This project builds upon concepts from ifc-developer-tools, which is also MIT licensed.

## Support

- 🐛 **Report bugs & Feature requests**: https://hub.openingdesign.com/OpeningDesign/ifc-language-server/issues


---

**Enjoy working with IFC files in VSCode/VSCodium! 🏗️**