@ontrails/warden 1.0.0-beta.4 → 1.0.0-beta.42

package/src/rules/draft-file-marking.ts

@@ -0,0 +1,155 @@
+import { isDraftId } from '@ontrails/core';
+
+import { isDraftMarkedFile } from '../draft.js';
+import { collectFrameworkDraftPrefixConstantOffsets } from './source/drafts.js';
+import { hasIgnoreCommentOnLine, splitSourceLines } from './source/pragmas.js';
+import { findStringLiterals, offsetToLine, parse } from '@ontrails/source';
+import type { StringLiteralMatch } from '@ontrails/source';
+import type { WardenDiagnostic, WardenRule } from './types.js';
+
+const messageForMissingMarker = (draftId: string): string =>
+  `Draft id "${draftId}" appears in source, but the file is not draft-marked. ` +
+  'Rename it with an _draft. prefix or a .draft. trailing segment.';
+
+const makeDiagnostic = (
+  sourceCode: string,
+  filePath: string,
+  start: number,
+  message: string,
+  severity: WardenDiagnostic['severity']
+): WardenDiagnostic => ({
+  filePath,
+  line: offsetToLine(sourceCode, start),
+  message,
+  rule: 'draft-file-marking',
+  severity,
+});
+
+const collectDraftMatches = (
+  sourceCode: string,
+  filePath: string,
+  ast: NonNullable<ReturnType<typeof parse>>
+): StringLiteralMatch[] => {
+  const frameworkConstantOffsets = collectFrameworkDraftPrefixConstantOffsets(
+    ast,
+    filePath
+  );
+  const lines = splitSourceLines(sourceCode);
+  return findStringLiterals(ast, (value) => isDraftId(value)).filter(
+    (match) => {
+      if (frameworkConstantOffsets.has(match.start)) {
+        return false;
+      }
+      if (
+        hasIgnoreCommentOnLine(lines, offsetToLine(sourceCode, match.start))
+      ) {
+        return false;
+      }
+      return true;
+    }
+  );
+};
+
+const draftMissingMarkerDiagnostic = (
+  sourceCode: string,
+  filePath: string,
+  ast: NonNullable<ReturnType<typeof parse>>
+): WardenDiagnostic | null => {
+  const draftMatches = collectDraftMatches(sourceCode, filePath, ast);
+  if (!draftMatches.length || isDraftMarkedFile(filePath)) {
+    return null;
+  }
+
+  const [first] = draftMatches;
+  if (!first) {
+    return null;
+  }
+
+  return makeDiagnostic(
+    sourceCode,
+    filePath,
+    first.start,
+    messageForMissingMarker(first.value),
+    'error'
+  );
+};
+
+const draftMarkedWithoutIdsDiagnostic = (
+  filePath: string,
+  ast: NonNullable<ReturnType<typeof parse>>
+): WardenDiagnostic | null => {
+  // Deciding whether the file's `_draft.` marker is still warranted is a
+  // question about *all* draft ids present in source, not just the unsuppressed
+  // ones. Pragma-suppressed ids still justify a draft-marked filename — a user
+  // intentionally silencing them has not removed the draft content. We
+  // therefore filter only the framework-constant declarations (which are not
+  // draft ids at all) and bypass the pragma filter that `collectDraftMatches`
+  // applies.
+  const frameworkConstantOffsets = collectFrameworkDraftPrefixConstantOffsets(
+    ast,
+    filePath
+  );
+  const unsuppressedDraftIds = findStringLiterals(ast, (value) =>
+    isDraftId(value)
+  ).filter((match) => !frameworkConstantOffsets.has(match.start));
+
+  if (unsuppressedDraftIds.length > 0) {
+    return null;
+  }
+
+  if (!isDraftMarkedFile(filePath)) {
+    return null;
+  }
+
+  return {
+    filePath,
+    line: 1,
+    message:
+      'File is draft-marked but no longer contains draft ids. Remove the draft filename marker or finish the promotion cleanup.',
+    rule: 'draft-file-marking',
+    severity: 'warn',
+  };
+};
+
+const collectDraftFileMarkingDiagnostics = (
+  sourceCode: string,
+  filePath: string,
+  ast: NonNullable<ReturnType<typeof parse>>
+): WardenDiagnostic[] => {
+  const missingMarkerDiagnostic = draftMissingMarkerDiagnostic(
+    sourceCode,
+    filePath,
+    ast
+  );
+  if (missingMarkerDiagnostic) {
+    return [missingMarkerDiagnostic];
+  }
+
+  const markedWithoutIdsDiagnostic = draftMarkedWithoutIdsDiagnostic(
+    filePath,
+    ast
+  );
+  if (markedWithoutIdsDiagnostic) {
+    return [markedWithoutIdsDiagnostic];
+  }
+
+  return [];
+};
+
+/**
+ * Ensures files containing draft ids are visibly marked as draft-bearing files.
+ */
+export const draftFileMarking: WardenRule = {
+  check(sourceCode: string, filePath: string): readonly WardenDiagnostic[] {
+    const ast = parse(filePath, sourceCode);
+    if (!ast) {
+      return [];
+    }
+
+    return collectDraftFileMarkingDiagnostics(sourceCode, filePath, ast);
+  },
+  description:
+    'Require draft-bearing files to use _draft.* or *.draft.* filename markers.',
+  name: 'draft-file-marking',
+  severity: 'error',
+};

package/src/rules/draft-visible-debt.ts

@@ -0,0 +1,82 @@
+import { isDraftId } from '@ontrails/core';
+
+import { collectFrameworkDraftPrefixConstantOffsets } from './source/drafts.js';
+import { hasIgnoreCommentOnLine, splitSourceLines } from './source/pragmas.js';
+import { findStringLiterals, offsetToLine, parse } from '@ontrails/source';
+import type { WardenDiagnostic, WardenRule } from './types.js';
+
+const createDiagnostic = (
+  sourceCode: string,
+  filePath: string,
+  match: { start: number; value: string }
+): WardenDiagnostic => ({
+  filePath,
+  line: offsetToLine(sourceCode, match.start),
+  message:
+    `Draft id "${match.value}" is still visible debt. ` +
+    'Established surfaces, lock export, and OpenAPI generation will reject it until it is promoted.',
+  rule: 'draft-visible-debt',
+  severity: 'warn',
+});
+
+const isSuppressedMatch = (
+  match: { start: number },
+  sourceCode: string,
+  lines: readonly string[],
+  frameworkConstantOffsets: ReadonlySet<number>
+): boolean =>
+  frameworkConstantOffsets.has(match.start) ||
+  hasIgnoreCommentOnLine(lines, offsetToLine(sourceCode, match.start));
+
+const collectDraftVisibleDebtDiagnostics = (
+  sourceCode: string,
+  filePath: string,
+  ast: NonNullable<ReturnType<typeof parse>>
+): WardenDiagnostic[] => {
+  const frameworkConstantOffsets = collectFrameworkDraftPrefixConstantOffsets(
+    ast,
+    filePath
+  );
+  const lines = splitSourceLines(sourceCode);
+  const seen = new Set<string>();
+
+  return findStringLiterals(ast, (value) => isDraftId(value)).flatMap(
+    (match) => {
+      if (
+        isSuppressedMatch(match, sourceCode, lines, frameworkConstantOffsets)
+      ) {
+        return [];
+      }
+      const key = `${match.value}:${String(match.start)}`;
+      if (seen.has(key)) {
+        return [];
+      }
+      seen.add(key);
+      return [createDiagnostic(sourceCode, filePath, match)];
+    }
+  );
+};
+
+/**
+ * Warns when draft ids are still present so the debt stays visible during
+ * review even when the file is correctly marked.
+ *
+ * Severity is intentionally `warn`, not `error`. The hard rejection layer for
+ * draft state leaking into established outputs is `validateEstablishedTopo` at
+ * runtime — it blocks topo compile, surface projection, and lockfile writes.
+ * This rule surfaces the debt for human reviewers without duplicating that layer.
+ */
+export const draftVisibleDebt: WardenRule = {
+  check(sourceCode: string, filePath: string): readonly WardenDiagnostic[] {
+    const ast = parse(filePath, sourceCode);
+    if (!ast) {
+      return [];
+    }
+
+    return collectDraftVisibleDebtDiagnostics(sourceCode, filePath, ast);
+  },
+  description:
+    'Warn when draft ids remain in source so the debt stays visible during review.',
+  name: 'draft-visible-debt',
+  severity: 'warn',
+};

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

@@ -0,0 +1,137 @@
+import { deriveTopoGraph } from '@ontrails/topography';
+import type { TopoGraph, TopoGraphEntry } from '@ontrails/topography';
+
+import type { TopoAwareWardenRule, WardenDiagnostic } from './types.js';
+
+const RULE_NAME = 'duplicate-public-contract';
+const TOPO_FILE = '<topo>';
+const INVERSE_OPERATION_PAIRS = new Map([
+  ['archive', 'restore'],
+  ['disable', 'enable'],
+  ['pause', 'resume'],
+  ['star', 'unstar'],
+]);
+
+const resolveGraph = (
+  topo: Parameters<TopoAwareWardenRule['checkTopo']>[0],
+  graph: TopoGraph | undefined
+): TopoGraph => graph ?? deriveTopoGraph(topo);
+
+const canonicalize = (value: unknown): unknown => {
+  if (Array.isArray(value)) {
+    return value.map(canonicalize);
+  }
+  if (value && typeof value === 'object') {
+    return Object.fromEntries(
+      Object.entries(value as Record<string, unknown>)
+        .filter(([, entryValue]) => entryValue !== undefined)
+        .toSorted(([left], [right]) => left.localeCompare(right))
+        .map(([key, entryValue]) => [key, canonicalize(entryValue)])
+    );
+  }
+  return value;
+};
+
+const contractFingerprint = (entry: TopoGraphEntry): string =>
+  JSON.stringify(
+    canonicalize({
+      composes: entry.composes,
+      detours: entry.detours,
+      dryRunCapable: entry.dryRunCapable,
+      entities: entry.entities,
+      fires: entry.fires,
+      idempotent: entry.idempotent,
+      input: entry.input,
+      intent: entry.intent,
+      meta: entry.meta,
+      on: entry.on,
+      output: entry.output,
+      permit: entry.permit,
+      resources: entry.resources,
+    })
+  );
+
+const isCandidate = (entry: TopoGraphEntry): boolean =>
+  entry.kind === 'trail' &&
+  !entry.id.startsWith('warden.rule.') &&
+  entry.deprecated !== true &&
+  entry.meta?.['internal'] !== true &&
+  entry.input !== undefined &&
+  entry.output !== undefined &&
+  Boolean(entry.cli || entry.surfaces.length > 0);
+
+const renderTrailIds = (trailIds: readonly string[]): string =>
+  trailIds
+    .toSorted((left, right) => left.localeCompare(right))
+    .map((trailId) => `"${trailId}"`)
+    .join(', ');
+
+const splitOperation = (
+  trailId: string
+): { readonly scope: string; readonly operation: string } | undefined => {
+  const separatorIndex = trailId.lastIndexOf('.');
+
+  if (separatorIndex <= 0 || separatorIndex === trailId.length - 1) {
+    return undefined;
+  }
+
+  return {
+    operation: trailId.slice(separatorIndex + 1),
+    scope: trailId.slice(0, separatorIndex),
+  };
+};
+
+const areInverseOperations = (left: string, right: string): boolean =>
+  INVERSE_OPERATION_PAIRS.get(left) === right ||
+  INVERSE_OPERATION_PAIRS.get(right) === left;
+
+const isAcceptedInverseOperationPair = (
+  trailIds: readonly string[]
+): boolean => {
+  if (trailIds.length !== 2) {
+    return false;
+  }
+
+  const [left, right] = trailIds.map(splitOperation);
+
+  return Boolean(
+    left &&
+    right &&
+    left.scope === right.scope &&
+    areInverseOperations(left.operation, right.operation)
+  );
+};
+
+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, entities, 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',
+});
+
+export const duplicatePublicContract: TopoAwareWardenRule = {
+  checkTopo(topo, context) {
+    const graph = resolveGraph(topo, context?.graph);
+    const groups = new Map<string, string[]>();
+
+    for (const entry of graph.entries) {
+      if (!isCandidate(entry)) {
+        continue;
+      }
+      const key = contractFingerprint(entry);
+      groups.set(key, [...(groups.get(key) ?? []), entry.id]);
+    }
+
+    return [...groups.values()]
+      .filter(
+        (trailIds) =>
+          trailIds.length > 1 && !isAcceptedInverseOperationPair(trailIds)
+      )
+      .map(buildDiagnostic);
+  },
+  description:
+    'Warn when public surface trails expose the same normalized contract facts.',
+  name: RULE_NAME,
+  severity: 'warn',
+};