@ontrails/core 1.0.0-beta.13 → 1.0.0-beta.15

package/src/store/accessor-protocol.ts

@@ -0,0 +1,56 @@
+/**
+ * Structural accessor protocol used by `deriveTrail()` to synthesize default
+ * blazes for standard CRUD operations without depending on `@ontrails/store`.
+ *
+ * @remarks
+ * This type is intentionally minimal and structural. `@ontrails/store`'s
+ * `StoreAccessor` / `StoreTableAccessor` interfaces satisfy this protocol
+ * through a compile-time extends check (see `packages/store/src/types.ts`).
+ * Keeping the protocol in core avoids a core → store dependency while still
+ * allowing the derivation helper to call accessors by convention.
+ *
+ * Required methods (`get`, `list`, `upsert`, `remove`) match the
+ * connector-agnostic write contract every bound store must expose. Optional
+ * methods (`insert`, `update`) are declared by tabular connectors that
+ * distinguish create-only and patch-only operations from the generalized
+ * `upsert` contract.
+ */
+export interface StoreAccessorProtocol<
+  TInput,
+  TEntity,
+  TId,
+  TFilters = unknown,
+> {
+  /** Retrieve a single entity by identity. Returns `null` when not found. */
+  get(id: TId): Promise<TEntity | null>;
+  /** List entities, optionally filtered. Returns `[]` when no rows match. */
+  list(filters?: TFilters): Promise<readonly TEntity[]>;
+  /** Create-or-replace one entity using the connector-agnostic contract. */
+  upsert(input: TInput): Promise<TEntity>;
+  /**
+   * Remove an entity by identity. Returns `{ deleted: true }` when the row
+   * was found and removed, `{ deleted: false }` when no matching row
+   * existed (not an error).
+   */
+  remove(id: TId): Promise<{ readonly deleted: boolean }>;
+  /**
+   * Optional insert — available on tabular connectors that distinguish
+   * create from update. When absent, synthesized blazes fall back to
+   * `upsert`.
+   */
+  insert?(input: TInput): Promise<TEntity>;
+  /**
+   * Optional patch-by-identity — available on tabular connectors. Returns
+   * `null` when no row with the given identity exists. When absent,
+   * synthesized update blazes fall back to `get` + merge + `upsert`.
+   */
+  update?(id: TId, patch: Partial<TInput>): Promise<TEntity | null>;
+}
+
+/**
+ * Record shape returned by a resource's `from(ctx)` call, keyed by accessor
+ * name. Used by `deriveTrail()` to resolve an accessor by contour name.
+ */
+export type StoreAccessorRecord = Readonly<
+  Record<string, StoreAccessorProtocol<unknown, unknown, unknown, unknown>>
+>;

package/src/store/index.ts

@@ -0,0 +1,4 @@
+export type {
+  StoreAccessorProtocol,
+  StoreAccessorRecord,
+} from './accessor-protocol.js';

package/src/surface-filter.ts

@@ -0,0 +1,182 @@
+import type { Intent, Trail } from './trail.js';
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+export interface SurfaceFilterOptions {
+  /** Glob patterns that keep only matching trail IDs when provided. */
+  readonly include?: readonly string[] | undefined;
+  /** Glob patterns that remove matching trail IDs. */
+  readonly exclude?: readonly string[] | undefined;
+  /** Allowed intents for exposed trailheads. Empty arrays act as no filter. */
+  readonly intent?: readonly Intent[] | undefined;
+}
+
+// ---------------------------------------------------------------------------
+// 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);
+};
+
+// ---------------------------------------------------------------------------
+// Trailhead filtering
+// ---------------------------------------------------------------------------
+
+const matchesAnyPattern = (
+  trailId: string,
+  patterns: readonly string[] | undefined
+): boolean =>
+  patterns !== undefined &&
+  patterns.some((pattern) => matchesTrailPattern(trailId, pattern));
+
+const isExplicitInternalInclude = (
+  trailId: string,
+  include: readonly string[] | undefined
+): boolean => include !== undefined && include.includes(trailId);
+
+/**
+ * Resolve the effective visibility for a trail.
+ *
+ * Returns `'internal'` when either the explicit `visibility` field is
+ * `'internal'` or the legacy `meta.internal === true` convention is set.
+ * Honoring the legacy flag keeps trails authored before the visibility
+ * field was introduced (e.g. `meta: { internal: true }`) off trailheads.
+ *
+ * The runtime always fills in `visibility: 'public'` when the spec did not
+ * declare it, so we cannot distinguish explicit `'public'` from the default.
+ * This means a trail that sets both `meta.internal = true` and
+ * `visibility: 'public'` will still be treated as internal — that
+ * combination has never been a documented override and, if the author
+ * really means "public", they should remove the legacy flag.
+ */
+const effectiveVisibility = (
+  trail: Trail<unknown, unknown, unknown>
+): 'public' | 'internal' => {
+  if (trail.visibility === 'internal') {
+    return 'internal';
+  }
+  return trail.meta?.['internal'] === true ? 'internal' : 'public';
+};
+
+const isVisibleToTrailheads = (
+  trail: Trail<unknown, unknown, unknown>,
+  include: readonly string[] | undefined
+): boolean =>
+  effectiveVisibility(trail) !== 'internal' ||
+  isExplicitInternalInclude(trail.id, include);
+
+const passesIncludeFilter = (
+  trailId: string,
+  include: readonly string[] | undefined
+): boolean =>
+  include === undefined ||
+  include.length === 0 ||
+  matchesAnyPattern(trailId, include);
+
+const passesIntentFilter = (
+  trail: Trail<unknown, unknown, unknown>,
+  intent: readonly Intent[] | undefined
+): boolean =>
+  intent === undefined || intent.length === 0 || intent.includes(trail.intent);
+
+export const shouldIncludeTrailForSurface = (
+  trail: Trail<unknown, unknown, unknown>,
+  options: SurfaceFilterOptions = {}
+): boolean => {
+  if (trail.on.length > 0) {
+    return false;
+  }
+
+  const { exclude, include, intent } = options;
+  if (!isVisibleToTrailheads(trail, include)) {
+    return false;
+  }
+
+  if (matchesAnyPattern(trail.id, exclude)) {
+    return false;
+  }
+
+  return (
+    passesIncludeFilter(trail.id, include) && passesIntentFilter(trail, intent)
+  );
+};
+
+export const filterSurfaceTrails = (
+  trails: readonly Trail<unknown, unknown, unknown>[],
+  options: SurfaceFilterOptions = {}
+): Trail<unknown, unknown, unknown>[] =>
+  trails.filter((trail) => shouldIncludeTrailForSurface(trail, options));