@ontrails/topography 0.2.0

package/src/wayfind/relations.ts

@@ -0,0 +1,344 @@
+import { AmbiguousError, Result } from '@ontrails/core';
+import { z } from 'zod';
+
+import type { DiffResult, TopoGraph, TopoGraphEntry } from '../types.js';
+import { listWayfinderEntityRefs } from './filters.js';
+import type { WayfinderEntityKind, WayfinderEntityRef } from './filters.js';
+
+export const relationKindSchema = z.enum([
+  'composed-by',
+  'consumed-by',
+  'entity-referenced-by',
+  'trailhead-groups',
+  'fired-by',
+  'has-version',
+  'surface-renders',
+  'used-by',
+]);
+
+export const relationRefSchema = z.object({
+  id: z.string(),
+  kind: z.enum([
+    'entity',
+    'trailhead',
+    'resource',
+    'signal',
+    'surface',
+    'trail',
+    'version',
+  ]),
+  trailId: z.string().optional(),
+  versionKey: z.string().optional(),
+});
+
+export const relationEdgeSchema = z.object({
+  from: relationRefSchema,
+  relation: relationKindSchema,
+  to: relationRefSchema,
+});
+
+export const relationGroupSchema = z.object({
+  direction: z.enum(['incoming', 'outgoing']),
+  refs: z.array(relationRefSchema).readonly(),
+  relation: relationKindSchema,
+});
+
+export const impactNodeSchema = relationRefSchema.extend({
+  depth: z.number(),
+  from: relationRefSchema.optional(),
+  via: relationKindSchema.optional(),
+});
+
+export type RelationKind = z.output<typeof relationKindSchema>;
+export type RelationRef = z.output<typeof relationRefSchema>;
+export type RelationEdge = z.output<typeof relationEdgeSchema>;
+export type ImpactDirection = 'downstream' | 'upstream' | 'both';
+
+export interface ImpactOptions {
+  readonly direction: ImpactDirection;
+  readonly limit: number;
+  readonly maxDepth: number;
+}
+
+const entryRef = (entry: TopoGraphEntry): WayfinderEntityRef => ({
+  entry,
+  id: entry.id,
+  kind: entry.kind,
+});
+
+const refFor = (
+  graph: TopoGraph,
+  id: string,
+  kind: WayfinderEntityKind
+): WayfinderEntityRef =>
+  listWayfinderEntityRefs(graph).find(
+    (ref) => ref.id === id && ref.kind === kind
+  ) ?? { id, kind };
+
+export const refSummary = (ref: WayfinderEntityRef): RelationRef => ({
+  id: ref.id,
+  kind: ref.kind,
+  ...(ref.trailId === undefined ? {} : { trailId: ref.trailId }),
+  ...(ref.versionKey === undefined ? {} : { versionKey: ref.versionKey }),
+});
+
+const signalUses = (
+  entry: TopoGraphEntry
+): readonly {
+  readonly relation: Extract<RelationKind, 'consumed-by' | 'fired-by'>;
+  readonly signalId: string;
+}[] => [
+  ...(entry.fires ?? []).map((signalId) => ({
+    relation: 'fired-by' as const,
+    signalId,
+  })),
+  ...[
+    ...(entry.on ?? []),
+    ...(entry.from ?? []),
+    ...(entry.consumers ?? []),
+  ].map((signalId) => ({
+    relation: 'consumed-by' as const,
+    signalId,
+  })),
+  ...(entry.producers ?? []).map((signalId) => ({
+    relation: 'fired-by' as const,
+    signalId,
+  })),
+];
+
+const relationEdge = (
+  from: WayfinderEntityRef,
+  relation: RelationKind,
+  to: WayfinderEntityRef
+): RelationEdge => ({
+  from: refSummary(from),
+  relation,
+  to: refSummary(to),
+});
+
+const relationKey = (edge: RelationEdge): string =>
+  `${edge.from.kind}:${edge.from.id}:${edge.relation}:${edge.to.kind}:${edge.to.id}`;
+
+export const relationEdges = (graph: TopoGraph): readonly RelationEdge[] => {
+  const edges: RelationEdge[] = [];
+  const add = (
+    from: WayfinderEntityRef,
+    relation: RelationKind,
+    to: WayfinderEntityRef
+  ) => edges.push(relationEdge(from, relation, to));
+
+  for (const entry of graph.entries) {
+    const target = entryRef(entry);
+    for (const composedId of entry.composes ?? []) {
+      add(refFor(graph, composedId, 'trail'), 'composed-by', target);
+    }
+    for (const entityId of entry.entities ?? []) {
+      add(refFor(graph, entityId, 'entity'), 'entity-referenced-by', target);
+    }
+    for (const resourceId of entry.resources ?? []) {
+      add(refFor(graph, resourceId, 'resource'), 'used-by', target);
+    }
+    for (const { relation, signalId } of signalUses(entry)) {
+      add(refFor(graph, signalId, 'signal'), relation, target);
+    }
+    for (const surfaceId of entry.surfaces) {
+      add(refFor(graph, surfaceId, 'surface'), 'surface-renders', target);
+    }
+    if (entry.kind === 'trail' && entry.version !== undefined) {
+      add(target, 'has-version', {
+        entry,
+        id: `${entry.id}@${entry.version}`,
+        kind: 'version',
+        trailId: entry.id,
+        versionKey: String(entry.version),
+      });
+    }
+    for (const [versionKey, version] of Object.entries(entry.versions ?? {})) {
+      add(target, 'has-version', {
+        entry,
+        id: `${entry.id}@${versionKey}`,
+        kind: 'version',
+        trailId: entry.id,
+        version,
+        versionKey,
+      });
+    }
+  }
+
+  for (const trailhead of graph.trailheads ?? []) {
+    const trailheadRef = refFor(graph, trailhead.id, 'trailhead');
+    const surfaceRefs = trailhead.surfaces.map((surfaceId) =>
+      refFor(graph, surfaceId, 'surface')
+    );
+    for (const memberId of trailhead.memberIds) {
+      const memberRef = refFor(graph, memberId, 'trail');
+      add(trailheadRef, 'trailhead-groups', memberRef);
+      for (const surfaceRef of surfaceRefs) {
+        add(surfaceRef, 'surface-renders', memberRef);
+      }
+    }
+  }
+
+  return [
+    ...new Map(edges.map((edge) => [relationKey(edge), edge])).values(),
+  ].toSorted((left, right) =>
+    relationKey(left).localeCompare(relationKey(right))
+  );
+};
+
+const refMatches = (ref: RelationRef, target: RelationRef): boolean =>
+  ref.id === target.id && ref.kind === target.kind;
+
+export const groupNearbyEdges = (
+  edges: readonly RelationEdge[],
+  target: RelationRef
+) => {
+  const groups = new Map<string, z.output<typeof relationGroupSchema>>();
+  for (const edge of edges) {
+    const direction = refMatches(edge.from, target) ? 'outgoing' : 'incoming';
+    const ref = direction === 'outgoing' ? edge.to : edge.from;
+    const key = `${direction}:${edge.relation}`;
+    const group = groups.get(key) ?? {
+      direction,
+      refs: [],
+      relation: edge.relation,
+    };
+    groups.set(key, {
+      ...group,
+      refs: [...group.refs, ref].toSorted((left, right) =>
+        `${left.kind}:${left.id}`.localeCompare(`${right.kind}:${right.id}`)
+      ),
+    });
+  }
+  return [...groups.values()].toSorted((left, right) =>
+    `${left.direction}:${left.relation}`.localeCompare(
+      `${right.direction}:${right.relation}`
+    )
+  );
+};
+
+export const edgeTouches = (edge: RelationEdge, target: RelationRef): boolean =>
+  refMatches(edge.from, target) || refMatches(edge.to, target);
+
+const ambiguousRefId = (
+  id: string,
+  refs: readonly WayfinderEntityRef[]
+): AmbiguousError =>
+  new AmbiguousError(
+    `Wayfinder id "${id}" matched multiple entity kinds: ${refs
+      .map((ref) => ref.kind)
+      .join(', ')}. Pass kind to disambiguate.`
+  );
+
+export const resolveEntityRef = (
+  graph: TopoGraph,
+  input: {
+    readonly id: string;
+    readonly kind?: WayfinderEntityKind | undefined;
+  }
+): Result<WayfinderEntityRef | undefined, AmbiguousError> => {
+  const refs = listWayfinderEntityRefs(graph).filter(
+    (ref) =>
+      ref.id === input.id &&
+      (input.kind === undefined || ref.kind === input.kind)
+  );
+  if (input.kind === undefined) {
+    const uniqueKinds = new Set(refs.map((ref) => ref.kind));
+    if (uniqueKinds.size > 1) {
+      return Result.err(ambiguousRefId(input.id, refs));
+    }
+  }
+  return Result.ok(refs[0]);
+};
+
+const edgesForDirection = (
+  edges: readonly RelationEdge[],
+  current: RelationRef,
+  direction: ImpactDirection
+): readonly {
+  readonly edge: RelationEdge;
+  readonly node: RelationRef;
+}[] => {
+  const outgoing =
+    direction === 'downstream' || direction === 'both'
+      ? edges
+          .filter((edge) => refMatches(edge.from, current))
+          .map((edge) => ({ edge, node: edge.to }))
+      : [];
+  const incoming =
+    direction === 'upstream' || direction === 'both'
+      ? edges
+          .filter((edge) => refMatches(edge.to, current))
+          .map((edge) => ({ edge, node: edge.from }))
+      : [];
+  return [...outgoing, ...incoming].toSorted((left, right) =>
+    relationKey(left.edge).localeCompare(relationKey(right.edge))
+  );
+};
+
+export const impactFor = (
+  graph: TopoGraph,
+  input: ImpactOptions,
+  target: RelationRef
+) => {
+  const edges = relationEdges(graph);
+  const seen = new Set([`${target.kind}:${target.id}`]);
+  const queue: {
+    readonly depth: number;
+    readonly ref: RelationRef;
+  }[] = [{ depth: 0, ref: target }];
+  const nodes: z.output<typeof impactNodeSchema>[] = [];
+  const includedEdges = new Map<string, RelationEdge>();
+
+  for (
+    let index = 0;
+    index < queue.length && nodes.length < input.limit;
+    index += 1
+  ) {
+    const current = queue[index];
+    if (current === undefined) {
+      break;
+    }
+    if (current.depth >= input.maxDepth) {
+      continue;
+    }
+    for (const { edge, node } of edgesForDirection(
+      edges,
+      current.ref,
+      input.direction
+    )) {
+      includedEdges.set(relationKey(edge), edge);
+      const key = `${node.kind}:${node.id}`;
+      if (seen.has(key)) {
+        continue;
+      }
+      seen.add(key);
+      const reached = {
+        ...node,
+        depth: current.depth + 1,
+        from: current.ref,
+        via: edge.relation,
+      };
+      nodes.push(reached);
+      queue.push({ depth: reached.depth, ref: node });
+      if (nodes.length >= input.limit) {
+        break;
+      }
+    }
+  }
+
+  return {
+    edges: [...includedEdges.values()].toSorted((left, right) =>
+      relationKey(left).localeCompare(relationKey(right))
+    ),
+    nodes,
+  };
+};
+
+export const diffResult = (diff: DiffResult): DiffResult => ({
+  breaking: diff.breaking,
+  entries: diff.entries,
+  hasBreaking: diff.hasBreaking,
+  info: diff.info,
+  warnings: diff.warnings,
+});

package/src/workspace-configured-aliases.ts

@@ -0,0 +1,221 @@
+import { trailsLockFileName } from '@ontrails/config';
+import type { ReadTrailsProjectIdentityResult } from '@ontrails/config';
+import { lstatSync, readlinkSync, realpathSync } from 'node:fs';
+import {
+  basename,
+  dirname,
+  isAbsolute,
+  posix,
+  relative,
+  resolve,
+  sep,
+} from 'node:path';
+
+export interface ConfiguredAppAlias {
+  readonly aliasEntryPaths: ReadonlySet<string>;
+  readonly authoredLockPath: string;
+  readonly authoredRoot: string;
+  readonly physicalLockPath: string;
+  readonly physicalAliasEntryPaths: ReadonlySet<string>;
+  readonly physicalRoot: string;
+  readonly physicalRootDir: string;
+}
+
+const toPosixRelative = (root: string, target: string): string => {
+  const path = relative(root, target);
+  return sep === posix.sep ? path : path.split(sep).join(posix.sep);
+};
+
+const isWithinBoundary = (boundary: string, target: string): boolean => {
+  const path = relative(boundary, target);
+  return (
+    path === '' ||
+    (!isAbsolute(path) && path !== '..' && !path.startsWith(`..${sep}`))
+  );
+};
+
+const isNormalizedConfiguredRoot = (root: string): boolean =>
+  root !== '.' &&
+  !posix.isAbsolute(root) &&
+  posix.normalize(root) === root &&
+  root.split('/').every((segment) => segment !== '' && segment !== '..');
+
+/** Express an in-workspace target as segments to descend from the canonical root. */
+const workspaceDescentSegments = (
+  canonicalWorkspaceRoot: string,
+  target: string
+): readonly string[] | undefined => {
+  const suffix: string[] = [];
+  let ancestor = target;
+  while (!isWithinBoundary(canonicalWorkspaceRoot, ancestor)) {
+    if (realpathSync(ancestor) === canonicalWorkspaceRoot) {
+      return suffix;
+    }
+    const parent = dirname(ancestor);
+    if (parent === ancestor) {
+      return undefined;
+    }
+    suffix.unshift(basename(ancestor));
+    ancestor = parent;
+  }
+  const path = toPosixRelative(canonicalWorkspaceRoot, ancestor);
+  return path === '' ? suffix : [...path.split(posix.sep), ...suffix];
+};
+
+/** Walk a target path segment by segment so parent alias hops stay visible. */
+const physicalAliasTargetChain = (
+  canonicalWorkspaceRoot: string,
+  absoluteAliasPath: string,
+  canonicalAliasTarget: string
+): readonly string[] | undefined => {
+  const entries: string[] = [];
+  const visited = new Set<string>();
+  const pending: string[] = [];
+  let current = resolve(
+    realpathSync(dirname(absoluteAliasPath)),
+    basename(absoluteAliasPath)
+  );
+  while (true) {
+    if (!isWithinBoundary(canonicalWorkspaceRoot, current)) {
+      return undefined;
+    }
+    if (!lstatSync(current).isSymbolicLink()) {
+      const segment = pending.shift();
+      if (segment === undefined) {
+        return realpathSync(current) === canonicalAliasTarget
+          ? entries
+          : undefined;
+      }
+      current = resolve(current, segment);
+      continue;
+    }
+    if (visited.has(current)) {
+      return undefined;
+    }
+    visited.add(current);
+    entries.push(toPosixRelative(canonicalWorkspaceRoot, current));
+    if (pending.length > 0) {
+      entries.push(
+        toPosixRelative(canonicalWorkspaceRoot, resolve(current, ...pending))
+      );
+    }
+    const targetSegments = workspaceDescentSegments(
+      canonicalWorkspaceRoot,
+      resolve(dirname(current), readlinkSync(current))
+    );
+    if (targetSegments === undefined) {
+      return undefined;
+    }
+    pending.unshift(...targetSegments);
+    current = canonicalWorkspaceRoot;
+  }
+};
+
+const configuredAliasEntryPaths = (
+  workspaceRoot: string,
+  canonicalWorkspaceRoot: string,
+  authoredRoot: string
+): {
+  readonly authored: ReadonlySet<string>;
+  readonly physical: ReadonlySet<string>;
+} => {
+  const authored = new Set<string>();
+  const physical = new Set<string>();
+  const segments = authoredRoot.split('/');
+  for (let index = 1; index <= segments.length; index += 1) {
+    const path = segments.slice(0, index).join('/');
+    const absolutePath = resolve(workspaceRoot, path);
+    try {
+      if (!lstatSync(absolutePath).isSymbolicLink()) {
+        continue;
+      }
+      const canonicalAliasTarget = realpathSync(absolutePath);
+      if (isWithinBoundary(canonicalWorkspaceRoot, canonicalAliasTarget)) {
+        const physicalEntries = physicalAliasTargetChain(
+          canonicalWorkspaceRoot,
+          absolutePath,
+          canonicalAliasTarget
+        );
+        if (physicalEntries !== undefined) {
+          authored.add(path);
+          for (const physicalEntry of physicalEntries) {
+            physical.add(physicalEntry);
+          }
+        }
+      }
+    } catch {
+      // A changing or unreadable alias remains an unsupported collection edge.
+    }
+  }
+  return { authored, physical };
+};
+
+/** Reconcile only normalized, unique aliases whose real target stays in-workspace. */
+export const deriveConfiguredAppAliases = (
+  identity: ReadTrailsProjectIdentityResult
+): readonly ConfiguredAppAlias[] => {
+  let canonicalWorkspaceRoot: string;
+  try {
+    canonicalWorkspaceRoot = realpathSync(identity.rootDir);
+  } catch {
+    return [];
+  }
+
+  const candidates = identity.apps.flatMap((app): ConfiguredAppAlias[] => {
+    if (!isNormalizedConfiguredRoot(app.root)) {
+      return [];
+    }
+    const authoredAppRoot = resolve(identity.rootDir, app.root);
+    if (resolve(app.rootDir) !== authoredAppRoot) {
+      return [];
+    }
+
+    let canonicalAppRoot: string;
+    try {
+      canonicalAppRoot = realpathSync(app.rootDir);
+    } catch {
+      return [];
+    }
+    if (!isWithinBoundary(canonicalWorkspaceRoot, canonicalAppRoot)) {
+      return [];
+    }
+
+    const physicalRoot = toPosixRelative(
+      canonicalWorkspaceRoot,
+      canonicalAppRoot
+    );
+    if (physicalRoot === app.root) {
+      return [];
+    }
+    const aliasEntryPaths = configuredAliasEntryPaths(
+      identity.rootDir,
+      canonicalWorkspaceRoot,
+      app.root
+    );
+    if (aliasEntryPaths.authored.size === 0) {
+      return [];
+    }
+    return [
+      {
+        aliasEntryPaths: aliasEntryPaths.authored,
+        authoredLockPath: posix.join(app.root, trailsLockFileName),
+        authoredRoot: app.root,
+        physicalAliasEntryPaths: aliasEntryPaths.physical,
+        physicalLockPath: posix.join(physicalRoot, trailsLockFileName),
+        physicalRoot,
+        physicalRootDir: canonicalAppRoot,
+      },
+    ];
+  });
+
+  const physicalLockOwners = new Map<string, number>();
+  for (const alias of candidates) {
+    physicalLockOwners.set(
+      alias.physicalLockPath,
+      (physicalLockOwners.get(alias.physicalLockPath) ?? 0) + 1
+    );
+  }
+  return candidates.filter(
+    (alias) => physicalLockOwners.get(alias.physicalLockPath) === 1
+  );
+};