@rk0429/agentic-relay 22.0.0 → 22.2.0

package/scripts/check-chat-boundary.mjs

@@ -0,0 +1,220 @@
+import { existsSync } from "node:fs";
+import { readdir, readFile } from "node:fs/promises";
+import path from "node:path";
+import { builtinModules } from "node:module";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const PROJECT_ROOT = path.resolve(__dirname, "..");
+const TARGET_DIRECTORY_SEGMENTS = [
+  ["src", "domain", "chat"],
+  ["src", "application", "chat"],
+];
+const STATIC_IMPORT_RE =
+  /^[\t ]*import(?:\s+type)?(?:[\s\S]*?\sfrom\s+|\s+)["']([^"'\n]+)["'];?/gm;
+const DYNAMIC_IMPORT_RE = /\bimport\s*\(\s*["']([^"'\n]+)["']\s*\)/g;
+
+export const CHAT_BOUNDARY_ALLOWLIST = [];
+
+const builtinModuleNames = new Set(
+  builtinModules.flatMap((name) =>
+    name.startsWith("node:") ? [name, name.slice(5)] : [name, `node:${name}`],
+  ),
+);
+
+export async function checkChatBoundary(options = {}) {
+  const projectRoot = options.projectRoot ?? PROJECT_ROOT;
+  const targetFiles = await collectTargetFiles(projectRoot);
+  const violations = [];
+  const matchedAllowlist = new Set();
+
+  for (const filePath of targetFiles) {
+    const source = await readFile(filePath, "utf8");
+    const sourceRelativePath = toPosixPath(path.relative(projectRoot, filePath));
+
+    for (const entry of findImports(source)) {
+      const allowlistKey = `${sourceRelativePath}::${entry.specifier}`;
+      if (
+        CHAT_BOUNDARY_ALLOWLIST.some(
+          (item) =>
+            item.importer === sourceRelativePath && item.specifier === entry.specifier,
+        )
+      ) {
+        matchedAllowlist.add(allowlistKey);
+        continue;
+      }
+
+      if (isAllowedImport(filePath, entry.specifier, projectRoot)) {
+        continue;
+      }
+
+      violations.push({
+        file: sourceRelativePath,
+        line: entry.line,
+        specifier: entry.specifier,
+      });
+    }
+  }
+
+  const warnings = CHAT_BOUNDARY_ALLOWLIST.filter(
+    (entry) => !matchedAllowlist.has(`${entry.importer}::${entry.specifier}`),
+  ).map((entry) => ({
+    importer: entry.importer,
+    specifier: entry.specifier,
+    reason: entry.reason,
+  }));
+
+  return { violations, warnings };
+}
+
+async function collectTargetFiles(projectRoot) {
+  const files = [];
+  for (const directory of TARGET_DIRECTORY_SEGMENTS.map((segments) =>
+    path.join(projectRoot, ...segments),
+  )) {
+    files.push(...(await walk(directory)));
+  }
+  return files.filter((filePath) => filePath.endsWith(".ts") && !filePath.endsWith(".test.ts"));
+}
+
+async function walk(directory) {
+  const entries = await readdir(directory, { withFileTypes: true });
+  const files = [];
+
+  for (const entry of entries) {
+    const fullPath = path.join(directory, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...(await walk(fullPath)));
+      continue;
+    }
+    if (entry.isFile()) {
+      files.push(fullPath);
+    }
+  }
+
+  return files;
+}
+
+function findImports(source) {
+  return [STATIC_IMPORT_RE, DYNAMIC_IMPORT_RE]
+    .flatMap((pattern) =>
+      [...source.matchAll(pattern)].map((match) => ({
+        specifier: match[1],
+        line: lineNumberAt(source, match.index ?? 0),
+        index: match.index ?? 0,
+      })),
+    )
+    .sort((left, right) => left.index - right.index)
+    .map(({ specifier, line }) => ({ specifier, line }));
+}
+
+function lineNumberAt(source, index) {
+  return source.slice(0, index).split("\n").length;
+}
+
+function isAllowedImport(sourceFilePath, specifier, projectRoot) {
+  if (builtinModuleNames.has(specifier)) {
+    return true;
+  }
+
+  if (!specifier.startsWith(".")) {
+    return true;
+  }
+
+  const resolvedTargetPath = resolveImport(sourceFilePath, specifier);
+  if (!resolvedTargetPath) {
+    return false;
+  }
+
+  const sourceRelativePath = toPosixPath(path.relative(projectRoot, sourceFilePath));
+  const targetRelativePath = toPosixPath(path.relative(projectRoot, resolvedTargetPath));
+  const sourceDirectory = toPosixPath(path.dirname(sourceRelativePath));
+  const targetDirectory = toPosixPath(path.dirname(targetRelativePath));
+  const sourceIsApplicationChat = sourceRelativePath.startsWith("src/application/chat/");
+
+  if (specifier.startsWith("./") && sourceDirectory === targetDirectory) {
+    return true;
+  }
+
+  if (targetRelativePath === "src/core/types.ts") {
+    return true;
+  }
+
+  if (targetRelativePath.startsWith("src/domain/chat/")) {
+    return true;
+  }
+
+  if (sourceIsApplicationChat && targetRelativePath.startsWith("src/application/chat/")) {
+    return true;
+  }
+
+  return false;
+}
+
+function resolveImport(sourceFilePath, specifier) {
+  const candidateBasePath = path.resolve(path.dirname(sourceFilePath), specifier);
+  return buildResolutionCandidates(candidateBasePath).find(fileExists) ?? null;
+}
+
+function buildResolutionCandidates(candidateBasePath) {
+  const extension = path.extname(candidateBasePath);
+
+  if (extension === ".ts" || extension === ".mts" || extension === ".cts") {
+    return [candidateBasePath];
+  }
+
+  if (extension === ".js") {
+    return [candidateBasePath.slice(0, -3) + ".ts"];
+  }
+
+  if (extension === ".mjs") {
+    return [candidateBasePath.slice(0, -4) + ".mts"];
+  }
+
+  if (extension === ".cjs") {
+    return [candidateBasePath.slice(0, -4) + ".cts"];
+  }
+
+  return [
+    `${candidateBasePath}.ts`,
+    `${candidateBasePath}.mts`,
+    `${candidateBasePath}.cts`,
+    path.join(candidateBasePath, "index.ts"),
+    path.join(candidateBasePath, "index.mts"),
+    path.join(candidateBasePath, "index.cts"),
+  ];
+}
+
+function fileExists(filePath) {
+  return Boolean(filePath) && existsSync(filePath);
+}
+
+function toPosixPath(filePath) {
+  return filePath.split(path.sep).join("/");
+}
+
+async function main() {
+  const { violations, warnings } = await checkChatBoundary();
+
+  for (const warning of warnings) {
+    console.error(
+      `warning: stale allowlist entry: ${warning.importer}:${warning.specifier} (${warning.reason})`,
+    );
+  }
+
+  if (violations.length > 0) {
+    for (const violation of violations) {
+      console.error(
+        `AF-1 violation: ${violation.file}:${violation.line} imports "${violation.specifier}"`,
+      );
+    }
+    process.exitCode = 1;
+    return;
+  }
+
+  console.error("✓ AF-1: chat boundary isolation check passed");
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === path.resolve(process.argv[1])) {
+  await main();
+}

package/scripts/check-chat-boundary.test.ts

@@ -0,0 +1,139 @@
+import { mkdtemp, mkdir, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { CHAT_BOUNDARY_ALLOWLIST, checkChatBoundary } from "./check-chat-boundary.mjs";
+
+const workspaces: string[] = [];
+
+afterEach(async () => {
+  const { rm } = await import("node:fs/promises");
+  await Promise.all(workspaces.map((workspace) => rm(workspace, { recursive: true, force: true })));
+  workspaces.length = 0;
+});
+
+describe("checkChatBoundary", () => {
+  it("accepts allowed imports including src/core/types.ts", async () => {
+    const projectRoot = await createBoundaryFixture({
+      "src/application/chat/chat-daemon-service.ts": [
+        'import { execFile } from "node:child_process";',
+        'import { ValidationError } from "../../core/types.js";',
+        'import { ChatOutboundHandler } from "./chat-outbound-handler.js";',
+        'import type { ChatPlatformAdapter } from "../../domain/chat/ports.js";',
+        "void execFile;",
+        "void ValidationError;",
+        "void ChatOutboundHandler;",
+      ].join("\n"),
+      "src/application/chat/chat-outbound-handler.ts": [
+        'import { MessageSplitter } from "../../domain/chat/message-splitter.js";',
+        "void MessageSplitter;",
+      ].join("\n"),
+      "src/core/types.ts": "export class ValidationError extends Error {}\n",
+      "src/domain/chat/message-splitter.ts": "export class MessageSplitter {}\n",
+      "src/domain/chat/ports.ts": "export interface ChatPlatformAdapter {}\n",
+    });
+
+    const result = await checkChatBoundary({ projectRoot });
+
+    expect(result.violations).toEqual([]);
+    expect(result.warnings).toEqual([]);
+  });
+
+  it("reports imports that escape the allowed chat boundary", async () => {
+    const projectRoot = await createBoundaryFixture({
+      "src/application/chat/chat-daemon-service.ts": [
+        'import { ValidationError } from "../../core/errors.js";',
+        "void ValidationError;",
+      ].join("\n"),
+      "src/core/errors.ts": "export class ValidationError extends Error {}\n",
+      "src/domain/chat/bad.ts": [
+        'import { resolveChatConfig } from "../config.js";',
+        "void resolveChatConfig;",
+      ].join("\n"),
+      "src/domain/config.ts": "export function resolveChatConfig() { return {}; }\n",
+    });
+
+    const result = await checkChatBoundary({ projectRoot });
+
+    expect(result.violations).toEqual([
+      {
+        file: "src/domain/chat/bad.ts",
+        line: 1,
+        specifier: "../config.js",
+      },
+      {
+        file: "src/application/chat/chat-daemon-service.ts",
+        line: 1,
+        specifier: "../../core/errors.js",
+      },
+    ]);
+  });
+
+  it("reports dynamic imports that escape the allowed chat boundary", async () => {
+    const projectRoot = await createBoundaryFixture({
+      "src/application/chat/chat-daemon-service.ts": [
+        'async function loadConfig() {',
+        '  return import("../../domain/config.js");',
+        "}",
+        "void loadConfig;",
+      ].join("\n"),
+      "src/domain/config.ts": "export function resolveChatConfig() { return {}; }\n",
+      "src/domain/chat/message-splitter.ts": "export class MessageSplitter {}\n",
+    });
+
+    const result = await checkChatBoundary({ projectRoot });
+
+    expect(result.violations).toEqual([
+      {
+        file: "src/application/chat/chat-daemon-service.ts",
+        line: 2,
+        specifier: "../../domain/config.js",
+      },
+    ]);
+  });
+
+  it("warns on stale allowlist entries", async () => {
+    CHAT_BOUNDARY_ALLOWLIST.push({
+      importer: "src/application/chat/chat-daemon-service.ts",
+      specifier: "../../domain/config.js",
+      reason: "temporary exception for test",
+    });
+
+    try {
+      const projectRoot = await createBoundaryFixture({
+        "src/application/chat/chat-daemon-service.ts": [
+          'import { ValidationError } from "../../core/types.js";',
+          "void ValidationError;",
+        ].join("\n"),
+        "src/core/types.ts": "export class ValidationError extends Error {}\n",
+        "src/domain/chat/message-splitter.ts": "export class MessageSplitter {}\n",
+      });
+
+      const result = await checkChatBoundary({ projectRoot });
+
+      expect(result.violations).toEqual([]);
+      expect(result.warnings).toEqual([
+        {
+          importer: "src/application/chat/chat-daemon-service.ts",
+          specifier: "../../domain/config.js",
+          reason: "temporary exception for test",
+        },
+      ]);
+    } finally {
+      CHAT_BOUNDARY_ALLOWLIST.splice(0);
+    }
+  });
+});
+
+async function createBoundaryFixture(files: Record<string, string>) {
+  const projectRoot = await mkdtemp(path.join(os.tmpdir(), "agentic-relay-boundary-"));
+  workspaces.push(projectRoot);
+
+  for (const [relativePath, content] of Object.entries(files)) {
+    const absolutePath = path.join(projectRoot, relativePath);
+    await mkdir(path.dirname(absolutePath), { recursive: true });
+    await writeFile(absolutePath, content, "utf8");
+  }
+
+  return projectRoot;
+}

package/scripts/check-circular-deps.mjs

@@ -0,0 +1,199 @@
+import { existsSync } from "node:fs";
+import { readdir, readFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const PROJECT_ROOT = path.resolve(__dirname, "..");
+const STATIC_IMPORT_RE =
+  /^[\t ]*import(?!\s+type\b)(?:[\s\S]*?\sfrom\s+|\s+)["']([^"'\n]+)["'];?/gm;
+const DYNAMIC_IMPORT_RE = /\bimport\s*\(\s*["']([^"'\n]+)["']\s*\)/g;
+
+export async function checkCircularDeps(options = {}) {
+  const projectRoot = options.projectRoot ?? PROJECT_ROOT;
+  const graph = await buildDependencyGraph(projectRoot);
+  const cycles = findCircularDependencies(graph);
+  return { graph, cycles };
+}
+
+export async function buildDependencyGraph(projectRoot = PROJECT_ROOT) {
+  const srcRoot = path.join(projectRoot, "src");
+  const files = await walk(srcRoot);
+  const graph = new Map();
+
+  for (const filePath of files) {
+    if (!filePath.endsWith(".ts") || filePath.endsWith(".test.ts") || filePath.endsWith(".d.ts")) {
+      continue;
+    }
+
+    const source = await readFile(filePath, "utf8");
+    const dependencies = new Set();
+    for (const specifier of findImportSpecifiers(source)) {
+      if (!specifier.startsWith(".")) {
+        continue;
+      }
+      const resolvedTargetPath = resolveImport(filePath, specifier);
+      if (!resolvedTargetPath?.startsWith(srcRoot)) {
+        continue;
+      }
+      if (resolvedTargetPath.endsWith(".test.ts")) {
+        continue;
+      }
+      dependencies.add(toPosixPath(path.relative(projectRoot, resolvedTargetPath)));
+    }
+
+    graph.set(toPosixPath(path.relative(projectRoot, filePath)), dependencies);
+  }
+
+  return graph;
+}
+
+export function findCircularDependencies(graph) {
+  const visiting = new Set();
+  const visited = new Set();
+  const stack = [];
+  const cycles = [];
+  const seenCycles = new Set();
+
+  const nodes = [...graph.keys()].sort();
+
+  const visit = (node) => {
+    visiting.add(node);
+    stack.push(node);
+
+    for (const dependency of [...(graph.get(node) ?? [])].sort()) {
+      if (!graph.has(dependency)) {
+        continue;
+      }
+
+      if (visiting.has(dependency)) {
+        const startIndex = stack.indexOf(dependency);
+        const cycle = stack.slice(startIndex).concat(dependency);
+        const cycleKey = canonicalizeCycle(cycle.slice(0, -1));
+        if (!seenCycles.has(cycleKey)) {
+          seenCycles.add(cycleKey);
+          cycles.push(cycle);
+        }
+        continue;
+      }
+
+      if (!visited.has(dependency)) {
+        visit(dependency);
+      }
+    }
+
+    stack.pop();
+    visiting.delete(node);
+    visited.add(node);
+  };
+
+  for (const node of nodes) {
+    if (!visited.has(node)) {
+      visit(node);
+    }
+  }
+
+  return cycles;
+}
+
+async function walk(directory) {
+  const entries = await readdir(directory, { withFileTypes: true });
+  const files = [];
+
+  for (const entry of entries) {
+    if (entry.name === "dist" || entry.name === "node_modules") {
+      continue;
+    }
+
+    const fullPath = path.join(directory, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...(await walk(fullPath)));
+      continue;
+    }
+    if (entry.isFile()) {
+      files.push(fullPath);
+    }
+  }
+
+  return files;
+}
+
+function findImportSpecifiers(source) {
+  const specifiers = new Set();
+
+  for (const match of source.matchAll(STATIC_IMPORT_RE)) {
+    specifiers.add(match[1]);
+  }
+
+  for (const match of source.matchAll(DYNAMIC_IMPORT_RE)) {
+    specifiers.add(match[1]);
+  }
+
+  return [...specifiers];
+}
+
+function resolveImport(sourceFilePath, specifier) {
+  const candidateBasePath = path.resolve(path.dirname(sourceFilePath), specifier);
+  return buildResolutionCandidates(candidateBasePath).find(fileExists) ?? null;
+}
+
+function buildResolutionCandidates(candidateBasePath) {
+  const extension = path.extname(candidateBasePath);
+
+  if (extension === ".ts" || extension === ".mts" || extension === ".cts") {
+    return [candidateBasePath];
+  }
+
+  if (extension === ".js") {
+    return [candidateBasePath.slice(0, -3) + ".ts"];
+  }
+
+  if (extension === ".mjs") {
+    return [candidateBasePath.slice(0, -4) + ".mts"];
+  }
+
+  if (extension === ".cjs") {
+    return [candidateBasePath.slice(0, -4) + ".cts"];
+  }
+
+  return [
+    `${candidateBasePath}.ts`,
+    `${candidateBasePath}.mts`,
+    `${candidateBasePath}.cts`,
+    path.join(candidateBasePath, "index.ts"),
+    path.join(candidateBasePath, "index.mts"),
+    path.join(candidateBasePath, "index.cts"),
+  ];
+}
+
+function canonicalizeCycle(cycle) {
+  const rotations = cycle.map((_, index) =>
+    [...cycle.slice(index), ...cycle.slice(0, index)].join("->"),
+  );
+  return rotations.sort()[0];
+}
+
+function fileExists(filePath) {
+  return Boolean(filePath) && existsSync(filePath);
+}
+
+function toPosixPath(filePath) {
+  return filePath.split(path.sep).join("/");
+}
+
+async function main() {
+  const { cycles } = await checkCircularDeps();
+  if (cycles.length > 0) {
+    for (const cycle of cycles) {
+      console.error(`AF-2 cycle: ${cycle.join(" -> ")}`);
+    }
+    process.exitCode = 1;
+    return;
+  }
+
+  console.error("✓ AF-2: no circular dependencies found");
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === path.resolve(process.argv[1])) {
+  await main();
+}

package/scripts/check-circular-deps.test.ts

@@ -0,0 +1,62 @@
+import { mkdtemp, mkdir, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { checkCircularDeps } from "./check-circular-deps.mjs";
+
+const workspaces: string[] = [];
+
+afterEach(async () => {
+  const { rm } = await import("node:fs/promises");
+  await Promise.all(workspaces.map((workspace) => rm(workspace, { recursive: true, force: true })));
+  workspaces.length = 0;
+});
+
+describe("checkCircularDeps", () => {
+  it("passes when relative imports do not form a cycle", async () => {
+    const projectRoot = await createCircularFixture({
+      "src/a.ts": 'import "./b.js";\n',
+      "src/b.ts": 'await import("./c.js");\n',
+      "src/c.ts": "export const c = 1;\n",
+    });
+
+    const result = await checkCircularDeps({ projectRoot });
+
+    expect(result.cycles).toEqual([]);
+  });
+
+  it("detects cycles across static and dynamic imports", async () => {
+    const projectRoot = await createCircularFixture({
+      "src/a.ts": 'await import("./b.js");\n',
+      "src/b.ts": 'import "./a.js";\n',
+    });
+
+    const result = await checkCircularDeps({ projectRoot });
+
+    expect(result.cycles).toEqual([["src/a.ts", "src/b.ts", "src/a.ts"]]);
+  });
+
+  it("ignores import type edges when detecting cycles", async () => {
+    const projectRoot = await createCircularFixture({
+      "src/a.ts": 'import type { B } from "./b.js";\nexport type A = { b: B };\n',
+      "src/b.ts": 'import type { A } from "./a.js";\nexport type B = { a: A };\n',
+    });
+
+    const result = await checkCircularDeps({ projectRoot });
+
+    expect(result.cycles).toEqual([]);
+  });
+});
+
+async function createCircularFixture(files: Record<string, string>) {
+  const projectRoot = await mkdtemp(path.join(os.tmpdir(), "agentic-relay-circular-"));
+  workspaces.push(projectRoot);
+
+  for (const [relativePath, content] of Object.entries(files)) {
+    const absolutePath = path.join(projectRoot, relativePath);
+    await mkdir(path.dirname(absolutePath), { recursive: true });
+    await writeFile(absolutePath, content, "utf8");
+  }
+
+  return projectRoot;
+}

package/dist/core/chat-types.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"chat-types.js","sourceRoot":"","sources":["../../src/core/chat-types.ts"],"names":[],"mappings":"AAAA,MAAM,CAAN,IAAY,YAGX;AAHD,WAAY,YAAY;IACtB,+BAAe,CAAA;IACf,mCAAmB,CAAA;AACrB,CAAC,EAHW,YAAY,KAAZ,YAAY,QAGvB;AAED,MAAM,CAAN,IAAY,eAMX;AAND,WAAY,eAAe;IACzB,gDAA6B,CAAA;IAC7B,4CAAyB,CAAA;IACzB,0CAAuB,CAAA;IACvB,gDAA6B,CAAA;IAC7B,oCAAiB,CAAA;AACnB,CAAC,EANW,eAAe,KAAf,eAAe,QAM1B"}