@sous-io/sous 0.2.28 → 0.2.30

package/src/lib/repos/formats/variable-definition.ts

@@ -0,0 +1,268 @@
+/**
+ * A recipe's variable definitions: what each variable is called, what shape an
+ * answer takes, and what question to ask. A recipe manifest declares them
+ * (`recipe-manifest.ts` re-exports everything here), and `sous repo release`
+ * copies each version's definitions into the index, so the same fields and the
+ * same rules read both copies.
+ *
+ * This module imports nothing but the shared primitives, because the index
+ * reads it, and the index sits below the ref parser the manifest needs.
+ */
+
+import { z } from "zod";
+import {
+  envVarNameSchema,
+  extensibleObject,
+  forwardCompatibleObject,
+  variableNameSchema,
+} from "./common.js";
+
+// --- Variable definitions -----------------------------------------------------------------------
+
+/** The value types a recipe may declare for a variable. */
+export const VARIABLE_TYPES = [
+  "string",
+  "number",
+  "boolean",
+  "enum",
+  "path",
+  "url",
+] as const;
+
+/** Which env file an answer is written to. */
+export const VARIABLE_SCOPES = ["shared", "local"] as const;
+
+/** Constraints checked against an answer before it is accepted or stored. */
+const variableValidationShape = {
+  /** A regular expression the answer must match, as a string. */
+  pattern: z
+    .string()
+    .refine(
+      (value) => {
+        try {
+          new RegExp(value);
+          return true;
+        } catch {
+          return false;
+        }
+      },
+      { message: "must be a valid regular expression" }
+    )
+    .optional(),
+  /** Minimum length of a string answer. */
+  minLength: z.number().int().min(0).optional(),
+  /** Maximum length of a string answer. */
+  maxLength: z.number().int().min(0).optional(),
+  /** Minimum value of a numeric answer. */
+  min: z.number().optional(),
+  /** Maximum value of a numeric answer. */
+  max: z.number().optional(),
+  /** The allowed answers. Required when the variable's type is 'enum'. */
+  enum: z.array(z.string()).min(1, "must list at least one option").optional(),
+};
+
+/** Constraints checked against an answer before it is accepted or stored. */
+export const variableValidationSchema = extensibleObject(variableValidationShape);
+
+/**
+ * The fields of a variable definition, shared by the two schemas that read
+ * one: the hand-written manifest, and the copy a release records in the index.
+ *
+ * @param validate - The schema for the `validate` block, strict or forward compatible.
+ */
+function variableDefinitionShape<Validate extends z.ZodType>(validate: Validate) {
+  return {
+    /** The variable's camelCase name, as templates refer to it. */
+    name: variableNameSchema,
+    /**
+     * The environment variable an answer binds to. Authors may name an existing
+     * variable such as GITHUB_TOKEN to reuse a value already in the environment.
+     * When omitted, `sous repo release` derives an upper snake case default from
+     * the name; the runtime never derives one.
+     */
+    env: envVarNameSchema.optional(),
+    /** The answer's type, which decides how it is validated and prompted for. */
+    type: z.enum(VARIABLE_TYPES),
+    /** The one-line question shown when the variable is asked. */
+    prompt: z.string().min(1, "must not be empty"),
+    /**
+     * The paragraph that explains the variable: what it is for, what a good
+     * answer looks like, and what changes when it is set. Shown above the
+     * question when sous asks, and by `sous vars <name>`. Required, because a
+     * consumer reading the question has no other way to learn what a publisher
+     * meant by it.
+     */
+    description: z
+      .string({
+        error:
+          "is required: every published variable must explain itself in a sentence or " +
+          "two. The description is shown above the question when sous asks, and by " +
+          "'sous vars <name>'",
+      })
+      .min(1, "must not be empty"),
+    /**
+     * A realistic sample answer. It is documentation and prompt copy only; sous
+     * never stores it, never offers it as the answer, and never falls back to it.
+     * Use `default` for a value a project should actually start with.
+     */
+    example: z.union([z.string(), z.number(), z.boolean()], {
+      error:
+        "is required: every published variable must show what a real answer looks like. " +
+        "The example is shown with the question and by 'sous vars <name>'; it is " +
+        "documentation only and is never stored as the answer (use 'default' for that)",
+    }),
+    /** The value offered when the question is asked with nothing else in scope. */
+    default: z.union([z.string(), z.number(), z.boolean()]).optional(),
+    /** Whether an answer is needed for a build to run. Defaults to true. */
+    required: z.boolean().default(true),
+    /**
+     * Whether the answer is a secret. A secret is always written to the
+     * gitignored `.sous/.env.local`, never to the committed `.sous/.env`.
+     */
+    secret: z.boolean().default(false),
+    /**
+     * Which env file the answer is written to: 'shared' is `.sous/.env`, which is
+     * committed and shared with the team; 'local' is `.sous/.env.local`, which is
+     * gitignored and machine-specific. Defaults to 'shared'.
+     */
+    scope: z.enum(VARIABLE_SCOPES).default("shared"),
+    /** Constraints checked against an answer. */
+    validate: validate.optional(),
+  };
+}
+
+/** What `checkVariableDefinition` reads from a definition. */
+type CheckedDefinition = {
+  type: VariableType;
+  secret: boolean;
+  scope: VariableScope;
+  default?: string | number | boolean | undefined;
+  example: string | number | boolean;
+  validate?:
+    | { minLength?: number; maxLength?: number; min?: number; max?: number; enum?: string[] }
+    | undefined;
+};
+
+/**
+ * The rules a variable definition obeys beyond the shape of each field, shared
+ * by both schemas so a definition the index records is held to exactly the rules
+ * its manifest was.
+ *
+ * @param definition - The definition, already parsed field by field.
+ * @param ctx - The refinement context issues are added to.
+ */
+function checkVariableDefinition(definition: CheckedDefinition, ctx: z.RefinementCtx): void {
+  const { type, validate } = definition;
+
+  if (type === "enum" && (validate?.enum === undefined || validate.enum.length === 0)) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["validate", "enum"],
+      message:
+        "a variable of type 'enum' must list its options under 'validate.enum'",
+    });
+  }
+
+  if (validate !== undefined) {
+    const { minLength, maxLength, min, max } = validate;
+    if (minLength !== undefined && maxLength !== undefined && minLength > maxLength) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["validate", "maxLength"],
+        message: "must not be smaller than 'validate.minLength'",
+      });
+    }
+    if (min !== undefined && max !== undefined && min > max) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["validate", "max"],
+        message: "must not be smaller than 'validate.min'",
+      });
+    }
+  }
+
+  // A secret written to the committed env file would leak, so the two fields
+  // are not allowed to contradict each other.
+  if (definition.secret && definition.scope === "shared") {
+    ctx.addIssue({
+      code: "custom",
+      path: ["scope"],
+      message:
+        "a secret variable is stored in the gitignored '.sous/.env.local', so its " +
+        "scope must be 'local' (or left unset)",
+    });
+  }
+
+  // `default` and `example` are both literal values written by the publisher,
+  // so both have to fit the variable they describe; an example that could
+  // never be a valid answer is worse than no example at all.
+  checkDeclaredValue(definition.default, "default");
+  checkDeclaredValue(definition.example, "example");
+
+  /**
+   * Checks one publisher-written literal against the declared type and the
+   * 'validate.enum' options.
+   *
+   * @param value - The literal to check, or undefined when it was omitted.
+   * @param field - The field name, used as the issue path.
+   */
+  function checkDeclaredValue(
+    value: string | number | boolean | undefined,
+    field: "default" | "example"
+  ): void {
+    if (value === undefined) return;
+
+    const expected =
+      type === "boolean" ? "boolean" : type === "number" ? "number" : "string";
+    if (typeof value !== expected) {
+      ctx.addIssue({
+        code: "custom",
+        path: [field],
+        message: `must be a ${expected}, to match the declared type '${type}'`,
+      });
+    } else if (
+      type === "enum" &&
+      validate?.enum !== undefined &&
+      !validate.enum.includes(String(value))
+    ) {
+      ctx.addIssue({
+        code: "custom",
+        path: [field],
+        message: "must be one of the options listed under 'validate.enum'",
+      });
+    }
+  }
+}
+
+/**
+ * A published variable definition: a specification, not a value. Definitions
+ * are inert; a question is asked only when a subscribed recipe needs the
+ * variable and no valid answer is already in scope.
+ */
+export const variableDefinitionSchema = extensibleObject(
+  variableDefinitionShape(variableValidationSchema)
+).superRefine(checkVariableDefinition);
+
+/**
+ * A variable definition as a release records it in the index, so a consumer
+ * can list a recipe's questions before its files are fetched. It is the
+ * manifest's definition, field for field and rule for rule; the one difference
+ * is that a field this sous does not define is kept rather than refused,
+ * because the index is read by every sous a project happens to pin, and a
+ * later one may add a field.
+ */
+export const publishedVariableDefinitionSchema = forwardCompatibleObject(
+  variableDefinitionShape(forwardCompatibleObject(variableValidationShape))
+).superRefine(checkVariableDefinition);
+
+/** One validated variable definition from a recipe manifest. */
+export type VariableDefinition = z.infer<typeof variableDefinitionSchema>;
+
+/** The constraints attached to a variable definition. */
+export type VariableValidation = z.infer<typeof variableValidationSchema>;
+
+/** The value type a variable definition declares. */
+export type VariableType = (typeof VARIABLE_TYPES)[number];
+
+/** Which env file an answer is written to. */
+export type VariableScope = (typeof VARIABLE_SCOPES)[number];

package/src/lib/repos/index.ts

@@ -18,7 +18,6 @@ export * from "./formats/lockfile.js";
 export * from "./formats/store-entry.js";
 export * from "./formats/links-map.js";
 export * from "./load-manifest.js";
-export * from "./ref.js";
 export * from "./identity.js";
 
 // Phase 2a: the machine-wide recipe store, under the user-level sous directory.

package/src/lib/repos/lock-service.ts

@@ -34,6 +34,7 @@ import type { ResolvedRecipe } from "./resolver.js";
 import type { RecipeStoreLike, StoreKey } from "./store/contract.js";
 import { builtInProviders, requireProvider } from "./providers/index.js";
 import { repoIdentity } from "./identity.js";
+import { splitRecipeKey } from "../refs/parse.js";
 import type { ProviderOptions, RepoProvider } from "./providers/provider.js";
 
 /** What the lockfile needs to know about a repository. */
@@ -382,11 +383,11 @@ export class LockService {
     const report: RestoreReport = { restored: [], alreadyPresent: [] };
 
     for (const [key, entry] of Object.entries(lock.recipes)) {
-      const namespace = key.slice(0, key.indexOf("/"));
+      const { namespace, name } = splitRecipeKey(key);
       const storeKey: StoreKey = {
         identity: lock.repos[entry.repo]!.identity,
         namespace,
-        name: key.slice(namespace.length + 1),
+        name,
         version: entry.version,
       };
 

package/src/lib/repos/locked-namespace-resolver.ts

@@ -4,14 +4,17 @@
  * Phase 4 defined the `NamespaceResolver` contract and shipped an in-memory
  * implementation for tests. This is the implementation backed by the project's
  * actual state: the lockfile says which recipes are in play and at what version,
- * the links map and the store say where each one's files are, and each recipe's
- * own manifest says what it is allowed to address.
+ * the links map and the store say where each one's files are, and the
+ * lockfile's holder lists say what each recipe is allowed to address.
  *
  * The scoping rule is the whole point, and it is enforced by handing
  * `StaticNamespaceResolver` the right two maps:
  *
  *   - a file inside a recipe may address only that recipe's own declared
- *     dependencies (`depends` plus `subscribes`), at their pinned versions;
+ *     dependencies (`depends` plus `subscribes`), at their pinned versions. The
+ *     lockfile records which keys each recipe holds, however its manifest wrote
+ *     them (a sibling ref, a locator, a URL copied from the browser), so that
+ *     record is what decides it;
  *   - a file in the project's own templates may address every recipe the
  *     lockfile pins, whatever holds it: the project, a set it subscribes to,
  *     or another recipe's `depends`.
@@ -28,16 +31,16 @@
 import semver from "semver";
 import type { Settings } from "../settings.js";
 import { resolveStoreRoot } from "../sous-home.js";
+import { RefSource } from "../refs/scopes.js";
+import { namespaceOfKey, parseShortRef, refKey } from "../refs/parse.js";
 import {
   StaticNamespaceResolver,
-  normalizeRef,
   type DroppedRecipe,
   type NamespaceResolver,
 } from "./namespace-resolver.js";
 import {
   listLockedRecipes,
   readProjectLockfile,
-  readRecipeManifestIn,
   type LockedRecipeLocation,
 } from "./locked-recipes.js";
 import { createIndexCache } from "./providers/index.js";
@@ -84,14 +87,11 @@ export function createProjectNamespaceResolver(
   for (const recipe of locked) {
     recipes[recipe.key] = recipe.dir;
 
-    // A recipe declares what it may address in its own manifest. A recipe whose
-    // files are not on disk yet declares nothing, which is the conservative
-    // answer: it cannot be including anything either.
-    const manifest = recipe.present ? readRecipeManifestIn(recipe.dir) : undefined;
-    if (manifest === undefined) continue;
-
-    const declared = [...(manifest.depends ?? []), ...(manifest.subscribes ?? [])];
-    if (declared.length > 0) dependencies[recipe.key] = declared;
+    // Every recipe holding this one declared it, in `depends` or `subscribes`,
+    // and the lockfile records the key that declaration resolved to.
+    for (const holder of recipe.requestedBy) {
+      (dependencies[holder] ??= []).push(recipe.key);
+    }
   }
 
   // No `projectScope`: a project template may address every recipe the
@@ -126,10 +126,16 @@ export function explainUnpinnedRecipe(
   recipe: string,
   options: Pick<ProjectNamespaceResolverOptions, "sousDir" | "settings" | "env">
 ): DroppedRecipe | undefined {
-  const namespace = recipe.slice(0, recipe.indexOf("/"));
+  const namespace = namespaceOfKey(recipe);
   for (const [key, entry] of Object.entries(options.settings.subscriptions ?? {})) {
     if (entry?.enabled !== false) continue;
-    const ref = normalizeRef(key);
+    let ref: string;
+    try {
+      ref = refKey(parseShortRef(key, RefSource.Config));
+    } catch {
+      // The config schema already refuses a key that is not a ref.
+      continue;
+    }
     if (ref === recipe || ref === namespace) {
       return { by: "disabled-subscription", subscription: key };
     }

package/src/lib/repos/locked-recipes.ts

@@ -33,6 +33,7 @@ import {
 } from "./load-manifest.js";
 import { readEffectiveLinks } from "./links.js";
 import { identitySegments } from "./identity.js";
+import { splitRecipeKey } from "../refs/parse.js";
 import { PROJECT_HOLDER } from "./formats/lockfile.js";
 
 /** One locked recipe, together with the directory its files are read from. */
@@ -164,8 +165,7 @@ export function listLockedRecipes(
 
   for (const key of keys.sort()) {
     const entry = lock.recipes[key]!;
-    const namespace = key.slice(0, key.indexOf("/"));
-    const name = key.slice(namespace.length + 1);
+    const { namespace, name } = splitRecipeKey(key);
 
     let dir: string | undefined;
     let linked = false;

package/src/lib/repos/namespace-resolver.ts

@@ -1,4 +1,5 @@
 import path from "node:path";
+import { namespaceOfKey } from "../refs/parse.js";
 
 /**
  * Namespace addressability for templates: the reserved `~` include sigil.
@@ -202,7 +203,7 @@ function describeDropped(
   dropped: DroppedRecipe,
   opts: { namespace: string; rest: string }
 ): string[] {
-  const recipe = `${opts.namespace}/${opts.rest.split("/")[0] ?? ""}`;
+  const { recipe } = splitIncludePath(opts.namespace, opts.rest);
   if (dropped.by === "disabled-subscription") {
     return [
       `This project subscribes to "${dropped.subscription}", but that subscription is ` +
@@ -232,14 +233,15 @@ export type StaticNamespaceResolverOptions = {
    */
   recipes: Record<string, string>;
   /**
-   * What each recipe declares, mapping `<namespace>/<recipe>` to the refs it
-   * may address. An entry may be a full ref (`workflow/task-files`) or a bare
-   * namespace (`workflow`, meaning every recipe in it). A recipe with no entry
-   * declares nothing and may address only itself.
+   * What each recipe declares, mapping `<namespace>/<recipe>` to the keys it
+   * may address. An entry is a recipe key (`workflow/task-files`) or a bare
+   * namespace (`workflow`, meaning every recipe in it), already settled from
+   * however the manifest wrote it. A recipe with no entry declares nothing and
+   * may address only itself.
    */
   dependencies?: Record<string, string[]>;
   /**
-   * What the project's own templates may address, in the same ref forms as
+   * What the project's own templates may address, as the same kind of keys as
    * `dependencies`. Omit it to make every known recipe addressable from
    * project templates, which is the rule for a real project: its templates may
    * address everything its lockfile pins.
@@ -293,7 +295,7 @@ export class StaticNamespaceResolver implements NamespaceResolver {
   private knownNamespaces(): string[] {
     const names = new Set<string>();
     for (const ref of Object.keys(this.recipes)) {
-      names.add(ref.split("/")[0]);
+      names.add(namespaceOfKey(ref));
     }
     return [...names].sort();
   }
@@ -301,7 +303,7 @@ export class StaticNamespaceResolver implements NamespaceResolver {
   /** Every known recipe ref inside one namespace, sorted. */
   private recipesIn(namespace: string): string[] {
     return Object.keys(this.recipes)
-      .filter((ref) => ref.split("/")[0] === namespace)
+      .filter((ref) => namespaceOfKey(ref) === namespace)
       .sort();
   }
 
@@ -329,9 +331,7 @@ export class StaticNamespaceResolver implements NamespaceResolver {
   resolve(request: NamespaceRequest): NamespaceResolution {
     const { namespace, rest, fromFile } = request;
 
-    const segments = rest.split("/").filter((segment) => segment.length > 0);
-    const recipeName = segments[0] ?? "";
-    const ref = `${namespace}/${recipeName}`;
+    const { recipe: ref, segments } = splitIncludePath(namespace, rest);
 
     if (!this.knownNamespaces().includes(namespace)) {
       return {
@@ -361,7 +361,7 @@ export class StaticNamespaceResolver implements NamespaceResolver {
       return { kind: "not-a-dependency", recipe: ref, includingRecipe };
     }
 
-    const inner = segments.slice(1).join("/");
+    const inner = segments.join("/");
     const resolved = path.resolve(recipeDir, inner);
 
     // A `~namespace` reference addresses a recipe's own files. Without this the
@@ -370,7 +370,7 @@ export class StaticNamespaceResolver implements NamespaceResolver {
     // segment check catches the written form, and the relative check catches
     // everything else, including an absolute inner path and any symlink-free
     // route out that normalisation would otherwise hide.
-    if (escapesRecipe(recipeDir, segments.slice(1), inner, resolved)) {
+    if (escapesRecipe(recipeDir, segments, inner, resolved)) {
       return { kind: "escapes-recipe", recipe: ref, reference: `${namespace}/${rest}` };
     }
 
@@ -378,6 +378,27 @@ export class StaticNamespaceResolver implements NamespaceResolver {
   }
 }
 
+/**
+ * Takes the part of a `@~namespace/...` include line after the namespace apart:
+ * its first segment names the recipe, and the rest is a file path inside it.
+ * This is an include path, not a ref; it is the one place such a path is split.
+ *
+ * splitIncludePath("workflow", "task-files/_partials/resume.md")
+ * // -> { recipe: "workflow/task-files", segments: ["_partials", "resume.md"] }
+ *
+ * @param namespace - The namespace the include line named.
+ * @param rest - Everything after `~<namespace>/`.
+ */
+function splitIncludePath(
+  namespace: string,
+  rest: string
+): { recipe: string; segments: string[] } {
+  const [recipeName = "", ...segments] = rest
+    .split("/")
+    .filter((segment) => segment.length > 0);
+  return { recipe: `${namespace}/${recipeName}`, segments };
+}
+
 /**
  * Whether an inner path would address something outside the recipe directory.
  *
@@ -401,46 +422,18 @@ function escapesRecipe(
 }
 
 /**
- * Strip the decorations a written reference may carry so it can be compared to
- * a plain `<namespace>/<recipe>` ref: a repository qualifier (a subscription's
- * `sous-public:misc/stuff`, or a manifest's
- * `github://owner/repo/misc/stuff` locator) and a trailing version range
- * (`misc/stuff@^1.2`).
- *
- * @param ref - A reference as written in a manifest or subscription entry.
- * @returns The bare `<namespace>` or `<namespace>/<recipe>` form.
- */
-export function normalizeRef(ref: string): string {
-  const trimmed = ref.trim();
-
-  // A locator URL names the repository first and the recipe last, so the two
-  // trailing segments are the ref; everything before them is where it lives.
-  const scheme = trimmed.indexOf("://");
-  const body =
-    scheme === -1
-      ? trimmed.includes(":")
-        ? trimmed.slice(trimmed.indexOf(":") + 1)
-        : trimmed
-      : trimmed.slice(scheme + 3).split("/").slice(-2).join("/");
-
-  const at = body.lastIndexOf("@");
-  return (at > 0 ? body.slice(0, at) : body).trim();
-}
-
-/**
- * Whether a list of declared refs covers a recipe, either by naming the recipe
- * itself or by naming its whole namespace.
+ * Whether a list of declared keys covers a recipe, either by naming the recipe
+ * itself or by naming its whole namespace. The keys are already settled
+ * (`namespace` or `namespace/recipe`): whatever form a manifest wrote a
+ * dependency in, the lockfile records the key it resolved to.
  *
- * @param declared - Declared refs (dependencies, or the project's subscriptions).
+ * @param declared - Declared keys (dependencies, or the project's subscriptions).
  * @param namespace - The namespace being addressed.
  * @param ref - The fully qualified recipe ref being addressed.
  * @returns True when the reference is in scope.
  */
 function declaresRef(declared: string[], namespace: string, ref: string): boolean {
-  return declared.some((entry) => {
-    const normalized = normalizeRef(entry);
-    return normalized === ref || normalized === namespace;
-  });
+  return declared.some((entry) => entry === ref || entry === namespace);
 }
 
 /**

package/src/lib/repos/providers/base.ts

@@ -37,6 +37,8 @@ import type {
   ProviderId,
   ProviderOptions,
   RepoProvider,
+  LocationReading,
+  WrittenLocation,
 } from "./provider.js";
 
 /**
@@ -68,6 +70,34 @@ export abstract class ProviderBase implements RepoProvider {
     options?: ProviderOptions
   ): Promise<void>;
 
+  // --- Reading a location ----------------------------------------------------
+
+  /** This provider's public host, declared by a provider that has one. */
+  declare readonly defaultHost?: string;
+
+  /**
+   * No readings: a provider that does not override this reads no location
+   * inside its repositories, so a ref naming one is refused with a sentence.
+   *
+   * @param _location - The written location; unused.
+   */
+  readLocation(_location: WrittenLocation): LocationReading[] {
+    return [];
+  }
+
+  /**
+   * `<id>://<host>/<repoPath>/<rest>`, with the host left out when it is this
+   * provider's default.
+   *
+   * @param host - The repository's host.
+   * @param repoPath - The repository's path on that host.
+   * @param rest - What is named inside it.
+   */
+  formatLocator(host: string, repoPath: string, rest: string): string {
+    const where = host === this.defaultHost ? repoPath : `${host}/${repoPath}`;
+    return `${this.id}://${where}${rest.length === 0 ? "" : `/${rest}`}`;
+  }
+
   // --- Subprocess plumbing ---------------------------------------------------
 
   /**

package/src/lib/repos/providers/github.ts

@@ -24,7 +24,11 @@ import { fetchText, type FetchLike } from "./http.js";
 import {
   buildCanonicalRepo,
   invalidRepoUrl,
+  readingsAfterRepository,
   splitRepoUrl,
+  withoutGitSuffix,
+  type LocationReading,
+  type WrittenLocation,
   type AuthStatus,
   type CanonicalRepo,
   type ChangeProposal,
@@ -83,6 +87,24 @@ export class GithubProvider extends ProviderBase {
   /** What GitHub calls a proposal. */
   readonly proposalNoun = "pull request";
 
+  /** The host a `github://` locator means when it names none. */
+  readonly defaultHost = GITHUB_HOST;
+
+  /**
+   * A GitHub repository is always an owner and a name, so the first two
+   * segments are the repository and everything after them names something
+   * inside it: a namespace, a recipe, or a browser path after `tree/` or
+   * `blob/`.
+   *
+   * @param location - The host and the segments after it.
+   */
+  readLocation(location: WrittenLocation): LocationReading[] {
+    const { segments } = location;
+    if (segments.length < 2) return [];
+    const repoPath = `${segments[0]}/${withoutGitSuffix(segments[1]!)}`;
+    return readingsAfterRepository(repoPath, segments.slice(2));
+  }
+
   matches(url: string): boolean {
     const parts = splitRepoUrl(url);
     return parts !== undefined && parts.host === GITHUB_HOST;