@cuzfrog/pi-module-gates 0.13.3 → 0.15.0

package/README.md

@@ -17,6 +17,9 @@ AI coding agents produce edits with limited context knowledge (myopia) — their
 
 The extension intercepts agent `write`/`edit` operations and enforces these contracts. Violations are blocked with a clear reason.
 
+The attempt to add 2 public helper functions is blocked, forcing the agent to re-think the design.
+![Module Gate denial example](doc/module_gates_block.png)
+
 ### How it works
 
 1. **Indexing** — On session start, scans the project tree for descriptor files and builds a module index.
@@ -28,7 +31,7 @@ The extension intercepts agent `write`/`edit` operations and enforces these cont
    - **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)
+- System prompt: [system-prompt.md](src/context/system-prompt.template.md)
 - Currently [supported languages](src/gates/checkers/index.ts): **TypeScript/JavaScript**, **Rust**, **Java**, **Go**, **Kotlin**, **Scala**
 
 ## Installation
@@ -127,6 +130,7 @@ Add a `module-gates` entry to `.pi/settings.json`:
 | `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. |
+| `disableSystemPrompt` | `false` | When `true`, skip injecting the module-gates hint into the agent's system prompt. |
 
 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.13.3",
+  "version": "0.15.0",
   "description": "pi extension that controls the entropy of the codebase by enforcing code module boundaries.",
   "keywords": [
     "pi-package"

package/src/config.ts

@@ -6,6 +6,7 @@ export type ModuleGateConfig = {
   moduleDescriptorReadonly: "file" | "frontmatter" | "off";
   sourceRoot: string;
   disableModuleInterfaceImportGate: boolean;
+  disableSystemPrompt: boolean;
 };
 
 const DEFAULTS: ModuleGateConfig = {
@@ -13,6 +14,7 @@ const DEFAULTS: ModuleGateConfig = {
   moduleDescriptorReadonly: "file",
   sourceRoot: "src/",
   disableModuleInterfaceImportGate: false,
+  disableSystemPrompt: false,
 };
 
 export function loadConfig(cwd: string): ModuleGateConfig {

package/src/context/system-prompt.template.md

@@ -0,0 +1,17 @@
+## Module gates (boundary enforcement)
+This project uses `{{descriptorFileName}}`(case-insensitive) files to declare visibility, readonly and frozen rules that you should follow.
+If you cannot comply, reconsider your design or raise to the user with tradeoffs if necessary.
+Each `{{descriptorFileName}}` gates its branching point in the tree.
+A `{{descriptorFileName}}` with a `visible` list means only entries in the list are allowed to be visible outside the module.
+
+- Violations will be blocked.
+{{#if descriptorReadonly}}- {{descriptorReadonly}}{{/if}}
+{{#if moduleInterfaceImportGate}}- {{moduleInterfaceImportGate}}{{/if}}
+
+### Glossary
+- `module`: a directory containing code;
+- `external files`: files not in the module directory;
+- `module interface`: the file representing the module surface, e.g. `index.ts` in Typescript, `mod.rs` in Rust;
+- `readonly`: files are readonly;
+- `frozen`: files cannot add new exports, but still editable;
+- `visible`: visible from outside the module; files not in the module directory are outside the module;

package/src/context/system-prompt.ts

@@ -1,3 +1,7 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+
 import type { ModuleIndex } from "../types.ts";
 import type { ModuleGateConfig } from "../config.ts";
 
@@ -7,22 +11,38 @@ export function buildSystemPromptHint(
   descriptorFileName: string,
   config: ModuleGateConfig,
 ): string {
+  if (config.disableSystemPrompt) return systemPrompt;
   if (index.contracts.length === 0) return systemPrompt;
 
-  const descriptorNote =
+  const descriptorReadonly =
     config.moduleDescriptorReadonly === "frontmatter"
-      ? ` The frontmatter of \`${descriptorFileName}\` is readonly.`
+      ? `The frontmatter of \`${descriptorFileName}\` is readonly.`
       : config.moduleDescriptorReadonly === "file"
-        ? ` The \`${descriptorFileName}\` file itself is readonly.`
+        ? `The \`${descriptorFileName}\` file itself is readonly.`
         : "";
 
-  return systemPrompt + `
+  const moduleInterfaceImportGate = config.disableModuleInterfaceImportGate
+    ? ""
+    : "External files can only import through the module interface (e.g. `index.ts` in TypeScript, `mod.rs` in Rust).";
+
+  const section = applyTemplate(TEMPLATE, {
+    descriptorFileName,
+    descriptorReadonly,
+    moduleInterfaceImportGate,
+  });
 
-## Module gates (boundary enforcement)
-This project uses \`${descriptorFileName}\`(case-insensitive) files to declare visibility, readonly and frozen rules that you should follow.
-If you cannot comply, reconsider your design, if impossible, raise to the user with tradeoffs.
-Each \`${descriptorFileName}\` gates its branching point in the tree.
-A \`${descriptorFileName}\` with a \`visible\` list means only entries in the list are allowed to be visible outside the module.
-\`readonly\` files are readonly; \`frozen\` files cannot add new exports.${descriptorNote}
-Violations will be blocked.`;
+  return systemPrompt + "\n\n" + section;
 }
+
+const TEMPLATE = fs.readFileSync(
+  path.join(path.dirname(fileURLToPath(import.meta.url)), "system-prompt.template.md"),
+  "utf-8",
+);
+
+function applyTemplate(template: string, vars: Record<string, string>): string {
+  const ifBlock = /\{\{#if\s+(\w+)\}\}([\s\S]*?)\{\{\/if\}\}/g;
+  const variable = /\{\{(\w+)\}\}/g;
+  return template
+    .replace(ifBlock, (_match, name: string, body: string) => (vars[name] ? body : ""))
+    .replace(variable, (_match, name: string) => vars[name] ?? "");
+}