Refactor executable IDs to use strings #262

This commit unifies executable ID structure across categories and
scripts, paving the way for more complex ID solutions for #262.
It also refactors related code to adapt to the changes.

Key changes:

- Change numeric IDs to string IDs for categories
- Use named types for string IDs to improve code clarity
- Add unit tests to verify ID uniqueness

Other supporting changes:

- Separate concerns in entities for data access and executables by using
  separate abstractions (`Identifiable` and `RepositoryEntity`)
- Simplify usage and construction of entities.
- Remove `BaseEntity` for simplicity.
- Move creation of categories/scripts to domain layer
- Refactor CategoryCollection for better validation logic isolation
- Rename some categories to keep the names (used as pseudo-IDs) unique
  on Windows.

src/domain/Collection/CategoryCollection.ts

@@ -0,0 +1,134 @@
+import { getEnumValues, assertInRange } from '@/application/Common/Enum';
+import { RecommendationLevel } from '../Executables/Script/RecommendationLevel';
+import { OperatingSystem } from '../OperatingSystem';
+import { validateCategoryCollection } from './Validation/CompositeCategoryCollectionValidator';
+import type { ExecutableId } from '../Executables/Identifiable';
+import type { Category } from '../Executables/Category/Category';
+import type { Script } from '../Executables/Script/Script';
+import type { IScriptingDefinition } from '../IScriptingDefinition';
+import type { ICategoryCollection } from './ICategoryCollection';
+import type { CategoryCollectionValidator } from './Validation/CategoryCollectionValidator';
+
+export class CategoryCollection implements ICategoryCollection {
+  public readonly os: OperatingSystem;
+
+  public readonly actions: ReadonlyArray<Category>;
+
+  public readonly scripting: IScriptingDefinition;
+
+  public get totalScripts(): number { return this.queryable.allScripts.length; }
+
+  public get totalCategories(): number { return this.queryable.allCategories.length; }
+
+  private readonly queryable: QueryableCollection;
+
+  constructor(
+    parameters: CategoryCollectionInitParameters,
+    validate: CategoryCollectionValidator = validateCategoryCollection,
+  ) {
+    this.os = parameters.os;
+    this.actions = parameters.actions;
+    this.scripting = parameters.scripting;
+
+    this.queryable = makeQueryable(this.actions);
+    validate({
+      allScripts: this.queryable.allScripts,
+      allCategories: this.queryable.allCategories,
+      operatingSystem: this.os,
+    });
+  }
+
+  public getCategory(executableId: ExecutableId): Category {
+    const category = this.queryable.allCategories.find((c) => c.executableId === executableId);
+    if (!category) {
+      throw new Error(`Missing category with ID: "${executableId}"`);
+    }
+    return category;
+  }
+
+  public getScriptsByLevel(level: RecommendationLevel): readonly Script[] {
+    assertInRange(level, RecommendationLevel);
+    const scripts = this.queryable.scriptsByLevel.get(level);
+    return scripts ?? [];
+  }
+
+  public getScript(executableId: ExecutableId): Script {
+    const script = this.queryable.allScripts.find((s) => s.executableId === executableId);
+    if (!script) {
+      throw new Error(`Missing script: ${executableId}`);
+    }
+    return script;
+  }
+
+  public getAllScripts(): Script[] {
+    return this.queryable.allScripts;
+  }
+
+  public getAllCategories(): Category[] {
+    return this.queryable.allCategories;
+  }
+}
+
+export interface CategoryCollectionInitParameters {
+  readonly os: OperatingSystem;
+  readonly actions: ReadonlyArray<Category>;
+  readonly scripting: IScriptingDefinition;
+}
+
+interface QueryableCollection {
+  readonly allCategories: Category[];
+  readonly allScripts: Script[];
+  readonly scriptsByLevel: Map<RecommendationLevel, readonly Script[]>;
+}
+
+function flattenCategoryHierarchy(
+  categories: ReadonlyArray<Category>,
+): [Category[], Script[]] {
+  const [subCategories, subScripts] = (categories || [])
+    // Parse children
+    .map((category) => flattenCategoryHierarchy(category.subcategories))
+    // Flatten results
+    .reduce(([previousCategories, previousScripts], [currentCategories, currentScripts]) => {
+      return [
+        [...previousCategories, ...currentCategories],
+        [...previousScripts, ...currentScripts],
+      ];
+    }, [new Array<Category>(), new Array<Script>()]);
+  return [
+    [
+      ...(categories || []),
+      ...subCategories,
+    ],
+    [
+      ...(categories || []).flatMap((category) => category.scripts || []),
+      ...subScripts,
+    ],
+  ];
+}
+
+function makeQueryable(
+  actions: ReadonlyArray<Category>,
+): QueryableCollection {
+  const flattened = flattenCategoryHierarchy(actions);
+  return {
+    allCategories: flattened[0],
+    allScripts: flattened[1],
+    scriptsByLevel: groupByLevel(flattened[1]),
+  };
+}
+
+function groupByLevel(
+  allScripts: readonly Script[],
+): Map<RecommendationLevel, readonly Script[]> {
+  return getEnumValues(RecommendationLevel)
+    .map((level) => ({
+      level,
+      scripts: allScripts.filter(
+        (script) => script.level !== undefined && script.level <= level,
+      ),
+    }))
+    .reduce((map, group) => {
+      map.set(group.level, group.scripts);
+      return map;
+    }, new Map<RecommendationLevel, readonly Script[]>());
+}

src/domain/Collection/ICategoryCollection.ts

@@ -0,0 +1,20 @@
+import type { IScriptingDefinition } from '@/domain/IScriptingDefinition';
+import { OperatingSystem } from '@/domain/OperatingSystem';
+import { RecommendationLevel } from '@/domain/Executables/Script/RecommendationLevel';
+import type { Script } from '@/domain/Executables/Script/Script';
+import type { Category } from '@/domain/Executables/Category/Category';
+import type { ExecutableId } from '../Executables/Identifiable';
+
+export interface ICategoryCollection {
+  readonly scripting: IScriptingDefinition;
+  readonly os: OperatingSystem;
+  readonly totalScripts: number;
+  readonly totalCategories: number;
+  readonly actions: ReadonlyArray<Category>;
+
+  getScriptsByLevel(level: RecommendationLevel): ReadonlyArray<Script>;
+  getCategory(categoryId: ExecutableId): Category;
+  getScript(scriptId: ExecutableId): Script;
+  getAllScripts(): ReadonlyArray<Script>;
+  getAllCategories(): ReadonlyArray<Category>;
+}

src/domain/Collection/Validation/CategoryCollectionValidator.ts

@@ -0,0 +1,15 @@
+import type { Category } from '@/domain/Executables/Category/Category';
+import type { Script } from '@/domain/Executables/Script/Script';
+import type { OperatingSystem } from '@/domain/OperatingSystem';
+
+export interface CategoryCollectionValidationContext {
+  readonly allScripts: readonly Script[];
+  readonly allCategories: readonly Category[];
+  readonly operatingSystem: OperatingSystem;
+}
+
+export interface CategoryCollectionValidator {
+  (
+    context: CategoryCollectionValidationContext,
+  ): void;
+}

src/domain/Collection/Validation/CompositeCategoryCollectionValidator.ts

@@ -0,0 +1,33 @@
+import { ensurePresenceOfAtLeastOneScript } from './Rules/EnsurePresenceOfAtLeastOneScript';
+import { ensurePresenceOfAtLeastOneCategory } from './Rules/EnsurePresenceOfAtLeastOneCategory';
+import { ensureUniqueIdsAcrossExecutables } from './Rules/EnsureUniqueIdsAcrossExecutables';
+import { ensureKnownOperatingSystem } from './Rules/EnsureKnownOperatingSystem';
+import type { CategoryCollectionValidationContext, CategoryCollectionValidator } from './CategoryCollectionValidator';
+
+export type CompositeCategoryCollectionValidator = CategoryCollectionValidator & {
+  (
+    ...args: [
+      ...Parameters<CategoryCollectionValidator>,
+      (readonly CategoryCollectionValidator[])?,
+    ]
+  ): void;
+};
+
+export const validateCategoryCollection: CompositeCategoryCollectionValidator = (
+  context: CategoryCollectionValidationContext,
+  validators: readonly CategoryCollectionValidator[] = DefaultValidators,
+) => {
+  if (!validators.length) {
+    throw new Error('No validators provided.');
+  }
+  for (const validate of validators) {
+    validate(context);
+  }
+};
+
+const DefaultValidators: readonly CategoryCollectionValidator[] = [
+  ensureKnownOperatingSystem,
+  ensurePresenceOfAtLeastOneScript,
+  ensurePresenceOfAtLeastOneCategory,
+  ensureUniqueIdsAcrossExecutables,
+];

src/domain/Collection/Validation/Rules/EnsureKnownOperatingSystem.ts

@@ -0,0 +1,9 @@
+import { assertInRange } from '@/application/Common/Enum';
+import { OperatingSystem } from '@/domain/OperatingSystem';
+import type { CategoryCollectionValidator } from '../CategoryCollectionValidator';
+
+export const ensureKnownOperatingSystem: CategoryCollectionValidator = (
+  context,
+) => {
+  assertInRange(context.operatingSystem, OperatingSystem);
+};

src/domain/Collection/Validation/Rules/EnsurePresenceOfAllRecommendationLevels.ts

@@ -0,0 +1,35 @@
+import { getEnumValues } from '@/application/Common/Enum';
+import { RecommendationLevel } from '@/domain/Executables/Script/RecommendationLevel';
+import type { Script } from '@/domain/Executables/Script/Script';
+import type { CategoryCollectionValidator } from '../CategoryCollectionValidator';
+
+export const ensurePresenceOfAllRecommendationLevels: CategoryCollectionValidator = (
+  context,
+) => {
+  const unrepresentedRecommendationLevels = getUnrepresentedRecommendationLevels(
+    context.allScripts,
+  );
+  if (unrepresentedRecommendationLevels.length === 0) {
+    return;
+  }
+  const formattedRecommendationLevels = unrepresentedRecommendationLevels
+    .map((level) => getDisplayName(level))
+    .join(', ');
+  throw new Error(`Missing recommendation levels: ${formattedRecommendationLevels}.`);
+};
+
+function getUnrepresentedRecommendationLevels(
+  scripts: readonly Script[],
+): (RecommendationLevel | undefined)[] {
+  const expectedLevels = [
+    undefined,
+    ...getEnumValues(RecommendationLevel),
+  ];
+  return expectedLevels.filter(
+    (level) => scripts.every((script) => script.level !== level),
+  );
+}
+
+function getDisplayName(level: RecommendationLevel | undefined): string {
+  return level === undefined ? 'None' : RecommendationLevel[level];
+}

src/domain/Collection/Validation/Rules/EnsurePresenceOfAtLeastOneCategory.ts

@@ -0,0 +1,9 @@
+import type { CategoryCollectionValidator } from '../CategoryCollectionValidator';
+
+export const ensurePresenceOfAtLeastOneCategory: CategoryCollectionValidator = (
+  context,
+) => {
+  if (!context.allCategories.length) {
+    throw new Error('Collection must have at least one category');
+  }
+};

src/domain/Collection/Validation/Rules/EnsurePresenceOfAtLeastOneScript.ts

@@ -0,0 +1,9 @@
+import type { CategoryCollectionValidator } from '../CategoryCollectionValidator';
+
+export const ensurePresenceOfAtLeastOneScript: CategoryCollectionValidator = (
+  context,
+) => {
+  if (!context.allScripts.length) {
+    throw new Error('Collection must have at least one script');
+  }
+};

src/domain/Collection/Validation/Rules/EnsureUniqueIdsAcrossExecutables.ts

@@ -0,0 +1,43 @@
+import type { Identifiable } from '@/domain/Executables/Identifiable';
+import type { CategoryCollectionValidator } from '../CategoryCollectionValidator';
+
+export const ensureUniqueIdsAcrossExecutables: CategoryCollectionValidator = (
+  context,
+) => {
+  const allExecutables: readonly Identifiable[] = [
+    ...context.allCategories,
+    ...context.allScripts,
+  ];
+  ensureNoDuplicateIds(allExecutables);
+};
+
+function ensureNoDuplicateIds(
+  executables: readonly Identifiable[],
+) {
+  const duplicateExecutables = getExecutablesWithDuplicateIds(executables);
+  if (duplicateExecutables.length === 0) {
+    return;
+  }
+  const formattedDuplicateIds = duplicateExecutables.map(
+    (executable) => `"${executable.executableId}"`,
+  ).join(', ');
+  throw new Error(`Duplicate executable IDs found: ${formattedDuplicateIds}`);
+}
+
+function getExecutablesWithDuplicateIds(
+  executables: readonly Identifiable[],
+): Identifiable[] {
+  return executables
+    .filter(
+      (executable, index, array) => {
+        const otherIndex = array.findIndex(
+          (otherExecutable) => haveIdenticalIds(executable, otherExecutable),
+        );
+        return otherIndex !== index;
+      },
+    );
+}
+
+function haveIdenticalIds(first: Identifiable, second: Identifiable): boolean {
+  return first.executableId === second.executableId;
+}