feat(observability-map): package scaffold and route scanner

Author: 1stvamp

internal-packages/observability-map/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@internal/observability-map",
+  "private": true,
+  "version": "0.0.1",
+  "main": "./dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
+  "dependencies": {
+    "typescript": "catalog:"
+  },
+  "devDependencies": {
+    "@types/node": "^24.13.3",
+    "rimraf": "6.0.1"
+  },
+  "scripts": {
+    "clean": "rimraf dist",
+    "typecheck": "tsc --noEmit",
+    "build": "pnpm run clean && tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}

internal-packages/observability-map/src/scan.ts

@@ -0,0 +1,111 @@
+import ts from "typescript";
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { EntryPoint } from "./types.js";
+
+function calleeName(expr: ts.Expression): string | null {
+  if (ts.isIdentifier(expr)) return expr.text;
+  if (ts.isPropertyAccessExpression(expr)) return expr.name.text;
+  return null;
+}
+
+export function scanFile(fileName: string, source: string): EntryPoint | null {
+  const sf = ts.createSourceFile(fileName, source, ts.ScriptTarget.Latest, true);
+
+  const ep: EntryPoint = {
+    fileName,
+    source,
+    hasLoader: false,
+    hasAction: false,
+    loaderInitializerCallee: null,
+    actionInitializerCallee: null,
+    importedNames: [],
+    calleeNames: [],
+    hasTryCatch: false,
+    statementCount: 0,
+  };
+
+  const isExported = (n: ts.Node) =>
+    ts.canHaveModifiers(n) &&
+    ts.getModifiers(n)?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword) === true;
+
+  const visit = (node: ts.Node) => {
+    if (ts.isImportDeclaration(node) && node.importClause) {
+      const bindings = node.importClause.namedBindings;
+      if (bindings && ts.isNamedImports(bindings)) {
+        for (const el of bindings.elements) ep.importedNames.push(el.name.text);
+      }
+      if (node.importClause.name) ep.importedNames.push(node.importClause.name.text);
+    }
+
+    if (ts.isVariableStatement(node) && isExported(node)) {
+      for (const decl of node.declarationList.declarations) {
+        const name = decl.name.getText(sf);
+        if (name !== "loader" && name !== "action") continue;
+        if (name === "loader") ep.hasLoader = true;
+        if (name === "action") ep.hasAction = true;
+        let init = decl.initializer;
+        if (init && ts.isPropertyAccessExpression(init)) init = init.expression;
+        if (init && ts.isCallExpression(init)) {
+          const cn = calleeName(init.expression);
+          if (name === "loader") ep.loaderInitializerCallee = cn;
+          else ep.actionInitializerCallee = cn;
+        }
+      }
+    }
+
+    if (ts.isFunctionDeclaration(node) && node.name && isExported(node)) {
+      if (node.name.text === "loader") ep.hasLoader = true;
+      if (node.name.text === "action") ep.hasAction = true;
+      if (node.body) ep.statementCount += node.body.statements.length;
+    }
+
+    if (ts.isTryStatement(node)) ep.hasTryCatch = true;
+
+    if (ts.isCallExpression(node)) {
+      const cn = calleeName(node.expression);
+      if (cn) ep.calleeNames.push(cn);
+    }
+
+    ts.forEachChild(node, visit);
+  };
+
+  visit(sf);
+
+  if (!ep.hasLoader && !ep.hasAction) return null;
+  if (ep.statementCount === 0) {
+    ep.statementCount = countArrowBodyStatements(sf);
+  }
+  return ep;
+}
+
+function countArrowBodyStatements(sf: ts.SourceFile): number {
+  let count = 0;
+  const visit = (n: ts.Node) => {
+    if ((ts.isArrowFunction(n) || ts.isFunctionExpression(n)) && n.body && ts.isBlock(n.body)) {
+      count += n.body.statements.length;
+    }
+    ts.forEachChild(n, visit);
+  };
+  visit(sf);
+  return count;
+}
+
+export function scanDirectory(dir: string): {
+  entryPoints: EntryPoint[];
+  parseFailures: string[];
+} {
+  const entryPoints: EntryPoint[] = [];
+  const parseFailures: string[] = [];
+  const files = readdirSync(dir).filter((f) => /\.(ts|tsx)$/.test(f) && !f.endsWith(".test.ts"));
+
+  for (const fileName of files) {
+    try {
+      const ep = scanFile(fileName, readFileSync(join(dir, fileName), "utf8"));
+      if (ep) entryPoints.push(ep);
+    } catch {
+      parseFailures.push(fileName);
+    }
+  }
+  return { entryPoints, parseFailures };
+}

internal-packages/observability-map/src/types.ts

@@ -0,0 +1,22 @@
+export type CheckStatus = "pass" | "fail" | "not-applicable";
+
+export type CheckResult = {
+  id: string;
+  status: CheckStatus;
+  detail?: string;
+};
+
+export type EntryPoint = {
+  fileName: string;
+  source: string;
+  hasLoader: boolean;
+  hasAction: boolean;
+  /** Callee name when `loader`/`action` is assigned from a call, e.g. a route builder. */
+  loaderInitializerCallee: string | null;
+  actionInitializerCallee: string | null;
+  importedNames: string[];
+  calleeNames: string[];
+  hasTryCatch: boolean;
+  /** Statement count across loader/action bodies, used by the triviality rule. */
+  statementCount: number;
+};

internal-packages/observability-map/test/scan.test.ts

@@ -0,0 +1,29 @@
+import { scanFile } from "../src/scan.js";
+
+const LOADER = `
+import { json } from "@remix-run/server-runtime";
+export async function loader() { return json({}); }
+`;
+
+const COMPONENT_ONLY = `
+export default function Page() { return null; }
+`;
+
+describe("scanFile", () => {
+  it("detects an exported loader as a server entry point", () => {
+    const ep = scanFile("api.v1.things.ts", LOADER);
+    expect(ep).not.toBeNull();
+    expect(ep!.hasLoader).toBe(true);
+    expect(ep!.hasAction).toBe(false);
+  });
+
+  it("ignores a route that only exports a component", () => {
+    expect(scanFile("_app.things.tsx", COMPONENT_ONLY)).toBeNull();
+  });
+
+  it("detects a loader assigned from a call expression", () => {
+    const ep = scanFile("api.v1.x.ts", `export const loader = createLoaderApiRoute({});`);
+    expect(ep!.hasLoader).toBe(true);
+    expect(ep!.loaderInitializerCallee).toBe("createLoaderApiRoute");
+  });
+});

internal-packages/observability-map/tsconfig.build.json

@@ -0,0 +1,5 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": { "noEmit": false, "outDir": "dist", "declaration": true },
+  "exclude": ["node_modules", "dist", "test"]
+}

internal-packages/observability-map/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2019",
+    "lib": ["ES2019"],
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "isolatedModules": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "strict": true,
+    "types": ["vitest/globals", "node"],
+    "customConditions": ["@triggerdotdev/source"]
+  },
+  "exclude": ["node_modules", "dist"]
+}

internal-packages/observability-map/vitest.config.ts

@@ -0,0 +1,5 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: { include: ["**/*.test.ts"], globals: true, isolate: true, testTimeout: 10_000 },
+});