@ontrails/trails 1.0.0-beta.30 → 1.0.0-beta.32

package/src/trails/topo-activation.ts

@@ -1,385 +1,14 @@
-import type {
-  ActivationEntry,
-  ActivationSource,
-  ActivationSourceProjection,
-  AnyTrail,
-  Topo,
-} from '@ontrails/core';
-import {
-  activationSourceKey,
-  projectActivationSourceDeclaration,
-} from '@ontrails/core';
-
-export interface ActivationChainReport {
-  readonly consumer: string;
-  readonly producer: string;
-  readonly signal: string;
-}
-
-type JsonSchemaReport = Readonly<Record<string, unknown>>;
-
-export interface ActivationSourceReport extends ActivationSourceProjection {
-  readonly cron?: string | undefined;
-  readonly hasParse?: true | undefined;
-  readonly hasPayloadSchema?: true | undefined;
-  readonly hasVerify?: true | undefined;
-  readonly id: string;
-  readonly input?: unknown;
-  readonly inputSchema?: JsonSchemaReport | undefined;
-  readonly kind: string;
-  readonly key: string;
-  readonly meta?: Readonly<Record<string, unknown>> | undefined;
-  readonly method?: string | undefined;
-  readonly parseOutputSchema?: JsonSchemaReport | undefined;
-  readonly path?: string | undefined;
-  readonly payloadSchema?: JsonSchemaReport | undefined;
-  readonly timezone?: string | undefined;
-}
-
-export interface ActivationEdgeReport extends Readonly<
-  Record<string, unknown>
-> {
-  readonly hasWhere: boolean;
-  readonly sourceId: string;
-  readonly sourceKey: string;
-  readonly sourceKind: string;
-  readonly trailId: string;
-  readonly where?: { readonly predicate: true } | undefined;
-}
-
-export interface SignalActivationRelations {
-  readonly consumers: readonly string[];
-  readonly producers: readonly string[];
-}
-
-export interface TrailActivationReport {
-  readonly activatedBy: readonly string[];
-  readonly activates: readonly string[];
-  readonly chains: readonly ActivationChainReport[];
-  readonly edges: readonly ActivationEdgeReport[];
-  readonly fires: readonly string[];
-  readonly on: readonly string[];
-  readonly sources: readonly ActivationSourceReport[];
-}
-
-export interface ActivationOverviewReport {
-  readonly chainCount: number;
-  readonly chains: readonly ActivationChainReport[];
-  readonly edgeCount: number;
-  readonly edges: readonly ActivationEdgeReport[];
-  readonly signalIds: readonly string[];
-  readonly sourceCount: number;
-  readonly sourceKeys: readonly string[];
-  readonly trailIds: readonly string[];
-}
-
-export interface ActivationGraphReport {
-  readonly overview: ActivationOverviewReport;
-  readonly signals: ReadonlyMap<string, SignalActivationRelations>;
-  readonly sources: ReadonlyMap<string, ActivationSourceReport>;
-  readonly trails: ReadonlyMap<string, TrailActivationReport>;
-}
-
-interface MutableSignalRelations {
-  readonly consumers: Set<string>;
-  readonly producers: Set<string>;
-}
-
-interface MutableTrailActivation {
-  readonly activatedBy: Set<string>;
-  readonly activates: Set<string>;
-  readonly chains: ActivationChainReport[];
-  readonly fires: readonly string[];
-  readonly on: readonly string[];
-}
-
-const canonicalLeaf = (value: unknown): unknown => {
-  switch (typeof value) {
-    case 'bigint': {
-      return value.toString();
-    }
-    case 'function': {
-      return `[Function:${value.name || 'anonymous'}]`;
-    }
-    case 'symbol': {
-      return `[Symbol:${value.description ?? ''}]`;
-    }
-    case 'undefined': {
-      return '[Undefined]';
-    }
-    default: {
-      return value;
-    }
-  }
-};
-
-const canonicalize = (value: unknown): unknown => {
-  if (Array.isArray(value)) {
-    return value.map(canonicalize);
-  }
-  if (value instanceof Date) {
-    return value.toISOString();
-  }
-  if (value instanceof RegExp) {
-    return value.toString();
-  }
-  if (value !== null && typeof value === 'object') {
-    const sorted: Record<string, unknown> = {};
-    for (const key of Object.keys(value).toSorted()) {
-      const next = (value as Record<string, unknown>)[key];
-      sorted[key] = next === undefined ? '[Undefined]' : canonicalize(next);
-    }
-    return sorted;
-  }
-  return canonicalLeaf(value);
-};
-
-const sortKeys = <T extends Record<string, unknown>>(value: T): T => {
-  const sorted: Record<string, unknown> = {};
-  for (const key of Object.keys(value).toSorted()) {
-    sorted[key] = value[key];
-  }
-  return sorted as T;
-};
-
-const compareChains = (
-  a: ActivationChainReport,
-  b: ActivationChainReport
-): number =>
-  a.producer.localeCompare(b.producer) ||
-  a.signal.localeCompare(b.signal) ||
-  a.consumer.localeCompare(b.consumer);
-
-const sortedUnique = (values: Iterable<string>): readonly string[] =>
-  [...new Set(values)].toSorted();
-
-const projectActivationSource = (
-  source: ActivationSource
-): ActivationSourceReport =>
-  projectActivationSourceDeclaration(source) as ActivationSourceReport;
-
-const projectActivationEdge = (
-  trailId: string,
-  activation: ActivationEntry
-): ActivationEdgeReport => {
-  const sourceKey = activationSourceKey(activation.source);
-  const edge: Record<string, unknown> = {
-    hasWhere: activation.where !== undefined,
-    sourceId: activation.source.id,
-    sourceKey,
-    sourceKind: activation.source.kind,
-    trailId,
-  };
-
-  if (activation.meta !== undefined) {
-    edge['meta'] = canonicalize(activation.meta);
-  }
-  if (activation.where !== undefined) {
-    edge['where'] = { predicate: true };
-  }
-
-  return sortKeys(edge) as ActivationEdgeReport;
-};
-
-const collectActivationSourceCatalog = (
-  trails: readonly AnyTrail[]
-): readonly ActivationSourceReport[] => {
-  const sources = new Map<string, ActivationSourceReport>();
-  for (const trail of trails) {
-    for (const activation of trail.activationSources) {
-      const projected = projectActivationSource(activation.source);
-      sources.set(projected.key, projected);
-    }
-  }
-  return [...sources.values()].toSorted((a, b) => a.key.localeCompare(b.key));
-};
-
-const collectActivationEdges = (
-  trails: readonly AnyTrail[]
-): readonly ActivationEdgeReport[] => {
-  const edges = new Map<string, ActivationEdgeReport>();
-  for (const trail of trails) {
-    for (const activation of trail.activationSources) {
-      const edge = projectActivationEdge(trail.id, activation);
-      const key = `${edge.sourceKey}\0${edge.trailId}`;
-      const previous = edges.get(key);
-      edges.set(
-        key,
-        previous === undefined || (!previous.hasWhere && edge.hasWhere)
-          ? edge
-          : previous
-      );
-    }
-  }
-
-  return [...edges.values()].toSorted(
-    (a, b) =>
-      a.sourceKey.localeCompare(b.sourceKey) ||
-      a.trailId.localeCompare(b.trailId)
-  );
-};
-
-const getSignalRelations = (
-  relations: Map<string, MutableSignalRelations>,
-  signalId: string
-): MutableSignalRelations => {
-  const existing = relations.get(signalId);
-  if (existing !== undefined) {
-    return existing;
-  }
-
-  const created = {
-    consumers: new Set<string>(),
-    producers: new Set<string>(),
-  };
-  relations.set(signalId, created);
-  return created;
-};
-
-const getTrailActivation = (
-  trails: Map<string, MutableTrailActivation>,
-  trail: AnyTrail
-): MutableTrailActivation => {
-  const existing = trails.get(trail.id);
-  if (existing !== undefined) {
-    return existing;
-  }
-
-  const created = {
-    activatedBy: new Set<string>(),
-    activates: new Set<string>(),
-    chains: [],
-    fires: sortedUnique(trail.fires),
-    on: sortedUnique(trail.on),
-  };
-  trails.set(trail.id, created);
-  return created;
-};
-
-export const deriveDeclaredTrailActivation = (
-  trail: AnyTrail
-): TrailActivationReport => {
-  const sources = collectActivationSourceCatalog([trail]);
-  return {
-    activatedBy: [],
-    activates: [],
-    chains: [],
-    edges: collectActivationEdges([trail]),
-    fires: sortedUnique(trail.fires),
-    on: sortedUnique(trail.on),
-    sources,
-  };
-};
-
-export const deriveSignalActivationRelations = (
-  app: Topo,
-  signalId: string
-): SignalActivationRelations => {
-  const consumers: string[] = [];
-  const producers: string[] = [];
-
-  for (const trail of app.list()) {
-    if (trail.fires.includes(signalId)) {
-      producers.push(trail.id);
-    }
-    if (trail.on.includes(signalId)) {
-      consumers.push(trail.id);
-    }
-  }
-
-  return {
-    consumers: sortedUnique(consumers),
-    producers: sortedUnique(producers),
-  };
-};
-
-export const deriveActivationGraph = (app: Topo): ActivationGraphReport => {
-  const signalRelations = new Map<string, MutableSignalRelations>();
-  const trailActivations = new Map<string, MutableTrailActivation>();
-  const trails = app.list();
-  const sources = collectActivationSourceCatalog(trails);
-  const edges = collectActivationEdges(trails);
-
-  for (const signal of app.listSignals()) {
-    getSignalRelations(signalRelations, signal.id);
-  }
-
-  for (const trail of trails) {
-    const trailActivation = getTrailActivation(trailActivations, trail);
-    for (const signalId of trailActivation.fires) {
-      getSignalRelations(signalRelations, signalId).producers.add(trail.id);
-    }
-    for (const signalId of trailActivation.on) {
-      getSignalRelations(signalRelations, signalId).consumers.add(trail.id);
-    }
-  }
-
-  const chains: ActivationChainReport[] = [];
-  for (const [signal, related] of signalRelations) {
-    for (const producer of related.producers) {
-      const producerActivation = trailActivations.get(producer);
-      for (const consumer of related.consumers) {
-        const chain = { consumer, producer, signal };
-        chains.push(chain);
-        producerActivation?.activates.add(consumer);
-        producerActivation?.chains.push(chain);
-        const consumerActivation = trailActivations.get(consumer);
-        consumerActivation?.activatedBy.add(producer);
-        if (consumerActivation !== producerActivation) {
-          consumerActivation?.chains.push(chain);
-        }
-      }
-    }
-  }
-
-  chains.sort(compareChains);
-  const activeTrailIds = sortedUnique([
-    ...[...trailActivations.entries()].flatMap(([trailId, trail]) =>
-      trail.fires.length > 0 || trail.on.length > 0
-        ? [trailId, ...trail.activatedBy, ...trail.activates]
-        : []
-    ),
-    ...edges.map((edge) => edge.trailId),
-  ]);
-
-  return {
-    overview: {
-      chainCount: chains.length,
-      chains,
-      edgeCount: edges.length,
-      edges,
-      signalIds: [...signalRelations.keys()].toSorted(),
-      sourceCount: sources.length,
-      sourceKeys: sources.map((source) => source.key),
-      trailIds: activeTrailIds,
-    },
-    signals: new Map(
-      [...signalRelations.entries()].map(([id, relations]) => [
-        id,
-        {
-          consumers: sortedUnique(relations.consumers),
-          producers: sortedUnique(relations.producers),
-        },
-      ])
-    ),
-    sources: new Map(sources.map((source) => [source.key, source])),
-    trails: new Map(
-      [...trailActivations.entries()].map(([id, activation]) => [
-        id,
-        {
-          activatedBy: sortedUnique(activation.activatedBy),
-          activates: sortedUnique(activation.activates),
-          chains: activation.chains.toSorted(compareChains),
-          edges: edges.filter((edge) => edge.trailId === id),
-          fires: activation.fires,
-          on: activation.on,
-          sources: sources.filter((source) =>
-            edges.some(
-              (edge) => edge.trailId === id && edge.sourceKey === source.key
-            )
-          ),
-        },
-      ])
-    ),
-  };
-};
+export {
+  deriveActivationGraph,
+  deriveDeclaredTrailActivation,
+  deriveSignalActivationRelations,
+} from '@ontrails/topographer';
+export type {
+  ActivationChainReport,
+  ActivationEdgeReport,
+  ActivationGraphReport,
+  ActivationOverviewReport,
+  ActivationSourceReport,
+  SignalActivationRelations,
+  TrailActivationReport,
+} from '@ontrails/topographer';

package/src/trails/topo-read-support.ts

@@ -144,7 +144,7 @@ const readCommittedLock = async (
 // Public read-only consumers
 // ---------------------------------------------------------------------------
 
-export const buildTopoSummary = (
+export const deriveTopoSummary = (
   app: Topo,
   options?: { readonly rootDir?: string }
 ): TopoSummaryReport => {
@@ -160,17 +160,17 @@ export const buildTopoSummary = (
   };
 };
 
-export const buildCurrentTopoBrief = (
+export const deriveCurrentTopoBrief = (
   app: Topo,
   _options?: { readonly rootDir?: string }
 ): BriefReport => deriveBriefReport(app);
 
-export const buildCurrentTopoList = (
+export const deriveCurrentTopoList = (
   app: Topo,
   _options?: { readonly rootDir?: string }
 ): SurveyListReport => deriveSurveyList(app);
 
-export const buildCurrentGuideEntries = (
+export const deriveCurrentGuideEntries = (
   app: Topo,
   _options?: { readonly rootDir?: string }
 ): readonly {
@@ -189,7 +189,7 @@ export const buildCurrentGuideEntries = (
     }))
     .toSorted((a, b) => a.id.localeCompare(b.id));
 
-export const buildCurrentTrailDetail = (
+export const deriveCurrentTrailDetail = (
   app: Topo,
   id: string,
   options?: CurrentTopoReadOptions
@@ -203,7 +203,7 @@ export const buildCurrentTrailDetail = (
       });
 };
 
-export const buildCurrentResourceDetail = (
+export const deriveCurrentResourceDetail = (
   app: Topo,
   id: string,
   _options?: { readonly rootDir?: string }
@@ -212,22 +212,22 @@ export const buildCurrentResourceDetail = (
     ? undefined
     : (deriveResourceDetail(app, id) as CurrentResourceDetail);
 
-export const buildCurrentSignalDetail = (
+export const deriveCurrentSignalDetail = (
   app: Topo,
   id: string,
   _options?: { readonly rootDir?: string }
 ): SignalDetailReport | undefined => deriveSignalDetail(app, id);
 
-export const buildCurrentTopoDetail = (
+export const deriveCurrentTopoDetail = (
   app: Topo,
   id: string,
   options?: CurrentTopoReadOptions
 ): CurrentTopoDetail | undefined =>
-  buildCurrentTrailDetail(app, id, options) ??
-  buildCurrentResourceDetail(app, id) ??
-  buildCurrentSignalDetail(app, id);
+  deriveCurrentTrailDetail(app, id, options) ??
+  deriveCurrentResourceDetail(app, id) ??
+  deriveCurrentSignalDetail(app, id);
 
-export const buildCurrentTopoMatches = (
+export const deriveCurrentTopoMatches = (
   app: Topo,
   id: string,
   options?: CurrentTopoReadOptions
@@ -251,7 +251,7 @@ export const buildCurrentTopoMatches = (
     });
   }
 
-  const resource = buildCurrentResourceDetail(app, id);
+  const resource = deriveCurrentResourceDetail(app, id);
   if (resource !== undefined) {
     matches.push({ detail: resource, kind: 'resource' });
   }

package/src/trails/topo.ts

@@ -3,7 +3,7 @@ import { z } from 'zod';
 
 import { withFreshOperatorApp } from './operator-context.js';
 import { activationOverviewOutput } from './topo-output-schemas.js';
-import { buildTopoSummary } from './topo-read-support.js';
+import { deriveTopoSummary } from './topo-read-support.js';
 import { createIsolatedExampleInput } from './topo-support.js';
 
 const summaryOutput = z.object({
@@ -74,7 +74,7 @@ const summaryOutput = z.object({
 export const topoTrail = trail('topo', {
   blaze: async (input, ctx) =>
     withFreshOperatorApp(input, ctx, ({ lease, rootDir }) =>
-      Result.ok(buildTopoSummary(lease.app, { rootDir }))
+      Result.ok(deriveTopoSummary(lease.app, { rootDir }))
     ),
   description: 'Show the current topo summary and entry list',
   examples: [

package/src/trails/version-lifecycle-support.ts

@@ -23,7 +23,7 @@ export interface LifecycleCommandInput {
 }
 
 export interface LifecycleWriteResult {
-  readonly file: string;
+  readonly filePath: string;
   readonly trailId: string;
   readonly updated: boolean;
   readonly warnings?: readonly string[] | undefined;
@@ -32,8 +32,8 @@ export interface LifecycleWriteResult {
 interface TrailSourceMatch {
   readonly configEnd: number;
   readonly configStart: number;
-  readonly filePath: string;
   readonly source: string;
+  readonly sourcePath: string;
 }
 
 interface PropertyMatch {
@@ -108,8 +108,8 @@ const findTrailSource = (
       return Result.ok({
         configEnd: match.config.end,
         configStart: match.config.start,
-        filePath,
         source: source.value,
+        sourcePath: filePath,
       });
     }
   }
@@ -566,13 +566,13 @@ export const reviseTrailSource = (
       blaze?.value
     )
   );
-  const written = writeLifecycleSourceFile(match.value.filePath, nextSource);
+  const written = writeLifecycleSourceFile(match.value.sourcePath, nextSource);
   if (written.isErr()) {
     return written;
   }
 
   return Result.ok({
-    file: match.value.filePath,
+    filePath: match.value.sourcePath,
     trailId: trail.id,
     updated: true,
     ...(usesForkPlaceholder
@@ -724,18 +724,18 @@ export const setVersionStatusSource = (
         );
   if (nextSource === match.value.source) {
     return Result.ok({
-      file: match.value.filePath,
+      filePath: match.value.sourcePath,
       trailId: target.trailId,
       updated: false,
     });
   }
-  const written = writeLifecycleSourceFile(match.value.filePath, nextSource);
+  const written = writeLifecycleSourceFile(match.value.sourcePath, nextSource);
   if (written.isErr()) {
     return written;
   }
 
   return Result.ok({
-    file: match.value.filePath,
+    filePath: match.value.sourcePath,
     trailId: target.trailId,
     updated: true,
   });
@@ -768,18 +768,18 @@ export const forkVersionEntrySource = (
   const nextSource = rewrite.source;
   if (nextSource === match.value.source) {
     return Result.ok({
-      file: match.value.filePath,
+      filePath: match.value.sourcePath,
       trailId: target.trailId,
       updated: false,
     });
   }
-  const written = writeLifecycleSourceFile(match.value.filePath, nextSource);
+  const written = writeLifecycleSourceFile(match.value.sourcePath, nextSource);
   if (written.isErr()) {
     return written;
   }
 
   return Result.ok({
-    file: match.value.filePath,
+    filePath: match.value.sourcePath,
     trailId: target.trailId,
     updated: true,
     ...(rewrite.usedPlaceholder

package/src/trails/warden-guide.ts

@@ -37,6 +37,12 @@ const wardenRuleGuideEntrySchema = z.object({
     .object({
       class: z.enum(wardenFixClasses),
       safety: z.enum(wardenFixSafeties),
+      scanTargets: z
+        .object({
+          exclude: z.array(z.string()).readonly().optional(),
+          extensions: z.array(z.string()).readonly().optional(),
+        })
+        .optional(),
     })
     .optional(),
   guidance: wardenGuidanceSchema.optional(),
@@ -54,10 +60,9 @@ const wardenRuleGuideEntrySchema = z.object({
 const wardenGuideManifestSchema = z.object({
   generatedFrom: z.object({
     package: z.literal('@ontrails/warden'),
-    registries: z.tuple([
-      z.literal('wardenRules'),
-      z.literal('wardenTopoRules'),
-    ]),
+    registries: z
+      .tuple([z.literal('wardenRules'), z.literal('wardenTopoRules')])
+      .readonly(),
     source: z.literal('builtin-rule-metadata'),
   }),
   kind: z.literal('trails-warden-guide-manifest'),

package/src/trails/warden.ts

@@ -66,6 +66,10 @@ const wardenInputSchema = z.object({
   prePush: z.boolean().default(false).describe('Use the pre-push preset'),
   refresh: z.boolean().default(false).describe('Alias for --lock refresh'),
   rootDir: z.string().optional().describe('Root directory to scan'),
+  scopeExclude: z
+    .array(z.string())
+    .optional()
+    .describe('Root-relative path globs that Warden should not govern'),
   skipLock: z.boolean().default(false).describe('Alias for --lock skip'),
   strict: z.boolean().default(false).describe('Alias for --fail-on warning'),
   summary: z.boolean().default(false).describe('Alias for --format summary'),
@@ -106,6 +110,16 @@ const pushApps = (
   }
 };
 
+const pushRepeatedValues = (
+  args: string[],
+  flag: string,
+  values: readonly string[] | undefined
+): void => {
+  for (const value of values ?? []) {
+    args.push(flag, value);
+  }
+};
+
 export const buildWardenCommandArgs = (
   input: WardenTrailInput
 ): readonly string[] => {
@@ -150,6 +164,7 @@ export const buildWardenCommandArgs = (
   pushFlag(args, input.fix, '--fix');
   pushFlag(args, input.adapterCheck, '--adapter-check');
   pushValue(args, '--config-path', input.configPath);
+  pushRepeatedValues(args, '--scope-exclude', input.scopeExclude);
   pushApps(args, input.apps);
 
   return args;