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

package/src/infrastructure/manifest-include.ts

@@ -0,0 +1,318 @@
+import * as path from "node:path";
+
+import { ConfigInvalid } from "../domain/architecture-error.js";
+import {
+  type ManifestLocator,
+  type ManifestPath,
+  renderManifestPath,
+} from "../domain/manifest-location.js";
+
+// A manifest split across files. `{ include: "<path>" }` standing anywhere in
+// a manifest — a node under `tree`, a whole section, one entry of a list — is
+// replaced by the value of the file it names, read by the same parser and
+// resolved relative to the file that wrote the reference. This runs on the raw
+// value before anything else looks at it: the `defs`/`use` expansion sees one
+// document, the decoder sees one document, and the schema never learns that a
+// reference existed.
+//
+// What is deliberately not here: no merging (a value is replaced, full stop),
+// no parameters, no glob of files. An included file is YAML or JSON only — a
+// module would make a data manifest readable by one runtime — and a file may
+// carry a top-level `defs` of its own, which joins the manifest's under one
+// namespace, and a `$schema` for its editor, which is dropped.
+
+// One file, as the reader parsed it.
+export type SourceDocument = {
+  readonly value: unknown;
+  readonly locate: ManifestLocator | undefined;
+};
+
+export type IncludeReader = {
+  readonly exists: (file: string) => boolean;
+  // Throws `ConfigInvalid` naming the file when it does not parse.
+  readonly read: (file: string) => SourceDocument;
+};
+
+export type IncludedManifest = {
+  readonly value: unknown;
+  // Answers for every file: a position inside an included file carries that
+  // file's path, relative to the root manifest's directory.
+  readonly locate: ManifestLocator | undefined;
+  // Every file that took part, root first, as absolute paths.
+  readonly files: ReadonlyArray<string>;
+};
+
+const INCLUDABLE = [".yaml", ".yml", ".json"];
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+type IncludeReference = Record<string, unknown> & { readonly include: unknown };
+
+const isInclude = (value: unknown): value is IncludeReference =>
+  isRecord(value) && "include" in value;
+
+const isPrefix = (prefix: ManifestPath, whole: ManifestPath): boolean =>
+  prefix.length <= whole.length && prefix.every((segment, index) => whole[index] === segment);
+
+// Which file a region of the assembled document came from: everything under
+// `at` was written in the file whose locator this is, starting at `origin`
+// there. The root file mounts at the root; each include mounts where it
+// landed; a fragment hoisted out of an included file mounts under `defs`; and
+// a list item that moved — spliced in from another file, or shifted by a
+// splice before it — mounts on its own, since its index is not the one it
+// was written at.
+type Mount = {
+  readonly at: ManifestPath;
+  readonly origin: ManifestPath;
+  readonly label: string | undefined;
+  readonly locate: ManifestLocator | undefined;
+};
+
+// The file being walked.
+type Source = {
+  readonly file: string;
+  // How the file is named in a message: its path relative to the root
+  // manifest's directory. The root file itself has none, and is named by
+  // whoever reports the error.
+  readonly label: string | undefined;
+  readonly locate: ManifestLocator | undefined;
+  // Every file on the way here, for the cycle check.
+  readonly stack: ReadonlyArray<string>;
+};
+
+type Opened = {
+  readonly document: SourceDocument;
+  readonly source: Source;
+};
+
+const makeLocator = (mounts: ReadonlyArray<Mount>): ManifestLocator | undefined => {
+  if (!mounts.some((mount) => mount.locate !== undefined)) return undefined;
+  return (manifestPath) => {
+    const innermost = mounts
+      .filter((mount) => isPrefix(mount.at, manifestPath))
+      .sort((a, b) => a.at.length - b.at.length)
+      .at(-1);
+    if (innermost === undefined) return null;
+    const found =
+      innermost.locate?.([...innermost.origin, ...manifestPath.slice(innermost.at.length)]) ?? null;
+    if (found === null) return null;
+    return innermost.label === undefined ? found : { ...found, file: innermost.label };
+  };
+};
+
+export const expandIncludes = (
+  rootPath: string,
+  root: SourceDocument,
+  reader: IncludeReader,
+): IncludedManifest => {
+  const rootDirectory = path.dirname(rootPath);
+  const labelOf = (file: string): string =>
+    path.relative(rootDirectory, file).split(path.sep).join("/");
+  const nameOf = (source: Source): string => source.label ?? path.basename(rootPath);
+
+  const files: Array<string> = [rootPath];
+  const mounts: Array<Mount> = [{ at: [], origin: [], label: undefined, locate: root.locate }];
+  // Fragments hoisted out of included files, and the file each name came from.
+  const hoisted: Record<string, unknown> = {};
+  const definedIn = new Map<string, string>();
+
+  const refuse = (source: Source, origin: ManifestPath, detail: string): never => {
+    const position = source.locate?.(origin) ?? null;
+    const at =
+      position === null
+        ? ""
+        : `${nameOf(source)}:${String(position.line)}:${String(position.column)}  `;
+    throw new ConfigInvalid({
+      configPath: rootPath,
+      detail: `the manifest does not include:\n  ${at}${renderManifestPath(origin)}: ${detail}`,
+    });
+  };
+
+  // Checks a reference and reads the file it names. Nothing is placed yet:
+  // where the value lands depends on whether it is a list spliced into a list.
+  const open = (reference: IncludeReference, origin: ManifestPath, source: Source): Opened => {
+    const { include: specifier, ...rest } = reference;
+    if (typeof specifier !== "string") {
+      return refuse(source, origin, "`include` names a file, as a string.");
+    }
+    const shown = `\`include: ${JSON.stringify(specifier)}\``;
+    const beside = Object.keys(rest);
+    if (beside.length > 0) {
+      return refuse(
+        source,
+        origin,
+        `${shown} stands alone: an included file is replaced whole, so there is nothing for ` +
+          `${beside.map((key) => `\`${key}\``).join(", ")} to override. ` +
+          `To override a fragment, put it under \`defs\` and \`use\` it.`,
+      );
+    }
+    const target = path.resolve(path.dirname(source.file), specifier);
+    if (!INCLUDABLE.includes(path.extname(target).toLowerCase())) {
+      return refuse(
+        source,
+        origin,
+        `${shown} names a file that is not YAML or JSON. Only a data file can be included: ` +
+          `a module would make the manifest readable by one runtime only.`,
+      );
+    }
+    if (source.stack.includes(target)) {
+      return refuse(
+        source,
+        origin,
+        `${shown} includes a file that is already being included: ` +
+          `${[...source.stack, target].map(labelOf).join(" → ")}.`,
+      );
+    }
+    if (!reader.exists(target)) {
+      return refuse(
+        source,
+        origin,
+        `${shown} names a file that does not exist (looked for ${labelOf(target)}, ` +
+          `relative to ${nameOf(source)}).`,
+      );
+    }
+    const document = reader.read(target);
+    files.push(target);
+    return {
+      document,
+      source: {
+        file: target,
+        label: labelOf(target),
+        locate: document.locate,
+        stack: [...source.stack, target],
+      },
+    };
+  };
+
+  // Places an opened file at `at`, whole, and walks it so no reference is
+  // left inside. A top-level `defs` in the file joins the root's, and its
+  // `$schema` is for the editor — unless the file was included somewhere
+  // under `defs`, where it is a fragment or the map itself, and a key by
+  // either name is the author's.
+  const place = (opened: Opened, at: ManifestPath): unknown => {
+    const { document, source } = opened;
+    mounts.push({ at, origin: [], label: source.label, locate: source.locate });
+    if (!isRecord(document.value) || at[0] === "defs") {
+      return walk(document.value, at, [], source);
+    }
+    const { $schema: _schema, defs, ...body } = document.value;
+    if (defs !== undefined) {
+      if (!isRecord(defs)) {
+        return refuse(source, ["defs"], "`defs` must be a map of named fragments.");
+      }
+      for (const [name, fragment] of Object.entries(defs)) {
+        const already = definedIn.get(name);
+        if (already !== undefined) {
+          return refuse(
+            source,
+            ["defs", name],
+            `\`defs.${name}\` is already defined in ${already}. Every file's \`defs\` share ` +
+              `one namespace; rename one of them.`,
+          );
+        }
+        definedIn.set(name, nameOf(source));
+        mounts.push({
+          at: ["defs", name],
+          origin: ["defs", name],
+          label: source.label,
+          locate: source.locate,
+        });
+        hoisted[name] = walk(fragment, ["defs", name], ["defs", name], source);
+      }
+    }
+    return walk(body, at, [], source);
+  };
+
+  // Appends each item of `list` to `items`. An include standing as an item
+  // whose file holds a list is spliced in, so a list can be split across
+  // files; an item that does not sit at the index it was written at is
+  // mounted on its own.
+  const append = (
+    items: Array<unknown>,
+    list: ReadonlyArray<unknown>,
+    at: ManifestPath,
+    origin: ManifestPath,
+    source: Source,
+    spliced: boolean,
+  ): void => {
+    for (const [index, item] of list.entries()) {
+      const itemOrigin = [...origin, index];
+      const slot = [...at, items.length];
+      if (isInclude(item)) {
+        const opened = open(item, itemOrigin, source);
+        if (Array.isArray(opened.document.value)) {
+          append(items, opened.document.value, at, [], opened.source, true);
+        } else {
+          items.push(place(opened, slot));
+        }
+        continue;
+      }
+      if (spliced || items.length !== index) {
+        mounts.push({ at: slot, origin: itemOrigin, label: source.label, locate: source.locate });
+      }
+      items.push(walk(item, slot, itemOrigin, source));
+    }
+  };
+
+  const walk = (
+    value: unknown,
+    at: ManifestPath,
+    origin: ManifestPath,
+    source: Source,
+  ): unknown => {
+    if (isInclude(value)) return place(open(value, origin, source), at);
+
+    if (Array.isArray(value)) {
+      const items: Array<unknown> = [];
+      append(items, value, at, origin, source, false);
+      return items;
+    }
+
+    if (isRecord(value)) {
+      const entries: Record<string, unknown> = {};
+      for (const [key, item] of Object.entries(value)) {
+        entries[key] = walk(item, [...at, key], [...origin, key], source);
+      }
+      return entries;
+    }
+
+    return value;
+  };
+
+  const rootSource: Source = {
+    file: rootPath,
+    label: undefined,
+    locate: root.locate,
+    stack: [rootPath],
+  };
+  const value = walk(root.value, [], [], rootSource);
+
+  // Nothing was included: the value and the locator are the reader's own.
+  if (files.length === 1) return { value, locate: root.locate, files };
+
+  const names = Object.keys(hoisted);
+  if (names.length === 0 || !isRecord(value)) {
+    return { value, locate: makeLocator(mounts), files };
+  }
+
+  const own = value.defs;
+  if (own !== undefined && !isRecord(own)) {
+    return refuse(rootSource, ["defs"], "`defs` must be a map of named fragments.");
+  }
+  for (const name of names) {
+    if (own !== undefined && name in own) {
+      return refuse(
+        rootSource,
+        ["defs", name],
+        `\`defs.${name}\` is also defined in ${definedIn.get(name) ?? "an included file"}. ` +
+          `Every file's \`defs\` share one namespace; rename one of them.`,
+      );
+    }
+  }
+  return {
+    value: { ...value, defs: { ...(own ?? {}), ...hoisted } },
+    locate: makeLocator(mounts),
+    files,
+  };
+};

package/src/infrastructure/syntax-matcher-fake.ts

@@ -0,0 +1,51 @@
+import type { SyntaxMatch, SyntaxMatcher } from "../ports/syntax-matcher.js";
+
+// One match as a test states it: the text, its captures as a plain object,
+// the anchor, and optionally a line — the rest of the range is filled in.
+// `rule` narrows the match to one rule (compared by its JSON), so a test
+// about two `syntax` terms can answer each differently; omit it to answer
+// every rule the same.
+export type StagedMatch = {
+  readonly text: string;
+  readonly captures?: Readonly<Record<string, string>>;
+  readonly anchor?: string | null;
+  readonly line?: number;
+  readonly rule?: unknown;
+};
+
+const ZERO = { line: 0, column: 0 };
+
+// Keyed by the source text, as the extractor fake is: a core test states
+// what a snippet's syntax yields and never the parse, which has its own
+// tests in the matcher package. A text not staged parses to no matches; a
+// file whose extension is not among `extensions` does not parse at all,
+// which is the shape of a language with no matcher.
+export const makeSyntaxMatcherFake = (
+  staged: Readonly<Record<string, ReadonlyArray<StagedMatch>>>,
+  extensions: ReadonlyArray<string> | null = null,
+): SyntaxMatcher => ({
+  parse: (file, text) => {
+    if (extensions !== null && !extensions.some((extension) => file.endsWith(extension))) {
+      return null;
+    }
+    const matches = staged[text] ?? [];
+    return {
+      // A staged match's line is what a position is anchored by.
+      anchorAt: (position) => matches.find((one) => one.line === position.line)?.anchor ?? null,
+      findAll: (rule) => {
+        const asked = JSON.stringify(rule);
+        return matches
+          .filter((one) => one.rule === undefined || JSON.stringify(one.rule) === asked)
+          .map((one): SyntaxMatch => ({
+            text: one.text,
+            captures: new Map(Object.entries(one.captures ?? {})),
+            range: {
+              start: one.line === undefined ? ZERO : { line: one.line, column: 0 },
+              end: one.line === undefined ? ZERO : { line: one.line, column: one.text.length },
+            },
+            anchor: one.anchor ?? null,
+          }));
+      },
+    };
+  },
+});

package/src/infrastructure/walk.ts

@@ -1,4 +1,4 @@
-import { readdirSync, statSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import * as path from "node:path";
 
 import type { Language } from "../ports/language.js";
@@ -24,13 +24,16 @@ export type WalkedLanguage = Pick<Language, "extensions" | "ignoredFiles">;
 // Which files count as source is the languages' to say: the extension set is
 // the union of theirs, and so is the set of files to step over. A root that
 // names a file is that file, whatever its extension — `architecture check
-// <file>` is a reasonable thing to type.
+// <file>` is a reasonable thing to type. `widened` adds the extensions a
+// campaign's scope names beyond the packs' — a file the pack cannot parse
+// contributes no facts, and only a campaign that asked for it sees it.
 export const listSourceFiles = (
   repoRoot: string,
   roots: ReadonlyArray<string>,
   languages: ReadonlyArray<WalkedLanguage>,
+  widened: ReadonlyArray<string> = [],
 ): ReadonlyArray<string> => {
-  const extensions = new Set(languages.flatMap((language) => language.extensions));
+  const extensions = new Set([...languages.flatMap((language) => language.extensions), ...widened]);
   const ignored = languages.flatMap((language) => language.ignoredFiles);
   const isSource = (entry: string): boolean =>
     extensions.has(path.extname(entry)) && !ignored.some((pattern) => pattern.test(entry));
@@ -52,3 +55,124 @@ export const listSourceFiles = (
   }
   return found.sort();
 };
+
+// What `infer` needs to know about a language beyond the walker's two: what
+// marks a package of it, and where a package keeps its source.
+export type PackagedLanguage = Pick<Language, "packageMarkers" | "sourceRoots">;
+
+export type PackageRoot = {
+  // Repo-relative folder with forward slashes; `""` is the repository itself.
+  readonly root: string;
+  // The package's source folder, repo-relative, when one of the language's
+  // `sourceRoots` exists under it; otherwise `null`, and source sits at the root.
+  readonly source: string | null;
+};
+
+// The packages under (and above) `roots`: every folder holding one of the
+// languages' marker files, the walk roots' own ancestors included, so a walk
+// rooted at `src/` still finds the `package.json` beside it. Sorted by path.
+export const listPackageRoots = (
+  repoRoot: string,
+  roots: ReadonlyArray<string>,
+  languages: ReadonlyArray<PackagedLanguage>,
+): ReadonlyArray<PackageRoot> => {
+  const markers = languages.flatMap((language) => language.packageMarkers);
+  const sourceRoots = languages.flatMap((language) => language.sourceRoots);
+  if (markers.length === 0) return [];
+
+  const isDirectory = (absolute: string): boolean => {
+    try {
+      return statSync(absolute).isDirectory();
+    } catch {
+      return false;
+    }
+  };
+  const relative = (absolute: string): string =>
+    path.relative(repoRoot, absolute).replaceAll(path.sep, "/");
+
+  const found = new Map<string, PackageRoot>();
+  const consider = (absolute: string): void => {
+    const key = relative(absolute);
+    if (found.has(key)) return;
+    if (!markers.some((marker) => existsSync(path.join(absolute, marker)))) return;
+    const source = sourceRoots.find((name) => isDirectory(path.join(absolute, name)));
+    found.set(key, {
+      root: key,
+      source: source === undefined ? null : relative(path.join(absolute, source)),
+    });
+  };
+  const walk = (absolute: string): void => {
+    consider(absolute);
+    for (const entry of readdirSync(absolute)) {
+      if (SKIPPED.has(entry)) continue;
+      const child = path.join(absolute, entry);
+      if (isDirectory(child)) walk(child);
+    }
+  };
+
+  const top = path.resolve(repoRoot);
+  for (const root of roots) {
+    let absolute = path.resolve(repoRoot, root);
+    if (!isDirectory(absolute)) absolute = path.dirname(absolute);
+    walk(absolute);
+    // The ancestors, up to the repository: a package is as often above the
+    // walk root as inside it.
+    for (let above = absolute; above.startsWith(top); above = path.dirname(above)) {
+      consider(above);
+      if (above === top) break;
+    }
+  }
+  return [...found.values()].sort((a, b) => a.root.localeCompare(b.root));
+};
+
+export type WorkspaceProject = {
+  readonly name: string;
+  // Repo-relative folder with forward slashes.
+  readonly root: string;
+};
+
+// The workspace's projects, for an `nx` perimeter: every folder under the
+// roots holding a `project.json`, named by it — or, when it names nothing,
+// by the `package.json` beside it, or the folder. Read from the files
+// rather than from `nx graph`, so no process is spawned and a checkout
+// without the workspace's tooling installed still has its sectors.
+export const listWorkspaceProjects = (
+  repoRoot: string,
+  roots: ReadonlyArray<string>,
+): ReadonlyArray<WorkspaceProject> => {
+  const found: Array<WorkspaceProject> = [];
+  const nameIn = (absolute: string, file: string): string | null => {
+    try {
+      const parsed = JSON.parse(readFileSync(path.join(absolute, file), "utf8")) as unknown;
+      const name =
+        typeof parsed === "object" && parsed !== null
+          ? (parsed as { readonly name?: unknown }).name
+          : undefined;
+      return typeof name === "string" && name !== "" ? name : null;
+    } catch {
+      return null;
+    }
+  };
+  const walk = (absolute: string): void => {
+    if (existsSync(path.join(absolute, "project.json"))) {
+      const root = path.relative(repoRoot, absolute).replaceAll(path.sep, "/");
+      found.push({
+        name:
+          nameIn(absolute, "project.json") ??
+          nameIn(absolute, "package.json") ??
+          path.basename(absolute),
+        root,
+      });
+    }
+    for (const entry of readdirSync(absolute)) {
+      if (SKIPPED.has(entry)) continue;
+      const child = path.join(absolute, entry);
+      if (statSync(child).isDirectory()) walk(child);
+    }
+  };
+  for (const root of roots) {
+    const absolute = path.resolve(repoRoot, root);
+    if (statSync(absolute).isDirectory()) walk(absolute);
+  }
+  return found.sort((a, b) => a.root.localeCompare(b.root));
+};

package/src/load/extension.ts

@@ -0,0 +1,66 @@
+import type * as Result from "effect/Result";
+
+import type { ResolveScope } from "../domain/architecture-config.js";
+import type { ConfigInvalid, PatternInvalid } from "../domain/architecture-error.js";
+import type { ManifestExtension } from "../manifest/extension.js";
+import 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 { SyntaxMatcher } from "../ports/syntax-matcher.js";
+
+// The load half of a family the core does not own: what `loadPolicy` hands it,
+// and what it hands back.
+//
+// A host composes the extensions it wants — `loadPolicy({ …, extensions: [
+// campaignsExtension({ functions, reports }) ] })` — and reads its family's
+// state back off `LoadedPolicy.extensions` through whatever typed accessor
+// that package exports. The core carries the value and never looks inside it.
+//
+// An extension is given the same things the core's own families are given at
+// load: the routing extractor and syntax matcher, the file system port, the
+// language packs, and which scope covers a given file. It is not given the
+// resolver, which is built after every rule has been probed — a family that
+// needs one resolves at evaluation, off `LoadedPolicy`.
+
+export type ExtensionRoute = {
+  readonly language: Language;
+  readonly scope: ResolveScope;
+};
+
+export type ExtensionContext<Spec = unknown> = {
+  // What this family's `decode` returned.
+  readonly spec: Spec;
+  readonly configPath: string;
+  readonly repoRoot: string;
+  // The manifest the core decoded — `resolve`, `aliases`, `tree`, the
+  // families the core owns. The family's own keys are in `spec`.
+  readonly config: Manifest;
+  readonly languages: ReadonlyArray<Language>;
+  readonly fileSystem: FileSystem;
+  // Routes each file to the extractor of the language whose scope covers it:
+  // the same one the core parsed its own probes with.
+  readonly extractor: FactExtractor;
+  // Routes each file to the syntax matcher of its scope's language; `parse`
+  // answers `null` for a language carrying none.
+  readonly syntax: SyntaxMatcher;
+  readonly routeFor: (file: string) => ExtensionRoute | undefined;
+  readonly now: number;
+};
+
+export type LoadedExtension<Value = unknown> = {
+  // Carried on `LoadedPolicy.extensions`, keyed by the extension's id.
+  readonly value: Value;
+  // Rules of this family that do not report their own probe. Merged into the
+  // one refusal the loader raises for every family at once, so a vacuous
+  // campaign and a vacuous import rule are reported in the same sentence.
+  readonly vacuous?: ReadonlyArray<string> | undefined;
+};
+
+export type PolicyExtension<Spec = unknown, Value = unknown> = ManifestExtension<Spec> & {
+  // A method, like `decode`, so the loader can hold every extension at one
+  // erased type after their specs have been decoded.
+  load(
+    context: ExtensionContext<Spec>,
+  ): Result.Result<LoadedExtension<Value>, ConfigInvalid | PatternInvalid>;
+};