fix(plugin-code-blocks): fix region interpolation incorrectly parsed (#304)

* fix(plugin-code-blocks): fix region interpolation incorrectly parsed

Closes #291

* docs(plugin-code-blocks): update readme

Author: GerkinDev

packages/plugin-code-blocks/README.md

@@ -25,7 +25,9 @@ For more infos, please refer to [the documentation](https://knodescommunity.gith
 
 ## Usage
 
-In any markdown content, (in README, pages, or doc comments), use the `{@codeblock ...}` & `{@inlineCodeblock ...}` macros to use code blocks.
+In the *source code* you want to use as *code blocks*, delimitate *regions*. *Regions* are started with `// #region my-name`, & ended with `// #endregion [my-name]`. Interleaved/nested *regions* are supported. Regions **must** only contain `[a-zA-Z0-9-_.]`.
+
+In any *markdown* content, (in README, pages, or doc comments), use the `{@codeblock ...}` & `{@inlineCodeblock ...}` tags to use *code blocks*.
 
 ### Reference a file
 
@@ -35,11 +37,12 @@ Syntax:
 {@codeblock <path-to-file>[#region] [mode] [ | custom-file-name]}
 ```
 
-- `<path-to-file>`: A path to the code file to embed. Checkout [this documentation page](https://knodescommunity.github.io/typedoc-plugins/_knodes_typedoc_pluginutils/pages/resolving-paths.html) for more infos on the syntax of the path.
-- `[#<region>]`: A named region in the target file. Regions are started with `// #region my-name`, & ended with `// #endregion [my-name]`. Interleaved/nested regions are supported. Note that region markers are not outputted in the generated code block. The `<region>` parameter can be a glob pattern, or a list of block names/patterns separated by a `+`.
+- `<path-to-file>`: A path to the code file to embed. Checkout [this documentation page](https://knodescommunity.github.io/typedoc-plugins/_knodes_typedoc_pluginutils/pages/resolving-paths.html) for more infos on the syntax of the path for monorepo configuration.
+  > Note that the path **must not** contain any of the following characters: `#|`
+- `[#<region>]`: A region selector in the target file. The `<region>` parameter can be a glob pattern, or a list of block names/patterns separated by a `+`. See [minimatch](https://www.npmjs.com/package/minimatch) for details on supported patterns.
+  > Note that region markers are not outputted in the generated code block.
 - `[mode]`: optional. Can be any valid {@link EBlockMode}, to override the default settings.
 - `[ | custom-file-name]`: allow to specify an explicit file name to display in the code block header.
--
 
 `{@codeblock ...}` are by default looked up into your [*workspace*](https://knodescommunity.github.io/typedoc-plugins/_knodes_typedoc_pluginutils/pages/resolving-paths.html) `examples` folder, but you can customize it by using the [`source` option](https://knodescommunity.github.io/typedoc-plugins/_knodes_typedoc_plugin_code_blocks/pages/options.html)
 

packages/plugin-code-blocks/__tests__/integration/__snapshots__/simple.spec.ts.snap

@@ -1043,9 +1043,9 @@ exports[`Codeblock Inline tag \`classes/BlocInline.TestInlineExplicitProject.htm
 					<p>A test code block for project path implicitly in <code>examples</code> directory</p>
 					<details class="code-block" open>
 						<summary>
-							<p>From ./examples/example-test.json</p>
+							<p>From ./examples/complex-regions.js#1~8</p>
 						</summary>
-						<pre><code class="language-json"><span class="hl-0">{</span><span class="hl-1">&quot;Hello&quot;</span><span class="hl-0">: </span><span class="hl-2">&quot;World&quot;</span><span class="hl-0">}</span>
+						<pre><code class="language-js"><span class="hl-3">const</span><span class="hl-0"> </span><span class="hl-4">foo</span><span class="hl-0"> = </span><span class="hl-2">&#39;FOO&#39;</span><br/><span class="hl-5">// ...</span><br/><span class="hl-3">const</span><span class="hl-0"> </span><span class="hl-4">bar</span><span class="hl-0"> = </span><span class="hl-2">&#39;BAR&#39;</span>
 </code></pre>
 					</details>
 				</div>

packages/plugin-code-blocks/__tests__/integration/simple.spec.ts

@@ -76,7 +76,7 @@ describe( 'Codeblock', () => {
 
 				const codeblocks = dom.window.document.querySelectorAll( '.code-block' );
 				expect( codeblocks ).toHaveLength( 1 );
-				expect( codeblocks[0] ).toSatisfy( matchExpanded( './examples/example-test.json', SAMPLES['example-test.json'] ) );
+				expect( codeblocks[0] ).toSatisfy( matchExpanded( './examples/complex-regions.js#1~8', "const foo = 'FOO'// ...const bar = 'BAR'" ) );
 			} ) );
 			it( 'should have constant content', withContent( content => {
 				expect( formatHtml( content ) ).toMatchSnapshot();

packages/plugin-code-blocks/__tests__/mock-fs/simple/examples/complex-regions.js

@@ -0,0 +1,10 @@
+// #region foo
+const foo = 'FOO'
+// #endregion foo
+
+// #region ba-stuff
+// #region bar
+const bar = 'BAR'
+// #endregion bar
+const baz = 'BAZ'
+// #endregion ba-stuff

packages/plugin-code-blocks/__tests__/mock-fs/simple/src/codeblock/inline.ts

@@ -18,7 +18,7 @@ export class TestInlineRelativeModule{}
 /**
  * A test code block for project path implicitly in `examples` directory
  *
- * {@codeblock ~~:example-test.json}
+ * {@codeblock ~~:complex-regions.js#{foo,bar}}
  */
 export class TestInlineExplicitProject{}
 // #endregion

packages/plugin-code-blocks/src/output/markdown-code-blocks.spec.ts

@@ -67,17 +67,23 @@ describe( 'Behavior', () => {
 			withGitHub: boolean;
 		}
 		const defaultBlock = { startLine: 1, endLine: 1, file: FILE, region: DEFAULT_BLOCK_NAME as string };
-		const helloRegion: IBlockGenerationAssertion['blocks'] = [[ 'hello', { code: 'Content of foo/qux.txt', startLine: 13, endLine: 24 } ]];
+		const regions: IBlockGenerationAssertion['blocks'] = [
+			[ 'hello', { code: 'Content of foo/qux.txt', startLine: 13, endLine: 24 } ],
+			[ 'world', { code: 'stuff', startLine: 18, endLine: 42 } ],
+		];
 		it.each<[label: string, source: string, assertion: Partial<IBlockGenerationAssertion>]>( [
 			[ 'Mode ⇒ code block',            `{@codeblock ${FILE} default}`,          { renderCall: { mode: EBlockMode.DEFAULT }} ],
 			[ 'Mode ⇒ foldable code block',   `{@codeblock ${FILE} expanded}`,         { renderCall: { mode: EBlockMode.EXPANDED }} ],
 			[ 'Mode ⇒ folded code block',     `{@codeblock ${FILE} folded}`,           { renderCall: { mode: EBlockMode.FOLDED }} ],
 			[ 'Filename ⇒ default',           `{@codeblock ${FILE}}`,                  { renderCall: { asFile: `./${FILE}` }} ],
 			[ 'Filename ⇒ explicit',          `{@codeblock ${FILE} | hello.txt}`,      { renderCall: { asFile: 'hello.txt' }} ],
-			[ 'Filename ⇒ region',            `{@codeblock ${FILE}#hello}`,            { renderCall: { asFile: `./${FILE}#13~24` }, blocks: helloRegion } ],
-			[ 'Filename ⇒ region + explicit', `{@codeblock ${FILE}#hello | test.txt}`, { renderCall: { asFile: 'test.txt' }, blocks: helloRegion } ],
+			[ 'Filename ⇒ region',            `{@codeblock ${FILE}#hello}`,            { renderCall: { asFile: `./${FILE}#13~24` }, blocks: [ regions[0] ] } ],
+			[ 'Filename ⇒ region ({a,b})',    `{@codeblock ${FILE}#{hello,world}}`,    { renderCall: { asFile: `./${FILE}#13~42` }, blocks: regions } ],
+			[ 'Filename ⇒ region (a+b)',      `{@codeblock ${FILE}#hello+world}`,      { renderCall: { asFile: `./${FILE}#13~42` }, blocks: regions } ],
+			[ 'Filename ⇒ region + explicit', `{@codeblock ${FILE}#hello | test.txt}`, { renderCall: { asFile: 'test.txt' }, blocks: [ regions[0] ] } ],
 			[ 'URL ⇒ default',                `{@codeblock ${FILE}}`,                  { withGitHub: true, renderCall: { url: `${FakeSource.REPO_URL}/${FILE}#L1` }} ],
-			[ 'URL ⇒ region',                 `{@codeblock ${FILE}#hello}`,            { withGitHub: true, renderCall: { url: `${FakeSource.REPO_URL}/${FILE}#L13` }, blocks: helloRegion } ],
+			[ 'URL ⇒ region',                 `{@codeblock ${FILE}#hello}`,            { withGitHub: true, renderCall: { url: `${FakeSource.REPO_URL}/${FILE}#L13` }, blocks: [ regions[0] ] } ],
+			[ 'Filename ⇒ region+mode+name',  `{@codeblock ${FILE}#*o* folded | qux}`, { renderCall: { asFile: 'qux', mode: EBlockMode.FOLDED }, blocks: regions } ],
 		] )( 'Code block "%s"', ( _label, source, { renderCall, blocks, withGitHub } ) => {
 			if( withGitHub ){
 				plugin.application.converter.addComponent( 'source', FakeSource as any );

packages/plugin-code-blocks/src/output/markdown-code-blocks.ts

@@ -25,7 +25,7 @@ const comments = Object.entries( {
 } );
 const getFirstLineIndent = ( lines?: string[] ) => ( lines?.filter( l => l.trim() )[0]?.match( /^\s*/ ) ?? [ '' ] )[0];
 const CODEBLOCK_KIND = reflectionKindUtils.addReflectionKind( name, 'CodeBlock' ) as ReflectionKind;
-const EXTRACT_CODE_BLOCKS_REGEX = /(\S+?\w+?)(?:#(.+?))?(?:\s+(\w+))?(?:\s*\|\s*(.*?))?\s*/;
+const EXTRACT_CODE_BLOCKS_REGEX = /(?<file>\S+?\w+?)(?:#(?<regions>[^|\n\s]+))?(?:\s+(?<mode>\w+))?(?:\s*\|\s*(?<name>.*?))?/;
 const EXTRACT_INLINE_CODE_BLOCKS_REGEX = /(\S+?)(?:\s+(\w+))?\s*(```(\w+)?.*?```)/s;
 export class MarkdownCodeBlocks implements IPluginComponent<CodeBlockPlugin>{
 	private readonly _logger = this.plugin.logger.makeChildLogger( MarkdownCodeBlocks.name );