@grafema/core 0.1.0-alpha.5 → 0.1.1-alpha

package/src/plugins/analysis/ast/utils/location.ts

@@ -0,0 +1,103 @@
+/**
+ * Location extraction utilities for AST nodes.
+ *
+ * Convention: 0:0 means "unknown location" when AST node lacks position data.
+ * This can happen with synthetic nodes, transformed AST, or malformed source.
+ *
+ * This is the single source of truth for location extraction across all analyzers.
+ *
+ * @module location
+ */
+import type { Node } from '@babel/types';
+
+/**
+ * Fallback location for nodes without position data.
+ * Used when AST was generated without source maps or from synthetic nodes.
+ */
+export const UNKNOWN_LOCATION = { line: 0, column: 0 } as const;
+
+/**
+ * Location information extracted from an AST node.
+ * Both line and column are guaranteed to be numbers (not undefined).
+ */
+export interface NodeLocation {
+  readonly line: number;
+  readonly column: number;
+}
+
+/**
+ * Extract start location from an AST node.
+ *
+ * Returns { line: 0, column: 0 } if node is null, undefined, or lacks location data.
+ * This is the preferred way to get location info - use this instead of node.loc!
+ *
+ * @example
+ * // Instead of:
+ * const line = node.loc!.start.line;
+ * const column = node.loc!.start.column;
+ *
+ * // Use:
+ * const { line, column } = getNodeLocation(node);
+ *
+ * @param node - Babel AST node (may be null or undefined)
+ * @returns Location with line and column (both guaranteed numbers)
+ */
+export function getNodeLocation(node: Node | null | undefined): NodeLocation {
+  return {
+    line: node?.loc?.start?.line ?? 0,
+    column: node?.loc?.start?.column ?? 0
+  };
+}
+
+/**
+ * Extract start line number from an AST node.
+ *
+ * Returns 0 if node is null, undefined, or lacks location data.
+ *
+ * @example
+ * // Instead of:
+ * const line = node.loc!.start.line;
+ *
+ * // Use:
+ * const line = getLine(node);
+ *
+ * @param node - Babel AST node (may be null or undefined)
+ * @returns Line number (1-based) or 0 for unknown
+ */
+export function getLine(node: Node | null | undefined): number {
+  return node?.loc?.start?.line ?? 0;
+}
+
+/**
+ * Extract start column number from an AST node.
+ *
+ * Returns 0 if node is null, undefined, or lacks location data.
+ *
+ * @example
+ * // Instead of:
+ * const col = node.loc!.start.column;
+ *
+ * // Use:
+ * const col = getColumn(node);
+ *
+ * @param node - Babel AST node (may be null or undefined)
+ * @returns Column number (0-based) or 0 for unknown
+ */
+export function getColumn(node: Node | null | undefined): number {
+  return node?.loc?.start?.column ?? 0;
+}
+
+/**
+ * Extract end location from an AST node.
+ *
+ * Returns { line: 0, column: 0 } if node is null, undefined, or lacks location data.
+ *
+ * @param node - Babel AST node (may be null or undefined)
+ * @returns End location with line and column (both guaranteed numbers)
+ */
+export function getEndLocation(node: Node | null | undefined): NodeLocation {
+  return {
+    line: node?.loc?.end?.line ?? 0,
+    column: node?.loc?.end?.column ?? 0
+  };
+}

package/src/plugins/analysis/ast/visitors/ASTVisitor.ts

@@ -3,6 +3,7 @@
  * Each visitor handles specific AST node types and collects relevant data
  */
 import type { Node, SourceLocation } from '@babel/types';
+import { getNodeLocation, type NodeLocation } from '../utils/location.js';
 import type { NodePath } from '@babel/traverse';
 import type {
   FunctionInfo,
@@ -84,11 +85,13 @@ export interface VisitorCollections {
 }
 
 /**
- * Location info extracted from AST node
+ * Location info extracted from AST node.
+ * Both line and column are guaranteed to be numbers (not undefined).
+ * Convention: 0:0 means "unknown location".
  */
 export interface LocationInfo {
-  line: number | undefined;
-  column: number | undefined;
+  line: number;
+  column: number;
 }
 
 /**
@@ -126,12 +129,12 @@ export abstract class ASTVisitor {
   abstract getHandlers(): VisitorHandlers;
 
   /**
-   * Utility to get source location info
+   * Utility to get source location info.
+   * Returns { line: 0, column: 0 } if location is unavailable.
+   *
+   * @deprecated Prefer using getLine() or getNodeLocation() directly from utils/location.js
    */
   protected getLoc(node: Node): LocationInfo {
-    return {
-      line: node.loc?.start?.line,
-      column: node.loc?.start?.column
-    };
+    return getNodeLocation(node);
   }
 }