sailfork / t3code-github / .repos/ alchemy-effect/ packages/ gcp/ src/ ContainerAnalysis/ Note.ts

import * as containeranalysis from "@distilled.cloud/gcp/containeranalysis_v1";
import { Unowned } from "alchemy/AdoptPolicy";
import { isResolved } from "alchemy/Diff";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import * as Effect from "effect/Effect";
import { GcpEnvironment } from "../Environment.ts";
import { hasAlchemyLabels } from "../Labels.ts";
import type { Providers } from "../Providers.ts";
import {
  expandNoteName,
  hasOwnershipMarker,
  ignoreGone,
  listProjectNotes,
  missingGet,
  noteAttrs,
  noteKind,
  parseDescription,
  projectParent,
  reconcileNote,
  replaceOnIdentity,
  retryTransient,
  toPhysicalId,
} from "./internal.ts";

export type NoteProps = {
  /**
   * Note id (the `{note}` segment of
   * `projects/{project}/notes/{note}`). If omitted, a unique RFC1035 id is
   * generated. Immutable — changing it replaces the note.
   */
  noteId?: string;
  /**
   * One-sentence summary of the analysis this note describes.
   */
  shortDescription?: string;
  /**
   * Detailed description. Alchemy stamps ownership into this field for
   * `list` / nuke because notes have no labels API.
   */
  longDescription?: string;
  /**
   * RFC3339 expiration. Empty means the note does not expire.
   */
  expirationTime?: string;
  /**
   * URLs associated with this note.
   */
  relatedUrl?: containeranalysis.RelatedUrlList;
  /**
   * Other note resource names related to this note.
   */
  relatedNoteNames?: string[];
  /**
   * Attestation authority note. Used when no other kind is set.
   */
  attestation?: containeranalysis.AttestationNote;
  /**
   * Build provenance note.
   */
  build?: containeranalysis.BuildNote;
  /**
   * Discovery note.
   */
  discovery?: containeranalysis.DiscoveryNote;
  /**
   * Base image note.
   */
  image?: containeranalysis.ImageNote;
  /**
   * Package note.
   */
  package?: containeranalysis.PackageNote;
  /**
   * Vulnerability note.
   */
  vulnerability?: containeranalysis.VulnerabilityNote;
  /**
   * Compliance note.
   */
  compliance?: containeranalysis.ComplianceNote;
  /**
   * Deployment note.
   */
  deployment?: containeranalysis.DeploymentNote;
  /**
   * Upgrade note.
   */
  upgrade?: containeranalysis.UpgradeNote;
  /**
   * Vulnerability assessment note.
   */
  vulnerabilityAssessment?: containeranalysis.VulnerabilityAssessmentNote;
  /**
   * Secret note.
   */
  secret?: containeranalysis.SecretNote;
  /**
   * DSSE attestation note.
   */
  dsseAttestation?: containeranalysis.DSSEAttestationNote;
  /**
   * SBOM reference note.
   */
  sbomReference?: containeranalysis.SBOMReferenceNote;
  /**
   * AI skill analysis note.
   */
  aiSkillAnalysis?: containeranalysis.AISkillAnalysisNote;
};

export type Note = Resource<
  "GCP.ContainerAnalysis.Note",
  NoteProps,
  {
    /** Full resource name `projects/{project}/notes/{note}`. */
    name: string;
    /** Note id (last path segment). */
    noteId: string;
    /** Project id. */
    project: string;
    /** One-sentence summary. */
    shortDescription: string | undefined;
    /** User description with the Alchemy ownership prefix stripped. */
    longDescription: string | undefined;
    /** Server-reported analysis kind. */
    kind: string | undefined;
    /** RFC3339 expiration, if any. */
    expirationTime: string | undefined;
    /** URLs associated with this note. */
    relatedUrl: containeranalysis.RelatedUrlList;
    /** Related note resource names. */
    relatedNoteNames: string[];
    /** Attestation authority metadata. */
    attestation: containeranalysis.AttestationNote | undefined;
    /** Build provenance metadata. */
    build: containeranalysis.BuildNote | undefined;
    /** Discovery metadata. */
    discovery: containeranalysis.DiscoveryNote | undefined;
    /** Base image metadata. */
    image: containeranalysis.ImageNote | undefined;
    /** Package metadata. */
    package: containeranalysis.PackageNote | undefined;
    /** Vulnerability metadata. */
    vulnerability: containeranalysis.VulnerabilityNote | undefined;
    /** Compliance metadata. */
    compliance: containeranalysis.ComplianceNote | undefined;
    /** Deployment metadata. */
    deployment: containeranalysis.DeploymentNote | undefined;
    /** Upgrade metadata. */
    upgrade: containeranalysis.UpgradeNote | undefined;
    /** Vulnerability assessment metadata. */
    vulnerabilityAssessment: containeranalysis.VulnerabilityAssessmentNote | undefined;
    /** Secret metadata. */
    secret: containeranalysis.SecretNote | undefined;
    /** DSSE attestation metadata. */
    dsseAttestation: containeranalysis.DSSEAttestationNote | undefined;
    /** SBOM reference metadata. */
    sbomReference: containeranalysis.SBOMReferenceNote | undefined;
    /** AI skill analysis metadata. */
    aiSkillAnalysis: containeranalysis.AISkillAnalysisNote | undefined;
    /** RFC3339 creation timestamp. */
    createTime: string | undefined;
    /** RFC3339 last-update timestamp. */
    updateTime: string | undefined;
  },
  never,
  Providers
>;

/**
 * A project-scoped Container Analysis (Grafeas) note. Notes describe a
 * type of analysis; occurrences attach a note to a resource such as a
 * container image.
 *
 * Notes have no labels field, so Alchemy stamps ownership into
 * `longDescription` for `list` / nuke. `noteId` is identity — changing it
 * replaces the note. Descriptions, related URLs, and kind payloads update
 * in place. Switching the analysis kind replaces the note.
 *
 * ### Creating a Note
 * **Example:** Attestation authority
 * ```typescript
 * const note = yield* GCP.ContainerAnalysis.Note("Authority", {
 *   shortDescription: "qa attestor",
 *   attestation: { hint: { humanReadableName: "QA" } },
 * });
 * ```
 *
 * **Example:** Explicit id and related URL
 * ```typescript
 * const note = yield* GCP.ContainerAnalysis.Note("Authority", {
 *   noteId: "qa-attestor",
 *   shortDescription: "qa attestor",
 *   longDescription: "signs production images",
 *   relatedUrl: [{ url: "https://example.com/policy", label: "policy" }],
 *   attestation: { hint: { humanReadableName: "QA" } },
 * });
 * ```
 *
 * ### Updating a Note
 * Re-declare the same logical id with changed props; the engine keeps the
 * physical resource and updates it in place.
 *
 * **Example:** Change the summary
 * ```typescript
 * const note = yield* GCP.ContainerAnalysis.Note("Authority", {
 *   shortDescription: "qa and staging attestor",
 *   attestation: { hint: { humanReadableName: "QA" } },
 * });
 * ```
 *
 * @resource
 * @category ContainerAnalysis
 */
export const Note = Resource<Note>("GCP.ContainerAnalysis.Note");

const resourceName = (project: string, noteId: string) => expandNoteName(noteId, project);

const getByName = missingGet(containeranalysis.getProjectsNotes);

const toPublicAttrs = (note: containeranalysis.Note, project: string): Note["Attributes"] => {
  const attrs = noteAttrs(note, project);
  return {
    name: attrs.name,
    noteId: attrs.noteId,
    project: attrs.project,
    shortDescription: attrs.shortDescription,
    longDescription: attrs.longDescription,
    kind: attrs.kind,
    expirationTime: attrs.expirationTime,
    relatedUrl: attrs.relatedUrl,
    relatedNoteNames: attrs.relatedNoteNames,
    attestation: attrs.attestation,
    build: attrs.build,
    discovery: attrs.discovery,
    image: attrs.image,
    package: attrs.package,
    vulnerability: attrs.vulnerability,
    compliance: attrs.compliance,
    deployment: attrs.deployment,
    upgrade: attrs.upgrade,
    vulnerabilityAssessment: attrs.vulnerabilityAssessment,
    secret: attrs.secret,
    dsseAttestation: attrs.dsseAttestation,
    sbomReference: attrs.sbomReference,
    aiSkillAnalysis: attrs.aiSkillAnalysis,
    createTime: attrs.createTime,
    updateTime: attrs.updateTime,
  };
};

export const NoteProvider = () =>
  Provider.succeed(Note, {
    stables: ["name", "noteId", "project", "kind", "createTime"],

    diff: Effect.fn(function* ({ news, olds, output }) {
      if (!isResolved(news)) return undefined;
      const previousKind = noteKind(olds ?? {}) ?? output?.kind;
      const nextKind = noteKind(news) ?? previousKind;
      return replaceOnIdentity({
        previousId: olds?.noteId ?? output?.noteId,
        nextId: news.noteId,
        extra: previousKind !== undefined && nextKind !== undefined && previousKind !== nextKind,
      });
    }),

    read: Effect.fn(function* ({ id, olds, output }) {
      const env = yield* GcpEnvironment.current;
      const noteId = yield* toPhysicalId(id, olds?.noteId, output?.noteId);
      const name = output?.name ?? resourceName(env.project, noteId);
      const existing = yield* getByName(name);
      if (existing === undefined) return undefined;
      const attrs = toPublicAttrs(existing, env.project);
      const { labels } = parseDescription(existing.longDescription);
      return (yield* hasAlchemyLabels(id, labels)) ? attrs : Unowned(attrs);
    }),

    list: () =>
      Effect.gen(function* () {
        const env = yield* GcpEnvironment.current;
        const items = yield* listProjectNotes(env.project);
        return items
          .filter((item) => hasOwnershipMarker(item.longDescription))
          .map((item) => toPublicAttrs(item, env.project));
      }),

    reconcile: Effect.fn(function* ({ id, news, output }) {
      const env = yield* GcpEnvironment.current;
      const noteId = yield* toPhysicalId(id, news.noteId, output?.noteId);
      const parent = projectParent(env.project);
      const name = resourceName(env.project, noteId);
      const current = yield* reconcileNote({
        id,
        name: output?.name ?? name,
        parent,
        noteId,
        news,
        ops: {
          get: getByName,
          create: (request) =>
            retryTransient(
              containeranalysis.createProjectsNotes({
                parent: request.parent,
                noteId: request.noteId,
                body: request.body,
              }),
            ).pipe(
              Effect.catchTag("Conflict", () =>
                getByName(`${request.parent}/notes/${request.noteId}`),
              ),
            ),
          patch: (request) =>
            retryTransient(
              containeranalysis.patchProjectsNotes({
                name: request.name,
                updateMask: request.updateMask,
                body: request.body,
              }),
            ),
        },
      });
      return toPublicAttrs(current, env.project);
    }),

    delete: Effect.fn(function* ({ output }) {
      yield* ignoreGone(containeranalysis.deleteProjectsNotes({ name: output.name }));
    }),
  });