Skip to content

Commit 0448c3d

Browse files
LeighFinegoldLeighFinegold
authored
Merge pull request finos#1353 from LeighFinegold/OSFFLN-25
Adding better support for relationship in docify (finos#1352) + fixing bug (finos#1126)
2 parents 478af87 + 7be7743 commit 0448c3d

File tree

12 files changed

+365
-51
lines changed

12 files changed

+365
-51
lines changed

‎package-lock.json‎

Lines changed: 1 addition & 1 deletion
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎shared/src/docify/docifier.e2e.spec.ts‎

Lines changed: 12 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
1-
import { describe, it, expect, beforeEach, afterEach } from 'vitest';
1+
import { describe, it, expect, afterEach } from 'vitest';
22
import { Docifier } from './docifier.js';
3-
import { mkdirSync, rmSync, existsSync} from 'fs';
3+
import { rmSync, existsSync} from 'fs';
44
import { join } from 'path';
55

66
const INPUT_DIR = join(
@@ -13,16 +13,16 @@ const WORKSHOP_DIR = join(
1313
'../../../calm/workshop/controls'
1414
);
1515

16+
const CALM_DIR = join(
17+
__dirname,
18+
'../../../calm/release/1.0-rc1/meta'
19+
);
20+
1621
const OUTPUT_DIR = join(__dirname, '../../test_fixtures/docify/workshop/actual-output');
1722
const NON_SECURE_VERSION_DOC_WEBSITE = join(OUTPUT_DIR,'non-secure');
1823
const SECURE_VERSION_DOC_WEBSITE = join(OUTPUT_DIR,'secure');
1924

2025
describe('Docifier E2E - Real Model and Template', () => {
21-
beforeEach(() => {
22-
rmSync(OUTPUT_DIR, { recursive: true, force: true });
23-
mkdirSync(OUTPUT_DIR, { recursive: true });
24-
});
25-
2626
afterEach(() => {
2727
rmSync(OUTPUT_DIR, { recursive: true, force: true });
2828
});
@@ -45,13 +45,17 @@ describe('Docifier E2E - Real Model and Template', () => {
4545

4646
it('generates documentation from the conference-secure-signup.arch.json model', async () => {
4747
const mapping = new Map<string, string>([
48+
['https://calm.finos.org/release/1.0-rc1/meta/control-requirement.json', join(CALM_DIR, 'control-requirement.json')],
49+
['https://calm.finos.org/workshop/controls/micro-segmentation.config.json', join(WORKSHOP_DIR, 'micro-segmentation.config.json')],
50+
['https://calm.finos.org/workshop/controls/permitted-connection-http.config.json', join(WORKSHOP_DIR, 'permitted-connection-http.config.json')],
51+
['https://calm.finos.org/workshop/controls/permitted-connection-jdbc.config.json', join(WORKSHOP_DIR, 'permitted-connection-jdbc.config.json')],
4852
['https://calm.finos.org/workshop/controls/micro-segmentation.config.json', join(WORKSHOP_DIR, 'micro-segmentation.config.json')],
4953
['https://calm.finos.org/workshop/controls/micro-segmentation.requirement.json', join(WORKSHOP_DIR, 'micro-segmentation.requirement.json')],
5054
['https://calm.finos.org/workshop/controls/permitted-connection.requirement.json', join(WORKSHOP_DIR, 'permitted-connection.requirement.json')],
5155
]);
5256

5357

54-
const docifier = new Docifier('WEBSITE', join(INPUT_DIR, 'conference-signup.arch.json'), SECURE_VERSION_DOC_WEBSITE, mapping);
58+
const docifier = new Docifier('WEBSITE', join(INPUT_DIR, 'conference-secure-signup-amended.arch.json'), SECURE_VERSION_DOC_WEBSITE, mapping);
5559

5660
await docifier.docify();
5761

‎shared/src/docify/template-bundles/docusaurus/2025_CALM_Icon.svg‎

Lines changed: 19 additions & 0 deletions
Loading

‎shared/src/docify/template-bundles/docusaurus/docusaurus-transformer.ts‎

Lines changed: 26 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -11,46 +11,43 @@ export default class DocusaurusTransformer implements CalmTemplateTransformer {
1111
getTransformedModel(calmJson: string) {
1212
const calmSchema: CalmCoreSchema = JSON.parse(calmJson);
1313
const architecture: Architecture = CalmCore.fromJson(calmSchema);
14-
15-
const relationships = architecture.relationships;
1614
const graph = new CalmRelationshipGraph(architecture.relationships);
1715

1816
const nodes = architecture.nodes.map(node => ({
17+
...node,
1918
id: node.uniqueId,
2019
title: node.name,
21-
name: node.name,
22-
slug: node.uniqueId, // Generate slug
2320
description: node.description || 'No description available.',
2421
nodeType: node.nodeType || 'unknown',
25-
controls: node.controls,
26-
interfaces: node.interfaces,
27-
runAs: node.runAs,
28-
dataClassification: node.dataClassification,
2922
relatedRelationships: graph.getRelatedRelationships(node.uniqueId),
3023
relatedNodes: graph.getRelatedNodes(node.uniqueId)
3124
}));
3225

3326
const flows = architecture.flows.map(flow => {
3427
const transformedTransitions = flow.transitions.map((transition: CalmFlowTransition) => ({
28+
...transition,
3529
relationshipId: transition.relationshipUniqueId,
36-
sequenceNumber: transition.sequenceNumber,
37-
summary: transition.summary,
38-
direction: transition.direction,
3930
source: this.getSourceFromRelationship(transition.relationshipUniqueId),
4031
target: this.getTargetFromRelationship(transition.relationshipUniqueId)
4132
}));
4233

4334
return {
35+
...flow,
4436
title: flow.name,
4537
id: flow.uniqueId,
46-
slug: flow.uniqueId,
47-
name: flow.name,
48-
description: flow.description,
49-
transitions: transformedTransitions,
50-
controls: flow.controls
38+
transitions: transformedTransitions
5139
};
5240
});
5341

42+
const relationships = architecture.relationships.map(rel => ({
43+
...rel,
44+
id: rel.uniqueId,
45+
title: rel.uniqueId
46+
}));
47+
48+
const metadata = architecture.metadata;
49+
50+
5451
const controlRequirements: Record<string, { id:string, content:string, domain:string}[]> = {};
5552

5653
// eslint-disable-next-line @typescript-eslint/no-unused-vars
@@ -62,10 +59,9 @@ export default class DocusaurusTransformer implements CalmTemplateTransformer {
6259
if (!controlRequirements[id]) {
6360
controlRequirements[id] = [];
6461
controlRequirements[id].push({
65-
id: id,
62+
id,
6663
content: requirement,
6764
domain: control.controlId
68-
6965
});
7066
}
7167

@@ -75,18 +71,17 @@ export default class DocusaurusTransformer implements CalmTemplateTransformer {
7571

7672
const controlConfigurations: Record<string, { id:string, name:string, schema:string, description:string, domain: string, scope: string, appliedTo: string, content: string }[]> = {};
7773

78-
79-
// Collect control requirements and configurations from nodes, flows, and relationships
8074
const addControlConfigurationToTable = (controls: CalmControl[], scope: string, appliedTo: string) => {
8175
controls.forEach(control => {
8276
control.requirements.forEach( detail => {
8377
const configuration = detail.controlConfigUrl;
84-
if (configuration['control-id']) {
85-
if (!controlConfigurations[configuration['control-id']]) {
86-
controlConfigurations[configuration['control-id']] = [];
78+
const id = configuration['control-id'];
79+
if (id) {
80+
if (!controlConfigurations[id]) {
81+
controlConfigurations[id] = [];
8782
}
88-
controlConfigurations[configuration['control-id']].push({
89-
id: configuration['control-id'],
83+
controlConfigurations[id].push({
84+
id,
9085
name: configuration['name'],
9186
schema: configuration['$schema'],
9287
description: configuration['description'],
@@ -115,7 +110,6 @@ export default class DocusaurusTransformer implements CalmTemplateTransformer {
115110
addControlRequirementToTable(flow.controls, 'Flow', flow.uniqueId);
116111
});
117112

118-
119113
const groupedByDomainRequirements: Record<string, { id: string; content: string; domain: string }[]> = {};
120114

121115
Object.values(controlRequirements).forEach(requirements => {
@@ -127,7 +121,6 @@ export default class DocusaurusTransformer implements CalmTemplateTransformer {
127121
});
128122
});
129123

130-
131124
const groupedByDomainConfigurations: Record<string, { id:string, name:string, schema:string, description:string, domain: string, scope: string, appliedTo: string, content: string }[]> = {};
132125

133126
Object.values(controlConfigurations).forEach(controlConfigurations => {
@@ -139,8 +132,6 @@ export default class DocusaurusTransformer implements CalmTemplateTransformer {
139132
});
140133
});
141134

142-
143-
144135
const controls = Object.entries(controlConfigurations).flatMap(([id, configurations]) =>
145136
configurations.map(config => ({
146137
id,
@@ -155,14 +146,16 @@ export default class DocusaurusTransformer implements CalmTemplateTransformer {
155146
}))
156147
);
157148

158-
const C4model = new C4Model(architecture);
149+
const C4model = new C4Model(architecture);
159150

160151
return {
161152
nodes,
153+
relationships,
162154
flows,
163155
controls,
164156
controlReqs,
165157
C4model,
158+
metadata,
166159
docs: {
167160
nodes,
168161
flows,
@@ -172,7 +165,8 @@ export default class DocusaurusTransformer implements CalmTemplateTransformer {
172165
groupedByDomainRequirements,
173166
groupedByDomainConfigurations,
174167
C4model,
175-
controlConfigurations
168+
controlConfigurations,
169+
metadata
176170
}
177171
};
178172
}
@@ -208,14 +202,11 @@ export default class DocusaurusTransformer implements CalmTemplateTransformer {
208202
};
209203
}
210204

211-
212-
213-
214205
private getSourceFromRelationship(relationshipId: string): string {
215206
return relationshipId.split('-uses-')[0];
216207
}
217208

218209
private getTargetFromRelationship(relationshipId: string): string {
219210
return relationshipId.split('-uses-').slice(-1)[0];
220211
}
221-
}
212+
}

‎shared/src/docify/template-bundles/docusaurus/docusaurus.config.js‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,16 @@ module.exports = {
1212
organizationName: 'my-org',
1313
projectName: 'calm-docs',
1414

15+
themeConfig: {
16+
navbar: {
17+
title: 'CALM Documentation',
18+
logo: {
19+
alt: 'Calm Logo',
20+
src: 'img/2025_CALM_Icon.svg',
21+
},
22+
},
23+
},
24+
1525
themes: [
1626
'@docusaurus/theme-mermaid',
1727
],
@@ -44,4 +54,4 @@ module.exports = {
4454
},
4555
],
4656
],
47-
};
57+
};

‎shared/src/docify/template-bundles/docusaurus/index.json‎

Lines changed: 24 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,21 @@
1111
"controls.hbs",
1212
"relationships.hbs",
1313
"table-template.html",
14-
"row-template.html"
14+
"row-template.html",
15+
"metadata.hbs"
16+
]
17+
},
18+
{
19+
"template": "relationship.mdx.hbs",
20+
"from": "relationships",
21+
"output": "docs/relationships/{{id}}.md",
22+
"output-type": "repeated",
23+
"partials": [
24+
"controls.hbs",
25+
"relationships.hbs",
26+
"table-template.html",
27+
"row-template.html",
28+
"metadata.hbs"
1529
]
1630
},
1731
{
@@ -26,6 +40,12 @@
2640
"output": "docusaurus.config.js",
2741
"output-type": "single"
2842
},
43+
{
44+
"template": "2025_CALM_Icon.svg",
45+
"from": "docs",
46+
"output": "static/img/2025_CALM_Icon.svg",
47+
"output-type": "single"
48+
},
2949
{
3050
"template": "remark-replace-links.js",
3151
"from": "docs",
@@ -44,7 +64,9 @@
4464
"output": "docs/index.md",
4565
"output-type": "single",
4666
"partials": [
47-
"c4-container.hbs"
67+
"c4-container.hbs",
68+
"table-template.html",
69+
"metadata.hbs"
4870
]
4971
},
5072
{

‎shared/src/docify/template-bundles/docusaurus/index.md.hbs‎

Lines changed: 22 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -14,14 +14,22 @@ This documentation is generated from the **CALM Architecture-as-Code** model.
1414

1515
### Nodes
1616
{{#each nodes}}
17-
- [{{title}}](nodes/{{slug}})
17+
- [{{title}}](nodes/{{id}})
1818
{{/each}}
1919

20-
{{#if (notEmpty flows) }}
20+
### Relationships
21+
{{#each relationships}}
22+
- [{{kebabToTitleCase title}}](relationships/{{id}})
23+
{{/each}}
24+
25+
2126
### Flows
27+
{{#if (notEmpty flows) }}
2228
{{#each flows}}
23-
- [{{title}}](flows/{{slug}})
29+
- [{{title}}](flows/{{id}})
2430
{{/each}}
31+
{{else}}
32+
_No flows defined._
2533
{{/if}}
2634

2735
{{#if (notEmpty controls) }}
@@ -32,3 +40,14 @@ This documentation is generated from the **CALM Architecture-as-Code** model.
3240
|{{id}}|{{name}}|{{description}}|{{domain}}|{{scope}}|{{appliedTo}}|
3341
{{/controls}}
3442
{{/if}}
43+
44+
45+
### MetaData
46+
{{> metadata.hbs data=metadata.data}}
47+
48+
{{#if (notEmpty adrs)}}
49+
### Adrs
50+
{{#each adrs}}
51+
- [{{this}}]({{this}})
52+
{{/each}}
53+
{{/if}}

‎shared/src/docify/template-bundles/docusaurus/metadata.hbs‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
{{#if (notEmpty data)}}
2+
{{> table-template.html data=this.data}}
3+
{{else}}
4+
_No Metadata defined._
5+
{{/if}}

‎shared/src/docify/template-bundles/docusaurus/node.mdx.hbs‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,4 +31,7 @@ title: {{title}}
3131

3232
{{> relationships.hbs}}
3333

34-
{{> controls.hbs}}
34+
{{> controls.hbs}}
35+
36+
## MetaData
37+
{{> metadata.hbs data=metadata.data}}

0 commit comments

Comments
 (0)