@adobe/spacecat-shared-data-access 3.63.0 → 3.65.0

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [@adobe/spacecat-shared-data-access-v3.65.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-data-access-v3.64.0...@adobe/spacecat-shared-data-access-v3.65.0) (2026-05-16)
+
+### Features
+
+* submodule support — reinstate clone, fix pull, add hasSubmodules flag ([#1550](https://github.com/adobe/spacecat-shared/issues/1550)) ([3329ff8](https://github.com/adobe/spacecat-shared/commit/3329ff82740c2311545bd7a1ab693eb92ecb8f5d))
+
+## [@adobe/spacecat-shared-data-access-v3.64.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-data-access-v3.63.0...@adobe/spacecat-shared-data-access-v3.64.0) (2026-05-15)
+
+### Features
+
+* strict schema for data.issues[] with per-issue lifecycle fields       ([#1594](https://github.com/adobe/spacecat-shared/issues/1594)) ([d101db4](https://github.com/adobe/spacecat-shared/commit/d101db4e6407cfe9cbb742d54b500439cf62b64f))
+
 ## [@adobe/spacecat-shared-data-access-v3.63.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-data-access-v3.62.0...@adobe/spacecat-shared-data-access-v3.63.0) (2026-05-14)
 
 ### Features

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/spacecat-shared-data-access",
-  "version": "3.63.0",
+  "version": "3.65.0",
   "description": "Shared modules of the Spacecat Services - Data Access",
   "type": "module",
   "engines": {

package/src/models/site/index.d.ts

@@ -34,6 +34,92 @@ export interface HlxConfig {
   };
 }
 
+/**
+ * One entry per submodule declared in the parent repo's `.gitmodules`.
+ * Each row carries both the importer-detected facts (declared section,
+ * original URL, external flag) and any onboarding-resolved CM URL the
+ * cm-client uses at clone/pull time to rewrite `.git/config`.
+ *
+ * Lifecycle:
+ *   - Importer-written fields (`sectionName`, `gitmodulesUrl`, `external`)
+ *     are refreshed on every import. Entries whose `sectionName` is no
+ *     longer present in the parent's `.gitmodules` are dropped.
+ *   - Onboarding-written fields (`resolvedUrl`) are preserved across
+ *     imports for surviving entries — the importer cannot re-derive
+ *     them (no CM Management API access from Lambda) and onboarding
+ *     refreshes them out-of-band.
+ */
+export interface SubmoduleEntry {
+  /**
+   * The `<X>` from `[submodule "<X>"]` in `.gitmodules`. Used by
+   * cm-client as the `.git/config` key when rewriting URLs (i.e.
+   * `submodule.<sectionName>.url`). In every customer `.gitmodules`
+   * we've seen this matches the `path = …` value, but git's lookup
+   * is by section name so we capture it here.
+   */
+  sectionName: string;
+  /**
+   * The submodule URL exactly as declared in `.gitmodules`, with
+   * basic-auth credentials stripped from https/http forms. Relative
+   * (`../foo.git`) and SSH (`git@host:path`) forms are preserved as-is.
+   */
+  gitmodulesUrl: string;
+  /**
+   * True when this submodule's URL points to a host other than the
+   * parent repo's host. Relative URLs (`../foo.git`) and SSH URLs
+   * targeting the parent's host classify as internal (`false`).
+   */
+  external: boolean;
+  /**
+   * BYOG-only. Onboarding-populated URL the cm-client writes into
+   * `.git/config submodule.<sectionName>.url` at clone/pull time.
+   *
+   * The CM repo service proxies BYOG clones through URLs of the form
+   * `{CM_REPO_URL}/api/program/{programId}/repository/{numericId}.git`.
+   * When `.gitmodules` uses relative or SSH URLs, git resolves them to
+   * paths the proxy can't serve. The cm-client rewrites each submodule's
+   * `.git/config` URL to a CM-reachable form before running
+   * `git submodule update`. `.gitmodules` itself is never modified.
+   *
+   * URL form depends on the underlying repo type, decided at onboarding:
+   *   - BYOG (`github`/`gitlab`/`bitbucket`/`azure_devops`):
+   *       `{cmRepoUrl}/api/program/{programId}/repository/{numericId}.git`
+   *   - `standard`:
+   *       `https://git.cloudmanager.adobe.com/{orgName}/{repoName}/`
+   *
+   * The cm-client picks the auth scope to apply by parsing each
+   * `resolvedUrl`'s host. URLs on the CM proxy host get
+   * Bearer + x-api-key + x-gw-ims-org-id; URLs on
+   * `https://git.cloudmanager.adobe.com/{orgName}/` get Basic auth
+   * from `CM_STANDARD_REPO_CREDENTIALS[programId]` scoped to the org
+   * prefix.
+   *
+   * Absent when:
+   *   - the parent is `standard` (cm-client takes the native
+   *     `--recurse-submodules` path and ignores this array entirely),
+   *   - this submodule is `external` to a host outside CM's reach,
+   *   - onboarding hasn't run for this site yet.
+   *
+   * When absent on a BYOG parent, cm-client logs a warning and skips
+   * that submodule during `submodule update`.
+   */
+  resolvedUrl?: string;
+}
+
+/**
+ * Per-submodule list captured during code import. Empty array when the
+ * cloned repo has no `.gitmodules` file (and therefore no submodules).
+ */
+export type SubmodulesMetadata = SubmoduleEntry[];
+
+/**
+ * Metadata extracted during code import. Consumers should assume an
+ * empty object when a field is absent.
+ */
+export interface CodeMetadata {
+  submodules?: SubmodulesMetadata;
+}
+
 export interface CodeConfig {
   type: string;
   owner: string;
@@ -41,7 +127,17 @@ export interface CodeConfig {
   ref: string;
   installationId?: string;
   url: string;
+  /**
+   * S3 key (not full URL) where the imported repository ZIP is stored.
+   * Written by the code importer after successful ingestion.
+   */
   s3StoragePath?: string;
+  /**
+   * Metadata extracted from the cloned repository. Always overwritten
+   * on each successful import — a re-import that finds no submodules
+   * clears any submodule entries from an earlier import.
+   */
+  metadata?: CodeMetadata;
 }
 
 export interface DeliveryConfig {

package/src/models/site/site.schema.js

@@ -76,6 +76,27 @@ const schema = new SchemaBuilder(Site, SiteCollection)
     validate: (value) => isNonEmptyObject(validateConfiguration(value)),
     get: (value) => Config(value),
   })
+  /**
+   * Repository configuration used by the code importer and downstream
+   * consumers (autofix, suggestion generation, code analysis).
+   *
+   * Fields written by the importer after a successful clone:
+   *   - s3StoragePath: S3 key (not full URL) of the imported repository ZIP
+   *   - metadata.submodules: per-submodule array. Each entry carries
+   *     `{ sectionName, gitmodulesUrl, external }` from the parent's
+   *     `.gitmodules`. Empty array when the repo has no `.gitmodules`.
+   *     The importer refreshes these fields on every import; entries whose
+   *     `sectionName` is no longer present are dropped.
+   *
+   * Fields populated at onboarding (not by the importer):
+   *   - metadata.submodules[].resolvedUrl: BYOG-only. Pre-resolved CM URL
+   *     the cm-client writes into `.git/config submodule.<sectionName>.url`
+   *     at clone/pull time so submodules can fetch through the CM proxy
+   *     (or `git.cloudmanager.adobe.com` for standard submodules of BYOG
+   *     parents). Preserved across re-imports for surviving sectionNames.
+   *
+   * See SubmoduleEntry / CodeConfig in index.d.ts for the full TypeScript shape.
+   */
   .addAttribute('code', {
     type: 'any',
     required: false,
@@ -89,6 +110,7 @@ const schema = new SchemaBuilder(Site, SiteCollection)
       installationId: { type: 'string', required: false },
       url: { type: 'string', required: true, validate: (value) => isValidUrl(value) },
       s3StoragePath: { type: 'string', required: false },
+      metadata: { type: 'any', required: false },
     },
   })
   .addAttribute('deliveryType', {

package/src/models/suggestion/index.js

@@ -20,3 +20,11 @@ export {
 
 // Export DATA_SCHEMAS for api-service to reference
 export const { DATA_SCHEMAS } = Suggestion;
+
+// Re-export per-issue lifecycle constants so consumers (audit-worker, autofix-worker,
+// api-service, Mystique) can validate per-issue values without duplicating enum lists.
+export {
+  CWV_METRIC_TYPES,
+  ISSUE_STATUSES,
+  ISSUE_SKIP_REASONS,
+} from './suggestion.data-schemas.js';

package/src/models/suggestion/suggestion.data-schemas.js

@@ -26,6 +26,85 @@
 import Joi from 'joi';
 import { OPPORTUNITY_TYPES } from '@adobe/spacecat-shared-utils';
 
+/**
+ * Status and skip-reason values for per-issue lifecycle inside `data.issues[]`.
+ *
+ * Exported for consumers that need to construct or validate per-issue values
+ * (audit-worker, autofix-worker, api-service controllers, Mystique).
+ *
+ * Duplicated from `Suggestion.STATUSES` / `Suggestion.SKIP_REASONS` (suggestion.model.js)
+ * to avoid a circular import — the model already imports DATA_SCHEMAS from this file.
+ * Keep in sync if either set ever changes.
+ */
+export const ISSUE_STATUSES = [
+  'NEW',
+  'APPROVED',
+  'IN_PROGRESS',
+  'SKIPPED',
+  'FIXED',
+  'ERROR',
+  'OUTDATED',
+  'PENDING_VALIDATION',
+  'REJECTED',
+];
+
+export const ISSUE_SKIP_REASONS = [
+  'ALREADY_IMPLEMENTED',
+  'INACCURATE_OR_INCOMPLETE',
+  'TOO_RISKY',
+  'NO_REASON',
+  'OTHER',
+];
+
+/**
+ * Allowed CWV metric types for `data.issues[].type`.
+ * Exported so audit-worker / Mystique / api-service can reuse the same source of truth.
+ */
+export const CWV_METRIC_TYPES = ['lcp', 'cls', 'inp'];
+
+/**
+ * Strict per-issue schema for `data.issues[]` on CWV suggestions.
+ *
+ * All fields are optional initially so existing prod rows (issues without `id` / `type` /
+ * `status`) keep validating. Tighten to required after a backfill populates `id` and `type`
+ * on every existing issue.
+ *
+ * Field ownership:
+ * - `id`, `type`, `value`, `title`, `cwvValue`, `patchContent`, `isCodeChangeAvailable`,
+ *   initial `status: 'NEW'` — written by Mystique (guidance + code-fix tasks).
+ * - `status` transitions (APPROVED/REJECTED/SKIPPED/IN_PROGRESS) — written by api-service
+ *   via the existing PATCH /suggestions/:id endpoint (UI does read-modify-write of the
+ *   whole `data` payload).
+ * - `status: FIXED | ERROR` — written by autofix-worker after PR creation.
+ * - `status: OUTDATED` — written by audit-worker `handleOutdatedSuggestions` on re-audit.
+ * - `fixEntityId` — written by autofix-worker (or Mystique `_create_fix_entity`).
+ * - `jiraLink` — written by whichever service files the Jira ticket (today: UI or api-service).
+ * - `skipReason`, `skipDetail` — written by api-service when `status` transitions to SKIPPED.
+ */
+const CWV_ISSUE_SCHEMA = Joi.object({
+  // Identity
+  id: Joi.string().optional(),
+
+  // Semantic
+  type: Joi.string().valid(...CWV_METRIC_TYPES).optional(),
+  title: Joi.string().optional(),
+  value: Joi.string().optional(),
+  cwvValue: Joi.number().optional(),
+
+  // Patch
+  patchContent: Joi.string().allow('').optional(),
+  isCodeChangeAvailable: Joi.boolean().optional(),
+
+  // Lifecycle
+  status: Joi.string().valid(...ISSUE_STATUSES).optional(),
+  skipReason: Joi.string().valid(...ISSUE_SKIP_REASONS).optional(),
+  skipDetail: Joi.string().max(1000).optional(),
+
+  // Linkage
+  jiraLink: Joi.string().uri().allow(null).optional(),
+  fixEntityId: Joi.string().uuid().optional(),
+}).unknown(true);
+
 /**
  * Custom Joi validator that accepts malformed HTTP/HTTPS URLs and relative paths
  * while rejecting dangerous URI schemes (javascript:, data:, blob:, etc.).
@@ -148,22 +227,26 @@ export const DATA_SCHEMAS = {
       url: Joi.string().uri().optional(),
       pageviews: Joi.number().optional(),
       organic: Joi.number().optional(),
+      // RUM metrics are nullable in practice. INP requires user interaction events,
+      // so devices/pages without interactions report `inp: null`. The *Count fields
+      // similarly are null when the source RUM bundle has no sample for that metric.
+      // Mirror the existing `.allow(null)` already on lcp/ttfb/cls.
       metrics: Joi.array().items(
         Joi.object({
           deviceType: Joi.string().optional(),
-          pageviews: Joi.number().optional(),
-          clsCount: Joi.number().optional(),
-          ttfbCount: Joi.number().optional(),
+          pageviews: Joi.number().allow(null).optional(),
+          clsCount: Joi.number().allow(null).optional(),
+          ttfbCount: Joi.number().allow(null).optional(),
           lcp: Joi.number().allow(null).optional(),
-          inpCount: Joi.number().optional(),
-          inp: Joi.number().optional(),
+          inpCount: Joi.number().allow(null).optional(),
+          inp: Joi.number().allow(null).optional(),
           ttfb: Joi.number().allow(null).optional(),
           cls: Joi.number().allow(null).optional(),
-          lcpCount: Joi.number().optional(),
-          organic: Joi.number().optional(),
+          lcpCount: Joi.number().allow(null).optional(),
+          organic: Joi.number().allow(null).optional(),
         }).unknown(true),
       ).required(),
-      issues: Joi.array().items(Joi.object()).optional().default([]),
+      issues: Joi.array().items(CWV_ISSUE_SCHEMA).optional().default([]),
       jiraLink: Joi.string().uri().allow(null).optional(),
       aggregationKey: Joi.string().allow(null).optional(),
     }).unknown(true),