@cuzfrog/pi-module-gates 0.12.0 → 0.13.1

package/README.md

@@ -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`. A child module may import from a parent module's internal files (not recommended but allowed). (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)
@@ -125,6 +126,7 @@ Add a `module-gates` entry to `.pi/settings.json`:
 | `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` | When `true`, imports will not be forced to be from module interface. |
 
 When no settings file exists or no `module-gates` key is present, defaults apply.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cuzfrog/pi-module-gates",
-  "version": "0.12.0",
+  "version": "0.13.1",
   "description": "pi extension that controls the entropy of the codebase by enforcing code module boundaries.",
   "keywords": [
     "pi-package"

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 {

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

@@ -19,7 +19,9 @@ function extractExports(src: string): Signature[] {
     ),
   ].map((m) => ({ name: m[1] }));
 
-  for (const m of src.matchAll(/^export\s*\{\s*([^}]+)\s*\}\s*from/gm)) {
+  for (const m of src.matchAll(
+    /^export\s*(?:type\s+)?\{\s*([^}]+)\s*\}\s*from/gm,
+  )) {
     const inner = m[1];
     for (const entry of inner.split(",")) {
       const trimmed = entry.trim();
@@ -37,5 +39,15 @@ function extractExports(src: string): Signature[] {
     results.push({ name: m[1] });
   }
 
+  for (const m of src.matchAll(/^export\s*\*\s+from/gm)) {
+    results.push({ name: "*" });
+  }
+
+  for (const m of src.matchAll(
+    /^export\s+default\s+(?!function|class|const|let|var|type|interface|enum|abstract|async|declare)([a-zA-Z_]\w*)/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,153 @@
+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 && isDescendantOrSelf(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;
+}
+
+function isDescendantOrSelf(child: string, ancestor: string): boolean {
+  if (child === ancestor) return true;
+  return child.startsWith(ancestor + path.sep);
+}

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;