@ontrails/source 0.2.0

package/src/edits.ts

@@ -0,0 +1,57 @@
+/** Shared source-edit helpers. */
+
+import type { SourceEdit } from './nodes.js';
+
+export const createSourceEdit = (
+  start: number,
+  end: number,
+  replacement: string
+): SourceEdit => ({ end, replacement, start });
+
+export const validateSourceEdits = (
+  edits: readonly SourceEdit[],
+  sourceLength?: number
+): readonly SourceEdit[] => {
+  const ordered = [...edits].toSorted(
+    (left, right) => left.start - right.start
+  );
+  for (let i = 0; i < ordered.length; i += 1) {
+    const edit = ordered[i];
+    if (!edit) {
+      continue;
+    }
+    if (
+      !Number.isSafeInteger(edit.start) ||
+      !Number.isSafeInteger(edit.end) ||
+      edit.start < 0 ||
+      edit.end < edit.start ||
+      (sourceLength !== undefined && edit.end > sourceLength)
+    ) {
+      throw new Error(`Invalid source edit range ${edit.start}-${edit.end}.`);
+    }
+
+    const previous = ordered[i - 1];
+    if (previous && edit.start < previous.end) {
+      throw new Error(
+        `Overlapping source edits ${previous.start}-${previous.end} and ${edit.start}-${edit.end}.`
+      );
+    }
+  }
+
+  return ordered;
+};
+
+export const applySourceEdits = (
+  sourceCode: string,
+  edits: readonly SourceEdit[]
+): string => {
+  validateSourceEdits(edits, sourceCode.length);
+
+  return [...edits]
+    .toSorted((left, right) => right.start - left.start)
+    .reduce(
+      (output, edit) =>
+        output.slice(0, edit.start) + edit.replacement + output.slice(edit.end),
+      sourceCode
+    );
+};

package/src/index.ts

@@ -0,0 +1,25 @@
+export * from './nodes.js';
+export * from './parse.js';
+export * from './walk.js';
+export * from './scopes.js';
+export * from './locations.js';
+export * from './edits.js';
+export * from './literals.js';
+export * from './collection.js';
+export type {
+  EntityDefinition,
+  FindEntityDefinitionsOptions,
+  FrameworkNamespaceContext,
+  TrailDefinition,
+} from './trails.js';
+export {
+  buildFrameworkNamespaceContext,
+  extractEntityDefinition,
+  extractTrailDefinition,
+  findEntityDefinitions,
+  findImplementationBodies,
+  findTrailDefinitions,
+  getImportSourceValue,
+  isImplementationCall,
+  isFrameworkNamespaceSource,
+} from './trails.js';

package/src/literals.ts

@@ -0,0 +1,234 @@
+/** Shared literal, string, and static property-key helpers. */
+
+import { isAstNode } from './nodes.js';
+import type { AstNode, StringLiteralNode } from './nodes.js';
+import { walk } from './walk.js';
+
+export const identifierName = (node: AstNode | undefined): string | null => {
+  if (node?.type !== 'Identifier') {
+    return null;
+  }
+  return (node as unknown as { name?: string }).name ?? null;
+};
+
+/** Check if a node is a string literal. */
+export const isStringLiteral = (
+  node: AstNode | undefined
+): node is StringLiteralNode => {
+  if (!node) {
+    return false;
+  }
+  if (node.type === 'StringLiteral') {
+    return true;
+  }
+  if (node.type === 'Literal') {
+    return typeof (node as unknown as { value?: unknown }).value === 'string';
+  }
+  return false;
+};
+
+/** Extract the string value from a string literal node. */
+export const getStringValue = (node: AstNode): string | null => {
+  const val = (node as unknown as { value?: unknown }).value;
+  return typeof val === 'string' ? val : null;
+};
+
+/**
+ * Best-effort resolution of `const NAME = 'value'` declarations via regex.
+ *
+ * Returns the string value if a simple `const <name> = '...'` or `"..."` is
+ * found in the source. Returns null for anything more complex. Shared between
+ * warden rules that need to resolve identifier references to signal / trail
+ * IDs at lint time.
+ */
+export const deriveConstString = (
+  name: string,
+  sourceCode: string
+): string | null => {
+  const pattern = new RegExp(
+    `const\\s+${name}\\s*=\\s*(?:'([^']*)'|"([^"]*)")`
+  );
+  const match = pattern.exec(sourceCode);
+  if (!match) {
+    return null;
+  }
+  return match[1] ?? match[2] ?? null;
+};
+
+/** Extract a string literal value, or null when the node is not a string. */
+export const extractStringLiteral = (
+  node: AstNode | undefined
+): string | null =>
+  node && isStringLiteral(node) ? getStringValue(node) : null;
+
+/**
+ * Extract the cooked value from a `TemplateLiteral` with no interpolations
+ * (e.g. `` `entity.fallback` ``). Template literals with `${...}` expressions
+ * cannot be resolved at lint time and return null.
+ *
+ * Shared helper used by rules that accept both string literals and simple
+ * backtick-literal IDs (e.g. `valid-describe-refs`).
+ */
+const getSingleQuasi = (node: AstNode): AstNode | null => {
+  const expressions =
+    (node['expressions'] as readonly AstNode[] | undefined) ?? [];
+  if (expressions.length > 0) {
+    return null;
+  }
+  const quasis = (node['quasis'] as readonly AstNode[] | undefined) ?? [];
+  return quasis.length === 1 ? (quasis[0] ?? null) : null;
+};
+
+export const extractPlainTemplateLiteral = (
+  node: AstNode | undefined
+): string | null => {
+  if (!node || node.type !== 'TemplateLiteral') {
+    return null;
+  }
+  const quasi = getSingleQuasi(node);
+  if (!quasi) {
+    return null;
+  }
+  const cooked = (quasi as unknown as { value?: { cooked?: unknown } }).value
+    ?.cooked;
+  return typeof cooked === 'string' ? cooked : null;
+};
+
+/**
+ * Extract a string value from either a string literal or a plain template
+ * literal (no `${...}` expressions). Returns null for anything else.
+ */
+export const extractStringOrTemplateLiteral = (
+  node: AstNode | undefined
+): string | null =>
+  extractStringLiteral(node) ?? extractPlainTemplateLiteral(node);
+
+export interface StringLiteralMatch {
+  readonly end: number;
+  readonly node: AstNode;
+  readonly start: number;
+  readonly value: string;
+}
+
+export const findStringLiterals = (
+  ast: AstNode,
+  predicate?: (value: string, node: AstNode) => boolean
+): StringLiteralMatch[] => {
+  const matches: StringLiteralMatch[] = [];
+
+  walk(ast, (node) => {
+    if (!isStringLiteral(node)) {
+      return;
+    }
+
+    const value = getStringValue(node);
+    if (value === null) {
+      return;
+    }
+
+    if (predicate && !predicate(value, node)) {
+      return;
+    }
+
+    matches.push({
+      end: node.end,
+      node,
+      start: node.start,
+      value,
+    });
+  });
+
+  return matches;
+};
+
+/** Extract the first string argument from a CallExpression. */
+export const extractFirstStringArg = (node: AstNode): string | null => {
+  if (node.type !== 'CallExpression') {
+    return null;
+  }
+
+  const args = node['arguments'] as readonly AstNode[] | undefined;
+  const [firstArg] = args ?? [];
+  return extractStringLiteral(firstArg);
+};
+
+export const extractBindingName = (
+  node: AstNode | undefined
+): string | null => {
+  if (!node) {
+    return null;
+  }
+  if (node.type === 'Identifier') {
+    return identifierName(node);
+  }
+  if (node.type === 'AssignmentPattern') {
+    return identifierName((node as unknown as { left?: AstNode }).left);
+  }
+  return null;
+};
+
+export const staticPropertyKeyName = (key: AstNode): string | null => {
+  if (key.type === 'Identifier') {
+    return (key as unknown as { name?: string }).name ?? null;
+  }
+  if (isStringLiteral(key)) {
+    return getStringValue(key);
+  }
+  const { value } = key as unknown as { value?: unknown };
+  return (key.type === 'Literal' || key.type === 'NumericLiteral') &&
+    typeof value === 'number' &&
+    Number.isFinite(value)
+    ? String(value)
+    : null;
+};
+
+export const propertyKeyName = (prop: AstNode): string | null => {
+  if (prop.type !== 'Property') {
+    return null;
+  }
+  const { computed } = prop as unknown as { computed?: boolean };
+  if (computed) {
+    return null;
+  }
+  const key = prop.key as AstNode | undefined;
+  return key ? staticPropertyKeyName(key) : null;
+};
+
+/** Find a Property node by key name inside an ObjectExpression config. */
+export const findConfigProperty = (
+  config: AstNode,
+  propertyName: string
+): AstNode | null => {
+  if (config.type !== 'ObjectExpression') {
+    return null;
+  }
+  const properties = config['properties'] as readonly AstNode[] | undefined;
+  if (!properties) {
+    return null;
+  }
+  for (const prop of properties) {
+    if (propertyKeyName(prop) === propertyName) {
+      return prop;
+    }
+  }
+  return null;
+};
+
+/**
+ * Read a property key or member access identifier.
+ *
+ * Returns the identifier name for `Identifier` keys, or the underlying
+ * string literal value for computed access via `['name']` / `"name"`.
+ */
+export const getPropertyName = (node: unknown): string | null => {
+  if (typeof node !== 'object' || node === null) {
+    return null;
+  }
+
+  const { name } = node as { readonly name?: unknown };
+  if (typeof name === 'string') {
+    return name;
+  }
+
+  return isAstNode(node) ? extractStringLiteral(node) : null;
+};

package/src/locations.ts

@@ -0,0 +1,35 @@
+/** Shared source location helpers. */
+
+import type { SourceLocation } from './nodes.js';
+
+/** Find the byte offset's line number (1-based) in source code. */
+export const offsetToLine = (sourceCode: string, offset: number): number => {
+  let line = 1;
+  for (let i = 0; i < offset && i < sourceCode.length; i += 1) {
+    if (sourceCode[i] === '\n') {
+      line += 1;
+    }
+  }
+  return line;
+};
+
+/** Find the byte offset's line and column (1-based) in source code. */
+export const offsetToLineColumn = (
+  sourceCode: string,
+  offset: number
+): SourceLocation => {
+  let line = 1;
+  let column = 1;
+  const limit = Math.min(Math.max(offset, 0), sourceCode.length);
+
+  for (let i = 0; i < limit; i += 1) {
+    if (sourceCode[i] === '\n') {
+      line += 1;
+      column = 1;
+    } else {
+      column += 1;
+    }
+  }
+
+  return { column, line };
+};