Improve script/category name validation

- Use better error messages with more context.
- Unify their validation logic and share tests.
- Validate also type of the name.
- Refactor node (Script/Category) parser tests for easier future
  changes and cleaner test code (using `TestBuilder` to do dirty work in
  unified way).
- Add more tests. Custom `Error` properties are compared manually due to
  `chai` not supporting deep equality checks (chaijs/chai#1065,
  chaijs/chai#1405).

src/application/Parser/CategoryParser.ts

@@ -3,6 +3,8 @@ import type {
 } from '@/application/collections/';
 import { Script } from '@/domain/Script';
 import { Category } from '@/domain/Category';
+import { NodeValidator } from '@/application/Parser/NodeValidation/NodeValidator';
+import { NodeType } from '@/application/Parser/NodeValidation/NodeType';
 import { parseDocUrls } from './DocumentationParser';
 import { ICategoryCollectionParseContext } from './Script/ICategoryCollectionParseContext';
 import { parseScript } from './Script/ScriptParser';
@@ -12,35 +14,67 @@ let categoryIdCounter = 0;
 export function parseCategory(
   category: CategoryData,
   context: ICategoryCollectionParseContext,
+  factory: CategoryFactoryType = CategoryFactory,
 ): Category {
   if (!context) { throw new Error('missing context'); }
-  ensureValid(category);
+  return parseCategoryRecursively({
+    categoryData: category,
+    context,
+    factory,
+  });
+}
+
+interface ICategoryParseContext {
+  readonly categoryData: CategoryData,
+  readonly context: ICategoryCollectionParseContext,
+  readonly factory: CategoryFactoryType,
+  readonly parentCategory?: CategoryData,
+}
+// eslint-disable-next-line consistent-return
+function parseCategoryRecursively(context: ICategoryParseContext): Category {
+  ensureValidCategory(context.categoryData, context.parentCategory);
   const children: ICategoryChildren = {
     subCategories: new Array<Category>(),
     subScripts: new Array<Script>(),
   };
-  for (const data of category.children) {
-    parseCategoryChild(data, children, category, context);
+  for (const data of context.categoryData.children) {
+    parseNode({
+      nodeData: data,
+      children,
+      parent: context.categoryData,
+      factory: context.factory,
+      context: context.context,
+    });
+  }
+  try {
+    return context.factory(
+      /* id: */ categoryIdCounter++,
+      /* name: */ context.categoryData.category,
+      /* docs: */ parseDocUrls(context.categoryData),
+      /* categories: */ children.subCategories,
+      /* scripts: */ children.subScripts,
+    );
+  } catch (err) {
+    new NodeValidator({
+      type: NodeType.Category,
+      selfNode: context.categoryData,
+      parentNode: context.parentCategory,
+    }).throw(err.message);
   }
-  return new Category(
-    /* id: */ categoryIdCounter++,
-    /* name: */ category.category,
-    /* docs: */ parseDocUrls(category),
-    /* categories: */ children.subCategories,
-    /* scripts: */ children.subScripts,
-  );
 }
 
-function ensureValid(category: CategoryData) {
-  if (!category) {
-    throw Error('missing category');
-  }
-  if (!category.children || category.children.length === 0) {
-    throw Error(`category has no children: "${category.category}"`);
-  }
-  if (!category.category || category.category.length === 0) {
-    throw Error('category has no name');
-  }
+function ensureValidCategory(category: CategoryData, parentCategory?: CategoryData) {
+  new NodeValidator({
+    type: NodeType.Category,
+    selfNode: category,
+    parentNode: parentCategory,
+  })
+    .assertDefined(category)
+    .assertValidName(category.category)
+    .assert(
+      () => category.children && category.children.length > 0,
+      `"${category.category}" has no children.`,
+    );
 }
 
 interface ICategoryChildren {
@@ -48,22 +82,29 @@ interface ICategoryChildren {
   subScripts: Script[];
 }
 
-function parseCategoryChild(
-  data: CategoryOrScriptData,
-  children: ICategoryChildren,
-  parent: CategoryData,
-  context: ICategoryCollectionParseContext,
-) {
-  if (isCategory(data)) {
-    const subCategory = parseCategory(data as CategoryData, context);
-    children.subCategories.push(subCategory);
-  } else if (isScript(data)) {
-    const scriptData = data as ScriptData;
-    const script = parseScript(scriptData, context);
-    children.subScripts.push(script);
+interface INodeParseContext {
+  readonly nodeData: CategoryOrScriptData;
+  readonly children: ICategoryChildren;
+  readonly parent: CategoryData;
+  readonly factory: CategoryFactoryType;
+  readonly context: ICategoryCollectionParseContext;
+}
+function parseNode(context: INodeParseContext) {
+  const validator = new NodeValidator({ selfNode: context.nodeData, parentNode: context.parent });
+  validator.assertDefined(context.nodeData);
+  if (isCategory(context.nodeData)) {
+    const subCategory = parseCategoryRecursively({
+      categoryData: context.nodeData as CategoryData,
+      context: context.context,
+      factory: context.factory,
+      parentCategory: context.parent,
+    });
+    context.children.subCategories.push(subCategory);
+  } else if (isScript(context.nodeData)) {
+    const script = parseScript(context.nodeData as ScriptData, context.context);
+    context.children.subScripts.push(script);
   } else {
-    throw new Error(`Child element is neither a category or a script.
-                Parent: ${parent.category}, element: ${JSON.stringify(data)}`);
+    validator.throw('Node is neither a category or a script.');
   }
 }
 
@@ -73,14 +114,22 @@ function isScript(data: CategoryOrScriptData): data is ScriptData {
 }
 
 function isCategory(data: CategoryOrScriptData): data is CategoryData {
-  const { category } = data as CategoryData;
-  return category && category.length > 0;
+  return hasProperty(data, 'category');
 }
 
-function hasCode(holder: InstructionHolder): boolean {
-  return holder.code && holder.code.length > 0;
+function hasCode(data: InstructionHolder): boolean {
+  return hasProperty(data, 'code');
 }
 
-function hasCall(holder: InstructionHolder) {
-  return holder.call !== undefined;
+function hasCall(data: InstructionHolder) {
+  return hasProperty(data, 'call');
 }
+
+function hasProperty(object: unknown, propertyName: string) {
+  return Object.prototype.hasOwnProperty.call(object, propertyName);
+}
+
+export type CategoryFactoryType = (
+  ...parameters: ConstructorParameters<typeof Category>) => Category;
+
+const CategoryFactory: CategoryFactoryType = (...parameters) => new Category(...parameters);