docs(ui): trim the Azure onboarding comments to what they explain

- Drop comments that restate the code or the test title they sit under
- Keep each rationale where it belongs instead of repeating it per call site
- Reattach the AWS hierarchy fixture doc to the fixture it documents

Author: pfe-nazaries

ui/__tests__/msw/handlers/organizations.fixtures.ts

@@ -143,10 +143,7 @@ export interface FixtureDiscovery {
   result: unknown;
   /** Machine error code — never user copy. */
   error: string | null;
-  /**
-   * Sanitized human message the server sends alongside the code. Optional: it
-   * only exists for codes the API decided to explain itself.
-   */
+  /** Sanitized human message the server sends alongside the code, when it has one. */
   errorMessage?: string | null;
 }
 
@@ -478,10 +475,9 @@ export const AZURE_SUBSCRIPTION_DISABLED =
   "66666666-6666-4666-8666-666666666666";
 
 /**
- * Blocked reasons Azure discovery reports. It reuses GCP's `*_conflict`
- * vocabulary for the three linkage/type conflicts and adds one of its own:
- * `subscription_not_enabled`, raised whenever `state != "Enabled"`, which is the
- * only reason that can block a subscription with no provider involved at all.
+ * Blocked reasons Azure discovery reports: GCP's `*_conflict` vocabulary for the
+ * three linkage/type conflicts, plus its own `subscription_not_enabled`, raised
+ * whenever `state != "Enabled"`.
  */
 export const AZURE_BLOCKED_REASON = {
   ORGANIZATION: "organization_conflict",
@@ -495,7 +491,7 @@ interface AzureResultOverrides {
   replaceSubscriptionIds?: string[];
 }
 
-/** Pinned to the app's wire interfaces, for the reason `GcpFixtureDiscoveryResult` is. */
+/** Pinned to the app's wire interfaces, for the same reason `GcpFixtureDiscoveryResult` is. */
 type AzureFixtureDiscoveryResult = Omit<
   AzureDiscoveryResult,
   "subscriptions"
@@ -506,11 +502,9 @@ type AzureFixtureDiscoveryResult = Omit<
 };
 
 /**
- * The Azure discovery result as the API shapes it: management groups carry
- * canonical resource IDs in `id`/`parent_id`, subscriptions are identified by
- * their UUID and parent through their group's resource ID, and `display_name` is
- * the only human label. Subscription UUIDs are long by nature, so the id-column
- * overflow case needs no special candidate here.
+ * The Azure discovery result as the API shapes it: groups carry canonical resource
+ * IDs in `id`/`parent_id`, subscriptions are identified by their UUID. Those UUIDs
+ * are long by nature, so the id-column overflow case needs no special candidate.
  */
 export const buildAzureDiscoveryResult = ({
   replaceSubscriptionIds = [],
@@ -596,8 +590,6 @@ export const buildAzureDiscoveryResult = ({
           provider_secret_state: PROVIDER_SECRET_STATE.WILL_REPLACE,
         }),
       ),
-      // Blocked with no provider and no conflict: the state check alone is
-      // enough, which is the class the linkage-conflict cases cannot cover.
       subscription(
         AZURE_SUBSCRIPTION_DISABLED,
         "Dormant Sandbox",
@@ -783,13 +775,13 @@ export const azureOnboardingFixture = (
   };
 };
 
+/** The AWS organization identifier of `awsHierarchyFixture`. */
+export const AWS_HIERARCHY_ORG_EXTERNAL_ID = "o-aws0abcdef";
+
 /**
  * A providers-page hierarchy world with a fully onboarded AWS organization
  * (two OUs, three providers). Used for the providers-table grouping tests.
  */
-/** The AWS organization identifier of `awsHierarchyFixture`. */
-export const AWS_HIERARCHY_ORG_EXTERNAL_ID = "o-aws0abcdef";
-
 export const awsHierarchyFixture = (
   overrides: Partial<OrgFixture> = {},
 ): OrgFixture => {
@@ -898,9 +890,8 @@ export const mixedHierarchyFixture = (
       kind: NODE_KIND.MANAGEMENT_GROUP,
       name: AZURE_HIERARCHY_GROUP_NAME,
       externalId: AZURE_HIERARCHY_GROUP,
-      // The tenant-root Management Group is never persisted as a node — nodes
-      // exist only for selected descendant groups and their ancestors — so it
-      // appears here as a parent id that resolves to no node row.
+      // The tenant-root Management Group is never persisted as a node, so this
+      // parent id deliberately resolves to no node row.
       parentExternalId: AZURE_ROOT_GROUP,
       organizationId: azureOrgId,
       providerIds: ["azp-1"],
@@ -988,12 +979,10 @@ export const mixedHierarchyFixture = (
 };
 
 /**
- * An `org_type` this build has no onboarding flow for. Every value of
- * `ORGANIZATION_TYPE` is onboardable now that Azure has a flow, so the
- * display-only behaviour has to be exercised through a type the enum itself does
- * not carry — which is also the real case: the enum mirrors a server-side one.
- * `oraclecloud` is a real provider type, so the provider rows underneath it still
- * render coherently.
+ * An `org_type` this build has no onboarding flow for. Every `ORGANIZATION_TYPE`
+ * value is onboardable now, so this has to come from outside the enum — which
+ * mirrors the real case, the enum tracking a server-side one. `oraclecloud` is a
+ * real provider type, so its provider rows still render coherently.
  */
 export const DISPLAY_ONLY_ORG_TYPE = "oraclecloud";
 export const DISPLAY_ONLY_ORG_NAME = "My Oracle Cloud Tenancy";

ui/__tests__/msw/handlers/organizations.ts

@@ -507,8 +507,7 @@ export const handlersForOrganizations = (
               result:
                 fx.discovery.status === "succeeded" ? fx.discovery.result : {},
               error: fx.discovery.error,
-              // Machine code and human message are separate fields; the message
-              // is only sent for the codes the API explains itself.
+              // Machine code and human message are separate fields on the wire.
               error_message: fx.discovery.errorMessage ?? null,
               inserted_at: TS,
               updated_at: TS,

ui/actions/organizations/organizations.test.ts

@@ -86,10 +86,9 @@ describe("organizations actions", () => {
   });
 
   it("rejects an organization type with no onboarding flow instead of coercing it", async () => {
-    // Given a form asking for a type this build cannot onboard. `oraclecloud` is
-    // a real provider the API can report an organization for — display supports
-    // it, onboarding does not — so it is the exact boundary a blind cast would
-    // let through.
+    // Given a type this build cannot onboard. `oraclecloud` is real — display
+    // supports it, onboarding does not — the exact boundary a blind cast lets
+    // through.
     const formData = new FormData();
     formData.set("name", "Tenancy");
     formData.set("externalId", "ocid1.tenancy.oc1..aaaa1111");

ui/app/(prowler)/providers/providers-page.harness.tsx

@@ -40,8 +40,8 @@ interface MountOptions {
 
 /**
  * Attributes a `POST /organizations` carries. `root_external_id` is deliberately
- * absent: the API derives every type's root, so a test asserting the client does
- * not send one reads it off the parsed body, not off this shape.
+ * absent: a test asserting the client sends none reads the parsed body, not this
+ * shape.
  */
 export interface OrganizationCreateAttributes {
   name?: string;
@@ -267,11 +267,7 @@ export class ProvidersPageHarness extends BrowserHarness<OrgFixture> {
 
   // --- Wizard: Azure setup step ------------------------------------------
 
-  /**
-   * Fill the Azure organization-details phase. The tenant is the only identifier
-   * collected: onboarding is always scoped to the tenant root Management Group,
-   * which the API derives from it.
-   */
+  /** Fill the Azure organization-details phase (the tenant is the only id asked for). */
   async fillAzureOrgDetails(tenantId: string, name?: string): Promise<void> {
     const tenantInput = await this.waitFor(() => this.inputByName("tenantId"));
     await this.user.fill(tenantInput, tenantId);
@@ -369,8 +365,7 @@ export class ProvidersPageHarness extends BrowserHarness<OrgFixture> {
 
   /**
    * Whether the pre-apply warning states how many already-onboarded candidates the
-   * apply would overwrite, and names them. Noun-bound per organization type: the
-   * warning saying the wrong noun is the failure this pins.
+   * apply would overwrite, and names them — in the noun this organization type uses.
    */
   private hasOverwriteWarningFor(
     count: number,
@@ -392,7 +387,7 @@ export class ProvidersPageHarness extends BrowserHarness<OrgFixture> {
     return this.hasOverwriteWarningFor(projectCount, names, "project");
   }
 
-  /** The GCP counterpart above, in Azure's noun. */
+  /** The same warning, in Azure's noun. */
   hasApplySubscriptionOverwriteWarning(
     subscriptionCount: number,
     names: string[] = [],
@@ -425,10 +420,7 @@ export class ProvidersPageHarness extends BrowserHarness<OrgFixture> {
     await this.waitForText(reason, timeoutMs);
   }
 
-  /**
-   * Whether that reason is showing — the negative half, for asserting which of
-   * the competing failure strings the user was actually given.
-   */
+  /** Whether that reason is showing — the negative half of the assertion. */
   hasDiscoveryFailureReason(reason: RegExp): boolean {
     return this.containsText(reason);
   }
@@ -484,11 +476,9 @@ export class ProvidersPageHarness extends BrowserHarness<OrgFixture> {
   }
 
   /**
-   * A container row identifies itself by its uid: a GCP folder ref, an AWS OU id,
-   * or an Azure Management Group resource id. Anchored, because it is matched
-   * against one element's own value — never the whole row, whose uid and name
-   * columns are adjacent and would run together as
-   * "…/managementGroups/archived" + "Archived".
+   * A container row's uid: a GCP folder ref, an AWS OU id, or an Azure Management
+   * Group resource id. Anchored because it is matched against one element's own
+   * value — the adjacent uid and name columns would otherwise run together.
    */
   private static readonly CONTAINER_UID =
     /^(?:folders\/\d+|ou-[\w-]+|\/providers\/Microsoft\.Management\/managementGroups\/[\w.()-]+)$/;
@@ -574,8 +564,8 @@ export class ProvidersPageHarness extends BrowserHarness<OrgFixture> {
     const row = this.containerRows.find((item) =>
       (item.textContent ?? "").includes(containerLabel),
     );
-    // The note is the icon-only `role="img"`; the id column carries the role too,
-    // so that it can name itself with the canonical id, and comes first in the row.
+    // The id column carries `role="img"` too, and comes first in the row, so the
+    // note is the one matched by its svg.
     return (
       row?.querySelector('[role="img"]:has(svg)')?.getAttribute("aria-label") ??
       null

ui/app/(prowler)/providers/providers-page.integration.test.tsx

@@ -165,11 +165,7 @@ const AZURE_CLIENT_ID = "99999999-9999-4999-8999-999999999999";
 const AZURE_CLIENT_SECRET = "azure-client-secret";
 const AZURE_ORG_DOCS = "prowler-cloud-azure-management-groups";
 
-/**
- * Drive a fresh Azure org onboarding up to the authentication submit. The tenant
- * is the only identifier collected: onboarding is always scoped to the tenant
- * root Management Group, which the API derives from it.
- */
+/** Drive a fresh Azure org onboarding up to the authentication submit. */
 async function authenticateAzureOrg(
   harness: ProvidersPageHarness,
   { name }: { name?: string } = {},
@@ -688,9 +684,8 @@ describe("Organization onboarding wizard", () => {
         expect(harness.hasSelectedSubscriptionCount(2, 2)).toBe(true);
         expect(harness.usesAccountWording()).toBe(false);
 
-        // The tenant is the whole identity on the wire: onboarding is only ever
-        // scoped to the tenant root Management Group, and the API derives that root
-        // itself — a client that sends one is claiming a choice it does not have.
+        // The tenant is the whole identity on the wire: the API derives the root
+        // Management Group itself, so the client must not send one.
         const created = await harness.createdOrganizationAttributes();
         expect(created?.org_type).toBe(ORGANIZATION_TYPE.AZURE);
         expect(created?.external_id).toBe(AZURE_TENANT_ID);
@@ -719,8 +714,8 @@ describe("Organization onboarding wizard", () => {
             "POST",
             "/organization-secrets",
           );
-        // The tenant lives on the organization, so repeating it inside the secret
-        // would be a second, silently divergent source of truth.
+        // The tenant lives on the organization; repeating it inside the secret
+        // would be a second source of truth.
         expect(secret?.data.attributes.secret).toEqual({
           client_id: AZURE_CLIENT_ID,
           client_secret: AZURE_CLIENT_SECRET,
@@ -772,9 +767,8 @@ describe("Organization onboarding wizard", () => {
           AZURE_GROUP_PLATFORM,
         ]);
 
-        // Every group's canonical id repeats the same ARM prefix, which is all a
-        // 176px column can show, so the id column reads the trailing Management
-        // Group name instead, keeping the canonical id as the accessible name.
+        // Every group's canonical id repeats the same ARM prefix, so the id column
+        // shows the trailing name and keeps the canonical id as its accessible name.
         expect(harness.containerIdLabel(AZURE_GROUP_ENGINEERING)).toBe(
           "engineering",
         );
@@ -811,8 +805,6 @@ describe("Organization onboarding wizard", () => {
         const harness = new ProvidersPageHarness(azureOnboardingFixture());
         await onboardAzureToSelection(harness);
 
-        // A subscription-less group still reaches the tree, and has to say so in
-        // Azure's nouns.
         expect(harness.isContainerInert(AZURE_EMPTY_GROUP_NAME)).toBe(true);
         expect(harness.inertContainerNote(AZURE_EMPTY_GROUP_NAME)).toBe(
           "No subscriptions available to select in this management group.",
@@ -835,8 +827,7 @@ describe("Organization onboarding wizard", () => {
           ),
         ).toBe(true);
 
-        // The row collapses and re-expands rather than selecting: an inert group that
-        // could not be opened would never explain itself.
+        // The row collapses and re-expands rather than selecting.
         await harness.clickContainerRow(AZURE_BLOCKED_GROUP_NAME);
         await harness.waitForTransition();
         expect(
@@ -1033,8 +1024,8 @@ describe("Organization onboarding wizard", () => {
         const harness = new ProvidersPageHarness(fixture);
         await authenticateAzureOrg(harness);
 
-        // A code we curate copy for outranks the server's own message: ours names the
-        // fix, and the framing is right — the credentials are fine here.
+        // Curated copy for a known code outranks the server's own message: ours
+        // names the fix, and the credentials are not the problem here.
         await harness.waitForDiscoveryFailureReason(
           /Grant it the Reader role at the Management Group level/,
         );
@@ -1045,7 +1036,6 @@ describe("Organization onboarding wizard", () => {
         ).toBe(false);
         await harness.waitForDiscoveryCount(1);
 
-        // Retry triggers a brand-new discovery, not a resumed poll.
         await harness.retryDiscovery();
         await harness.waitForDiscoveryCount(2);
       }, 40000);
@@ -1064,9 +1054,8 @@ describe("Organization onboarding wizard", () => {
         const harness = new ProvidersPageHarness(fixture);
         await authenticateAzureOrg(harness);
 
-        // Codes outrun the copy table, so an unmapped one must still say something
-        // specific — the sanitized server message, never the raw code, and never
-        // "authentication failed" for a problem that is not the credentials.
+        // An unmapped code must still be specific: the sanitized server message,
+        // never the raw code and never "authentication failed".
         await harness.waitForDiscoveryFailureReason(
           /Azure throttled the Management Group read for this tenant\./,
         );
@@ -1326,8 +1315,8 @@ describe("Providers page", () => {
           "PATCH",
           `/organizations/${AWS_HIERARCHY_ORG_ID}`,
         );
-        // Blank falls back to the identifier, the same rule creation applies —
-        // the action rejects an empty name outright.
+        // Same rule as creation: the action rejects an empty name, so the client
+        // substitutes the identifier.
         expect(body?.data.attributes.name).toBe(AWS_HIERARCHY_ORG_EXTERNAL_ID);
       }, 30000);
 

ui/components/providers/organizations/hooks/org-setup-strategy.test.ts

@@ -39,22 +39,17 @@ const SETUP_DATA = {
   },
 } as const satisfies Record<OrgFlowType, OrgSetupSubmissionData>;
 
-/**
- * The structure each flow's hierarchy is made of. A tenant has no folders and an
- * organization has no Management Groups, so copy for a code every provider
- * reports has to pick the right one.
- */
+/** The structure each flow's hierarchy is made of — a tenant has no folders. */
 const HIERARCHY_WORDING = {
   [ORGANIZATION_TYPE.AWS]: "organizational unit hierarchy",
   [ORGANIZATION_TYPE.AZURE]: "Management Group hierarchy",
   [ORGANIZATION_TYPE.GCP]: "folder hierarchy",
 } as const satisfies Record<OrgFlowType, string>;
 
 describe("bindOrgSetupStrategy", () => {
-  // `hierarchy_depth_exceeded` is one API code for every provider. The
-  // precedence chain (curated → server message → auth failure) is covered by the
-  // submission hook's suite; what only an exhaustive per-flow check can catch is
-  // one flow being told about another cloud's structure.
+  // `hierarchy_depth_exceeded` is one API code for every provider. The precedence
+  // chain is covered by the submission hook's suite; only an exhaustive per-flow
+  // check catches one flow being told about another cloud's structure.
   it.each(ORG_FLOW_TYPES)(
     "describes %s's own hierarchy for the shared hierarchy_depth_exceeded code",
     (orgType) => {
@@ -86,10 +81,8 @@ describe("bindOrgSetupStrategy", () => {
     },
   );
 
-  // The API stores an Azure tenant as `str(UUID(...))` — canonical lowercase —
-  // and `filter[external_id]` is an exact lookup, so a tenant typed in uppercase
-  // has to reach find-or-create already folded. Unfolded, the second wizard run
-  // misses its own organization and then collides on the POST.
+  // `filter[external_id]` is an exact lookup, so an uppercase-typed tenant would
+  // miss its own organization on a second run and then collide on the POST.
   it("folds an uppercase Azure tenant ID to the API's canonical form", () => {
     const bound = bindOrgSetupStrategy({
       ...SETUP_DATA[ORGANIZATION_TYPE.AZURE],