@ontrails/warden 1.0.0-beta.32 → 1.0.0-beta.39

package/src/trails/no-legacy-cli-alias-export.trail.ts

@@ -0,0 +1,41 @@
+import { noLegacyCliAliasExport } from '../rules/no-legacy-cli-alias-export.js';
+import { wrapRule } from './wrap-rule.js';
+
+export const noLegacyCliAliasExportTrail = wrapRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        filePath: 'apps/example/src/app.ts',
+        sourceCode: `import { surfaceOverlay } from '@ontrails/core';\n\nexport const trailsOverlays = [surfaceOverlay({ cli: { ls: 'gear.list' } })];\n`,
+      },
+      name: 'App modules binding CLI through trailsOverlays are clean',
+    },
+    {
+      expected: {
+        diagnostics: [
+          {
+            filePath: 'apps/example/src/app.ts',
+            fix: {
+              class: 'export-restructure',
+              reason:
+                "Legacy CLI alias export 'trailsCliAliases' must be rewritten into a surfaceOverlay({ cli: { ... } }) entry inside the module's trailsOverlays array export; run the Regrade class export-restructure:cli-aliases (TRL-1210) to automate this restructure.",
+              safety: 'review',
+            },
+            line: 1,
+            message:
+              "Legacy CLI alias export 'trailsCliAliases' was removed in the TRL-1207 surfaces-overlay cutover. Wrap the alias map into surfaceOverlay({ cli: { ... } }) from @ontrails/core inside the module's trailsOverlays array export.",
+            rule: 'no-legacy-cli-alias-export',
+            severity: 'error',
+          },
+        ],
+      },
+      input: {
+        filePath: 'apps/example/src/app.ts',
+        sourceCode: `export const trailsCliAliases = { 'gear.ls': [['gear', 'ls']] };\n`,
+      },
+      name: 'Legacy CLI alias exports produce migration diagnostics',
+    },
+  ],
+  rule: noLegacyCliAliasExport,
+});

package/src/trails/schema.ts

@@ -85,13 +85,48 @@ export const publicWorkspaceSchema = z.object({
   rootDir: z.string(),
 });
 
+export const exportedSymbolDefinitionSchema = z.object({
+  filePath: z.string(),
+  kind: z.enum([
+    'class',
+    'const',
+    'enum',
+    'export',
+    'function',
+    'interface',
+    'type',
+  ]),
+  line: z.number(),
+  name: z.string(),
+  workspaceName: z.string(),
+  workspaceRoot: z.string(),
+});
+
 /**
  * Extended input for project-aware warden rule trails.
  *
  * Adds `knownTrailIds` so the caller can supply compose-file context and avoid
  * false positives for `@see` references or compose-file contour relationships.
  */
+export const authoredMcpSurfaceBindingSetSchema = z.object({
+  appName: z.string().describe('App/topo label the bindings were authored for'),
+  bindings: z
+    .record(z.string(), z.union([z.string(), z.array(z.string()).readonly()]))
+    .describe('Surfaces overlay mcp bindings: binding name to selector(s)'),
+  trailIds: z
+    .array(z.string())
+    .readonly()
+    .describe('Trail ids registered in the owning app topo'),
+});
+
 export const projectAwareRuleInput = ruleInput.extend({
+  authoredMcpSurfaceBindingSets: z
+    .array(authoredMcpSurfaceBindingSetSchema)
+    .readonly()
+    .optional()
+    .describe(
+      'Per-app authored surfaces overlay mcp bindings with owning-app trail ids'
+    ),
   composeTargetTrailIds: z
     .array(z.string())
     .optional()
@@ -114,6 +149,10 @@ export const projectAwareRuleInput = ruleInput.extend({
     .record(z.string(), z.array(importResolutionSchema))
     .optional()
     .describe('Resolved docs/specifier facts keyed by documentation file path'),
+  exportedSymbolDefinitionsByName: z
+    .record(z.string(), z.array(exportedSymbolDefinitionSchema))
+    .optional()
+    .describe('Public exported symbol definitions grouped by exported name'),
   importResolutionsByFile: z
     .record(z.string(), z.array(importResolutionSchema))
     .optional()

package/src/trails/surface-overlay-coherence.trail.ts

@@ -0,0 +1,24 @@
+import { Result, topo, trail } from '@ontrails/core';
+import { z } from 'zod';
+
+import { surfaceOverlayCoherence } from '../rules/surface-overlay-coherence.js';
+import { wrapTopoRule } from './wrap-rule.js';
+
+const listTrail = trail('gear.list', {
+  blaze: () => Result.ok([]),
+  input: z.object({}),
+  output: z.array(z.string()),
+});
+
+export const surfaceOverlayCoherenceTrail = wrapTopoRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        topo: topo('surface-overlay-coherence', { listTrail }),
+      },
+      name: 'Topo without a serialized surfaces overlay stays quiet',
+    },
+  ],
+  rule: surfaceOverlayCoherence,
+});

package/src/trails/{surface-facet-coherence.trail.ts → surface-trailhead-coherence.trail.ts}

@@ -1,13 +1,13 @@
-import { surfaceFacetCoherence } from '../rules/surface-facet-coherence.js';
+import { surfaceTrailheadCoherence } from '../rules/surface-trailhead-coherence.js';
 import { wrapRule } from './wrap-rule.js';
 
-export const surfaceFacetCoherenceTrail = wrapRule({
+export const surfaceTrailheadCoherenceTrail = wrapRule({
   examples: [
     {
       expected: { diagnostics: [] },
       input: {
         filePath: 'mcp-options.ts',
-        sourceCode: `export const facets = {
+        sourceCode: `export const trailheads = {
   inspect: {
     description: "Inspect topo state.",
     trails: ["survey", "survey.brief"],
@@ -21,5 +21,5 @@ export const surfaceFacetCoherenceTrail = wrapRule({
       name: 'Reviewable trailhead map',
     },
   ],
-  rule: surfaceFacetCoherence,
+  rule: surfaceTrailheadCoherence,
 });

package/src/trails/trailhead-override-divergence.trail.ts

@@ -0,0 +1,47 @@
+import { trailheadOverrideDivergence } from '../rules/trailhead-override-divergence.js';
+import { wrapRule } from './wrap-rule.js';
+
+export const trailheadOverrideDivergenceTrail = wrapRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        authoredMcpSurfaceBindingSets: [
+          {
+            appName: 'demo',
+            bindings: { inspect: ['survey', 'survey.brief'] },
+            trailIds: ['survey', 'survey.brief'],
+          },
+        ],
+        filePath: 'mcp-options.ts',
+        sourceCode: `export const trailheads = {
+  inspect: {
+    description: "Inspect topo state.",
+    trails: ["survey", "survey.brief"],
+  },
+};`,
+      },
+      name: 'Aligned call-site override',
+    },
+    {
+      input: {
+        authoredMcpSurfaceBindingSets: [
+          {
+            appName: 'demo',
+            bindings: { inspect: ['survey', 'survey.brief'] },
+            trailIds: ['survey', 'survey.brief'],
+          },
+        ],
+        filePath: 'mcp-options.ts',
+        sourceCode: `export const trailheads = {
+  inspect: {
+    description: "Inspect topo state.",
+    trails: ["survey"],
+  },
+};`,
+      },
+      name: 'Diverging member selectors are flagged',
+    },
+  ],
+  rule: trailheadOverrideDivergence,
+});

package/src/trails/wrap-rule.ts

@@ -51,6 +51,9 @@ const buildRuleMeta = (rule: WardenRule | TopoAwareWardenRule) => {
 };
 
 const buildProjectContext = (input: ProjectAwareRuleInput): ProjectContext => ({
+  ...(input.authoredMcpSurfaceBindingSets
+    ? { authoredMcpSurfaceBindingSets: input.authoredMcpSurfaceBindingSets }
+    : {}),
   ...(input.contourReferencesByName
     ? {
         contourReferencesByName: new Map(
@@ -88,6 +91,13 @@ const buildProjectContext = (input: ProjectAwareRuleInput): ProjectContext => ({
         ),
       }
     : {}),
+  ...(input.exportedSymbolDefinitionsByName
+    ? {
+        exportedSymbolDefinitionsByName: new Map(
+          Object.entries(input.exportedSymbolDefinitionsByName)
+        ),
+      }
+    : {}),
   ...(input.publicWorkspaces
     ? { publicWorkspaces: new Map(Object.entries(input.publicWorkspaces)) }
     : {}),