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

Add [all] sentinel to bc-version; apply to version-agnostic knowledge

Browse source 
Most of the corpus — FindSet/SetLoadFields/CalcFields patterns, permission
sets, SingleInstance codeunits, DataClassification, IsolatedStorage,
transaction scope, SecretText — describes BC platform behaviour that is
identical across supported versions. The seed [26..28] range on every
file implied a version-specificity the content does not actually have,
and there was no way to express "applies to every version" in the
schema the way [w1] and [all] already do for countries and
application-area.

Extend the v1 schema with a universal sentinel for bc-version, parallel
to the sentinels already defined for the other dimensions:

  bc-version: [all]         # applies to every BC version

[all] is mutually exclusive with explicit versions. Range shorthand
([26..28]) and explicit lists ([26, 27, 28]) continue to work for files
genuinely tied to a version-gated API or deprecation.

Update read.md (field definition, matching semantics, partial-context
rule), write.md (default to [all], use ranges only with a concrete
reason), README.md (frontmatter example), and the CI validator. All
forty existing knowledge files and the three action skills convert to
[all]; none of the current content is version-gated. Validator passes.
This commit is contained in:
Jesper Schulz-Wedde 2026-04-23 16:00:03 +02:00
parent 23184480d0
commit 9a4198eb28
52 changed files with 68 additions and 58 deletions
Download patch file Download diff file Expand all files Collapse all files

15
.github/scripts/validate_frontmatter.py vendored
View file

@ -145,10 +145,19 @@ def is_non_empty_list_of_str(value: Any) -> bool:
return isinstance(value, list) and len(value) > 0 and all(isinstance(v, str) and v for v in value)
def expand_bc_version(value: Any) -> tuple[list[int] | None, str | None]:
"""Return (expanded-list, error-message). One of the two is None."""
def expand_bc_version(value: Any) -> tuple[list[int] | str | None, str | None]:
"""Return (expanded, error-message). One of the two is None.
For the universal sentinel ["all"], `expanded` is the string "all".
Otherwise it is the expanded list of version integers.
"""
if not isinstance(value, list) or not value:
return None, "must be a non-empty list"
# Case 0: universal sentinel
if len(value) == 1 and value[0] == "all":
return "all", None
if "all" in value:
return None, "'all' is mutually exclusive with explicit versions"
# Case 1: all integers
if all(isinstance(v, int) and not isinstance(v, bool) for v in value):
if any(v <= 0 for v in value):
@ -162,7 +171,7 @@ def expand_bc_version(value: Any) -> tuple[list[int] | None, str | None]:
if start > end:
return None, f"range '{value[0]}' is not ascending"
return list(range(start, end + 1)), None
return None, "must be a list of integers or a single-element range shorthand like [26..28]"
return None, "must be [all], a list of integers, or a single-element range shorthand like [26..28]"
def headings_in_order(body: str) -> list[tuple[str, int]]:

2
README.md
View file

@ -72,7 +72,7 @@ Every knowledge file is a markdown file with mandatory YAML frontmatter. Files t
```yaml
---
bc-version: [26..28] # BC versions this applies to
bc-version: [all] # or [26..28] for version-gated guidance
domain: performance # security | performance | ux | telemetry | ...
keywords: [query, filtering, partial] # free-text tags for retrieval
technologies: [al] # al | javascript | powershell | ...

2
community/knowledge/performance/avoid-growing-globals-in-singleinstance-subscribers.md
View file

@ -1,5 +1,5 @@
---
bc-version: [26..28]
bc-version: [all]
domain: performance
keywords: [singleinstance, subscriber, event, memory, session]
technologies: [al]

2
community/knowledge/performance/call-setloadfields-before-filters.md
View file

@ -1,5 +1,5 @@
---
bc-version: [26..28]
bc-version: [all]
domain: performance
keywords: [setloadfields, placement, filter, setrange, query-plan]
technologies: [al]

2
community/knowledge/performance/choose-maintainsiftindex-by-read-write-ratio.md
View file

@ -1,5 +1,5 @@
---
bc-version: [26..28]
bc-version: [all]
domain: performance
keywords: [maintainsiftindex, sift, calcsums, flowfield, write-cost]
technologies: [al]

2
community/knowledge/performance/load-common-fields-before-branching-on-case.md
View file

@ -1,5 +1,5 @@
---
bc-version: [26..28]
bc-version: [all]
domain: performance
keywords: [setloadfields, case, conditional, branch, field-loading]
technologies: [al]

2
community/knowledge/performance/load-only-primary-key-fields-for-reference-work.md
View file

@ -1,5 +1,5 @@
---
bc-version: [26..28]
bc-version: [all]
domain: performance
keywords: [setloadfields, primary-key, reference, existence-check, memory]
technologies: [al]

2
community/knowledge/performance/omit-filter-only-fields-from-setloadfields.md
View file

@ -1,5 +1,5 @@
---
bc-version: [26..28]
bc-version: [all]
domain: performance
keywords: [setloadfields, filter, field-exclusion, index]
technologies: [al]

2
community/knowledge/performance/order-case-branches-by-frequency.md
View file

@ -1,5 +1,5 @@
---
bc-version: [26..28]
bc-version: [all]
domain: performance
keywords: [case, branch, frequency, control-flow, hot-path]
technologies: [al]

2
community/knowledge/performance/use-deleteall-for-filtered-bulk-deletion.md
View file

@ -1,5 +1,5 @@
---
bc-version: [26..28]
bc-version: [all]
domain: performance
keywords: [deleteall, bulk-delete, sql, ondelete, trigger-bypass]
technologies: [al]

2
community/knowledge/security/classify-every-field-with-dataclassification.md
View file

@ -1,5 +1,5 @@
---
bc-version: [26..28]
bc-version: [all]
domain: security
keywords: [dataclassification, gdpr, privacy, euii, compliance]
technologies: [al]

2
community/knowledge/security/compose-permission-sets-with-included-sets.md
View file

@ -1,5 +1,5 @@
---
bc-version: [26..28]
bc-version: [all]
domain: security
keywords: [permissionset, includedpermissionsets, assignable, composition, role]
technologies: [al]

2
community/knowledge/security/do-not-grant-rights-beyond-a-users-entitlement.md
View file

@ -1,5 +1,5 @@
---
bc-version: [26..28]
bc-version: [all]
domain: security
keywords: [entitlement, permissionset, license, clipping, sandbox-drift]
technologies: [al]

2
community/knowledge/security/guard-bulk-operations-with-istemporary.md
View file

@ -1,5 +1,5 @@
---
bc-version: [26..28]
bc-version: [all]
domain: security
keywords: [istemporary, deleteall, modifyall, safeguard, precondition]
technologies: [al]

2
community/knowledge/security/prefer-oauth2-over-api-keys-for-external-http-calls.md
View file

@ -1,5 +1,5 @@
---
bc-version: [26..28]
bc-version: [all]
domain: security
keywords: [oauth2, api-key, authentication, httpclient, token-refresh]
technologies: [al]

2
community/knowledge/security/protect-sensitive-data-in-temporary-tables.md
View file

@ -1,5 +1,5 @@
---
bc-version: [26..28]
bc-version: [all]
domain: security
keywords: [temporary-table, data-protection, permission, cleanup]
technologies: [al]

2
microsoft/knowledge/performance/add-sift-keys-for-flowfields.md
View file

@ -1,5 +1,5 @@
---
bc-version: [26..28]
bc-version: [all]
domain: performance
keywords: [sift, sumindexfields, flowfield, key, aa0232]
technologies: [al]

2
microsoft/knowledge/performance/avoid-calcfields-in-loops.md
View file

@ -1,5 +1,5 @@
---
bc-version: [26..28]
bc-version: [all]
domain: performance
keywords: [calcfields, flowfield, loop, n-plus-one]
technologies: [al]

2
microsoft/knowledge/performance/avoid-commit-inside-loops.md
View file

@ -1,5 +1,5 @@
---
bc-version: [26..28]
bc-version: [all]
domain: performance
keywords: [commit, loop, transaction, lock]
technologies: [al]

2
microsoft/knowledge/performance/avoid-findfirst-with-next.md
View file

@ -1,5 +1,5 @@
---
bc-version: [26..28]
bc-version: [all]
domain: performance
keywords: [findfirst, findlast, get, next, aa0233]
technologies: [al]

2
microsoft/knowledge/performance/avoid-user-interaction-in-transactions.md
View file

@ -1,5 +1,5 @@
---
bc-version: [26..28]
bc-version: [all]
domain: performance
keywords: [confirm, strmenu, message, transaction, dialog]
technologies: [al]

2
microsoft/knowledge/performance/filter-before-find.md
View file

@ -1,5 +1,5 @@
---
bc-version: [26..28]
bc-version: [all]
domain: performance
keywords: [filter, setrange, setfilter, findset, scan]
technologies: [al]

2
microsoft/knowledge/performance/keep-event-subscribers-lightweight.md
View file

@ -1,5 +1,5 @@
---
bc-version: [26..28]
bc-version: [all]
domain: performance
keywords: [event, subscriber, publisher, extension]
technologies: [al]

2
microsoft/knowledge/performance/only-fetch-records-you-use.md
View file

@ -1,5 +1,5 @@
---
bc-version: [26..28]
bc-version: [all]
domain: performance
keywords: [findset, get, aa0175, wasted-fetch, read]
technologies: [al]

2
microsoft/knowledge/performance/prefer-direct-record-over-recordref.md
View file

@ -1,5 +1,5 @@
---
bc-version: [26..28]
bc-version: [all]
domain: performance
keywords: [recordref, fieldref, dynamic, reflection]
technologies: [al]

2
microsoft/knowledge/performance/prefer-get-for-primary-key-lookups.md
View file

@ -1,5 +1,5 @@
---
bc-version: [26..28]
bc-version: [all]
domain: performance
keywords: [get, findfirst, primary-key, lookup]
technologies: [al]

2
microsoft/knowledge/performance/set-current-key-to-match-filters.md
View file

@ -1,5 +1,5 @@
---
bc-version: [26..28]
bc-version: [all]
domain: performance
keywords: [setcurrentkey, key, index, sort, filter]
technologies: [al]

2
microsoft/knowledge/performance/use-addloadfields-in-report-layouts.md
View file

@ -1,5 +1,5 @@
---
bc-version: [26..28]
bc-version: [all]
domain: performance
keywords: [report, addloadfields, ondatapreitem, layout, partial-record]
technologies: [al]

2
microsoft/knowledge/performance/use-calcsums-for-flowfield-totals.md
View file

@ -1,5 +1,5 @@
---
bc-version: [26..28]
bc-version: [all]
domain: performance
keywords: [calcsums, sift, sum, aggregate, totals]
technologies: [al]

2
microsoft/knowledge/performance/use-findset-readonly-by-default.md
View file

@ -1,5 +1,5 @@
---
bc-version: [26..28]
bc-version: [all]
domain: performance
keywords: [findset, lock, locktable, readonly, update]
technologies: [al]

2
microsoft/knowledge/performance/use-findset-with-next.md
View file

@ -1,5 +1,5 @@
---
bc-version: [26..28]
bc-version: [all]
domain: performance
keywords: [findset, next, repeat, iteration, aa0181]
technologies: [al]

2
microsoft/knowledge/performance/use-insert-false-when-skipping-triggers.md
View file

@ -1,5 +1,5 @@
---
bc-version: [26..28]
bc-version: [all]
domain: performance
keywords: [insert, modify, delete, triggers, parameters]
technologies: [al]

2
microsoft/knowledge/performance/use-isempty-for-existence-checks.md
View file

@ -1,5 +1,5 @@
---
bc-version: [26..28]
bc-version: [all]
domain: performance
keywords: [isempty, count, findfirst, existence]
technologies: [al]

2
microsoft/knowledge/performance/use-setloadfields-for-partial-records.md
View file

@ -1,5 +1,5 @@
---
bc-version: [26..28]
bc-version: [all]
domain: performance
keywords: [setloadfields, partial-record, blob, bandwidth]
technologies: [al]

2
microsoft/knowledge/performance/use-single-instance-codeunits-for-caching.md
View file

@ -1,5 +1,5 @@
---
bc-version: [26..28]
bc-version: [all]
domain: performance
keywords: [singleinstance, cache, codeunit, session]
technologies: [al]

2
microsoft/knowledge/performance/use-temporary-tables-for-intermediate-data.md
View file

@ -1,5 +1,5 @@
---
bc-version: [26..28]
bc-version: [all]
domain: performance
keywords: [temporary-table, in-memory, intermediate, working-set]
technologies: [al]

2
microsoft/knowledge/security/compose-secrets-with-secretstrsubstno.md
View file

@ -1,5 +1,5 @@
---
bc-version: [26..28]
bc-version: [all]
domain: security
keywords: [secretstrsubstno, secrettext, composition]
technologies: [al]

2
microsoft/knowledge/security/do-not-expose-sensitive-data-in-event-publishers.md
View file

@ -1,5 +1,5 @@
---
bc-version: [26..28]
bc-version: [all]
domain: security
keywords: [event, publisher, extensibility, var-parameter]
technologies: [al]

2
microsoft/knowledge/security/follow-least-privilege-in-permission-sets.md
View file

@ -1,5 +1,5 @@
---
bc-version: [26..28]
bc-version: [all]
domain: security
keywords: [permissionset, least-privilege, rimd, tabledata]
technologies: [al]

2
microsoft/knowledge/security/never-hardcode-secrets-in-al.md
View file

@ -1,5 +1,5 @@
---
bc-version: [26..28]
bc-version: [all]
domain: security
keywords: [secrets, credentials, hardcoded, label, apikey]
technologies: [al]

2
microsoft/knowledge/security/prefer-azure-key-vault-for-production-secrets.md
View file

@ -1,5 +1,5 @@
---
bc-version: [26..28]
bc-version: [all]
domain: security
keywords: [keyvault, azure, secrets, rotation, audit]
technologies: [al]

2
microsoft/knowledge/security/use-indirect-permissions-for-elevated-access.md
View file

@ -1,5 +1,5 @@
---
bc-version: [26..28]
bc-version: [all]
domain: security
keywords: [indirect-permission, elevation, permissionset]
technologies: [al]

2
microsoft/knowledge/security/use-inherent-permissions-to-grant-minimal-access.md
View file

@ -1,5 +1,5 @@
---
bc-version: [26..28]
bc-version: [all]
domain: security
keywords: [inherentpermissions, attribute, least-privilege]
technologies: [al]

2
microsoft/knowledge/security/use-isolated-storage-for-module-and-company-secrets.md
View file

@ -1,5 +1,5 @@
---
bc-version: [26..28]
bc-version: [all]
domain: security
keywords: [isolatedstorage, encryption, datascope, secrets]
technologies: [al]

2
microsoft/knowledge/security/use-nondebuggable-when-parsing-secrets.md
View file

@ -1,5 +1,5 @@
---
bc-version: [26..28]
bc-version: [all]
domain: security
keywords: [nondebuggable, secrettext, attribute, parse]
technologies: [al]

2
microsoft/knowledge/security/use-secrettext-for-credentials.md
View file

@ -1,5 +1,5 @@
---
bc-version: [26..28]
bc-version: [all]
domain: security
keywords: [secrettext, credentials, debugger, type]
technologies: [al]

2
microsoft/knowledge/security/use-secrettext-with-httpclient.md
View file

@ -1,5 +1,5 @@
---
bc-version: [26..28]
bc-version: [all]
domain: security
keywords: [httpclient, secrettext, headers, uri]
technologies: [al]

2
microsoft/skills/al-code-review.md
View file

@ -6,7 +6,7 @@ title: AL code review
description: Reviews AL source changes by composing the AL review leaf skills (performance, security, ...).
inputs: [pr-diff, file-path]
outputs: [findings-report]
bc-version: [26..28]
bc-version: [all]
technologies: [al]
countries: [w1]
application-area: [all]

2
microsoft/skills/al-performance-review.md
View file

@ -6,7 +6,7 @@ title: AL performance review
description: Reviews AL source changes against performance guidance from BCQuality.
inputs: [pr-diff, file-path]
outputs: [findings-report]
bc-version: [26..28]
bc-version: [all]
technologies: [al]
countries: [w1]
application-area: [all]

2
microsoft/skills/al-security-review.md
View file

@ -6,7 +6,7 @@ title: AL security review
description: Reviews AL source changes against security guidance from BCQuality.
inputs: [pr-diff, file-path]
outputs: [findings-report]
bc-version: [26..28]
bc-version: [all]
technologies: [al]
countries: [w1]
application-area: [all]

11
skills/read.md
View file

@ -26,7 +26,7 @@ A file that violates any of these rules is invalid and MUST be skipped by consum
```yaml
---
bc-version: [26, 27, 28] # or the range shorthand [26..28]
bc-version: [all] # or [26, 27, 28] or the range shorthand [26..28]
domain: performance
keywords: [query, filtering, partial]
technologies: [al]
@ -39,12 +39,13 @@ All six fields are required. Missing or empty fields invalidate the file.
### Fields
**`bc-version`** — Array. The Business Central major versions this file applies to. Two forms are accepted:
**`bc-version`** — Array. The Business Central major versions this file applies to. Three forms are accepted:
- Universal sentinel: `[all]` means the guidance applies to every BC version and matches any target.
- Explicit list: `[26, 27, 28]`.
- Range shorthand: `[26..28]` means every integer from 26 through 28 inclusive.
Consumers MUST expand ranges to the full set before comparison.
`[all]` is mutually exclusive with explicit versions; do not combine. Consumers MUST expand ranges to the full set before comparison.
**`domain`** — String. A single domain tag that places the file within a broader area of concern. Standard values include `performance`, `security`, `ux`, `telemetry`, `testing`, `api`, `pipelines`, `finance`, `supply-chain`, `manufacturing`, `jobs`. New domains may be introduced by contributors; no closed enumeration is enforced at the schema level. Consumers MUST treat unknown domains as valid.
@ -93,7 +94,7 @@ Conflict detection is the consumer's responsibility; BCQuality does not enforce
When a consumer filters or matches files against a task context, these rules apply:
- **`bc-version`** — the target BC version MUST be an element of the file's expanded `bc-version` set. Range shorthand (`[26..28]`) MUST be expanded before comparison.
- **`bc-version`** — the file matches if its set is `[all]`, or if the target BC version is an element of the file's expanded `bc-version` set. Range shorthand (`[26..28]`) MUST be expanded before comparison.
- **`technologies`** — non-empty intersection between the task's technologies and the file's technologies. There is no sentinel for this field.
- **`countries`** — the file matches if its set contains `w1`, or if there is a non-empty intersection with the task's countries.
- **`application-area`** — the file matches if its set contains `all`, or if there is a non-empty intersection with the task's application areas.
@ -104,7 +105,7 @@ A file is **applicable** to a task when all four rules match. Applicability is a
A task context may omit one or more dimensions (for example, a skill invoked against a raw file path with no known target BC version). For any omitted dimension:
- If the file's value for that dimension is a universal sentinel (`w1` for countries, `all` for application-area), the rule matches.
- If the file's value for that dimension is a universal sentinel (`all` for bc-version, `w1` for countries, `all` for application-area), the rule matches.
- Otherwise the rule is treated as **unknown**, not as a match and not as a failure.
A file with any `unknown` rule is **conditionally applicable**. A consumer MAY include conditionally applicable files in the worklist; if it does, every finding derived from such a file MUST have `confidence` no higher than `medium` and MUST record the unknown dimensions in the finding's `message`. A consumer MAY be configured to exclude conditionally applicable files entirely.

2
skills/write.md
View file

@ -43,7 +43,7 @@ Knowledge files do not contain code. Samples live as **sibling files** next to t
## Choosing frontmatter values
**`bc-version`.** Claim only the versions you have evidence for. If the guidance is known to apply from BC 24 onward and you have tested against 26–28, write `[26..28]`, not `[24..28]`. Under-claim; a future contributor can widen the range.
**`bc-version`.** Default to `[all]` when the guidance is universal — a BC language pattern, a property on a long-standing platform type, a CodeCop rule, or a platform behaviour that has not changed across versions. Use an explicit list or range (`[26, 27, 28]`, `[26..28]`) only when the guidance is tied to a version-gated API, a deprecation, or platform behaviour that genuinely differs across versions. Most knowledge files should be `[all]`; reach for a range only with a concrete reason.
**`domain`.** Pick one. If two fit, the file is probably two concerns. If no existing domain fits, introduce a new one — domains are open. Prefer existing domains when they are a reasonable fit, to keep retrieval predictable.