@goodbones/core 0.1.0-beta.5 → 0.1.0-beta.7

package/schema/conformance.schema.json

@@ -262,6 +262,32 @@
       "additionalProperties": false,
       "description": "What the policy has nothing to say about. A file in an open folder under no allowlist is claimed, not policed, and counts."
     },
+    "vacant": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "node": {
+            "type": "string",
+            "description": "The manifest node."
+          },
+          "allowances": {
+            "type": "number",
+            "allOf": [
+              {
+                "description": "Distinct entries the node wrote, `allow` and `external` together."
+              }
+            ]
+          }
+        },
+        "required": [
+          "node",
+          "allowances"
+        ],
+        "additionalProperties": false
+      },
+      "description": "Nodes that state an import allowlist and select no walked file, in manifest order. Every allowance on one is unused by construction, so none is counted as slack; the node is a tier declared ahead of its first file, or a pattern that no longer matches. Residue is files no node reaches; this is nodes no file reaches."
+    },
     "violations": {
       "type": "array",
       "items": {
@@ -387,7 +413,7 @@
         "properties": {
           "node": {
             "type": "string",
-            "description": "The manifest node that wrote the entry."
+            "description": "The manifest node that wrote the entry — or, when `fragment` is set, the `defs` fragment it was written in."
           },
           "kind": {
             "type": "string",
@@ -400,6 +426,18 @@
           "entry": {
             "type": "string",
             "description": "The entry as written, after alias expansion."
+          },
+          "fragment": {
+            "type": "string",
+            "description": "Present when the entry arrived through `use`. The nodes that referenced the fragment wrote one word, so the entry is reported once, against the fragment, rather than once per node."
+          },
+          "of": {
+            "type": "number",
+            "allOf": [
+              {
+                "description": "With `fragment`: how many non-vacant nodes were granted the entry through it. None of them uses it."
+              }
+            ]
           }
         },
         "required": [
@@ -409,7 +447,56 @@
         ],
         "additionalProperties": false
       },
-      "description": "Allowances no observed import uses, in manifest order. A manifest inferred from the tree has none on the day it is written; every entry here is permission nothing needs."
+      "description": "Allowances no observed import uses, in manifest order, vacant nodes excluded. A manifest inferred from the tree has none on the day it is written; every entry here is permission nothing needs. An entry that arrived through `use` is reported once, against the fragment, and only when no node granted it uses it."
+    },
+    "concentration": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "fragment": {
+            "type": "string",
+            "description": "The `defs` fragment the entry was written in."
+          },
+          "kind": {
+            "type": "string",
+            "enum": [
+              "allow",
+              "external"
+            ],
+            "description": "`allow` is a path glob under `imports.allow`; `external` a package name under `imports.external`."
+          },
+          "entry": {
+            "type": "string",
+            "description": "The entry as written, after alias expansion."
+          },
+          "usedAt": {
+            "type": "number",
+            "allOf": [
+              {
+                "description": "Nodes granted the entry through the fragment that use it."
+              }
+            ]
+          },
+          "of": {
+            "type": "number",
+            "allOf": [
+              {
+                "description": "Non-vacant nodes granted the entry through the fragment."
+              }
+            ]
+          }
+        },
+        "required": [
+          "fragment",
+          "kind",
+          "entry",
+          "usedAt",
+          "of"
+        ],
+        "additionalProperties": false
+      },
+      "description": "Fragment entries used at some of the nodes granted them and not the rest. Not slack — the fragment's line is needed somewhere — but a per-file permission written as a many-node allowance, which is what an allowlist widened to make one build green looks like."
     },
     "adoption": {
       "type": "object",
@@ -445,12 +532,14 @@
     "ok",
     "coverage",
     "residue",
+    "vacant",
     "violations",
     "unresolved",
     "stale",
     "baseline",
     "cycles",
     "slack",
+    "concentration",
     "adoption"
   ],
   "additionalProperties": false

package/src/core/coverage.ts

@@ -194,6 +194,59 @@ export type CoverageFloors = {
 
 export type CoverageFamily = keyof CoverageFloors;
 
+// Residue is files no node reaches; this is nodes no file reaches. A node
+// that states an import allowlist and selects no walked file grants
+// permission to nothing: every allowance on it is unused by construction,
+// which is not slack — there is no line to delete, only a node that is a
+// tier declared ahead of its first file, or a pattern that no longer
+// matches. Which of the two, the reader decides; the report tells both
+// apart from slack so nothing has to be read twice.
+export type Vacancy = ReadonlyArray<{
+  readonly node: string;
+  // Distinct entries the node wrote, `allow` and `external` together.
+  readonly allowances: number;
+}>;
+
+// The nodes whose allowances no live rule carries. A node's allowlist is
+// inherited by every descendant's rule until one `reset`s, so a node whose
+// own rule steps aside for an overriding child still reaches that child's
+// files through the child's rule — and is not vacant while the child has any.
+export const vacantNodesOf = (
+  rules: ReadonlyArray<CompiledImportRule>,
+  files: ReadonlyArray<string>,
+): ReadonlySet<string> => {
+  const declaring = new Set<string>();
+  const reached = new Set<string>();
+  for (const rule of rules) {
+    if (rule.allowances.length === 0) continue;
+    const live = files.some((file) => selects(rule, file));
+    for (const { node } of rule.allowances) {
+      declaring.add(node);
+      if (live) reached.add(node);
+    }
+  }
+  return new Set([...declaring].filter((node) => !reached.has(node)));
+};
+
+// Every vacant node with how many entries it wrote, in the order the
+// allowlists declared them.
+export const vacancyOf = (
+  rules: ReadonlyArray<CompiledImportRule>,
+  files: ReadonlyArray<string>,
+): Vacancy => {
+  const vacant = vacantNodesOf(rules, files);
+  const entries = new Map<string, Set<string>>();
+  for (const rule of rules) {
+    for (const { entry, kind, node } of rule.allowances) {
+      if (!vacant.has(node)) continue;
+      const written = entries.get(node) ?? new Set<string>();
+      written.add(`${kind} ${entry}`);
+      entries.set(node, written);
+    }
+  }
+  return [...entries.entries()].map(([node, written]) => ({ node, allowances: written.size }));
+};
+
 export const fractionOf = (covered: number, total: number): number =>
   total === 0 ? 1 : covered / total;
 

package/src/core/slack.ts

@@ -1,5 +1,6 @@
 import type { Allowance } from "../domain/architecture-config.js";
 import type { ResolvedTarget } from "../ports/module-resolver.js";
+import { vacantNodesOf } from "./coverage.js";
 import type { CompiledImportRule } from "./imports.js";
 import { firstFromMatch, matchesAny } from "./patterns.js";
 
@@ -17,10 +18,31 @@ export type ObservedEdge = {
 };
 
 // An allowance no observed edge uses. The same shape the lowering recorded,
-// minus the compiled pattern nobody wrote.
-export type Slack = Pick<Allowance, "node" | "kind" | "entry">;
+// minus the compiled pattern nobody wrote. When the entry arrived through
+// `use`, `node` is the fragment's name — the line to delete is in `defs` —
+// and `of` says how many nodes wrote the reference that carried it.
+export type Slack = Pick<Allowance, "node" | "kind" | "entry"> & {
+  readonly fragment?: string;
+  readonly of?: number;
+};
+
+// A fragment entry used at some of the nodes it was granted to and not the
+// rest. At the fragment level it is not slack — there is no line nobody
+// needs — but it is a per-file permission written as a many-node allowance,
+// which is what an allowlist widened to make one build green looks like.
+export type Concentration = Pick<Allowance, "kind" | "entry"> & {
+  readonly fragment: string;
+  readonly usedAt: number;
+  readonly of: number;
+};
 
-const keyOf = (one: Slack): string => `${one.node} ${one.kind} ${one.entry}`;
+export type SlackReport = {
+  readonly slack: ReadonlyArray<Slack>;
+  readonly concentration: ReadonlyArray<Concentration>;
+};
+
+const keyOf = (one: Pick<Allowance, "node" | "kind" | "entry">): string =>
+  `${one.node} ${one.kind} ${one.entry}`;
 
 // Whether one edge, from a file this rule selects, passes through this entry.
 const uses = (allowance: Allowance, captures: RegExpExecArray, target: ResolvedTarget): boolean => {
@@ -30,22 +52,57 @@ const uses = (allowance: Allowance, captures: RegExpExecArray, target: ResolvedT
   return allowance.pattern !== undefined && matchesAny([allowance.pattern], captures, target.path);
 };
 
+// One entry as one place wrote it: a node that wrote the line, or a fragment
+// that N nodes pulled in with `use`. Keyed by that place, so a fragment's
+// entry is reported once however many nodes reference it.
+type Declared = {
+  readonly node: string;
+  readonly kind: Allowance["kind"];
+  readonly entry: string;
+  readonly fragment: string | undefined;
+  // The nodes that declared it, vacant ones excluded — every allowance on a
+  // vacant node is unused by construction, and is vacancy, not slack.
+  readonly at: Set<string>;
+};
+
+const groupKeyOf = (one: Allowance): string =>
+  one.fragment === undefined
+    ? `node ${one.node} ${one.kind} ${one.entry}`
+    : `use ${one.fragment} ${one.kind} ${one.entry}`;
+
 // Every allowance the rules carry that no edge uses, in the order the manifest
 // declared them. An entry is inherited by every descendant's rule and written
 // once, so it is keyed by where it was written: an import anywhere under the
-// declaring node is a use.
+// declaring node is a use. An entry that arrived through `use` is keyed by
+// the fragment, and is slack only when no node it was granted to uses it;
+// used at some and not others, it is reported as concentration instead. A
+// vacant node — one whose allowlist selects no walked file — contributes
+// nothing to either.
 export const slackOf = (
   rules: ReadonlyArray<CompiledImportRule>,
   edges: ReadonlyArray<ObservedEdge>,
-): ReadonlyArray<Slack> => {
-  const declared = new Map<string, Slack>();
+  files: ReadonlyArray<string>,
+): SlackReport => {
+  const vacant = vacantNodesOf(rules, files);
+
+  const declared = new Map<string, Declared>();
   for (const rule of rules) {
-    for (const { entry, kind, node } of rule.allowances) {
-      const one = { node, kind, entry };
-      if (!declared.has(keyOf(one))) declared.set(keyOf(one), one);
+    for (const allowance of rule.allowances) {
+      if (vacant.has(allowance.node)) continue;
+      const key = groupKeyOf(allowance);
+      const group = declared.get(key) ?? {
+        node: allowance.fragment ?? allowance.node,
+        kind: allowance.kind,
+        entry: allowance.entry,
+        fragment: allowance.fragment,
+        at: new Set<string>(),
+      };
+      group.at.add(allowance.node);
+      declared.set(key, group);
     }
   }
 
+  // Which (node, kind, entry) some edge passes through.
   const used = new Set<string>();
   for (const edge of edges) {
     for (const rule of rules) {
@@ -58,5 +115,21 @@ export const slackOf = (
     }
   }
 
-  return [...declared.values()].filter((one) => !used.has(keyOf(one)));
+  const slack: Array<Slack> = [];
+  const concentration: Array<Concentration> = [];
+  for (const group of declared.values()) {
+    const { entry, kind } = group;
+    const usedAt = [...group.at].filter((node) => used.has(keyOf({ node, kind, entry }))).length;
+    if (group.fragment === undefined) {
+      if (usedAt === 0) slack.push({ node: group.node, kind, entry });
+      continue;
+    }
+    const of = group.at.size;
+    if (usedAt === 0) {
+      slack.push({ node: group.node, kind, entry, fragment: group.fragment, of });
+    } else if (usedAt < of) {
+      concentration.push({ fragment: group.fragment, kind, entry, usedAt, of });
+    }
+  }
+  return { slack, concentration };
 };

package/src/domain/architecture-config.ts

@@ -42,6 +42,11 @@ export const Allowance = Schema.Struct({
   entry: Schema.String,
   // For an `allow`: the compiled target pattern, as `toNot` carries it.
   pattern: Schema.optionalKey(Schema.String),
+  // The `defs` fragment the entry arrived through, when the node wrote
+  // `use: <name>` rather than the entry itself. Slack is attributed to the
+  // fragment then: the node's authors wrote one word, and the line to delete
+  // is in `defs`.
+  fragment: Schema.optionalKey(Schema.String),
 });
 
 export const ImportRule = Schema.Struct({

package/src/domain/facts.ts

@@ -1,9 +1,9 @@
 import type { BindingKind, DeclarationKind, MemberSubject } from "./architecture-config.js";
 
-// What a policy can know about one source file, read once. Both adapters
-// produce this vocabulary — the plugin from oxlint's syntax tree, the CLI from
-// TypeScript's — which is what keeps them answerable to the same core rather
-// than to each other. A rule is evaluated against these and nothing else.
+// What a policy can know about one source file, read once. A language pack
+// produces this vocabulary out of its syntax tree, and both hosts read it —
+// which is what keeps them answerable to the same core rather than to each
+// other. A rule is evaluated against these and nothing else.
 
 // One name pulled across one import edge: `import { makeCommandBus } from "…"`
 // is a single binding, and so is the `Effect` in `import { Effect } from "effect"`.

package/src/domain/snapshot.ts

@@ -65,13 +65,48 @@ export const SnapshotViolation = Schema.Struct({
   baselined: describe(Schema.Boolean, "Carried by the baseline, so `check` does not fail on it."),
 });
 
+const AllowanceKind = describe(
+  Schema.Literals(["allow", "external"]),
+  "`allow` is a path glob under `imports.allow`; `external` a package name under `imports.external`.",
+);
+
+const Entry = describe(Schema.String, "The entry as written, after alias expansion.");
+
 export const SnapshotSlack = Schema.Struct({
-  node: describe(Schema.String, "The manifest node that wrote the entry."),
-  kind: describe(
-    Schema.Literals(["allow", "external"]),
-    "`allow` is a path glob under `imports.allow`; `external` a package name under `imports.external`.",
+  node: describe(
+    Schema.String,
+    "The manifest node that wrote the entry — or, when `fragment` is set, the `defs` fragment it was written in.",
+  ),
+  kind: AllowanceKind,
+  entry: Entry,
+  fragment: Schema.optionalKey(
+    describe(
+      Schema.String,
+      "Present when the entry arrived through `use`. The nodes that referenced the fragment wrote one word, so the entry is reported once, against the fragment, rather than once per node.",
+    ),
+  ),
+  of: Schema.optionalKey(
+    describe(
+      Schema.Finite,
+      "With `fragment`: how many non-vacant nodes were granted the entry through it. None of them uses it.",
+    ),
+  ),
+});
+
+export const SnapshotConcentration = Schema.Struct({
+  fragment: describe(Schema.String, "The `defs` fragment the entry was written in."),
+  kind: AllowanceKind,
+  entry: Entry,
+  usedAt: describe(Schema.Finite, "Nodes granted the entry through the fragment that use it."),
+  of: describe(Schema.Finite, "Non-vacant nodes granted the entry through the fragment."),
+});
+
+export const SnapshotVacancy = Schema.Struct({
+  node: describe(Schema.String, "The manifest node."),
+  allowances: describe(
+    Schema.Finite,
+    "Distinct entries the node wrote, `allow` and `external` together.",
   ),
-  entry: describe(Schema.String, "The entry as written, after alias expansion."),
 });
 
 export const Snapshot = Schema.Struct({
@@ -114,6 +149,10 @@ export const Snapshot = Schema.Struct({
     }),
     "What the policy has nothing to say about. A file in an open folder under no allowlist is claimed, not policed, and counts.",
   ),
+  vacant: describe(
+    Schema.Array(SnapshotVacancy),
+    "Nodes that state an import allowlist and select no walked file, in manifest order. Every allowance on one is unused by construction, so none is counted as slack; the node is a tier declared ahead of its first file, or a pattern that no longer matches. Residue is files no node reaches; this is nodes no file reaches.",
+  ),
   violations: describe(
     Schema.Array(SnapshotViolation),
     "Every finding, baselined ones included, ordered so the ones cheapest to fix come first: by the height of the violated target in the import graph, leaves first.",
@@ -135,7 +174,11 @@ export const Snapshot = Schema.Struct({
   ),
   slack: describe(
     Schema.Array(SnapshotSlack),
-    "Allowances no observed import uses, in manifest order. A manifest inferred from the tree has none on the day it is written; every entry here is permission nothing needs.",
+    "Allowances no observed import uses, in manifest order, vacant nodes excluded. A manifest inferred from the tree has none on the day it is written; every entry here is permission nothing needs. An entry that arrived through `use` is reported once, against the fragment, and only when no node granted it uses it.",
+  ),
+  concentration: describe(
+    Schema.Array(SnapshotConcentration),
+    "Fragment entries used at some of the nodes granted them and not the rest. Not slack — the fragment's line is needed somewhere — but a per-file permission written as a many-node allowance, which is what an allowlist widened to make one build green looks like.",
   ),
   adoption: describe(
     Schema.Struct({
@@ -149,6 +192,8 @@ export const Snapshot = Schema.Struct({
 export type Snapshot = typeof Snapshot.Type;
 export type SnapshotViolation = typeof SnapshotViolation.Type;
 export type SnapshotSlack = typeof SnapshotSlack.Type;
+export type SnapshotConcentration = typeof SnapshotConcentration.Type;
+export type SnapshotVacancy = typeof SnapshotVacancy.Type;
 
 // Decodes a document some other run wrote — the base of a pull request, a
 // stored one — refusing a key the shape does not declare, so a consumer never

package/src/index.ts

@@ -25,6 +25,8 @@ export {
   reachOf,
   type Residue,
   residueOf,
+  type Vacancy,
+  vacancyOf,
 } from "./core/coverage.js";
 export {
   type BindingEdge,
@@ -69,7 +71,13 @@ export {
   memberRulesFailingTheirProbe,
   memberRulesSelecting,
 } from "./core/members.js";
-export { type ObservedEdge, type Slack, slackOf } from "./core/slack.js";
+export {
+  type Concentration,
+  type ObservedEdge,
+  type Slack,
+  slackOf,
+  type SlackReport,
+} from "./core/slack.js";
 export {
   type CompiledStructure,
   compileStructure,
@@ -128,9 +136,11 @@ export {
   type Snapshot,
   SNAPSHOT_SCHEMA_ID,
   SNAPSHOT_VERSION,
+  type SnapshotConcentration,
   snapshotJsonSchema,
   Snapshot as SnapshotSchema,
   type SnapshotSlack,
+  type SnapshotVacancy,
   type SnapshotViolation,
 } from "./domain/snapshot.js";
 export {
@@ -161,7 +171,12 @@ export {
   type WalkedLanguage,
 } from "./infrastructure/walk.js";
 export { type LoadedPolicy, loadPolicy, type LoadPolicyInput } from "./load/policy.js";
-export { type LoweredRules, lowerManifest, type ProbeLanguage } from "./manifest/compile.js";
+export {
+  type LoweredRules,
+  lowerManifest,
+  type LowerOptions,
+  type ProbeLanguage,
+} from "./manifest/compile.js";
 export {
   type ExpandedManifest,
   type ExpandIssue,

package/src/load/policy.ts

@@ -216,7 +216,7 @@ export const loadPolicy = (
   // The manifest is the authoring surface; these flat rules are the machine's.
   // The languages tell lowering what a source file in each scope is called, so
   // a synthetic probe is a file of the scope's language.
-  const rules = lowerManifest(config, languages);
+  const rules = lowerManifest(config, languages, { substitutions: decoded.success.substitutions });
 
   // The ceilings. A tier that says "not tightened yet" is a sentence someone
   // wrote; a ceiling on how many may say so is what keeps the backlog from

package/src/manifest/compile.ts

@@ -11,6 +11,8 @@ 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 {
   globsOf,
@@ -225,6 +227,11 @@ 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,
@@ -232,6 +239,7 @@ const mergeImports = (
   captures: CaptureIndex,
   nextGroup: number,
   node: string,
+  provenance: ImportsProvenance,
 ): Pick<Frame, "allowances" | "importsMessage"> & {
   readonly deny: ReadonlyArray<Denial>;
 } => {
@@ -245,14 +253,24 @@ const mergeImports = (
         .source,
     );
 
+  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"),
     })),
-    ...(spec.external ?? []).map((name) => ({ node, kind: "external" as const, entry: name })),
   ];
   const deny = (spec.deny ?? []).flatMap((entry) =>
     globsOf(entry.match).map((glob) => ({
@@ -278,11 +296,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
@@ -345,6 +372,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)
@@ -394,7 +424,15 @@ 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, name);
+    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,
@@ -591,7 +629,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,
+        ]);
       }
     }
 
@@ -863,6 +905,7 @@ export const lowerManifest = (
     {},
     1,
     "repo",
+    () => undefined,
   ).deny.entries()) {
     imports.push({
       name: `repo/deny-${String(index)}`,
@@ -905,6 +948,7 @@ export const lowerManifest = (
         .replace(/[^a-zA-Z0-9]+/g, "-")
         .replace(/^-|-$/g, ""),
       Object.keys(manifest.tree),
+      ["tree", key],
     );
   }
 

package/src/manifest/expand.ts

@@ -172,3 +172,12 @@ export const originOf = (
     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;

package/src/manifest/manifest.ts

@@ -305,6 +305,9 @@ export type DecodedManifest = {
   // Things the manifest said in a form that still loads but is on its way out.
   // The host prints them; nothing else acts on them.
   readonly notices: ReadonlyArray<string>;
+  // Every `use` the expansion replaced. Lowering reads them to say which
+  // fragment an allowance came through; nothing else needs them.
+  readonly substitutions: ReadonlyArray<Substitution>;
 };
 
 const isRecord = (value: unknown): value is Record<string, unknown> =>
@@ -496,5 +499,6 @@ export const decodeManifest = (
   return Result.succeed({
     manifest: decoded.success,
     notices: [...resolve.notices, ...members.notices],
+    substitutions,
   });
 };