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

package/src/trails/index.ts

@@ -10,10 +10,12 @@ export { deprecationWithoutGuidanceTrail } from './deprecation-without-guidance.
 export { duplicatePublicContractTrail } from './duplicate-public-contract.trail.js';
 export { draftFileMarkingTrail } from './draft-file-marking.trail.js';
 export { draftVisibleDebtTrail } from './draft-visible-debt.trail.js';
+export { duplicateExportedSymbolTrail } from './duplicate-exported-symbol.trail.js';
 export { errorMappingCompletenessTrail } from './error-mapping-completeness.trail.js';
 export { exampleValidTrail } from './example-valid.trail.js';
 export { firesDeclarationsTrail } from './fires-declarations.trail.js';
 export { forkWithoutPreservedBlazeTrail } from './fork-without-preserved-blaze.trail.js';
+export { governedSymbolResidueTrail } from './governed-symbol-residue.trail.js';
 export { implementationReturnsResultTrail } from './implementation-returns-result.trail.js';
 export { incompleteAccessorForStandardOpTrail } from './incomplete-accessor-for-standard-op.trail.js';
 export { incompleteCrudTrail } from './incomplete-crud.trail.js';
@@ -26,6 +28,7 @@ export { missingReconcileTrail } from './missing-reconcile.trail.js';
 export { onReferencesExistTrail } from './on-references-exist.trail.js';
 export { noDevPermitInSourceTrail } from './no-dev-permit-in-source.trail.js';
 export { noDestructuredComposeTrail } from './no-destructured-compose.trail.js';
+export { noLegacyCliAliasExportTrail } from './no-legacy-cli-alias-export.trail.js';
 export { noLegacyLayerImportsTrail } from './no-legacy-layer-imports.trail.js';
 export { noDirectImplementationCallTrail } from './no-direct-implementation-call.trail.js';
 export { noNativeErrorResultTrail } from './no-native-error-result.trail.js';
@@ -54,8 +57,10 @@ export { resourceMockCoverageTrail } from './resource-mock-coverage.trail.js';
 export { scheduledDestroyIntentTrail } from './scheduled-destroy-intent.trail.js';
 export { signalGraphCoachingTrail } from './signal-graph-coaching.trail.js';
 export { staticResourceAccessorPreferenceTrail } from './static-resource-accessor-preference.trail.js';
-export { surfaceFacetCoherenceTrail } from './surface-facet-coherence.trail.js';
+export { surfaceOverlayCoherenceTrail } from './surface-overlay-coherence.trail.js';
+export { surfaceTrailheadCoherenceTrail } from './surface-trailhead-coherence.trail.js';
 export { trailForkCoachingTrail } from './trail-fork-coaching.trail.js';
+export { trailheadOverrideDivergenceTrail } from './trailhead-override-divergence.trail.js';
 export { unmaterializedActivationSourceTrail } from './unmaterialized-activation-source.trail.js';
 export { unreachableDetourShadowingTrail } from './unreachable-detour-shadowing.trail.js';
 export { validDetourContractTrail } from './valid-detour-contract.trail.js';

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"],
@@ -18,8 +18,8 @@ export const surfaceFacetCoherenceTrail = wrapRule({
   },
 };`,
       },
-      name: 'Reviewable surface facet map',
+      name: 'Reviewable trailhead map',
     },
   ],
-  rule: surfaceFacetCoherence,
+  rule: surfaceTrailheadCoherence,
 });

package/src/trails/trail-fork-coaching.trail.ts

@@ -10,7 +10,7 @@ export const trailForkCoachingTrail = wrapRule({
             filePath: 'users.ts',
             line: 9,
             message:
-              'Trail "users.manage" branches on input.action ("create", "delete"). This may be a trail fork hidden as a surface accommodation. If branches change semantics (intent, permits, errors, outputs, lifecycle, or side effects) or structure (selected trail identity), split them into distinct trails, a composing trail, or a surface facet that preserves member identity.',
+              'Trail "users.manage" branches on input.action ("create", "delete"). This may be a trail fork hidden as a surface accommodation. If branches change semantics (intent, permits, errors, outputs, lifecycle, or side effects) or structure (selected trail identity), split them into distinct trails, a composing trail, or a trailhead that preserves member identity.',
             rule: 'trail-fork-coaching',
             severity: 'warn',
           },

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)) }
     : {}),

package/src/workspaces.ts

@@ -2,8 +2,10 @@
  * Workspace-manifest discovery for Warden project-aware rules.
  */
 
-import { existsSync, readdirSync, readFileSync, realpathSync } from 'node:fs';
-import { dirname, join, resolve } from 'node:path';
+import { realpathSync } from 'node:fs';
+import { dirname, join, relative, resolve } from 'node:path';
+
+import { listWorkspacePackages, matchesAnyPathGlob } from '@ontrails/core';
 
 export interface WardenPublicWorkspace {
   readonly name: string;
@@ -15,8 +17,8 @@ export interface WardenPublicWorkspace {
   readonly files?: readonly string[] | undefined;
 }
 
-interface RootManifest {
-  readonly workspaces?: unknown;
+export interface WardenWorkspaceCollectionOptions {
+  readonly exclude?: readonly string[];
 }
 
 interface PackageManifest {
@@ -37,55 +39,12 @@ const normalizeRealPath = (path: string): string => {
   }
 };
 
+const rootRelativePath = (rootDir: string, path: string): string =>
+  normalizePath(relative(rootDir, path));
+
 const isRecord = (value: unknown): value is Record<string, unknown> =>
   Boolean(value && typeof value === 'object' && !Array.isArray(value));
 
-const readJson = <T>(path: string): T | undefined => {
-  try {
-    return JSON.parse(readFileSync(path, 'utf8')) as T;
-  } catch {
-    return undefined;
-  }
-};
-
-const workspacePatternsFromManifest = (
-  manifest: RootManifest | 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(workspaceDir) ? [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))
-    .toSorted();
-};
-
 const packageLocalName = (name: string): string =>
   name.split('/').at(-1) ?? name;
 
@@ -208,29 +167,31 @@ const publicWorkspaceFromManifest = (
 };
 
 export const collectPublicWorkspaces = (
-  rootDir: string
+  rootDir: string,
+  options: WardenWorkspaceCollectionOptions = {}
 ): ReadonlyMap<string, WardenPublicWorkspace> => {
   const normalizedRoot = normalizeRealPath(rootDir);
-  const rootManifest = readJson<RootManifest>(
-    join(normalizedRoot, 'package.json')
-  );
   const workspaces = new Map<string, WardenPublicWorkspace>();
 
-  for (const pattern of workspacePatternsFromManifest(rootManifest)) {
-    for (const workspaceDir of workspaceDirsForPattern(
-      normalizedRoot,
-      pattern
-    )) {
-      const packageJsonPath = join(workspaceDir, 'package.json');
-      const manifest = readJson<PackageManifest>(packageJsonPath);
-      if (!manifest) {
-        continue;
-      }
-
-      const workspace = publicWorkspaceFromManifest(packageJsonPath, manifest);
-      if (workspace) {
-        workspaces.set(workspace.name, workspace);
-      }
+  for (const workspacePackage of listWorkspacePackages<PackageManifest>(
+    normalizedRoot
+  )) {
+    const workspace = publicWorkspaceFromManifest(
+      workspacePackage.packageJsonPath,
+      workspacePackage.manifest
+    );
+    if (
+      workspace &&
+      !matchesAnyPathGlob(
+        rootRelativePath(normalizedRoot, workspace.rootDir),
+        options.exclude ?? []
+      ) &&
+      !matchesAnyPathGlob(
+        rootRelativePath(normalizedRoot, workspace.packageJsonPath),
+        options.exclude ?? []
+      )
+    ) {
+      workspaces.set(workspace.name, workspace);
     }
   }