@atheory-ai/ce-plugin-sdk 0.1.0

package/dist/tree.d.ts

@@ -0,0 +1,27 @@
+import type { SyntaxNode } from "./types.js";
+/**
+ * walk visits node and every descendant in pre-order. Iterative (explicit
+ * stack) so a deeply nested CST — long expression chains, minified/generated
+ * code — cannot overflow the call stack.
+ */
+export declare function walk(node: SyntaxNode | null, visit: (n: SyntaxNode) => void): void;
+/**
+ * walkTopLevel visits node and its descendants, but does NOT descend into
+ * nested function/closure scopes — a boundary node itself is visited, its body
+ * is not. Use it to collect a scope's own declarations without pulling in ones
+ * nested inside inner functions.
+ */
+export declare function walkTopLevel(node: SyntaxNode | null, visit: (n: SyntaxNode) => void): void;
+/** childByField returns the child occupying the given field, or null. */
+export declare function childByField(node: SyntaxNode, field: string): SyntaxNode | null;
+/** childrenByType returns direct children of a given type. */
+export declare function childrenByType(node: SyntaxNode, type: string): SyntaxNode[];
+/** firstByType returns the first direct child of a given type, or null. */
+export declare function firstByType(node: SyntaxNode, type: string): SyntaxNode | null;
+/** hasChildType reports whether node has a direct child (named or token) of the given type. */
+export declare function hasChildType(node: SyntaxNode, type: string): boolean;
+/** fieldText returns the text of the child in the given field, or "". */
+export declare function fieldText(node: SyntaxNode, field: string): string;
+/** firstDescendantByType returns the first descendant of a given type (pre-order), or null. */
+export declare function firstDescendantByType(node: SyntaxNode, type: string): SyntaxNode | null;
+//# sourceMappingURL=tree.d.ts.map

package/dist/tree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree.d.ts","sourceRoot":"","sources":["../src/tree.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAQ5C;;;;GAIG;AACH,wBAAgB,IAAI,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,EAAE,UAAU,KAAK,IAAI,GAAG,IAAI,CASlF;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,EAAE,UAAU,KAAK,IAAI,GAAG,IAAI,CAe1F;AAWD,yEAAyE;AACzE,wBAAgB,YAAY,CAAC,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAK/E;AAED,8DAA8D;AAC9D,wBAAgB,cAAc,CAAC,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,GAAG,UAAU,EAAE,CAE3E;AAED,2EAA2E;AAC3E,wBAAgB,WAAW,CAAC,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAE7E;AAED,+FAA+F;AAC/F,wBAAgB,YAAY,CAAC,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAEpE;AAED,yEAAyE;AACzE,wBAAgB,SAAS,CAAC,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAEjE;AAED,+FAA+F;AAC/F,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAMvF"}

package/dist/types.d.ts

@@ -0,0 +1,175 @@
+import type { ExtractedFunction } from "./iir.js";
+export type NodeType = "symbol" | "namespace" | "concept" | "file" | "directory" | string;
+export type EdgeType = "calls" | "imports" | "implements" | "extends" | "contains" | "references" | "defines" | "belongs_to" | "synonym_of" | "co_activates" | "annotates" | string;
+export type SourceClass = "structural" | "associative" | "speculative" | "derived";
+export interface Node {
+    id: string;
+    type: NodeType;
+    label: string;
+    canonicalID: string;
+    sourceClass: SourceClass;
+    properties: Record<string, unknown>;
+}
+export interface Edge {
+    id: string;
+    sourceID: string;
+    targetID: string;
+    type: EdgeType;
+    sourceClass: SourceClass;
+    properties: Record<string, unknown>;
+}
+export interface ExtractionResult {
+    nodes: Node[];
+    edges: Edge[];
+    iir?: ExtractedFunction[];
+}
+export interface Position {
+    row: number;
+    column: number;
+}
+export interface SyntaxNode {
+    /** tree-sitter node type, e.g. "function_declaration", "identifier". */
+    type: string;
+    /** true for grammar-named nodes, false for anonymous tokens ("(", "async"). */
+    isNamed: boolean;
+    /** the field this node occupies in its parent, e.g. "name", "body"; null if none. */
+    fieldName: string | null;
+    /** source text spanned by this node. */
+    text: string;
+    startByte: number;
+    endByte: number;
+    startPosition: Position;
+    endPosition: Position;
+    /** child nodes; absent (null) on leaf nodes — use the SDK's tree helpers, which tolerate this. */
+    children: SyntaxNode[] | null;
+}
+export interface ConceptSeed {
+    term: string;
+    definition?: string;
+    related?: string[];
+    synonyms?: string[];
+}
+export interface AnchorRef {
+    type: "symbol" | "namespace" | "concept" | "file";
+    id: string;
+    confidence: "high" | "medium" | "low";
+}
+export interface Anchor {
+    ref: AnchorRef;
+    node?: Node;
+    edges: Edge[];
+    activation: number;
+}
+export interface IR {
+    mode: "thinking" | "direct" | "audit";
+    anchors: AnchorRef[];
+    predicates: Record<string, string>;
+    openQueries: string[];
+    maxLoops: number;
+    kLimit: number;
+    roleHint: string;
+    modelTier: string;
+}
+export interface Emission {
+    channel: "thinking" | "action" | "debug" | "warning";
+    content: string;
+    metadata?: Record<string, unknown>;
+}
+export interface ToolRequest {
+    runID: string;
+    turnID: string;
+    loopIndex: number;
+    ir: IR;
+    anchors: Anchor[];
+}
+export interface ToolResult {
+    emissions: Emission[];
+    proposedNodes: Node[];
+    proposedEdges: Edge[];
+}
+export interface SubstrateQuery {
+    projectID: string;
+    nodeTypes?: NodeType[];
+    minActivation?: number;
+    properties?: Record<string, string>;
+    limit?: number;
+}
+export interface LanguageDefinition {
+    match: (filePath: string) => boolean;
+    /**
+     * File extensions (with leading dot, e.g. [".ex", ".exs"]) this language
+     * covers. Used by the host to route those files to `grammar` for parsing.
+     * Optional — omit when relying on a host built-in grammar.
+     */
+    extensions?: string[];
+    /**
+     * Path to a tree-sitter grammar WASM (relative to the plugin .wasm), letting a
+     * plugin add a language the host doesn't bundle. The host loads it at runtime
+     * for the declared `extensions`. Optional — omit to use a host built-in.
+     */
+    grammar?: string;
+    /**
+     * Turn a file into graph nodes/edges. `tree` is the host's parsed CST — walk
+     * it rather than matching raw text. It is null only when no grammar is
+     * available for the file (rare); for grammared languages it is always present.
+     */
+    extract: (filePath: string, content: string, tree: SyntaxNode | null) => ExtractionResult;
+    concepts?: ConceptSeed[];
+}
+export interface RoleDefinition {
+    name: string;
+    systemPrompt: string;
+    tools?: string[];
+}
+export interface AnalyzerDefinition {
+    name: string;
+    description: string;
+    analyze: (nodes: Node[]) => Edge[];
+}
+export interface SubstrateClient {
+    query: (q: SubstrateQuery) => Node[];
+}
+export interface ToolDefinition {
+    name: string;
+    description: string;
+    activationHint?: string;
+    activate: (ir: IR) => boolean;
+    execute: (request: ToolRequest, substrate: SubstrateClient) => ToolResult;
+}
+export type IIRSeverity = "error" | "warning" | "info";
+export type IIRTarget = "FunctionIntent";
+export interface IIRExprPattern {
+    ops?: string[];
+    operandLiteral?: string;
+}
+export interface IIRRuleWhen {
+    visibility?: "public" | "private";
+    hasFailureModes?: boolean;
+}
+export interface IIRRuleRequire {
+    explicitReturnType?: boolean;
+    sideEffectsDeclared?: boolean;
+    failureStrategy?: string;
+    forbidConditionShape?: IIRExprPattern;
+}
+export interface IIRRule {
+    id: string;
+    target: IIRTarget;
+    severity: IIRSeverity;
+    when?: IIRRuleWhen;
+    require?: IIRRuleRequire;
+}
+export interface IIRRulePack {
+    rules: IIRRule[];
+}
+export interface PluginDefinition {
+    id: string;
+    name: string;
+    version: string;
+    language?: LanguageDefinition;
+    role?: RoleDefinition;
+    analyzers?: AnalyzerDefinition[];
+    tools?: ToolDefinition[];
+    iirRules?: IIRRulePack;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,84 @@
+{
+  "name": "@atheory-ai/ce-plugin-sdk",
+  "version": "0.1.0",
+  "description": "TypeScript SDK for authoring Context Engine plugins.",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs",
+      "types": "./dist/index.d.ts"
+    },
+    "./abi": {
+      "import": "./dist/abi.js",
+      "types": "./dist/abi.d.ts"
+    },
+    "./build/abi": {
+      "import": "./dist/build/ce-abi.js",
+      "types": "./dist/build/ce-abi.d.ts"
+    },
+    "./eslint-plugin-ce": {
+      "import": "./dist/eslint/index.js",
+      "types": "./dist/eslint/index.d.ts"
+    },
+    "./tsconfig.plugin.json": {
+      "default": "./tsconfig.plugin.json"
+    }
+  },
+  "peerDependencies": {
+    "@atheory-ai/wasm-plugin-toolkit": "^0.0.4",
+    "eslint": "^8.57.0 || ^9.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@atheory-ai/wasm-plugin-toolkit": {
+      "optional": true
+    },
+    "eslint": {
+      "optional": true
+    }
+  },
+  "files": [
+    "dist",
+    "tsconfig.plugin.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "devDependencies": {
+    "@types/eslint": "^9.6.1",
+    "typescript": "*",
+    "esbuild": "*",
+    "vitest": "*"
+  },
+  "license": "Apache-2.0",
+  "engines": {
+    "node": ">=20"
+  },
+  "homepage": "https://github.com/atheory-ai/context-engine/tree/main/sdk#readme",
+  "bugs": {
+    "url": "https://github.com/atheory-ai/context-engine/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/atheory-ai/context-engine.git",
+    "directory": "sdk/packages/plugin-sdk"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "context-engine",
+    "plugin-sdk",
+    "wasm",
+    "webassembly",
+    "semantic-code"
+  ],
+  "scripts": {
+    "build": "node build.mjs && tsc --emitDeclarationOnly --declaration --declarationMap",
+    "test": "vitest run --passWithNoTests",
+    "lint": "eslint src build.mjs --ext .ts,.js,.mjs",
+    "clean": "rm -rf dist"
+  }
+}

package/tsconfig.plugin.json

@@ -0,0 +1,7 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "lib":   ["ES2020"],
+    "types": []
+  }
+}