skir 1.0.5 → 1.0.7

package/src/formatter.ts

@@ -14,11 +14,17 @@ export interface TextEdit {
   readonly newText: string;
 }
 
+/** A function which returns a random number between 0 and 1. */
+export type RandomGenerator = () => number;
+
 /**
  * Formats the given module and returns the new source code.
  * Preserves token ordering.
  */
-export function formatModule(moduleTokens: ModuleTokens): FormattedModule {
+export function formatModule(
+  moduleTokens: ModuleTokens,
+  randomGenerator: RandomGenerator = Math.random,
+): FormattedModule {
   const tokens = moduleTokens.tokensWithComments;
 
   const context: Context = {
@@ -28,9 +34,14 @@ export function formatModule(moduleTokens: ModuleTokens): FormattedModule {
 
   let newSourceCode = "";
   const textEdits: TextEdit[] = [];
+  let lastNonCommentToken = "";
 
   const appendToken: (t: Token) => void = (t: Token) => {
-    const newToken = normalizeToken(t.text);
+    const newToken = normalizeToken(
+      t.text,
+      lastNonCommentToken,
+      randomGenerator,
+    );
     if (newToken !== t.text) {
       textEdits.push({
         oldStart: t.position,
@@ -38,6 +49,9 @@ export function formatModule(moduleTokens: ModuleTokens): FormattedModule {
         newText: newToken,
       });
     }
+    if (!isComment(t)) {
+      lastNonCommentToken = t.text;
+    }
     newSourceCode += newToken;
   };
   appendToken(tokens[0]!);
@@ -248,7 +262,11 @@ function isComment(token: Token): boolean {
   return token.text.startsWith("//") || token.text.startsWith("/*");
 }
 
-function normalizeToken(token: string): string {
+function normalizeToken(
+  token: string,
+  lastNonCommentToken: string,
+  randomGenerator: RandomGenerator,
+): string {
   if (token.startsWith("//")) {
     // Make sure there is a space between the double slash and the comment text.
     if (
@@ -279,6 +297,9 @@ function normalizeToken(token: string): string {
     // A double-quoted string
     // Remove escape characters before double quotes.
     return token.replace(/\\(?=(?:\\\\)*')/g, "");
+  } else if (token === "?" && ["=", "("].includes(lastNonCommentToken)) {
+    const randomNumber = Math.floor(randomGenerator() * 1_000_000);
+    return String(randomNumber);
   } else {
     return token;
   }

package/src/module_set.ts

@@ -1298,7 +1298,7 @@ abstract class ModuleParserBase implements ModuleParser {
       };
     }
 
-    return parseModule(tokens.result);
+    return parseModule(tokens.result, "strict");
   }
 }
 

package/src/parser.ts

@@ -33,10 +33,13 @@ import { mergeDocs } from "./doc_comment_parser.js";
 import { ModuleTokens } from "./tokenizer.js";
 
 /** Runs syntactic analysis on a module. */
-export function parseModule(moduleTokens: ModuleTokens): Result<MutableModule> {
+export function parseModule(
+  moduleTokens: ModuleTokens,
+  mode: "strict" | "lenient",
+): Result<MutableModule> {
   const { modulePath, sourceCode } = moduleTokens;
   const errors: SkirError[] = [];
-  const it = new TokenIterator(moduleTokens, errors);
+  const it = new TokenIterator(moduleTokens, mode, errors);
   const declarations = parseDeclarations(it, "module");
   it.expectThenNext([""]);
   // Create a mappinng from names to declarations, and check for duplicates.
@@ -404,8 +407,8 @@ function parseRecord(
   let stableId: number | null = null;
   if (it.current === "(") {
     it.next();
-    stableId = parseUint32(it);
-    if (stableId < 0) {
+    stableId = parseUint32(it, "?");
+    if (stableId === -2) {
       return null;
     }
     if (it.expectThenNext([")"]).case < 0) {
@@ -671,10 +674,14 @@ function parseRecordRef(
   return { kind: "record", nameParts: nameParts, absolute: absolute };
 }
 
-function parseUint32(it: TokenIterator): number {
+function parseUint32(it: TokenIterator, maybeQuestionMark?: "?"): number {
+  if (maybeQuestionMark && it.mode === "lenient" && it.current === "?") {
+    it.next();
+    return -1;
+  }
   const match = it.expectThenNext([TOKEN_IS_POSITIVE_INT]);
   if (match.case < 0) {
-    return -1;
+    return -2;
   }
   const { text } = match.token;
   const valueAsBigInt = BigInt(text);
@@ -685,7 +692,7 @@ function parseUint32(it: TokenIterator): number {
       token: match.token,
       message: "Value out of uint32 range",
     });
-    return -1;
+    return -2;
   }
 }
 
@@ -865,8 +872,8 @@ function parseMethod(it: TokenIterator, doc: Doc): MutableMethod | null {
   if (it.expectThenNext(["="]).case < 0) {
     return null;
   }
-  const number = parseUint32(it);
-  if (number < 0) {
+  const number = parseUint32(it, "?");
+  if (number === -2) {
     return null;
   }
   it.expectThenNext([";"]);
@@ -1121,6 +1128,7 @@ class TokenIterator {
 
   constructor(
     readonly moduleTokens: ModuleTokens,
+    readonly mode: "strict" | "lenient",
     readonly errors: ErrorSink,
   ) {
     this.tokens = moduleTokens.tokens;

package/src/snapshotter.ts

@@ -1,6 +1,7 @@
 import { readFile, writeFile } from "node:fs/promises";
 import { join } from "node:path";
-import { checkBackwardCompatibility } from "./compatibility_checker.js";
+import { RecordLocation, ResolvedType } from "skir-internal";
+import { checkCompatibility } from "./compatibility_checker.js";
 import {
   formatError,
   makeGreen,
@@ -37,7 +38,7 @@ export async function takeSnapshot(args: {
     );
     return false;
   }
-  const breakingChanges = checkBackwardCompatibility({
+  const breakingChanges = checkCompatibility({
     before: oldModuleSet,
     after: newModuleSet,
   });
@@ -65,6 +66,33 @@ export async function takeSnapshot(args: {
   }
   await writeFile(snapshotPath, JSON.stringify(newSnapshot, null, 2), "utf-8");
   console.log("Snapshot taken. No breaking changes detected.");
+
+  const trackedRecordCount = newSnapshot.trackedRecordIds.length;
+  const untrackedRecordCount = newSnapshot.untrackedRecordIds.length;
+  const formatCount = (n: number, what: string): string => {
+    return `${n} ${what}${n === 1 ? "" : "s"}`;
+  };
+  console.log(
+    [
+      formatCount(trackedRecordCount, "tracked record"),
+      ", ",
+      formatCount(untrackedRecordCount, "untracked record"),
+      " found in new snapshot.",
+    ].join(""),
+  );
+  console.log("See them in " + rewritePathForRendering(snapshotPath));
+
+  if (trackedRecordCount === 0) {
+    console.log(makeRed("Warning: no tracked records found."));
+    console.log(
+      "Breaking changes cannot be detected without tracking records.",
+    );
+    console.log(
+      "To track a record and its dependencies, give it a stable identifier, e.g.:",
+    );
+    console.log("  struct MyStruct(56789) { ... }");
+  }
+
   return true;
 }
 
@@ -173,9 +201,12 @@ function makeSnapshot(moduleSet: ModuleSet, now: Date): Snapshot {
   for (const module of moduleSet.resolvedModules) {
     modules[module.path] = module.sourceCode;
   }
+  const trackedRecordIds = collectTrackedRecords(moduleSet);
   return {
     readMe: "DO NOT EDIT. To update, run: npx skir snapshot",
     lastChange: now.toISOString(),
+    trackedRecordIds: Array.from(trackedRecordIds.trackedRecordIds).sort(),
+    untrackedRecordIds: Array.from(trackedRecordIds.untrackedRecordIds).sort(),
     modules,
   };
 }
@@ -192,5 +223,70 @@ function sameModules(a: Snapshot, b: Snapshot): boolean {
 interface Snapshot {
   readMe: string;
   lastChange: string;
-  modules: { [path: string]: string };
+  trackedRecordIds: readonly string[];
+  untrackedRecordIds: readonly string[];
+  modules: Readonly<{ [path: string]: string }>;
+}
+
+interface TrackedRecords {
+  trackedRecordIds: ReadonlySet<string>;
+  untrackedRecordIds: ReadonlySet<string>;
+}
+
+function collectTrackedRecords(moduleSet: ModuleSet): TrackedRecords {
+  const seenRecordIds = new Set<string>();
+  const trackedRecordIds = new Set<string>();
+
+  const getRecordId = (record: RecordLocation): string => {
+    const qualifiedName = record.recordAncestors
+      .map((token) => token.name.text)
+      .join(".");
+    return `${record.modulePath}:${qualifiedName}`;
+  };
+
+  const getRecordForType = (type: ResolvedType): RecordLocation | null => {
+    switch (type.kind) {
+      case "array":
+        return getRecordForType(type.item);
+      case "optional":
+        return getRecordForType(type.other);
+      case "primitive":
+        return null;
+      case "record":
+        return moduleSet.recordMap.get(type.key) ?? null;
+    }
+  };
+
+  const processRecord = (record: RecordLocation): void => {
+    const recordId = getRecordId(record);
+    if (seenRecordIds.has(recordId)) {
+      return;
+    }
+    seenRecordIds.add(recordId);
+    if (record.record.recordNumber === null) {
+      return;
+    }
+    trackedRecordIds.add(recordId);
+    // Recursively process the field/variant types
+    for (const field of record.record.fields) {
+      const fieldType = field.type;
+      if (fieldType) {
+        const fieldRecord = getRecordForType(fieldType);
+        if (fieldRecord) {
+          processRecord(fieldRecord);
+        }
+      }
+    }
+  };
+
+  for (const record of moduleSet.recordMap.values()) {
+    processRecord(record);
+  }
+  const untrackedRecordIds = new Set(
+    [...seenRecordIds].filter((id) => !trackedRecordIds.has(id)),
+  );
+  return {
+    trackedRecordIds: trackedRecordIds,
+    untrackedRecordIds: untrackedRecordIds,
+  };
 }