@atlaspack/inspector 0.0.19-canary.3998

package/src/backend/errors/HTTPError.ts

@@ -0,0 +1,14 @@
+/**
+ * A custom error class for HTTP errors.
+ *
+ * The {@link errorHandlingMiddleware} will automatically set HTTP response
+ * status codes for instances of this class.
+ */
+export class HTTPError extends Error {
+  constructor(
+    message: string,
+    public status: number,
+  ) {
+    super(message);
+  }
+}

package/src/backend/globals.d.ts

@@ -0,0 +1,9 @@
+declare module '@atlaspack/query' {
+  import type {BundleGraph, RequestTracker, AssetGraph} from '@atlaspack/core';
+
+  export function loadGraphs(cacheDir: string): Promise<{
+    requestTracker: RequestTracker;
+    bundleGraph: BundleGraph;
+    assetGraph: AssetGraph;
+  }>;
+}

package/src/backend/index.ts

@@ -0,0 +1,271 @@
+/* eslint-disable import/first */
+// Stateful import to ensure serializers are loaded
+require('@atlaspack/core');
+
+import {program} from 'commander';
+import express from 'express';
+import cors from 'cors';
+import path from 'path';
+import {setFeatureFlags, DEFAULT_FEATURE_FLAGS} from '@atlaspack/feature-flags';
+
+import {CacheData, loadCacheData} from './services/loadCacheData';
+import {logger} from './config/logger';
+import {errorHandlingMiddleware} from './config/middleware/errorHandlingMiddleware';
+import {loggingMiddleware} from './config/middleware/loggingMiddleware';
+import {makeFrontendAssetsController} from './controllers/FrontendAssetsController';
+import {cacheDataMiddleware} from './config/middleware/cacheDataMiddleware';
+import {makeBundleGraphController} from './controllers/BundleGraphController';
+import {makeTreemapController} from './controllers/TreeMapController';
+import {makeCacheDataController} from './controllers/CacheDataController';
+import {
+  findProjectRoot,
+  findRepositoryRoot,
+  findSourceCodeURL,
+  SourceCodeURL,
+} from './services/findSourceCodeUrl';
+import {AddressInfo} from 'net';
+import {makeInspectorMCPController} from './controllers/mcp/InspectorMCPController';
+import {spawn} from 'child_process';
+import {analyticsService} from './services/AnalyticsService';
+
+/**
+ * We split preparing cache data and building the app.
+ *
+ * The cache is opened once and some models are created from it.
+ *
+ * These models are shared through the application on the `res.locals` express field.
+ */
+interface ConfigureInspectorAppParams {
+  /**
+   * A path to the cache directory or a path to a project.
+   *
+   * If a cache isn't found in this path, the tool will traverse up until it finds
+   * a suitable root.
+   *
+   * Once a cache is found, a `.git` directory will be looked-up to find a "project root".
+   *
+   * This will be used to find files and to find source code URLs on GitHub or BitBucket
+   * cloud.
+   */
+  target: string;
+  /**
+   * A path to the project root.
+   *
+   * If not provided, the tool will traverse up until it finds a suitable root.
+   */
+  projectRoot?: string;
+}
+
+/**
+ * Configures the inspector app.
+ *
+ * - Find paths for the source repository, project and cache.
+ * - Open the cache and deserialize bundler data out of it.
+ * - Build the tree-map model.
+ */
+export function configureInspectorApp({
+  projectRoot: projectRootFromFlags,
+  target,
+}: ConfigureInspectorAppParams): BuildInspectorAppParams {
+  const flags = {
+    ...DEFAULT_FEATURE_FLAGS,
+    cachePerformanceImprovements: true,
+  };
+  setFeatureFlags(flags);
+
+  const projectRoot =
+    projectRootFromFlags ?? findProjectRoot(target) ?? path.dirname(target);
+  const repositoryRoot = findRepositoryRoot(target) ?? path.dirname(target);
+
+  const sourceCodeURL = findSourceCodeURL(target);
+
+  logger.debug(
+    {target, projectRoot, repositoryRoot, sourceCodeURL},
+    'Found paths',
+  );
+
+  const cacheData = loadCacheData({target, projectRoot, repositoryRoot});
+
+  return {
+    cacheData,
+    projectRoot,
+    repositoryRoot,
+    sourceCodeURL,
+  };
+}
+
+export interface BuildInspectorAppParams {
+  /**
+   * A promise to the cache data.
+   */
+  cacheData: Promise<CacheData>;
+  /**
+   * The atlaspack project root.
+   */
+  projectRoot: string;
+  /**
+   * The repository root path for the target project. This will be used to link
+   * to the source code on GitHub or BitBucket.
+   */
+  repositoryRoot: string;
+  /**
+   * The source code URL for the target project. The parsed remote URL.
+   */
+  sourceCodeURL: SourceCodeURL | null;
+}
+
+/**
+ * Wire-up the express server app.
+ */
+export function buildInspectorApp({
+  cacheData,
+  projectRoot,
+  repositoryRoot,
+  sourceCodeURL,
+}: BuildInspectorAppParams): express.Express {
+  const app = express();
+
+  app.use(loggingMiddleware());
+  app.use(
+    cors({
+      origin: /http:\/\/localhost:(\d+)/,
+      credentials: true,
+    }),
+  );
+  app.use(express.json());
+
+  app.use(cacheDataMiddleware(cacheData));
+  app.use(makeFrontendAssetsController());
+  app.use(makeBundleGraphController({projectRoot, repositoryRoot}));
+  app.use(
+    makeTreemapController({
+      projectRoot,
+      repositoryRoot,
+      sourceCodeURL,
+    }),
+  );
+  app.use(makeInspectorMCPController());
+  app.use(makeCacheDataController());
+  app.use(errorHandlingMiddleware);
+
+  return app;
+}
+
+/**
+ * Executes `atlaspack build` to build the client application for the inspector.
+ *
+ * The inspector requires `cachePerformanceImprovements` to be enabled.
+ *
+ * @param targets - The targets/entry-points to build.
+ */
+async function buildClientApplicationForInspector(targets: string[]) {
+  logger.info({targets}, 'Building app...');
+
+  const child = spawn(
+    'yarn',
+    [
+      'atlaspack',
+      'build',
+      '--feature-flag',
+      'cachePerformanceImprovements=true',
+      ...targets,
+    ],
+    {
+      shell: true,
+      stdio: 'inherit',
+    },
+  );
+
+  await new Promise((resolve, reject) => {
+    child.on('error', (error) => {
+      logger.error(error, 'Build error');
+      process.exitCode = 1;
+
+      reject(error);
+    });
+
+    child.on('exit', (code) => {
+      logger.info(`Build process exited with code ${code}`);
+      if (code !== 0) {
+        process.exitCode = code ?? 1;
+        reject(new Error(`Build failed with code ${code}`));
+      } else {
+        resolve(null);
+      }
+    });
+  });
+}
+
+/**
+ * CLI entry point for `@atlaspack/inspector`.
+ *
+ * Usage:
+ *
+ * ```bash
+ * yarn @atlaspack/inspector --target ./path/to/cache --project-root ./path/to/project
+ * ```
+ */
+export function main() {
+  const version = require('../../package.json').version;
+  let isStartCommand = false;
+  program.name('atlaspack-inspector').version(version);
+
+  analyticsService.sendEvent({
+    data: {
+      name: 'atlaspack-inspector-start',
+      action: 'atlaspack-inspector-start',
+    },
+  });
+
+  const command = program
+    .command('start [options]', {isDefault: true})
+    .description('Start the inspector server')
+    .option('-t, --target <path>', 'Path to the target cache', process.cwd())
+    .option('-p, --port <port>', 'Port to run the server on', '3000')
+    .option('--project-root <path>', 'Path to the project root', undefined)
+    .action(() => {
+      isStartCommand = true;
+    });
+
+  program
+    .command('build <target...>')
+    .description('Build an app with atlaspack-inspector required feature-flags')
+    .action(async (targets) => {
+      await buildClientApplicationForInspector(targets);
+    });
+
+  program.parse(process.argv);
+
+  if (!isStartCommand) {
+    return;
+  }
+
+  const options = command.opts();
+
+  const inspectorAppParams = configureInspectorApp({
+    target: options.target,
+    projectRoot: options.projectRoot,
+  });
+  const app = buildInspectorApp(inspectorAppParams);
+
+  const port = Number(options.port ?? process.env.PORT ?? 3000);
+
+  const server = app.listen(port, () => {
+    const address: AddressInfo | string | null = server.address();
+    if (address == null) {
+      logger.error('Server did not start correctly');
+    } else {
+      const addressString =
+        typeof address === 'string'
+          ? address
+          : `http://localhost:${address.port}`;
+
+      logger.info(`Server is running on ${addressString}`);
+    }
+  });
+  server.on('error', (error) => {
+    logger.error(error, 'HTTP Server error');
+  });
+
+  return server;
+}

package/src/backend/services/AnalyticsService.ts

@@ -0,0 +1,118 @@
+import {randomUUID} from 'crypto';
+import {logger} from '../config/logger';
+
+export type AnalyticsServiceAvailableResponse =
+  | {
+      available: true;
+      name: string;
+      version: string;
+    }
+  | {
+      available: false;
+    };
+
+export interface AnalyticsEvent {
+  id?: string;
+  cwd?: string;
+  data: {
+    name?: string;
+    category?: string;
+    status?: 'success' | 'failure';
+    action: string;
+    startTimestamp?: Date;
+    product?: string;
+  };
+}
+
+/**
+ * Reports analytics events to a daemon server running at port 16621.
+ *
+ * The application will automatically check if the service is available and will not report
+ * anything if it is not.
+ */
+export class AnalyticsService {
+  private readonly daemonUrl: string = 'http://localhost:16621';
+  private isAvailable: boolean | null = null;
+
+  /**
+   * Return the analytics service status.
+   */
+  public async checkAvailable(): Promise<AnalyticsServiceAvailableResponse> {
+    const response = await fetch(`${this.daemonUrl}/version`);
+    if (!response.ok) {
+      const status = response.status;
+      const body = await response.json();
+      logger.warn(
+        {body, status},
+        'Failed to check analytics service availability',
+      );
+      this.isAvailable = false;
+      return {available: false};
+    }
+
+    const data: any = await response.json();
+
+    this.isAvailable = true;
+
+    return {
+      available: data.version !== 'unknown',
+      name: data.name,
+      version: data.version,
+    };
+  }
+
+  /**
+   * Record an analytics event.
+   */
+  async sendEvent(event: AnalyticsEvent): Promise<void> {
+    try {
+      if (this.isAvailable == null) {
+        const available = await this.checkAvailable();
+        logger.debug(
+          available,
+          `Analytics service is ${available.available ? 'available' : 'not available'}`,
+        );
+      }
+      if (!this.isAvailable) {
+        return;
+      }
+
+      const body = {
+        id: `atlaspack-inspector-${randomUUID()}`,
+        cwd: process.cwd(),
+        type: 'DISCRETE_EVENT',
+        ...event,
+        data: {
+          startTimestamp: new Date().toISOString(),
+          status: 'success',
+          product: 'atlaspack-inspector',
+          category: 'atlaspack-internal',
+          name: 'atlaspack-inspector',
+          ...event.data,
+        },
+      };
+      logger.debug({event: body}, 'Tracking analytics event');
+      const response = await fetch(`${this.daemonUrl}/events`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify(body),
+      });
+
+      if (!response.ok) {
+        const status = response.status;
+        const body = await response.json();
+        logger.warn({body, status}, 'Failed to send analytics event, skipping');
+        return;
+      }
+
+      const json = await response.json();
+      logger.debug({json}, 'Analytics event sent');
+    } catch (err) {
+      logger.warn({err}, 'Failed to send analytics event');
+    }
+  }
+}
+
+export const analyticsService = new AnalyticsService();

package/src/backend/services/LazyValue.test.ts

@@ -0,0 +1,13 @@
+import {LazyValue} from './LazyValue';
+
+describe('LazyValue', () => {
+  it('should return the value by calling the factory function once', () => {
+    const mock = jest.fn().mockImplementation(() => 'test');
+    const lazyValue = new LazyValue(mock);
+
+    expect(lazyValue.get()).toBe('test');
+    expect(lazyValue.get()).toBe('test');
+
+    expect(mock).toHaveBeenCalledTimes(1);
+  });
+});

package/src/backend/services/LazyValue.ts

@@ -0,0 +1,29 @@
+/**
+ * A value that is computed once on read, then cached.
+ *
+ * @example
+ *
+ * ```ts
+ * const lazyComputation = new LazyValue(() => doExpensiveComputation());
+ *
+ * const result1 = lazyComputation.get();
+ * const result2 = lazyComputation.get();
+ *
+ * assert(result1 === result2);
+ * ```
+ */
+export class LazyValue<T> {
+  private value: T | null = null;
+
+  constructor(private readonly factory: () => T) {}
+
+  /**
+   * Builds the value if it hasn't been built and returns it.
+   */
+  get(): T {
+    if (this.value == null) {
+      this.value = this.factory();
+    }
+    return this.value;
+  }
+}

package/src/backend/services/buildJsonGraph.ts

@@ -0,0 +1,124 @@
+/* eslint-disable import/no-extraneous-dependencies */
+/* eslint-disable monorepo/no-internal-import */
+// @ts-expect-error TS2749
+import type {Node} from '@atlaspack/core/lib/types.js';
+import {ALL_EDGE_TYPES, ContentGraph} from '@atlaspack/graph';
+import {getDisplayName} from './getDisplayName';
+
+export interface JsonGraph<T> {
+  nodes: Array<{
+    id: string;
+    nodeId: string;
+    path: string[] | null;
+    displayName: string;
+    level: number;
+    edges: string[];
+    extra: T | null;
+  }>;
+}
+
+/**
+ * Build a simplified representation of a graph for a front-end to render.
+ *
+ * The graph is simplified by:
+ * - being a JSON serialisable object
+ * - filtering out unnecessary nodes
+ * - limiting the depth of nodes returned from the root
+ */
+export function buildJsonGraph<T>(
+  graph: ContentGraph<Node>,
+  rootNodeId: string | null | undefined,
+  filter: (node: Node) => boolean = () => true,
+  extra?: (node: Node) => T,
+): JsonGraph<T> {
+  const depths = new Map<number, number>();
+
+  const rootNodeIndex = rootNodeId
+    ? graph.getNodeIdByContentKey(rootNodeId)
+    : graph.rootNodeId;
+
+  // build path from `graph.rootNodeId` node to `rootNodeId`
+  let path: number[] | null = null;
+  {
+    const stack: number[] = [];
+    const visited = new Set<number>();
+    graph.dfs({
+      visit: {
+        enter(nodeId: number, context: any, actions: {stop: () => void}) {
+          stack.push(nodeId);
+          visited.add(nodeId);
+
+          if (nodeId === rootNodeIndex) {
+            actions.stop();
+            path = stack.slice();
+          }
+        },
+        exit() {
+          stack.pop();
+        },
+      },
+      getChildren: (nodeId: number) => {
+        return graph.getNodeIdsConnectedFrom(nodeId, ALL_EDGE_TYPES);
+      },
+      startNodeId: graph.rootNodeId,
+    });
+  }
+
+  // Build depths of all nodes in the graph
+  {
+    const topologicalOrder: number[] = [];
+    graph.traverse(
+      {
+        exit(nodeId: number) {
+          topologicalOrder.push(nodeId);
+        },
+      },
+      rootNodeIndex,
+      ALL_EDGE_TYPES,
+    );
+    topologicalOrder.reverse();
+
+    for (let i = 0; i < topologicalOrder.length; i++) {
+      const nodeId = topologicalOrder[i];
+      const currentDepth = depths.get(nodeId) ?? 0;
+      const neighbors = graph.getNodeIdsConnectedFrom(nodeId, ALL_EDGE_TYPES);
+      for (const other of neighbors) {
+        const increment = filter(graph.getNode(other)) ? 1 : 0;
+        depths.set(
+          other,
+          Math.max(currentDepth + increment, depths.get(other) ?? 0),
+        );
+      }
+    }
+  }
+
+  const allNodes: string[] = [];
+  graph.traverse(
+    (nodeId: any) => {
+      allNodes.push(nodeId);
+    },
+    rootNodeIndex,
+    ALL_EDGE_TYPES,
+  );
+
+  const maxDepth = 100;
+  return {
+    nodes: allNodes
+      .filter((nodeId: any) => (depths.get(nodeId) ?? 0) < maxDepth)
+      .filter((nodeId: any) => filter(graph.getNode(nodeId)))
+      .map((nodeId: any) => ({
+        id: graph.getNode(nodeId).id,
+        nodeId,
+        path:
+          nodeId === rootNodeIndex
+            ? (path?.map((id: any) => graph.getNode(id).id) ?? null)
+            : null,
+        displayName: getDisplayName(graph.getNode(nodeId)),
+        level: depths.get(nodeId) ?? 0,
+        edges: graph
+          .getNodeIdsConnectedFrom(nodeId, ALL_EDGE_TYPES)
+          .map((nodeId) => graph.getNode(nodeId).id),
+        extra: extra ? extra(graph.getNode(nodeId)) : null,
+      })),
+  };
+}