fixing and simplifying logic for content exclusion to catch certain edge cases

Author: williamdalessandro

scripts/prebuild/mdx-transforms/exclude-content/ast-utils.mjs

@@ -29,7 +29,7 @@ function isCommentNode(node) {
  * Parse all directive blocks from AST in a single pass
  *
  * @param {Object} tree Remark AST
- * @returns {Array} Array of block objects with start, end, and content
+ * @returns {Array} Array of block objects with startNode, endNode, and content
  */
 export function parseDirectiveBlocks(tree) {
 	const blocks = []
@@ -48,7 +48,7 @@ export function parseDirectiveBlocks(tree) {
 		if (beginMatch) {
 			if (currentBlock) {
 				throw new Error(
-					`Nested BEGIN blocks not allowed. Found BEGIN at line ${lineNumber}, previous BEGIN at line ${currentBlock.start}`,
+					`Nested BEGIN blocks not allowed. Found BEGIN at line ${lineNumber}, previous BEGIN at line ${currentBlock.startLine}`,
 				)
 			}
 
@@ -58,9 +58,11 @@ export function parseDirectiveBlocks(tree) {
 			}
 
 			currentBlock = {
-				start: lineNumber,
+				startNode: node,
+				startLine: lineNumber,
 				content: blockContent.trim(),
-				end: null,
+				endNode: null,
+				endLine: null,
 			}
 			return
 		}
@@ -81,13 +83,14 @@ export function parseDirectiveBlocks(tree) {
 
 			if (endContent.trim() !== currentBlock.content) {
 				throw new Error(
-					`Mismatched block names: BEGIN="${currentBlock.content}" at line ${currentBlock.start}, ` +
+					`Mismatched block names: BEGIN="${currentBlock.content}" at line ${currentBlock.startLine}, ` +
 						`END="${endContent.trim()}" at line ${lineNumber}`,
 				)
 			}
 
 			// Complete the block
-			currentBlock.end = lineNumber
+			currentBlock.endNode = node
+			currentBlock.endLine = lineNumber
 			blocks.push(currentBlock)
 			currentBlock = null
 		}
@@ -96,47 +99,56 @@ export function parseDirectiveBlocks(tree) {
 	// Check for unclosed blocks
 	if (currentBlock) {
 		throw new Error(
-			`Unclosed BEGIN block: "${currentBlock.content}" opened at line ${currentBlock.start}`,
+			`Unclosed BEGIN block: "${currentBlock.content}" opened at line ${currentBlock.startLine}`,
 		)
 	}
 
 	return blocks
 }
 
 /**
- * Remove nodes from AST within specified line range
+ * Remove nodes from AST within specified block using node references
  *
- * This handles nodes from included partials which may not have position data
- * matching the parent file's line numbers. We track when we enter/exit the
- * removal range based on the BEGIN/END comments.
+ * This uses actual node object references to identify the range, avoiding
+ * issues with overlapping line numbers from multiple partials.
  *
  * @param {Object} tree Remark AST
- * @param {number} startLine Start line (inclusive)
- * @param {number} endLine End line (inclusive)
+ * @param {Object} block Block object with startNode and endNode references
  */
-export function removeNodesInRange(tree, startLine, endLine) {
+export function removeNodesInRange(tree, block) {
+	const { startNode, endNode } = block
+
 	function removeFromNodes(nodes, depth = 0, parentInsideRange = false) {
 		if (!Array.isArray(nodes)) {
 			return parentInsideRange
 		}
 
 		const indicesToRemove = []
 		let insideRange = parentInsideRange
-		let lastEndLine = null // Track the line number where we last found an END comment
 
 		for (let i = 0; i < nodes.length; i++) {
 			const node = nodes[i]
-			const hasPosition = node.position?.start?.line && node.position?.end?.line
 
-			// Recursively check children FIRST to find any nested END comments
-			// before deciding whether to remove this node
-			// const hadChildren = !!node.children
+			// Check if this is the START node
+			if (node === startNode) {
+				insideRange = true
+				indicesToRemove.push(i)
+				continue
+			}
+
+			// Check if this is the END node
+			if (node === endNode) {
+				indicesToRemove.push(i)
+				insideRange = false
+				continue
+			}
+
+			// Recursively check children
 			const wasInsideRange = insideRange
 			if (node.children) {
 				insideRange = removeFromNodes(node.children, depth + 1, insideRange)
 
-				// After recursion, children have already been removed.
-				// Determine whether to remove the parent node:
+				// After recursion, decide whether to remove the parent node
 				const nodeIsComment = isCommentNode(node)
 
 				// If we were inside range and still are, remove the parent (fully in range)
@@ -146,9 +158,7 @@ export function removeNodesInRange(tree, startLine, endLine) {
 				}
 
 				// If range ENDED inside this node's children (END found in children),
-				// only remove parent if it's now empty (all children were removed).
-				// Example: list containing [listItem1 (removed), listItem2 with END (removed), listItem3 (kept)]
-				// → Keep the list since listItem3 remains
+				// only remove parent if it's now empty (all children were removed)
 				if (wasInsideRange && !insideRange) {
 					if (!node.children || node.children.length === 0) {
 						indicesToRemove.push(i)
@@ -157,70 +167,15 @@ export function removeNodesInRange(tree, startLine, endLine) {
 				}
 
 				// If range STARTED inside this node's children (BEGIN found in children),
-				// the parent node CONTAINS the range start and should NOT be removed.
-				// Example: listItem containing [paragraph, BEGIN comment] - keep the listItem, only BEGIN removed
+				// the parent node CONTAINS the range start and should NOT be removed
 				if (!wasInsideRange && insideRange) {
 					continue
 				}
 			}
 
-			if (hasPosition) {
-				const nodeStart = node.position.start.line
-				const nodeEnd = node.position.end.line
-
-				// Check if we've moved past the end of the range
-				// Only check this for comment nodes (jsx/html/code), as content nodes
-				// from partials can have any line numbers
-				const nodeIsComment = isCommentNode(node)
-				if (
-					insideRange &&
-					nodeIsComment &&
-					nodeStart >= startLine &&
-					nodeStart > endLine
-				) {
-					insideRange = false
-				}
-
-				// If we're NOT inside a range, check if this node starts one
-				if (!insideRange) {
-					// Special case: if we just found an END comment on this same line (lastEndLine),
-					// do NOT start a new range. This prevents removing unrelated BEGIN comments
-					// that happen to be on the same line as the END comment (e.g., line 24 has both
-					// "<!-- END: TFC:only -->" and "<!-- BEGIN: TFEnterprise:only -->")
-					if (lastEndLine !== null && nodeEnd === lastEndLine) {
-						// This is a BEGIN comment on the same line as the last END - skip it
-					}
-					// Check if this node marks the start of the range
-					// Only jsx/html/code nodes can be BEGIN comments
-					else if (
-						nodeIsComment &&
-						nodeStart >= startLine &&
-						nodeEnd <= endLine
-					) {
-						insideRange = true
-						indicesToRemove.push(i)
-					}
-				}
-				// If we're inside a range, all nodes are from the partial (except the END comment)
-				else {
-					// Check if this is the END comment
-					// END comments are jsx/html/code nodes with position data from the parent file
-					if (nodeIsComment && nodeStart >= startLine && nodeEnd === endLine) {
-						indicesToRemove.push(i)
-						insideRange = false
-						lastEndLine = nodeEnd // Remember the line where we found the END comment
-					}
-					// Otherwise, it's a partial node - remove it
-					else {
-						indicesToRemove.push(i)
-					}
-				}
-			} else {
-				// Node without position (e.g., from included partial)
-				// Remove it if we're currently inside the range
-				if (insideRange) {
-					indicesToRemove.push(i)
-				}
+			// If we're inside the range and this node isn't a boundary comment, remove it
+			if (insideRange) {
+				indicesToRemove.push(i)
 			}
 		}
 

scripts/prebuild/mdx-transforms/exclude-content/terraform-processor.mjs

@@ -10,7 +10,7 @@ import { removeNodesInRange } from './ast-utils.mjs'
  * Implements cross-product behavior based on your test requirements
  *
  * @param {string} directive The directive part (e.g., "only")
- * @param {Object} block Block information with start, end, content
+ * @param {Object} block Block information with startNode, endNode, content
  * @param {Object} tree Remark AST
  * @param {Object} options Processing options
  */
@@ -21,15 +21,15 @@ export function processTFCBlock(directive, block, tree, options) {
 	if (directive === 'only' || directive.startsWith('only ')) {
 		// TFC:only should be kept ONLY in terraform-docs-common, removed everywhere else
 		if (repoSlug !== 'terraform-docs-common') {
-			removeNodesInRange(tree, block.start, block.end)
+			removeNodesInRange(tree, block)
 		}
 		// else keeping block in terraform-docs-common
 		return
 	}
 
 	// If we get here, it's an invalid TFC directive
 	throw new Error(
-		`Invalid TFC directive: "${directive}" at lines ${block.start}-${block.end}. ` +
+		`Invalid TFC directive: "${directive}" at lines ${block.startLine}-${block.endLine}. ` +
 			`Expected format: TFC:only`,
 	)
 }
@@ -39,7 +39,7 @@ export function processTFCBlock(directive, block, tree, options) {
  * Implements cross-product behavior based on your test requirements
  *
  * @param {string} directive The directive part (e.g., "only")
- * @param {Object} block Block information with start, end, content
+ * @param {Object} block Block information with startNode, endNode, content
  * @param {Object} tree Remark AST
  * @param {Object} options Processing options
  */
@@ -50,14 +50,15 @@ export function processTFEnterpriseBlock(directive, block, tree, options) {
 	if (directive === 'only' || directive.startsWith('only ')) {
 		// TFEnterprise:only kept only in terraform-enterprise, removed everywhere else
 		if (repoSlug !== 'terraform-enterprise') {
-			removeNodesInRange(tree, block.start, block.end)
+			removeNodesInRange(tree, block)
 		}
 		// else keeping block (in terraform-enterprise)`)
 		return
 	}
 
 	// If we get here, it's an invalid TFEnterprise directive
 	throw new Error(
-		`Invalid TFEnterprise directive: "${directive}" at lines ${block.start}-${block.end}. Expected format: TFEnterprise:only`,
+		`Invalid TFEnterprise directive: "${directive}" at lines ${block.startLine}-${block.endLine}. ` +
+			`Expected format: TFEnterprise:only`,
 	)
 }

scripts/prebuild/mdx-transforms/exclude-content/vault-processor.mjs

@@ -11,7 +11,7 @@ import { removeNodesInRange } from './ast-utils.mjs'
  * Only processes Vault directives in vault files - ignores them elsewhere
  *
  * @param {string} directive The directive part (e.g., ">=v1.21.x")
- * @param {Object} block Block information with start, end, content
+ * @param {Object} block Block information with startNode, endNode, content
  * @param {Object} tree Remark AST
  * @param {Object} options Processing options
  */
@@ -32,7 +32,7 @@ export function processVaultBlock(directive, block, tree, options) {
 
 	// If we get here, it's an invalid Vault directive
 	throw new Error(
-		`Invalid Vault directive: "${directive}" at lines ${block.start}-${block.end}. ` +
+		`Invalid Vault directive: "${directive}" at lines ${block.startLine}-${block.endLine}. ` +
 			`Expected format: Vault:>=vX.Y.x`,
 	)
 }
@@ -46,7 +46,7 @@ function processVaultVersionDirective(versionMatch, block, tree, options) {
 
 	if (!version) {
 		throw new Error(
-			`Version directive requires version option at lines ${block.start}-${block.end}`,
+			`Version directive requires version option at lines ${block.startLine}-${block.endLine}`,
 		)
 	}
 
@@ -59,11 +59,11 @@ function processVaultVersionDirective(versionMatch, block, tree, options) {
 
 		// If version comparison fails, remove the content
 		if (!shouldKeepContent) {
-			removeNodesInRange(tree, block.start, block.end)
+			removeNodesInRange(tree, block)
 		}
 	} catch (error) {
 		throw new Error(
-			`Version comparison failed for "${block.content}" at lines ${block.start}-${block.end}: ${error.message}`,
+			`Version comparison failed for "${block.content}" at lines ${block.startLine}-${block.endLine}: ${error.message}`,
 		)
 	}
 }