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

package/src/formatters.ts

@@ -7,6 +7,7 @@
  */
 
 import type { WardenReport } from './cli.js';
+import { staleDriftMessage } from './drift.js';
 import type { WardenGuidanceLink, WardenSeverity } from './rules/types.js';
 
 /** Map warden severity to GitHub Actions annotation level. */
@@ -35,9 +36,7 @@ export const formatGitHubAnnotations = (report: WardenReport): string => {
   if (report.drift?.blockedReason !== undefined) {
     lines.push(`::error::drift: ${report.drift.blockedReason}`);
   } else if (report.drift?.stale) {
-    lines.push(
-      '::error::drift: trails.lock is stale (regenerate with `trails compile`)'
-    );
+    lines.push(`::error::drift: ${staleDriftMessage(report.drift)}`);
   }
 
   return lines.join('\n');
@@ -144,11 +143,7 @@ const driftSection = (drift: WardenReport['drift']): readonly string[] => {
   if (!drift?.stale) {
     return [];
   }
-  return [
-    '',
-    '### Drift',
-    '- trails.lock is stale (regenerate with `trails compile`)',
-  ];
+  return ['', '### Drift', `- ${staleDriftMessage(drift)}`];
 };
 
 /** Render safe-fix counts when a fix pass was requested. */

package/src/index.ts

@@ -14,6 +14,7 @@ export type {
   ProjectContext,
   TopoAwareWardenRule,
   WardenDiagnostic,
+  WardenExportedSymbolDefinition,
   WardenFix,
   WardenFixCapability,
   WardenFixClass,
@@ -35,8 +36,21 @@ export type {
 // Rule registry
 export {
   builtinWardenRuleMetadata,
+  formatGovernedVocabularyTransitionGuide,
+  getGovernedVocabularyTransition,
+  governedVocabularyLiteralRenameSchema,
+  governedVocabularyPreserveRuleSchema,
+  governedVocabularyRegistrySchema,
+  governedVocabularyScopeSchema,
+  governedVocabularySymbolRenameSchema,
+  governedVocabularyTargetSchema,
+  governedVocabularyTransitionSchema,
+  governedVocabularyTransitionStatuses,
+  governedVocabularyTransitions,
   getWardenRuleMetadata,
   listWardenRuleMetadata,
+  listGovernedVocabularyTransitions,
+  requireGovernedVocabularyTransition,
   wardenFixClasses,
   wardenFixSafeties,
   wardenRuleConcerns,
@@ -46,6 +60,15 @@ export {
   wardenRules,
   wardenTopoRules,
 } from './rules/index.js';
+export type {
+  GovernedVocabularyLiteralRename,
+  GovernedVocabularyPreserveRule,
+  GovernedVocabularyScope,
+  GovernedVocabularySymbolRename,
+  GovernedVocabularyTarget,
+  GovernedVocabularyTransition,
+  GovernedVocabularyTransitionInput,
+} from './rules/index.js';
 
 // Rule-scoped cache controls for long-lived consumers (watch mode, LSPs).
 export { clearImplementationReturnsResultCache } from './rules/implementation-returns-result.js';
@@ -118,7 +141,7 @@ export {
 } from './formatters.js';
 
 // Drift detection
-export type { DriftResult } from './drift.js';
+export type { CheckDriftOptions, DriftResult } from './drift.js';
 export { checkDrift } from './drift.js';
 
 // Project-local rule loading
@@ -176,6 +199,7 @@ export {
   deadPublicTrailTrail,
   deprecationWithoutGuidanceTrail,
   diagnosticSchema,
+  duplicateExportedSymbolTrail,
   duplicatePublicContractTrail,
   draftFileMarkingTrail,
   draftVisibleDebtTrail,
@@ -183,6 +207,7 @@ export {
   exampleValidTrail,
   firesDeclarationsTrail,
   forkWithoutPreservedBlazeTrail,
+  governedSymbolResidueTrail,
   implementationReturnsResultTrail,
   incompleteAccessorForStandardOpTrail,
   incompleteCrudTrail,
@@ -195,6 +220,7 @@ export {
   noDevPermitInSourceTrail,
   noDestructuredComposeTrail,
   noDirectImplementationCallTrail,
+  noLegacyCliAliasExportTrail,
   noLegacyLayerImportsTrail,
   noNativeErrorResultTrail,
   noRedundantResultErrorWrapTrail,
@@ -226,8 +252,10 @@ export {
   scheduledDestroyIntentTrail,
   signalGraphCoachingTrail,
   staticResourceAccessorPreferenceTrail,
-  surfaceFacetCoherenceTrail,
+  surfaceOverlayCoherenceTrail,
+  surfaceTrailheadCoherenceTrail,
   trailForkCoachingTrail,
+  trailheadOverrideDivergenceTrail,
   unmaterializedActivationSourceTrail,
   topoAwareRuleInput,
   unreachableDetourShadowingTrail,

package/src/project-context.ts

@@ -15,7 +15,26 @@ import type {
   WardenImportResolution,
   WardenResolverOptions,
 } from './resolve.js';
-import { offsetToLine } from './rules/ast.js';
+import {
+  getNodeBodyStatements,
+  getNodeDeclaration,
+  getNodeDeclarations,
+  getNodeExportKind,
+  getNodeExported,
+  getNodeId,
+  getNodeLocal,
+  getNodeName,
+  getNodeSource,
+  getNodeSpecifiers,
+  getNodeValue,
+  isDeclarationWithId,
+  isExportNamedDeclaration,
+  isVariableDeclaration,
+  offsetToLine,
+  parse,
+} from './rules/ast.js';
+import type { AstNode } from './rules/ast.js';
+import type { WardenExportedSymbolDefinition } from './rules/types.js';
 import { collectPublicWorkspaces } from './workspaces.js';
 import type { WardenPublicWorkspace } from './workspaces.js';
 
@@ -188,5 +207,240 @@ export const collectProjectDocumentationImportResolutions = ({
   return resolutionsByFile;
 };
 
+const exportedKindForDeclaration = (
+  declaration: AstNode
+): WardenExportedSymbolDefinition['kind'] | null => {
+  if (declaration.type === 'ClassDeclaration') {
+    return 'class';
+  }
+  if (declaration.type === 'FunctionDeclaration') {
+    return 'function';
+  }
+  if (
+    declaration.type === 'EnumDeclaration' ||
+    declaration.type === 'TSEnumDeclaration'
+  ) {
+    return 'enum';
+  }
+  if (
+    declaration.type === 'InterfaceDeclaration' ||
+    declaration.type === 'TSInterfaceDeclaration'
+  ) {
+    return 'interface';
+  }
+  if (declaration.type === 'TSTypeAliasDeclaration') {
+    return 'type';
+  }
+  if (isVariableDeclaration(declaration)) {
+    return 'const';
+  }
+  return null;
+};
+
+const publicExportTargetWorkspacesByPath = (
+  publicWorkspaces: ReadonlyMap<string, WardenPublicWorkspace>
+): ReadonlyMap<string, WardenPublicWorkspace> => {
+  const workspacesByTargetPath = new Map<string, WardenPublicWorkspace>();
+  for (const workspace of publicWorkspaces.values()) {
+    for (const target of Object.values(workspace.exportTargets ?? {})) {
+      workspacesByTargetPath.set(normalizeRealPath(target), workspace);
+    }
+  }
+  return workspacesByTargetPath;
+};
+
+const readNameNode = (node: AstNode | undefined): string | null => {
+  if (!node) {
+    return null;
+  }
+  if (node.type === 'Identifier') {
+    return getNodeName(node) ?? null;
+  }
+  if (node.type === 'Literal' || node.type === 'StringLiteral') {
+    const value = getNodeValue(node);
+    return typeof value === 'string' ? value : null;
+  }
+  return null;
+};
+
+const exportedSpecifierKind = (
+  statement: AstNode,
+  specifier: AstNode
+): WardenExportedSymbolDefinition['kind'] =>
+  getNodeExportKind(statement) === 'type' ||
+  getNodeExportKind(specifier) === 'type'
+    ? 'type'
+    : 'export';
+
+const reexportedDefinitions = ({
+  filePath,
+  sourceCode,
+  statement,
+  workspace,
+}: {
+  readonly filePath: string;
+  readonly sourceCode: string;
+  readonly statement: AstNode;
+  readonly workspace: WardenPublicWorkspace;
+}): readonly WardenExportedSymbolDefinition[] => {
+  const specifiers = getNodeSpecifiers(statement) ?? [];
+  return specifiers.flatMap((specifier) => {
+    if (specifier.type !== 'ExportSpecifier') {
+      return [];
+    }
+    const exported = getNodeExported(specifier);
+    const local = getNodeLocal(specifier);
+    const name = readNameNode(exported) ?? readNameNode(local);
+    return name
+      ? [
+          {
+            filePath,
+            kind: exportedSpecifierKind(statement, specifier),
+            line: offsetToLine(sourceCode, specifier.start),
+            name,
+            workspaceName: workspace.name,
+            workspaceRoot: workspace.rootDir,
+          } satisfies WardenExportedSymbolDefinition,
+        ]
+      : [];
+  });
+};
+
+const namedDeclarationDefinitions = ({
+  declaration,
+  filePath,
+  sourceCode,
+  workspace,
+}: {
+  readonly declaration: AstNode;
+  readonly filePath: string;
+  readonly sourceCode: string;
+  readonly workspace: WardenPublicWorkspace;
+}): readonly WardenExportedSymbolDefinition[] => {
+  const kind = exportedKindForDeclaration(declaration);
+  if (!kind) {
+    return [];
+  }
+
+  if (isVariableDeclaration(declaration)) {
+    return getNodeDeclarations(declaration).flatMap((declarator) => {
+      const name = getNodeName(getNodeId(declarator));
+      return name
+        ? [
+            {
+              filePath,
+              kind,
+              line: offsetToLine(sourceCode, declarator.start),
+              name,
+              workspaceName: workspace.name,
+              workspaceRoot: workspace.rootDir,
+            } satisfies WardenExportedSymbolDefinition,
+          ]
+        : [];
+    });
+  }
+
+  if (!isDeclarationWithId(declaration)) {
+    return [];
+  }
+
+  const name = getNodeName(getNodeId(declaration));
+  return name
+    ? [
+        {
+          filePath,
+          kind,
+          line: offsetToLine(sourceCode, declaration.start),
+          name,
+          workspaceName: workspace.name,
+          workspaceRoot: workspace.rootDir,
+        } satisfies WardenExportedSymbolDefinition,
+      ]
+    : [];
+};
+
+const collectExportedSymbolDefinitionsForFile = (
+  sourceFile: WardenProjectContextSourceFile,
+  publicExportTargetWorkspaces: ReadonlyMap<string, WardenPublicWorkspace>
+): readonly WardenExportedSymbolDefinition[] => {
+  if (sourceFile.kind !== 'typescript') {
+    return [];
+  }
+
+  const workspace = publicExportTargetWorkspaces.get(
+    normalizeRealPath(sourceFile.filePath)
+  );
+  if (!workspace) {
+    return [];
+  }
+
+  const ast = parse(sourceFile.filePath, sourceFile.sourceCode);
+  if (!ast) {
+    return [];
+  }
+
+  return getNodeBodyStatements(ast).flatMap((statement) => {
+    if (!isExportNamedDeclaration(statement)) {
+      return [];
+    }
+    if (getNodeSource(statement) || getNodeSpecifiers(statement)?.length) {
+      return reexportedDefinitions({
+        filePath: sourceFile.filePath,
+        sourceCode: sourceFile.sourceCode,
+        statement,
+        workspace,
+      });
+    }
+    const declaration = getNodeDeclaration(statement);
+    return declaration
+      ? namedDeclarationDefinitions({
+          declaration,
+          filePath: sourceFile.filePath,
+          sourceCode: sourceFile.sourceCode,
+          workspace,
+        })
+      : [];
+  });
+};
+
+export const collectProjectExportedSymbolDefinitions = ({
+  publicWorkspaces: providedPublicWorkspaces,
+  rootDir,
+  sourceFiles,
+}: {
+  readonly publicWorkspaces?: ReadonlyMap<string, WardenPublicWorkspace>;
+  readonly rootDir: string;
+  readonly sourceFiles: readonly WardenProjectContextSourceFile[];
+}): ReadonlyMap<string, readonly WardenExportedSymbolDefinition[]> => {
+  const publicWorkspaces =
+    providedPublicWorkspaces ?? collectPublicWorkspaces(rootDir);
+  const publicExportTargetWorkspaces =
+    publicExportTargetWorkspacesByPath(publicWorkspaces);
+  const definitionsByName = new Map<string, WardenExportedSymbolDefinition[]>();
+
+  for (const sourceFile of sourceFiles) {
+    for (const definition of collectExportedSymbolDefinitionsForFile(
+      sourceFile,
+      publicExportTargetWorkspaces
+    )) {
+      const existing = definitionsByName.get(definition.name) ?? [];
+      existing.push(definition);
+      definitionsByName.set(definition.name, existing);
+    }
+  }
+
+  return new Map(
+    [...definitionsByName.entries()].map(([name, definitions]) => [
+      name,
+      definitions.toSorted(
+        (left, right) =>
+          left.workspaceName.localeCompare(right.workspaceName) ||
+          left.filePath.localeCompare(right.filePath) ||
+          left.line - right.line
+      ),
+    ])
+  );
+};
+
 export { collectPublicWorkspaces };
 export type { WardenPublicWorkspace } from './workspaces.js';

package/src/rules/ast.ts

@@ -109,9 +109,11 @@ export interface VariableDeclaratorNode extends AstNode {
 export interface DeclarationWithIdNode extends AstNode {
   readonly type:
     | 'ClassDeclaration'
+    | 'EnumDeclaration'
     | 'FunctionDeclaration'
     | 'InterfaceDeclaration'
     | 'TSInterfaceDeclaration'
+    | 'TSEnumDeclaration'
     | 'TSTypeAliasDeclaration';
   readonly id?: AstNode;
 }
@@ -408,9 +410,11 @@ export const isDeclarationWithId = (
 ): node is DeclarationWithIdNode =>
   isNodeType<DeclarationWithIdNode>(node, [
     'ClassDeclaration',
+    'EnumDeclaration',
     'FunctionDeclaration',
     'InterfaceDeclaration',
     'TSInterfaceDeclaration',
+    'TSEnumDeclaration',
     'TSTypeAliasDeclaration',
   ]);
 

package/src/rules/duplicate-exported-symbol.ts

@@ -0,0 +1,211 @@
+import type {
+  ProjectAwareWardenRule,
+  ProjectContext,
+  WardenDiagnostic,
+  WardenExportedSymbolDefinition,
+} from './types.js';
+
+const RULE_NAME = 'duplicate-exported-symbol';
+
+const ALLOWED_DUPLICATE_EXPORT_GROUPS: readonly {
+  readonly names: readonly string[];
+  readonly reason: string;
+  readonly workspaceNames: readonly string[];
+}[] = [
+  {
+    names: ['surface'],
+    reason: 'peer surface packages expose the same conventional entry point',
+    workspaceNames: [
+      '@ontrails/commander',
+      '@ontrails/hono',
+      '@ontrails/http',
+      '@ontrails/library',
+      '@ontrails/mcp',
+    ],
+  },
+  {
+    names: ['createApp'],
+    reason: 'HTTP native and Hono bindings share app-construction vocabulary',
+    workspaceNames: ['@ontrails/hono', '@ontrails/http'],
+  },
+  {
+    names: ['CreateAppOptions'],
+    reason: 'HTTP native and Hono bindings share option vocabulary',
+    workspaceNames: ['@ontrails/hono', '@ontrails/http'],
+  },
+  {
+    names: ['SurfaceHttpResult'],
+    reason: 'HTTP native and Hono bindings share runtime handle vocabulary',
+    workspaceNames: ['@ontrails/hono', '@ontrails/http'],
+  },
+  {
+    names: ['AnyTrail', 'Field'],
+    reason: '@ontrails/cli mirrors core command-model types for CLI consumers',
+    workspaceNames: ['@ontrails/cli', '@ontrails/core'],
+  },
+  {
+    names: [
+      'Logger',
+      'LogFormatter',
+      'LogLevel',
+      'LogRecord',
+      'LogSink',
+      'ObserveCapabilities',
+      'ObserveConfig',
+      'ObserveInput',
+    ],
+    reason: '@ontrails/observe mirrors core observability contracts',
+    workspaceNames: ['@ontrails/core', '@ontrails/observe'],
+  },
+  {
+    names: [
+      'DEFAULT_MEMORY_SINK_MAX_RECORDS',
+      'MemorySinkOptions',
+      'MemoryTraceSink',
+      'createBoundedMemorySink',
+      'createMemorySink',
+    ],
+    reason:
+      '@ontrails/tracing compatibility memory sink mirrors @ontrails/observe',
+    workspaceNames: ['@ontrails/observe', '@ontrails/tracing'],
+  },
+  {
+    names: [
+      'ActivationTraceRecordName',
+      'NOOP_SINK',
+      'SignalTraceRecordName',
+      'TRACE_CONTEXT_KEY',
+      'TraceFn',
+      'clearTraceSink',
+      'createActivationTraceRecord',
+      'createSignalTraceRecord',
+      'createTraceRecord',
+      'getTraceContext',
+      'getTraceSink',
+      'registerTraceSink',
+      'traceContextFromRecord',
+      'writeActivationTraceRecord',
+      'writeSignalTraceRecord',
+    ],
+    reason:
+      '@ontrails/tracing mirrors core tracing contracts for compatibility',
+    workspaceNames: ['@ontrails/core', '@ontrails/tracing'],
+  },
+  {
+    names: ['TraceContext', 'TraceRecord', 'TraceSink'],
+    reason:
+      '@ontrails/observe and @ontrails/tracing mirror core trace contracts',
+    workspaceNames: [
+      '@ontrails/core',
+      '@ontrails/observe',
+      '@ontrails/tracing',
+    ],
+  },
+  {
+    names: ['AuthError', 'PermitError'],
+    reason:
+      '@ontrails/core owns the TrailsError subclass; @ontrails/permits owns the auth-adapter payload type',
+    workspaceNames: ['@ontrails/core', '@ontrails/permits'],
+  },
+  {
+    names: ['Result', 'Topo', 'TrailContextInit', 'TrailInput', 'TrailOutput'],
+    reason: '@ontrails/library mirrors core runtime types for library users',
+    workspaceNames: ['@ontrails/core', '@ontrails/library'],
+  },
+];
+
+const definitionKey = (definition: WardenExportedSymbolDefinition): string =>
+  `${definition.workspaceName}:${definition.filePath}:${definition.line}:${definition.name}`;
+
+const isAllowedDuplicateGroup = (
+  definitions: readonly WardenExportedSymbolDefinition[]
+): boolean => {
+  const [first] = definitions;
+  if (!first) {
+    return false;
+  }
+  const workspaceNames = new Set(
+    definitions.map((definition) => definition.workspaceName)
+  );
+  return ALLOWED_DUPLICATE_EXPORT_GROUPS.some(
+    (group) =>
+      group.names.includes(first.name) &&
+      [...workspaceNames].every((name) => group.workspaceNames.includes(name))
+  );
+};
+
+const duplicateGroupsForFile = (
+  context: ProjectContext,
+  filePath: string
+): readonly {
+  readonly current: WardenExportedSymbolDefinition;
+  readonly definitions: readonly WardenExportedSymbolDefinition[];
+}[] => {
+  const groups: {
+    current: WardenExportedSymbolDefinition;
+    definitions: readonly WardenExportedSymbolDefinition[];
+  }[] = [];
+
+  for (const definitions of context.exportedSymbolDefinitionsByName?.values() ??
+    []) {
+    const workspaceNames = new Set(
+      definitions.map((definition) => definition.workspaceName)
+    );
+    if (workspaceNames.size < 2) {
+      continue;
+    }
+    if (isAllowedDuplicateGroup(definitions)) {
+      continue;
+    }
+
+    for (const definition of definitions) {
+      if (definition.filePath === filePath) {
+        groups.push({ current: definition, definitions });
+      }
+    }
+  }
+
+  return groups;
+};
+
+const formatOtherDefinitions = (
+  current: WardenExportedSymbolDefinition,
+  definitions: readonly WardenExportedSymbolDefinition[]
+): string =>
+  definitions
+    .filter(
+      (definition) => definitionKey(definition) !== definitionKey(current)
+    )
+    .map(
+      (definition) =>
+        `${definition.workspaceName} (${definition.filePath}:${definition.line})`
+    )
+    .join(', ');
+
+export const duplicateExportedSymbol: ProjectAwareWardenRule = {
+  check(): readonly WardenDiagnostic[] {
+    return [];
+  },
+  checkWithContext(
+    _sourceCode: string,
+    filePath: string,
+    context: ProjectContext
+  ): readonly WardenDiagnostic[] {
+    return duplicateGroupsForFile(context, filePath).map(
+      ({ current, definitions }) => ({
+        filePath,
+        line: current.line,
+        message: `Exported symbol "${current.name}" is defined by ${current.workspaceName} and also by ${formatOtherDefinitions(
+          current,
+          definitions
+        )}. Keep one package as the owner, rename one side, or document a deliberate ownership mirror before exporting both symbols.`,
+        rule: RULE_NAME,
+        severity: 'warn',
+      })
+    );
+  },
+  description:
+    'Warn when the same exported symbol is defined by multiple first-party packages.',
+  name: RULE_NAME,
+  severity: 'warn',
+};

package/src/rules/duplicate-public-contract.ts

@@ -30,6 +30,7 @@ const contractFingerprint = (entry: TopoGraphEntry): string =>
   JSON.stringify(
     canonicalize({
       composes: entry.composes,
+      contours: entry.contours,
       detours: entry.detours,
       dryRunCapable: entry.dryRunCapable,
       fires: entry.fires,
@@ -62,7 +63,7 @@ const renderTrailIds = (trailIds: readonly string[]): string =>
 const buildDiagnostic = (trailIds: readonly string[]): WardenDiagnostic => ({
   filePath: TOPO_FILE,
   line: 1,
-  message: `Likely duplicate public trail contracts ${renderTrailIds(trailIds)} share the same input, output, intent, permits, resources, composes, signals, and detours. Keep one contract with aliases/input mappings, compose a distinct wrapper, or document why these public contracts are separate.`,
+  message: `Likely duplicate public trail contracts ${renderTrailIds(trailIds)} share the same input, output, intent, permits, resources, contours, composes, signals, and detours. Keep one contract with aliases/input mappings, compose a distinct wrapper, or document why these public contracts are separate.`,
   rule: RULE_NAME,
   severity: 'warn',
 });