@ontrails/warden 1.0.0-beta.19 → 1.0.0-beta.21

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # @ontrails/warden
 
+## 1.0.0-beta.21
+
+### Minor Changes
+
+- 5be032c: Add the repo-local `public-export-example-coverage` Warden rule (and its `publicExportExampleCoverageTrail` wrapper), graduating `scripts/check-public-api-examples.ts` into governed rule coverage. The rule anchors to this repository's five public surface package barrels via the rule module's own on-disk location, so it stays silent in consumer repositories.
+
+### Patch Changes
+
+- Updated dependencies [99523f2]
+- Updated dependencies [3caa263]
+  - @ontrails/core@1.0.0-beta.21
+  - @ontrails/permits@1.0.0-beta.21
+  - @ontrails/topographer@1.0.0-beta.21
+  - @ontrails/adapter-kit@1.0.0-beta.21
+  - @ontrails/cli@1.0.0-beta.21
+  - @ontrails/store@1.0.0-beta.21
+
+## 1.0.0-beta.20
+
+### Minor Changes
+
+- 8bc0708: Add surface facet coherence diagnostics for selector overlap, visibility widening acknowledgements, dynamic selectors, and description hygiene.
+
+### Patch Changes
+
+- 851a2a3: Derive trail caller and blaze input types from the authored input schema while keeping one public input contract.
+- 6901776: Add a Warden rule and safe-fix metadata for rewriting retired cross vocabulary to compose vocabulary.
+- Updated dependencies [851a2a3]
+- Updated dependencies [eee1307]
+- Updated dependencies [b248d4a]
+  - @ontrails/core@1.0.0-beta.20
+  - @ontrails/store@1.0.0-beta.20
+  - @ontrails/topographer@1.0.0-beta.20
+  - @ontrails/adapter-kit@1.0.0-beta.20
+  - @ontrails/cli@1.0.0-beta.20
+  - @ontrails/permits@1.0.0-beta.20
+
 ## 1.0.0-beta.19
 
 ### Major Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ontrails/warden",
-  "version": "1.0.0-beta.19",
+  "version": "1.0.0-beta.21",
   "bin": {
     "warden": "./bin/warden.ts"
   },
@@ -28,20 +28,20 @@
     "clean": "rm -rf dist *.tsbuildinfo"
   },
   "dependencies": {
-    "@ontrails/adapter-kit": "^1.0.0-beta.19",
-    "@ontrails/cli": "^1.0.0-beta.19",
-    "@ontrails/permits": "^1.0.0-beta.19",
-    "@ontrails/store": "^1.0.0-beta.19",
+    "@ontrails/adapter-kit": "^1.0.0-beta.21",
+    "@ontrails/cli": "^1.0.0-beta.21",
+    "@ontrails/permits": "^1.0.0-beta.21",
+    "@ontrails/store": "^1.0.0-beta.21",
     "oxc-parser": "^0.121.0",
     "oxc-resolver": "11.19.1",
     "zod": "^4.3.5"
   },
   "devDependencies": {
-    "@ontrails/config": "^1.0.0-beta.19",
-    "@ontrails/testing": "^1.0.0-beta.19"
+    "@ontrails/config": "^1.0.0-beta.21",
+    "@ontrails/testing": "^1.0.0-beta.21"
   },
   "peerDependencies": {
-    "@ontrails/core": "^1.0.0-beta.19",
-    "@ontrails/topographer": "^1.0.0-beta.19"
+    "@ontrails/core": "^1.0.0-beta.21",
+    "@ontrails/topographer": "^1.0.0-beta.21"
   }
 }

package/src/index.ts

@@ -188,6 +188,7 @@ export {
   noLegacyLayerImportsTrail,
   noNativeErrorResultTrail,
   noRedundantResultErrorWrapTrail,
+  noRetiredCrossVocabularyTrail,
   noSyncResultAssumptionTrail,
   noThrowInDetourRecoverTrail,
   noThrowInImplementationTrail,
@@ -199,6 +200,7 @@ export {
   permitGovernanceTrail,
   preferSchemaInferenceTrail,
   projectAwareRuleInput,
+  publicExportExampleCoverageTrail,
   publicInternalDeepImportsTrail,
   publicOutputSchemaTrail,
   publicUnionOutputDiscriminantsTrail,
@@ -214,6 +216,7 @@ export {
   scheduledDestroyIntentTrail,
   signalGraphCoachingTrail,
   staticResourceAccessorPreferenceTrail,
+  surfaceFacetCoherenceTrail,
   unmaterializedActivationSourceTrail,
   topoAwareRuleInput,
   unreachableDetourShadowingTrail,

package/src/rules/index.ts

@@ -22,6 +22,7 @@ import { noLegacyLayerImports } from './no-legacy-layer-imports.js';
 import { noDirectImplementationCall } from './no-direct-implementation-call.js';
 import { noNativeErrorResult } from './no-native-error-result.js';
 import { noRedundantResultErrorWrap } from './no-redundant-result-error-wrap.js';
+import { noRetiredCrossVocabulary } from './no-retired-cross-vocabulary.js';
 import { noSyncResultAssumption } from './no-sync-result-assumption.js';
 import { noThrowInDetourRecover } from './no-throw-in-detour-recover.js';
 import { noThrowInImplementation } from './no-throw-in-implementation.js';
@@ -31,6 +32,7 @@ import { orphanedSignal } from './orphaned-signal.js';
 import { ownerProjectionParity } from './owner-projection-parity.js';
 import { permitGovernance } from './permit-governance.js';
 import { preferSchemaInference } from './prefer-schema-inference.js';
+import { publicExportExampleCoverage } from './public-export-example-coverage.js';
 import { publicInternalDeepImports } from './public-internal-deep-imports.js';
 import { publicOutputSchema } from './public-output-schema.js';
 import { publicUnionOutputDiscriminants } from './public-union-output-discriminants.js';
@@ -44,6 +46,7 @@ import { resourceMockCoverage } from './resource-mock-coverage.js';
 import { scheduledDestroyIntent } from './scheduled-destroy-intent.js';
 import { signalGraphCoaching } from './signal-graph-coaching.js';
 import { staticResourceAccessorPreference } from './static-resource-accessor-preference.js';
+import { surfaceFacetCoherence } from './surface-facet-coherence.js';
 import {
   forkWithoutPreservedBlaze,
   markerSchemaUnsupported,
@@ -124,6 +127,7 @@ export { noLegacyLayerImports } from './no-legacy-layer-imports.js';
 export { noDirectImplementationCall } from './no-direct-implementation-call.js';
 export { noNativeErrorResult } from './no-native-error-result.js';
 export { noRedundantResultErrorWrap } from './no-redundant-result-error-wrap.js';
+export { noRetiredCrossVocabulary } from './no-retired-cross-vocabulary.js';
 export { noSyncResultAssumption } from './no-sync-result-assumption.js';
 export { implementationReturnsResult } from './implementation-returns-result.js';
 export { noThrowInDetourRecover } from './no-throw-in-detour-recover.js';
@@ -145,6 +149,7 @@ export { resourceMockCoverage } from './resource-mock-coverage.js';
 export { scheduledDestroyIntent } from './scheduled-destroy-intent.js';
 export { signalGraphCoaching } from './signal-graph-coaching.js';
 export { staticResourceAccessorPreference } from './static-resource-accessor-preference.js';
+export { surfaceFacetCoherence } from './surface-facet-coherence.js';
 export {
   forkWithoutPreservedBlaze,
   markerSchemaUnsupported,
@@ -186,6 +191,7 @@ export const wardenRules: ReadonlyMap<string, WardenRule> = new Map<
   [onReferencesExist.name, onReferencesExist],
   [orphanedSignal.name, orphanedSignal],
   [ownerProjectionParity.name, ownerProjectionParity],
+  [publicExportExampleCoverage.name, publicExportExampleCoverage],
   [publicInternalDeepImports.name, publicInternalDeepImports],
   [resourceDeclarations.name, resourceDeclarations],
   [readIntentFires.name, readIntentFires],
@@ -196,6 +202,7 @@ export const wardenRules: ReadonlyMap<string, WardenRule> = new Map<
   [resourceMockCoverage.name, resourceMockCoverage],
   [preferSchemaInference.name, preferSchemaInference],
   [staticResourceAccessorPreference.name, staticResourceAccessorPreference],
+  [surfaceFacetCoherence.name, surfaceFacetCoherence],
   [validDescribeRefs.name, validDescribeRefs],
   [noDevPermitInSource.name, noDevPermitInSource],
   [noDestructuredCompose.name, noDestructuredCompose],
@@ -203,6 +210,7 @@ export const wardenRules: ReadonlyMap<string, WardenRule> = new Map<
   [noLegacyLayerImports.name, noLegacyLayerImports],
   [noNativeErrorResult.name, noNativeErrorResult],
   [noRedundantResultErrorWrap.name, noRedundantResultErrorWrap],
+  [noRetiredCrossVocabulary.name, noRetiredCrossVocabulary],
   [noSyncResultAssumption.name, noSyncResultAssumption],
   [implementationReturnsResult.name, implementationReturnsResult],
   [noThrowInDetourRecover.name, noThrowInDetourRecover],

package/src/rules/metadata.ts

@@ -87,6 +87,7 @@ const concernByRuleName: Partial<Record<string, WardenRuleConcern>> = {
   'no-direct-implementation-call': 'composition',
   'no-native-error-result': 'results',
   'no-redundant-result-error-wrap': 'results',
+  'no-retired-cross-vocabulary': 'composition',
   'no-sync-result-assumption': 'results',
   'no-throw-in-detour-recover': 'results',
   'no-throw-in-implementation': 'results',
@@ -104,6 +105,7 @@ const concernByRuleName: Partial<Record<string, WardenRuleConcern>> = {
   'scheduled-destroy-intent': 'lifecycle',
   'signal-graph-coaching': 'signals',
   'static-resource-accessor-preference': 'resources',
+  'surface-facet-coherence': 'meta',
   'unmaterialized-activation-source': 'lifecycle',
   'valid-detour-contract': 'results',
   'version-gap': 'lifecycle',
@@ -295,6 +297,18 @@ const builtinWardenRuleMetadataInput = {
       'Result error pass-throughs preserve the original Result boundary.',
     tier: 'source-static',
   },
+  'no-retired-cross-vocabulary': {
+    fix: { class: 'term-rewrite', safety: 'safe' },
+    invariant:
+      'Retired cross composition vocabulary does not remain in downstream source after the beta.19 compose cutover.',
+    lifecycle: {
+      retireWhen:
+        'Downstream beta.19 cross-to-compose migration window closes and supported apps have adopted compose vocabulary.',
+      state: 'temporary',
+    },
+    scope: 'external',
+    tier: 'source-static',
+  },
   'no-sync-result-assumption': {
     ...durableExternal,
     invariant:
@@ -391,6 +405,12 @@ const builtinWardenRuleMetadataInput = {
     scope: 'advisory',
     tier: 'source-static',
   },
+  'public-export-example-coverage': {
+    ...durableRepoLocal,
+    invariant:
+      'Public API barrel exports carry leading @example TSDoc coverage.',
+    tier: 'source-static',
+  },
   'public-internal-deep-imports': {
     invariant: 'Cross-package imports stay on package-owned public exports.',
     lifecycle: { state: 'durable' },
@@ -513,6 +533,27 @@ const builtinWardenRuleMetadataInput = {
     scope: 'advisory',
     tier: 'source-static',
   },
+  'surface-facet-coherence': {
+    ...durableExternal,
+    guidance: {
+      docs: [
+        {
+          label: 'Surface Facets ADR',
+          path: 'docs/adr/drafts/20260603-surface-facets-shape-dense-topos.md',
+        },
+      ],
+      steps: [
+        'Keep facet selectors as explicit string literals or literal arrays when possible.',
+        'Ensure each public trail belongs to one facet owner.',
+        'Record explicit visibility-widening acceptance and stable-description metadata when a facet intentionally widens visibility.',
+      ],
+      summary:
+        'Keep surface facet maps reviewable before they reach MCP projection.',
+    },
+    invariant:
+      'Surface facet maps avoid selector overlap, hidden visibility widening, and drift-prone dynamic selectors.',
+    tier: 'source-static',
+  },
   'unmaterialized-activation-source': {
     ...durableExternal,
     invariant:

package/src/rules/no-retired-cross-vocabulary.ts

@@ -0,0 +1,194 @@
+/**
+ * Flags retired `cross` composition vocabulary after the beta.19 compose cutover.
+ *
+ * Exact authored terms that have a mechanical successor carry safe
+ * `term-rewrite` edits. Larger identifiers and type prefixes remain
+ * review-required because the text-only rule cannot prove the intended symbol
+ * boundary.
+ */
+import { resolve, sep } from 'node:path';
+
+import type { WardenDiagnostic, WardenFix, WardenRule } from './types.js';
+
+const RULE_NAME = 'no-retired-cross-vocabulary';
+
+const SAFE_REWRITES = [
+  { from: 'ctx.cross', to: 'ctx.compose' },
+  { from: 'crossInput', to: 'composeInput' },
+  { from: 'crosses', to: 'composes' },
+] as const;
+
+const REVIEW_TERMS = ['Cross', 'cross'] as const;
+
+const IDENTIFIER_CHAR = /[$0-9A-Z_a-z]/u;
+
+const ALLOWED_PATH_SUFFIXES: readonly string[] = [
+  '/docs/migration/cross-to-compose.md',
+  '/docs/releases/beta15-to-beta19.md',
+  '/docs/adr/0049-composition-is-compose-not-cross.md',
+  '/packages/warden/src/rules/no-retired-cross-vocabulary.ts',
+  '/packages/warden/src/rules/metadata.ts',
+  '/packages/warden/src/trails/no-retired-cross-vocabulary.trail.ts',
+  '/scripts/vocab-cutover-rewrite.ts',
+];
+
+interface SafeRewriteMatch {
+  readonly from: string;
+  readonly index: number;
+  readonly to: string;
+}
+
+interface ReviewMatch {
+  readonly index: number;
+  readonly term: (typeof REVIEW_TERMS)[number];
+}
+
+const normalizePath = (filePath: string): string =>
+  resolve(filePath).split(sep).join('/');
+
+const isAllowedFile = (filePath: string): boolean => {
+  const normalized = normalizePath(filePath);
+  return ALLOWED_PATH_SUFFIXES.some((suffix) => normalized.endsWith(suffix));
+};
+
+const isIdentifierChar = (value: string): boolean =>
+  value !== '' && IDENTIFIER_CHAR.test(value);
+
+const isReviewPrefix = (
+  sourceCode: string,
+  index: number,
+  term: string
+): boolean => !(term === 'cross' && sourceCode.startsWith('crosses', index));
+
+const isStandaloneSpan = (
+  sourceCode: string,
+  start: number,
+  end: number
+): boolean => {
+  const before = start === 0 ? '' : (sourceCode[start - 1] ?? '');
+  const after = sourceCode[end] ?? '';
+  return !(isIdentifierChar(before) || isIdentifierChar(after));
+};
+
+const findSafeRewriteMatches = (
+  sourceCode: string
+): readonly SafeRewriteMatch[] => {
+  const matches: SafeRewriteMatch[] = [];
+  for (const rewrite of SAFE_REWRITES) {
+    let fromIndex = 0;
+    while (fromIndex < sourceCode.length) {
+      const index = sourceCode.indexOf(rewrite.from, fromIndex);
+      if (index === -1) {
+        break;
+      }
+      const end = index + rewrite.from.length;
+      if (isStandaloneSpan(sourceCode, index, end)) {
+        matches.push({ ...rewrite, index });
+      }
+      fromIndex = end;
+    }
+  }
+  return matches.toSorted((a, b) => a.index - b.index);
+};
+
+const findReviewMatches = (sourceCode: string): readonly ReviewMatch[] => {
+  const safeSpans = findSafeRewriteMatches(sourceCode).map((match) => ({
+    end: match.index + match.from.length,
+    start: match.index,
+  }));
+  const isInsideSafeSpan = (index: number): boolean =>
+    safeSpans.some((span) => index >= span.start && index < span.end);
+
+  const matches: ReviewMatch[] = [];
+  for (const term of REVIEW_TERMS) {
+    let fromIndex = 0;
+    while (fromIndex < sourceCode.length) {
+      const index = sourceCode.indexOf(term, fromIndex);
+      if (index === -1) {
+        break;
+      }
+      const end = index + term.length;
+      if (!isInsideSafeSpan(index)) {
+        const before = index === 0 ? '' : (sourceCode[index - 1] ?? '');
+        const after = sourceCode[end] ?? '';
+        if (
+          !isIdentifierChar(before) &&
+          isIdentifierChar(after) &&
+          isReviewPrefix(sourceCode, index, term)
+        ) {
+          matches.push({ index, term });
+        }
+      }
+      fromIndex = end;
+    }
+  }
+  return matches.toSorted((a, b) => a.index - b.index);
+};
+
+const lineForOffset = (sourceCode: string, offset: number): number => {
+  let line = 1;
+  for (let i = 0; i < offset; i += 1) {
+    if (sourceCode.codePointAt(i) === 10) {
+      line += 1;
+    }
+  }
+  return line;
+};
+
+const safeFix = (match: SafeRewriteMatch): WardenFix => ({
+  class: 'term-rewrite',
+  edits: [
+    {
+      end: match.index + match.from.length,
+      replacement: match.to,
+      start: match.index,
+    },
+  ],
+  reason: `Retired composition vocabulary '${match.from}' has a mechanical beta.19 replacement '${match.to}'.`,
+  safety: 'safe',
+});
+
+const reviewFix = (term: string): WardenFix => ({
+  class: 'term-rewrite',
+  reason: `Retired composition vocabulary '${term}' appears in a larger or ambiguous form. Review before migrating to compose vocabulary.`,
+  safety: 'review',
+});
+
+const safeMessage = (match: SafeRewriteMatch): string =>
+  `Retired composition vocabulary '${match.from}' should be '${match.to}' after the beta.19 compose cutover.`;
+
+const reviewMessage = (term: string): string =>
+  `Retired composition vocabulary '${term}' needs review before migrating to compose vocabulary.`;
+
+export const noRetiredCrossVocabulary: WardenRule = {
+  check(sourceCode: string, filePath: string): readonly WardenDiagnostic[] {
+    if (isAllowedFile(filePath)) {
+      return [];
+    }
+
+    const reviewMatches = findReviewMatches(sourceCode);
+    if (reviewMatches.length > 0) {
+      return reviewMatches.map((match) => ({
+        filePath,
+        fix: reviewFix(match.term),
+        line: lineForOffset(sourceCode, match.index),
+        message: reviewMessage(match.term),
+        rule: RULE_NAME,
+        severity: 'error',
+      }));
+    }
+
+    return findSafeRewriteMatches(sourceCode).map((match) => ({
+      filePath,
+      fix: safeFix(match),
+      line: lineForOffset(sourceCode, match.index),
+      message: safeMessage(match),
+      rule: RULE_NAME,
+      severity: 'error',
+    }));
+  },
+  description:
+    'Disallow retired cross composition vocabulary after the beta.19 compose cutover.',
+  name: RULE_NAME,
+  severity: 'error',
+};