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

package/src/load/policy.ts

@@ -44,18 +44,26 @@ import {
   type PatternInvalid,
 } from "../domain/architecture-error.js";
 import type { SourceFacts } from "../domain/facts.js";
+import type { ManifestLocator } from "../domain/manifest-location.js";
 import { type LoweredRules, lowerManifest } from "../manifest/compile.js";
 import { decodeManifest, type Manifest } from "../manifest/manifest.js";
 import type { FactExtractor } from "../ports/fact-extractor.js";
 import type { FileSystem } from "../ports/file-system.js";
 import type { Language } from "../ports/language.js";
 import type { ModuleResolver } from "../ports/module-resolver.js";
+import type { SyntaxMatcher } from "../ports/syntax-matcher.js";
+import type { ExtensionRoute, PolicyExtension } from "./extension.js";
 
 // A manifest, read by a host, turned into the policy both adapters evaluate.
 // Decoding, lowering, compiling and probing happen here, once, with whatever
 // languages the host hands in — this tier never names one. The host reads the
 // manifest file, constructs its language packs and the live file system, and
 // hands them over; that is the whole of what a host has to know.
+//
+// A family the core does not own arrives the same way: as a `PolicyExtension`
+// in `extensions`, which claims its keys of the manifest, decodes them, and
+// hands back a value carried on `extensions` below. The core never looks
+// inside that value; the package that produced it exports the accessor.
 
 export type LoadedPolicy = {
   readonly repoRoot: string;
@@ -69,6 +77,10 @@ export type LoadedPolicy = {
   readonly graph: CompiledGraph;
   readonly adoption: LoweredRules["adoption"];
   readonly structure: CompiledStructure;
+  // What each loaded extension loaded, keyed by its id. Opaque here.
+  readonly extensions: ReadonlyMap<string, unknown>;
+  // The clock the policy is judged by — a stall, a window, a timestamp.
+  readonly now: number;
   readonly fileSystem: FileSystem;
   // The language packs this policy is evaluated with. The walker takes its
   // extensions from them, and lowering the shape of its probes.
@@ -81,6 +93,11 @@ export type LoadedPolicy = {
   // Routes each file to the extractor of the language whose scope covers it.
   // The CLI reads every file through this; the plugin reads oxlint's tree.
   readonly extractor: FactExtractor;
+  // Routes each file to the syntax matcher of the language whose scope
+  // covers it; `parse` answers `null` for a file whose language has none.
+  readonly syntax: SyntaxMatcher;
+  // Which scope, and so which language, covers a given file.
+  readonly routeFor: (file: string) => ExtensionRoute | undefined;
   readonly ignoreUnresolved: ReadonlyArray<RegExp>;
   // Deprecation notices from reading the manifest. The host prints them once.
   readonly notices: ReadonlyArray<string>;
@@ -93,8 +110,17 @@ export type LoadPolicyInput = {
   // The manifest as the host read it — a module's default export, a parsed
   // document — before decoding.
   readonly manifest: unknown;
+  // From a data file, where a path in the manifest was written, so a decode
+  // error names a line. A module manifest has none.
+  readonly locate?: ManifestLocator | undefined;
   readonly languages: ReadonlyArray<Language>;
   readonly fileSystem: FileSystem;
+  // The families the core does not own, composed by the host. A manifest key
+  // one of these claims is decoded by it; a key none claims is refused as the
+  // excess property it is.
+  readonly extensions?: ReadonlyArray<PolicyExtension> | undefined;
+  // For tests and for a CI that pins the clock; defaults to `Date.now()`.
+  readonly now?: number | undefined;
 };
 
 const NOTHING: SourceFacts = {
@@ -180,6 +206,14 @@ const makeRoutingExtractor = (routes: ReadonlyArray<Route>): FactExtractor => ({
     routeFor(routes, file)?.language.extractor.factsOf(file, text) ?? NOTHING,
 });
 
+// One matcher per scope, behind one port that picks the scope by the file. A
+// language without one parses nothing, which a `syntax` term reads as no
+// matches — and which an extension's probe check refuses for a family that
+// depends on it.
+const makeRoutingMatcher = (routes: ReadonlyArray<Route>): SyntaxMatcher => ({
+  parse: (file, text) => routeFor(routes, file)?.language.syntax?.parse(file, text) ?? null,
+});
+
 // The baseline is read through the port, so this tier touches no file itself.
 // An absent or unreadable one carries nothing, which is the safe direction:
 // every violation reports.
@@ -201,8 +235,12 @@ export const loadPolicy = (
   input: LoadPolicyInput,
 ): Result.Result<LoadedPolicy, ConfigInvalid | PatternInvalid> => {
   const { configPath, fileSystem, languages, repoRoot } = input;
+  const extensions = input.extensions ?? [];
 
-  const decoded = decodeManifest(configPath, input.manifest);
+  const decoded = decodeManifest(configPath, input.manifest, {
+    locate: input.locate,
+    extensions,
+  });
   if (Result.isFailure(decoded)) return Result.fail(decoded.failure);
   const config = decoded.success.manifest;
 
@@ -212,7 +250,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
@@ -281,12 +319,44 @@ export const loadPolicy = (
   // reads that file through. The plugin reads through oxlint's tree instead,
   // and the parity suite is what holds that tree to this one.
   const extractor = makeRoutingExtractor(routes.success);
+  const syntax = makeRoutingMatcher(routes.success);
+  const routeOf = (file: string): ExtensionRoute | undefined => {
+    const found = routeFor(routes.success, file);
+    return found === undefined ? undefined : { language: found.language, scope: found.scope };
+  };
+  const now = input.now ?? Date.now();
+
+  // Each family the core does not own compiles and probes its own rules, with
+  // the same extractor and matcher the core used for its. Its probe failures
+  // join the one refusal below, so a vacuous campaign and a vacuous import
+  // rule are reported in the same sentence.
+  const loadedExtensions = new Map<string, unknown>();
+  const extensionVacuous: Array<string> = [];
+  for (const extension of extensions) {
+    const loaded = extension.load({
+      spec: decoded.success.extensions.get(extension.id),
+      configPath,
+      repoRoot,
+      config,
+      languages,
+      fileSystem,
+      extractor,
+      syntax,
+      routeFor: routeOf,
+      now,
+    });
+    if (Result.isFailure(loaded)) return Result.fail(loaded.failure);
+    loadedExtensions.set(extension.id, loaded.success.value);
+    for (const name of loaded.success.vacuous ?? []) extensionVacuous.push(name);
+  }
+
   const parsedBy = (rule: { readonly probe: { readonly from: string } }): string => {
     const route = routeFor(routes.success, rule.probe.from);
     return route === undefined
       ? ` — no resolve scope covers its probe ${JSON.stringify(rule.probe.from)}, so no language parsed it`
       : ` — probe parsed by ${route.language.id}, selected by the scope ${JSON.stringify(route.scope.files)}`;
   };
+
   const vacuous = [
     ...rulesFailingTheirProbe(importRules.success).map((rule) => rule.name),
     ...exportRulesFailingTheirProbe(exportRules.success, extractor).map(
@@ -300,6 +370,7 @@ export const loadPolicy = (
     ),
     ...structureRulesFailingTheirProbe(structure.success),
     ...graphRulesFailingTheirProbe(graph.success),
+    ...extensionVacuous,
   ];
   if (vacuous.length > 0) {
     return Result.fail(
@@ -331,11 +402,15 @@ export const loadPolicy = (
     graph: graph.success,
     adoption: rules.adoption,
     structure: structure.success,
+    extensions: loadedExtensions,
+    now,
     fileSystem,
     languages,
     baseline: makeBaselineFilter(readBaseline(fileSystem, config.baseline)),
     resolver: resolver.success,
     extractor,
+    syntax,
+    routeFor: routeOf,
     ignoreUnresolved: (config.resolve.ignoreUnresolved ?? []).map(
       (pattern: string) => new RegExp(pattern),
     ),

package/src/manifest/compile.ts

@@ -1,4 +1,5 @@
 import {
+  type Allowance,
   type ExportRule,
   type GraphConfig,
   type ImportRule,
@@ -10,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,
@@ -69,7 +72,7 @@ const alternativesOf = (key: string): ReadonlyArray<string> =>
     .map(stripSlash)
     .filter((one) => one !== "");
 
-const expandAliases = (glob: string, aliases: Readonly<Record<string, string>>): string => {
+export const expandAliases = (glob: string, aliases: Readonly<Record<string, string>>): string => {
   for (const [alias, target] of Object.entries(aliases)) {
     if (glob === alias) return target;
     if (glob.startsWith(`${alias}/`)) return target + glob.slice(alias.length);
@@ -84,12 +87,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;
@@ -136,7 +138,7 @@ const probeMemberName = (match: string | ReadonlyArray<string> | undefined): str
 
 // Each convention pairs the shape a name must have with a name that does not
 // have it, so the rule's probe is generated rather than written.
-const CONVENTIONS: Readonly<
+export const CONVENTIONS: Readonly<
   Record<string, { readonly source: string; readonly violating: string; readonly shape: string }>
 > = {
   "kebab-case": {
@@ -225,22 +227,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 +253,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 +287,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 +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
@@ -343,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)
@@ -392,15 +424,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 +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,
+        ]);
       }
     }
 
@@ -608,9 +651,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 +678,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 +890,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 +904,8 @@ export const lowerManifest = (
     aliases,
     {},
     1,
+    "repo",
+    () => undefined,
   ).deny.entries()) {
     imports.push({
       name: `repo/deny-${String(index)}`,
@@ -898,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

@@ -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;

package/src/manifest/extension.ts

@@ -0,0 +1,41 @@
+import type * as Result from "effect/Result";
+
+import type { ManifestPath } from "../domain/manifest-location.js";
+
+// A family the core does not own.
+//
+// The five per-file families, the graph and the limits are the core's: it
+// declares their vocabulary, decodes it and evaluates it. A family that is
+// not — `campaigns`, which @goodbones/campaigns owns — states which top-level
+// manifest keys it claims, and decodes them itself. The core splits those
+// keys off the expanded manifest before decoding what is left, so the core's
+// codec never learns a word of the family's vocabulary and a key no
+// extension claims is still the excess property it always was.
+//
+// This is the decode half. The load half — compiling, probing, and whatever
+// state the family reads off disk — is `PolicyExtension` in `load/`, which
+// needs the ports and so cannot live here.
+
+export type ManifestExtension<Spec = unknown> = {
+  // Names the family in errors, and keys it in `LoadedPolicy.extensions`.
+  readonly id: string;
+  // The top-level keys of the manifest this family owns.
+  readonly manifestKeys: ReadonlyArray<string>;
+  // The slice, as the expansion passes left it: the claimed keys that were
+  // present, with `defs`/`use` and `include` already resolved.
+  //
+  // `describe` renders one issue the way the core's own decoder does — the
+  // position in the file, the path, and the `use` it came through — so a
+  // decode error from a family the core does not own reads exactly like one
+  // from a tree node. Failure is a list of rendered lines, because a manifest
+  // is edited by hand and the reader fixing one wants the other three.
+  //
+  // Declared as a method rather than a function property on purpose: the
+  // loader holds extensions as `PolicyExtension<unknown, unknown>`, having
+  // erased what each one decodes, and method signatures are what let a
+  // concretely-typed extension be one of those.
+  decode(
+    slice: Readonly<Record<string, unknown>>,
+    describe: (path: ManifestPath, detail: string) => string,
+  ): Result.Result<Spec, ReadonlyArray<string>>;
+};

package/src/manifest/glob.ts

@@ -106,3 +106,8 @@ export const globToRegexSource = (
 export const anchored = (source: string): string => `^${source}$`;
 
 export const prefixed = (source: string): string => `^${source}`;
+
+// A repo-relative glob as the sector discovery compiles a marker's `owns`:
+// anchored at the start, so it names a subtree.
+export const globToRegExp = (glob: string): RegExp =>
+  new RegExp(prefixed(globToRegexSource(glob, {}, { declaring: false, nextGroup: 1 }).source));