@atheory-ai/ce-plugin-sdk 0.1.0

package/dist/index.cjs

@@ -0,0 +1,267 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  IIRTypeUnknown: () => IIRTypeUnknown,
+  childByField: () => childByField,
+  childrenByType: () => childrenByType,
+  classifyEffect: () => classifyEffect,
+  createSubstrateClient: () => createSubstrateClient,
+  definePlugin: () => definePlugin,
+  edgeID: () => edgeID,
+  emit: () => emit,
+  fieldText: () => fieldText,
+  firstByType: () => firstByType,
+  firstDescendantByType: () => firstDescendantByType,
+  getConfig: () => getConfig,
+  hasChildType: () => hasChildType,
+  log: () => log,
+  nodeID: () => nodeID,
+  setPluginDefinition: () => setPluginDefinition,
+  walk: () => walk,
+  walkTopLevel: () => walkTopLevel
+});
+module.exports = __toCommonJS(src_exports);
+
+// src/define.ts
+function definePlugin(definition) {
+  if (!definition.id || !definition.id.includes(".")) {
+    throw new Error(
+      `Plugin id must be reverse-domain format (e.g., "com.example.my-plugin"). Got: "${definition.id}"`
+    );
+  }
+  if (!definition.name) {
+    throw new Error("Plugin name is required");
+  }
+  if (!definition.version || !isValidSemver(definition.version)) {
+    throw new Error(
+      `Plugin version must be valid semver (e.g., "1.0.0"). Got: "${definition.version}"`
+    );
+  }
+  if (definition.language) {
+    if (typeof definition.language.match !== "function") {
+      throw new Error("language.match must be a function");
+    }
+    if (typeof definition.language.extract !== "function") {
+      throw new Error("language.extract must be a function");
+    }
+    if (definition.language.concepts) {
+      for (const seed of definition.language.concepts) {
+        if (seed.term !== seed.term.toLowerCase()) {
+          throw new Error(`Concept terms must be lowercase. Got: "${seed.term}"`);
+        }
+        if (!seed.term.match(/^[a-z][a-z0-9-]*$/)) {
+          throw new Error(
+            `Concept terms must be lowercase-hyphenated. Got: "${seed.term}"`
+          );
+        }
+      }
+    }
+  }
+  if (definition.tools) {
+    for (const tool of definition.tools) {
+      if (!tool.name) {
+        throw new Error("Tool name is required");
+      }
+      if (!tool.description) {
+        throw new Error(`Tool "${tool.name}" description is required`);
+      }
+      if (tool.description.length > 100) {
+        throw new Error(
+          `Tool "${tool.name}" description exceeds 100 characters (${tool.description.length}). The Strategizer receives this in its prompt \u2014 keep it concise.`
+        );
+      }
+      if (typeof tool.activate !== "function") {
+        throw new Error(`Tool "${tool.name}" activate must be a function`);
+      }
+      if (typeof tool.execute !== "function") {
+        throw new Error(`Tool "${tool.name}" execute must be a function`);
+      }
+    }
+  }
+  if (definition.analyzers) {
+    for (const analyzer of definition.analyzers) {
+      if (!analyzer.name) {
+        throw new Error("Analyzer name is required");
+      }
+      if (typeof analyzer.analyze !== "function") {
+        throw new Error(`Analyzer "${analyzer.name}" analyze must be a function`);
+      }
+    }
+  }
+  if (definition.iirRules) {
+    if (!Array.isArray(definition.iirRules.rules) || definition.iirRules.rules.length === 0) {
+      throw new Error("iirRules.rules must be a non-empty array");
+    }
+    for (const rule of definition.iirRules.rules) {
+      if (!rule.id) {
+        throw new Error("Each IIR rule requires an id");
+      }
+      if (!rule.target || !rule.severity) {
+        throw new Error(`IIR rule "${rule.id}" requires target and severity`);
+      }
+    }
+  }
+  setPluginDefinition(definition);
+  return definition;
+}
+function setPluginDefinition(definition) {
+  const globalScope = globalThis;
+  globalScope.__ce_plugin_definition = definition;
+}
+function isValidSemver(version) {
+  return /^\d+\.\d+\.\d+(-[\w.]+)?(\+[\w.]+)?$/.test(version);
+}
+
+// src/host.ts
+var log = {
+  debug: (message) => __ce_log("debug", message),
+  info: (message) => __ce_log("info", message),
+  warn: (message) => __ce_log("warn", message),
+  error: (message) => __ce_log("error", message)
+};
+function emit(channel, content) {
+  __ce_emit(channel, content);
+}
+function createSubstrateClient() {
+  return {
+    query(q) {
+      const result = __ce_substrate_query(JSON.stringify(q));
+      return JSON.parse(result);
+    }
+  };
+}
+function getConfig(key) {
+  const result = __ce_get_config(key);
+  if (!result)
+    return void 0;
+  return JSON.parse(result);
+}
+function nodeID(projectID, type, canonicalID) {
+  return __ce_node_id(projectID, type, canonicalID);
+}
+function edgeID(sourceID, type, targetID) {
+  return __ce_edge_id(sourceID, type, targetID);
+}
+
+// src/tree.ts
+function kids(node) {
+  return node.children ?? [];
+}
+function walk(node, visit) {
+  if (!node)
+    return;
+  const stack = [node];
+  while (stack.length > 0) {
+    const n = stack.pop();
+    visit(n);
+    const cs = kids(n);
+    for (let i = cs.length - 1; i >= 0; i--)
+      stack.push(cs[i]);
+  }
+}
+function walkTopLevel(node, visit) {
+  if (!node)
+    return;
+  const stack = [{ n: node, descend: true }];
+  while (stack.length > 0) {
+    const { n, descend } = stack.pop();
+    visit(n);
+    if (!descend)
+      continue;
+    const cs = kids(n);
+    for (let i = cs.length - 1; i >= 0; i--) {
+      stack.push({ n: cs[i], descend: !SCOPE_BOUNDARY.has(cs[i].type) });
+    }
+  }
+}
+var SCOPE_BOUNDARY = /* @__PURE__ */ new Set([
+  "function_declaration",
+  "function_expression",
+  "arrow_function",
+  "method_definition",
+  "generator_function",
+  "generator_function_declaration"
+]);
+function childByField(node, field) {
+  for (const child of kids(node)) {
+    if (child.fieldName === field)
+      return child;
+  }
+  return null;
+}
+function childrenByType(node, type) {
+  return kids(node).filter((c) => c.type === type);
+}
+function firstByType(node, type) {
+  return kids(node).find((c) => c.type === type) ?? null;
+}
+function hasChildType(node, type) {
+  return kids(node).some((c) => c.type === type);
+}
+function fieldText(node, field) {
+  return childByField(node, field)?.text ?? "";
+}
+function firstDescendantByType(node, type) {
+  let found = null;
+  walk(node, (n) => {
+    if (found === null && n.type === type)
+      found = n;
+  });
+  return found;
+}
+
+// src/iir.ts
+var IIRTypeUnknown = "unknown";
+
+// src/effects.ts
+var pathCategories = [
+  ["network", ["net/http", "net/url", "net", "google.golang.org/grpc", "github.com/gorilla/websocket"]],
+  ["db", ["database/sql", "gorm.io", "go.mongodb.org", "github.com/redis", "github.com/jmoiron/sqlx"]],
+  ["io", ["os", "io", "io/ioutil", "bufio", "path/filepath"]],
+  // fmt's pure formatters (Sprintf, Errorf) are excluded before classification;
+  // what reaches here (Println/Printf/Fprint…) writes output.
+  ["log", ["log", "log/slog", "fmt"]]
+];
+var rootCategories = [
+  ["network", ["http", "https", "fetch", "axios", "request", "requests", "grpc", "ws", "socket", "urllib"]],
+  ["db", ["db", "sql", "database", "redis", "mongo", "session", "repository", "datastore"]],
+  ["io", ["os", "io", "fs", "ioutil", "file", "pathlib"]],
+  ["log", ["log", "logger", "logging", "console", "slog", "fmt"]]
+];
+var mutationVerbs = ["track", "send", "emit", "publish", "save", "create", "update", "delete", "write"];
+function classifyEffect(input) {
+  const path = (input.importPath ?? "").toLowerCase();
+  const root = (input.root ?? "").toLowerCase();
+  const method = (input.method ?? "").toLowerCase();
+  for (const [kind, prefixes] of pathCategories) {
+    if (prefixes.some((p) => path === p || path.startsWith(p + "/")))
+      return { kind, basis: "resolved" };
+  }
+  for (const [kind, roots] of rootCategories) {
+    if (roots.includes(root))
+      return { kind, basis: "resolved" };
+  }
+  if (mutationVerbs.some((v) => method.includes(v)))
+    return { kind: "mutation", basis: "heuristic" };
+  return { kind: "unclassified", basis: "heuristic" };
+}
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/index.ts", "../src/define.ts", "../src/host.ts", "../src/tree.ts", "../src/iir.ts", "../src/effects.ts"],
+  "sourcesContent": ["export { definePlugin, setPluginDefinition } from \"./define.js\"\nexport { log, emit, createSubstrateClient, getConfig, nodeID, edgeID } from \"./host.js\"\nexport {\n  walk,\n  walkTopLevel,\n  childByField,\n  childrenByType,\n  firstByType,\n  hasChildType,\n  fieldText,\n  firstDescendantByType,\n} from \"./tree.js\"\nexport type {\n  SyntaxNode,\n  Position,\n  Node,\n  Edge,\n  NodeType,\n  EdgeType,\n  SourceClass,\n  ExtractionResult,\n  ConceptSeed,\n  AnchorRef,\n  Anchor,\n  IR,\n  Emission,\n  ToolRequest,\n  ToolResult,\n  SubstrateQuery,\n  SubstrateClient,\n  LanguageDefinition,\n  RoleDefinition,\n  AnalyzerDefinition,\n  ToolDefinition,\n  PluginDefinition,\n  IIRSeverity,\n  IIRTarget,\n  IIRExprPattern,\n  IIRRuleWhen,\n  IIRRuleRequire,\n  IIRRule,\n  IIRRulePack,\n} from \"./types.js\"\nexport { IIRTypeUnknown } from \"./iir.js\"\nexport type {\n  IIRVisibility,\n  IIRParam,\n  IIRReturn,\n  IIRExpr,\n  IIRBehaviorClause,\n  IIRConsequence,\n  IIRSideEffect,\n  IIRFailureMode,\n  FunctionIntent,\n  ExtractedFunction,\n} from \"./iir.js\"\nexport { classifyEffect } from \"./effects.js\"\nexport type { EffectKind, EffectBasis, EffectClassifierInput } from \"./effects.js\"\n", "import type { PluginDefinition } from \"./types.js\"\n\n/**\n * definePlugin is the single entry point for all plugin authors.\n *\n * Usage:\n *   import { definePlugin } from \"@atheory-ai/ce-plugin-sdk\"\n *\n *   export default definePlugin({\n *     id: \"com.example.my-plugin\",\n *     name: \"My Plugin\",\n *     version: \"1.0.0\",\n *     language: { match, extract, concepts },\n *     tools: [{ name, description, activate, execute }],\n *   })\n */\nexport function definePlugin(definition: PluginDefinition): PluginDefinition {\n  if (!definition.id || !definition.id.includes(\".\")) {\n    throw new Error(\n      `Plugin id must be reverse-domain format (e.g., \"com.example.my-plugin\"). Got: \"${definition.id}\"`\n    )\n  }\n\n  if (!definition.name) {\n    throw new Error(\"Plugin name is required\")\n  }\n\n  if (!definition.version || !isValidSemver(definition.version)) {\n    throw new Error(\n      `Plugin version must be valid semver (e.g., \"1.0.0\"). Got: \"${definition.version}\"`\n    )\n  }\n\n  if (definition.language) {\n    if (typeof definition.language.match !== \"function\") {\n      throw new Error(\"language.match must be a function\")\n    }\n    if (typeof definition.language.extract !== \"function\") {\n      throw new Error(\"language.extract must be a function\")\n    }\n    if (definition.language.concepts) {\n      for (const seed of definition.language.concepts) {\n        if (seed.term !== seed.term.toLowerCase()) {\n          throw new Error(`Concept terms must be lowercase. Got: \"${seed.term}\"`)\n        }\n        if (!seed.term.match(/^[a-z][a-z0-9-]*$/)) {\n          throw new Error(\n            `Concept terms must be lowercase-hyphenated. Got: \"${seed.term}\"`\n          )\n        }\n      }\n    }\n  }\n\n  if (definition.tools) {\n    for (const tool of definition.tools) {\n      if (!tool.name) {\n        throw new Error(\"Tool name is required\")\n      }\n      if (!tool.description) {\n        throw new Error(`Tool \"${tool.name}\" description is required`)\n      }\n      if (tool.description.length > 100) {\n        throw new Error(\n          `Tool \"${tool.name}\" description exceeds 100 characters (${tool.description.length}). ` +\n          `The Strategizer receives this in its prompt \u2014 keep it concise.`\n        )\n      }\n      if (typeof tool.activate !== \"function\") {\n        throw new Error(`Tool \"${tool.name}\" activate must be a function`)\n      }\n      if (typeof tool.execute !== \"function\") {\n        throw new Error(`Tool \"${tool.name}\" execute must be a function`)\n      }\n    }\n  }\n\n  if (definition.analyzers) {\n    for (const analyzer of definition.analyzers) {\n      if (!analyzer.name) {\n        throw new Error(\"Analyzer name is required\")\n      }\n      if (typeof analyzer.analyze !== \"function\") {\n        throw new Error(`Analyzer \"${analyzer.name}\" analyze must be a function`)\n      }\n    }\n  }\n\n  if (definition.iirRules) {\n    // The host is the authoritative validator (internal/iir). Keep this to a\n    // shape sanity check so an obvious mistake fails at author time rather than\n    // silently shipping an empty pack.\n    if (!Array.isArray(definition.iirRules.rules) || definition.iirRules.rules.length === 0) {\n      throw new Error(\"iirRules.rules must be a non-empty array\")\n    }\n    for (const rule of definition.iirRules.rules) {\n      if (!rule.id) {\n        throw new Error(\"Each IIR rule requires an id\")\n      }\n      if (!rule.target || !rule.severity) {\n        throw new Error(`IIR rule \"${rule.id}\" requires target and severity`)\n      }\n    }\n  }\n\n  setPluginDefinition(definition)\n  return definition\n}\n\nexport function setPluginDefinition(definition: PluginDefinition): void {\n  const globalScope = globalThis as typeof globalThis & {\n    __ce_plugin_definition?: PluginDefinition\n  }\n  globalScope.__ce_plugin_definition = definition\n}\n\nfunction isValidSemver(version: string): boolean {\n  return /^\\d+\\.\\d+\\.\\d+(-[\\w.]+)?(\\+[\\w.]+)?$/.test(version)\n}\n", "import type { SubstrateQuery, Node, SubstrateClient, NodeType, EdgeType } from \"./types.js\"\n\n/**\n * Low-level host function declarations.\n * These are provided by the engine's wazero runtime.\n */\ndeclare function __ce_log(level: string, message: string): void\ndeclare function __ce_emit(channel: string, content: string): void\ndeclare function __ce_substrate_query(queryJSON: string): string\ndeclare function __ce_get_config(key: string): string\ndeclare function __ce_node_id(projectID: string, type: string, canonicalID: string): string\ndeclare function __ce_edge_id(sourceID: string, type: string, targetID: string): string\n\n// \u2500\u2500 Logging \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\nexport const log = {\n  debug: (message: string) => __ce_log(\"debug\", message),\n  info:  (message: string) => __ce_log(\"info\",  message),\n  warn:  (message: string) => __ce_log(\"warn\",  message),\n  error: (message: string) => __ce_log(\"error\", message),\n}\n\n// \u2500\u2500 Emit \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\nexport function emit(channel: \"thinking\" | \"action\" | \"debug\" | \"warning\", content: string): void {\n  __ce_emit(channel, content)\n}\n\n// \u2500\u2500 Substrate \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\nexport function createSubstrateClient(): SubstrateClient {\n  return {\n    query(q: SubstrateQuery): Node[] {\n      const result = __ce_substrate_query(JSON.stringify(q))\n      return JSON.parse(result) as Node[]\n    }\n  }\n}\n\n// \u2500\u2500 Config \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\nexport function getConfig<T = unknown>(key: string): T | undefined {\n  const result = __ce_get_config(key)\n  if (!result) return undefined\n  return JSON.parse(result) as T\n}\n\n// \u2500\u2500 ID generation \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\nexport function nodeID(projectID: string, type: NodeType, canonicalID: string): string {\n  return __ce_node_id(projectID, type as string, canonicalID)\n}\n\nexport function edgeID(sourceID: string, type: EdgeType, targetID: string): string {\n  return __ce_edge_id(sourceID, type as string, targetID)\n}\n", "// CST-walking helpers for language extractors. The host hands plugins a parsed\n// tree-sitter tree (SyntaxNode); these make walking it ergonomic so extractors\n// never fall back to regex.\n\nimport type { SyntaxNode } from \"./types.js\"\n\n// The host omits `children` on leaf nodes (serialized as null), so every access\n// goes through this \u2014 helpers must never assume `children` is an array.\nfunction kids(node: SyntaxNode): SyntaxNode[] {\n  return node.children ?? []\n}\n\n/**\n * walk visits node and every descendant in pre-order. Iterative (explicit\n * stack) so a deeply nested CST \u2014 long expression chains, minified/generated\n * code \u2014 cannot overflow the call stack.\n */\nexport function walk(node: SyntaxNode | null, visit: (n: SyntaxNode) => void): void {\n  if (!node) return\n  const stack: SyntaxNode[] = [node]\n  while (stack.length > 0) {\n    const n = stack.pop()!\n    visit(n)\n    const cs = kids(n)\n    for (let i = cs.length - 1; i >= 0; i--) stack.push(cs[i]) // reversed \u2192 pop in order\n  }\n}\n\n/**\n * walkTopLevel visits node and its descendants, but does NOT descend into\n * nested function/closure scopes \u2014 a boundary node itself is visited, its body\n * is not. Use it to collect a scope's own declarations without pulling in ones\n * nested inside inner functions.\n */\nexport function walkTopLevel(node: SyntaxNode | null, visit: (n: SyntaxNode) => void): void {\n  if (!node) return\n  // Stack entries carry whether to descend into that node's children \u2014 a\n  // boundary node is visited but its subtree is not walked. Iterative to avoid\n  // call-stack overflow on deep trees.\n  const stack: Array<{ n: SyntaxNode; descend: boolean }> = [{ n: node, descend: true }]\n  while (stack.length > 0) {\n    const { n, descend } = stack.pop()!\n    visit(n)\n    if (!descend) continue\n    const cs = kids(n)\n    for (let i = cs.length - 1; i >= 0; i--) {\n      stack.push({ n: cs[i], descend: !SCOPE_BOUNDARY.has(cs[i].type) })\n    }\n  }\n}\n\nconst SCOPE_BOUNDARY = new Set([\n  \"function_declaration\",\n  \"function_expression\",\n  \"arrow_function\",\n  \"method_definition\",\n  \"generator_function\",\n  \"generator_function_declaration\",\n])\n\n/** childByField returns the child occupying the given field, or null. */\nexport function childByField(node: SyntaxNode, field: string): SyntaxNode | null {\n  for (const child of kids(node)) {\n    if (child.fieldName === field) return child\n  }\n  return null\n}\n\n/** childrenByType returns direct children of a given type. */\nexport function childrenByType(node: SyntaxNode, type: string): SyntaxNode[] {\n  return kids(node).filter(c => c.type === type)\n}\n\n/** firstByType returns the first direct child of a given type, or null. */\nexport function firstByType(node: SyntaxNode, type: string): SyntaxNode | null {\n  return kids(node).find(c => c.type === type) ?? null\n}\n\n/** hasChildType reports whether node has a direct child (named or token) of the given type. */\nexport function hasChildType(node: SyntaxNode, type: string): boolean {\n  return kids(node).some(c => c.type === type)\n}\n\n/** fieldText returns the text of the child in the given field, or \"\". */\nexport function fieldText(node: SyntaxNode, field: string): string {\n  return childByField(node, field)?.text ?? \"\"\n}\n\n/** firstDescendantByType returns the first descendant of a given type (pre-order), or null. */\nexport function firstDescendantByType(node: SyntaxNode, type: string): SyntaxNode | null {\n  let found: SyntaxNode | null = null\n  walk(node, n => {\n    if (found === null && n.type === type) found = n\n  })\n  return found\n}\n", "// The IIR (Intermediate Intent Representation) model, mirrored from Context\n// Engine's internal/iir. A language plugin may *lift* source into these types\n// during extraction; the host validates and stores them (it remains the\n// authoritative parser \u2014 these are the authoring/contract surface). Field names\n// match the host's JSON tags so a host-side ParseIntentJSON accepts them.\n\nexport type IIRVisibility = \"public\" | \"private\"\n\n// TypeUnknown marks a parameter type that could not be determined from source \u2014\n// represented explicitly rather than dropped, so comparison can tell \"unknown\"\n// from \"absent\".\nexport const IIRTypeUnknown = \"unknown\"\n\nexport interface IIRParam {\n  name: string\n  type: string\n}\n\nexport interface IIRReturn {\n  // Empty string means the return type was absent in source (distinct from the\n  // explicit type \"void\").\n  type:     string\n  explicit: boolean\n}\n\n// IIRExpr is a normalized condition expression node (mirrors iir.Expr): `op`\n// names the node (\"<\", \"&&\", \"!\", \"path\", \"lit\"), `args` are operands in source\n// order, `text` carries a leaf payload (a literal value or a dotted access path).\nexport interface IIRExpr {\n  op:    string\n  args?: IIRExpr[]\n  text?: string\n}\n\n/**\n * A normalized behavior consequence \u2014 the `then` action of a clause, structured\n * just enough to compare across languages. `op` is the action: \"return\", \"throw\"\n * (Go panic / JS-TS throw / Python raise, folded), or \"invoke\" (a call). `value`\n * is an opaque canonical payload (the returned expression, the thrown failure's\n * identity, or the invoked callee), omitted when the action carries none.\n */\nexport interface IIRConsequence {\n  op:     \"return\" | \"throw\" | \"invoke\"\n  value?: string\n}\n\nexport interface IIRBehaviorClause {\n  when:      string\n  then:      string\n  whenExpr?: IIRExpr\n  thenExpr?: IIRConsequence\n}\n\n/**\n * An observable side effect. Either a bare name (\"analytics.track\") or an object\n * carrying an optional kind (network | db | io | log | mutation | unclassified)\n * and basis \u2014 \"resolved\" when the kind came from a known effectful API (an\n * import path or recognized client), \"heuristic\" when it was guessed from a\n * method-name verb. The host accepts both forms; a plugin that can categorize an\n * effect emits the object form, otherwise a bare string.\n */\nexport type IIRSideEffect = string | {\n  name:  string\n  kind?: \"network\" | \"db\" | \"io\" | \"log\" | \"mutation\" | \"unclassified\"\n  basis?: \"resolved\" | \"heuristic\"\n}\n\n/**\n * An expected failure outcome. Either a bare code (\"amount_below_minimum\") or an\n * object carrying an optional kind and source. The kind names *how* the function\n * signals the failure: \"constructed\" (created inline, e.g. throw new Error(\"msg\")\n * / errors.New), \"sentinel\" (a named error value/type, e.g. ErrClosed or a custom\n * error class), or \"propagated\" (an upstream failure forwarded on \u2014 a re-throw or\n * `return nil, err`). For a propagated failure, `source` names the forwarded\n * identifier. The host accepts both forms; a code-only failure round-trips as a\n * bare string.\n */\nexport type IIRFailureMode = string | {\n  code:    string\n  kind?:   \"constructed\" | \"sentinel\" | \"propagated\"\n  source?: string\n}\n\nexport interface FunctionIntent {\n  kind:         \"FunctionIntent\"\n  name:         string\n  language:     string\n  /**\n   * The epistemic layer this intent comes from. A plugin lift emits \"observed\"\n   * (ground truth about what the code does); a hand-authored spec is \"declared\";\n   * the shaper emits \"inferred\". The host defaults an absent origin to declared.\n   */\n  origin?:      \"observed\" | \"declared\" | \"inferred\"\n  visibility?:  IIRVisibility\n  inputs:       IIRParam[]\n  returns:      IIRReturn\n  behavior:     IIRBehaviorClause[]\n  sideEffects:  IIRSideEffect[]\n  failureModes: IIRFailureMode[]\n  constraints:  string[]\n}\n\n// ExtractedFunction pairs a lifted FunctionIntent with the id of the symbol node\n// it was lifted from. The plugin knows this id directly (it created the node),\n// so the host can attach the IIR to the exact node without the (name,start_byte)\n// correlation the Go-side lift needs.\nexport interface ExtractedFunction {\n  nodeId: string\n  intent: FunctionIntent\n}\n", "// Shared side-effect classifier for language plugins. Given the structured parts\n// of a detected call \u2014 the receiver root, the method, and (when the root is an\n// imported package) its full import path \u2014 it returns the effect kind and a\n// confidence. Plugins emit these on each SideEffect so the host doesn't have to\n// re-derive them from the name string at compare time.\n//\n// Matching is structural (exact root, method substring, import-path prefix)\n// rather than substring-on-the-whole-name, which avoids false hits like\n// \"catalog.save\" being read as a log effect because the name contains \"log\".\n\nexport type EffectKind = \"network\" | \"db\" | \"io\" | \"log\" | \"mutation\" | \"unclassified\"\n// How an effect's kind was established. \"resolved\" means it matched a known\n// effectful API (an import path or a recognized client root) \u2014 deterministic\n// knowledge, not a probabilistic guess. \"heuristic\" means it was inferred from a\n// method-name verb or is uncategorized. The comparator treats an undeclared\n// resolved effect as an error and an undeclared heuristic one as a warning: it\n// should not fail verification on a guess.\nexport type EffectBasis = \"resolved\" | \"heuristic\"\n\nexport interface EffectClassifierInput {\n  /** The called method / function name, e.g. \"Get\", \"track\". */\n  method?: string\n  /** The receiver root, e.g. \"http\", \"analytics\". */\n  root?: string\n  /** Full import path of the root when it is an imported package, e.g. \"net/http\". */\n  importPath?: string\n}\n\n// Import-path prefixes are the strongest signal (a real, categorizable package).\nconst pathCategories: [EffectKind, string[]][] = [\n  [\"network\", [\"net/http\", \"net/url\", \"net\", \"google.golang.org/grpc\", \"github.com/gorilla/websocket\"]],\n  [\"db\", [\"database/sql\", \"gorm.io\", \"go.mongodb.org\", \"github.com/redis\", \"github.com/jmoiron/sqlx\"]],\n  [\"io\", [\"os\", \"io\", \"io/ioutil\", \"bufio\", \"path/filepath\"]],\n  // fmt's pure formatters (Sprintf, Errorf) are excluded before classification;\n  // what reaches here (Println/Printf/Fprint\u2026) writes output.\n  [\"log\", [\"log\", \"log/slog\", \"fmt\"]],\n]\n\n// Receiver roots that categorize a call even without a resolved import path\n// (e.g. member calls on a well-known client name).\nconst rootCategories: [EffectKind, string[]][] = [\n  [\"network\", [\"http\", \"https\", \"fetch\", \"axios\", \"request\", \"requests\", \"grpc\", \"ws\", \"socket\", \"urllib\"]],\n  [\"db\", [\"db\", \"sql\", \"database\", \"redis\", \"mongo\", \"session\", \"repository\", \"datastore\"]],\n  [\"io\", [\"os\", \"io\", \"fs\", \"ioutil\", \"file\", \"pathlib\"]],\n  [\"log\", [\"log\", \"logger\", \"logging\", \"console\", \"slog\", \"fmt\"]],\n]\n\n// Method names that signal an observable mutation/effect.\nconst mutationVerbs = [\"track\", \"send\", \"emit\", \"publish\", \"save\", \"create\", \"update\", \"delete\", \"write\"]\n\n/**\n * classifyEffect returns the (kind, basis) for a detected effectful call. A call\n * matched against a known effectful API \u2014 by import path or a recognized client\n * root \u2014 is \"resolved\" (deterministic). A call categorized only from a\n * method-name verb, or left uncategorized, is \"heuristic\" (a guess).\n */\nexport function classifyEffect(input: EffectClassifierInput): { kind: EffectKind; basis: EffectBasis } {\n  const path = (input.importPath ?? \"\").toLowerCase()\n  const root = (input.root ?? \"\").toLowerCase()\n  const method = (input.method ?? \"\").toLowerCase()\n\n  for (const [kind, prefixes] of pathCategories) {\n    if (prefixes.some(p => path === p || path.startsWith(p + \"/\"))) return { kind, basis: \"resolved\" }\n  }\n  for (const [kind, roots] of rootCategories) {\n    if (roots.includes(root)) return { kind, basis: \"resolved\" }\n  }\n  if (mutationVerbs.some(v => method.includes(v))) return { kind: \"mutation\", basis: \"heuristic\" }\n  return { kind: \"unclassified\", basis: \"heuristic\" }\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { definePlugin, setPluginDefinition } from "./define.js";
+export { log, emit, createSubstrateClient, getConfig, nodeID, edgeID } from "./host.js";
+export { walk, walkTopLevel, childByField, childrenByType, firstByType, hasChildType, fieldText, firstDescendantByType, } from "./tree.js";
+export type { SyntaxNode, Position, Node, Edge, NodeType, EdgeType, SourceClass, ExtractionResult, ConceptSeed, AnchorRef, Anchor, IR, Emission, ToolRequest, ToolResult, SubstrateQuery, SubstrateClient, LanguageDefinition, RoleDefinition, AnalyzerDefinition, ToolDefinition, PluginDefinition, IIRSeverity, IIRTarget, IIRExprPattern, IIRRuleWhen, IIRRuleRequire, IIRRule, IIRRulePack, } from "./types.js";
+export { IIRTypeUnknown } from "./iir.js";
+export type { IIRVisibility, IIRParam, IIRReturn, IIRExpr, IIRBehaviorClause, IIRConsequence, IIRSideEffect, IIRFailureMode, FunctionIntent, ExtractedFunction, } from "./iir.js";
+export { classifyEffect } from "./effects.js";
+export type { EffectKind, EffectBasis, EffectClassifierInput } from "./effects.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAA;AAC/D,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,qBAAqB,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,WAAW,CAAA;AACvF,OAAO,EACL,IAAI,EACJ,YAAY,EACZ,YAAY,EACZ,cAAc,EACd,WAAW,EACX,YAAY,EACZ,SAAS,EACT,qBAAqB,GACtB,MAAM,WAAW,CAAA;AAClB,YAAY,EACV,UAAU,EACV,QAAQ,EACR,IAAI,EACJ,IAAI,EACJ,QAAQ,EACR,QAAQ,EACR,WAAW,EACX,gBAAgB,EAChB,WAAW,EACX,SAAS,EACT,MAAM,EACN,EAAE,EACF,QAAQ,EACR,WAAW,EACX,UAAU,EACV,cAAc,EACd,eAAe,EACf,kBAAkB,EAClB,cAAc,EACd,kBAAkB,EAClB,cAAc,EACd,gBAAgB,EAChB,WAAW,EACX,SAAS,EACT,cAAc,EACd,WAAW,EACX,cAAc,EACd,OAAO,EACP,WAAW,GACZ,MAAM,YAAY,CAAA;AACnB,OAAO,EAAE,cAAc,EAAE,MAAM,UAAU,CAAA;AACzC,YAAY,EACV,aAAa,EACb,QAAQ,EACR,SAAS,EACT,OAAO,EACP,iBAAiB,EACjB,cAAc,EACd,aAAa,EACb,cAAc,EACd,cAAc,EACd,iBAAiB,GAClB,MAAM,UAAU,CAAA;AACjB,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAC7C,YAAY,EAAE,UAAU,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAA"}

package/dist/index.js

@@ -0,0 +1,244 @@
+// src/define.ts
+function definePlugin(definition) {
+  if (!definition.id || !definition.id.includes(".")) {
+    throw new Error(
+      `Plugin id must be reverse-domain format (e.g., "com.example.my-plugin"). Got: "${definition.id}"`
+    );
+  }
+  if (!definition.name) {
+    throw new Error("Plugin name is required");
+  }
+  if (!definition.version || !isValidSemver(definition.version)) {
+    throw new Error(
+      `Plugin version must be valid semver (e.g., "1.0.0"). Got: "${definition.version}"`
+    );
+  }
+  if (definition.language) {
+    if (typeof definition.language.match !== "function") {
+      throw new Error("language.match must be a function");
+    }
+    if (typeof definition.language.extract !== "function") {
+      throw new Error("language.extract must be a function");
+    }
+    if (definition.language.concepts) {
+      for (const seed of definition.language.concepts) {
+        if (seed.term !== seed.term.toLowerCase()) {
+          throw new Error(`Concept terms must be lowercase. Got: "${seed.term}"`);
+        }
+        if (!seed.term.match(/^[a-z][a-z0-9-]*$/)) {
+          throw new Error(
+            `Concept terms must be lowercase-hyphenated. Got: "${seed.term}"`
+          );
+        }
+      }
+    }
+  }
+  if (definition.tools) {
+    for (const tool of definition.tools) {
+      if (!tool.name) {
+        throw new Error("Tool name is required");
+      }
+      if (!tool.description) {
+        throw new Error(`Tool "${tool.name}" description is required`);
+      }
+      if (tool.description.length > 100) {
+        throw new Error(
+          `Tool "${tool.name}" description exceeds 100 characters (${tool.description.length}). The Strategizer receives this in its prompt \u2014 keep it concise.`
+        );
+      }
+      if (typeof tool.activate !== "function") {
+        throw new Error(`Tool "${tool.name}" activate must be a function`);
+      }
+      if (typeof tool.execute !== "function") {
+        throw new Error(`Tool "${tool.name}" execute must be a function`);
+      }
+    }
+  }
+  if (definition.analyzers) {
+    for (const analyzer of definition.analyzers) {
+      if (!analyzer.name) {
+        throw new Error("Analyzer name is required");
+      }
+      if (typeof analyzer.analyze !== "function") {
+        throw new Error(`Analyzer "${analyzer.name}" analyze must be a function`);
+      }
+    }
+  }
+  if (definition.iirRules) {
+    if (!Array.isArray(definition.iirRules.rules) || definition.iirRules.rules.length === 0) {
+      throw new Error("iirRules.rules must be a non-empty array");
+    }
+    for (const rule of definition.iirRules.rules) {
+      if (!rule.id) {
+        throw new Error("Each IIR rule requires an id");
+      }
+      if (!rule.target || !rule.severity) {
+        throw new Error(`IIR rule "${rule.id}" requires target and severity`);
+      }
+    }
+  }
+  setPluginDefinition(definition);
+  return definition;
+}
+function setPluginDefinition(definition) {
+  const globalScope = globalThis;
+  globalScope.__ce_plugin_definition = definition;
+}
+function isValidSemver(version) {
+  return /^\d+\.\d+\.\d+(-[\w.]+)?(\+[\w.]+)?$/.test(version);
+}
+
+// src/host.ts
+var log = {
+  debug: (message) => __ce_log("debug", message),
+  info: (message) => __ce_log("info", message),
+  warn: (message) => __ce_log("warn", message),
+  error: (message) => __ce_log("error", message)
+};
+function emit(channel, content) {
+  __ce_emit(channel, content);
+}
+function createSubstrateClient() {
+  return {
+    query(q) {
+      const result = __ce_substrate_query(JSON.stringify(q));
+      return JSON.parse(result);
+    }
+  };
+}
+function getConfig(key) {
+  const result = __ce_get_config(key);
+  if (!result)
+    return void 0;
+  return JSON.parse(result);
+}
+function nodeID(projectID, type, canonicalID) {
+  return __ce_node_id(projectID, type, canonicalID);
+}
+function edgeID(sourceID, type, targetID) {
+  return __ce_edge_id(sourceID, type, targetID);
+}
+
+// src/tree.ts
+function kids(node) {
+  return node.children ?? [];
+}
+function walk(node, visit) {
+  if (!node)
+    return;
+  const stack = [node];
+  while (stack.length > 0) {
+    const n = stack.pop();
+    visit(n);
+    const cs = kids(n);
+    for (let i = cs.length - 1; i >= 0; i--)
+      stack.push(cs[i]);
+  }
+}
+function walkTopLevel(node, visit) {
+  if (!node)
+    return;
+  const stack = [{ n: node, descend: true }];
+  while (stack.length > 0) {
+    const { n, descend } = stack.pop();
+    visit(n);
+    if (!descend)
+      continue;
+    const cs = kids(n);
+    for (let i = cs.length - 1; i >= 0; i--) {
+      stack.push({ n: cs[i], descend: !SCOPE_BOUNDARY.has(cs[i].type) });
+    }
+  }
+}
+var SCOPE_BOUNDARY = /* @__PURE__ */ new Set([
+  "function_declaration",
+  "function_expression",
+  "arrow_function",
+  "method_definition",
+  "generator_function",
+  "generator_function_declaration"
+]);
+function childByField(node, field) {
+  for (const child of kids(node)) {
+    if (child.fieldName === field)
+      return child;
+  }
+  return null;
+}
+function childrenByType(node, type) {
+  return kids(node).filter((c) => c.type === type);
+}
+function firstByType(node, type) {
+  return kids(node).find((c) => c.type === type) ?? null;
+}
+function hasChildType(node, type) {
+  return kids(node).some((c) => c.type === type);
+}
+function fieldText(node, field) {
+  return childByField(node, field)?.text ?? "";
+}
+function firstDescendantByType(node, type) {
+  let found = null;
+  walk(node, (n) => {
+    if (found === null && n.type === type)
+      found = n;
+  });
+  return found;
+}
+
+// src/iir.ts
+var IIRTypeUnknown = "unknown";
+
+// src/effects.ts
+var pathCategories = [
+  ["network", ["net/http", "net/url", "net", "google.golang.org/grpc", "github.com/gorilla/websocket"]],
+  ["db", ["database/sql", "gorm.io", "go.mongodb.org", "github.com/redis", "github.com/jmoiron/sqlx"]],
+  ["io", ["os", "io", "io/ioutil", "bufio", "path/filepath"]],
+  // fmt's pure formatters (Sprintf, Errorf) are excluded before classification;
+  // what reaches here (Println/Printf/Fprint…) writes output.
+  ["log", ["log", "log/slog", "fmt"]]
+];
+var rootCategories = [
+  ["network", ["http", "https", "fetch", "axios", "request", "requests", "grpc", "ws", "socket", "urllib"]],
+  ["db", ["db", "sql", "database", "redis", "mongo", "session", "repository", "datastore"]],
+  ["io", ["os", "io", "fs", "ioutil", "file", "pathlib"]],
+  ["log", ["log", "logger", "logging", "console", "slog", "fmt"]]
+];
+var mutationVerbs = ["track", "send", "emit", "publish", "save", "create", "update", "delete", "write"];
+function classifyEffect(input) {
+  const path = (input.importPath ?? "").toLowerCase();
+  const root = (input.root ?? "").toLowerCase();
+  const method = (input.method ?? "").toLowerCase();
+  for (const [kind, prefixes] of pathCategories) {
+    if (prefixes.some((p) => path === p || path.startsWith(p + "/")))
+      return { kind, basis: "resolved" };
+  }
+  for (const [kind, roots] of rootCategories) {
+    if (roots.includes(root))
+      return { kind, basis: "resolved" };
+  }
+  if (mutationVerbs.some((v) => method.includes(v)))
+    return { kind: "mutation", basis: "heuristic" };
+  return { kind: "unclassified", basis: "heuristic" };
+}
+export {
+  IIRTypeUnknown,
+  childByField,
+  childrenByType,
+  classifyEffect,
+  createSubstrateClient,
+  definePlugin,
+  edgeID,
+  emit,
+  fieldText,
+  firstByType,
+  firstDescendantByType,
+  getConfig,
+  hasChildType,
+  log,
+  nodeID,
+  setPluginDefinition,
+  walk,
+  walkTopLevel
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/define.ts", "../src/host.ts", "../src/tree.ts", "../src/iir.ts", "../src/effects.ts"],
+  "sourcesContent": ["import type { PluginDefinition } from \"./types.js\"\n\n/**\n * definePlugin is the single entry point for all plugin authors.\n *\n * Usage:\n *   import { definePlugin } from \"@atheory-ai/ce-plugin-sdk\"\n *\n *   export default definePlugin({\n *     id: \"com.example.my-plugin\",\n *     name: \"My Plugin\",\n *     version: \"1.0.0\",\n *     language: { match, extract, concepts },\n *     tools: [{ name, description, activate, execute }],\n *   })\n */\nexport function definePlugin(definition: PluginDefinition): PluginDefinition {\n  if (!definition.id || !definition.id.includes(\".\")) {\n    throw new Error(\n      `Plugin id must be reverse-domain format (e.g., \"com.example.my-plugin\"). Got: \"${definition.id}\"`\n    )\n  }\n\n  if (!definition.name) {\n    throw new Error(\"Plugin name is required\")\n  }\n\n  if (!definition.version || !isValidSemver(definition.version)) {\n    throw new Error(\n      `Plugin version must be valid semver (e.g., \"1.0.0\"). Got: \"${definition.version}\"`\n    )\n  }\n\n  if (definition.language) {\n    if (typeof definition.language.match !== \"function\") {\n      throw new Error(\"language.match must be a function\")\n    }\n    if (typeof definition.language.extract !== \"function\") {\n      throw new Error(\"language.extract must be a function\")\n    }\n    if (definition.language.concepts) {\n      for (const seed of definition.language.concepts) {\n        if (seed.term !== seed.term.toLowerCase()) {\n          throw new Error(`Concept terms must be lowercase. Got: \"${seed.term}\"`)\n        }\n        if (!seed.term.match(/^[a-z][a-z0-9-]*$/)) {\n          throw new Error(\n            `Concept terms must be lowercase-hyphenated. Got: \"${seed.term}\"`\n          )\n        }\n      }\n    }\n  }\n\n  if (definition.tools) {\n    for (const tool of definition.tools) {\n      if (!tool.name) {\n        throw new Error(\"Tool name is required\")\n      }\n      if (!tool.description) {\n        throw new Error(`Tool \"${tool.name}\" description is required`)\n      }\n      if (tool.description.length > 100) {\n        throw new Error(\n          `Tool \"${tool.name}\" description exceeds 100 characters (${tool.description.length}). ` +\n          `The Strategizer receives this in its prompt \u2014 keep it concise.`\n        )\n      }\n      if (typeof tool.activate !== \"function\") {\n        throw new Error(`Tool \"${tool.name}\" activate must be a function`)\n      }\n      if (typeof tool.execute !== \"function\") {\n        throw new Error(`Tool \"${tool.name}\" execute must be a function`)\n      }\n    }\n  }\n\n  if (definition.analyzers) {\n    for (const analyzer of definition.analyzers) {\n      if (!analyzer.name) {\n        throw new Error(\"Analyzer name is required\")\n      }\n      if (typeof analyzer.analyze !== \"function\") {\n        throw new Error(`Analyzer \"${analyzer.name}\" analyze must be a function`)\n      }\n    }\n  }\n\n  if (definition.iirRules) {\n    // The host is the authoritative validator (internal/iir). Keep this to a\n    // shape sanity check so an obvious mistake fails at author time rather than\n    // silently shipping an empty pack.\n    if (!Array.isArray(definition.iirRules.rules) || definition.iirRules.rules.length === 0) {\n      throw new Error(\"iirRules.rules must be a non-empty array\")\n    }\n    for (const rule of definition.iirRules.rules) {\n      if (!rule.id) {\n        throw new Error(\"Each IIR rule requires an id\")\n      }\n      if (!rule.target || !rule.severity) {\n        throw new Error(`IIR rule \"${rule.id}\" requires target and severity`)\n      }\n    }\n  }\n\n  setPluginDefinition(definition)\n  return definition\n}\n\nexport function setPluginDefinition(definition: PluginDefinition): void {\n  const globalScope = globalThis as typeof globalThis & {\n    __ce_plugin_definition?: PluginDefinition\n  }\n  globalScope.__ce_plugin_definition = definition\n}\n\nfunction isValidSemver(version: string): boolean {\n  return /^\\d+\\.\\d+\\.\\d+(-[\\w.]+)?(\\+[\\w.]+)?$/.test(version)\n}\n", "import type { SubstrateQuery, Node, SubstrateClient, NodeType, EdgeType } from \"./types.js\"\n\n/**\n * Low-level host function declarations.\n * These are provided by the engine's wazero runtime.\n */\ndeclare function __ce_log(level: string, message: string): void\ndeclare function __ce_emit(channel: string, content: string): void\ndeclare function __ce_substrate_query(queryJSON: string): string\ndeclare function __ce_get_config(key: string): string\ndeclare function __ce_node_id(projectID: string, type: string, canonicalID: string): string\ndeclare function __ce_edge_id(sourceID: string, type: string, targetID: string): string\n\n// \u2500\u2500 Logging \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\nexport const log = {\n  debug: (message: string) => __ce_log(\"debug\", message),\n  info:  (message: string) => __ce_log(\"info\",  message),\n  warn:  (message: string) => __ce_log(\"warn\",  message),\n  error: (message: string) => __ce_log(\"error\", message),\n}\n\n// \u2500\u2500 Emit \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\nexport function emit(channel: \"thinking\" | \"action\" | \"debug\" | \"warning\", content: string): void {\n  __ce_emit(channel, content)\n}\n\n// \u2500\u2500 Substrate \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\nexport function createSubstrateClient(): SubstrateClient {\n  return {\n    query(q: SubstrateQuery): Node[] {\n      const result = __ce_substrate_query(JSON.stringify(q))\n      return JSON.parse(result) as Node[]\n    }\n  }\n}\n\n// \u2500\u2500 Config \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\nexport function getConfig<T = unknown>(key: string): T | undefined {\n  const result = __ce_get_config(key)\n  if (!result) return undefined\n  return JSON.parse(result) as T\n}\n\n// \u2500\u2500 ID generation \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\nexport function nodeID(projectID: string, type: NodeType, canonicalID: string): string {\n  return __ce_node_id(projectID, type as string, canonicalID)\n}\n\nexport function edgeID(sourceID: string, type: EdgeType, targetID: string): string {\n  return __ce_edge_id(sourceID, type as string, targetID)\n}\n", "// CST-walking helpers for language extractors. The host hands plugins a parsed\n// tree-sitter tree (SyntaxNode); these make walking it ergonomic so extractors\n// never fall back to regex.\n\nimport type { SyntaxNode } from \"./types.js\"\n\n// The host omits `children` on leaf nodes (serialized as null), so every access\n// goes through this \u2014 helpers must never assume `children` is an array.\nfunction kids(node: SyntaxNode): SyntaxNode[] {\n  return node.children ?? []\n}\n\n/**\n * walk visits node and every descendant in pre-order. Iterative (explicit\n * stack) so a deeply nested CST \u2014 long expression chains, minified/generated\n * code \u2014 cannot overflow the call stack.\n */\nexport function walk(node: SyntaxNode | null, visit: (n: SyntaxNode) => void): void {\n  if (!node) return\n  const stack: SyntaxNode[] = [node]\n  while (stack.length > 0) {\n    const n = stack.pop()!\n    visit(n)\n    const cs = kids(n)\n    for (let i = cs.length - 1; i >= 0; i--) stack.push(cs[i]) // reversed \u2192 pop in order\n  }\n}\n\n/**\n * walkTopLevel visits node and its descendants, but does NOT descend into\n * nested function/closure scopes \u2014 a boundary node itself is visited, its body\n * is not. Use it to collect a scope's own declarations without pulling in ones\n * nested inside inner functions.\n */\nexport function walkTopLevel(node: SyntaxNode | null, visit: (n: SyntaxNode) => void): void {\n  if (!node) return\n  // Stack entries carry whether to descend into that node's children \u2014 a\n  // boundary node is visited but its subtree is not walked. Iterative to avoid\n  // call-stack overflow on deep trees.\n  const stack: Array<{ n: SyntaxNode; descend: boolean }> = [{ n: node, descend: true }]\n  while (stack.length > 0) {\n    const { n, descend } = stack.pop()!\n    visit(n)\n    if (!descend) continue\n    const cs = kids(n)\n    for (let i = cs.length - 1; i >= 0; i--) {\n      stack.push({ n: cs[i], descend: !SCOPE_BOUNDARY.has(cs[i].type) })\n    }\n  }\n}\n\nconst SCOPE_BOUNDARY = new Set([\n  \"function_declaration\",\n  \"function_expression\",\n  \"arrow_function\",\n  \"method_definition\",\n  \"generator_function\",\n  \"generator_function_declaration\",\n])\n\n/** childByField returns the child occupying the given field, or null. */\nexport function childByField(node: SyntaxNode, field: string): SyntaxNode | null {\n  for (const child of kids(node)) {\n    if (child.fieldName === field) return child\n  }\n  return null\n}\n\n/** childrenByType returns direct children of a given type. */\nexport function childrenByType(node: SyntaxNode, type: string): SyntaxNode[] {\n  return kids(node).filter(c => c.type === type)\n}\n\n/** firstByType returns the first direct child of a given type, or null. */\nexport function firstByType(node: SyntaxNode, type: string): SyntaxNode | null {\n  return kids(node).find(c => c.type === type) ?? null\n}\n\n/** hasChildType reports whether node has a direct child (named or token) of the given type. */\nexport function hasChildType(node: SyntaxNode, type: string): boolean {\n  return kids(node).some(c => c.type === type)\n}\n\n/** fieldText returns the text of the child in the given field, or \"\". */\nexport function fieldText(node: SyntaxNode, field: string): string {\n  return childByField(node, field)?.text ?? \"\"\n}\n\n/** firstDescendantByType returns the first descendant of a given type (pre-order), or null. */\nexport function firstDescendantByType(node: SyntaxNode, type: string): SyntaxNode | null {\n  let found: SyntaxNode | null = null\n  walk(node, n => {\n    if (found === null && n.type === type) found = n\n  })\n  return found\n}\n", "// The IIR (Intermediate Intent Representation) model, mirrored from Context\n// Engine's internal/iir. A language plugin may *lift* source into these types\n// during extraction; the host validates and stores them (it remains the\n// authoritative parser \u2014 these are the authoring/contract surface). Field names\n// match the host's JSON tags so a host-side ParseIntentJSON accepts them.\n\nexport type IIRVisibility = \"public\" | \"private\"\n\n// TypeUnknown marks a parameter type that could not be determined from source \u2014\n// represented explicitly rather than dropped, so comparison can tell \"unknown\"\n// from \"absent\".\nexport const IIRTypeUnknown = \"unknown\"\n\nexport interface IIRParam {\n  name: string\n  type: string\n}\n\nexport interface IIRReturn {\n  // Empty string means the return type was absent in source (distinct from the\n  // explicit type \"void\").\n  type:     string\n  explicit: boolean\n}\n\n// IIRExpr is a normalized condition expression node (mirrors iir.Expr): `op`\n// names the node (\"<\", \"&&\", \"!\", \"path\", \"lit\"), `args` are operands in source\n// order, `text` carries a leaf payload (a literal value or a dotted access path).\nexport interface IIRExpr {\n  op:    string\n  args?: IIRExpr[]\n  text?: string\n}\n\n/**\n * A normalized behavior consequence \u2014 the `then` action of a clause, structured\n * just enough to compare across languages. `op` is the action: \"return\", \"throw\"\n * (Go panic / JS-TS throw / Python raise, folded), or \"invoke\" (a call). `value`\n * is an opaque canonical payload (the returned expression, the thrown failure's\n * identity, or the invoked callee), omitted when the action carries none.\n */\nexport interface IIRConsequence {\n  op:     \"return\" | \"throw\" | \"invoke\"\n  value?: string\n}\n\nexport interface IIRBehaviorClause {\n  when:      string\n  then:      string\n  whenExpr?: IIRExpr\n  thenExpr?: IIRConsequence\n}\n\n/**\n * An observable side effect. Either a bare name (\"analytics.track\") or an object\n * carrying an optional kind (network | db | io | log | mutation | unclassified)\n * and basis \u2014 \"resolved\" when the kind came from a known effectful API (an\n * import path or recognized client), \"heuristic\" when it was guessed from a\n * method-name verb. The host accepts both forms; a plugin that can categorize an\n * effect emits the object form, otherwise a bare string.\n */\nexport type IIRSideEffect = string | {\n  name:  string\n  kind?: \"network\" | \"db\" | \"io\" | \"log\" | \"mutation\" | \"unclassified\"\n  basis?: \"resolved\" | \"heuristic\"\n}\n\n/**\n * An expected failure outcome. Either a bare code (\"amount_below_minimum\") or an\n * object carrying an optional kind and source. The kind names *how* the function\n * signals the failure: \"constructed\" (created inline, e.g. throw new Error(\"msg\")\n * / errors.New), \"sentinel\" (a named error value/type, e.g. ErrClosed or a custom\n * error class), or \"propagated\" (an upstream failure forwarded on \u2014 a re-throw or\n * `return nil, err`). For a propagated failure, `source` names the forwarded\n * identifier. The host accepts both forms; a code-only failure round-trips as a\n * bare string.\n */\nexport type IIRFailureMode = string | {\n  code:    string\n  kind?:   \"constructed\" | \"sentinel\" | \"propagated\"\n  source?: string\n}\n\nexport interface FunctionIntent {\n  kind:         \"FunctionIntent\"\n  name:         string\n  language:     string\n  /**\n   * The epistemic layer this intent comes from. A plugin lift emits \"observed\"\n   * (ground truth about what the code does); a hand-authored spec is \"declared\";\n   * the shaper emits \"inferred\". The host defaults an absent origin to declared.\n   */\n  origin?:      \"observed\" | \"declared\" | \"inferred\"\n  visibility?:  IIRVisibility\n  inputs:       IIRParam[]\n  returns:      IIRReturn\n  behavior:     IIRBehaviorClause[]\n  sideEffects:  IIRSideEffect[]\n  failureModes: IIRFailureMode[]\n  constraints:  string[]\n}\n\n// ExtractedFunction pairs a lifted FunctionIntent with the id of the symbol node\n// it was lifted from. The plugin knows this id directly (it created the node),\n// so the host can attach the IIR to the exact node without the (name,start_byte)\n// correlation the Go-side lift needs.\nexport interface ExtractedFunction {\n  nodeId: string\n  intent: FunctionIntent\n}\n", "// Shared side-effect classifier for language plugins. Given the structured parts\n// of a detected call \u2014 the receiver root, the method, and (when the root is an\n// imported package) its full import path \u2014 it returns the effect kind and a\n// confidence. Plugins emit these on each SideEffect so the host doesn't have to\n// re-derive them from the name string at compare time.\n//\n// Matching is structural (exact root, method substring, import-path prefix)\n// rather than substring-on-the-whole-name, which avoids false hits like\n// \"catalog.save\" being read as a log effect because the name contains \"log\".\n\nexport type EffectKind = \"network\" | \"db\" | \"io\" | \"log\" | \"mutation\" | \"unclassified\"\n// How an effect's kind was established. \"resolved\" means it matched a known\n// effectful API (an import path or a recognized client root) \u2014 deterministic\n// knowledge, not a probabilistic guess. \"heuristic\" means it was inferred from a\n// method-name verb or is uncategorized. The comparator treats an undeclared\n// resolved effect as an error and an undeclared heuristic one as a warning: it\n// should not fail verification on a guess.\nexport type EffectBasis = \"resolved\" | \"heuristic\"\n\nexport interface EffectClassifierInput {\n  /** The called method / function name, e.g. \"Get\", \"track\". */\n  method?: string\n  /** The receiver root, e.g. \"http\", \"analytics\". */\n  root?: string\n  /** Full import path of the root when it is an imported package, e.g. \"net/http\". */\n  importPath?: string\n}\n\n// Import-path prefixes are the strongest signal (a real, categorizable package).\nconst pathCategories: [EffectKind, string[]][] = [\n  [\"network\", [\"net/http\", \"net/url\", \"net\", \"google.golang.org/grpc\", \"github.com/gorilla/websocket\"]],\n  [\"db\", [\"database/sql\", \"gorm.io\", \"go.mongodb.org\", \"github.com/redis\", \"github.com/jmoiron/sqlx\"]],\n  [\"io\", [\"os\", \"io\", \"io/ioutil\", \"bufio\", \"path/filepath\"]],\n  // fmt's pure formatters (Sprintf, Errorf) are excluded before classification;\n  // what reaches here (Println/Printf/Fprint\u2026) writes output.\n  [\"log\", [\"log\", \"log/slog\", \"fmt\"]],\n]\n\n// Receiver roots that categorize a call even without a resolved import path\n// (e.g. member calls on a well-known client name).\nconst rootCategories: [EffectKind, string[]][] = [\n  [\"network\", [\"http\", \"https\", \"fetch\", \"axios\", \"request\", \"requests\", \"grpc\", \"ws\", \"socket\", \"urllib\"]],\n  [\"db\", [\"db\", \"sql\", \"database\", \"redis\", \"mongo\", \"session\", \"repository\", \"datastore\"]],\n  [\"io\", [\"os\", \"io\", \"fs\", \"ioutil\", \"file\", \"pathlib\"]],\n  [\"log\", [\"log\", \"logger\", \"logging\", \"console\", \"slog\", \"fmt\"]],\n]\n\n// Method names that signal an observable mutation/effect.\nconst mutationVerbs = [\"track\", \"send\", \"emit\", \"publish\", \"save\", \"create\", \"update\", \"delete\", \"write\"]\n\n/**\n * classifyEffect returns the (kind, basis) for a detected effectful call. A call\n * matched against a known effectful API \u2014 by import path or a recognized client\n * root \u2014 is \"resolved\" (deterministic). A call categorized only from a\n * method-name verb, or left uncategorized, is \"heuristic\" (a guess).\n */\nexport function classifyEffect(input: EffectClassifierInput): { kind: EffectKind; basis: EffectBasis } {\n  const path = (input.importPath ?? \"\").toLowerCase()\n  const root = (input.root ?? \"\").toLowerCase()\n  const method = (input.method ?? \"\").toLowerCase()\n\n  for (const [kind, prefixes] of pathCategories) {\n    if (prefixes.some(p => path === p || path.startsWith(p + \"/\"))) return { kind, basis: \"resolved\" }\n  }\n  for (const [kind, roots] of rootCategories) {\n    if (roots.includes(root)) return { kind, basis: \"resolved\" }\n  }\n  if (mutationVerbs.some(v => method.includes(v))) return { kind: \"mutation\", basis: \"heuristic\" }\n  return { kind: \"unclassified\", basis: \"heuristic\" }\n}\n"],
+  "mappings": "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",
+  "names": []
+}