diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 50700ff..a1d970d 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -1,5 +1,36 @@ # Mango.Nop Libraries — Domain Rules +## 🛑 AI AGENT CORE PROTOCOL (CRITICAL ENFORCEMENT) +You are operating in a multi-repo, documentation-first architecture. You MUST STRICTLY follow this protocol for every response. Failure to do so will break the workspace rules. + +1. **MANDATORY OUTPUT PREFIX:** Your response MUST begin exactly with this format on the very first line: + `[LOADED_DOCS: ]` + *(If no .md files are loaded yet, write `[LOADED_DOCS: NONE]`.)* + +2. **HARD-GATE DELAY (DOCS BEFORE CODE) & TOOL EXECUTION BLOCK:** + - If `[LOADED_DOCS: NONE]` applies, you **MUST STOP** and you are **STRICTLY FORBIDDEN** to use the following tools: `code_search`, `get_symbols_by_name`, `find_symbol`, or `get_file` (for non-markdown files). + - Your VERY FIRST AND ONLY allowed tool calls must be `file_search` or `get_file` targeting the `.md` documentation in the relevant `docs/` folders or `README.md`. + - Do not answer the user's core question until the `[LOADED_DOCS]` list is populated with the base architecture files. + - **CRITICAL EXCEPTION:** Do **NOT** re-read `.md` files that are already mapped in your context or `LOADED_DOCS` list (strictly maintain rule 18). + +3. **STRICT NO-RE-READ POLICY (ANTI-LOOP):** + You are PHYSICALLY FORBIDDEN from calling `get_file` or `file_search` on any `.md` file that is already listed in your `[LOADED_DOCS]` prefix. + - Once an `.md` file is in your context, it STAYS in your context. + - Re-reading them wastes tokens and breaks the protocol. + - ONLY re-read an `.md` file if the user EXPLICITLY states "the file has changed on disk, read it again". + - If the user simply mentions a glossary term or requests info found in a loaded doc, answer directly from memory. DO NOT search for it again. + +4. **CONTEXT RECOVERY (SMART READ):** + If the user asks a domain/architecture specific question and you realize the essential `.md` files are NO LONGER in your current context (they dropped out of memory), you **MUST automatically re-read** the necessary documentation before answering. + Do NOT wait for the user to explicitly tell you to re-read them. Prioritize scanning the `docs/` folders to recover the lost context. + + Directories to read (when recovering context): + - `docs/` (in this repository root) + +5. **EXPLICIT CONSENT FOR MODIFICATIONS:** + NEVER rewrite, create, or delete code/files without the user's explicit permission. If the user does not specifically request a code modification (e.g., using phrases like "we are just thinking," "what do you think," "let's plan"), you MUST ONLY provide text-based analysis and planning. You are FORBIDDEN from using file-modifying tools (`replace_string_in_file`, `edit_file`, `create_file`, etc.) until the user explicitly says "ok", "go ahead", "implement", or a similar unambiguous approval. + +## Workspace Dependencies # own-dep-repos: "name: path" — paths are relative to this repo root (.github/..) @repo { name = "Mango.Nop Libraries" @@ -39,12 +70,16 @@ ## Conventions 14. **`Mg` prefix** for all custom types: `MgEntityBase`, `MgOrderDto`, `MgDbTableBase`, etc. 15. **No redundant code** — before writing new logic, check whether similar methods already exist in the current context. Reuse or extract shared logic. -16. **Keep all .md files in sync** — when you modify code and you know which .md file documents it, update that .md file too. If you notice a contradiction between code and an .md file, automatically update the .md to match the code (code is the source of truth). When fixing a reference, check other .md files that may share the same broken reference. If the root cause is at a lower layer, fix it there first. During code review, if you find useful behavior or conventions not yet documented, briefly suggest what to document and where — but do not add new content without approval. +16. **Keep all .md documentation in sync (PASSIVE DETECTION & ASK FIRST)** — If you notice *any contradiction, error, or missing information* between the code and your currently loaded `.md` files, **briefly notify the user and ask for permission before making changes**. Do NOT automatically update `.md` files or trigger new searches yet. Once the user approves, you may actively search, read, and update the necessary docs in the correct layer. +**Identify missing documentation:** If you notice during your task that a frequently used pattern, underlying logic, or important behavior is missing from the docs, **and adding it would improve future LLM context-efficiency (saving searches/tokens)**, briefly notify the user to get approval. +**Topic-based separation:** When creating or expanding documentation, keep logically distinct features or domains in separate `.md` files (e.g., architecture, data model, billing) and only reference them in the main/index documents. Do not cram everything into a single monolithic file. Keep in mind: these `.md` files are primarily for LLM grounding and context providing. Keep them concise, structured, and focused on rules/patterns rather than human-readable prose. +**ENFORCEMENT:** At the end of EVERY code-modifying response, append a **`[DOCUMENTATION CHECK]`** section. Evaluate ONLY the `.md` files *already in your context*. State in 1-2 sentences if you found discrepancies or missing concepts, and ask if they should be documented. **DO NOT trigger searches or tool calls for this initial check**. 17. All AyCode references are via **DLL** (not ProjectReference) — this is intentional. **AyCode.Core** solution (`../../../../../Aycode/Source/AyCode.Core/`) contains all core framework code: interfaces, serialization, binary protocol, SignalR base classes, data sources, logging. Types not defined in this library (e.g. `IEntityInt`, `IId`, `AcConst`, `ToonDescription`) likely live in AyCode.Core. 18. **Do not re-read .md files** already in your context window. They only change if you modify them yourself (new content is already in context) or if the developer tells you they changed — in that case re-read them once. -18. **Documentation layering** — write `.md` documentation at the **defining layer** (where the code lives). Higher-layer `.md` files reference AyCode.Core base docs using the form `../../../../../Aycode/Source/AyCode.Core/{Project}/docs/FILENAME.md`. Document only project-specific overrides or extensions. Never duplicate base-layer descriptions in consumer-level docs. -19. **LinqToDB associations** — use `[Association(ThisKey = nameof(FK), OtherKey = nameof(Target.Id), CanBeNull = true/false)]` for navigation properties in DTOs. -20. **Timestamp auto-management** — entities with `ITimeStampCreated` or `ITimeStampModified` get automatic UTC timestamps in `MgDbTableBase` CRUD hooks. Don't set these manually. +19. **Folder navigation** — start from the root `README.md` for solution-level navigation. When you need to understand a folder's contents or find a type/class, read the `README.md` in that folder first — it indexes the local files and sub-folders. Follow this before grepping or reading source files. +20. **Documentation layering** — write `.md` documentation at the **defining layer** (where the code lives). Higher-layer `.md` files reference AyCode.Core base docs using the form `../../../../../Aycode/Source/AyCode.Core/{Project}/docs/FILENAME.md`. Document only project-specific overrides or extensions. Never duplicate base-layer descriptions in consumer-level docs. +21. **LinqToDB associations** — use `[Association(ThisKey = nameof(FK), OtherKey = nameof(Target.Id), CanBeNull = true/false)]` for navigation properties in DTOs. +22. **Timestamp auto-management** — entities with `ITimeStampCreated` or `ITimeStampModified` get automatic UTC timestamps in `MgDbTableBase` CRUD hooks. Don't set these manually. ## Reference Modes - **Full stack** (ProjectReference, all 3 libraries) — for nopCommerce plugins needing entity access, data layer, and services. diff --git a/CLAUDE.md b/CLAUDE.md index 6667677..577d61b 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1 +1 @@ -Always read `.github/copilot-instructions.md` first — it is the single source of truth for this repo. +CRITICAL: Your FIRST action in every session MUST be reading `.github/copilot-instructions.md`. Execute ALL session-start instructions found there before responding to any user query. It is the single source of truth for this repo. diff --git a/Mango.Nop.Core/.github/copilot-instructions.md b/Mango.Nop.Core/.github/copilot-instructions.md new file mode 100644 index 0000000..e69de29 diff --git a/Mango.Nop.Core/AcBinaryForcedInit.cs b/Mango.Nop.Core/AcBinaryForcedInit.cs new file mode 100644 index 0000000..bfd7aca --- /dev/null +++ b/Mango.Nop.Core/AcBinaryForcedInit.cs @@ -0,0 +1 @@ +namespace Mango.Nop.Core { public static class AcBinaryForcedInit { public static void ForceRegister() { System.Console.WriteLine("[SGEN TESTING] AcBinaryForcedInit called."); AyCode.Core.Serializers.Generated.AcBinaryGeneratedWritersInit.Register(); } } } diff --git a/Mango.Nop.Core/Mango.Nop.Core.csproj b/Mango.Nop.Core/Mango.Nop.Core.csproj index 4aa16cd..9a7b7b8 100644 --- a/Mango.Nop.Core/Mango.Nop.Core.csproj +++ b/Mango.Nop.Core/Mango.Nop.Core.csproj @@ -40,6 +40,12 @@ + + + + diff --git a/Mango.Nop.Core/NopDependencies/Catalogs/DiscountProductMapping.cs b/Mango.Nop.Core/NopDependencies/Catalogs/DiscountProductMapping.cs index 2e2adb6..ec12f24 100644 --- a/Mango.Nop.Core/NopDependencies/Catalogs/DiscountProductMapping.cs +++ b/Mango.Nop.Core/NopDependencies/Catalogs/DiscountProductMapping.cs @@ -5,7 +5,8 @@ namespace Nop.Core.Domain.Discounts; /// /// Represents a discount-product mapping class /// -[AcBinarySerializable(false, true, false, true)] +// SGen incompatible: DiscountMapping.Id is readonly (new int Id { get; }) — generated reader cannot set it (CS0200) +//[AcBinarySerializable(false, true, false, true)] public partial class DiscountProductMapping : DiscountMapping { /// diff --git a/Mango.Nop.Core/README.md b/Mango.Nop.Core/README.md index 96cfe30..77c1b55 100644 --- a/Mango.Nop.Core/README.md +++ b/Mango.Nop.Core/README.md @@ -89,4 +89,17 @@ Extends AyCode logging infrastructure — for base types see `AyCode.Core/docs/L - `linq2db` — data access, `[Association]` / `[Table]` attributes - `Microsoft.AspNetCore.Mvc.NewtonsoftJson` — JSON serialization - Binary serialization: `AcBinarySerializer` (see `AyCode.Core/docs/BINARY_FORMAT.md`). SignalR transport: `AcSignalR` (see `AyCode.Core/AyCode.Services/docs/SIGNALR.md`). +- `AyCode.Core.Serializers.SourceGenerator` (ProjectReference, `OutputItemType="Analyzer"`) — compile-time binary serializer. See [`AyCode.Core/docs/BINARY_SOURCE_GEN.md`](../../../../../../Aycode/Source/AyCode.Core/AyCode.Core/docs/BINARY_SOURCE_GEN.md) - AyCode DLL references: `AyCode.Interfaces`, `AyCode.Core`, `AyCode.Utils`, `AyCode.Entities` (types only, no runtime nopCommerce dependency) + +## AcBinary Source Generator (SGen) + +9 types annotated with `[AcBinarySerializable]`. For general SGen docs see [`AyCode.Core/docs/BINARY_SOURCE_GEN.md`](../../../../../../Aycode/Source/AyCode.Core/AyCode.Core/docs/BINARY_SOURCE_GEN.md). + +Requires `InternalsVisibleTo("Mango.Nop.Core")` in `AyCode.Core/Properties/AssemblyInfo.cs`. + +### Excluded types + +| Type | Reason | +|---|---| +| `DiscountProductMapping` | Base `DiscountMapping` hides `BaseEntity.Id` with readonly `new int Id { get; }` → CS0200. Uses compiled-expression fallback. |