389 lines
15 KiB
TypeScript
389 lines
15 KiB
TypeScript
// SPDX-License-Identifier: GPL-3.0-or-later
|
|
// Copyright (C) 2026 ZiroEDA and contributors.
|
|
// Portions derived from KiCad, copyright The KiCad Developers. See NOTICE.md.
|
|
/**
|
|
* `include/local_history.h`: what a document hands the local-history
|
|
* snapshot. The snapshot store itself (a git repo under the project) is the
|
|
* app's; the savers only fill these.
|
|
*/
|
|
import type { FORMAT_MODE } from './io/kicad/kicad_io_utils.js';
|
|
|
|
export interface HISTORY_FILE_DATA {
|
|
relativePath: string; ///< Destination path relative to the project root
|
|
content: string; ///< Serialized content (mutually exclusive with sourcePath)
|
|
sourcePath: string; ///< For file-copy savers (small files like .kicad_pro)
|
|
prettify: boolean;
|
|
formatMode: FORMAT_MODE;
|
|
}
|
|
|
|
// ---------------------------------------------------------------------------
|
|
// The snapshot list, as LOCAL_HISTORY and DIALOG_RESTORE_LOCAL_HISTORY read it.
|
|
// Moved from designer/src/home/local_history.ts on 09-26; the storage (IndexedDB,
|
|
// the blob hash) stays in the app's local_history_store.ts.
|
|
|
|
/**
|
|
* Local History: the snapshot store behind `View > Panels > Local History`.
|
|
*
|
|
* Counterpart: `LOCAL_HISTORY` (common/local_history.cpp) and the pane that
|
|
* reads it (kicad/local_history_pane.cpp). Upstream keeps a real git repository
|
|
* inside the project directory and drives it with libgit2 - a save runs the
|
|
* registered savers, writes the files, and commits them:
|
|
*
|
|
* bool CommitSnapshot( const std::vector<wxString>& aFiles, const wxString& aTitle );
|
|
* bool CommitFullProjectSnapshot( const wxString& aProjectPath, const wxString& aTitle );
|
|
* std::vector<LOCAL_HISTORY_SNAPSHOT_INFO> LoadSnapshots( const wxString& aProjectPath );
|
|
*
|
|
* and a snapshot is
|
|
*
|
|
* struct LOCAL_HISTORY_SNAPSHOT_INFO
|
|
* {
|
|
* wxString hash;
|
|
* wxDateTime date;
|
|
* wxString summary;
|
|
* wxString message;
|
|
* int filesChanged = 0;
|
|
* wxArrayString changedFiles;
|
|
* };
|
|
*
|
|
* There is no git here and no directory to put one in, so the *shape* is ported
|
|
* rather than the mechanism: a snapshot is a list of file names each pointing
|
|
* at a content hash, and the bytes live once per hash. That is what a git tree
|
|
* is, minus the parts that exist to make it a distributed version control
|
|
* system - packfiles, refs, merges, remotes - none of which a "restore what I
|
|
* had an hour ago" pane uses.
|
|
*
|
|
* The consequence worth stating: unchanged files cost nothing across snapshots,
|
|
* which is the property that makes snapshotting on every save affordable. A
|
|
* board project is mostly footprints and 3D models that do not change while you
|
|
* edit a schematic.
|
|
*
|
|
* This module is the store and the rules. The pane that renders it is
|
|
* LocalHistoryPane.tsx.
|
|
*/
|
|
|
|
/**
|
|
* One snapshot, as the pane lists it.
|
|
*
|
|
* `LOCAL_HISTORY_SNAPSHOT_INFO`, with git's identifiers dropped: `hash` there
|
|
* is a commit oid, which is how libgit2 addresses a commit; ours is an id
|
|
* because there is no object database to look it up in.
|
|
*/
|
|
export interface Snapshot {
|
|
/** Unique and sortable: the timestamp plus a counter, newest last. */
|
|
id: string;
|
|
/** `git_commit_time`, in ms. */
|
|
at: number;
|
|
/**
|
|
* `info.message.BeforeFirst( '\n' )` - what the Title column shows.
|
|
*
|
|
* Upstream's is a commit message written by whatever asked for the snapshot,
|
|
* and the pane tints two of them: a summary starting "Autosave" is drawn in
|
|
* grey text, one starting "Backup" in blue. So the first word is load-bearing
|
|
* and {@link SnapshotKind} keeps it that way rather than leaving it to
|
|
* whoever writes the string.
|
|
*/
|
|
title: string;
|
|
/** What asked for the snapshot, which decides how the row is tinted. */
|
|
kind: SnapshotKind;
|
|
/** `filesChanged`, and the names behind it. */
|
|
files: SnapshotFile[];
|
|
/** Names whose content differs from the snapshot before this one. */
|
|
changed: string[];
|
|
}
|
|
|
|
/** A file in a snapshot: its name and the hash its bytes are stored under. */
|
|
export interface SnapshotFile {
|
|
name: string;
|
|
hash: string;
|
|
/** Uncompressed length, so a snapshot's size is known without reading it. */
|
|
size: number;
|
|
}
|
|
|
|
/**
|
|
* The three the pane distinguishes.
|
|
*
|
|
* if( info.summary.StartsWith( wxS( "Autosave" ) ) )
|
|
* m_list->SetItemTextColour( row, ...GRAYTEXT );
|
|
* else if( info.summary.StartsWith( wxS( "Backup" ) ) )
|
|
* m_list->SetItemTextColour( row, wxColour( 80, 120, 200 ) );
|
|
*
|
|
* Everything else is drawn in the normal foreground, which is the manual save.
|
|
*/
|
|
export type SnapshotKind = 'save' | 'autosave' | 'backup';
|
|
|
|
/** Whether a snapshot has anything in it that the one before did not. */
|
|
export const isEmptySnapshot = (s: Snapshot): boolean => s.changed.length === 0;
|
|
|
|
/**
|
|
* The Time column, ported exactly.
|
|
*
|
|
* wxTimeSpan elapsed = now - info.date;
|
|
*
|
|
* if( elapsed.GetMinutes() < 1 ) timeStr = _( "Moments ago" );
|
|
* else if( elapsed.GetMinutes() < 91 ) timeStr = Format( _( "%d minutes ago" ), minutes );
|
|
* else if( elapsed.GetHours() < 24 ) timeStr = Format( _( "%d hours ago" ), hours );
|
|
* else timeStr = info.date.Format();
|
|
*
|
|
* The 91 is not a typo for 90 and not a rounding artefact: it means the list
|
|
* says "90 minutes ago" and never "1 hours ago", because the hours branch only
|
|
* starts once the minutes reading would have reached 91. Reproduced rather than
|
|
* tidied to 60, because a list that switched units at an hour would disagree
|
|
* with the same list in a desktop KiCad open beside it.
|
|
*
|
|
* `wxDateTime::Format()` with no argument is the locale's default date and
|
|
* time, which is `toLocaleString()` here.
|
|
*/
|
|
export function relativeTime(at: number, now: number): string {
|
|
const elapsedMs = Math.max(0, now - at);
|
|
const minutes = Math.floor(elapsedMs / 60_000);
|
|
const hours = Math.floor(elapsedMs / 3_600_000);
|
|
|
|
if (minutes < 1) return 'Moments ago';
|
|
if (minutes < 91) return `${minutes} minutes ago`;
|
|
if (hours < 24) return `${hours} hours ago`;
|
|
return new Date(at).toLocaleString();
|
|
}
|
|
|
|
/**
|
|
* The hover tooltip:
|
|
*
|
|
* wxString tip = info.message;
|
|
* ...
|
|
* tip << wxS( "\n" ) << info.date.FormatISOCombined();
|
|
*
|
|
* `FormatISOCombined` is `YYYY-MM-DDTHH:MM:SS` in *local* time, which is not
|
|
* what `toISOString()` gives - that is UTC, and would read an hour or thirteen
|
|
* out from the row above it.
|
|
*/
|
|
export function snapshotTooltip(s: Snapshot, at = s.at): string {
|
|
const d = new Date(at);
|
|
const pad = (n: number): string => String(n).padStart(2, '0');
|
|
const iso =
|
|
`${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}` +
|
|
`T${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}`;
|
|
const changed = s.changed.length > 0 ? `\n${s.changed.join('\n')}` : '';
|
|
return `${s.title}${changed}\n${iso}`;
|
|
}
|
|
|
|
/**
|
|
* Which files differ from the previous snapshot.
|
|
*
|
|
* `filesChanged` upstream is what git reports for the commit, so a rename is
|
|
* two entries and a deletion is one. Same here: a name present in one and not
|
|
* the other counts, as does a name whose hash moved.
|
|
*/
|
|
export function changedAgainst(
|
|
previous: readonly SnapshotFile[] | undefined,
|
|
next: readonly SnapshotFile[],
|
|
): string[] {
|
|
const before = new Map((previous ?? []).map((f) => [f.name, f.hash]));
|
|
const out: string[] = [];
|
|
|
|
for (const f of next) {
|
|
if (before.get(f.name) !== f.hash) out.push(f.name);
|
|
before.delete(f.name);
|
|
}
|
|
// Whatever is left was in the previous snapshot and is not in this one.
|
|
out.push(...before.keys());
|
|
|
|
return out.sort();
|
|
}
|
|
|
|
/**
|
|
* The title a snapshot gets, in the form the pane's tinting depends on.
|
|
*
|
|
* Upstream's messages are written at each call site; centralising it here is
|
|
* the difference between a rule and a convention, given the pane decides a
|
|
* row's colour by reading the first word back out of the string.
|
|
*/
|
|
export function snapshotTitle(kind: SnapshotKind, detail?: string): string {
|
|
const head = kind === 'autosave' ? 'Autosave' : kind === 'backup' ? 'Backup' : 'Save';
|
|
return detail ? `${head}: ${detail}` : head;
|
|
}
|
|
|
|
/**
|
|
* The two commit messages `RestoreCommit` writes verbatim
|
|
* (common/local_history.cpp:2288 and :2371).
|
|
*
|
|
* [data] KiCad hardcodes both. Neither begins "Autosave" or "Backup", so both
|
|
* take the pane's default row colour upstream, and `kindOfTitle` puts them on
|
|
* `save` here for the same reason.
|
|
*/
|
|
export const PRE_RESTORE_TITLE = 'Pre-restore backup';
|
|
|
|
/** `wxString::Format( wxS( "Restored from %s" ), aHash )`. */
|
|
export const restoredFromTitle = (hash: string): string => `Restored from ${hash}`;
|
|
|
|
/**
|
|
* `KICAD_MESSAGE_DIALOG`'s wording in `RestoreCommit`
|
|
* (common/local_history.cpp:2252-2270), which is shown when `aConfirm` is set —
|
|
* the Local History pane's menu item leaves it at its default of true, and only
|
|
* the recovery prompt passes false, "the recovery prompt already asked".
|
|
*
|
|
* `wxYES_NO | wxNO_DEFAULT | wxICON_QUESTION` with
|
|
* `SetYesNoLabels( _( "Restore" ), _( "Cancel" ) )`, so Cancel holds the focus
|
|
* ring: the destructive answer is never the one Enter picks.
|
|
*/
|
|
export const RESTORE_CAPTION = 'Restore Version';
|
|
export const RESTORE_YES_LABEL = 'Restore';
|
|
export const RESTORE_NO_LABEL = 'Cancel';
|
|
export const RESTORE_EXTENDED =
|
|
'Your current files are backed up first so you can undo the restore. Files ' +
|
|
'that are not part of this version are left untouched.';
|
|
|
|
/**
|
|
* `_( "Restore the project to the version from %s?" )` with the commit's own
|
|
* time, formatted `wxS( "%Y-%m-%d %H:%M:%S" )`.
|
|
*
|
|
* `wxDateTime::Format` renders LOCAL time, so this does too — a snapshot taken
|
|
* at 14:05 must read 14:05 to the person who took it. `toISOString` would print
|
|
* UTC and silently shift the number the user is being asked about.
|
|
*/
|
|
export function restoreConfirmMessage(at: number): string {
|
|
const d = new Date(at);
|
|
const p = (n: number): string => String(n).padStart(2, '0');
|
|
const stamp =
|
|
`${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())} ` +
|
|
`${p(d.getHours())}:${p(d.getMinutes())}:${p(d.getSeconds())}`;
|
|
return `Restore the project to the version from ${stamp}?`;
|
|
}
|
|
|
|
/**
|
|
* `DIALOG_RESTORE_LOCAL_HISTORY` (common/dialogs/dialog_restore_local_history.cpp),
|
|
* behind File > "Restore Project from Local History..."
|
|
* (kicad/tools/kicad_manager_actions.cpp:235-240 -> KICAD_MANAGER_FRAME::
|
|
* RestoreLocalHistory, kicad/files-io.cpp:101-104 -> LOCAL_HISTORY::
|
|
* ShowRestoreDialog, common/local_history.cpp:2384-2404).
|
|
*
|
|
* The three columns and their declared widths (:47-49, :89-91).
|
|
*
|
|
* [data] KiCad states the widths itself, as `FromDIP` pixels: 170 / 380 / 70.
|
|
*/
|
|
export const RESTORE_DIALOG_TITLE = 'Restore Project from Local History...';
|
|
export const RESTORE_LIST_COLUMNS = [
|
|
{ key: 'time', label: 'Time', width: 170 },
|
|
{ key: 'action', label: 'Action', width: 380 },
|
|
{ key: 'count', label: 'Count', width: 70 },
|
|
] as const;
|
|
|
|
/** `SetMinSize( FromDIP( wxSize( 700, 500 ) ) )` (:68). */
|
|
export const RESTORE_DIALOG_MIN_WIDTH = 700;
|
|
export const RESTORE_DIALOG_MIN_HEIGHT = 500;
|
|
|
|
/**
|
|
* `wxDateTime::FormatISOCombined()`, the Time column and the second line of the
|
|
* details box (:80, :111).
|
|
*
|
|
* Default separator is 'T', and like every other wxDateTime formatter it renders
|
|
* LOCAL time - `toISOString()` would print UTC and shift the stamp the user is
|
|
* choosing between.
|
|
*/
|
|
export function formatISOCombined(at: number): string {
|
|
const d = new Date(at);
|
|
const p = (n: number): string => String(n).padStart(2, '0');
|
|
return (
|
|
`${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())}` +
|
|
`T${p(d.getHours())}:${p(d.getMinutes())}:${p(d.getSeconds())}`
|
|
);
|
|
}
|
|
|
|
/**
|
|
* The Count column (:81-82):
|
|
*
|
|
* snapshot.filesChanged > 0 ? wxString::Format( "%d", ... ) : wxString( "-" )
|
|
*
|
|
* A plain hyphen, not an em dash and not an empty cell.
|
|
*/
|
|
export const restoreCountText = (filesChanged: number): string =>
|
|
filesChanged > 0 ? String(filesChanged) : '-';
|
|
|
|
/**
|
|
* The read-only details box, `UpdateDetails` (:102-126), built in this order:
|
|
*
|
|
* summary \n date(ISO combined) \n hash
|
|
* [ blank line, ONLY when there are changed files ]
|
|
* one changed file per line
|
|
*
|
|
* Upstream's per-file line is `<path> <adds>/<dels>/<updated>`, the line stats
|
|
* libgit2 hands it from the diff (common/local_history.cpp:1083-1097). We store
|
|
* the changed NAMES and never computed line stats, so ours is the path alone -
|
|
* a reduction, stated here rather than faked with zeroes.
|
|
*/
|
|
export function restoreDetailText(snapshot: Snapshot): string {
|
|
let text = `${snapshot.title}\n${formatISOCombined(snapshot.at)}\n${snapshot.id}`;
|
|
if (snapshot.changed.length > 0) text += `\n\n${snapshot.changed.join('\n')}`;
|
|
return text;
|
|
}
|
|
|
|
/** The kind a title encodes, which is how the pane tints a row it read back. */
|
|
export function kindOfTitle(title: string): SnapshotKind {
|
|
if (title.startsWith('Autosave')) return 'autosave';
|
|
if (title.startsWith('Backup')) return 'backup';
|
|
return 'save';
|
|
}
|
|
|
|
/**
|
|
* How much of the store a set of snapshots accounts for.
|
|
*
|
|
* Counted per distinct hash, not per file: the whole point of addressing by
|
|
* content is that ten snapshots of a project where one file changed cost one
|
|
* file, and a size that ignored that would report ten times the truth and drive
|
|
* a retention policy to delete history nobody needed to lose.
|
|
*/
|
|
export function storedBytes(snapshots: readonly Snapshot[]): number {
|
|
const seen = new Map<string, number>();
|
|
for (const s of snapshots) {
|
|
for (const f of s.files) seen.set(f.hash, f.size);
|
|
}
|
|
let total = 0;
|
|
for (const size of seen.values()) total += size;
|
|
return total;
|
|
}
|
|
|
|
/**
|
|
* Which snapshots to drop to get under a byte budget, oldest first.
|
|
*
|
|
* `EnforceSizeLimit( aProjectPath, aMaxBytes, ... )` upstream, which walks back
|
|
* from the oldest commit. Two rules that are not obvious:
|
|
*
|
|
* - The newest snapshot is never dropped. A history whose limit is smaller
|
|
* than one snapshot should hold one snapshot, not none; deleting the last
|
|
* copy of the current state to satisfy a size cap is the one outcome nobody
|
|
* wants from a feature called history.
|
|
* - Dropping a snapshot frees only the hashes no surviving snapshot still
|
|
* references, which is why this measures what is left rather than what goes.
|
|
*/
|
|
/**
|
|
* Newest first. `at` alone ties for two saves inside one millisecond, and the
|
|
* index hands ties back oldest first, so `commitSnapshot` compared against the
|
|
* OLDER of the two: a file reverted within that millisecond read as unchanged
|
|
* and the save was dropped. The id's suffix is the sub-millisecond stamp that
|
|
* separates them, compared as a number - as a base-36 string it misorders
|
|
* across a change of length.
|
|
*/
|
|
export function newestFirst(a: { at: number; id: string }, b: { at: number; id: string }): number {
|
|
return b.at - a.at || snapshotIdTick(b.id) - snapshotIdTick(a.id);
|
|
}
|
|
|
|
/** The sub-millisecond stamp after the `-` of a snapshot id; 0 for none. */
|
|
export function snapshotIdTick(id: string): number {
|
|
const tick = Number.parseInt(id.slice(id.indexOf('-') + 1), 36);
|
|
return Number.isNaN(tick) ? 0 : tick;
|
|
}
|
|
|
|
export function snapshotsToEvict(snapshots: readonly Snapshot[], maxBytes: number): string[] {
|
|
// Oldest first, by the same order as the list: three saves in one
|
|
// millisecond, handed over newest first, sorted on `at` alone kept the
|
|
// newest at the front and evicted it.
|
|
const byAge = [...snapshots].sort((a, b) => newestFirst(b, a));
|
|
const evicted: string[] = [];
|
|
|
|
for (let i = 0; i < byAge.length - 1; i++) {
|
|
if (storedBytes(byAge.slice(i)) <= maxBytes) break;
|
|
const victim = byAge[i];
|
|
if (victim) evicted.push(victim.id);
|
|
}
|
|
|
|
return evicted;
|
|
}
|