@ontrails/warden 0.2.0

package/src/rules/source/stores.ts

@@ -0,0 +1,310 @@
+/** Warden-private store/factory pattern helpers. */
+
+import {
+  extractBindingName,
+  findConfigProperty,
+  getPropertyName,
+  identifierName,
+  walk,
+} from '@ontrails/source';
+import type { AstNode } from '@ontrails/source';
+
+export interface StoreTableDefinition {
+  /** Table name declared inside store({ ... }). */
+  readonly name: string;
+  /**
+   * Local binding name of the enclosing `store(...)` declaration, if the
+   * `store(...)` call is bound to a `const`/`let`/`var` (e.g. `db` in
+   * `const db = store({ ... })`). Null for anonymous stores.
+   */
+  readonly storeBinding: string | null;
+  /**
+   * Stable composite key for this table in the form `${storeBinding}:${name}`,
+   * falling back to the bare `name` when the store is anonymous. Use this for
+   * compose-rule / compose-file keying so two stores with the same table name
+   * never collide.
+   */
+  readonly key: string;
+  /** Start offset of the table property declaration. */
+  readonly start: number;
+  /** Whether the authored table opts into version tracking. */
+  readonly versioned: boolean;
+}
+
+/**
+ * Build a composite key for a store table: `${storeBinding}:${tableName}`,
+ * falling back to the bare `tableName` when the enclosing store has no local
+ * binding. Centralized so rule keying stays stable.
+ *
+ * @remarks
+ * The key is intentionally file-local (no module path prefix). Compose-file
+ * aggregation in `ProjectContext` merges keys from all files, so two files
+ * with `const db = store({ notes: ... })` both produce `db:notes` — this is
+ * the desired behavior because the warden checks for *pattern completeness*
+ * across the project and matching keys signals that the same logical table
+ * is covered. If two genuinely different tables share a binding and name,
+ * that is a code-level naming collision the developer should resolve.
+ */
+export const makeStoreTableKey = (
+  storeBinding: string | null,
+  tableName: string
+): string => (storeBinding ? `${storeBinding}:${tableName}` : tableName);
+
+const isBooleanLiteral = (node: AstNode | undefined): boolean =>
+  Boolean(
+    node &&
+    ((node.type === 'BooleanLiteral' &&
+      (node as unknown as { value?: unknown }).value === true) ||
+      (node.type === 'Literal' &&
+        (node as unknown as { value?: unknown }).value === true))
+  );
+
+/**
+ * Check if a node is a `CallExpression` to the identifier `name`.
+ *
+ * e.g. `isNamedCall(node, 'store')` matches `store({...})` but not
+ * `someObj.store()` or `storeAlt()`.
+ */
+export const isNamedCall = (node: AstNode | undefined, name: string): boolean =>
+  !!node &&
+  node.type === 'CallExpression' &&
+  identifierName((node as unknown as { callee?: AstNode }).callee) === name;
+
+/**
+ * Narrow a member-expression node (`a.b` or `a['b']`) to its `object` /
+ * `property` pair, returning `null` for anything else.
+ */
+export const getMemberExpression = (
+  node: AstNode | undefined
+): { readonly object?: AstNode; readonly property?: AstNode } | null => {
+  if (
+    !node ||
+    (node.type !== 'MemberExpression' && node.type !== 'StaticMemberExpression')
+  ) {
+    return null;
+  }
+
+  return node as unknown as {
+    readonly object?: AstNode;
+    readonly property?: AstNode;
+  };
+};
+
+/**
+ * Resolve a `<store>.tables.<name>` member expression to its store binding
+ * and table name.
+ *
+ * Returns `null` for anything that isn't a two-level member access ending in
+ * `.tables.<name>`. The store binding is the identifier of the object owning
+ * `.tables` — typically the local binding from `const db = store(...)`.
+ */
+export const extractStoreTableFromMember = (
+  node: AstNode | undefined
+): {
+  readonly storeBinding: string | null;
+  readonly tableName: string;
+} | null => {
+  const member = getMemberExpression(node);
+  const tableName = member ? getPropertyName(member.property) : null;
+  const tablesMember = member ? getMemberExpression(member.object) : null;
+  if (!tableName || !tablesMember) {
+    return null;
+  }
+
+  if (getPropertyName(tablesMember.property) !== 'tables') {
+    return null;
+  }
+
+  const storeBinding = identifierName(tablesMember.object) ?? null;
+  return { storeBinding, tableName };
+};
+
+/**
+ * Collect `const foo = <store>.tables.<name>` bindings from a parsed file,
+ * keyed by the local binding name. Values are the composite table key
+ * (`${storeBinding}:${tableName}`) so callers can dedupe across stores that
+ * share a table name.
+ */
+export const collectNamedStoreTableIds = (
+  ast: AstNode
+): ReadonlyMap<string, string> => {
+  const ids = new Map<string, string>();
+
+  walk(ast, (node) => {
+    if (node.type !== 'VariableDeclarator') {
+      return;
+    }
+
+    const { id, init } = node as unknown as {
+      readonly id?: AstNode;
+      readonly init?: AstNode;
+    };
+    const name = extractBindingName(id);
+    const table = extractStoreTableFromMember(init);
+    if (name && table) {
+      ids.set(name, makeStoreTableKey(table.storeBinding, table.tableName));
+    }
+  });
+
+  return ids;
+};
+
+/**
+ * Resolve an argument node to a composite store-table key
+ * (`${storeBinding}:${tableName}` or bare `tableName` when anonymous).
+ *
+ * Handles the two authoring patterns:
+ *   - direct member access: `db.tables.notes`
+ *   - identifier reference: `const notesTable = db.tables.notes; crud(notesTable, …)`
+ */
+export const deriveStoreTableId = (
+  node: AstNode | undefined,
+  namedStoreTableIds: ReadonlyMap<string, string>
+): string | null => {
+  if (!node) {
+    return null;
+  }
+
+  if (node.type === 'Identifier') {
+    const name = identifierName(node);
+    return name ? (namedStoreTableIds.get(name) ?? null) : null;
+  }
+
+  const member = extractStoreTableFromMember(node);
+  return member
+    ? makeStoreTableKey(member.storeBinding, member.tableName)
+    : null;
+};
+
+const extractStoreTableDefinitions = (
+  node: AstNode,
+  storeBinding: string | null
+): readonly StoreTableDefinition[] => {
+  if (!isNamedCall(node, 'store')) {
+    return [];
+  }
+
+  const [tablesArg] = ((node as unknown as { arguments?: readonly AstNode[] })
+    .arguments ?? []) as readonly AstNode[];
+  if (!tablesArg || tablesArg.type !== 'ObjectExpression') {
+    return [];
+  }
+
+  const properties = tablesArg['properties'] as readonly AstNode[] | undefined;
+  if (!properties) {
+    return [];
+  }
+
+  return properties.flatMap((property) => {
+    if (property.type !== 'Property') {
+      return [];
+    }
+
+    const name = getPropertyName(property.key);
+    const value = property.value as AstNode | undefined;
+    if (!name || value?.type !== 'ObjectExpression') {
+      return [];
+    }
+
+    const versionedProp = findConfigProperty(value, 'versioned');
+    return [
+      {
+        key: makeStoreTableKey(storeBinding, name),
+        name,
+        start: property.start,
+        storeBinding,
+        versioned: isBooleanLiteral(
+          versionedProp?.value as AstNode | undefined
+        ),
+      },
+    ];
+  });
+};
+
+export const findStoreTableDefinitions = (
+  ast: AstNode
+): readonly StoreTableDefinition[] => {
+  const definitions: StoreTableDefinition[] = [];
+  const seenStoreCalls = new WeakSet<AstNode>();
+
+  // First pass: bound stores (walk VariableDeclarators so we know the binding).
+  walk(ast, (node) => {
+    if (node.type !== 'VariableDeclarator') {
+      return;
+    }
+
+    const { id, init } = node as unknown as {
+      readonly id?: AstNode;
+      readonly init?: AstNode;
+    };
+    if (!init || !isNamedCall(init, 'store')) {
+      return;
+    }
+
+    seenStoreCalls.add(init);
+    const storeBinding = extractBindingName(id);
+    definitions.push(...extractStoreTableDefinitions(init, storeBinding));
+  });
+
+  // Second pass: anonymous `store({...})` calls not bound to a variable
+  // (e.g. an inline default export). Use the bare table name as the key.
+  walk(ast, (node) => {
+    if (!isNamedCall(node, 'store') || seenStoreCalls.has(node)) {
+      return;
+    }
+    definitions.push(...extractStoreTableDefinitions(node, null));
+  });
+
+  return definitions;
+};
+
+export const collectCrudTableIds = (ast: AstNode): ReadonlySet<string> => {
+  const ids = new Set<string>();
+  const namedStoreTableIds = collectNamedStoreTableIds(ast);
+
+  walk(ast, (node) => {
+    if (!isNamedCall(node, 'crud')) {
+      return;
+    }
+
+    const [tableArg] = ((node as unknown as { arguments?: readonly AstNode[] })
+      .arguments ?? []) as readonly AstNode[];
+    const tableId = deriveStoreTableId(tableArg, namedStoreTableIds);
+    if (tableId) {
+      ids.add(tableId);
+    }
+  });
+
+  return ids;
+};
+
+export const collectReconcileTableIds = (ast: AstNode): ReadonlySet<string> => {
+  const ids = new Set<string>();
+  const namedStoreTableIds = collectNamedStoreTableIds(ast);
+
+  walk(ast, (node) => {
+    if (!isNamedCall(node, 'reconcile')) {
+      return;
+    }
+
+    const [configArg] = ((
+      node as unknown as {
+        arguments?: readonly AstNode[];
+      }
+    ).arguments ?? []) as readonly AstNode[];
+    if (!configArg || configArg.type !== 'ObjectExpression') {
+      return;
+    }
+
+    const tableProp = findConfigProperty(configArg, 'table');
+    const tableId = deriveStoreTableId(
+      tableProp?.value as AstNode | undefined,
+      namedStoreTableIds
+    );
+    if (tableId) {
+      ids.add(tableId);
+    }
+  });
+
+  return ids;
+};

package/src/rules/specs.ts

@@ -0,0 +1,388 @@
+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: 'signal' | '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;
+}
+
+// Match `trail(...)` / `signal(...)` declaration sites, not method calls.
+// The negative lookbehind excludes `foo.signal(...)`, `foo?.signal(...)`, and
+// similar member-expression call sites (including optional chaining with
+// whitespace) where `signal` / `trail` is a property name, not a factory.
+const TRAIL_LIKE_PATTERN = /(?<![.?])\b(trail|signal)\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: 'signal' | '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: 'signal' | '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] === 'signal' ? 'signal' : '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),
+    ])
+  );
+};