Refactor compiler for separation of concerns

This commit separates concerns of "compiling" and "building" the
application. Before, both operations were called "parsing" but now the
parsing necessary is done inside the compiler and appplication object
constructed is separated to its own utility. Isolating compiling to its
own module allows refactoring/modifying compiler easily (to be able to
for example support ahead of time compilation) without affecting the
rest of the application.

Key Changes:

- Create DTO (data transfer objects) for compiler and make it
  independent of domain layer.

Other supporting changes:

- Refactor loading collection file to its own utility.
- Refactor application factory to be functional rather than OOD.
- Rename related interfaces to drop `I` prefix to align with new coding
  conventions.
- Prefer using "Loader" in naming in place of "Parser" where its about
  loading information, not really parsing data.
- Refactor domain objects to use more factory pattern

docs/application.md

@@ -3,7 +3,7 @@
 Application layer is mainly responsible for:
 
 - creating an event-based and mutable [application state](#application-state),
-- [parsing and compiling](#parsing-and-compiling) the [application data](#application-data).
+- [compiling](#compiling) the [application data](#application-data).
 
 📖 Refer to [architecture.md | Layered Application](./architecture.md#layered-application) to read more about the layered architecture.
 
@@ -27,17 +27,27 @@ Presentation layer uses a singleton (same instance of) [`ApplicationContext.ts`]
 
 Application data is collection files using YAML. You can refer to [collection-files.md](./collection-files.md) to read more about the scheme and structure of application data files. You can also check the source code [collection yaml files](./../src/application/collections/) to directly see the application data using that scheme.
 
-Application layer [parses and compiles](#parsing-and-compiling) application data into [`Application`](./../src/domain/Application.ts)). Once parsed, application layer provides the necessary functionality to presentation layer based on the application data. You can read more about how presentation layer consumes the application data in [presentation.md | Application Data](./presentation.md#application-data).
+Application layer loads and [compiles](#compiling) application data into [`Application`](./../src/domain/Application.ts).
+Once loaded, application layer provides the necessary functionality to presentation layer based on the application data.
+You can read more about how presentation layer consumes the application data in [presentation.md | Application Data](./presentation.md#application-data).
 
 Application layer enables [data-driven programming](https://en.wikipedia.org/wiki/Data-driven_programming) by leveraging the data to the rest of the source code. It makes it easy for community to contribute on the project by using a declarative language used in collection files.
 
-### Parsing and compiling
+### Compiling
 
-Application layer parses the application data to compile the domain object [`Application.ts`](./../src/domain/Application.ts).
+Application layer loads the application data, compiles it, and makes it available as the domain object [`Application.ts`](./../src/domain/Application.ts).
 
-The build tool loads (or injects) application data ([collection yaml files](./../src/application/collections/)) into the application layer in compile time. Application layer ([`ApplicationFactory.ts`](./../src/application/ApplicationFactory.ts)) parses and compiles this data in runtime.
+The process looks like this:
 
-Application layer compiles templating syntax during parsing to create the end scripts. You can read more about templating syntax in [templating.md](./templating.md) and how application data uses them through functions in [collection-files.md | Function](./collection-files.md#function).
+1. *(Compile time)*
+   The build tool loads (or injects) application data ([collection yaml files](./../src/application/collections/)) into the application layer in compile time.
+   See [`PreloadedCollectionDataProvider.ts`](./../src/application/PreloadedCollectionDataProvider.ts)
+2. *(Runtime)*
+   Compiler compiles the data into a data transfer object (DTO).
+   Compiler compiles templating syntax during parsing to create the end scripts
+   See [`Compiler/`](./../src/application/Compiler/), [templating.md](./templating.md), [collection-files.md](./collection-files.md).
+3. *(Runtime)*
+   Application layer ([`ApplicationProvider.ts`](./../src/application/Loader/ApplicationProvider.ts)) provides this application object.
 
 The steps to extend the templating syntax:
 

src/application/Parser/ScriptingDefinition/CodeSubstituter.ts → src/application/Compiler/Collection/ScriptingDefinition/CodeSubstituter.ts

@@ -5,7 +5,7 @@ import { ExpressionsCompiler } from '@/application/Parser/Executable/Script/Comp
 import type { ProjectDetails } from '@/domain/Project/ProjectDetails';
 import { FunctionCallArgumentCollection } from '@/application/Parser/Executable/Script/Compiler/Function/Call/Argument/FunctionCallArgumentCollection';
 import type { IExpressionParser } from '@/application/Parser/Executable/Script/Compiler/Expressions/Parser/IExpressionParser';
-import { createFunctionCallArgument, type FunctionCallArgumentFactory } from '../Executable/Script/Compiler/Function/Call/Argument/FunctionCallArgument';
+import { createFunctionCallArgument, type FunctionCallArgumentFactory } from '../../../Parser/Executable/Script/Compiler/Function/Call/Argument/FunctionCallArgument';
 
 export interface CodeSubstituter {
   (

src/application/Parser/ScriptingDefinition/ScriptingDefinitionParser.ts → src/application/Compiler/Collection/ScriptingDefinition/ScriptingDefinitionParser.ts

@@ -1,13 +1,13 @@
 import type { ScriptingDefinitionData } from '@/application/collections/';
-import type { IScriptingDefinition } from '@/domain/IScriptingDefinition';
-import { ScriptingDefinition } from '@/domain/ScriptingDefinition';
+import type { ScriptingDefinition } from '@/domain/ScriptingDefinition';
+import { ScriptingDefinition } from '@/domain/ScriptingDefinitionFactory';
 import { ScriptingLanguage } from '@/domain/ScriptingLanguage';
 import type { ProjectDetails } from '@/domain/Project/ProjectDetails';
-import { createEnumParser, type EnumParser } from '../../Common/Enum';
-import { createTypeValidator, type TypeValidator } from '../Common/TypeValidator';
+import { createEnumParser, type EnumParser } from '../../../Common/Enum';
+import { createTypeValidator, type TypeValidator } from '../../Common/TypeValidator';
 import { type CodeSubstituter, substituteCode } from './CodeSubstituter';
 
-export const parseScriptingDefinition: ScriptingDefinitionParser = (
+export const parseScriptingDefinition: ScriptingDefinitionCompiler = (
   definition,
   projectDetails,
   utilities: ScriptingDefinitionParserUtilities = DefaultUtilities,
@@ -16,19 +16,19 @@ export const parseScriptingDefinition: ScriptingDefinitionParser = (
   const language = utilities.languageParser.parseEnum(definition.language, 'language');
   const startCode = utilities.codeSubstituter(definition.startCode, projectDetails);
   const endCode = utilities.codeSubstituter(definition.endCode, projectDetails);
-  return new ScriptingDefinition(
+  return new ScriptingDefinitionDto(
     language,
     startCode,
     endCode,
   );
 };
 
-export interface ScriptingDefinitionParser {
+export interface ScriptingDefinitionCompiler {
   (
     definition: ScriptingDefinitionData,
     projectDetails: ProjectDetails,
     utilities?: ScriptingDefinitionParserUtilities,
-  ): IScriptingDefinition;
+  ): ScriptingDefinition;
 }
 
 function validateData(

src/application/Compiler/Collection/SingleCollectionCompiler.ts

@@ -0,0 +1,55 @@
+import type { CollectionData } from '@/application/collections/';
+import type { ProjectDetails } from '@/domain/Project/ProjectDetails';
+import type { CompiledCollectionDto } from '../CompiledCollectionDto';
+import TypeValidator, { createTypeValidator } from '@/application/Compiler/Common/TypeValidator';
+
+export interface SingleCollectionCompiler { //TODO: CategoryCollectionParser will become this.
+  (
+    collectionData: CollectionData,
+    projectDetails: ProjectDetails,
+    utilities?: SingleCollectionCompilerUtilities,
+  ): CompiledCollectionDto;
+}
+
+interface SingleCollectionCompilerUtilities {
+  readonly osParser: EnumParser<OperatingSystem>;
+  readonly validator: TypeValidator;
+  readonly parseScriptingDefinition: ScriptingDefinitionParser;
+  readonly createContext: CategoryCollectionContextFactory;
+  readonly parseCategory: CategoryParser;
+  readonly createCategoryCollection: CategoryCollectionFactory;
+}
+
+export const compileCollection: SingleCollectionCompiler = (
+  collectionData,
+  projectDetails,
+  utilities = DefaultUtilities,
+) => {
+  validateCollection(content, utilities.validator);
+};
+
+function validateCollection(
+  content: CollectionData,
+  validator: TypeValidator,
+): void {
+  validator.assertObject({
+    value: content,
+    valueName: 'Collection',
+    allowedProperties: [
+      'os', 'scripting', 'actions', 'functions',
+    ],
+  });
+  validator.assertNonEmptyCollection({
+    value: content.actions,
+    valueName: '\'actions\' in collection',
+  });
+}
+
+const DefaultUtilities: CategoryCollectionParserUtilities = {
+  validator: createTypeValidator(),
+  osParser: createEnumParser(OperatingSystem),
+  parseScriptingDefinition,
+  createContext: createCategoryCollectionContext,
+  parseCategory,
+  createCategoryCollection,
+};

src/application/Compiler/CompiledCollectionDto.ts

@@ -0,0 +1,23 @@
+export interface CompiledCollectionDto {
+  readonly os: string;
+  readonly startCode: string;
+  readonly endCode: string;
+  readonly language: string;
+  readonly rootCategories: readonly CompiledCategoryDto[];
+}
+
+export interface CompiledExecutableDto {
+  readonly markdownDocs: string;
+  readonly title: string;
+  readonly executableId: string;
+}
+
+export interface CompiledScriptDto extends CompiledExecutableDto {
+  readonly code: string;
+  readonly revertCode: string;
+}
+
+export interface CompiledCategoryDto extends CompiledExecutableDto {
+  readonly categories: readonly CompiledCategoryDto[];
+  readonly scripts: readonly CompiledScriptDto[];
+}

src/application/Compiler/MultipleCollectionsCompiler.ts

@@ -0,0 +1,54 @@
+import type { CollectionData } from '@/application/collections/';
+import type { ProjectDetails } from '@/domain/Project/ProjectDetails';
+import { createTypeValidator, type TypeValidator } from './Common/TypeValidator';
+import { compileCollection, type SingleCollectionCompiler } from './Collection/SingleCollectionCompiler';
+import type { CompiledCollectionDto } from './CompiledCollectionDto';
+
+/**
+ * This utility is responsible for compiling collection data into an application object.
+ * It serves as part of the application layer, parsing and compiling the application data
+ * defined in collection YAML files.
+ *
+ * The compiler creates basic, decoupled abstractions without external references,
+ * acting as an anti-corruption layer. This design allows for independent changes
+ * to the compiler and its models.
+ */
+export interface MultipleCollectionsCompiler {
+  (
+    collectionsData: readonly CollectionData[],
+    projectDetails: ProjectDetails,
+    utilities?: CollectionCompilerUtilities,
+  ): CompiledCollectionDto[];
+}
+
+export const compileCollections: MultipleCollectionsCompiler = (
+  collectionsData,
+  projectDetails,
+  utilities = DefaultUtilities,
+) => {
+  validateCollectionsData(collectionsData, utilities.validator);
+  const collections = collectionsData.map(
+    (collection) => utilities.compileCollection(collection, projectDetails),
+  );
+  return collections;
+};
+
+interface CollectionCompilerUtilities {
+  readonly validator: TypeValidator;
+  readonly compileCollection: SingleCollectionCompiler;
+}
+
+const DefaultUtilities: CollectionCompilerUtilities = {
+  validator: createTypeValidator(),
+  compileCollection,
+};
+
+function validateCollectionsData(
+  collections: readonly CollectionData[],
+  validator: TypeValidator,
+) {
+  validator.assertNonEmptyCollection({
+    value: collections,
+    valueName: 'Collections',
+  });
+}

src/application/Context/ApplicationContext.ts

@@ -1,6 +1,6 @@
-import type { IApplication } from '@/domain/IApplication';
+import type { Application } from '@/domain/Application';
 import { OperatingSystem } from '@/domain/OperatingSystem';
-import type { ICategoryCollection } from '@/domain/Collection/ICategoryCollection';
+import type { CategoryCollection } from '@/domain/Collection/CategoryCollection';
 import { EventSource } from '@/infrastructure/Events/EventSource';
 import { assertInRange } from '@/application/Common/Enum';
 import { CategoryCollectionState } from './State/CategoryCollectionState';
@@ -12,7 +12,7 @@ type StateMachine = Map<OperatingSystem, ICategoryCollectionState>;
 export class ApplicationContext implements IApplicationContext {
   public readonly contextChanged = new EventSource<IApplicationContextChangedEvent>();
 
-  public collection: ICategoryCollection;
+  public collection: CategoryCollection;
 
   public currentOs: OperatingSystem;
 
@@ -23,7 +23,7 @@ export class ApplicationContext implements IApplicationContext {
   private readonly states: StateMachine;
 
   public constructor(
-    public readonly app: IApplication,
+    public readonly app: Application,
     initialContext: OperatingSystem,
   ) {
     this.setContext(initialContext);
@@ -59,15 +59,15 @@ export class ApplicationContext implements IApplicationContext {
 
 function validateOperatingSystem(
   os: OperatingSystem,
-  app: IApplication,
+  app: Application,
 ): void {
   assertInRange(os, OperatingSystem);
   if (!app.getSupportedOsList().includes(os)) {
     throw new Error(`Operating system "${OperatingSystem[os]}" is not supported.`);
   }
 }
 
-function initializeStates(app: IApplication): StateMachine {
+function initializeStates(app: Application): StateMachine {
   const machine = new Map<OperatingSystem, ICategoryCollectionState>();
   for (const collection of app.collections) {
     machine.set(collection.os, new CategoryCollectionState(collection));

src/application/Context/ApplicationContextFactory.ts

@@ -1,22 +1,22 @@
 import type { IApplicationContext } from '@/application/Context/IApplicationContext';
 import { OperatingSystem } from '@/domain/OperatingSystem';
-import type { IApplication } from '@/domain/IApplication';
+import type { Application } from '@/domain/Application';
 import { CurrentEnvironment } from '@/infrastructure/RuntimeEnvironment/RuntimeEnvironmentFactory';
-import { ApplicationFactory } from '../ApplicationFactory';
+import { createOrGetApplication } from '../Loader/LazySingletonApplicationProvider';
 import { ApplicationContext } from './ApplicationContext';
-import type { IApplicationFactory } from '../IApplicationFactory';
+import type { ApplicationProvider } from '../Loader/ApplicationProvider';
 
 export async function buildContext(
-  factory: IApplicationFactory = ApplicationFactory.Current,
+  getApplication: ApplicationProvider = createOrGetApplication,
   environment = CurrentEnvironment,
 ): Promise<IApplicationContext> {
-  const app = await factory.getApp();
+  const app = await getApplication();
   const os = getInitialOs(app, environment.os);
   return new ApplicationContext(app, os);
 }
 
 function getInitialOs(
-  app: IApplication,
+  app: Application,
   currentOs: OperatingSystem | undefined,
 ): OperatingSystem {
   const supportedOsList = app.getSupportedOsList();
@@ -26,7 +26,7 @@ function getInitialOs(
   return getMostSupportedOs(supportedOsList, app);
 }
 
-function getMostSupportedOs(supportedOsList: OperatingSystem[], app: IApplication) {
+function getMostSupportedOs(supportedOsList: OperatingSystem[], app: Application) {
   supportedOsList.sort((os1, os2) => {
     const getPriority = (os: OperatingSystem) => app.getCollection(os).totalScripts;
     return getPriority(os2) - getPriority(os1);

src/application/Context/IApplicationContext.ts

@@ -1,10 +1,10 @@
 import { OperatingSystem } from '@/domain/OperatingSystem';
 import type { IEventSource } from '@/infrastructure/Events/IEventSource';
-import type { IApplication } from '@/domain/IApplication';
+import type { Application } from '@/domain/Application';
 import type { ICategoryCollectionState, IReadOnlyCategoryCollectionState } from './State/ICategoryCollectionState';
 
 export interface IReadOnlyApplicationContext {
-  readonly app: IApplication;
+  readonly app: Application;
   readonly state: IReadOnlyCategoryCollectionState;
   readonly contextChanged: IEventSource<IApplicationContextChangedEvent>;
 }

src/application/Context/State/CategoryCollectionState.ts

@@ -1,4 +1,4 @@
-import type { ICategoryCollection } from '@/domain/Collection/ICategoryCollection';
+import type { CategoryCollection } from '@/domain/Collection/CategoryCollection';
 import { OperatingSystem } from '@/domain/OperatingSystem';
 import { AdaptiveFilterContext } from './Filter/AdaptiveFilterContext';
 import { ApplicationCode } from './Code/ApplicationCode';
@@ -18,7 +18,7 @@ export class CategoryCollectionState implements ICategoryCollectionState {
   public readonly filter: FilterContext;
 
   public constructor(
-    public readonly collection: ICategoryCollection,
+    public readonly collection: CategoryCollection,
     selectionFactory = DefaultSelectionFactory,
     codeFactory = DefaultCodeFactory,
     filterFactory = DefaultFilterFactory,

src/application/Context/State/Code/ApplicationCode.ts

@@ -1,5 +1,5 @@
 import { EventSource } from '@/infrastructure/Events/EventSource';
-import type { IScriptingDefinition } from '@/domain/IScriptingDefinition';
+import type { ScriptingDefinition } from '@/domain/ScriptingDefinition';
 import type { SelectedScript } from '@/application/Context/State/Selection/Script/SelectedScript';
 import type { ReadonlyScriptSelection } from '@/application/Context/State/Selection/Script/ScriptSelection';
 import { CodeChangedEvent } from './Event/CodeChangedEvent';
@@ -18,7 +18,7 @@ export class ApplicationCode implements IApplicationCode {
 
   constructor(
     selection: ReadonlyScriptSelection,
-    private readonly scriptingDefinition: IScriptingDefinition,
+    private readonly scriptingDefinition: ScriptingDefinition,
     private readonly generator: IUserScriptGenerator = new UserScriptGenerator(),
   ) {
     this.setCode(selection.selectedScripts);

src/application/Context/State/Code/Generation/IUserScriptGenerator.ts

@@ -1,10 +1,10 @@
-import type { IScriptingDefinition } from '@/domain/IScriptingDefinition';
+import type { ScriptingDefinition } from '@/domain/ScriptingDefinition';
 import type { SelectedScript } from '@/application/Context/State/Selection/Script/SelectedScript';
 import type { IUserScript } from './IUserScript';
 
 export interface IUserScriptGenerator {
   buildCode(
     selectedScripts: ReadonlyArray<SelectedScript>,
-    scriptingDefinition: IScriptingDefinition,
+    scriptingDefinition: ScriptingDefinition,
   ): IUserScript;
 }