@goodbones/core 0.1.0-beta.1 → 0.1.0-beta.10

package/src/manifest/compile.ts

@@ -1,4 +1,7 @@
 import {
+  type Allowance,
+  type CampaignRule,
+  type Detector,
   type ExportRule,
   type GraphConfig,
   type ImportRule,
@@ -10,13 +13,19 @@ import {
   type StructureRoot,
   type SurfaceRule,
 } from "../domain/architecture-config.js";
+import type { ManifestPath } from "../domain/manifest-location.js";
+import { fragmentOf, type Substitution } from "./expand.js";
 import { anchored, type CaptureIndex, globToRegexSource, prefixed } from "./glob.js";
 import {
+  type CampaignSpec,
+  type DetectorSpec,
+  durationMs,
   globsOf,
   type ImportsSpec,
   type Manifest,
   type ManifestNode,
   type NamingSpec,
+  type SyntaxTermSpec,
 } from "./manifest.js";
 
 // The manifest is the authoring surface; these flat rules are the machine's.
@@ -28,6 +37,8 @@ export type LoweredRules = {
   readonly members: ReadonlyArray<MemberRule>;
   readonly surface: ReadonlyArray<SurfaceRule>;
   readonly graph: GraphConfig;
+  // Campaigns pass through by their own id, as top-level `exports` rules do.
+  readonly campaigns: ReadonlyArray<CampaignRule>;
   // The nodes that said "not tightened yet", by name — the adoption backlog,
   // and what `limits` puts a ceiling on.
   readonly adoption: {
@@ -84,12 +95,11 @@ type Frame = {
   readonly pathGlob: string;
   readonly captures: CaptureIndex;
   readonly nextGroup: number;
-  // Accumulated down the tree. `reset` is the only thing that clears it.
-  readonly allow: ReadonlyArray<string>;
-  // Third-party packages, by name, accumulated and reset the same way. Kept
-  // apart from `allow` because a package is judged by its name and never by
-  // where the language's resolver found it.
-  readonly externals: ReadonlyArray<string>;
+  // The allowlist in force, accumulated down the tree; `reset` is the only
+  // thing that clears it. Each entry remembers the node that wrote it. A path
+  // glob is compiled to a target pattern; a package is judged by its name and
+  // never by where the language's resolver found it, so it carries none.
+  readonly allowances: ReadonlyArray<Allowance>;
   readonly importsMessage: string;
   // Inherited like the allowlist: a tier states its naming convention once.
   readonly naming: NamingSpec | undefined;
@@ -225,22 +235,24 @@ type Denial = {
   readonly probe: string;
 };
 
+// Which `defs` fragment one key of a node's `imports` was written in, when it
+// was written in one. Resolved per key, since `imports: { use: x, allow: […] }`
+// takes `allow` from the reference site and `external` from the fragment.
+type ImportsProvenance = (key: "allow" | "external") => string | undefined;
+
 const mergeImports = (
   frame: Frame,
   spec: ImportsSpec | undefined,
   aliases: Readonly<Record<string, string>>,
   captures: CaptureIndex,
   nextGroup: number,
-): Pick<Frame, "allow" | "externals" | "importsMessage"> & {
+  node: string,
+  provenance: ImportsProvenance,
+): Pick<Frame, "allowances" | "importsMessage"> & {
   readonly deny: ReadonlyArray<Denial>;
 } => {
   if (spec === undefined) {
-    return {
-      allow: frame.allow,
-      externals: frame.externals,
-      deny: [],
-      importsMessage: frame.importsMessage,
-    };
+    return { allowances: frame.allowances, deny: [], importsMessage: frame.importsMessage };
   }
 
   const compileAllow = (glob: string): string =>
@@ -249,8 +261,25 @@ const mergeImports = (
         .source,
     );
 
-  const own = globsOf(spec.allow ?? []).map(compileAllow);
-  const external = spec.external ?? [];
+  const via = (key: "allow" | "external"): Pick<Allowance, "fragment"> => {
+    const fragment = provenance(key);
+    return fragment === undefined ? {} : { fragment };
+  };
+  const own: ReadonlyArray<Allowance> = [
+    ...globsOf(spec.allow ?? []).map((glob) => ({
+      node,
+      kind: "allow" as const,
+      entry: expandAliases(glob, aliases),
+      pattern: compileAllow(glob),
+      ...via("allow"),
+    })),
+    ...(spec.external ?? []).map((name) => ({
+      node,
+      kind: "external" as const,
+      entry: name,
+      ...via("external"),
+    })),
+  ];
   const deny = (spec.deny ?? []).flatMap((entry) =>
     globsOf(entry.match).map((glob) => ({
       match: compileAllow(glob),
@@ -266,8 +295,7 @@ const mergeImports = (
   // a mistake here would be dangerous in.
   const dropping = spec.reset === true || spec.unrestricted === true;
   return {
-    allow: dropping ? own : [...frame.allow, ...own],
-    externals: dropping ? external : [...frame.externals, ...external],
+    allowances: dropping ? own : [...frame.allowances, ...own],
     // Only what this node declares. A prohibition is emitted once, over its whole
     // subtree, so descendants neither re-emit it nor can escape it — which is
     // what makes `reset` structurally unable to make a subtree quieter.
@@ -276,11 +304,20 @@ const mergeImports = (
   };
 };
 
+export type LowerOptions = {
+  // The `use` references the expansion replaced, so an allowance can say
+  // which fragment it came through. A manifest lowered without them is one
+  // whose every entry reads as authored where it sits.
+  readonly substitutions?: ReadonlyArray<Substitution>;
+};
+
 export const lowerManifest = (
   manifest: Manifest,
   languages: ReadonlyArray<ProbeLanguage> = [],
+  options: LowerOptions = {},
 ): LoweredRules => {
   const aliases = manifest.aliases ?? {};
+  const substitutions = options.substitutions ?? [];
 
   // The extension a synthetic probe file carries: the first extension of the
   // language whose scope covers the probe's folder. A probe is matched by its
@@ -343,6 +380,9 @@ export const lowerManifest = (
     parent: Frame,
     name: string,
     siblings: ReadonlyArray<string>,
+    // Where this node sits in the expanded document, so its `imports` keys
+    // can be traced back through any `use` that carried them.
+    nodePath: ManifestPath,
   ): void => {
     const literalSiblings = siblings
       .filter((sibling) => sibling !== key)
@@ -392,15 +432,22 @@ export const lowerManifest = (
       parent.nextGroup +
       (Object.keys(compiled.captures).length - Object.keys(parent.captures).length);
 
-    const merged = mergeImports(parent, node.imports, aliases, compiled.captures, nextGroup);
+    const merged = mergeImports(
+      parent,
+      node.imports,
+      aliases,
+      compiled.captures,
+      nextGroup,
+      name,
+      (field) => fragmentOf(substitutions, [...nodePath, "imports", field]),
+    );
     const ownDenials = merged.deny;
     const frame: Frame = {
       pathSource,
       pathGlob: joinedGlob,
       captures: compiled.captures,
       nextGroup,
-      allow: merged.allow,
-      externals: merged.externals,
+      allowances: merged.allowances,
       importsMessage: merged.importsMessage,
       naming: node.name ?? parent.naming,
     };
@@ -590,7 +637,11 @@ export const lowerManifest = (
       }
       const siblingKeys = childKeys.map(([childKey]) => childKey);
       for (const [childKey, child] of childKeys) {
-        walk(childKey, child, frame, `${name}/${alternativesOf(childKey)[0] ?? ""}`, siblingKeys);
+        walk(childKey, child, frame, `${name}/${alternativesOf(childKey)[0] ?? ""}`, siblingKeys, [
+          ...nodePath,
+          "children",
+          childKey,
+        ]);
       }
     }
 
@@ -608,9 +659,14 @@ export const lowerManifest = (
       ? probePathOf(joinedGlob, "")
       : probePathOf(joinedGlob, "").replace(/\/[^/]*$/, "");
 
-    const admitsEverything = frame.allow.some((pattern) => pattern === "^.*" || pattern === "^");
-    const hasAllowlist =
-      (frame.allow.length > 0 || frame.externals.length > 0) && !admitsEverything;
+    const allow = frame.allowances.flatMap((one) =>
+      one.pattern === undefined ? [] : [one.pattern],
+    );
+    const externals = frame.allowances
+      .filter((one) => one.kind === "external")
+      .map((one) => one.entry);
+    const admitsEverything = allow.some((pattern) => pattern === "^.*" || pattern === "^");
+    const hasAllowlist = frame.allowances.length > 0 && !admitsEverything;
 
     if (emitsOwnImports && node.imports?.unrestricted !== true && !hasAllowlist) {
       throw new Error(
@@ -630,8 +686,9 @@ export const lowerManifest = (
           probe: { from: scopeProbe, to: probeOutside("nowhere", ownFolder) },
           from: scope,
           ...exemptions,
-          toNot: [...frame.allow],
-          ...(frame.externals.length > 0 ? { externals: [...frame.externals] } : {}),
+          toNot: allow,
+          ...(externals.length > 0 ? { externals } : {}),
+          allowances: frame.allowances,
         });
       }
     }
@@ -841,8 +898,7 @@ export const lowerManifest = (
     pathGlob: "",
     captures: {},
     nextGroup: 1,
-    allow: [],
-    externals: [],
+    allowances: [],
     importsMessage: "This import is not on this folder's allowlist.",
     naming: undefined,
   };
@@ -856,6 +912,8 @@ export const lowerManifest = (
     aliases,
     {},
     1,
+    "repo",
+    () => undefined,
   ).deny.entries()) {
     imports.push({
       name: `repo/deny-${String(index)}`,
@@ -898,6 +956,7 @@ export const lowerManifest = (
         .replace(/[^a-zA-Z0-9]+/g, "-")
         .replace(/^-|-$/g, ""),
       Object.keys(manifest.tree),
+      ["tree", key],
     );
   }
 
@@ -999,13 +1058,216 @@ export const lowerManifest = (
     })),
   };
 
+  const campaigns = (manifest.campaigns ?? []).map((campaign) => lowerCampaign(campaign, aliases));
+
   return {
     imports,
     exports,
     members,
     surface,
     graph,
+    campaigns,
     adoption: { unrestricted: unrestrictedNodes, partial: partialNodes },
     structure: { roots, folders, parity, naming: namingRules },
   };
 };
+
+// The keys of a `syntax` term that belong to the engine's rule; `where` is
+// the one that does not.
+const SYNTAX_RULE_KEYS = [
+  "pattern",
+  "kind",
+  "regex",
+  "nthChild",
+  "inside",
+  "has",
+  "precedes",
+  "follows",
+  "all",
+  "any",
+  "not",
+] as const;
+
+const syntaxRuleOf = (term: SyntaxTermSpec): unknown =>
+  Object.fromEntries(
+    SYNTAX_RULE_KEYS.flatMap((key) => (term[key] === undefined ? [] : [[key, term[key]]])),
+  );
+
+// The leaf terms a path alone cannot exercise: each reads the file's text,
+// its syntax, or its facts, so a probe for a detector holding one must carry
+// a `source`.
+const TERMS_NEEDING_SOURCE = ["content", "syntax", "exports", "members", "fn"] as const;
+
+const leafTermsOf = (detector: DetectorSpec): ReadonlyArray<string> => {
+  if ("all" in detector) return detector.all.flatMap(leafTermsOf);
+  if ("any" in detector) return detector.any.flatMap(leafTermsOf);
+  if ("not" in detector) return leafTermsOf(detector.not);
+  return Object.keys(detector);
+};
+
+// A campaign's globs resolved: `scope` and a path-shaped `resolves` the way
+// graph rules resolve theirs, `exports`/`members` names the way `surface` and
+// `members` rules do, and the rest carried as written. The `fn` string is
+// kept verbatim for the loader, which holds the function it names.
+const lowerCampaign = (
+  campaign: CampaignSpec,
+  aliases: Readonly<Record<string, string>>,
+): CampaignRule => {
+  const asPath = (glob: string): string =>
+    prefixed(
+      globToRegexSource(expandAliases(glob, aliases), {}, { declaring: false, nextGroup: 1 })
+        .source,
+    );
+  const asName = (globs: string | ReadonlyArray<string>): ReadonlyArray<string> =>
+    globsOf(globs).map((one) =>
+      anchored(globToRegexSource(one, {}, { declaring: false, nextGroup: 1 }).source),
+    );
+  const name = `campaign/${campaign.id}`;
+
+  const lower = (detector: DetectorSpec): Detector => {
+    if ("all" in detector) return { all: detector.all.map(lower) };
+    if ("any" in detector) return { any: detector.any.map(lower) };
+    if ("not" in detector) return { not: lower(detector.not) };
+    if ("path" in detector) {
+      const { convention, ...rest } = detector.path;
+      const conventionSource =
+        convention === undefined
+          ? undefined
+          : typeof convention === "string"
+            ? CONVENTIONS[convention]?.source
+            : convention.regex;
+      if (convention !== undefined && conventionSource === undefined) {
+        throw new Error(`campaign "${campaign.id}" names an unknown convention "${convention}".`);
+      }
+      if (conventionSource !== undefined && rest.subject === undefined) {
+        throw new Error(
+          `campaign "${campaign.id}" states a path convention with no \`subject\`: say which ` +
+            `capture group of \`file\` holds the name the convention is about.`,
+        );
+      }
+      return {
+        path: {
+          file: globsOf(rest.file),
+          ...(rest.fileNot === undefined ? {} : { fileNot: globsOf(rest.fileNot) }),
+          ...(rest.subject === undefined ? {} : { subject: rest.subject }),
+          ...(conventionSource === undefined ? {} : { convention: conventionSource }),
+        },
+      };
+    }
+    if ("imports" in detector) {
+      const { resolves, symbols } = detector.imports;
+      return {
+        imports: {
+          resolves: typeof resolves === "string" ? asPath(resolves) : resolves,
+          ...(symbols === undefined ? {} : { symbols: [...symbols] }),
+        },
+      };
+    }
+    if ("exports" in detector) {
+      const term = detector.exports;
+      return {
+        exports: {
+          ...(term.name === undefined ? {} : { name: asName(term.name) }),
+          ...(term.kinds === undefined ? {} : { kinds: [...term.kinds] }),
+          ...(term.declares === undefined ? {} : { declares: [...term.declares] }),
+          ...(term.reexport === undefined ? {} : { reexport: term.reexport }),
+        },
+      };
+    }
+    if ("members" in detector) {
+      const term = detector.members;
+      return {
+        members: {
+          subject: term.subject,
+          ...(term.name === undefined ? {} : { name: asName(term.name) }),
+          ...(term.in === undefined ? {} : { in: asName(term.in) }),
+          ...(term.declares === undefined ? {} : { declares: [...term.declares] }),
+        },
+      };
+    }
+    if ("requires" in detector) return { requires: [...detector.requires] };
+    if ("content" in detector) return { content: { regex: detector.content.regex } };
+    if ("report" in detector) {
+      // Exactly one of `command` and `file`, and a pattern for `regex`: the
+      // manifest schema refused anything else at decode.
+      const term = detector.report;
+      return {
+        report: {
+          ...(term.command === undefined ? {} : { command: globsOf(term.command) }),
+          ...(term.file === undefined ? {} : { file: globsOf(term.file) }),
+          format: term.format,
+          ...(term.pattern === undefined ? {} : { pattern: term.pattern }),
+          ...(term.codes === undefined ? {} : { codes: [...term.codes] }),
+          ...(term.codesNot === undefined ? {} : { codesNot: [...term.codesNot] }),
+        },
+      };
+    }
+    if ("syntax" in detector) {
+      const { where } = detector.syntax;
+      const narrowed =
+        where === undefined
+          ? {}
+          : {
+              where: Object.fromEntries(
+                Object.entries(where).map(([capture, narrowing]) => [
+                  capture,
+                  {
+                    ...(narrowing.regex === undefined ? {} : { regex: narrowing.regex }),
+                    ...(narrowing.binding === undefined
+                      ? {}
+                      : {
+                          binding: {
+                            resolves:
+                              typeof narrowing.binding.resolves === "string"
+                                ? asPath(narrowing.binding.resolves)
+                                : narrowing.binding.resolves,
+                            ...(narrowing.binding.member === undefined
+                              ? {}
+                              : { member: [...narrowing.binding.member] }),
+                          },
+                        }),
+                  },
+                ]),
+              ),
+            };
+      return { syntax: { rule: syntaxRuleOf(detector.syntax), ...narrowed } };
+    }
+    return { fn: detector.fn };
+  };
+
+  // A probe without a source proves only the path; a detector that reads the
+  // file needs the file. Refused here, with the term named, rather than at
+  // load as a probe that mysteriously never fires.
+  const leaves = leafTermsOf(campaign.detect);
+  const needsSource = TERMS_NEEDING_SOURCE.filter((term) => leaves.includes(term));
+  const probes = [...campaign.probes.fires, ...(campaign.probes.ignores ?? [])];
+  const sourceless = probes.find((probe) => probe.source === undefined);
+  if (needsSource.length > 0 && sourceless !== undefined) {
+    throw new Error(
+      `campaign "${campaign.id}" has a probe (${sourceless.path}) with no \`source\`, and its ` +
+        `detector holds a ${needsSource.map((term) => `\`${term}\``).join(", ")} term, which ` +
+        `a path alone cannot exercise. Give every probe a source.`,
+    );
+  }
+  if (campaign.probes.fires.length === 0) {
+    throw new Error(
+      `campaign "${campaign.id}" carries no \`probes.fires\`. A campaign proves it can fire ` +
+        `the way every rule does; write at least one source it must report.`,
+    );
+  }
+
+  return {
+    name,
+    id: campaign.id,
+    ...(campaign.title === undefined ? {} : { title: campaign.title }),
+    message: campaign.how,
+    why: campaign.why,
+    ...(campaign.owner === undefined ? {} : { owner: campaign.owner }),
+    scope: globsOf(campaign.scope).map(asPath),
+    unit: campaign.unit,
+    detect: lower(campaign.detect),
+    probes: { fires: [...campaign.probes.fires], ignores: [...(campaign.probes.ignores ?? [])] },
+    staleAfter: durationMs(campaign.staleAfter),
+    onComplete: campaign.onComplete ?? "keep",
+  };
+};

package/src/manifest/expand.ts

@@ -0,0 +1,183 @@
+import * as Result from "effect/Result";
+
+import type { ManifestPath } from "../domain/manifest-location.js";
+
+// Reuse inside a manifest, in the manifest's own schema rather than the
+// format's. A top-level `defs` map names fragments; `{ use: "<name>" }`
+// anywhere in the rest of the document is replaced by a deep copy of the
+// fragment. This runs on the raw value before decoding, so it works the same
+// in YAML, in JSON, and in a JavaScript module that chose to write it — and
+// the schema that decodes the result never has to know a reference existed.
+//
+// There is deliberately nothing else here: no interpolation, no includes, no
+// deep merge. A fragment that needs partial override is two fragments; a
+// manifest that needs more than a data format offers needs a generator, and
+// a generator can emit YAML.
+
+export type ExpandIssue = {
+  readonly path: ManifestPath;
+  readonly detail: string;
+};
+
+// One `use` that was expanded. `at` is where the fragment landed in the
+// expanded document; `ref` is where the reference was written in the original
+// one; `overrides` are the keys written beside `use`, which came from the
+// reference site rather than from the fragment.
+export type Substitution = {
+  readonly at: ManifestPath;
+  readonly ref: ManifestPath;
+  readonly name: string;
+  readonly overrides: ReadonlySet<string>;
+};
+
+export type ExpandedManifest = {
+  readonly value: unknown;
+  readonly substitutions: ReadonlyArray<Substitution>;
+};
+
+// Where a path in the expanded document was written in the original one. When
+// the path crosses a `use`, `via` lists each reference it passed through,
+// outermost first, so an error inside a fragment can name the line that pulled
+// the fragment in as well as the fragment itself.
+export type Origin = {
+  readonly path: ManifestPath;
+  readonly via: ReadonlyArray<{ readonly at: ManifestPath; readonly name: string }>;
+};
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+const isReference = (value: unknown): value is Record<string, unknown> & { readonly use: string } =>
+  isRecord(value) && typeof value.use === "string";
+
+export const expandManifest = (input: unknown): Result.Result<ExpandedManifest, ExpandIssue> => {
+  if (!isRecord(input)) return Result.succeed({ value: input, substitutions: [] });
+
+  // Two keys the file may carry that the schema does not: the fragments, and
+  // the `$schema` a JSON author writes for editor validation.
+  const { $schema: _schema, defs, ...rest } = input;
+  if (defs !== undefined && !isRecord(defs)) {
+    return Result.fail({
+      path: ["defs"],
+      detail: "`defs` must be a map of named fragments.",
+    });
+  }
+  const fragments: Record<string, unknown> = defs ?? {};
+  const defined = Object.keys(fragments);
+  const substitutions: Array<Substitution> = [];
+
+  // `at` is the path in the document being built; `origin` the path in the
+  // document as written; `stack` the fragments currently being expanded, for
+  // the cycle check.
+  const walk = (
+    value: unknown,
+    at: ManifestPath,
+    origin: ManifestPath,
+    stack: ReadonlyArray<string>,
+  ): Result.Result<unknown, ExpandIssue> => {
+    if (isReference(value)) {
+      const { use: name, ...overrides } = value;
+      if (!(name in fragments)) {
+        return Result.fail({
+          path: origin,
+          detail:
+            `\`use: ${JSON.stringify(name)}\` names no entry in \`defs\`` +
+            (defined.length === 0
+              ? " — the manifest defines none."
+              : ` (defined: ${defined.join(", ")}).`),
+        });
+      }
+      if (stack.includes(name)) {
+        return Result.fail({
+          path: origin,
+          detail: `\`defs\` contains a cycle: ${[...stack, name].join(" → ")}.`,
+        });
+      }
+      substitutions.push({ at, ref: origin, name, overrides: new Set(Object.keys(overrides)) });
+
+      const fragment = walk(fragments[name], at, ["defs", name], [...stack, name]);
+      if (Result.isFailure(fragment)) return fragment;
+      if (Object.keys(overrides).length === 0) return fragment;
+
+      if (!isRecord(fragment.success)) {
+        return Result.fail({
+          path: origin,
+          detail:
+            `\`use: ${JSON.stringify(name)}\` is written with overrides ` +
+            `(${Object.keys(overrides).join(", ")}), but \`defs.${name}\` is not an object, ` +
+            `so there is nothing to override.`,
+        });
+      }
+      const merged: Record<string, unknown> = { ...fragment.success };
+      for (const [key, override] of Object.entries(overrides)) {
+        const expanded = walk(override, [...at, key], [...origin, key], stack);
+        if (Result.isFailure(expanded)) return expanded;
+        merged[key] = expanded.success;
+      }
+      return Result.succeed(merged);
+    }
+
+    if (Array.isArray(value)) {
+      const items: Array<unknown> = [];
+      for (const [index, item] of value.entries()) {
+        const expanded = walk(item, [...at, index], [...origin, index], stack);
+        if (Result.isFailure(expanded)) return expanded;
+        items.push(expanded.success);
+      }
+      return Result.succeed(items);
+    }
+
+    if (isRecord(value)) {
+      const entries: Record<string, unknown> = {};
+      for (const [key, item] of Object.entries(value)) {
+        const expanded = walk(item, [...at, key], [...origin, key], stack);
+        if (Result.isFailure(expanded)) return expanded;
+        entries[key] = expanded.success;
+      }
+      return Result.succeed(entries);
+    }
+
+    return Result.succeed(value);
+  };
+
+  const expanded = walk(rest, [], [], []);
+  if (Result.isFailure(expanded)) return Result.fail(expanded.failure);
+  return Result.succeed({ value: expanded.success, substitutions });
+};
+
+const isPrefix = (prefix: ManifestPath, path: ManifestPath): boolean =>
+  prefix.length <= path.length && prefix.every((segment, index) => path[index] === segment);
+
+// Maps a path in the expanded document back to where it was written.
+export const originOf = (
+  substitutions: ReadonlyArray<Substitution>,
+  path: ManifestPath,
+): Origin => {
+  const crossed = substitutions
+    .filter((one) => isPrefix(one.at, path))
+    .sort((a, b) => a.at.length - b.at.length);
+  const innermost = crossed.at(-1);
+  if (innermost === undefined) return { path, via: [] };
+
+  const outer = crossed.slice(0, -1).map((one) => ({ at: one.ref, name: one.name }));
+  const rest = path.slice(innermost.at.length);
+  const first = rest[0];
+
+  // A key written beside `use` belongs to the reference site, not the fragment.
+  if (typeof first === "string" && innermost.overrides.has(first)) {
+    return { path: [...innermost.ref, ...rest], via: outer };
+  }
+  return {
+    path: ["defs", innermost.name, ...rest],
+    via: [...outer, { at: innermost.ref, name: innermost.name }],
+  };
+};
+
+// The fragment a path in the expanded document was written in, when it was:
+// the innermost `use` the path crossed, or nothing when the value at that path
+// was authored where it sits — including a key written beside `use`, which
+// belongs to the reference site.
+export const fragmentOf = (
+  substitutions: ReadonlyArray<Substitution>,
+  path: ManifestPath,
+): string | undefined => originOf(substitutions, path).via.at(-1)?.name;