@morscherlab/mint-sdk 1.2.0-beta.3 → 1.2.0-beta.4

package/src/composables/autoGroup/replicatePreGroup.ts

@@ -0,0 +1,124 @@
+/**
+ * Replicate pre-grouping.
+ *
+ * Strip the replicate / injection-number markers from each sample's name, then
+ * collapse samples that share a base name. Those samples ARE replicates of one
+ * another by definition; the remaining unique base names are what the rest of
+ * the pipeline (tokenize → classify → schema → compose) should operate on.
+ *
+ * This pre-pass replaces the older "treat every sample as independent, then
+ * infer replicate columns" approach. Identifying replicate-equivalence by name
+ * before tokenisation removes a class of fragile cardinality heuristics.
+ */
+
+import type { TreeNode } from '../../types/componentLabTypes'
+import vocabData from './vocab.json'
+
+const STRIP_PATTERNS: RegExp[] = (vocabData.replicateStripPatterns as string[]).map(
+  src => new RegExp(src, 'gi'),
+)
+
+/**
+ * Iteratively strip every replicate / injection-number marker from `name`.
+ * Each pattern is applied repeatedly until it stops matching, so a sample like
+ * `study_T1_Rep2_004` collapses to `study` in one call.
+ */
+export function stripReplicateTokens(name: string): string {
+  let base = name
+  for (const re of STRIP_PATTERNS) {
+    let prev
+    do {
+      prev = base
+      base = base.replace(re, '')
+      re.lastIndex = 0
+    } while (base !== prev)
+  }
+  return base
+}
+
+export interface ReplicatePreGrouping {
+  /** Unique base names in first-seen order. Length === `originalSamples.length` only if every sample has a distinct base. */
+  baseNames: string[]
+  /**
+   * `membersByBase[i]` = original-sample indices that collapsed onto `baseNames[i]`.
+   * Length of each entry is the replicate count for that base.
+   */
+  membersByBase: number[][]
+  /** Original sample names indexed by their position in `samples`. Retained so the compose layer can expand groups back to originals. */
+  originalSamples: string[]
+}
+
+export function preGroupReplicates(samples: string[]): ReplicatePreGrouping {
+  const map = new Map<string, number[]>()
+  const baseOrder: string[] = []
+  for (let i = 0; i < samples.length; i++) {
+    const base = stripReplicateTokens(samples[i])
+    const bucket = map.get(base)
+    if (bucket) {
+      bucket.push(i)
+    } else {
+      map.set(base, [i])
+      baseOrder.push(base)
+    }
+  }
+  return {
+    baseNames: baseOrder,
+    membersByBase: baseOrder.map(b => map.get(b)!),
+    originalSamples: samples,
+  }
+}
+
+/**
+ * Expand groups produced over base names back to groups of original sample
+ * names. Each entry in `group.samples` is treated as a base name and replaced
+ * by the list of original samples that collapsed onto it.
+ */
+export function expandGroupsWithReplicates<G extends { samples: string[] }>(
+  groups: G[],
+  preGrouping: ReplicatePreGrouping,
+): G[] {
+  const baseToMembers = new Map<string, number[]>()
+  for (let i = 0; i < preGrouping.baseNames.length; i++) {
+    baseToMembers.set(preGrouping.baseNames[i], preGrouping.membersByBase[i])
+  }
+  return groups.map(g => ({
+    ...g,
+    samples: g.samples.flatMap(baseName => {
+      const indices = baseToMembers.get(baseName)
+      return indices ? indices.map(i => preGrouping.originalSamples[i]) : [baseName]
+    }),
+  }))
+}
+
+/**
+ * Expand a group hierarchy (built over base names) back to original samples.
+ * Each leaf node's `label` is a base name; it is replaced by one leaf per
+ * original sample that collapsed onto it (sharing the leaf's injection badge,
+ * since collapsed replicates have identical base tokens). Every ancestor's
+ * `badge` (sample count) is recomputed from the expanded leaf count so the tree
+ * agrees with the flat groups produced by `expandGroupsWithReplicates`.
+ */
+export function expandTreeWithReplicates(
+  nodes: TreeNode[],
+  preGrouping: ReplicatePreGrouping,
+): TreeNode[] {
+  const baseToOriginals = new Map<string, string[]>()
+  for (let i = 0; i < preGrouping.baseNames.length; i++) {
+    baseToOriginals.set(
+      preGrouping.baseNames[i],
+      preGrouping.membersByBase[i].map(m => preGrouping.originalSamples[m]),
+    )
+  }
+  const leafCount = (n: TreeNode): number =>
+    n.children && n.children.length ? n.children.reduce((acc, c) => acc + leafCount(c), 0) : 1
+  const expand = (node: TreeNode): TreeNode[] => {
+    if (node.children && node.children.length) {
+      const children = node.children.flatMap(expand)
+      return [{ ...node, children, badge: children.reduce((acc, c) => acc + leafCount(c), 0) }]
+    }
+    const originals = baseToOriginals.get(node.label)
+    if (!originals || originals.length === 0) return [node]
+    return originals.map((name, k) => ({ ...node, id: `${node.id}
${k}`, label: name }))
+  }
+  return nodes.flatMap(expand)
+}

package/src/composables/autoGroup/template.ts

@@ -0,0 +1,126 @@
+import type { ClassSchema, ColumnInfo, SampleClass } from '../../types/auto-group'
+import { classKey } from './classKey'
+
+export interface TemplateOptions {
+  mode: 'blank' | 'prefilled'
+  format: 'csv' | 'tsv'
+  /** For prefilled mode. Indexed parallel to `samples`. */
+  tokenizedSamples?: string[][]
+  /** Used to compute the filename; omitted → falls back to `sample_metadata_<date>`. */
+  experimentCode?: string
+  /** Override the blank-mode suggested headers. Defaults to ['group','class','replicate','notes']. */
+  suggestedColumns?: string[]
+}
+
+const DEFAULT_BLANK_HEADERS = ['group', 'class', 'replicate', 'notes']
+
+function rfc4180Quote(cell: string): string {
+  if (/[",\n]/.test(cell)) {
+    return `"${cell.replace(/"/g, '""')}"`
+  }
+  return cell
+}
+
+function joinRow(cells: string[], sep: string): string {
+  return sep === ','
+    ? cells.map(rfc4180Quote).join(',')
+    : cells.join('\t')
+}
+
+function today(): string {
+  return new Date().toISOString().slice(0, 10)
+}
+
+export function composeTemplate(
+  samples: string[],
+  schemas: ClassSchema[] | null,
+  classes: SampleClass[] | null,
+  options: TemplateOptions,
+): { content: string; filename: string } {
+  const sep = options.format === 'tsv' ? '\t' : ','
+  const ext = options.format === 'tsv' ? 'tsv' : 'csv'
+
+  const stem = options.experimentCode ? `${options.experimentCode}_metadata` : 'sample_metadata'
+  const filename = `${stem}_${today()}.${ext}`
+
+  if (options.mode === 'blank' || !schemas || !classes) {
+    const headers = ['sample_name', ...(options.suggestedColumns ?? DEFAULT_BLANK_HEADERS)]
+    const rows = samples.map(s => {
+      const r = [s, ...Array(headers.length - 1).fill('')]
+      return joinRow(r, sep)
+    })
+    return { content: [joinRow(headers, sep), ...rows].join('\n'), filename }
+  }
+
+  // Prefilled mode: union of all class columns, wide layout.
+  const tokenized = options.tokenizedSamples ?? []
+  const allColumns: { schemaKey: string; colName: string }[] = []
+
+  // Hoist: build lookup maps before the per-sample loop.
+  const sampleToClass = new Map<number, SampleClass>()
+  for (const cls of classes) for (const m of cls.members) sampleToClass.set(m, cls)
+
+  const schemaByKey = new Map<string, ClassSchema>()
+  for (const s of schemas) {
+    const k = classKey({ kind: s.classKind, subKind: s.subKind, tokenLength: s.tokenLength })
+    schemaByKey.set(k, s)
+  }
+
+  const colByNameByKey = new Map<string, Map<string, ColumnInfo>>()
+  const groupBySetByKey = new Map<string, Set<number>>()
+  for (const s of schemas) {
+    const k = classKey({ kind: s.classKind, subKind: s.subKind, tokenLength: s.tokenLength })
+    const m = new Map<string, ColumnInfo>()
+    for (const c of s.columns) m.set(c.displayName ?? c.name, c)
+    colByNameByKey.set(k, m)
+    groupBySetByKey.set(k, new Set(s.groupBy))
+    // Collect allColumns with dedup via Set
+    const seenColNames = new Set<string>()
+    for (const c of s.columns) {
+      const name = c.displayName ?? c.name
+      if (!seenColNames.has(name)) {
+        seenColNames.add(name)
+        if (!allColumns.some(x => x.colName === name)) {
+          allColumns.push({ schemaKey: k, colName: name })
+        }
+      }
+    }
+  }
+
+  const headers = ['sample_name', 'class', ...allColumns.map(c => c.colName), 'group', 'notes']
+
+  const rows: string[] = []
+  for (let i = 0; i < samples.length; i++) {
+    const cls = sampleToClass.get(i)
+    const classLabel = cls?.label ?? ''
+    const tokens = tokenized[i] ?? []
+    const cells: string[] = [samples[i], classLabel]
+
+    if (cls) {
+      const k = classKey(cls)
+      const groupBySet = groupBySetByKey.get(k)
+      const colByName: Map<string, ColumnInfo> | undefined = colByNameByKey.get(k)
+      const keyParts: string[] = []
+      for (const col of allColumns) {
+        if (col.schemaKey === k && colByName) {
+          const schemaCol = colByName.get(col.colName)
+          const raw =
+            schemaCol?.sourceIndices.map(idx => tokens[idx] ?? '').join('_') ?? ''
+          cells.push(raw)
+          if (schemaCol && groupBySet?.has(schemaCol.index)) keyParts.push(raw)
+        } else {
+          cells.push('')
+        }
+      }
+      cells.push(keyParts.join(' / '))
+    } else {
+      for (const _ of allColumns) cells.push('')
+      cells.push('')
+    }
+
+    cells.push('') // notes
+    rows.push(joinRow(cells, sep))
+  }
+
+  return { content: [joinRow(headers, sep), ...rows].join('\n'), filename }
+}

package/src/composables/autoGroup/tokenLength.ts

@@ -0,0 +1,53 @@
+import type { SampleClass } from '../../types/auto-group'
+
+/**
+ * Token-length pre-grouping.
+ *
+ * After type classification (`detectClass`), members of one class can still have
+ * different token counts — e.g. a Plasma batch where some names carry an extra
+ * descriptor field. Splitting each class so every member shares the same token
+ * length is the "group same token-length sample, then extract tokens inside the
+ * group" step: it guarantees `buildClassSchema` sees a rectangular token matrix,
+ * so column index N means the same field for every sample in the group.
+ *
+ * Each output class carries `tokenLength`; `classKey` folds that into the schema
+ * key so length-split classes never collide. The label only gains a `· N fields`
+ * suffix when a (kind, subKind) genuinely spans more than one length, keeping the
+ * common (uniform) case visually identical to before.
+ */
+export function splitByTokenLength(
+  classes: SampleClass[],
+  tokenized: string[][],
+): SampleClass[] {
+  const out: SampleClass[] = []
+
+  for (const cls of classes) {
+    // Bucket members by token count, preserving first-seen order of lengths.
+    const byLength = new Map<number, number[]>()
+    const lengthOrder: number[] = []
+    for (const m of cls.members) {
+      const len = tokenized[m]?.length ?? 0
+      const bucket = byLength.get(len)
+      if (bucket) {
+        bucket.push(m)
+      } else {
+        byLength.set(len, [m])
+        lengthOrder.push(len)
+      }
+    }
+
+    const multipleLengths = lengthOrder.length > 1
+    for (const len of lengthOrder) {
+      out.push({
+        ...cls,
+        members: byLength.get(len)!,
+        tokenLength: len,
+        // Drop class-tag positions that fall outside this split's token range.
+        classTagPositions: cls.classTagPositions.filter(p => p < len),
+        label: multipleLengths ? `${cls.label} · ${len} fields` : cls.label,
+      })
+    }
+  }
+
+  return out
+}

package/src/composables/autoGroup/tokenize.ts

@@ -0,0 +1,41 @@
+const DELIMITER_CANDIDATES = ['_', '-', '.'] as const
+export type Delimiter = (typeof DELIMITER_CANDIDATES)[number]
+
+/** Pick the delimiter whose split produces the most consistent field count across `lines`. */
+export function pickPrimaryDelimiter(lines: string[]): Delimiter {
+  if (lines.length === 0) return '_'
+
+  let best: Delimiter = '_'
+  let bestScore = -1
+
+  for (const candidate of DELIMITER_CANDIDATES) {
+    const counts = lines.map(l => l.split(candidate).length)
+    const frequency = new Map<number, number>()
+    for (const c of counts) frequency.set(c, (frequency.get(c) ?? 0) + 1)
+
+    // Mode and its frequency
+    let mode = 1
+    let modeFreq = 0
+    for (const [c, f] of frequency) {
+      if (f > modeFreq || (f === modeFreq && c > mode)) {
+        mode = c
+        modeFreq = f
+      }
+    }
+
+    // A delimiter that produces field count 1 didn't split anything — score 0.
+    const score = mode > 1 ? modeFreq / lines.length : 0
+    if (score > bestScore) {
+      best = candidate
+      bestScore = score
+    }
+  }
+
+  return best
+}
+
+/** Split a single sample name on `delimiter`. Empty input returns `['']` so callers
+ *  always receive at least one token. */
+export function splitMulti(name: string, delimiter: Delimiter): string[] {
+  return name.split(delimiter)
+}

package/src/composables/autoGroup/vocab.json

@@ -0,0 +1,66 @@
+{
+  "$schema": "./vocab.schema.json",
+  "_doc": {
+    "purpose": "Sample-name classification vocabulary for the auto-group pipeline. Edit this file to teach the classifier new sample types or matrices without changing TypeScript. All matching is case-insensitive unless a pattern's regex flags say otherwise.",
+    "patterns": "Regex source strings (no surrounding slashes). Compiled with the `i` flag at load time.",
+    "standardAllow": "Tokens that should be classified as Standard even when they don't match `patterns.standard`. Case-sensitive — use the exact spelling that appears in your filenames.",
+    "matrixVocab": "Lowercase token → canonical display name. Tokens are normalised to lowercase before lookup, so adding 'tissues' handles 'Tissues' / 'TISSUES' / 'tissues' uniformly. Multiple aliases map to one canonical (e.g. cell + cells → Cells).",
+    "ionizationModes": "Lowercase polarity tokens (pos / positive / neg / negative). Suffixed to the subKind so POS and NEG acquisitions get independent schemas.",
+    "tissueParentTokens": "Tokens that flag the immediately-following token as the organ subKind (so `tissues / kidney` becomes Biological/Tissues, tagging both positions).",
+    "replicateStripPatterns": "Regex sources stripped from each sample name during the replicate pre-grouping pass. Samples whose stripped (base) names match are treated as replicates of one another and grouped together before tokenisation. Default set covers _T<n>, _B<n>, and _Rep<n> markers. The trailing injection / run-order number is intentionally NOT stripped here — it survives tokenisation and is surfaced as a 'run-order' column (named 'Injection #'), then excluded from the default group key so replicates still collapse."
+  },
+
+  "patterns": {
+    "blank":    "^(blank|blk|solv?blank|matrix.?blank)$",
+    "iqc":      "^iqc$",
+    "eqc":      "^eqc$",
+    "standard": "^(standard|std\\d*|cal(?:ibrator)?\\d*|.+standard)$",
+    "spikeIn":  "spike.?in",
+    "stock":    "^stock$"
+  },
+
+  "standardAllow": [
+    "ExtractionS",
+    "IS",
+    "internal.standard",
+    "PQC",
+    "pooledQC"
+  ],
+
+  "matrixVocab": {
+    "plasma":  "Plasma",
+    "serum":   "Serum",
+    "tissue":  "Tissue",
+    "tissues": "Tissues",
+    "kidney":  "Kidney",
+    "liver":   "Liver",
+    "tumor":   "Tumor",
+    "urine":   "Urine",
+    "brain":   "Brain",
+    "muscle":  "Muscle",
+    "adipose": "Adipose",
+    "csf":     "CSF",
+    "feces":   "Feces",
+    "faeces":  "Faeces",
+    "cells":   "Cells",
+    "cell":    "Cells",
+    "media":   "Media",
+    "medium":  "Medium",
+    "extract": "Extract"
+  },
+
+  "ionizationModes": {
+    "pos":      "POS",
+    "positive": "POS",
+    "neg":      "NEG",
+    "negative": "NEG"
+  },
+
+  "tissueParentTokens": ["tissue", "tissues"],
+
+  "replicateStripPatterns": [
+    "[_-]T\\d+(?=[_-]|$)",
+    "[_-]B\\d+(?=[_-]|$)",
+    "[_-](?:rep(?:licate)?)\\d+(?=[_-]|$)"
+  ]
+}

package/src/composables/autoGroupConstants.ts

@@ -0,0 +1,4 @@
+export const DEFAULT_COLORS = [
+  '#3B82F6', '#10B981', '#F59E0B', '#EF4444', '#8B5CF6',
+  '#EC4899', '#06B6D4', '#84CC16', '#F97316', '#6366F1',
+]

package/src/composables/autoGroupGrouping.ts

@@ -0,0 +1,148 @@
+import type {
+  AutoGroupResult,
+  ColumnInfo,
+  MetadataRow,
+  OutlierAction,
+  ParsedCsvData,
+} from '../types/auto-group'
+import type { SampleGroup } from '../types/components'
+import { DEFAULT_COLORS } from './autoGroupConstants'
+
+export function computeGroups(
+  allSamples: string[],
+  columns: ColumnInfo[],
+  enabledFields: Set<number>,
+  outlierActions: Map<number, OutlierAction>,
+  delimiter: string,
+  minFieldCount: number,
+): AutoGroupResult {
+  const excludedSamples: string[] = []
+  const qcSamples: string[] = []
+  const conformingSamples: string[] = []
+
+  for (let i = 0; i < allSamples.length; i++) {
+    const action = outlierActions.get(i)
+    if (action === 'exclude') {
+      excludedSamples.push(allSamples[i])
+    } else if (action === 'qc') {
+      qcSamples.push(allSamples[i])
+    } else {
+      conformingSamples.push(allSamples[i])
+    }
+  }
+
+  // Build group map
+  const groupMap = new Map<string, string[]>()
+  const metadata: MetadataRow[] = []
+  const enabledIndices = [...enabledFields].sort((a, b) => a - b)
+  const suffixCount = minFieldCount - 1
+
+  for (const sample of conformingSamples) {
+    const parts = sample.split(delimiter)
+    const splitAt = Math.max(1, parts.length - suffixCount)
+    const row = [
+      parts.slice(0, splitAt).join(delimiter),
+      ...parts.slice(splitAt),
+    ]
+
+    // Build group key from enabled columns
+    const keyParts: string[] = []
+    for (const idx of enabledIndices) {
+      if (idx < row.length && idx < columns.length) {
+        keyParts.push(row[idx])
+      }
+    }
+    const groupKey = keyParts.join(' / ')
+
+    const group = groupMap.get(groupKey)
+    if (group) {
+      group.push(sample)
+    } else {
+      groupMap.set(groupKey, [sample])
+    }
+
+    // Build metadata row with ALL columns
+    const fields: Record<string, string> = {}
+    for (const col of columns) {
+      if (col.index < row.length) {
+        fields[col.name] = row[col.index]
+      }
+    }
+    metadata.push({ sampleName: sample, fields, group: groupKey })
+  }
+
+  // Convert to SampleGroup[]
+  const groups: SampleGroup[] = []
+  let colorIdx = 0
+  for (const [name, samples] of groupMap) {
+    groups.push({
+      name,
+      color: DEFAULT_COLORS[colorIdx % DEFAULT_COLORS.length],
+      samples,
+    })
+    colorIdx++
+  }
+
+  // QC group
+  if (qcSamples.length > 0) {
+    groups.push({
+      name: 'QC',
+      color: '#6B7280',
+      samples: qcSamples,
+    })
+    for (const sample of qcSamples) {
+      metadata.push({ sampleName: sample, fields: {}, group: 'QC' })
+    }
+  }
+
+  return { groups, metadata, excludedSamples }
+}
+
+export function computeGroupsFromCsv(
+  csvData: ParsedCsvData,
+  columns: ColumnInfo[],
+  enabledFields: Set<number>,
+): AutoGroupResult {
+  const groupMap = new Map<string, string[]>()
+  const metadata: MetadataRow[] = []
+  const enabledCols = columns
+    .filter(c => enabledFields.has(c.index))
+    .sort((a, b) => a.index - b.index)
+
+  for (const row of csvData.rows) {
+    const sampleName = row[csvData.sampleColumn]
+
+    // Build group key from enabled CSV column values
+    // Use originalName for CSV row lookup (survives user renames), display name for group key
+    const keyParts = enabledCols.map(col => row[col.originalName ?? col.name])
+    const groupKey = keyParts.join(' / ')
+
+    const group = groupMap.get(groupKey)
+    if (group) {
+      group.push(sampleName)
+    } else {
+      groupMap.set(groupKey, [sampleName])
+    }
+
+    // Build metadata row with ALL columns - use display name as key, original for lookup
+    const fields: Record<string, string> = {}
+    for (const col of columns) {
+      fields[col.name] = row[col.originalName ?? col.name]
+    }
+    metadata.push({ sampleName, fields, group: groupKey })
+  }
+
+  // Convert to SampleGroup[]
+  const groups: SampleGroup[] = []
+  let colorIdx = 0
+  for (const [name, samples] of groupMap) {
+    groups.push({
+      name,
+      color: DEFAULT_COLORS[colorIdx % DEFAULT_COLORS.length],
+      samples,
+    })
+    colorIdx++
+  }
+
+  return { groups, metadata, excludedSamples: [] }
+}

package/src/composables/controlComponentBindings.ts

@@ -0,0 +1,80 @@
+import type {
+  ControlComponentBinding,
+  ControlComponentBindingConfig,
+  ControlComponentBindingRecordConfig,
+  ControlComponentBindingsById,
+  ControlComponentBindingsConfig,
+  ControlComponentPropsMap,
+  ControlComponentPropSource,
+} from './controlSchemaTypes'
+
+/** Map control workspace values into component props for direct `v-bind` usage. */
+export function controlValuesToComponentProps<TValues extends Record<string, unknown>>(
+  values: TValues,
+  mapping?: ControlComponentPropsMap<TValues>,
+): Record<string, unknown> {
+  if (mapping === undefined) return { ...values }
+
+  if (Array.isArray(mapping)) {
+    const props: Record<string, unknown> = {}
+    for (const key of mapping) {
+      props[key] = values[key]
+    }
+    return props
+  }
+
+  const props: Record<string, unknown> = {}
+  for (const [prop, source] of Object.entries(mapping) as Array<[string, ControlComponentPropSource<TValues>]>) {
+    props[prop] = typeof source === 'function' ? source(values) : values[source]
+  }
+  return props
+}
+
+/** Map control workspace values into named SDK component bindings for direct slot rendering. */
+export function controlValuesToComponentBindings<TValues extends Record<string, unknown>>(
+  values: TValues,
+  bindings?: ControlComponentBindingsConfig<TValues>,
+): ControlComponentBinding[] {
+  if (bindings === undefined) return []
+
+  return normalizeControlComponentBindingConfigs(bindings).map(binding => ({
+    id: binding.id,
+    component: binding.component,
+    props: controlValuesToComponentProps(values, binding.props),
+  }))
+}
+
+/** Map control workspace values into SDK component bindings keyed by binding id. */
+export function controlValuesToComponentBindingsById<TValues extends Record<string, unknown>>(
+  values: TValues,
+  bindings?: ControlComponentBindingsConfig<TValues>,
+): ControlComponentBindingsById {
+  return Object.fromEntries(
+    controlValuesToComponentBindings(values, bindings).map(binding => [binding.id, binding]),
+  )
+}
+
+function normalizeControlComponentBindingConfigs<TValues extends Record<string, unknown>>(
+  bindings: ControlComponentBindingsConfig<TValues>,
+): Array<Required<Pick<ControlComponentBindingConfig<TValues>, 'id' | 'component'>> & Pick<ControlComponentBindingConfig<TValues>, 'props'>> {
+  if (Array.isArray(bindings)) {
+    const usedIds = new Map<string, number>()
+    return bindings.map(binding => ({
+      id: uniqueComponentBindingId(binding.id ?? binding.component, usedIds),
+      component: binding.component,
+      props: binding.props,
+    }))
+  }
+
+  return Object.entries(bindings).map(([id, binding]: [string, ControlComponentBindingRecordConfig<TValues>]) => ({
+    id,
+    component: binding.component,
+    props: binding.props,
+  }))
+}
+
+function uniqueComponentBindingId(id: string, usedIds: Map<string, number>): string {
+  const count = usedIds.get(id) ?? 0
+  usedIds.set(id, count + 1)
+  return count === 0 ? id : `${id}-${count + 1}`
+}