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

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @ontrails/core
 
+## 1.0.0-beta.32
+
+### Patch Changes
+
+- 3e5c0fc: Export shared diagnostic base types from core and align governance diagnostic
+  severity vocabulary across adapter checks, permits, and Warden.
+- f3c4fef: Export a shared `escapeRegExp` helper from core and migrate first-party callers off local copies.
+- cb0a9d8: Export shared workspace package discovery helpers from core and migrate first-party discovery callers.
+- 21c6dda: Rename topo and draft report types to `TopoDiagnostic` and `DraftDiagnostic`, with deprecated `TopoIssue` and `DraftFinding` aliases preserved for source compatibility.
+- fe72b84: Fold remaining Regrade and Warden scan-target surfaces onto the shared path-scope vocabulary.
+
+## 1.0.0-beta.31
+
+### Patch Changes
+
+- 4cd5d4e: Add shared glob, path-scope, and trail-id glob contracts for downstream Trails tooling.
+- 38907cc: Adopt the shared trail-id glob engine for surface filtering and Wayfinder entity filters so dotted `*`, `**`, and `?` patterns behave consistently across graph inspection and surface selection.
+
 ## 1.0.0-beta.30
 
 ## 1.0.0-beta.29

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ontrails/core",
-  "version": "1.0.0-beta.30",
+  "version": "1.0.0-beta.32",
   "files": [
     "src/**/*.ts",
     "!src/**/__tests__/**",

package/src/derive.ts

@@ -145,7 +145,7 @@ const propagateDescription = (
   }
 };
 
-/** Step one level of optional/default unwrapping. Returns null if not a wrapper type. */
+/** Step one level of transparent wrapper unwrapping. Returns null if not a wrapper type. */
 const unwrapStep = (
   current: ZodInternals,
   state: {
@@ -155,10 +155,16 @@ const unwrapStep = (
   }
 ): ZodInternals | null => {
   const defType = current._zod.def['type'] as string;
-  if (defType !== 'optional' && defType !== 'default') {
+  if (
+    defType !== 'optional' &&
+    defType !== 'default' &&
+    defType !== 'readonly'
+  ) {
     return null;
   }
-  state.required = false;
+  if (defType !== 'readonly') {
+    state.required = false;
+  }
   if (defType === 'default') {
     state.defaultValue = current._zod.def['defaultValue'];
   }

package/src/diagnostics.ts

@@ -0,0 +1,21 @@
+/**
+ * Shared diagnostic vocabulary for governance-style findings.
+ *
+ * Runtime side-channel records and field-state reports can still define their
+ * own shapes. This base exists for tools that report rule or check failures.
+ */
+
+export type DiagnosticSeverity = 'error' | 'warn';
+
+export interface DiagnosticBase<TCode extends string = string> {
+  readonly code?: TCode | undefined;
+  readonly message: string;
+  readonly severity: DiagnosticSeverity;
+}
+
+export interface RuleDiagnosticBase<
+  TCode extends string = string,
+  TRule extends string = string,
+> extends DiagnosticBase<TCode> {
+  readonly rule: TRule;
+}

package/src/draft.ts

@@ -25,7 +25,7 @@ export interface DraftDependency {
   readonly toId: string;
 }
 
-export interface DraftFinding {
+export interface DraftDiagnostic {
   readonly id: string;
   readonly kind: 'contour' | 'resource' | 'signal' | 'trail' | 'unknown';
   readonly message: string;
@@ -34,11 +34,19 @@ export interface DraftFinding {
   readonly dependsOn?: string | undefined;
 }
 
+/**
+ * @deprecated Use {@link DraftDiagnostic}. Kept as a source-compatible alias
+ * during the v1 vocabulary cutover.
+ */
+export interface DraftFinding extends DraftDiagnostic {
+  readonly id: DraftDiagnostic['id'];
+}
+
 export interface DraftReport {
   readonly contaminatedIds: ReadonlySet<string>;
   readonly declaredDraftIds: ReadonlySet<string>;
   readonly dependencies: readonly DraftDependency[];
-  readonly findings: readonly DraftFinding[];
+  readonly findings: readonly DraftDiagnostic[];
 }
 
 interface DraftReason {
@@ -120,7 +128,7 @@ const nodeKind = (
   trails: ReadonlyMap<string, AnyTrail>,
   signals: ReadonlyMap<string, AnySignal>,
   resources: ReadonlyMap<string, AnyResource>
-): DraftFinding['kind'] => {
+): DraftDiagnostic['kind'] => {
   if (contours.has(id)) {
     return 'contour';
   }
@@ -136,7 +144,7 @@ const nodeKind = (
   return 'unknown';
 };
 
-const displayKind = (kind: DraftFinding['kind']): string =>
+const displayKind = (kind: DraftDiagnostic['kind']): string =>
   kind === 'unknown' ? 'Node' : kind[0]?.toUpperCase() + kind.slice(1);
 
 const draftIdsFromKeys = (keys: Iterable<string>): string[] =>
@@ -152,8 +160,8 @@ const collectDeclaredDraftIds = (topo: Topo): ReadonlySet<string> =>
 
 const findingForDraftId = (
   id: string,
-  kind: DraftFinding['kind']
-): DraftFinding => ({
+  kind: DraftDiagnostic['kind']
+): DraftDiagnostic => ({
   id,
   kind,
   message: `${displayKind(id ? kind : 'unknown')} "${id}" is draft and cannot appear in the established graph.`,
@@ -162,9 +170,9 @@ const findingForDraftId = (
 
 const findingForContamination = (
   id: string,
-  kind: DraftFinding['kind'],
+  kind: DraftDiagnostic['kind'],
   reason: DraftReason
-): DraftFinding => {
+): DraftDiagnostic => {
   const dependencyLabel = isDraftId(reason.dependsOn)
     ? `draft "${reason.dependsOn}"`
     : `draft-contaminated "${reason.dependsOn}"`;
@@ -244,7 +252,7 @@ const contaminationFindingForId = (
   trails: ReadonlyMap<string, AnyTrail>,
   signals: ReadonlyMap<string, AnySignal>,
   resources: ReadonlyMap<string, AnyResource>
-): DraftFinding | undefined => {
+): DraftDiagnostic | undefined => {
   if (declaredDraftIds.has(id)) {
     return undefined;
   }
@@ -269,7 +277,7 @@ const collectFindings = (
   trails: ReadonlyMap<string, AnyTrail>,
   signals: ReadonlyMap<string, AnySignal>,
   resources: ReadonlyMap<string, AnyResource>
-): DraftFinding[] => [
+): DraftDiagnostic[] => [
   ...[...declaredDraftIds]
     .toSorted()
     .map((id) =>

package/src/glob.ts

@@ -0,0 +1,81 @@
+export interface GlobConfig {
+  readonly separator: '/' | '.';
+}
+
+/**
+ * Escape a literal string so it can be embedded safely in a RegExp source.
+ *
+ * @example
+ * ```ts
+ * const pattern = new RegExp(`^${escapeRegExp('@ontrails/core')}$`);
+ * ```
+ */
+export const escapeRegExp = (value: string): string =>
+  value.replaceAll(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+const separatorRegExp = (separator: GlobConfig['separator']): string =>
+  escapeRegExp(separator);
+
+export const globToRegExp = (pattern: string, config: GlobConfig): RegExp => {
+  const separator = separatorRegExp(config.separator);
+  const parts: string[] = ['^'];
+
+  for (let index = 0; index < pattern.length; index += 1) {
+    const char = pattern[index];
+    const next = pattern[index + 1];
+
+    if (char === '*' && next === '*') {
+      if (pattern[index + 2] === config.separator) {
+        parts.push(`(?:.*${separator})?`);
+        index += 2;
+      } else {
+        parts.push('.*');
+        index += 1;
+      }
+      continue;
+    }
+
+    if (char === '*') {
+      parts.push(`[^${separator}]*`);
+      continue;
+    }
+
+    if (char === '?') {
+      parts.push(`[^${separator}]`);
+      continue;
+    }
+
+    parts.push(escapeRegExp(char ?? ''));
+  }
+
+  parts.push('$');
+  return new RegExp(parts.join(''));
+};
+
+export const matchesGlob = (
+  value: string,
+  pattern: string,
+  config: GlobConfig
+): boolean => {
+  if (value === pattern) {
+    return true;
+  }
+
+  const terminalDoubleStar = `${config.separator}**`;
+  if (pattern.endsWith(terminalDoubleStar)) {
+    const parent = pattern.slice(0, -terminalDoubleStar.length);
+    if (value === parent) {
+      return true;
+    }
+  }
+
+  return globToRegExp(pattern, config).test(value);
+};
+
+export const matchesAnyGlob = (
+  value: string,
+  patterns: readonly string[] | undefined,
+  config: GlobConfig
+): boolean =>
+  patterns !== undefined &&
+  patterns.some((pattern) => matchesGlob(value, pattern, config));

package/src/index.ts

@@ -68,6 +68,11 @@ export {
   redactErrorString,
 } from './error-projection.js';
 export type { ErrorDiagnosticsProjection } from './error-projection.js';
+export type {
+  DiagnosticBase,
+  DiagnosticSeverity,
+  RuleDiagnosticBase,
+} from './diagnostics.js';
 
 // Types
 export type {
@@ -112,6 +117,25 @@ export type {
 // Context factory
 export { createTrailContext, passthroughTrace } from './context.js';
 
+// Glob and path scope
+export {
+  escapeRegExp,
+  globToRegExp,
+  matchesAnyGlob,
+  matchesGlob,
+} from './glob.js';
+export type { GlobConfig } from './glob.js';
+export {
+  includedByPathScope,
+  matchesAnyPathGlob,
+  matchesPathGlob,
+  normalizePathScopePath,
+  pathScopeSchema,
+} from './path-scope.js';
+export type { PathGlob, PathScope, ScanTargets } from './path-scope.js';
+export { matchesAnyTrailIdGlob, matchesTrailIdGlob } from './trail-id-glob.js';
+export type { TrailIdGlob } from './trail-id-glob.js';
+
 // Resource
 export {
   createResourceLookup,
@@ -417,13 +441,14 @@ export {
 export type {
   DraftDependency,
   DraftDependencyKind,
+  DraftDiagnostic,
   DraftFinding,
   DraftReport,
 } from './draft.js';
 
 // Topo validation
 export { validateTopo } from './validate-topo.js';
-export type { TopoIssue } from './validate-topo.js';
+export type { TopoDiagnostic, TopoIssue } from './validate-topo.js';
 export { validateEstablishedTopo } from './validate-established-topo.js';
 
 // Layer
@@ -581,10 +606,15 @@ export { securePath, isPathSafe, deriveSafePath } from './path-security.js';
 
 // Workspace
 export {
+  deriveRelativePath,
+  findWorkspacePackage,
   findWorkspaceRoot,
   isInsideWorkspace,
-  deriveRelativePath,
+  listWorkspacePackageDirs,
+  listWorkspacePackages,
+  listWorkspacePatterns,
 } from './workspace.js';
+export type { WorkspacePackage, WorkspaceRootManifest } from './workspace.js';
 
 // Blob
 export {

package/src/path-scope.ts

@@ -0,0 +1,66 @@
+import { z } from 'zod';
+
+import { matchesAnyGlob, matchesGlob } from './glob.js';
+
+declare const pathGlobBrand: unique symbol;
+
+export type PathGlob = string & {
+  readonly [pathGlobBrand]: 'PathGlob';
+};
+
+export const normalizePathScopePath = (value: string): string =>
+  value.replaceAll('\\', '/').replace(/^\.\//, '');
+
+export const matchesPathGlob = (path: string, pattern: string): boolean =>
+  matchesGlob(normalizePathScopePath(path), normalizePathScopePath(pattern), {
+    separator: '/',
+  });
+
+export const matchesAnyPathGlob = (
+  path: string,
+  patterns: readonly string[] | undefined
+): boolean =>
+  matchesAnyGlob(
+    normalizePathScopePath(path),
+    patterns?.map(normalizePathScopePath),
+    { separator: '/' }
+  );
+
+const pathGlobArraySchema = z.array(z.string()).readonly();
+
+export const pathScopeSchema = z
+  .object({
+    exclude: pathGlobArraySchema.optional(),
+    extensions: z.array(z.string()).readonly().optional(),
+    include: pathGlobArraySchema.optional(),
+  })
+  .strict();
+
+export type PathScope = z.output<typeof pathScopeSchema>;
+
+export type ScanTargets = Pick<PathScope, 'exclude' | 'extensions'>;
+
+const extensionOf = (path: string): string => {
+  const normalized = normalizePathScopePath(path);
+  const name = normalized.slice(normalized.lastIndexOf('/') + 1);
+  const dot = name.lastIndexOf('.');
+  return dot <= 0 ? '' : name.slice(dot);
+};
+
+const normalizeExtension = (extension: string): string =>
+  extension === '' || extension.startsWith('.') ? extension : `.${extension}`;
+
+const includedByExtension = (
+  path: string,
+  extensions: readonly string[] | undefined
+): boolean =>
+  extensions === undefined ||
+  extensions.length === 0 ||
+  extensions.map(normalizeExtension).includes(extensionOf(path));
+
+export const includedByPathScope = (path: string, scope?: PathScope): boolean =>
+  (scope?.include === undefined ||
+    scope.include.length === 0 ||
+    matchesAnyPathGlob(path, scope.include)) &&
+  !matchesAnyPathGlob(path, scope?.exclude) &&
+  includedByExtension(path, scope?.extensions);

package/src/surface-filter.ts

@@ -1,4 +1,5 @@
 import type { Intent, Trail } from './trail.js';
+import { matchesAnyTrailIdGlob, matchesTrailIdGlob } from './trail-id-glob.js';
 import type { SurfaceSelectionOptions } from './surface-derivation.js';
 
 // ---------------------------------------------------------------------------
@@ -7,84 +8,10 @@ import type { SurfaceSelectionOptions } from './surface-derivation.js';
 
 export type SurfaceFilterOptions = SurfaceSelectionOptions;
 
-// ---------------------------------------------------------------------------
-// Glob matching
-// ---------------------------------------------------------------------------
-
-const trailIdSegments = (trailId: string): readonly string[] =>
-  trailId.split('.');
-
-const patternSegments = (pattern: string): readonly string[] =>
-  pattern.split('.');
-
-type SegmentMatcher = (
-  trail: readonly string[],
-  pattern: readonly string[],
-  trailIndex: number,
-  patternIndex: number
-) => boolean;
-
-const matchesDoubleStar = (
-  trail: readonly string[],
-  pattern: readonly string[],
-  trailIndex: number,
-  patternIndex: number,
-  matchSegments: SegmentMatcher
-): boolean =>
-  patternIndex === pattern.length - 1 ||
-  Array.from(
-    { length: trail.length - trailIndex + 1 },
-    (_, offset) => trailIndex + offset
-  ).some((index) => matchSegments(trail, pattern, index, patternIndex + 1));
-
-const matchesSingleSegment = (
-  trail: readonly string[],
-  pattern: readonly string[],
-  trailIndex: number,
-  patternIndex: number,
-  current: string,
-  matchSegments: SegmentMatcher
-): boolean =>
-  trailIndex < trail.length &&
-  (current === '*' || current === trail[trailIndex]) &&
-  matchSegments(trail, pattern, trailIndex + 1, patternIndex + 1);
-
-const matchesFrom = function matchesFrom(
-  trail: readonly string[],
-  pattern: readonly string[],
-  trailIndex: number,
-  patternIndex: number
-): boolean {
-  if (patternIndex >= pattern.length) {
-    return trailIndex >= trail.length;
-  }
-
-  const current = pattern[patternIndex];
-  if (current === undefined) {
-    return false;
-  }
-
-  return current === '**'
-    ? matchesDoubleStar(trail, pattern, trailIndex, patternIndex, matchesFrom)
-    : matchesSingleSegment(
-        trail,
-        pattern,
-        trailIndex,
-        patternIndex,
-        current,
-        matchesFrom
-      );
-};
-
 export const matchesTrailPattern = (
   trailId: string,
   pattern: string
-): boolean => {
-  if (pattern === trailId) {
-    return true;
-  }
-  return matchesFrom(trailIdSegments(trailId), patternSegments(pattern), 0, 0);
-};
+): boolean => matchesTrailIdGlob(trailId, pattern);
 
 // ---------------------------------------------------------------------------
 // Surface filtering
@@ -93,9 +20,7 @@ export const matchesTrailPattern = (
 const matchesAnyPattern = (
   trailId: string,
   patterns: readonly string[] | undefined
-): boolean =>
-  patterns !== undefined &&
-  patterns.some((pattern) => matchesTrailPattern(trailId, pattern));
+): boolean => matchesAnyTrailIdGlob(trailId, patterns);
 
 const isExplicitInternalInclude = (
   trailId: string,

package/src/trail-id-glob.ts

@@ -0,0 +1,15 @@
+import { matchesAnyGlob, matchesGlob } from './glob.js';
+
+declare const trailIdGlobBrand: unique symbol;
+
+export type TrailIdGlob = string & {
+  readonly [trailIdGlobBrand]: 'TrailIdGlob';
+};
+
+export const matchesTrailIdGlob = (id: string, pattern: string): boolean =>
+  matchesGlob(id, pattern, { separator: '.' });
+
+export const matchesAnyTrailIdGlob = (
+  id: string,
+  patterns: readonly string[] | undefined
+): boolean => matchesAnyGlob(id, patterns, { separator: '.' });

package/src/validate-established-topo.ts

@@ -2,7 +2,7 @@ import { ValidationError } from './errors.js';
 import { Result } from './result.js';
 import type { Topo } from './topo.js';
 import { validateDraftFreeTopo } from './draft.js';
-import type { TopoIssue } from './validate-topo.js';
+import type { TopoDiagnostic } from './validate-topo.js';
 import { validateTopo } from './validate-topo.js';
 
 const PROJECTION_BLOCKING_RULES = new Set([
@@ -27,7 +27,7 @@ const keepProjectionBlockingIssues = (
   }
 
   const issues = (
-    result.error.context as { issues?: readonly TopoIssue[] } | undefined
+    result.error.context as { issues?: readonly TopoDiagnostic[] } | undefined
   )?.issues;
   const remainingIssues = issues?.filter((issue) =>
     PROJECTION_BLOCKING_RULES.has(issue.rule)

package/src/validate-topo.ts

@@ -34,7 +34,7 @@ import { validateWebhookSource } from './webhook.js';
 // Issue shape
 // ---------------------------------------------------------------------------
 
-export interface TopoIssue {
+export interface TopoDiagnostic {
   readonly trailId: string;
   readonly rule: string;
   readonly message: string;
@@ -44,6 +44,14 @@ export interface TopoIssue {
   readonly sourceKind?: string;
 }
 
+/**
+ * @deprecated Use {@link TopoDiagnostic}. Kept as a source-compatible alias
+ * during the v1 vocabulary cutover.
+ */
+export interface TopoIssue extends TopoDiagnostic {
+  readonly trailId: TopoDiagnostic['trailId'];
+}
+
 export type TopoSchemaIssue = ActivationSchemaIssue;
 
 // ---------------------------------------------------------------------------
@@ -92,8 +100,8 @@ const buildComposeGraph = (
 /** Detect multi-node cycles in the trail composing graph via DFS. */
 const detectComposeCycles = (
   trails: ReadonlyMap<string, AnyTrail>
-): TopoIssue[] => {
-  const issues: TopoIssue[] = [];
+): TopoDiagnostic[] => {
+  const issues: TopoDiagnostic[] = [];
   const { color, graph } = buildComposeGraph(trails);
 
   const dfs = (node: string, path: string[]): void => {
@@ -128,8 +136,8 @@ const detectComposeCycles = (
 const checkComposes = (
   trails: ReadonlyMap<string, AnyTrail>,
   topo: Topo
-): TopoIssue[] => {
-  const issues: TopoIssue[] = [];
+): TopoDiagnostic[] => {
+  const issues: TopoDiagnostic[] = [];
   for (const [id, trail] of trails) {
     for (const composedId of trail.composes) {
       if (composedId === id) {
@@ -182,8 +190,8 @@ const checkComposes = (
 const checkResources = (
   trails: ReadonlyMap<string, AnyTrail>,
   topo: Topo
-): TopoIssue[] => {
-  const issues: TopoIssue[] = [];
+): TopoDiagnostic[] => {
+  const issues: TopoDiagnostic[] = [];
 
   for (const [id, trail] of trails) {
     for (const declaredResource of trail.resources) {
@@ -237,8 +245,8 @@ const checkOneExample = (
   inputSchema: { safeParse: (data: unknown) => { success: boolean } },
   hasOutput: boolean,
   label = `Example "${example.name}"`
-): TopoIssue[] => {
-  const issues: TopoIssue[] = [];
+): TopoDiagnostic[] => {
+  const issues: TopoDiagnostic[] = [];
   const result = validateInput(inputSchema as AnyTrail['input'], example.input);
   if (result.isErr() && example.error !== 'ValidationError') {
     issues.push({
@@ -257,7 +265,7 @@ const checkOneExample = (
   return issues;
 };
 
-const checkVersionExamples = (id: string, trail: AnyTrail): TopoIssue[] =>
+const checkVersionExamples = (id: string, trail: AnyTrail): TopoDiagnostic[] =>
   Object.entries(trail.versions ?? {}).flatMap(([version, entry]) => {
     if (isArchivedTrailVersionEntry(entry)) {
       return [];
@@ -274,8 +282,10 @@ const checkVersionExamples = (id: string, trail: AnyTrail): TopoIssue[] =>
     );
   });
 
-const checkExamples = (trails: ReadonlyMap<string, AnyTrail>): TopoIssue[] => {
-  const issues: TopoIssue[] = [];
+const checkExamples = (
+  trails: ReadonlyMap<string, AnyTrail>
+): TopoDiagnostic[] => {
+  const issues: TopoDiagnostic[] = [];
   for (const [id, trail] of trails) {
     if (trail.examples) {
       for (const example of trail.examples) {
@@ -292,8 +302,8 @@ const checkExamples = (trails: ReadonlyMap<string, AnyTrail>): TopoIssue[] => {
 const checkSignalOrigins = (
   signals: ReadonlyMap<string, AnySignal>,
   topo: Topo
-): TopoIssue[] => {
-  const issues: TopoIssue[] = [];
+): TopoDiagnostic[] => {
+  const issues: TopoDiagnostic[] = [];
   for (const [id, evt] of signals) {
     if (!evt.from) {
       continue;
@@ -314,8 +324,8 @@ const checkSignalOrigins = (
 const checkSignalReferences = (
   trails: ReadonlyMap<string, AnyTrail>,
   signals: ReadonlyMap<string, AnySignal>
-): TopoIssue[] => {
-  const issues: TopoIssue[] = [];
+): TopoDiagnostic[] => {
+  const issues: TopoDiagnostic[] = [];
 
   for (const [id, trail] of trails) {
     for (const signalId of trail.fires ?? []) {
@@ -344,8 +354,8 @@ const checkSignalReferences = (
 
 const checkActivationSources = (
   trails: ReadonlyMap<string, AnyTrail>
-): TopoIssue[] => {
-  const issues: TopoIssue[] = [];
+): TopoDiagnostic[] => {
+  const issues: TopoDiagnostic[] = [];
   const sourceDeclarations = new Map<
     string,
     {
@@ -440,7 +450,7 @@ const createSourceCompatibilityIssue = (
   trailId: string,
   activation: ActivationEntry,
   schemaIssues: readonly TopoSchemaIssue[]
-): TopoIssue => {
+): TopoDiagnostic => {
   const [firstIssue] = schemaIssues;
   const inputPath = firstIssue?.path ?? Object.freeze([]);
   return {
@@ -458,7 +468,7 @@ const checkSourcePayloadCompatibility = (
   trail: AnyTrail,
   activation: ActivationEntry,
   signals: ReadonlyMap<string, AnySignal>
-): TopoIssue | undefined => {
+): TopoDiagnostic | undefined => {
   if (
     !isKnownActivationSourceKind(activation.source.kind) ||
     isDraftId(activation.source.id)
@@ -483,8 +493,8 @@ const checkSourcePayloadCompatibility = (
 const checkActivationSourceInputCompatibility = (
   trails: ReadonlyMap<string, AnyTrail>,
   signals: ReadonlyMap<string, AnySignal>
-): TopoIssue[] => {
-  const issues: TopoIssue[] = [];
+): TopoDiagnostic[] => {
+  const issues: TopoDiagnostic[] = [];
 
   for (const trail of trails.values()) {
     for (const activation of trail.activationSources ?? []) {
@@ -501,8 +511,8 @@ const checkActivationSourceInputCompatibility = (
 const checkContourReferences = (
   contours: ReadonlyMap<string, AnyContour>,
   topo: Topo
-): TopoIssue[] => {
-  const issues: TopoIssue[] = [];
+): TopoDiagnostic[] => {
+  const issues: TopoDiagnostic[] = [];
 
   for (const [name, contourDef] of contours) {
     for (const ref of getContourReferences(contourDef)) {

package/src/workspace.ts

@@ -5,11 +5,46 @@
  * helpers for working with paths relative to a workspace.
  */
 
+import { existsSync, readFileSync, readdirSync, realpathSync } from 'node:fs';
 import { resolve, relative, dirname, join, isAbsolute } from 'node:path';
 
 import { NotFoundError } from './errors.js';
 import { Result } from './result.js';
 
+export interface WorkspaceRootManifest {
+  readonly workspaces?: unknown;
+}
+
+export interface WorkspacePackage<
+  Manifest extends object = Record<string, unknown>,
+> {
+  readonly manifest: Manifest;
+  readonly packageJsonPath: string;
+  readonly packageRoot: string;
+  readonly workspacePath: string;
+}
+
+const isRecord = (value: unknown): value is Readonly<Record<string, unknown>> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+const normalizePath = (path: string): string => path.replaceAll('\\', '/');
+
+const normalizeRealPath = (path: string): string => {
+  try {
+    return normalizePath(realpathSync(path));
+  } catch {
+    return normalizePath(resolve(path));
+  }
+};
+
+const readJsonSync = <T>(path: string): T | undefined => {
+  try {
+    return JSON.parse(readFileSync(path, 'utf8')) as T;
+  } catch {
+    return undefined;
+  }
+};
+
 /** Check if a directory has a package.json with a `workspaces` field. */
 const hasWorkspacesField = async (dir: string): Promise<boolean> => {
   const pkgPath = join(dir, 'package.json');
@@ -25,6 +60,132 @@ const hasWorkspacesField = async (dir: string): Promise<boolean> => {
   }
 };
 
+/**
+ * List workspace patterns from a root package manifest.
+ *
+ * Supports npm/Bun's array form and Yarn-style `{ packages: [] }` form.
+ *
+ * @example
+ * ```ts
+ * listWorkspacePatterns({ workspaces: ['packages/*'] });
+ * ```
+ */
+export const listWorkspacePatterns = (
+  manifest: WorkspaceRootManifest | undefined
+): readonly string[] => {
+  const { workspaces } = manifest ?? {};
+  if (Array.isArray(workspaces)) {
+    return workspaces.filter(
+      (pattern): pattern is string => typeof pattern === 'string'
+    );
+  }
+
+  const packages = isRecord(workspaces) ? workspaces['packages'] : undefined;
+  return Array.isArray(packages)
+    ? packages.filter(
+        (pattern): pattern is string => typeof pattern === 'string'
+      )
+    : [];
+};
+
+const workspaceDirsForPattern = (
+  rootDir: string,
+  pattern: string
+): readonly string[] => {
+  if (!pattern.endsWith('/*')) {
+    const workspaceDir = join(rootDir, pattern);
+    return existsSync(join(workspaceDir, 'package.json')) ? [workspaceDir] : [];
+  }
+
+  const groupDir = join(rootDir, pattern.slice(0, -2));
+  if (!existsSync(groupDir)) {
+    return [];
+  }
+
+  return readdirSync(groupDir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => join(groupDir, entry.name))
+    .filter((workspaceDir) => existsSync(join(workspaceDir, 'package.json')))
+    .toSorted();
+};
+
+/**
+ * List package directories matched by workspace patterns.
+ *
+ * Only directories containing `package.json` are returned.
+ *
+ * @example
+ * ```ts
+ * listWorkspacePackageDirs('/repo', ['packages/*']);
+ * ```
+ */
+export const listWorkspacePackageDirs = (
+  rootDir: string,
+  patterns: readonly string[]
+): readonly string[] =>
+  patterns.flatMap((pattern) => workspaceDirsForPattern(rootDir, pattern));
+
+/**
+ * List workspace package manifests from a workspace root.
+ *
+ * @example
+ * ```ts
+ * const packages = listWorkspacePackages('/repo');
+ * ```
+ */
+export const listWorkspacePackages = <
+  Manifest extends { readonly name?: unknown } = { readonly name?: unknown },
+>(
+  rootDir: string
+): readonly WorkspacePackage<Manifest>[] => {
+  const normalizedRoot = normalizeRealPath(rootDir);
+  const rootManifest = readJsonSync<WorkspaceRootManifest>(
+    join(normalizedRoot, 'package.json')
+  );
+  const packages: WorkspacePackage<Manifest>[] = [];
+
+  for (const workspaceDir of listWorkspacePackageDirs(
+    normalizedRoot,
+    listWorkspacePatterns(rootManifest)
+  )) {
+    const packageJsonPath = join(workspaceDir, 'package.json');
+    const manifest = readJsonSync<Manifest>(packageJsonPath);
+    if (!manifest || typeof manifest.name !== 'string') {
+      continue;
+    }
+
+    const packageRoot = normalizeRealPath(dirname(packageJsonPath));
+    packages.push({
+      manifest,
+      packageJsonPath: normalizeRealPath(packageJsonPath),
+      packageRoot,
+      workspacePath: normalizePath(relative(normalizedRoot, packageRoot)),
+    });
+  }
+
+  return packages.toSorted((left, right) =>
+    left.workspacePath.localeCompare(right.workspacePath)
+  );
+};
+
+/**
+ * Find a workspace package by its package name.
+ *
+ * @example
+ * ```ts
+ * const workspace = findWorkspacePackage('/repo', '@ontrails/core');
+ * ```
+ */
+export const findWorkspacePackage = <
+  Manifest extends { readonly name?: unknown } = { readonly name?: unknown },
+>(
+  rootDir: string,
+  packageName: string
+): WorkspacePackage<Manifest> | undefined =>
+  listWorkspacePackages<Manifest>(rootDir).find(
+    (workspacePackage) => workspacePackage.manifest.name === packageName
+  );
+
 /**
  * Walks up from `startDir` (defaults to `process.cwd()`) looking for a
  * `package.json` that contains a `"workspaces"` field.