feat(folder-structure-cruiser): allow imports from direct children

packages/folder-structure-cruiser/README.md

@@ -81,7 +81,14 @@ npx depcruise --ts-config ./tsconfig.base.json --webpack-config ./webpack.config
 
 ```json
 {
-  "extends": ["@leancodepl/folder-structure-cruiser/.dependency-cruiser.json"]
+  "extends": ["@leancodepl/folder-structure-cruiser/.dependency-cruiser.json"],
+  "options": {
+    "folderStructureCruiser": {
+      "crossFeatureImports": {
+        "allowImportsFromDirectChildrenOf": ["src/features"]
+      }
+    }
+  }
 }
 ```
 

packages/folder-structure-cruiser/__tests__/cross-feature-imports.spec.ts

@@ -50,6 +50,23 @@ describe("cross-feature-imports validation", () => {
     )
   }, 30000)
 
+  it("should allow imports from direct children of configured folder", async () => {
+    const dirname = import.meta.dirname
+    const testDir = join(dirname, "test-structure")
+    const filePath = join(testDir, "polls/SnapshotPollEditor/index.tsx")
+    const configPath = join(dirname, "test-configs/allow-direct-children.config.json")
+
+    await validateCrossFeatureImports({
+      directories: [filePath],
+      configPath: configPath,
+    })
+
+    expect(consoleErrorSpy).not.toHaveBeenCalledWith(
+      expect.anything(),
+      expect.stringContaining("SnapshotPollEditor/index.tsx → __tests__/test-structure/surveys/SurveyEditor/index.tsx"),
+    )
+  }, 30000)
+
   it("should detect violations in ActivityEditor (nested sibling child import)", async () => {
     const dirname = import.meta.dirname
     const testDir = join(dirname, "test-structure")

packages/folder-structure-cruiser/__tests__/test-configs/allow-direct-children.config.json

@@ -0,0 +1,10 @@
+{
+  "extends": ["../../.dependency-cruiser.json"],
+  "options": {
+    "folderStructureCruiser": {
+      "crossFeatureImports": {
+        "allowImportsFromDirectChildrenOf": ["surveys"]
+      }
+    }
+  }
+}

packages/folder-structure-cruiser/src/bin.ts

@@ -36,7 +36,12 @@ program
     const tsConfigPath = options.tsConfig
     const webpackConfigPath = options.webpackConfig
 
-    await validateCrossFeatureImports({ directories, configPath, tsConfigPath, webpackConfigPath })
+    await validateCrossFeatureImports({
+      directories,
+      configPath,
+      tsConfigPath,
+      webpackConfigPath,
+    })
   })
 
 program.parse()

packages/folder-structure-cruiser/src/commands/validateCrossFeatureImports.ts

@@ -1,6 +1,7 @@
 import { checkCrossFeatureImports } from "../lib/checkCrossFeatureImports.js"
 import { formatMessages } from "../lib/formatMessages.js"
 import { CruiseParams, getCruiseResult } from "../lib/getCruiseResult.js"
+import { getFolderStructureCruiserConfig } from "../lib/getFolderStructureCruiserConfig.js"
 import { logger } from "../lib/logger.js"
 
 /**
@@ -62,9 +63,12 @@ import { logger } from "../lib/logger.js"
  */
 export async function validateCrossFeatureImports(cruiseParams: CruiseParams) {
   try {
+    const folderStructureCruiserConfig = await getFolderStructureCruiserConfig(cruiseParams.configPath)
     const cruiseResult = await getCruiseResult(cruiseParams)
 
-    const { messages: errorMessages, totalCruised } = checkCrossFeatureImports(cruiseResult)
+    const { messages: errorMessages, totalCruised } = checkCrossFeatureImports(cruiseResult, {
+      allowImportsFromDirectChildrenOf: folderStructureCruiserConfig.allowImportsFromDirectChildrenOf,
+    })
 
     if (errorMessages.length === 0) {
       logger.success("✅ No issues found!")

packages/folder-structure-cruiser/src/lib/checkCrossFeatureImports.ts

@@ -3,10 +3,55 @@ import { findCommonPathsPrefixLength } from "./findCommonPathsPrefix.js"
 import { Message } from "./formatMessages.js"
 
 type CheckResult = { messages: Message[]; totalCruised: number }
+type CheckCrossFeatureImportsOptions = {
+  allowImportsFromDirectChildrenOf?: string[]
+}
+
+const indexFilePattern = /^index(?:\..+)?$/
+
+function normalizePath(path: string): string[] {
+  return path.split("/").filter(segment => segment.length > 0 && segment !== ".")
+}
+
+function findSubPathIndex(path: string[], subPath: string[]): number {
+  if (subPath.length === 0 || path.length < subPath.length) {
+    return -1
+  }
+
+  for (let i = 0; i <= path.length - subPath.length; i++) {
+    const isMatch = subPath.every((segment, offset) => path[i + offset] === segment)
+
+    if (isMatch) {
+      return i
+    }
+  }
+
+  return -1
+}
+
+function isDirectChildImportOfDirectory(dependencyPath: string[], directoryPath: string[]): boolean {
+  const directoryPathStartIndex = findSubPathIndex(dependencyPath, directoryPath)
+
+  if (directoryPathStartIndex < 0) {
+    return false
+  }
+
+  const relativePathFromDirectory = dependencyPath.slice(directoryPathStartIndex + directoryPath.length)
+
+  if (relativePathFromDirectory.length === 1) {
+    return true
+  }
+
+  return relativePathFromDirectory.length === 2 && indexFilePattern.test(relativePathFromDirectory[1])
+}
 
-export function checkCrossFeatureImports(result: IReporterOutput): CheckResult {
+export function checkCrossFeatureImports(
+  result: IReporterOutput,
+  options: CheckCrossFeatureImportsOptions = {},
+): CheckResult {
   const output = typeof result.output === "object" ? result.output : undefined
   const modules = output?.modules ?? []
+  const allowedDirectChildrenDirectories = (options.allowImportsFromDirectChildrenOf ?? []).map(normalizePath)
 
   const errorMessages: Message[] = []
 
@@ -22,10 +67,14 @@ export function checkCrossFeatureImports(result: IReporterOutput): CheckResult {
     dependencies.forEach(dependency => {
       const dependencyPath = dependency.resolved.split("/")
       const commonPrefixPathLength = findCommonPathsPrefixLength([modulePath, dependencyPath])
+      const shouldAllowDirectChildrenImport = allowedDirectChildrenDirectories.some(directoryPath =>
+        isDirectChildImportOfDirectory(dependencyPath, directoryPath),
+      )
 
       if (
-        !commonPrefixPathLength ||
-        (commonPrefixPathLength < modulePath.length && dependencyPath.length > commonPrefixPathLength + 2)
+        !shouldAllowDirectChildrenImport &&
+        (!commonPrefixPathLength ||
+          (commonPrefixPathLength < modulePath.length && dependencyPath.length > commonPrefixPathLength + 2))
       ) {
         errorMessages.push({
           source: module.source,

packages/folder-structure-cruiser/src/lib/getFolderStructureCruiserConfig.ts

@@ -0,0 +1,32 @@
+import extractDepcruiseOptions from "dependency-cruiser/config-utl/extract-depcruise-options"
+
+type CruiseOptionsWithFolderStructureCruiser = {
+  folderStructureCruiser?: {
+    crossFeatureImports?: {
+      allowImportsFromDirectChildrenOf?: string[]
+    }
+  }
+}
+
+export type FolderStructureCruiserConfig = {
+  allowImportsFromDirectChildrenOf: string[]
+}
+
+function parseStringArray(value: unknown): string[] {
+  return Array.isArray(value) && value.every(item => typeof item === "string") ? value : []
+}
+
+export async function getFolderStructureCruiserConfig(configPath: string): Promise<FolderStructureCruiserConfig> {
+  if (!configPath) {
+    return { allowImportsFromDirectChildrenOf: [] }
+  }
+
+  const depcruiseOptions = (await extractDepcruiseOptions(configPath)) as CruiseOptionsWithFolderStructureCruiser
+  const allowImportsFromDirectChildrenOf = parseStringArray(
+    depcruiseOptions.folderStructureCruiser?.crossFeatureImports?.allowImportsFromDirectChildrenOf,
+  )
+
+  return {
+    allowImportsFromDirectChildrenOf,
+  }
+}