@nordcraft/search 1.0.0

package/src/rules/dom/createRequiredDirectParentRule.test.ts

@@ -0,0 +1,124 @@
+import { searchProject } from '../../searchProject'
+import { createRequiredDirectParentRule } from './createRequiredDirectParentRule'
+
+describe('createRequiredDirectParentRule', () => {
+  test('should detect wrong direct parent', () => {
+    const problems = Array.from(
+      searchProject({
+        files: {
+          formulas: {},
+          components: {
+            test: {
+              name: 'test',
+              nodes: {
+                root: {
+                  type: 'element',
+                  attrs: {},
+                  classes: {},
+                  events: {},
+                  tag: 'div',
+                  children: ['child1', 'child2'],
+                  style: {},
+                },
+                child1: {
+                  type: 'element',
+                  attrs: {},
+                  classes: {},
+                  events: {},
+                  tag: 'li',
+                  children: [],
+                  style: {},
+                },
+                child2: {
+                  type: 'element',
+                  attrs: {},
+                  classes: {},
+                  events: {},
+                  tag: 'li',
+                  children: [],
+                  style: {},
+                },
+              },
+              formulas: {},
+              apis: {},
+              attributes: {},
+              variables: {},
+            },
+          },
+        },
+        rules: [
+          createRequiredDirectParentRule(
+            ['ul', 'ol'],
+            ['li', 'script', 'template'],
+          ),
+        ],
+      }),
+    )
+
+    expect(problems).toHaveLength(2)
+    expect(problems[0].code).toBe('required direct parent')
+    expect(problems[0].path).toEqual(['components', 'test', 'nodes', 'child1'])
+    expect(problems[0].details).toEqual({
+      parentTag: 'div',
+      childTag: 'li',
+      allowedParentTags: ['ul', 'ol'],
+    })
+    expect(problems[1].code).toBe('required direct parent')
+    expect(problems[1].path).toEqual(['components', 'test', 'nodes', 'child2'])
+    expect(problems[1].details).toEqual({
+      parentTag: 'div',
+      childTag: 'li',
+      allowedParentTags: ['ul', 'ol'],
+    })
+  })
+  test('should not detect valid direct parent', () => {
+    const problems = Array.from(
+      searchProject({
+        files: {
+          formulas: {},
+          components: {
+            test: {
+              name: 'test',
+              nodes: {
+                root: {
+                  type: 'element',
+                  attrs: {},
+                  classes: {},
+                  events: {},
+                  tag: 'ul',
+                  children: ['child1', 'child2'],
+                  style: {},
+                },
+                child1: {
+                  type: 'element',
+                  attrs: {},
+                  classes: {},
+                  events: {},
+                  tag: 'li',
+                  children: [],
+                  style: {},
+                },
+                child2: {
+                  type: 'element',
+                  attrs: {},
+                  classes: {},
+                  events: {},
+                  tag: 'li',
+                  children: [],
+                  style: {},
+                },
+              },
+              formulas: {},
+              apis: {},
+              attributes: {},
+              variables: {},
+            },
+          },
+        },
+        rules: [createRequiredDirectParentRule(['ul'], ['li'])],
+      }),
+    )
+
+    expect(problems).toHaveLength(0)
+  })
+})

package/src/rules/dom/createRequiredDirectParentRule.ts

@@ -0,0 +1,41 @@
+import type { Level, Rule } from '../../types'
+
+export function createRequiredDirectParentRule(
+  parentTags: string[],
+  childTags: string[],
+  level: Level = 'warning',
+): Rule<{
+  parentTag: string
+  childTag: string
+  allowedParentTags: string[]
+}> {
+  return {
+    code: 'required direct parent',
+    level,
+    category: 'Accessibility',
+    visit: (report, args) => {
+      if (args.nodeType !== 'component-node') {
+        return
+      }
+      const { value, component, path } = args
+      if (value.type !== 'element' || !childTags.includes(value.tag)) {
+        return
+      }
+      const nodeId = String(args.path[args.path.length - 1])
+      const parent = Object.values(component.nodes).find(
+        (node) => node.type === 'element' && node.children.includes(nodeId),
+      )
+      if (
+        parent &&
+        parent.type === 'element' &&
+        !parentTags.includes(parent.tag)
+      ) {
+        report(path, {
+          parentTag: parent.tag,
+          childTag: value.tag,
+          allowedParentTags: parentTags,
+        })
+      }
+    },
+  }
+}

package/src/rules/dom/createRequiredElementAttributeRule.test.ts

@@ -0,0 +1,39 @@
+import { searchProject } from '../../searchProject'
+import { createRequiredElementAttributeRule } from './createRequiredElementAttributeRule'
+
+describe('requiredElementAttributeRule', () => {
+  test('should detect missing required element attribute', () => {
+    const problems = Array.from(
+      searchProject({
+        files: {
+          formulas: {},
+          components: {
+            test: {
+              name: 'test',
+              nodes: {
+                root: {
+                  type: 'element',
+                  attrs: {},
+                  classes: {},
+                  events: {},
+                  tag: 'img',
+                  children: [],
+                  style: {},
+                },
+              },
+              formulas: {},
+              apis: {},
+              attributes: {},
+              variables: {},
+            },
+          },
+        },
+        rules: [createRequiredElementAttributeRule('img', 'alt')],
+      }),
+    )
+
+    expect(problems).toHaveLength(1)
+    expect(problems[0].code).toBe('required element attribute')
+    expect(problems[0].path).toEqual(['components', 'test', 'nodes', 'root'])
+  })
+})

package/src/rules/dom/createRequiredElementAttributeRule.ts

@@ -0,0 +1,27 @@
+import { isDefined } from '@nordcraft/core/dist/utils/util'
+import type { Level, Rule } from '../../types'
+
+export function createRequiredElementAttributeRule(
+  tag: string,
+  attribute: string,
+  level: Level = 'warning',
+): Rule<{
+  tag: string
+  attribute: string
+}> {
+  return {
+    code: 'required element attribute',
+    level: level,
+    category: 'Accessibility',
+    visit: (report, { path, nodeType, value }) => {
+      if (
+        nodeType === 'component-node' &&
+        value.type === 'element' &&
+        value.tag === tag &&
+        !isDefined(value.attrs[attribute])
+      ) {
+        report(path, { tag, attribute })
+      }
+    },
+  }
+}

package/src/rules/dom/createRequiredMetaTagRule.test.ts

@@ -0,0 +1,76 @@
+import { searchProject } from '../../searchProject'
+import { createRequiredMetaTagRule } from './createRequiredMetaTagRule'
+
+describe('createRequiredMetaTagRule', () => {
+  test('should detect missing required meta tag', () => {
+    const problems = Array.from(
+      searchProject({
+        files: {
+          formulas: {},
+          components: {
+            'test-page': {
+              name: 'test-page',
+              nodes: {},
+              formulas: {},
+              apis: {},
+              attributes: {},
+              variables: {},
+              route: {
+                info: {
+                  title: { formula: { type: 'value', value: null } },
+                },
+                path: [],
+                query: {},
+              },
+            },
+          },
+        },
+        rules: [
+          createRequiredMetaTagRule('title'),
+          createRequiredMetaTagRule('description'),
+        ],
+      }),
+    )
+
+    expect(problems).toHaveLength(2)
+    expect(problems[0].code).toBe('required meta tag')
+    expect(problems[0].details.tag).toEqual('title')
+    expect(problems[1].code).toBe('required meta tag')
+    expect(problems[1].details.tag).toEqual('description')
+  })
+  test('should not detect meta tags with required meta tag', () => {
+    const problems = Array.from(
+      searchProject({
+        files: {
+          formulas: {},
+          components: {
+            'test-page': {
+              name: 'test-page',
+              nodes: {},
+              formulas: {},
+              apis: {},
+              attributes: {},
+              variables: {},
+              route: {
+                info: {
+                  title: { formula: { type: 'value', value: 'some value' } },
+                  description: {
+                    formula: { type: 'and', arguments: [] },
+                  },
+                },
+                path: [],
+                query: {},
+              },
+            },
+          },
+        },
+        rules: [
+          createRequiredMetaTagRule('title'),
+          createRequiredMetaTagRule('description'),
+        ],
+      }),
+    )
+
+    expect(problems).toEqual([])
+  })
+})

package/src/rules/dom/createRequiredMetaTagRule.ts

@@ -0,0 +1,33 @@
+import { isFormula } from '@nordcraft/core/dist/formula/formula'
+import type { Level, Rule } from '../../types'
+
+export function createRequiredMetaTagRule(
+  tag: string,
+  level: Level = 'warning',
+): Rule<{
+  tag: string
+}> {
+  return {
+    code: 'required meta tag',
+    level: level,
+    category: 'SEO',
+    visit: (report, { path, nodeType, value }) => {
+      if (!(nodeType === 'component' && value.route)) {
+        return
+      }
+
+      const tagValue = value.route.info?.[tag as keyof typeof value.route.info]
+      const formula = isFormula(tagValue?.formula)
+        ? tagValue.formula
+        : undefined
+
+      if (
+        !tagValue ||
+        !formula ||
+        (formula.type === 'value' && !formula.value)
+      ) {
+        report(path, { tag: tag })
+      }
+    },
+  }
+}

package/src/rules/dom/imageWithoutDimensionRule.test.ts

@@ -0,0 +1,161 @@
+import { searchProject } from '../../searchProject'
+import { imageWithoutDimensionRule } from './imageWithoutDimensionRule'
+
+describe('imageWithoutDimensionRule', () => {
+  test('should detect missing image dimensions', () => {
+    const problems = Array.from(
+      searchProject({
+        files: {
+          formulas: {},
+          components: {
+            test: {
+              name: 'test',
+              nodes: {
+                root: {
+                  type: 'element',
+                  attrs: {},
+                  classes: {},
+                  events: {},
+                  tag: 'img',
+                  children: [],
+                  style: {},
+                },
+              },
+              formulas: {},
+              apis: {},
+              attributes: {},
+              variables: {},
+            },
+          },
+        },
+        rules: [imageWithoutDimensionRule],
+      }),
+    )
+
+    expect(problems).toHaveLength(1)
+    expect(problems[0].code).toBe('image without dimension')
+    expect(problems[0].path).toEqual(['components', 'test', 'nodes', 'root'])
+  })
+
+  test('should not detect image with explicit dimensions set', () => {
+    const problems = Array.from(
+      searchProject({
+        files: {
+          formulas: {},
+          components: {
+            test: {
+              name: 'test',
+              nodes: {
+                root: {
+                  type: 'element',
+                  attrs: {
+                    width: {
+                      type: 'value',
+                      value: '100',
+                    },
+                    height: {
+                      type: 'value',
+                      value: '100',
+                    },
+                  },
+                  classes: {},
+                  events: {},
+                  tag: 'img',
+                  children: [],
+                  style: {},
+                },
+              },
+              formulas: {},
+              apis: {},
+              attributes: {},
+              variables: {},
+            },
+          },
+        },
+        rules: [imageWithoutDimensionRule],
+      }),
+    )
+
+    expect(problems).toHaveLength(0)
+  })
+
+  test('should report if image has width but no height', () => {
+    const problems = Array.from(
+      searchProject({
+        files: {
+          formulas: {},
+          components: {
+            test: {
+              name: 'test',
+              nodes: {
+                root: {
+                  type: 'element',
+                  attrs: {
+                    width: {
+                      type: 'value',
+                      value: '100',
+                    },
+                  },
+                  classes: {},
+                  events: {},
+                  tag: 'source',
+                  children: [],
+                  style: {},
+                },
+              },
+              formulas: {},
+              apis: {},
+              attributes: {},
+              variables: {},
+            },
+          },
+        },
+        rules: [imageWithoutDimensionRule],
+      }),
+    )
+
+    expect(problems).toHaveLength(1)
+    expect(problems[0].code).toBe('image without dimension')
+    expect(problems[0].path).toEqual(['components', 'test', 'nodes', 'root'])
+  })
+
+  test('should report if image has height but no width', () => {
+    const problems = Array.from(
+      searchProject({
+        files: {
+          formulas: {},
+          components: {
+            test: {
+              name: 'test',
+              nodes: {
+                root: {
+                  type: 'element',
+                  attrs: {
+                    height: {
+                      type: 'value',
+                      value: '100',
+                    },
+                  },
+                  classes: {},
+                  events: {},
+                  tag: 'source',
+                  children: [],
+                  style: {},
+                },
+              },
+              formulas: {},
+              apis: {},
+              attributes: {},
+              variables: {},
+            },
+          },
+        },
+        rules: [imageWithoutDimensionRule],
+      }),
+    )
+
+    expect(problems).toHaveLength(1)
+    expect(problems[0].code).toBe('image without dimension')
+    expect(problems[0].path).toEqual(['components', 'test', 'nodes', 'root'])
+  })
+})

package/src/rules/dom/imageWithoutDimensionRule.ts

@@ -0,0 +1,50 @@
+import { isDefined } from '@nordcraft/core/dist/utils/util'
+import type { Rule } from '../../types'
+
+/**
+ * Lighthouse reports a similar issue:
+ * https://web.dev/articles/optimize-cls?utm_source=lighthouse&utm_medium=devtools#images_without_dimensions
+ */
+export const imageWithoutDimensionRule: Rule = {
+  code: 'image without dimension',
+  level: 'warning',
+  category: 'Performance',
+  visit: (report, { path, nodeType, value }) => {
+    if (
+      nodeType !== 'component-node' ||
+      value.type !== 'element' ||
+      !['img', 'source'].includes(value.tag)
+    ) {
+      return
+    }
+
+    // Aspect ratio can be calculated from width and height attributes
+    if (isDefined(value.attrs.width) && isDefined(value.attrs.height)) {
+      return
+    }
+
+    if (
+      [
+        value.style,
+        // We don't know the circumstances under which the style is applied, so we assume it is Okay if just one of the variants has correct style
+        ...(value.variants?.map((variant) => variant.style) ?? []),
+      ].some((style) => {
+        // Aspect ratio is not required if width and height are fixed
+        if (isDefined(style.width) && isDefined(style.height)) {
+          return true
+        }
+
+        // Aspect ratio is set explicitly
+        if (isDefined(style['aspect-ratio'])) {
+          return true
+        }
+
+        return false
+      })
+    ) {
+      return
+    }
+
+    report(path)
+  },
+}

package/src/rules/dom/nonEmptyVoidElementRule.test.ts

@@ -0,0 +1,82 @@
+import { searchProject } from '../../searchProject'
+import { nonEmptyVoidElementRule } from './nonEmptyVoidElementRule'
+
+describe('voidElementRule', () => {
+  test('should detect void elements with children', () => {
+    const problems = Array.from(
+      searchProject({
+        files: {
+          formulas: {},
+          components: {
+            test: {
+              name: 'test',
+              nodes: {
+                root: {
+                  type: 'element',
+                  attrs: {},
+                  classes: {},
+                  events: {},
+                  tag: 'img',
+                  children: ['other'],
+                  style: {},
+                },
+                other: {
+                  type: 'element',
+                  attrs: {},
+                  classes: {},
+                  events: {},
+                  tag: 'p',
+                  children: [],
+                  style: {},
+                },
+              },
+              formulas: {},
+              apis: {},
+              attributes: {},
+              variables: {},
+            },
+          },
+        },
+        rules: [nonEmptyVoidElementRule],
+      }),
+    )
+
+    expect(problems).toHaveLength(1)
+    expect(problems[0].code).toBe('non-empty void element')
+    expect(problems[0].details).toEqual({ tag: 'img' })
+    expect(problems[0].path).toEqual(['components', 'test', 'nodes', 'root'])
+  })
+
+  test('should not detect void elements with no children', () => {
+    const problems = Array.from(
+      searchProject({
+        files: {
+          formulas: {},
+          components: {
+            test: {
+              name: 'test',
+              nodes: {
+                root: {
+                  type: 'element',
+                  attrs: {},
+                  classes: {},
+                  events: {},
+                  tag: 'input',
+                  children: [],
+                  style: {},
+                },
+              },
+              formulas: {},
+              apis: {},
+              attributes: {},
+              variables: {},
+            },
+          },
+        },
+        rules: [nonEmptyVoidElementRule],
+      }),
+    )
+
+    expect(problems).toHaveLength(0)
+  })
+})

package/src/rules/dom/nonEmptyVoidElementRule.ts

@@ -0,0 +1,23 @@
+import type { Rule } from '../../types'
+
+import { VOID_HTML_ELEMENTS } from '@nordcraft/ssr/dist/const'
+/**
+ * See full list here
+ * https://developer.mozilla.org/en-US/docs/Glossary/Void_element
+ */
+export const nonEmptyVoidElementRule: Rule<{ tag: string }> = {
+  code: 'non-empty void element',
+  level: 'warning',
+  category: 'Quality',
+  visit: (report, { path, nodeType, value }) => {
+    if (
+      nodeType !== 'component-node' ||
+      value.type !== 'element' ||
+      value.children.length <= 0 ||
+      !VOID_HTML_ELEMENTS.includes(value.tag)
+    ) {
+      return
+    }
+    report(path, { tag: value.tag })
+  },
+}