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

package/src/rules/captured-kernel.ts

@@ -0,0 +1,375 @@
+import { realpathSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+import {
+  extractStringLiteral,
+  getNodeDeclaration,
+  getNodeImportKind,
+  getNodeLocal,
+  getNodeSource,
+  getNodeSpecifiers,
+  identifierName,
+  isExportDefaultDeclaration,
+  isExportNamedDeclaration,
+  isImportDeclaration,
+  offsetToLine,
+  parse,
+  walk,
+} from '@ontrails/source';
+import type { WardenImportResolution } from '../resolve.js';
+import type { WardenPublicWorkspace } from '../workspaces.js';
+import { hasIgnoreCommentOnLine, splitSourceLines } from './source/pragmas.js';
+import { isTestFile } from './scan.js';
+import type {
+  ProjectAwareWardenRule,
+  ProjectContext,
+  WardenDiagnostic,
+} from './types.js';
+
+const RULE_NAME = 'captured-kernel';
+
+interface InternalReExportSite {
+  readonly importSource: string;
+  readonly line: number;
+  readonly resolutionLine: number;
+}
+
+interface ImportedBindingSite {
+  readonly importSource: string;
+  readonly resolutionLine: number;
+}
+
+interface ExportTarget {
+  readonly specifier: string;
+  readonly workspace: WardenPublicWorkspace;
+}
+
+const normalizePath = (path: string): string => path.replaceAll('\\', '/');
+
+const normalizeRealPath = (path: string): string => {
+  try {
+    return normalizePath(realpathSync(path));
+  } catch {
+    return normalizePath(resolve(path));
+  }
+};
+
+const pathIsInside = (filePath: string, rootDir: string): boolean => {
+  const absoluteFilePath = normalizeRealPath(filePath);
+  const absoluteRootDir = normalizeRealPath(rootDir);
+  return (
+    absoluteFilePath === absoluteRootDir ||
+    absoluteFilePath.startsWith(`${absoluteRootDir}/`)
+  );
+};
+
+const sourcePackageNameForFile = (
+  filePath: string,
+  workspaces: ReadonlyMap<string, WardenPublicWorkspace>
+): string | undefined => {
+  for (const workspace of workspaces.values()) {
+    if (pathIsInside(filePath, workspace.rootDir)) {
+      return workspace.name;
+    }
+  }
+  return undefined;
+};
+
+const exportTargetsForFile = (
+  filePath: string,
+  workspaces: ReadonlyMap<string, WardenPublicWorkspace>
+): readonly ExportTarget[] => {
+  const normalizedFilePath = normalizeRealPath(filePath);
+  const targets: ExportTarget[] = [];
+  for (const workspace of workspaces.values()) {
+    for (const [specifier, target] of Object.entries(
+      workspace.exportTargets ?? {}
+    )) {
+      if (specifier === workspace.name) {
+        continue;
+      }
+      if (normalizeRealPath(target) === normalizedFilePath) {
+        targets.push({ specifier, workspace });
+      }
+    }
+  }
+  return targets.toSorted((left, right) =>
+    left.specifier.localeCompare(right.specifier)
+  );
+};
+
+const collectReExportSites = (
+  sourceCode: string,
+  filePath: string
+): readonly InternalReExportSite[] => {
+  const ast = parse(filePath, sourceCode);
+  if (!ast) {
+    return [];
+  }
+
+  const sites: InternalReExportSite[] = [];
+  const importedBindings = new Map<string, ImportedBindingSite>();
+  walk(ast, (node) => {
+    if (!isImportDeclaration(node)) {
+      return;
+    }
+    if (getNodeImportKind(node) === 'type') {
+      return;
+    }
+    const value = extractStringLiteral(getNodeSource(node));
+    if (typeof value !== 'string') {
+      return;
+    }
+    const resolutionLine = offsetToLine(sourceCode, node.start);
+    for (const specifier of getNodeSpecifiers(node) ?? []) {
+      if (getNodeImportKind(specifier) === 'type') {
+        continue;
+      }
+      const localName = identifierName(getNodeLocal(specifier));
+      if (localName !== null) {
+        importedBindings.set(localName, {
+          importSource: value,
+          resolutionLine,
+        });
+      }
+    }
+  });
+
+  const siteKeys = new Set<string>();
+  const addSite = (site: InternalReExportSite): void => {
+    const key = `${site.importSource}:${site.line}:${site.resolutionLine}`;
+    if (!siteKeys.has(key)) {
+      siteKeys.add(key);
+      sites.push(site);
+    }
+  };
+  walk(ast, (node) => {
+    if (isExportDefaultDeclaration(node)) {
+      const localName = identifierName(getNodeDeclaration(node));
+      if (localName === null) {
+        return;
+      }
+      const imported = importedBindings.get(localName);
+      if (imported !== undefined) {
+        addSite({
+          ...imported,
+          line: offsetToLine(sourceCode, node.start),
+        });
+      }
+      return;
+    }
+
+    if (
+      node.type !== 'ExportNamedDeclaration' &&
+      node.type !== 'ExportAllDeclaration'
+    ) {
+      return;
+    }
+
+    const line = offsetToLine(sourceCode, node.start);
+    const value = extractStringLiteral(getNodeSource(node));
+    if (typeof value === 'string') {
+      addSite({ importSource: value, line, resolutionLine: line });
+      return;
+    }
+
+    if (!isExportNamedDeclaration(node)) {
+      return;
+    }
+    for (const specifier of getNodeSpecifiers(node) ?? []) {
+      const localName = identifierName(getNodeLocal(specifier));
+      if (localName === null) {
+        continue;
+      }
+      const imported = importedBindings.get(localName);
+      if (imported !== undefined) {
+        addSite({ ...imported, line });
+      }
+    }
+  });
+  return sites.toSorted((left, right) => left.line - right.line);
+};
+
+const importResolutionsForFile = (
+  context: ProjectContext,
+  filePath: string
+): readonly WardenImportResolution[] =>
+  context.importResolutionsByFile?.get(filePath) ?? [];
+
+const reExportResolution = (
+  resolutions: readonly WardenImportResolution[],
+  site: InternalReExportSite
+): WardenImportResolution | undefined =>
+  resolutions.find(
+    (resolution) =>
+      resolution.importSource === site.importSource &&
+      resolution.line === site.resolutionLine
+  );
+
+const isOwnedInternalReExport = (
+  workspace: WardenPublicWorkspace,
+  resolution: WardenImportResolution | undefined
+): boolean => {
+  if (!resolution?.isInternalTarget) {
+    return false;
+  }
+  if (resolution.packageName === workspace.name) {
+    return true;
+  }
+  if (
+    resolution.packageRoot &&
+    normalizeRealPath(resolution.packageRoot) ===
+      normalizeRealPath(workspace.rootDir)
+  ) {
+    return true;
+  }
+  return resolution.resolvedPath
+    ? pathIsInside(resolution.resolvedPath, workspace.rootDir)
+    : false;
+};
+
+const isNonProductionEvidenceFile = (filePath: string): boolean => {
+  const normalized = normalizePath(filePath);
+  return (
+    isTestFile(filePath) ||
+    /(?:^|\/)(?:__fixtures__|fixtures?|migrations?|historical|changelogs?|changesets?|agent-notes?)(?:\/|$)/.test(
+      normalized
+    ) ||
+    /(?:^|\/)\.(?:changeset|agents)(?:\/|$)/.test(normalized) ||
+    /(?:^|\/)(?:CHANGELOG|changeset)\.md$/i.test(normalized)
+  );
+};
+
+const externalProductionConsumerPackages = ({
+  context,
+  exportSpecifier,
+  hostPackage,
+  workspaces,
+}: {
+  readonly context: ProjectContext;
+  readonly exportSpecifier: string;
+  readonly hostPackage: string;
+  readonly workspaces: ReadonlyMap<string, WardenPublicWorkspace>;
+}): readonly string[] => {
+  const consumers = new Set<string>();
+  for (const resolutions of context.importResolutionsByFile?.values() ?? []) {
+    for (const resolution of resolutions) {
+      if (resolution.importSource !== exportSpecifier) {
+        continue;
+      }
+      if (resolution.errorKind || !resolution.usesPublicExport) {
+        continue;
+      }
+      if (!resolution.crossesPackageBoundary) {
+        continue;
+      }
+      if (resolution.packageName !== hostPackage) {
+        continue;
+      }
+      if (isNonProductionEvidenceFile(resolution.importerPath)) {
+        continue;
+      }
+
+      const sourcePackageName = sourcePackageNameForFile(
+        resolution.importerPath,
+        workspaces
+      );
+      if (!sourcePackageName || sourcePackageName === hostPackage) {
+        continue;
+      }
+      consumers.add(sourcePackageName);
+    }
+  }
+  return [...consumers].toSorted();
+};
+
+const diagnosticMessage = ({
+  consumers,
+  exportSpecifier,
+  hostPackage,
+  importSource,
+}: {
+  readonly consumers: readonly string[];
+  readonly exportSpecifier: string;
+  readonly hostPackage: string;
+  readonly importSource: string;
+}): string =>
+  `${hostPackage} export target "${exportSpecifier}" re-exports internal target "${importSource}" and is consumed by external production packages ${consumers.join(
+    ', '
+  )}. Review ownership of the exported subpath and its captured kernel before it becomes a durable public seam.`;
+
+export const capturedKernel: ProjectAwareWardenRule = {
+  check(): readonly WardenDiagnostic[] {
+    return [];
+  },
+  checkWithContext(
+    sourceCode: string,
+    filePath: string,
+    context: ProjectContext
+  ): readonly WardenDiagnostic[] {
+    const workspaces = context.publicWorkspaces;
+    if (!workspaces || workspaces.size === 0) {
+      return [];
+    }
+
+    const exportTargets = exportTargetsForFile(filePath, workspaces);
+    if (exportTargets.length === 0) {
+      return [];
+    }
+
+    const lines = splitSourceLines(sourceCode);
+    const resolutions = importResolutionsForFile(context, filePath);
+    const diagnostics: WardenDiagnostic[] = [];
+
+    for (const exportTarget of exportTargets) {
+      const consumers = externalProductionConsumerPackages({
+        context,
+        exportSpecifier: exportTarget.specifier,
+        hostPackage: exportTarget.workspace.name,
+        workspaces,
+      });
+      if (consumers.length < 2) {
+        continue;
+      }
+
+      for (const site of collectReExportSites(sourceCode, filePath)) {
+        if (hasIgnoreCommentOnLine(lines, site.line)) {
+          continue;
+        }
+
+        const resolution = reExportResolution(resolutions, site);
+        if (!isOwnedInternalReExport(exportTarget.workspace, resolution)) {
+          continue;
+        }
+
+        diagnostics.push({
+          filePath,
+          guidance: {
+            steps: [
+              'Review whether the public subpath should become an owned package surface, move back behind the package root, or be split into a better-owned package.',
+              'If the imported capability is reusable source-code machinery, serves at least two independently owned toolchain capabilities, exposes one genuinely shared contract, and owns no verdict, migration plan, graph query, or surface rendering, consider relocating it to @ontrails/source.',
+              'Otherwise, preserve the current owner or choose another doctrinal owner.',
+            ],
+            summary:
+              'Review ownership before an internal re-exported kernel hardens into a public package seam.',
+          },
+          line: site.line,
+          message: diagnosticMessage({
+            consumers,
+            exportSpecifier: exportTarget.specifier,
+            hostPackage: exportTarget.workspace.name,
+            importSource: site.importSource,
+          }),
+          rule: RULE_NAME,
+          severity: 'warn',
+        });
+      }
+    }
+
+    return diagnostics;
+  },
+  description:
+    'Flag public subpath exports that capture internal kernels after multiple production packages consume them.',
+  name: RULE_NAME,
+  severity: 'warn',
+};

package/src/rules/circular-refs.ts

@@ -1,10 +1,6 @@
-import {
-  collectContourReferenceTargetsByName,
-  findContourDefinitions,
-  offsetToLine,
-  parse,
-} from './ast.js';
-import type { AstNode } from './ast.js';
+import { collectEntityReferenceTargetsByName } from './source/entities.js';
+import { findEntityDefinitions, offsetToLine, parse } from '@ontrails/source';
+import type { AstNode } from '@ontrails/source';
 import { isTestFile } from './scan.js';
 import type {
   ProjectAwareWardenRule,
@@ -75,14 +71,14 @@ const findCyclePath = (
 };
 
 const buildCircularReferenceDiagnostic = (
-  contourName: string,
+  entityName: string,
   cyclePath: readonly string[],
   filePath: string,
   line: number
 ): WardenDiagnostic => ({
   filePath,
   line,
-  message: `Contour "${contourName}" participates in circular contour references: ${cyclePath.join(' -> ')}. Break the cycle by removing one contour reference, or extract the shared shape into a new contour neither side depends on.`,
+  message: `Entity "${entityName}" participates in circular entity references: ${cyclePath.join(' -> ')}. Break the cycle by removing one entity reference, or extract the shared shape into a new entity neither side depends on.`,
   rule: 'circular-refs',
   severity: 'warn',
 });
@@ -97,7 +93,7 @@ const checkCircularReferences = (
     return [];
   }
 
-  return findContourDefinitions(ast).flatMap((definition) => {
+  return findEntityDefinitions(ast).flatMap((definition) => {
     const cyclePath = findCyclePath(definition.name, graph);
     if (!cyclePath) {
       return [];
@@ -115,7 +111,7 @@ const checkCircularReferences = (
 };
 
 /**
- * Warns when contour references form a direct or transitive cycle.
+ * Warns when entity references form a direct or transitive cycle.
  */
 export const circularRefs: ProjectAwareWardenRule = {
   check(sourceCode: string, filePath: string): readonly WardenDiagnostic[] {
@@ -124,7 +120,7 @@ export const circularRefs: ProjectAwareWardenRule = {
       return [];
     }
 
-    const graph = collectContourReferenceTargetsByName(ast);
+    const graph = collectEntityReferenceTargetsByName(ast);
     return checkCircularReferences(ast, sourceCode, filePath, graph);
   },
   checkWithContext(
@@ -137,18 +133,18 @@ export const circularRefs: ProjectAwareWardenRule = {
       return [];
     }
 
-    const localGraph = collectContourReferenceTargetsByName(
+    const localGraph = collectEntityReferenceTargetsByName(
       ast,
-      context.knownContourIds
+      context.knownEntityIds
     );
     return checkCircularReferences(
       ast,
       sourceCode,
       filePath,
-      mergeReferenceGraphs(localGraph, context.contourReferencesByName)
+      mergeReferenceGraphs(localGraph, context.entityReferencesByName)
     );
   },
-  description: 'Warn when contour references form direct or transitive cycles.',
+  description: 'Warn when entity references form direct or transitive cycles.',
   name: 'circular-refs',
   severity: 'warn',
 };

package/src/rules/cli-command-route-coherence.ts

@@ -1,6 +1,6 @@
 import { deriveTrailCliCommandProjection } from '@ontrails/core';
 import type { CliCommandRoute, Topo } from '@ontrails/core';
-import type { TopoGraph } from '@ontrails/topographer';
+import type { TopoGraph } from '@ontrails/topography';
 
 import type { TopoAwareWardenRule, WardenDiagnostic } from './types.js';
 

package/src/rules/composes-declarations.ts

@@ -1,14 +1,14 @@
 /**
  * Validates that `ctx.compose()` calls match the declared `composes` array.
  *
- * Statically analyzes trail `blaze` functions to find `ctx.compose('trailId', ...)`
+ * Statically analyzes trail `implementation` functions to find `ctx.compose('trailId', ...)`
  * calls and compares them against the `composes: [...]` declaration in the trail
  * config. Reports errors for undeclared compositions and warnings for unused ones.
  */
 
 import {
-  findBlazeBodies,
   findConfigProperty,
+  findImplementationBodies,
   findTrailDefinitions,
   getNodeArguments,
   getNodeBodyNode,
@@ -32,8 +32,8 @@ import {
   offsetToLine,
   parse,
   walkWithScopes,
-} from './ast.js';
-import type { AstNode } from './ast.js';
+} from '@ontrails/source';
+import type { AstNode } from '@ontrails/source';
 import { isTestFile } from './scan.js';
 import type { WardenDiagnostic, WardenRule } from './types.js';
 
@@ -220,15 +220,17 @@ const extractMemberPair = (
 };
 
 /**
- * Extract the second parameter name from a blaze function node.
+ * Extract the second parameter name from a implementation function node.
  *
  * Handles `(input, ctx) => ...`, `async (input, context) => ...`,
  * `function(input, ctx) { ... }`, and defaulted params like
  * `(input, ctx = fallback) => ...` (AssignmentPattern whose `.left` is the
  * Identifier).
  */
-const extractContextParamName = (blazeBody: AstNode): string | null => {
-  const params = blazeBody['params'] as readonly AstNode[] | undefined;
+const extractContextParamName = (
+  implementationBody: AstNode
+): string | null => {
+  const params = implementationBody['params'] as readonly AstNode[] | undefined;
   if (!params || params.length < 2) {
     return null;
   }
@@ -422,10 +424,10 @@ const extractComposeCall = (
 /**
  * Build the set of context parameter names to match against.
  *
- * Returns ONLY the actual second-parameter name from the blaze signature.
- * No seeded defaults: if the blaze has no second parameter, the returned set
+ * Returns ONLY the actual second-parameter name from the implementation signature.
+ * No seeded defaults: if the implementation has no second parameter, the returned set
  * is empty and no `ctx.compose(...)` / `context.compose(...)` calls are tracked
- * for that blaze. An unrelated closure-scoped `ctx` identifier is not the
+ * for that implementation. An unrelated closure-scoped `ctx` identifier is not the
  * trail context and must not be treated as one.
  *
  * Mirrors `fires-declarations.ts` and `resource-declarations.ts` for the same
@@ -613,7 +615,7 @@ interface CalledComposes {
   readonly hasUnresolved: boolean;
 }
 
-/** Collect compose call results from a single blaze body. */
+/** Collect compose call results from a single implementation body. */
 const collectComposeCallsFromBody = (
   body: AstNode,
   ids: Set<string>,
@@ -682,7 +684,7 @@ const collectComposeCallsFromBody = (
   return foundUnresolved;
 };
 
-/** Walk blaze bodies and collect all statically resolvable ctx.compose() trail IDs. */
+/** Walk implementation bodies and collect all statically resolvable ctx.compose() trail IDs. */
 const extractCalledComposes = (
   config: AstNode,
   ast: AstNode,
@@ -692,7 +694,7 @@ const extractCalledComposes = (
   let hasUnresolved = false;
   const helpers = collectComposeHelpers(ast);
 
-  for (const body of findBlazeBodies(config)) {
+  for (const body of findImplementationBodies(config)) {
     if (collectComposeCallsFromBody(body, ids, sourceCode, helpers)) {
       hasUnresolved = true;
     }

package/src/rules/context-no-surface-types.ts

@@ -13,8 +13,8 @@ import {
   offsetToLine,
   parse,
   walk,
-} from './ast.js';
-import type { AstNode } from './ast.js';
+} from '@ontrails/source';
+import type { AstNode } from '@ontrails/source';
 import type { WardenDiagnostic, WardenRule } from './types.js';
 
 const SURFACE_MODULES = new Set([
@@ -82,7 +82,8 @@ const isNamespacedTrailCallee = (callee: AstNode): boolean => {
  * `import * as ns from '@ontrails/core'` are detected as trail definitions.
  *
  * The inner `if (found)` guard skips further work in each callback invocation,
- * but the shared `walk` helper in `./ast.ts` exposes no abort mechanism, so
+ * but the shared `walk` helper from `@ontrails/source` exposes no abort
+ * mechanism, so
  * the full tree is still traversed once a match is seen. Acceptable: `walk`
  * is cheap and this rule only runs on files that already matched a path
  * filter upstream.

package/src/rules/dead-internal-trail.ts

@@ -1,5 +1,5 @@
+import { collectComposeTargetTrailIds } from './source/composition.js';
 import {
-  collectComposeTargetTrailIds,
   findConfigProperty,
   findTrailDefinitions,
   getNodeValue,
@@ -7,8 +7,8 @@ import {
   isStringLiteral,
   offsetToLine,
   parse,
-} from './ast.js';
-import type { AstNode } from './ast.js';
+} from '@ontrails/source';
+import type { AstNode } from '@ontrails/source';
 import { isTestFile } from './scan.js';
 import type {
   ProjectAwareWardenRule,

package/src/rules/dead-public-trail.ts

@@ -1,5 +1,5 @@
+import { collectComposeTargetTrailIds } from './source/composition.js';
 import {
-  collectComposeTargetTrailIds,
   findConfigProperty,
   findTrailDefinitions,
   getNodeDeclaration,
@@ -15,8 +15,8 @@ import {
   offsetToLine,
   parse,
   walkWithParents,
-} from './ast.js';
-import type { AstNode, AstParentContext } from './ast.js';
+} from '@ontrails/source';
+import type { AstNode, AstParentContext } from '@ontrails/source';
 import { isTestFile } from './scan.js';
 import type {
   ProjectAwareWardenRule,

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

@@ -1,15 +1,10 @@
 import { isDraftId } from '@ontrails/core';
 
 import { isDraftMarkedFile } from '../draft.js';
-import {
-  collectFrameworkDraftPrefixConstantOffsets,
-  findStringLiterals,
-  hasIgnoreCommentOnLine,
-  offsetToLine,
-  parse,
-  splitSourceLines,
-} from './ast.js';
-import type { StringLiteralMatch } from './ast.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 =>

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

@@ -1,13 +1,8 @@
 import { isDraftId } from '@ontrails/core';
 
-import {
-  collectFrameworkDraftPrefixConstantOffsets,
-  findStringLiterals,
-  hasIgnoreCommentOnLine,
-  offsetToLine,
-  parse,
-  splitSourceLines,
-} from './ast.js';
+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 = (