@slip-stream-kit/eslint-plugin 0.10.0 → 0.11.0

package/dist/index.js

@@ -1001,6 +1001,317 @@ var maxJsxReturnSize = {
   }
 };
 
+// src/utils/package-root.ts
+import fs from "node:fs";
+import path from "node:path";
+var CONFIG_FILENAME = "infra-kit.config.ts";
+var PACKAGE_MARKERS = [CONFIG_FILENAME, "package.json"];
+var REPO_MARKERS = ["pnpm-workspace.yaml"];
+var hasAnyMarker = (dir, markers) => {
+  return markers.some((marker) => {
+    return fs.existsSync(path.posix.join(dir, marker));
+  });
+};
+var rootCache = /* @__PURE__ */ new Map();
+var findUp = (startDir, markers) => {
+  let current = startDir;
+  while (!hasAnyMarker(current, markers)) {
+    const parent = path.posix.dirname(current);
+    if (parent === current) {
+      return null;
+    }
+    current = parent;
+  }
+  return current;
+};
+var findPackageRoot = (filename) => {
+  if (!path.posix.isAbsolute(filename)) {
+    return null;
+  }
+  const dir = path.posix.dirname(filename);
+  const cached = rootCache.get(dir);
+  if (cached !== void 0) {
+    return cached;
+  }
+  const root = findUp(dir, PACKAGE_MARKERS);
+  rootCache.set(dir, root);
+  return root;
+};
+var dirsUnderSrc = (packageRoot, filename) => {
+  const srcPrefix = `${packageRoot}/src/`;
+  if (!filename.startsWith(srcPrefix)) {
+    return null;
+  }
+  return filename.slice(srcPrefix.length).split("/").slice(0, -1);
+};
+var findRepoRoot = (packageRoot) => {
+  return findUp(packageRoot, REPO_MARKERS);
+};
+
+// ../config/dist/package-type.js
+import path2 from "node:path";
+var PACKAGE_TYPES = ["frontend", "backend", "lib", "e2e", "mobile"];
+var APP_DIRECTORY_TYPES = {
+  ui: "frontend",
+  api: "backend",
+  tests: "e2e"
+};
+var MOBILE_BASENAME = "mobile-app";
+var DEPENDENCY_SIGNALS = [
+  { type: "e2e", packages: ["@playwright/test"] },
+  { type: "mobile", packages: ["@capacitor/core", "@capacitor/cli"] },
+  // `aws-lambda` / `@types/aws-lambda` are deliberately NOT signals: every consumer backend already
+  // lives at `apps/<app>/api` (row 2), while the only packages those two deps would catch are
+  // libraries (`packages/lib-core` in both consumers, the infra-kit CLI itself) — a lambda types
+  // dependency alone never means backend, exactly as `react` alone never means frontend.
+  { type: "backend", packages: ["serverless"] }
+];
+var fromDirectory = (packageDir, repoRoot) => {
+  const segments = path2.relative(repoRoot, packageDir).split(path2.sep).filter((segment) => {
+    return segment !== "" && segment !== ".";
+  });
+  const [first, , third] = segments;
+  if (segments.length === 3 && first === "apps" && third !== void 0) {
+    const appType = APP_DIRECTORY_TYPES[third];
+    if (appType) return appType;
+  }
+  return segments.at(-1) === MOBILE_BASENAME ? "mobile" : null;
+};
+var fromDependencies = (pkgJson) => {
+  const deps = /* @__PURE__ */ new Set([
+    ...Object.keys(pkgJson.dependencies ?? {}),
+    ...Object.keys(pkgJson.devDependencies ?? {}),
+    ...Object.keys(pkgJson.peerDependencies ?? {})
+  ]);
+  for (const signal of DEPENDENCY_SIGNALS) {
+    if (signal.packages.some((name) => {
+      return deps.has(name);
+    }))
+      return signal.type;
+  }
+  const isViteReactApp = deps.has("vite") && deps.has("react") && Boolean(pkgJson.scripts?.dev);
+  return isViteReactApp ? "frontend" : null;
+};
+var detectPackageType = ({
+  packageDir,
+  repoRoot,
+  pkgJson,
+  declaredType
+}) => {
+  return declaredType ?? fromDirectory(packageDir, repoRoot) ?? fromDependencies(pkgJson) ?? "lib";
+};
+
+// src/utils/package-type-reader.ts
+import fs2 from "node:fs";
+import path3 from "node:path";
+var BLOCK_COMMENT = /\/\*[\s\S]*?\*\//g;
+var FULL_LINE_COMMENT = /^[ \t]*\/\/.*$/gm;
+var DECLARED_TYPE = new RegExp(`(?:^|[\\s{,])type:\\s*['"](${PACKAGE_TYPES.join("|")})['"]`, "m");
+var readDeclaredType = (text) => {
+  const stripped = text.replace(BLOCK_COMMENT, "").replace(FULL_LINE_COMMENT, "");
+  const literal = DECLARED_TYPE.exec(stripped)?.[1];
+  return PACKAGE_TYPES.find((candidate) => {
+    return candidate === literal;
+  });
+};
+var typeCache = /* @__PURE__ */ new Map();
+var configMtimeMs = (configPath) => {
+  try {
+    return fs2.statSync(configPath).mtimeMs;
+  } catch {
+    return -1;
+  }
+};
+var readManifest = (manifestPath) => {
+  try {
+    return JSON.parse(fs2.readFileSync(manifestPath, "utf8"));
+  } catch {
+    return {};
+  }
+};
+var resolvePackageType = (packageRoot) => {
+  const configPath = path3.posix.join(packageRoot, CONFIG_FILENAME);
+  const mtimeMs = configMtimeMs(configPath);
+  const hit = typeCache.get(packageRoot);
+  if (hit !== void 0 && hit.mtimeMs === mtimeMs) {
+    return hit.type;
+  }
+  const declaredType = mtimeMs >= 0 ? readDeclaredType(fs2.readFileSync(configPath, "utf8")) : void 0;
+  const type = detectPackageType({
+    packageDir: packageRoot,
+    repoRoot: findRepoRoot(packageRoot) ?? packageRoot,
+    pkgJson: readManifest(path3.posix.join(packageRoot, "package.json")),
+    declaredType
+  });
+  typeCache.set(packageRoot, { mtimeMs, type });
+  return type;
+};
+
+// src/rules/package-structure/package-structure.ts
+var DEFAULT_ENTRIES = {
+  frontend: {
+    layers: ["app", "features", "lib", "components", "pages", "routes"],
+    segments: {
+      "features/*": ["containers", "components", "services", "__stories__", "__tests__"]
+    },
+    skill: "/infra-kit:fe-architect"
+  },
+  backend: {
+    layers: ["controllers", "services", "lib", "config"],
+    segments: {
+      "services/*": ["__tests__"]
+    },
+    // The skill does not exist yet; the user adds `plugins/infra-kit/skills/be-architect/SKILL.md`
+    // and accepted the dangling pointer until then.
+    skill: "/infra-kit:be-architect"
+  },
+  e2e: {
+    layers: ["tests", "pages", "fixtures", "mocks", "data", "config", "lib", "components"],
+    skill: "/infra-kit:e2e-architect"
+  }
+};
+var resolveEntry = (type, options) => {
+  return options[type] ?? DEFAULT_ENTRIES[type];
+};
+var UNIT_KEY_SUFFIX = "/*";
+var assertSegmentKeysNameLayers = (type, entry) => {
+  for (const key of Object.keys(entry.segments ?? {})) {
+    const layer = key.endsWith(UNIT_KEY_SUFFIX) ? key.slice(0, -UNIT_KEY_SUFFIX.length) : key;
+    if (!entry.layers.includes(layer)) {
+      throw new Error(
+        `@wl/package-structure: \`${type}.segments\` key "${key}" names a layer that is not in \`${type}.layers\` (${entry.layers.join(", ")}).`
+      );
+    }
+  }
+};
+var LAYER_ENTRY_SCHEMA = {
+  type: "object",
+  properties: {
+    layers: {
+      type: "array",
+      items: { type: "string", minLength: 1 },
+      uniqueItems: true,
+      description: "First-level directories allowed under `src/`."
+    },
+    segments: {
+      type: "object",
+      propertyNames: { pattern: "^[^/]+(/\\*)?$" },
+      additionalProperties: {
+        type: "array",
+        items: { type: "string", minLength: 1 },
+        uniqueItems: true
+      },
+      description: "Allowed directories one level down, keyed by `<layer>` (directly inside it) or `<layer>/*` (inside each of its folders)."
+    },
+    skill: {
+      type: "string",
+      description: 'Skill or doc that owns this layout, appended to the message; `""` drops the sentence.'
+    }
+  },
+  required: ["layers"],
+  additionalProperties: false
+};
+var findSegmentViolation = (dirs, entry) => {
+  const [layer, second, third] = dirs;
+  const segments = entry.segments ?? {};
+  const perUnit = segments[`${layer}${UNIT_KEY_SUFFIX}`];
+  if (perUnit !== void 0) {
+    return second !== void 0 && third !== void 0 && !perUnit.includes(third) ? { messageId: "unknownSegment", name: third, scope: `${layer}/${second}`, allowed: perUnit } : null;
+  }
+  const direct = segments[layer];
+  if (direct !== void 0 && second !== void 0 && !direct.includes(second)) {
+    return { messageId: "unknownSegment", name: second, scope: layer, allowed: direct };
+  }
+  return null;
+};
+var findViolation = (dirs, entry) => {
+  const layer = dirs[0];
+  if (!entry.layers.includes(layer)) {
+    return { messageId: "unknownLayer", name: layer, scope: "src", allowed: entry.layers };
+  }
+  return findSegmentViolation(dirs, entry);
+};
+var inspect = (filename, options) => {
+  const packageRoot = findPackageRoot(filename);
+  if (packageRoot === null) {
+    return null;
+  }
+  const dirs = dirsUnderSrc(packageRoot, filename);
+  if (dirs === null || dirs.length === 0) {
+    return null;
+  }
+  const type = resolvePackageType(packageRoot);
+  const entry = resolveEntry(type, options);
+  if (entry === void 0) {
+    return null;
+  }
+  assertSegmentKeysNameLayers(type, entry);
+  const violation = findViolation(dirs, entry);
+  return violation === null ? null : { violation, type, entry };
+};
+var packageStructure = {
+  meta: {
+    type: "problem",
+    docs: {
+      description: "Allow only the `src/` layers, and the segments inside them, that belong to the package type.",
+      recommended: true,
+      url: "https://github.com/ArthurSaenz/infra-kit/tree/main/apps/infra-kit/eslint-plugin#package-structure"
+    },
+    schema: [
+      {
+        type: "object",
+        properties: {
+          frontend: LAYER_ENTRY_SCHEMA,
+          backend: LAYER_ENTRY_SCHEMA,
+          lib: LAYER_ENTRY_SCHEMA,
+          e2e: LAYER_ENTRY_SCHEMA,
+          mobile: LAYER_ENTRY_SCHEMA,
+          ignore: {
+            type: "array",
+            items: { type: "string" },
+            description: "Optional globs; the rule is skipped for matching files."
+          }
+        },
+        additionalProperties: false
+      }
+    ],
+    messages: {
+      unknownLayer: "`{{name}}` is not an allowed `src/` layer for package type `{{type}}` (allowed: {{allowed}}).{{seeSkill}}",
+      unknownSegment: "`{{name}}` is not an allowed segment of `{{scope}}` for package type `{{type}}` (allowed: {{allowed}}).{{seeSkill}}"
+    }
+  },
+  create(context) {
+    const options = context.options[0] ?? {};
+    const ignore = options.ignore ?? [];
+    if (ignore.length > 0 && matchesAnyGlob(context.filename, ignore)) {
+      return {};
+    }
+    const found = inspect(context.filename, options);
+    if (found === null) {
+      return {};
+    }
+    const { violation, type, entry } = found;
+    return {
+      // Reported on Program so the IDE marks the file from line 1: every file under the offending
+      // directory carries the same message, which is how a "red folder" surfaces in the explorer.
+      Program(program) {
+        context.report({
+          node: program,
+          messageId: violation.messageId,
+          data: {
+            name: violation.name,
+            scope: violation.scope,
+            type,
+            allowed: violation.allowed.join(", "),
+            // Message templates have no conditionals, so the optional sentence is assembled here.
+            seeSkill: entry.skill ? ` See ${entry.skill} for the ${type} layout.` : ""
+          }
+        });
+      }
+    };
+  }
+};
+
 // src/rules/props-destructuring-blank-line/props-destructuring-blank-line.ts
 var isPropsDestructuring = (statement) => {
   if (statement.type !== "VariableDeclaration") {
@@ -1315,10 +1626,10 @@ var propsTypeReference = {
 
 // src/rules/require-component-stories/require-component-stories.ts
 import { existsSync } from "node:fs";
-import path2 from "node:path";
+import path5 from "node:path";
 
 // src/utils/story-path.ts
-import path from "node:path";
+import path4 from "node:path";
 var DEFAULT_STORY_PATH_OPTIONS = {
   storiesDir: "__stories__",
   storySuffix: ".stories",
@@ -1337,10 +1648,10 @@ var parse = (filePath) => {
   const normalized = toPosix(filePath);
   const segments = normalized.split("/");
   const basename = segments[segments.length - 1] ?? "";
-  const ext = path.posix.extname(basename);
+  const ext = path4.posix.extname(basename);
   const base = ext ? basename.slice(0, -ext.length) : basename;
   return {
-    dir: path.posix.dirname(normalized),
+    dir: path4.posix.dirname(normalized),
     base,
     ext,
     parent: segments[segments.length - 2] ?? "",
@@ -1382,10 +1693,10 @@ var deriveExpectedStoryPaths = (filePath, opts) => {
     return [];
   }
   const parsed = parse(filePath);
-  const storyBaseDir = classification.mode === "feature-root" ? path.posix.dirname(parsed.dir) : parsed.dir;
-  const storyDir = path.posix.join(storyBaseDir, options.storiesDir);
+  const storyBaseDir = classification.mode === "feature-root" ? path4.posix.dirname(parsed.dir) : parsed.dir;
+  const storyDir = path4.posix.join(storyBaseDir, options.storiesDir);
   return options.storyExtensions.map((extension) => {
-    return path.posix.join(storyDir, `${parsed.base}${options.storySuffix}${extension}`);
+    return path4.posix.join(storyDir, `${parsed.base}${options.storySuffix}${extension}`);
   });
 };
 
@@ -1505,7 +1816,7 @@ var requireComponentStories = {
           node: program,
           messageId: "missingStory",
           data: {
-            component: path2.posix.basename(context.filename.split("\\").join("/")),
+            component: path5.posix.basename(context.filename.split("\\").join("/")),
             expected: candidates[0] ?? ""
           }
         });
@@ -1803,7 +2114,8 @@ var rules = {
   "max-jsdoc-lines": maxJsdocLines,
   "max-jsdoc-summary-lines": maxJsdocSummaryLines,
   "require-component-stories": requireComponentStories,
-  "require-jsdoc-example": requireJsdocExample
+  "require-jsdoc-example": requireJsdocExample,
+  "package-structure": packageStructure
 };
 
 // src/index.ts
@@ -1811,7 +2123,7 @@ var PLUGIN_NAME = "@wl";
 var plugin = {
   meta: {
     name: "@wl/eslint-plugin",
-    version: "0.10.0"
+    version: "0.11.0"
   },
   rules,
   configs: {}
@@ -1887,6 +2199,19 @@ plugin.configs.recommended = [
     rules: {
       [`${PLUGIN_NAME}/require-jsdoc-example`]: "warn"
     }
+  },
+  // `package-structure` judges a file by its directory, not its contents, so it must reach every
+  // source extension — the `**/*.tsx` block above would never see a `.ts` under `src/core/`. Its
+  // own block (like `require-jsdoc-example`) with `plugins` re-declared keeps it self-contained.
+  // `error` from day one: the per-type entries are overridable per package via `config({ rules })`.
+  {
+    files: ["**/*.{ts,tsx,js,jsx}"],
+    plugins: {
+      [PLUGIN_NAME]: plugin
+    },
+    rules: {
+      [`${PLUGIN_NAME}/package-structure`]: "error"
+    }
   }
 ];
 var meta = plugin.meta;