@beignet/cli 0.0.3 → 0.0.5

package/src/lint.ts

@@ -1,5 +1,6 @@
 import { readdir, readFile, stat } from "node:fs/promises";
 import path from "node:path";
+import { createPainter } from "./ansi.js";
 import {
   type BeignetConfig,
   directoryPath,
@@ -8,6 +9,7 @@ import {
   type ResolvedBeignetConfig,
   resolveConfig,
 } from "./config.js";
+import { formatGithubAnnotation } from "./github-annotations.js";
 
 type LintAppOptions = {
   cwd?: string;
@@ -35,10 +37,18 @@ type SourceLayer =
 
 type ImportReference = {
   importPath: string;
+  kind: ImportKind;
+  offset: number;
   resolvedPath?: string;
   packageName?: string;
 };
 
+type ImportKind = "type" | "value";
+
+type ImportGraph = Map<string, ImportReference[]>;
+
+type RuntimeBoundaryRootKind = "client" | "contract";
+
 /**
  * Dependency-direction lint diagnostic.
  */
@@ -48,12 +58,15 @@ export type LintDiagnostic = {
   message: string;
   file: string;
   importPath: string;
+  line?: number;
+  column?: number;
 };
 
 /**
  * Result returned by `beignet lint`.
  */
 export type LintAppResult = {
+  schemaVersion: 1;
   targetDir: string;
   config: ResolvedBeignetConfig;
   diagnostics: LintDiagnostic[];
@@ -73,29 +86,87 @@ export async function lintApp(
     ? resolveConfig(options.config)
     : await loadBeignetConfig(targetDir, files);
   const diagnostics: LintDiagnostic[] = [];
+  const sourceFiles = lintSourceFiles(files);
+  const sourceFileSet = new Set(sourceFiles);
+  const sourceByFile = new Map<string, string>();
+  const importGraph: ImportGraph = new Map();
 
-  for (const file of lintSourceFiles(files)) {
+  for (const file of sourceFiles) {
     const sourceLayer = classifyPath(file, config);
+    const source = await readFile(path.join(targetDir, file), "utf8");
+    sourceByFile.set(file, source);
+    importGraph.set(file, parseImports(source, file, sourceFileSet));
+
     if (sourceLayer === "test" || sourceLayer === "unknown") continue;
 
-    const source = await readFile(path.join(targetDir, file), "utf8");
-    for (const reference of parseImports(source, file)) {
+    const lineStarts = computeLineStarts(source);
+    for (const reference of importGraph.get(file) ?? []) {
       const diagnostic = lintImport(file, sourceLayer, reference, config);
-      if (diagnostic) diagnostics.push(diagnostic);
+      if (diagnostic) {
+        diagnostics.push({
+          ...diagnostic,
+          ...positionFromOffset(lineStarts, reference.offset),
+        });
+      }
     }
   }
 
+  diagnostics.push(
+    ...lintRuntimeBoundary({
+      config,
+      graph: importGraph,
+      sourceByFile,
+    }),
+  );
+
   return {
+    schemaVersion: 1,
     targetDir,
     config,
     diagnostics: dedupeDiagnostics(diagnostics),
   };
 }
 
+function computeLineStarts(source: string): number[] {
+  const lineStarts = [0];
+
+  for (let index = 0; index < source.length; index++) {
+    if (source[index] === "\n") {
+      lineStarts.push(index + 1);
+    }
+  }
+
+  return lineStarts;
+}
+
+function positionFromOffset(
+  lineStarts: number[],
+  offset: number,
+): { line: number; column: number } {
+  let low = 0;
+  let high = lineStarts.length - 1;
+
+  while (low < high) {
+    const middle = Math.ceil((low + high) / 2);
+    if (lineStarts[middle] <= offset) {
+      low = middle;
+    } else {
+      high = middle - 1;
+    }
+  }
+
+  return { line: low + 1, column: offset - lineStarts[low] + 1 };
+}
+
 /**
  * Format dependency-direction lint diagnostics for CLI output.
  */
-export function formatLint(result: LintAppResult): string {
+export function formatLint(
+  result: LintAppResult,
+  options: { color?: boolean } = {},
+): string {
+  const paint = createPainter(options.color);
+
   if (result.diagnostics.length === 0) {
     return `No Beignet lint issues found in ${result.targetDir}.`;
   }
@@ -106,12 +177,39 @@ export function formatLint(result: LintAppResult): string {
     } in ${result.targetDir}:`,
     "",
     ...result.diagnostics.map(
-      (diagnostic) => `ERROR ${diagnostic.code} ${diagnostic.file}
+      (
+        diagnostic,
+      ) => `${paint("ERROR", "red")} ${diagnostic.code} ${lintDiagnosticLocation(diagnostic)}
   ${diagnostic.message}`,
     ),
   ].join("\n");
 }
 
+function lintDiagnosticLocation(diagnostic: LintDiagnostic): string {
+  if (diagnostic.line === undefined || diagnostic.column === undefined) {
+    return diagnostic.file;
+  }
+
+  return `${diagnostic.file}:${diagnostic.line}:${diagnostic.column}`;
+}
+
+/**
+ * Format dependency-direction lint diagnostics as GitHub Actions annotations.
+ */
+export function formatLintGithub(result: LintAppResult): string {
+  return result.diagnostics
+    .map((diagnostic) =>
+      formatGithubAnnotation({
+        severity: "error",
+        file: diagnostic.file,
+        line: diagnostic.line,
+        col: diagnostic.column,
+        message: `${diagnostic.code}: ${diagnostic.message}`,
+      }),
+    )
+    .join("\n");
+}
+
 async function assertDirectory(targetDir: string): Promise<void> {
   try {
     const stats = await stat(targetDir);
@@ -165,17 +263,27 @@ function lintSourceFiles(files: string[]): string[] {
   });
 }
 
-function parseImports(source: string, importerFile: string): ImportReference[] {
+function parseImports(
+  source: string,
+  importerFile: string,
+  files: Set<string>,
+): ImportReference[] {
   const references = parseImportSpecifiers(source);
 
-  return references.map((importPath) => ({
-    importPath,
-    ...resolveImport(importPath, importerFile),
+  return references.map((reference) => ({
+    ...reference,
+    ...resolveImport(reference.importPath, importerFile, files),
   }));
 }
 
-function parseImportSpecifiers(source: string): string[] {
-  const specifiers: string[] = [];
+function parseImportSpecifiers(
+  source: string,
+): Array<{ importPath: string; kind: ImportKind; offset: number }> {
+  const specifiers: Array<{
+    importPath: string;
+    kind: ImportKind;
+    offset: number;
+  }> = [];
   let index = 0;
 
   while (index < source.length) {
@@ -183,14 +291,26 @@ function parseImportSpecifiers(source: string): string[] {
 
     if (isKeywordAt(source, index, "import")) {
       const parsed = parseImportSpecifierAt(source, index + "import".length);
-      if (parsed?.specifier) specifiers.push(parsed.specifier);
+      if (parsed?.specifier) {
+        specifiers.push({
+          importPath: parsed.specifier,
+          kind: parsed.kind ?? "value",
+          offset: index,
+        });
+      }
       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);
+      if (parsed?.specifier) {
+        specifiers.push({
+          importPath: parsed.specifier,
+          kind: parsed.kind ?? "value",
+          offset: index,
+        });
+      }
       index = parsed?.end ?? index + "export".length;
       continue;
     }
@@ -204,7 +324,7 @@ function parseImportSpecifiers(source: string): string[] {
 function parseImportSpecifierAt(
   source: string,
   index: number,
-): { specifier?: string; end: number } | undefined {
+): { specifier?: string; kind?: ImportKind; end: number } | undefined {
   let cursor = skipWhitespaceAndComments(source, index);
   if (source[cursor] === "(") {
     cursor = skipWhitespaceAndComments(source, cursor + 1);
@@ -220,10 +340,18 @@ function parseImportSpecifierAt(
   if (sideEffectImport) {
     return {
       specifier: sideEffectImport.value,
+      kind: "value",
       end: sideEffectImport.end,
     };
   }
 
+  const importClauseStart = cursor;
+  let isImportType = false;
+  if (isKeywordAt(source, cursor, "type")) {
+    isImportType = true;
+    cursor = cursorAfterKeyword("type", cursor);
+  }
+
   while (cursor < source.length) {
     cursor = skipWhitespaceAndComments(source, cursor);
 
@@ -240,6 +368,9 @@ function parseImportSpecifierAt(
       if (!stringLiteral) return { end: fromCursor };
       return {
         specifier: stringLiteral.value,
+        kind: isImportType
+          ? "type"
+          : inferImportClauseKind(source.slice(importClauseStart, cursor)),
         end: stringLiteral.end,
       };
     }
@@ -253,12 +384,20 @@ function parseImportSpecifierAt(
 function parseExportSpecifierAt(
   source: string,
   index: number,
-): { specifier?: string; end: number } | undefined {
+): { specifier?: string; kind?: ImportKind; end: number } | undefined {
   let cursor = index;
+  let isExportType = false;
+  const exportClauseStart = cursor;
 
   while (cursor < source.length) {
     cursor = skipWhitespaceAndComments(source, cursor);
 
+    if (isKeywordAt(source, cursor, "type")) {
+      isExportType = true;
+      cursor = cursorAfterKeyword("type", cursor);
+      continue;
+    }
+
     if (source[cursor] === ";" || source[cursor] === "\n") {
       return { end: cursor + 1 };
     }
@@ -272,6 +411,9 @@ function parseExportSpecifierAt(
       if (!stringLiteral) return { end: fromCursor };
       return {
         specifier: stringLiteral.value,
+        kind: isExportType
+          ? "type"
+          : inferImportClauseKind(source.slice(exportClauseStart, cursor)),
         end: stringLiteral.end,
       };
     }
@@ -282,6 +424,14 @@ function parseExportSpecifierAt(
   return undefined;
 }
 
+function inferImportClauseKind(importClause: string): ImportKind {
+  const trimmed = importClause.trim();
+  if (/^\{\s*type\s+[^,}]+(?:,\s*type\s+[^,}]+)*,?\s*\}$/.test(trimmed)) {
+    return "type";
+  }
+  return "value";
+}
+
 function cursorAfterKeyword(keyword: string, index: number): number {
   return index + keyword.length;
 }
@@ -425,17 +575,24 @@ function isIdentifierChar(char: string | undefined): boolean {
 function resolveImport(
   importPath: string,
   importerFile: string,
+  files: Set<string>,
 ): Pick<ImportReference, "packageName" | "resolvedPath"> {
   if (importPath.startsWith("@/")) {
     return {
-      resolvedPath: stripKnownExtension(importPath.slice(2)),
+      resolvedPath: resolveLocalImportPath(
+        stripKnownExtension(importPath.slice(2)),
+        files,
+      ),
     };
   }
 
   if (importPath.startsWith(".")) {
     return {
-      resolvedPath: stripKnownExtension(
-        normalizePath(path.join(path.dirname(importerFile), importPath)),
+      resolvedPath: resolveLocalImportPath(
+        stripKnownExtension(
+          normalizePath(path.join(path.dirname(importerFile), importPath)),
+        ),
+        files,
       ),
     };
   }
@@ -445,6 +602,33 @@ function resolveImport(
   };
 }
 
+function resolveLocalImportPath(
+  importPath: string,
+  files: Set<string>,
+): string | undefined {
+  const candidates = [
+    importPath,
+    `${importPath}.ts`,
+    `${importPath}.tsx`,
+    `${importPath}.mts`,
+    `${importPath}.cts`,
+    `${importPath}/index.ts`,
+    `${importPath}/index.tsx`,
+    `${importPath}/index.mts`,
+    `${importPath}/index.cts`,
+  ];
+
+  for (const candidate of candidates) {
+    for (const file of files) {
+      if (stripKnownExtension(file) === stripKnownExtension(candidate)) {
+        return file;
+      }
+    }
+  }
+
+  return stripKnownExtension(importPath);
+}
+
 function packageName(importPath: string): string {
   if (!importPath.startsWith("@")) return importPath.split("/")[0];
 
@@ -462,9 +646,24 @@ function lintImport(
   reference: ImportReference,
   config: ResolvedBeignetConfig,
 ): LintDiagnostic | undefined {
+  if (reference.kind === "type") return undefined;
+
   const targetLayer = reference.resolvedPath
     ? classifyPath(reference.resolvedPath, config)
     : undefined;
+  const featureImport = reference.resolvedPath
+    ? featureImportViolation(file, sourceLayer, reference.resolvedPath, config)
+    : undefined;
+  if (featureImport) {
+    return {
+      severity: "error",
+      code: "BEIGNET_IMPORT_DIRECTION",
+      file,
+      importPath: reference.importPath,
+      message: featureImport,
+    };
+  }
+
   const appImport = reference.resolvedPath
     ? appImportViolation(sourceLayer, targetLayer)
     : undefined;
@@ -472,23 +671,24 @@ function lintImport(
   if (appImport) {
     return {
       severity: "error",
-      code: "CK_IMPORT_DIRECTION",
+      code: "BEIGNET_IMPORT_DIRECTION",
       file,
       importPath: reference.importPath,
       message: appImportMessage(sourceLayer, reference.importPath, appImport),
     };
   }
 
-  if (
-    reference.packageName &&
-    packageImportViolation(sourceLayer, reference.packageName)
-  ) {
+  const bannedPackage = reference.packageName
+    ? packageImportViolation(sourceLayer, reference.importPath)
+    : undefined;
+
+  if (bannedPackage) {
     return {
       severity: "error",
-      code: "CK_IMPORT_DIRECTION",
+      code: "BEIGNET_IMPORT_DIRECTION",
       file,
       importPath: reference.importPath,
-      message: packageImportMessage(sourceLayer, reference.packageName),
+      message: packageImportMessage(sourceLayer, bannedPackage),
     };
   }
 
@@ -563,17 +763,24 @@ function appImportViolation(
     return targetLayer;
   }
 
+  if (
+    sourceLayer === "infra" &&
+    ["app", "client", "component", "route", "server"].includes(targetLayer)
+  ) {
+    return targetLayer;
+  }
+
   return undefined;
 }
 
 function packageImportViolation(
   sourceLayer: SourceLayer,
-  packageName: string,
-): boolean {
+  importPath: string,
+): string | undefined {
   if (sourceLayer === "domain") {
     return (
-      domainBannedPackages.has(packageName) ||
-      packageName.startsWith("@beignet/provider-")
+      matchBannedPackage(domainBannedPackages, importPath) ??
+      matchBeignetProviderPackage(importPath)
     );
   }
 
@@ -588,20 +795,245 @@ function packageImportViolation(
     ].includes(sourceLayer)
   ) {
     return (
-      coreBannedPackages.has(packageName) ||
-      serverRuntimePackages.has(packageName) ||
-      packageName.startsWith("@beignet/provider-")
+      matchBannedPackage(coreBannedPackages, importPath) ??
+      matchBannedPackage(serverRuntimePackages, importPath) ??
+      matchBeignetProviderPackage(importPath)
     );
   }
 
   if (sourceLayer === "route") {
     return (
-      coreBannedPackages.has(packageName) ||
-      packageName.startsWith("@beignet/provider-")
+      matchBannedPackage(coreBannedPackages, importPath) ??
+      matchBeignetProviderPackage(importPath)
+    );
+  }
+
+  return undefined;
+}
+
+function matchBannedPackage(
+  bannedPackages: ReadonlySet<string>,
+  importPath: string,
+): string | undefined {
+  let candidate = importPath;
+
+  while (candidate.length > 0) {
+    if (bannedPackages.has(candidate)) return candidate;
+
+    const separator = candidate.lastIndexOf("/");
+    if (separator === -1) return undefined;
+    candidate = candidate.slice(0, separator);
+  }
+
+  return undefined;
+}
+
+function matchBeignetProviderPackage(importPath: string): string | undefined {
+  const name = packageName(importPath);
+  return name.startsWith("@beignet/provider-") ? name : undefined;
+}
+
+function lintRuntimeBoundary({
+  config,
+  graph,
+  sourceByFile,
+}: {
+  config: ResolvedBeignetConfig;
+  graph: ImportGraph;
+  sourceByFile: Map<string, string>;
+}): LintDiagnostic[] {
+  const diagnostics: LintDiagnostic[] = [];
+
+  for (const file of graph.keys()) {
+    const rootKind = runtimeBoundaryRootKind(
+      file,
+      sourceByFile.get(file) ?? "",
+      config,
+    );
+    if (!rootKind) continue;
+
+    diagnostics.push(
+      ...lintRuntimeBoundaryRoot({
+        root: file,
+        rootKind,
+        config,
+        graph,
+      }),
     );
   }
 
-  return false;
+  return diagnostics;
+}
+
+function lintRuntimeBoundaryRoot({
+  root,
+  rootKind,
+  config,
+  graph,
+}: {
+  root: string;
+  rootKind: RuntimeBoundaryRootKind;
+  config: ResolvedBeignetConfig;
+  graph: ImportGraph;
+}): LintDiagnostic[] {
+  const diagnostics: LintDiagnostic[] = [];
+  const visited = new Set<string>();
+  const queue: Array<{ file: string; chain: string[] }> = [
+    { file: root, chain: [root] },
+  ];
+
+  while (queue.length > 0) {
+    const current = queue.shift();
+    if (!current) continue;
+    if (visited.has(current.file)) continue;
+    visited.add(current.file);
+
+    for (const reference of graph.get(current.file) ?? []) {
+      if (
+        reference.kind === "type" &&
+        reference.importPath !== "@beignet/core/server-only"
+      ) {
+        continue;
+      }
+
+      const chain = reference.resolvedPath
+        ? [...current.chain, reference.resolvedPath]
+        : current.chain;
+      const violation = runtimeBoundaryViolation(reference, config);
+
+      if (violation) {
+        diagnostics.push({
+          severity: "error",
+          code: "BEIGNET_RUNTIME_BOUNDARY",
+          file: root,
+          importPath: reference.importPath,
+          message: runtimeBoundaryMessage(rootKind, violation, chain),
+        });
+        continue;
+      }
+
+      if (reference.resolvedPath && graph.has(reference.resolvedPath)) {
+        queue.push({
+          file: reference.resolvedPath,
+          chain,
+        });
+      }
+    }
+  }
+
+  return diagnostics;
+}
+
+function runtimeBoundaryRootKind(
+  file: string,
+  source: string,
+  config: ResolvedBeignetConfig,
+): RuntimeBoundaryRootKind | undefined {
+  const layer = classifyPath(file, config);
+  if (layer === "contract") return "contract";
+  if (layer === "client") return "client";
+  if (hasUseClientDirective(source)) return "client";
+  if (isGeneratedClientAdapter(file)) return "client";
+  return undefined;
+}
+
+function hasUseClientDirective(source: string): boolean {
+  const trimmed = source.trimStart();
+  return (
+    trimmed.startsWith('"use client";') ||
+    trimmed.startsWith('"use client"') ||
+    trimmed.startsWith("'use client';") ||
+    trimmed.startsWith("'use client'")
+  );
+}
+
+function isGeneratedClientAdapter(file: string): boolean {
+  return (
+    file === "client/index.ts" ||
+    file === "client/api-client.ts" ||
+    file === "client/rhf.ts" ||
+    file === "client/rq.ts" ||
+    file === "client/uploads.ts"
+  );
+}
+
+function runtimeBoundaryViolation(
+  reference: ImportReference,
+  config: ResolvedBeignetConfig,
+): string | undefined {
+  if (reference.resolvedPath) {
+    const targetLayer = classifyPath(reference.resolvedPath, config);
+    if (
+      targetLayer === "use-case" ||
+      targetLayer === "route" ||
+      targetLayer === "infra" ||
+      targetLayer === "server"
+    ) {
+      return `${layerLabel(targetLayer)} module ${reference.resolvedPath}`;
+    }
+    if (targetLayer === "app-context") {
+      return `app context module ${reference.resolvedPath}`;
+    }
+  }
+
+  if (reference.importPath === "@beignet/core/server-only") {
+    return "server-only marker @beignet/core/server-only";
+  }
+
+  if (reference.importPath.startsWith("node:")) {
+    return `Node runtime module ${reference.importPath}`;
+  }
+
+  if (
+    serverRuntimePackages.has(reference.importPath) ||
+    reference.importPath.startsWith("@beignet/provider-")
+  ) {
+    return `server runtime package ${reference.importPath}`;
+  }
+
+  return undefined;
+}
+
+function runtimeBoundaryMessage(
+  rootKind: RuntimeBoundaryRootKind,
+  violation: string,
+  chain: string[],
+): string {
+  return `${rootKindLabel(
+    rootKind,
+  )} roots must not value-import server-only code. Reached ${violation} through ${formatImportChain(
+    chain,
+  )}. Move shared DTO and validation schemas to features/<feature>/schemas.ts, keep use cases/routes/infra/server modules behind server entrypoints, or import server-shaped modules with import type only.`;
+}
+
+function rootKindLabel(rootKind: RuntimeBoundaryRootKind): string {
+  return rootKind === "contract" ? "contract" : "client";
+}
+
+function formatImportChain(chain: string[]): string {
+  return chain.join(" -> ");
+}
+
+function featureImportViolation(
+  file: string,
+  sourceLayer: SourceLayer,
+  resolvedPath: string,
+  config: ResolvedBeignetConfig,
+): string | undefined {
+  if (sourceLayer !== "domain") return undefined;
+
+  const sourceFeature = featureLayerInfo(file, config);
+  const targetFeature = featureLayerInfo(resolvedPath, config);
+  if (!sourceFeature || !targetFeature) return undefined;
+  if (sourceFeature.layer !== "domain" || targetFeature.layer !== "domain") {
+    return undefined;
+  }
+  if (sourceFeature.feature === targetFeature.feature) return undefined;
+  if (targetFeature.feature === "shared") return undefined;
+
+  return `feature-specific domain files must not import another feature's domain (${stripKnownExtension(
+    resolvedPath,
+  )}). Move shared concepts to features/shared/domain.`;
 }
 
 const domainBannedPackages = new Set([
@@ -744,9 +1176,14 @@ function classifyPath(
     if (layerSegment === "policy") return "policy";
     if (layerSegment === "use-cases") return "use-case";
     if (
-      ["jobs", "listeners", "notifications", "schedules", "uploads"].includes(
-        layerSegment,
-      )
+      [
+        "jobs",
+        "listeners",
+        "notifications",
+        "schedules",
+        "tasks",
+        "uploads",
+      ].includes(layerSegment)
     ) {
       return "workflow";
     }
@@ -790,6 +1227,23 @@ function featureRelativePath(
   return filePath.slice(prefix.length);
 }
 
+function featureLayerInfo(
+  filePath: string,
+  config: ResolvedBeignetConfig,
+): { feature: string; layer: string | undefined } | undefined {
+  const normalizedPath = stripKnownExtension(normalizePath(filePath));
+  const relativePath = featureRelativePath(
+    normalizedPath,
+    directoryPath(config.paths.features),
+  );
+  if (!relativePath) return undefined;
+
+  const [feature, layer] = relativePath.split("/");
+  if (!feature) return undefined;
+
+  return { feature, layer };
+}
+
 function sharedDomainPath(config: ResolvedBeignetConfig): string {
   const featuresDir = directoryPath(config.paths.features);
   const featuresParent = directoryPath(path.dirname(featuresDir));