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

package/src/domain/manifest-location.ts

@@ -0,0 +1,19 @@
+// Where in the manifest file a value was written. A decode error that names a
+// path is something the reader has to find; one that names a line is something
+// an editor can jump to. The host that read the file knows its lines; the
+// decoder knows the path — the locator is how the second asks the first.
+
+// A path into the manifest as the decoder sees it: object keys and array
+// indices, root first.
+export type ManifestPath = ReadonlyArray<PropertyKey>;
+
+export type ManifestPosition = {
+  // 1-based, as editors count.
+  readonly line: number;
+  readonly column: number;
+};
+
+// Answers with the position of the value at `path`, or the nearest ancestor
+// that exists when the path names something the file does not contain (a
+// missing key), or `null` when the source has no positions to give.
+export type ManifestLocator = (path: ManifestPath) => ManifestPosition | null;

package/src/index.ts

@@ -108,6 +108,11 @@ export {
   type MemberSite,
   type SourceFacts,
 } from "./domain/facts.js";
+export {
+  type ManifestLocator,
+  type ManifestPath,
+  type ManifestPosition,
+} from "./domain/manifest-location.js";
 export {
   fingerprintOf,
   formatMessage,
@@ -115,13 +120,29 @@ export {
   type ViolationKind,
 } from "./domain/violation.js";
 export { makeFileSystemLive } from "./infrastructure/file-system-live.js";
-export { DEFAULT_CONFIG_FILENAME, readManifestFile } from "./infrastructure/manifest-file.js";
+export {
+  findManifestFile,
+  formatManifestYaml,
+  MANIFEST_FILENAMES,
+  type ManifestFile,
+  readManifestFile,
+} from "./infrastructure/manifest-file.js";
 export { listSourceFiles, 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 ExpandedManifest,
+  type ExpandIssue,
+  expandManifest,
+  type Origin,
+  originOf,
+  type Substitution,
+} from "./manifest/expand.js";
+export { MANIFEST_SCHEMA_ID, manifestJsonSchema } from "./manifest/json-schema.js";
 export {
   type DecodedManifest,
   decodeManifest,
+  type DecodeManifestOptions,
   type Manifest,
   type ManifestNode,
   Manifest as ManifestSchema,

package/src/infrastructure/manifest-file.ts

@@ -1,17 +1,193 @@
+import { existsSync, readFileSync } from "node:fs";
+import * as path from "node:path";
 import { pathToFileURL } from "node:url";
 
+import {
+  type Document,
+  isAlias,
+  isMap,
+  isScalar,
+  isSeq,
+  LineCounter,
+  type Node,
+  type Pair,
+  parseDocument,
+  stringify,
+} from "yaml";
+
 import { ConfigInvalid } from "../domain/architecture-error.js";
+import type {
+  ManifestLocator,
+  ManifestPath,
+  ManifestPosition,
+} from "../domain/manifest-location.js";
+
+// The manifest, as the file on disk states it, before any decoding. A data
+// file — YAML, or JSON, which YAML 1.2 contains — is what any host in any
+// language can read, and is the form the docs are written in. A JavaScript
+// module is the escape hatch a Node host alone honours: for a manifest
+// generated from other data, and for what the ecosystem expects of a config
+// file. Whichever it is, what comes out is one `unknown` value for the decoder,
+// and, from the data formats, a way to turn a path in it back into a line.
+
+// In discovery order. A repository with none of these is told all four; one
+// with more than one is refused, so nobody edits the wrong file for a week.
+export const MANIFEST_FILENAMES = [
+  "architecture.yaml",
+  "architecture.yml",
+  "architecture.json",
+  "architecture.config.mjs",
+] as const;
+
+export type ManifestFile = {
+  readonly configPath: string;
+  readonly manifest: unknown;
+  // Absent for a JavaScript module, which has no positions to give.
+  readonly locate: ManifestLocator | undefined;
+};
+
+export const findManifestFile = (repoRoot: string): string => {
+  const present = MANIFEST_FILENAMES.filter((name) => existsSync(path.resolve(repoRoot, name)));
+  const [found] = present;
+  if (found === undefined) {
+    throw new ConfigInvalid({
+      configPath: repoRoot,
+      detail:
+        `no architecture manifest found. Looked for ${MANIFEST_FILENAMES.join(", ")} ` +
+        `in this directory; \`architecture init\` writes a starter architecture.yaml.`,
+    });
+  }
+  if (present.length > 1) {
+    throw new ConfigInvalid({
+      configPath: repoRoot,
+      detail:
+        `more than one architecture manifest is present (${present.join(", ")}), and only one ` +
+        `can be the policy. Delete the others, or name one with ARCHITECTURE_CONFIG.`,
+    });
+  }
+  return path.resolve(repoRoot, found);
+};
+
+const extensionOf = (configPath: string): string => path.extname(configPath).toLowerCase();
+
+const isDataManifest = (configPath: string): boolean =>
+  [".yaml", ".yml", ".json"].includes(extensionOf(configPath));
 
-export const DEFAULT_CONFIG_FILENAME = "architecture.config.mjs";
+const isModuleManifest = (configPath: string): boolean =>
+  [".mjs", ".js", ".cjs"].includes(extensionOf(configPath));
+
+export const readManifestFile = async (configPath: string): Promise<ManifestFile> => {
+  if (isDataManifest(configPath)) return readDataManifest(configPath);
+  if (isModuleManifest(configPath)) return readModuleManifest(configPath);
+  throw new ConfigInvalid({
+    configPath,
+    detail:
+      "a manifest is a .yaml, .yml or .json file, or a .mjs/.js module — " +
+      `not ${JSON.stringify(path.basename(configPath))}.`,
+  });
+};
 
-// The manifest, as the file on disk states it, before any decoding. Today that
-// is a JavaScript module and its default export; a manifest in another format
-// changes this function and nothing behind it.
-export const readManifestFile = async (configPath: string): Promise<unknown> => {
+const readModuleManifest = async (configPath: string): Promise<ManifestFile> => {
   const module: unknown = await import(pathToFileURL(configPath).href).catch((cause: unknown) => {
     throw new ConfigInvalid({ configPath, detail: String(cause) });
   });
-  return typeof module === "object" && module !== null && "default" in module
-    ? module.default
-    : module;
+  const manifest =
+    typeof module === "object" && module !== null && "default" in module ? module.default : module;
+  return { configPath, manifest, locate: undefined };
 };
+
+// YAML 1.2 core schema, which is what a reader without a YAML background
+// expects: `on` and `no` are strings, not booleans. Merge keys (`<<`) resolve,
+// because the parser handles them before the manifest sees the document, and
+// duplicate keys are refused rather than last-one-wins. A tag the parser does
+// not know is refused too — a manifest is data, and a `!!js/function` in it
+// would be a manifest only one runtime could read.
+const readDataManifest = (configPath: string): ManifestFile => {
+  let text: string;
+  try {
+    text = readFileSync(configPath, "utf8");
+  } catch (cause) {
+    throw new ConfigInvalid({ configPath, detail: String(cause) });
+  }
+
+  const lines = new LineCounter();
+  const document = parseDocument(text, {
+    merge: true,
+    uniqueKeys: true,
+    customTags: [],
+    lineCounter: lines,
+    // A JSON file is read by the same parser; strict JSON is valid YAML.
+    schema: "core",
+  });
+  const problems = [...document.errors, ...document.warnings];
+  if (problems.length > 0) {
+    const file = path.basename(configPath);
+    throw new ConfigInvalid({
+      configPath,
+      detail:
+        "the manifest does not parse:\n" +
+        problems
+          .map((problem) => {
+            const [position] = problem.linePos ?? [];
+            const at =
+              position === undefined
+                ? ""
+                : `${file}:${String(position.line)}:${String(position.col)}  `;
+            return `  ${at}${problem.code}: ${problem.message.split("\n")[0] ?? problem.message}`;
+          })
+          .join("\n"),
+    });
+  }
+
+  return {
+    configPath,
+    manifest: document.toJS({ mapAsMap: false }) as unknown,
+    locate: makeLocator(document, lines),
+  };
+};
+
+const keyMatches = (pair: Pair, segment: PropertyKey): boolean =>
+  isScalar(pair.key) && String(pair.key.value) === String(segment);
+
+// Walks the document's own tree by the decoder's path and answers with the
+// position of the deepest thing that exists along it. A map key is reported
+// at the key, where the reader's eye lands; a sequence item at the item. A
+// key merged in through `<<` lives in the fragment it came from, which the
+// walk cannot see — the reader then gets the position of the map instead.
+const makeLocator = (document: Document, lines: LineCounter): ManifestLocator => {
+  const positionOf = (node: Node | null | undefined): ManifestPosition | null => {
+    const offset = node?.range?.[0];
+    if (offset === undefined) return null;
+    const { col, line } = lines.linePos(offset);
+    return { line, column: col };
+  };
+  const resolved = (node: unknown): unknown => (isAlias(node) ? node.resolve(document) : node);
+
+  return (manifestPath: ManifestPath) => {
+    let current: unknown = resolved(document.contents);
+    let position = positionOf(document.contents);
+    for (const segment of manifestPath) {
+      if (isMap(current)) {
+        const pair = current.items.find((one) => keyMatches(one, segment));
+        if (pair === undefined) break;
+        position = positionOf(isScalar(pair.key) ? pair.key : null) ?? position;
+        current = resolved(pair.value);
+      } else if (isSeq(current) && typeof segment === "number") {
+        const item = current.items[segment];
+        if (item === undefined) break;
+        position = positionOf(item as Node) ?? position;
+        current = resolved(item);
+      } else {
+        break;
+      }
+    }
+    return position;
+  };
+};
+
+// The value as a YAML document, for `architecture migrate` and anything else
+// that writes a manifest rather than reads one. Strings are quoted whenever
+// the core schema would read them as something else, and a multi-line one —
+// a probe source — becomes a block scalar.
+export const formatManifestYaml = (manifest: unknown): string =>
+  stringify(manifest, { lineWidth: 100, blockQuote: "literal", schema: "core" });

package/src/load/policy.ts

@@ -44,6 +44,7 @@ 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";
@@ -93,6 +94,9 @@ 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 to give.
+  readonly locate?: ManifestLocator | undefined;
   readonly languages: ReadonlyArray<Language>;
   readonly fileSystem: FileSystem;
 };
@@ -202,7 +206,7 @@ export const loadPolicy = (
 ): Result.Result<LoadedPolicy, ConfigInvalid | PatternInvalid> => {
   const { configPath, fileSystem, languages, repoRoot } = input;
 
-  const decoded = decodeManifest(configPath, input.manifest);
+  const decoded = decodeManifest(configPath, input.manifest, { locate: input.locate });
   if (Result.isFailure(decoded)) return Result.fail(decoded.failure);
   const config = decoded.success.manifest;
 

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,99 @@
+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.
+//
+// Two things the codec does not know are added here: the `defs` map, and the
+// `{ use }` reference form that may stand in for any object — both belong to
+// the expansion pass that runs before decoding.
+
+export const MANIFEST_SCHEMA_ID =
+  "https://dataquail.github.io/goodbones/schema/architecture.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);
+
+// 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 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"],
+};
+
+// Every object schema below the root becomes "this object, or a `use` of a
+// fragment shaped like it". The expansion pass replaces a reference wherever
+// it stands, so the schema admits one wherever an object 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);
+    }
+  }
+  const isObjectSchema = rebuilt.type === "object" && "properties" in rebuilt;
+  return isObjectSchema ? { anyOf: [{ $ref: USE_REFERENCE }, rebuilt] } : rebuilt;
+};
+
+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: {
+        type: "string",
+        description: "For editors. Ignored by the loader.",
+      },
+      defs: {
+        type: "object",
+        description:
+          'Named fragments, referenced elsewhere in the manifest as `{ use: "<name>" }`. A fragment may itself contain `use`.',
+        additionalProperties: true,
+      },
+      ...Object.fromEntries(
+        entriesOf(properties).map(([key, value]) => [key, admitReferences(value)]),
+      ),
+    },
+    $defs: { ...definitions, Use },
+  };
+};