Improve mmap behavior and tests

Author: linhay

.github/workflows/release.yml

@@ -0,0 +1,104 @@
+name: Release
+
+on:
+  push:
+    branches: [ main ]
+
+concurrency:
+  group: release
+  cancel-in-progress: false
+
+jobs:
+  release:
+    name: Release (on push to main)
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Compute next tag
+        id: version
+        shell: bash
+        run: |
+          set -euo pipefail
+          latest_tag="$(git tag --list --sort=-v:refname | grep -E '^[0-9]+\.[0-9]+\.[0-9]+$' | head -n 1)"
+          if [[ -z "${latest_tag}" ]]; then
+            next_tag="1.0.0"
+          else
+            IFS='.' read -r major minor patch <<< "${latest_tag}"
+            patch=$((patch + 1))
+            next_tag="${major}.${minor}.${patch}"
+          fi
+          echo "next_tag=${next_tag}" >> "${GITHUB_OUTPUT}"
+
+      - name: Package skill artifact
+        shell: bash
+        run: |
+          set -euo pipefail
+          python3 - <<'PY'
+          from pathlib import Path
+          import zipfile
+          import sys
+
+          skill_path = Path("skills/STFilePath").resolve()
+          out_dir = Path("skills/dist").resolve()
+          skill_md = skill_path / "SKILL.md"
+
+          if not skill_md.exists():
+              print(f"[ERROR] SKILL.md not found at {skill_md}")
+              sys.exit(1)
+
+          lines = skill_md.read_text(encoding="utf-8").lstrip("\ufeff").splitlines()
+          if not lines or lines[0].strip() != "---":
+              print("[ERROR] Missing YAML frontmatter in SKILL.md (no opening ---)")
+              sys.exit(1)
+          try:
+              end_index = lines.index("---", 1)
+          except ValueError:
+              print("[ERROR] Missing YAML frontmatter in SKILL.md (no closing ---)")
+              sys.exit(1)
+
+          frontmatter = lines[1:end_index]
+          def get_field(name: str):
+              prefix = f"{name}:"
+              for line in frontmatter:
+                  if line.strip().startswith(prefix):
+                      return line.split(":", 1)[1].strip().strip('"').strip("'")
+              return None
+
+          name = get_field("name")
+          description = get_field("description")
+          if not name or not description:
+              print("[ERROR] SKILL.md frontmatter must include name and description")
+              sys.exit(1)
+
+          out_dir.mkdir(parents=True, exist_ok=True)
+          skill_filename = out_dir / f"{skill_path.name}.skill"
+          skip_names = {".DS_Store"}
+
+          with zipfile.ZipFile(skill_filename, "w", zipfile.ZIP_DEFLATED) as zipf:
+              for file_path in skill_path.rglob("*"):
+                  if file_path.is_file():
+                      if file_path.name in skip_names:
+                          continue
+                      if any(part in ("__MACOSX",) for part in file_path.parts):
+                          continue
+                      arcname = file_path.relative_to(skill_path.parent)
+                      zipf.write(file_path, arcname)
+                      print(f"  Added: {arcname}")
+
+          print(f"\n[OK] Successfully packaged skill to: {skill_filename}")
+          PY
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: ${{ steps.version.outputs.next_tag }}
+          name: Release ${{ steps.version.outputs.next_tag }}
+          generate_release_notes: true
+          files: |
+            skills/dist/STFilePath.skill

README.md

@@ -129,6 +129,31 @@ Task {
 }
 ```
 
+### Memory Mapping (mmap)
+
+`STFile` supports scoped memory mapping for fast reads/writes.
+
+```swift
+import STFilePath
+
+let file = STFile("path/to/data.bin")
+try file.setSize(4096)
+
+try file.withMmap { mmap in
+    let data = mmap.read()
+    print("bytes:", data.count)
+    try mmap.write(Data([0x01, 0x02, 0x03]), at: 0)
+    mmap.sync()
+}
+```
+
+Notes:
+- `offset` must be page-aligned (e.g. `getpagesize()`).
+- Mapping size must be greater than 0 and within file bounds.
+- If `size` is `nil`, the mapping size is `fileSize - offset`.
+- Use `.share` to write back to disk, `.private` for copy-on-write.
+- `MAP_SHARED` mappings can observe external process writes once they are flushed (platform behavior applies).
+
 ## License
 
 `STFilePath` is available under the MIT license. See the [LICENSE](LICENSE) file for more info.

README_zh-CN.md

@@ -129,6 +129,31 @@ Task {
 }
 ```
 
+### 内存映射（mmap）
+
+`STFile` 支持作用域内存映射，便于快速读写。
+
+```swift
+import STFilePath
+
+let file = STFile("path/to/data.bin")
+try file.setSize(4096)
+
+try file.withMmap { mmap in
+    let data = mmap.read()
+    print("bytes:", data.count)
+    try mmap.write(Data([0x01, 0x02, 0x03]), at: 0)
+    mmap.sync()
+}
+```
+
+注意事项：
+- `offset` 必须按页大小对齐（例如 `getpagesize()`）。
+- 映射大小必须大于 0 且不能超出文件范围。
+- 当 `size` 为 `nil` 时，映射大小为 `fileSize - offset`。
+- `.share` 会写回磁盘，`.private` 为写时复制（不回写）。
+- `MAP_SHARED` 的映射在外部进程写入并刷新后可被观察到（具体行为以平台为准）。
+
 ## 许可证
 
 `STFilePath` 在 MIT 许可下可用。有关更多信息，请参阅 [LICENSE](LICENSE) 文件。

Sources/STFilePath/STFile+MMAP.swift

@@ -116,16 +116,26 @@ public class STFileMMAP {
                      size: Int?,
                      offset: Int) throws {
 
-        guard file.isExist else {
+        guard file.isExists else {
             throw STPathError(message: "[en] Cannot open non-existent file at \'\(file.url.path)\' [zh] 无法打开不存在的文件 \'\(file.url.path)\'")
         }
-        
-        self.descriptor = try file.system.open(flag1: .readAndWrite, flag2: nil, mode: nil)
+
+        let openType: STFileSystem.OpenType = prot.contains(.write) ? .readAndWrite : .readOnly
+        self.descriptor = try file.system.open(flag1: openType, flag2: nil, mode: nil)
 
         do {
             let info = try file.system.stat(descriptor: descriptor)
-            let fileSize = info.st_size
-            let mapSize = size ?? Int(fileSize)
+            let fileSize = Int(info.st_size)
+            let mapSize = size ?? (fileSize - offset)
+            
+            guard offset >= 0 else {
+                throw STPathError(message: "[en] Offset must be greater than or equal to 0 [zh] 偏移量必须大于或等于 0")
+            }
+            
+            let pageSize = Int(getpagesize())
+            if offset % pageSize != 0 {
+                throw STPathError(message: "[en] Offset must be page-aligned (\(pageSize)) [zh] 偏移量必须按页大小对齐 (\(pageSize))")
+            }
 
             guard mapSize > 0 else {
                 throw STPathError(message: "[en] Mapping size must be greater than 0 [zh] 映射大小必须大于 0")
@@ -135,6 +145,10 @@ public class STFileMMAP {
                 throw STPathError(message: "[en] Mapping size (\(mapSize)) cannot exceed file size (\(fileSize)). Use file.setSize() first. [zh] 映射大小 (\(mapSize)) 不能超过文件大小 (\(fileSize))。请先使用 file.setSize()。")
             }
 
+            if offset + mapSize > fileSize {
+                throw STPathError(message: "[en] Mapping range exceeds file size (offset \(offset) + size \(mapSize) > \(fileSize)). [zh] 映射范围超出文件大小（偏移 \(offset) + 大小 \(mapSize) > \(fileSize)）。")
+            }
+            
             self.size = mapSize
             self.startPoint = Darwin.mmap(nil,
                                           self.size,