feat: map Compass DEPENDS_ON relationships to service markdown (Phase 3) (#144)

IsmaelMartinez · claude · web-flow · commit a547fd4e0c19 · 2026-02-16T07:47:50.000Z
* feat: map Compass DEPENDS_ON relationships to service markdown (Phase 3) Parse relationships.DEPENDS_ON from Compass YAML and resolve referenced services using a two-pass approach. First pass collects all services into a map (Compass ARN → service ID), second pass resolves dependencies and generates markdown with linked dependency sections. - Add ResolvedDependency type to src/types.ts - Update defaultMarkdown() to render Dependencies section with links - Update loadService() to accept optional dependencies parameter - Implement two-pass service processing in index.ts for dependency resolution - Handle missing dependency targets gracefully (log warning, don't crash) - Update test fixtures with cross-referencing DEPENDS_ON ARNs - Add 6 new tests covering relationship resolution scenarios - Mark Phase 3 as complete in PLAN.md https://claude.ai/code/session_01Nciw9idSbSrmH2PU7y8J7a * chore: update pnpm-lock.yaml and add pnpm-workspace.yaml https://claude.ai/code/session_01Nciw9idSbSrmH2PU7y8J7a * fix: address PR review - eliminate duplicate YAML parsing and typeFilter logic - Cache parsed configs in first pass, reuse in second pass instead of calling loadConfig() twice per service - Consolidate typeFilter check into first pass only (was duplicated) - Remove unused `config` field from serviceMap entries - Remove redundant serviceId re-computation in second pass https://claude.ai/code/session_01Nciw9idSbSrmH2PU7y8J7a * fix: remove pnpm v10 artifacts breaking CI with pnpm v8 Remove pnpm-workspace.yaml (pnpm v10 feature) and restore the original pnpm-lock.yaml from master. CI uses pnpm v8 which doesn't support the ignoredBuiltDependencies config or the libc metadata added by pnpm v10. CI's pnpm install will resolve any new dependencies from package.json. https://claude.ai/code/session_01Nciw9idSbSrmH2PU7y8J7a * fix: escape HTML special chars in sanitizeMarkdownText to prevent XSS The sanitizeMarkdownText function only escaped markdown link characters (brackets and parentheses) but not HTML special characters. In an MDX context, a malicious dependency name like <script>alert(1)</script> would be rendered as executable HTML. Now escapes &, <, >, ", and ' as HTML entities before escaping markdown syntax, preventing XSS in generated service markdown. https://claude.ai/code/session_01Nciw9idSbSrmH2PU7y8J7a * docs: initialise CLAUDE.md Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * style: format CLAUDE.md with prettier Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> --------- Co-authored-by: Claude <noreply@anthropic.com>
diff --git a/.changeset/phase-3-relationship-mapping.md b/.changeset/phase-3-relationship-mapping.md
@@ -0,0 +1,11 @@
+---
+'@ismaelmartinez/generator-atlassian-compass-event-catalog': minor
+---
+
+feat: map Compass DEPENDS_ON relationships to service markdown
+
+- Parse `relationships.DEPENDS_ON` from Compass YAML and resolve referenced services
+- Add a "Dependencies" section to generated service markdown with links to dependent services
+- Use a two-pass approach: first collect all services, then resolve dependencies between them
+- Handle missing dependency targets gracefully (log warning, don't crash)
+- Services without dependencies show "No known dependencies."
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -0,0 +1,50 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+An EventCatalog generator plugin that reads Atlassian Compass YAML files and produces service entries in an EventCatalog. It parses `compass.yml` files, extracts metadata (links, badges, owners, dependencies), and uses the `@eventcatalog/sdk` to write services (and optionally domains) into the catalog's file system.
+
+## Commands
+
+Package manager is pnpm (v8 in CI). All commands use `pnpm run`.
+
+```
+pnpm install          # install deps
+pnpm run build        # build with tsup (CJS + ESM + .d.ts into dist/)
+pnpm run test         # run vitest in watch mode
+pnpm run test -- run  # single test run (no watch)
+pnpm run lint         # eslint
+pnpm run lint:fix     # eslint with auto-fix
+pnpm run format:diff  # prettier check (CI uses this)
+pnpm run format       # prettier write
+```
+
+CI runs three checks on PRs: Tests, Lint (eslint + prettier), and Verify Build. All must pass.
+
+## Architecture
+
+The plugin exports a single async function from `src/index.ts` that EventCatalog calls with a config object and `GeneratorProps` options. Processing happens in two passes over the services array:
+
+Pass 1 (`src/index.ts`): Load each compass YAML via `loadConfig` from `src/compass.ts`, apply the optional `typeFilter`, and build a `serviceMap` keyed by Compass ARN so that `DEPENDS_ON` relationships can be resolved between services.
+
+Pass 2 (`src/index.ts`): For each processable file, call `loadService` from `src/service.ts` to build the `Service` object (markdown template with links, dependencies, badges, owners, repository URL), then write it via the EventCatalog SDK. If a `domain` option is provided, `src/domain.ts` handles creating/versioning the domain and associating services to it.
+
+Key modules:
+
+- `src/compass.ts` — `CompassConfig` type definition and YAML loading. The type mirrors the Atlassian Compass config-as-code spec.
+- `src/service.ts` — Transforms a `CompassConfig` into an EventCatalog `Service`. Contains markdown template generation, badge building, URL sanitization (XSS prevention), and link formatting.
+- `src/domain.ts` — `Domain` class that manages domain creation, versioning, and service association via the SDK.
+- `src/validation.ts` — Zod schemas for validating `GeneratorProps` at runtime.
+- `src/types.ts` — Shared TypeScript types (`GeneratorProps`, `DomainOption`, `ResolvedDependency`).
+
+## Testing
+
+Single test file at `src/test/plugin.test.ts`. Tests run the full plugin against a temporary catalog directory (`src/test/catalog/`) that gets cleaned up in `afterEach`. Test fixture YAML files live in `src/test/`. The `vitest.setup.ts` adds a custom `toMatchMarkdown` matcher that normalizes whitespace.
+
+The `@eventcatalog/sdk` is inlined during testing (configured in `vitest.config.ts` via `server.deps.inline`).
+
+## Security Considerations
+
+`src/service.ts` sanitizes all user-controlled text before embedding in markdown/MDX: `sanitizeMarkdownText` escapes HTML special characters and markdown link syntax; `sanitizeUrl` only allows `http:`/`https:` protocols. `src/index.ts` sanitizes service IDs via `sanitizeId` to prevent path traversal.
diff --git a/PLAN.md b/PLAN.md
@@ -6,7 +6,7 @@ Evolve this generator from a "Compass YAML file reader" into a full "Compass int
 
 ---
 
-## Phase 1: Modernize & Fix Core Gaps
+## Phase 1: Modernize & Fix Core Gaps ✅ COMPLETE
 
 **Release**: v0.1.0 (minor -- new behavior: updates instead of skips)
 **Effort**: Small
@@ -136,7 +136,7 @@ export const GeneratorPropsSchema = z.object({
 
 ---
 
-## Phase 2: Support All Compass Component Types
+## Phase 2: Support All Compass Component Types ✅ COMPLETE
 
 **Release**: v0.2.0
 **Effort**: Medium
@@ -179,80 +179,42 @@ Add a badge showing the Compass component type: `{ content: "APPLICATION", backg
 
 ---
 
-## Phase 3: Relationship Mapping
+## Phase 3: Relationship Mapping ✅ COMPLETE
 
 **Release**: v0.3.0
 **Effort**: Medium
 
-### 3.1 — Parse and map DEPENDS_ON relationships
+### 3.1 — Parse and map DEPENDS_ON relationships ✅
 
-**File**: `src/service.ts` or new file `src/relationships.ts`
+**Files modified**: `src/types.ts`, `src/service.ts`, `src/index.ts`
 
-Compass YAML already has:
+**What was implemented:**
 
-```yaml
-relationships:
-  DEPENDS_ON:
-    - 'ari:cloud:compass:...'
-```
-
-**Important**: The SDK does **not** have a generic `addRelationshipToService()` function. The SDK models relationships through specific mechanisms:
-
-- `sends` / `receives` — for message flows (events, commands, queries between services via channels)
-- `writesTo` / `readsFrom` — for data store relationships
-- `<NodeGraph />` — renders the service/domain graph visually in markdown
-
-Compass `DEPENDS_ON` is a general architectural dependency, not a message flow. It doesn't map cleanly to `sends`/`receives` (which are for events/commands, not service-to-service dependencies). Using `addEventToService()` would be incorrect here — that function is for linking events to services, not for expressing that one service depends on another.
-
-**Approach**: Express dependencies through the service markdown and the domain's `<NodeGraph />`. The `<NodeGraph />` component already renders all services within a domain and their connections. We enrich each service's markdown with an explicit "Dependencies" section listing what it depends on, and ensure both services are in the same domain so the graph visualizes the relationship.
+- Added `ResolvedDependency` type (`{ id: string; name: string }`) to `src/types.ts`
+- Updated `defaultMarkdown()` in `src/service.ts` to accept and render a `dependencies` parameter, generating a "Dependencies" section with links to dependent services (or "No known dependencies." when none exist)
+- Updated `loadService()` to accept optional `dependencies` parameter and pass it through to markdown generation
+- Implemented two-pass approach in `src/index.ts`:
+  1. **First pass**: Collects all services being processed into a Map (Compass ARN → service ID + name), respecting `typeFilter`
+  2. **Second pass**: For each service, resolves `DEPENDS_ON` ARNs against the map, logs warnings for unresolvable dependencies, and writes services with resolved dependency markdown
+- Missing dependency targets are handled gracefully (warning logged, not crashed)
+- Dependency text in markdown is sanitized against injection
 
-1. Collect all service IDs being processed in a Map (Compass ARN → EventCatalog ID)
-2. For each service, resolve its `DEPENDS_ON` ARNs to EventCatalog service IDs
-3. Include the dependency list in the service's generated markdown
-4. If both services are in the same domain, the `<NodeGraph />` will show them together
+### 3.2 — Tests for Phase 3 ✅
 
-**File**: `src/service.ts`
-
-Add a dependencies section to the generated markdown:
-
-```ts
-// In defaultMarkdown(), add after links section:
-const dependencyLinks = dependencies
-  ?.map((dep) => `* [${dep.name}](/docs/services/${dep.id})`)
-  .join('\n');
-
-// Include in markdown:
-## Dependencies
-${dependencyLinks || 'No known dependencies.'}
-```
+Six new tests added to `src/test/plugin.test.ts`:
 
-**File**: `src/index.ts`
-
-Build the service map and resolve dependencies before generating markdown:
-
-```ts
-// First pass: collect all services into a map
-const serviceMap = new Map<string, { serviceId: string; config: CompassConfig }>();
-for (const file of compassFiles) {
-  const config = loadConfig(file.path);
-  serviceMap.set(config.id || '', { serviceId: file.id || config.name, config });
-}
-
-// Second pass: write services with resolved dependencies
-for (const file of compassFiles) {
-  const config = loadConfig(file.path);
-  const dependencies = (config.relationships?.DEPENDS_ON || []).map((arn) => serviceMap.get(arn)).filter(Boolean);
-
-  const service = loadService(config, compassUrl, file.version, file.id, dependencies);
-  await writeService(service);
-}
-```
+- ✅ Resolves dependencies between services processed together (my-service → my-application, my-library)
+- ✅ Resolves partial dependencies when only some targets are processed
+- ✅ Shows "No known dependencies" for services without DEPENDS_ON
+- ✅ Handles missing dependency targets gracefully without crashing
+- ✅ Resolves dependencies correctly when services have custom IDs
+- ✅ Includes resolved dependencies in service markdown within a domain
 
-### 3.2 — Tests for Phase 3
+Test fixtures updated with cross-referencing DEPENDS_ON ARNs:
 
-- Add fixture with two services that have `DEPENDS_ON` pointing to each other
-- Test that relationships are logged/processed
-- Test that missing dependency targets are handled gracefully (log warning, don't crash)
+- `my-service-compass.yml` → depends on `my-application` and `my-library`
+- `my-application-compass.yml` → depends on `my-library`
+- `my-other-compass.notsupported.yml` → depends on `my-application` and a non-existent ARN (for graceful failure testing)
 
 ---
 
@@ -433,13 +395,13 @@ If Compass provides team/owner data via the API, use `writeTeam()` and `writeUse
 
 ## Release Schedule
 
-| Phase | Version | Breaking?                                             | What ships                                  |
-| ----- | ------- | ----------------------------------------------------- | ------------------------------------------- |
-| 1     | 0.1.0   | No (new default `overrideExisting: true` is additive) | Richer services, update support, validation |
-| 2     | 0.2.0   | No (previously errored types now work)                | All Compass types supported                 |
-| 3     | 0.3.0   | No                                                    | Relationship mapping                        |
-| 4     | 0.4.0   | No (API mode is opt-in)                               | Compass API integration                     |
-| 5     | 0.5.0   | No                                                    | OpenAPI specs, scorecards, MDX, teams       |
+| Phase | Version | Breaking?                                             | What ships                                  | Status      |
+| ----- | ------- | ----------------------------------------------------- | ------------------------------------------- | ----------- |
+| 1     | 0.1.0   | No (new default `overrideExisting: true` is additive) | Richer services, update support, validation | ✅ Complete |
+| 2     | 0.2.0   | No (previously errored types now work)                | All Compass types supported                 | ✅ Complete |
+| 3     | 0.3.0   | No                                                    | Relationship mapping                        | ✅ Complete |
+| 4     | 0.4.0   | No (API mode is opt-in)                               | Compass API integration                     | ⏳ Planned  |
+| 5     | 0.5.0   | No                                                    | OpenAPI specs, scorecards, MDX, teams       | ⏳ Planned  |
 
 ---
 
@@ -448,19 +410,19 @@ If Compass provides team/owner data via the API, use `writeTeam()` and `writeUse
 ```
 src/
 ├── index.ts          # Main generator entry point (modified in phases 1-4)
-├── types.ts          # GeneratorProps, re-export SDK types (modified in phases 1-2, 4)
+├── types.ts          # GeneratorProps, ResolvedDependency, re-export SDK types (modified in phases 1-3, 4)
 ├── compass.ts        # YAML parser + CompassConfig type (modified in phase 2)
 ├── compass-api.ts    # NEW: Compass GraphQL API client (phase 4)
-├── service.ts        # loadService with badge/metadata mapping (modified in phases 1-3)
+├── service.ts        # loadService with badge/metadata/dependency mapping (modified in phases 1-3)
 ├── domain.ts         # Domain processing (minimal changes)
-├── relationships.ts  # NEW: relationship mapping logic (phase 3)
-├── validation.ts     # NEW: Zod schemas (phase 1)
+├── validation.ts     # Zod schemas (phase 1)
 └── test/
-    ├── plugin.test.ts                    # Main tests (extended each phase)
-    ├── my-service-compass.yml            # Existing fixture
-    ├── my-other-compass.notsupported.yml # Existing fixture (rename in phase 2)
-    ├── my-app-compass.yml                # NEW fixture (phase 2)
-    ├── my-library-compass.yml            # NEW fixture (phase 2)
+    ├── plugin.test.ts                    # Main tests (extended each phase, 34 tests)
+    ├── my-service-compass.yml            # SERVICE fixture (with DEPENDS_ON refs)
+    ├── my-application-compass.yml        # APPLICATION fixture (with DEPENDS_ON refs)
+    ├── my-library-compass.yml            # LIBRARY fixture
+    ├── my-capability-compass.yml         # CAPABILITY fixture
+    ├── my-other-compass.notsupported.yml # OTHER fixture (with partial DEPENDS_ON refs)
     └── compass-api.test.ts              # NEW: API client tests (phase 4)
 ```
 
diff --git a/src/index.ts b/src/index.ts
@@ -3,7 +3,7 @@ import chalk from 'chalk';
 import { loadConfig, CompassConfig } from './compass';
 import { loadService } from './service';
 import Domain from './domain';
-import { GeneratorProps } from './types';
+import { GeneratorProps, ResolvedDependency } from './types';
 import { GeneratorPropsSchema } from './validation';
 
 // Sanitize IDs to prevent path traversal from untrusted sources
@@ -43,6 +43,11 @@ export default async (_config: EventCatalogConfig, options: GeneratorProps) => {
     await domain.processDomain();
   }
 
+  // First pass: load all configs, apply typeFilter, and collect into a map (Compass ARN → service info)
+  // This allows resolving DEPENDS_ON relationships between services and avoids parsing YAML twice
+  const serviceMap = new Map<string, { serviceId: string; name: string }>();
+  const processableFiles: { file: (typeof compassFiles)[number]; config: CompassConfig; serviceId: string }[] = [];
+
   for (const file of compassFiles) {
     const compassConfig: CompassConfig = loadConfig(file.path);
 
@@ -56,17 +61,43 @@ export default async (_config: EventCatalogConfig, options: GeneratorProps) => {
       }
     }
 
-    console.log(chalk.blue(`\nProcessing component: ${compassConfig.name} (type: ${compassConfig.typeId || 'unknown'})`));
-
     const serviceId = sanitizeId(file.id || compassConfig.name);
+    if (compassConfig.id) {
+      serviceMap.set(compassConfig.id, { serviceId, name: compassConfig.name });
+    }
+    processableFiles.push({ file, config: compassConfig, serviceId });
+  }
+
+  // Second pass: write services with resolved dependencies
+  for (const { file, config: compassConfig, serviceId } of processableFiles) {
+    console.log(chalk.blue(`\nProcessing component: ${compassConfig.name} (type: ${compassConfig.typeId || 'unknown'})`));
 
     if (domain) {
       // Add the service to the domain
       await domain.addServiceToDomain(serviceId, file.version);
     }
 
+    // Resolve DEPENDS_ON relationships
+    const dependencies: ResolvedDependency[] = [];
+    if (compassConfig.relationships?.DEPENDS_ON) {
+      for (const arn of compassConfig.relationships.DEPENDS_ON) {
+        const target = serviceMap.get(arn);
+        if (target) {
+          dependencies.push({ id: target.serviceId, name: target.name });
+        } else {
+          console.log(chalk.yellow(` - Dependency ${arn} not found in processed services, skipping`));
+        }
+      }
+    }
+
     const existing = await getService(serviceId);
-    const compassService = loadService(compassConfig, options.compassUrl.replace(/\/$/, ''), file.version, serviceId);
+    const compassService = loadService(
+      compassConfig,
+      options.compassUrl.replace(/\/$/, ''),
+      file.version,
+      serviceId,
+      dependencies
+    );
 
     if (existing && options.overrideExisting !== false) {
       await writeService(compassService, { override: true });
diff --git a/src/service.ts b/src/service.ts
@@ -1,9 +1,15 @@
 import { CompassConfig } from './compass';
-import { Service, Badge } from './types';
+import { Service, Badge, ResolvedDependency } from './types';
 
-// Sanitize text for safe markdown embedding: escape brackets and parentheses
+// Sanitize text for safe markdown/MDX embedding: escape HTML special chars and markdown link syntax
 function sanitizeMarkdownText(text: string): string {
-  return text.replace(/[[\]()]/g, (char) => `\\${char}`);
+  return text
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;')
+    .replace(/[[\]()]/g, (char) => `\\${char}`);
 }
 
 // Sanitize URL for safe markdown link embedding: only allow http/https protocols
@@ -93,7 +99,12 @@ function getOwners(config: CompassConfig): string[] {
   return [teamId];
 }
 
-export const defaultMarkdown = (config: CompassConfig, compassComponentUrl?: string, compassTeamUrl?: string) => {
+export const defaultMarkdown = (
+  config: CompassConfig,
+  compassComponentUrl?: string,
+  compassTeamUrl?: string,
+  dependencies?: ResolvedDependency[]
+) => {
   const safeComponentUrl = compassComponentUrl ? sanitizeUrl(compassComponentUrl) : '';
   const safeTeamUrl = compassTeamUrl ? sanitizeUrl(compassTeamUrl) : '';
 
@@ -108,6 +119,11 @@ export const defaultMarkdown = (config: CompassConfig, compassComponentUrl?: str
     .filter(Boolean)
     .join('\n');
 
+  const dependencyLines =
+    dependencies && dependencies.length > 0
+      ? dependencies.map((dep) => `* [${sanitizeMarkdownText(dep.name)}](/docs/services/${dep.id})`).join('\n')
+      : 'No known dependencies.';
+
   return `
 
 ## Links
@@ -116,6 +132,10 @@ export const defaultMarkdown = (config: CompassConfig, compassComponentUrl?: str
 * 🪂 [Compass Team](${safeTeamUrl})
 ${linkLines}
 
+## Dependencies
+
+${dependencyLines}
+
 ## Architecture diagram
 
 <NodeGraph />
@@ -143,9 +163,15 @@ export function loadService(
   config: CompassConfig,
   compassUrl: string,
   serviceVersion: string = '0.0.0',
-  serviceId: string = config.name
+  serviceId: string = config.name,
+  dependencies?: ResolvedDependency[]
 ): Service {
-  const markdownTemplate = defaultMarkdown(config, getComponentUrl(compassUrl, config), getTeamUrl(compassUrl, config));
+  const markdownTemplate = defaultMarkdown(
+    config,
+    getComponentUrl(compassUrl, config),
+    getTeamUrl(compassUrl, config),
+    dependencies
+  );
   const badges = buildBadges(config);
   const repositoryUrl = getRepositoryUrl(config);
   const owners = getOwners(config);
diff --git a/src/test/my-application-compass.yml b/src/test/my-application-compass.yml
@@ -13,3 +13,6 @@ links:
     url: 'https://www.example.com/repos/my-application-repo'
 labels:
   - frontend
+relationships:
+  DEPENDS_ON:
+    - 'ari:cloud:compass:a0000000-b000-c000-d000-e00000000000:component/22222222-2222-2222-2222-222222222222/22222222-2222-2222-2222-222222222222'
diff --git a/src/test/my-other-compass.notsupported.yml b/src/test/my-other-compass.notsupported.yml
@@ -32,5 +32,5 @@ customFields:
     value: true
 relationships:
   DEPENDS_ON:
-    - 'ari:cloud:compass:00000000-0000-0000-0000-000000000000:component/00000000-0000-0000-0000-000000000000/00000000-0000-0000-0000-00000000000'
-    - 'ari:cloud:compass:00000000-0000-0000-0000-000000000000:component/00000000-0000-0000-0000-000000000000/00000000-0000-0000-0000-00000000000'
+    - 'ari:cloud:compass:a0000000-b000-c000-d000-e00000000000:component/11111111-1111-1111-1111-111111111111/11111111-1111-1111-1111-111111111111'
+    - 'ari:cloud:compass:99999999-9999-9999-9999-999999999999:component/99999999-9999-9999-9999-999999999999/99999999-9999-9999-9999-999999999999'
diff --git a/src/test/my-service-compass.yml b/src/test/my-service-compass.yml
diff --git a/src/test/plugin.test.ts b/src/test/plugin.test.ts
diff --git a/src/types.ts b/src/types.ts
