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.

tests/unit/domain/Collection/Validation/Rules/EnsureKnownOperatingSystem.spec.ts

@@ -0,0 +1,21 @@
+import { describe } from 'vitest';
+import { OperatingSystem } from '@/domain/OperatingSystem';
+import { EnumRangeTestRunner } from '@tests/unit/application/Common/EnumRangeTestRunner';
+import { ensureKnownOperatingSystem } from '@/domain/Collection/Validation/Rules/EnsureKnownOperatingSystem';
+import { CategoryCollectionValidationContextStub } from '@tests/unit/shared/Stubs/CategoryCollectionValidationContextStub';
+
+describe('ensureKnownOperatingSystem', () => {
+  // act
+  const act = (os: OperatingSystem) => test(os);
+  // assert
+  new EnumRangeTestRunner(act)
+    .testValidValueDoesNotThrow(OperatingSystem.Android)
+    .testOutOfRangeThrows();
+});
+
+function test(operatingSystem: OperatingSystem):
+ReturnType<typeof ensureKnownOperatingSystem> {
+  const context = new CategoryCollectionValidationContextStub()
+    .withOperatingSystem(operatingSystem);
+  return ensureKnownOperatingSystem(context);
+}

tests/unit/domain/Collection/Validation/Rules/EnsurePresenceOfAllRecommendationLevels.spec.ts

@@ -0,0 +1,99 @@
+import { describe, it, expect } from 'vitest';
+import { RecommendationLevel } from '@/domain/Executables/Script/RecommendationLevel';
+import type { Script } from '@/domain/Executables/Script/Script';
+import { ensurePresenceOfAllRecommendationLevels } from '@/domain/Collection/Validation/Rules/EnsurePresenceOfAllRecommendationLevels';
+import { CategoryCollectionValidationContextStub } from '@tests/unit/shared/Stubs/CategoryCollectionValidationContextStub';
+import { ScriptStub } from '@tests/unit/shared/Stubs/ScriptStub';
+import { getEnumValues } from '@/application/Common/Enum';
+import { collectExceptionMessage } from '@tests/unit/shared/ExceptionCollector';
+
+describe('ensurePresenceOfAllRecommendationLevels', () => {
+  it('passes when all recommendation levels are present', () => {
+    // arrange
+    const scripts = getAllPossibleRecommendationLevels().map((level, index) => {
+      return new ScriptStub(`script-${index}`)
+        .withLevel(level);
+    });
+
+    // act
+    const act = () => test(scripts);
+
+    // assert
+    expect(act).to.not.throw();
+  });
+
+  describe('missing single level', () => {
+    // arrange
+    const recommendationLevels = getAllPossibleRecommendationLevels();
+    recommendationLevels.forEach((missingLevel) => {
+      const expectedDisplayName = getDisplayName(missingLevel);
+      it(`throws an error when when "${expectedDisplayName}" is missing`, () => {
+        const expectedError = `Missing recommendation levels: ${expectedDisplayName}.`;
+        const otherLevels = recommendationLevels.filter((level) => level !== missingLevel);
+        const scripts = otherLevels.map(
+          (level, index) => new ScriptStub(`script-${index}`).withLevel(level),
+        );
+        // act
+        const act = () => test(scripts);
+        // assert
+        expect(act).to.throw(expectedError);
+      });
+    });
+  });
+
+  it('throws an error with multiple missing recommendation levels', () => {
+    // arrange
+    const [
+      notExpectedLevelInError,
+      ...expectedLevelsInError
+    ] = getAllPossibleRecommendationLevels();
+    const scripts: Script[] = [
+      new ScriptStub('recommended').withLevel(notExpectedLevelInError),
+    ];
+
+    // act
+    const act = () => test(scripts);
+
+    // assert
+    const actualErrorMessage = collectExceptionMessage(act);
+    expectedLevelsInError.forEach((level) => {
+      const expectedLevelInError = getDisplayName(level);
+      expect(actualErrorMessage).to.include(expectedLevelInError);
+    });
+    expect(actualErrorMessage).to.not.include(getDisplayName(notExpectedLevelInError));
+  });
+
+  it('throws an error when no scripts are provided', () => {
+    // arrange
+    const expectedLevelsInError = getAllPossibleRecommendationLevels()
+      .map((level) => getDisplayName(level));
+    const scripts: Script[] = [];
+
+    // act
+    const act = () => test(scripts);
+
+    // assert
+    const actualErrorMessage = collectExceptionMessage(act);
+    expectedLevelsInError.forEach((expectedLevelInError) => {
+      expect(actualErrorMessage).to.include(expectedLevelInError);
+    });
+  });
+});
+
+function test(allScripts: Script[]):
+ReturnType<typeof ensurePresenceOfAllRecommendationLevels> {
+  const context = new CategoryCollectionValidationContextStub()
+    .withAllScripts(allScripts);
+  return ensurePresenceOfAllRecommendationLevels(context);
+}
+
+function getAllPossibleRecommendationLevels(): readonly (RecommendationLevel | undefined)[] {
+  return [
+    ...getEnumValues(RecommendationLevel),
+    undefined,
+  ];
+}
+
+function getDisplayName(level: RecommendationLevel | undefined): string {
+  return level === undefined ? 'None' : RecommendationLevel[level];
+}

tests/unit/domain/Collection/Validation/Rules/EnsurePresenceOfAtLeastOneCategory.spec.ts

@@ -0,0 +1,39 @@
+import { describe, it, expect } from 'vitest';
+import { CategoryCollectionValidationContextStub } from '@tests/unit/shared/Stubs/CategoryCollectionValidationContextStub';
+import type { Category } from '@/domain/Executables/Category/Category';
+import { ensurePresenceOfAtLeastOneCategory } from '@/domain/Collection/Validation/Rules/EnsurePresenceOfAtLeastOneCategory';
+import { CategoryStub } from '@tests/unit/shared/Stubs/CategoryStub';
+
+describe('ensurePresenceOfAtLeastOneCategory', () => {
+  it('throws an error when no categories are present', () => {
+    // arrange
+    const expectedErrorMessage = 'Collection must have at least one category';
+    const categories: Category[] = [];
+
+    // act
+    const act = () => test(categories);
+
+    // assert
+    expect(act).to.throw(expectedErrorMessage);
+  });
+
+  it('does not throw an error when at least one category is present', () => {
+    // arrange
+    const categories: Category[] = [
+      new CategoryStub('existing-category'),
+    ];
+
+    // act
+    const act = () => test(categories);
+
+    // assert
+    expect(act).not.to.throw();
+  });
+});
+
+function test(allCategories: readonly Category[]):
+ReturnType<typeof ensurePresenceOfAtLeastOneCategory> {
+  const context = new CategoryCollectionValidationContextStub()
+    .withAllCategories(allCategories);
+  return ensurePresenceOfAtLeastOneCategory(context);
+}

tests/unit/domain/Collection/Validation/Rules/EnsurePresenceOfAtLeastOneScript.spec.ts

@@ -0,0 +1,39 @@
+import { describe, it, expect } from 'vitest';
+import { CategoryCollectionValidationContextStub } from '@tests/unit/shared/Stubs/CategoryCollectionValidationContextStub';
+import type { Script } from '@/domain/Executables/Script/Script';
+import { ensurePresenceOfAtLeastOneScript } from '@/domain/Collection/Validation/Rules/EnsurePresenceOfAtLeastOneScript';
+import { ScriptStub } from '@tests/unit/shared/Stubs/ScriptStub';
+
+describe('ensurePresenceOfAtLeastOneScript', () => {
+  it('throws an error when no scripts are present', () => {
+    // arrange
+    const expectedErrorMessage = 'Collection must have at least one script';
+    const scripts: Script[] = [];
+
+    // act
+    const act = () => test(scripts);
+
+    // assert
+    expect(act).to.throw(expectedErrorMessage);
+  });
+
+  it('does not throw an error when at least one category is present', () => {
+    // arrange
+    const scripts: Script[] = [
+      new ScriptStub('existing-script'),
+    ];
+
+    // act
+    const act = () => test(scripts);
+
+    // assert
+    expect(act).not.to.throw();
+  });
+});
+
+function test(allScripts: readonly Script[]):
+ReturnType<typeof ensurePresenceOfAtLeastOneScript> {
+  const context = new CategoryCollectionValidationContextStub()
+    .withAllScripts(allScripts);
+  return ensurePresenceOfAtLeastOneScript(context);
+}

tests/unit/domain/Collection/Validation/Rules/EnsureUniqueIdsAcrossExecutables.spec.ts

@@ -0,0 +1,146 @@
+import { describe, it, expect } from 'vitest';
+import { ensureUniqueIdsAcrossExecutables } from '@/domain/Collection/Validation/Rules/EnsureUniqueIdsAcrossExecutables';
+import type { Category } from '@/domain/Executables/Category/Category';
+import type { Script } from '@/domain/Executables/Script/Script';
+import { CategoryCollectionValidationContextStub } from '@tests/unit/shared/Stubs/CategoryCollectionValidationContextStub';
+import { CategoryStub } from '@tests/unit/shared/Stubs/CategoryStub';
+import { ScriptStub } from '@tests/unit/shared/Stubs/ScriptStub';
+import type { ExecutableId } from '@/domain/Executables/Identifiable';
+
+describe('ensureUniqueIdsAcrossExecutables', () => {
+  it('does not throw an error when all IDs are unique', () => {
+    // arrange
+    const testData: TestData = {
+      categories: [
+        new CategoryStub('category1'),
+        new CategoryStub('category2'),
+      ],
+      scripts: [
+        new ScriptStub('script1'),
+        new ScriptStub('script2'),
+      ],
+    };
+
+    // act
+    const act = () => test(testData);
+
+    // assert
+    expect(act).to.not.throw();
+  });
+
+  it('throws an error when duplicate IDs are found across categories and scripts', () => {
+    // arrange
+    const duplicateId: ExecutableId = 'duplicate';
+    const expectedErrorMessage = `Duplicate executable IDs found: "${duplicateId}"`;
+    const testData: TestData = {
+      categories: [
+        new CategoryStub(duplicateId),
+        new CategoryStub('category2'),
+      ],
+      scripts: [
+        new ScriptStub(duplicateId),
+        new ScriptStub('script2'),
+      ],
+    };
+
+    // act
+    const act = () => test(testData);
+
+    // assert
+    expect(act).to.throw(expectedErrorMessage);
+  });
+
+  it('throws an error when duplicate IDs are found within categories', () => {
+    // arrange
+    const duplicateId: ExecutableId = 'duplicate';
+    const expectedErrorMessage = `Duplicate executable IDs found: "${duplicateId}"`;
+    const testData: TestData = {
+      categories: [
+        new CategoryStub(duplicateId),
+        new CategoryStub(duplicateId),
+      ],
+      scripts: [
+        new ScriptStub('script1'),
+        new ScriptStub('script2'),
+      ],
+    };
+
+    // act
+    const act = () => test(testData);
+
+    // assert
+    expect(act).to.throw(expectedErrorMessage);
+  });
+
+  it('throws an error when duplicate IDs are found within scripts', () => {
+    // arrange
+    const duplicateId: ExecutableId = 'duplicate';
+    const expectedErrorMessage = `Duplicate executable IDs found: "${duplicateId}"`;
+    const testData: TestData = {
+      categories: [
+        new CategoryStub('category1'),
+        new CategoryStub('category2'),
+      ],
+      scripts: [
+        new ScriptStub(duplicateId),
+        new ScriptStub(duplicateId),
+      ],
+    };
+
+    // act
+    const act = () => test(testData);
+
+    // assert
+    expect(act).to.throw(expectedErrorMessage);
+  });
+
+  it('throws an error with multiple duplicate IDs', () => {
+    // arrange
+    const duplicateId1: ExecutableId = 'duplicate-1';
+    const duplicateId2: ExecutableId = 'duplicate-2';
+    const expectedErrorMessage = `Duplicate executable IDs found: "${duplicateId1}", "${duplicateId2}"`;
+    const testData: TestData = {
+      categories: [
+        new CategoryStub(duplicateId1),
+        new CategoryStub(duplicateId2),
+      ],
+      scripts: [
+        new ScriptStub(duplicateId1),
+        new ScriptStub(duplicateId2),
+      ],
+    };
+
+    // act
+    const act = () => test(testData);
+
+    // assert
+    expect(act).to.throw(expectedErrorMessage);
+  });
+
+  it('handles empty categories and scripts arrays', () => {
+    // arrange
+    const testData: TestData = {
+      categories: [],
+      scripts: [],
+    };
+
+    // act
+    const act = () => test(testData);
+
+    // assert
+    expect(act).to.not.throw();
+  });
+});
+
+interface TestData {
+  readonly categories: readonly Category[];
+  readonly scripts: readonly Script[];
+}
+
+function test(testData: TestData):
+ReturnType<typeof ensureUniqueIdsAcrossExecutables> {
+  const context = new CategoryCollectionValidationContextStub()
+    .withAllCategories(testData.categories)
+    .withAllScripts(testData.scripts);
+  return ensureUniqueIdsAcrossExecutables(context);
+}