import { GlobSet } from "@effected/glob"; import { DependencyField } from "@effected/npm"; import { Effect, Graph, Option, Schema } from "effect"; import { ALL_DEPENDENCY_FIELDS } from "./internal/dependencyFields.js"; import type { LayerPolicy } from "./LayerPolicy.js"; import { WorkspaceDiscovery } from "./WorkspaceDiscovery.js"; import type { WorkspacePackage } from "./WorkspacePackage.js"; /** * One dependency edge between two workspace packages, in one field. * * @public */ export class LayerEdge extends Schema.Class("LayerEdge")({ /** The dependent package. */ from: Schema.String, /** The package depended on. */ to: Schema.String, /** The manifest map that declares it. */ field: DependencyField, }) { /** `from -> to (field)`. */ get label(): string { return `${this.from} -> ${this.to} (${this.field})`; } } /** * The input to {@link WorkspaceLayering.check}: package names, and per-field edges between them. * * @public */ export interface LayeringGraph { /** Every workspace package name, the root included. */ readonly names: ReadonlyArray; /** One edge per declaring field. */ readonly edges: ReadonlyArray; } type OffenceReason = "upward" | "sameLayer" | "toolingReachesLayer" | "intoUnconstrained" | "intoUnclassified"; /** * What a layering check found. * * @public */ export class LayeringReport extends Schema.Class("LayeringReport")({ /** Packages the policy declares more than once, or declares and also matches with an unconstrained glob. */ duplicates: Schema.Array(Schema.String), /** Workspace packages the policy does not classify. */ unclassified: Schema.Array(Schema.String), /** Edges that break the policy, each with why. */ offenders: Schema.Array( Schema.Struct({ edge: LayerEdge, reason: Schema.Literals(["upward", "sameLayer", "toolingReachesLayer", "intoUnconstrained", "intoUnclassified"]), }), ), /** The members of every dependency cycle in the checked fields, or none. */ cycle: Schema.Option(Schema.Array(Schema.String)), /** Packages the policy names that the workspace does not contain. */ missingDeclared: Schema.Array(Schema.String), /** Required edges absent from the checked fields. */ missingRequiredEdges: Schema.Array(Schema.String), /** Edges in the checked fields; `0` is itself a violation. */ edgeCount: Schema.Number, }) { /** One line per violation: `[]` means the graph honours the policy and the check was not vacuous. */ get violations(): ReadonlyArray { return [ ...this.duplicates.map((name) => `classified more than once: ${name}`), ...this.unclassified.map((name) => `not classified by the policy: ${name}`), ...this.offenders.map(({ edge, reason }) => `${reason}: ${edge.label}`), ...Option.match(this.cycle, { onNone: () => [], onSome: (members) => [`dependency cycle among: ${members.join(", ")}`], }), ...this.missingDeclared.map((name) => `declared but not in the workspace: ${name}`), ...this.missingRequiredEdges.map((edge) => `required edge missing: ${edge}`), ...(this.edgeCount === 0 ? ["no workspace edges in the checked fields: the check is vacuous"] : []), ]; } } type Place = | { readonly kind: "layer"; readonly index: number } | { readonly kind: "tooling" } | { readonly kind: "unconstrained" } | { readonly kind: "unclassified" }; const offence = (from: Place, to: Place): OffenceReason | undefined => { if (from.kind === "unconstrained" || from.kind === "unclassified") return undefined; if (to.kind === "unconstrained") return "intoUnconstrained"; if (to.kind === "unclassified") return "intoUnclassified"; if (from.kind === "tooling") return to.kind === "layer" ? "toolingReachesLayer" : undefined; if (to.kind === "tooling") return undefined; return to.index > from.index ? undefined : to.index === from.index ? "sameLayer" : "upward"; }; /** The sorted members of every strongly connected component larger than one (cf. `DependencyGraph.ts` `cycleMembers`). */ const cycleOf = ( names: ReadonlyArray, edges: ReadonlyArray, ): Option.Option> => { const sorted = [...new Set([...names, ...edges.flatMap((e) => [e.from, e.to])])].sort(); const graph = Graph.directed((mutable) => { const index = new Map(); for (const name of sorted) index.set(name, Graph.addNode(mutable, name)); for (const e of edges) { const from = index.get(e.from); const to = index.get(e.to); if (from !== undefined && to !== undefined && from !== to) Graph.addEdge(mutable, from, to, e.field); } }); const members = new Set(); for (const component of Graph.stronglyConnectedComponents(graph)) { if (component.length < 2) continue; for (const index of component) { const name = sorted[index]; if (name !== undefined) members.add(name); } } return members.size === 0 ? Option.none() : Option.some([...members].sort()); }; /** * Holds a workspace's package graph to a committed {@link LayerPolicy}. * * @remarks * `check` is pure, so positive-control fixture graphs need no filesystem. * `edgesOf` recomputes one edge per declaring field, because * `DependencyGraph` merges the four fields into one adjacency and a policy * may check only some of them. An edge exists wherever a dependency NAME is * a workspace package, whatever its specifier protocol. * * @example * ```ts * import * as NodeServices from "@effect/platform-node/NodeServices"; * import { Workspaces } from "@effected/workspaces"; * import { LayerPolicy, WorkspaceLayering } from "@effected/workspaces/testing"; * import { Effect, Layer } from "effect"; * * const Live = Workspaces.layer({ cwd: "/repo" }).pipe(Layer.provideMerge(NodeServices.layer)); * * const violations = Effect.gen(function* () { * const policy = yield* LayerPolicy.load("/repo/layers.json"); * const report = yield* WorkspaceLayering.checkWorkspace(policy); * return report.violations; * }).pipe(Effect.provide(Live)); * ``` * * @public */ export class WorkspaceLayering { private constructor() {} /** Check `graph` against `policy`, reading only the policy's fields. Pure. */ static readonly check = (graph: LayeringGraph, policy: LayerPolicy): LayeringReport => { const fields = new Set(policy.effectiveFields); const edges = graph.edges.filter((e) => fields.has(e.field)); const unconstrained = GlobSet.make({ patterns: policy.unconstrained }); const layerOf = new Map(); const declared = new Map(); const count = (name: string): void => { declared.set(name, (declared.get(name) ?? 0) + 1); }; policy.layers.forEach((members, index) => { for (const name of members) { count(name); if (!layerOf.has(name)) layerOf.set(name, index); } }); for (const name of policy.tooling) count(name); const tooling = new Set(policy.tooling); const place = (name: string): Place => { const index = layerOf.get(name); if (index !== undefined) return { kind: "layer", index }; if (tooling.has(name)) return { kind: "tooling" }; return unconstrained.matches(name) ? { kind: "unconstrained" } : { kind: "unclassified" }; }; const offenders: Array<{ readonly edge: LayerEdge; readonly reason: OffenceReason }> = []; for (const e of edges) { const reason = offence(place(e.from), place(e.to)); if (reason !== undefined) offenders.push({ edge: e, reason }); } const names = new Set(graph.names); const present = new Set(edges.map((e) => `${e.from} -> ${e.to}`)); return LayeringReport.make({ duplicates: [...declared] .filter(([name, times]) => times > 1 || unconstrained.matches(name)) .map(([name]) => name) .sort(), unclassified: graph.names.filter((name) => place(name).kind === "unclassified").sort(), offenders, cycle: cycleOf(graph.names, edges), missingDeclared: [...declared.keys()].filter((name) => !names.has(name)).sort(), missingRequiredEdges: (policy.requiredEdges ?? []).filter((required) => !present.has(required)), edgeCount: edges.length, }); }; /** One edge per declaring field between workspace packages; self-edges dropped. */ static readonly edgesOf = (packages: ReadonlyArray): ReadonlyArray => { const names = new Set(packages.map((pkg) => pkg.name)); return packages.flatMap((pkg) => ALL_DEPENDENCY_FIELDS.flatMap((field) => Object.keys(pkg[field]) .filter((name) => names.has(name) && name !== pkg.name) .sort() .map((to) => LayerEdge.make({ from: pkg.name, to, field })), ), ); }; /** Discover the workspace and check it against `policy`. */ static readonly checkWorkspace = Effect.fn("WorkspaceLayering.checkWorkspace")(function* (policy: LayerPolicy) { const discovery = yield* WorkspaceDiscovery; const packages = yield* discovery.listPackages(); return WorkspaceLayering.check( { names: packages.map((pkg) => pkg.name), edges: WorkspaceLayering.edgesOf(packages) }, policy, ); }); }