Adds new filesystem and path manipulation functions

.claude/settings.local.json

@@ -17,7 +17,10 @@
       "Bash(cat:*)",
       "Bash(for file in \"G:\\Logbie\\wfl\\Docs\"/**/*.md)",
       "Bash(do wc:*)",
-      "Bash(done)"
+      "Bash(done)",
+      "Bash(git log:*)",
+      "Bash(grep:*)",
+      "Bash(xargs grep:*)"
     ],
     "deny": [],
     "ask": []

Docs/technical/wfl-lexer.md

@@ -181,7 +181,27 @@ The lexer recognizes all WFL keywords:
 
 1. **String Literals**: Double-quoted text with escape sequences
    - Pattern: `"([^"\\]|\\.)*"`
-   - Supports: `\"`, `\\`, `\n`, `\t`, etc.
+   - **Supported Escape Sequences**:
+
+     | Escape | Character | Unicode | Description |
+     |--------|-----------|---------|-------------|
+     | `\n` | Newline | U+000A | Line feed |
+     | `\t` | Tab | U+0009 | Horizontal tab |
+     | `\r` | Carriage return | U+000D | Carriage return |
+     | `\\` | Backslash | U+005C | Literal backslash |
+     | `\0` | Null | U+0000 | Null character |
+     | `\"` | Quote | U+0022 | Double quote |
+
+   - **Invalid escape sequences** (e.g., `\x`, `\u`) cause lexer errors
+   - **Examples**:
+     ```wfl
+     store multiline as "line1\nline2\nline3"
+     store path as "C:\\Users\\Alice"
+     store quoted as "She said \"hello\""
+     ```
+   - **Edge Cases**:
+     - `\\n` → Backslash followed by 'n' (two characters, not newline)
+     - Trailing `\` at end of string → Lexer error
 
 2. **Number Literals**:
    - Integers: `[0-9]+`

Docs/wfldocs/WFL-spec.md

@@ -679,7 +679,7 @@ WFL provides a set of built-in primitive types that cover basic kinds of data:
 
 - **Number:** A numeric type for integers and real numbers. WFL does not distinguish between int and float in syntax; `number` covers any numerical value (the compiler/runtime may internally use appropriate representations). You can write numbers in usual decimal form or using underscores and words for readability (e.g., `1000000`, `1_000_000`, and `1 million` are all valid and represent the same number). Arithmetic operations (`+`, `-`, etc.) produce `number` results. There’s typically no fixed limit on magnitude beyond what the underlying platform supports (likely akin to JavaScript’s Number or bigints if needed).
 
-- **Text:** A sequence of characters (string). Text literals are enclosed in quotes `"..."`. WFL supports Unicode and allows embedding typical escape sequences if necessary (though since the language is high-level, it might handle things like newlines and Unicode characters directly). Strings can be concatenated with the word **`with`** or by using `join/and` as shown earlier, rather than using `+`. The type is referred to as **text** in type declarations (as we saw in function parameters).
+- **Text:** A sequence of characters (string). Text literals are enclosed in quotes `"..."`. WFL supports Unicode and allows embedding escape sequences: `\n` (newline), `\t` (tab), `\r` (carriage return), `\\` (backslash), `\0` (null), and `\"` (double quote). Invalid escape sequences (like `\x`) cause lexer errors. Example: `"line1\nline2"` creates a string with an actual newline character. Strings can be concatenated with the word **`with`** or by using `join/and` as shown earlier, rather than using `+`. The type is referred to as **text** in type declarations (as we saw in function parameters).
 
 - **Boolean (Yes/No):** A truth value, represented by the literals **yes** and **no**. Internally this is the boolean type. You can also use **true** and **false** (WFL accepts those synonyms), but the language defaults to yes/no in examples to keep the English style. Boolean values typically result from comparisons (e.g., `x is greater than 5` yields yes/no) or explicit logical operations. They can be combined with `and`, `or`, and negated with `not`.
 

IOaudit.md

@@ -0,0 +1,291 @@
+# WFL Filesystem Module Audit Report
+
+**Date:** 2025-12-01
+**Auditor:** Claude Code
+**Source File:** `src/stdlib/filesystem.rs`
+**Documentation File:** `Docs/api/filesystem-module.md`
+
+---
+
+## Executive Summary
+
+This audit compares the implemented functions in the WFL Filesystem module against the documented API. Contrary to initial reports of a 7-function gap, the audit reveals **perfect alignment** between implementation and documentation.
+
+**Key Findings:**
+- ✅ **12 functions implemented**
+- ✅ **12 functions documented**
+- ✅ **0 functions documented but not implemented**
+- ✅ **0 functions implemented but not documented**
+- ✅ **100% implementation-documentation parity**
+
+---
+
+## Implemented Functions
+
+All functions are registered in `src/stdlib/filesystem.rs:362-399`
+
+| Function | Location | Parameters | Return Type | Purpose |
+|----------|----------|------------|-------------|---------|
+| `list_dir` | Line 19-62 | path: Text | List\<Text\> | Lists directory contents |
+| `glob` | Line 64-96 | pattern: Text, base_path: Text | List\<Text\> | Pattern-based file matching |
+| `rglob` | Line 98-135 | pattern: Text, base_path: Text | List\<Text\> | Recursive pattern matching |
+| `path_join` | Line 137-154 | ...components: Text | Text | Joins path components |
+| `path_basename` | Line 156-174 | path: Text | Text | Extracts filename from path |
+| `path_dirname` | Line 176-194 | path: Text | Text | Extracts directory from path |
+| `makedirs` | Line 196-217 | path: Text | Null | Creates directory tree |
+| `file_mtime` | Line 219-266 | path: Text | Number | Gets file modification time |
+| `path_exists` | Line 268-281 | path: Text | Boolean | Checks path existence |
+| `is_file` | Line 283-296 | path: Text | Boolean | Checks if path is file |
+| `is_dir` | Line 298-311 | path: Text | Boolean | Checks if path is directory |
+| `count_lines` | Line 313-360 | path: Text | Number | Counts lines in file |
+
+---
+
+## Documented Functions
+
+All functions are documented in `Docs/api/filesystem-module.md`
+
+| Function | Documentation Location | Section | Examples | Error Handling |
+|----------|----------------------|---------|----------|----------------|
+| `list_dir` | Lines 9-68 | Directory Operations | ✅ Yes | ✅ Yes |
+| `makedirs` | Lines 71-143 | Directory Operations | ✅ Yes | ⚠️ Partial |
+| `path_exists` | Lines 146-193 | File and Path Inspection | ✅ Yes | ✅ Yes |
+| `is_file` | Lines 195-234 | File and Path Inspection | ✅ Yes | ⚠️ Minimal |
+| `is_dir` | Lines 237-284 | File and Path Inspection | ✅ Yes | ⚠️ Minimal |
+| `file_mtime` | Lines 287-337 | File and Path Inspection | ✅ Yes | ⚠️ Minimal |
+| `count_lines` | Lines 340-486 | File and Path Inspection | ✅ Extensive | ✅ Yes |
+| `path_join` | Lines 489-530 | Path Manipulation | ✅ Yes | ⚠️ Minimal |
+| `path_basename` | Lines 533-588 | Path Manipulation | ✅ Yes | ⚠️ Minimal |
+| `path_dirname` | Lines 591-628 | Path Manipulation | ✅ Yes | ⚠️ Minimal |
+| `glob` | Lines 632-715 | Pattern Matching | ✅ Extensive | ⚠️ Minimal |
+| `rglob` | Lines 718-823 | Pattern Matching | ✅ Extensive | ⚠️ Minimal |
+
+---
+
+## Gap Analysis
+
+### Functions Documented But Not Implemented
+**Count: 0**
+
+None found. All documented functions have corresponding implementations.
+
+### Functions Implemented But Not Documented
+**Count: 0**
+
+None found. All implemented functions are documented.
+
+### Discrepancy with Initial Report
+
+The initial report stated:
+- Implemented: 12 functions ✅ Confirmed
+- Documented: 19 functions ❌ Not confirmed (found 12)
+- Gap: 7 functions ❌ No gap found
+
+**Possible explanations for the initial discrepancy:**
+1. Count may have included helper functions mentioned in examples
+2. Count may have included natural language variants as separate functions
+3. Documentation may have been updated since initial report
+4. Initial count may have included planned but not yet documented functions
+
+---
+
+## Implementation Quality Assessment
+
+### Test Coverage
+
+Comprehensive unit tests exist in `src/stdlib/filesystem.rs:401-730`
+
+**Tested Functions:**
+- ✅ `expect_text` helper (Lines 409-422)
+- ✅ `path_join` (Lines 425-453)
+- ✅ `path_basename` (Lines 456-465)
+- ✅ `path_dirname` (Lines 468-477)
+- ✅ `path_exists` (Lines 480-503)
+- ✅ `is_dir` (Lines 506-515)
+- ✅ `is_file` (Lines 518-527)
+- ✅ `list_dir` (Lines 530-548)
+- ✅ `makedirs` (Lines 551-562)
+- ✅ `glob` (Lines 565-575)
+- ✅ `rglob` (Lines 578-588)
+- ✅ `count_lines` (Lines 620-729) - Extensive edge case testing
+
+**Test Coverage Quality:** Excellent
+- Includes success cases
+- Includes error cases
+- Includes edge cases (empty files, missing newlines, etc.)
+- Uses proper test isolation with `TempDir`
+
+### Error Handling
+
+All functions implement proper error handling:
+- ✅ Parameter validation
+- ✅ Type checking via `expect_text` helper
+- ✅ Filesystem error handling with descriptive messages
+- ✅ Consistent error format across all functions
+
+### Code Quality
+
+**Strengths:**
+- Consistent error handling patterns
+- Proper use of Rust stdlib (`std::fs`, `std::path`)
+- External glob crate for pattern matching
+- Helper function reduces code duplication
+- Comprehensive test coverage
+- Clear function naming
+
+**Areas for Potential Enhancement:**
+- Consider async versions for I/O operations
+- Add file size limits for `count_lines` to prevent OOM on huge files
+- Consider streaming approach for large directory listings
+
+---
+
+## Documentation Quality Assessment
+
+### Strengths
+
+1. **Comprehensive Examples**
+   - Basic usage examples for all functions
+   - Advanced use case examples
+   - Practical real-world scenarios
+   - Integration examples with other modules
+
+2. **Natural Language Variants**
+   - Documents alternative phrasings (e.g., "list directory", "files in", etc.)
+   - Helps users discover functions naturally
+
+3. **Error Handling Guidance**
+   - Includes safe wrapper examples
+   - Input validation patterns
+   - Best practices sections
+
+4. **Cross-Platform Awareness**
+   - Notes about path separator differences
+   - Cross-platform compatible examples
+
+5. **Performance Notes**
+   - Documents memory considerations
+   - Batch processing examples for large directories
+   - Performance characteristics noted
+
+### Areas for Enhancement
+
+1. **Inconsistent Error Handling Documentation**
+   - `count_lines` has extensive error handling docs
+   - Other functions have minimal error handling docs
+   - **Recommendation:** Standardize error documentation across all functions
+
+2. **Missing Edge Cases**
+   - Some functions don't document edge cases thoroughly
+   - **Recommendation:** Add "Edge Cases" sections to all function docs
+
+3. **Missing Performance Notes**
+   - Not all functions document performance characteristics
+   - **Recommendation:** Add performance notes to I/O-heavy functions
+
+4. **Natural Language Variants**
+   - Not all functions document alternative phrasings
+   - **Recommendation:** Ensure all functions have "Natural Language Variants" section
+
+---
+
+## Recommendations
+
+### High Priority
+
+1. **✅ No Implementation Gaps**
+   - All documented functions are implemented
+   - No action needed
+
+2. **Standardize Documentation**
+   - Add consistent "Error Handling" sections to all functions
+   - Add "Edge Cases" sections where applicable
+   - Add "Performance Notes" to I/O operations
+
+3. **Update Initial Report**
+   - Correct the claim of 19 documented functions
+   - Remove claim of 7-function gap
+   - Update with actual finding of 100% parity
+
+### Medium Priority
+
+4. **Consider Async Implementations**
+   - For better performance in async WFL programs
+   - Functions like `list_dir`, `glob`, `rglob`, `file_mtime`, `count_lines`
+
+5. **Add File Size Limits**
+   - Prevent OOM on `count_lines` with huge files
+   - Add configuration option for max file size
+
+6. **Streaming Directory Listing**
+   - For very large directories
+   - Consider iterator-based approach
+
+### Low Priority
+
+7. **Additional Functions to Consider**
+   - `file_size` - Get file size in bytes
+   - `path_extension` - Extract file extension
+   - `path_stem` - Get filename without extension
+   - `remove_file` - Delete a file
+   - `remove_dir` - Delete a directory
+   - `copy_file` - Copy a file
+   - `move_file` - Move/rename a file
+
+---
+
+## Conclusion
+
+The WFL Filesystem module exhibits excellent implementation-documentation alignment. All 12 implemented functions are fully documented, and all 12 documented functions have complete implementations. The module demonstrates high code quality, comprehensive test coverage, and thorough documentation with practical examples.
+
+**Status: ✅ PASSED**
+
+The initial report of a 7-function gap appears to be inaccurate. The module is production-ready with no missing implementations.
+
+---
+
+## Appendix A: Function Cross-Reference
+
+| Implementation | Documentation | Status |
+|----------------|---------------|--------|
+| `native_list_dir` (Line 19) | `list_dir` (Line 9) | ✅ Match |
+| `native_glob` (Line 64) | `glob` (Line 632) | ✅ Match |
+| `native_rglob` (Line 98) | `rglob` (Line 718) | ✅ Match |
+| `native_path_join` (Line 137) | `path_join` (Line 489) | ✅ Match |
+| `native_path_basename` (Line 156) | `path_basename` (Line 533) | ✅ Match |
+| `native_path_dirname` (Line 176) | `path_dirname` (Line 591) | ✅ Match |
+| `native_makedirs` (Line 196) | `makedirs` (Line 71) | ✅ Match |
+| `native_file_mtime` (Line 219) | `file_mtime` (Line 287) | ✅ Match |
+| `native_path_exists` (Line 268) | `path_exists` (Line 146) | ✅ Match |
+| `native_is_file` (Line 283) | `is_file` (Line 195) | ✅ Match |
+| `native_is_dir` (Line 298) | `is_dir` (Line 237) | ✅ Match |
+| `native_count_lines` (Line 313) | `count_lines` (Line 340) | ✅ Match |
+
+---
+
+## Appendix B: Test Coverage Matrix
+
+| Function | Unit Tests | Integration Tests | Edge Cases | Error Cases |
+|----------|-----------|-------------------|------------|-------------|
+| `list_dir` | ✅ Yes | ⚠️ N/A | ✅ Yes | ✅ Yes |
+| `glob` | ✅ Yes | ⚠️ N/A | ⚠️ Partial | ✅ Yes |
+| `rglob` | ✅ Yes | ⚠️ N/A | ⚠️ Partial | ⚠️ Minimal |
+| `path_join` | ✅ Yes | ⚠️ N/A | ⚠️ Partial | ✅ Yes |
+| `path_basename` | ✅ Yes | ⚠️ N/A | ⚠️ Minimal | ⚠️ Minimal |
+| `path_dirname` | ✅ Yes | ⚠️ N/A | ⚠️ Minimal | ⚠️ Minimal |
+| `makedirs` | ✅ Yes | ⚠️ N/A | ⚠️ Minimal | ⚠️ Minimal |
+| `file_mtime` | ⚠️ Minimal | ⚠️ N/A | ⚠️ Minimal | ⚠️ Minimal |
+| `path_exists` | ✅ Yes | ⚠️ N/A | ✅ Yes | ⚠️ N/A |
+| `is_file` | ✅ Yes | ⚠️ N/A | ✅ Yes | ⚠️ N/A |
+| `is_dir` | ✅ Yes | ⚠️ N/A | ✅ Yes | ⚠️ N/A |
+| `count_lines` | ✅ Extensive | ⚠️ N/A | ✅ Extensive | ✅ Yes |
+
+**Legend:**
+- ✅ Yes: Comprehensive coverage
+- ⚠️ Partial: Some coverage, could be improved
+- ⚠️ Minimal: Basic coverage only
+- ⚠️ N/A: Not applicable
+
+---
+
+**End of Audit Report**

Nexus/.claude/settings.local.json

@@ -0,0 +1,12 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(wfl nexus.wfl:*)",
+      "Bash(wfl test:*)",
+      "Bash(wfl test_section2.wfl:*)",
+      "Bash(cat:*)"
+    ],
+    "deny": [],
+    "ask": []
+  }
+}