remark-retext - npm Package Compare versions

Comparing version 5.0.0 to 5.0.1

index.d.ts

 export default remarkRetext
-export type Node = import('unist').Node
-export type MdastRoot = import('mdast').Root
-export type ParserInstance = import('mdast-util-to-nlcst').ParserInstance
-export type ParserConstructor = import('mdast-util-to-nlcst').ParserConstructor
-export type Options = import('mdast-util-to-nlcst').Options
-export type Processor = import('unified').Processor<any, any, any, any>
-export type Parser = import('unified').Parser<any>
-/**
- * Plugin to bridge or mutate to retext.
- *
- * If a destination processor is given, runs the destination with the new nlcst
- * tree (bridge-mode).
- * If a parser is given, returns the nlcst tree: further plugins run on that
- * tree (mutate-mode).
- *
- * @param destination
- *   Either a processor (`unified().use(retextEnglish)…`) or a parser.
- * @param options
- *   Configuration passed to `mdast-util-to-nlcst`.
- */
-declare const remarkRetext: import('unified').Plugin<
-  [Processor, Options?] | [Processor],
-  MdastRoot,
-  MdastRoot
-> &
-  import('unified').Plugin<[Parser, Options?] | [Parser], MdastRoot, Node>
+export type Options = import('./lib/index.js').Options
+import remarkRetext from './lib/index.js'

index.js

 /**
- * @typedef {import('unist').Node} Node
- * @typedef {import('mdast').Root} MdastRoot
- * @typedef {import('mdast-util-to-nlcst').ParserInstance} ParserInstance
- * @typedef {import('mdast-util-to-nlcst').ParserConstructor} ParserConstructor
- * @typedef {import('mdast-util-to-nlcst').Options} Options
- * @typedef {import('unified').Processor<any, any, any, any>} Processor
- * @typedef {import('unified').Parser<any>} Parser
+ * @typedef {import('./lib/index.js').Options} Options
  */
 
-import {toNlcst} from 'mdast-util-to-nlcst'
+import remarkRetext from './lib/index.js'
 
-/**
- * Plugin to bridge or mutate to retext.
- *
- * If a destination processor is given, runs the destination with the new nlcst
- * tree (bridge-mode).
- * If a parser is given, returns the nlcst tree: further plugins run on that
- * tree (mutate-mode).
- *
- * @param destination
- *   Either a processor (`unified().use(retextEnglish)…`) or a parser.
- * @param options
- *   Configuration passed to `mdast-util-to-nlcst`.
- */
-const remarkRetext =
-  /**
-   * @type {(import('unified').Plugin<[Processor, Options?]|[Processor], MdastRoot, MdastRoot> & import('unified').Plugin<[Parser, Options?]|[Parser], MdastRoot, Node>)}
-   */
-  (
-    /**
-     * @param {Processor|Parser} destination
-     * @param {Options|undefined} options
-     */
-    function (destination, options) {
-      return destination && 'run' in destination
-        ? bridge(destination, options)
-        : mutate(destination, options)
-    }
-  )
-
 export default remarkRetext
-
-/**
- * Mutate-mode.
- * Further transformers run on the nlcst tree.
- *
- * @type {import('unified').Plugin<[Parser, Options?], MdastRoot, Node>}
- */
-function mutate(parser, options) {
-  // Assume the parser is a retext parser.
-  const Parser = /** @type {ParserInstance|ParserConstructor} */ (parser)
-  return (node, file) => toNlcst(node, file, Parser, options)
-}
-
-/**
- * Bridge-mode.
- * Runs the destination with the new nlcst tree.
- *
- * @type {import('unified').Plugin<[Processor, Options?], MdastRoot>}
- */
-function bridge(destination, options) {
-  return (node, file, next) => {
-    // Assume the parser is a retext parser.
-    const Parser = /** @type {ParserConstructor|ParserInstance} */ (
-      destination.freeze().Parser
-    )
-
-    destination.run(toNlcst(node, file, Parser, options), file, (error) => {
-      next(error)
-    })
-  }
-}

package.json

 {
   "name": "remark-retext",
-  "version": "5.0.0",
-  "description": "remark plugin to transform to retext",
+  "version": "5.0.1",
+  "description": "remark plugin to support retext",
   "license": "MIT",
@@ -33,2 +33,3 @@ "keywords": [
   "files": [
+    "lib/",
     "index.d.ts",
@@ -49,3 +50,3 @@ "index.js"
     "remark-parse": "^10.0.0",
-    "remark-preset-wooorm": "^8.0.0",
+    "remark-preset-wooorm": "^9.0.0",
     "remark-stringify": "^10.0.0",
@@ -58,6 +59,6 @@ "retext-english": "^4.0.0",
     "typescript": "^4.0.0",
-    "xo": "^0.42.0"
+    "xo": "^0.45.0"
   },
   "scripts": {
-    "build": "rimraf \"*.d.ts\" && tsc && type-coverage",
+    "build": "rimraf \"lib/**/*.d.ts\" \"*.d.ts\" && tsc && type-coverage",
     "format": "remark . -qfo && prettier . -w --loglevel warn && xo --fix",
@@ -91,6 +92,6 @@ "test-api": "node --conditions development test.js",
     "ignoreFiles": [
-      "index.d.ts",
-      "index.js"
+      "lib/index.d.ts",
+      "lib/index.js"
     ]
   }
 }

readme.md

@@ -11,17 +11,50 @@ # remark-retext
 
-[**remark**][remark] plugin to bridge or mutate to [**retext**][retext].
+**[remark][]** plugin to support **[retext][]**.
 
-## Note!
+## Contents
 
-This plugin is ready for the new parser in remark
-([`remarkjs/remark#536`](https://github.com/remarkjs/remark/pull/536)).
-No change is needed: it works exactly the same now as it did previously!
+*   [What is this?](#what-is-this)
+*   [When should I use this?](#when-should-i-use-this)
+*   [Install](#install)
+*   [Use](#use)
+*   [API](#api)
+    *   [`unified().use(remarkRetext, destination[, options])`](#unifieduseremarkretext-destination-options)
+*   [Examples](#examples)
+*   [Example: mutate mode](#example-mutate-mode)
+*   [Types](#types)
+*   [Compatibility](#compatibility)
+*   [Security](#security)
+*   [Related](#related)
+*   [Contribute](#contribute)
+*   [License](#license)
 
+## What is this?
+
+This package is a [unified][] ([remark][]) plugin to support [retext][].
+
+**unified** is a project that transforms content with abstract syntax trees
+(ASTs).
+**remark** adds support for markdown to unified.
+**retext** adds support for natural language to unified.
+**mdast** is the markdown AST that remark uses.
+**nlcst** is the natural language AST that retext uses.
+This is a remark plugin that transforms mdast into nlcst to support retext.
+
+## When should I use this?
+
+This project is useful if you want to check natural language in markdown.
+The retext ecosystem has many useful plugins to check prose, such as
+[`retext-indefinite-article`][retext-indefinite-article] which checks that `a`
+and `an` are used correctly, or [`retext-readability`][retext-readability] which
+checks that sentences are not too complex.
+This plugins lets you use them on markdown documents.
+
+This plugin is unfortunately not able to apply changes by retext plugins (such
+as done by `retext-smartypants`) to the markdown content.
+
 ## Install
 
-This package is [ESM only](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c):
-Node 12+ is needed to use it and it must be `import`ed instead of `require`d.
+This package is [ESM only](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c).
+In Node.js (version 12.20+, 14.14+, or 16.0+), install with [npm][]:
 
-[npm][]:
-
 ```sh
@@ -31,2 +64,16 @@ npm install remark-retext
 
+In Deno with [Skypack][]:
+
+```js
+import remarkRetext from 'https://cdn.skypack.dev/remark-retext@5?dts'
+```
+
+In browsers with [Skypack][]:
+
+```html
+<script type="module">
+  import remarkRetext from 'https://cdn.skypack.dev/remark-retext@5?min'
+</script>
+```
+
 ## Use
@@ -43,3 +90,3 @@
 ```js
-import {readSync} from 'to-vfile'
+import {read} from 'to-vfile'
 import {reporter} from 'vfile-reporter'
@@ -53,12 +100,13 @@ import {unified} from 'unified'
 
-const file = readSync('example.md')
+main()
 
-unified()
-  .use(remarkParse)
-  .use(remarkRetext, unified().use(retextEnglish).use(retextEquality))
-  .use(remarkStringify)
-  .process(file)
-  .then((file) => {
-    console.error(reporter(file))
-  })
+async function main() {
+  const file = await unified()
+    .use(remarkParse)
+    .use(remarkRetext, unified().use(retextEnglish).use(retextEquality))
+    .use(remarkStringify)
+    .process(await read('example.md'))
+
+  console.error(reporter(file))
+}
 ```
@@ -82,21 +130,97 @@
 
-[**remark**][remark] ([**mdast**][mdast]) plugin to bridge or mutate to
-[**retext**][retext] ([**nlcst**][nlcst]).
+**[remark][]** plugin to support **[retext][]**.
 
-###### `destination`
+##### `destination`
 
 `destination` is either a parser or a processor.
 
-If a [`Unified`][processor] processor is given, runs the destination processor
-with the new nlcst tree, then, after running discards that tree and continues on
-running the origin processor with the original tree ([*bridge mode*][bridge]).
+*   If a destination [processor][] is given, runs the plugins attached to it
+    with the new nlcst tree ([*bridge mode*][bridge]).
+    This given processor must have a parser attached (this can be done by using
+    the plugin `retext-english` or similar) and should use other retext plugins
+*   If a parser is given, runs further plugins attached to the same processor
+    with the new tree (*mutate mode*).
+    Such parsers are exported by packages like `retext-english` as `Parser`.
+    You should use other retext plugins after `remark-retext`.
 
-If a parser (such as [`parse-latin`][latin], [`parse-english`][english], or
-[`parse-dutch`][dutch]) is given, passes the tree to further plugins
-(*mutate mode*).
+##### `options`
 
-###### `options`
+Configuration (`Object`, optional).
 
-Passed to [`mdast-util-to-nlcst`][to-nlcst].
+###### `options.ignore`
 
+List of [mdast][] node types to ignore (`Array.<string>`).
+The types `'table'`, `'tableRow'`, and `'tableCell'` are always ignored.
+
+###### `options.source`
+
+List of [mdast][] node types to mark as [nlcst][] source nodes
+(`Array.<string>`).
+`'inlineCode'` is always marked as source.
+
+## Examples
+
+## Example: mutate mode
+
+The previous example was using *bridge* mode: the markdown AST remained for
+other plugins after `remark-retext`.
+This example uses *mutate* mode: the markdown AST is discarded and the natural
+language AST.
+This is not very useful: this is not a good way to get the plain text version
+of a markdown document.
+
+```js
+import {read} from 'to-vfile'
+import {reporter} from 'vfile-reporter'
+import {unified} from 'unified'
+import remarkParse from 'remark-parse'
+import remarkRetext from 'remark-retext'
+import {Parser} from 'retext-english'
+import retextEquality from 'retext-equality'
+import retextStringify from 'retext-stringify'
+
+main()
+
+async function main() {
+  const file = await unified()
+    .use(remarkParse)
+    .use(remarkRetext, Parser)
+    .use(retextEquality)
+    .use(retextStringify)
+    .process(await read('example.md'))
+
+  console.error(reporter(file))
+  console.log(String(file))
+}
+```
+
+…yields:
+
+```txt
+example.md
+  1:10-1:14  warning  `guys` may be insensitive, use `people`, `persons`, `folks` instead  gals-man  retext-equality
+
+⚠ 1 warning
+```
+
+```txt
+Hello guys!
+```
+
+## Types
+
+This package is fully typed with [TypeScript][].
+It exports an `Options` type, which specifies the interface of the accepted
+options.
+
+## Compatibility
+
+Projects maintained by the unified collective are compatible with all maintained
+versions of Node.js.
+As of now, that is Node.js 12.20+, 14.14+, and 16.0+.
+Our projects sometimes work with older versions, but this is not guaranteed.
+
+This plugin works with `unified` version 6+, `remark` version 3+, and `retext`
+version 7+.
+
 ## Security
@@ -163,2 +287,4 @@
 
+[skypack]: https://www.skypack.dev
+
 [health]: https://github.com/remarkjs/.github
@@ -180,2 +306,4 @@
 
+[unified]: https://github.com/unifiedjs/unified
+
 [processor]: https://github.com/unifiedjs/unified#processor
@@ -191,12 +319,12 @@
 
-[latin]: https://github.com/wooorm/parse-latin
+[to-nlcst]: https://github.com/syntax-tree/mdast-util-to-nlcst
 
-[english]: https://github.com/wooorm/parse-english
+[typescript]: https://www.typescriptlang.org
 
-[dutch]: https://github.com/wooorm/parse-dutch
+[xss]: https://en.wikipedia.org/wiki/Cross-site_scripting
 
-[to-nlcst]: https://github.com/syntax-tree/mdast-util-to-nlcst
+[rehype]: https://github.com/rehypejs/rehype
 
-[xss]: https://en.wikipedia.org/wiki/Cross-site_scripting
+[retext-indefinite-article]: https://github.com/retextjs/retext-indefinite-article
 
-[rehype]: https://github.com/rehypejs/rehype
+[retext-readability]: https://github.com/retextjs/retext-readability

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

16809

increased by38.65%

Number of package files

7

increased by40%

Lines of code

112

increased by19.15%

Number of lines in readme file

323

increased by65.64%

Worsened metrics

Number of medium supply chain risk alerts

1

increased byInfinity%

No dependency changes