angular-grab 0.1.1 → 0.1.3

package/packages/angular-grab/src/angular/resolvers/context-builder.ts

@@ -0,0 +1,86 @@
+import { filterAngularClasses, type ElementContext, type ComponentStackEntry } from '../../core';
+import { resolveComponent } from './component-resolver';
+import { resolveSource, resolveSourceForComponent } from './source-resolver';
+
+const MAX_HTML_LENGTH = 2000;
+
+export function buildContext(element: Element): ElementContext {
+  const compResult = resolveComponent(element);
+  const { filePath, line, column } = resolveSource(element);
+  const html = extractHtml(element);
+  const selector = generateSelector(element);
+
+  const cssClasses = filterAngularClasses(element.classList);
+
+  const componentStack: ComponentStackEntry[] = compResult.stack.map((entry) => {
+    const src = resolveSourceForComponent(entry.name);
+    return {
+      name: entry.name,
+      filePath: src.filePath,
+      line: src.line,
+      column: src.column,
+    };
+  });
+
+  return {
+    element,
+    html,
+    componentName: compResult.name,
+    filePath,
+    line,
+    column,
+    componentStack,
+    selector,
+    cssClasses,
+  };
+}
+
+function extractHtml(element: Element): string {
+  const html = element.outerHTML;
+  if (html.length <= MAX_HTML_LENGTH) return html;
+  return html.slice(0, MAX_HTML_LENGTH) + '<!-- truncated -->';
+}
+
+function generateSelector(element: Element): string {
+  const parts: string[] = [];
+  let current: Element | null = element;
+
+  while (current && current !== document.documentElement) {
+    let selector = current.tagName.toLowerCase();
+
+    if (current.id) {
+      selector += `#${current.id}`;
+      parts.unshift(selector);
+      break;
+    }
+
+    const className = current.getAttribute('class');
+    if (className) {
+      const classes = className
+        .trim()
+        .split(/\s+/)
+        .filter(Boolean)
+        .slice(0, 3);
+      if (classes.length > 0) {
+        selector += '.' + classes.join('.');
+      }
+    }
+
+    // Add nth-of-type if there are sibling elements with the same tag
+    const parent = current.parentElement;
+    if (parent) {
+      const siblings = Array.from(parent.children).filter(
+        (s) => s.tagName === current!.tagName
+      );
+      if (siblings.length > 1) {
+        const index = siblings.indexOf(current) + 1;
+        selector += `:nth-of-type(${index})`;
+      }
+    }
+
+    parts.unshift(selector);
+    current = current.parentElement;
+  }
+
+  return parts.join(' > ');
+}

package/packages/angular-grab/src/angular/resolvers/ng-utils.ts

@@ -0,0 +1,14 @@
+export interface NgDebugApi {
+  getComponent<T>(element: Element): T | null;
+  getOwningComponent<T>(element: Element): T | null;
+  getDirectives(element: Element): any[];
+}
+
+export function getNgApi(): NgDebugApi | null {
+  if (typeof window === 'undefined') return null;
+  return (window as any).ng || null;
+}
+
+export function cleanComponentName(name: string): string {
+  return name.startsWith('_') ? name.slice(1) : name;
+}

package/packages/angular-grab/src/angular/resolvers/source-resolver.ts

@@ -0,0 +1,61 @@
+import { type NgDebugApi, getNgApi, cleanComponentName } from './ng-utils';
+
+interface SourceMapEntry {
+  file: string;
+  line: number;
+}
+
+function getSourceMap(): Record<string, SourceMapEntry> | null {
+  return (globalThis as any).__ANGULAR_GRAB_SOURCE_MAP__ ?? null;
+}
+
+export function resolveSource(element: Element): {
+  filePath: string | null;
+  line: number | null;
+  column: number | null;
+} {
+  const sourceMap = getSourceMap();
+  if (!sourceMap) return { filePath: null, line: null, column: null };
+
+  const ng = getNgApi();
+  if (!ng) return { filePath: null, line: null, column: null };
+
+  // Find the component that owns this element
+  const componentName = findComponentName(element, ng);
+  if (!componentName) return { filePath: null, line: null, column: null };
+
+  const entry = sourceMap[componentName];
+  if (!entry) return { filePath: null, line: null, column: null };
+
+  return { filePath: entry.file, line: entry.line, column: null };
+}
+
+export function resolveSourceForComponent(componentName: string): {
+  filePath: string | null;
+  line: number | null;
+  column: number | null;
+} {
+  const sourceMap = getSourceMap();
+  if (!sourceMap) return { filePath: null, line: null, column: null };
+
+  const entry = sourceMap[componentName];
+  if (!entry) return { filePath: null, line: null, column: null };
+
+  return { filePath: entry.file, line: entry.line, column: null };
+}
+
+function findComponentName(element: Element, ng: NgDebugApi): string | null {
+  // Try direct component on this element
+  const direct = ng.getComponent(element);
+  if (direct) return cleanComponentName(direct.constructor.name);
+
+  // Walk up to find owning component
+  let current: Element | null = element;
+  while (current) {
+    const owning = ng.getOwningComponent(current);
+    if (owning) return cleanComponentName(owning.constructor.name);
+    current = current.parentElement;
+  }
+
+  return null;
+}

package/packages/angular-grab/src/builder/__tests__/builder.test.ts

@@ -0,0 +1,72 @@
+import { describe, it, expect } from 'vitest';
+import { readFileSync } from 'fs';
+import { join } from 'path';
+
+const PACKAGE_ROOT = join(__dirname, '..', '..', '..');
+
+describe('builders.json', () => {
+  const buildersJson = JSON.parse(
+    readFileSync(join(PACKAGE_ROOT, 'builders.json'), 'utf8'),
+  );
+
+  it('has a builders property', () => {
+    expect(buildersJson.builders).toBeDefined();
+    expect(typeof buildersJson.builders).toBe('object');
+  });
+
+  it('defines an application builder', () => {
+    const app = buildersJson.builders.application;
+    expect(app).toBeDefined();
+    expect(app.implementation).toBeDefined();
+    expect(app.schema).toBeDefined();
+    expect(app.description).toBeDefined();
+  });
+
+  it('defines a dev-server builder', () => {
+    const devServer = buildersJson.builders['dev-server'];
+    expect(devServer).toBeDefined();
+    expect(devServer.implementation).toBeDefined();
+    expect(devServer.schema).toBeDefined();
+    expect(devServer.description).toBeDefined();
+  });
+
+  it('application builder points to correct implementation path', () => {
+    const app = buildersJson.builders.application;
+    expect(app.implementation).toContain('builders/application');
+  });
+
+  it('dev-server builder points to correct implementation path', () => {
+    const devServer = buildersJson.builders['dev-server'];
+    expect(devServer.implementation).toContain('builders/dev-server');
+  });
+});
+
+describe('package.json', () => {
+  const packageJson = JSON.parse(
+    readFileSync(join(PACKAGE_ROOT, 'package.json'), 'utf8'),
+  );
+
+  it('declares builders field pointing to builders.json', () => {
+    expect(packageJson.builders).toBe('./builders.json');
+  });
+
+  it('exports builders.json', () => {
+    expect(packageJson.exports['./builders.json']).toBe('./builders.json');
+  });
+});
+
+describe('schema files', () => {
+  it('application schema is valid JSON', () => {
+    const schema = JSON.parse(
+      readFileSync(join(PACKAGE_ROOT, 'src', 'builder', 'builders', 'application', 'schema.json'), 'utf8'),
+    );
+    expect(schema.type).toBe('object');
+  });
+
+  it('dev-server schema is valid JSON', () => {
+    const schema = JSON.parse(
+      readFileSync(join(PACKAGE_ROOT, 'src', 'builder', 'builders', 'dev-server', 'schema.json'), 'utf8'),
+    );
+    expect(schema.type).toBe('object');
+  });
+});

package/packages/angular-grab/src/builder/builders/application/index.ts

@@ -0,0 +1,13 @@
+import { createBuilder } from '@angular-devkit/architect';
+import { buildApplication } from '@angular/build';
+import { angularGrabEsbuildPlugin } from '../../../esbuild-plugin';
+
+export default createBuilder(async function* (options: any, context) {
+  const isProduction = !!options.optimization;
+  yield* buildApplication(options, context, {
+    codePlugins: [angularGrabEsbuildPlugin({
+      rootDir: context.workspaceRoot,
+      enabled: !isProduction,
+    })],
+  });
+});

package/packages/angular-grab/src/builder/builders/dev-server/index.ts

@@ -0,0 +1,9 @@
+import { createBuilder } from '@angular-devkit/architect';
+import { executeDevServerBuilder } from '@angular/build';
+import { angularGrabEsbuildPlugin } from '../../../esbuild-plugin';
+
+export default createBuilder(async function* (options: any, context) {
+  yield* executeDevServerBuilder(options, context, {
+    buildPlugins: [angularGrabEsbuildPlugin({ rootDir: context.workspaceRoot })],
+  });
+});

package/packages/angular-grab/src/builder/index.ts

@@ -0,0 +1,3 @@
+// angular-grab/builder
+// This package provides Angular CLI builders that inject angular-grab source location mapping.
+// Builders are resolved via builders.json — this file is not directly imported by users.

package/packages/angular-grab/src/cli/__tests__/cli.test.ts

@@ -0,0 +1,239 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtempSync, writeFileSync, mkdirSync, rmSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+import { findAngularJson, detectProject } from '../utils/detect-project';
+
+describe('findAngularJson', () => {
+  let tempDir: string;
+
+  beforeEach(() => {
+    tempDir = mkdtempSync(join(tmpdir(), 'cli-test-'));
+  });
+
+  afterEach(() => {
+    rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it('finds angular.json in the given directory', () => {
+    writeFileSync(join(tempDir, 'angular.json'), '{}');
+    const result = findAngularJson(tempDir);
+    expect(result).toBe(join(tempDir, 'angular.json'));
+  });
+
+  it('finds angular.json in a parent directory', () => {
+    writeFileSync(join(tempDir, 'angular.json'), '{}');
+    const subDir = join(tempDir, 'src', 'app');
+    mkdirSync(subDir, { recursive: true });
+
+    const result = findAngularJson(subDir);
+    expect(result).toBe(join(tempDir, 'angular.json'));
+  });
+
+  it('returns null when no angular.json exists', () => {
+    const result = findAngularJson(tempDir);
+    expect(result).toBeNull();
+  });
+});
+
+describe('detectProject', () => {
+  let tempDir: string;
+
+  beforeEach(() => {
+    tempDir = mkdtempSync(join(tmpdir(), 'cli-test-'));
+  });
+
+  afterEach(() => {
+    rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  function writeAngularJson(content: object): string {
+    const path = join(tempDir, 'angular.json');
+    writeFileSync(path, JSON.stringify(content));
+    return path;
+  }
+
+  it('detects project name from angular.json', () => {
+    const path = writeAngularJson({
+      projects: {
+        'my-app': {
+          sourceRoot: 'src',
+          architect: {
+            build: { builder: '@angular/build:application' },
+          },
+        },
+      },
+    });
+
+    const info = detectProject(path);
+    expect(info.projectName).toBe('my-app');
+  });
+
+  it('detects "application" builder type', () => {
+    const path = writeAngularJson({
+      projects: {
+        app: {
+          architect: {
+            build: { builder: '@angular/build:application' },
+          },
+        },
+      },
+    });
+
+    const info = detectProject(path);
+    expect(info.builderType).toBe('application');
+  });
+
+  it('detects "browser-esbuild" builder type', () => {
+    const path = writeAngularJson({
+      projects: {
+        app: {
+          architect: {
+            build: { builder: '@angular-devkit/build-angular:browser-esbuild' },
+          },
+        },
+      },
+    });
+
+    const info = detectProject(path);
+    expect(info.builderType).toBe('browser-esbuild');
+  });
+
+  it('detects "browser" builder type', () => {
+    const path = writeAngularJson({
+      projects: {
+        app: {
+          architect: {
+            build: { builder: '@angular-devkit/build-angular:browser' },
+          },
+        },
+      },
+    });
+
+    const info = detectProject(path);
+    expect(info.builderType).toBe('browser');
+  });
+
+  it('detects angular-grab:application as "application"', () => {
+    const path = writeAngularJson({
+      projects: {
+        app: {
+          architect: {
+            build: { builder: 'angular-grab:application' },
+          },
+        },
+      },
+    });
+
+    const info = detectProject(path);
+    expect(info.builderType).toBe('application');
+  });
+
+  it('defaults sourceRoot to "src" when not specified', () => {
+    const path = writeAngularJson({
+      projects: {
+        app: {
+          architect: {
+            build: { builder: '@angular/build:application' },
+          },
+        },
+      },
+    });
+
+    const info = detectProject(path);
+    expect(info.sourceRoot).toBe('src');
+  });
+
+  it('uses custom sourceRoot when specified', () => {
+    const path = writeAngularJson({
+      projects: {
+        app: {
+          sourceRoot: 'projects/app/src',
+          architect: {
+            build: { builder: '@angular/build:application' },
+          },
+        },
+      },
+    });
+
+    const info = detectProject(path);
+    expect(info.sourceRoot).toBe('projects/app/src');
+  });
+
+  it('throws when no projects are found', () => {
+    const path = writeAngularJson({ projects: {} });
+    expect(() => detectProject(path)).toThrow('No projects found');
+  });
+
+  it('throws when no build target is found', () => {
+    const path = writeAngularJson({
+      projects: {
+        app: { architect: {} },
+      },
+    });
+
+    expect(() => detectProject(path)).toThrow('No build target found');
+  });
+
+  it('detects npm as default package manager', () => {
+    const path = writeAngularJson({
+      projects: {
+        app: {
+          architect: {
+            build: { builder: '@angular/build:application' },
+          },
+        },
+      },
+    });
+
+    const info = detectProject(path);
+    expect(info.packageManager).toBe('npm');
+  });
+
+  it('detects pnpm when pnpm-lock.yaml exists', () => {
+    writeFileSync(join(tempDir, 'pnpm-lock.yaml'), '');
+    const path = writeAngularJson({
+      projects: {
+        app: {
+          architect: {
+            build: { builder: '@angular/build:application' },
+          },
+        },
+      },
+    });
+
+    const info = detectProject(path);
+    expect(info.packageManager).toBe('pnpm');
+  });
+
+  it('detects yarn when yarn.lock exists', () => {
+    writeFileSync(join(tempDir, 'yarn.lock'), '');
+    const path = writeAngularJson({
+      projects: {
+        app: {
+          architect: {
+            build: { builder: '@angular/build:application' },
+          },
+        },
+      },
+    });
+
+    const info = detectProject(path);
+    expect(info.packageManager).toBe('yarn');
+  });
+
+  it('supports "targets" as an alternative to "architect"', () => {
+    const path = writeAngularJson({
+      projects: {
+        app: {
+          targets: {
+            build: { builder: '@angular/build:application' },
+          },
+        },
+      },
+    });
+
+    const info = detectProject(path);
+    expect(info.builderType).toBe('application');
+  });
+});

package/packages/angular-grab/src/cli/commands/init.ts

@@ -0,0 +1,106 @@
+import { execSync } from 'child_process';
+import { findAngularJson, detectProject, type ProjectInfo } from '../utils/detect-project';
+import { modifyAngularJson } from '../utils/modify-angular-json';
+import { modifyAppConfig } from '../utils/modify-app-config';
+
+const PACKAGES = ['angular-grab'];
+
+function log(msg: string): void {
+  console.log(`\x1b[36m[angular-grab]\x1b[0m ${msg}`);
+}
+
+function warn(msg: string): void {
+  console.log(`\x1b[33m[angular-grab]\x1b[0m ${msg}`);
+}
+
+function getInstallCommand(pm: ProjectInfo['packageManager']): string {
+  const deps = PACKAGES.join(' ');
+  switch (pm) {
+    case 'pnpm':
+      return `pnpm add -D ${deps}`;
+    case 'yarn':
+      return `yarn add -D ${deps}`;
+    default:
+      return `npm install -D ${deps}`;
+  }
+}
+
+export async function init(): Promise<void> {
+  log('Initializing angular-grab...\n');
+
+  // 1. Find angular.json
+  const angularJsonPath = findAngularJson();
+  if (!angularJsonPath) {
+    throw new Error(
+      'Could not find angular.json. Are you in an Angular project directory?',
+    );
+  }
+
+  // 2. Detect project info
+  const info = detectProject(angularJsonPath);
+  log(`Found project: ${info.projectName}`);
+  log(`Builder type: ${info.builderType}`);
+  log(`Package manager: ${info.packageManager}`);
+  console.log('');
+
+  // 3. Reject legacy builders
+  if (info.builderType === 'browser') {
+    throw new Error(
+      'angular-grab requires the "application" builder (Angular 17+).\n' +
+      'Please migrate from "@angular-devkit/build-angular:browser" to "@angular/build:application".\n' +
+      'See: https://angular.dev/tools/cli/build-system-migration',
+    );
+  }
+
+  if (info.builderType === 'browser-esbuild') {
+    throw new Error(
+      'angular-grab requires the "application" builder, not the transitional "browser-esbuild" builder.\n' +
+      'Please migrate from "@angular-devkit/build-angular:browser-esbuild" to "@angular/build:application".\n' +
+      'See: https://angular.dev/tools/cli/build-system-migration',
+    );
+  }
+
+  // 4. Install packages
+  log('Installing packages...');
+  const installCmd = getInstallCommand(info.packageManager);
+  try {
+    execSync(installCmd, {
+      cwd: info.projectRoot,
+      stdio: 'inherit',
+    });
+  } catch {
+    warn('Package installation failed. You may need to install manually:');
+    warn(`  ${installCmd}`);
+    console.log('');
+  }
+
+  // 5. Modify angular.json
+  log('Updating angular.json...');
+  const jsonModified = modifyAngularJson(info.angularJsonPath, info.projectName);
+  if (jsonModified) {
+    log('  Swapped builders to angular-grab');
+  } else {
+    warn('  angular.json builders were already configured or could not be modified');
+  }
+
+  // 6. Try to add provideAngularGrab() to app config
+  log('Updating app.config.ts...');
+  const configModified = modifyAppConfig(info.projectRoot, info.sourceRoot);
+  if (configModified) {
+    log('  Added provideAngularGrab() to providers');
+  } else {
+    warn('  Could not modify app.config.ts (already configured or not found)');
+    warn('  Please add manually:');
+    warn("    import { provideAngularGrab } from 'angular-grab/angular';");
+    warn('    // then add provideAngularGrab() to your providers array');
+  }
+
+  console.log('');
+  log('\x1b[32mDone!\x1b[0m angular-grab is ready.');
+  console.log('');
+  console.log('  Next steps:');
+  console.log('    1. Run \x1b[1mng serve\x1b[0m');
+  console.log('    2. Hold \x1b[1mCmd+C\x1b[0m (Mac) or \x1b[1mCtrl+C\x1b[0m (Windows) and hover over elements');
+  console.log('    3. Click to copy element context to clipboard');
+  console.log('');
+}

package/packages/angular-grab/src/cli/index.ts

@@ -0,0 +1,15 @@
+import { init } from './commands/init';
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+if (command === 'init' || !command) {
+  init().catch((err) => {
+    console.error('\x1b[31mError:\x1b[0m', err.message);
+    process.exit(1);
+  });
+} else {
+  console.error(`Unknown command: ${command}`);
+  console.log('\nUsage: npx angular-grab init');
+  process.exit(1);
+}