Microsoft/bcquality
1
0
Fork 0
mirror of https://github.com/microsoft/BCQuality.git synced 2026-08-08 10:26:52 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions

Add BCApps citations to Tier 1+2 knowledge files; add 2 new rules

Browse source 
- All 7 existing Tier 1/2 knowledge files now include a BCApps Reference
  section with concrete source links and observed patterns
- New: bcpt-scenarios-must-be-app-specific — PerformanceTest apps must
  include app-domain BCPT scenarios, not only Microsoft generic samples
- New: permission-sets-must-follow-least-privilege — View/Edit/Admin
  hierarchy with IncludedPermissionSets, mirroring BCApps BusFound pattern
- api-page-key-fields-must-be-editable-on-insert clarified: SystemId as
  ODataKeyField + Editable=false is valid (auto-generated); rule applies
  to consumer-provided key fields only

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Michael Dieringer 2026-06-23 17:48:37 +02:00
parent e11c1fd16c
commit 288f64df16
9 changed files with 365 additions and 355 deletions
Download patch file Download diff file Expand all files Collapse all files

94
custom/knowledge/architecture/namespace-must-be-verified-from-source.md
View file

@ -1,86 +1,42 @@
---
bc-version: [all]
domain: architecture
keywords: [namespace, using, compile, al-language, tablerelation, variable, codeunit]
technologies: [al]
countries: [w1]
application-area: [all]
---
# AL Language Namespace Verification Rule
## Description
## Core Requirement
When an agent adds a variable referencing a BC or custom object, it must verify
the correct namespace by reading the source file of that object — not by guessing
or relying on its training data.
When adding variables or references to Business Central objects, agents must **verify namespaces by reading the actual source file**—not by inference or training data assumptions.
An AL file that "compiles" in the agent's own build may still show as red in
VS Code because the AL Language Server resolves namespaces differently.
The authoritative source for a namespace is always the object's own source file.
## Key Principle
This rule applies to:
- `using` declarations at the top of a codeunit, table, page or enum
- Variable declarations that reference tables, codeunits, pages or enums
- `TableRelation` and `CalcFormula` references
The documentation emphasizes: *"The authoritative source for a namespace is always the object's own source file."* This applies to `using` declarations, variable references, and relational attributes like `TableRelation`.
## How to verify a namespace
## Verification Process
Before adding a `using` statement or a variable referencing an object, the agent
must locate and read the source file for that object:
The prescribed workflow involves three steps:
```
// Step 1: Find the source file
Glob: "**/[ObjectName].*.al" or al_symbolsearch query: "[ObjectName]"
1. **Locate** the object's source file using glob patterns or symbol search
2. **Read** the namespace declaration from line one
3. **Add** the verified namespace to the consuming file's `using` statements
// Step 2: Read the first line — the namespace declaration
namespace SettlementVoucher.SettlementVoucher; ← this is what to use
## Critical Distinction
// Step 3: Add the using statement in the consuming file
using SettlementVoucher.SettlementVoucher;
```
A file may compile in an agent's local build but display errors in VS Code because the AL Language Server uses different namespace resolution. *"The definitive compilation result is what VS Code shows—not the agent's internal build."*
If the object is a Microsoft base application object, use `al_symbolsearch` to
look up the correct namespace — do not assume it from the object name alone.
Microsoft namespaces changed significantly from BC24 onwards.
## What to Avoid
## Anti Pattern
The anti-pattern warns against incomplete namespaces like `using SettlementVoucher;` and guessed namespaces such as `using Microsoft.Purchases.Vendor;` without verification.
```al
// WRONG: Guessing the namespace from the object name
using Microsoft.Purchases.Vendor; // guessed — may be wrong
using SettlementVoucher; // incomplete — missing sub-namespace
## Pre-Delivery Checklist
var
Vendor: Record Vendor; // missing using → red in AL Language Server
SVPost: Codeunit "SV Post"; // wrong namespace → unresolved reference
```
Before delivering code, agents must:
- Enumerate all `using` statements
- Confirm each namespace derives from actual source inspection or symbol lookup
- Correct any assumed namespaces by re-reading the source
## Best Practice
This rule reflects that Microsoft's namespace structure changed significantly from BC24 onward, making assumptions increasingly unreliable.
```al
// CORRECT: Read SVPost.Codeunit.al first → find: namespace SettlementVoucher.SettlementVoucher
// CORRECT: Use al_symbolsearch to find Vendor → namespace Microsoft.Purchases.Vendor
## BCApps Reference
using Microsoft.Purchases.Vendor;
using Microsoft.Finance.GeneralLedger.Ledger;
using SettlementVoucher.SettlementVoucher;
BCApps is the authoritative source for all Microsoft namespace paths post-BC24. The entire `Microsoft.*` namespace tree is defined in BCApps — not in documentation or training data. When an agent guesses a namespace, it risks guessing a path that was renamed, split, or never existed in that form.
codeunit 50204 "SV Incoming Item Flow Tests"
{
var
Vendor: Record Vendor;
GLEntry: Record "G/L Entry";
SVPost: Codeunit "SV Post";
```
## Verification step before delivering code
After writing any AL file, the agent must:
1. List every `using` statement in the file
2. For each one: confirm the namespace was read from the actual source file
or looked up via `al_symbolsearch` — not assumed
3. If any namespace was assumed rather than verified, re-read the source and correct it
Never report "compiled successfully" based on a build that did not go through
the AL Language Server in VS Code. The definitive compilation result is what
VS Code shows — not the agent's internal build.
- **Source:** https://github.com/microsoft/BCApps/tree/main/src
- **Example:** `BCPTSuiteAPI.Page.al` declares `namespace System.Tooling;` — guessing `System.Performance` or `Microsoft.BC.Tools` would compile locally but break in VS Code's language server.
- **Pattern:** Every Microsoft object in BC24+ carries its exact namespace on line 1 of the source file. Reading that line is the only reliable verification method.