libmodulor 0.4.0 → 0.6.0

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

@@ -4,31 +4,46 @@ 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({ errMsg = null, execState, field, onChange: onChangeBase, }) {
-    const attrs = htmlInputDef(field, execState, errMsg);
+export function UCFormFieldControl({ errMsg = null, execState, f, onChange: onChangeBase, }) {
+    const attrs = htmlInputDef(f, execState, errMsg);
     const onChange = (e) => {
         const target = e.currentTarget;
         const type = target.type;
         let value = target.value;
+        if (target.localName === 'select' && !value) {
+            // Prevent the value from being '' when we set/unset the select
+            // Otherwise it sets '' as value and prevents the form for being valid
+            onChangeBase(f, UCInputFieldChangeOperator.RESET, value);
+            return;
+        }
         if (CHECKED_FIELD_TYPES.includes(type) && 'checked' in target) {
             value = target.checked;
         }
         else if (FILE_FIELD_TYPES.includes(type) && 'files' in target) {
             value = target.files?.item(0);
         }
-        const [isRepeatable] = ucifRepeatability(field.def);
+        const [isRepeatable] = ucifRepeatability(f.def);
         if (isRepeatable && typeof value === 'string') {
             const valueArr = value
                 .split(MULTIPLE_VALUES_SEPARATOR)
                 .map((v) => v.trim());
-            onChangeBase(field, UCInputFieldChangeOperator.SET, valueArr);
+            onChangeBase(f, UCInputFieldChangeOperator.SET, valueArr);
         }
         else {
-            onChangeBase(field, UCInputFieldChangeOperator.SET, value);
+            onChangeBase(f, UCInputFieldChangeOperator.SET, value);
         }
     };
     if (attrs.internal?.multiline) {
         return React.createElement("textarea", { ...attrs.spec, onChange: onChange });
     }
+    const { type } = f.def;
+    const options = type.getOptions();
+    if (options) {
+        // TODO : Handle type.hasStrictOptions() => display an input text alongside the select
+        // TODO : Consider using a radio and/or checkbox and/or selectable buttons when the options count < X
+        return (React.createElement("select", { ...attrs.spec, onChange: onChange },
+            React.createElement("option", null),
+            options.map((o) => (React.createElement("option", { key: o.value.toString(), value: o.value.toString() }, o.label)))));
+    }
     return React.createElement("input", { ...attrs.spec, onChange: onChange });
 }

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

@@ -1,7 +1,4 @@
 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;
+import type { UCFormFieldDescProps } from '../lib/react/form.js';
+export declare function UCFormFieldDesc<T extends DataType>({ f, }: UCFormFieldDescProps<T>): ReactElement | null;

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

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

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

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

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

@@ -1,7 +1,4 @@
 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;
+import type { UCFormFieldLabelProps } from '../lib/react/form.js';
+export declare function UCFormFieldLabel<T extends DataType>({ f, }: UCFormFieldLabelProps<T>): ReactElement;

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

@@ -1,8 +1,8 @@
 import React, {} from 'react';
 import { ucifId } from '../../uc/index.js';
 import { useDIContext } from '../lib/react/DIContextProvider.js';
-export function UCFormFieldLabel({ field, }) {
+export function UCFormFieldLabel({ f, }) {
     const { wordingManager } = useDIContext();
-    const { label } = wordingManager.ucif(field);
-    return React.createElement("label", { htmlFor: ucifId(field.key) }, label);
+    const { label } = wordingManager.ucif(f);
+    return React.createElement("label", { htmlFor: ucifId(f.key) }, label);
 }

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

@@ -1,6 +1,4 @@
 import { type ReactElement } from 'react';
 import type { UCInput, UCOPIBase } from '../../uc/index.js';
-import type { UCPanelCtx } from '../lib/react/panel.js';
-type Props<I extends UCInput | undefined = undefined, OPI0 extends UCOPIBase | undefined = undefined, OPI1 extends UCOPIBase | undefined = undefined> = UCPanelCtx<I, OPI0, OPI1>;
-export declare function UCFormSubmitControl<I extends UCInput | undefined = undefined, OPI0 extends UCOPIBase | undefined = undefined, OPI1 extends UCOPIBase | undefined = undefined>({ execState, disabled, uc }: Props<I, OPI0, OPI1>): ReactElement;
-export {};
+import type { UCFormSubmitControlProps } from '../lib/react/form.js';
+export declare function UCFormSubmitControl<I extends UCInput | undefined = undefined, OPI0 extends UCOPIBase | undefined = undefined, OPI1 extends UCOPIBase | undefined = undefined>({ execState, disabled, uc, }: UCFormSubmitControlProps<I, OPI0, OPI1>): ReactElement;

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

@@ -1,6 +1,6 @@
 import React, {} from 'react';
 import { useDIContext } from '../lib/react/DIContextProvider.js';
-export function UCFormSubmitControl({ execState, disabled, uc }) {
+export function UCFormSubmitControl({ execState, disabled, uc, }) {
     const { wordingManager } = useDIContext();
     return (React.createElement("input", { disabled: disabled, type: "submit", value: wordingManager.ucISubmit(uc.def, execState) }));
 }

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;
             }

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

@@ -19,6 +19,7 @@ let VitestAppTestSuiteEmitter = class VitestAppTestSuiteEmitter {
     }
     async exec({ appPath, depsMapping, idx, monkeyTestingTimeoutInMs, serverPortRangeStart, }) {
         const testPath = this.fsManager.path(appPath, APP_TEST_DIR_NAME);
+        // Since we're using 'recursive: true', there will be no error if the directory already exists
         await this.fsManager.mkdir(testPath, { recursive: true });
         const outPath = this.fsManager.path(testPath, APP_TEST_MAIN_FILE_NAME);
         let tpl = template(serverPortRangeStart, idx, monkeyTestingTimeoutInMs);
@@ -37,6 +38,11 @@ VitestAppTestSuiteEmitter = __decorate([
     __metadata("design:paramtypes", [Object])
 ], VitestAppTestSuiteEmitter);
 export { VitestAppTestSuiteEmitter };
+// 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 = (serverPortRangeStart, idx, monkeyTestingTimeoutInMs) => `/*
     All this code has been auto generated.
     DO NOT EDIT.

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

@@ -5,25 +5,63 @@ import type { AppTesterCtx } from './ctx.js';
 type AppTesterOptsAliasPrefix = string;
 type AppTesterOptsImportsList = string[];
 export interface AppTesterTypeScriptOpts {
+    /**
+     * Although the TS lib relies on an enum (`ModuleKind`), we use plain text so it's compatible with a regular tsconfig.json
+     * @see https://www.typescriptlang.org/tsconfig/#module
+     * @defaultValue "NodeNext"
+     */
     module?: string;
+    /**
+     * Although the TS lib relies on an enum (`ModuleResolutionKind`), we use plain text so it's compatible with a regular tsconfig.json
+     * @see https://www.typescriptlang.org/tsconfig/#moduleResolution
+     * @defaultValue "NodeNext"
+     */
     moduleResolution?: string;
+    /**
+     * @see https://www.typescriptlang.org/tsconfig/#noCheck
+     * @defaultValue true
+     */
     noCheck?: boolean;
+    /**
+     * @see https://www.typescriptlang.org/tsconfig/#skipLibCheck
+     * @defaultValue true
+     */
     skipLibCheck?: boolean;
+    /**
+     * Although the TS lib relies on an enum (`ScriptTarget`), we use plain text so it's compatible with a regular tsconfig.json
+     * @see https://www.typescriptlang.org/tsconfig/#target
+     * @defaultValue "ESNext"
+     */
     target?: string;
 }
 export type AppTesterOpts = Partial<Pick<LoggerSettings, 'logger_level'>> & {
     source?: {
         imports?: {
             external?: {
+                /**
+                 * @defaultValue '@'
+                 */
                 aliasPrefix?: AppTesterOptsAliasPrefix;
+                /**
+                 * @defaultValue ['fik-sdk', 'inversify']
+                 */
                 allowed?: AppTesterOptsImportsList;
             };
             internal?: {
+                /**
+                 * @defaultValue '../../'
+                 */
                 maxDepth?: FilePath;
+                /**
+                 * @defaultValue '.'
+                 */
                 startChar?: string;
             };
         };
         ts?: {
+            /**
+             * @defaultValue tsconfig.json
+             */
             configFileName?: FileName;
         } & AppTesterTypeScriptOpts;
     };

package/dist/esm/testing/opts.js

@@ -1,5 +1,5 @@
 export const DEFAULT_APP_TESTER_OPTS = {
-    logger_level: 'error',
+    logger_level: 'error', // Having 'debug' makes the test output bloated so it's opt-in
     source: {
         imports: {
             external: {

package/dist/esm/testing/uc-input.js

@@ -33,11 +33,13 @@ export function onlySetProgrammaticallyWithExamples(uc) {
         fillWithExample(f);
     }
 }
+// biome-ignore lint/suspicious/noExplicitAny: can be anything
 function fillWithExample(f) {
     const { type } = f.def;
     let val = type.getExamples()?.[0] ?? type.example();
     if (type instanceof TFile) {
         const file = val;
+        // TODO : Consider building a real file with real data (e.g. image, pdf, txt, etc.)
         val = new File(['01010101010101010101010101010101'], file.path, {
             type: file.type,
         });