feat(parser): add support for internal ## File: header

This commit introduces support for a new internal header format within code blocks: `## File: path/to/file.ext`.

Similar to the existing `// File:` format, this header can appear on the first line of a fenced code block to specify the file path for the block's content. The header line itself is excluded from the generated file content.

This format provides an alternative way to define file paths internally, especially useful in contexts where `//` comments might not be standard (e.g., YAML, plain text).

Key features:
- Recognizes `## File: path` and `## File: \`path with spaces\``.
- Extracts the path, handling optional backticks.
- Excludes the header line from the output file content.
- Applies path format validation (rejects empty or invalid paths like `//`).
- Ignores the header if it doesn't appear on the *first* line of the block.

Added corresponding integration tests in `tests/parser/create_internal.rs` to verify the new format and its edge cases.

Author: Romelium

src/parser/pass1/internal_header.rs

@@ -2,8 +2,9 @@
 
 use crate::core_types::Action; // Import Action
 use crate::errors::ParseError;
-use crate::parser::helpers::{is_likely_comment, is_likely_string};
+use crate::parser::helpers::{ensure_trailing_newline, is_likely_comment, is_likely_string};
 use crate::parser::internal_comment::extract_path_from_internal_comment;
+use crate::parser::path_utils::validate_path_format;
 // Import the specific handler function and the context struct (if needed, though it's internal to the handler)
 use crate::parser::pass1::internal_comment_handler;
 use crate::parser::pass1::internal_standard_handler;
@@ -31,7 +32,7 @@ pub(crate) fn handle_internal_header(
     let stripped_first_line = first_line.trim();
     let header_original_pos = block_content_start + parse_offset; // Calculate original pos
 
-    // Check for // File: path or // path
+    // --- Check for // File: path or // path ---
     if let Some((path, include_header)) =
         extract_path_from_internal_comment(first_line, stripped_first_line)
     {
@@ -52,7 +53,59 @@ pub(crate) fn handle_internal_header(
         );
     }
 
-    // Check for **Action:** or ## Action:
+    // --- Check for ## File: path or ## File: `path` ---
+    // This is a new internal header format, similar to // File: but using ##
+    if stripped_first_line.starts_with("## File:") {
+        let content_after_prefix = stripped_first_line.strip_prefix("## File:").unwrap().trim();
+        let path = if content_after_prefix.len() > 1
+            && content_after_prefix.starts_with('`')
+            && content_after_prefix.ends_with('`')
+        {
+            content_after_prefix[1..content_after_prefix.len() - 1]
+                .trim()
+                .to_string()
+        } else {
+            content_after_prefix.to_string()
+        };
+
+        if path.is_empty() {
+            eprintln!(
+                "Warning: Internal header '## File:' at original pos {} found with empty path. Skipping.",
+                header_original_pos
+            );
+            return Ok(None);
+        }
+
+        if validate_path_format(&path).is_err() {
+            eprintln!(
+                "Warning: Invalid path format in internal header '{}' at original pos {}. Skipping.",
+                stripped_first_line, header_original_pos
+            );
+            return Ok(None);
+        }
+
+        println!(
+            "    Found internal header: '{}' (Excluded from output)",
+            stripped_first_line
+        );
+        processed_header_starts.insert(header_original_pos); // Mark header as processed
+
+        let mut final_content = rest_content.to_string();
+        ensure_trailing_newline(&mut final_content);
+
+        let action = Action {
+            action_type: crate::core_types::ActionType::Create,
+            path,
+            content: Some(final_content),
+            original_pos: 0, // Set later in pass1 mod
+        };
+        println!("     -> Added CREATE action for '{}'", action.path);
+        // Return the action and the block content start position (relative)
+        return Ok(Some((action, block_content_start)));
+    }
+
+    // --- Check for **Action:** or ## Action: (but not ## File:) ---
+    // This handles standard markdown headers like **File:** if they appear internally
     if let Some(caps) = HEADER_REGEX.captures(first_line) {
         // Apply heuristics *before* trying to extract path/action
         if is_likely_comment(stripped_first_line) || is_likely_string(stripped_first_line) {
@@ -62,6 +115,7 @@ pub(crate) fn handle_internal_header(
             );
             return Ok(None); // Ignore, do not mark as processed
         }
+        // Call the standard handler for these formats
         return internal_standard_handler::handle_internal_standard_header(
             caps,
             rest_content,
@@ -72,5 +126,6 @@ pub(crate) fn handle_internal_header(
         );
     }
 
+    // No internal header format matched on the first line
     Ok(None)
 }

tests/parser/create_internal.rs

@@ -1,4 +1,4 @@
-//! Tests for parsing internal 'Create' headers (// File:, //path).
+//! Tests for parsing internal 'Create' headers (// File:, //path, ## File:).
 
 use super::common::*; // Use helper from common.rs
 use strux::core_types::ActionType;
@@ -42,3 +42,61 @@ fn test_parse_internal_comment_backticks_path_excluded() {
         Some("Content here.\n"), // Header line excluded
     );
 }
+
+// --- NEW TESTS for ## File: internal header ---
+
+#[test]
+fn test_parse_internal_hash_file_header_excluded() {
+    let md = "\n```yaml\n## File: config/settings.yaml\nkey: value\nlist:\n  - item1\n```\n";
+    let actions = parse_markdown(md).expect("Parsing failed");
+    assert_eq!(actions.len(), 1);
+    assert_action(
+        actions.first(),
+        ActionType::Create,
+        "config/settings.yaml",
+        Some("key: value\nlist:\n  - item1\n"), // Header line excluded
+    );
+}
+
+#[test]
+fn test_parse_internal_hash_file_header_backticks_excluded() {
+    let md = "\n```\n## File: `docs/My Document.md`\n# Title\nSome text.\n```\n";
+    let actions = parse_markdown(md).expect("Parsing failed");
+    assert_eq!(actions.len(), 1);
+    assert_action(
+        actions.first(),
+        ActionType::Create,
+        "docs/My Document.md",
+        Some("# Title\nSome text.\n"), // Header line excluded
+    );
+}
+
+#[test]
+fn test_parse_internal_hash_file_header_not_first_line_ignored() {
+    let md = "\n```\nSome initial content.\n## File: should_be_ignored.txt\nMore content.\n```\n";
+    let actions = parse_markdown(md).expect("Parsing failed");
+    assert!(
+        actions.is_empty(),
+        "Internal ## File: header not on the first line should be ignored"
+    );
+}
+
+#[test]
+fn test_parse_internal_hash_file_header_invalid_path_ignored() {
+    let md = "\n```\n## File: invalid//path.log\nLog data\n```\n";
+    let actions = parse_markdown(md).expect("Parsing failed");
+    assert!(
+        actions.is_empty(),
+        "Internal ## File: header with invalid path should be ignored"
+    );
+}
+
+#[test]
+fn test_parse_internal_hash_file_header_empty_path_ignored() {
+    let md = "\n```\n## File: \nContent\n```\n";
+    let actions = parse_markdown(md).expect("Parsing failed");
+    assert!(
+        actions.is_empty(),
+        "Internal ## File: header with empty path should be ignored"
+    );
+}