larkup 0.4.12 → 0.4.14

package/.next/standalone/apps/web/lib/chat/retrieval-ranking.test.ts

@@ -0,0 +1,62 @@
+import { describe, expect, it } from 'vitest';
+import { rankKnowledgeHits } from './retrieval-ranking';
+
+describe('rankKnowledgeHits', () => {
+  it('does not let a query term match as a fragment inside a longer word', () => {
+    // Regression: a plain substring check let "day" match inside "Tuesday"
+    // and "color" match inside "Colored", which caused a long, unrelated
+    // document to systematically outrank a short, genuinely on-topic one
+    // (observed live: an indexed video transcript naming "Tuesday" and
+    // "Colored Canyon" tourism copy neither of which mention a video).
+    const hits = [
+      {
+        title: 'video clip',
+        text: 'A red drone crash-landed into a blue pool on Tuesday afternoon in Austin.',
+      },
+      {
+        title: 'unrelated tourism page',
+        text: 'The Colored Canyon is a natural wonder. It is a great day out for the family.',
+      },
+    ];
+    // Dense rank 0 is the video clip (the correct, highest vector-similarity
+    // match); the ranker must not flip that order just because the second
+    // document's word fragments happen to contain "color" and "day".
+    const ranked = rankKnowledgeHits('video crash details color landing day city', hits);
+    expect(ranked[0].title).toBe('video clip');
+  });
+
+  it('still rewards a real whole-word match in a short document over a longer one', () => {
+    const hits = [
+      { title: 'unrelated page', text: 'Some long unrelated document about many other topics.' },
+      { title: 'video clip', text: 'A drone crash landed in a pool on a sunny day.' },
+    ];
+    const ranked = rankKnowledgeHits('what day did the drone crash', hits);
+    expect(ranked[0].title).toBe('video clip');
+  });
+
+  it('still matches an ordinary plural/possessive form of a query term', () => {
+    // Regression: the word-boundary fix above initially rejected "views"
+    // as a match for the term "view" (a real, pre-existing e2e test
+    // exercised this: a query for "view" and "routine" needed to match a
+    // doc naming "Views" and "routines"). Ordinary English inflection is
+    // not the same failure mode as "day" inside "Tuesday" -- only the
+    // second should be rejected.
+    const hits = [
+      { title: 'unrelated', text: 'Nothing relevant here at all, just filler words.' },
+      { title: 'schema doc', text: 'Views: film_list. Resources contains routines: get_customer.' },
+    ];
+    const ranked = rankKnowledgeHits('list every view and routine under Resources', hits);
+    expect(ranked[0].title).toBe('schema doc');
+  });
+
+  it('preserves dense-rank order when no hit has any keyword overlap', () => {
+    const hits = [{ title: 'first', text: 'alpha' }, { title: 'second', text: 'beta' }];
+    const ranked = rankKnowledgeHits('completely unrelated query terms', hits);
+    expect(ranked.map((hit) => hit.title)).toEqual(['first', 'second']);
+  });
+
+  it('is a no-op for fewer than two hits', () => {
+    const hits = [{ title: 'only', text: 'one hit' }];
+    expect(rankKnowledgeHits('query', hits)).toEqual(hits);
+  });
+});

package/.next/standalone/apps/web/lib/chat/retrieval-routing.test.ts

@@ -0,0 +1,80 @@
+import { describe, expect, it } from 'vitest';
+import { requiresKnowledgeBaseSearch, retrievalToolsForStep } from './retrieval-routing';
+
+const TOOL_NAMES = ['searchKnowledgeBase', 'webSearch', 'presentMedia'] as const;
+
+describe('requiresKnowledgeBaseSearch', () => {
+  it('matches a possessive noun with a modifier word in between', () => {
+    // Regression: the underlying regexes required "my"/"this"/"the" to sit
+    // directly next to the noun (\s+ only). "my test video" has "test" in
+    // between and fell through every branch, silently skipping the forced
+    // search step -- observed live: the model answered "no video content"
+    // instead of searching, even though the video was indexed and findable.
+    expect(
+      requiresKnowledgeBaseSearch(
+        'Where did the drone in my test video end up, and when did it happen?',
+      ),
+    ).toBe(true);
+    expect(requiresKnowledgeBaseSearch('What does this uploaded recording show?')).toBe(true);
+    expect(requiresKnowledgeBaseSearch('Summarize the quarterly sales report')).toBe(true);
+  });
+
+  it('still matches the direct-adjacency phrasing with no modifier', () => {
+    expect(requiresKnowledgeBaseSearch('What happens in my video?')).toBe(true);
+    expect(requiresKnowledgeBaseSearch('Show me the document')).toBe(true);
+  });
+
+  it('does not match across an unbounded number of intervening words', () => {
+    expect(
+      requiresKnowledgeBaseSearch(
+        'my extremely long winded description of a totally unrelated video',
+      ),
+    ).toBe(false);
+  });
+
+  it('does not flag an ordinary greeting', () => {
+    expect(requiresKnowledgeBaseSearch('Hey, how are you?')).toBe(false);
+  });
+});
+
+describe('retrievalToolsForStep', () => {
+  it('forces searchKnowledgeBase on step 0 when required', () => {
+    const step = retrievalToolsForStep({
+      stepNumber: 0,
+      forceKnowledgeBaseSearch: true,
+      forceWebSearch: false,
+      toolNames: TOOL_NAMES,
+    });
+    expect(step?.toolChoice).toEqual({ type: 'tool', toolName: 'searchKnowledgeBase' });
+    expect(step?.activeTools).toEqual(['searchKnowledgeBase']);
+  });
+
+  it('explicitly disables tool choice on the final answer step instead of leaving a stale auto', () => {
+    // Regression: an empty activeTools array paired with the top-level
+    // streamText toolChoice ('auto') left over from earlier in the request
+    // produced a degenerate near-empty model response (observed live: 1
+    // output token, no text) instead of a normal final answer. Being
+    // explicit here removes the ambiguity for the provider.
+    const step = retrievalToolsForStep({
+      stepNumber: 2,
+      forceKnowledgeBaseSearch: true,
+      forceWebSearch: false,
+      toolNames: TOOL_NAMES,
+      finalAnswerStep: 2,
+    });
+    expect(step?.activeTools).toEqual([]);
+    expect(step?.toolChoice).toBe('none');
+  });
+
+  it('does not force a final-answer step before finalAnswerStep is reached', () => {
+    const step = retrievalToolsForStep({
+      stepNumber: 1,
+      forceKnowledgeBaseSearch: true,
+      forceWebSearch: false,
+      toolNames: TOOL_NAMES,
+      finalAnswerStep: 2,
+    });
+    expect(step?.toolChoice).toBeUndefined();
+    expect(step?.activeTools).toEqual(['presentMedia']);
+  });
+});

package/.next/standalone/apps/web/lib/chat/tabular-dataset-routing.test.ts

@@ -0,0 +1,83 @@
+import { describe, expect, it } from 'vitest';
+import type { TabularDatasetMeta } from '@larkup/core/tabular-store';
+import {
+  resolveTabularDatasetForQuestion,
+  selectTabularDatasetForQuestion,
+} from './tabular-dataset-routing';
+
+const datasets: TabularDatasetMeta[] = [
+  {
+    id: 'generic-sales',
+    fileName: 'sample_sales_data.xlsx',
+    rowCount: 500,
+    columns: [
+      { name: 'Date', type: 'date', nullCount: 0, uniqueCount: 365 },
+      { name: 'Net Revenue', type: 'number', nullCount: 0, uniqueCount: 500 },
+    ],
+    summary: {
+      totalRows: 500,
+      totalColumns: 2,
+      numericColumns: 1,
+      categoricalColumns: 0,
+      dateColumns: 1,
+    },
+    createdAt: '2026-01-01T00:00:00.000Z',
+  },
+  {
+    id: 'superstore-orders',
+    fileName: 'Sample - Superstore.xlsx — Orders',
+    rowCount: 9994,
+    columns: [
+      { name: 'Order Date', type: 'date', nullCount: 0, uniqueCount: 1200 },
+      { name: 'Sub-Category', type: 'string', nullCount: 0, uniqueCount: 17 },
+      { name: 'Sales', type: 'number', nullCount: 0, uniqueCount: 9000 },
+      { name: 'Profit', type: 'number', nullCount: 0, uniqueCount: 7000 },
+      { name: 'Discount', type: 'number', nullCount: 0, uniqueCount: 15 },
+    ],
+    summary: {
+      totalRows: 9994,
+      totalColumns: 5,
+      numericColumns: 3,
+      categoricalColumns: 1,
+      dateColumns: 1,
+    },
+    createdAt: '2026-01-01T00:00:00.000Z',
+  },
+];
+
+describe('resolveTabularDatasetForQuestion', () => {
+  it('corrects a plausible but schema-incompatible sales sheet selection', () => {
+    expect(
+      resolveTabularDatasetForQuestion(
+        'Show monthly Sales and Profit trends.',
+        datasets,
+        'generic-sales',
+      ),
+    ).toBe('superstore-orders');
+  });
+
+  it('keeps the revenue sheet when its measure is the one the user asked for', () => {
+    expect(
+      resolveTabularDatasetForQuestion(
+        'Show the monthly Net Revenue trend.',
+        datasets,
+        'generic-sales',
+      ),
+    ).toBe('generic-sales');
+  });
+
+  it('supplies the unambiguous source for a sandbox analysis with no dataset ID', () => {
+    expect(
+      selectTabularDatasetForQuestion(
+        'Does Discount correlate with Profit? Run a correlation analysis.',
+        datasets,
+      ),
+    ).toBe('superstore-orders');
+  });
+
+  it('does not stage an arbitrary sheet when multiple schemas do not match', () => {
+    expect(
+      selectTabularDatasetForQuestion('Run a statistical analysis.', datasets),
+    ).toBeUndefined();
+  });
+});

package/.next/standalone/apps/web/lib/chat/tabular-query-plan.test.ts

@@ -0,0 +1,148 @@
+import { describe, expect, it } from 'vitest';
+import type { TabularDataset } from '@larkup/core/tabular-store';
+import { inferTabularPlan } from './tabular-query-plan';
+
+const dataset: TabularDataset = {
+  id: 'sales-data',
+  fileName: 'sales.csv',
+  columns: [
+    { name: 'Date', type: 'date', nullCount: 0, uniqueCount: 364 },
+    { name: 'Region', type: 'string', nullCount: 0, uniqueCount: 4 },
+    { name: 'Sales Rep', type: 'string', nullCount: 0, uniqueCount: 12 },
+    { name: 'Net Revenue', type: 'number', nullCount: 0, uniqueCount: 364 },
+  ],
+  rows: [],
+  summary: {
+    totalRows: 364,
+    totalColumns: 4,
+    numericColumns: 1,
+    categoricalColumns: 2,
+    dateColumns: 1,
+  },
+  rowCount: 364,
+  createdAt: '2025-01-01T00:00:00.000Z',
+};
+
+const superstoreOrders: TabularDataset = {
+  ...dataset,
+  id: 'superstore-orders',
+  fileName: 'Superstore.xlsx — Orders',
+  columns: [
+    { name: 'Order Date', type: 'date', nullCount: 0, uniqueCount: 100 },
+    { name: 'Sub-Category', type: 'string', nullCount: 0, uniqueCount: 17 },
+    { name: 'Sales', type: 'number', nullCount: 0, uniqueCount: 100 },
+    { name: 'Profit', type: 'number', nullCount: 0, uniqueCount: 100 },
+    { name: 'Discount', type: 'number', nullCount: 0, uniqueCount: 15 },
+  ],
+  summary: {
+    totalRows: 100,
+    totalColumns: 5,
+    numericColumns: 3,
+    categoricalColumns: 1,
+    dateColumns: 1,
+  },
+};
+
+describe('inferTabularPlan', () => {
+  it('turns a monthly 2025 request into a bounded grouped date query', () => {
+    const plan = inferTabularPlan("What's the monthly revenue trend for 2025?", dataset, {
+      datasetId: dataset.id,
+      columns: ['Date', 'Net Revenue'],
+    });
+
+    expect(plan.request).toMatchObject({
+      timeBucket: { column: 'Date', grain: 'month' },
+      groupBy: ['Date_month'],
+      aggregations: [{ column: 'Net Revenue', op: 'sum' }],
+      sortBy: 'Date_month',
+      sortOrder: 'asc',
+      limit: 120,
+    });
+    expect(plan.request.filters).toEqual([
+      { column: 'Date', op: 'gte', value: '2025-01-01' },
+      { column: 'Date', op: 'lt', value: '2026-01-01' },
+    ]);
+    expect(plan.request.columns).toBeUndefined();
+  });
+
+  it('repairs an invalid text aggregation only when the schema has one numeric measure', () => {
+    const plan = inferTabularPlan('show me distribution over sales by area', dataset, {
+      datasetId: dataset.id,
+      groupBy: ['Region'],
+      aggregations: [{ column: 'Sales Rep', op: 'sum' }],
+    });
+
+    expect(plan.request).toMatchObject({
+      groupBy: ['Region'],
+      aggregations: [{ column: 'Net Revenue', op: 'sum' }],
+    });
+  });
+
+  it('uses a distinct count for a natural-language unique-value request', () => {
+    const plan = inferTabularPlan('How many unique sales reps are there?', dataset, {
+      datasetId: dataset.id,
+      aggregations: [{ column: 'Sales Rep', op: 'count' }],
+    });
+
+    expect(plan.request.aggregations).toEqual([{ column: 'Sales Rep', op: 'countDistinct' }]);
+  });
+
+  it('completes a monthly grouping when the model selected one measure from several', () => {
+    const multiMeasureDataset: TabularDataset = {
+      ...dataset,
+      columns: [
+        ...dataset.columns,
+        { name: 'Quantity', type: 'number', nullCount: 0, uniqueCount: 20 },
+      ],
+      summary: { ...dataset.summary, numericColumns: 2, totalColumns: 5 },
+    };
+
+    const plan = inferTabularPlan('Show the monthly revenue trend for 2025', multiMeasureDataset, {
+      datasetId: dataset.id,
+      timeBucket: { column: 'Date', grain: 'month' },
+      aggregations: [{ column: 'Net Revenue', op: 'sum' }],
+      sortBy: 'Date',
+    });
+
+    expect(plan.request).toMatchObject({
+      groupBy: ['Date_month'],
+      aggregations: [{ column: 'Net Revenue', op: 'sum' }],
+      sortBy: 'Date_month',
+      sortOrder: 'asc',
+    });
+  });
+
+  it('keeps every explicitly requested metric in a monthly trend', () => {
+    const plan = inferTabularPlan('Show monthly Sales and Profit trends.', superstoreOrders, {
+      datasetId: superstoreOrders.id,
+      aggregations: [{ column: 'Sales', op: 'sum' }],
+    });
+
+    expect(plan.request).toMatchObject({
+      timeBucket: { column: 'Order Date', grain: 'month' },
+      groupBy: ['Order Date_month'],
+      aggregations: [
+        { column: 'Sales', op: 'sum' },
+        { column: 'Profit', op: 'sum' },
+      ],
+      sortBy: 'Order Date_month',
+      sortOrder: 'asc',
+    });
+  });
+
+  it('derives a sorted grouped measure from an explicit by-column request', () => {
+    const plan = inferTabularPlan(
+      'Create a bar chart of Profit by Sub-Category, sorted from lowest to highest.',
+      superstoreOrders,
+      { datasetId: superstoreOrders.id, limit: 20 },
+    );
+
+    expect(plan.request).toMatchObject({
+      groupBy: ['Sub-Category'],
+      aggregations: [{ column: 'Profit', op: 'sum' }],
+      sortBy: 'sum_Profit',
+      sortOrder: 'asc',
+      limit: 20,
+    });
+  });
+});

package/.next/standalone/apps/web/lib/chat/tabular-routing.test.ts

@@ -0,0 +1,109 @@
+import { describe, expect, it } from 'vitest';
+import {
+  hasCompletedTabularVisualizationStep,
+  isLikelyTabularQuestion,
+  requiresTabularSandbox,
+  tabularToolsForStep,
+} from './tabular-routing';
+
+describe('isLikelyTabularQuestion', () => {
+  it('routes a question that names one distinctive workbook metric', () => {
+    expect(
+      isLikelyTabularQuestion({
+        text: "What is the dropout level among master's students in Germany?",
+        datasetNames: ['germany_integration_university_dataset_clean.xlsx'],
+        columnNames: ['Student cohort', 'Master dropout rate', 'University'],
+      }),
+    ).toBe(true);
+  });
+
+  it('does not route an ordinary question solely because a generic column exists', () => {
+    expect(
+      isLikelyTabularQuestion({
+        text: 'Who is presenting in the evacuation video?',
+        datasetNames: ['metrics.xlsx'],
+        columnNames: ['Name', 'Date', 'Status'],
+      }),
+    ).toBe(false);
+  });
+
+  it('does not mistake a requested table format for a tabular source', () => {
+    expect(
+      isLikelyTabularQuestion({
+        text: 'Create a table with each named team member and a clothing description from the video.',
+        datasetNames: ['Superstore.xlsx'],
+        columnNames: ['Order ID', 'Product Name', 'Sales'],
+      }),
+    ).toBe(false);
+  });
+
+  it('keeps explicit data-table requests on the structured table path', () => {
+    expect(
+      isLikelyTabularQuestion({
+        text: 'Show the data table columns and rows for Superstore.',
+        datasetNames: ['Superstore.xlsx'],
+        columnNames: ['Order ID', 'Product Name', 'Sales'],
+      }),
+    ).toBe(true);
+  });
+});
+
+describe('tabularToolsForStep', () => {
+  it('requires the exact table query before an answer is generated', () => {
+    expect(tabularToolsForStep({ stepNumber: 0, toolNames: ['queryTabularData'] })).toEqual({
+      toolChoice: { type: 'tool', toolName: 'queryTabularData' },
+      activeTools: ['queryTabularData'],
+    });
+  });
+
+  it('requires the sandbox for a cross-sheet join', () => {
+    expect(
+      tabularToolsForStep({
+        stepNumber: 0,
+        toolNames: ['queryTabularData', 'executeAnalysis'],
+        requiresSandbox: requiresTabularSandbox('Join the Orders and Returns sheets with Python.'),
+      }),
+    ).toEqual({
+      toolChoice: { type: 'tool', toolName: 'executeAnalysis' },
+      activeTools: ['executeAnalysis'],
+    });
+  });
+
+  it('does not require code for an ordinary grouped tabular question', () => {
+    expect(requiresTabularSandbox('Show total sales by region.')).toBe(false);
+  });
+
+  it('answers after the first table result instead of requesting a second chart tool', () => {
+    expect(
+      tabularToolsForStep({
+        stepNumber: 1,
+        toolNames: ['queryTabularData', 'generateVisualization', 'executeAnalysis'],
+      }),
+    ).toEqual({ toolChoice: 'none', activeTools: [] });
+  });
+});
+
+describe('hasCompletedTabularVisualizationStep', () => {
+  it('stops after the structured query returns a host-renderable chart', () => {
+    expect(
+      hasCompletedTabularVisualizationStep([
+        {
+          toolResults: [
+            {
+              toolName: 'queryTabularData',
+              output: {
+                rows: [{ region: 'North', total: 10 }],
+                visualization: { chartType: 'bar' },
+              },
+            },
+          ],
+        },
+      ]),
+    ).toBe(true);
+    expect(
+      hasCompletedTabularVisualizationStep([
+        { toolResults: [{ toolName: 'queryTabularData', output: { rows: [] } }] },
+      ]),
+    ).toBe(false);
+  });
+});

package/.next/standalone/apps/web/lib/chat/tabular-sandbox-files.test.ts

@@ -0,0 +1,100 @@
+import { describe, expect, it } from 'vitest';
+import type { TabularDataset } from '@larkup/core/tabular-store';
+import {
+  createTabularSandboxFiles,
+  remapLegacyMultiDatasetReads,
+  tabularDatasetToCsv,
+} from './tabular-sandbox-files';
+
+function dataset(id: string, fileName: string, rows: Record<string, unknown>[]): TabularDataset {
+  return {
+    id,
+    fileName,
+    columns: [
+      { name: 'Name', type: 'string', nullCount: 0, uniqueCount: rows.length },
+      { name: 'Amount', type: 'number', nullCount: 0, uniqueCount: rows.length },
+    ],
+    rows,
+    summary: {
+      totalRows: rows.length,
+      totalColumns: 2,
+      numericColumns: 1,
+      categoricalColumns: 1,
+      dateColumns: 0,
+    },
+    rowCount: rows.length,
+    createdAt: '2026-01-01T00:00:00.000Z',
+  };
+}
+
+describe('tabular sandbox files', () => {
+  it('preserves the legacy data.csv contract and safely escapes CSV text', () => {
+    const source = dataset('orders', 'orders.csv', [{ Name: 'Desk, "Large"', Amount: 42 }]);
+
+    expect(tabularDatasetToCsv(source)).toBe('Name,Amount\n"Desk, ""Large""",42');
+    expect(createTabularSandboxFiles([source])).toEqual({
+      files: [{ name: 'data.csv', content: 'Name,Amount\n"Desk, ""Large""",42' }],
+    });
+  });
+
+  it('creates a manifest and distinct files for a cross-dataset analysis', () => {
+    const orders = dataset('orders', 'Orders', [{ Name: 'CA-1', Amount: 20 }]);
+    const returns = dataset('returns', 'Returns', [{ Name: 'CA-1', Amount: 1 }]);
+
+    const staged = createTabularSandboxFiles([orders, returns]);
+
+    expect(staged.files.map((file) => file.name)).toEqual([
+      'dataset-1.csv',
+      'dataset-2.csv',
+      'datasets.json',
+    ]);
+    expect(staged.manifest).toEqual({
+      datasets: [
+        {
+          id: 'orders',
+          fileName: 'Orders',
+          file: 'dataset-1.csv',
+          rowCount: 1,
+          columns: ['Name', 'Amount'],
+        },
+        {
+          id: 'returns',
+          fileName: 'Returns',
+          file: 'dataset-2.csv',
+          rowCount: 1,
+          columns: ['Name', 'Amount'],
+        },
+      ],
+    });
+  });
+
+  it('recovers exactly one legacy CSV read per selected dataset', () => {
+    const code = [
+      "orders = pd.read_csv('data.csv')",
+      "returns = pd.read_csv('data.csv')",
+      "people = pd.read_csv('data.csv')",
+    ].join('\n');
+
+    expect(remapLegacyMultiDatasetReads(code, 3)).toBe(
+      [
+        "orders = pd.read_csv('dataset-1.csv')",
+        "returns = pd.read_csv('dataset-2.csv')",
+        "people = pd.read_csv('dataset-3.csv')",
+      ].join('\n'),
+    );
+    expect(remapLegacyMultiDatasetReads(code, 2)).toBe(code);
+  });
+
+  it('converts legacy Excel sheet reads to the staged CSV files', () => {
+    const code = [
+      "orders = pd.read_excel('data.csv', sheet_name='Orders')",
+      "returns = pd.read_excel('data.csv', sheet_name='Returns')",
+    ].join('\n');
+
+    expect(remapLegacyMultiDatasetReads(code, 2)).toBe(
+      ["orders = pd.read_csv('dataset-1.csv')", "returns = pd.read_csv('dataset-2.csv')"].join(
+        '\n',
+      ),
+    );
+  });
+});

package/.next/standalone/apps/web/lib/chat/tabular-visualization.test.ts

@@ -0,0 +1,89 @@
+import { describe, expect, it } from 'vitest';
+import { createTabularVisualization } from './tabular-visualization';
+
+describe('createTabularVisualization', () => {
+  it('uses a line chart for a time trend', () => {
+    expect(
+      createTabularVisualization("What's the monthly revenue trend?", {
+        columns: ['Date_month', 'sum_Revenue'],
+        rows: [
+          { Date_month: '2025-01', sum_Revenue: 100 },
+          { Date_month: '2025-02', sum_Revenue: 150 },
+        ],
+      }),
+    ).toMatchObject({
+      chartType: 'line',
+      xAxisKey: 'Date_month',
+      series: [{ dataKey: 'sum_Revenue', label: 'sum Revenue' }],
+    });
+  });
+
+  it('recognizes plural trend requests as a visualization intent', () => {
+    expect(
+      createTabularVisualization('Show monthly Sales and Profit trends.', {
+        columns: ['Order Date_month', 'sum_Sales', 'sum_Profit'],
+        rows: [{ 'Order Date_month': '2025-01', sum_Sales: 100, sum_Profit: 10 }],
+      }),
+    ).toMatchObject({
+      chartType: 'line',
+      series: [{ dataKey: 'sum_Sales' }, { dataKey: 'sum_Profit' }],
+    });
+  });
+
+  it('uses a line chart when the user explicitly requests one', () => {
+    expect(
+      createTabularVisualization('Create a line chart of monthly sales.', {
+        columns: ['Order Date_month', 'sum_Sales'],
+        rows: [
+          { 'Order Date_month': '2025-01', sum_Sales: 100 },
+          { 'Order Date_month': '2025-02', sum_Sales: 150 },
+        ],
+      }),
+    ).toMatchObject({ chartType: 'line' });
+  });
+
+  it('never exposes empty spreadsheet columns as chart labels', () => {
+    expect(
+      createTabularVisualization('show a comparison chart', {
+        columns: ['__EMPTY', 'University', 'International dropout', 'Domestic dropout'],
+        rows: [
+          {
+            __EMPTY: 'ignored',
+            University: 'North',
+            'International dropout': '16%',
+            'Domestic dropout': '13%',
+          },
+          {
+            __EMPTY: 'ignored',
+            University: 'South',
+            'International dropout': '49%',
+            'Domestic dropout': '26%',
+          },
+        ],
+      }),
+    ).toMatchObject({
+      xAxisKey: 'University',
+      series: [
+        { dataKey: 'International dropout', label: 'International dropout' },
+        { dataKey: 'Domestic dropout', label: 'Domestic dropout' },
+      ],
+    });
+  });
+
+  it('uses a varying year column for a year-to-year follow-up', () => {
+    expect(
+      createTabularVisualization('Graph this integration cost year to year.', {
+        columns: ['University', 'Year', 'Modeled integration cost'],
+        rows: [
+          { University: 'Freiburg', Year: 2023, 'Modeled integration cost': 5.59 },
+          { University: 'Freiburg', Year: 2024, 'Modeled integration cost': 7.47 },
+          { University: 'Freiburg', Year: 2025, 'Modeled integration cost': 6.63 },
+        ],
+      }),
+    ).toMatchObject({
+      chartType: 'line',
+      xAxisKey: 'Year',
+      series: [{ dataKey: 'Modeled integration cost' }],
+    });
+  });
+});