Sync Copilot knowledge base

.github/Guidelines/Coding.md

@@ -13,6 +13,20 @@ In general, here is my preference for any languages:
   - DRY requires finding if a feature has already been implemented somewhere else before implementing it. avoiding massive duplication.
     - If the existing implementation is not sharable, refactoring is preferred.
 
+## C++ Coding Convention
+
+- Although C++ does not require this but we want to have `extern` on all function forward declarations.
+  - In general we don't use `inline` in header files unless such function is performance critical, e.g. very simple comparison operators.
+- Rules for C++ header files:
+  - Guard them with macros instead of `#pragma once`.
+  - In a class/struct/union declaration, member names must be aligned in the same column at least in the same public, protected or private section.
+  - Keep the coding style consistent with other header files in the same project.
+- Extra Rules for C++ header files in `Source` folder:
+  - Do not use `using namespace` statements; the full names of types are always required.
+- Rules for cpp files:
+  - Use `using namespace` statement if necessary to prevent from repeating namespace everywhere.
+  - `vl::stream::` is an exception, always use `stream::` with `using namespace vl;`, DO NOT use `using namespace vl::stream;`.
+
 ## Basic C++ Library Leveraging
 
 - This project uses C++ 20, you are recommended to use new C++ 20 features aggressively.
@@ -29,22 +43,13 @@ In general, here is my preference for any languages:
   - Always use `FilePath` for file path operations.
   - Use my own collection types vl::collections::* instead of std::*
   - Check out `REPO-ROOT/.github/KnowledgeBase/Index.md` for more information on how to choose the correct C++ data types.
-- Rules for expressing unavailable values:
+- To attach availability semantic to a value:
   - If any number is expected to be valid only when non-negative, you could use `-1` to represent invalid value.
   - If an object is expected to be valid only when non-null, you could use `nullptr` on `T*` or `Ptr<T>` to represent invalid value.
   - Use `Nullable<T>` to represent any invalid value if possible.
     - DO NOT use `Nullable<T*>`, `Nullable<Ptr<T>>` or `Nullable<Nullable<T>>`, this is too confusing.
   - Only when there is no other choice, use an extra `bool` variable.
     - This could happen when "null" semantic is valid.
-- Rules for C++ header files:
-  - Guard them with macros instead of `#pragma once`.
-  - In a class/struct/union declaration, member names must be aligned in the same column at least in the same public, protected or private section.
-  - Keep the coding style consistent with other header files in the same project.
-- Extra Rules for C++ header files in `Source` folder:
-  - Do not use `using namespace` statements; the full names of types are always required.
-- Rules for cpp files:
-  - Use `using namespace` statement if necessary to prevent from repeating namespace everywhere.
-  - `vl::stream::` is an exception, always use `stream::` with `using namespace vl;`, DO NOT use `using namespace vl::stream;`.
 
 ### Regular Expression
 
@@ -90,12 +95,18 @@ When `VlppParser2` is available to the current project, complex parsers always r
   - Avoid using an expression that creates temporary objects in `for(... : HERE)` or `for(... : indexed(HERE))`. The current C++ destroys the temporary object too early; therefore this becomes UB.
 - Prefer Inversion of Control (IoC) and other design patterns, over trivial virtual functions, over switch-case on types, over if-else on types.
 - Prefer static dispatching over dynamic dispatching when possible and reasonable.
+- Unless explicitly instructed:
+  - You are not allowed to test if `VCZH_DEBUG_NO_REFLECTION` is defined.
+  - You are not allowed to test if `VCZH_DEBUG_METAONLY_REFLECTION` is defined.
+  - You are not allowed to call any function that does not work with `VCZH_DEBUG_NO_REFLECTION`.
+  - Reflection registration is an exception follow the document for recommended patterns.
 
-## Workflow Script Generation Rules
+## Keep C++ Code Cross Platform
 
-- When generating Workflow script, avoid building text, you should always build the AST. The AST type for a complete Workflow script module is `WfModule`.
+- All source files must aim for cross platform unless the file name has `.Windows` or `.Linux.`.
+- Use FilePath to normalize file path, for file path operations and delimiter access.
 
-## Workflow Script Authoring Rules
+## Workflow Script Coding Convention
 
 - Avoid explicit type specification whenever possible:
   - Prefer `var v = e;` whenever `T` can be omitted.
@@ -104,3 +115,7 @@ When `VlppParser2` is available to the current project, complex parsers always r
   - Prefer `cast *` over `cast T` when the context accepts `T`.
 - Nested `try-catch` and `try-finally` can be merged into one single `try-catch-finally` statement.
 - Prefer strong typed collections in Workflow, but when writing C++ reflectable interfaces, use `Ptr<IValue*>`.
+
+## Workflow Script Generation in C++
+
+- When generating Workflow script, avoid building text, you should always build the AST. The AST type for a complete Workflow script module is `WfModule`.

.github/KnowledgeBase/Learning.md

@@ -2,8 +2,8 @@
 
 # Orders
 
+- Process staged tasks one by one with verification [7]
 - Crash early instead of adding error-tolerance fallbacks [5]
-- Process staged tasks one by one with verification [5]
 - Use `WString::IndexOf` with `wchar_t` (not `const wchar_t*`) [4]
 - Use `collections::BinarySearchLambda` on contiguous buffers (guard empty) [4]
 - Capture dependent lambdas explicitly [2]
@@ -11,6 +11,7 @@
 - Use `ERROR_MESSAGE_PREFIX` for meaningful `CHECK_ERROR` / `CHECK_FAIL` messages [2]
 - Prefer simple calls before interface casts [2]
 - Validate expectations against implementation and existing tests [2]
+- Use `vl::Exception` for expected semantic failures and `CHECK_ERROR` for invariants [2]
 - Prefer well-defined tests over ambiguous edge cases [1]
 - Prefer `operator<=> = default` for lexicographic key structs [1]
 - Prefer two-pointer merge for sorted range maps [1]
@@ -23,7 +24,6 @@
 - `vl::regex` separator regex: `L"[\\/\\\\]+"` [1]
 - Use 2-space indentation in embedded XML/JSON literals [1]
 - `collections::List` has deleted copy constructor; use `std::move()` for structs with `List` members [1]
-- Use `vl::Exception` for expected semantic failures and `CHECK_ERROR` for invariants [1]
 
 # Refinements
 
@@ -41,7 +41,7 @@ When an invariant says a value must exist or a conversion must succeed, prefer u
 
 ## Process staged tasks one by one with verification
 
-When a request is split into explicit tasks, complete and verify each task before starting the next one. This keeps commits easy to understand and review, limits side effects to the current task, and avoids having to diagnose many unrelated issues at the same time.
+When a request is split into explicit tasks, complete and verify each task before starting the next one. This keeps commits easy to understand and review, limits side effects to the current task, and avoids having to diagnose many unrelated issues at the same time. If a task has its own finishing instructions, finish that task properly before moving on.
 
 ## Use `ERROR_MESSAGE_PREFIX` for meaningful `CHECK_ERROR` / `CHECK_FAIL` messages
 
@@ -123,4 +123,4 @@ When a C++ struct contains `vl::collections::List` fields, the struct's implicit
 
 ## Use `vl::Exception` for expected semantic failures and `CHECK_ERROR` for invariants
 
-When a failure is part of the public or script-visible semantics and tests are expected to catch it as a recoverable error, throw `vl::Exception`. Reserve `CHECK_ERROR` / `vl::Error` for internal invariant violations and states that indicate implementation corruption.
+When a failure is part of the public or script-visible semantics and tests are expected to catch it as a recoverable error, throw `vl::Exception`. Reserve `CHECK_ERROR` / `CHECK_FAIL` / `vl::Error` for internal invariant violations and states that indicate implementation corruption. For example, duplicate RPC registration can remain a catchable semantic exception when samples intentionally verify it, while impossible local type ids should fail as invariants.