@sigil-engine/core 0.1.0

package/src/plugin.ts

@@ -0,0 +1,186 @@
+/**
+ * Sigil Plugin System — the extensibility contract.
+ *
+ * Every language parser implements `ExtractorPlugin`. The core engine
+ * discovers registered plugins and orchestrates them.
+ *
+ * To add Python support:
+ *   1. Create @sigil-engine/parser-python
+ *   2. Implement ExtractorPlugin
+ *   3. Export a default plugin instance
+ *   4. Users install it — Sigil discovers it automatically
+ */
+
+import type { ContextDocument } from "./schema.js";
+
+// ---------------------------------------------------------------------------
+// Plugin interface
+// ---------------------------------------------------------------------------
+
+/**
+ * The parsed project representation passed to plugins.
+ * Language-agnostic — each plugin casts or wraps this with its own type.
+ */
+export interface ParsedProject {
+  /** Absolute path to the project root */
+  projectPath: string;
+  /** List of source file paths (absolute) */
+  sourceFiles: string[];
+  /** Package manifest (package.json, pyproject.toml, etc.) parsed as object */
+  manifest?: Record<string, unknown>;
+}
+
+/**
+ * Result returned by a plugin's extract method.
+ * Partial<ContextDocument> — plugins only fill what they understand.
+ */
+export type ExtractResult = Partial<Omit<ContextDocument, "version" | "project" | "_extraction">>;
+
+/**
+ * The core plugin contract. Every language parser implements this.
+ */
+export interface ExtractorPlugin {
+  /** Unique plugin name (e.g., "typescript", "python", "go") */
+  name: string;
+
+  /** Semver version of the plugin */
+  version: string;
+
+  /** Languages/frameworks this plugin handles */
+  languages: string[];
+
+  /**
+   * Check if this plugin should run for the given project.
+   * Called before extract() — return false to skip.
+   *
+   * Example: typescript plugin checks for tsconfig.json or .ts files
+   */
+  detect(projectPath: string): boolean | Promise<boolean>;
+
+  /**
+   * Initialize the plugin for a specific project.
+   * Returns a ParsedProject (or plugin-specific extension of it).
+   * Called once before extract().
+   */
+  init(projectPath: string): ParsedProject | Promise<ParsedProject>;
+
+  /**
+   * Extract context from the project.
+   * Returns partial context — the orchestrator merges results from all plugins.
+   */
+  extract(project: ParsedProject): ExtractResult | Promise<ExtractResult>;
+
+  /**
+   * Optional: handle apply intents for elements this plugin created.
+   * Called by the apply engine when an intent targets a _meta.tags
+   * value owned by this plugin.
+   */
+  apply?(intent: ApplyIntent, projectPath: string): ApplyResult | Promise<ApplyResult>;
+}
+
+// ---------------------------------------------------------------------------
+// Apply types (used by plugins that support apply)
+// ---------------------------------------------------------------------------
+
+export type IntentType =
+  | "AddEntity"
+  | "RemoveEntity"
+  | "AddField"
+  | "RemoveField"
+  | "ModifyField"
+  | "RenameSymbol"
+  | "AddComponent"
+  | "RemoveComponent"
+  | "AddRoute"
+  | "RemoveRoute"
+  | "AddMethod"
+  | "RemoveMethod"
+  | "ModifyProps"
+  | "ChangeSignature"
+  | "MoveFile"
+  | "AddDependency"
+  | "RemoveDependency";
+
+export type IntentConfidence = "deterministic" | "needs-ai";
+
+export interface ApplyIntent {
+  type: IntentType;
+  confidence: IntentConfidence;
+  target_file?: string;
+  target_symbol?: string;
+  description: string;
+  old_value?: unknown;
+  new_value?: unknown;
+  priority: number;
+}
+
+export interface ApplyResult {
+  intent: ApplyIntent;
+  success: boolean;
+  error?: string;
+  files_created: string[];
+  files_modified: string[];
+  preview?: string;
+  code?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Plugin registry
+// ---------------------------------------------------------------------------
+
+const registry: ExtractorPlugin[] = [];
+
+/** Register a plugin with Sigil */
+export function registerPlugin(plugin: ExtractorPlugin): void {
+  // Prevent duplicate registration
+  const existing = registry.findIndex((p) => p.name === plugin.name);
+  if (existing >= 0) {
+    registry[existing] = plugin;
+  } else {
+    registry.push(plugin);
+  }
+}
+
+/** Get all registered plugins */
+export function getPlugins(): readonly ExtractorPlugin[] {
+  return registry;
+}
+
+/** Get plugins that detect support for a given project */
+export async function detectPlugins(projectPath: string): Promise<ExtractorPlugin[]> {
+  const detected: ExtractorPlugin[] = [];
+  for (const plugin of registry) {
+    const supports = await plugin.detect(projectPath);
+    if (supports) {
+      detected.push(plugin);
+    }
+  }
+  return detected;
+}
+
+/** Clear all registered plugins (for testing) */
+export function clearPlugins(): void {
+  registry.length = 0;
+}
+
+// ---------------------------------------------------------------------------
+// Progress reporting
+// ---------------------------------------------------------------------------
+
+export type ProgressPhase =
+  | "init"
+  | "detect"
+  | "extract"
+  | "merge"
+  | "serialize"
+  | "cache"
+  | "done";
+
+export interface ProgressEvent {
+  phase: ProgressPhase;
+  plugin?: string;
+  message: string;
+  elapsed_ms?: number;
+}
+
+export type ProgressCallback = (event: ProgressEvent) => void;

package/src/safety.ts

@@ -0,0 +1,185 @@
+/**
+ * Apply safety mechanisms — git stash before, validation after, rollback on failure.
+ *
+ * SECURITY: All git operations use execFileSync (not execSync) to prevent
+ * shell injection. Destructive operations require explicit confirmation.
+ */
+
+import { execFileSync } from "child_process";
+import { resolve } from "path";
+
+// ---------------------------------------------------------------------------
+// Pre-apply: save state
+// ---------------------------------------------------------------------------
+
+export interface SafetyCheckpoint {
+  hadDirtyFiles: boolean;
+  stashCreated: boolean;
+  originalHead: string;
+}
+
+/**
+ * Callback for confirming destructive operations.
+ * Return true to proceed, false to abort.
+ */
+export type ConfirmCallback = (message: string) => boolean | Promise<boolean>;
+
+/** Default confirmation — always denies (safe default) */
+const denyAll: ConfirmCallback = () => false;
+
+export function preApplySafety(
+  projectPath: string,
+  confirm: ConfirmCallback = denyAll,
+): SafetyCheckpoint {
+  const absPath = resolve(projectPath);
+
+  // Get current HEAD — using execFileSync (no shell)
+  let originalHead = "";
+  try {
+    originalHead = execFileSync("git", ["rev-parse", "HEAD"], {
+      cwd: absPath,
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"],
+    }).trim();
+  } catch {
+    // Not a git repo — skip safety
+    return { hadDirtyFiles: false, stashCreated: false, originalHead: "" };
+  }
+
+  // Check for dirty files
+  let gitStatus = "";
+  try {
+    gitStatus = execFileSync("git", ["status", "--porcelain"], {
+      cwd: absPath,
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"],
+    }).trim();
+  } catch {
+    return { hadDirtyFiles: false, stashCreated: false, originalHead };
+  }
+
+  const hadDirtyFiles = gitStatus.length > 0;
+
+  if (hadDirtyFiles) {
+    try {
+      execFileSync("git", ["stash", "push", "-m", "sigil-pre-apply"], {
+        cwd: absPath,
+        encoding: "utf-8",
+        stdio: ["pipe", "pipe", "pipe"],
+      });
+      return { hadDirtyFiles, stashCreated: true, originalHead };
+    } catch {
+      return { hadDirtyFiles, stashCreated: false, originalHead };
+    }
+  }
+
+  return { hadDirtyFiles, stashCreated: false, originalHead };
+}
+
+// ---------------------------------------------------------------------------
+// Post-apply: validate types
+// ---------------------------------------------------------------------------
+
+export interface ValidationResult {
+  typesOk: boolean;
+  errors: string[];
+}
+
+export function postApplyValidation(projectPath: string): ValidationResult {
+  const absPath = resolve(projectPath);
+
+  try {
+    execFileSync("npx", ["tsc", "--noEmit"], {
+      cwd: absPath,
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"],
+      timeout: 30000,
+    });
+    return { typesOk: true, errors: [] };
+  } catch (err: unknown) {
+    const output =
+      (err as { stdout?: string }).stdout ??
+      (err as { stderr?: string }).stderr ??
+      "";
+    const errors = output
+      .split("\n")
+      .filter((line) => line.includes("error TS"))
+      .slice(0, 10);
+    return { typesOk: false, errors };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Rollback
+// ---------------------------------------------------------------------------
+
+export async function rollbackApply(
+  projectPath: string,
+  checkpoint: SafetyCheckpoint,
+  confirm: ConfirmCallback = denyAll,
+): Promise<boolean> {
+  const absPath = resolve(projectPath);
+
+  // Require confirmation before destructive rollback
+  const confirmed = await confirm(
+    "Apply produced type errors. Roll back all changes and restore previous state?",
+  );
+
+  if (!confirmed) {
+    return false;
+  }
+
+  // Discard apply changes — execFileSync, no shell
+  try {
+    execFileSync("git", ["checkout", "."], {
+      cwd: absPath,
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+  } catch {
+    // Could not roll back
+    return false;
+  }
+
+  // Clean untracked files created by apply
+  try {
+    execFileSync("git", ["clean", "-fd"], {
+      cwd: absPath,
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+  } catch {
+    // Non-fatal
+  }
+
+  // Restore stash if we created one
+  if (checkpoint.stashCreated) {
+    try {
+      execFileSync("git", ["stash", "pop"], {
+        cwd: absPath,
+        encoding: "utf-8",
+        stdio: ["pipe", "pipe", "pipe"],
+      });
+    } catch {
+      // Stash pop failed — user must handle manually
+    }
+  }
+
+  return true;
+}
+
+// ---------------------------------------------------------------------------
+// Git commit helper (for post-apply)
+// ---------------------------------------------------------------------------
+
+export function getGitStatus(projectPath: string): string {
+  try {
+    return execFileSync("git", ["status", "--porcelain"], {
+      cwd: resolve(projectPath),
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"],
+    }).trim();
+  } catch {
+    return "";
+  }
+}

package/src/schema.ts

@@ -0,0 +1,270 @@
+/**
+ * Sigil Context Document Schema — the universal intermediate representation.
+ *
+ * DESIGN PRINCIPLE: This schema is LANGUAGE-AGNOSTIC. It contains zero
+ * references to any specific language, framework, ORM, or toolchain.
+ * Technology-specific metadata is contributed by plugins via the `tags`
+ * system and extensible record types.
+ *
+ * The _meta anchor on every element enables bidirectional sync —
+ * each context element links back to its source location.
+ */
+
+// ---------------------------------------------------------------------------
+// Meta anchor — the bidirectional link
+// ---------------------------------------------------------------------------
+
+export interface Meta {
+  /** Relative path from project root to source file */
+  file: string;
+  /** Exported symbol name (function, class, variable, type) */
+  symbol: string;
+  /** Generic element category — language-agnostic */
+  type: MetaType;
+  /** Plugin-contributed tags for technology-specific classification */
+  tags?: string[];
+  /** Line number in source file (for precise anchoring) */
+  line?: number;
+  /** Truncated SHA-256 hash of source file at extraction time */
+  hash?: string;
+}
+
+/**
+ * Generic element categories. These are structural roles, not
+ * technology-specific types. Plugins use `tags` for specificity.
+ *
+ * Example: a Drizzle table has type "entity" with tags ["orm:drizzle", "db:postgresql"]
+ * Example: a React component has type "component" with tags ["framework:react", "client"]
+ * Example: a Django model has type "entity" with tags ["orm:django", "db:postgresql"]
+ */
+export type MetaType =
+  | "entity"       // Data model (DB table, ORM model, GraphQL type)
+  | "component"    // UI component (React, Vue, Svelte, etc.)
+  | "route"        // HTTP route / API endpoint
+  | "function"     // Standalone function
+  | "class"        // Class declaration
+  | "type"         // Type alias, interface, enum
+  | "constant"     // Constant / config value
+  | "middleware"    // Request middleware / interceptor
+  | "hook"         // Framework-specific hook (React hook, lifecycle, etc.)
+  | "config";      // Configuration file / entry
+
+// ---------------------------------------------------------------------------
+// Stack & project metadata (extensible)
+// ---------------------------------------------------------------------------
+
+/**
+ * Project stack information — plugins contribute their own key-value pairs.
+ *
+ * Common keys (by convention, not enforced):
+ *   framework, language, orm, database, ui, auth, testing, package_manager
+ *
+ * Values are strings or string arrays.
+ */
+export type StackInfo = Record<string, string | string[]>;
+
+/** Extraction metadata — when and how the context was generated */
+export interface ExtractionMeta {
+  extracted_at: string;
+  sigil_version?: string;
+  source_commit?: string;
+  extraction_ms?: number;
+  plugins_used?: string[];
+}
+
+// ---------------------------------------------------------------------------
+// Entities (data models — ORM tables, GraphQL types, etc.)
+// ---------------------------------------------------------------------------
+
+export interface Entity {
+  name: string;
+  _meta: Meta;
+  fields: EntityField[];
+  relations: EntityRelation[];
+}
+
+export interface EntityField {
+  name: string;
+  type: string;
+  primary?: boolean;
+  unique?: boolean;
+  nullable?: boolean;
+  default?: string;
+  references?: { table: string; column: string };
+}
+
+export interface EntityRelation {
+  to: string;
+  type: "one-to-one" | "one-to-many" | "many-to-many";
+  via?: string;
+  through?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Components (UI elements — framework-agnostic)
+// ---------------------------------------------------------------------------
+
+export interface Component {
+  name: string;
+  _meta: Meta;
+  props: ComponentProp[];
+  dependencies: string[];
+  hooks: string[];
+  data_sources: string[];
+  route?: string;
+  /** Plugin-specific flags via tags instead of hardcoded booleans */
+}
+
+export interface ComponentProp {
+  name: string;
+  type: string;
+  required?: boolean;
+  default?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Routes (API endpoints — framework-agnostic)
+// ---------------------------------------------------------------------------
+
+export interface Route {
+  path: string;
+  _meta: Meta;
+  methods: Record<string, RouteMethod>;
+}
+
+export interface RouteMethod {
+  auth?: boolean;
+  returns?: string;
+  params?: string[];
+  body?: string;
+  description?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Exports (generic symbols not captured elsewhere)
+// ---------------------------------------------------------------------------
+
+export interface ExportedSymbol {
+  name: string;
+  _meta: Meta;
+  kind: "function" | "class" | "interface" | "type" | "enum" | "constant";
+  signature?: string;
+  description?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Patterns & conventions (extensible key-value)
+// ---------------------------------------------------------------------------
+
+/**
+ * Detected architectural patterns. Plugins contribute entries.
+ * Keys are pattern categories (e.g., "auth", "data_fetching", "state").
+ * Values describe the detected pattern.
+ */
+export type Patterns = Record<string, string>;
+
+/**
+ * Detected conventions. Plugins contribute entries.
+ * Keys are convention categories (e.g., "file_naming", "import_style").
+ * Values describe the convention.
+ */
+export type Conventions = Record<string, string>;
+
+// ---------------------------------------------------------------------------
+// Dependencies (from package manifest)
+// ---------------------------------------------------------------------------
+
+export interface Dependency {
+  name: string;
+  version: string;
+  dev?: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Call graph (behavior layer)
+// ---------------------------------------------------------------------------
+
+export interface CallEdge {
+  /** Fully qualified caller: "file::symbol" */
+  caller: string;
+  /** Fully qualified callee: "file::symbol" */
+  callee: string;
+  location: { file: string; line: number };
+  data_flow?: { args: string[]; returns: string };
+}
+
+export interface ComponentEdge {
+  source: string;
+  target: string;
+  weight: number;
+}
+
+// ---------------------------------------------------------------------------
+// Environment variables
+// ---------------------------------------------------------------------------
+
+export interface EnvVar {
+  name: string;
+  required: boolean;
+  used_in: string[];
+}
+
+// ---------------------------------------------------------------------------
+// The root document
+// ---------------------------------------------------------------------------
+
+export interface ContextDocument {
+  /** Schema version for compatibility checking */
+  version: string;
+  /** Project name */
+  project: string;
+  /** Extraction metadata */
+  _extraction: ExtractionMeta;
+  /** Technology stack (extensible key-value) */
+  stack: StackInfo;
+  /** Data entities (DB tables, models) */
+  entities: Entity[];
+  /** UI components */
+  components: Component[];
+  /** API routes / endpoints */
+  routes: Route[];
+  /** Other exported symbols */
+  exports: ExportedSymbol[];
+  /** Function-level call graph */
+  call_graph: CallEdge[];
+  /** File-level interaction graph */
+  component_graph: ComponentEdge[];
+  /** Environment variables */
+  env_vars: EnvVar[];
+  /** Detected architectural patterns */
+  patterns: Patterns;
+  /** Detected conventions */
+  conventions: Conventions;
+  /** Package dependencies */
+  dependencies: Dependency[];
+  /** Plugin-contributed custom sections */
+  extensions?: Record<string, unknown>;
+}
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+export function createEmptyDocument(project: string): ContextDocument {
+  return {
+    version: "1.0",
+    project,
+    _extraction: { extracted_at: new Date().toISOString() },
+    stack: {},
+    entities: [],
+    components: [],
+    routes: [],
+    exports: [],
+    call_graph: [],
+    component_graph: [],
+    env_vars: [],
+    patterns: {},
+    conventions: {},
+    dependencies: [],
+  };
+}