Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion cmf-codereview/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -60,7 +60,9 @@ documented in [docs/commands.md](docs/commands.md) — start there for anything

## What it looks for

See [docs/rules.md](docs/rules.md) for the full list of the 17 rules, their severity, and suggested fixes.
See [docs/rules.md](docs/rules.md) for checks, severities, and suggested fixes.
[PR validation](docs/pr-validation.md) covers DEE UseReference declarations, deployment folder
versions, and the added/renamed file input required by PR-Changes.

## Configuration

Expand Down
15 changes: 11 additions & 4 deletions cmf-codereview/docs/commands.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ Runs the review engine over a repository and prints findings as a JSON array by
SARIF 2.1.0 log with `--report-format Sarif`. Optionally also saves the selected output to a file.

```bash
cmf-codereview scan --repository-root <path> [--scope DEEs|Orchestration|Both] [--roots <rel1> <rel2> ...] [--output <file>] [--report-format Json|Sarif] [--changed-files-list <file>] [--fail-on Critical|High|Medium] [--update-baseline]
cmf-codereview scan --repository-root <path> [--scope DEEs|Orchestration|Both] [--roots <rel1> <rel2> ...] [--output <file>] [--report-format Json|Sarif] [--changed-files-list <file>] [--added-files-list <file>] [--fail-on Critical|High|Medium] [--update-baseline]
```

| Option | Required | Default | Description |
Expand All @@ -25,6 +25,7 @@ cmf-codereview scan --repository-root <path> [--scope DEEs|Orchestration|Both] [
| `--output` | No | (none — stdout only) | Path to also write findings in the selected format to disk. Parent directories are created automatically. |
| `--report-format` | No | `Json` | `Json` (findings array) or `Sarif` (SARIF 2.1.0). Values are case-insensitive. The selected format applies to stdout and `--output`. |
| `--changed-files-list` | No | (none — reports on every scanned file) | Path to a text file listing changed files, one relative or absolute path per line (e.g. the output of `git diff --name-only`). When given, only findings on those files are returned — but the whole repository is still analyzed for cross-reference and loop-exposure context, so a finding on a changed file caused by an unchanged caller elsewhere is still correctly reported. Intended for CI gates that should only comment on files actually touched by a change. |
| `--added-files-list` | No | (deployment version check skipped) | Added/renamed PR destinations, one path per line. Enables package-version folder checks for new MasterData and Process Rules, including JSON. Use `git diff --name-only --diff-filter=AR --find-renames` with the same range as the changed-file list. |
| `--fail-on` | No | (none — always exits `0`) | `Critical`, `High`, or `Medium`. When given, the command exits `1` if any reported finding is at or above this severity. Omit it to keep `scan` purely informational. |
| `--update-baseline` | No | `false` | Write all current findings (ignoring any existing baseline) to `.codereview.baseline.json` at the repository root, accepting them as known debt — subsequent scans only report findings not in the baseline. Always exits `0` (ignores `--fail-on`). See [docs/configuration.md](configuration.md). |

Expand All @@ -40,7 +41,7 @@ metadata the CM Framework build/pack tooling reads:
sibling subfolders as Orchestration roots.
- Every manifest with `"packageType": "Data"` contributes a DEE root for each `contentToPack` entry
whose `"contentType": "DEE"`, resolved from that entry's own `source` glob (e.g. `"DEEs/*"` under
the manifest's directory) — so both the nested Micron-style `Cmf.<Project>.Data.Packages/DEEs` shape
the manifest's directory) — so both the nested `Cmf.<Project>.Data.Packages/DEEs` shape
and a flat `Cmf.<Project>.Data/DEEs` shape resolve correctly, and a repository with more than one
Data package (e.g. a Tests package bundling its own DEE fixtures) gets every one of them.

Expand Down Expand Up @@ -219,13 +220,19 @@ before rendering, so choosing SARIF does not change the findings or exit-code po
This functionality writes report files. Publishing results or creating PR annotations requires
a separately configured consumer; no pipeline generation or scaffolding is performed.

## PR deployment validation

See [pr-validation.md](pr-validation.md) for DEE reference rules, package-version folder checks,
and the required Bash PR-Changes task edits. Historical folder versions are checked only for
explicit added/renamed files; the reviewer does not infer additions from the changed-file list.

## Reviewing Process Rules

Process Rule diagnostics run automatically as part of the DEEs/Both scope. No guideline file
or additional validation flag is required. To focus on the Micron deployment rules:
or additional validation flag is required. To focus on a customization project's deployment rules:

```powershell
cmf-codereview scan --repository-root C:\workspaces\Micron --roots Cmf.Custom.Data/Cmf.Custom.Data.Packages/DEEs/ProcessRules --fail-on High --output findings.json
cmf-codereview scan --repository-root C:\workspaces\Project --roots Cmf.Custom.Data/Cmf.Custom.Data.Packages/DEEs/ProcessRules --fail-on High --output findings.json
cmf-codereview report --findings-path findings.json --report-mode Detailed --report-format Html --report-path process-rules.html
```

Expand Down
8 changes: 8 additions & 0 deletions cmf-codereview/docs/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -173,3 +173,11 @@ Those are the two supported kinds; a pattern that fits neither needs a code rule
`docs/rules.md` and `IReviewRule`) — or ask for the kind to be added.

Commit `.codereview.json` alongside the code so every teammate and CI run enforces the same rules.

## DEE references and deployment versions

Use the normal `rules` dictionary to configure `DeeInvalidReference`, `DeeMissingReference`,
`DeeReferenceUnresolved`, `DeploymentVersionMismatch`, and `DeploymentVersionUnresolved`.
For example, `"DeeReferenceUnresolved": { "enabled": false }` disables only unresolved-reference
review findings; it does not disable confirmed invalid or missing-reference findings.
See [pr-validation.md](pr-validation.md) for the metadata and added-file inputs needed for validation.
151 changes: 151 additions & 0 deletions cmf-codereview/docs/pr-validation.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,151 @@
# PR deployment and DEE reference validation

The reviewer validates literal `UseReference(assembly, namespace)` declarations in `DeeDevBase`
methods and checks new deployment content against its owning Data package version.

## DEE references

Restore the DEE project and its project references before the scan. The reviewer reads the owning
`.csproj`, `obj/project.assets.json`, reference HintPaths and referenced project sources. It uses
Roslyn to bind type/extension usages and reads the referenced CMF compiler's default namespace and
assembly arrays from metadata. No product assemblies or type initializers are executed.

- `DeeInvalidReference` (High): a declared namespace is known in the available metadata but is

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Testing showed as it being triggered as medium (attached file as reference)

cm-framework-scan-standard-20261110-155711.md

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This same finding is also a false positive. Sent in private message the scenario

unavailable from the combined default and explicitly declared assemblies.
- `DeeMissingReference` (High): a bound type/extension needs an import or assembly not supplied by
either a declaration or the compiler defaults. The finding points to the usage.
- `DeeReferenceUnresolved` (Medium): project/dependency metadata, compiler defaults, a type, an
assembly or non-literal arguments cannot be resolved. This is a validation limitation, not proof
that the reference is invalid. Unknown compiler initializer layouts are not executed or guessed.

An unused C# `using` alone does not require a declaration. The product compiler combines the assembly
arguments independently of the namespace arguments: a namespace may be supplied by any default or
explicitly declared assembly, including a declaration that appears later. Empty assembly arguments,
assembly-only references, fully qualified type usages, and the harmless `UseReference("", "")` no-op
are supported. Framework assemblies supplied by the runtime take precedence over older NuGet facade
assets when binding symbols. The check covers direct `DeeDevBase` classes and deployed
`DeeActionCode`/`DeeTestCondition` methods; it does not evaluate MSBuild conditions, generate code,
execute helpers or prove completeness for arbitrary dynamic/alias-based imports.

### Deferred Product parsing parity

The reviewer currently inspects complete method bodies rather than extracting only the regions
between deployed-code markers. Its C# syntax analysis also accepts declaration forms that Product's
regex extraction does not, such as whitespace between `UseReference` and `(`. Declarations outside
the deployed region can incorrectly satisfy a reference, and syntax differences can cause missed
findings or false positives. Marker extraction, declaration-syntax parity and host configuration
remain deferred follow-up work.

### Product compiler verification

The product implementation in `Platform/Host/Biz/Core/Common/DynamicExecutionEngine/Compiler.cs`
was inspected at Product commit `306f9c47cb0`. `GenerateFullActionCode` creates a new class from the
action and condition bodies. `GetUsings` combines default imports with the second arguments of
literal declarations; `GetReferences` independently combines default references with their first
arguments. `GetDefaultReferences` resolves framework DLLs from the .NET runtime directory.
`CompileActionCode` additionally applies host-configured `alsoInclude` reference rules.
`RuleEvaluatorAdapter.UseReference` itself has an empty body.

The reviewer does not reproduce a running host's configuration, keyword substitutions, arbitrary
reference paths or `alsoInclude` rules. It uses the dependencies restored in the reviewed workspace
and cannot prove that these match a deployed host. Core-only hosting and unsupported compiler
layouts also need separate validation; the current default import check targets MES projects.

An opt-in check exercises the **actual compiler binary restored by a DEE project**, rather than the
unit tests' compiler fixture:

```powershell
dotnet run --project tools/DeeCompilerCheck -c Release -- `
C:\workspaces\Project\Cmf.Custom.Data\Cmf.Custom.Data.Packages\DEEs\Cmf.Custom.Actions.csproj `
compiler-check.json
```

Restore that project first. This helper invokes `GenerateFullActionCode`, `GetReferences` and
`CompileSources`, resolving returned DLL names to the runtime and restored package files instead
of a deployed BusinessTier directory. It verifies missing assembly/import failures, the corrected
reference, independent inputs, and the empty no-op. It writes compilation results and exits nonzero
if an expectation fails. It creates artifacts under the system temporary directory and does not
execute any compiled DEE. This verifies generation and compilation; it does not exercise deployment,
execution, debug mode or host-specific `alsoInclude` configuration. Normal unit tests remain
independent of Product packages and do not execute product assemblies.

## Added deployment content

Pass **both** lists when scanning a PR:

```bash
cmf-codereview scan --repository-root . \
--changed-files-list changed-files.txt \
--added-files-list added-files.txt \
--output findings.json
```

Both files contain one repository-relative (or absolute in-repository) path per line. The added
list must describe added **or renamed** destinations, not all modified files. An empty list is valid.
Without the added list, deployment version validation is skipped; the reviewer warns when a PR
changed-file list was provided without it. It never guesses that historical edits are new files.

`DeploymentVersionMismatch` (High) compares the new file's folder version with the owning Data
package's `cmfpackage.json` version from the checked-out PR head. Content is classified from
`contentToPack`: `MasterData`, `EntityTypes`, `ProcessRulesPre`, and `ProcessRulesPost`. This supports
Before/After and EntityTypes/EntityTypesAttributes folders. Unversioned content such as Services
and untouched historical folders are excluded. An unreadable manifest or missing version produces
`DeploymentVersionUnresolved` (Medium).

For a package version `2.61.0`, a new `MasterData/2.60.0/data.json` or
`DEEs/ProcessRules/2.60.0/After/Rule.cs` is flagged with the expected destination under `2.61.0`.
The metadata finding is placed at line 1 of the new file. This repository-level check uses the
explicit added-file list, independently of the C# `--roots` selection, so MasterData-only PRs work.

All new diagnostics participate in rule enable/severity configuration, suppression/baselines where
applicable, `--fail-on`, and the existing JSON, HTML, Markdown and SARIF outputs.

## Changes to the Bash PR-Changes task

Apply these edits to the consuming project's Bash PR-Changes task
once `CmfCodeReviewVersion` selects a published version containing this feature. Keep findings in
JSON for the existing inline-comment consumer. Restore/build must precede reference validation;
the reviewer does not perform restores or acquire feed credentials.

**1. Add a path and generate the new-file list beside the existing changed-file list:**

```bash
addedFilesPath="$(Agent.TempDirectory)/codereview-added-files.txt"
git -c core.quotepath=off diff --name-only --diff-filter=AR --find-renames \
"origin/${targetBranch}...HEAD" > "$addedFilesPath"
```

Use the same merge-base range for both lists. Rename detection ensures that version-folder moves
are checked using their destination path. `--added-files-list` is a separate input so older release
files modified by the PR are not incorrectly treated as new content.

**2. Add to `scanArgs` before invoking npx:**

```bash
scanArgs+=(--added-files-list "$addedFilesPath")
```

**3. After the changed-hunk loop, add a line-1 anchor for added/renamed files:**

```bash
while IFS= read -r file || [[ -n "$file" ]]; do
if [[ -n "$file" && -s "$(Build.SourcesDirectory)/$file" ]]; then
printf '%s\t1\t1\n' "$file" >> "$changedLinesPath"
fi
done < "$addedFilesPath"
```

This keeps the TSV format of the supplied Bash task. A pure rename can have no changed-line hunks;
without this anchor, a folder-version finding can fail the gate yet be omitted by the PR comment
step's changed-line filter. Existing overlapping ranges for added files are harmless.

**4. Fix the findings counter's zero-result case under `set -euo pipefail`:**

```bash
findingsCount="$(grep -c '^[[:space:]]*"RelativePath"[[:space:]]*:' "$findingsPath" || true)"
echo "Findings count: $findingsCount"
```

The original `grep -o ... | wc -l` returns nonzero when no finding matches. That can fail an otherwise
successful clean scan before output variables are exposed. The revised counter tolerates zero
findings while preserving the reviewer's exit code and JSON output.
13 changes: 10 additions & 3 deletions cmf-codereview/docs/rules.md
Original file line number Diff line number Diff line change
Expand Up @@ -101,9 +101,10 @@ Guards recognize `HasProperty`, `TryGetEntityTypeProperty`, `ObjectExists`, `Try
negation/comparisons, applicable branches, and early returns. Checks on another property or target
do not protect an operation. Reachable local functions are analyzed, including guards at their
call sites; dormant local functions and callbacks are excluded. Raw metadata changes recognize
`GenerateSchema` and `GenerateEntityTypeDBSchema` after the update. The normal
`IMicronEntityTypeService.UpdateEntityTypeProperties` route does not require a duplicate schema
call. A guarded removal followed by recreation supports deliberate attribute-definition repairs;
`GenerateSchema` and `GenerateEntityTypeDBSchema` after the update. The supported
`UpdateEntityTypeProperties` helper pattern is treated as schema-aware and does not require a
duplicate schema call; verify that the project's helper performs regeneration. A guarded removal
followed by recreation supports deliberate attribute-definition repairs;
the removal still needs value cleanup.

Schema context is read once per scan from the same Data package's versioned MasterData. It tracks
Expand Down Expand Up @@ -195,3 +196,9 @@ carry the reverse link (`CalledByDee`). Findings flagged via `LoopInducedByCalle
same reason) carry a `LoopExposure` chain describing the call path back to the loop that causes the
repetition — rendered as prose by `CmLoopExposureFinder.FormatChain` and included in both the Standard and
Detailed reports.

## DEE references and deployment versions

The reference checks and PR deployment-folder diagnostics are described in
[pr-validation.md](pr-validation.md), including their default severities, required metadata,
historical-folder exclusions, and CLI/pipeline inputs.
Loading
Loading