@oneuptime/common 13.0.5 → 13.0.7

package/Utils/NetworkDiscovery/ShortHostnameUtil.ts

@@ -0,0 +1,91 @@
+import { normalizeReverseDnsName } from "./ReverseDnsNameUtil";
+
+/*
+ * The short form of a fully qualified hostname: "wb-0660-kds01.wbhq.com"
+ * becomes "wb-0660-kds01" (OneUptime issue #3678).
+ *
+ * Reverse DNS names a discovered host by its FQDN, and on an estate with one
+ * corporate domain that suffix is the same on every device in the list — it
+ * is noise, and it pushes the part an operator recognises to the far left of
+ * a truncated column. This is the one rule every piece of the short-name
+ * feature shares: the scan setting that names new imports, the Review dialog
+ * that previews them, and the bulk action that fixes devices imported before
+ * the setting existed. One function, so the three cannot disagree about what
+ * "short" means.
+ *
+ * WHY THE FIRST LABEL, AND NOT A SUFFIX THE OPERATOR TYPES. The issue asked
+ * for a configurable suffix (".wbhq.com"). A suffix list is strictly more
+ * work for the same answer on the reporter's estate, and it fails silently:
+ * a typo, a missing leading dot, or a second domain nobody listed leaves
+ * names unchanged with nothing to say why. The first label needs no
+ * configuration and behaves the same on every domain. The cost is on estates
+ * that put meaning in a middle label ("web.prod.example.com" and
+ * "web.stage.example.com" both become "web"), which is why the scan setting
+ * is opt-in and why import still falls back to an address-qualified name
+ * when a short name is already taken.
+ */
+
+/*
+ * A top-level label is letters (or an IDNA "xn--" label). Checked so that a
+ * dotted string which merely PASSES as a DNS name is not mistaken for one:
+ * "ubuntu-22.04" is a legal label sequence and a common sysName, and cutting
+ * it at the dot would rename a device "ubuntu-22".
+ */
+const TOP_LEVEL_LABEL_PATTERN: RegExp =
+  /^(?:[A-Za-z]+|[Xx][Nn]--[A-Za-z0-9-]+)$/;
+
+/*
+ * The short name has to NAME something. A first label with no letter in it —
+ * "10-18-167-31.dhcp.corp.com", "51.corp.example" — is an address spelled
+ * with dashes, and shortening it would present an address as though it were
+ * a hostname.
+ */
+const HAS_LETTER_PATTERN: RegExp = /[A-Za-z]/;
+
+/**
+ * The first label of `value` when it is a fully qualified hostname worth
+ * shortening, or undefined when it is not.
+ *
+ * Undefined — rather than the value unchanged — so a caller can tell "this is
+ * already as short as it gets" from "this was shortened", which the bulk
+ * action needs in order to skip a device honestly rather than rewrite it with
+ * its own name.
+ *
+ * Accepts `unknown` for the same reason normalizeReverseDnsName does: names
+ * reach here out of jsonb and out of API rows, and a number or null must
+ * return undefined rather than throw inside a render. Case is preserved.
+ */
+export function getShortHostname(value: unknown): string | undefined {
+  /*
+   * The full reverse-DNS rules first. A name with a space, markup, a
+   * control character, an in-addr.arpa echo, or nothing but digits is not a
+   * hostname, so it has no "short form" either — "Core Switch 1.5" stays
+   * exactly as it is.
+   */
+  const normalized: string | undefined = normalizeReverseDnsName(value);
+
+  if (!normalized) {
+    return undefined;
+  }
+
+  const labels: Array<string> = normalized.split(".");
+
+  if (labels.length < 2) {
+    return undefined;
+  }
+
+  const topLevelLabel: string = labels[labels.length - 1]!;
+  const firstLabel: string = labels[0]!;
+
+  if (!TOP_LEVEL_LABEL_PATTERN.test(topLevelLabel)) {
+    return undefined;
+  }
+
+  if (!HAS_LETTER_PATTERN.test(firstLabel)) {
+    return undefined;
+  }
+
+  return firstLabel;
+}
+
+export default getShortHostname;

package/Utils/NetworkSite/CidrMatchUtil.ts

@@ -27,12 +27,22 @@ export interface AssignmentRuleCandidate {
  * stores the responding IP in `hostname` and the SNMP sysName in `name`, so a
  * pattern like `*0664*` would never see the string the user is looking at in
  * the device list if we only tried `hostname`.
+ *
+ * `dnsName` is the device's fully qualified DNS name, kept apart from `name`
+ * once a discovery scan (or the bulk "shorten names" action) names the device
+ * by its short hostname (OneUptime/oneuptime#3678). It is a candidate for the
+ * same reason `name` is: a rule like `*.corp.example.com` was written against
+ * the FQDN the device used to be called, and renaming the device to
+ * `core-sw-01` must not silently drop it out of the site that rule placed it
+ * in. The FQDN either lands here or already lives in `sysName`, so matching
+ * all four keeps every match a device had before the rename.
  */
 export interface RuleMatchTarget {
   ip?: string | null | undefined;
   hostname?: string | null | undefined;
   sysName?: string | null | undefined;
   name?: string | null | undefined;
+  dnsName?: string | null | undefined;
 }
 
 export class CidrMatchUtil {
@@ -192,8 +202,8 @@ export class CidrMatchUtil {
   /*
    * True when the rule's populated criteria all match the target. A CIDR
    * criterion matches the target's ip; a hostname pattern matches the
-   * hostname, the SNMP sysName, or the device's display name — see
-   * RuleMatchTarget. A rule with no criteria never matches.
+   * hostname, the SNMP sysName, the device's display name, or its DNS name —
+   * see RuleMatchTarget. A rule with no criteria never matches.
    */
   public static ruleMatches(
     rule: AssignmentRuleCandidate,
@@ -234,11 +244,8 @@ export class CidrMatchUtil {
     }
 
     if (hasPattern) {
-      const candidates: Array<string | null | undefined> = [
-        target.hostname,
-        target.sysName,
-        target.name,
-      ];
+      const candidates: Array<string | null | undefined> =
+        CidrMatchUtil.getNameCandidates(target);
 
       const matchesAnyName: boolean = candidates.some(
         (candidate: string | null | undefined) => {
@@ -260,6 +267,19 @@ export class CidrMatchUtil {
     return true;
   }
 
+  /*
+   * The name-ish attributes a hostname pattern is tried against, in one place
+   * so the legacy column path and the criteria path can never disagree about
+   * which names count: a device that matched a rule stored as a plain
+   * `hostnamePattern` column must match the same pattern once the rule is
+   * re-saved as criteria. See RuleMatchTarget for why each attribute is here.
+   */
+  private static getNameCandidates(
+    target: RuleMatchTarget,
+  ): Array<string | null | undefined> {
+    return [target.hostname, target.sysName, target.name, target.dnsName];
+  }
+
   private static matchesConfiguredFilter(
     filter: RuleCriteriaFilter,
     target: RuleMatchTarget,
@@ -286,11 +306,16 @@ export class CidrMatchUtil {
       return false;
     }
 
-    const candidates: Array<string> = [
-      target.hostname,
-      target.sysName,
-      target.name,
-    ].filter((candidate: string | null | undefined): candidate is string => {
+    /*
+     * Every operator below is phrased over the same candidate list, and the
+     * negated ones mean "NO candidate matches" rather than "some candidate
+     * does not match". That is what keeps adding `dnsName` safe: a device
+     * whose FQDN contains "printer" is still excluded by a DoesNotContain
+     * "printer" rule after it is renamed to its short hostname.
+     */
+    const candidates: Array<string> = CidrMatchUtil.getNameCandidates(
+      target,
+    ).filter((candidate: string | null | undefined): candidate is string => {
       return typeof candidate === "string";
     });
     const expectedLower: string = expected.toLocaleLowerCase();

package/Utils/Project/DataResidency.ts

@@ -0,0 +1,63 @@
+import ColumnLength from "../../Types/Database/ColumnLength";
+import BadDataException from "../../Types/Exception/BadDataException";
+
+/*
+ * Project.dataResidency is a free-text label a master admin puts on a SaaS
+ * project - "EU (Frankfurt)", "US East" - to record where the customer's data
+ * is meant to live. Today it is informational only: nothing routes data by it.
+ *
+ * The rules live here rather than in ProjectService so that the server, which
+ * stores the value, and the dashboard, which decides whether to show it,
+ * cannot disagree about what "not set" means.
+ */
+export default class DataResidencyUtil {
+  // Project.dataResidency is a ShortText column.
+  public static readonly MAX_LENGTH: number = ColumnLength.ShortText;
+
+  /*
+   * Surrounding whitespace is dropped, and a value that is nothing but
+   * whitespace is stored as null. Without that, clearing the field in a form
+   * could store "" or "  ", which the dashboard would have to treat as unset
+   * anyway - and any query for projects without a residency would miss them.
+   */
+  public static normalize(value: unknown): string | null {
+    if (value === null || value === undefined) {
+      return null;
+    }
+
+    if (typeof value !== "string") {
+      throw new BadDataException("Data residency must be text.");
+    }
+
+    const trimmed: string = value.trim();
+
+    if (!trimmed) {
+      return null;
+    }
+
+    if (trimmed.length > DataResidencyUtil.MAX_LENGTH) {
+      throw new BadDataException(
+        `Data residency cannot be more than ${DataResidencyUtil.MAX_LENGTH} characters.`,
+      );
+    }
+
+    return trimmed;
+  }
+
+  public static isSet(value: unknown): boolean {
+    return typeof value === "string" && value.trim().length > 0;
+  }
+
+  /*
+   * Data residency only means something on a server that bills - a
+   * self-hosted install is wherever its operator put it. The project settings
+   * page shows the row only when both hold, so a project with no residency
+   * shows no empty "Data Residency" row.
+   */
+  public static shouldShowInProjectSettings(data: {
+    isBillingEnabled: boolean;
+    dataResidency: unknown;
+  }): boolean {
+    return data.isBillingEnabled && DataResidencyUtil.isSet(data.dataResidency);
+  }
+}

package/Utils/Rules/RuleRunSummary.ts

@@ -0,0 +1,323 @@
+import {
+  RuleRunAction,
+  RuleRunResult,
+  RuleRunType,
+  RuleRunTypeMetadata,
+  RuleRunTypeUtil,
+} from "../../Types/Rules/RuleRun";
+
+/*
+ * The sentences a rule run shows: before it starts, while it is chaining
+ * passes, and once it is done.
+ *
+ * Pure and dependency-free on purpose. A run that changes nothing is the
+ * common case once a rule has been run - "matched 40, added 0" with no reason
+ * reads as a broken button - so how each outcome is phrased is the part of
+ * this feature that most needs every branch pinned by a test.
+ */
+
+function count(value: number, singular: string, plural: string): string {
+  return `${value} ${value === 1 ? singular : plural}`;
+}
+
+function resources(value: number, meta: RuleRunTypeMetadata): string {
+  return count(value, meta.resourceSingular, meta.resourcePlural);
+}
+
+// "was" / "were", agreeing with a count.
+function wasOrWere(value: number): string {
+  return value === 1 ? "was" : "were";
+}
+
+function capitalize(text: string): string {
+  return text.charAt(0).toUpperCase() + text.slice(1);
+}
+
+export default class RuleRunSummary {
+  // What the confirmation modal says the run is about to do.
+  public static describeConfirmation(ruleType: RuleRunType): string {
+    const meta: RuleRunTypeMetadata = RuleRunTypeUtil.getMetadata(ruleType);
+
+    switch (meta.action) {
+      case RuleRunAction.AddLabels:
+        return `Evaluate this rule against the ${meta.resourcePlural} that already exist in this project and attach its labels to the ones it matches. Label rules normally only run when a ${meta.resourceSingular} is created, so this is how a rule reaches ${meta.resourcePlural} that existed before it was written.\n\nLabels are only added, never removed, so running this more than once is safe.`;
+      case RuleRunAction.AddOwners:
+        return `Evaluate this rule against the ${meta.resourcePlural} that already exist in this project and add its owners to the ones it matches. Owner rules normally only run when a ${meta.resourceSingular} is created, so this is how a rule reaches ${meta.resourcePlural} that existed before it was written.\n\nOwners are only added, never removed, and owners who are already assigned are skipped, so running this more than once is safe.`;
+      case RuleRunAction.MarkPrivate:
+        return `Evaluate this rule against the ${meta.resourcePlural} that already exist in this project and make the ones it matches private. Privacy rules normally only run when a ${meta.resourceSingular} is created, so this is how a rule reaches ${meta.resourcePlural} that existed before it was written.\n\nNothing is ever made public again by a run, so running this more than once is safe.`;
+      case RuleRunAction.SyncStatusPageMonitors:
+        return "Re-evaluate this rule against every monitor in the project: monitors it matches are added to this status page, and monitors it added earlier that no longer match are removed. Monitors added to the page by hand are never touched.\n\nRules already re-sync when they are saved, so use this to pick up changes the page missed.";
+      case RuleRunAction.SyncSloMonitors:
+        /*
+         * Says "this SLO's enabled monitor rules", not "this rule": membership
+         * is a union, so the sync evaluates every enabled rule of the SLO
+         * together, and promising one rule's effect would misdescribe it.
+         */
+        return "Re-evaluate this SLO's enabled monitor rules against every monitor in the project: monitors any of them matches are attached to this SLO, and monitors the rules attached earlier that none of them matches any more are detached. Monitors attached to the SLO by hand are never touched.\n\nRules already re-sync the SLO when they are saved, so use this to pick up changes the SLO missed.";
+    }
+  }
+
+  // The sentence beside "Run Now" on a rule's own view page.
+  public static describeRunNowCard(ruleType: RuleRunType): string {
+    const meta: RuleRunTypeMetadata = RuleRunTypeUtil.getMetadata(ruleType);
+
+    if (meta.action === RuleRunAction.SyncStatusPageMonitors) {
+      return "Re-sync this status page with this rule now: add the monitors it matches and remove the ones it added that no longer match.";
+    }
+
+    if (meta.action === RuleRunAction.SyncSloMonitors) {
+      return "Re-sync this SLO's monitors now: attach the monitors its enabled rules match and detach the ones the rules attached that no longer match. Monitors attached by hand are left alone.";
+    }
+
+    return `This rule runs automatically only when a ${meta.resourceSingular} is created. Run it now to apply it to the ${meta.resourcePlural} that already exist in this project.`;
+  }
+
+  /*
+   * The confirmation for running several rules from the table's bulk actions.
+   * A bulk run cannot ask the per-run notification question, so for owner
+   * rules it says plainly that it adds owners silently.
+   */
+  public static describeBulkConfirmation(data: {
+    ruleType: RuleRunType;
+    ruleCount: number;
+  }): string {
+    const meta: RuleRunTypeMetadata = RuleRunTypeUtil.getMetadata(
+      data.ruleType,
+    );
+    const rules: string = count(
+      data.ruleCount,
+      "selected rule",
+      "selected rules",
+    );
+
+    if (meta.action === RuleRunAction.SyncStatusPageMonitors) {
+      return `Re-sync this status page against ${rules}? Each rule adds the monitors it matches and removes the monitors it added that no longer match. Monitors added by hand are never touched.`;
+    }
+
+    if (meta.action === RuleRunAction.SyncSloMonitors) {
+      return `Re-sync this SLO's monitors for ${rules}? Each run re-evaluates all of this SLO's enabled monitor rules together, so after the first one the rest usually find nothing to change. Monitors attached by hand are never touched, and disabled rules are skipped with an error.`;
+    }
+
+    const lines: Array<string> = [
+      `Run ${rules} against the ${meta.resourcePlural} that already exist in this project? Each rule is applied the same way it is when a ${meta.resourceSingular} is created, and disabled rules are skipped with an error.`,
+    ];
+
+    if (meta.action === RuleRunAction.AddOwners) {
+      lines.push(
+        "Owners added by a bulk run are not notified. To notify them, run a single rule from its page instead.",
+      );
+    }
+
+    return lines.join(" ");
+  }
+
+  // The line shown while a run is still chaining passes.
+  public static describeProgress(data: {
+    ruleType: RuleRunType;
+    result: RuleRunResult;
+  }): string {
+    const meta: RuleRunTypeMetadata = RuleRunTypeUtil.getMetadata(
+      data.ruleType,
+    );
+
+    return `Evaluated ${resources(
+      data.result.resourcesEvaluated,
+      meta,
+    )} so far, and updated ${data.result.resourcesUpdated}. Still running — leave this open.`;
+  }
+
+  // The report once a run is done.
+  public static describe(data: {
+    ruleType: RuleRunType;
+    result: RuleRunResult;
+  }): string {
+    const meta: RuleRunTypeMetadata = RuleRunTypeUtil.getMetadata(
+      data.ruleType,
+    );
+    const result: RuleRunResult = data.result;
+
+    if (meta.action === RuleRunAction.SyncStatusPageMonitors) {
+      return RuleRunSummary.describeStatusPageSync(result);
+    }
+
+    if (meta.action === RuleRunAction.SyncSloMonitors) {
+      return RuleRunSummary.describeSloSync(result);
+    }
+
+    const lines: Array<string> = [];
+
+    /*
+     * Matched resources that neither changed nor failed already had what the
+     * rule adds. Reported separately because "nothing to do" and "could not
+     * do it" call for opposite reactions.
+     */
+    const alreadyApplied: number = Math.max(
+      result.resourcesMatched -
+        result.resourcesUpdated -
+        result.resourcesFailed,
+      0,
+    );
+
+    const matchedOutOf: string = `This rule matched ${resources(
+      result.resourcesMatched,
+      meta,
+    )} out of the ${resources(result.resourcesEvaluated, meta)} it looked at.`;
+
+    if (meta.action === RuleRunAction.AddLabels) {
+      if (result.resourcesUpdated > 0) {
+        lines.push(
+          `Added labels to ${resources(result.resourcesUpdated, meta)} (${count(
+            result.itemsAdded,
+            "label",
+            "labels",
+          )} attached).`,
+        );
+
+        if (alreadyApplied > 0) {
+          lines.push(
+            `${capitalize(resources(alreadyApplied, meta))} already had this rule's labels.`,
+          );
+        }
+      } else {
+        lines.push(`No labels were attached. ${matchedOutOf}`);
+
+        if (alreadyApplied > 0) {
+          lines.push(
+            `Every matching ${meta.resourceSingular} already has this rule's labels, so there was nothing to add.`,
+          );
+        }
+      }
+    }
+
+    if (meta.action === RuleRunAction.AddOwners) {
+      if (result.resourcesUpdated > 0) {
+        lines.push(
+          `Added owners to ${resources(result.resourcesUpdated, meta)} (${count(
+            result.itemsAdded,
+            "owner",
+            "owners",
+          )} assigned).`,
+        );
+
+        lines.push(
+          result.ownersNotified
+            ? "The added owners will be notified."
+            : "The added owners were not notified.",
+        );
+
+        if (alreadyApplied > 0) {
+          lines.push(
+            `${capitalize(resources(alreadyApplied, meta))} already had this rule's owners.`,
+          );
+        }
+      } else {
+        lines.push(`No owners were added. ${matchedOutOf}`);
+
+        if (alreadyApplied > 0) {
+          lines.push(
+            `Every matching ${meta.resourceSingular} already has this rule's owners, so there was nothing to add.`,
+          );
+        }
+      }
+    }
+
+    if (meta.action === RuleRunAction.MarkPrivate) {
+      if (result.resourcesUpdated > 0) {
+        lines.push(`Made ${resources(result.resourcesUpdated, meta)} private.`);
+
+        if (alreadyApplied > 0) {
+          lines.push(
+            `${capitalize(resources(alreadyApplied, meta))} ${wasOrWere(
+              alreadyApplied,
+            )} already private.`,
+          );
+        }
+      } else {
+        lines.push(
+          `No ${meta.resourcePlural} were made private. ${matchedOutOf}`,
+        );
+
+        if (alreadyApplied > 0) {
+          lines.push(
+            `Every matching ${meta.resourceSingular} is already private, so there was nothing to change.`,
+          );
+        }
+      }
+    }
+
+    if (result.resourcesFailed > 0) {
+      lines.push(
+        `${capitalize(resources(result.resourcesFailed, meta))} could not be updated. Check the server logs for the reason.`,
+      );
+    }
+
+    if (result.isTruncated) {
+      lines.push(
+        `The run stopped after evaluating ${resources(
+          result.resourcesEvaluated,
+          meta,
+        )} so that it stays bounded. Run the rule again to continue - ${meta.resourcePlural} it already updated are skipped.`,
+      );
+    }
+
+    return lines.join(" ");
+  }
+
+  private static describeStatusPageSync(result: RuleRunResult): string {
+    const monitors: (value: number) => string = (value: number): string => {
+      return count(value, "monitor", "monitors");
+    };
+
+    const changes: Array<string> = [];
+
+    if (result.itemsAdded > 0) {
+      changes.push(`added ${monitors(result.itemsAdded)} to the status page`);
+    }
+
+    if (result.itemsRemoved > 0) {
+      changes.push(
+        `removed ${monitors(result.itemsRemoved)} this rule no longer matches`,
+      );
+    }
+
+    if (result.resourcesUpdated > 0) {
+      changes.push(
+        `refreshed the display settings of ${monitors(result.resourcesUpdated)}`,
+      );
+    }
+
+    if (changes.length === 0) {
+      return "The status page already matches this rule, so nothing changed.";
+    }
+
+    return `${capitalize(changes.join(", "))}.`;
+  }
+
+  /*
+   * An SLO sync attaches and detaches monitors and has nothing else to
+   * refresh, so resourcesUpdated is not reported: the run never sets it.
+   */
+  private static describeSloSync(result: RuleRunResult): string {
+    const monitors: (value: number) => string = (value: number): string => {
+      return count(value, "monitor", "monitors");
+    };
+
+    const changes: Array<string> = [];
+
+    if (result.itemsAdded > 0) {
+      changes.push(`attached ${monitors(result.itemsAdded)} to the SLO`);
+    }
+
+    if (result.itemsRemoved > 0) {
+      changes.push(
+        `detached ${monitors(result.itemsRemoved)} that no enabled rule matches any more`,
+      );
+    }
+
+    if (changes.length === 0) {
+      return "The SLO's monitors already match its enabled rules, so nothing changed.";
+    }
+
+    return `${capitalize(changes.join(", "))}.`;
+  }
+}

package/Utils/Slo/SloAffectedResourceMarkdown.ts

@@ -0,0 +1,123 @@
+import URL from "../../Types/API/URL";
+import ObjectID from "../../Types/ObjectID";
+import { escapeMarkdownInline } from "../Markdown/MarkdownEscape";
+
+/*
+ * The SLO bullets under "Resources Affected" in an incident's or alert's
+ * "created" feed item: `- [SLO <name>](<dashboard link>)`, one per SLO the
+ * record is linked to.
+ *
+ * Why this lives here and not on ServiceLevelObjectiveService: the services
+ * that write those feed items cannot import it. ServiceLevelObjectiveService
+ * imports ServiceLevelObjectiveBurnRateRuleService, which imports
+ * IncidentService and AlertService to resolve burn-rate outputs, so the link
+ * is built from the dashboard URL the caller already has. The route and the
+ * `SLO <name>` wording match ServiceLevelObjectiveService.getSloLinkInDashboard
+ * and getSloMarkdownLink exactly, and a test pins that, so an SLO reads the
+ * same in every feed.
+ *
+ * The name is escaped exactly once, here, at the point it becomes markdown:
+ * feeds render without safe mode, and a name like `x](https://evil)` must not
+ * be able to re-point the link or restyle the sentence.
+ */
+
+/*
+ * Structural rather than the ServiceLevelObjective model, so this stays a
+ * dependency-free helper. A relation select on Incident / Alert yields
+ * exactly these columns; all three are readable on relation queries.
+ *
+ * projectId is required for a bullet to print: see
+ * getSloAffectedResourceMarkdownLines.
+ */
+export interface SloAffectedResourceLinkSubject {
+  _id?: string | undefined;
+  name?: string | undefined;
+  projectId?: ObjectID | string | undefined | null;
+}
+
+export type GetSloDashboardUrlFunction = (data: {
+  dashboardUrl: URL;
+  projectId: ObjectID;
+  sloId: ObjectID | string;
+}) => URL;
+
+export const getSloDashboardUrl: GetSloDashboardUrlFunction = (data: {
+  dashboardUrl: URL;
+  projectId: ObjectID;
+  sloId: ObjectID | string;
+}): URL => {
+  /*
+   * URL.addRoute mutates and returns the same instance, so start from a copy:
+   * the caller's dashboard URL is reused for every bullet.
+   */
+  return URL.fromString(data.dashboardUrl.toString()).addRoute(
+    `/${data.projectId.toString()}/slos/${data.sloId.toString()}`,
+  );
+};
+
+export type GetSloAffectedResourceMarkdownLinesFunction = (data: {
+  dashboardUrl: URL;
+  projectId: ObjectID;
+  serviceLevelObjectives:
+    | Array<SloAffectedResourceLinkSubject>
+    | undefined
+    | null;
+}) => Array<string>;
+
+export const getSloAffectedResourceMarkdownLines: GetSloAffectedResourceMarkdownLinesFunction =
+  (data: {
+    dashboardUrl: URL;
+    projectId: ObjectID;
+    serviceLevelObjectives:
+      | Array<SloAffectedResourceLinkSubject>
+      | undefined
+      | null;
+  }): Array<string> => {
+    const lines: Array<string> = [];
+    const seenSloIds: Set<string> = new Set<string>();
+
+    for (const slo of data.serviceLevelObjectives || []) {
+      const sloId: string = slo?._id?.toString() || "";
+
+      /*
+       * A row without an id cannot be linked, and the relation cannot hold
+       * one twice - skipping both keeps a malformed payload from printing a
+       * dead link or a duplicate bullet.
+       */
+      if (!sloId || seenSloIds.has(sloId)) {
+        continue;
+      }
+
+      /*
+       * Only an SLO of the record's own project is named. The callers read
+       * the record as root, so a link to another project's SLO would put
+       * that SLO's name into this project's feed (and Slack / Teams). The
+       * write hooks reject such links now, but rows saved before that check
+       * existed may still hold one. An SLO whose project was not read cannot
+       * be shown to belong here, so it is left out too; that also makes a
+       * caller that drops projectId from its select fail loudly in its tests
+       * rather than quietly lose the pin.
+       */
+      if (
+        !slo.projectId ||
+        slo.projectId.toString().trim().toLowerCase() !==
+          data.projectId.toString().trim().toLowerCase()
+      ) {
+        continue;
+      }
+
+      seenSloIds.add(sloId);
+
+      const escapedName: string = escapeMarkdownInline(slo.name).trim();
+      const linkText: string = escapedName ? `SLO ${escapedName}` : "SLO";
+      const link: URL = getSloDashboardUrl({
+        dashboardUrl: data.dashboardUrl,
+        projectId: data.projectId,
+        sloId: sloId,
+      });
+
+      lines.push(`- [${linkText}](${link.toString()})`);
+    }
+
+    return lines;
+  };