@cuzfrog/pi-module-gates 0.8.0 → 0.10.0

package/README.md

@@ -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:

package/package.json

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

package/src/config.ts

@@ -3,19 +3,19 @@ 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);
@@ -25,5 +25,13 @@ export function loadConfig(cwd: string): ModuleGateConfig {
   } 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/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 {};
+  }
+}