@wrongstack/plugins 0.281.3 → 0.282.1

package/dist/interface-contract-guard.d.ts

@@ -0,0 +1,37 @@
+import { Plugin } from '@wrongstack/core';
+
+/**
+ * interface-contract-guard plugin — checks TypeScript interface declarations
+ * for apparent implementers, warning when an interface looks unimplemented.
+ *
+ * Tools registered:
+ * - check_interface_contracts : Scan TypeScript files for unimplemented interfaces.
+ * - interface_contract_status : Report config + counters.
+ *
+ * Hooks registered:
+ * - PostToolUse with matcher `write|edit` to .ts/.tsx files, warning when the
+ *   changed file contains interface declarations because implementers may need
+ *   updating.
+ *
+ * Config (`config.extensions['interface-contract-guard']`):
+ *
+ * ```jsonc
+ * {
+ *   "enabled": true,
+ *   "extensions": [".ts", ".tsx"],
+ *   "maxFindings": 50
+ * }
+ * ```
+ *
+ * @public
+ */
+
+interface InterfaceContractFinding {
+    interfaceName: string;
+    file: string;
+    line: number;
+    message: string;
+}
+declare const plugin: Plugin;
+
+export { type InterfaceContractFinding, plugin as default };

package/dist/interface-contract-guard.js

@@ -0,0 +1,302 @@
+import { readFileSync, existsSync, statSync, readdirSync } from 'fs';
+import { resolve, isAbsolute, relative, extname } from 'path';
+
+// src/interface-contract-guard/index.ts
+var API_VERSION = "^0.1.10";
+var state = {
+  scanCount: 0,
+  findingCount: 0,
+  hookInvocationCount: 0,
+  warningCount: 0,
+  errorCount: 0,
+  hookUnregister: null
+};
+var DEFAULTS = {
+  enabled: false,
+  extensions: [".ts", ".tsx"],
+  maxFindings: 50
+};
+function readConfig(raw) {
+  if (!raw || typeof raw !== "object") return { ...DEFAULTS };
+  const r = raw;
+  return {
+    enabled: r["enabled"] !== false,
+    extensions: Array.isArray(r["extensions"]) ? r["extensions"].filter((x) => typeof x === "string") : DEFAULTS.extensions,
+    maxFindings: typeof r["maxFindings"] === "number" && r["maxFindings"] >= 1 && r["maxFindings"] <= 500 ? r["maxFindings"] : DEFAULTS.maxFindings
+  };
+}
+function withinProject(p) {
+  if (typeof p !== "string" || p.length === 0 || p.length > 4096) return false;
+  const root = process.cwd();
+  const resolved = isAbsolute(p) ? resolve(p) : resolve(root, p);
+  const rel = relative(root, resolved);
+  if (rel === "" || rel === ".") return true;
+  if (rel.startsWith("..")) return false;
+  if (isAbsolute(rel)) return false;
+  return true;
+}
+function normalizeExtensions(exts) {
+  return exts.map((e) => e.startsWith(".") ? e.toLowerCase() : `.${e.toLowerCase()}`);
+}
+function matchesExtension(p, exts) {
+  return exts.includes(extname(p).toLowerCase());
+}
+function collectSourceFiles(root, exts) {
+  const files = [];
+  if (!existsSync(root)) return files;
+  const s = statSync(root);
+  if (s.isFile()) {
+    if (matchesExtension(root, exts)) files.push(root);
+    return files;
+  }
+  if (!s.isDirectory()) return files;
+  function walk(dir) {
+    let entries;
+    try {
+      entries = readdirSync(dir);
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (entry === "node_modules" || entry === "dist" || entry === ".git" || entry === "coverage") continue;
+      const full = resolve(dir, entry);
+      let st;
+      try {
+        st = statSync(full);
+      } catch {
+        continue;
+      }
+      if (st.isDirectory()) {
+        walk(full);
+      } else if (st.isFile() && matchesExtension(full, exts)) {
+        files.push(full);
+      }
+    }
+  }
+  walk(root);
+  return files;
+}
+function toPosix(p) {
+  return p.replace(/\\/g, "/");
+}
+function relativePath(p) {
+  return toPosix(relative(process.cwd(), p));
+}
+var INTERFACE_RE = /(?:export\s+)?interface\s+([A-Za-z_$][A-Za-z0-9_$]*)/g;
+function extractInterfaceNames(content) {
+  const names = [];
+  let m;
+  INTERFACE_RE.lastIndex = 0;
+  while ((m = INTERFACE_RE.exec(content)) !== null) {
+    names.push({ name: m[1], line: content.slice(0, m.index).split(/\r?\n/).length });
+  }
+  return names;
+}
+function hasImplementer(name, contents) {
+  const implRe = new RegExp(`(?:implements|satisfies|\\bas)\\s+${name}\\b`, "g");
+  for (const content of contents) {
+    if (implRe.test(content)) return true;
+  }
+  return false;
+}
+function scanPath(rawPath, cfg) {
+  const root = process.cwd();
+  const resolved = isAbsolute(rawPath) ? resolve(rawPath) : resolve(root, rawPath);
+  const exts = normalizeExtensions(cfg.extensions);
+  const files = collectSourceFiles(resolved, exts);
+  const contents = [];
+  for (const p of files) {
+    try {
+      contents.push({ path: p, content: readFileSync(p, "utf-8") });
+    } catch {
+    }
+  }
+  const allContentStrings = contents.map((c) => c.content);
+  const findings = [];
+  for (const { path, content } of contents) {
+    for (const { name, line } of extractInterfaceNames(content)) {
+      if (!hasImplementer(name, allContentStrings)) {
+        findings.push({
+          interfaceName: name,
+          file: relativePath(path),
+          line,
+          message: `interface "${name}" is declared but has no visible implementer`
+        });
+        if (findings.length >= cfg.maxFindings) break;
+      }
+    }
+    if (findings.length >= cfg.maxFindings) break;
+  }
+  return { findings, scannedFiles: contents.length };
+}
+var plugin = {
+  name: "interface-contract-guard",
+  version: "0.1.0",
+  description: "Checks TypeScript interfaces for visible implementers and warns about contract drift",
+  apiVersion: API_VERSION,
+  capabilities: { tools: true, hooks: true },
+  defaultConfig: { ...DEFAULTS },
+  configSchema: {
+    type: "object",
+    properties: {
+      enabled: { type: "boolean", default: true, description: "Master switch." },
+      extensions: {
+        type: "array",
+        items: { type: "string" },
+        default: [".ts", ".tsx"],
+        description: "File extensions to scan."
+      },
+      maxFindings: {
+        type: "number",
+        minimum: 1,
+        maximum: 500,
+        default: 50,
+        description: "Maximum findings reported per scan."
+      }
+    }
+  },
+  setup(api) {
+    state.scanCount = 0;
+    state.findingCount = 0;
+    state.hookInvocationCount = 0;
+    state.warningCount = 0;
+    state.errorCount = 0;
+    if (state.hookUnregister) {
+      try {
+        state.hookUnregister();
+      } catch {
+      }
+      state.hookUnregister = null;
+    }
+    const cfg = readConfig(api.config.extensions?.["interface-contract-guard"]);
+    const hook = (input) => {
+      if (!cfg.enabled) return;
+      if (input.toolResult?.isError) return;
+      const inp = input.toolInput ?? {};
+      const sourcePath = inp["path"];
+      if (!sourcePath || typeof sourcePath !== "string") return;
+      if (!withinProject(sourcePath)) return;
+      const exts = normalizeExtensions(cfg.extensions);
+      if (!matchesExtension(sourcePath, exts)) return;
+      state.hookInvocationCount += 1;
+      const resolved = resolve(process.cwd(), sourcePath);
+      let content;
+      try {
+        content = readFileSync(resolved, "utf-8");
+      } catch {
+        state.errorCount += 1;
+        return;
+      }
+      const interfaces = extractInterfaceNames(content);
+      if (interfaces.length === 0) return;
+      state.warningCount += 1;
+      const names = interfaces.map((i) => i.name).join(", ");
+      return {
+        additionalContext: `
+\u{1F6E1}\uFE0F interface-contract-guard: ${sourcePath} declares interface(s): ${names}.
+If you changed member shapes, search the project for implementers/\`satisfies\`/\`as\` usages and update them accordingly.`
+      };
+    };
+    state.hookUnregister = api.registerHook("PostToolUse", "write|edit", hook);
+    api.tools.register({
+      name: "check_interface_contracts",
+      description: "Scan TypeScript files for interface declarations that have no visible implementer (implements / as / satisfies).",
+      inputSchema: {
+        type: "object",
+        properties: {
+          path: { type: "string", default: ".", description: "File or directory path to scan." }
+        }
+      },
+      permission: "auto",
+      category: "Diagnostics",
+      mutating: false,
+      async execute(input) {
+        if (!cfg.enabled) return { ok: false, error: "interface-contract-guard is disabled" };
+        const rawPath = typeof input.path === "string" ? input.path : ".";
+        if (!withinProject(rawPath)) {
+          return { ok: false, error: "path is outside the project root" };
+        }
+        state.scanCount += 1;
+        let result;
+        try {
+          result = scanPath(rawPath, cfg);
+        } catch (err) {
+          state.errorCount += 1;
+          return { ok: false, error: String(err) };
+        }
+        state.findingCount += result.findings.length;
+        return {
+          ok: true,
+          path: relativePath(resolve(process.cwd(), rawPath)),
+          scannedFiles: result.scannedFiles,
+          findings: result.findings
+        };
+      }
+    });
+    api.tools.register({
+      name: "interface_contract_status",
+      description: "Reports interface-contract-guard state: config + counters.",
+      inputSchema: { type: "object", properties: {} },
+      permission: "auto",
+      category: "Diagnostics",
+      mutating: false,
+      async execute() {
+        return {
+          ok: true,
+          enabled: cfg.enabled,
+          extensions: cfg.extensions,
+          maxFindings: cfg.maxFindings,
+          counters: {
+            scans: state.scanCount,
+            findings: state.findingCount,
+            hookInvocations: state.hookInvocationCount,
+            warnings: state.warningCount,
+            errors: state.errorCount
+          }
+        };
+      }
+    });
+    api.log.info("interface-contract-guard plugin loaded", {
+      version: "0.1.0",
+      extensions: cfg.extensions
+    });
+  },
+  teardown(api) {
+    if (state.hookUnregister) {
+      try {
+        state.hookUnregister();
+      } catch {
+      }
+      state.hookUnregister = null;
+    }
+    const final = {
+      scans: state.scanCount,
+      findings: state.findingCount,
+      hookInvocations: state.hookInvocationCount,
+      warnings: state.warningCount,
+      errors: state.errorCount
+    };
+    state.scanCount = 0;
+    state.findingCount = 0;
+    state.hookInvocationCount = 0;
+    state.warningCount = 0;
+    state.errorCount = 0;
+    api.log.info("interface-contract-guard: teardown complete", { final });
+  },
+  async health() {
+    return {
+      ok: state.errorCount === 0,
+      message: state.errorCount ? `interface-contract-guard: ${state.errorCount} error(s)` : `interface-contract-guard: ${state.scanCount} scan(s), ${state.findingCount} finding(s)`,
+      counters: {
+        scans: state.scanCount,
+        findings: state.findingCount,
+        hookInvocations: state.hookInvocationCount,
+        warnings: state.warningCount,
+        errors: state.errorCount
+      }
+    };
+  }
+};
+var interface_contract_guard_default = plugin;
+
+export { interface_contract_guard_default as default };

package/dist/knowledge-graph.d.ts

@@ -0,0 +1,45 @@
+import { Plugin } from '@wrongstack/core';
+
+/**
+ * knowledge-graph plugin — accumulates structured facts about the project
+ * across sessions.
+ *
+ * The plugin gives the agent three tools:
+ *  - `kg_add_fact`    — add a (subject, relation, object) triple
+ *  - `kg_query`       — query facts by subject, relation, or object
+ *  - `kg_remove_fact` — remove a fact by id
+ *  - `kg_status`      — counters + persisted path
+ *
+ * Facts persist in a project-local JSON file (default:
+ * `<projectDir>/.wrongstack/knowledge-graph.json`) so they survive across
+ * sessions. Optionally the plugin can contribute a compact summary of
+ * relevant facts to the system prompt for the current task.
+ *
+ * Config (`config.extensions['knowledge-graph']`):
+ *
+ * ```jsonc
+ * {
+ *   "enabled": true,
+ *   "filePath": ".wrongstack/knowledge-graph.json",
+ *   "maxFacts": 200,
+ *   "maxFactChars": 300,
+ *   "contributeToSystemPrompt": true,
+ *   "contributeMaxChars": 1500
+ * }
+ * ```
+ *
+ * @public
+ */
+
+interface Fact {
+    id: string;
+    subject: string;
+    relation: string;
+    object: string;
+    source: string | null;
+    confidence: 'low' | 'medium' | 'high';
+    createdAt: string;
+}
+declare const plugin: Plugin;
+
+export { type Fact, plugin as default };