Prompt file imported from HyperLee/BitManipulation (.github/prompts/BitManipulation.prompt.md). Copyright stays with the author.

BitManipulation 開發規格書（Single Source of Truth）

本文件為 BitManipulation 專案唯一事實來源（Single Source of Truth, SSoT）。 所有實作、測試、文件撰寫均須以此規格為準；如需變更，請先修訂本文件再行實作。

1. 專案概述（Overview）

1.1 專案目的（Purpose）

建構一個以 C# / .NET 10 為基礎、聚焦於 位元運算（Bit Manipulation） 的學習與實戰專案，內容涵蓋：

• 六大核心位元運算子（Bitwise Operators）的觀念、API 與互動式示範。
• 常見實戰技巧（Bit Tricks）：奇偶判斷、2 的冪次、變數交換、漢明重量（Hamming Weight）、位元遮罩（Bit Mask）等。
• 進階位元演算法（Advanced Algorithms）：Single Number、Subsets、Gray Code、Bit Compression 等。
• 15 題精選 LeetCode 位元運算題庫，含完整解題思路與複雜度分析。
• 完整 xUnit 單元測試與教學文件。

1.2 學習目標（Learning Objectives）

完成本專案後，讀者 / 開發者應能夠：

1. 熟練使用 C# 中的位元運算子（&、|、^、~、<<、>>、>>>）。
2. 推導並實作常見位元技巧背後的數學原理（補數、二補數、位元遮罩）。
3. 在演算法題目中辨識可用位元運算優化的場景。
4. 撰寫具邊界條件、覆蓋率 ≥ 90% 的 xUnit 單元測試。
5. 善用 System.Numerics.BitOperations 等內建高效 API。

1.3 預期產出（Deliverables）

1.4 適用對象與先備知識（Audience & Prerequisites）

• 主要讀者：本專案開發者、GitHub Copilot Agent。
• 次要讀者：研讀位元運算與演算法的 C# / .NET 學習者。
• 先備知識：C# 基本語法、.NET CLI 操作、基礎資料結構與演算法。

2. 技術棧與環境（Tech Stack）

啟用設定（所有 .csproj 共通）：

• <Nullable>enable</Nullable>
• <ImplicitUsings>enable</ImplicitUsings>
• <LangVersion>latest</LangVersion>
• <TreatWarningsAsErrors>true</TreatWarningsAsErrors>（驗收條件之一）

3. 解決方案結構（Solution Layout）

BitManipulation.sln
├── BitManipulation/                  # 主專案（Console + 類別庫）
│   ├── BitManipulation.csproj
│   ├── Program.cs                    # Console 進入點 + 主選單
│   ├── Core/
│   │   └── BitwiseOperators.cs       # 六大運算子 API 與示範
│   ├── Algorithms/
│   │   ├── BitTricks.cs              # 實戰技巧
│   │   └── AdvancedBitAlgorithms.cs  # 進階演算法
│   ├── LeetCode/
│   │   ├── Solution0136.cs           # Single Number
│   │   ├── Solution0137.cs           # Single Number II
│   │   ├── Solution0260.cs           # Single Number III
│   │   ├── Solution0191.cs           # Number of 1 Bits
│   │   ├── Solution0231.cs           # Power of Two
│   │   ├── Solution0338.cs           # Counting Bits
│   │   ├── Solution0389.cs           # Find the Difference
│   │   ├── Solution0371.cs           # Sum of Two Integers
│   │   ├── Solution0461.cs           # Hamming Distance
│   │   ├── Solution0477.cs           # Total Hamming Distance
│   │   ├── Solution0201.cs           # Bitwise AND of Numbers Range
│   │   ├── Solution0693.cs           # Binary Number with Alternating Bits
│   │   ├── Solution0762.cs           # Prime Number of Set Bits
│   │   ├── Solution1009.cs           # Complement of Base 10 Integer
│   │   └── Solution0078.cs           # Subsets
│   └── UI/
│       ├── MenuRunner.cs             # 主選單分派
│       └── ConsoleHelper.cs          # 輸入驗證 / 顯示工具
│
├── BitManipulation.Tests/            # xUnit 測試專案
│   ├── BitManipulation.Tests.csproj
│   ├── Core/
│   │   └── BitwiseOperatorsTests.cs
│   ├── Algorithms/
│   │   ├── BitTricksTests.cs
│   │   └── AdvancedBitAlgorithmsTests.cs
│   └── LeetCode/
│       └── Solution{XXXX}Tests.cs    # 對應每題
│
├── docs/                              # 教學文件
│   ├── 01-fundamentals.md
│   ├── 02-operators.md
│   ├── 03-tricks.md
│   ├── 04-advanced.md
│   └── 05-leetcode.md
│
├── README.md
├── .editorconfig
└── .github/
    ├── instructions/csharp.instructions.md
    └── prompts/BitManipulation.prompt.md   # 本規格書

3.1 命名空間（Namespaces）

4. 功能模組規格（Functional Modules）

API 共通要求：所有公開方法須附 XML doc，含 <summary>、<param>、<returns>、<example>；所有靜態類別之公開 API 標示為 public static。

4.1 核心運算子示範（BitManipulation.Core.BitwiseOperators）

• 輸入限制：位移量 n 必須為 0 ≤ n < 32，超出範圍丟 ArgumentOutOfRangeException。
• 複雜度：所有方法 O(1)。

4.2 實戰技巧（BitManipulation.Algorithms.BitTricks）

• 邊界條件：index 必須 0 ≤ index < 32，違反者拋 ArgumentOutOfRangeException。
• 複雜度：除 HammingWeight 為 O(k)（k 為 1 的個數）外，其餘 O(1)。

4.3 進階演算法（BitManipulation.Algorithms.AdvancedBitAlgorithms）

• 邊界條件：Subsets 限制 nums.Length ≤ 20；Compress 超過 64 位元拋例外。
• 複雜度：詳見 docs/04-advanced.md。

4.4 LeetCode 題集（BitManipulation.LeetCode.Solution{XXXX}）

每個題目對應一個 Solution{XXXX} 類別，至少包含：

/// <summary>
/// LeetCode {XXXX}. {Title}
/// 連結：https://leetcode.com/problems/{slug}/
/// 難度：{Easy|Medium|Hard}
/// 標籤：Bit Manipulation, ...
/// 思路：{簡述}
/// 時間複雜度：O(?)
/// 空間複雜度：O(?)
/// </summary>
public sealed class Solution{XXXX}
{
    public {ReturnType} {MethodName}({Params}) { ... }
}

各題公開方法須與 LeetCode 題目原始簽章一致（命名與型別），方便對照。

5. LeetCode 精選題目清單（15 題）

每題在 docs/05-leetcode.md 中皆有專屬段落，包含題意翻譯、範例、解法推導、複雜度與常見陷阱。

6. Console UI 規格

6.1 主選單（Main Menu）

============================================
  BitManipulation 位元運算示範
============================================
  [1] 核心運算子（Bitwise Operators）
  [2] 實戰技巧（Bit Tricks）
  [3] 進階演算法（Advanced Algorithms）
  [4] LeetCode 題集
  [0] 離開
--------------------------------------------
請選擇：

6.2 子選單規範

• 每個分類進入後顯示功能列表（編號 + 名稱）。
• 使用者輸入編號 → 提示輸入參數 → 顯示結果與二進位視覺化（呼叫 BitwiseOperators.ToBinaryString）→ 等待 Enter 返回。

6.3 輸入驗證

6.4 退出機制

• 主選單輸入 0 → 顯示「Goodbye」→ 結束程式（return 0）。
• 任何未捕獲例外應由 Program.Main 最外層 try/catch 攔截，輸出友善訊息並回傳非零狀態碼。

7. 編碼規範（Coding Standards）

本節為 .github/instructions/csharp.instructions.md 的補充與專案級強制要求。

• 語言版本：C# 14、<LangVersion>latest</LangVersion>。
• 命名空間：一律使用 file-scoped namespace。
• 命名：型別 / 公開成員 PascalCase；私有欄位 / 區域變數 camelCase；介面以 I 起始。
• null 檢查：使用 is null / is not null。
• Nullable：全專案啟用，公開 API 不接受 null 時應於進入點檢查並拋 ArgumentNullException。
• 使用宣告：優先 using declaration（C# 8+）。
• 模式比對：迴圈、條件分支盡量採用 switch expression / pattern matching。
• nameof：傳遞成員名稱字串（如例外訊息、ArgumentOutOfRangeException）一律使用 nameof。
• XML 文件：所有 public 與 protected 成員均須提供 XML doc；位元運算類別額外提供 <example> 與 <code>。
• 避免裝箱：位元運算路徑禁止對 int、long、uint 等型別進行不必要裝箱（不要將其透過 object、非泛型集合存取）。
• 禁用：goto、未經設計的 unsafe。

8. 測試規範（Testing）

8.1 框架與套件

• 測試框架：xUnit（xunit、xunit.runner.visualstudio）。
• 涵蓋率工具：coverlet.collector（透過 dotnet test --collect:"XPlat Code Coverage"）。
• 不引入第三方 mocking / fluent assertion 框架。

8.2 命名與結構

• 測試類別：{被測類別名稱}Tests。
• 測試方法：Method_Scenario_Expected，例如 IsPowerOfTwo_WhenInputIsZero_ReturnsFalse。
• 不撰寫 Arrange / Act / Assert 註解。
• 優先使用 [Theory] + [InlineData]，相同邏輯共用單一測試方法。

8.3 案例覆蓋要求

每個公開方法至少 3 種案例：

1. 正常案例（Happy path）
2. 邊界案例：0、1、int.MinValue、int.MaxValue、空陣列、單一元素等
3. 極端 / 例外案例：負位移、超出範圍、null 輸入等（驗證例外型別）

8.4 覆蓋率目標

• 行覆蓋率（line coverage）≥ 90%。
• 分支覆蓋率（branch coverage）≥ 85%。
• 由 CI 或 dotnet test 報告檢查；未達標視為驗收失敗。

8.5 範例（僅作格式示意，非實作）

public class BitTricksTests
{
    [Theory]
    [InlineData(1, true)]
    [InlineData(2, false)]
    [InlineData(0, false)]
    [InlineData(int.MaxValue, true)]
    public void IsOdd_VariousInputs_ReturnsExpected(int input, bool expected)
        => Assert.Equal(expected, BitTricks.IsOdd(input));
}

9. 教學文件規格（docs/）

每篇 Markdown 須包含以下固定段落：

1. 學習目標（Learning Objectives）
2. 理論背景（Theory）
3. C# 範例（Examples）：可執行片段，引用本專案 API。
4. 複雜度分析（Complexity）
5. 常見陷阱（Pitfalls）
6. 延伸閱讀（Further Reading）

10. README.md 規格

README.md 須涵蓋：

1. 專案簡介：一段話說明定位與目標。
2. 特色（Features）：條列 4–6 點。
3. 快速開始（Quick Start）：

   git clone <repo>
   cd BitManipulation
   dotnet build
   dotnet run --project BitManipulation
   dotnet test

4. 目錄結構：與 §3 一致的樹狀圖。
5. 執行方式：Console 互動範例截圖或 ASCII 範例。
6. 學習路徑（Learning Path）：建議順序 docs/01 → 05。
7. 貢獻指南（Contributing）：分支策略、commit 規範、PR 檢查清單。
8. 授權（License）：MIT。
9. 參考資料：與 §15 對齊。

11. 錯誤處理與邊界條件（Error Handling & Edge Cases）

12. 效能考量（Performance Considerations，非強制）

• 對於漢明重量、TrailingZeroCount、LeadingZeroCount 等場景，優先使用 System.Numerics.BitOperations，因其在支援的 CPU 上會編譯為 POPCNT / LZCNT / TZCNT 指令。
• 在熱路徑（hot path）避免：
  • 對 int、uint 進行不必要裝箱（如塞入 ArrayList、object[]）。
  • 使用 LINQ 取代簡單迴圈（除非可讀性顯著提升）。
• 若加入 BenchmarkDotNet：
  • 放置於獨立 BitManipulation.Benchmarks 專案（選用）。
  • 不影響主專案 / 測試專案建置。

13. 里程碑（Milestones）

14. 驗收標準（Acceptance Criteria）

專案視為「完成」須同時滿足：

• dotnet build -c Release 0 警告 0 錯誤（已啟用 TreatWarningsAsErrors）。
• dotnet test 全綠燈。
• 行覆蓋率 ≥ 90%、分支覆蓋率 ≥ 85%。
• 所有 public API 皆具備 XML doc，且具範例之核心 API 含 <example>。
• §3 解決方案結構與檔案命名完全一致。
• §5 列出之 15 題皆已實作並通過 LeetCode 官方範例對應的測試案例。
• docs/01-05 與 README.md 全部存在，無 TODO / 佔位符。
• Console 主選單可成功執行所有功能而不拋未捕獲例外。
• 規格書（本檔）與實作一致，若有差異須先修正本檔。

15. 參考資料（References）

• Wikipedia — Bitwise operation：https://en.wikipedia.org/wiki/Bitwise_operation
• Wikipedia — Two's complement：https://en.wikipedia.org/wiki/Two%27s_complement
• Wikipedia — Gray code：https://en.wikipedia.org/wiki/Gray_code
• GeeksforGeeks — Bit Manipulation：https://www.geeksforgeeks.org/bit-manipulation/
• Henry S. Warren, Jr. — Hacker's Delight (2nd Edition)
• LeetCode — Bit Manipulation tag：https://leetcode.com/tag/bit-manipulation/
• Microsoft Docs — System.Numerics.BitOperations：https://learn.microsoft.com/dotnet/api/system.numerics.bitoperations
• Microsoft Docs — Bitwise and shift operators：https://learn.microsoft.com/dotnet/csharp/language-reference/operators/bitwise-and-shift-operators

規格書變更紀錄（Changelog）

• v1.0：依 撰寫計畫 §1–§15 章節大綱完整建立規格書，移除原檔 OCR 雜訊與斷句錯誤。