@ontrails/warden 1.0.0-beta.14 → 1.0.0-beta.16

package/src/index.ts

@@ -9,36 +9,86 @@
 
 // Rule types
 export type {
+  BuiltinWardenRuleName,
   ProjectAwareWardenRule,
   ProjectContext,
+  TopoAwareWardenRule,
   WardenDiagnostic,
+  WardenGuidance,
+  WardenGuidanceLink,
   WardenRule,
+  WardenRuleConcern,
+  WardenRuleLifecycle,
+  WardenRuleLifecycleState,
+  WardenRuleMetadata,
+  WardenRuleScope,
+  WardenRuleTier,
   WardenSeverity,
 } from './rules/index.js';
 
-// Individual rules
-export { noThrowInImplementation } from './rules/no-throw-in-implementation.js';
-export { contextNoTrailheadTypes } from './rules/context-no-trailhead-types.js';
-export { draftFileMarking } from './rules/draft-file-marking.js';
-export { draftVisibleDebt } from './rules/draft-visible-debt.js';
-export { validDetourRefs } from './rules/valid-detour-refs.js';
-export { noDirectImplInRoute } from './rules/no-direct-impl-in-route.js';
-export { noDirectImplementationCall } from './rules/no-direct-implementation-call.js';
-export { noSyncResultAssumption } from './rules/no-sync-result-assumption.js';
-export { implementationReturnsResult } from './rules/implementation-returns-result.js';
-export { noThrowInDetourTarget } from './rules/no-throw-in-detour-target.js';
-export { preferSchemaInference } from './rules/prefer-schema-inference.js';
-export { provisionDeclarations } from './rules/provision-declarations.js';
-export { provisionExists } from './rules/provision-exists.js';
-export { validDescribeRefs } from './rules/valid-describe-refs.js';
-
 // Rule registry
-export { wardenRules } from './rules/index.js';
+export {
+  builtinWardenRuleMetadata,
+  getWardenRuleMetadata,
+  listWardenRuleMetadata,
+  wardenRuleConcerns,
+  wardenRuleLifecycleStates,
+  wardenRuleScopes,
+  wardenRuleTiers,
+  wardenRules,
+  wardenTopoRules,
+} from './rules/index.js';
+
+// Rule-scoped cache controls for long-lived consumers (watch mode, LSPs).
+export { clearImplementationReturnsResultCache } from './rules/implementation-returns-result.js';
 
 // CLI runner
-export type { WardenOptions, WardenReport } from './cli.js';
+export type {
+  WardenOptions,
+  WardenReport,
+  WardenRunOptions,
+  WardenTopoTarget,
+} from './cli.js';
 export { formatWardenReport, runWarden } from './cli.js';
 
+// CLI command surface
+export type {
+  ParsedWardenCommand,
+  RunWardenCommandOptions,
+  WardenCommandResult,
+} from './command.js';
+export {
+  formatWardenCommandOutput,
+  loadWardenConfig,
+  parseWardenCommandArgs,
+  resolveWardenTopoTargets,
+  runWardenCommand,
+} from './command.js';
+
+// Config schema
+export {
+  wardenConfigSchema,
+  wardenDepthValues,
+  wardenDraftsValues,
+  wardenFailOnValues,
+  wardenFormatValues,
+  wardenLockValues,
+} from './config.js';
+export type {
+  WardenConfig,
+  WardenConfigInput,
+  WardenDepth,
+  WardenDraftsMode,
+  WardenFailOn,
+  WardenFormat,
+  WardenLockMode,
+  EffectiveWardenConfig,
+  ResolveWardenConfigOptions,
+  WardenConfigLayer,
+  WardenConfigResolution,
+} from './config.js';
+export { resolveWardenConfig } from './config.js';
+
 // CI formatters
 export {
   formatGitHubAnnotations,
@@ -50,6 +100,35 @@ export {
 export type { DriftResult } from './drift.js';
 export { checkDrift } from './drift.js';
 
+// Guide projection
+export type {
+  WardenGuideFormat,
+  WardenGuideManifest,
+  WardenRuleGuideEntry,
+} from './guide.js';
+export {
+  buildWardenAgentGuide,
+  buildWardenGuideManifest,
+  formatWardenGuide,
+  formatWardenGuideMarkdown,
+  wardenGuideFormatValues,
+} from './guide.js';
+
+// Resolver helpers
+export {
+  collectImportResolutionsForFile,
+  collectImportSpecifiers,
+  createWardenResolver,
+  defaultWardenResolveOptions,
+} from './resolve.js';
+export type {
+  WardenImportResolution,
+  WardenImportResolutionErrorKind,
+  WardenImportSpecifier,
+  WardenProjectResolver,
+  WardenResolverOptions,
+} from './resolve.js';
+
 // Draft helpers
 export {
   DRAFT_FILE_PREFIX,
@@ -58,36 +137,70 @@ export {
   stripDraftFileMarkers,
 } from './draft.js';
 
-// AST helpers for repo-local tooling
-export {
-  findStringLiterals,
-  getStringValue,
-  isStringLiteral,
-  offsetToLine,
-  parse,
-  walk,
-} from './rules/ast.js';
-export type { AstNode, StringLiteralMatch } from './rules/ast.js';
-
-// Trail gate
+// Trail layer
 export { wardenTopo } from './trails/topo.js';
-export { runWardenTrails } from './trails/run.js';
+export { runTopoAwareWardenTrails, runWardenTrails } from './trails/run.js';
 export {
-  contextNoTrailheadTypesTrail,
+  activationOrphanTrail,
+  circularRefsTrail,
+  contourExistsTrail,
+  contextNoSurfaceTypesTrail,
   crossDeclarationsTrail,
+  deadInternalTrailTrail,
   diagnosticSchema,
+  draftFileMarkingTrail,
+  draftVisibleDebtTrail,
+  errorMappingCompletenessTrail,
+  exampleValidTrail,
+  firesDeclarationsTrail,
   implementationReturnsResultTrail,
-  noDirectImplInRouteTrail,
+  incompleteAccessorForStandardOpTrail,
+  incompleteCrudTrail,
+  intentPropagationTrail,
+  layerFieldNameDriftTrail,
+  missingVisibilityTrail,
+  missingReconcileTrail,
+  noDevPermitInSourceTrail,
   noDirectImplementationCallTrail,
+  noLegacyLayerImportsTrail,
+  noNativeErrorResultTrail,
   noSyncResultAssumptionTrail,
-  noThrowInDetourTargetTrail,
+  noThrowInDetourRecoverTrail,
   noThrowInImplementationTrail,
+  onReferencesExistTrail,
+  orphanedSignalTrail,
+  ownerProjectionParityTrail,
+  permitGovernanceTrail,
   preferSchemaInferenceTrail,
+  projectAwareRuleInput,
+  publicInternalDeepImportsTrail,
+  publicOutputSchemaTrail,
+  publicUnionOutputDiscriminantsTrail,
+  readIntentFiresTrail,
+  referenceExistsTrail,
+  resolvedImportBoundaryTrail,
   ruleInput,
   ruleOutput,
-  provisionDeclarationsTrail,
-  provisionExistsTrail,
+  resourceDeclarationsTrail,
+  resourceIdGrammarTrail,
+  resourceExistsTrail,
+  scheduledDestroyIntentTrail,
+  signalGraphCoachingTrail,
+  staticResourceAccessorPreferenceTrail,
+  unmaterializedActivationSourceTrail,
+  topoAwareRuleInput,
+  unreachableDetourShadowingTrail,
+  validDetourContractTrail,
   validDescribeRefsTrail,
-  validDetourRefsTrail,
+  wardenExportSymmetryTrail,
+  wardenRulesUseAstTrail,
+  webhookRouteCollisionTrail,
+  wrapRule,
+  wrapTopoRule,
+} from './trails/index.js';
+export type {
+  ProjectAwareRuleInput,
+  RuleInput,
+  RuleOutput,
+  TopoAwareRuleInput,
 } from './trails/index.js';
-export type { RuleInput, RuleOutput } from './trails/index.js';

package/src/project-context.ts

@@ -0,0 +1,163 @@
+/**
+ * Project-context helpers shared by the Warden runner and resolver-backed
+ * rules.
+ */
+
+import { realpathSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+import {
+  collectImportResolutionsForFile,
+  createWardenResolver,
+  normalizePath,
+} from './resolve.js';
+import type {
+  WardenImportResolution,
+  WardenResolverOptions,
+} from './resolve.js';
+import { offsetToLine } from './rules/ast.js';
+import { collectPublicWorkspaces } from './workspaces.js';
+import type { WardenPublicWorkspace } from './workspaces.js';
+
+const ONTRAILS_DOCUMENTATION_SPECIFIER_PATTERN =
+  /@ontrails\/[a-z0-9-]+(?:\/[A-Za-z0-9._~-]+)+/g;
+
+const normalizeRealPath = (path: string): string => {
+  try {
+    return normalizePath(realpathSync(path));
+  } catch {
+    return normalizePath(resolve(path));
+  }
+};
+
+const setResolutionsForFile = (
+  resolutionsByFile: Map<string, readonly WardenImportResolution[]>,
+  sourceFilePath: string,
+  resolutions: readonly WardenImportResolution[]
+): void => {
+  const normalizedFilePath =
+    resolutions[0]?.importerPath ?? normalizeRealPath(sourceFilePath);
+  resolutionsByFile.set(normalizedFilePath, resolutions);
+  if (normalizedFilePath !== sourceFilePath) {
+    resolutionsByFile.set(sourceFilePath, resolutions);
+  }
+};
+
+export interface WardenProjectContextSourceFile {
+  readonly filePath: string;
+  readonly kind: 'documentation' | 'text' | 'typescript';
+  readonly sourceCode: string;
+}
+
+const collectDocumentationImportSpecifiers = (
+  sourceCode: string
+): readonly { readonly importSource: string; readonly line: number }[] => {
+  const specifiers: { importSource: string; line: number }[] = [];
+  for (const match of sourceCode.matchAll(
+    ONTRAILS_DOCUMENTATION_SPECIFIER_PATTERN
+  )) {
+    if (match.index === undefined) {
+      continue;
+    }
+    specifiers.push({
+      importSource: match[0],
+      line: offsetToLine(sourceCode, match.index),
+    });
+  }
+  return specifiers;
+};
+
+const exportAliasesForWorkspaces = (
+  workspaces: ReadonlyMap<string, WardenPublicWorkspace>
+): Record<string, string[]> => {
+  const aliases: Record<string, string[]> = {};
+  for (const workspace of workspaces.values()) {
+    for (const [specifier, target] of Object.entries(
+      workspace.exportTargets ?? {}
+    )) {
+      aliases[`${specifier}$`] = [target];
+    }
+  }
+  return aliases;
+};
+
+export const collectProjectImportResolutions = ({
+  resolveOptions,
+  rootDir,
+  sourceFiles,
+}: {
+  readonly resolveOptions?: WardenResolverOptions['resolveOptions'];
+  readonly rootDir: string;
+  readonly sourceFiles: readonly WardenProjectContextSourceFile[];
+}): ReadonlyMap<string, readonly WardenImportResolution[]> => {
+  const resolver = createWardenResolver({ resolveOptions, rootDir });
+  const resolutionsByFile = new Map<
+    string,
+    readonly WardenImportResolution[]
+  >();
+
+  for (const sourceFile of sourceFiles) {
+    if (sourceFile.kind !== 'typescript') {
+      continue;
+    }
+    const resolutions = collectImportResolutionsForFile({
+      filePath: sourceFile.filePath,
+      resolver,
+      sourceCode: sourceFile.sourceCode,
+    });
+    if (resolutions.length > 0) {
+      setResolutionsForFile(
+        resolutionsByFile,
+        sourceFile.filePath,
+        resolutions
+      );
+    }
+  }
+
+  return resolutionsByFile;
+};
+
+export const collectProjectDocumentationImportResolutions = ({
+  rootDir,
+  sourceFiles,
+}: {
+  readonly rootDir: string;
+  readonly sourceFiles: readonly WardenProjectContextSourceFile[];
+}): ReadonlyMap<string, readonly WardenImportResolution[]> => {
+  const publicWorkspaces = collectPublicWorkspaces(rootDir);
+  const resolver = createWardenResolver({
+    resolveOptions: { alias: exportAliasesForWorkspaces(publicWorkspaces) },
+    rootDir,
+  });
+  const resolutionsByFile = new Map<
+    string,
+    readonly WardenImportResolution[]
+  >();
+
+  for (const sourceFile of sourceFiles) {
+    if (sourceFile.kind !== 'documentation') {
+      continue;
+    }
+    const resolutions = collectDocumentationImportSpecifiers(
+      sourceFile.sourceCode
+    ).map((specifier) =>
+      resolver.resolveImport(
+        sourceFile.filePath,
+        specifier.importSource,
+        specifier.line
+      )
+    );
+    if (resolutions.length > 0) {
+      setResolutionsForFile(
+        resolutionsByFile,
+        sourceFile.filePath,
+        resolutions
+      );
+    }
+  }
+
+  return resolutionsByFile;
+};
+
+export { collectPublicWorkspaces };
+export type { WardenPublicWorkspace } from './workspaces.js';