@beignet/cli 0.0.1

package/src/lint.ts

@@ -0,0 +1,785 @@
+import { readdir, readFile, stat } from "node:fs/promises";
+import path from "node:path";
+import {
+  type BeignetConfig,
+  directoryPath,
+  loadBeignetConfig,
+  normalizePath,
+  type ResolvedBeignetConfig,
+  resolveConfig,
+} from "./config.js";
+
+type LintAppOptions = {
+  cwd?: string;
+  config?: BeignetConfig;
+};
+
+type SourceLayer =
+  | "app"
+  | "app-context"
+  | "client"
+  | "component"
+  | "contract"
+  | "domain"
+  | "feature-port"
+  | "infra"
+  | "lib"
+  | "policy"
+  | "port"
+  | "route"
+  | "server"
+  | "test"
+  | "use-case"
+  | "unknown";
+
+type ImportReference = {
+  importPath: string;
+  resolvedPath?: string;
+  packageName?: string;
+};
+
+export type LintDiagnostic = {
+  severity: "error";
+  code: string;
+  message: string;
+  file: string;
+  importPath: string;
+};
+
+export type LintAppResult = {
+  targetDir: string;
+  config: ResolvedBeignetConfig;
+  diagnostics: LintDiagnostic[];
+};
+
+export async function lintApp(
+  options: LintAppOptions = {},
+): Promise<LintAppResult> {
+  const targetDir = path.resolve(options.cwd ?? process.cwd());
+  await assertDirectory(targetDir);
+
+  const files = await listFiles(targetDir);
+  const config = options.config
+    ? resolveConfig(options.config)
+    : await loadBeignetConfig(targetDir, files);
+  const diagnostics: LintDiagnostic[] = [];
+
+  for (const file of lintSourceFiles(files)) {
+    const sourceLayer = classifyPath(file, config);
+    if (sourceLayer === "test" || sourceLayer === "unknown") continue;
+
+    const source = await readFile(path.join(targetDir, file), "utf8");
+    for (const reference of parseImports(source, file)) {
+      const diagnostic = lintImport(file, sourceLayer, reference, config);
+      if (diagnostic) diagnostics.push(diagnostic);
+    }
+  }
+
+  return {
+    targetDir,
+    config,
+    diagnostics: dedupeDiagnostics(diagnostics),
+  };
+}
+
+export function formatLint(result: LintAppResult): string {
+  if (result.diagnostics.length === 0) {
+    return `No Beignet lint issues found in ${result.targetDir}.`;
+  }
+
+  return [
+    `Found ${result.diagnostics.length} Beignet lint issue${
+      result.diagnostics.length === 1 ? "" : "s"
+    } in ${result.targetDir}:`,
+    "",
+    ...result.diagnostics.map(
+      (diagnostic) => `ERROR ${diagnostic.code} ${diagnostic.file}
+  ${diagnostic.message}`,
+    ),
+  ].join("\n");
+}
+
+async function assertDirectory(targetDir: string): Promise<void> {
+  try {
+    const stats = await stat(targetDir);
+    if (!stats.isDirectory()) {
+      throw new Error(`${targetDir} is not a directory.`);
+    }
+  } catch (error) {
+    if (error instanceof Error && error.message.includes("not a directory")) {
+      throw error;
+    }
+    throw new Error(`Directory ${targetDir} does not exist.`);
+  }
+}
+
+async function listFiles(targetDir: string): Promise<string[]> {
+  const files: string[] = [];
+
+  async function visit(relativeDir: string): Promise<void> {
+    const absoluteDir = path.join(targetDir, relativeDir);
+    const entries = await readdir(absoluteDir, { withFileTypes: true });
+
+    for (const entry of entries) {
+      if (ignoredDirectoryNames.has(entry.name)) continue;
+
+      const relativePath = normalizePath(path.join(relativeDir, entry.name));
+      if (entry.isDirectory()) {
+        await visit(relativePath);
+      } else if (entry.isFile()) {
+        files.push(relativePath);
+      }
+    }
+  }
+
+  await visit("");
+  return files.sort();
+}
+
+const ignoredDirectoryNames = new Set([
+  ".git",
+  ".next",
+  ".turbo",
+  "coverage",
+  "dist",
+  "node_modules",
+]);
+
+function lintSourceFiles(files: string[]): string[] {
+  return files.filter((file) => {
+    if (file.endsWith(".d.ts")) return false;
+    return /\.(c|m)?tsx?$/.test(file);
+  });
+}
+
+function parseImports(source: string, importerFile: string): ImportReference[] {
+  const references = parseImportSpecifiers(source);
+
+  return references.map((importPath) => ({
+    importPath,
+    ...resolveImport(importPath, importerFile),
+  }));
+}
+
+function parseImportSpecifiers(source: string): string[] {
+  const specifiers: string[] = [];
+  let index = 0;
+
+  while (index < source.length) {
+    index = skipNonCode(source, index);
+
+    if (isKeywordAt(source, index, "import")) {
+      const parsed = parseImportSpecifierAt(source, index + "import".length);
+      if (parsed?.specifier) specifiers.push(parsed.specifier);
+      index = parsed?.end ?? index + "import".length;
+      continue;
+    }
+
+    if (isKeywordAt(source, index, "export")) {
+      const parsed = parseExportSpecifierAt(source, index + "export".length);
+      if (parsed?.specifier) specifiers.push(parsed.specifier);
+      index = parsed?.end ?? index + "export".length;
+      continue;
+    }
+
+    index++;
+  }
+
+  return specifiers;
+}
+
+function parseImportSpecifierAt(
+  source: string,
+  index: number,
+): { specifier?: string; end: number } | undefined {
+  let cursor = skipWhitespaceAndComments(source, index);
+  if (source[cursor] === "(") {
+    cursor = skipWhitespaceAndComments(source, cursor + 1);
+    const stringLiteral = readStringLiteral(source, cursor);
+    if (!stringLiteral) return { end: cursor };
+    return {
+      specifier: stringLiteral.value,
+      end: stringLiteral.end,
+    };
+  }
+
+  const sideEffectImport = readStringLiteral(source, cursor);
+  if (sideEffectImport) {
+    return {
+      specifier: sideEffectImport.value,
+      end: sideEffectImport.end,
+    };
+  }
+
+  while (cursor < source.length) {
+    cursor = skipWhitespaceAndComments(source, cursor);
+
+    if (source[cursor] === ";" || source[cursor] === "\n") {
+      return { end: cursor + 1 };
+    }
+
+    if (isKeywordAt(source, cursor, "from")) {
+      const fromCursor = skipWhitespaceAndComments(
+        source,
+        cursorAfterKeyword("from", cursor),
+      );
+      const stringLiteral = readStringLiteral(source, fromCursor);
+      if (!stringLiteral) return { end: fromCursor };
+      return {
+        specifier: stringLiteral.value,
+        end: stringLiteral.end,
+      };
+    }
+
+    cursor = skipToken(source, cursor);
+  }
+
+  return undefined;
+}
+
+function parseExportSpecifierAt(
+  source: string,
+  index: number,
+): { specifier?: string; end: number } | undefined {
+  let cursor = index;
+
+  while (cursor < source.length) {
+    cursor = skipWhitespaceAndComments(source, cursor);
+
+    if (source[cursor] === ";" || source[cursor] === "\n") {
+      return { end: cursor + 1 };
+    }
+
+    if (isKeywordAt(source, cursor, "from")) {
+      const fromCursor = skipWhitespaceAndComments(
+        source,
+        cursorAfterKeyword("from", cursor),
+      );
+      const stringLiteral = readStringLiteral(source, fromCursor);
+      if (!stringLiteral) return { end: fromCursor };
+      return {
+        specifier: stringLiteral.value,
+        end: stringLiteral.end,
+      };
+    }
+
+    cursor = skipToken(source, cursor);
+  }
+
+  return undefined;
+}
+
+function cursorAfterKeyword(keyword: string, index: number): number {
+  return index + keyword.length;
+}
+
+function skipNonCode(source: string, index: number): number {
+  let cursor = index;
+
+  while (cursor < source.length) {
+    if (source.startsWith("//", cursor)) {
+      cursor = skipLineComment(source, cursor);
+      continue;
+    }
+    if (source.startsWith("/*", cursor)) {
+      cursor = skipBlockComment(source, cursor);
+      continue;
+    }
+    if (source[cursor] === '"' || source[cursor] === "'") {
+      cursor = skipStringLiteral(source, cursor);
+      continue;
+    }
+    if (source[cursor] === "`") {
+      cursor = skipTemplateLiteral(source, cursor);
+      continue;
+    }
+    break;
+  }
+
+  return cursor;
+}
+
+function skipWhitespaceAndComments(source: string, index: number): number {
+  let cursor = index;
+
+  while (cursor < source.length) {
+    if (/\s/.test(source[cursor])) {
+      cursor++;
+      continue;
+    }
+    if (source.startsWith("//", cursor)) {
+      cursor = skipLineComment(source, cursor);
+      continue;
+    }
+    if (source.startsWith("/*", cursor)) {
+      cursor = skipBlockComment(source, cursor);
+      continue;
+    }
+    break;
+  }
+
+  return cursor;
+}
+
+function skipToken(source: string, index: number): number {
+  if (source[index] === '"' || source[index] === "'") {
+    return skipStringLiteral(source, index);
+  }
+  if (source[index] === "`") {
+    return skipTemplateLiteral(source, index);
+  }
+
+  return index + 1;
+}
+
+function readStringLiteral(
+  source: string,
+  index: number,
+): { value: string; end: number } | undefined {
+  const quote = source[index];
+  if (quote !== '"' && quote !== "'") return undefined;
+
+  let value = "";
+  let escaped = false;
+
+  for (let cursor = index + 1; cursor < source.length; cursor++) {
+    const char = source[cursor];
+    if (escaped) {
+      value += char;
+      escaped = false;
+      continue;
+    }
+    if (char === "\\") {
+      escaped = true;
+      continue;
+    }
+    if (char === quote) {
+      return { value, end: cursor + 1 };
+    }
+    value += char;
+  }
+
+  return undefined;
+}
+
+function skipStringLiteral(source: string, index: number): number {
+  return readStringLiteral(source, index)?.end ?? source.length;
+}
+
+function skipTemplateLiteral(source: string, index: number): number {
+  let escaped = false;
+
+  for (let cursor = index + 1; cursor < source.length; cursor++) {
+    const char = source[cursor];
+    if (escaped) {
+      escaped = false;
+      continue;
+    }
+    if (char === "\\") {
+      escaped = true;
+      continue;
+    }
+    if (char === "`") {
+      return cursor + 1;
+    }
+  }
+
+  return source.length;
+}
+
+function skipLineComment(source: string, index: number): number {
+  const end = source.indexOf("\n", index + 2);
+  return end === -1 ? source.length : end + 1;
+}
+
+function skipBlockComment(source: string, index: number): number {
+  const end = source.indexOf("*/", index + 2);
+  return end === -1 ? source.length : end + 2;
+}
+
+function isKeywordAt(source: string, index: number, keyword: string): boolean {
+  if (!source.startsWith(keyword, index)) return false;
+
+  const before = source[index - 1];
+  const after = source[index + keyword.length];
+  return !isIdentifierChar(before) && !isIdentifierChar(after);
+}
+
+function isIdentifierChar(char: string | undefined): boolean {
+  return Boolean(char && /[A-Za-z0-9_$]/.test(char));
+}
+
+function resolveImport(
+  importPath: string,
+  importerFile: string,
+): Pick<ImportReference, "packageName" | "resolvedPath"> {
+  if (importPath.startsWith("@/")) {
+    return {
+      resolvedPath: stripKnownExtension(importPath.slice(2)),
+    };
+  }
+
+  if (importPath.startsWith(".")) {
+    return {
+      resolvedPath: stripKnownExtension(
+        normalizePath(path.join(path.dirname(importerFile), importPath)),
+      ),
+    };
+  }
+
+  return {
+    packageName: packageName(importPath),
+  };
+}
+
+function packageName(importPath: string): string {
+  if (!importPath.startsWith("@")) return importPath.split("/")[0];
+
+  const [scope, name] = importPath.split("/");
+  return `${scope}/${name}`;
+}
+
+function stripKnownExtension(filePath: string): string {
+  return filePath.replace(/\.(c|m)?tsx?$/, "");
+}
+
+function lintImport(
+  file: string,
+  sourceLayer: SourceLayer,
+  reference: ImportReference,
+  config: ResolvedBeignetConfig,
+): LintDiagnostic | undefined {
+  const targetLayer = reference.resolvedPath
+    ? classifyPath(reference.resolvedPath, config)
+    : undefined;
+  const appImport = reference.resolvedPath
+    ? appImportViolation(sourceLayer, targetLayer)
+    : undefined;
+
+  if (appImport) {
+    return {
+      severity: "error",
+      code: "CK_IMPORT_DIRECTION",
+      file,
+      importPath: reference.importPath,
+      message: appImportMessage(sourceLayer, reference.importPath, appImport),
+    };
+  }
+
+  if (
+    reference.packageName &&
+    packageImportViolation(sourceLayer, reference.packageName)
+  ) {
+    return {
+      severity: "error",
+      code: "CK_IMPORT_DIRECTION",
+      file,
+      importPath: reference.importPath,
+      message: packageImportMessage(sourceLayer, reference.packageName),
+    };
+  }
+
+  return undefined;
+}
+
+function appImportViolation(
+  sourceLayer: SourceLayer,
+  targetLayer: SourceLayer | undefined,
+): SourceLayer | undefined {
+  if (!targetLayer) return undefined;
+
+  if (
+    sourceLayer === "domain" &&
+    [
+      "app",
+      "app-context",
+      "client",
+      "component",
+      "contract",
+      "feature-port",
+      "infra",
+      "lib",
+      "policy",
+      "port",
+      "route",
+      "server",
+      "use-case",
+    ].includes(targetLayer)
+  ) {
+    return targetLayer;
+  }
+
+  if (
+    sourceLayer === "use-case" &&
+    ["app", "client", "component", "infra", "route", "server"].includes(
+      targetLayer,
+    )
+  ) {
+    return targetLayer;
+  }
+
+  if (
+    ["feature-port", "policy", "port"].includes(sourceLayer) &&
+    ["app", "client", "component", "infra", "route", "server"].includes(
+      targetLayer,
+    )
+  ) {
+    return targetLayer;
+  }
+
+  if (
+    sourceLayer === "contract" &&
+    ["app", "client", "component", "infra", "route"].includes(targetLayer)
+  ) {
+    return targetLayer;
+  }
+
+  if (
+    sourceLayer === "route" &&
+    ["app", "client", "component", "infra"].includes(targetLayer)
+  ) {
+    return targetLayer;
+  }
+
+  return undefined;
+}
+
+function packageImportViolation(
+  sourceLayer: SourceLayer,
+  packageName: string,
+): boolean {
+  if (sourceLayer === "domain") {
+    return (
+      domainBannedPackages.has(packageName) ||
+      packageName.startsWith("@beignet/provider-")
+    );
+  }
+
+  if (
+    ["contract", "feature-port", "policy", "port", "use-case"].includes(
+      sourceLayer,
+    )
+  ) {
+    return (
+      coreBannedPackages.has(packageName) ||
+      serverRuntimePackages.has(packageName) ||
+      packageName.startsWith("@beignet/provider-")
+    );
+  }
+
+  if (sourceLayer === "route") {
+    return (
+      coreBannedPackages.has(packageName) ||
+      packageName.startsWith("@beignet/provider-")
+    );
+  }
+
+  return false;
+}
+
+const domainBannedPackages = new Set([
+  "@aws-sdk/client-s3",
+  "@aws-sdk/lib-storage",
+  "@aws-sdk/s3-request-presigner",
+  "@beignet/core/application",
+  "@beignet/core/client",
+  "@beignet/core/errors",
+  "@beignet/next",
+  "@beignet/core/ports",
+  "@beignet/react-hook-form",
+  "@beignet/react-query",
+  "@hookform/resolvers",
+  "@libsql/client",
+  "@neondatabase/serverless",
+  "@planetscale/database",
+  "@tanstack/react-query",
+  "@upstash/ratelimit",
+  "@upstash/redis",
+  "better-auth",
+  "drizzle-orm",
+  "inngest",
+  "mongodb",
+  "mongoose",
+  "mysql2",
+  "next",
+  "nodemailer",
+  "pg",
+  "pino",
+  "postgres",
+  "react",
+  "react-dom",
+  "react-hook-form",
+  "redis",
+  "resend",
+]);
+
+const coreBannedPackages = new Set([
+  "@aws-sdk/client-s3",
+  "@aws-sdk/lib-storage",
+  "@aws-sdk/s3-request-presigner",
+  "@beignet/core/client",
+  "@beignet/react-hook-form",
+  "@beignet/react-query",
+  "@hookform/resolvers",
+  "@libsql/client",
+  "@neondatabase/serverless",
+  "@planetscale/database",
+  "@tanstack/react-query",
+  "@upstash/ratelimit",
+  "@upstash/redis",
+  "better-auth",
+  "drizzle-orm",
+  "inngest",
+  "mongodb",
+  "mongoose",
+  "mysql2",
+  "next",
+  "nodemailer",
+  "pg",
+  "pino",
+  "postgres",
+  "react",
+  "react-dom",
+  "react-hook-form",
+  "redis",
+  "resend",
+]);
+
+const serverRuntimePackages = new Set([
+  "@beignet/devtools",
+  "@beignet/next",
+  "@beignet/core/openapi",
+  "@beignet/core/server",
+]);
+
+function appImportMessage(
+  sourceLayer: SourceLayer,
+  importPath: string,
+  targetLayer: SourceLayer,
+): string {
+  return `${layerLabel(sourceLayer)} files must not import ${layerLabel(
+    targetLayer,
+  )} modules (${importPath}). Keep framework, UI, and infrastructure dependencies outside the core application boundary.`;
+}
+
+function packageImportMessage(
+  sourceLayer: SourceLayer,
+  packageName: string,
+): string {
+  return `${layerLabel(
+    sourceLayer,
+  )} files must not import runtime or provider package ${packageName}. Depend on Beignet ports or app-owned ports instead.`;
+}
+
+function classifyPath(
+  filePath: string,
+  config: ResolvedBeignetConfig,
+): SourceLayer {
+  const normalizedPath = stripKnownExtension(normalizePath(filePath));
+  const featuresPath = directoryPath(config.paths.features);
+  const portsDir = directoryPath(path.dirname(config.paths.ports));
+
+  if (isTestPath(normalizedPath)) return "test";
+  if (normalizedPath === stripKnownExtension(config.paths.appContext)) {
+    return "app-context";
+  }
+  if (
+    isUnder(normalizedPath, directoryPath(path.dirname(config.paths.server)))
+  ) {
+    return "server";
+  }
+  if (
+    isUnder(normalizedPath, directoryPath(path.dirname(config.paths.routes)))
+  ) {
+    return "app";
+  }
+  if (
+    isUnder(
+      normalizedPath,
+      directoryPath(path.dirname(config.paths.infrastructurePorts)),
+    )
+  ) {
+    return "infra";
+  }
+  if (isUnder(normalizedPath, portsDir)) return "port";
+  if (isUnder(normalizedPath, "client")) return "client";
+  if (isUnder(normalizedPath, "components")) return "component";
+  if (isUnder(normalizedPath, sharedDomainPath(config))) return "domain";
+  if (isUnder(normalizedPath, "lib")) return "lib";
+
+  const featurePath = featureRelativePath(normalizedPath, featuresPath);
+  if (featurePath) {
+    const layerSegment = featurePath.split("/")[1];
+    if (layerSegment === "domain") return "domain";
+    if (layerSegment === "contracts") return "contract";
+    if (layerSegment === "routes") return "route";
+    if (layerSegment === "ports") return "feature-port";
+    if (layerSegment === "policy") return "policy";
+    if (layerSegment === "use-cases") return "use-case";
+    if (layerSegment === "components") return "component";
+  }
+
+  if (isUnder(normalizedPath, directoryPath(config.paths.contracts))) {
+    return "contract";
+  }
+  if (isUnder(normalizedPath, directoryPath(config.paths.useCases))) {
+    return "use-case";
+  }
+  if (isUnder(normalizedPath, directoryPath(config.paths.policies))) {
+    return "policy";
+  }
+
+  return "unknown";
+}
+
+function isTestPath(filePath: string): boolean {
+  return (
+    filePath.includes("/tests/") ||
+    filePath.endsWith(".test") ||
+    filePath.endsWith(".spec")
+  );
+}
+
+function isUnder(filePath: string, directory: string): boolean {
+  const normalizedDir = directoryPath(directory);
+  if (!normalizedDir || normalizedDir === ".") return false;
+  return filePath === normalizedDir || filePath.startsWith(`${normalizedDir}/`);
+}
+
+function featureRelativePath(
+  filePath: string,
+  featuresPath: string,
+): string | undefined {
+  if (!isUnder(filePath, featuresPath)) return undefined;
+
+  const prefix = `${directoryPath(featuresPath)}/`;
+  return filePath.slice(prefix.length);
+}
+
+function sharedDomainPath(config: ResolvedBeignetConfig): string {
+  const featuresDir = directoryPath(config.paths.features);
+  const featuresParent = directoryPath(path.dirname(featuresDir));
+  if (!featuresParent || featuresParent === ".") return "domain";
+
+  return path.join(featuresParent, "domain");
+}
+
+function layerLabel(layer: SourceLayer): string {
+  return layer.replaceAll("-", " ");
+}
+
+function dedupeDiagnostics(diagnostics: LintDiagnostic[]): LintDiagnostic[] {
+  const seen = new Set<string>();
+  const deduped: LintDiagnostic[] = [];
+
+  for (const diagnostic of diagnostics) {
+    const key = [diagnostic.code, diagnostic.file, diagnostic.importPath].join(
+      ":",
+    );
+    if (seen.has(key)) continue;
+    seen.add(key);
+    deduped.push(diagnostic);
+  }
+
+  return deduped;
+}