@morscherlab/mint-sdk 1.0.0-rc.2 → 1.0.0-rc.5

package/src/__tests__/composables/autoGroup/columns.test.ts

@@ -0,0 +1,135 @@
+import { describe, it, expect } from 'vitest'
+import { inferRole, parseNumeric, buildClassSchema } from '../../../composables/autoGroup/columns'
+
+describe('parseNumeric', () => {
+  it('parses value+unit tokens', () => {
+    expect(parseNumeric('5nM')).toEqual({ value: 5, unit: 'nM', raw: '5nM' })
+    expect(parseNumeric('400ulES')).toEqual({ value: 400, unit: 'ulES', raw: '400ulES' })
+    expect(parseNumeric('1ul')).toEqual({ value: 1, unit: 'ul', raw: '1ul' })
+  })
+
+  it('decodes the dot-encoded decimal point', () => {
+    expect(parseNumeric('0dot5ul')).toEqual({ value: 0.5, unit: 'ul', raw: '0dot5ul' })
+  })
+
+  it('parses ratios via the dedicated branch', () => {
+    expect(parseNumeric('1to100')).toEqual({ value: 0.01, unit: 'ratio', raw: '1to100' })
+    expect(parseNumeric('1to10')).toEqual({ value: 0.1, unit: 'ratio', raw: '1to10' })
+  })
+
+  it('rejects bare IDs, dates, and pure numbers', () => {
+    expect(parseNumeric('M10')).toBeNull()
+    expect(parseNumeric('exp281')).toBeNull()
+    expect(parseNumeric('260415')).toBeNull()
+    expect(parseNumeric('123')).toBeNull()
+  })
+})
+
+describe('inferRole', () => {
+  const make = (values: string[]) => ({
+    values,
+    position: 0,
+    totalPositions: 1,
+    classSize: values.length,
+  })
+
+  it('returns constant when every value is the same', () => {
+    expect(inferRole(make(['exp281', 'exp281', 'exp281']))).toBe('constant')
+  })
+
+  it('returns run-order when trailing position has high-card numeric values', () => {
+    expect(inferRole({
+      values: ['001', '002', '003', '004', '005'],
+      position: 4,
+      totalPositions: 5,
+      classSize: 5,
+    })).toBe('run-order')
+  })
+
+  it('returns numeric when many distinct value+unit values are present', () => {
+    // 6+ distinct numeric levels read as numeric (binning candidates).
+    expect(inferRole(make(['1nM', '5nM', '10nM', '20nM', '50nM', '100nM']))).toBe('numeric')
+  })
+
+  it('returns factor for low-cardinality numerics (<=5 unique levels)', () => {
+    // 5min / 10min and similar small dose ladders read as factors by default;
+    // users opt into binning via the column popover for the cases that want it.
+    expect(inferRole(make(['5min', '10min']))).toBe('factor')
+    expect(inferRole(make(['5nM', '10nM', '20nM']))).toBe('factor')
+  })
+
+  it('returns replicate ONLY for explicit replicate-named tokens (rep1, Rep2, replicate3, R1)', () => {
+    // The replicate pre-grouping pass collapses real replicates by name
+    // before tokenisation, so the cardinality-based ID_PATTERN heuristic
+    // (M1, M2, …) was removed — those reach inferRole now only when they
+    // represent distinct conditions, and should be treated as factors.
+    expect(inferRole({
+      values: ['M1', 'M2', 'M3', 'M4', 'M5'],
+      position: 1,
+      totalPositions: 3,
+      classSize: 5,
+    })).toBe('factor')
+    expect(inferRole({
+      values: ['rep1', 'rep2', 'rep3'],
+      position: 1,
+      totalPositions: 3,
+      classSize: 3,
+    })).toBe('replicate')
+    expect(inferRole({
+      values: ['Replicate1', 'Replicate2'],
+      position: 1,
+      totalPositions: 3,
+      classSize: 2,
+    })).toBe('replicate')
+  })
+
+  it('returns factor for low-cardinality categoricals', () => {
+    expect(inferRole(make(['Kidney', 'Liver', 'Tumor', 'Kidney', 'Liver']))).toBe('factor')
+  })
+
+  it('returns ignore for very-high-cardinality opaque values', () => {
+    // Real-world LC-MS batches routinely have 30–50 distinct conditions, so the
+    // factor cap was raised to 50 (was 20). 80 unique values still reads as
+    // ignore — likely a sample-ID column rather than a meaningful factor.
+    const values = Array.from({ length: 80 }, (_, i) => `opaque-${i}`)
+    expect(inferRole({ values, position: 0, totalPositions: 1, classSize: 80 })).toBe('ignore')
+  })
+})
+
+describe('buildClassSchema', () => {
+  it('builds one ColumnInfo per position, constant class-tag positions get class-tag role', () => {
+    const schema = buildClassSchema(
+      [
+        ['exp281', 'SAM_SAH', 'Tissues', 'Kidney', 'M10', '085'],
+        ['exp281', 'SAM_SAH', 'Tissues', 'Liver', 'M10', '047'],
+      ],
+      'biological',
+      'Tissues',
+      [2, 3], // positions flagged as class-related tags
+    )
+    expect(schema.classKind).toBe('biological')
+    expect(schema.subKind).toBe('Tissues')
+    // Position 2 ('Tissues') is constant → class-tag.
+    // Position 3 ('Kidney'/'Liver') is multi-valued → falls through to factor inference.
+    const tagCols = schema.columns.filter(c => c.role === 'class-tag')
+    expect(tagCols.length).toBe(1)
+    expect(tagCols[0].index).toBe(2)
+    const factorCols = schema.columns.filter(c => c.role === 'factor')
+    expect(factorCols.some(c => c.index === 3)).toBe(true)
+  })
+
+  it('default groupBy is every Factor column', () => {
+    const schema = buildClassSchema(
+      [
+        ['exp', 'Kidney', '1'],
+        ['exp', 'Liver', '2'],
+        ['exp', 'Tumor', '3'],
+      ],
+      'biological',
+      'Tissues',
+      [],
+    )
+    const factorIndices = schema.columns.filter(c => c.role === 'factor').map(c => c.index)
+    expect(schema.groupBy).toEqual(factorIndices)
+  })
+})

package/src/__tests__/composables/autoGroup/compose.test.ts

@@ -0,0 +1,227 @@
+import { describe, it, expect } from 'vitest'
+import { composeGroups } from '../../../composables/autoGroup/compose'
+import type { ClassSchema } from '../../../types/auto-group'
+
+const tissueSchema: ClassSchema = {
+  classKind: 'biological',
+  subKind: 'Tissues',
+  columns: [
+    { index: 0, name: 'Tissue', sourceIndices: [0], uniqueValues: ['Kidney', 'Liver'], cardinality: 2, role: 'factor' },
+    { index: 1, name: 'Animal', sourceIndices: [1], uniqueValues: ['M1', 'M2', 'M3'], cardinality: 3, role: 'replicate' },
+  ],
+  groupBy: [0],
+}
+
+const iqcSchema: ClassSchema = {
+  classKind: 'iqc',
+  columns: [
+    { index: 0, name: 'IQC', sourceIndices: [0], uniqueValues: ['IQC'], cardinality: 1, role: 'class-tag' },
+    { index: 1, name: 'Run', sourceIndices: [1], uniqueValues: ['001', '002'], cardinality: 2, role: 'run-order' },
+  ],
+  groupBy: [],
+}
+
+describe('composeGroups', () => {
+  it('builds groups by enabled factor columns, ignoring replicate and run-order roles', () => {
+    const result = composeGroups({
+      tokenizedSamples: [
+        ['Kidney', 'M1'],
+        ['Kidney', 'M2'],
+        ['Liver', 'M1'],
+      ],
+      sampleNames: ['s1', 's2', 's3'],
+      schemas: { 'biological:Tissues': tissueSchema },
+      classes: [
+        {
+          kind: 'biological',
+          subKind: 'Tissues',
+          label: 'Biological / Tissues',
+          members: [0, 1, 2],
+          classTagPositions: [],
+          disposition: 'group',
+        },
+      ],
+    })
+    // Group names carry class context: "Biological / Tissues / <factor>".
+    // The class label is prepended so labels from different classes don't
+    // collide when they share a factor value.
+    expect(result.experimentalGroups!.map(g => g.name).sort()).toEqual([
+      'Biological / Tissues / Kidney',
+      'Biological / Tissues / Liver',
+    ])
+    expect(
+      result.experimentalGroups!.find(g => g.name === 'Biological / Tissues / Kidney')!.samples,
+    ).toEqual(['s1', 's2'])
+  })
+
+  it('routes overlay classes to qcGroups (separate from experimental)', () => {
+    const result = composeGroups({
+      tokenizedSamples: [
+        ['Kidney', 'M1'],
+        ['IQC', '001'],
+        ['IQC', '002'],
+      ],
+      sampleNames: ['bio1', 'iqc1', 'iqc2'],
+      schemas: { 'biological:Tissues': tissueSchema, iqc: iqcSchema },
+      classes: [
+        {
+          kind: 'biological',
+          subKind: 'Tissues',
+          label: 'Biological / Tissues',
+          members: [0],
+          classTagPositions: [],
+          disposition: 'group',
+        },
+        {
+          kind: 'iqc',
+          label: 'IQC',
+          members: [1, 2],
+          classTagPositions: [0],
+          disposition: 'overlay',
+        },
+      ],
+    })
+    expect(result.qcGroups!.length).toBe(1)
+    expect(result.qcGroups![0].name).toBe('IQC')
+    expect(result.qcGroups![0].samples).toEqual(['iqc1', 'iqc2'])
+    expect(result.experimentalGroups!.length).toBe(1)
+  })
+
+  it('routes excluded-disposition classes to excludedSamples', () => {
+    const result = composeGroups({
+      tokenizedSamples: [
+        ['Kidney', 'M1'],
+        ['IQC', '001'],
+      ],
+      sampleNames: ['bio1', 'iqc1'],
+      schemas: { 'biological:Tissues': tissueSchema, iqc: iqcSchema },
+      classes: [
+        {
+          kind: 'biological',
+          subKind: 'Tissues',
+          label: 'Biological / Tissues',
+          members: [0],
+          classTagPositions: [],
+          disposition: 'group',
+        },
+        {
+          kind: 'iqc',
+          label: 'IQC',
+          members: [1],
+          classTagPositions: [0],
+          disposition: 'exclude',
+        },
+      ],
+    })
+    expect(result.excludedSamples).toEqual(['iqc1'])
+    expect(result.qcGroups!.length).toBe(0)
+  })
+
+  it('legacy groups field equals experimentalGroups concat qcGroups', () => {
+    const result = composeGroups({
+      tokenizedSamples: [
+        ['Kidney', 'M1'],
+        ['IQC', '001'],
+      ],
+      sampleNames: ['bio1', 'iqc1'],
+      schemas: { 'biological:Tissues': tissueSchema, iqc: iqcSchema },
+      classes: [
+        {
+          kind: 'biological',
+          subKind: 'Tissues',
+          label: 'Biological / Tissues',
+          members: [0],
+          classTagPositions: [],
+          disposition: 'group',
+        },
+        {
+          kind: 'iqc',
+          label: 'IQC',
+          members: [1],
+          classTagPositions: [0],
+          disposition: 'overlay',
+        },
+      ],
+    })
+    const concatNames = [
+      ...result.experimentalGroups!.map(g => g.name),
+      ...result.qcGroups!.map(g => g.name),
+    ]
+    expect(result.groups.map(g => g.name)).toEqual(concatNames)
+  })
+
+  it('applies alias before exclude before bin in the operation pipeline', () => {
+    const schema: ClassSchema = {
+      classKind: 'biological',
+      columns: [
+        {
+          index: 0,
+          name: 'Treatment',
+          sourceIndices: [0],
+          uniqueValues: ['Drug-A', 'drug-A', 'CTL', 'CTL'],
+          cardinality: 3,
+          role: 'factor',
+          ops: {
+            alias: { 'drug-A': 'Drug-A' },
+            exclude: ['CTL'],
+          },
+        },
+      ],
+      groupBy: [0],
+    }
+    const result = composeGroups({
+      tokenizedSamples: [['Drug-A'], ['drug-A'], ['CTL']],
+      sampleNames: ['s1', 's2', 's3'],
+      schemas: { biological: schema },
+      classes: [
+        {
+          kind: 'biological',
+          label: 'Biological',
+          members: [0, 1, 2],
+          classTagPositions: [],
+          disposition: 'group',
+        },
+      ],
+    })
+    expect(result.experimentalGroups!.length).toBe(1)
+    // Class-prefixed group name (cls.label === 'Biological' → "Biological / Drug-A").
+    expect(result.experimentalGroups![0].name).toBe('Biological / Drug-A')
+    expect(result.experimentalGroups![0].samples).toEqual(['s1', 's2'])
+    expect(result.excludedSamples).toEqual(['s3'])
+  })
+
+  it('stores post-alias / post-bin display values in MetadataRow.fields', () => {
+    const schema: ClassSchema = {
+      classKind: 'biological',
+      columns: [
+        {
+          index: 0,
+          name: 'Tissue',
+          sourceIndices: [0],
+          uniqueValues: ['Kidney', 'Liver'],
+          cardinality: 2,
+          role: 'factor',
+          ops: { alias: { Kidney: 'kidney_panel' } },
+        },
+      ],
+      groupBy: [0],
+    }
+    const result = composeGroups({
+      tokenizedSamples: [['Kidney']],
+      sampleNames: ['s1'],
+      schemas: { biological: schema },
+      classes: [
+        {
+          kind: 'biological',
+          label: 'Biological',
+          members: [0],
+          classTagPositions: [],
+          disposition: 'group',
+        },
+      ],
+    })
+    expect(result.metadata[0].fields.Tissue).toBe('kidney_panel')
+    // Group label is class-prefixed: cls.label ("Biological") + post-alias value.
+    expect(result.metadata[0].group).toBe('Biological / kidney_panel')
+  })
+})

package/src/__tests__/composables/autoGroup/cooccurrence.test.ts

@@ -0,0 +1,91 @@
+import { describe, it, expect } from 'vitest'
+import { findMerges } from '../../../composables/autoGroup/cooccurrence'
+import type { ClassSchema } from '../../../types/auto-group'
+
+const schema = (overrides: Partial<ClassSchema> = {}): ClassSchema => ({
+  classKind: 'biological',
+  columns: [
+    { index: 0, name: 'A', sourceIndices: [0], uniqueValues: ['SAM'], cardinality: 1, role: 'factor' },
+    { index: 1, name: 'B', sourceIndices: [1], uniqueValues: ['SAH'], cardinality: 1, role: 'factor' },
+  ],
+  groupBy: [],
+  ...overrides,
+})
+
+describe('findMerges', () => {
+  it('suggests merging SAM + SAH when both columns are factors and mutually paired', () => {
+    const s = schema({
+      columns: [
+        { index: 0, name: 'A', sourceIndices: [0], uniqueValues: ['SAM', 'WT'], cardinality: 2, role: 'factor' },
+        { index: 1, name: 'B', sourceIndices: [1], uniqueValues: ['SAH', 'CTL'], cardinality: 2, role: 'factor' },
+      ],
+    })
+    const rows = [
+      ['SAM', 'SAH'],
+      ['SAM', 'SAH'],
+      ['SAM', 'SAH'],
+      ['SAM', 'SAH'],
+      ['WT', 'CTL'],
+      ['WT', 'CTL'],
+      ['WT', 'CTL'],
+      ['WT', 'CTL'],
+    ]
+    const out = findMerges(s, rows)
+    expect(out.length).toBe(1)
+    expect(out[0].columnIndices).toEqual([0, 1])
+    expect(out[0].confidence).toBeGreaterThanOrEqual(0.95)
+  })
+
+  it('rejects merge between two adjacent constants (no factor among them)', () => {
+    const s = schema({
+      columns: [
+        { index: 0, name: 'A', sourceIndices: [0], uniqueValues: ['exp281'], cardinality: 1, role: 'constant' },
+        { index: 1, name: 'B', sourceIndices: [1], uniqueValues: ['260415'], cardinality: 1, role: 'constant' },
+      ],
+    })
+    const rows = Array.from({ length: 10 }, () => ['exp281', '260415'])
+    expect(findMerges(s, rows)).toEqual([])
+  })
+
+  it('rejects asymmetric pairing (forward functional but not backward)', () => {
+    const s = schema({
+      columns: [
+        { index: 0, name: 'A', sourceIndices: [0], uniqueValues: ['a', 'b'], cardinality: 2, role: 'factor' },
+        { index: 1, name: 'B', sourceIndices: [1], uniqueValues: ['x'], cardinality: 1, role: 'constant' },
+      ],
+    })
+    const rows = [
+      ['a', 'x'],
+      ['a', 'x'],
+      ['b', 'x'],
+      ['b', 'x'],
+    ]
+    expect(findMerges(s, rows)).toEqual([])
+  })
+
+  it('rejects suggestions when class size < 4', () => {
+    const s = schema({
+      columns: [
+        { index: 0, name: 'A', sourceIndices: [0], uniqueValues: ['a', 'b'], cardinality: 2, role: 'factor' },
+        { index: 1, name: 'B', sourceIndices: [1], uniqueValues: ['x', 'y'], cardinality: 2, role: 'factor' },
+      ],
+    })
+    const rows = [
+      ['a', 'x'],
+      ['b', 'y'],
+      ['a', 'x'],
+    ]
+    expect(findMerges(s, rows)).toEqual([])
+  })
+
+  it('rejects merge that would collapse two adjacent factors into a single constant', () => {
+    const s = schema({
+      columns: [
+        { index: 0, name: 'A', sourceIndices: [0], uniqueValues: ['x'], cardinality: 1, role: 'factor' },
+        { index: 1, name: 'B', sourceIndices: [1], uniqueValues: ['y'], cardinality: 1, role: 'factor' },
+      ],
+    })
+    const rows = Array.from({ length: 6 }, () => ['x', 'y'])
+    expect(findMerges(s, rows)).toEqual([])
+  })
+})

package/src/__tests__/composables/autoGroup/fingerprint.test.ts

@@ -0,0 +1,50 @@
+import { describe, it, expect } from 'vitest'
+import { serializeFingerprint, restoreFingerprint } from '../../../composables/autoGroup/fingerprint'
+import type { ClassSchema } from '../../../types/auto-group'
+
+const schemas: ClassSchema[] = [
+  {
+    classKind: 'biological',
+    subKind: 'Tissues',
+    columns: [
+      {
+        index: 0,
+        name: 'Tissue',
+        sourceIndices: [0],
+        uniqueValues: ['Kidney', 'Liver'],
+        cardinality: 2,
+        role: 'factor',
+        ops: { alias: { Kidney: 'kidney_panel' } },
+      },
+    ],
+    groupBy: [0],
+  },
+]
+
+describe('fingerprint round-trip', () => {
+  it('serializes to a JSON-stringify-safe object (no Maps)', () => {
+    const fp = serializeFingerprint(schemas)
+    const stringified = JSON.stringify(fp)
+    const reparsed = JSON.parse(stringified)
+    expect(reparsed.version).toBe(1)
+    expect(reparsed.classes[0].columns[0].ops.alias.Kidney).toBe('kidney_panel')
+  })
+
+  it('round-trips through restore preserving group-by and ops', () => {
+    const fp = serializeFingerprint(schemas)
+    const restored = restoreFingerprint(fp, schemas)
+    expect(restored[0].groupBy).toEqual([0])
+    expect(restored[0].columns[0].ops?.alias?.Kidney).toBe('kidney_panel')
+  })
+
+  it('reports a clear error when current schema column count differs', () => {
+    const fp = serializeFingerprint(schemas)
+    const mismatched: ClassSchema[] = [
+      {
+        ...schemas[0],
+        columns: [], // empty
+      },
+    ]
+    expect(() => restoreFingerprint(fp, mismatched)).toThrow(/column count/i)
+  })
+})

package/src/__tests__/composables/autoGroup/integration.test.ts

@@ -0,0 +1,79 @@
+import { describe, it, expect } from 'vitest'
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import {
+  pickPrimaryDelimiter,
+  splitMulti,
+  detectClass,
+  buildClassSchema,
+  composeGroups,
+} from '../../../composables/autoGroup'
+
+const FIXTURE = resolve(__dirname, '../../fixtures/auto-group/mixed-lc-ms-batch.txt')
+
+describe('mixed LC-MS batch integration', () => {
+  const samples = readFileSync(FIXTURE, 'utf-8').trim().split('\n')
+  const delim = pickPrimaryDelimiter(samples)
+  const tokenized = samples.map(s => splitMulti(s, delim))
+  const classes = detectClass(tokenized, {})
+
+  it('detects exactly 81 Biological/Tissues samples', () => {
+    const c = classes.find(c => c.kind === 'biological' && c.subKind === 'Tissues')
+    expect(c?.members.length).toBe(81)
+  })
+
+  it('detects exactly 81 Biological/Plasma samples', () => {
+    const c = classes.find(c => c.kind === 'biological' && c.subKind === 'Plasma')
+    expect(c?.members.length).toBe(81)
+  })
+
+  it('detects exactly 3 IQC and 3 EQC samples', () => {
+    const iqc = classes.find(c => c.kind === 'iqc')
+    const eqc = classes.find(c => c.kind === 'eqc')
+    expect(iqc?.members.length).toBe(3)
+    expect(eqc?.members.length).toBe(3)
+  })
+
+  it('totals biological + QC overlay + excluded === 187', () => {
+    const tissues = classes.find(c => c.kind === 'biological' && c.subKind === 'Tissues')
+    const plasma = classes.find(c => c.kind === 'biological' && c.subKind === 'Plasma')
+    const overlayKinds = ['iqc', 'eqc', 'standard', 'spike-in', 'stock', 'blank']
+    const overlayCount = classes
+      .filter(c => overlayKinds.includes(c.kind))
+      .reduce((acc, c) => acc + c.members.length, 0)
+    const unknownCount = classes
+      .filter(c => c.kind === 'unknown')
+      .reduce((acc, c) => acc + c.members.length, 0)
+    expect((tissues?.members.length ?? 0) + (plasma?.members.length ?? 0) + overlayCount + unknownCount).toBe(187)
+  })
+
+  it('default workspace produces 3 Kidney/Liver/Tumor groups of 27 each', () => {
+    const tissuesClass = classes.find(c => c.kind === 'biological' && c.subKind === 'Tissues')!
+    const tissuesTokens = tissuesClass.members.map(i => tokenized[i])
+    const schema = buildClassSchema(
+      tissuesTokens,
+      'biological',
+      'Tissues',
+      tissuesClass.classTagPositions,
+    )
+    // The Tissue column should be a factor with 3 unique values.
+    const tissueCol = schema.columns.find(c => c.uniqueValues.length === 3 && c.role === 'factor')
+    expect(tissueCol).toBeDefined()
+    const result = composeGroups({
+      tokenizedSamples: tokenized,
+      sampleNames: samples,
+      schemas: { 'biological:Tissues': { ...schema, groupBy: [tissueCol!.index] } },
+      classes: [tissuesClass],
+    })
+    expect(result.experimentalGroups!.length).toBe(3)
+    expect(result.experimentalGroups!.every(g => g.samples.length === 27)).toBe(true)
+    const names = result.experimentalGroups!.map(g => g.name).sort()
+    // Class-prefixed: "Biological / Tissues / <organ>" disambiguates from
+    // other classes that might also produce a Kidney/Liver/Tumor factor.
+    expect(names).toEqual([
+      'Biological / Tissues / Kidney',
+      'Biological / Tissues / Liver',
+      'Biological / Tissues / Tumor',
+    ])
+  })
+})

package/src/__tests__/composables/autoGroup/template.test.ts

@@ -0,0 +1,70 @@
+import { describe, it, expect } from 'vitest'
+import { composeTemplate } from '../../../composables/autoGroup/template'
+import type { ClassSchema, SampleClass } from '../../../types/auto-group'
+
+describe('composeTemplate', () => {
+  const samples = ['s_1', 's_2,with_comma', 's_3']
+  const classes: SampleClass[] = [
+    {
+      kind: 'biological',
+      subKind: 'Tissues',
+      label: 'Biological / Tissues',
+      members: [0, 1, 2],
+      classTagPositions: [],
+      disposition: 'group',
+    },
+  ]
+  const schema: ClassSchema = {
+    classKind: 'biological',
+    subKind: 'Tissues',
+    columns: [
+      { index: 0, name: 'Tissue', sourceIndices: [0], uniqueValues: ['Kidney', 'Liver'], cardinality: 2, role: 'factor' },
+    ],
+    groupBy: [0],
+  }
+
+  it('blank mode emits one row per sample with sample_name and header-only suggested columns', () => {
+    const { content } = composeTemplate(samples, null, null, { mode: 'blank', format: 'csv' })
+    const lines = content.split('\n')
+    expect(lines[0]).toBe('sample_name,group,class,replicate,notes')
+    expect(lines[1].startsWith('s_1,')).toBe(true)
+    expect(lines.length).toBe(samples.length + 1)
+  })
+
+  it('quotes values containing commas per RFC 4180', () => {
+    const { content } = composeTemplate(samples, null, null, { mode: 'blank', format: 'csv' })
+    expect(content).toContain('"s_2,with_comma"')
+  })
+
+  it('prefilled mode includes class label and schema columns', () => {
+    const tokenized = [['Kidney'], ['Kidney'], ['Liver']]
+    const { content } = composeTemplate(samples, [schema], classes, {
+      mode: 'prefilled',
+      format: 'csv',
+      tokenizedSamples: tokenized,
+    })
+    const lines = content.split('\n')
+    expect(lines[0]).toBe('sample_name,class,Tissue,group,notes')
+    expect(lines[1]).toContain('Biological / Tissues')
+    expect(lines[1]).toContain('Kidney')
+  })
+
+  it('TSV format uses tab separator and skips quoting commas', () => {
+    const { content } = composeTemplate(samples, null, null, { mode: 'blank', format: 'tsv' })
+    expect(content.split('\n')[2].split('\t')[0]).toBe('s_2,with_comma')
+  })
+
+  it('uses experiment code in filename when provided', () => {
+    const { filename } = composeTemplate(samples, null, null, {
+      mode: 'blank',
+      format: 'csv',
+      experimentCode: 'EXP-042',
+    })
+    expect(filename).toMatch(/^EXP-042_metadata_\d{4}-\d{2}-\d{2}\.csv$/)
+  })
+
+  it('falls back to default filename without experiment code', () => {
+    const { filename } = composeTemplate(samples, null, null, { mode: 'blank', format: 'csv' })
+    expect(filename).toMatch(/^sample_metadata_\d{4}-\d{2}-\d{2}\.csv$/)
+  })
+})

package/src/__tests__/composables/autoGroup/tokenize.test.ts

@@ -0,0 +1,33 @@
+import { describe, it, expect } from 'vitest'
+import { splitMulti, pickPrimaryDelimiter } from '../../../composables/autoGroup/tokenize'
+
+describe('pickPrimaryDelimiter', () => {
+  it('should pick underscore when underscore field counts are most consistent', () => {
+    const lines = ['a_b_c', 'd_e_f', 'g_h_i']
+    expect(pickPrimaryDelimiter(lines)).toBe('_')
+  })
+
+  it('should pick hyphen when underscore is absent but hyphen is consistent', () => {
+    const lines = ['a-b-c', 'd-e-f']
+    expect(pickPrimaryDelimiter(lines)).toBe('-')
+  })
+
+  it('should fall back to underscore when no delimiter splits anything', () => {
+    const lines = ['abc', 'def']
+    expect(pickPrimaryDelimiter(lines)).toBe('_')
+  })
+})
+
+describe('splitMulti', () => {
+  it('should split a single sample on the primary delimiter', () => {
+    expect(splitMulti('a_b_c', '_')).toEqual(['a', 'b', 'c'])
+  })
+
+  it('should not re-split on secondary delimiters', () => {
+    expect(splitMulti('a-b_c-d', '_')).toEqual(['a-b', 'c-d'])
+  })
+
+  it('should handle empty string as a single empty token', () => {
+    expect(splitMulti('', '_')).toEqual([''])
+  })
+})