@davmash/bygone 0.9.8 → 0.10.1

package/out/tourDocument.js

@@ -0,0 +1,97 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/tourDocument.ts
+var tourDocument_exports = {};
+__export(tourDocument_exports, {
+  classifyAuthoredTourPaths: () => classifyAuthoredTourPaths,
+  discoverAuthoredTourDocument: () => discoverAuthoredTourDocument,
+  isAuthoredTourPath: () => isAuthoredTourPath
+});
+module.exports = __toCommonJS(tourDocument_exports);
+var import_child_process = require("child_process");
+var fs = __toESM(require("fs"));
+var path = __toESM(require("path"));
+function isAuthoredTourPath(candidate, platform = process.platform) {
+  const comparable = platform === "win32" || platform === "darwin" ? candidate.toLocaleLowerCase("en-US") : candidate;
+  return comparable.endsWith(".bygone") || comparable.endsWith(".bygone.yaml");
+}
+function classifyAuthoredTourPaths(candidates, platform = process.platform) {
+  const tourPaths = candidates.filter((candidate) => isAuthoredTourPath(candidate, platform));
+  if (tourPaths.length === 0) return { kind: "none", paths: candidates };
+  if (tourPaths.length === 1 && candidates.length === 1) return { kind: "single", path: tourPaths[0] };
+  if (tourPaths.length === candidates.length) return { kind: "multiple", paths: tourPaths };
+  return {
+    kind: "mixed",
+    tourPaths,
+    otherPaths: candidates.filter((candidate) => !isAuthoredTourPath(candidate, platform))
+  };
+}
+function discoverAuthoredTourDocument(sourcePath) {
+  const requestedPath = path.resolve(sourcePath);
+  let documentPath;
+  try {
+    documentPath = fs.realpathSync(requestedPath);
+    if (!fs.statSync(documentPath).isFile()) {
+      throw new Error("path is not a regular file");
+    }
+  } catch (error) {
+    throw errorWithCause(`Could not open Bygone source ${requestedPath}: ${errorMessage(error)}`, error);
+  }
+  let repoRoot;
+  try {
+    const discoveredRoot = (0, import_child_process.execFileSync)("git", ["rev-parse", "--show-toplevel"], {
+      cwd: path.dirname(documentPath),
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"]
+    }).trim();
+    repoRoot = fs.realpathSync(discoveredRoot);
+  } catch (error) {
+    throw errorWithCause(
+      `Bygone source ${documentPath} needs its Git repository. Place it inside the corresponding worktree or open it with an explicit repository working directory.`,
+      error
+    );
+  }
+  return { documentPath, repoRoot };
+}
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function errorWithCause(message, cause) {
+  const error = new Error(message);
+  error.cause = cause;
+  return error;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  classifyAuthoredTourPaths,
+  discoverAuthoredTourDocument,
+  isAuthoredTourPath
+});
+//# sourceMappingURL=tourDocument.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davmash/bygone",
-  "version": "0.9.8",
+  "version": "0.10.1",
   "description": "See how change happened. Visual diff and file history.",
   "author": "David Mashburn",
   "license": "MIT",

package/schemas/change-tour-source.schema.json

@@ -7,20 +7,23 @@
   "additionalProperties": false,
   "required": ["version", "anchors", "connections", "chapters"],
   "properties": {
-    "version": { "enum": [1, 2, 3] },
+    "version": { "enum": [1, 2, 4, 5] },
+    "opening": { "$ref": "#/$defs/passage" },
+    "conclusion": { "$ref": "#/$defs/passage" },
     "title": { "$ref": "#/$defs/nonEmptyString" },
     "windowTitle": {
       "$ref": "#/$defs/nonEmptyString",
       "description": "Optional native window title for the tour presenter. Use a short label such as a pull request number when multiple tours may be open."
     },
     "sourceUrl": { "type": "string", "minLength": 1 },
+    "details": { "$ref": "#/$defs/details" },
     "range": {
       "type": "object",
       "additionalProperties": false,
       "required": ["base", "head"],
       "properties": {
-        "base": { "$ref": "#/$defs/nonEmptyString" },
-        "head": { "$ref": "#/$defs/nonEmptyString" }
+        "base": { "$ref": "#/$defs/prose" },
+        "head": { "$ref": "#/$defs/prose" }
       }
     },
     "coverage": {
@@ -34,7 +37,6 @@
         }
       }
     },
-    "review": { "$ref": "#/$defs/review" },
     "anchors": {
       "type": "object",
       "propertyNames": { "minLength": 1 },
@@ -69,10 +71,29 @@
     }
   },
   "allOf": [
+    {
+      "if": { "properties": { "version": { "const": 5 } } },
+      "then": {
+        "properties": {
+          "chapters": { "$ref": "#/$defs/purposeChapters" },
+          "tours": { "additionalProperties": { "properties": {
+            "chapters": { "$ref": "#/$defs/purposeChapters" }
+          } } }
+        }
+      },
+      "else": {
+        "properties": {
+          "opening": false, "conclusion": false, "details": false, "chapters": { "$ref": "#/$defs/legacyFramingChapters" },
+          "tours": { "additionalProperties": { "properties": {
+            "opening": false, "conclusion": false, "details": false, "chapters": { "$ref": "#/$defs/legacyFramingChapters" }
+          } } }
+        }
+      }
+    },
     {
       "if": { "properties": { "version": { "enum": [1, 2] } }, "required": ["version"] },
       "then": {
-        "not": { "anyOf": [{ "required": ["tours"] }, { "required": ["review"] }] },
+        "not": { "required": ["tours"] },
         "properties": {
           "chapters": {
             "items": {
@@ -106,7 +127,7 @@
       }
     },
     {
-      "if": { "properties": { "version": { "enum": [2, 3] } }, "required": ["version"] },
+      "if": { "properties": { "version": { "enum": [2, 4, 5] } }, "required": ["version"] },
       "then": {
         "properties": {
           "chapters": {
@@ -126,8 +147,53 @@
     }
   ],
   "$defs": {
+    "legacyFramingChapters": {
+      "items": {
+        "allOf": [
+          { "not": { "required": ["summary"] } },
+          { "properties": { "scenes": {
+            "items": { "properties": { "overview": { "not": { "required": ["purpose"] } } } }
+          } } }
+        ]
+      }
+    },
+    "purposeChapters": {
+      "items": { "properties": { "scenes": {
+        "items": { "properties": { "overview": { "required": ["purpose"] } } }
+      } } }
+    },
+    "prose": { "type": "string", "pattern": "\\S" },
+    "passage": {
+      "type": "object", "additionalProperties": false,
+      "required": ["title", "summary"],
+      "properties": {
+        "title": { "$ref": "#/$defs/prose" },
+        "summary": { "$ref": "#/$defs/prose" },
+        "bullets": { "type": "array", "items": { "$ref": "#/$defs/prose" } }
+      }
+    },
     "nonEmptyString": { "type": "string", "minLength": 1 },
-    "reviewString": { "type": "string", "minLength": 1, "pattern": "\\S" },
+    "details": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "audience": { "$ref": "#/$defs/audience" }
+      }
+    },
+    "audience": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["codebase", "language", "readingDemand", "purpose", "scope"],
+      "properties": {
+        "codebase": { "enum": ["none", "some", "maintainer"] },
+        "language": { "enum": ["none", "basic", "fluent", "advanced"] },
+        "domain": { "type": "array", "items": { "$ref": "#/$defs/prose" } },
+        "readingDemand": { "enum": ["general", "technical", "specialist"] },
+        "purpose": { "enum": ["overview", "explanation", "review"] },
+        "scope": { "$ref": "#/$defs/prose" },
+        "estimatedMinutes": { "type": "number", "exclusiveMinimum": 0 }
+      }
+    },
     "stringArray": {
       "type": "array",
       "items": { "type": "string" }
@@ -179,6 +245,7 @@
       "additionalProperties": false,
       "required": ["kind"],
       "properties": {
+        "purpose": { "$ref": "#/$defs/prose" },
         "kind": { "const": "directory-diff" },
         "comparison": {
           "type": "object",
@@ -208,63 +275,6 @@
         "confidence": { "enum": ["high", "medium", "low"] }
       }
     },
-    "review": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": ["baseOid", "headOid", "items"],
-      "properties": {
-        "baseOid": { "$ref": "#/$defs/fullGitOid" },
-        "headOid": { "$ref": "#/$defs/fullGitOid" },
-        "items": {
-          "type": "array",
-          "minItems": 1,
-          "items": { "$ref": "#/$defs/reviewItem" }
-        }
-      }
-    },
-    "fullGitOid": {
-      "type": "string",
-      "pattern": "^(?:[0-9a-fA-F]{40}|[0-9a-fA-F]{64})$"
-    },
-    "reviewItem": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": ["id", "kind", "title", "body", "evidence"],
-      "properties": {
-        "id": { "$ref": "#/$defs/reviewString" },
-        "kind": { "enum": ["concept", "boundary", "tradeoff", "question"] },
-        "title": { "$ref": "#/$defs/reviewString" },
-        "body": { "$ref": "#/$defs/reviewString" },
-        "evidence": {
-          "type": "array",
-          "items": { "$ref": "#/$defs/reviewEvidence" }
-        },
-        "nextCheck": { "$ref": "#/$defs/reviewString" }
-      },
-      "allOf": [
-        {
-          "if": {
-            "properties": { "kind": { "const": "question" } },
-            "required": ["kind"]
-          },
-          "then": { "required": ["nextCheck"] },
-          "else": {
-            "properties": {
-              "evidence": { "minItems": 1 }
-            }
-          }
-        }
-      ]
-    },
-    "reviewEvidence": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": ["sceneId", "stepId"],
-      "properties": {
-        "sceneId": { "$ref": "#/$defs/reviewString" },
-        "stepId": { "$ref": "#/$defs/reviewString" }
-      }
-    },
     "step": {
       "type": "object",
       "additionalProperties": false,
@@ -274,6 +284,15 @@
         "title": { "$ref": "#/$defs/nonEmptyString" },
         "body": { "$ref": "#/$defs/nonEmptyString" },
         "focus": { "$ref": "#/$defs/nonEmptyString" },
+        "image": {
+          "type": "object", "additionalProperties": false,
+          "required": ["file", "revision", "alt"],
+          "properties": {
+            "file": { "$ref": "#/$defs/nonEmptyString" },
+            "revision": { "enum": ["base", "head"] },
+            "alt": { "$ref": "#/$defs/nonEmptyString" }
+          }
+        },
         "connection": { "$ref": "#/$defs/nonEmptyString" },
         "depth": { "enum": ["mentioned", "explained", "contextualized"] },
         "requirement": { "$ref": "#/$defs/requirement" }
@@ -440,6 +459,7 @@
       "properties": {
         "id": { "$ref": "#/$defs/nonEmptyString" },
         "title": { "$ref": "#/$defs/nonEmptyString" },
+        "summary": { "$ref": "#/$defs/prose" },
         "scenes": {
           "type": "array",
           "minItems": 1,
@@ -458,6 +478,9 @@
       "additionalProperties": false,
       "required": ["chapters"],
       "properties": {
+        "opening": { "$ref": "#/$defs/passage" },
+        "conclusion": { "$ref": "#/$defs/passage" },
+        "details": { "$ref": "#/$defs/details" },
         "chapters": {
           "type": "array",
           "minItems": 1,
@@ -472,6 +495,7 @@
       "properties": {
         "id": { "$ref": "#/$defs/nonEmptyString" },
         "title": { "$ref": "#/$defs/nonEmptyString" },
+        "summary": { "$ref": "#/$defs/prose" },
         "scenes": {
           "type": "array",
           "minItems": 1,
@@ -489,6 +513,9 @@
       "additionalProperties": false,
       "required": ["chapters"],
       "properties": {
+        "opening": { "$ref": "#/$defs/passage" },
+        "conclusion": { "$ref": "#/$defs/passage" },
+        "details": { "$ref": "#/$defs/details" },
         "chapters": {
           "type": "array",
           "minItems": 1,