@cuzfrog/pi-module-gates 0.10.0 → 0.13.0

package/README.md

@@ -1,6 +1,6 @@
 # pi-module-gates - Constraints liberate, liberties constrain.
 
-pi cli extension that controls the entropy of the codebase by enforcing code module boundaries.
+Expirimental pi cli extension that controls the entropy of the codebase by enforcing code module boundaries.
 It helps combat slop generation and code architecture degradation.
 
 ## Problem
@@ -25,6 +25,7 @@ The extension intercepts agent `write`/`edit` operations and enforces these cont
    - **Readonly gate** — is the target file locked?
      **Fronzen gate** — is there any surface change to the target file?
    - **Export gate** — would the change introduce an export not in the `visible` list?
+   - **Module interface import gate** — external files can only import from the module not internal files, i.e. re-exports from `index.ts` or `mod.rs`. (Only Typescript/JavaScript and Rust are supported)
    - **Import gate** (not implemented yet) — would the change introduce an import violating visibility scope?
 
 - System prompt: [system-prompt.md](src/context/system-prompt.ts)
@@ -108,11 +109,11 @@ A `MODULE.md` semantically gates exposures at the module level it resides.
 
 ## Configuration
 
-Add a `module-gate` entry to `.pi/settings.json`:
+Add a `module-gates` entry to `.pi/settings.json`:
 
 ```json
 {
-  "module-gate": {
+  "module-gates": {
     "moduleDescriptorFileName": "MODULE.md",
     "moduleDescriptorReadonly": true,
     "sourceRoot": "src/"
@@ -122,11 +123,12 @@ Add a `module-gate` entry to `.pi/settings.json`:
 
 | Option | Default | Description |
 |--------|---------|-------------|
-| `moduleDescriptorFileName` | `"MODULE.md"` | File name used for module descriptors (case-insensitive) |
+| `moduleDescriptorFileName` | `MODULE.md` | File name used for module descriptors (case-insensitive) |
 | `moduleDescriptorReadonly` | `true` | When `true`, descriptor files are readonly.|
 | `sourceRoot` | `"src/"` | Directory to scan for descriptor files and enforce gates. Set to `""` to scan from project root. |
+| `disableModuleInterfaceImportGate` | `false` | By default, external files can only import from the module not internal files, i.e. re-exports from `index.ts` or `mod.rs` |
 
-When no settings file exists or no `module-gate` key is present, defaults apply.
+When no settings file exists or no `module-gates` key is present, defaults apply.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cuzfrog/pi-module-gates",
-  "version": "0.10.0",
+  "version": "0.13.0",
   "description": "pi extension that controls the entropy of the codebase by enforcing code module boundaries.",
   "keywords": [
     "pi-package"
@@ -29,12 +29,12 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/cuzfrog/pi-module-gate.git"
+    "url": "git+https://github.com/cuzfrog/pi-module-gates.git"
   },
   "bugs": {
-    "url": "https://github.com/cuzfrog/pi-module-gate/issues"
+    "url": "https://github.com/cuzfrog/pi-module-gates/issues"
   },
-  "homepage": "https://github.com/cuzfrog/pi-module-gate#readme",
+  "homepage": "https://github.com/cuzfrog/pi-module-gates#readme",
   "license": "MIT",
   "author": "Cause Chung (cuzfrog@gmail.com)",
   "files": [

package/skills/module-freeze-all/scripts/freeze-all.mjs

@@ -17,7 +17,7 @@ function main() {
       root: { type: "string", default: "src" },
       "dry-run": { type: "boolean", default: false },
       create: { type: "boolean", default: false },
-      "descriptor-name": { type: "string", default: "module.md" },
+      "descriptor-name": { type: "string", default: "MODULE.md" },
     },
   });
 

package/src/config.ts

@@ -5,12 +5,14 @@ export type ModuleGateConfig = {
   moduleDescriptorFileName: string;
   moduleDescriptorReadonly: "file" | "frontmatter" | "off";
   sourceRoot: string;
+  disableModuleInterfaceImportGate: boolean;
 };
 
 const DEFAULTS: ModuleGateConfig = {
   moduleDescriptorFileName: "module.md",
   moduleDescriptorReadonly: "file",
   sourceRoot: "src/",
+  disableModuleInterfaceImportGate: false,
 };
 
 export function loadConfig(cwd: string): ModuleGateConfig {
@@ -19,8 +21,8 @@ export function loadConfig(cwd: string): ModuleGateConfig {
   try {
     const raw = fs.readFileSync(settingsPath, "utf-8");
     const settings = JSON.parse(raw);
-    if (settings["module-gate"] && typeof settings["module-gate"] === "object") {
-      userConfig = settings["module-gate"];
+    if (settings["module-gates"] && typeof settings["module-gates"] === "object") {
+      userConfig = settings["module-gates"];
     }
   } catch {
     // file doesn't exist or invalid — use defaults

package/src/context/MODULE.md

@@ -1,5 +1,6 @@
 ---
 frozen:
   - system-prompt.ts
+  - index.ts
 ---
 

package/src/context/index.ts

@@ -0,0 +1 @@
+export { buildSystemPromptHint } from "./system-prompt.ts";

package/src/gates/MODULE.md

@@ -3,5 +3,6 @@ frozen:
   - export-gate.ts
   - frozen-gate.ts
   - readonly-gate.ts
+  - index.ts
 ---
 

package/src/gates/checkers/index.ts

@@ -4,3 +4,5 @@ import "./java.ts";
 import "./go.ts";
 import "./kotlin.ts";
 import "./scala.ts";
+
+export { registerChecker, getChecker, ExportChecker } from "./registry.ts";

package/src/gates/checkers/typescript.ts

@@ -13,7 +13,29 @@ const tsChecker: ExportChecker = {
 registerChecker(tsChecker);
 
 function extractExports(src: string): Signature[] {
-  return [...src.matchAll(
-    /^export\s+(?:default\s+)?(?:\w+\s+)*(?:function(?:\s*\*)?|class|const|let|var|type|interface|enum)\s+(\w+)/gm,
-  )].map((m) => ({ name: m[1] }));
+  const results: Signature[] = [
+    ...src.matchAll(
+      /^export\s+(?:default\s+)?(?:\w+\s+)*(?:function(?:\s*\*)?|class|const|let|var|type|interface|enum)\s+(\w+)/gm,
+    ),
+  ].map((m) => ({ name: m[1] }));
+
+  for (const m of src.matchAll(/^export\s*\{\s*([^}]+)\s*\}\s*from/gm)) {
+    const inner = m[1];
+    for (const entry of inner.split(",")) {
+      const trimmed = entry.trim();
+      if (!trimmed) continue;
+      const asMatch = trimmed.match(/^(\w+)\s+as\s+(\w+)$/);
+      if (asMatch) {
+        results.push({ name: asMatch[2] });
+      } else {
+        results.push({ name: trimmed });
+      }
+    }
+  }
+
+  for (const m of src.matchAll(/^export\s*\*\s*as\s+(\w+)\s+from/gm)) {
+    results.push({ name: m[1] });
+  }
+
+  return results;
 }

package/src/gates/index.ts

@@ -0,0 +1,4 @@
+export { checkReadonly } from "./readonly-gate.ts";
+export { checkFrozen } from "./frozen-gate.ts";
+export { checkExports } from "./export-gate.ts";
+export { checkModuleInterfaceImports } from "./module-interface-import-gate.ts";

package/src/gates/module-interface-import-gate.ts

@@ -0,0 +1,148 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { ModuleIndex } from "../types.ts";
+import { findOwningModule } from "../utils.ts";
+
+export type ImportCheckResult =
+  | { blocked: true; reason: string }
+  | { blocked: false };
+
+export function checkModuleInterfaceImports(
+  filePath: string,
+  afterContent: string,
+  index: ModuleIndex,
+  cwd: string,
+  disabled: boolean,
+  sourceRoot: string,
+): ImportCheckResult {
+  if (disabled) return { blocked: false };
+
+  const absFile = path.resolve(cwd, filePath);
+  const fileDir = path.dirname(absFile);
+  const srcRoot = path.resolve(cwd, sourceRoot);
+  const violations: string[] = [];
+
+  for (const importPath of extractJsImportPaths(afterContent)) {
+    const resolved = resolveRelativeImport(importPath, fileDir);
+    if (!resolved) continue;
+    if (isInNodeModules(resolved, cwd)) continue;
+
+    const violation = checkViolation(resolved, fileDir, cwd, index);
+    if (violation) violations.push(violation);
+  }
+
+  for (const modulePath of extractRustUsePaths(afterContent)) {
+    const resolved = resolveRustCratePath(modulePath, srcRoot);
+    if (!resolved) continue;
+    if (isInNodeModules(resolved, cwd)) continue;
+
+    const violation = checkViolation(resolved, fileDir, cwd, index);
+    if (violation) violations.push(violation);
+  }
+
+  if (violations.length === 0) return { blocked: false };
+
+  return {
+    blocked: true,
+    reason: `Module interface import violations:\n${violations.map((v) => `  - ${v}`).join("\n")}`,
+  };
+}
+
+function checkViolation(
+  resolved: string,
+  fileDir: string,
+  cwd: string,
+  index: ModuleIndex,
+): string | undefined {
+  const targetModule = findOwningModule(resolved, index);
+  if (!targetModule) return undefined;
+
+  const targetDir = path.dirname(resolved);
+  if (targetDir === fileDir) return undefined;
+
+  if (isInterfaceFile(resolved)) return undefined;
+
+  const sourceModule = findOwningModule(path.join(fileDir, "dummy.ts"), index);
+  if (sourceModule && sourceModule === targetModule) return undefined;
+
+  const relTarget = path.relative(cwd, resolved);
+  const relModule = path.relative(cwd, targetModule);
+  return `Import from "${relTarget}" bypasses module interface of ${relModule}/`;
+}
+
+function extractJsImportPaths(content: string): string[] {
+  const results: string[] = [];
+
+  for (const m of content.matchAll(/^\s*import\s+[\s\S]*?\s+from\s+["']([^"']+)["']/gm)) {
+    results.push(m[1]);
+  }
+
+  for (const m of content.matchAll(/^\s*(?:const|let|var)\s+[\s\S]*?=\s*require\s*\(\s*["']([^"']+)["']\s*\)/gm)) {
+    results.push(m[1]);
+  }
+
+  return results;
+}
+
+function extractRustUsePaths(content: string): string[] {
+  const results: string[] = [];
+
+  for (const m of content.matchAll(/^\s*(?:pub\s+)?use\s+crate::(\w+(?:::\w+)*)::/gm)) {
+    const segments = m[1].split("::");
+    if (segments.length >= 2) {
+      results.push(segments.join("/"));
+    }
+  }
+
+  return results;
+}
+
+function resolveRelativeImport(importPath: string, fileDir: string): string | undefined {
+  if (!importPath.startsWith(".")) return undefined;
+
+  const resolved = path.resolve(fileDir, importPath);
+  const ext = path.extname(resolved);
+
+  if (ext) {
+    return fs.existsSync(resolved) ? resolved : undefined;
+  }
+
+  for (const tryExt of [".ts", ".tsx", ".js", ".jsx", ".rs"]) {
+    const candidate = resolved + tryExt;
+    if (fs.existsSync(candidate)) return candidate;
+  }
+
+  return undefined;
+}
+
+function resolveRustCratePath(modulePath: string, srcRoot: string): string | undefined {
+  const segments = modulePath.split("/");
+  const base = path.resolve(srcRoot, ...segments);
+
+  const asFile = base + ".rs";
+  if (fs.existsSync(asFile)) return asFile;
+
+  const asMod = path.join(base, "mod.rs");
+  if (fs.existsSync(asMod)) return asMod;
+
+  return undefined;
+}
+
+function isInNodeModules(resolvedPath: string, _cwd: string): boolean {
+  return resolvedPath.split(path.sep).includes("node_modules");
+}
+
+function isInterfaceFile(absPath: string): boolean {
+  const basename = path.basename(absPath);
+  const ext = path.extname(absPath);
+
+  if ([".ts", ".tsx", ".js", ".jsx"].includes(ext)) {
+    return ["index.ts", "index.tsx", "index.js", "index.jsx"].includes(basename);
+  }
+
+  if (ext === ".rs") {
+    return basename === "mod.rs";
+  }
+
+  return false;
+}

package/src/graph/MODULE.md

@@ -3,6 +3,7 @@ frozen:
   - frontmatter-parser.ts
   - module-index-builder.ts
   - validation.ts
+  - index.ts
 ---
 
 

package/src/graph/index.ts

@@ -0,0 +1,4 @@
+export { buildModuleIndex } from "./module-index-builder.ts";
+export { validateVisibleEntries } from "./validation.ts";
+export { parseVisibleEntry } from "./frontmatter-parser.ts";
+export type { VisibleEntryRaw, ModuleFrontmatter } from "./frontmatter-parser.ts";

package/src/graph/module-index-builder.ts

@@ -8,7 +8,7 @@ import type { ModuleGateConfig } from "../config.ts";
 type ModuleDescriptorReadonly = ModuleGateConfig["moduleDescriptorReadonly"];
 import type { Dirent } from "node:fs";
 import { validateVisibleEntries } from "./validation.ts";
-import { parseVisibleEntry, type VisibleEntryRaw, type ModuleFrontmatter } from "./frontmatter-parser.ts";
+import { parseVisibleEntry, type ModuleFrontmatter } from "./frontmatter-parser.ts";
 
 type IndexContext = {
   cwd: string;

package/src/graph/validation.ts

@@ -1,7 +1,7 @@
 import * as path from "node:path";
 import { readdir } from "node:fs/promises";
 import type { ModuleIndex } from "../types.ts";
-import { getChecker } from "../gates/checkers/registry.ts";
+import { getChecker } from "../gates/checkers/index.ts";
 import { readFileSafe } from "../utils.ts";
 import type { Dirent } from "node:fs";
 

package/src/index.ts

@@ -8,12 +8,15 @@ import { isToolCallEventType, parseFrontmatter } from "@earendil-works/pi-coding
 import type { ModuleIndex } from "./types.ts";
 import { loadConfig } from "./config.ts";
 import type { ModuleGateConfig } from "./config.ts";
-import { buildModuleIndex } from "./graph/module-index-builder.ts";
+import { buildModuleIndex } from "./graph/index.ts";
 import { findOwningModule, readFileSafe, applyEdits, isWithinSourceRoot } from "./utils.ts";
-import { checkReadonly } from "./gates/readonly-gate.ts";
-import { checkExports } from "./gates/export-gate.ts";
-import { checkFrozen } from "./gates/frozen-gate.ts";
-import { buildSystemPromptHint } from "./context/system-prompt.ts";
+import {
+  checkReadonly,
+  checkExports,
+  checkFrozen,
+  checkModuleInterfaceImports,
+} from "./gates/index.ts";
+import { buildSystemPromptHint } from "./context/index.ts";
 import "./gates/checkers/index.ts";
 
 export default function (pi: ExtensionAPI): void {
@@ -101,6 +104,11 @@ function handleEdit(
     return { block: true, reason: formatDenial(filePath, exportResult.reason, absPath, index, cwd, config.moduleDescriptorFileName) };
   }
 
+  const importResult = checkModuleInterfaceImports(filePath, after, index, cwd, config.disableModuleInterfaceImportGate, config.sourceRoot);
+  if (importResult.blocked) {
+    return { block: true, reason: formatDenial(filePath, importResult.reason, absPath, index, cwd, config.moduleDescriptorFileName) };
+  }
+
   return undefined;
 }
 

package/src/types.ts

@@ -1,3 +1,4 @@
+
 export type Signature = {
   modifier?: string;
   name: string;