feat(util): fromDocs

Signed-off-by: Lexus Drumgold <[email protected]>

Author: unicornware

.commitlintrc.ts

@@ -21,8 +21,9 @@ const config: UserConfig = {
     'scope-enum': [Severity.Error, 'always', scopes([
       'chore',
       'lexer',
+      'markdown',
       'parser',
-      'reader'
+      'util'
     ])]
   }
 }

.dictionary.txt

@@ -1,5 +1,6 @@
 attw
 cefc
+codecov
 commitlintrc
 dedupe
 dessant
@@ -14,6 +15,7 @@ iife
 jchen
 jsdoc
 kaisugi
+lcov
 lintstagedrc
 mdast
 mkbuild

.github/infrastructure.yml

@@ -75,6 +75,15 @@ labels:
   - name: scope:install
     description: package install
     color: 74cefc
+  - name: scope:markdown
+    description: markdown integration
+    color: 74cefc
+  - name: scope:mdast
+    description: mdast
+    color: 74cefc
+  - name: scope:micromark
+    description: micromark
+    color: 74cefc
   - name: scope:parser
     description: file parser
     color: 74cefc
@@ -172,7 +181,7 @@ repository:
   automated_security_fixes: true
   default_branch: main
   delete_branch_on_merge: true
-  description: docast utility for parsing docblocks
+  description: docast utility to parse docblocks
   has_issues: true
   has_projects: true
   has_wiki: false

__fixtures__/dbl-linear.ts

@@ -9,7 +9,14 @@
  *
  *  1. The number `u(0) = 1` is the first one in `u`
  *  2. For each `x` in `u`, `y = 2x + 1` and `z = 3x + 1` must be in `u` too
+ *      - some
+ *      - additional
+ *      - info
  *  3. There are no other numbers in `u`
+ *      - some
+ *      - more
+ *      - additional
+ *      - info
  *
  * Given an index, `n`, the function returns the element at `u(n)`.
  *

__fixtures__/detect-syntax.ts

@@ -19,7 +19,11 @@ import { hasCJSSyntax, hasESMSyntax } from '@flex-development/mlly'
  *  console.debug(detectSyntax('export default {}'))
  *
  * @param {string} code - Code to evaluate
- * @return {{ cjs: boolean; esm: boolean; mixed: boolean }} Detection result
+ * @return {{
+ *  cjs: boolean;
+ *  esm: boolean;
+ *  mixed: boolean
+ * }} Detection result
  */
 const detectSyntax = (
   code: string

__fixtures__/reader.ts

@@ -0,0 +1,200 @@
+/**
+ * @file Fixtures - Reader
+ * @module fixtures/Reader
+ */
+
+import type { Point } from '@flex-development/docast'
+import { at, clamp, fallback, isInteger } from '@flex-development/tutils'
+import { ok } from 'devlop'
+import type { Code } from 'micromark-util-types'
+import type { VFile } from 'vfile'
+
+/**
+ * Source document reader.
+ *
+ * @class
+ */
+class Reader {
+  /**
+   * Source document.
+   *
+   * @public
+   * @readonly
+   * @instance
+   * @member {string} document
+   */
+  public readonly document: string
+
+  /**
+   * List, where each index is a line number (`0`-based), and each value is the
+   * number of columns in the line.
+   *
+   * @protected
+   * @readonly
+   * @instance
+   * @member {number[]} indices
+   */
+  protected readonly indices: number[]
+
+  /**
+   * Current position in {@linkcode document}.
+   *
+   * @protected
+   * @instance
+   * @member {number} position
+   */
+  protected position: number
+
+  /**
+   * Create a new source document reader.
+   *
+   * @see {@linkcode VFile}
+   *
+   * @param {VFile | string} source - Source document or file
+   */
+  constructor(source: VFile | string) {
+    this.document = source = String(source)
+    this.indices = [...source.matchAll(/^.*/gm)].map(([m]) => m.length + 1)
+    this.position = 0
+  }
+
+  /**
+   * Check if the reader is at the end of the document.
+   *
+   * @example
+   *  ```ts
+   *  while (!reader.eof) {
+   *    // do something
+   *  }
+   *  ```
+   *
+   * @public
+   * @instance
+   *
+   * @return {boolean} `true` if at end of document
+   */
+  public get eof(): boolean {
+    return this.index >= this.document.length
+  }
+
+  /**
+   * Get the current position in the document.
+   *
+   * @public
+   * @instance
+   *
+   * @return {number} Current position in document
+   */
+  public get index(): number {
+    return this.position
+  }
+
+  /**
+   * Get the next `k`-th character code from the document without changing the
+   * position of the reader, with `null` denoting the end of the document.
+   *
+   * @see {@linkcode Code}
+   *
+   * @public
+   * @instance
+   *
+   * @param {number} [k=1] - Difference between index of next `k`-th character
+   * code and current position in document
+   * @return {Code} Peeked character code or `null`
+   */
+  public peek(k: number = 1): Code {
+    ok(isInteger(k), 'expected k to be an integer')
+    return fallback(this.document.codePointAt(this.index + k), null)
+  }
+
+  /**
+   * Get a [*point*][1] in the document by `offset`.
+   *
+   * The given `offset` must be an integer in the range `[0, document.length]`.\
+   * If invalid, `point.column` and `point.line` will have a value of `-1`.
+   *
+   * > **Point** represents one place in a source [*file*][2].
+   * >
+   * > The `line` field (`1`-indexed integer) represents a line in a source
+   * > file. The `column` field (`1`-indexed integer) represents a column in a
+   * > source file. The `offset` field (`0`-indexed integer) represents a
+   * > character in a source file.
+   * >
+   * > The term character means a (UTF-16) code unit which is defined in the
+   * > [Web IDL][3] specification.
+   *
+   * [1]: https://github.com/syntax-tree/unist#point
+   * [2]: https://github.com/syntax-tree/unist#file
+   * [3]: https://webidl.spec.whatwg.org/
+   *
+   * @see {@linkcode Point}
+   * @see https://github.com/syntax-tree/unist#point
+   *
+   * @public
+   * @instance
+   *
+   * @param {number?} [offset=this.index] - Index of character in document
+   * @return {Point} Point in document
+   */
+  public point(offset: number = this.index): Point {
+    /**
+     * Current offset (`0`-indexed integer).
+     *
+     * @var {number} index
+     */
+    let index: number = 0
+
+    /**
+     * Current line (`1`-indexed integer).
+     *
+     * @var {number} line
+     */
+    let line: number = -1
+
+    /**
+     * Current {@linkcode Point} in source document.
+     *
+     * @const {Point} point
+     */
+    const point: Point = { column: -1, line, offset }
+
+    // convert offset to point
+    if (isInteger(offset) && offset > -1 && offset <= this.document.length) {
+      while (++line < this.indices.length) {
+        for (let j = 0; j < at(this.indices, line)!; j++) {
+          if (index++ === offset) {
+            point.column = j + 1
+            point.line = line + 1
+            break
+          }
+        }
+      }
+    }
+
+    return point
+  }
+
+  /**
+   * Get the next `k`-th character code from the document, with `null` denoting
+   * the end of the document.
+   *
+   * Unlike {@linkcode peek}, this method changes the position of the reader.
+   *
+   * @see {@linkcode Code}
+   *
+   * @public
+   * @instance
+   *
+   * @param {number} [k=1] - Difference between index of next `k`-th character
+   * code and current position in document
+   * @return {Code} Next `k`-th character or `null`
+   */
+  public read(k: number = 1): Code {
+    ok(isInteger(k), 'expected k to be an integer')
+    ok(!this.eof, 'cannot read past end of document')
+    this.position = clamp(this.position + k, 0, this.document.length)
+    return fallback(this.document.codePointAt(this.position), null)
+  }
+}
+
+export default Reader

__fixtures__/to-relative-specifier.ts

@@ -0,0 +1,57 @@
+/**
+ * @file Fixtures - toRelativeSpecifier
+ * @module fixtures/toRelativeSpecifier
+ */
+
+import type { NodeError } from '@flex-development/errnode'
+import pathe from '@flex-development/pathe'
+import { DOT } from '@flex-development/tutils'
+import { URL, fileURLToPath } from 'node:url'
+import validateURLString from './validate-url-string'
+
+/**
+ * Converts `specifier` into a relative specifier.
+ *
+ * :::info
+ * The relative specifier will only include a file extension if `specifier`
+ * includes a file extension.
+ * :::
+ *
+ * @see {@linkcode URL}
+ * @see https://nodejs.org/api/esm.html#terminology
+ *
+ * @param {URL | string} specifier - Module specifier to convert
+ * @param {URL | string} parent - Parent module URL or path to resolve from
+ * @return {string} `specifier` as relative specifier
+ * @throws {NodeError<TypeError>} If either `specifier` or `parent` is not a
+ * string or an instance of {@linkcode URL}
+ */
+const toRelativeSpecifier = (
+  specifier: URL | string,
+  parent: URL | string
+): string => {
+  validateURLString(specifier, 'specifier')
+  validateURLString(parent, 'parent')
+
+  // convert file url objects to file url strings
+  if (parent instanceof URL) parent = parent.href
+  if (specifier instanceof URL) specifier = specifier.href
+
+  // convert file url strings to paths
+  if (parent.startsWith('file:')) parent = fileURLToPath(parent)
+  if (specifier.startsWith('file:')) specifier = fileURLToPath(specifier)
+
+  // convert specifier to relative specifier
+  specifier = pathe
+    .relative(pathe.resolve(parent), pathe.resolve(specifier))
+    .replace(/^\.\.\/?/, '')
+    .replace(/^(\w)/, './$1')
+
+  // set specifier to dot character if empty string
+  // this occurs when specifier is a directory, but is not fully specified
+  if (!specifier) specifier = DOT
+
+  return specifier
+}
+
+export default toRelativeSpecifier

__fixtures__/validate-url-string.ts

@@ -0,0 +1,34 @@
+/**
+ * @file Fixtures - validateURLString
+ * @module fixtures/validateURLString
+ */
+
+import { ERR_INVALID_ARG_TYPE, type NodeError } from '@flex-development/errnode'
+import { isString } from '@flex-development/tutils'
+import { URL } from 'node:url'
+
+/**
+ * Checks if `value` is an instance of {@linkcode URL} or a string.
+ *
+ * Throws [`ERR_INVALID_ARG_TYPE`][1] if `value` is of neither type.
+ *
+ * [1]: https://nodejs.org/api/errors.html#err_invalid_arg_value
+ *
+ * @see {@linkcode ERR_INVALID_ARG_TYPE}
+ *
+ * @internal
+ *
+ * @param {unknown} value - Value supplied by user
+ * @param {string} name - Name of invalid argument or property
+ * @return {value is URL | string} `true` if `value` is `URL` instance or string
+ * @throws {NodeError<TypeError>} If `value` is not `URL` instance or string
+ */
+const validateURLString = (
+  value: unknown,
+  name: string
+): value is URL | string => {
+  if (value instanceof URL || isString(value)) return true
+  throw new ERR_INVALID_ARG_TYPE(name, ['URL', 'string'], value)
+}
+
+export default validateURLString

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flex-development/docast-util-from-docs",
-  "description": "docast utility for parsing docblocks",
+  "description": "docast utility to parse docblocks",
   "version": "1.0.0-alpha.1",
   "keywords": [
     "comment",
@@ -140,6 +140,8 @@
     "is-ci": "3.0.1",
     "jsonc-eslint-parser": "2.4.0",
     "lint-staged": "15.2.2",
+    "mdast-util-directive": "3.0.0",
+    "micromark-extension-directive": "3.0.0",
     "micromark-util-types": "2.0.0",
     "node-notifier": "10.0.1",
     "prettier": "3.2.5",