Skip to content

Commit fbfd5a6

Browse files
IsmaelMartinezclaude
IsmaelMartinez
and
claude
authored
docs: update README, example config, CONTRIBUTING and improve test coverage (#152)
Rewrite README with all current features (YAML/API modes, templates, dry-run, etc.), update example config with comprehensive options, fix CONTRIBUTING.md clone URL and add dev commands, add 12 new tests for security/debug/error paths, and remove Phase comments from source and test files. Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
1 parent f9351d4 commit fbfd5a6

File tree

5 files changed

+422
-81
lines changed

5 files changed

+422
-81
lines changed

‎CONTRIBUTING.md‎

Lines changed: 13 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ We welcome contributions to this project.
1313
Once forked, clone the repository to your machine.
1414

1515
```sh
16-
git clone git@github.com:ismaelmartinez/generator-compass-event-catalog.git
16+
git clone git@github.com:<your-username>/generator-atlassian-compass-event-catalog.git
1717
```
1818

1919
1. Install the dependencies
@@ -26,10 +26,17 @@ We welcome contributions to this project.
2626

2727
## Developing
2828

29-
It uses [vitest](https://vitest.dev/) for testing.
29+
It uses [vitest](https://vitest.dev/) for testing, [eslint](https://eslint.org/) for linting, and [prettier](https://prettier.io/) for formatting.
3030

3131
```sh
32-
pnpm test
32+
pnpm run test # run tests in watch mode
33+
pnpm run test -- run # single test run (no watch)
34+
pnpm run test:coverage # run tests with coverage report
35+
pnpm run lint # check for lint errors
36+
pnpm run lint:fix # auto-fix lint errors
37+
pnpm run format:diff # check formatting
38+
pnpm run format # auto-format files
39+
pnpm run build # build with tsup (CJS + ESM + .d.ts)
3340
```
3441

3542
You can link the project to your EventCatalog to test your generator.
@@ -44,7 +51,7 @@ After linking, then you can navigate to your EventCatalog directory and link bac
4451
npm link @ismaelmartinez/generator-atlassian-compass-event-catalog
4552
```
4653

47-
Then, in the this generator project, you can run the build command to build the project.
54+
Then, in this generator project, you can run the build command to build the project.
4855

4956
```sh
5057
pnpm run build
@@ -56,8 +63,6 @@ Finally, you can run the generate command in your EventCatalog project as you wi
5663
npm run generate
5764
```
5865

59-
You should be ready to start developing with the generator. Open and [issue](https://github.com/IsmaelMartinez/generator-atlassian-compass-event-catalog/issues) if you find any problems.
66+
You should be ready to start developing with the generator. Open an [issue](https://github.com/IsmaelMartinez/generator-atlassian-compass-event-catalog/issues) if you find any problems.
6067

61-
EventCatalog uses [EventCatalog SDK](https://www.eventcatalog.dev/docs/sdk) to interact with the Catalog.
62-
63-
You can also explore the [get started building compass apps](https://developer.atlassian.com/cloud/compass/integrations/get-started-integrating-with-Compass/#get-started-building-compass-apps) to learn more about the Compass API. I haven't explore it yet.
68+
EventCatalog uses the [EventCatalog SDK](https://www.eventcatalog.dev/docs/sdk) to interact with the Catalog. The generator also integrates with the [Compass GraphQL API](https://developer.atlassian.com/cloud/compass/integrations/get-started-integrating-with-Compass/) for API mode, fetching components, teams, and metadata directly from Compass.

‎README.md‎

Lines changed: 115 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -1,70 +1,138 @@
11
# Atlassian Compass EventCatalog Generator
22

3-
This generator can be used to create services in Event Catalog from an [Atlassian Compass file].
3+
An [EventCatalog](https://eventcatalog.dev/) generator plugin that creates services from [Atlassian Compass](https://developer.atlassian.com/cloud/compass/config-as-code/structure-and-contents-of-a-compass-yml-file/) components. It supports two modes: reading local `compass.yml` files (YAML mode) or fetching components directly from the Compass GraphQL API (API mode).
4+
5+
## Installation
6+
7+
```sh
8+
npm install @ismaelmartinez/generator-atlassian-compass-event-catalog
9+
```
10+
11+
## Configuration
12+
13+
Add the generator to your `eventcatalog.config.js`. The plugin supports two mutually exclusive modes: YAML mode (local files) and API mode (Compass GraphQL API).
14+
15+
### YAML mode
16+
17+
Read services from local `compass.yml` files:
18+
19+
```js
20+
generators: [
21+
[
22+
'@ismaelmartinez/generator-atlassian-compass-event-catalog',
23+
{
24+
services: [
25+
{
26+
path: 'path/to/compass.yml',
27+
version: '1.0.0', // optional, defaults to '0.0.0'
28+
id: 'custom-id', // optional, defaults to the name in the compass file
29+
},
30+
],
31+
compassUrl: 'https://your-site.atlassian.net/compass',
32+
},
33+
],
34+
],
35+
```
36+
37+
### API mode
38+
39+
Fetch components directly from the Compass GraphQL API:
40+
41+
```js
42+
generators: [
43+
[
44+
'@ismaelmartinez/generator-atlassian-compass-event-catalog',
45+
{
46+
api: {
47+
cloudId: '$COMPASS_CLOUD_ID', // supports $ENV_VAR syntax
48+
apiToken: '$COMPASS_API_TOKEN',
49+
email: '$COMPASS_EMAIL',
50+
baseUrl: 'https://your-site.atlassian.net', // must be HTTPS
51+
typeFilter: ['SERVICE', 'APPLICATION'], // optional, server-side filtering
52+
},
53+
compassUrl: 'https://your-site.atlassian.net/compass',
54+
},
55+
],
56+
],
57+
```
58+
59+
API mode credentials support `$ENV_VAR` syntax, so you can reference environment variables rather than hardcoding secrets.
60+
61+
### All options
62+
63+
| Option | Type | Default | Description |
64+
| ------------------- | ------------------------------------ | ---------- | ------------------------------------------------------------------ |
65+
| `services` | `ServiceOptions[]` | - | YAML mode: array of local compass file paths |
66+
| `api` | `ApiConfig` | - | API mode: Compass GraphQL API connection config |
67+
| `compassUrl` | `string` | (required) | Base URL for Compass component links |
68+
| `domain` | `{ id, name, version }` | - | Associate all services with a domain (created if it doesn't exist) |
69+
| `typeFilter` | `string[]` | - | Only process components matching these type IDs |
70+
| `overrideExisting` | `boolean` | `true` | Whether to update existing services or skip them |
71+
| `debug` | `boolean` | `false` | Enable debug logging (credentials are redacted) |
72+
| `format` | `'md' \| 'mdx'` | `'mdx'` | Output file format |
73+
| `serviceIdStrategy` | `'name' \| 'compass-id' \| Function` | `'name'` | How service IDs are derived |
74+
| `markdownTemplate` | `Function` | - | Custom function to generate service markdown content |
75+
| `dryRun` | `boolean` | `false` | Log what would happen without writing any changes |
76+
77+
See the [example configuration](examples/eventcatalog.config.js) for a complete working setup.
478

5-
# Getting started
79+
## Features
680

7-
## Installation and configuration
81+
### Component type support
882

9-
_Make sure you are on the latest version of EventCatalog_.
83+
All Compass component types are supported: SERVICE, APPLICATION, LIBRARY, CAPABILITY, CLOUD_RESOURCE, DATA_PIPELINE, MACHINE_LEARNING_MODEL, UI_ELEMENT, WEBSITE, and OTHER. Each component is written as an EventCatalog service entry. Use `typeFilter` to restrict which types are processed.
1084

11-
1. Install the package
85+
### Dependency mapping
1286

13-
```sh
14-
npm install @ismaelmartinez/generator-atlassian-compass-event-catalog
15-
```
87+
`DEPENDS_ON` relationships defined in Compass are resolved to links between EventCatalog services. Dependencies are resolved across all services processed in the same generator run, and unresolvable ARNs are logged and skipped gracefully.
1688

17-
1. Configure your EventCatalog to use your generator
89+
### Badge generation
1890

19-
Edit your `eventcatalog.config.js` file and add the generator
91+
Services receive color-coded badges based on their Compass metadata: component type (e.g. SERVICE, APPLICATION), lifecycle stage (Active, Pre-release, Deprecated), tier level (1-4), labels, and scorecard scores (green/amber/red based on percentage). Scorecard badges show the score name and percentage.
2092

21-
```js
22-
...
23-
generators: [
24-
[
25-
"@ismaelmartinez/generator-atlassian-compass-event-catalog",
26-
// These are options to give your generator
27-
{
28-
services: [
29-
{
30-
path: ["path/to/your/compass/file"],
31-
version: "1.0.0" //Optional (defaults to 0.0.0)
32-
id: "your-service-id" //Optional (defaults to the `name` in the compass file)
33-
}, // Repeat for each service
34-
],
35-
compassUrl: "https://your.atlassian.compass.url",
36-
domain: { id: 'orders', name: 'Compass', version: '1.0.0' }, //Optional
37-
debug: false //Optional
38-
}
39-
// Repeat for each domain
40-
]
41-
]
42-
...
43-
```
93+
### Team creation
4494

45-
[Example configuration file](examples/eventcatalog.config.js)
95+
When a component has an `ownerId`, the generator extracts the team UUID and creates an EventCatalog team entity. In API mode, the team's display name is fetched from Compass; in YAML mode the UUID is used as the name. Teams are deduplicated across services.
4696

47-
NOTE: If a domain is provided, the services will be added to it. If the domain does not exist, it will be created.
97+
### OpenAPI and AsyncAPI spec detection
4898

49-
1. Generate your services
99+
Links with names containing "openapi" or "swagger" are attached as OpenAPI specifications, and links with "asyncapi" are attached as AsyncAPI specifications. This allows EventCatalog to render API documentation alongside service pages.
50100

51-
On your EventCatalog project, run the generate command:
101+
### Custom markdown templates
52102

53-
```sh
54-
npm run generate
55-
```
103+
Provide a `markdownTemplate` function to fully control the markdown content generated for each service. The function receives the `CompassConfig` and resolved dependencies array:
56104

57-
1. And explore your services in your catalog:
105+
```js
106+
markdownTemplate: (config, dependencies) => {
107+
return `# ${config.name}\n\nDeps: ${dependencies.map(d => d.name).join(', ')}`;
108+
},
109+
```
58110

59-
```sh
60-
npm run dev
61-
```
111+
### Service ID strategies
62112

63-
## Features
113+
Control how service IDs are derived with `serviceIdStrategy`:
114+
115+
- `'name'` (default): uses the component name from Compass
116+
- `'compass-id'`: uses the Compass ARN (sanitized for filesystem safety)
117+
- Custom function: `(config) => string` for full control
118+
119+
File-level `id` overrides in YAML mode always take precedence over the strategy.
120+
121+
### Dry-run mode
122+
123+
Set `dryRun: true` to see what the generator would do without writing any files. Services, teams, and domain associations are all logged but not persisted.
64124

65-
Currently, the generator only supports generating services from an [Atlassian Compass file].
125+
### Error resilience
66126

67-
By design, the links with name 'null' are ignored. This is to allow having the links to EventCatalog in the Compass file without having to worry to show the link in the EventCatalog Service page.
127+
The generator continues processing when individual services fail (e.g. malformed YAML, missing files). A summary at the end reports succeeded and failed counts with error details.
128+
129+
### Domain support
130+
131+
When a `domain` option is provided, all generated services are associated with that domain. The domain is created automatically if it doesn't exist, and versioned if the version changes between runs.
132+
133+
## Security
134+
135+
All user-controlled text is sanitized before embedding in markdown/MDX output. `sanitizeMarkdownText` escapes HTML special characters and markdown link syntax. `sanitizeUrl` only allows `http:` and `https:` protocols, preventing `javascript:` and `data:` URI injection. Service IDs are sanitized to prevent path traversal. In API mode, the `baseUrl` is validated to require HTTPS, and debug logging redacts API tokens and email addresses.
68136

69137
## Found a problem?
70138

@@ -77,5 +145,3 @@ See [LICENSE](LICENSE).
77145
## Contributing
78146

79147
See the [CONTRIBUTING.md](CONTRIBUTING.md) file for more information.
80-
81-
[Atlassian Compass file]: https://developer.atlassian.com/cloud/compass/config-as-code/structure-and-contents-of-a-compass-yml-file/

‎examples/eventcatalog.config.js‎

Lines changed: 66 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -11,33 +11,90 @@ export default {
1111
homepageLink: 'https://eventcatalog.dev/',
1212
landingPage: '',
1313
editUrl: 'https://github.com/boyney123/eventcatalog-demo/edit/master',
14-
// By default set to false, add true to get urls ending in /
1514
trailingSlash: false,
16-
// Change to make the base url of the site different, by default https://{website}.com/docs,
17-
// changing to /company would be https://{website}.com/company/docs,
1815
base: '/',
19-
// Customize the logo, add your logo to public/ folder
2016
logo: {
2117
alt: 'EventCatalog Logo',
2218
src: '/logo.png',
2319
text: 'OurLogix',
2420
},
2521
docs: {
2622
sidebar: {
27-
// Should the sub heading be rendered in the docs sidebar?
2823
showPageHeadings: true,
2924
},
3025
},
3126
generators: [
27+
// ──────────────────────────────────────────────
28+
// YAML mode: read local compass.yml files
29+
// ──────────────────────────────────────────────
3230
[
33-
'@ismaelmartinez/generator-atlassian-compass',
31+
'@ismaelmartinez/generator-atlassian-compass-event-catalog',
3432
{
33+
// List of local compass.yml files to process
3534
services: [
36-
{ path: path.join(__dirname, 'src', 'test', 'my-service-compass.yml'), version: '0.0.1' },
37-
{ path: path.join(__dirname, 'src', 'test', 'my-other-compass.notsupported.yml') },
35+
{
36+
path: path.join(__dirname, 'src', 'test', 'my-service-compass.yml'),
37+
version: '0.0.1', // optional, defaults to '0.0.0'
38+
// id: 'custom-service-id', // optional, overrides name from YAML
39+
},
40+
{
41+
path: path.join(__dirname, 'src', 'test', 'my-application-compass.yml'),
42+
},
3843
],
39-
domain: { id: 'orders', name: 'Compass', version: '0.0.1' },
44+
45+
// Required: base URL for Compass component links
46+
compassUrl: 'https://mysite.atlassian.net/compass',
47+
48+
// Optional: group services under a domain (created if it doesn't exist)
49+
domain: { id: 'orders', name: 'Orders Domain', version: '0.0.1' },
50+
51+
// Optional: only process components of these types
52+
// typeFilter: ['SERVICE', 'APPLICATION'],
53+
54+
// Optional: skip updating services that already exist in the catalog
55+
// overrideExisting: false,
56+
57+
// Optional: output format — 'mdx' (default) or 'md'
58+
// format: 'md',
59+
60+
// Optional: how service IDs are derived — 'name' (default), 'compass-id', or a function
61+
// serviceIdStrategy: 'name',
62+
// serviceIdStrategy: (config) => `prefix-${config.name}`,
63+
64+
// Optional: custom markdown template for service pages
65+
// markdownTemplate: (config, dependencies) => {
66+
// const depList = dependencies.map(d => d.name).join(', ') || 'none';
67+
// return `# ${config.name}\n\nDepends on: ${depList}`;
68+
// },
69+
70+
// Optional: preview changes without writing files
71+
// dryRun: true,
72+
73+
// Optional: enable debug logging (credentials are redacted)
74+
// debug: true,
4075
},
4176
],
77+
78+
// ──────────────────────────────────────────────
79+
// API mode: fetch components from Compass GraphQL API
80+
// ──────────────────────────────────────────────
81+
// [
82+
// '@ismaelmartinez/generator-atlassian-compass-event-catalog',
83+
// {
84+
// api: {
85+
// cloudId: '$COMPASS_CLOUD_ID', // supports $ENV_VAR syntax
86+
// apiToken: '$COMPASS_API_TOKEN',
87+
// email: '$COMPASS_EMAIL',
88+
// baseUrl: 'https://mysite.atlassian.net', // must be HTTPS
89+
// typeFilter: ['SERVICE'], // optional server-side filtering
90+
// },
91+
//
92+
// compassUrl: 'https://mysite.atlassian.net/compass',
93+
//
94+
// // All the same options as YAML mode are available:
95+
// // domain, typeFilter, overrideExisting, format,
96+
// // serviceIdStrategy, markdownTemplate, dryRun, debug
97+
// },
98+
// ],
4299
],
43100
};

0 commit comments

Comments
 (0)