@cuzfrog/pi-module-gates 0.8.0 → 0.12.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
@@ -11,8 +11,9 @@ AI coding agents produce edits with limited context knowledge (myopia) — their
 
 **Module contracts as guardrails.** Each directory can contain a descriptor file that declares:
 
-- `visible` — the set of exports allowed to be added or modified in that module
 - `readonly` — files and directories the agent must not touch
+- `frozen` — files where no new exports are allowed
+- `visible` — the set of exports allowed to be added or modified in that module
 
 The extension intercepts agent `write`/`edit` operations and enforces these contracts. Violations are blocked with a clear reason.
 
@@ -26,7 +27,8 @@ The extension intercepts agent `write`/`edit` operations and enforces these cont
    - **Export gate** — would the change introduce an export not in the `visible` list?
    - **Import gate** (not implemented yet) — would the change introduce an import violating visibility scope?
 
-System prompt: [system-prompt.md](src/context/system-prompt.ts)
+- System prompt: [system-prompt.md](src/context/system-prompt.ts)
+- Currently [supported languages](src/gates/checkers/index.ts): **TypeScript/JavaScript**, **Rust**, **Java**, **Go**, **Kotlin**, **Scala**
 
 ## Installation
 ```bash
@@ -58,8 +60,9 @@ frozen: [mod.rs]
 ```
 Frozen files cannot change their surface size: no new exports or public entries are allowed.
 
+A skill [module-freeze-all](src/skills/module-freeze-all) has been included to auto-freeze modules.
+
 ### Visibility whitelist (under redesign)
-Supported languages: Rust, TypeScript
 
 ```yaml
 visible:
@@ -105,11 +108,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/"
@@ -119,11 +122,11 @@ 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. |
 
-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.8.0",
+  "version": "0.12.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

@@ -3,27 +3,35 @@ import * as path from "node:path";
 
 export type ModuleGateConfig = {
   moduleDescriptorFileName: string;
-  moduleDescriptorReadonly: boolean;
+  moduleDescriptorReadonly: "file" | "frontmatter" | "off";
   sourceRoot: string;
 };
 
 const DEFAULTS: ModuleGateConfig = {
   moduleDescriptorFileName: "module.md",
-  moduleDescriptorReadonly: true,
+  moduleDescriptorReadonly: "file",
   sourceRoot: "src/",
 };
 
 export function loadConfig(cwd: string): ModuleGateConfig {
   const settingsPath = path.join(cwd, ".pi", "settings.json");
-  let userConfig: Partial<ModuleGateConfig> = {};
+  let userConfig: Partial<Omit<ModuleGateConfig, "moduleDescriptorReadonly"> & { moduleDescriptorReadonly?: ModuleGateConfig["moduleDescriptorReadonly"] | boolean }> = {};
   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
   }
-  return { ...DEFAULTS, ...userConfig };
+  const merged = { ...DEFAULTS, ...userConfig };
+  merged.moduleDescriptorReadonly = normalizeReadonly(merged.moduleDescriptorReadonly);
+  return merged as ModuleGateConfig;
+}
+
+function normalizeReadonly(value: ModuleGateConfig["moduleDescriptorReadonly"] | boolean): ModuleGateConfig["moduleDescriptorReadonly"] {
+  if (value === true || value === "file") return "file";
+  if (value === false || value === "off") return "off";
+  return value;
 }

package/src/context/system-prompt.ts

@@ -1,16 +1,20 @@
 import type { ModuleIndex } from "../types.ts";
+import type { ModuleGateConfig } from "../config.ts";
 
 export function buildSystemPromptHint(
   index: ModuleIndex,
   systemPrompt: string,
   descriptorFileName: string,
-  moduleDescriptorReadonly: boolean,
+  moduleDescriptorReadonly: ModuleGateConfig["moduleDescriptorReadonly"],
 ): string {
   if (index.contracts.length === 0) return systemPrompt;
 
-  const descriptorNote = moduleDescriptorReadonly
-    ? ` The \`${descriptorFileName}\` file itself is readonly.`
-    : "";
+  const descriptorNote =
+    moduleDescriptorReadonly === "frontmatter"
+      ? ` The frontmatter of \`${descriptorFileName}\` is readonly.`
+      : moduleDescriptorReadonly === "file"
+        ? ` The \`${descriptorFileName}\` file itself is readonly.`
+        : "";
 
   return systemPrompt + `
 

package/src/gates/checkers/go.ts

@@ -0,0 +1,19 @@
+import { registerChecker } from "./registry.ts";
+import type { ExportChecker } from "./registry.ts";
+import type { Signature } from "../../types.ts";
+
+const goChecker: ExportChecker = {
+  extensions: [".go"],
+  getNewExports(before: string, after: string): Signature[] {
+    const beforeNames = new Set(extractExports(before).map((s) => s.name));
+    return extractExports(after).filter((sig) => !beforeNames.has(sig.name));
+  },
+};
+
+registerChecker(goChecker);
+
+function extractExports(src: string): Signature[] {
+  return [...src.matchAll(
+    /^(?:func\s+(?!\()|type\s+|var\s+|const\s+)([\p{Lu}]\w*)/gmu,
+  )].map((m) => ({ name: m[1] }));
+}

package/src/gates/checkers/index.ts

@@ -1,2 +1,6 @@
 import "./typescript.ts";
 import "./rust.ts";
+import "./java.ts";
+import "./go.ts";
+import "./kotlin.ts";
+import "./scala.ts";

package/src/gates/checkers/java.ts

@@ -0,0 +1,19 @@
+import { registerChecker } from "./registry.ts";
+import type { ExportChecker } from "./registry.ts";
+import type { Signature } from "../../types.ts";
+
+const javaChecker: ExportChecker = {
+  extensions: [".java"],
+  getNewExports(before: string, after: string): Signature[] {
+    const beforeNames = new Set(extractExports(before).map((s) => s.name));
+    return extractExports(after).filter((sig) => !beforeNames.has(sig.name));
+  },
+};
+
+registerChecker(javaChecker);
+
+function extractExports(src: string): Signature[] {
+  return [...src.matchAll(
+    /^public\s+(?:class|interface|enum|@interface|record)\s+(\w+)/gm,
+  )].map((m) => ({ modifier: "public", name: m[1] }));
+}

package/src/gates/checkers/kotlin.ts

@@ -0,0 +1,26 @@
+import { registerChecker } from "./registry.ts";
+import type { ExportChecker } from "./registry.ts";
+import type { Signature } from "../../types.ts";
+
+const kotlinChecker: ExportChecker = {
+  extensions: [".kt", ".kts"],
+  getNewExports(before: string, after: string): Signature[] {
+    const beforeNames = new Set(extractExports(before).map((s) => s.name));
+    return extractExports(after).filter((sig) => !beforeNames.has(sig.name));
+  },
+};
+
+registerChecker(kotlinChecker);
+
+function extractExports(src: string): Signature[] {
+  const re = /^(?:(public|internal|protected|private)\s+)?(?:(?:data|sealed|enum|abstract|open)\s+)?(?:class|interface|object|fun|val|var|typealias)\s+(\w+)/gm;
+  const results: Signature[] = [];
+  for (const m of src.matchAll(re)) {
+    if (m[1] === "private") continue;
+    results.push({
+      modifier: m[1] || undefined,
+      name: m[2],
+    });
+  }
+  return results;
+}

package/src/gates/checkers/scala.ts

@@ -0,0 +1,26 @@
+import { registerChecker } from "./registry.ts";
+import type { ExportChecker } from "./registry.ts";
+import type { Signature } from "../../types.ts";
+
+const scalaChecker: ExportChecker = {
+  extensions: [".scala", ".sc"],
+  getNewExports(before: string, after: string): Signature[] {
+    const beforeNames = new Set(extractExports(before).map((s) => s.name));
+    return extractExports(after).filter((sig) => !beforeNames.has(sig.name));
+  },
+};
+
+registerChecker(scalaChecker);
+
+function extractExports(src: string): Signature[] {
+  const re = /^(?:(private(?:\[[^\]]*\])?|protected(?:\[[^\]]*\])?)\s+)?(?:class|object|trait|def|val|var|type|given|extension)\s+(\w+)/gm;
+  const results: Signature[] = [];
+  for (const m of src.matchAll(re)) {
+    if (m[1] === "private" || m[1] === "protected") continue;
+    results.push({
+      modifier: m[1] || undefined,
+      name: m[2],
+    });
+  }
+  return results;
+}

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/graph/module-index-builder.ts

@@ -4,6 +4,8 @@ import { readdir } from "node:fs/promises";
 import { parseFrontmatter } from "@earendil-works/pi-coding-agent";
 import type { ModuleContract, ModuleIndex } from "../types.ts";
 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";
@@ -35,7 +37,7 @@ function buildContracts(
   moduleFiles: string[],
   onInfo: (message: string) => void,
   descriptorFileName: string,
-  moduleDescriptorReadonly: boolean,
+  moduleDescriptorReadonly: ModuleDescriptorReadonly,
 ): ModuleContract[] {
   const contracts: ModuleContract[] = [];
 
@@ -57,7 +59,7 @@ function buildContracts(
     }
 
     const readonlyEntries = frontmatter.readonly ?? [];
-    if (moduleDescriptorReadonly) {
+    if (moduleDescriptorReadonly !== "off") {
       readonlyEntries.push(descriptorFileName);
     }
 

package/src/index.ts

@@ -4,7 +4,7 @@ import type {
   ToolCallEventResult,
   BeforeAgentStartEventResult,
 } from "@earendil-works/pi-coding-agent";
-import { isToolCallEventType } from "@earendil-works/pi-coding-agent";
+import { isToolCallEventType, parseFrontmatter } from "@earendil-works/pi-coding-agent";
 import type { ModuleIndex } from "./types.ts";
 import { loadConfig } from "./config.ts";
 import type { ModuleGateConfig } from "./config.ts";
@@ -67,6 +67,27 @@ function handleEdit(
 
   const readonlyResult = checkReadonly(filePath, index, cwd, config.moduleDescriptorFileName);
   if (readonlyResult.blocked) {
+    if (
+      config.moduleDescriptorReadonly === "frontmatter" &&
+      isDescriptorFile(absPath, config.moduleDescriptorFileName)
+    ) {
+      const fmBefore = extractFrontmatter(before);
+      const fmAfter = extractFrontmatter(after);
+      if (JSON.stringify(fmBefore) === JSON.stringify(fmAfter)) {
+        return undefined;
+      }
+      return {
+        block: true,
+        reason: formatDenial(
+          filePath,
+          `Readonly rule: frontmatter of ${config.moduleDescriptorFileName} is readonly`,
+          absPath,
+          index,
+          cwd,
+          config.moduleDescriptorFileName,
+        ),
+      };
+    }
     return { block: true, reason: formatDenial(filePath, readonlyResult.reason, absPath, index, cwd, config.moduleDescriptorFileName) };
   }
 
@@ -105,3 +126,16 @@ function formatDenial(
 
   return message;
 }
+
+function isDescriptorFile(absPath: string, descriptorFileName: string): boolean {
+  const basename = path.basename(absPath);
+  return basename.toLowerCase() === descriptorFileName.toLowerCase();
+}
+
+function extractFrontmatter(content: string): Record<string, unknown> {
+  try {
+    return parseFrontmatter(content).frontmatter;
+  } catch {
+    return {};
+  }
+}