@ontrails/warden 0.2.0

package/src/formatters.ts

@@ -0,0 +1,178 @@
+/**
+ * CI-oriented formatters for warden reports.
+ *
+ * Each formatter takes a `WardenReport` and produces output suited to a
+ * specific CI environment: GitHub Actions annotations, structured JSON,
+ * or a concise markdown summary.
+ */
+
+import type { WardenReport } from './cli.js';
+import { staleDriftMessage } from './drift.js';
+import type { WardenGuidanceLink, WardenSeverity } from './rules/types.js';
+
+/** Map warden severity to GitHub Actions annotation level. */
+const ghLevel: Record<WardenSeverity, string> = {
+  error: 'error',
+  warn: 'warning',
+};
+
+/**
+ * Produce GitHub Actions workflow command annotations, one per diagnostic.
+ *
+ * Severity mapping: `error` to `::error`, `warn` to `::warning`.
+ * Drift staleness or established-export blocking is emitted as a single
+ * `::error` annotation when detected.
+ */
+export const formatGitHubAnnotations = (report: WardenReport): string => {
+  const lines: string[] = [];
+
+  for (const d of report.diagnostics) {
+    const level = ghLevel[d.severity];
+    lines.push(
+      `::${level} file=${d.filePath},line=${String(d.line)}::${d.rule}: ${d.message}`
+    );
+  }
+
+  if (report.drift?.blockedReason !== undefined) {
+    lines.push(`::error::drift: ${report.drift.blockedReason}`);
+  } else if (report.drift?.stale) {
+    lines.push(`::error::drift: ${staleDriftMessage(report.drift)}`);
+  }
+
+  return lines.join('\n');
+};
+
+/**
+ * Produce a structured JSON string from the report.
+ *
+ * Includes a `summary` object with error, warning, and suggestion counts
+ * for easy consumption by downstream tooling.
+ */
+export const formatJson = (report: WardenReport): string => {
+  const summary = {
+    errors: report.errorCount,
+    suggestions: 0,
+    warnings: report.warnCount,
+  };
+
+  return JSON.stringify(
+    {
+      diagnostics: report.diagnostics,
+      drift: report.drift,
+      fixes: report.fixes,
+      passed: report.passed,
+      summary,
+    },
+    null,
+    2
+  );
+};
+
+const formatGuidanceLink = (link: WardenGuidanceLink): string => {
+  if (link.path !== undefined) {
+    return `[${link.label}](${link.path})`;
+  }
+  if (link.url !== undefined) {
+    return `[${link.label}](${link.url})`;
+  }
+  return link.label;
+};
+
+/** Format diagnostic guidance as indented markdown lines. */
+const diagnosticGuidanceLines = (
+  d: WardenReport['diagnostics'][number]
+): readonly string[] => {
+  const { guidance } = d;
+  if (guidance === undefined) {
+    return [];
+  }
+
+  const lines = [`  - Next: ${guidance.summary}`];
+  if (guidance.steps !== undefined && guidance.steps.length > 0) {
+    lines.push(
+      `  - Steps: ${guidance.steps
+        .map((step, index) => `${String(index + 1)}. ${step}`)
+        .join(' ')}`
+    );
+  }
+  if (guidance.docs !== undefined && guidance.docs.length > 0) {
+    lines.push(`  - Docs: ${guidance.docs.map(formatGuidanceLink).join(', ')}`);
+  }
+  if (guidance.commands !== undefined && guidance.commands.length > 0) {
+    lines.push(
+      `  - Commands: ${guidance.commands.map((cmd) => `\`${cmd}\``).join(', ')}`
+    );
+  }
+  if (guidance.relatedRules !== undefined && guidance.relatedRules.length > 0) {
+    lines.push(
+      `  - Related: ${guidance.relatedRules.map((rule) => `\`${rule}\``).join(', ')}`
+    );
+  }
+  return lines;
+};
+
+/** Format a diagnostic as markdown lines. */
+const diagnosticLines = (
+  d: WardenReport['diagnostics'][number]
+): readonly string[] => [
+  `- \`${d.filePath}:${String(d.line)}\` — ${d.rule}: ${d.message}`,
+  ...diagnosticGuidanceLines(d),
+];
+
+/** Render a severity group as a headed markdown section, or empty array. */
+const severitySection = (
+  heading: string,
+  diagnostics: WardenReport['diagnostics']
+): readonly string[] => {
+  if (diagnostics.length === 0) {
+    return [];
+  }
+  return ['', `### ${heading}`, ...diagnostics.flatMap(diagnosticLines)];
+};
+
+/** Render a drift section if stale, otherwise empty array. */
+const driftSection = (drift: WardenReport['drift']): readonly string[] => {
+  if (drift?.blockedReason !== undefined) {
+    return [
+      '',
+      '### Drift',
+      `- established exports are blocked: ${drift.blockedReason}`,
+    ];
+  }
+
+  if (!drift?.stale) {
+    return [];
+  }
+  return ['', '### Drift', `- ${staleDriftMessage(drift)}`];
+};
+
+/** Render safe-fix counts when a fix pass was requested. */
+const fixSummaryLine = (fixes: WardenReport['fixes']): readonly string[] => {
+  if (fixes === undefined) {
+    return [];
+  }
+  return [
+    `**Fixes:** ${String(fixes.applied)} applied, ${String(fixes.filesChanged)} files changed, ${String(fixes.skipped)} skipped`,
+  ];
+};
+
+/**
+ * Produce a concise markdown summary suitable for a GitHub job summary or PR comment.
+ *
+ * Groups diagnostics by severity and includes drift status when relevant.
+ */
+export const formatSummary = (report: WardenReport): string => {
+  const result = report.passed ? 'PASS' : 'FAIL';
+  const errors = report.diagnostics.filter((d) => d.severity === 'error');
+  const warnings = report.diagnostics.filter((d) => d.severity === 'warn');
+
+  return [
+    '## Warden Report',
+    '',
+    `**Result: ${result}** | ${String(report.errorCount)} errors, ${String(report.warnCount)} warnings`,
+    ...fixSummaryLine(report.fixes),
+    ...severitySection('Errors', errors),
+    ...severitySection('Warnings', warnings),
+    ...driftSection(report.drift),
+  ].join('\n');
+};

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

@@ -0,0 +1,295 @@
+/**
+ * Warden - Governance package for Trails.
+ *
+ * Provides lint rules, drift detection, and a CLI runner to enforce
+ * contract-first discipline at development time.
+ *
+ * Package: `@ontrails/warden`
+ */
+
+// Rule types
+export type {
+  BuiltinWardenRuleName,
+  GovernedVocabularyHistoryEvidence,
+  GovernedVocabularyHistoryFormJudgment,
+  GovernedVocabularyHistoryIssue,
+  ProjectAwareWardenRule,
+  ProjectContext,
+  TopoAwareWardenRule,
+  WardenDiagnostic,
+  WardenExportedSymbolDefinition,
+  WardenFix,
+  WardenFixCapability,
+  WardenFixClass,
+  WardenFixEdit,
+  WardenFixScanTargets,
+  WardenFixSafety,
+  WardenGuidance,
+  WardenGuidanceLink,
+  WardenRule,
+  WardenRuleConcern,
+  WardenRuleLifecycle,
+  WardenRuleLifecycleState,
+  WardenRuleMetadata,
+  WardenRuleScope,
+  WardenRuleTier,
+  WardenSeverity,
+} from './rules/index.js';
+
+// Rule registry
+export {
+  builtinWardenRuleMetadata,
+  formatGovernedVocabularyTransitionGuide,
+  getGovernedVocabularyTransition,
+  governedVocabularyLiteralRenameSchema,
+  governedVocabularyFileRenameSchema,
+  governedVocabularyHistoryProvenanceSchema,
+  governedVocabularyPreserveRuleSchema,
+  governedVocabularyProvenancePolicySchema,
+  governedVocabularyRegistrySchema,
+  governedVocabularyScopeSchema,
+  governedVocabularySymbolRenameSchema,
+  governedVocabularyTargetSchema,
+  governedVocabularyTransitionSchema,
+  governedVocabularyTransitionStatuses,
+  governedVocabularyTransitions,
+  getWardenRuleMetadata,
+  listWardenRuleMetadata,
+  listGovernedVocabularyTransitions,
+  requireGovernedVocabularyTransition,
+  wardenFixClasses,
+  wardenFixSafeties,
+  wardenRuleConcerns,
+  wardenRuleLifecycleStates,
+  wardenRuleScopes,
+  wardenRuleTiers,
+  wardenRules,
+  wardenTopoRules,
+} from './rules/index.js';
+export type {
+  GovernedVocabularyLiteralRename,
+  GovernedVocabularyHistoryProvenance,
+  GovernedVocabularyPreserveRule,
+  GovernedVocabularyProvenancePolicy,
+  GovernedVocabularyScope,
+  GovernedVocabularySymbolRename,
+  GovernedVocabularyTarget,
+  GovernedVocabularyTransition,
+  GovernedVocabularyTransitionInput,
+} 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,
+  WardenRunOptions,
+  WardenTopoDriftResult,
+  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,
+  WardenExpectedAppBinding,
+  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,
+  WardenScope,
+  WardenLockMode,
+  EffectiveWardenConfig,
+  ResolveWardenConfigOptions,
+  WardenConfigLayer,
+  WardenConfigResolution,
+} from './config.js';
+export { resolveWardenConfig } from './config.js';
+
+// CI formatters
+export {
+  formatGitHubAnnotations,
+  formatJson,
+  formatSummary,
+} from './formatters.js';
+
+// Drift detection
+export type { CheckDriftOptions, DriftResult } from './drift.js';
+export { checkDrift } from './drift.js';
+
+// Project-local rule loading
+export type { ProjectWardenRules } from './project-rules.js';
+export { loadProjectWardenRules } from './project-rules.js';
+
+// Guide rendering
+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 {
+  runProjectWardenRules,
+  runTopoAwareWardenTrails,
+  runWardenTrails,
+} from './trails/run.js';
+export {
+  activationOrphanTrail,
+  capturedKernelTrail,
+  cliCommandRouteCoherenceTrail,
+  circularRefsTrail,
+  entityExistsTrail,
+  contextNoSurfaceTypesTrail,
+  composesDeclarationsTrail,
+  deadInternalTrailTrail,
+  deadPublicTrailTrail,
+  deprecationWithoutGuidanceTrail,
+  diagnosticSchema,
+  duplicateExportedSymbolTrail,
+  duplicatePublicContractTrail,
+  draftFileMarkingTrail,
+  draftVisibleDebtTrail,
+  errorMappingCompletenessTrail,
+  exampleValidTrail,
+  firesDeclarationsTrail,
+  forkWithoutPreservedImplementationTrail,
+  governedSymbolResidueTrail,
+  governedVocabularyPermutationWatchTrail,
+  implementationReturnsResultTrail,
+  incompleteAccessorForStandardOpTrail,
+  incompleteCrudTrail,
+  intentPropagationTrail,
+  layerFieldNameDriftTrail,
+  libraryRenderCoherenceTrail,
+  markerSchemaUnsupportedTrail,
+  missingVisibilityTrail,
+  missingReconcileTrail,
+  noDevPermitInSourceTrail,
+  noDestructuredComposeTrail,
+  noDirectImplementationCallTrail,
+  noLegacyCliAliasExportTrail,
+  noLegacyLayerImportsTrail,
+  noNativeErrorResultTrail,
+  noRedundantResultErrorWrapTrail,
+  noRetiredCrossVocabularyTrail,
+  noSyncResultAssumptionTrail,
+  noThrowInDetourRecoverTrail,
+  noThrowInImplementationTrail,
+  noTopLevelSurfaceTrail,
+  onReferencesExistTrail,
+  orphanedSignalTrail,
+  ownerRenderParityTrail,
+  pendingForceTrail,
+  permitGovernanceTrail,
+  preferSchemaInferenceTrail,
+  projectAwareRuleInput,
+  publicExportExampleCoverageTrail,
+  publicInternalDeepImportsTrail,
+  publicOutputSchemaTrail,
+  publicUnionOutputDiscriminantsTrail,
+  readIntentFiresTrail,
+  referenceExistsTrail,
+  resolvedImportBoundaryTrail,
+  ruleInput,
+  ruleOutput,
+  resourceDeclarationsTrail,
+  resourceIdGrammarTrail,
+  resourceExistsTrail,
+  resourceMockCoverageTrail,
+  scheduledDestroyIntentTrail,
+  signalGraphCoachingTrail,
+  staticResourceAccessorPreferenceTrail,
+  surfaceOverlayCoherenceTrail,
+  surfaceTrailheadCoherenceTrail,
+  trailForkCoachingTrail,
+  trailheadOverrideDivergenceTrail,
+  unmaterializedActivationSourceTrail,
+  topoAwareRuleInput,
+  unreachableDetourShadowingTrail,
+  validDetourContractTrail,
+  validDescribeRefsTrail,
+  versionGapTrail,
+  versionPinnedComposeTrail,
+  versionWithoutExamplesTrail,
+  wardenExportSymmetryTrail,
+  wardenRulesUseAstTrail,
+  webhookRouteCollisionTrail,
+  workspaceLockOwnershipTrail,
+  wrapRule,
+  wrapTopoRule,
+} from './trails/index.js';
+export type {
+  ProjectAwareRuleInput,
+  RuleInput,
+  RuleOutput,
+  TopoAwareRuleInput,
+} from './trails/index.js';