Skip to content

docs(aem-cloud-service): consistent report rendering for the 5 guided code-assessment patterns#217

Open
Himanich wants to merge 3 commits into
mainfrom
feat/code-assessment-guided-candidates-table
Open

docs(aem-cloud-service): consistent report rendering for the 5 guided code-assessment patterns#217
Himanich wants to merge 3 commits into
mainfrom
feat/code-assessment-guided-candidates-table

Conversation

@Himanich

@Himanich Himanich commented Jun 25, 2026

Copy link
Copy Markdown
Collaborator

Description

Each of the 5 guided patterns gained two sections (mirroring unbounded-query / outbound-call-timeouts):

Discovery — the analyze.sh --pattern command + match criteria that mirror the merged detector logic exactly, and the emitted snippet. Drives the Finding column.

Resolution contract — labeled guided, with a per-site disposition table. Drives the Planned action column.

Related Issue

Motivation and Context

The five architectural patterns under code-assessment/ (scheduler, resource-change-listener, replication, event-migration, asset-manager) lacked the two sections that drive the code-assessment report table

How Has This Been Tested?

  • bash plugins/aem/cloud-service/test/code-assessment/run-tests.sh → 103/103 pass.
  • Verified each pattern's Discovery match criteria against the live analyzer output (analyze.sh --pattern per fixture).
  • Migration-skill consistency checked: migration reads each guide's SKILL.md directly and skips analyzer discovery on handoff, so these sections don't affect the BPA-driven path; routing already matches the detector taxonomy.

Screenshots (if appropriate):

Types of changes

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to change)

Checklist:

  • I have signed the Adobe Open Source CLA.
  • My code follows the code style of this project.
  • My change requires a change to the documentation.
  • I have updated the documentation accordingly.
  • I have read the CONTRIBUTING document.
  • I have added tests to cover my changes.
  • All new and existing tests passed.

Himani Chauhan and others added 3 commits June 25, 2026 23:29
@claude
docs(aem-cloud-service): add Discovery + Resolution contract to the 5…
2d70f97 
… guided patterns

The architectural patterns moved from best-practices (scheduler,
resource-change-listener, replication, event-migration, asset-manager) lacked the
two sections that feed the code-assessment report table — so a discover+report run
rendered them as bare file lists while the mechanical patterns
(outbound-call-timeouts, unbounded-query) showed File | Finding | Planned action.

Each of the 5 now mirrors the mechanical-pattern skeleton:

- ## Discovery — analyze.sh --pattern <slug> command + match criteria that mirror
  the merged detector logic exactly (Job/RCL/EventHandler/EventListener implements,
  OSGi-property scheduler, Replicator import → one finding per file, AssetManager
  calls → one finding per call site) and the emitted snippet. Drives the Finding column.
- ## Resolution contract — labeled `guided`, with a disposition table mapping each
  site shape to `migrate (guided) → <step-set>` or a skip reason
  (already-compliant, test-scope, workflow-owned, wrong-pattern). Drives the
  Planned action column.

Cross-pattern nuances captured inline: replication is analyzer-only (no BPA
subtype); event-migration routes resource-topic handlers to resource-change-listener
as skipped: wrong-pattern; RCL notes JCR EventListener is detected under
event-migration per the BPA taxonomy.

runbook.md:
- Candidates: same columns for every pattern (mechanical and guided); Planned
  action vocabulary keyed off the catalog `fix` field (mechanical → apply/skipped;
  guided → migrate (guided)); never collapse a guided pattern to a file list.
- Step 2: acknowledge guided patterns may carry steps inline (no recipe.md/path-*.md)
  and read the Discovery + Resolution contract sections.

No detector/code changes. Test suite 113/113.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@claude
fix(aem-cloud-service): Planned action from each pattern's Resolution…
227b023 
… contract; rename to apply (guided)

Two fixes to the guided-pattern report rendering:

1. Regression: the runbook Candidates note keyed Planned action off the catalog
   `fix` field (`fix: guided` → one blanket label). That overrode unbounded-query
   — itself `fix: guided` but with a per-site triage — flattening its
   `apply → 1` / `skipped — needs-pagination` / `skipped — test-scope` rows into a
   uniform label, and (worse) turning test-scope skips into apply candidates.
   Planned action now comes from each pattern's own Resolution contract; the
   `fix` field no longer dictates a blanket action.

2. Rename `migrate (guided)` → `apply (guided)` across the runbook note and all
   five architectural Resolution contracts. Keeps one action vocabulary
   (`apply` / `apply → N` / `apply (guided)` / `skipped — <reason>`), ties to the
   `apply <slug>` command users type, and avoids overloading "migrate" (the name
   of the sibling skill); fits resource-change-listener (review/refactor) too.

No detector/code changes. Test suite 103/103.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@claude
docs(aem-cloud-service): disambiguate EventListener/EventHandler/RCL …
28b99dc 
…routing in Resolution contracts

Detection is unambiguous (each interface maps to exactly one detector), but the
fix-routing across the three observation patterns relied on prose to disambiguate.
Make the Resolution-contract tables self-disambiguating:

- event-migration: reorder rows so "observes repository content" (JCR EventListener
  on content, or EventHandler on a resource topic) comes first and routes to
  resource-change-listener; add an explicit "first match wins" note; mark the E0
  path as the rare residual fall-through ("genuinely cannot be modeled as a
  ResourceChangeListener"), not a competing option.
- resource-change-listener: annotate the R0 row as redirect-only — it arrives via
  event-migration redirect or migration handoff; this pattern's own detector flags
  only the modern API.
- Both: note that a class implementing both ResourceChangeListener and an event
  interface is flagged by both patterns (rare).

Doc-only; no detector/code changes. Test suite 103/103.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@Himanich Himanich requested a review from mandeep294 June 25, 2026 18:50
@github-actions

github-actions Bot commented Jun 25, 2026

Copy link
Copy Markdown

Tessl Skill Lint

⚠️ edge-delivery-services — 1 warning(s) 
⚠ tile.json is deprecated. Migrate to .tessl-plugin/plugin.json to publish a plugin-shape package. Run `tessl plugin migrate` to convert automatically. tile.json support will be removed in a future release.

✔ Plugin adobe/aem-edge-delivery-services@0.1.0 is valid
⚠️ stardust — 1 warning(s) 
⚠ tile.json is deprecated. Migrate to .tessl-plugin/plugin.json to publish a plugin-shape package. Run `tessl plugin migrate` to convert automatically. tile.json support will be removed in a future release.

✔ Plugin adobe/stardust@0.12.0 is valid

✅ All 2 tile(s) lint passed with 2 warning(s) total.

Updated by tessl-lint for commit 47b2d51.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@rombert rombert rombert approved these changes
@abhishekgarg18 abhishekgarg18 Awaiting requested review from abhishekgarg18 abhishekgarg18 is a code owner
@pkumargaddam pkumargaddam Awaiting requested review from pkumargaddam pkumargaddam is a code owner
@akankshajain18 akankshajain18 Awaiting requested review from akankshajain18 akankshajain18 is a code owner
@mandeep294 mandeep294 Awaiting requested review from mandeep294

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@Himanich @rombert