Refactor code-style

wooorm · wooorm · commit ca404c77d727 · 2023-08-05T09:47:55.000+02:00
diff --git a/lib/index.js b/lib/index.js
@@ -1,15 +1,19 @@
 /**
- * @typedef {import('vfile').VFile} VFile
- * @typedef {import('property-information').Schema} Schema
- * @typedef {import('unist').Position} Position
- * @typedef {import('unist').Point} Point
  * @typedef {import('hast').Element} Element
+ * @typedef {import('hast').Nodes} Nodes
  * @typedef {import('hast').Root} Root
  * @typedef {import('hast').RootContent} RootContent
- * @typedef {import('hast').Nodes} Nodes
+ *
  * @typedef {import('parse5').DefaultTreeAdapterMap} DefaultTreeAdapterMap
  * @typedef {import('parse5').Token.ElementLocation} P5ElementLocation
  * @typedef {import('parse5').Token.Location} P5Location
+ *
+ * @typedef {import('property-information').Schema} Schema
+ *
+ * @typedef {import('unist').Point} Point
+ * @typedef {import('unist').Position} Position
+ *
+ * @typedef {import('vfile').VFile} VFile
  */
 
 /**
@@ -21,42 +25,45 @@
  * @typedef {DefaultTreeAdapterMap['element']} P5Element
  * @typedef {DefaultTreeAdapterMap['node']} P5Node
  * @typedef {DefaultTreeAdapterMap['template']} P5Template
- *
- * @typedef {'html' | 'svg'} Space
- *   Namespace.
- *
+ */
+
+/**
  * @typedef Options
  *   Configuration.
  * @property {Space | null | undefined} [space='html']
- *   Which space the document is in.
+ *   Which space the document is in (default: `'html'`).
  *
  *   When an `<svg>` element is found in the HTML space, this package already
  *   automatically switches to and from the SVG space when entering and exiting
  *   it.
  * @property {VFile | null | undefined} [file]
- *   File used to add positional info to nodes.
+ *   File used to add positional info to nodes (optional).
  *
  *   If given, the file should represent the original HTML source.
  * @property {boolean} [verbose=false]
  *   Whether to add extra positional info about starting tags, closing tags,
- *   and attributes to elements.
+ *   and attributes to elements (default: `false`).
  *
  *   > 👉 **Note**: only used when `file` is given.
  *
+ * @typedef {'html' | 'svg'} Space
+ *   Namespace.
+ *
  * @typedef State
  *   Info passed around about the current state.
- * @property {Schema} schema
- *   Current schema.
  * @property {VFile | undefined} file
  *   Corresponding file.
- * @property {boolean | undefined} verbose
- *   Add extra positional info.
  * @property {boolean} location
  *   Whether location info was found.
+ * @property {Schema} schema
+ *   Current schema.
+ * @property {boolean | undefined} verbose
+ *   Add extra positional info.
  */
 
+import {ok as assert} from 'devlop'
 import {h, s} from 'hastscript'
-import {html, svg, find} from 'property-information'
+import {find, html, svg} from 'property-information'
 import {location} from 'vfile-location'
 import {webNamespaces} from 'web-namespaces'
 
@@ -71,7 +78,7 @@ const proto = Object.prototype
  * @param {P5Node} tree
  *   `parse5` tree to transform.
  * @param {Options | VFile | null | undefined} [options]
- *   Configuration.
+ *   Configuration (optional).
  * @returns {Nodes}
  *   hast tree.
  */
@@ -92,10 +99,10 @@ export function fromParse5(tree, options) {
 
   return one(
     {
-      schema: settings.space === 'svg' ? svg : html,
       file,
-      verbose: settings.verbose,
-      location: false
+      location: false,
+      schema: settings.space === 'svg' ? svg : html,
+      verbose: settings.verbose
     },
     tree
   )
@@ -142,7 +149,9 @@ function one(state, node) {
         const loc = location(doc)
         const start = loc.toPoint(0)
         const end = loc.toPoint(doc.length)
-        // @ts-expect-error: always defined as we give valid input.
+        // Always defined as we give valid input.
+        assert(start, 'expected `start`')
+        assert(end, 'expected `end`')
         result.position = {start, end}
       }
 
@@ -185,14 +194,15 @@ function one(state, node) {
 function all(state, nodes) {
   let index = -1
   /** @type {Array<RootContent>} */
-  const result = []
+  const results = []
 
   while (++index < nodes.length) {
-    // @ts-expect-error Assume no roots in `nodes`.
-    result[index] = one(state, nodes[index])
+    // Assume no roots in `nodes`.
+    const result = /** @type {RootContent} */ (one(state, nodes[index]))
+    results.push(result)
   }
 
-  return result
+  return results
 }
 
 /**
@@ -236,9 +246,8 @@ function element(state, node) {
     const startTag = pos && pos.startTag && position(pos.startTag)
     const endTag = pos && pos.endTag && position(pos.endTag)
 
-    /** @type {Root} */
-    // @ts-expect-error Types are wrong.
-    const content = one(state, reference.content)
+    // Root in, root out.
+    const content = /** @type {Root} */ (one(state, reference.content))
 
     if (startTag && endTag && state.file) {
       content.position = {start: startTag.end, end: endTag.start}
@@ -261,7 +270,7 @@ function element(state, node) {
  *   p5 node.
  * @param {Nodes} to
  *   hast node.
- * @returns {void}
+ * @returns {undefined}
  *   Nothing.
  */
 function patch(state, from, to) {
@@ -321,14 +330,15 @@ function createLocation(state, node, location) {
         }
       }
 
-      node.data = {
-        position: {
-          // @ts-expect-error: assume not `undefined`.
-          opening: position(location.startTag),
-          closing: location.endTag ? position(location.endTag) : null,
-          properties: props
-        }
-      }
+      assert(location.startTag, 'a start tag should exist')
+      const opening = position(location.startTag)
+      const closing = location.endTag ? position(location.endTag) : undefined
+      /** @type {Record<string, unknown>} */
+      const data = {opening}
+      if (closing) data.closing = closing
+      data.properties = props
+
+      node.data = {position: data}
     }
   }
 
@@ -354,7 +364,9 @@ function position(loc) {
     column: loc.endCol,
     offset: loc.endOffset
   })
-  // @ts-expect-error `undefined` is fine.
+
+  // @ts-expect-error: we do use `undefined` for points if one or the other
+  // exists.
   return start || end ? {start, end} : undefined
 }
 
diff --git a/package.json b/package.json
@@ -35,6 +35,7 @@
   "dependencies": {
     "@types/hast": "^3.0.0",
     "@types/unist": "^3.0.0",
+    "devlop": "^1.0.0",
     "hastscript": "^8.0.0",
     "property-information": "^6.0.0",
     "vfile": "^6.0.0",
diff --git a/test/fixtures/attributes/index.json b/test/fixtures/attributes/index.json
@@ -221,7 +221,6 @@
                       "offset": 90
                     }
                   },
-                  "closing": null,
                   "properties": {
                     "alt": {
                       "start": {
diff --git a/test/fixtures/element-void-close/index.json b/test/fixtures/element-void-close/index.json
@@ -36,7 +36,6 @@
                       "offset": 4
                     }
                   },
-                  "closing": null,
                   "properties": {}
                 }
               },
@@ -110,7 +109,6 @@
                       "offset": 19
                     }
                   },
-                  "closing": null,
                   "properties": {}
                 }
               },
diff --git a/test/fixtures/element-void/index.json b/test/fixtures/element-void/index.json
@@ -40,7 +40,6 @@
                       "offset": 60
                     }
                   },
-                  "closing": null,
                   "properties": {
                     "src": {
                       "start": {
@@ -129,7 +128,6 @@
                       "offset": 66
                     }
                   },
-                  "closing": null,
                   "properties": {}
                 }
               },
@@ -202,7 +200,6 @@
                           "offset": 80
                         }
                       },
-                      "closing": null,
                       "properties": {}
                     }
                   },
@@ -334,7 +331,6 @@
                           "offset": 105
                         }
                       },
-                      "closing": null,
                       "properties": {}
                     }
                   },
@@ -465,7 +461,6 @@
                                       "offset": 147
                                     }
                                   },
-                                  "closing": null,
                                   "properties": {}
                                 }
                               },
@@ -497,7 +492,6 @@
                                   "offset": 141
                                 }
                               },
-                              "closing": null,
                               "properties": {}
                             }
                           },
@@ -529,7 +523,6 @@
                               "offset": 138
                             }
                           },
-                          "closing": null,
                           "properties": {}
                         }
                       },
@@ -561,7 +554,6 @@
                           "offset": 130
                         }
                       },
-                      "closing": null,
                       "properties": {}
                     }
                   },
@@ -661,7 +653,6 @@
                           "offset": 167
                         }
                       },
-                      "closing": null,
                       "properties": {}
                     }
                   },
@@ -697,7 +688,6 @@
                           "offset": 176
                         }
                       },
-                      "closing": null,
                       "properties": {}
                     }
                   },
@@ -733,7 +723,6 @@
                           "offset": 180
                         }
                       },
-                      "closing": null,
                       "properties": {}
                     }
                   },
@@ -769,7 +758,6 @@
                           "offset": 187
                         }
                       },
-                      "closing": null,
                       "properties": {}
                     }
                   },
@@ -879,7 +867,6 @@
                                   "offset": 229
                                 }
                               },
-                              "closing": null,
                               "properties": {}
                             }
                           },
@@ -911,7 +898,6 @@
                               "offset": 217
                             }
                           },
-                          "closing": null,
                           "properties": {}
                         }
                       },
@@ -943,7 +929,6 @@
                           "offset": 209
                         }
                       },
-                      "closing": null,
                       "properties": {}
                     }
                   },
@@ -1043,7 +1028,6 @@
                           "offset": 253
                         }
                       },
-                      "closing": null,
                       "properties": {}
                     }
                   },
@@ -1079,7 +1063,6 @@
                           "offset": 262
                         }
                       },
-                      "closing": null,
                       "properties": {}
                     }
                   },
@@ -1115,7 +1098,6 @@
                           "offset": 275
                         }
                       },
-                      "closing": null,
                       "properties": {}
                     }
                   },
diff --git a/test/fixtures/simple/index.json b/test/fixtures/simple/index.json
@@ -167,7 +167,6 @@
                       "offset": 51
                     }
                   },
-                  "closing": null,
                   "properties": {
                     "id": {
                       "start": {
diff --git a/test/fixtures/svg/index.json b/test/fixtures/svg/index.json
@@ -89,7 +89,6 @@
                               "offset": 187
                             }
                           },
-                          "closing": null,
                           "properties": {
                             "cx": {
                               "start": {
@@ -195,7 +194,6 @@
                               "offset": 238
                             }
                           },
-                          "closing": null,
                           "properties": {
                             "cx": {
                               "start": {
diff --git a/test/fixtures/template/index.json b/test/fixtures/template/index.json
diff --git a/test/index.js b/test/index.js

Original file line number	Diff line number	Diff line change
`@@ -221,7 +221,6 @@`
`221`	`221`	`"offset": 90`
`222`	`222`	`}`
`223`	`223`	`},`
`224`		`- "closing": null,`
`225`	`224`	`"properties": {`
`226`	`225`	`"alt": {`
`227`	`226`	`"start": {`
Original file line number	Diff line number	Diff line change
`@@ -36,7 +36,6 @@`
`36`	`36`	`"offset": 4`
`37`	`37`	`}`
`38`	`38`	`},`
`39`		`- "closing": null,`
`40`	`39`	`"properties": {}`
`41`	`40`	`}`
`42`	`41`	`},`
`@@ -110,7 +109,6 @@`
`110`	`109`	`"offset": 19`
`111`	`110`	`}`
`112`	`111`	`},`
`113`		`- "closing": null,`
`114`	`112`	`"properties": {}`
`115`	`113`	`}`
`116`	`114`	`},`
Original file line number	Diff line number	Diff line change
`@@ -40,7 +40,6 @@`
`40`	`40`	`"offset": 60`
`41`	`41`	`}`
`42`	`42`	`},`
`43`		`- "closing": null,`
`44`	`43`	`"properties": {`
`45`	`44`	`"src": {`
`46`	`45`	`"start": {`
`@@ -129,7 +128,6 @@`
`129`	`128`	`"offset": 66`
`130`	`129`	`}`
`131`	`130`	`},`
`132`		`- "closing": null,`
`133`	`131`	`"properties": {}`
`134`	`132`	`}`
`135`	`133`	`},`
`@@ -202,7 +200,6 @@`
`202`	`200`	`"offset": 80`
`203`	`201`	`}`
`204`	`202`	`},`
`205`		`- "closing": null,`
`206`	`203`	`"properties": {}`
`207`	`204`	`}`
`208`	`205`	`},`
`@@ -334,7 +331,6 @@`
`334`	`331`	`"offset": 105`
`335`	`332`	`}`
`336`	`333`	`},`
`337`		`- "closing": null,`
`338`	`334`	`"properties": {}`
`339`	`335`	`}`
`340`	`336`	`},`
`@@ -465,7 +461,6 @@`
`465`	`461`	`"offset": 147`
`466`	`462`	`}`
`467`	`463`	`},`
`468`		`- "closing": null,`
`469`	`464`	`"properties": {}`
`470`	`465`	`}`
`471`	`466`	`},`
`@@ -497,7 +492,6 @@`
`497`	`492`	`"offset": 141`
`498`	`493`	`}`
`499`	`494`	`},`
`500`		`- "closing": null,`
`501`	`495`	`"properties": {}`
`502`	`496`	`}`
`503`	`497`	`},`
`@@ -529,7 +523,6 @@`
`529`	`523`	`"offset": 138`
`530`	`524`	`}`
`531`	`525`	`},`
`532`		`- "closing": null,`
`533`	`526`	`"properties": {}`
`534`	`527`	`}`
`535`	`528`	`},`
`@@ -561,7 +554,6 @@`
`561`	`554`	`"offset": 130`
`562`	`555`	`}`
`563`	`556`	`},`
`564`		`- "closing": null,`
`565`	`557`	`"properties": {}`
`566`	`558`	`}`
`567`	`559`	`},`
`@@ -661,7 +653,6 @@`
`661`	`653`	`"offset": 167`
`662`	`654`	`}`
`663`	`655`	`},`
`664`		`- "closing": null,`
`665`	`656`	`"properties": {}`
`666`	`657`	`}`
`667`	`658`	`},`
`@@ -697,7 +688,6 @@`
`697`	`688`	`"offset": 176`
`698`	`689`	`}`
`699`	`690`	`},`
`700`		`- "closing": null,`
`701`	`691`	`"properties": {}`
`702`	`692`	`}`
`703`	`693`	`},`
`@@ -733,7 +723,6 @@`
`733`	`723`	`"offset": 180`
`734`	`724`	`}`
`735`	`725`	`},`
`736`		`- "closing": null,`
`737`	`726`	`"properties": {}`
`738`	`727`	`}`
`739`	`728`	`},`
`@@ -769,7 +758,6 @@`
`769`	`758`	`"offset": 187`
`770`	`759`	`}`
`771`	`760`	`},`
`772`		`- "closing": null,`
`773`	`761`	`"properties": {}`
`774`	`762`	`}`
`775`	`763`	`},`
`@@ -879,7 +867,6 @@`
`879`	`867`	`"offset": 229`
`880`	`868`	`}`
`881`	`869`	`},`
`882`		`- "closing": null,`
`883`	`870`	`"properties": {}`
`884`	`871`	`}`
`885`	`872`	`},`
`@@ -911,7 +898,6 @@`
`911`	`898`	`"offset": 217`
`912`	`899`	`}`
`913`	`900`	`},`
`914`		`- "closing": null,`
`915`	`901`	`"properties": {}`
`916`	`902`	`}`
`917`	`903`	`},`
`@@ -943,7 +929,6 @@`
`943`	`929`	`"offset": 209`
`944`	`930`	`}`
`945`	`931`	`},`
`946`		`- "closing": null,`
`947`	`932`	`"properties": {}`
`948`	`933`	`}`
`949`	`934`	`},`
`@@ -1043,7 +1028,6 @@`
`1043`	`1028`	`"offset": 253`
`1044`	`1029`	`}`
`1045`	`1030`	`},`
`1046`		`- "closing": null,`
`1047`	`1031`	`"properties": {}`
`1048`	`1032`	`}`
`1049`	`1033`	`},`
`@@ -1079,7 +1063,6 @@`
`1079`	`1063`	`"offset": 262`
`1080`	`1064`	`}`
`1081`	`1065`	`},`
`1082`		`- "closing": null,`
`1083`	`1066`	`"properties": {}`
`1084`	`1067`	`}`
`1085`	`1068`	`},`
`@@ -1115,7 +1098,6 @@`
`1115`	`1098`	`"offset": 275`
`1116`	`1099`	`}`
`1117`	`1100`	`},`
`1118`		`- "closing": null,`
`1119`	`1101`	`"properties": {}`
`1120`	`1102`	`}`
`1121`	`1103`	`},`
Original file line number	Diff line number	Diff line change
`@@ -167,7 +167,6 @@`
`167`	`167`	`"offset": 51`
`168`	`168`	`}`
`169`	`169`	`},`
`170`		`- "closing": null,`
`171`	`170`	`"properties": {`
`172`	`171`	`"id": {`
`173`	`172`	`"start": {`