npm package: @jemo/archi-comatrix
Description: Archi script to export model elements to Excel matrix
Author: jemo
Latest version: 1.0.0

# Comatrix

Export Archi model relationships to Excel connectivity matrix with baseline comparison support, and generate application lists.

## Description

Comatrix is an Archi JavaScript extension that provides two main tools:

1. **Connectivity Matrix (comatrix)**: Analyzes ArchiMate model relationships and exports them to a styled Excel connectivity matrix (`comatrix.xlsx`). It shows which A-elements (application components) connect to which B-elements through specific interfaces (Schnittstellen), with support for baseline comparison to highlight changes between model versions.

2. **Application List (applist)**: Generates a list of all application components with specialization "Geschäftsanwendung" and their associated domains (`applist.xlsx`).

> **📖 New to these scripts?** See [doc/metamodel.md](doc/metamodel.md) for a comprehensive guide on how to structure your Archi model to work with these scripts, including which elements, relationships, specializations, and properties influence the outputs.

## Features

### Connectivity Matrix (comatrix)
- **Connectivity Matrix**: Generates a matrix showing connections between A-elements and B-elements via interfaces
- **Baseline Comparison**: Compare current model against a baseline to identify:
  - New elements/connections (green)
  - Changed connections (yellow/orange)
  - Removed elements/connections (red)
- **Domain Detection**: Automatically groups elements by domain using aggregation/composition relationships
- **Relationship Types**: Focuses on serving relationships and related ArchiMate connections
- **Visual Styling**: Color-coded cells with proper borders, fonts, and text rotation
- **Excel Features**: Frozen panes (first 4 columns and 2 rows), auto-fit column widths
- **Intern/Extern Classification**: Automatically detects whether connections are internal or external based on domains

### Application List (applist)
- **Application Listing**: Lists all application components with specializations:
  - "Geschäftsanwendung"
  - "Register"
  - "Querschnittsanwendung"
- **Domain Assignment**: Shows ALL domains (Domäne) for each application from grouping elements with specialization "Domäne"
  - Multiple domains are comma-separated
  - Handles nested groupings by traversing the entire hierarchy
- **Fachbereich Assignment**: Shows ALL Fachbereich for each application from grouping elements with specialization "Fachbereich"
  - Multiple Fachbereich are comma-separated
  - Handles nested groupings by traversing the entire hierarchy
- **Cycle Detection**: Detects circular grouping references and displays "cycle" instead of infinite loop
- **Type Classification**: Displays the specialization type for each application
- **Sorted Output**: Applications sorted by Fachbereich, then domain, then type, then name
- **Clean Formatting**: Styled Excel output with headers and borders

## Installation

1. Navigate to the comatrix directory:
```bash
cd comatrix
```

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

## Usage

### Connectivity Matrix

#### Option 1: Bundled Version (Recommended)
1. Open your ArchiMate model in Archi
2. Run the script: `Scripts > comatrix-bundled.ajs` (located in `dist/` folder)
3. The Excel file `comatrix.xlsx` will be created in the same directory as your model
4. The file explorer will automatically open showing the output file

**No npm install required!** The bundled version includes all dependencies in a single ~932 KiB file.

#### Option 2: Development Version
For development, you can work directly with the source files in `src/main/` and rebuild using webpack.

#### Baseline Comparison
To compare a current model against a baseline:
1. Add a property "baseline" to your model with the name of the baseline model
2. Ensure both models are opened in Archi
3. Run the script - it will automatically detect and compare against the baseline
4. The Excel output highlights differences:
   - **Green (RGB 155/187/89)**: New elements or connections
   - **Yellow/Orange (RGB 255/192/0 or 255/255/0)**: Changed connections
   - **Red (RGB 192/80/77)**: Removed elements or connections
5. Legend is displayed in cells A1-C1 for easy reference

### Application List

1. Open your ArchiMate model in Archi
2. Run the script: `Scripts > applist-bundled.ajs` (located in `dist/` folder)
3. The Excel file `applist.xlsx` will be created in the same directory as your model
4. The file explorer will automatically open showing the output file

The application list includes:
- All application components with specializations: "Geschäftsanwendung", "Register", "Querschnittsanwendung"
- Their specialization type (Typ column)
- Their associated domains (Domäne) from ALL grouping elements with specialization "Domäne"
  - If an application is grouped by multiple domains (directly or through nested groupings), all are shown comma-separated
- Their associated Fachbereich from ALL grouping elements with specialization "Fachbereich"
  - If an application belongs to multiple Fachbereich (directly or through nested groupings), all are shown comma-separated
- Sorted by Fachbereich, then domain, then type, then application name
- Cycle detection: If circular grouping references are detected, "cycle" is displayed

## Building

To create the bundled versions:

```bash
npm run build
```

This generates both:
- `dist/comatrix-bundled.ajs` - Connectivity matrix script (~932 KiB)
- `dist/applist-bundled.ajs` - Application list script (~906 KiB)

Both include xlsx-js-style and all dependencies.

## Publishing to npm

This package is automatically published to npm under `@jemo/archi-comatrix` when changes are pushed to the main branch.

### Initial Setup (First-Time Only)

Before automated publishing can work, you need to publish the package manually once:

```bash
npm login
npm run build
npm publish --access public
```

This creates the package on npmjs.com and establishes your ownership.

### Configuring Trusted Publisher

After the first manual publish, set up automated publishing:

1. Go to https://www.npmjs.com/package/@jemo/archi-comatrix
2. Navigate to Settings → Publishing Access
3. Click "Add a trusted publisher"
4. Configure with these settings:
   - **Provider**: GitHub Actions
   - **Owner**: jemo (your GitHub username/org)
   - **Repository**: comatrix (your repository name)
   - **Workflow**: build-release.yml
   - **Environment**: (leave blank)
5. Save the configuration

### Automatic Publishing (via GitHub Actions)

Once trusted publishing is configured, the `.github/workflows/build-release.yml` workflow automatically:
1. Builds the bundled scripts
2. Publishes to npm with provenance attestations using OIDC authentication
3. Deploys to the `release` branch

No npm access tokens or secrets are needed - authentication happens automatically via OIDC.

### Subsequent Manual Publishing

To publish manually after setup:
```bash
npm run build
npm publish --provenance --access public
```

Note: Manual publishing requires npm authentication (`npm login`) and appropriate permissions for the `@jemo` scope.

## Project Structure

```
comatrix/
├── package.json                  # Project configuration and dependencies
├── webpack.config.js             # Webpack bundling configuration
├── doc/
│   └── metamodel.md              # Archi model structure guide
├── src/
│   └── main/
│       ├── comatrix.js           # Main entry point - connectivity matrix
│       ├── applist.js            # Application list generator
│       ├── output2Excel.js       # Excel generation with styling
│       └── model.js              # Archi model interaction functions
├── dist/
│   ├── comatrix-bundled.ajs     # Bundled connectivity matrix script
│   └── applist-bundled.ajs      # Bundled application list script
├── tests/                        # Test files
└── .github/
    └── workflows/
        └── build-release.yml     # Automated build to release branch
```

## Requirements

- Archi (https://www.archimatetool.com/) with jArchi plugin
- Node.js and npm (for building only, not required to run bundled version)
- xlsx-js-style library (automatically included in bundle)

## Output Format

### Connectivity Matrix (comatrix.xlsx)

The generated Excel file contains one worksheet named "Matrix" with:
- **Row 0 (Legend)**: Color-coded legend in A1-C1, domain names for B-elements
- **Row 1 (Headers)**: Column headers with vertical text for B-elements
- **Row 2+ (Data)**: Each row represents an A-element + Interface combination
  - Column A: Domäne (Domain)
  - Column B: Anwendungssystem (Application System / A-element)
  - Column C: Angebotene Schnittstelle (Offered Interface)
  - Column D: intern/extern classification
  - Columns E+: B-elements with "x" marking connections

#### Color Coding
- **Green fill**: New elements or connections (not in baseline)
- **Yellow/Orange fill**: Changed connections or modified elements
- **Red fill**: Removed elements or connections (in baseline but not current)
- **Text colors**: White text on red background, black text on all others
- **Blue background (RGB 184/204/228)**: Standard B-element columns

### Application List (applist.xlsx)

The generated Excel file contains one worksheet named "Anwendungen" with:
- **Row 1 (Header)**: "Anwendung", "Typ", "Domäne", "Fachbereich" columns with gray background
- **Row 2+ (Data)**: All application components with specializations "Geschäftsanwendung", "Register", or "Querschnittsanwendung"
  - Column A: Anwendung (Application name)
  - Column B: Typ (Specialization: Geschäftsanwendung, Register, or Querschnittsanwendung)
  - Column C: Domäne (All domains from groupings with specialization "Domäne", comma-separated if multiple)
  - Column D: Fachbereich (All Fachbereich from groupings with specialization "Fachbereich", comma-separated if multiple)
  
**Special values:**
- Multiple domains/Fachbereich: Shown as comma-separated list (e.g., "Domain1, Domain2")
- Cycle detected: Shows "cycle" if circular grouping references exist
- No grouping found: Shows "(keine Domäne)" or "(kein Fachbereich)"

Applications are sorted by Fachbereich, then domain, then type, then alphabetically by name.

## Development

The codebase is organized into several modules:

1. **model.js**: Archi model interaction
   - `findAllGroupings()`: Helper function that traverses aggregation/composition relationships to find all groupings with a specific specialization
   - `findDomain()`: Finds ALL domains by traversing aggregation/composition relationships, looking for specialization "Domäne"
     - Returns comma-separated list of all found domains
     - Detects and reports cycles
     - Handles nested groupings
   - `findFachbereich()`: Finds ALL Fachbereich by traversing aggregation/composition relationships, looking for specialization "Fachbereich"
     - Returns comma-separated list of all found Fachbereich
     - Detects and reports cycles
     - Handles nested groupings
   - `extractElements()`: Finds triggering relationships starting with NST_*

2. **comatrix.js**: Connectivity matrix generator
   - `buildComatrix()`: Extracts relationships from Archi model
   - `merge()`: Combines baseline and current matrices
   - `sortElementsByDomain()`: Sorts elements by domain and name
   - `runComatrix()`: Main execution flow with baseline detection

3. **applist.js**: Application list generator
   - Queries application components with specializations: "Geschäftsanwendung", "Register", "Querschnittsanwendung"
   - Uses `findDomain()` and `findFachbereich()` to get ALL classifications (comma-separated)
   - Handles nested groupings and detects cycles
   - Generates Excel with 4 columns: Anwendung, Typ, Domäne (can be multi-value), Fachbereich (can be multi-value)
   - `generateAppListExcel()`: Creates styled Excel output with wider columns for multi-value cells

4. **output2Excel.js**: Excel generation utilities
   - Styling definitions with color constants
   - `getFontStyle()`: Unified font styling
   - `getTextColor()`: Text color based on background
   - Baseline comparison logic
   - Cell coloring based on comparison results
   - Excel file writing using Java FileOutputStream

To add more features:
1. Modify relationship detection in `buildComatrix()` or extend `extractElements()`
2. Enhance comparison logic in `output2Excel()` 
3. Add new specializations or filtering in `applist.js`
4. Extend domain detection logic in `model.js`

## Documentation

### Metamodel Guide

For a comprehensive understanding of how to structure your Archi model to work effectively with these scripts, see **[doc/metamodel.md](doc/metamodel.md)**.

This guide covers:
- Which Archi element types are analyzed (application components, groupings)
- Which relationship types matter (triggering, aggregation, composition)
- Required specializations (Domäne, Fachbereich, Geschäftsanwendung, Register, Querschnittsanwendung)
- Properties and naming conventions (NST_* prefix, Schnittstelle property)
- How model structure influences outputs
- Example structures and troubleshooting tips

**When to read this:**
- Setting up a new Archi model for these scripts
- Troubleshooting empty or unexpected outputs
- Understanding why certain elements appear/don't appear in the Excel files
- Planning your model's organization strategy

## License

MIT