libmodulor 0.3.0 → 0.5.0

package/dist/esm/target/react-native-pure/UCForm.d.ts

@@ -0,0 +1,4 @@
+import { type ReactElement } from 'react';
+import type { UCInput, UCOPIBase } from '../../uc/index.js';
+import type { UCFormProps } from '../lib/react/form.js';
+export declare function UCForm<I extends UCInput | undefined = undefined, OPI0 extends UCOPIBase | undefined = undefined, OPI1 extends UCOPIBase | undefined = undefined>({ disabled, execState, onChange, onSubmit, uc, }: UCFormProps<I, OPI0, OPI1>): ReactElement;

package/dist/esm/target/react-native-pure/UCForm.js

@@ -0,0 +1,13 @@
+import React, {} from 'react';
+import { View } from 'react-native';
+import { UCFormField } from './UCFormField.js';
+import { UCFormSubmitControl, } from './UCFormSubmitControl.js';
+export function UCForm({ disabled, execState, onChange, onSubmit, uc, }) {
+    const onPress = async () => {
+        await onSubmit();
+    };
+    return (React.createElement(View, null,
+        uc.inputFieldsForForm().map((f) => (React.createElement(View, { key: f.key },
+            React.createElement(UCFormField, { disabled: disabled, execState: execState, field: f, onChange: onChange })))),
+        React.createElement(UCFormSubmitControl, { execState: execState, disabled: disabled, onPress: onPress, uc: uc })));
+}

package/dist/esm/target/react-native-pure/UCFormField.d.ts

@@ -0,0 +1,11 @@
+import { type ReactElement } from 'react';
+import type { DataType } from '../../dt/index.js';
+import { type Props as FormFieldControlProps } from './UCFormFieldControl.js';
+import { type Props as FormFieldLabelProps } from './UCFormFieldLabel.js';
+declare const ELEMENTS: readonly ["control", "desc", "err", "label"];
+type Element = (typeof ELEMENTS)[number];
+type Props<T extends DataType> = FormFieldControlProps<T> & FormFieldLabelProps<T> & {
+    only?: Element[];
+};
+export declare function UCFormField<T extends DataType>({ disabled, execState, field, onChange: onChangeBase, only, }: Props<T>): ReactElement;
+export {};

package/dist/esm/target/react-native-pure/UCFormField.js

@@ -0,0 +1,32 @@
+import React, { useState } from 'react';
+import { useDIContext } from '../lib/react/DIContextProvider.js';
+import { UCFormFieldControl, } from './UCFormFieldControl.js';
+import { UCFormFieldDesc } from './UCFormFieldDesc.js';
+import { UCFormFieldErr } from './UCFormFieldErr.js';
+import { UCFormFieldLabel, } from './UCFormFieldLabel.js';
+const ELEMENTS = ['control', 'desc', 'err', 'label'];
+export function UCFormField({ disabled, execState, field, onChange: onChangeBase, only, }) {
+    const { i18nManager } = useDIContext();
+    const { type } = field.def;
+    const [errMsg, setErrMsg] = useState(null);
+    const elements = only ?? ELEMENTS;
+    const onChange = (f, op, v) => {
+        setErrMsg(null);
+        const vArr = Array.isArray(v) ? v : [v];
+        for (const vv of vArr) {
+            const validation = type.assign(vv).validate();
+            const violation = validation.get();
+            if (violation) {
+                const [key, expected] = violation;
+                setErrMsg(i18nManager.t(key, { vars: { expected } }));
+                break;
+            }
+        }
+        onChangeBase(f, op, v);
+    };
+    return (React.createElement(React.Fragment, null,
+        elements.includes('label') && React.createElement(UCFormFieldLabel, { field: field }),
+        elements.includes('control') && (React.createElement(UCFormFieldControl, { disabled: disabled, execState: execState, field: field, onChange: onChange })),
+        elements.includes('err') && errMsg && (React.createElement(UCFormFieldErr, { errMsg: errMsg })),
+        elements.includes('desc') && React.createElement(UCFormFieldDesc, { field: field })));
+}

package/dist/esm/target/react-native-pure/UCFormFieldControl.d.ts

@@ -0,0 +1,11 @@
+import { type ReactElement } from 'react';
+import type { DataType, ErrorMessage } from '../../dt/index.js';
+import { type UCInputField } from '../../uc/index.js';
+import type { UCFormFieldControlOnChange } from '../lib/react/form.js';
+import type { UCPanelState } from '../lib/react/panel.js';
+export type Props<T extends DataType> = UCPanelState & {
+    errMsg?: ErrorMessage | null;
+    field: UCInputField<T>;
+    onChange: UCFormFieldControlOnChange<T>;
+};
+export declare function UCFormFieldControl<T extends DataType>({ errMsg, execState, field, onChange: onChangeBase, }: Props<T>): ReactElement;

package/dist/esm/target/react-native-pure/UCFormFieldControl.js

@@ -0,0 +1,37 @@
+import React, { useEffect, useState } from 'react';
+import { TextInput } from 'react-native';
+import { UCInputFieldChangeOperator, ucifRepeatability, } from '../../uc/index.js';
+import { isBlank } from '../../utils/index.js';
+import { rnInputDef } from '../lib/rn/input.js';
+const MULTIPLE_VALUES_SEPARATOR = ',';
+export function UCFormFieldControl({ errMsg = null, execState, field, onChange: onChangeBase, }) {
+    const [internalValue, setInternalValue] = useState(field.getValue());
+    // biome-ignore lint/correctness/useExhaustiveDependencies: false positive : It is actually necessary (only `field` does not trigger the effect)
+    useEffect(() => {
+        setInternalValue(field.getValue());
+    }, [field.getValue()]);
+    const attrs = rnInputDef(field, execState, errMsg);
+    const onChangeText = (value) => {
+        const [isRepeatable] = ucifRepeatability(field.def);
+        if (isRepeatable && typeof value === 'string') {
+            const valueArr = value
+                .split(MULTIPLE_VALUES_SEPARATOR)
+                .map((v) => v.trim());
+            onChangeBase(field, UCInputFieldChangeOperator.SET, valueArr);
+        }
+        else {
+            onChangeBase(field, UCInputFieldChangeOperator.SET, value);
+        }
+        setInternalValue(value);
+    };
+    let valueAsString = '';
+    if (!isBlank(internalValue)) {
+        if (Array.isArray(internalValue)) {
+            valueAsString = internalValue.join(MULTIPLE_VALUES_SEPARATOR);
+        }
+        else {
+            valueAsString = internalValue.toString();
+        }
+    }
+    return (React.createElement(TextInput, { ...attrs.spec, onChangeText: onChangeText, value: valueAsString }));
+}

package/dist/esm/target/react-native-pure/UCFormFieldDesc.d.ts

@@ -0,0 +1,7 @@
+import { type ReactElement } from 'react';
+import type { DataType } from '../../dt/index.js';
+import type { UCInputField } from '../../uc/index.js';
+export interface Props<T extends DataType> {
+    field: UCInputField<T>;
+}
+export declare function UCFormFieldDesc<T extends DataType>({ field, }: Props<T>): ReactElement | null;

package/dist/esm/target/react-native-pure/UCFormFieldDesc.js

@@ -0,0 +1,11 @@
+import React, {} from 'react';
+import { Text } from 'react-native';
+import { useDIContext } from '../lib/react/DIContextProvider.js';
+export function UCFormFieldDesc({ field, }) {
+    const { wordingManager } = useDIContext();
+    const { desc } = wordingManager.ucif(field);
+    if (!desc) {
+        return null;
+    }
+    return React.createElement(Text, null, desc);
+}

package/dist/esm/target/react-native-pure/UCFormFieldErr.d.ts

@@ -0,0 +1,7 @@
+import { type ReactElement } from 'react';
+import type { ErrorMessage } from '../../dt/index.js';
+interface Props {
+    errMsg: ErrorMessage;
+}
+export declare function UCFormFieldErr({ errMsg }: Props): ReactElement;
+export {};

package/dist/esm/target/react-native-pure/UCFormFieldErr.js

@@ -0,0 +1,5 @@
+import React, {} from 'react';
+import { Text } from 'react-native';
+export function UCFormFieldErr({ errMsg }) {
+    return React.createElement(Text, null, errMsg);
+}

package/dist/esm/target/react-native-pure/UCFormFieldLabel.d.ts

@@ -0,0 +1,7 @@
+import { type ReactElement } from 'react';
+import type { DataType } from '../../dt/index.js';
+import type { UCInputField } from '../../uc/index.js';
+export interface Props<T extends DataType> {
+    field: UCInputField<T>;
+}
+export declare function UCFormFieldLabel<T extends DataType>({ field, }: Props<T>): ReactElement;

package/dist/esm/target/react-native-pure/UCFormFieldLabel.js

@@ -0,0 +1,8 @@
+import React, {} from 'react';
+import { Text } from 'react-native';
+import { useDIContext } from '../lib/react/DIContextProvider.js';
+export function UCFormFieldLabel({ field, }) {
+    const { wordingManager } = useDIContext();
+    const { label } = wordingManager.ucif(field);
+    return React.createElement(Text, null, label);
+}

package/dist/esm/target/react-native-pure/UCFormSubmitControl.d.ts

@@ -0,0 +1,9 @@
+import { type ReactElement } from 'react';
+import type { UCInput, UCOPIBase } from '../../uc/index.js';
+import type { UCPanelCtx } from '../lib/react/panel.js';
+export type UCFormSubmitOnPress = () => Promise<void>;
+type Props<I extends UCInput | undefined = undefined, OPI0 extends UCOPIBase | undefined = undefined, OPI1 extends UCOPIBase | undefined = undefined> = UCPanelCtx<I, OPI0, OPI1> & {
+    onPress?: UCFormSubmitOnPress;
+};
+export declare function UCFormSubmitControl<I extends UCInput | undefined = undefined, OPI0 extends UCOPIBase | undefined = undefined, OPI1 extends UCOPIBase | undefined = undefined>({ execState, disabled, onPress, uc }: Props<I, OPI0, OPI1>): ReactElement;
+export {};

package/dist/esm/target/react-native-pure/UCFormSubmitControl.js

@@ -0,0 +1,8 @@
+import React, {} from 'react';
+import { Pressable, Text } from 'react-native';
+import { useDIContext } from '../lib/react/DIContextProvider.js';
+export function UCFormSubmitControl({ execState, disabled, onPress, uc }) {
+    const { wordingManager } = useDIContext();
+    return (React.createElement(Pressable, { onPress: onPress, disabled: disabled },
+        React.createElement(Text, null, wordingManager.ucISubmit(uc.def, execState))));
+}

package/dist/esm/target/react-web-pure/UCEntrypointTouchable.d.ts

@@ -1,4 +1,4 @@
 import { type ReactElement } from 'react';
-import type { UCEntrypointTouchableProps } from '../../index.react.js';
 import type { UCInput, UCOPIBase } from '../../uc/index.js';
+import type { UCEntrypointTouchableProps } from '../lib/react/touchable.js';
 export declare function UCEntrypointTouchable<I extends UCInput | undefined = undefined, OPI0 extends UCOPIBase | undefined = undefined, OPI1 extends UCOPIBase | undefined = undefined>({ path, wording }: UCEntrypointTouchableProps<I, OPI0, OPI1>): ReactElement;

package/dist/esm/target/react-web-pure/UCExecTouchable.d.ts

@@ -1,4 +1,4 @@
 import { type ReactElement } from 'react';
-import { type UCExecTouchableProps } from '../../index.react.js';
 import type { UCInput, UCOPIBase } from '../../uc/index.js';
+import type { UCExecTouchableProps } from '../lib/react/touchable.js';
 export declare function UCExecTouchable<I extends UCInput | undefined = undefined, OPI0 extends UCOPIBase | undefined = undefined, OPI1 extends UCOPIBase | undefined = undefined>({ disabled, execState, onSubmit, uc, }: UCExecTouchableProps<I, OPI0, OPI1>): ReactElement;

package/dist/esm/target/react-web-pure/UCExecTouchable.js

@@ -1,5 +1,5 @@
 import React, {} from 'react';
-import { useDIContext } from '../../index.react.js';
+import { useDIContext } from '../lib/react/DIContextProvider.js';
 export function UCExecTouchable({ disabled, execState, onSubmit, uc, }) {
     const { wordingManager } = useDIContext();
     const label = wordingManager.ucISubmit(uc.def, execState);

package/dist/esm/target/react-web-pure/UCFormFieldControl.d.ts

@@ -8,4 +8,4 @@ export type Props<T extends DataType> = UCPanelState & {
     field: UCInputField<T>;
     onChange: UCFormFieldControlOnChange<T>;
 };
-export declare function UCFormFieldControl<T extends DataType>({ disabled, errMsg, execState, field, onChange: onChangeBase, }: Props<T>): ReactElement;
+export declare function UCFormFieldControl<T extends DataType>({ errMsg, execState, field, onChange: onChangeBase, }: Props<T>): ReactElement;

package/dist/esm/target/react-web-pure/UCFormFieldControl.js

@@ -4,7 +4,7 @@ import { htmlInputDef } from '../lib/web/input.js';
 const CHECKED_FIELD_TYPES = ['checkbox', 'radio'];
 const FILE_FIELD_TYPES = ['file'];
 const MULTIPLE_VALUES_SEPARATOR = ',';
-export function UCFormFieldControl({ disabled, errMsg = null, execState, field, onChange: onChangeBase, }) {
+export function UCFormFieldControl({ errMsg = null, execState, field, onChange: onChangeBase, }) {
     const attrs = htmlInputDef(field, execState, errMsg);
     const onChange = (e) => {
         const target = e.currentTarget;
@@ -28,7 +28,7 @@ export function UCFormFieldControl({ disabled, errMsg = null, execState, field,
         }
     };
     if (attrs.internal?.multiline) {
-        return (React.createElement("textarea", { ...attrs.spec, disabled: disabled, onChange: onChange }));
+        return React.createElement("textarea", { ...attrs.spec, onChange: onChange });
     }
-    return React.createElement("input", { ...attrs.spec, disabled: disabled, onChange: onChange });
+    return React.createElement("input", { ...attrs.spec, onChange: onChange });
 }

package/dist/esm/testing/AppTester.d.ts

@@ -43,6 +43,10 @@ export declare class AppTester {
     private ucExecutor;
     private configurator;
     private ctx;
+    /**
+     * We use a "safe" one to avoid any "infinite loop" while trying to import/resolve a file.
+     * This can happen in case of circular dependencies for example.
+     */
     private safeSrcImporter;
     private testResults;
     private testSummary;

package/dist/esm/testing/AppTester.js

@@ -14,6 +14,8 @@ import { inject, injectable } from 'inversify';
 import { I18nEN } from '../i18n/locales/en.js';
 import { I18nFR } from '../i18n/locales/fr.js';
 import { FAKE_USER_ADMIN, UCBuilder, UCInputFieldChangeOperator, ucHTTPContract, } from '../uc/index.js';
+// We inject directly the implementation because we'll generate all the reports and not only the one that is bound to the interface.
+// We can plan a setting à la Vitest where we specify the types of reports to generate though.
 import { SimpleHTMLAppTestReportEmitter } from './impl/SimpleHTMLAppTestReportEmitter.js';
 import { optsAllSet } from './opts.js';
 import { defaultUCAuthSetters } from './uc-auth.js';
@@ -40,7 +42,12 @@ let AppTester = class AppTester {
     ucExecutor;
     configurator;
     ctx;
+    /**
+     * We use a "safe" one to avoid any "infinite loop" while trying to import/resolve a file.
+     * This can happen in case of circular dependencies for example.
+     */
     safeSrcImporter;
+    // biome-ignore lint/suspicious/noExplicitAny: can be anything
     testResults;
     testSummary;
     ucDefSourcesCheckerOutput;
@@ -134,7 +141,9 @@ let AppTester = class AppTester {
         const inputFiller = (uc) => {
             uc.fill(input);
         };
+        // biome-ignore lint/suspicious/noExplicitAny: can be anything
         const { out } = await this.execUC({
+            // TODO : Pass the appropriate one so we test the real flow and not the auth
             auth: FAKE_USER_ADMIN,
             authName: 'ADMIN',
             inputFiller,
@@ -148,6 +157,7 @@ let AppTester = class AppTester {
             ...input,
             appManifest: this.ctx.appManifest,
         });
+        // TODO : Add errors mapping to configurator so the developer can override this default behavior
         let status = 'warning';
         if (!out.err) {
             status = 'success';
@@ -169,6 +179,9 @@ let AppTester = class AppTester {
         let sideEffects = await this.configurator.sideEffects(this.ctx);
         if (flow) {
             name = `${flow.name} > ${name}`;
+            // For regular uc tests, side effects are cleared between each execution
+            // But it's not the case for a flow, thus each flow uc test shares the same side effects ref
+            // To have the side effects at each stage, we take a snapshot (to be improved as this is not performant at all)
             if (sideEffects) {
                 const snapshot = JSON.parse(JSON.stringify(Array.from(sideEffects.entries())));
                 sideEffects = new Map(snapshot);
@@ -205,6 +218,7 @@ let AppTester = class AppTester {
     async init({ appPath, configurator, serverClientSettings, srcImporter, }) {
         this.configurator = configurator;
         this.safeSrcImporter = (path) => Promise.race([
+            // We can cast because it fails or looses the race.
             awaitForSrcImport(path),
             srcImporter(path),
         ]);
@@ -222,6 +236,7 @@ let AppTester = class AppTester {
         await this.initServer();
     }
     async ucTestData(ucdRef) {
+        // Auth setters
         const defaultASs = defaultUCAuthSetters();
         let asEntries = Object.entries(defaultASs);
         const asConfig = await this.configurator.authSettersConfig();
@@ -236,6 +251,7 @@ let AppTester = class AppTester {
                 asEntries.push(...Object.entries(add));
             }
         }
+        // Input fillers
         const defaultIFs = defaultUCInputFillers();
         const ifEntries = Object.entries(defaultIFs);
         const specificIFs = await this.configurator.inputFillers();

package/dist/esm/testing/AppTesterConfigurator.d.ts

@@ -6,21 +6,89 @@ import type { DefaultUCAuthSetter, UCAuthSetterSet } from './uc-auth.js';
 import type { CustomUCInputFiller, UCInputFillerSet } from './uc-input.js';
 import type { UCExecutorAssertion } from './workers/UCExecutor.js';
 export type AppTesterConfiguratorAuthSettersConfig = {
+    /**
+     * Specific auth setters to add to the default ones
+     */
     add?: UCAuthSetterSet;
+    /**
+     * Default auth setters to exclude
+     *
+     * For instance, if your app does not care about auth (e.g. only client side app), you can safely exclude everything except {@link ANONYMOUS}
+     */
     exclude?: Set<DefaultUCAuthSetter>;
 };
 export type AppTesterConfiguratorInputFillers<I extends UCInput = any, OPI0 extends UCOPIBase = any, OPI1 extends UCOPIBase = any> = Map<UCName, UCInputFillerSet<CustomUCInputFiller, I, OPI0, OPI1>>;
 export type AppTesterConfiguratorSideEffects = Map<string, any>;
 export type AppTesterConfiguratorSideEffectsSerialized = [string, any][];
 export type AppTesterConfiguratorSpecificAssertions<I extends UCInput | undefined = undefined, OPI0 extends UCOPIBase | undefined = undefined, OPI1 extends UCOPIBase | undefined = undefined> = Map<CryptoManagerHash, UCExecutorAssertion<I, OPI0, OPI1>>;
+/**
+ * Configure the tester for a specific app
+ *
+ * @defaultValue See {@link SimpleAppTesterConfigurator}
+ */
 export interface AppTesterConfigurator {
+    /**
+     * Auth setters config to add some or exclude default ones
+     */
     authSettersConfig(): Promise<AppTesterConfiguratorAuthSettersConfig | undefined>;
+    /**
+     * Override the implementations needed by the use cases, in `ctx.container`
+     *
+     * @param ctx
+     */
     bindImplementations(ctx: AppTesterCtx): Promise<void>;
+    /**
+     * Clear what needs to be cleared after a use case execution
+     *
+     * For instance, this includes the data store, some fake queue processor checked in side effects, etc.
+     *
+     * @param ctx
+     */
     clearExecution(ctx: AppTesterCtx): Promise<void>;
+    /**
+     * Define specific flows to test multiple use cases sequentially
+     *
+     * For example : SignUp > SignIn > SignOut > ResetPassword, etc.
+     */
     flows(): Promise<AppTesterFlow[]>;
+    /**
+     * Define specific input fillers, per use case, in addition to the default ones
+     *
+     * @see defaultInputFillers
+     */
     inputFillers(): Promise<AppTesterConfiguratorInputFillers | undefined>;
+    /**
+     * Override the `ctx.opts()`, in case the app has some specificities
+     */
     opts(): Promise<AppTesterCtx['opts']>;
+    /**
+     * Seed some data in any data store needed by the use cases
+     *
+     * @param ctx
+     */
     seed(ctx: AppTesterCtx): Promise<void>;
+    /**
+     * Register the side effects that need to be tracked
+     *
+     * For instance, this is where you register {@link FakeEmailManager.entries} to check the emails sent by use cases.
+     *
+     * Or it can also be the entries of some fake job processor to check the jobs dispatched by use cases.
+     *
+     * Note that it works only if there are no `specificAssertions` for the given use case.
+     *
+     * Otherwise, you need to assert side effects manually.
+     *
+     * @param ctx
+     */
     sideEffects(ctx: AppTesterCtx): Promise<AppTesterConfiguratorSideEffects | undefined>;
+    /**
+     * Define specific assertions for a specific use case
+     *
+     * Otherwise, it matches the snapshot.
+     *
+     * For instance, you can use this if a specific use case performs some random processing (e.g. generating random data).
+     *
+     * Generally speaking, it's always better to have deterministic tests, so it's usually better to bind deterministic implementations in the tests.
+     */
     specificAssertions(): Promise<AppTesterConfiguratorSpecificAssertions | undefined>;
 }

package/dist/esm/testing/UCDataStoreTester.d.ts

@@ -3,6 +3,15 @@ import { type UCDataStore } from '../uc/index.js';
 interface Input {
     ucDataStore: UCDataStore;
 }
+/**
+ * Test that a {@link UCDataStore} conforms to the spec
+ *
+ * By default it runs tests on the projection mechanism.
+ * Therefore, you need to create one in your implementation when creating your test suite.
+ * See `src/uc/impl/KnexUCDataStore.test.ts` for an example.
+ *
+ * Otherwise you can just `skipProjectionTesting`, although it's not recommended.
+ */
 export declare class UCDataStoreTester implements Worker<Input, Promise<void>> {
     private clockManager;
     private cryptoManager;

package/dist/esm/testing/UCDataStoreTester.js

@@ -18,6 +18,15 @@ import { UCExecMode, } from '../uc/index.js';
 const ERR_SHOULD_NOT_EXIST_AFTER_DESTROY = 'It should not exist after destroy';
 const ERR_SHOULD_EXIST_AFTER_INSTALL = 'It should exist after install';
 const ERR_SHOULD_RETURN_X_RECORDS = (n) => `It should return ${n} record(s)`;
+/**
+ * Test that a {@link UCDataStore} conforms to the spec
+ *
+ * By default it runs tests on the projection mechanism.
+ * Therefore, you need to create one in your implementation when creating your test suite.
+ * See `src/uc/impl/KnexUCDataStore.test.ts` for an example.
+ *
+ * Otherwise you can just `skipProjectionTesting`, although it's not recommended.
+ */
 let UCDataStoreTester = class UCDataStoreTester {
     static { UCDataStoreTester_1 = this; }
     clockManager;
@@ -60,6 +69,7 @@ let UCDataStoreTester = class UCDataStoreTester {
         await ucDataStore.clear();
         this.readRes = await ucDataStore.read();
         this.expectXRecords(0);
+        // Write a last one in case need to watch data in the DB
         await this.ucDataStore.write({
             aggregateId: this.cryptoManager.randomUUID(),
             appName: APP_NAME_PLACEHOLDER,
@@ -116,9 +126,12 @@ let UCDataStoreTester = class UCDataStoreTester {
         ];
     }
     buildFiltersTestData() {
+        // biome-ignore lint/style/noNonNullAssertion: we're in a test
         const entry = this.entries[0];
         const [aggregateId, appName, ucNames, organizationId, userId] = entry;
+        // biome-ignore lint/style/noNonNullAssertion: we're in a test
         const name = ucNames[0];
+        // TODO : Enhance these with a combination of filters
         return [
             [{ aggregateId }, 2],
             [{ aggregateId: [aggregateId] }, 2],

package/dist/esm/testing/impl/SimpleAppDocsEmitter.js

@@ -33,6 +33,13 @@ SimpleAppDocsEmitter = __decorate([
     __metadata("design:paramtypes", [Object])
 ], SimpleAppDocsEmitter);
 export { SimpleAppDocsEmitter };
+// For now, we can have it here. When it becomes harder to maintain, we can introduce some kind of template engine.
+// Be aware that this will introduce complexities on building the lib.
+// We'll need to include these templates in the build and make them accessible via package.json "exports" or any other mechanism.
+// Hence the choice to keep it simple for now.
+// Defined it as function in case we need to pass args.
+// Using --- for the comment to make it compatible with pandoc
+// See https://stackoverflow.com/a/4829998/1259118
 const template = (cols, items) => `<!---
     All this code has been auto generated.
     DO NOT EDIT.
@@ -55,6 +62,9 @@ ${diagram(item)}`)
 |---|${cols.map((_c) => '---').join('|')}|
 ${items.map((item, idx) => ['', idx + 1, ...cols.map((c) => fmtTechSummaryField(item[c])), ''].join('|')).join('\n')}
 `;
+/*
+ * Diagram
+ */
 const CHECK_POLICY = '🔐 Check policy';
 const CHECK_POLICY_COND = 'when any validation fails';
 const CHECK_POLICY_COND_ACTION = 'show failure';
@@ -69,6 +79,8 @@ const SEND = '📤 Send';
 const SUBMIT = '↩️ Submit';
 const TRIGGER = '⤴️ Trigger';
 function diagram(item) {
+    // Debugger : https://mermaid.live/edit
+    // Messages : https://mermaid.js.org/syntax/sequenceDiagram.html#messages
     const client = 'Client';
     const server = 'Server';
     const user = 'User';
@@ -76,6 +88,8 @@ function diagram(item) {
     const { ioIFields, ioOPI0Fields, ioOPI1Fields, lifecycleClientPolicy, lifecycleClientSteps, lifecycleServerPolicy, lifecycleServerSteps, metadataSensitive, } = item;
     let req = TRIGGER;
     if (ioIFields && ioIFields.length > 0) {
+        // TODO : Include only fields to fill manually
+        // Not sure though, as for CLI for example (i.e. noContext), one needs to provide all of them
         req = `${FILL}${LB}${diagramUCFields(item.ioIFields)}`;
     }
     lines.push(`${user}->>+${client}: ${req}`);
@@ -89,6 +103,7 @@ function diagram(item) {
     if (lifecycleClientSteps) {
         lines.push(...diagramUCMainSteps(client, lifecycleClientSteps));
     }
+    // This is an approximation. Might need to improve it.
     const hasServer = item.lifecycleServerPolicy?.value;
     if (hasServer) {
         req = SEND;
@@ -142,11 +157,16 @@ function diagramUCPolicy(participant, caller, lifecyclePolicyField) {
         'end',
     ];
 }
+/*
+ * Technical Summary
+ */
 function fmtTechSummaryField(field) {
     if (!field) {
         return '';
     }
     const values = Array.isArray(field) ? field : [field];
+    // NOTE : <br> won't work for every markdown renderer.
+    // See https://stackoverflow.com/questions/11700487/how-do-i-add-a-newline-in-a-markdown-table
     return values.map(fmtTechSummaryFieldVal).join('<br>');
 }
 function fmtTechSummaryFieldVal(field) {
@@ -155,7 +175,7 @@ function fmtTechSummaryFieldVal(field) {
     if (err) {
         res += `❌ ${err}`;
     }
-    res = res.replace(/[\u00A0-\u9999<>\&]/g, (i) => `&#${i.charCodeAt(0)};`);
-    res = res.replaceAll('|', '\\|');
+    res = res.replace(/[\u00A0-\u9999<>\&]/g, (i) => `&#${i.charCodeAt(0)};`); // TS generics considered as HTML
+    res = res.replaceAll('|', '\\|'); // TS intersection vs Markdown table column
     return res;
 }

package/dist/esm/testing/impl/SimpleAppTesterConfigurator.js

@@ -24,6 +24,7 @@ export class SimpleAppTesterConfigurator {
         return undefined;
     }
     async seed(_ctx) {
+        // Nothing to do
     }
     async sideEffects(_ctx) {
         return undefined;

package/dist/esm/testing/impl/SimpleHTMLAppTestReportEmitter.js

@@ -19,6 +19,7 @@ let SimpleHTMLAppTestReportEmitter = class SimpleHTMLAppTestReportEmitter {
     }
     async exec({ appPath, testResults, testSummary, }) {
         const reportPath = this.reportPath(appPath);
+        // Since we're using 'recursive: true', there will be no error if the directory already exists
         await this.fsManager.mkdir(reportPath, { recursive: true });
         const tpl = template(appPath, testResults, testSummary);
         const outPath = await this.entrypointPath(appPath);
@@ -43,6 +44,11 @@ SimpleHTMLAppTestReportEmitter = __decorate([
     __metadata("design:paramtypes", [Object])
 ], SimpleHTMLAppTestReportEmitter);
 export { SimpleHTMLAppTestReportEmitter };
+// For now, we can have it here. When it becomes harder to maintain, we can introduce some kind of template engine.
+// Be aware that this will introduce complexities on building the lib.
+// We'll need to include these templates in the build and make them accessible via package.json "exports" or any other mechanism.
+// Hence the choice to keep it simple for now.
+// Defined it as function in case we need to pass args.
 const template = (appPath, testResults, testSummary) => `<!DOCTYPE html>
 <html lang="en">
     <head>
@@ -142,9 +148,9 @@ const template = (appPath, testResults, testSummary) => `<!DOCTYPE html>
 </html>
 `;
 const STATUS_COLOR_MAPPING = {
-    danger: '#ff4136',
-    success: '#42e6a4',
-    warning: '#ffff00',
+    danger: '#ff4136', // red
+    success: '#42e6a4', // green
+    warning: '#ffff00', // yellow
 };
 function statusStyles() {
     return Object.entries(STATUS_COLOR_MAPPING)

package/dist/esm/testing/impl/TypeScriptLibUCDefASTParser.js

@@ -12,6 +12,9 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
 };
 import { inject, injectable } from 'inversify';
 import { isClassDeclaration, isObjectLiteralExpression, isPropertyAssignment, } from 'typescript';
+// To avoid the following error when used in a consumer :
+// SyntaxError: Named export 'ModuleKind' not found. The requested module 'typescript' is a CommonJS module, which may not support all module.exports as named exports.
+// CommonJS modules can always be imported via the default export
 import typescript from 'typescript';
 const { ModuleKind, ModuleResolutionKind, ScriptTarget, createProgram, flattenDiagnosticMessageText, forEachChild, getPreEmitDiagnostics, isIdentifier, isImportDeclaration, isPropertySignature, isStringLiteral, isTypeReferenceNode, isVariableStatement, } = typescript;
 import { UC_MAIN_CLIENT_SUFFIX, UC_MAIN_SERVER_SUFFIX, UC_MAIN_STEP_PREFIX_REGULAR, UC_MAIN_SUFFIX, UC_POLICY_SUFFIX, } from '../../convention.js';
@@ -89,8 +92,10 @@ let TypeScriptLibUCDefASTParser = class TypeScriptLibUCDefASTParser {
             target: ScriptTarget[(compilerOptionsBase.target ??
                 target)],
         };
-        this.compilerOptions.jsx = undefined;
-        this.compilerOptions.lib = undefined;
+        // @ts-ignore
+        this.compilerOptions.jsx = undefined; // Otherwise it triggers the following error since TS 5.5 : jsx is a string value; tsconfig JSON must be parsed with parseJsonSourceFileConfigFileContent or getParsedCommandLineOfConfigFile before passing to createProgram
+        // @ts-ignore
+        this.compilerOptions.lib = undefined; // Otherwise it triggers errors saying it does not find them
     }
     getTypeFields(node) {
         const type = this.typeChecker.getTypeAtLocation(node);
@@ -114,9 +119,12 @@ let TypeScriptLibUCDefASTParser = class TypeScriptLibUCDefASTParser {
         return fields;
     }
     processConstDeclaration(node, onMainStep, onPolicy, onMetadata) {
+        // TODO : Improve this whole pattern by making it more robust
+        // I think there is a risk of it to break in some cases (e.g. if there are other properties named main, policy, etc.)
         const metadataPropertyName = 'metadata';
         const nodes = [];
         const populateNodes = (node1) => {
+            // "main: SendClientMain" => "main", ":", "SendClientMain" => 3
             if (isPropertyAssignment(node1) && node1.getChildCount() === 3) {
                 const propertyName = node1.getChildAt(0).getText();
                 if (propertyName === UC_MAIN_SUFFIX.toLocaleLowerCase() ||
@@ -137,7 +145,7 @@ let TypeScriptLibUCDefASTParser = class TypeScriptLibUCDefASTParser {
                 this.processLifecycleMain('server', node1, onMainStep);
             }
             else if (text.endsWith(UC_POLICY_SUFFIX)) {
-                const parent = node1.parent.getText();
+                const parent = node1.parent.getText(); // { main: X(Client|Server)Main, policy: XUCPolicy }
                 if (parent.includes(UC_MAIN_CLIENT_SUFFIX)) {
                     this.processLifecyclePolicy('client', node1, onPolicy);
                 }
@@ -211,7 +219,7 @@ let TypeScriptLibUCDefASTParser = class TypeScriptLibUCDefASTParser {
                     value = Boolean(value);
                 }
                 else {
-                    value = value.substring(1, v.length - 1);
+                    value = value.substring(1, v.length - 1); // To remove the single quotes
                 }
                 metadataLike[k] = value;
             }