{"id":13339465,"url":"https://github.com/flex-development/docast","last_synced_at":"2026-02-14T05:11:51.326Z","repository":{"id":62974208,"uuid":"563674194","full_name":"flex-development/docast","owner":"flex-development","description":"Docblock Abstract Syntax Tree format","archived":false,"fork":false,"pushed_at":"2026-01-23T08:20:02.000Z","size":6367,"stargazers_count":3,"open_issues_count":6,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-01-24T01:17:13.126Z","etag":null,"topics":["ast","doc","docblock","markdown","mdast","syntax-tree","unist","unist-spec"],"latest_commit_sha":null,"homepage":"https://github.com/flex-development/docast","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/flex-development.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/funding.yml","license":"LICENSE.md","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":["flex-development"]}},"created_at":"2022-11-09T04:51:39.000Z","updated_at":"2026-01-23T08:20:05.000Z","dependencies_parsed_at":"2023-09-21T21:17:02.397Z","dependency_job_id":"e49b0692-7f30-4d8e-b2d2-894fb053d05c","html_url":"https://github.com/flex-development/docast","commit_stats":{"total_commits":87,"total_committers":2,"mean_commits":43.5,"dds":0.367816091954023,"last_synced_commit":"3bd29e66fce22f8fa86ca39f96569344dbdb54d5"},"previous_names":[],"tags_count":18,"template":false,"template_full_name":null,"purl":"pkg:github/flex-development/docast","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flex-development%2Fdocast","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flex-development%2Fdocast/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flex-development%2Fdocast/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flex-development%2Fdocast/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/flex-development","download_url":"https://codeload.github.com/flex-development/docast/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flex-development%2Fdocast/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29433297,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-14T02:20:56.896Z","status":"ssl_error","status_checked_at":"2026-02-14T02:11:29.478Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ast","doc","docblock","markdown","mdast","syntax-tree","unist","unist-spec"],"created_at":"2024-07-29T19:20:03.630Z","updated_at":"2026-02-14T05:11:51.320Z","avatar_url":"https://github.com/flex-development.png","language":"TypeScript","funding_links":["https://github.com/sponsors/flex-development"],"categories":[],"sub_categories":[],"readme":"# docast\n\n[![github release](https://img.shields.io/github/v/release/flex-development/docast.svg?include_prereleases\\\u0026sort=semver)](https://github.com/flex-development/docast/releases/latest)\n[![npm](https://img.shields.io/npm/v/@flex-development/docast.svg)](https://npmjs.com/package/@flex-development/docast)\n[![npm downloads](https://img.shields.io/npm/dm/@flex-development/docast.svg)](https://www.npmcharts.com/compare/@flex-development/docast?interval=30)\n[![install size](https://packagephobia.now.sh/badge?p=@flex-development/docast)](https://packagephobia.now.sh/result?p=@flex-development/docast)\n[![module type: esm](https://img.shields.io/badge/module%20type-esm-brightgreen)](https://github.com/voxpelli/badges-cjs-esm)\n[![license](https://img.shields.io/github/license/flex-development/docast.svg)](LICENSE.md)\n[![conventional commits](https://img.shields.io/badge/-conventional%20commits-fe5196?logo=conventional-commits\\\u0026logoColor=ffffff)](https://conventionalcommits.org)\n[![typescript](https://img.shields.io/badge/-typescript-3178c6?logo=typescript\\\u0026logoColor=ffffff)](https://typescriptlang.org)\n[![vitest](https://img.shields.io/badge/-vitest-6e9f18?style=flat\\\u0026logo=vitest\\\u0026logoColor=ffffff)](https://vitest.dev)\n[![yarn](https://img.shields.io/badge/-yarn-2c8ebb?style=flat\\\u0026logo=yarn\\\u0026logoColor=ffffff)](https://yarnpkg.com)\n\n**Doc**block **A**bstract **S**yntax **T**ree.\n\n---\n\n**docast** is a specification for representing [docblock comments](#docblock-comment)\nas [abstract syntax trees][unist-syntax-tree].\n\nIt implements the [**unist**][unist] spec.\n\n## Contents\n\n- [Introduction](#introduction)\n  - [Where this specification fits](#where-this-specification-fits)\n- [Types](#types)\n- [Nodes (abstract)](#nodes-abstract)\n  - [`Node`](#node)\n  - [`Literal`](#literal)\n  - [`Parent`](#parent)\n- [Nodes](#nodes)\n  - [`BlockTag`](#blocktag)\n  - [`Comment`](#comment)\n    - [`CodeSegment`](#codesegment)\n  - [`Description`](#description)\n  - [`InlineTag`](#inlinetag)\n  - [`Root`](#root)\n  - [`TypeMetadata`](#typemetadata)\n- [Mixins](#mixins)\n  - [`Tag`](#tag)\n    - [`TagName`](#tagname)\n- [Content model](#content-model)\n  - [`BlockTagContent`](#blocktagcontent)\n  - [`DescriptionContent`](#descriptioncontent)\n  - [`FlowContent`](#flowcontent)\n  - [`PhrasingContent`](#phrasingcontent)\n  - [`TypeExpression`](#typeexpression)\n- [Glossary](#glossary)\n- [List of utilities](#list-of-utilities)\n- [Contribute](#contribute)\n\n## Introduction\n\nThis document defines a format for representing [docblock comments](#docblock-comment)\nas [abstract syntax trees][unist-syntax-tree].\\\nDevelopment of docast started in October 2022. This specification is written in a [TypeScript][]-like grammar.\n\n### Where this specification fits\n\ndocast extends [unist][], a format for syntax trees, to benefit from its [ecosystem of utilities][unist-utilities].\nIt also integrates with [mdast][], a specification for representing markdown.\n\ndocast relates to [JavaScript][] and [TypeScript][] in that both languages support docblock comments.\ndocast is **language-agnostic**, however, and can be used with any programming language that supports docblock comments.\n\ndocast relates to [JSDoc][], [TSDoc][], and [typedoc][] in that these tools parse docblock comments.\nThese tools also have a limited set of tags that developers are allowed to use.\nIf developers already have a set of tags they're using, they must spend additional time re-configuring those tags for\ntheir chosen tool.\n**docast does not enforce any tag semantics** — the user does. Tag specifications can be left to an [ESLint][] rule, or\na setting akin to [`jsdoc/check-tag-names`][check-tag-names] or [`jsdoc.structuredTags`][structuredtags].\n\n## Types\n\nTypeScript users can integrate `docast` type definitions into their project by installing the appropriate packages:\n\n```sh\nyarn add @flex-development/docast\n```\n\n## Nodes (abstract)\n\n### `Node`\n\n```ts\ninterface Node extends unist.Node {}\n```\n\n**Node** ([**unist.Node**][unist-node]) is a syntactic unit in docast syntax trees.\n\n### `Literal`\n\n```ts\ninterface Literal extends Node {\n  value: bigint | boolean | number | string | null | undefined\n}\n```\n\n**Literal** represents an abstract interface in docast containing the smallest possible value.\n\n### `Parent`\n\n```ts\ninterface Parent extends unist.Parent {\n  children: Child[]\n}\n```\n\n**Parent** ([**unist.Parent**][unist-parent]) represents an abstract interface in docast\ncontaining other nodes (said to be [*children*][unist-child]).\n\nIts content is limited to [docast content](#content-model) and [mdast content][mdast-content].\n\n## Nodes\n\n### `BlockTag`\n\n```ts\ninterface BlockTag extends Parent, Tag {\n  children:\n    | Exclude\u003cBlockTagContent, TypeMetadata\u003e[]\n    | [TypeMetadata, ...Exclude\u003cBlockTagContent, TypeMetadata\u003e[]]\n  data?: BlockTagData | undefined\n  type: 'blockTag'\n}\n```\n\n**BlockTag** ([**Parent**](#parent)) represents top-level metadata.\n\nBlock tags should be the only element on their line,\nexcept in cases where special meaning is assigned to succeeding text.\nAll text following a block [tag name](#tagname), up until the start of the next block tag name,\nor comment closer (`*/`), is considered to be the block tag's [*tag content*](#tag-content).\n\n**BlockTag** can be used in [**comment**](#comment) nodes.\nIts content model is [**block tag**](#blocktagcontent) content.\n\n### `Comment`\n\n```ts\ninterface Comment extends Parent {\n  children:\n    | Exclude\u003cFlowContent, Description\u003e[]\n    | [summary: Description, ...Exclude\u003cFlowContent, Description\u003e[]]\n  code?: CodeSegment | null | undefined\n  data?: CommentData | undefined\n  type: 'comment'\n}\n```\n\n**Comment** ([**Parent**](#parent)) represents a [*docblock comment*](#docblock-comment)\nin a source [*file*][unist-file].\n\nThe `code` field represents the segment of code documented by a comment.\nThe value of the `code` field may be `null`, `undefined`, or implement the [`CodeSegment`](#codesegment) interface.\nThe `code` field must not be present if a comment is used only to provide additional information.\n\n**Comment** can be used in [**root**](#root) nodes.\nIts content model is [**flow**](#flowcontent) content.\n\n#### `CodeSegment`\n\n```ts\ninterface CodeSegment {\n  position: unist.Position\n  type: string\n}\n```\n\n**CodeSegment** represents the code segment in a [*file*][unist-file] that is documented by a [**comment**](#comment).\n\nThe value of the `type` field is the node type of the code segment.\n\n### `Description`\n\n```ts\ninterface Description extends Parent {\n  children: DescriptionContent[]\n  data?: DescriptionData | undefined\n  type: 'description'\n}\n```\n\n**Description** ([**Parent**](#parent)) represents the text of a [**comment**](#comment).\nIt is located at the start of a comment, before any [**block tags**](#blocktag),\nand may contain [Markdown][mdast] content.\n\n**Description** can be used in [**comment**](#comment) nodes.\nIts content model is [**description**](#descriptioncontent).\n\n### `InlineTag`\n\n```ts\ninterface InlineTag extends Literal, Tag {\n  data?: InlineTagData | undefined\n  type: 'inlineTag'\n  value: string\n}\n```\n\n**InlineTag** ([**Literal**](#literal)) represents inline metadata.\n\nInline tags are denoted by wrapping a [tag name](#tagname)\nand any [*tag content*](#tag-content) in angle brackets (`{` and `}`).\n\n**InlineTag** can be used in [**block tag**](#blocktag) and [**description**](#description) nodes.\nIt cannot contain any children — it is a [*leaf*][unist-leaf].\n\n### `Root`\n\n```ts\ninterface Root extends Parent {\n  children: Comment[]\n  data?: RootData | undefined\n  type: 'root'\n}\n```\n\n**Root** ([**Parent**](#parent)) represents a document.\n\n**Root** can be used as the [*root*][unist-root] of a [*tree*][unist-tree], never as a [*child*][unist-child].\nIt can contain [**comment**](#comment) nodes.\n\n### `TypeMetadata`\n\n```ts\ninterface TypeMetadata extends Parent {\n  children: TypeExpression[]\n  data?: TypeMetadataData | undefined\n  raw: string\n  type: 'typeMetadata'\n}\n```\n\n**TypeMetadata** ([**Parent**](#parent)) represents an inlined type expression (e.g. `{number}`).\n\n**TypeMetadata** can be used in [**block tag**](#blocktag) nodes.\nIts content model is [**type expresssion**](#typeexpression).\n\nA `raw` field must be present. Its value is the raw type expression (e.g. `number`).\n\n## Mixins\n\n### `Tag`\n\n```ts\ninterface Tag {\n  name: TagName\n}\n```\n\n**Tag** represents metadata associated with a [**comment**](#comment).\n\nThe `name` field represents the tag name.\nTag names start with an at-sign (`@`) and may contain any ASCII letter after the at-sign.\n\n#### `TagName`\n\n```ts\ntype TagName\u003cT extends string = string\u003e = `@${T}`\n```\n\n## Content model\n\n```ts\ntype Content = BlockTagContent | DescriptionContent | FlowContent | PhrasingContent\n```\n\nNodes are grouped by content type, if applicable.\nEach node in docast, with the exception of [`Comment`](#comment), falls into one or more categories of `Content`.\n\n### `BlockTagContent`\n\n```ts\ntype BlockTagContent = PhrasingContent | TypeMetadata\n```\n\n**Block** content represents [**block tag**](#blocktag) text, and its markup.\n\n### `DescriptionContent`\n\n```ts\ntype DescriptionContent =\n  | mdast.Blockquote\n  | mdast.Definition\n  | mdast.FootnoteDefinition\n  | mdast.List\n  | mdast.ListItem\n  | mdast.Paragraph\n  | mdast.Table\n  | mdast.ThematicBreak\n  | PhrasingContent\n```\n\n**Description** content represents [**description**](#description) text, and its markup.\n\n### `FlowContent`\n\n```ts\ntype FlowContent = BlockTag | Description\n```\n\n**Flow** content represents the sections of [**comment**](#comment).\n\n### `PhrasingContent`\n\n```ts\ntype PhrasingContent = InlineTag | mdast.Code | mdast.PhrasingContent\n```\n\n**Phrasing** content represents [**comment**](#comment) text, and its markup.\n\n### `TypeExpression`\n\n```ts\ntype TypeExpression = TypeExpressionMap[keyof TypeExpressionMap]\n```\n\n**TypeExpression** content is a type expression.\n\nWhen developing type expression parsers compatible with docast,\nthe `TypeExpressionMap` map should be augmented (and exported! \\:wink:) to register custom nodes:\n\n```ts\ndeclare module '@flex-development/docast' {\n  interface TypeExpressionMap {\n    arrayType: ArrayType\n    assertionPredicate: AssertionPredicate\n    bigint: BigIntLiteral\n    boolean: BooleanLiteral\n    conditionalType: ConditionalType\n    constructorType: ConstructorType\n    functionType: FunctionType\n    genericType: GenericType\n    identifier: Identifier\n    inferType: InferType\n    intersectionType: IntersectionType\n    nonNullableType: NonNullableType\n    null: NullLiteral\n    nullableType: NullableType\n    number: NumberLiteral\n    objectLiteralType: ObjectLiteralType\n    optionalType: OptionalType\n    parenthesizedType: ParenthesizedType\n    propertyAccessType: PropertyAccessType\n    string: StringLiteral\n    super: Super\n    templateLiteral: TemplateLiteral\n    this: This\n    tupleType: TupleType\n    typeOperation: TypeOperation\n    typePredicate: TypePredicate\n    typeSymbol: TypeSymbol\n    undefined: UndefinedLiteral\n    unionType: UnionType\n    variadicType: VariadicType\n  }\n}\n```\n\n## Glossary\n\nSee the [unist glossary][unist-glossary] for more terms.\n\n### Docblock comment\n\nA specially formatted [comment][wiki-comment] in a source [*file*][unist-file] used to document a segment of code or\nprovide additional information.\n\n### Tag content\n\nAny text following a [block tag](#blocktag) name (e.g. `@example`, `@param`), up until the start of the next block tag\nor comment closer (`*/`), or any text following an [inline tag](#inlinetag) name, up until the closing punctuator (`}`).\n\n## List of utilities\n\nSee the [unist list of utilities][unist-utilities] for more utilities.\n\n- [`docast-util-from-docs`][docast-util-from-docs]\n  — parse docblocks\n\n## Contribute\n\nSee [`CONTRIBUTING.md`](CONTRIBUTING.md).\n\nIdeas for new utilities and tools can be posted in [docast/ideas][docast-ideas].\n\nThis project has a [code of conduct](CODE_OF_CONDUCT.md).\nBy interacting with this repository, organization, or community you agree to abide by its terms.\n\n[check-tag-names]: https://github.com/gajus/eslint-plugin-jsdoc-check-tag-names\n\n[docast-ideas]: https://github.com/flex-development/docast/discussions/new?category=idea\n\n[docast-util-from-docs]: https://github.com/flex-development/docast-util-from-docs\n\n[eslint]: https://eslint.org\n\n[javascript]: https://www.ecma-international.org/ecma-262/9.0/index.html\n\n[jsdoc]: https://jsdoc.app\n\n[mdast-content]: https://github.com/syntax-tree/mdast#content-model\n\n[mdast]: https://github.com/syntax-tree/mdast\n\n[structuredtags]: https://github.com/gajus/eslint-plugin-jsdoc-structuredtags\n\n[tsdoc]: https://tsdoc.org\n\n[typedoc]: https://github.com/TypeStrong/typedoc\n\n[typescript]: https://typescriptlang.org\n\n[unist-child]: https://github.com/syntax-tree/unist#child\n\n[unist-file]: https://github.com/syntax-tree/unist#file\n\n[unist-glossary]: https://github.com/syntax-tree/unist#glossary\n\n[unist-leaf]: https://github.com/syntax-tree/unist#leaf\n\n[unist-node]: https://github.com/syntax-tree/unist#node\n\n[unist-parent]: https://github.com/syntax-tree/unist#parent\n\n[unist-root]: https://github.com/syntax-tree/unist#root\n\n[unist-syntax-tree]: https://github.com/syntax-tree/unist#syntax-tree\n\n[unist-tree]: https://github.com/syntax-tree/unist#tree\n\n[unist-utilities]: https://github.com/syntax-tree/unist#list-of-utilities\n\n[unist]: https://github.com/syntax-tree/unist\n\n[wiki-comment]: https://en.wikipedia.org/wiki/Comment_\\(computer_programming\\)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflex-development%2Fdocast","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fflex-development%2Fdocast","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflex-development%2Fdocast/lists"}