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

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';
 
@@ -81,16 +100,42 @@ const exportAliasesForWorkspaces = (
   return aliases;
 };
 
+const resolveOptionsWithWorkspaceAliases = (
+  publicWorkspaces: ReadonlyMap<string, WardenPublicWorkspace> | undefined,
+  resolveOptions: WardenResolverOptions['resolveOptions'] | undefined
+): WardenResolverOptions['resolveOptions'] => {
+  if (!publicWorkspaces) {
+    return resolveOptions;
+  }
+
+  const workspaceAliases = exportAliasesForWorkspaces(publicWorkspaces);
+  return {
+    ...resolveOptions,
+    alias: {
+      ...workspaceAliases,
+      ...resolveOptions?.alias,
+    },
+  };
+};
+
 export const collectProjectImportResolutions = ({
+  publicWorkspaces,
   resolveOptions,
   rootDir,
   sourceFiles,
 }: {
+  readonly publicWorkspaces?: ReadonlyMap<string, WardenPublicWorkspace>;
   readonly resolveOptions?: WardenResolverOptions['resolveOptions'];
   readonly rootDir: string;
   readonly sourceFiles: readonly WardenProjectContextSourceFile[];
 }): ReadonlyMap<string, readonly WardenImportResolution[]> => {
-  const resolver = createWardenResolver({ resolveOptions, rootDir });
+  const resolver = createWardenResolver({
+    resolveOptions: resolveOptionsWithWorkspaceAliases(
+      publicWorkspaces,
+      resolveOptions
+    ),
+    rootDir,
+  });
   const resolutionsByFile = new Map<
     string,
     readonly WardenImportResolution[]
@@ -118,13 +163,16 @@ export const collectProjectImportResolutions = ({
 };
 
 export const collectProjectDocumentationImportResolutions = ({
+  publicWorkspaces: providedPublicWorkspaces,
   rootDir,
   sourceFiles,
 }: {
+  readonly publicWorkspaces?: ReadonlyMap<string, WardenPublicWorkspace>;
   readonly rootDir: string;
   readonly sourceFiles: readonly WardenProjectContextSourceFile[];
 }): ReadonlyMap<string, readonly WardenImportResolution[]> => {
-  const publicWorkspaces = collectPublicWorkspaces(rootDir);
+  const publicWorkspaces =
+    providedPublicWorkspaces ?? collectPublicWorkspaces(rootDir);
   const resolver = createWardenResolver({
     resolveOptions: { alias: exportAliasesForWorkspaces(publicWorkspaces) },
     rootDir,
@@ -159,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',
 });

package/src/rules/governed-symbol-residue.ts

@@ -0,0 +1,131 @@
+import {
+  identifierName,
+  offsetToLine,
+  parseWithDiagnostics,
+  walk,
+} from './ast.js';
+import type { AstNode } from './ast.js';
+import { listGovernedVocabularyTransitions } from './retired-vocabulary.js';
+import type {
+  GovernedVocabularySymbolRename,
+  GovernedVocabularyTransition,
+} from './retired-vocabulary.js';
+import type { WardenDiagnostic, WardenFix, WardenRule } from './types.js';
+
+const RULE_NAME = 'governed-symbol-residue';
+
+const ACTIVE_STATUSES = new Set<GovernedVocabularyTransition['status']>([
+  'active',
+  'complete',
+]);
+
+const FIX_OWNED_TRANSITION_IDS = new Set(['cross-compose']);
+
+const ALLOWED_SOURCE_PATH_SUFFIXES = [
+  '/packages/warden/src/rules/governed-symbol-residue.ts',
+  '/packages/warden/src/rules/retired-vocabulary.ts',
+] as const;
+
+const normalizePath = (filePath: string): string =>
+  filePath.replaceAll('\\', '/');
+
+const isAllowedSourcePath = (filePath: string): boolean =>
+  ALLOWED_SOURCE_PATH_SUFFIXES.some((suffix) =>
+    normalizePath(filePath).endsWith(suffix)
+  );
+
+const activeSymbolRenames = (): readonly GovernedVocabularySymbolRename[] =>
+  listGovernedVocabularyTransitions()
+    .filter(
+      (transition) =>
+        ACTIVE_STATUSES.has(transition.status) &&
+        !FIX_OWNED_TRANSITION_IDS.has(transition.id)
+    )
+    .flatMap((transition) => transition.symbolRenames);
+
+const renameBySourceSymbol = (): ReadonlyMap<
+  string,
+  GovernedVocabularySymbolRename
+> =>
+  new Map(
+    activeSymbolRenames().map((rename) => [rename.from, rename] as const)
+  );
+
+const safeFixFor = (
+  sourceCode: string,
+  node: AstNode,
+  rename: GovernedVocabularySymbolRename
+): WardenFix | undefined => {
+  const end = node.start + rename.from.length;
+  if (sourceCode.slice(node.start, end) !== rename.from) {
+    return undefined;
+  }
+  return {
+    class: 'term-rewrite',
+    edits: [
+      {
+        end,
+        replacement: rename.to,
+        start: node.start,
+      },
+    ],
+    reason: `Retired governed symbol '${rename.from}' has a mechanical replacement '${rename.to}'.`,
+    safety: 'safe',
+  };
+};
+
+const diagnosticFor = (
+  sourceCode: string,
+  filePath: string,
+  node: AstNode,
+  rename: GovernedVocabularySymbolRename
+): WardenDiagnostic => {
+  const fix = safeFixFor(sourceCode, node, rename);
+  return {
+    filePath,
+    ...(fix === undefined ? {} : { fix }),
+    line: offsetToLine(sourceCode, node.start),
+    message: `Retired governed symbol '${rename.from}' should migrate to '${rename.to}'.`,
+    rule: RULE_NAME,
+    severity: 'error',
+  };
+};
+
+export const governedSymbolResidue: WardenRule = {
+  check(sourceCode: string, filePath: string): readonly WardenDiagnostic[] {
+    if (isAllowedSourcePath(filePath)) {
+      return [];
+    }
+
+    const renames = renameBySourceSymbol();
+    if (renames.size === 0) {
+      return [];
+    }
+
+    const parsed = parseWithDiagnostics(filePath, sourceCode);
+    if (!parsed.ast || parsed.diagnostics.length > 0) {
+      return [];
+    }
+
+    const diagnostics: WardenDiagnostic[] = [];
+    walk(parsed.ast, (node) => {
+      const name = identifierName(node);
+      if (name === null) {
+        return;
+      }
+
+      const rename = renames.get(name);
+      if (rename === undefined) {
+        return;
+      }
+
+      diagnostics.push(diagnosticFor(sourceCode, filePath, node, rename));
+    });
+
+    return diagnostics;
+  },
+  description:
+    'Detect active governed vocabulary symbols that remain in source code.',
+  name: RULE_NAME,
+  severity: 'error',
+};