Update notes to specific version. (#156)

* Update notes to specific version.

* Address review comments.

* Update to 'latest'.

Author: tomusdrw

shared/links-metadata/src/link.ts

@@ -1,6 +1,6 @@
 import type { SynctexStore } from "./SynctexStore";
 import type { TexStore } from "./TexStore";
-import { type Metadata, ORIGIN } from "./metadata";
+import { type Metadata, ORIGIN, shortVersionId } from "./metadata";
 import { migrateSelection } from "./migrate";
 import type { ISelectionParams, ISynctexBlockId } from "./types";
 
@@ -61,6 +61,7 @@ export async function parseAndMigrateLink(
   meta: Metadata,
   synctexStore: SynctexStore,
   texStore: TexStore,
+  toVersion: string,
   lineNumber = 0,
 ): Promise<Link> {
   const linkData = parseLink(url, meta);
@@ -78,30 +79,31 @@ export async function parseAndMigrateLink(
     };
   }
   const { version, versionName, selectionStart, selectionEnd } = linkData;
-  const isOutdated = version !== meta.metadata.latest;
+  const isOutdated = version !== toVersion;
   let updated: string | null = null;
   let migrated = false;
 
-  // check if the blocks are still there in the latest metadata
+  // check if the blocks are still there in the requested version of metadata
   if (isOutdated && selectionStart && selectionEnd) {
     const migratedSelection = await migrateSelection(
       { selectionStart, selectionEnd },
       version,
-      meta.metadata.latest,
+      toVersion,
       synctexStore,
       texStore,
     );
 
+    const toVersionShort = shortVersionId(toVersion);
     if (migratedSelection) {
-      updated = `${ORIGIN}#/${meta.latestShort}/${encodePageNumberAndIndex(migratedSelection.selectionStart)}${encodePageNumberAndIndex(migratedSelection.selectionEnd)}`;
+      updated = `${ORIGIN}#/${toVersionShort}/${encodePageNumberAndIndex(migratedSelection.selectionStart)}${encodePageNumberAndIndex(migratedSelection.selectionEnd)}`;
       migrated = true;
     } else {
-      const latestSynctex = await synctexStore.getSynctex(meta.metadata.latest);
-      const hasStart = !!latestSynctex.blocksByPage.get(selectionStart.pageNumber)?.[selectionStart.index];
-      const hasEnd = !!latestSynctex.blocksByPage.get(selectionEnd.pageNumber)?.[selectionEnd.index];
+      const toVersionSynctex = await synctexStore.getSynctex(toVersion);
+      const hasStart = !!toVersionSynctex.blocksByPage.get(selectionStart.pageNumber)?.[selectionStart.index];
+      const hasEnd = !!toVersionSynctex.blocksByPage.get(selectionEnd.pageNumber)?.[selectionEnd.index];
 
       if (hasStart && hasEnd) {
-        updated = `${ORIGIN}#/${meta.latestShort}/${linkData.blocks}`;
+        updated = `${ORIGIN}#/${toVersionShort}/${linkData.blocks}`;
       }
     }
   }

shared/links-metadata/src/metadata.ts

@@ -63,7 +63,7 @@ function getShortVersionMapping(data: JsonMetadata) {
   return res;
 }
 
-function shortVersionId(hash: string) {
+export function shortVersionId(hash: string) {
   const SHORT_COMMIT_HASH_LENGTH = 7; // as many as git uses for `git rev-parse --short`
   return hash.substring(0, SHORT_COMMIT_HASH_LENGTH);
 }

tools/links-check/index.ts

@@ -26,7 +26,8 @@ async function main() {
       "--ignore-file <path>",
       "Path to a file containing patterns to ignore. Gitignore format applies. Patterns are resolved according to current working directory.",
     )
-    .option("--write", "Modify the files and update reader links to their newest versions.")
+    .option("--version <name>", "Commit hash of specific version to update to (instead of latest)")
+    .option("--write", "Modify the files and update reader links to requested/lastest versions.")
     .option("--fix", "Alias for --write.")
     .option("--generate-notes <file.json>", "Generate notes for the Gray Paper Reader")
     .action(async (paths, options) => {
@@ -82,7 +83,7 @@ async function main() {
       console.time(label);
       let report: Report | null = null;
       try {
-        report = await scan(files, metadata);
+        report = await scan(files, metadata, options.version);
       } finally {
         console.timeEnd(label);
       }

tools/links-check/scan.ts

@@ -23,24 +23,27 @@ class Timer {
   }
 }
 
-export async function scan(files: Path[], metadata: Metadata): Promise<Report> {
+export async function scan(files: Path[], metadata: Metadata, version?: string): Promise<Report> {
   const timer = new Timer();
   const synctexStore = new SynctexStore();
   const texStore = new TexStore();
   const cwd = process.cwd();
+  const versionData = findVersion(metadata, version);
+  const toVersion = versionData.hash;
+
   const results = await Promise.allSettled(
     files.map(async (file) => {
       const relativeFilePath = path.relative(cwd, file);
       timer.start(relativeFilePath);
-      const fileReport = await scanFile(file, metadata, synctexStore, texStore);
+      const fileReport = await scanFile(file, metadata, synctexStore, texStore, toVersion);
       timer.end(relativeFilePath, fileReport.allLinks.length > 0);
       printFileReport(fileReport);
       return fileReport;
     }),
   );
 
   const report = {
-    latestVersion: metadata.metadata.versions[metadata.metadata.latest]?.name || metadata.latestShort,
+    latestVersion: versionData.name || version || metadata.latestShort,
     detected: new Map(),
     outdated: new Map(),
     failed: new Map(),
@@ -63,11 +66,29 @@ export async function scan(files: Path[], metadata: Metadata): Promise<Report> {
   return Promise.resolve(report);
 }
 
+function findVersion(metadata: Metadata, version = "latest") {
+  const v = version === "latest" ? metadata.metadata.latest : version;
+  const versionData = metadata.metadata.versions[v];
+  if (versionData) {
+    return versionData;
+  }
+
+  // try lookup by name instead.
+  for (const v of Object.values(metadata.metadata.versions)) {
+    if (v.name === version) {
+      return v;
+    }
+  }
+
+  throw new Error(`Version ${version} not found.`);
+}
+
 async function scanFile(
   path: Path,
   metadata: Metadata,
   synctexStore: SynctexStore,
   texStore: TexStore,
+  toVersion: string,
 ): Promise<FileReport> {
   const links: [number, string][] = [];
   const report: FileReport = {
@@ -83,7 +104,9 @@ async function scanFile(
   });
 
   const linksParsed = await Promise.all(
-    links.map(([lineNumber, link]) => parseAndMigrateLink(link, metadata, synctexStore, texStore, lineNumber)),
+    links.map(([lineNumber, link]) =>
+      parseAndMigrateLink(link, metadata, synctexStore, texStore, toVersion, lineNumber),
+    ),
   );
 
   report.allLinks = linksParsed;