fix(remark-includes): address review feedback

Create a local remark parser in the transformer and use it to parse
included markdown content. This removes reliance on processor context
being forwarded through the attacher, which improves robustness.

Update docs and examples to use the fs/read-file sync helper and
document that include blocks must be non-overlapping sibling regions.

Assisted-by: Claude-Sonnet-4-6

---
type: pre_commit_static_analysis_report
description: Results of running static analysis checks when committing changes.
report:
  - task: lint_filenames
    status: passed
  - task: lint_editorconfig
    status: passed
  - task: lint_markdown
    status: passed
  - task: lint_package_json
    status: na
  - task: lint_repl_help
    status: na
  - task: lint_javascript_src
    status: passed
  - task: lint_javascript_cli
    status: na
  - task: lint_javascript_examples
    status: passed
  - task: lint_javascript_tests
    status: na
  - task: lint_javascript_benchmarks
    status: na
  - task: lint_python
    status: na
  - task: lint_r
    status: na
  - task: lint_c_src
    status: na
  - task: lint_c_examples
    status: na
  - task: lint_c_benchmarks
    status: na
  - task: lint_c_tests_fixtures
    status: na
  - task: lint_shell
    status: na
  - task: lint_typescript_declarations
    status: passed
  - task: lint_typescript_tests
    status: na
  - task: lint_license_headers
    status: passed
---

Author: batpigandme

lib/node_modules/@stdlib/_tools/remark/plugins/remark-includes/README.md

@@ -67,6 +67,8 @@ and inserts the parsed Markdown content of the referenced file between the openi
 
 The opening include directive requires a `path` attribute with a double-quoted value.
 
+Include blocks must be non-overlapping sibling regions. Nested or overlapping include blocks are not supported.
+
 The plugin accepts the following `options`:
 
 -   **dir**: base directory for resolving include paths. Default: `null` (resolved relative to the processed file's directory).
@@ -87,8 +89,8 @@ If an opening include directive does not have a matching closing include directi
 
 ```javascript
 var join = require( 'path' ).join;
-var readFileSync = require( 'fs' ).readFileSync;
 var remark = require( 'remark' );
+var readFileSync = require( '@stdlib/fs/read-file' ).sync;
 var includes = require( '@stdlib/_tools/remark/plugins/remark-includes' );
 
 // Load a Markdown file...

lib/node_modules/@stdlib/_tools/remark/plugins/remark-includes/examples/index.js

@@ -18,9 +18,9 @@
 
 'use strict';
 
-var readFileSync = require( 'fs' ).readFileSync;
 var join = require( 'path' ).join;
 var remark = require( 'remark' );
+var readFileSync = require( '@stdlib/fs/read-file' ).sync;
 var includes = require( './../lib' );
 
 // Load a Markdown file...

lib/node_modules/@stdlib/_tools/remark/plugins/remark-includes/lib/attacher.js

@@ -62,7 +62,7 @@ function attacher( options ) {
 		}
 	}
 	debug( 'Attaching a plugin configured with the following options: %s', JSON.stringify( opts ) );
-	return transformerFactory( opts, this ); // eslint-disable-line no-invalid-this
+	return transformerFactory( opts );
 }
 
 

lib/node_modules/@stdlib/_tools/remark/plugins/remark-includes/lib/transformer.js

@@ -21,6 +21,7 @@
 // MODULES //
 
 var resolve = require( 'path' ).resolve;
+var remark = require( 'remark' );
 var logger = require( 'debug' );
 var visit = require( 'unist-util-visit' );
 var readFileSync = require( '@stdlib/fs/read-file' ).sync;
@@ -42,10 +43,12 @@ var INCLUDE_END = /<!--\s*<\/include>\s*-->/;
 * @private
 * @param {Options} opts - transformer options
 * @param {(string|null)} opts.dir - base directory for resolving include paths
-* @param {Object} processor - remark processor instance
 * @returns {Function} transformer function
 */
-function factory( opts, processor ) {
+function factory( opts ) {
+	var parser;
+
+	parser = remark();
 	return transformer;
 
 	/**
@@ -127,19 +130,14 @@ function factory( opts, processor ) {
 			debug( 'Found closing include comment at index: %d', end );
 
 			// Parse the included Markdown content into AST nodes:
-			if ( processor && typeof processor.parse === 'function' ) {
-				children = processor.parse( content ).children;
-			} else {
-				file.message( format( 'unable to parse include using processor context: %s', fpath ), node );
-				return;
-			}
+			children = parser.parse( content ).children;
 			debug( 'Parsed %d nodes from include file.', children.length );
 
 			// Remove existing nodes between the opening and closing tags:
 			parent.children.splice( index + 1, end - index - 1 );
 
 			// Insert the parsed nodes between the opening and closing tags:
-			Array.prototype.splice.apply(parent.children, [ index + 1, 0 ].concat( children ));
+			Array.prototype.splice.apply( parent.children, [ index + 1, 0 ].concat( children ) ); // eslint-disable-line max-len
 			debug( 'Inserted include content.' );
 		}
 	}