Refactor to use @imports

dev/index.d.ts

@@ -1,14 +1,95 @@
-import type {Attribute, Directive} from './lib/html.js'
+import type {CompileContext} from 'micromark-util-types'
 
 export {directive} from './lib/syntax.js'
-export {
+export {directiveHtml} from './lib/html.js'
-  directiveHtml,
-  type Directive,
-  type Handle,
-  type HtmlOptions
-} from './lib/html.js'
 
+/**
+ * Internal tuple representing an attribute.
+ */
+type AttributeTuple = [key: string, value: string]
+
+/**
+ * Directive attribute.
+ */
+interface Attributes {
+  /**
+   * Key to value.
+   */
+  [key: string]: string
+}
+
+/**
+ * Structure representing a directive.
+ */
+export interface Directive {
+  /**
+   * Private :)
+   */
+  _fenceCount?: number | undefined
+  /**
+   * Object w/ HTML attributes.
+   */
+  attributes?: Attributes | undefined
+  /**
+   * Compiled HTML content inside container directive.
+   */
+  content?: string | undefined
+  /**
+   * Compiled HTML content that was in `[brackets]`.
+   */
+  label?: string | undefined
+  /**
+   * Name of directive.
+   */
+  name: string
+  /**
+   * Kind.
+   */
+  type: 'containerDirective' | 'leafDirective' | 'textDirective'
+}
+
+/**
+ * Handle a directive.
+ *
+ * @param this
+ *   Current context.
+ * @param directive
+ *   Directive.
+ * @returns
+ *   Signal whether the directive was handled.
+ *
+ *   Yield `false` to let the fallback (a special handle for `'*'`) handle it.
+ */
+export type Handle = (
+  this: CompileContext,
+  directive: Directive
+) => boolean | undefined
+
+/**
+ * Configuration.
+ *
+ * > 👉 **Note**: the special field `'*'` can be used to specify a fallback
+ * > handle to handle all otherwise unhandled directives.
+ */
+export interface HtmlOptions {
+  [name: string]: Handle
+}
+
+/**
+ * Augment types.
+ */
 declare module 'micromark-util-types' {
+  /**
+   * Compile data.
+   */
+  interface CompileData {
+    directiveAttributes?: Array<AttributeTuple>
+    directiveStack?: Array<Directive>
+  }
+
+  /**
+   * Token types.
+   */
   interface TokenTypeMap {
     directiveContainer: 'directiveContainer'
     directiveContainerAttributes: 'directiveContainerAttributes'
@@ -72,9 +153,4 @@ declare module 'micromark-util-types' {
     directiveTextMarker: 'directiveTextMarker'
     directiveTextName: 'directiveTextName'
   }
-
-  interface CompileData {
-    directiveAttributes?: Attribute[]
-    directiveStack?: Directive[]
-  }
 }

dev/lib/directive-container.js

@@ -1,9 +1,5 @@
 /**
- * @typedef {import('micromark-util-types').Construct} Construct
+ * @import {Construct, State, Token, TokenizeContext, Tokenizer} from 'micromark-util-types'
- * @typedef {import('micromark-util-types').State} State
- * @typedef {import('micromark-util-types').Token} Token
- * @typedef {import('micromark-util-types').TokenizeContext} TokenizeContext
- * @typedef {import('micromark-util-types').Tokenizer} Tokenizer
  */
 
 import {ok as assert} from 'devlop'

dev/lib/directive-leaf.js

@@ -1,8 +1,5 @@
 /**
- * @typedef {import('micromark-util-types').Construct} Construct
+ * @import {Construct, State, TokenizeContext, Tokenizer} from 'micromark-util-types'
- * @typedef {import('micromark-util-types').State} State
- * @typedef {import('micromark-util-types').TokenizeContext} TokenizeContext
- * @typedef {import('micromark-util-types').Tokenizer} Tokenizer
  */
 
 import {ok as assert} from 'devlop'

dev/lib/directive-text.js

@@ -1,9 +1,5 @@
 /**
- * @typedef {import('micromark-util-types').Construct} Construct
+ * @import {Construct, Previous, State, TokenizeContext, Tokenizer} from 'micromark-util-types'
- * @typedef {import('micromark-util-types').Previous} Previous
- * @typedef {import('micromark-util-types').State} State
- * @typedef {import('micromark-util-types').TokenizeContext} TokenizeContext
- * @typedef {import('micromark-util-types').Tokenizer} Tokenizer
  */
 
 import {ok as assert} from 'devlop'

dev/lib/factory-attributes.js

@@ -1,8 +1,5 @@
 /**
- * @typedef {import('micromark-util-types').Code} Code
+ * @import {Code, Effects, State, TokenType} from 'micromark-util-types'
- * @typedef {import('micromark-util-types').Effects} Effects
- * @typedef {import('micromark-util-types').State} State
- * @typedef {import('micromark-util-types').TokenType} TokenType
  */
 
 import {ok as assert} from 'devlop'

dev/lib/factory-label.js

@@ -1,8 +1,5 @@
 /**
- * @typedef {import('micromark-util-types').Effects} Effects
+ * @import {Code, Effects, State, Token, TokenType} from 'micromark-util-types'
- * @typedef {import('micromark-util-types').State} State
- * @typedef {import('micromark-util-types').Token} Token
- * @typedef {import('micromark-util-types').TokenType} TokenType
  */
 
 import {ok as assert} from 'devlop'

dev/lib/factory-name.js

@@ -1,8 +1,5 @@
 /**
- * @typedef {import('micromark-util-types').Effects} Effects
+ * @import {Code, Effects, State, TokenizeContext, TokenType} from 'micromark-util-types'
- * @typedef {import('micromark-util-types').State} State
- * @typedef {import('micromark-util-types').TokenizeContext} TokenizeContext
- * @typedef {import('micromark-util-types').TokenType} TokenType
  */
 
 import {asciiAlpha, asciiAlphanumeric} from 'micromark-util-character'

dev/lib/html.js

@@ -1,49 +1,6 @@
 /**
- * @typedef {import('micromark-util-types').CompileContext} CompileContext
+ * @import {Directive, HtmlOptions} from 'micromark-extension-directive'
- * @typedef {import('micromark-util-types').Handle} _Handle
+ * @import {CompileContext, Handle as MicromarkHandle, HtmlExtension} from 'micromark-util-types'
- * @typedef {import('micromark-util-types').HtmlExtension} HtmlExtension
- */
-
-/**
- * @typedef {[string, string]} Attribute
- *   Internal tuple representing an attribute.
- */
-
-/**
- * @typedef {Record<string, Handle>} HtmlOptions
- *   Configuration.
- *
- *   > 👉 **Note**: the special field `'*'` can be used to specify a fallback
- *   > handle to handle all otherwise unhandled directives.
- *
- * @callback Handle
- *   Handle a directive.
- * @param {CompileContext} this
- *   Current context.
- * @param {Directive} directive
- *   Directive.
- * @returns {boolean | undefined}
- *   Signal whether the directive was handled.
- *
- *   Yield `false` to let the fallback (a special handle for `'*'`) handle it.
- *
- * @typedef Directive
- *   Structure representing a directive.
- * @property {DirectiveType} type
- *   Kind.
- * @property {string} name
- *   Name of directive.
- * @property {string | undefined} [label]
- *   Compiled HTML content that was in `[brackets]`.
- * @property {Record<string, string> | undefined} [attributes]
- *   Object w/ HTML attributes.
- * @property {string | undefined} [content]
- *   Compiled HTML content inside container directive.
- * @property {number | undefined} [_fenceCount]
- *   Private :)
- *
- * @typedef {'containerDirective' | 'leafDirective' | 'textDirective'} DirectiveType
- *   Kind.
  */
 
 import {ok as assert} from 'devlop'
@@ -120,7 +77,7 @@ export function directiveHtml(options) {
 
   /**
    * @this {CompileContext}
-   * @param {DirectiveType} type
+   * @param {Directive['type']} type
    */
   function enter(type) {
     let stack = this.getData('directiveStack')
@@ -130,7 +87,7 @@ export function directiveHtml(options) {
 
   /**
    * @this {CompileContext}
-   * @type {_Handle}
+   * @type {MicromarkHandle}
    */
   function exitName(token) {
     const stack = this.getData('directiveStack')
@@ -140,7 +97,7 @@ export function directiveHtml(options) {
 
   /**
    * @this {CompileContext}
-   * @type {_Handle}
+   * @type {MicromarkHandle}
    */
   function enterLabel() {
     this.buffer()
@@ -148,7 +105,7 @@ export function directiveHtml(options) {
 
   /**
    * @this {CompileContext}
-   * @type {_Handle}
+   * @type {MicromarkHandle}
    */
   function exitLabel() {
     const data = this.resume()
@@ -159,7 +116,7 @@ export function directiveHtml(options) {
 
   /**
    * @this {CompileContext}
-   * @type {_Handle}
+   * @type {MicromarkHandle}
    */
   function enterAttributes() {
     this.buffer()
@@ -168,7 +125,7 @@ export function directiveHtml(options) {
 
   /**
    * @this {CompileContext}
-   * @type {_Handle}
+   * @type {MicromarkHandle}
    */
   function exitAttributeIdValue(token) {
     const attributes = this.getData('directiveAttributes')
@@ -183,7 +140,7 @@ export function directiveHtml(options) {
 
   /**
    * @this {CompileContext}
-   * @type {_Handle}
+   * @type {MicromarkHandle}
    */
   function exitAttributeClassValue(token) {
     const attributes = this.getData('directiveAttributes')
@@ -199,7 +156,7 @@ export function directiveHtml(options) {
 
   /**
    * @this {CompileContext}
-   * @type {_Handle}
+   * @type {MicromarkHandle}
    */
   function exitAttributeName(token) {
     // Attribute names in CommonMark are significantly limited, so character
@@ -212,7 +169,7 @@ export function directiveHtml(options) {
 
   /**
    * @this {CompileContext}
-   * @type {_Handle}
+   * @type {MicromarkHandle}
    */
   function exitAttributeValue(token) {
     const attributes = this.getData('directiveAttributes')
@@ -225,14 +182,14 @@ export function directiveHtml(options) {
 
   /**
    * @this {CompileContext}
-   * @type {_Handle}
+   * @type {MicromarkHandle}
    */
   function exitAttributes() {
     const stack = this.getData('directiveStack')
     assert(stack, 'expected directive stack')
     const attributes = this.getData('directiveAttributes')
     assert(attributes, 'expected attributes')
-    /** @type {Directive['attributes']} */
+    /** @type {Record<string, string>} */
     const cleaned = {}
     let index = -1
 
@@ -253,7 +210,7 @@ export function directiveHtml(options) {
 
   /**
    * @this {CompileContext}
-   * @type {_Handle}
+   * @type {MicromarkHandle}
    */
   function exitContainerContent() {
     const data = this.resume()
@@ -264,7 +221,7 @@ export function directiveHtml(options) {
 
   /**
    * @this {CompileContext}
-   * @type {_Handle}
+   * @type {MicromarkHandle}
    */
   function exitContainerFence() {
     const stack = this.getData('directiveStack')
@@ -277,7 +234,7 @@ export function directiveHtml(options) {
 
   /**
    * @this {CompileContext}
-   * @type {_Handle}
+   * @type {MicromarkHandle}
    */
   function exit() {
     const stack = this.getData('directiveStack')

dev/lib/syntax.js

@@ -1,5 +1,5 @@
 /**
- * @typedef {import('micromark-util-types').Extension} Extension
+ * @import {Extension} from 'micromark-util-types'
  */
 
 import {codes} from 'micromark-util-symbol'

package.json

@@ -90,10 +90,29 @@
     "overrides": [
       {
         "files": [
-          "**/*.ts"
+          "**/*.d.ts"
         ],
         "rules": {
-          "@typescript-eslint/consistent-type-definitions": "off"
+          "@typescript-eslint/array-type": [
+            "error",
+            {
+              "default": "generic"
+            }
+          ],
+          "@typescript-eslint/ban-types": [
+            "error",
+            {
+              "extendDefaults": true
+            }
+          ],
+          "@typescript-eslint/consistent-indexed-object-style": [
+            "error",
+            "index-signature"
+          ],
+          "@typescript-eslint/consistent-type-definitions": [
+            "error",
+            "interface"
+          ]
         }
       }
     ],

readme.md

@@ -90,6 +90,11 @@ A lovely language know as :abbr[HTML]{title="HyperText Markup Language"}.
 …and our module `example.js` looks as follows:
 
 ```js
+/**
+ * @import {Handle} from 'micromark-extension-directive'
+ * @import {CompileContext} from 'micromark-util-types'
+ */
+
 import fs from 'node:fs/promises'
 import {micromark} from 'micromark'
 import {directive, directiveHtml} from 'micromark-extension-directive'
@@ -102,8 +107,8 @@ const output = micromark(await fs.readFile('example.md'), {
 console.log(output)
 
 /**
- * @this {import('micromark-util-types').CompileContext}
+ * @this {CompileContext}
- * @type {import('micromark-extension-directive').Handle}
+ * @type {Handle}
  * @returns {undefined}
  */
 function abbr(d) {

test/index.js

@@ -1,7 +1,6 @@
 /**
- * @typedef {import('micromark-util-types').CompileContext} CompileContext
+ * @import {Handle, HtmlOptions} from 'micromark-extension-directive'
- * @typedef {import('micromark-extension-directive').HtmlOptions} HtmlOptions
+ * @import {CompileContext} from 'micromark-util-types'
- * @typedef {import('micromark-extension-directive').Handle} Handle
  */
 
 import assert from 'node:assert/strict'