Add option to sort tours by date in Start Tour dialog

[jonathan-oron]

Description:

Feature Request

Problem

When opening the "Start Tour" dialog, tours are currently sorted alphabetically by name. In projects with many tours that document changes over time, it's difficult to find the most recent tours without using naming conventions (like numeric prefixes) to force sort order.

Proposed Solution

Add a sorting option in the Start Tour dialog that allows users to sort tours by:

• Name (current behavior, alphabetical)
• Date modified (newest first)
• Date created (newest first)

This could be implemented as:

1. A dropdown/toggle in the Start Tour dialog UI
2. A VS Code setting like codetour.sortToursBy: "name" | "dateModified" | "dateCreated"
3. Both options combined (setting for default + UI toggle to change on the fly)

Use Case

I use CodeTours to document code changes alongside commits. Each tour documents a feature or fix, creating a historical record of changes. Being able to sort by date would let me quickly find and review the most recent tours without relying on naming hacks like prefixing tour titles with descending numbers (e.g., "997 feat: ...", "996 fix: ...").

Additional Context

The .tour files are stored on disk and have filesystem timestamps that could be used for sorting. Alternatively, an optional createdAt or date field could be added to the tour schema.

[jonathan-oron]

Proposed Solution

The sorting logic is in https://github.com/microsoft/codetour/blob/main/src/store/provider.ts within the discoverTours() function:

store.tours = tours
.flat()
.sort((a, b) => a.title.localeCompare(b.title)) // <-- alphabetical sort
.filter(tour => !tour.when || jexl.evalSync(tour.when, TOUR_CONTEXT));

Implementation

1. Add a VS Code setting in package.json:

"codetour.sortBy": {
"type": "string",
"enum": ["title", "dateModified", "dateCreated"],
"default": "title",
"description": "How to sort tours in the Start Tour dialog"
}

2. Update the sort logic in src/store/provider.ts:

import * as fs from "fs";

const sortBy = vscode.workspace.getConfiguration("codetour").get("sortBy", "title");

const sortFn = (a: CodeTour, b: CodeTour) => {
switch (sortBy) {
case "dateModified":
const aMtime = fs.statSync(a.uri.fsPath).mtimeMs;
const bMtime = fs.statSync(b.uri.fsPath).mtimeMs;
return bMtime - aMtime; // newest first
case "dateCreated":
// Use birthtimeMs for true creation time (macOS/Windows)
const aBirth = fs.statSync(a.uri.fsPath).birthtimeMs;
const bBirth = fs.statSync(b.uri.fsPath).birthtimeMs;
return bBirth - aBirth; // newest first
default:
return a.title.localeCompare(b.title);
}
};

store.tours = tours.flat().sort(sortFn).filter(...);

3. No schema changes needed - uses existing filesystem metadata directly from the .tour files.