@ontrails/warden 1.0.0-beta.0

package/src/rules/scan.ts

@@ -0,0 +1,46 @@
+const TEST_FILE_PATTERN =
+  /(?:^|\/)__tests__(?:\/|$)|(?:\.test|\.spec)\.[cm]?[jt]sx?$/;
+
+const FRAMEWORK_INTERNAL_SEGMENTS = [
+  '/packages/testing/',
+  '/packages/warden/',
+] as const;
+
+const normalizeFilePath = (filePath: string): string =>
+  filePath.replaceAll('\\', '/');
+
+const maskText = (text: string): string => text.replaceAll(/[^\n]/g, ' ');
+
+const stripPattern = (sourceCode: string, pattern: RegExp): string =>
+  sourceCode.replaceAll(pattern, (match) => maskText(match));
+
+export const isTestFile = (filePath: string): boolean =>
+  TEST_FILE_PATTERN.test(normalizeFilePath(filePath));
+
+export const isFrameworkInternalFile = (filePath: string): boolean => {
+  const normalized = normalizeFilePath(filePath);
+  return FRAMEWORK_INTERNAL_SEGMENTS.some((segment) =>
+    normalized.includes(segment)
+  );
+};
+
+/**
+ * Replace quoted content and comments with whitespace while preserving line
+ * breaks so simple line-based scanners do not match examples or messages.
+ */
+export const stripQuotedContent = (sourceCode: string): string => {
+  let sanitized = sourceCode;
+  const patterns = [
+    /\/\/[^\n]*/g,
+    /\/\*[\s\S]*?\*\//g,
+    /'[^'\\\n]*(?:\\.[^'\\\n]*)*'/g,
+    /"[^"\\\n]*(?:\\.[^"\\\n]*)*"/g,
+    /`[\s\S]*?`/g,
+  ];
+
+  for (const pattern of patterns) {
+    sanitized = stripPattern(sanitized, pattern);
+  }
+
+  return sanitized;
+};

package/src/rules/specs.ts

@@ -0,0 +1,384 @@
+import {
+  captureBalanced,
+  lineNumberAt,
+  splitTopLevelEntriesWithOffsets,
+} from './structure.js';
+import type { SplitEntry } from './structure.js';
+
+export interface ParsedEntry {
+  readonly line: number;
+  readonly start: number;
+  readonly text: string;
+}
+
+export interface ObjectProperty extends ParsedEntry {
+  readonly key: string;
+  readonly value: string;
+}
+
+export interface TrailLikeSpec {
+  readonly id: string;
+  readonly kind: 'hike' | 'trail';
+  readonly line: number;
+  readonly properties: ReadonlyMap<string, ObjectProperty>;
+  readonly specText: string;
+  readonly start: number;
+}
+
+export interface SchemaFieldInfo {
+  readonly derivedLabel: string;
+  readonly options?: readonly string[] | undefined;
+  readonly required: boolean;
+}
+
+const TRAIL_LIKE_PATTERN = /\b(trail|hike)\s*\(/g;
+
+const PROPERTY_PATTERN =
+  /^(?:readonly\s+)?(?:(["'`])([^"'`]+)\1|([A-Za-z_$][\w$]*))\s*:\s*([\s\S]+)$/;
+
+const OPTIONALISH_PATTERN =
+  /(?:^|[^\w])z\.(?:default|nullish|optional)\s*\(|\.(?:default|nullish|optional)\s*\(/;
+
+const humanize = (str: string): string =>
+  str
+    .replaceAll(/([a-z])([A-Z])/g, '$1 $2')
+    .replaceAll(/([A-Z]+)([A-Z][a-z])/g, '$1 $2')
+    .replace(/^./, (ch) => ch.toUpperCase());
+
+const trimWrapped = (
+  text: string,
+  open: '{' | '[',
+  close: '}' | ']'
+): string | null => {
+  const trimmed = text.trim();
+  if (!trimmed.startsWith(open) || !trimmed.endsWith(close)) {
+    return null;
+  }
+
+  return trimmed.slice(1, -1);
+};
+
+const firstEntry = (text: string): SplitEntry | null => {
+  const [entry] = splitTopLevelEntriesWithOffsets(text);
+  return entry ?? null;
+};
+
+const createParsedEntry = (
+  sourceCode: string,
+  start: number,
+  text: string
+): ParsedEntry => ({
+  line: lineNumberAt(sourceCode, start),
+  start,
+  text,
+});
+
+const createObjectProperty = (
+  entry: SplitEntry,
+  key: string,
+  value: string,
+  objectStart: number,
+  objectOffset: number,
+  sourceCode: string
+): ObjectProperty => {
+  const start = objectStart + objectOffset + 1 + entry.start;
+  return {
+    key,
+    line: lineNumberAt(sourceCode, start),
+    start,
+    text: entry.text,
+    value,
+  };
+};
+
+const parsePropertyEntry = (
+  entry: SplitEntry,
+  objectStart: number,
+  objectOffset: number,
+  sourceCode: string
+): ObjectProperty | null => {
+  const propertyMatch = entry.text.match(PROPERTY_PATTERN);
+  const key = propertyMatch?.[2] ?? propertyMatch?.[3];
+  const value = propertyMatch?.[4]?.trim();
+  if (!key || !value) {
+    return null;
+  }
+
+  return createObjectProperty(
+    entry,
+    key,
+    value,
+    objectStart,
+    objectOffset,
+    sourceCode
+  );
+};
+
+const isDefined = <T>(value: T | null): value is T => value !== null;
+
+export const parseStringLiteral = (text: string): string | null => {
+  const trimmed = text.trim();
+  const [quote = ''] = trimmed;
+  const closer = quote === "'" || quote === '"' || quote === '`' ? quote : null;
+  if (closer === null || trimmed.at(-1) !== closer) {
+    return null;
+  }
+
+  const value = trimmed.slice(1, -1);
+  if (quote === '`' && value.includes('${')) {
+    return null;
+  }
+
+  return value;
+};
+
+export const parseArrayEntries = (
+  arrayText: string,
+  arrayStart: number,
+  sourceCode: string
+): readonly ParsedEntry[] => {
+  const inner = trimWrapped(arrayText, '[', ']');
+  if (inner === null) {
+    return [];
+  }
+
+  const arrayOffset = arrayText.indexOf('[');
+  return splitTopLevelEntriesWithOffsets(inner).map((entry) =>
+    createParsedEntry(
+      sourceCode,
+      arrayStart + arrayOffset + 1 + entry.start,
+      entry.text
+    )
+  );
+};
+
+export const parseObjectProperties = (
+  objectText: string,
+  objectStart: number,
+  sourceCode: string
+): ReadonlyMap<string, ObjectProperty> => {
+  const inner = trimWrapped(objectText, '{', '}');
+  if (inner === null) {
+    return new Map();
+  }
+
+  const objectOffset = objectText.indexOf('{');
+  const properties = splitTopLevelEntriesWithOffsets(inner)
+    .map((entry) =>
+      parsePropertyEntry(entry, objectStart, objectOffset, sourceCode)
+    )
+    .filter(isDefined);
+
+  return new Map(properties.map((property) => [property.key, property]));
+};
+
+const resolveSpecTarget = (
+  args: readonly SplitEntry[]
+): { id: string | null; specArg: SplitEntry } | null => {
+  const [firstArg, secondArg] = args;
+  if (!firstArg) {
+    return null;
+  }
+
+  const id = parseStringLiteral(firstArg.text);
+  return {
+    id,
+    specArg: id === null ? firstArg : (secondArg ?? firstArg),
+  };
+};
+
+const parseCallArguments = (
+  sourceCode: string,
+  callStart: number
+): { argsStart: number; argsText: string } | null => {
+  const openParen = sourceCode.indexOf('(', callStart);
+  const call = openParen === -1 ? null : captureBalanced(sourceCode, openParen);
+  if (call === null || openParen === -1) {
+    return null;
+  }
+
+  return {
+    argsStart: openParen + 1,
+    argsText: call.text.slice(1, -1),
+  };
+};
+
+const isSpecObject = (entry: SplitEntry | undefined): entry is SplitEntry =>
+  entry !== undefined && entry.text.trim().startsWith('{');
+
+const resolveSpecId = (
+  resolved: { id: string | null; specArg: SplitEntry },
+  properties: ReadonlyMap<string, ObjectProperty>
+): string | null =>
+  resolved.id ?? parseStringLiteral(properties.get('id')?.value ?? '');
+
+const buildTrailLikeSpec = (
+  sourceCode: string,
+  kind: 'hike' | 'trail',
+  specArg: SplitEntry,
+  specStart: number,
+  id: string,
+  properties: ReadonlyMap<string, ObjectProperty>
+): TrailLikeSpec => ({
+  id,
+  kind,
+  line: lineNumberAt(sourceCode, specStart),
+  properties,
+  specText: specArg.text,
+  start: specStart,
+});
+
+const parseResolvedSpec = (
+  sourceCode: string,
+  resolved: { id: string | null; specArg: SplitEntry },
+  call: { argsStart: number; argsText: string }
+): {
+  id: string;
+  properties: ReadonlyMap<string, ObjectProperty>;
+  specStart: number;
+} | null => {
+  const specStart = call.argsStart + resolved.specArg.start;
+  const properties = parseObjectProperties(
+    resolved.specArg.text,
+    specStart,
+    sourceCode
+  );
+  const id = resolveSpecId(resolved, properties);
+  return id === null ? null : { id, properties, specStart };
+};
+
+const resolveTrailLikeSpec = (
+  sourceCode: string,
+  callStart: number
+): {
+  parsed: {
+    id: string;
+    properties: ReadonlyMap<string, ObjectProperty>;
+    specStart: number;
+  };
+  resolved: { id: string | null; specArg: SplitEntry };
+} | null => {
+  const call = parseCallArguments(sourceCode, callStart);
+  if (call === null) {
+    return null;
+  }
+
+  const resolved = resolveSpecTarget(
+    splitTopLevelEntriesWithOffsets(call.argsText)
+  );
+  if (!resolved || !isSpecObject(resolved.specArg)) {
+    return null;
+  }
+
+  const parsed = parseResolvedSpec(sourceCode, resolved, call);
+  return parsed === null ? null : { parsed, resolved };
+};
+
+const parseTrailLikeMatch = (
+  sourceCode: string,
+  kind: 'hike' | 'trail',
+  callStart: number
+): TrailLikeSpec | null => {
+  const resolved = resolveTrailLikeSpec(sourceCode, callStart);
+  if (resolved === null) {
+    return null;
+  }
+
+  return buildTrailLikeSpec(
+    sourceCode,
+    kind,
+    resolved.resolved.specArg,
+    resolved.parsed.specStart,
+    resolved.parsed.id,
+    resolved.parsed.properties
+  );
+};
+
+const findCallArguments = (
+  sourceText: string,
+  pattern: RegExp
+): string | null => {
+  const index = pattern.exec(sourceText)?.index;
+  if (index === undefined) {
+    return null;
+  }
+
+  return parseCallArguments(sourceText, index)?.argsText ?? null;
+};
+
+const parseStringArrayLiteral = (
+  arrayText: string
+): readonly string[] | null => {
+  const inner = trimWrapped(arrayText, '[', ']');
+  if (inner === null) {
+    return null;
+  }
+
+  const values = splitTopLevelEntriesWithOffsets(inner).map((entry) =>
+    parseStringLiteral(entry.text)
+  );
+  const strings = values.filter((value): value is string => value !== null);
+  return strings.length === values.length ? strings : null;
+};
+
+const parseDescribeLabel = (fieldText: string): string | undefined => {
+  const args = findCallArguments(fieldText, /\.describe\s*\(/);
+  return args === null ? undefined : (parseStringLiteral(args) ?? undefined);
+};
+
+const parseEnumValues = (fieldText: string): readonly string[] | undefined => {
+  const args = findCallArguments(fieldText, /\bz\.enum\s*\(/);
+  const entry = args === null ? null : firstEntry(args);
+  return entry ? (parseStringArrayLiteral(entry.text) ?? undefined) : undefined;
+};
+
+const toSchemaFieldInfo = (
+  key: string,
+  property: ObjectProperty
+): SchemaFieldInfo => ({
+  derivedLabel: parseDescribeLabel(property.value) ?? humanize(key),
+  options: parseEnumValues(property.value),
+  required: !OPTIONALISH_PATTERN.test(property.value),
+});
+
+export const findTrailLikeSpecs = (
+  sourceCode: string
+): readonly TrailLikeSpec[] => {
+  const specs: TrailLikeSpec[] = [];
+
+  for (const match of sourceCode.matchAll(TRAIL_LIKE_PATTERN)) {
+    const callStart = match.index;
+    if (callStart === undefined) {
+      continue;
+    }
+
+    const kind = match[1] === 'hike' ? 'hike' : 'trail';
+    const spec = parseTrailLikeMatch(sourceCode, kind, callStart);
+    if (spec !== null) {
+      specs.push(spec);
+    }
+  }
+
+  return specs;
+};
+
+export const collectTrailIds = (sourceCode: string): ReadonlySet<string> =>
+  new Set(findTrailLikeSpecs(sourceCode).map((spec) => spec.id));
+
+export const parseZodObjectShape = (
+  schemaText: string
+): ReadonlyMap<string, SchemaFieldInfo> => {
+  const args = findCallArguments(schemaText, /\bz\.object\s*\(/);
+  const shapeEntry = args === null ? null : firstEntry(args);
+  if (!shapeEntry || !shapeEntry.text.trim().startsWith('{')) {
+    return new Map();
+  }
+
+  const shape = parseObjectProperties(shapeEntry.text, 0, shapeEntry.text);
+  return new Map(
+    [...shape.entries()].map(([key, property]) => [
+      key,
+      toSchemaFieldInfo(key, property),
+    ])
+  );
+};

package/src/rules/structure.ts

@@ -0,0 +1,234 @@
+type QuoteMode = '"' | "'" | '`' | null;
+
+interface ScanState {
+  braceDepth: number;
+  bracketDepth: number;
+  escaped: boolean;
+  parenDepth: number;
+  quoteMode: QuoteMode;
+}
+
+type DepthKey = 'braceDepth' | 'bracketDepth' | 'parenDepth';
+
+interface BalancedSegment {
+  readonly end: number;
+  readonly text: string;
+}
+
+export interface SplitEntry {
+  readonly start: number;
+  readonly text: string;
+}
+
+const createState = (): ScanState => ({
+  braceDepth: 0,
+  bracketDepth: 0,
+  escaped: false,
+  parenDepth: 0,
+  quoteMode: null,
+});
+
+const enterQuote = (ch: string): QuoteMode => {
+  if (ch === "'" || ch === '"' || ch === '`') {
+    return ch;
+  }
+  return null;
+};
+
+const clearEscape = (state: ScanState): boolean => {
+  if (!state.escaped) {
+    return false;
+  }
+
+  state.escaped = false;
+  return true;
+};
+
+const beginEscape = (state: ScanState, ch: string): boolean => {
+  if (ch !== '\\') {
+    return false;
+  }
+
+  state.escaped = true;
+  return true;
+};
+
+const closeQuote = (state: ScanState, ch: string): void => {
+  if (ch === state.quoteMode) {
+    state.quoteMode = null;
+  }
+};
+
+const updateQuotedState = (state: ScanState, ch: string): boolean => {
+  if (state.quoteMode === null) {
+    return false;
+  }
+
+  if (clearEscape(state)) {
+    return true;
+  }
+
+  if (beginEscape(state, ch)) {
+    return true;
+  }
+
+  closeQuote(state, ch);
+  return true;
+};
+
+const STRUCTURAL_DELTAS = {
+  '(': ['parenDepth', 1],
+  ')': ['parenDepth', -1],
+  '[': ['bracketDepth', 1],
+  ']': ['bracketDepth', -1],
+  '{': ['braceDepth', 1],
+  '}': ['braceDepth', -1],
+} as const satisfies Record<string, readonly [DepthKey, number]>;
+
+const updateStructuralDepth = (state: ScanState, ch: string): void => {
+  if (!(ch in STRUCTURAL_DELTAS)) {
+    return;
+  }
+
+  const delta = STRUCTURAL_DELTAS[ch as keyof typeof STRUCTURAL_DELTAS];
+  const [key, amount] = delta;
+  state[key] += amount;
+};
+
+const isTopLevel = (state: ScanState): boolean =>
+  state.braceDepth === 0 &&
+  state.bracketDepth === 0 &&
+  state.parenDepth === 0 &&
+  state.quoteMode === null;
+
+const scanCharacter = (state: ScanState, ch: string): void => {
+  if (updateQuotedState(state, ch)) {
+    return;
+  }
+
+  const nextQuoteMode = enterQuote(ch);
+  if (nextQuoteMode !== null) {
+    state.quoteMode = nextQuoteMode;
+    return;
+  }
+
+  updateStructuralDepth(state, ch);
+};
+
+const isBalancedOpener = (ch: string | undefined): boolean =>
+  ch === '{' || ch === '[' || ch === '(';
+
+const appendBalancedCharacter = (
+  sourceText: string,
+  state: ScanState,
+  index: number,
+  text: string
+): string => {
+  const ch = sourceText[index];
+  if (!ch) {
+    return text;
+  }
+
+  scanCharacter(state, ch);
+  return `${text}${ch}`;
+};
+
+export const captureBalanced = (
+  sourceText: string,
+  startIndex: number
+): BalancedSegment | null => {
+  if (!isBalancedOpener(sourceText[startIndex])) {
+    return null;
+  }
+
+  const state = createState();
+  let text = '';
+
+  for (let index = startIndex; index < sourceText.length; index += 1) {
+    text = appendBalancedCharacter(sourceText, state, index, text);
+
+    if (index > startIndex && isTopLevel(state)) {
+      return { end: index, text };
+    }
+  }
+
+  return null;
+};
+
+export const lineNumberAt = (sourceText: string, startIndex: number): number =>
+  sourceText.slice(0, startIndex).split('\n').length;
+
+const createSplitEntry = (
+  sourceText: string,
+  startIndex: number,
+  endIndex: number
+): SplitEntry | null => {
+  const raw = sourceText.slice(startIndex, endIndex);
+  const firstContent = raw.search(/\S/);
+  if (firstContent === -1) {
+    return null;
+  }
+
+  const trailingWhitespace = raw.match(/\s*$/)?.[0].length ?? 0;
+  const trimmedEnd = raw.length - trailingWhitespace;
+
+  return {
+    start: startIndex + firstContent,
+    text: raw.slice(firstContent, trimmedEnd),
+  };
+};
+
+const pushSplitEntry = (
+  entries: SplitEntry[],
+  sourceText: string,
+  startIndex: number,
+  endIndex: number
+): void => {
+  const entry = createSplitEntry(sourceText, startIndex, endIndex);
+  if (entry !== null) {
+    entries.push(entry);
+  }
+};
+
+const processSplitCharacter = (
+  entries: SplitEntry[],
+  sourceText: string,
+  state: ScanState,
+  entryStart: number,
+  index: number
+): number => {
+  const ch = sourceText[index];
+  if (!ch) {
+    return entryStart;
+  }
+
+  if (ch === ',' && isTopLevel(state)) {
+    pushSplitEntry(entries, sourceText, entryStart, index);
+    return index + 1;
+  }
+
+  scanCharacter(state, ch);
+  return entryStart;
+};
+
+export const splitTopLevelEntriesWithOffsets = (
+  sourceText: string
+): SplitEntry[] => {
+  const entries: SplitEntry[] = [];
+  const state = createState();
+  let entryStart = 0;
+
+  for (let index = 0; index < sourceText.length; index += 1) {
+    entryStart = processSplitCharacter(
+      entries,
+      sourceText,
+      state,
+      entryStart,
+      index
+    );
+  }
+
+  pushSplitEntry(entries, sourceText, entryStart, sourceText.length);
+
+  return entries;
+};

package/src/rules/types.ts

@@ -0,0 +1,62 @@
+/**
+ * Severity level for warden diagnostics.
+ */
+export type WardenSeverity = 'error' | 'warn';
+
+/**
+ * A single diagnostic reported by a warden rule.
+ */
+export interface WardenDiagnostic {
+  /** Rule identifier, e.g. "no-throw-in-implementation" */
+  readonly rule: string;
+  /** Severity level */
+  readonly severity: WardenSeverity;
+  /** Human-readable message describing the violation */
+  readonly message: string;
+  /** 1-based line number where the violation was detected */
+  readonly line: number;
+  /** File path that was analyzed */
+  readonly filePath: string;
+}
+
+/**
+ * A warden rule is a function that analyzes source code and returns diagnostics.
+ *
+ * Rules use string/regex analysis (not full AST parsing) to detect patterns
+ * that violate Trails conventions.
+ */
+export interface WardenRule {
+  /** Unique rule identifier */
+  readonly name: string;
+  /** Default severity */
+  readonly severity: WardenSeverity;
+  /** Human-readable description of what the rule enforces */
+  readonly description: string;
+  /** Run the rule against source code and return any diagnostics */
+  readonly check: (
+    sourceCode: string,
+    filePath: string
+  ) => readonly WardenDiagnostic[];
+}
+
+/**
+ * Options for cross-file rules that need knowledge of all trail IDs in a project.
+ */
+export interface ProjectContext {
+  /** All known trail IDs in the project */
+  readonly knownTrailIds: ReadonlySet<string>;
+  /** All trail IDs referenced as detour targets across the project */
+  readonly detourTargetTrailIds?: ReadonlySet<string>;
+}
+
+/**
+ * A project-aware rule that requires knowledge of all trail IDs.
+ */
+export interface ProjectAwareWardenRule extends WardenRule {
+  /** Run the rule with project-level context */
+  readonly checkWithContext: (
+    sourceCode: string,
+    filePath: string,
+    context: ProjectContext
+  ) => readonly WardenDiagnostic[];
+}