Skip to content

Commit 4849b29

Browse files
authored
Merge pull request #6515 from ConductionNL/quality/build-method-decomposition-3
feat(dossiq): build method-decomposition
2 parents c6802b8 + b18506b commit 4849b29

11 files changed

Lines changed: 1116 additions & 546 deletions

‎lib/Service/CaseModelConverter.php‎

Lines changed: 327 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,327 @@
1+
<?php
2+
3+
/**
4+
* Convert a dossiq caseModel into an OpenRegister case-plan definition.
5+
*
6+
* @category Service
7+
* @package OCA\Dossiq\Service
8+
*
9+
* @author Conduction Development Team <info@conduction.nl>
10+
* @copyright 2026 Conduction B.V.
11+
* @license EUPL-1.2 https://joinup.ec.europa.eu/collection/eupl/eupl-text-eupl-12
12+
*
13+
* @version GIT: <git-id>
14+
*
15+
* @link https://conduction.nl
16+
*
17+
* SPDX-License-Identifier: EUPL-1.2
18+
* SPDX-FileCopyrightText: 2026 Conduction B.V. <info@conduction.nl>
19+
*
20+
* @spec openspec/changes/retire-cmmn-caseplanstate/specs/retire-cmmn-caseplanstate/spec.md#requirement-req-rcmn-001-case-semantics-are-consumed-from-openregister
21+
* @spec openspec/changes/method-decomposition/tasks.md
22+
*/
23+
24+
declare(strict_types=1);
25+
26+
namespace OCA\Dossiq\Service;
27+
28+
use UnexpectedValueException;
29+
30+
/**
31+
* The plan-item half of the caseModel conversion: pure, no I/O.
32+
*
33+
* The flat `planItems` list with `parentId` links becomes the nested `items`
34+
* tree OpenRegister validates; every criteria list goes through the
35+
* {@see SentryConverter}. Moved out of {@see CasePlanProjectionService}
36+
* unchanged (method-decomposition).
37+
*
38+
* @spec openspec/changes/retire-cmmn-caseplanstate/specs/retire-cmmn-caseplanstate/spec.md#requirement-req-rcmn-001-case-semantics-are-consumed-from-openregister
39+
*/
40+
final class CaseModelConverter {
41+
42+
/**
43+
* Constructor.
44+
*
45+
* @param SentryConverter $sentries Converts every entry and exit criterion.
46+
*
47+
* @spec openspec/changes/retire-cmmn-caseplanstate/specs/retire-cmmn-caseplanstate/spec.md#requirement-req-rcmn-001-case-semantics-are-consumed-from-openregister
48+
*/
49+
public function __construct(
50+
private readonly SentryConverter $sentries = new SentryConverter(),
51+
) {
52+
}//end __construct()
53+
54+
/**
55+
* Convert a whole `caseModel` into an OpenRegister case-plan definition.
56+
*
57+
* Pure: no I/O, no container. The flat `planItems` list with `parentId`
58+
* links becomes the nested `items` tree OpenRegister validates, and every
59+
* sentry is converted through the closed table.
60+
*
61+
* @param array<string, mixed> $caseModel The published caseModel object.
62+
*
63+
* @return array{settings: array<string, mixed>, items: array<int, array<string, mixed>>} The definition.
64+
*
65+
* @throws UnexpectedValueException Naming the construct it refuses to convert.
66+
*
67+
* @spec openspec/changes/retire-cmmn-caseplanstate/specs/retire-cmmn-caseplanstate/spec.md#requirement-req-rcmn-001-case-semantics-are-consumed-from-openregister
68+
*/
69+
public function convertModel(array $caseModel): array {
70+
$planItems = ($caseModel['planItems'] ?? []);
71+
if (is_array($planItems) === false) {
72+
throw new UnexpectedValueException('caseModel.planItems must be a list of plan items.');
73+
}
74+
75+
$byId = $this->indexPlanItems(planItems: $planItems);
76+
$order = array_map(static fn ($id): string => (string)$id, array_keys($byId));
77+
78+
$this->assertParentsResolve(byId: $byId);
79+
$items = $this->convertRootItems(byId: $byId, order: $order);
80+
81+
return ['settings' => $this->convertSettings(caseModel: $caseModel), 'items' => $items];
82+
}//end convertModel()
83+
84+
/**
85+
* Convert every plan item without a parent, each with its subtree, in declared order.
86+
*
87+
* @param array<string, array<string, mixed>> $byId The plan items by id.
88+
* @param array<int, string> $order The ids in declared order.
89+
*
90+
* @return array<int, array<string, mixed>> The top-level nodes.
91+
*/
92+
private function convertRootItems(array $byId, array $order): array {
93+
$index = new PlanItemIndex(byId: $byId, order: $order);
94+
$items = [];
95+
foreach ($order as $id) {
96+
if (trim((string)($byId[$id]['parentId'] ?? '')) === '') {
97+
$items[] = $this->convertItem(item: $byId[$id], index: $index, seen: []);
98+
}
99+
}
100+
101+
return $items;
102+
}//end convertRootItems()
103+
104+
/**
105+
* Index the plan items by their trimmed id, in declared order.
106+
*
107+
* @param array<int|string, mixed> $planItems The declared plan items.
108+
*
109+
* @return array<string, array<string, mixed>> The items by id.
110+
*
111+
* @throws UnexpectedValueException Naming the entry without an object, without an id, or with a repeated id.
112+
*/
113+
private function indexPlanItems(array $planItems): array {
114+
$byId = [];
115+
foreach ($planItems as $index => $item) {
116+
$id = $this->planItemId(item: $item, index: (int)$index);
117+
if (isset($byId[$id]) === true) {
118+
throw new UnexpectedValueException(sprintf("caseModel repeats plan-item id '%s'; ids are unique within a model.", $id));
119+
}
120+
121+
$byId[$id] = $item;
122+
}
123+
124+
return $byId;
125+
}//end indexPlanItems()
126+
127+
/**
128+
* The trimmed id of one declared plan item.
129+
*
130+
* @param mixed $item The declared entry.
131+
* @param int $index Its position, for the refusal message.
132+
*
133+
* @return string The id.
134+
*
135+
* @throws UnexpectedValueException When the entry is not an object or has no id.
136+
*/
137+
private function planItemId(mixed $item, int $index): string {
138+
if (is_array($item) === false) {
139+
throw new UnexpectedValueException(sprintf('caseModel.planItems[%d] must be an object.', $index));
140+
}
141+
142+
$id = trim((string)($item['id'] ?? ''));
143+
if ($id === '') {
144+
throw new UnexpectedValueException(sprintf('caseModel.planItems[%d] has no id.', $index));
145+
}
146+
147+
return $id;
148+
}//end planItemId()
149+
150+
/**
151+
* Convert one plan item and, for a stage, its children.
152+
*
153+
* @param array<string, mixed> $item The dossiq plan item.
154+
* @param PlanItemIndex $index Every plan item, keyed by id, and the declared order of ids.
155+
* @param array<string, boolean> $seen Ancestor ids, to catch a parent cycle.
156+
*
157+
* @return array<string, mixed> The OpenRegister node.
158+
*
159+
* @throws UnexpectedValueException Naming the item it refuses.
160+
*/
161+
private function convertItem(array $item, PlanItemIndex $index, array $seen): array {
162+
$id = trim((string)($item['id'] ?? ''));
163+
if (isset($seen[$id]) === true) {
164+
throw new UnexpectedValueException(sprintf("caseModel plan item '%s' is its own ancestor.", $id));
165+
}
166+
167+
$seen[$id] = true;
168+
$node = $this->nodeFor(item: $item, id: $id);
169+
if ($node['type'] !== 'stage') {
170+
return $node;
171+
}
172+
173+
$node['children'] = $this->childrenOf(id: $id, index: $index, seen: $seen);
174+
175+
return $node;
176+
}//end convertItem()
177+
178+
/**
179+
* Build the OpenRegister node for one plan item, children aside.
180+
*
181+
* @param array<string, mixed> $item The dossiq plan item.
182+
* @param string $id Its id.
183+
*
184+
* @return array<string, mixed> The node.
185+
*
186+
* @throws UnexpectedValueException Naming the item it refuses.
187+
*/
188+
private function nodeFor(array $item, string $id): array {
189+
$type = $this->convertibleType(item: $item, id: $id);
190+
$discretionary = (($item['discretionary'] ?? false) === true);
191+
192+
$node = [
193+
'key' => $id,
194+
'type' => $type,
195+
'name' => (string)($item['name'] ?? $id),
196+
// The mandatory/discretionary split IS OpenRegister's `required`:
197+
// a stage waits for every non-discretionary direct child, and
198+
// OpenRegister's CasePlanTree waits for every required one.
199+
'required' => ($discretionary === false),
200+
'discretionary' => $discretionary,
201+
'entryCriteria' => $this->sentries->convertCriteria(criteria: ($item['entryCriteria'] ?? []), where: sprintf("plan item '%s' entry", $id)),
202+
'exitCriteria' => $this->sentries->convertCriteria(criteria: ($item['exitCriteria'] ?? []), where: sprintf("plan item '%s' exit", $id)),
203+
];
204+
205+
return array_merge($node, $this->optionalNodeFields(item: $item));
206+
}//end nodeFor()
207+
208+
/**
209+
* The type of a plan item, refused when the case layer cannot hold it.
210+
*
211+
* @param array<string, mixed> $item The dossiq plan item.
212+
* @param string $id Its id.
213+
*
214+
* @return string The type: stage, humanTask or milestone.
215+
*
216+
* @throws UnexpectedValueException For an unknown type or a discretionary milestone.
217+
*/
218+
private function convertibleType(array $item, string $id): string {
219+
$type = (string)($item['type'] ?? '');
220+
if (in_array($type, ['stage', 'humanTask', 'milestone'], true) === false) {
221+
throw new UnexpectedValueException(
222+
sprintf("caseModel plan item '%s' has type '%s'; expected stage, humanTask or milestone.", $id, $type)
223+
);
224+
}
225+
226+
if ($type === 'milestone' && ($item['discretionary'] ?? false) === true) {
227+
throw new UnexpectedValueException(
228+
sprintf("caseModel plan item '%s' is a discretionary milestone, which the case layer refuses: a milestone is never enabled.", $id)
229+
);
230+
}
231+
232+
return $type;
233+
}//end convertibleType()
234+
235+
/**
236+
* The description and authorization of a node, each only when the plan item sets it.
237+
*
238+
* @param array<string, mixed> $item The dossiq plan item.
239+
*
240+
* @return array<string, mixed> `{description?, authorization?}`.
241+
*/
242+
private function optionalNodeFields(array $item): array {
243+
$fields = [];
244+
$description = trim((string)($item['description'] ?? ''));
245+
if ($description !== '') {
246+
$fields['description'] = $description;
247+
}
248+
249+
$authorization = ($item['authorization'] ?? []);
250+
if (is_array($authorization) === true && $authorization !== []) {
251+
$fields['authorization'] = array_values(array_map(static fn ($rule): string => (string)$rule, $authorization));
252+
}
253+
254+
return $fields;
255+
}//end optionalNodeFields()
256+
257+
/**
258+
* Convert the direct children of a stage, in declared order.
259+
*
260+
* @param string $id The stage's id.
261+
* @param PlanItemIndex $index Every plan item, keyed by id, and the declared order of ids.
262+
* @param array<string, boolean> $seen Ancestor ids, to catch a parent cycle.
263+
*
264+
* @return array<int, array<string, mixed>> The child nodes.
265+
*
266+
* @throws UnexpectedValueException Naming the child it refuses.
267+
*/
268+
private function childrenOf(string $id, PlanItemIndex $index, array $seen): array {
269+
$byId = $index->byId;
270+
$children = [];
271+
foreach ($index->order as $childId) {
272+
if (trim((string)($byId[$childId]['parentId'] ?? '')) === $id) {
273+
$children[] = $this->convertItem(item: $byId[$childId], index: $index, seen: $seen);
274+
}
275+
}
276+
277+
return $children;
278+
}//end childrenOf()
279+
280+
/**
281+
* Build the definition's `settings` block.
282+
*
283+
* @param array<string, mixed> $caseModel The caseModel object.
284+
*
285+
* @return array<string, mixed> The settings.
286+
*/
287+
private function convertSettings(array $caseModel): array {
288+
$settings = [];
289+
$title = trim((string)($caseModel['title'] ?? ''));
290+
if ($title !== '') {
291+
$settings['name'] = $title;
292+
}
293+
294+
return $settings;
295+
}//end convertSettings()
296+
297+
/**
298+
* Refuse a `parentId` that names an item the model does not declare.
299+
*
300+
* A dangling parent would otherwise drop the child out of the tree
301+
* silently: it is neither a root (it has a parentId) nor anybody's child.
302+
*
303+
* @param array<string, array<string, mixed>> $byId Every plan item, keyed by id.
304+
*
305+
* @return void
306+
*
307+
* @throws UnexpectedValueException Naming the dangling parent.
308+
*/
309+
private function assertParentsResolve(array $byId): void {
310+
foreach ($byId as $id => $item) {
311+
$parentId = trim((string)($item['parentId'] ?? ''));
312+
if ($parentId === '') {
313+
continue;
314+
}
315+
316+
if (isset($byId[$parentId]) === false) {
317+
throw new UnexpectedValueException(sprintf("caseModel plan item '%s' names parent '%s', which the model does not declare.", $id, $parentId));
318+
}
319+
320+
if ((string)($byId[$parentId]['type'] ?? '') !== 'stage') {
321+
throw new UnexpectedValueException(
322+
sprintf("caseModel plan item '%s' names parent '%s', which is not a stage; only a stage nests.", $id, $parentId)
323+
);
324+
}
325+
}
326+
}//end assertParentsResolve()
327+
}//end class

0 commit comments

Comments
 (0)