From 4bb71009f1d426da128c1496242c514e99132e3b Mon Sep 17 00:00:00 2001 From: Lexus Drumgold Date: Wed, 31 Jan 2024 23:40:33 -0500 Subject: [PATCH] refactor(spec)!: rewrite specification Signed-off-by: Lexus Drumgold --- .commitlintrc.cts | 6 +- .dictionary.txt | 1 + .eslintrc.base.cjs | 1 + .github/infrastructure.yml | 8 + .github/workflows/publish.yml | 3 +- .vscode/settings.json | 1 + CODE_OF_CONDUCT.md | 105 +++++ README.md | 399 +++++++++++++----- build.config.ts | 5 +- package.json | 12 +- src/content/__tests__/block-tag.spec-d.ts | 23 + src/content/__tests__/content.spec-d.ts | 28 ++ src/content/__tests__/description.spec-d.ts | 65 +++ src/content/__tests__/flow.spec-d.ts | 23 + src/content/__tests__/phrasing.spec-d.ts | 29 ++ src/content/block-tag.ts | 37 ++ src/content/content.ts | 28 ++ src/content/description.ts | 44 ++ src/content/flow.ts | 35 ++ src/content/index.ts | 10 + src/content/phrasing.ts | 38 ++ src/enums/__tests__/kind.spec-d.ts | 162 ------- src/enums/__tests__/modifier.spec-d.ts | 85 ---- src/enums/__tests__/type.spec-d.ts | 43 -- src/enums/index.ts | 8 - src/enums/kind.ts | 36 -- src/enums/modifier.ts | 25 -- src/enums/type.ts | 21 - src/index.ts | 8 +- .../__tests__/code-segment.spec-d.ts | 32 ++ src/interfaces/__tests__/context.spec-d.ts | 33 -- src/interfaces/__tests__/data.spec-d.ts | 13 + src/interfaces/__tests__/position.spec-d.ts | 5 - src/interfaces/code-segment.ts | 38 ++ src/interfaces/context.ts | 39 -- src/interfaces/data.ts | 26 ++ src/interfaces/index.ts | 5 +- src/interfaces/point.ts | 4 +- src/interfaces/position.ts | 20 +- src/mixins/__tests__/tag.spec-d.ts | 20 + src/mixins/index.ts | 6 + src/mixins/tag.ts | 26 ++ src/nodes/__tests__/block-tag.spec-d.ts | 38 ++ src/nodes/__tests__/comment.spec-d.ts | 40 +- src/nodes/__tests__/description.spec-d.ts | 33 ++ .../__tests__/implicit-description.spec-d.ts | 32 -- src/nodes/__tests__/inline-tag.spec-d.ts | 31 ++ src/nodes/__tests__/literal.spec-d.ts | 17 + src/nodes/__tests__/node.spec-d.ts | 18 +- src/nodes/__tests__/parent.spec-d.ts | 15 +- src/nodes/__tests__/root.spec-d.ts | 28 +- src/nodes/__tests__/tag-block.spec-d.ts | 40 -- src/nodes/__tests__/tag-inline.spec-d.ts | 39 -- src/nodes/__tests__/type-expression.spec-d.ts | 29 ++ src/nodes/block-tag.ts | 51 +++ src/nodes/comment.ts | 64 ++- src/nodes/description.ts | 48 +++ src/nodes/implicit-description.ts | 50 --- src/nodes/index.ts | 17 +- src/nodes/inline-tag.ts | 42 ++ src/nodes/literal.ts | 22 + src/nodes/node.ts | 30 +- src/nodes/parent.ts | 34 +- src/nodes/root.ts | 56 ++- src/nodes/tag-block.ts | 59 --- src/nodes/tag-inline.ts | 57 --- src/nodes/type-expression.ts | 40 ++ src/types/__tests__/child.spec-d.ts | 30 -- src/types/__tests__/type-parent.spec-d.ts | 27 -- src/types/child.ts | 20 - src/types/index.ts | 7 - src/types/type-parent.ts | 19 - yarn.lock | 31 +- 73 files changed, 1476 insertions(+), 1144 deletions(-) create mode 100644 CODE_OF_CONDUCT.md create mode 100644 src/content/__tests__/block-tag.spec-d.ts create mode 100644 src/content/__tests__/content.spec-d.ts create mode 100644 src/content/__tests__/description.spec-d.ts create mode 100644 src/content/__tests__/flow.spec-d.ts create mode 100644 src/content/__tests__/phrasing.spec-d.ts create mode 100644 src/content/block-tag.ts create mode 100644 src/content/content.ts create mode 100644 src/content/description.ts create mode 100644 src/content/flow.ts create mode 100644 src/content/index.ts create mode 100644 src/content/phrasing.ts delete mode 100644 src/enums/__tests__/kind.spec-d.ts delete mode 100644 src/enums/__tests__/modifier.spec-d.ts delete mode 100644 src/enums/__tests__/type.spec-d.ts delete mode 100644 src/enums/index.ts delete mode 100644 src/enums/kind.ts delete mode 100644 src/enums/modifier.ts delete mode 100644 src/enums/type.ts create mode 100644 src/interfaces/__tests__/code-segment.spec-d.ts delete mode 100644 src/interfaces/__tests__/context.spec-d.ts create mode 100644 src/interfaces/__tests__/data.spec-d.ts create mode 100644 src/interfaces/code-segment.ts delete mode 100644 src/interfaces/context.ts create mode 100644 src/interfaces/data.ts create mode 100644 src/mixins/__tests__/tag.spec-d.ts create mode 100644 src/mixins/index.ts create mode 100644 src/mixins/tag.ts create mode 100644 src/nodes/__tests__/block-tag.spec-d.ts create mode 100644 src/nodes/__tests__/description.spec-d.ts delete mode 100644 src/nodes/__tests__/implicit-description.spec-d.ts create mode 100644 src/nodes/__tests__/inline-tag.spec-d.ts create mode 100644 src/nodes/__tests__/literal.spec-d.ts delete mode 100644 src/nodes/__tests__/tag-block.spec-d.ts delete mode 100644 src/nodes/__tests__/tag-inline.spec-d.ts create mode 100644 src/nodes/__tests__/type-expression.spec-d.ts create mode 100644 src/nodes/block-tag.ts create mode 100644 src/nodes/description.ts delete mode 100644 src/nodes/implicit-description.ts create mode 100644 src/nodes/inline-tag.ts create mode 100644 src/nodes/literal.ts delete mode 100644 src/nodes/tag-block.ts delete mode 100644 src/nodes/tag-inline.ts create mode 100644 src/nodes/type-expression.ts delete mode 100644 src/types/__tests__/child.spec-d.ts delete mode 100644 src/types/__tests__/type-parent.spec-d.ts delete mode 100644 src/types/child.ts delete mode 100644 src/types/index.ts delete mode 100644 src/types/type-parent.ts diff --git a/.commitlintrc.cts b/.commitlintrc.cts index 294a4e70..10aa963a 100644 --- a/.commitlintrc.cts +++ b/.commitlintrc.cts @@ -18,7 +18,11 @@ import { scopes } from '@flex-development/commitlint-config' const config: UserConfig = { extends: ['@flex-development'], rules: { - 'scope-enum': [Severity.Error, 'always', scopes(['nodes', 'spec'])] + 'scope-enum': [Severity.Error, 'always', scopes([ + 'content', + 'nodes', + 'spec' + ])] } } diff --git a/.dictionary.txt b/.dictionary.txt index d576b144..a8b5f1fd 100644 --- a/.dictionary.txt +++ b/.dictionary.txt @@ -17,6 +17,7 @@ iife jchen kaisugi lintstagedrc +mdast mkbuild mlly nocheck diff --git a/.eslintrc.base.cjs b/.eslintrc.base.cjs index 104323f8..11a81939 100644 --- a/.eslintrc.base.cjs +++ b/.eslintrc.base.cjs @@ -1027,6 +1027,7 @@ const config = { '@typescript-eslint/no-unsafe-member-access': 0, '@typescript-eslint/no-unsafe-return': 0, '@typescript-eslint/no-unused-expressions': 0, + '@typescript-eslint/no-unused-vars': 0, '@typescript-eslint/non-nullable-type-assertion-style': 0, '@typescript-eslint/prefer-includes': 0, '@typescript-eslint/prefer-nullish-coalescing': 0, diff --git a/.github/infrastructure.yml b/.github/infrastructure.yml index fcb8a9f9..1c9cc901 100644 --- a/.github/infrastructure.yml +++ b/.github/infrastructure.yml @@ -56,6 +56,9 @@ labels: - name: flag:needs-refactor description: code improvements required before being merged color: fbca04 + - name: scope:content + description: syntax tree content + color: 74cefc - name: scope:dependencies description: dependency updates color: 74cefc @@ -65,6 +68,9 @@ labels: - name: scope:install description: package install color: 74cefc + - name: scope:mixins + description: syntax tree node mixins + color: 74cefc - name: scope:nodes description: syntax tree nodes color: 74cefc @@ -180,6 +186,8 @@ repository: - ast - doc - docblock + - markdown + - mdast - syntax-tree - unist - unist-spec diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index 04ddf71e..53197e8e 100644 --- a/.github/workflows/publish.yml +++ b/.github/workflows/publish.yml @@ -12,6 +12,7 @@ # - https://docs.github.com/actions/using-workflows/workflow-commands-for-github-actions # - https://docs.github.com/webhooks-and-events/webhooks/webhook-events-and-payloads#release # - https://docs.github.com/webhooks-and-events/webhooks/webhook-events-and-payloads#workflow_dispatch +# - https://docs.npmjs.com/generating-provenance-statements # - https://github.com/actions/checkout # - https://github.com/actions/setup-node # - https://github.com/actions/setup-node/blob/main/docs/advanced-usage.md#yarn2-configuration @@ -67,7 +68,7 @@ jobs: env: ARTIFACT: ${{ steps.artifact.outputs.result }} FLAGS: ${{ steps.dist-tag.outputs.flag }} - run: echo "result=npm publish $FLAGS $ARTIFACT" >>$GITHUB_OUTPUT + run: echo "result=npm publish --provenance $FLAGS $ARTIFACT" >>$GITHUB_OUTPUT gpr: needs: preflight permissions: diff --git a/.vscode/settings.json b/.vscode/settings.json index db3ac67e..3dd62725 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -184,6 +184,7 @@ ], "overrideConfigFile": ".eslintrc.cjs" }, + "eslint.runtime": "node", "eslint.validate": [ "css", "github-actions-workflow", diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 00000000..98b244ea --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,105 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for +everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity +and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, +or sexual identity and orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community. + +## Our Standards + +Examples of behavior that contributes to a positive environment for our community include: + +- Demonstrating empathy and kindness toward other people +- Being respectful of differing opinions, viewpoints, and experiences +- Giving and gracefully accepting constructive feedback +- Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience +- Focusing on what is best not just for us as individuals, but for the overall community + +Examples of unacceptable behavior include: + +- The use of sexualized language or imagery, and sexual attention or advances of any kind +- Trolling, insulting or derogatory comments, and personal or political attacks +- Public or private harassment +- Publishing others' private information, such as a physical or email address, without their explicit permission +- Other conduct which could reasonably be considered inappropriate in a professional setting + +## Enforcement Responsibilities + +Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take +appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, +or harmful. + +Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, +issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for +moderation decisions when appropriate. + +## Scope + +This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing +the community in public spaces. + +Examples of representing our community include using an official e-mail address, posting via an official social media +account, or acting as an appointed representative at an online or offline event. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible +for enforcement at [`support@flexdevelopment.llc`](mailto:support@flexdevelopment.llc). All complaints will be reviewed +and investigated promptly and fairly. + +All community leaders are obligated to respect the privacy and security of the reporter of any incident. + +## Enforcement Guidelines + +Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem +in violation of this Code of Conduct: + +### 1. Correction + +**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community. + +**Consequence**: A private, written warning from community leaders, providing clarity around the nature of the violation +and an explanation of why the behavior was inappropriate. A public apology may be requested. + +### 2. Warning + +**Community Impact**: A violation through a single incident or series of actions. + +**Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including +unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding +interactions in community spaces as well as external channels like social media. Violating these terms may lead to a +temporary or permanent ban. + +### 3. Temporary Ban + +**Community Impact**: A serious violation of community standards, including sustained inappropriate behavior. + +**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified +period of time. No public or private interaction with the people involved, including unsolicited interaction with those +enforcing the Code of Conduct, is allowed during this period. + +Violating these terms may lead to a permanent ban. + +### 4. Permanent Ban + +**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate +behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals. + +**Consequence**: A permanent ban from any sort of public interaction within the community. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][1], [version 2.0][2]. + +Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder][3]. + +For answers to common questions about this code of conduct, see the FAQ at . +Translations are available at . + +[1]: https://www.contributor-covenant.org +[2]: https://www.contributor-covenant.org/version/2/0/code_of_conduct.html +[3]: https://github.com/mozilla/inclusion/blob/master/code-of-conduct-enforcement/consequence-ladder.md diff --git a/README.md b/README.md index fa42f9ca..50f2b133 100644 --- a/README.md +++ b/README.md @@ -13,206 +13,371 @@ --- -**docast** is a specification for representing [docblock comments](#docblock-comment) as [abstract syntax trees][1]. +**docast** is a specification for representing [docblock comments](#docblock-comment) as [abstract syntax trees][unist-syntax-tree]. -It implements the [**unist**][2] spec. +It implements the [**unist**][unist] spec. ## Contents - [Introduction](#introduction) - [Where this specification fits](#where-this-specification-fits) -- [Nodes](#nodes) +- [Types](#types) +- [Nodes (abstract)](#nodes-abstract) - [`Node`](#node) + - [`Position`](#position) + - [`Point`](#point) + - [`Literal`](#literal) - [`Parent`](#parent) - - [`Root`](#root) - - [`Comment`](#comment) - - [`ImplicitDescription`](#implicitdescription) +- [Nodes](#nodes) - [`BlockTag`](#blocktag) + - [`Comment`](#comment) + - [`CodeSegment`](#codesegment) + - [`Description`](#description) - [`InlineTag`](#inlinetag) -- [Interfaces](#interfaces) - - [`Context`](#context) + - [`Root`](#root) + - [`TypeExpression`](#typeexpression) +- [Mixins](#mixins) + - [`Tag`](#tag) +- [Content model](#content-model) + - [`BlockTagContent`](#blocktagcontent) + - [`DescriptionContent`](#descriptioncontent) + - [`FlowContent`](#flowcontent) + - [`PhrasingContent`](#phrasingcontent) - [Glossary](#glossary) - [List of utilities](#list-of-utilities) - [Contribute](#contribute) ## Introduction -This document defines a format for representing [docblock comments](#docblock-comment) as [abstract syntax trees][1]. -Development of docast started in October 2022. This specification is written in a [Web IDL][3]-like grammar. +This document defines a format for representing [docblock comments](#docblock-comment) as [abstract syntax trees][unist-syntax-tree]. +Development of docast started in October 2022. This specification is written in a [TypeScript][typescript]-like grammar. ### Where this specification fits -docast extends [unist][2], a format for syntax trees, to benefit from its [ecosystem of utilities][4]. +docast extends [unist][unist], a format for syntax trees, to benefit from its [ecosystem of utilities][unist-utilities]. +It also integrates with [mdast][mdast], a specification for representing markdown. -docast relates to [JavaScript][5] and [TypeScript][6] in that both languages support docblock comments. docast is -**language-agnostic**, however, and can be used with any programming language. +docast relates to [JavaScript][javascript] and [TypeScript][typescript] in that both languages support docblock comments. +docast is **language-agnostic**, however, and can be used with any programming language that supports docblock comments. -docast relates to [JSDoc][7], [TSDoc][8], and [typedoc][9] in that these tools parse docblock comments. These tools also -have a limited set of tags that developers are allowed to use. If developers already have a set of tags they're using, -they must spend additional time re-configuring those tags for their chosen tool. **docast does not enforce any tag -semantics** — the user does. Tag specifications can be left to an [ESLint][10] rule or setting akin to -[`jsdoc/check-tag-names`][11] or [`jsdoc.structuredTags`][12]. +docast relates to [JSDoc][jsdoc], [TSDoc][tsdoc], and [typedoc][typedoc] in that these tools parse docblock comments. +These tools also have a limited set of tags that developers are allowed to use. If developers already have a set of tags +they're using, they must spend additional time re-configuring those tags for their chosen tool. **docast does not +enforce any tag semantics** — the user does. Tag specifications can be left to an [ESLint][eslint] rule or setting +akin to [`jsdoc/check-tag-names`][check-tag-names] or [`jsdoc.structuredTags`][structuredtags]. -## Nodes +## Types + +TypeScript users can integrate `docast` type definitions into their project by installing the appropriate packages: + +```sh +yarn add @flex-development/docast @types/mdast @types/unist +``` + +## Nodes (abstract) ### Node -```idl -interface Node <: UnistNode { - type: 'block-tag' | 'comment' | 'implicit-description' | 'inline-tag' | 'root' +```ts +interface Node extends unist.Node { + position?: Position | undefined } ``` -**Node** ([**UnistNode**][13]) is a syntactic unit in docast syntax trees. +**Node** ([**unist.Node**][unist-node]) is a syntactic unit in docast syntax trees. -### Parent +The `position` field represents the location of a node in a source document. The value of the `position` field implements +the [`Position`](#position) interface. The `position` field must not be present if a node is [*generated*][unist-generated]. -```idl -interface Parent <: UnistParent { - children: [BlockTag | Comment | ImplicitDescription | InlineTag] - type: 'block-tag' | 'comment' | 'implicit-description' | 'root' +#### `Position` + +```ts +interface Position { + end: Point + start: Point } ``` -**Parent** ([**UnistParent**][14]) represents an abstract interface in docast containing other nodes (said to be -[*children*][15]). +**Position** represents the location of a node in a source [*file*][unist-file]. -### Root +The `start` field of **Position** represents the index of the first character of the parsed source region. The `end` +field represents the index of the first character after the parsed source region, whether it exists or not. The value +of the `start` and `end` fields implement the [**Point**](#point) interface. -```idl -interface Root <: Parent { - children: [Comment] - type: 'root' +If the syntactic unit represented by a node is not present in the source [*file*][unist-file] at the time of parsing, +the node is said to be [*generated*][unist-generated] and it must not have positional information. + +#### `Point` + +```ts +interface Point { + column: number // >= 1 + line: number // >= 1 + offset: number // >= 0 } ``` -**Root** ([**Parent**](#parent)) represents a document. +**Point** represents one place in a source [*file*][unist-file]. -**Root** can be used as the [*root*][16] of a [*tree*][17], never as a [*child*][18]. It can contain -[**comment**](#comment) nodes. +The `line` and `column` fields are `1`-indexed integers representing a line and column in a source file. The offset +field (`0`-indexed integer) represents a character in a source file. -### Comment +The term character refers to a (UTF-16) code unit as defined by the [Web IDL specification][webidl-spec]. -```idl -interface Comment <: Parent { - children: [BlockTag | ImplicitDescription] - context: Context? - type: 'comment' +### `Literal` + +```ts +interface Literal extends Node { value: string } ``` -**Comment** ([**Parent**](#parent)) represents a [docblock comment](#docblock-comment). - -**Comment** can be used in [**root**](#root) nodes. It can contain [**implicit description**](#implicitdescription) and -[**block tag**](#blocktag) nodes. +**Literal** represents an abstract interface in docast containing a value. -A **comment** has [*context*](#context) if [positioned][19] exactly one line before the code it documents. +Its `value` field is a `string`. -### ImplicitDescription +### `Parent` -```idl -interface ImplicitDescription <: Parent { - children: [InlineTag] - type: 'implicit-description' - value: string +```ts +interface Parent extends unist.Parent { + children: (Comment | Content)[] } ``` -**ImplicitDescription** ([**Parent**](#parent)) represents a piece of text located at the **beginning** of a [docblock comment](#docblock-comment). +**Parent** ([**unist.Parent**][unist-parent]) represents an abstract interface in docast containing other nodes (said to +be [*children*][unist-child]). -**ImplicitDescription** can be used in [**comment**](#comment) nodes. It can contain [**inline tag**](#inlinetag) nodes. +Its content is limited to [**comment**](#comment) nodes and [docast content](#content-model). -### BlockTag +## Nodes -```idl -interface BlockTag <: Parent { - children: [InlineTag] - tag: string - text: string +### `BlockTag` + +```ts +interface BlockTag extends Parent, Tag { + children: BlockTagContent[] + data?: BlockTagData | undefined type: 'block-tag' - value: string } ``` -**BlockTag** ([**Parent**](#parent)) represents metadata in a [docblock comment](#docblock-comment). +**BlockTag** ([**Parent**](#parent)) represents top-level metadata. -**BlockTag** can be used in [**comment**](#comment) nodes. It can contain [**inline tag**](#inlinetag) nodes. +**BlockTag** can be used in [**comment**](#comment) nodes. Its content model is [**block tag**](#blocktagcontent) +content. -### InlineTag +### `Comment` -```idl -interface InlineTag <: Node { - tag: string - text: string - type: 'inline-tag' - value: string +```ts +interface Comment extends Parent { + children: FlowContent[] + code?: CodeSegment | null | undefined + data?: CommentData | undefined + type: 'comment' } ``` -**InlineTag** ([**Node**](#node)) represents inline metadata in a [docblock comment](#docblock-comment). +**Comment** ([**Parent**](#parent)) represents a [*docblock comment*](#docblock-comment) in a source [*file*][unist-file]. -**InlineTag** can be used in [**implicit description**](#implicitdescription) and [**block tag**](#blocktag) nodes. It -cannot contain any children — it is a [*leaf*][20]. +The `code` field represents the segment of code documented by a comment. The value of the `code` field may be `null`, +`undefined`, or implement the [`CodeSegment`](#codesegment) interface. The `code` field must not be present if a comment +is used only to provide additional information. -## Interfaces +**Comment** can be used in [**root**](#root) nodes. Its content model is [**flow**](#flowcontent) content. -### Context +#### `CodeSegment` -```idl -interface Context { +```ts +interface CodeSegment { identifier: string - kind: string - parent: string? - position: UnistPosition + kind: number | string + parent?: CodeSegment | null | undefined + position: Position +} +``` + +**CodeSegment** represents the code segment in a [*file*][unist-file] that is documented by a [**comment**](#comment). + +The `identifier` field represents the name of documented code segment. The value of the `identifier` field is a +non-empty string that matches the identifier found in the respective programming langauge's AST. + +The `kind` field represents the syntax kind of the code segment. The value of the `kind` field is an enumerated value. + +The `parent` field represents the code segment the current segment is nested under. The value of the `parent` field may +be `null` or `undefined` for top-level code segments, or for nested code segments, implement the `CodeSegment` interface. + +### `Description` + +```ts +interface Description extends Parent { + children: DescriptionContent[] + data?: DescriptionData | undefined + type: 'description' } ``` -Data representing the segment of code a [**comment**](#comment) documents. +**Description** ([**Parent**](#parent)) represents the text of a [**comment**](#comment). It is located at the start of +a comment, before any [**block tags**](#blocktag), and may contain [Markdown][mdast] content. + +**Description** can be used in [**comment**](#comment) nodes. Its content model is [**description**](#descriptioncontent). + +### `InlineTag` + +```ts +interface InlineTag extends Literal, Tag { + data?: InlineTagData | undefined + type: 'inline-tag' +} +``` + +**InlineTag** ([**Literal**](#literal)) represents inline metadata. + +**InlineTag** can be used in [**block tag**](#blocktag) and [**description**](#description) nodes. It cannot contain any +children — it is a [*leaf*][unist-leaf]. + +### `Root` + +```ts +interface Root extends Parent { + children: Comment[] + data?: RootData | undefined + position?: undefined + type: 'root' +} +``` + +**Root** ([**Parent**](#parent)) represents a document. + +**Root** can be used as the [*root*][unist-root] of a [*tree*][unist-tree], never as a [*child*][unist-child]. It can +contain [**comment**](#comment) nodes. + +### `TypeExpression` + +```ts +interface TypeExpression extends Literal { + data?: TypeExpressionData | undefined + type: 'type-expression' +} +``` + +**TypeExpression** ([**Literal**](#literal)) represents a type defintion or constraint. + +**TypeExpression** can be used in [**block tag**](#blocktag) nodes. It cannot contain any children — it is a +[*leaf*][unist-leaf]. + +## Mixins + +### `Tag` + +```ts +interface Tag { + name: string + prefix: string + tag: string +} +``` + +**Tag** represents metadata associated with a [**comment**](#comment). + +The `prefix` field represents the tag prefix. The value is a non-empty string. + +The `name` field represents the tag name without `prefix`. The value of the `name` field is a non-empty string. + +The `tag` field represents the parsed tag. The value of `tag` field is `prefix` and `name`. + +## Content model + +```ts +type Content = BlockTagContent | DescriptionContent | FlowContent | PhrasingContent +``` + +Nodes are grouped by content type, if applicable. Each node in docast, with the exception of [`Comment`](#comment), +falls into one or more categories of `Content`. + +### `BlockTagContent` + +```ts +type BlockTagContent = PhrasingContent | TypeExpression +``` + +**Block** content represents [**block tag**](#blocktag) text, and its markup. + +### `DescriptionContent` + +```ts +type DescriptionContent = + | mdast.Blockquote + | mdast.Definition + | mdast.FootnoteDefinition + | mdast.List + | mdast.ListItem + | mdast.Paragraph + | mdast.Table + | mdast.ThematicBreak + | PhrasingContent +``` + +**Description** content represents [**description**](#description) text, and its markup. + +### `FlowContent` + +```ts +type FlowContent = BlockTag | Description +``` + +**Flow** content represents the sections of [**comment**](#comment). + +### `PhrasingContent` + +```ts +type PhrasingContent = InlineTag | mdast.Code | mdast.PhrasingContent +``` + +**Phrasing** content represents [**comment**](#comment) text, and its markup. ## Glossary -See the [unist glossary][21] for more terms. +See the [unist glossary][unist-glossary] for more terms. ### Docblock comment -A specially formatted [comment][22] in a source file used to document a segment of code or provide additional -information. +A specially formatted [comment][wiki-comment] in a source [*file*][unist-file] used to document a segment of code or +provide additional information. ## List of utilities -See the [unist list of utilities][4] for more utilities. - -- [`docast-parse`][23] — [unified][24] compliant file parser +See the [unist list of utilities][unist-utilities] for more utilities. ## Contribute See [`CONTRIBUTING.md`](CONTRIBUTING.md). -Ideas for new utilities and tools can be posted in [docast/ideas][25]. - -[1]: https://github.com/syntax-tree/unist#syntax-tree -[2]: https://github.com/syntax-tree/unist -[3]: https://heycam.github.io/webidl -[4]: https://github.com/syntax-tree/unist#list-of-utilities -[5]: https://www.ecma-international.org/ecma-262/9.0/index.html -[6]: https://typescriptlang.org -[7]: https://jsdoc.app -[8]: https://tsdoc.org -[9]: https://github.com/TypeStrong/typedoc -[10]: https://eslint.org -[11]: https://github.com/gajus/eslint-plugin-jsdoc#check-tag-names -[12]: https://github.com/gajus/eslint-plugin-jsdoc#structuredtags -[13]: https://github.com/syntax-tree/unist#node -[14]: https://github.com/syntax-tree/unist#parent -[15]: https://github.com/syntax-tree/unist#child -[16]: https://github.com/syntax-tree/unist#root -[17]: https://github.com/syntax-tree/unist#tree -[18]: https://github.com/syntax-tree/unist#child -[19]: https://github.com/syntax-tree/unist#positional-information -[20]: https://github.com/syntax-tree/unist#leaf -[21]: https://github.com/syntax-tree/unist#glossary -[22]: https://en.wikipedia.org/wiki/Comment_(computer_programming) -[23]: https://github.com/flex-development/docast-parse -[24]: https://github.com/unifiedjs/unified -[25]: https://github.com/flex-development/docast/discussions/new?category=ideas +Ideas for new utilities and tools can be posted in [docast/ideas][docast-ideas]. + +This project has a [code of conduct](CODE_OF_CONDUCT.md). By interacting with this repository, organization, or +community you agree to abide by its terms. + +[check-tag-names]: https://github.com/gajus/eslint-plugin-jsdoc-check-tag-names +[docast-ideas]: https://github.com/flex-development/docast/discussions/new?category=ideas +[eslint]: https://eslint.org +[javascript]: https://www.ecma-international.org/ecma-262/9.0/index.html +[jsdoc]: https://jsdoc.app +[mdast]: https://github.com/syntax-tree/mdast +[structuredtags]: https://github.com/gajus/eslint-plugin-jsdoc-structuredtags +[tsdoc]: https://tsdoc.org +[typedoc]: https://github.com/TypeStrong/typedoc +[typescript]: https://typescriptlang.org +[unist-child]: https://github.com/syntax-tree/unist#child +[unist-file]: https://github.com/syntax-tree/unist#file +[unist-generated]: https://github.com/syntax-tree/unist#generated +[unist-glossary]: https://github.com/syntax-tree/unist#glossary +[unist-leaf]: https://github.com/syntax-tree/unist#leaf +[unist-node]: https://github.com/syntax-tree/unist#node +[unist-parent]: https://github.com/syntax-tree/unist#parent +[unist-root]: https://github.com/syntax-tree/unist#root +[unist-syntax-tree]: https://github.com/syntax-tree/unist#syntax-tree +[unist-tree]: https://github.com/syntax-tree/unist#tree +[unist-utilities]: https://github.com/syntax-tree/unist#list-of-utilities +[unist]: https://github.com/syntax-tree/unist +[webidl-spec]: https://webidl.spec.whatwg.org/ +[wiki-comment]: https://en.wikipedia.org/wiki/Comment_(computer_programming) diff --git a/build.config.ts b/build.config.ts index 27c9c818..ab6b0b12 100644 --- a/build.config.ts +++ b/build.config.ts @@ -13,10 +13,7 @@ import { defineBuildConfig, type Config } from '@flex-development/mkbuild' */ const config: Config = defineBuildConfig({ charset: 'utf8', - entries: [ - { dts: 'only' }, - { dts: false, pattern: ['**/index.ts', 'enums/*'] } - ], + dts: 'only', tsconfig: 'tsconfig.build.json' }) diff --git a/package.json b/package.json index 1d050dfb..a96d5dbd 100644 --- a/package.json +++ b/package.json @@ -6,6 +6,8 @@ "ast", "doc", "docblock", + "markdown", + "mdast", "syntax-tree", "unist", "unist-spec" @@ -29,10 +31,9 @@ "dist" ], "exports": { - ".": "./dist/index.mjs", + ".": "./dist/index.d.mts", "./package.json": "./package.json" }, - "module": "./dist/index.mjs", "types": "./dist/index.d.mts", "scripts": { "build": "mkbuild", @@ -81,7 +82,8 @@ "@flex-development/tsconfig-utils": "2.0.2", "@types/eslint": "8.56.2", "@types/is-ci": "3.0.4", - "@types/node": "20.11.12", + "@types/mdast": "4.0.3", + "@types/node": "20.11.14", "@types/node-notifier": "8.0.5", "@types/unist": "3.0.2", "@typescript-eslint/eslint-plugin": "6.20.0", @@ -89,6 +91,7 @@ "@vates/toggle-scripts": "1.0.0", "cross-env": "7.0.3", "cspell": "8.3.2", + "debug": "4.3.4", "dprint": "0.45.0", "editorconfig": "2.0.0", "esbuild": "0.20.0", @@ -128,7 +131,8 @@ "yaml-eslint-parser": "1.2.2" }, "peerDependencies": { - "@types/unist": ">=2.0.6" + "@types/mdast": ">=4.0.3", + "@types/unist": ">=3.0.2" }, "packageManager": "yarn@4.1.0", "sideEffects": false diff --git a/src/content/__tests__/block-tag.spec-d.ts b/src/content/__tests__/block-tag.spec-d.ts new file mode 100644 index 00000000..be2fc5e4 --- /dev/null +++ b/src/content/__tests__/block-tag.spec-d.ts @@ -0,0 +1,23 @@ +/** + * @file Type Tests - BlockTag + * @module docast/content/tests/unit-d/BlockTag + */ + +import type { TypeExpression } from '#src/nodes' +import type * as TestSubject from '../block-tag' +import type { PhrasingContentMap } from '../phrasing' + +describe('unit-d:content/BlockTag', () => { + describe('BlockTagContentMap', () => { + it('should extend PhrasingContentMap', () => { + expectTypeOf() + .toMatchTypeOf() + }) + + it('should match [typeExpression: TypeExpression]', () => { + expectTypeOf() + .toHaveProperty('typeExpression') + .toEqualTypeOf + }) + }) +}) diff --git a/src/content/__tests__/content.spec-d.ts b/src/content/__tests__/content.spec-d.ts new file mode 100644 index 00000000..7900d31d --- /dev/null +++ b/src/content/__tests__/content.spec-d.ts @@ -0,0 +1,28 @@ +/** + * @file Type Tests - Content + * @module docast/content/tests/unit-d/Content + */ + +import type { BlockTagContent } from '../block-tag' +import type TestSubject from '../content' +import type { DescriptionContent } from '../description' +import type { FlowContent } from '../flow' +import type { PhrasingContent } from '../phrasing' + +describe('unit-d:content/Content', () => { + it('should allow BlockTagContent', () => { + expectTypeOf().toMatchTypeOf + }) + + it('should allow DescriptionContent', () => { + expectTypeOf().toMatchTypeOf + }) + + it('should allow FlowContent', () => { + expectTypeOf().toMatchTypeOf + }) + + it('should allow PhrasingContent', () => { + expectTypeOf().toMatchTypeOf + }) +}) diff --git a/src/content/__tests__/description.spec-d.ts b/src/content/__tests__/description.spec-d.ts new file mode 100644 index 00000000..40782ca8 --- /dev/null +++ b/src/content/__tests__/description.spec-d.ts @@ -0,0 +1,65 @@ +/** + * @file Type Tests - Description + * @module docast/content/tests/unit-d/Description + */ + +import type mdast from 'mdast' +import type * as TestSubject from '../description' +import type { PhrasingContentMap } from '../phrasing' + +describe('unit-d:content/Description', () => { + describe('DescriptionContentMap', () => { + it('should extend PhrasingContentMap', () => { + expectTypeOf() + .toMatchTypeOf() + }) + + it('should match [blockquote: mdast.Blockquote]', () => { + expectTypeOf() + .toHaveProperty('blockquote') + .toEqualTypeOf + }) + + it('should match [definition: mdast.Definition]', () => { + expectTypeOf() + .toHaveProperty('definition') + .toEqualTypeOf + }) + + it('should match [footnoteDefinition: mdast.FootnoteDefinition]', () => { + expectTypeOf() + .toHaveProperty('footnoteDefinition') + .toEqualTypeOf + }) + + it('should match [list: mdast.List]', () => { + expectTypeOf() + .toHaveProperty('list') + .toEqualTypeOf + }) + + it('should match [listItem: mdast.ListItem]', () => { + expectTypeOf() + .toHaveProperty('listItem') + .toEqualTypeOf + }) + + it('should match [paragraph: mdast.Paragraph]', () => { + expectTypeOf() + .toHaveProperty('paragraph') + .toEqualTypeOf + }) + + it('should match [table: mdast.Table]', () => { + expectTypeOf() + .toHaveProperty('table') + .toEqualTypeOf + }) + + it('should match [thematicBreak: mdast.ThematicBreak]', () => { + expectTypeOf() + .toHaveProperty('thematicBreak') + .toEqualTypeOf + }) + }) +}) diff --git a/src/content/__tests__/flow.spec-d.ts b/src/content/__tests__/flow.spec-d.ts new file mode 100644 index 00000000..6502918f --- /dev/null +++ b/src/content/__tests__/flow.spec-d.ts @@ -0,0 +1,23 @@ +/** + * @file Type Tests - Flow + * @module docast/content/tests/unit-d/Flow + */ + +import type { BlockTag, Description } from '#src/nodes' +import type * as TestSubject from '../flow' + +describe('unit-d:content/Flow', () => { + describe('FlowContentMap', () => { + it('should match [blockTag: BlockTag]', () => { + expectTypeOf() + .toHaveProperty('blockTag') + .toEqualTypeOf + }) + + it('should match [description: Description]', () => { + expectTypeOf() + .toHaveProperty('description') + .toEqualTypeOf + }) + }) +}) diff --git a/src/content/__tests__/phrasing.spec-d.ts b/src/content/__tests__/phrasing.spec-d.ts new file mode 100644 index 00000000..ee1622a4 --- /dev/null +++ b/src/content/__tests__/phrasing.spec-d.ts @@ -0,0 +1,29 @@ +/** + * @file Type Tests - Phrasing + * @module docast/content/tests/unit-d/Phrasing + */ + +import type { InlineTag } from '#src/nodes' +import type mdast from 'mdast' +import type * as TestSubject from '../phrasing' + +describe('unit-d:content/Phrasing', () => { + describe('PhrasingContentMap', () => { + it('should extend { + expectTypeOf() + .toMatchTypeOf() + }) + + it('should match [code: mdast.Code]', () => { + expectTypeOf() + .toHaveProperty('code') + .toEqualTypeOf + }) + + it('should match [inlineTag: InlineTag]', () => { + expectTypeOf() + .toHaveProperty('inlineTag') + .toEqualTypeOf + }) + }) +}) diff --git a/src/content/block-tag.ts b/src/content/block-tag.ts new file mode 100644 index 00000000..c674b834 --- /dev/null +++ b/src/content/block-tag.ts @@ -0,0 +1,37 @@ +/** + * @file Content - BlockTag + * @module docast/content/BlockTag + */ + +import type { TypeExpression } from '#src/nodes' +import type { PhrasingContentMap } from './phrasing' + +/** + * Union of registered docast nodes that can occur where block tag content is + * expected. + * + * To register custom docast nodes, augment {@linkcode BlockTagContentMap}. They + * will be added to this union automatically. + */ +type BlockTagContent = BlockTagContentMap[keyof BlockTagContentMap] + +/** + * Registry of nodes that can occur where {@linkcode BlockTagContent} is + * expected. + * + * This interface can be augmented to register custom node types. + * + * @example + * declare module '@flex-development/docast' { + * interface BlockContentMap { + * custom: CustomNode + * } + * } + * + * @extends {PhrasingContentMap} + */ +interface BlockTagContentMap extends PhrasingContentMap { + typeExpression: TypeExpression +} + +export type { BlockTagContent, BlockTagContentMap } diff --git a/src/content/content.ts b/src/content/content.ts new file mode 100644 index 00000000..3ae83e2b --- /dev/null +++ b/src/content/content.ts @@ -0,0 +1,28 @@ +/** + * @file Content - Content + * @module docast/content/Content + */ + +import type { BlockTagContent } from './block-tag' +import type { DescriptionContent } from './description' +import type { FlowContent } from './flow' +import type { PhrasingContent } from './phrasing' + +/** + * Union of registered content model nodes. + * + * Nodes are grouped by content type, if applicable. Each node in docast, with + * the exception of `Comment`, falls into one or more categories of `Content`. + * + * @see {@linkcode BlockTagContent} + * @see {@linkcode DescriptionContent} + * @see {@linkcode FlowContent} + * @see {@linkcode PhrasingContent} + */ +type Content = + | BlockTagContent + | DescriptionContent + | FlowContent + | PhrasingContent + +export type { Content as default } diff --git a/src/content/description.ts b/src/content/description.ts new file mode 100644 index 00000000..ca38998d --- /dev/null +++ b/src/content/description.ts @@ -0,0 +1,44 @@ +/** + * @file Content - Description + * @module docast/content/Description + */ + +import type mdast from 'mdast' +import type { PhrasingContentMap } from './phrasing' + +/** + * Union of registered docast nodes that can occur where description content is + * expected. + * + * To register custom docast nodes, augment {@linkcode DescriptionContentMap}. + * They will be added to this union automatically. + */ +type DescriptionContent = DescriptionContentMap[keyof DescriptionContentMap] + +/** + * Registry of docast nodes that can occur where {@linkcode DescriptionContent} + * is expected. + * + * This interface can be augmented to register custom node types. + * + * @example + * declare module '@flex-development/docast' { + * interface DescriptionContentMap { + * custom: CustomNode + * } + * } + * + * @extends {PhrasingContentMap} + */ +interface DescriptionContentMap extends PhrasingContentMap { + blockquote: mdast.Blockquote + definition: mdast.Definition + footnoteDefinition: mdast.FootnoteDefinition + list: mdast.List + listItem: mdast.ListItem + paragraph: mdast.Paragraph + table: mdast.Table + thematicBreak: mdast.ThematicBreak +} + +export type { DescriptionContent, DescriptionContentMap } diff --git a/src/content/flow.ts b/src/content/flow.ts new file mode 100644 index 00000000..4793139e --- /dev/null +++ b/src/content/flow.ts @@ -0,0 +1,35 @@ +/** + * @file Content - Flow + * @module docast/content/Flow + */ + +import type { BlockTag, Description } from '#src/nodes' + +/** + * Union of registered docast nodes that can occur where `Comment` flow content + * is expected. + * + * To register custom docast nodes, augment {@linkcode FlowContentMap}. They + * will be added to this union automatically. + */ +type FlowContent = FlowContentMap[keyof FlowContentMap] + +/** + * Registry of docast nodes that can occur where {@linkcode FlowContent} is + * expected. + * + * This interface can be augmented to register custom node types. + * + * @example + * declare module '@flex-development/docast' { + * interface FlowContentMap { + * custom: CustomNode + * } + * } + */ +interface FlowContentMap { + blockTag: BlockTag + description: Description +} + +export type { FlowContent, FlowContentMap } diff --git a/src/content/index.ts b/src/content/index.ts new file mode 100644 index 00000000..e9911043 --- /dev/null +++ b/src/content/index.ts @@ -0,0 +1,10 @@ +/** + * @file Entry Point - Content + * @module docast/content + */ + +export type * from './block-tag' +export type { default as Content } from './content' +export type * from './description' +export type * from './flow' +export type * from './phrasing' diff --git a/src/content/phrasing.ts b/src/content/phrasing.ts new file mode 100644 index 00000000..1b1b43bd --- /dev/null +++ b/src/content/phrasing.ts @@ -0,0 +1,38 @@ +/** + * @file Content - Phrasing + * @module docast/content/Phrasing + */ + +import type { InlineTag } from '#src/nodes' +import type mdast from 'mdast' + +/** + * Union of registered docast nodes that can occur where phrasing content is + * expected. + * + * To register custom docast nodes, augment {@linkcode PhrasingContentMap}. They + * will be added to this union automatically. + */ +type PhrasingContent = PhrasingContentMap[keyof PhrasingContentMap] + +/** + * Registry of docast nodes that can occur where {@linkcode PhrasingContent} is + * expected. + * + * This interface can be augmented to register custom node types. + * + * @example + * declare module '@flex-development/docast' { + * interface PhrasingContentMap { + * custom: CustomNode + * } + * } + * + * @extends {mdast.PhrasingContentMap} + */ +interface PhrasingContentMap extends mdast.PhrasingContentMap { + code: mdast.Code + inlineTag: InlineTag +} + +export type { PhrasingContent, PhrasingContentMap } diff --git a/src/enums/__tests__/kind.spec-d.ts b/src/enums/__tests__/kind.spec-d.ts deleted file mode 100644 index 8939f378..00000000 --- a/src/enums/__tests__/kind.spec-d.ts +++ /dev/null @@ -1,162 +0,0 @@ -/** - * @file Type Tests - Kind - * @module docast/enums/tests/unit-d/Kind - */ - -import type { EmptyString } from '@flex-development/tutils' -import type TestSubject from '../kind' - -describe('unit-d:enums/Kind', () => { - it('should match [ACCESSOR = "accessor"]', () => { - expectTypeOf() - .toHaveProperty('ACCESSOR') - .extract<'accessor'>() - .toBeString() - }) - - it('should match [CLASS = "class"]', () => { - expectTypeOf() - .toHaveProperty('CLASS') - .extract<'class'>() - .toBeString() - }) - - it('should match [CONST = "const"]', () => { - expectTypeOf() - .toHaveProperty('CONST') - .extract<'const'>() - .toBeString() - }) - - it('should match [CONSTRUCTOR = "constructor"]', () => { - expectTypeOf() - .toHaveProperty('CONSTRUCTOR') - .extract<'constructor'>() - .toBeString() - }) - - it('should match [DEFAULT = "default"]', () => { - expectTypeOf() - .toHaveProperty('DEFAULT') - .extract<'default'>() - .toBeString() - }) - - it('should match [ENUM = "enum"]', () => { - expectTypeOf() - .toHaveProperty('ENUM') - .extract<'enum'>() - .toBeString() - }) - - it('should match [ENUM_CONST = "const enum"]', () => { - expectTypeOf() - .toHaveProperty('ENUM_CONST') - .extract<'const enum'>() - .toBeString() - }) - - it('should match [FUNCTION = "function"]', () => { - expectTypeOf() - .toHaveProperty('FUNCTION') - .extract<'function'>() - .toBeString() - }) - - it('should match [GENERATOR = "function*"]', () => { - expectTypeOf() - .toHaveProperty('GENERATOR') - .extract<'function*'>() - .toBeString() - }) - - it('should match [GET = "get"]', () => { - expectTypeOf() - .toHaveProperty('GET') - .extract<'get'>() - .toBeString() - }) - - it('should match [INTERFACE = "interface"]', () => { - expectTypeOf() - .toHaveProperty('INTERFACE') - .extract<'interface'>() - .toBeString() - }) - - it('should match [LET = "let"]', () => { - expectTypeOf() - .toHaveProperty('LET') - .extract<'let'>() - .toBeString() - }) - - it('should match [MEMBER = "member"]', () => { - expectTypeOf() - .toHaveProperty('MEMBER') - .extract<'member'>() - .toBeString() - }) - - it('should match [METHOD = "method"]', () => { - expectTypeOf() - .toHaveProperty('METHOD') - .extract<'method'>() - .toBeString() - }) - - it('should match [MODULE = "module"]', () => { - expectTypeOf() - .toHaveProperty('MODULE') - .extract<'module'>() - .toBeString() - }) - - it('should match [NAMESPACE = "namespace"]', () => { - expectTypeOf() - .toHaveProperty('NAMESPACE') - .extract<'namespace'>() - .toBeString() - }) - - it('should match [PROPERTY = "property"]', () => { - expectTypeOf() - .toHaveProperty('PROPERTY') - .extract<'property'>() - .toBeString() - }) - - it('should match [SET = "set"]', () => { - expectTypeOf() - .toHaveProperty('SET') - .extract<'set'>() - .toBeString() - }) - - it('should match [STATEMENT = "statement"]', () => { - expectTypeOf() - .toHaveProperty('STATEMENT') - .extract<'statement'>() - .toBeString() - }) - - it('should match [TYPE = "type"]', () => { - expectTypeOf() - .toHaveProperty('TYPE') - .extract<'type'>() - .toBeString() - }) - - it('should match [UNKNOWN = ""]', () => { - expectTypeOf() - .toHaveProperty('UNKNOWN') - .toMatchTypeOf() - }) - - it('should match [VAR = "var"]', () => { - expectTypeOf() - .toHaveProperty('VAR') - .extract<'var'>() - .toBeString() - }) -}) diff --git a/src/enums/__tests__/modifier.spec-d.ts b/src/enums/__tests__/modifier.spec-d.ts deleted file mode 100644 index b3c56303..00000000 --- a/src/enums/__tests__/modifier.spec-d.ts +++ /dev/null @@ -1,85 +0,0 @@ -/** - * @file Type Tests - Modifier - * @module docast/enums/tests/unit-d/Modifier - */ - -import type TestSubject from '../modifier' - -describe('unit-d:enums/Modifier', () => { - it('should match [ABSTRACT = "abstract"]', () => { - expectTypeOf() - .toHaveProperty('ABSTRACT') - .extract<'abstract'>() - .toBeString() - }) - - it('should match [ASYNC = "async"]', () => { - expectTypeOf() - .toHaveProperty('ASYNC') - .extract<'async'>() - .toBeString() - }) - - it('should match [DECLARE = "declare"]', () => { - expectTypeOf() - .toHaveProperty('DECLARE') - .extract<'declare'>() - .toBeString() - }) - - it('should match [DEFAULT = "default"]', () => { - expectTypeOf() - .toHaveProperty('DEFAULT') - .extract<'default'>() - .toBeString() - }) - - it('should match [EXPORT = "export"]', () => { - expectTypeOf() - .toHaveProperty('EXPORT') - .extract<'export'>() - .toBeString() - }) - - it('should match [OVERRIDE = "override"]', () => { - expectTypeOf() - .toHaveProperty('OVERRIDE') - .extract<'override'>() - .toBeString() - }) - - it('should match [PRIVATE = "private"]', () => { - expectTypeOf() - .toHaveProperty('PRIVATE') - .extract<'private'>() - .toBeString() - }) - - it('should match [PROTECTED = "protected"]', () => { - expectTypeOf() - .toHaveProperty('PROTECTED') - .extract<'protected'>() - .toBeString() - }) - - it('should match [PUBLIC = "public"]', () => { - expectTypeOf() - .toHaveProperty('PUBLIC') - .extract<'public'>() - .toBeString() - }) - - it('should match [READONLY = "readonly"]', () => { - expectTypeOf() - .toHaveProperty('READONLY') - .extract<'readonly'>() - .toBeString() - }) - - it('should match [STATIC = "static"]', () => { - expectTypeOf() - .toHaveProperty('STATIC') - .extract<'static'>() - .toBeString() - }) -}) diff --git a/src/enums/__tests__/type.spec-d.ts b/src/enums/__tests__/type.spec-d.ts deleted file mode 100644 index 0f04926f..00000000 --- a/src/enums/__tests__/type.spec-d.ts +++ /dev/null @@ -1,43 +0,0 @@ -/** - * @file Type Tests - Type - * @module docast/enums/tests/unit-d/Type - */ - -import type TestSubject from '../type' - -describe('unit-d:enums/Type', () => { - it('should match [BLOCK_TAG = "block-tag"]', () => { - expectTypeOf() - .toHaveProperty('BLOCK_TAG') - .extract<'block-tag'>() - .toBeString() - }) - - it('should match [COMMENT = "comment"]', () => { - expectTypeOf() - .toHaveProperty('COMMENT') - .extract<'comment'>() - .toBeString() - }) - - it('should match [IMPLICIT_DESCRIPTION = "implicit-description"]', () => { - expectTypeOf() - .toHaveProperty('IMPLICIT_DESCRIPTION') - .extract<'implicit-description'>() - .toBeString() - }) - - it('should match [INLINE_TAG = "inline-tag"]', () => { - expectTypeOf() - .toHaveProperty('INLINE_TAG') - .extract<'inline-tag'>() - .toBeString() - }) - - it('should match [ROOT = "root"]', () => { - expectTypeOf() - .toHaveProperty('ROOT') - .extract<'root'>() - .toBeString() - }) -}) diff --git a/src/enums/index.ts b/src/enums/index.ts deleted file mode 100644 index 4ae3aa86..00000000 --- a/src/enums/index.ts +++ /dev/null @@ -1,8 +0,0 @@ -/** - * @file Enums - Entry Point - * @module docast/enums - */ - -export { default as Kind } from './kind' -export { default as Modifier } from './modifier' -export { default as Type } from './type' diff --git a/src/enums/kind.ts b/src/enums/kind.ts deleted file mode 100644 index ae4904c7..00000000 --- a/src/enums/kind.ts +++ /dev/null @@ -1,36 +0,0 @@ -/** - * @file Enums - Kind - * @module docast/enums/Kind - */ - -/** - * Code segment syntax kinds. - * - * @enum {Lowercase} - */ -enum Kind { - ACCESSOR = 'accessor', - CLASS = 'class', - CONST = 'const', - CONSTRUCTOR = 'constructor', - DEFAULT = 'default', - ENUM = 'enum', - ENUM_CONST = 'const enum', - FUNCTION = 'function', - GENERATOR = 'function*', - GET = 'get', - INTERFACE = 'interface', - LET = 'let', - MEMBER = 'member', - METHOD = 'method', - MODULE = 'module', - NAMESPACE = 'namespace', - PROPERTY = 'property', - SET = 'set', - STATEMENT = 'statement', - TYPE = 'type', - UNKNOWN = '', - VAR = 'var' -} - -export default Kind diff --git a/src/enums/modifier.ts b/src/enums/modifier.ts deleted file mode 100644 index 8be64057..00000000 --- a/src/enums/modifier.ts +++ /dev/null @@ -1,25 +0,0 @@ -/** - * @file Enums - Modifier - * @module docast/enums/Modifier - */ - -/** - * Modifier keywords. - * - * @enum {Lowercase} - */ -enum Modifier { - ABSTRACT = 'abstract', - ASYNC = 'async', - DECLARE = 'declare', - DEFAULT = 'default', - EXPORT = 'export', - OVERRIDE = 'override', - PRIVATE = 'private', - PROTECTED = 'protected', - PUBLIC = 'public', - READONLY = 'readonly', - STATIC = 'static' -} - -export default Modifier diff --git a/src/enums/type.ts b/src/enums/type.ts deleted file mode 100644 index 6a0756ac..00000000 --- a/src/enums/type.ts +++ /dev/null @@ -1,21 +0,0 @@ -/** - * @file Enums - Type - * @module docast/enums/Type - */ - -/** - * Node variants. - * - * @see https://github.com/syntax-tree/unist#type - * - * @enum {Lowercase} - */ -enum Type { - BLOCK_TAG = 'block-tag', - COMMENT = 'comment', - IMPLICIT_DESCRIPTION = 'implicit-description', - INLINE_TAG = 'inline-tag', - ROOT = 'root' -} - -export default Type diff --git a/src/index.ts b/src/index.ts index 305ca69a..b9185ec4 100644 --- a/src/index.ts +++ b/src/index.ts @@ -3,7 +3,7 @@ * @module docast */ -export * from './enums' -export * from './interfaces' -export * from './nodes' -export * from './types' +export type * from './content' +export type * from './interfaces' +export type * from './mixins' +export type * from './nodes' diff --git a/src/interfaces/__tests__/code-segment.spec-d.ts b/src/interfaces/__tests__/code-segment.spec-d.ts new file mode 100644 index 00000000..fd833fce --- /dev/null +++ b/src/interfaces/__tests__/code-segment.spec-d.ts @@ -0,0 +1,32 @@ +/** + * @file Type Tests - CodeSegment + * @module docast/interfaces/tests/unit-d/CodeSegment + */ + +import type { Nilable, NumberString } from '@flex-development/tutils' +import type TestSubject from '../code-segment' +import type Position from '../position' + +describe('unit-d:interfaces/CodeSegment', () => { + it('should match [identifier: string]', () => { + expectTypeOf().toHaveProperty('identifier').toBeString() + }) + + it('should match [kind: NumberString]', () => { + expectTypeOf() + .toHaveProperty('kind') + .toEqualTypeOf() + }) + + it('should match [parent?: Nilable]', () => { + expectTypeOf() + .toHaveProperty('parent') + .toEqualTypeOf>() + }) + + it('should match [position: Position]', () => { + expectTypeOf() + .toHaveProperty('position') + .toEqualTypeOf() + }) +}) diff --git a/src/interfaces/__tests__/context.spec-d.ts b/src/interfaces/__tests__/context.spec-d.ts deleted file mode 100644 index 3d2afe2e..00000000 --- a/src/interfaces/__tests__/context.spec-d.ts +++ /dev/null @@ -1,33 +0,0 @@ -/** - * @file Type Tests - Context - * @module docast/interfaces/tests/unit-d/Context - */ - -import type { Kind } from '#src/enums' -import type { LiteralUnion, Nullable } from '@flex-development/tutils' -import type TestSubject from '../context' -import type Position from '../position' - -describe('unit-d:interfaces/Context', () => { - it('should match [identifier: string]', () => { - expectTypeOf().toHaveProperty('identifier').toBeString() - }) - - it('should match [kind: LiteralUnion]', () => { - expectTypeOf() - .toHaveProperty('kind') - .toEqualTypeOf>() - }) - - it('should match [parent: Nullable]', () => { - expectTypeOf() - .toHaveProperty('parent') - .toEqualTypeOf>() - }) - - it('should match [position: Position]', () => { - expectTypeOf() - .toHaveProperty('position') - .toEqualTypeOf() - }) -}) diff --git a/src/interfaces/__tests__/data.spec-d.ts b/src/interfaces/__tests__/data.spec-d.ts new file mode 100644 index 00000000..addbf2d2 --- /dev/null +++ b/src/interfaces/__tests__/data.spec-d.ts @@ -0,0 +1,13 @@ +/** + * @file Type Tests - Data + * @module docast/interfaces/tests/unit-d/Data + */ + +import type unist from 'unist' +import type TestSubject from '../data' + +describe('unit-d:interfaces/Data', () => { + it('should extend unist.Data', () => { + expectTypeOf().toMatchTypeOf() + }) +}) diff --git a/src/interfaces/__tests__/position.spec-d.ts b/src/interfaces/__tests__/position.spec-d.ts index a1d4d21b..a261eb47 100644 --- a/src/interfaces/__tests__/position.spec-d.ts +++ b/src/interfaces/__tests__/position.spec-d.ts @@ -3,15 +3,10 @@ * @module docast/interfaces/tests/unit-d/Position */ -import type unist from 'unist' import type Point from '../point' import type TestSubject from '../position' describe('unit-d:interfaces/Position', () => { - it('should extend unist.Position', () => { - expectTypeOf().toMatchTypeOf() - }) - it('should match [end: Point]', () => { expectTypeOf().toHaveProperty('end').toEqualTypeOf() }) diff --git a/src/interfaces/code-segment.ts b/src/interfaces/code-segment.ts new file mode 100644 index 00000000..8ca2082c --- /dev/null +++ b/src/interfaces/code-segment.ts @@ -0,0 +1,38 @@ +/** + * @file Interfaces - CodeSegment + * @module docast/interfaces/CodeSegment + */ + +import type { Nilable, NumberString } from '@flex-development/tutils' +import type Position from './position' + +/** + * The segment of code a comment documents. + */ +interface CodeSegment { + /** + * Code segment name. + */ + identifier: string + + /** + * Code syntax kind. + */ + kind: NumberString + + /** + * Parent code. + */ + parent?: Nilable + + /** + * [Position][1] of code in source file. + * + * [1]: https://github.com/syntax-tree/unist#position + * + * @see {@linkcode Position} + */ + position: Position +} + +export type { CodeSegment as default } diff --git a/src/interfaces/context.ts b/src/interfaces/context.ts deleted file mode 100644 index 8add116c..00000000 --- a/src/interfaces/context.ts +++ /dev/null @@ -1,39 +0,0 @@ -/** - * @file Interfaces - Context - * @module docast/interfaces/Context - */ - -import type { Kind } from '#src/enums' -import type { LiteralUnion, Nullable } from '@flex-development/tutils' -import type Position from './position' - -/** - * Data representing the segment of code a [`Comment`][1] documents. - * - * [1]: {@link ../nodes/comment.ts} - */ -interface Context { - /** - * Segment name. - */ - identifier: string - - /** - * Segment syntax kind. - */ - kind: LiteralUnion - - /** - * Segment parent. - */ - parent: Nullable - - /** - * [Position][1] of code segment in source file. - * - * [1]: https://github.com/syntax-tree/unist#position - */ - position: Position -} - -export type { Context as default } diff --git a/src/interfaces/data.ts b/src/interfaces/data.ts new file mode 100644 index 00000000..682ca2d9 --- /dev/null +++ b/src/interfaces/data.ts @@ -0,0 +1,26 @@ +/** + * @file Interfaces - Data + * @module docast/interfaces/Data + */ + +import type unist from 'unist' + +/** + * Info associated with docast nodes. + * + * This space is guaranteed to never be specified by unist or docast, but it + * can be used in utilities and plugins to store custom data. + * + * @example + * declare module '@flex-development/docast' { + * interface Data { + * // `node.data.id` is typed as `number | undefined` + * id?: number | undefined + * } + * } + * + * @extends {unist.Data} + */ +interface Data extends unist.Data {} + +export type { Data as default } diff --git a/src/interfaces/index.ts b/src/interfaces/index.ts index 4f41d712..ae411ccb 100644 --- a/src/interfaces/index.ts +++ b/src/interfaces/index.ts @@ -1,8 +1,9 @@ /** - * @file Interfaces - Entry Point + * @file Entry Point - Interfaces * @module docast/interfaces */ -export type { default as Context } from './context' +export type { default as CodeSegment } from './code-segment' +export type { default as Data } from './data' export type { default as Point } from './point' export type { default as Position } from './position' diff --git a/src/interfaces/point.ts b/src/interfaces/point.ts index 992490ef..ac329833 100644 --- a/src/interfaces/point.ts +++ b/src/interfaces/point.ts @@ -10,13 +10,13 @@ import type unist from 'unist' * * [1]: https://github.com/syntax-tree/unist#file * - * @see https://github.com/syntax-tree/unist#point + * @see {@linkcode unist.Point} * * @extends {Required} */ interface Point extends Required { /** - * Index of character in a source file (0-indexed integer). + * Index of character in source file (0-indexed integer). */ offset: number } diff --git a/src/interfaces/position.ts b/src/interfaces/position.ts index 945d72e9..b8d4060c 100644 --- a/src/interfaces/position.ts +++ b/src/interfaces/position.ts @@ -3,20 +3,28 @@ * @module docast/interfaces/Position */ -import type unist from 'unist' import type Point from './point' /** * Location of a node in a source [*file*][1]. * - * [1]: https://github.com/syntax-tree/unist#file - * - * @see https://github.com/syntax-tree/unist#position + * A position is a range between two points. * - * @extends {unist.Position} + * [1]: https://github.com/syntax-tree/unist#file */ -interface Position extends unist.Position { +interface Position { + /** + * Index of first character after parsed source region. + * + * @see {@linkcode Point} + */ end: Point + + /** + * Index of first character in parsed source region. + * + * @see {@linkcode Point} + */ start: Point } diff --git a/src/mixins/__tests__/tag.spec-d.ts b/src/mixins/__tests__/tag.spec-d.ts new file mode 100644 index 00000000..8796b80b --- /dev/null +++ b/src/mixins/__tests__/tag.spec-d.ts @@ -0,0 +1,20 @@ +/** + * @file Type Tests - Tag + * @module docast/mixins/tests/unit-d/Tag + */ + +import type TestSubject from '../tag' + +describe('unit-d:mixins/Tag', () => { + it('should match [name: string]', () => { + expectTypeOf().toHaveProperty('name').toBeString() + }) + + it('should match [prefix: string]', () => { + expectTypeOf().toHaveProperty('prefix').toBeString() + }) + + it('should match [tag: string]', () => { + expectTypeOf().toHaveProperty('tag').toBeString() + }) +}) diff --git a/src/mixins/index.ts b/src/mixins/index.ts new file mode 100644 index 00000000..a789a9e4 --- /dev/null +++ b/src/mixins/index.ts @@ -0,0 +1,6 @@ +/** + * @file Entry Point - Mixins + * @module docast/mixins + */ + +export type { default as Tag } from './tag' diff --git a/src/mixins/tag.ts b/src/mixins/tag.ts new file mode 100644 index 00000000..5d6ccfd7 --- /dev/null +++ b/src/mixins/tag.ts @@ -0,0 +1,26 @@ +/** + * @file Mixins - Tag + * @module docast/mixins/Tag + */ + +/** + * Metadata associated with a docblock comment. + */ +interface Tag { + /** + * Tag name. + */ + name: string + + /** + * Tag prefix. + */ + prefix: string + + /** + * Parsed tag. + */ + tag: string +} + +export type { Tag as default } diff --git a/src/nodes/__tests__/block-tag.spec-d.ts b/src/nodes/__tests__/block-tag.spec-d.ts new file mode 100644 index 00000000..fa3936be --- /dev/null +++ b/src/nodes/__tests__/block-tag.spec-d.ts @@ -0,0 +1,38 @@ +/** + * @file Type Tests - BlockTag + * @module docast/nodes/tests/unit-d/BlockTag + */ + +import type { BlockTagContent } from '#src/content' +import type { Tag } from '#src/mixins' +import type { Optional } from '@flex-development/tutils' +import type { BlockTagData, default as TestSubject } from '../block-tag' +import type Parent from '../parent' + +describe('unit-d:nodes/BlockTag', () => { + it('should extend Parent', () => { + expectTypeOf().toMatchTypeOf() + }) + + it('should extend Tag', () => { + expectTypeOf().toMatchTypeOf() + }) + + it('should match [children: BlockContent[]]', () => { + expectTypeOf() + .toHaveProperty('children') + .toEqualTypeOf() + }) + + it('should match [data?: Optional]', () => { + expectTypeOf() + .toHaveProperty('data') + .toEqualTypeOf>() + }) + + it('should match [type: "block-tag"]', () => { + expectTypeOf() + .toHaveProperty('type') + .toEqualTypeOf<'block-tag'>() + }) +}) diff --git a/src/nodes/__tests__/comment.spec-d.ts b/src/nodes/__tests__/comment.spec-d.ts index 4d4532fa..cd73b1b9 100644 --- a/src/nodes/__tests__/comment.spec-d.ts +++ b/src/nodes/__tests__/comment.spec-d.ts @@ -3,40 +3,38 @@ * @module docast/nodes/tests/unit-d/Comment */ -import type { Type } from '#src/enums' -import type { Context, Position } from '#src/interfaces' -import type { Nullable } from '@flex-development/tutils' -import type TestSubject from '../comment' -import type ImplicitDescription from '../implicit-description' +import type { FlowContent } from '#src/content' +import type { CodeSegment } from '#src/interfaces' +import type { Nilable, Optional } from '@flex-development/tutils' +import type { CommentData, default as TestSubject } from '../comment' import type Parent from '../parent' -import type BlockTag from '../tag-block' describe('unit-d:nodes/Comment', () => { - it('should extend Parent', () => { - expectTypeOf().toMatchTypeOf< - Parent - >() + it('should extend Parent>', () => { + expectTypeOf().toMatchTypeOf() }) - it('should match [context: Nullable]', () => { + it('should match [children: FlowContent[]]', () => { expectTypeOf() - .toHaveProperty('context') - .toEqualTypeOf>() + .toHaveProperty('children') + .toEqualTypeOf() }) - it('should match [position: Position]', () => { + it('should match [code?: Nilable]', () => { expectTypeOf() - .toHaveProperty('position') - .toEqualTypeOf() + .toHaveProperty('code') + .toEqualTypeOf>() }) - it('should match [type: Type.COMMENT]', () => { + it('should match [data?: Optional]', () => { expectTypeOf() - .toHaveProperty('type') - .toEqualTypeOf() + .toHaveProperty('data') + .toEqualTypeOf>() }) - it('should match [value: string]', () => { - expectTypeOf().toHaveProperty('value').toBeString() + it('should match [type: "comment"]', () => { + expectTypeOf() + .toHaveProperty('type') + .toEqualTypeOf<'comment'>() }) }) diff --git a/src/nodes/__tests__/description.spec-d.ts b/src/nodes/__tests__/description.spec-d.ts new file mode 100644 index 00000000..744f1020 --- /dev/null +++ b/src/nodes/__tests__/description.spec-d.ts @@ -0,0 +1,33 @@ +/** + * @file Type Tests - Description + * @module docast/nodes/tests/unit-d/Description + */ + +import type { DescriptionContent } from '#src/content' +import type { Optional } from '@flex-development/tutils' +import type { DescriptionData, default as TestSubject } from '../description' +import type Parent from '../parent' + +describe('unit-d:nodes/Description', () => { + it('should extend Parent', () => { + expectTypeOf().toMatchTypeOf() + }) + + it('should match [children: DescriptionContent[]]', () => { + expectTypeOf() + .toHaveProperty('children') + .toEqualTypeOf() + }) + + it('should match [data?: Optional]', () => { + expectTypeOf() + .toHaveProperty('data') + .toEqualTypeOf>() + }) + + it('should match [type: "description"]', () => { + expectTypeOf() + .toHaveProperty('type') + .toEqualTypeOf<'description'>() + }) +}) diff --git a/src/nodes/__tests__/implicit-description.spec-d.ts b/src/nodes/__tests__/implicit-description.spec-d.ts deleted file mode 100644 index 0977b107..00000000 --- a/src/nodes/__tests__/implicit-description.spec-d.ts +++ /dev/null @@ -1,32 +0,0 @@ -/** - * @file Type Tests - ImplicitDescription - * @module docast/nodes/tests/unit-d/ImplicitDescription - */ - -import type { Type } from '#src/enums' -import type { Position } from '#src/interfaces' -import type TestSubject from '../implicit-description' -import type Parent from '../parent' -import type InlineTag from '../tag-inline' - -describe('unit-d:nodes/ImplicitDescription', () => { - it('should extend Parent', () => { - expectTypeOf().toMatchTypeOf>() - }) - - it('should match [position: Position]', () => { - expectTypeOf() - .toHaveProperty('position') - .toEqualTypeOf() - }) - - it('should match [type: Type.IMPLICIT_DESCRIPTION]', () => { - expectTypeOf() - .toHaveProperty('type') - .toEqualTypeOf() - }) - - it('should match [value: string]', () => { - expectTypeOf().toHaveProperty('value').toBeString() - }) -}) diff --git a/src/nodes/__tests__/inline-tag.spec-d.ts b/src/nodes/__tests__/inline-tag.spec-d.ts new file mode 100644 index 00000000..850eec6f --- /dev/null +++ b/src/nodes/__tests__/inline-tag.spec-d.ts @@ -0,0 +1,31 @@ +/** + * @file Type Tests - InlineTag + * @module docast/nodes/tests/unit-d/InlineTag + */ + +import type { Tag } from '#src/mixins' +import type { Optional } from '@flex-development/tutils' +import type { InlineTagData, default as TestSubject } from '../inline-tag' +import type Literal from '../literal' + +describe('unit-d:nodes/InlineTag', () => { + it('should extend Literal', () => { + expectTypeOf().toMatchTypeOf() + }) + + it('should extend Tag', () => { + expectTypeOf().toMatchTypeOf() + }) + + it('should match [data?: Optional]', () => { + expectTypeOf() + .toHaveProperty('data') + .toEqualTypeOf>() + }) + + it('should match [type: "inline-tag"]', () => { + expectTypeOf() + .toHaveProperty('type') + .toEqualTypeOf<'inline-tag'>() + }) +}) diff --git a/src/nodes/__tests__/literal.spec-d.ts b/src/nodes/__tests__/literal.spec-d.ts new file mode 100644 index 00000000..bfafd756 --- /dev/null +++ b/src/nodes/__tests__/literal.spec-d.ts @@ -0,0 +1,17 @@ +/** + * @file Type Tests - Literal + * @module docast/nodes/tests/unit-d/Literal + */ + +import type TestSubject from '../literal' +import type Node from '../node' + +describe('unit-d:nodes/Literal', () => { + it('should extend Node', () => { + expectTypeOf().toMatchTypeOf() + }) + + it('should match [value: string]', () => { + expectTypeOf().toHaveProperty('value').toBeString() + }) +}) diff --git a/src/nodes/__tests__/node.spec-d.ts b/src/nodes/__tests__/node.spec-d.ts index 7159a0c1..08a0809a 100644 --- a/src/nodes/__tests__/node.spec-d.ts +++ b/src/nodes/__tests__/node.spec-d.ts @@ -3,29 +3,25 @@ * @module docast/nodes/tests/unit-d/Node */ -import type { Type } from '#src/enums' -import type { Position } from '#src/interfaces' +import type { Data, Position } from '#src/interfaces' +import type { Optional } from '@flex-development/tutils' import type unist from 'unist' import type TestSubject from '../node' describe('unit-d:nodes/Node', () => { - it('should extend unist.Node', () => { + it('should extend unist.Node', () => { expectTypeOf().toMatchTypeOf() }) - it('should match [data?: Data]', () => { + it('should match [data?: Optional]', () => { expectTypeOf() .toHaveProperty('data') - .toEqualTypeOf() + .toEqualTypeOf>() }) - it('should match [position?: Position]', () => { + it('should match [position?: Optional]', () => { expectTypeOf() .toHaveProperty('position') - .toEqualTypeOf() - }) - - it('should match [type: Type]', () => { - expectTypeOf().toHaveProperty('type').toEqualTypeOf() + .toEqualTypeOf>() }) }) diff --git a/src/nodes/__tests__/parent.spec-d.ts b/src/nodes/__tests__/parent.spec-d.ts index bb2f1a1f..a87b9968 100644 --- a/src/nodes/__tests__/parent.spec-d.ts +++ b/src/nodes/__tests__/parent.spec-d.ts @@ -3,24 +3,19 @@ * @module docast/nodes/tests/unit-d/Parent */ -import type { Child, ParentType } from '#src/types' +import type { Content } from '#src/content' +import type Comment from '../comment' import type Node from '../node' import type TestSubject from '../parent' describe('unit-d:nodes/Parent', () => { - it('should extend Node', () => { + it('should extend Node', () => { expectTypeOf().toMatchTypeOf() }) - it('should match [children: ChildNode[]]', () => { + it('should match [children: (Comment | Content)[]]', () => { expectTypeOf() .toHaveProperty('children') - .toEqualTypeOf() - }) - - it('should match [type: ParentType]', () => { - expectTypeOf() - .toHaveProperty('type') - .toEqualTypeOf() + .toEqualTypeOf<(Comment | Content)[]>() }) }) diff --git a/src/nodes/__tests__/root.spec-d.ts b/src/nodes/__tests__/root.spec-d.ts index 8b3b5105..6adef972 100644 --- a/src/nodes/__tests__/root.spec-d.ts +++ b/src/nodes/__tests__/root.spec-d.ts @@ -3,25 +3,33 @@ * @module docast/nodes/tests/unit-d/Root */ -import type { Type } from '#src/enums' +import type { Optional } from '@flex-development/tutils' import type Comment from '../comment' import type Parent from '../parent' -import type TestSubject from '../root' +import type { RootData, default as TestSubject } from '../root' describe('unit-d:nodes/Root', () => { - it('should extend Parent', () => { - expectTypeOf().toMatchTypeOf>() + it('should extend Parent', () => { + expectTypeOf().toMatchTypeOf() }) - it('should match [position?: never]', () => { + it('should match [children: Comment[]]', () => { expectTypeOf() - .toHaveProperty('position') - .toMatchTypeOf() + .toHaveProperty('children') + .toEqualTypeOf() }) - it('should match [type: Type.ROOT]', () => { + it('should match [data?: Optional]', () => { expectTypeOf() - .toHaveProperty('type') - .toEqualTypeOf() + .toHaveProperty('data') + .toEqualTypeOf>() + }) + + it('should match [position?: undefined]', () => { + expectTypeOf().toHaveProperty('position').toBeUndefined() + }) + + it('should match [type: "root"]', () => { + expectTypeOf().toHaveProperty('type').toEqualTypeOf<'root'>() }) }) diff --git a/src/nodes/__tests__/tag-block.spec-d.ts b/src/nodes/__tests__/tag-block.spec-d.ts deleted file mode 100644 index ce3447de..00000000 --- a/src/nodes/__tests__/tag-block.spec-d.ts +++ /dev/null @@ -1,40 +0,0 @@ -/** - * @file Type Tests - BlockTag - * @module docast/nodes/tests/unit-d/BlockTag - */ - -import type { Type } from '#src/enums' -import type { Position } from '#src/interfaces' -import type Parent from '../parent' -import type TestSubject from '../tag-block' -import type InlineTag from '../tag-inline' - -describe('unit-d:nodes/BlockTag', () => { - it('should extend Parent', () => { - expectTypeOf().toMatchTypeOf>() - }) - - it('should match [position: Position]', () => { - expectTypeOf() - .toHaveProperty('position') - .toEqualTypeOf() - }) - - it('should match [tag: string]', () => { - expectTypeOf().toHaveProperty('tag').toBeString() - }) - - it('should match [text: string]', () => { - expectTypeOf().toHaveProperty('text').toBeString() - }) - - it('should match [type: Type.BLOCK_TAG]', () => { - expectTypeOf() - .toHaveProperty('type') - .toEqualTypeOf() - }) - - it('should match [value: string]', () => { - expectTypeOf().toHaveProperty('value').toBeString() - }) -}) diff --git a/src/nodes/__tests__/tag-inline.spec-d.ts b/src/nodes/__tests__/tag-inline.spec-d.ts deleted file mode 100644 index 71c1839f..00000000 --- a/src/nodes/__tests__/tag-inline.spec-d.ts +++ /dev/null @@ -1,39 +0,0 @@ -/** - * @file Type Tests - InlineTag - * @module docast/nodes/tests/unit-d/InlineTag - */ - -import type { Type } from '#src/enums' -import type { Position } from '#src/interfaces' -import type Node from '../node' -import type TestSubject from '../tag-inline' - -describe('unit-d:nodes/InlineTag', () => { - it('should extend Node', () => { - expectTypeOf().toMatchTypeOf() - }) - - it('should match [position: Position]', () => { - expectTypeOf() - .toHaveProperty('position') - .toEqualTypeOf() - }) - - it('should match [tag: string]', () => { - expectTypeOf().toHaveProperty('tag').toBeString() - }) - - it('should match [text: string]', () => { - expectTypeOf().toHaveProperty('text').toBeString() - }) - - it('should match [type: Type.INLINE_TAG]', () => { - expectTypeOf() - .toHaveProperty('type') - .toEqualTypeOf() - }) - - it('should match [value: string]', () => { - expectTypeOf().toHaveProperty('value').toBeString() - }) -}) diff --git a/src/nodes/__tests__/type-expression.spec-d.ts b/src/nodes/__tests__/type-expression.spec-d.ts new file mode 100644 index 00000000..773457e3 --- /dev/null +++ b/src/nodes/__tests__/type-expression.spec-d.ts @@ -0,0 +1,29 @@ +/** + * @file Type Tests - TypeExpression + * @module docast/nodes/tests/unit-d/TypeExpression + */ + +import type { Optional } from '@flex-development/tutils' +import type Literal from '../literal' +import type { + default as TestSubject, + TypeExpressionData +} from '../type-expression' + +describe('unit-d:nodes/TypeExpression', () => { + it('should extend Literal', () => { + expectTypeOf().toMatchTypeOf() + }) + + it('should match [data?: Optional]', () => { + expectTypeOf() + .toHaveProperty('data') + .toEqualTypeOf>() + }) + + it('should match [type: "type-expression"]', () => { + expectTypeOf() + .toHaveProperty('type') + .toEqualTypeOf<'type-expression'>() + }) +}) diff --git a/src/nodes/block-tag.ts b/src/nodes/block-tag.ts new file mode 100644 index 00000000..89f359e5 --- /dev/null +++ b/src/nodes/block-tag.ts @@ -0,0 +1,51 @@ +/** + * @file Nodes - BlockTag + * @module docast/nodes/BlockTag + */ + +import type { BlockTagContent } from '#src/content' +import type { Data } from '#src/interfaces' +import type { Tag } from '#src/mixins' +import type { Optional } from '@flex-development/tutils' +import type Parent from './parent' + +/** + * Info associated with block tag nodes. + * + * @see {@linkcode Data} + * + * @extends {Data} + */ +interface BlockTagData extends Data {} + +/** + * Top-level metadata. + * + * @see {@linkcode Parent} + * @see {@linkcode Tag} + * + * @extends {Parent} + * @extends {Tag} + */ +interface BlockTag extends Parent, Tag { + /** + * List of children. + * + * @see {@linkcode BlockTagContent} + */ + children: BlockTagContent[] + + /** + * Data associated with block tag. + * + * @see {@linkcode BlockTagData} + */ + data?: Optional + + /** + * Node type. + */ + type: 'block-tag' +} + +export type { BlockTagData, BlockTag as default } diff --git a/src/nodes/comment.ts b/src/nodes/comment.ts index e6fdb9ae..8881fe53 100644 --- a/src/nodes/comment.ts +++ b/src/nodes/comment.ts @@ -3,59 +3,57 @@ * @module docast/nodes/Comment */ -import type { Type } from '#src/enums' -import type { Context, Position } from '#src/interfaces' -import type { Nullable } from '@flex-development/tutils' -import type unist from 'unist' -import type ImplicitDescription from './implicit-description' +import type { FlowContent } from '#src/content' +import type { CodeSegment, Data } from '#src/interfaces' +import type { Nilable, Optional } from '@flex-development/tutils' import type Parent from './parent' -import type BlockTag from './tag-block' /** - * **Comment** ([**Parent**][1]) represents a specially formatted [comment][2] - * within a source file that is used to document a particular segment of code. - * These kinds of comments are also known as docblock comments. + * Info associated with comment nodes. * - * **Comment** can be used in [**root**][3] nodes. It can contain [**implicit - * description**][4] and [**block tag**][5] nodes. + * @see {@linkcode Data} * - * A **Comment** has *context* if [positioned][6] exactly one line before the - * code it documents. + * @extends {Data} + */ +interface CommentData extends Data {} + +/** + * A specially formatted [comment][1] within a source file that is used to + * document a particular segment of code. These kinds of comments are also + * known as docblock comments. * - * [1]: {@link ./parent.ts} - * [2]: https://en.wikipedia.org/wiki/Comment_(computer_programming) - * [3]: {@link ./root.ts} - * [4]: {@link ./implicit-description.ts} - * [5]: {@link ./tag-block.ts} - * [6]: https://github.com/syntax-tree/unist#positional-information + * [1]: https://en.wikipedia.org/wiki/Comment_(computer_programming) * - * @template Data - Information from the ecosystem + * @see {@linkcode Parent} * - * @extends {Parent} + * @extends {Parent} */ -interface Comment - extends Parent { +interface Comment extends Parent { /** - * Data representing the segment of code a comment is for. + * List of children. * - * @see [`Context`]({@link ../interfaces/context.ts}) + * @see {@linkcode FlowContent} */ - context: Nullable + children: FlowContent[] /** - * Location of node in source document. + * Code segment documented by comment. + * + * @see {@linkcode CodeSegment} */ - position: Position + code?: Nilable /** - * Node variant. + * Data associated with comment. + * + * @see {@linkcode CommentData} */ - type: Type.COMMENT + data?: Optional /** - * Docblock comment parsed from source document. + * Node type. */ - value: string + type: 'comment' } -export type { Comment as default } +export type { CommentData, Comment as default } diff --git a/src/nodes/description.ts b/src/nodes/description.ts new file mode 100644 index 00000000..f87f20d6 --- /dev/null +++ b/src/nodes/description.ts @@ -0,0 +1,48 @@ +/** + * @file Nodes - Description + * @module docast/nodes/Description + */ + +import type { DescriptionContent } from '#src/content' +import type { Data } from '#src/interfaces' +import type { Optional } from '@flex-development/tutils' +import type Parent from './parent' + +/** + * Info associated with implicit description nodes. + * + * @see {@linkcode Data} + * + * @extends {Data} + */ +interface DescriptionData extends Data {} + +/** + * A piece of text located at the **beginning** of a docblock comment. + * + * @see {@linkcode Parent} + * + * @extends {Parent} + */ +interface Description extends Parent { + /** + * List of children. + * + * @see {@linkcode DescriptionContent} + */ + children: DescriptionContent[] + + /** + * Data associated with implicit description. + * + * @see {@linkcode DescriptionData} + */ + data?: Optional + + /** + * Node type. + */ + type: 'description' +} + +export type { DescriptionData, Description as default } diff --git a/src/nodes/implicit-description.ts b/src/nodes/implicit-description.ts deleted file mode 100644 index 202dc2ad..00000000 --- a/src/nodes/implicit-description.ts +++ /dev/null @@ -1,50 +0,0 @@ -/** - * @file Nodes - ImplicitDescription - * @module docast/nodes/ImplicitDescription - */ - -import type { Type } from '#src/enums' -import type { Position } from '#src/interfaces' -import type unist from 'unist' -import type Parent from './parent' -import type InlineTag from './tag-inline' - -/** - * **ImplicitDescription** ([**Parent**][1]) represents a piece of text located - * at the **beginning** of a docblock comment. - * - * **ImplicitDescription** can be used in [**comment**][2] nodes. It can contain - * [**inline tag**][3] nodes. - * - * [1]: {@link ./parent.ts} - * [2]: {@link ./comment.ts} - * [3]: {@link ./tag-inline.ts} - * - * @template Data - Information from the ecosystem - * - * @extends {Parent} - */ -interface ImplicitDescription - extends Parent { - /** - * Location of node in source document. - */ - position: Position - - /** - * Node variant. - */ - type: Type.IMPLICIT_DESCRIPTION - - /** - * Description text parsed from [**comment**][1]. - * - * **Note**: Values that span multiple lines should not include comment - * delimiters. - * - * [1]: {@link ./comment.ts} - */ - value: string -} - -export type { ImplicitDescription as default } diff --git a/src/nodes/index.ts b/src/nodes/index.ts index 6ebacbb5..01a72595 100644 --- a/src/nodes/index.ts +++ b/src/nodes/index.ts @@ -1,13 +1,18 @@ /** - * @file Nodes - Entry Point + * @file Entry Point - Nodes * @module docast/nodes * @see https://github.com/syntax-tree/unist#nodes */ -export type { default as Comment } from './comment' -export type { default as ImplicitDescription } from './implicit-description' +export type { default as BlockTag, BlockTagData } from './block-tag' +export type { default as Comment, CommentData } from './comment' +export type { default as Description, DescriptionData } from './description' +export type { default as InlineTag, InlineTagData } from './inline-tag' +export type { default as Literal } from './literal' export type { default as Node } from './node' export type { default as Parent } from './parent' -export type { default as Root } from './root' -export type { default as BlockTag } from './tag-block' -export type { default as InlineTag } from './tag-inline' +export type { default as Root, RootData } from './root' +export type { + default as TypeExpression, + TypeExpressionData +} from './type-expression' diff --git a/src/nodes/inline-tag.ts b/src/nodes/inline-tag.ts new file mode 100644 index 00000000..3a19482b --- /dev/null +++ b/src/nodes/inline-tag.ts @@ -0,0 +1,42 @@ +/** + * @file Nodes - InlineTag + * @module docast/nodes/InlineTag + */ + +import type { Data } from '#src/interfaces' +import type { Tag } from '#src/mixins' +import type { Optional } from '@flex-development/tutils' +import type Literal from './literal' + +/** + * Info associated with inline tag nodes. + * + * @see {@linkcode Data} + * + * @extends {Data} + */ +interface InlineTagData extends Data {} + +/** + * Inline metadata. + * + * @see {@linkcode Tag} + * + * @extends {Literal} + * @extends {Tag} + */ +interface InlineTag extends Literal, Tag { + /** + * Data associated with inline tag. + * + * @see {@linkcode InlineTagData} + */ + data?: Optional + + /** + * Node type. + */ + type: 'inline-tag' +} + +export type { InlineTagData, InlineTag as default } diff --git a/src/nodes/literal.ts b/src/nodes/literal.ts new file mode 100644 index 00000000..7893b9ed --- /dev/null +++ b/src/nodes/literal.ts @@ -0,0 +1,22 @@ +/** + * @file Nodes - Literal + * @module docast/nodes/Literal + */ + +import type Node from './node' + +/** + * Abstract docast node containing the smallest possible value. + * + * @see {@linkcode Node} + * + * @extends {Node} + */ +interface Literal extends Node { + /** + * Plain-text value. + */ + value: string +} + +export type { Literal as default } diff --git a/src/nodes/node.ts b/src/nodes/node.ts index 35390638..2582c7e3 100644 --- a/src/nodes/node.ts +++ b/src/nodes/node.ts @@ -3,27 +3,24 @@ * @module docast/nodes/Node */ -import type { Type } from '#src/enums' -import type { Position } from '#src/interfaces' -import type { Objectify } from '@flex-development/tutils' +import type { Data, Position } from '#src/interfaces' +import type { Optional } from '@flex-development/tutils' import type unist from 'unist' /** - * **Node** ([**UnistNode**][1]) is a syntactic unit in docast syntax trees. + * Abstract docast node. * - * [1]: https://github.com/syntax-tree/unist#node - * - * @template Data - Information from the ecosystem + * @see {@linkcode unist.Node} * * @extends {unist.Node} */ -interface Node = unist.Data> extends unist.Node { +interface Node extends unist.Node { /** - * Information from the ecosystem. + * Info from the ecosystem. * - * @see https://github.com/syntax-tree/unist#data + * @see {@linkcode Data} */ - data?: Data + data?: Optional /** * Location of node in source document. @@ -32,16 +29,9 @@ interface Node = unist.Data> extends unist.Node { * * [1]: https://github.com/syntax-tree/unist#generated * - * @see [`Position`]({@link ../interfaces/position.ts}) - */ - position?: Position - - /** - * Node variant. - * - * @see [`Type`]({@link ../enums/type.ts}) + * @see {@linkcode Position} */ - type: Type + position?: Optional } export type { Node as default } diff --git a/src/nodes/parent.ts b/src/nodes/parent.ts index 4164b20f..9024f15f 100644 --- a/src/nodes/parent.ts +++ b/src/nodes/parent.ts @@ -3,39 +3,25 @@ * @module docast/nodes/Parent */ -import type { Child, ParentType } from '#src/types' -import type unist from 'unist' +import type { Content } from '#src/content' +import type Comment from './comment' import type Node from './node' /** - * **Parent** ([**UnistParent**][1]) represents an abstract interface in docast - * containing other nodes (said to be [*children*][2]). + * Abstract docast node that contains other docast or mdast nodes. * - * [1]: https://github.com/syntax-tree/unist#parent - * [2]: https://github.com/syntax-tree/unist#child + * @see {@linkcode Node} * - * @template ChildNode - Child node type - * @template Data - Information from the ecosystem - * - * @extends {Node} + * @extends {Node} */ -interface Parent< - ChildNode extends Child = Child, - Data extends unist.Data = unist.Data -> extends Node { - /** - * List representing [*children*][1]. - * - * [1]: https://github.com/syntax-tree/unist#child - */ - children: ChildNode[] - +interface Parent extends Node { /** - * Node variant. + * List of children. * - * @see [`ParentType`]({@link ../types/type-parent.ts}) + * @see {@linkcode Comment} + * @see {@linkcode Content} */ - type: ParentType + children: (Comment | Content)[] } export type { Parent as default } diff --git a/src/nodes/root.ts b/src/nodes/root.ts index 8792d76f..6c8896b6 100644 --- a/src/nodes/root.ts +++ b/src/nodes/root.ts @@ -3,31 +3,53 @@ * @module docast/nodes/Root */ -import type { Type } from '#src/enums' -import type unist from 'unist' +import type { Data } from '#src/interfaces' +import type { Optional } from '@flex-development/tutils' import type Comment from './comment' import type Parent from './parent' /** - * **Root** ([**Parent**][1]) represents a document. + * Info associated with documents. * - * **Root** can be used as the [*root*][2] of a [*tree*][3], never as a - * [*child*][4]. It can contain [**comment**][5] nodes. + * @see {@linkcode Data} * - * [1]: {@link ./parent.ts} - * [2]: https://github.com/syntax-tree/unist#root - * [3]: https://github.com/syntax-tree/unist#tree - * [4]: https://github.com/syntax-tree/unist#child - * [5]: {@link ./comment.ts} + * @extends {Data} + */ +interface RootData extends Data {} + +/** + * A document fragment or whole document. + * + * Should be used as the root of a tree; must not be used as a child. * - * @template Data - Information from the ecosystem + * @see {@linkcode Parent} * - * @extends {Parent} + * @extends {Parent} */ -interface Root - extends Parent { - position?: never - type: Type.ROOT +interface Root extends Parent { + /** + * List of children. + * + * @see {@linkcode Comment} + */ + children: Comment[] + + /** + * Data associated with docast root. + * + * @see {@linkcode RootData} + */ + data?: Optional + + /** + * Position of root in source document. + */ + position?: undefined + + /** + * Node type. + */ + type: 'root' } -export type { Root as default } +export type { RootData, Root as default } diff --git a/src/nodes/tag-block.ts b/src/nodes/tag-block.ts deleted file mode 100644 index 9cf0d534..00000000 --- a/src/nodes/tag-block.ts +++ /dev/null @@ -1,59 +0,0 @@ -/** - * @file Nodes - BlockTag - * @module docast/nodes/BlockTag - */ - -import type { Type } from '#src/enums' -import type { Position } from '#src/interfaces' -import type unist from 'unist' -import type Parent from './parent' -import type InlineTag from './tag-inline' - -/** - * **BlockTag** ([**Parent**][1]) represents metadata in a docblock comment. - * - * **BlockTag** can be used in [**comment**][2] nodes. It can contain [**inline - * tag**][3] nodes. - * - * [1]: {@link ./parent.ts} - * [2]: {@link ./comment.ts} - * [3]: {@link ./tag-inline.ts} - * - * @template Data - Information from the ecosystem - * - * @extends {Parent} - */ -interface BlockTag - extends Parent { - /** - * Location of node in source document. - */ - position: Position - - /** - * Tag name. - */ - tag: string - - /** - * Text after {@linkcode tag}. - */ - text: string - - /** - * Node variant. - */ - type: Type.BLOCK_TAG - - /** - * Tag as parsed from [**comment**][1]. - * - * **Note**: Values that span multiple lines should not include comment - * delimiters. - * - * [1]: {@link ./comment.ts} - */ - value: string -} - -export type { BlockTag as default } diff --git a/src/nodes/tag-inline.ts b/src/nodes/tag-inline.ts deleted file mode 100644 index f66cc9f0..00000000 --- a/src/nodes/tag-inline.ts +++ /dev/null @@ -1,57 +0,0 @@ -/** - * @file Nodes - InlineTag - * @module docast/nodes/InlineTag - */ - -import type { Type } from '#src/enums' -import type { Position } from '#src/interfaces' -import type unist from 'unist' -import type Node from './node' - -/** - * **InlineTag** ([**Node**][1]) represents inline metadata in a docblock - * comment. - * - * **InlineTag** can be used in [**implicit description**][2] and [**block - * tag**][3] nodes. It cannot contain any children — it is a [*leaf*][4]. - * - * [1]: {@link ./node.ts} - * [2]: {@link ./implicit-description.ts} - * [3]: {@link ./tag-block.ts} - * [4]: https://github.com/syntax-tree/unist#leaf - * - * @template Data - Information from the ecosystem - * - * @extends {Node} - */ -interface InlineTag extends Node { - /** - * Location of node in source document. - */ - position: Position - - /** - * Tag name. - */ - tag: string - - /** - * Text after {@linkcode tag}. - */ - text: string - - /** - * Node variant. - */ - type: Type.INLINE_TAG - - /** - * Tag as parsed from [**implicit description**][1] or [**block tag**][2]. - * - * [1]: {@link ./implicit-description.ts} - * [2]: {@link ./block-tag.ts} - */ - value: string -} - -export type { InlineTag as default } diff --git a/src/nodes/type-expression.ts b/src/nodes/type-expression.ts new file mode 100644 index 00000000..b41600c6 --- /dev/null +++ b/src/nodes/type-expression.ts @@ -0,0 +1,40 @@ +/** + * @file Nodes - TypeExpression + * @module docast/nodes/TypeExpression + */ + +import type { Data } from '#src/interfaces' +import type { Optional } from '@flex-development/tutils' +import type Literal from './literal' + +/** + * Info associated with type expression nodes. + * + * @see {@linkcode Data} + * + * @extends {Data} + */ +interface TypeExpressionData extends Data {} + +/** + * A type definition or constraint. + * + * @see {@linkcode Literal} + * + * @extends {Literal} + */ +interface TypeExpression extends Literal { + /** + * Data associated with type expression. + * + * @see {@linkcode TypeExpressionData} + */ + data?: Optional + + /** + * Node type. + */ + type: 'type-expression' +} + +export type { TypeExpressionData, TypeExpression as default } diff --git a/src/types/__tests__/child.spec-d.ts b/src/types/__tests__/child.spec-d.ts deleted file mode 100644 index e37335c0..00000000 --- a/src/types/__tests__/child.spec-d.ts +++ /dev/null @@ -1,30 +0,0 @@ -/** - * @file Type Tests - Child - * @module docast/types/tests/unit-d/Child - */ - -import type { - BlockTag, - Comment, - ImplicitDescription, - InlineTag -} from '#src/nodes' -import type TestSubject from '../child' - -describe('unit-d:types/Child', () => { - it('should extract BlockTag', () => { - expectTypeOf().extract().not.toBeNever() - }) - - it('should extract Comment', () => { - expectTypeOf().extract().not.toBeNever() - }) - - it('should extract ImplicitDescription', () => { - expectTypeOf().extract().not.toBeNever() - }) - - it('should extract InlineTag', () => { - expectTypeOf().extract().not.toBeNever() - }) -}) diff --git a/src/types/__tests__/type-parent.spec-d.ts b/src/types/__tests__/type-parent.spec-d.ts deleted file mode 100644 index 04ab8ed2..00000000 --- a/src/types/__tests__/type-parent.spec-d.ts +++ /dev/null @@ -1,27 +0,0 @@ -/** - * @file Type Tests - ParentType - * @module docast/types/tests/unit-d/ParentType - */ - -import type { Type } from '#src/enums' -import type TestSubject from '../type-parent' - -describe('unit-d:types/ParentType', () => { - it('should extract Type.BLOCK_TAG', () => { - expectTypeOf().extract().toBeString() - }) - - it('should extract Type.COMMENT', () => { - expectTypeOf().extract().toBeString() - }) - - it('should extract Type.IMPLICIT_DESCRIPTION', () => { - expectTypeOf() - .extract() - .toBeString() - }) - - it('should extract Type.ROOT', () => { - expectTypeOf().extract().toBeString() - }) -}) diff --git a/src/types/child.ts b/src/types/child.ts deleted file mode 100644 index 2d91f4ca..00000000 --- a/src/types/child.ts +++ /dev/null @@ -1,20 +0,0 @@ -/** - * @file Type Definitions - Child - * @module docast/types/Child - */ - -import type { - BlockTag, - Comment, - ImplicitDescription, - InlineTag -} from '#src/nodes' - -/** - * [*Child*][1] node types. - * - * [1]: https://github.com/syntax-tree/unist#child - */ -type Child = BlockTag | Comment | ImplicitDescription | InlineTag - -export type { Child as default } diff --git a/src/types/index.ts b/src/types/index.ts deleted file mode 100644 index 517e095f..00000000 --- a/src/types/index.ts +++ /dev/null @@ -1,7 +0,0 @@ -/** - * @file Entry Point - Type Definitions - * @module docast/types - */ - -export type { default as Child } from './child' -export type { default as ParentType } from './type-parent' diff --git a/src/types/type-parent.ts b/src/types/type-parent.ts deleted file mode 100644 index 3ee74b89..00000000 --- a/src/types/type-parent.ts +++ /dev/null @@ -1,19 +0,0 @@ -/** - * @file Type Definitions - ParentType - * @module docast/types/ParentType - */ - -import type { Type } from '#src/enums' - -/** - * **Parent** ([**UnistParent**][1]) node types. - * - * [1]: https://github.com/syntax-tree/unist#parent - */ -type ParentType = - | Type.BLOCK_TAG - | Type.COMMENT - | Type.IMPLICIT_DESCRIPTION - | Type.ROOT - -export type { ParentType as default } diff --git a/yarn.lock b/yarn.lock index 74194377..f292c3ea 100644 --- a/yarn.lock +++ b/yarn.lock @@ -1374,7 +1374,8 @@ __metadata: "@flex-development/tutils": "npm:6.0.0-alpha.25" "@types/eslint": "npm:8.56.2" "@types/is-ci": "npm:3.0.4" - "@types/node": "npm:20.11.12" + "@types/mdast": "npm:4.0.3" + "@types/node": "npm:20.11.14" "@types/node-notifier": "npm:8.0.5" "@types/unist": "npm:3.0.2" "@typescript-eslint/eslint-plugin": "npm:6.20.0" @@ -1382,6 +1383,7 @@ __metadata: "@vates/toggle-scripts": "npm:1.0.0" cross-env: "npm:7.0.3" cspell: "npm:8.3.2" + debug: "npm:4.3.4" dprint: "npm:0.45.0" editorconfig: "npm:2.0.0" esbuild: "npm:0.20.0" @@ -1420,7 +1422,8 @@ __metadata: vitest: "npm:1.2.2" yaml-eslint-parser: "npm:1.2.2" peerDependencies: - "@types/unist": ">=2.0.6" + "@types/mdast": ">=4.0.3" + "@types/unist": ">=3.0.2" languageName: unknown linkType: soft @@ -2263,21 +2266,21 @@ __metadata: languageName: node linkType: hard -"@types/mdast@npm:^3.0.0": - version: 3.0.10 - resolution: "@types/mdast@npm:3.0.10" +"@types/mdast@npm:4.0.3, @types/mdast@npm:^4.0.0": + version: 4.0.3 + resolution: "@types/mdast@npm:4.0.3" dependencies: "@types/unist": "npm:*" - checksum: 10/6b7f613feba54a394ca71694ed3b6719f7ce504d42454ec2d09203a9da3e7086189b4db080e0ea070bd6bae35f6f74f6596f23e21646566e3054e6539cb8a2fe + checksum: 10/6d2d8f00ffaff6663dd67ea9ab999a5e52066c001432a9b99947fa9e76bccba819dfca40e419588a637a70d42cd405071f5b76efd4ddeb1dc721353b7cc73623 languageName: node linkType: hard -"@types/mdast@npm:^4.0.0": - version: 4.0.3 - resolution: "@types/mdast@npm:4.0.3" +"@types/mdast@npm:^3.0.0": + version: 3.0.10 + resolution: "@types/mdast@npm:3.0.10" dependencies: "@types/unist": "npm:*" - checksum: 10/6d2d8f00ffaff6663dd67ea9ab999a5e52066c001432a9b99947fa9e76bccba819dfca40e419588a637a70d42cd405071f5b76efd4ddeb1dc721353b7cc73623 + checksum: 10/6b7f613feba54a394ca71694ed3b6719f7ce504d42454ec2d09203a9da3e7086189b4db080e0ea070bd6bae35f6f74f6596f23e21646566e3054e6539cb8a2fe languageName: node linkType: hard @@ -2304,12 +2307,12 @@ __metadata: languageName: node linkType: hard -"@types/node@npm:*, @types/node@npm:20.11.12, @types/node@npm:^20.0.0": - version: 20.11.12 - resolution: "@types/node@npm:20.11.12" +"@types/node@npm:*, @types/node@npm:20.11.14, @types/node@npm:^20.0.0": + version: 20.11.14 + resolution: "@types/node@npm:20.11.14" dependencies: undici-types: "npm:~5.26.4" - checksum: 10/26efca2c1a2d97d1db0e8c03964361bf3209259715e31bd856eaf783a9ccb1536405870e19613f2c142bc03ebcfec8a556ae37bae759daac5d5d695aa1197d2e + checksum: 10/129104b80a33b92ffcd139593b51d39b85e9dce0e7065a39eca23cd3c629da9f06a747509cdcbf0e6bd89349d944d1a4b112b598d122d0d33f10765d51a39334 languageName: node linkType: hard