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

package/src/manifest/expand.ts

@@ -0,0 +1,174 @@
+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 }],
+  };
+};

package/src/manifest/json-schema.ts

@@ -0,0 +1,164 @@
+import * as Schema from "effect/Schema";
+
+import { Manifest } from "./manifest.js";
+
+// The manifest's shape as a JSON Schema, generated from the same codec that
+// decodes it, so the two cannot disagree. A YAML file names it in a header
+// comment and a JSON file in a `$schema` key; either way the editor completes
+// keys and flags a misspelled one before the loader ever runs.
+//
+// Three things the codec does not know are added here: the `defs` map, the
+// `{ use }` reference form that may stand in for any object, and the
+// `{ include }` form that may stand in for any object or list — all belong to
+// the passes that run before decoding.
+
+export const MANIFEST_SCHEMA_ID =
+  "https://dataquail.github.io/goodbones/schema/architecture.schema.json";
+
+// The schema an included file names: one node of the tree, with the two keys
+// a file of its own may carry at the top.
+export const MANIFEST_NODE_SCHEMA_ID =
+  "https://dataquail.github.io/goodbones/schema/architecture-node.schema.json";
+
+type JsonValue = string | number | boolean | null | JsonObject | ReadonlyArray<JsonValue>;
+type JsonObject = { readonly [key: string]: JsonValue };
+
+const entriesOf = (value: JsonObject): ReadonlyArray<readonly [string, JsonValue]> =>
+  Object.entries(value);
+
+const isObject = (value: JsonValue): value is JsonObject =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+const isList = (value: JsonValue): value is ReadonlyArray<JsonValue> => Array.isArray(value);
+
+// The generator names the recursive node after its own internal wrapper. A
+// stable name is what a `$ref` in an error message or a docs page can point at.
+const DEFINITION_NAMES: Readonly<Record<string, string>> = { Suspend_: "ManifestNode" };
+
+const USE_REFERENCE = "#/$defs/Use";
+const INCLUDE_REFERENCE = "#/$defs/Include";
+
+const Use: JsonObject = {
+  type: "object",
+  description:
+    "A reference to a fragment under the top-level `defs`. Replaced by a copy of the fragment before the manifest is decoded; any other key written beside `use` overrides the fragment's key of the same name.",
+  properties: { use: { type: "string" } },
+  required: ["use"],
+};
+
+const Include: JsonObject = {
+  type: "object",
+  description:
+    "A reference to another YAML or JSON file, relative to this one. Replaced by that file's whole value before the manifest is decoded; a list item naming a file that holds a list is spliced in. Nothing may be written beside `include`.",
+  properties: { include: { type: "string" } },
+  required: ["include"],
+  additionalProperties: false,
+};
+
+// Every object schema below the root becomes "this object, or a `use` of a
+// fragment shaped like it, or an `include` of a file holding one", and every
+// list schema "this list, or an `include` of a file holding one". The
+// expansion passes replace a reference wherever it stands, so the schema
+// admits one wherever the value may stand.
+const admitReferences = (value: JsonValue): JsonValue => {
+  if (Array.isArray(value)) return value.map(admitReferences);
+  if (!isObject(value)) return value;
+
+  const rebuilt: Record<string, JsonValue> = {};
+  for (const [key, entry] of entriesOf(value)) {
+    if (key === "$ref" && typeof entry === "string") {
+      const name = entry.replace(/^#\/\$defs\//, "");
+      rebuilt[key] = `#/$defs/${DEFINITION_NAMES[name] ?? name}`;
+    } else {
+      rebuilt[key] = admitReferences(entry);
+    }
+  }
+  if (rebuilt.type === "object" && "properties" in rebuilt) {
+    return { anyOf: [{ $ref: USE_REFERENCE }, { $ref: INCLUDE_REFERENCE }, rebuilt] };
+  }
+  if (rebuilt.type === "array") {
+    return { anyOf: [{ $ref: INCLUDE_REFERENCE }, rebuilt] };
+  }
+  return rebuilt;
+};
+
+const DEFS_PROPERTY: JsonObject = {
+  type: "object",
+  description:
+    'Named fragments, referenced elsewhere in the manifest as `{ use: "<name>" }`. A fragment may itself contain `use`. Every file\'s `defs` share one namespace.',
+  additionalProperties: true,
+};
+
+const SCHEMA_PROPERTY: JsonObject = {
+  type: "string",
+  description: "For editors. Ignored by the loader.",
+};
+
+export const manifestJsonSchema = (): JsonObject => {
+  const generated = Schema.toJsonSchemaDocument(Manifest) as unknown as {
+    readonly schema: JsonObject;
+    readonly definitions: JsonObject;
+  };
+  const { properties, ...root } = generated.schema;
+  if (properties === undefined || !isObject(properties)) {
+    throw new Error("the manifest schema generated with no properties");
+  }
+
+  const definitions: Record<string, JsonValue> = {};
+  for (const [name, definition] of entriesOf(generated.definitions)) {
+    definitions[DEFINITION_NAMES[name] ?? name] = admitReferences(definition);
+  }
+
+  return {
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    $id: MANIFEST_SCHEMA_ID,
+    title: "Architecture manifest",
+    description:
+      "One manifest of a repository's architecture, read by @goodbones/cli and @goodbones/oxlint. See https://dataquail.github.io/goodbones/architecture-rules/manifest/.",
+    ...root,
+    properties: {
+      $schema: SCHEMA_PROPERTY,
+      defs: DEFS_PROPERTY,
+      ...Object.fromEntries(
+        entriesOf(properties).map(([key, value]) => [key, admitReferences(value)]),
+      ),
+    },
+    $defs: { ...definitions, Use, Include },
+  };
+};
+
+// One node of the tree as a file of its own — what a per-package
+// `architecture.yaml` that the root manifest `include`s is shaped like. The
+// node's object form, with the `$schema` and `defs` keys such a file may carry
+// at the top, over the same definitions as the whole manifest.
+export const manifestNodeJsonSchema = (): JsonObject => {
+  const whole = manifestJsonSchema();
+  const definitions = whole.$defs;
+  if (definitions === undefined || !isObject(definitions)) {
+    throw new Error("the manifest schema generated with no definitions");
+  }
+  const node = definitions.ManifestNode;
+  const variants = node !== undefined && isObject(node) ? node.anyOf : undefined;
+  const object =
+    variants !== undefined && isList(variants)
+      ? variants.find((variant) => isObject(variant) && variant.type === "object")
+      : undefined;
+  if (object === undefined || !isObject(object)) {
+    throw new Error("the manifest schema generated with no object form of a node");
+  }
+  const { $id: _id, $schema: _schema, ...rest } = object;
+  return {
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    $id: MANIFEST_NODE_SCHEMA_ID,
+    title: "Architecture manifest node",
+    description:
+      "One node of an architecture manifest's tree, as a file the manifest includes. See https://dataquail.github.io/goodbones/architecture-rules/manifest/#splitting-the-manifest-include.",
+    ...rest,
+    properties: {
+      $schema: SCHEMA_PROPERTY,
+      defs: DEFS_PROPERTY,
+      ...(rest.properties !== undefined && isObject(rest.properties) ? rest.properties : {}),
+    },
+    $defs: definitions,
+  };
+};

package/src/manifest/manifest.ts

@@ -1,8 +1,15 @@
 import * as Result from "effect/Result";
 import * as Schema from "effect/Schema";
+import * as SchemaIssue from "effect/SchemaIssue";
 
 import { DeclarationKind, ResolveConfig } from "../domain/architecture-config.js";
 import { ConfigInvalid } from "../domain/architecture-error.js";
+import {
+  type ManifestLocator,
+  type ManifestPath,
+  renderManifestPath,
+} from "../domain/manifest-location.js";
+import { expandManifest, originOf, type Substitution } from "./expand.js";
 
 // A manifest is a tree of nodes keyed by path pattern, where everything the
 // architecture says about a part of the tree is written at that part of the tree.
@@ -286,7 +293,12 @@ export type ExportRestriction = typeof ExportRestriction.Type;
 export const globsOf = (globs: string | ReadonlyArray<string>): ReadonlyArray<string> =>
   typeof globs === "string" ? [globs] : globs;
 
-const decode = Schema.decodeUnknownResult(Manifest);
+// Every issue, not the first: a manifest is edited by hand, and the reader
+// fixing one line wants to know about the other three. A key the schema does
+// not declare is refused rather than dropped — a misspelled `matchNot` that
+// decoded to nothing would be a rule quietly enforcing less than it says.
+const decode = Schema.decodeUnknownResult(Manifest, { errors: "all", onExcessProperty: "error" });
+const flatten = SchemaIssue.makeFormatterStandardSchemaV1();
 
 export type DecodedManifest = {
   readonly manifest: Manifest;
@@ -392,17 +404,97 @@ const normalizeLegacyMembers = (
   return { input: { ...input, tree }, notices };
 };
 
+export type DecodeManifestOptions = {
+  // Turns a path in the file into a line and column. The YAML reader supplies
+  // one; a JavaScript module has no positions to give and passes nothing.
+  readonly locate?: ManifestLocator | undefined;
+};
+
+const fileLabelOf = (configPath: string): string => configPath.split(/[\\/]/).at(-1) ?? configPath;
+
+// A position carries its own file when the value was written in a file the
+// manifest `include`d; otherwise it is in the manifest file itself.
+const positionOf = (
+  file: string,
+  locate: ManifestLocator | undefined,
+  path: ManifestPath,
+): string | null => {
+  const found = locate?.(path) ?? null;
+  return found === null
+    ? null
+    : `${found.file ?? file}:${String(found.line)}:${String(found.column)}`;
+};
+
+// One line per issue: where in the file, which path, what was wrong — and,
+// when the value came in through a `use`, the reference that pulled it in,
+// since the fragment's own line may sit far from where the reader is looking.
+const describeIssue = (
+  configPath: string,
+  locate: ManifestLocator | undefined,
+  substitutions: ReadonlyArray<Substitution>,
+  path: ManifestPath,
+  detail: string,
+): string => {
+  const file = fileLabelOf(configPath);
+  const origin = originOf(substitutions, path);
+  const at = positionOf(file, locate, origin.path);
+  const via = origin.via.map(({ at: ref, name }) => {
+    const position = positionOf(file, locate, ref);
+    return `via \`use: ${JSON.stringify(name)}\`${position === null ? "" : ` at ${position}`}`;
+  });
+  return (
+    `  ${at === null ? "" : `${at}  `}${renderManifestPath(origin.path)}: ${detail}` +
+    (via.length === 0 ? "" : ` (${via.join(", ")})`)
+  );
+};
+
+// The standard-schema formatter flattens the issue tree to `{ path, message }`
+// pairs; a path segment may arrive wrapped as `{ key }`.
+const pathOf = (issue: {
+  readonly path?: ReadonlyArray<PropertyKey | { readonly key: PropertyKey }> | undefined;
+}): ManifestPath =>
+  (issue.path ?? []).map((segment) => (typeof segment === "object" ? segment.key : segment));
+
 export const decodeManifest = (
   configPath: string,
   input: unknown,
+  options: DecodeManifestOptions = {},
 ): Result.Result<DecodedManifest, ConfigInvalid> => {
-  const resolve = normalizeLegacyResolve(input);
+  const expanded = expandManifest(input);
+  if (Result.isFailure(expanded)) {
+    return Result.fail(
+      new ConfigInvalid({
+        configPath,
+        detail:
+          "the manifest does not expand:\n" +
+          describeIssue(
+            configPath,
+            options.locate,
+            [],
+            expanded.failure.path,
+            expanded.failure.detail,
+          ),
+      }),
+    );
+  }
+  const { substitutions, value } = expanded.success;
+
+  const resolve = normalizeLegacyResolve(value);
   const members = normalizeLegacyMembers(resolve.input);
-  return Result.map(
-    Result.mapError(
-      decode(members.input),
-      (issue) => new ConfigInvalid({ configPath, detail: String(issue) }),
-    ),
-    (manifest) => ({ manifest, notices: [...resolve.notices, ...members.notices] }),
-  );
+  const decoded = decode(members.input);
+  if (Result.isFailure(decoded)) {
+    const lines = flatten(decoded.failure.issue).issues.map((issue) =>
+      describeIssue(configPath, options.locate, substitutions, pathOf(issue), issue.message),
+    );
+    return Result.fail(
+      new ConfigInvalid({
+        configPath,
+        detail: `the manifest does not decode:\n${lines.join("\n")}`,
+      }),
+    );
+  }
+  return Result.succeed({
+    manifest: decoded.success,
+    notices: [...resolve.notices, ...members.notices],
+  });
 };