@ontrails/warden 1.0.0-beta.0

package/src/rules/valid-describe-refs.ts

@@ -0,0 +1,94 @@
+import type {
+  ProjectAwareWardenRule,
+  ProjectContext,
+  WardenDiagnostic,
+} from './types.js';
+import { isTestFile } from './scan.js';
+import { collectTrailIds, parseStringLiteral } from './specs.js';
+import { captureBalanced, lineNumberAt } from './structure.js';
+
+const DESCRIBE_PATTERN = /\.describe\s*\(/g;
+
+const SEE_PATTERN = /@see\s+([A-Za-z0-9_.-]+)/g;
+
+interface DescribeRef {
+  readonly line: number;
+  readonly ref: string;
+}
+
+const describeTextAt = (
+  sourceCode: string,
+  matchIndex: number
+): string | null => {
+  const openParen = sourceCode.indexOf('(', matchIndex);
+  if (openParen === -1) {
+    return null;
+  }
+
+  return captureBalanced(sourceCode, openParen)?.text.slice(1, -1) ?? null;
+};
+
+const refsInDescription = (
+  description: string,
+  line: number
+): readonly DescribeRef[] =>
+  [...description.matchAll(SEE_PATTERN)].flatMap((see) =>
+    see[1] ? [{ line, ref: see[1] }] : []
+  );
+
+const refsForDescribe = (
+  sourceCode: string,
+  matchIndex: number
+): readonly DescribeRef[] => {
+  const args = describeTextAt(sourceCode, matchIndex);
+  const description = args ? parseStringLiteral(args) : null;
+  return description === null
+    ? []
+    : refsInDescription(description, lineNumberAt(sourceCode, matchIndex));
+};
+
+const collectDescribeRefs = (sourceCode: string): readonly DescribeRef[] =>
+  [...sourceCode.matchAll(DESCRIBE_PATTERN)].flatMap((match) =>
+    match.index === undefined ? [] : refsForDescribe(sourceCode, match.index)
+  );
+
+const checkDescribeRefs = (
+  sourceCode: string,
+  filePath: string,
+  knownTrailIds: ReadonlySet<string>
+): readonly WardenDiagnostic[] => {
+  if (isTestFile(filePath)) {
+    return [];
+  }
+
+  return collectDescribeRefs(sourceCode)
+    .filter(({ ref }) => !knownTrailIds.has(ref))
+    .map(({ line, ref }) => ({
+      filePath,
+      line,
+      message: `@see reference "${ref}" does not resolve to a defined trail.`,
+      rule: 'valid-describe-refs',
+      severity: 'warn' as const,
+    }));
+};
+
+/**
+ * Warns when @see references inside Zod .describe() strings point at unknown
+ * trails.
+ */
+export const validDescribeRefs: ProjectAwareWardenRule = {
+  check(sourceCode: string, filePath: string): readonly WardenDiagnostic[] {
+    return checkDescribeRefs(sourceCode, filePath, collectTrailIds(sourceCode));
+  },
+  checkWithContext(
+    sourceCode: string,
+    filePath: string,
+    context: ProjectContext
+  ): readonly WardenDiagnostic[] {
+    return checkDescribeRefs(sourceCode, filePath, context.knownTrailIds);
+  },
+  description:
+    'Ensure @see tags inside schema .describe() strings reference defined trails.',
+  name: 'valid-describe-refs',
+  severity: 'warn',
+};

package/src/rules/valid-detour-refs.ts

@@ -0,0 +1,187 @@
+import { collectTrailIds } from './specs.js';
+import type {
+  ProjectAwareWardenRule,
+  ProjectContext,
+  WardenDiagnostic,
+} from './types.js';
+
+interface BraceState {
+  depth: number;
+  found: boolean;
+}
+
+const trackBraces = (line: string, state: BraceState): void => {
+  for (const ch of line) {
+    if (ch === '{') {
+      state.depth += 1;
+      state.found = true;
+    }
+    if (ch === '}') {
+      state.depth -= 1;
+    }
+  }
+};
+
+const collectArrayText = (lines: readonly string[], start: number): string => {
+  let text = '';
+  for (let k = start; k < lines.length && k < start + 20; k += 1) {
+    const line = lines[k];
+    if (!line) {
+      continue;
+    }
+    text += `${line}\n`;
+    if (text.includes(']')) {
+      break;
+    }
+  }
+  return text;
+};
+
+const findMissingDetourTargets = (
+  text: string,
+  knownIds: ReadonlySet<string>
+): string[] => {
+  const missing: string[] = [];
+  for (const m of text.matchAll(/target\s*:\s*["'`]([^"'`]+)["'`]/g)) {
+    const [, id] = m;
+    if (id && !knownIds.has(id)) {
+      missing.push(id);
+    }
+  }
+  return missing;
+};
+
+const findMissingPlainDetours = (
+  text: string,
+  knownIds: ReadonlySet<string>
+): string[] => {
+  const missing: string[] = [];
+  const cleaned = text.replaceAll(/target\s*:\s*["'`][^"'`]+["'`]/g, '');
+  for (const m of cleaned.matchAll(/["'`]([^"'`]+)["'`]/g)) {
+    const [, id] = m;
+    if (id && id.includes('.') && !knownIds.has(id)) {
+      missing.push(id);
+    }
+  }
+  return missing;
+};
+
+const findAllMissingDetours = (
+  text: string,
+  knownIds: ReadonlySet<string>
+): string[] => [
+  ...findMissingDetourTargets(text, knownIds),
+  ...findMissingPlainDetours(text, knownIds),
+];
+
+const addMissingDetourDiagnostics = (
+  specLine: string,
+  j: number,
+  lines: readonly string[],
+  trailId: string,
+  lineNum: number,
+  filePath: string,
+  knownIds: ReadonlySet<string>,
+  diagnostics: WardenDiagnostic[]
+): void => {
+  if (!/\bdetours\s*:/.test(specLine)) {
+    return;
+  }
+  for (const targetId of findAllMissingDetours(
+    collectArrayText(lines, j),
+    knownIds
+  )) {
+    diagnostics.push({
+      filePath,
+      line: lineNum,
+      message: `Trail "${trailId}" has detour targeting "${targetId}" which is not defined.`,
+      rule: 'valid-detour-refs',
+      severity: 'error',
+    });
+  }
+};
+
+const scanTrailDetours = (
+  lines: readonly string[],
+  startIndex: number,
+  trailId: string,
+  filePath: string,
+  knownIds: ReadonlySet<string>,
+  diagnostics: WardenDiagnostic[]
+): void => {
+  const braceState: BraceState = { depth: 0, found: false };
+  for (let j = startIndex; j < lines.length && j < startIndex + 200; j += 1) {
+    const specLine = lines[j];
+    if (!specLine) {
+      continue;
+    }
+    trackBraces(specLine, braceState);
+    addMissingDetourDiagnostics(
+      specLine,
+      j,
+      lines,
+      trailId,
+      startIndex + 1,
+      filePath,
+      knownIds,
+      diagnostics
+    );
+    if (braceState.found && braceState.depth <= 0) {
+      break;
+    }
+  }
+};
+
+const processLine = (
+  line: string,
+  i: number,
+  lines: readonly string[],
+  filePath: string,
+  knownIds: ReadonlySet<string>,
+  diagnostics: WardenDiagnostic[]
+): void => {
+  const trailMatch = line.match(/\btrail\s*\(\s*["'`]([^"'`]+)["'`]/);
+  if (!trailMatch) {
+    return;
+  }
+  const [, trailId] = trailMatch;
+  if (!trailId) {
+    return;
+  }
+  scanTrailDetours(lines, i, trailId, filePath, knownIds, diagnostics);
+};
+
+const checkDetourRefs = (
+  sourceCode: string,
+  filePath: string,
+  knownIds: ReadonlySet<string>
+): readonly WardenDiagnostic[] => {
+  const diagnostics: WardenDiagnostic[] = [];
+  const lines = sourceCode.split('\n');
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i];
+    if (line) {
+      processLine(line, i, lines, filePath, knownIds, diagnostics);
+    }
+  }
+  return diagnostics;
+};
+
+/**
+ * Checks that all trail IDs referenced in `detours` declarations exist.
+ */
+export const validDetourRefs: ProjectAwareWardenRule = {
+  check(sourceCode: string, filePath: string): readonly WardenDiagnostic[] {
+    return checkDetourRefs(sourceCode, filePath, collectTrailIds(sourceCode));
+  },
+  checkWithContext(
+    sourceCode: string,
+    filePath: string,
+    context: ProjectContext
+  ): readonly WardenDiagnostic[] {
+    return checkDetourRefs(sourceCode, filePath, context.knownTrailIds);
+  },
+  description: 'Ensure all detour target trail IDs reference defined trails.',
+  name: 'valid-detour-refs',
+  severity: 'error',
+};

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"],
+  "exclude": ["**/__tests__/**", "**/*.test.ts", "dist"]
+}

package/tsconfig.tsbuildinfo

@@ -0,0 +1 @@
+{"root":["./src/cli.ts","./src/drift.ts","./src/formatters.ts","./src/index.ts","./src/rules/ast.ts","./src/rules/context-no-surface-types.ts","./src/rules/implementation-returns-result.ts","./src/rules/index.ts","./src/rules/no-direct-impl-in-route.ts","./src/rules/no-direct-implementation-call.ts","./src/rules/no-sync-result-assumption.ts","./src/rules/no-throw-in-detour-target.ts","./src/rules/no-throw-in-implementation.ts","./src/rules/prefer-schema-inference.ts","./src/rules/scan.ts","./src/rules/specs.ts","./src/rules/structure.ts","./src/rules/types.ts","./src/rules/valid-describe-refs.ts","./src/rules/valid-detour-refs.ts"],"version":"5.9.3"}