@ontrails/warden 1.0.0-beta.2 → 1.0.0-beta.21

package/src/guide.ts

@@ -0,0 +1,245 @@
+import type {
+  WardenFixCapability,
+  WardenGuidance,
+  WardenGuidanceLink,
+  WardenRuleConcern,
+  WardenRuleLifecycle,
+  WardenRuleScope,
+  WardenRuleTier,
+  WardenSeverity,
+} from './rules/index.js';
+import {
+  listWardenRuleMetadata,
+  wardenRules,
+  wardenTopoRules,
+} from './rules/index.js';
+import type { WardenDepth } from './config.js';
+
+export const wardenGuideFormatValues = [
+  'markdown',
+  'agent-json',
+  'manifest',
+] as const;
+
+export type WardenGuideFormat = (typeof wardenGuideFormatValues)[number];
+
+export interface WardenRuleGuideEntry {
+  readonly concern: WardenRuleConcern;
+  readonly depth: WardenDepth;
+  readonly description: string;
+  readonly docs: readonly WardenGuidanceLink[];
+  readonly fix?: WardenFixCapability | undefined;
+  readonly guidance?: WardenGuidance | undefined;
+  readonly id: string;
+  readonly invariant: string;
+  readonly lifecycle: WardenRuleLifecycle;
+  readonly scope: WardenRuleScope;
+  readonly severity: WardenSeverity;
+  readonly tier: WardenRuleTier;
+}
+
+export interface WardenGuideManifest {
+  readonly generatedFrom: {
+    readonly package: '@ontrails/warden';
+    readonly registries: readonly ['wardenRules', 'wardenTopoRules'];
+    readonly source: 'builtin-rule-metadata';
+  };
+  readonly kind: 'trails-warden-guide-manifest';
+  readonly ruleCount: number;
+  readonly rules: readonly WardenRuleGuideEntry[];
+  readonly version: 1;
+}
+
+interface WardenAgentRuleGuide {
+  readonly appliesAt: {
+    readonly depth: WardenDepth;
+    readonly scope: WardenRuleScope;
+    readonly tier: WardenRuleTier;
+  };
+  readonly concern: WardenRuleConcern;
+  readonly fix?: WardenFixCapability | undefined;
+  readonly guidance?: WardenGuidance | undefined;
+  readonly id: string;
+  readonly invariant: string;
+  readonly severity: WardenSeverity;
+}
+
+interface WardenAgentGuide {
+  readonly instructions: readonly string[];
+  readonly kind: 'trails-warden-agent-guide';
+  readonly rules: readonly WardenAgentRuleGuide[];
+  readonly version: 1;
+}
+
+const lookupRule = (id: string) =>
+  wardenRules.get(id) ?? wardenTopoRules.get(id);
+
+const compareRuleEntries = (
+  [left]: readonly [string, unknown],
+  [right]: readonly [string, unknown]
+): number => left.localeCompare(right);
+
+export const buildWardenGuideManifest = (): WardenGuideManifest => {
+  const rules = listWardenRuleMetadata()
+    .toSorted(compareRuleEntries)
+    .map(([id, metadata]) => {
+      const rule = lookupRule(id);
+      const docs = metadata.guidance?.docs ?? [];
+      return {
+        concern: metadata.concern,
+        depth: metadata.depth,
+        description: rule?.description ?? '',
+        docs,
+        fix: metadata.fix,
+        guidance: metadata.guidance,
+        id,
+        invariant: metadata.invariant,
+        lifecycle: metadata.lifecycle,
+        scope: metadata.scope,
+        severity: rule?.severity ?? 'warn',
+        tier: metadata.tier,
+      } satisfies WardenRuleGuideEntry;
+    });
+
+  return {
+    generatedFrom: {
+      package: '@ontrails/warden',
+      registries: ['wardenRules', 'wardenTopoRules'],
+      source: 'builtin-rule-metadata',
+    },
+    kind: 'trails-warden-guide-manifest',
+    ruleCount: rules.length,
+    rules,
+    version: 1,
+  };
+};
+
+const formatGuideLink = (link: WardenGuidanceLink): string => {
+  if (link.path) {
+    return `[${link.label}](${link.path})`;
+  }
+  if (link.url) {
+    return `[${link.label}](${link.url})`;
+  }
+  return link.label;
+};
+
+const renderOptionalList = (
+  lines: string[],
+  label: string,
+  items: readonly string[] | undefined
+): void => {
+  if (items === undefined || items.length === 0) {
+    return;
+  }
+
+  lines.push(`- ${label}:`);
+  for (const [index, item] of items.entries()) {
+    lines.push(`  ${index + 1}. ${item}`);
+  }
+};
+
+const renderRuleMarkdown = (rule: WardenRuleGuideEntry): readonly string[] => {
+  const lines = [
+    `### \`${rule.id}\``,
+    '',
+    `- Severity: \`${rule.severity}\``,
+    `- Concern: \`${rule.concern}\``,
+    `- Depth: \`${rule.depth}\``,
+    `- Tier: \`${rule.tier}\``,
+    `- Scope: \`${rule.scope}\``,
+    `- Lifecycle: \`${rule.lifecycle.state}\``,
+    `- Invariant: ${rule.invariant}`,
+    `- Description: ${rule.description}`,
+  ];
+
+  if (rule.lifecycle.retireWhen) {
+    lines.push(`- Retire when: ${rule.lifecycle.retireWhen}`);
+  }
+
+  if (rule.fix) {
+    lines.push(
+      `- Fix: \`${rule.fix.class}\` (${rule.fix.safety === 'safe' ? 'safe, applied by `warden --fix`' : 'review-required'})`
+    );
+  }
+
+  if (rule.guidance) {
+    lines.push('', `Guidance: ${rule.guidance.summary}`);
+    renderOptionalList(lines, 'Steps', rule.guidance.steps);
+    renderOptionalList(lines, 'Commands', rule.guidance.commands);
+    if (rule.docs.length > 0) {
+      lines.push(`- Docs: ${rule.docs.map(formatGuideLink).join(', ')}`);
+    }
+    if (rule.guidance.relatedRules && rule.guidance.relatedRules.length > 0) {
+      lines.push(
+        `- Related rules: ${rule.guidance.relatedRules.map((id) => `\`${id}\``).join(', ')}`
+      );
+    }
+  }
+
+  return lines;
+};
+
+export const formatWardenGuideMarkdown = (
+  manifest: WardenGuideManifest
+): string => {
+  const lines = [
+    '# Trails Warden Guide',
+    '',
+    'Generated from `@ontrails/warden` built-in rule metadata and live rule registries.',
+    '',
+    '## Summary',
+    '',
+    `- Rules: ${manifest.ruleCount}`,
+    `- Guided rules: ${manifest.rules.filter((rule) => rule.guidance).length}`,
+    '',
+    '## Rules',
+    '',
+  ];
+
+  for (const rule of manifest.rules) {
+    lines.push(...renderRuleMarkdown(rule), '');
+  }
+
+  return lines.join('\n').trimEnd();
+};
+
+export const buildWardenAgentGuide = (
+  manifest: WardenGuideManifest
+): WardenAgentGuide => ({
+  instructions: [
+    'Treat Warden rules as enforceable Trails doctrine when working in this repository.',
+    'Prefer the rule guidance summary and ordered steps over diagnostic prose when deciding how to remediate a finding.',
+    'When guidance is absent, use the invariant, concern, tier, and scope as classification metadata rather than inventing a rule-specific fix.',
+  ],
+  kind: 'trails-warden-agent-guide',
+  rules: manifest.rules.map((rule) => ({
+    appliesAt: {
+      depth: rule.depth,
+      scope: rule.scope,
+      tier: rule.tier,
+    },
+    concern: rule.concern,
+    fix: rule.fix,
+    guidance: rule.guidance,
+    id: rule.id,
+    invariant: rule.invariant,
+    severity: rule.severity,
+  })),
+  version: 1,
+});
+
+export const formatWardenGuide = (
+  manifest: WardenGuideManifest,
+  format: WardenGuideFormat
+): string => {
+  if (format === 'markdown') {
+    return formatWardenGuideMarkdown(manifest);
+  }
+
+  if (format === 'agent-json') {
+    return JSON.stringify(buildWardenAgentGuide(manifest), null, 2);
+  }
+
+  return JSON.stringify(manifest, null, 2);
+};

package/src/index.ts

@@ -9,32 +9,105 @@
 
 // Rule types
 export type {
+  BuiltinWardenRuleName,
   ProjectAwareWardenRule,
   ProjectContext,
+  TopoAwareWardenRule,
   WardenDiagnostic,
+  WardenFix,
+  WardenFixCapability,
+  WardenFixClass,
+  WardenFixEdit,
+  WardenFixSafety,
+  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 { contextNoSurfaceTypes } from './rules/context-no-surface-types.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 { validDescribeRefs } from './rules/valid-describe-refs.js';
-
 // Rule registry
-export { wardenRules } from './rules/index.js';
+export {
+  builtinWardenRuleMetadata,
+  getWardenRuleMetadata,
+  listWardenRuleMetadata,
+  wardenFixClasses,
+  wardenFixSafeties,
+  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';
+export {
+  isWardenDevPermitTestScanTarget,
+  isWardenInfrastructureScanTarget,
+  isWardenSourceScanTarget,
+  isWardenTestScanTarget,
+} from './rules/scan.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';
 
+// Adapter authoring checks
+export {
+  adapterCheckRuleName,
+  runWardenAdapterChecks,
+} from './adapter-check.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,
@@ -45,3 +118,122 @@ export {
 // Drift detection
 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,
+  DRAFT_FILE_SEGMENT,
+  isDraftMarkedFile,
+  stripDraftFileMarkers,
+} from './draft.js';
+
+// Trail layer
+export { wardenTopo } from './trails/topo.js';
+export { runTopoAwareWardenTrails, runWardenTrails } from './trails/run.js';
+export {
+  activationOrphanTrail,
+  circularRefsTrail,
+  contourExistsTrail,
+  contextNoSurfaceTypesTrail,
+  composesDeclarationsTrail,
+  deadInternalTrailTrail,
+  deprecationWithoutGuidanceTrail,
+  diagnosticSchema,
+  draftFileMarkingTrail,
+  draftVisibleDebtTrail,
+  errorMappingCompletenessTrail,
+  exampleValidTrail,
+  firesDeclarationsTrail,
+  forkWithoutPreservedBlazeTrail,
+  implementationReturnsResultTrail,
+  incompleteAccessorForStandardOpTrail,
+  incompleteCrudTrail,
+  intentPropagationTrail,
+  layerFieldNameDriftTrail,
+  markerSchemaUnsupportedTrail,
+  missingVisibilityTrail,
+  missingReconcileTrail,
+  noDevPermitInSourceTrail,
+  noDestructuredComposeTrail,
+  noDirectImplementationCallTrail,
+  noLegacyLayerImportsTrail,
+  noNativeErrorResultTrail,
+  noRedundantResultErrorWrapTrail,
+  noRetiredCrossVocabularyTrail,
+  noSyncResultAssumptionTrail,
+  noThrowInDetourRecoverTrail,
+  noThrowInImplementationTrail,
+  noTopLevelSurfaceTrail,
+  onReferencesExistTrail,
+  orphanedSignalTrail,
+  ownerProjectionParityTrail,
+  pendingForceTrail,
+  permitGovernanceTrail,
+  preferSchemaInferenceTrail,
+  projectAwareRuleInput,
+  publicExportExampleCoverageTrail,
+  publicInternalDeepImportsTrail,
+  publicOutputSchemaTrail,
+  publicUnionOutputDiscriminantsTrail,
+  readIntentFiresTrail,
+  referenceExistsTrail,
+  resolvedImportBoundaryTrail,
+  ruleInput,
+  ruleOutput,
+  resourceDeclarationsTrail,
+  resourceIdGrammarTrail,
+  resourceExistsTrail,
+  resourceMockCoverageTrail,
+  scheduledDestroyIntentTrail,
+  signalGraphCoachingTrail,
+  staticResourceAccessorPreferenceTrail,
+  surfaceFacetCoherenceTrail,
+  unmaterializedActivationSourceTrail,
+  topoAwareRuleInput,
+  unreachableDetourShadowingTrail,
+  validDetourContractTrail,
+  validDescribeRefsTrail,
+  versionGapTrail,
+  versionPinnedComposeTrail,
+  versionWithoutExamplesTrail,
+  wardenExportSymmetryTrail,
+  wardenRulesUseAstTrail,
+  webhookRouteCollisionTrail,
+  wrapRule,
+  wrapTopoRule,
+} from './trails/index.js';
+export type {
+  ProjectAwareRuleInput,
+  RuleInput,
+  RuleOutput,
+  TopoAwareRuleInput,
+} 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';