@sigil-engine/core 0.1.0

package/dist/schema.d.ts

@@ -0,0 +1,184 @@
+/**
+ * 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.
+ */
+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" | "component" | "route" | "function" | "class" | "type" | "constant" | "middleware" | "hook" | "config";
+/**
+ * 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[];
+}
+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;
+}
+export interface Component {
+    name: string;
+    _meta: Meta;
+    props: ComponentProp[];
+    dependencies: string[];
+    hooks: string[];
+    data_sources: string[];
+    route?: string;
+}
+export interface ComponentProp {
+    name: string;
+    type: string;
+    required?: boolean;
+    default?: string;
+}
+export interface Route {
+    path: string;
+    _meta: Meta;
+    methods: Record<string, RouteMethod>;
+}
+export interface RouteMethod {
+    auth?: boolean;
+    returns?: string;
+    params?: string[];
+    body?: string;
+    description?: string;
+}
+export interface ExportedSymbol {
+    name: string;
+    _meta: Meta;
+    kind: "function" | "class" | "interface" | "type" | "enum" | "constant";
+    signature?: string;
+    description?: string;
+}
+/**
+ * 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>;
+export interface Dependency {
+    name: string;
+    version: string;
+    dev?: boolean;
+}
+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;
+}
+export interface EnvVar {
+    name: string;
+    required: boolean;
+    used_in: string[];
+}
+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>;
+}
+export declare function createEmptyDocument(project: string): ContextDocument;
+//# sourceMappingURL=schema.d.ts.map

package/dist/schema.d.ts.map

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

package/dist/schema.js

@@ -0,0 +1,33 @@
+/**
+ * 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.
+ */
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+export function createEmptyDocument(project) {
+    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: [],
+    };
+}
+//# sourceMappingURL=schema.js.map

package/dist/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AA8OH,8EAA8E;AAC9E,UAAU;AACV,8EAA8E;AAE9E,MAAM,UAAU,mBAAmB,CAAC,OAAe;IACjD,OAAO;QACL,OAAO,EAAE,KAAK;QACd,OAAO;QACP,WAAW,EAAE,EAAE,YAAY,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,EAAE;QACvD,KAAK,EAAE,EAAE;QACT,QAAQ,EAAE,EAAE;QACZ,UAAU,EAAE,EAAE;QACd,MAAM,EAAE,EAAE;QACV,OAAO,EAAE,EAAE;QACX,UAAU,EAAE,EAAE;QACd,eAAe,EAAE,EAAE;QACnB,QAAQ,EAAE,EAAE;QACZ,QAAQ,EAAE,EAAE;QACZ,WAAW,EAAE,EAAE;QACf,YAAY,EAAE,EAAE;KACjB,CAAC;AACJ,CAAC"}

package/dist/serialize.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Context document serialization — YAML and JSON.
+ *
+ * YAML is the primary human-readable format.
+ * JSON is the machine-consumption format.
+ *
+ * _meta anchors are serialized as compact flow mappings for readability.
+ */
+import type { ContextDocument } from "./schema.js";
+export declare function serializeYaml(doc: ContextDocument): string;
+export declare function serializeJson(doc: ContextDocument): string;
+export declare function deserializeYaml(yamlStr: string): ContextDocument;
+export declare function deserializeJson(jsonStr: string): ContextDocument;
+export declare function writeContextFile(doc: ContextDocument, outputPath: string, format?: "yaml" | "json"): void;
+export declare function readContextFile(inputPath: string): ContextDocument;
+//# sourceMappingURL=serialize.d.ts.map

package/dist/serialize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serialize.d.ts","sourceRoot":"","sources":["../src/serialize.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAMnD,wBAAgB,aAAa,CAAC,GAAG,EAAE,eAAe,GAAG,MAAM,CA0C1D;AAED,wBAAgB,aAAa,CAAC,GAAG,EAAE,eAAe,GAAG,MAAM,CAE1D;AAMD,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,eAAe,CAEhE;AAED,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,eAAe,CAEhE;AAMD,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,eAAe,EACpB,UAAU,EAAE,MAAM,EAClB,MAAM,GAAE,MAAM,GAAG,MAAe,GAC/B,IAAI,CAGN;AAED,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,eAAe,CAMlE"}

package/dist/serialize.js

@@ -0,0 +1,75 @@
+/**
+ * Context document serialization — YAML and JSON.
+ *
+ * YAML is the primary human-readable format.
+ * JSON is the machine-consumption format.
+ *
+ * _meta anchors are serialized as compact flow mappings for readability.
+ */
+import { stringify, parse } from "yaml";
+import { readFileSync, writeFileSync } from "fs";
+// ---------------------------------------------------------------------------
+// Serialize
+// ---------------------------------------------------------------------------
+export function serializeYaml(doc) {
+    const header = `# context.yaml — generated by sigil extract\n# ${doc._extraction.extracted_at}\n\n`;
+    const yamlStr = stringify(doc, {
+        lineWidth: 120,
+        defaultKeyType: "PLAIN",
+        defaultStringType: "QUOTE_DOUBLE",
+        nullStr: "",
+        sortMapEntries: false,
+        flowCollectionPadding: true,
+    });
+    // Post-process: compact _meta blocks that are simple (no nested arrays/objects).
+    // _meta blocks with tags arrays are left in standard YAML format.
+    const processed = yamlStr.replace(/^(\s+)_meta:\n((?:\1\s+[^\s].*\n)*)/gm, (match, indent, body) => {
+        // If body contains array items (- "...") or nested objects, skip compaction
+        if (body.includes("\n" + indent + "    - ") || body.includes("\n" + indent + "      ")) {
+            return match; // Leave as-is
+        }
+        const lines = body.trim().split("\n").map((l) => l.trim()).filter((l) => l.length > 0);
+        // Only compact if all lines are simple key: value pairs
+        const pairs = [];
+        for (const line of lines) {
+            const colonIdx = line.indexOf(":");
+            if (colonIdx === -1)
+                return match; // Not a simple pair, abort
+            const key = line.slice(0, colonIdx).trim();
+            let val = line.slice(colonIdx + 1).trim();
+            if (val.startsWith('"') && val.endsWith('"')) {
+                val = val.slice(1, -1);
+            }
+            pairs.push(`${key}: "${val}"`);
+        }
+        return `${indent}_meta: { ${pairs.join(", ")} }\n`;
+    });
+    return header + processed;
+}
+export function serializeJson(doc) {
+    return JSON.stringify(doc, null, 2);
+}
+// ---------------------------------------------------------------------------
+// Deserialize
+// ---------------------------------------------------------------------------
+export function deserializeYaml(yamlStr) {
+    return parse(yamlStr);
+}
+export function deserializeJson(jsonStr) {
+    return JSON.parse(jsonStr);
+}
+// ---------------------------------------------------------------------------
+// File I/O helpers
+// ---------------------------------------------------------------------------
+export function writeContextFile(doc, outputPath, format = "yaml") {
+    const content = format === "json" ? serializeJson(doc) : serializeYaml(doc);
+    writeFileSync(outputPath, content, "utf-8");
+}
+export function readContextFile(inputPath) {
+    const content = readFileSync(inputPath, "utf-8");
+    if (inputPath.endsWith(".json")) {
+        return deserializeJson(content);
+    }
+    return deserializeYaml(content);
+}
+//# sourceMappingURL=serialize.js.map

package/dist/serialize.js.map

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

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@sigil-engine/core",
+  "version": "0.1.0",
+  "description": "Core engine for Sigil — schema, plugin interface, diff, plan, apply",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "yaml": "^2.7.0",
+    "glob": "^11.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0",
+    "@types/node": "^22.0.0",
+    "vitest": "^3.0.0"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/cache.ts

@@ -0,0 +1,133 @@
+/**
+ * Incremental extraction cache — skip unchanged files on re-extraction.
+ *
+ * Saves file hashes after extraction. On re-extract, compares hashes
+ * and returns which files need re-parsing.
+ */
+
+import { resolve } from "path";
+import { readFileSync, writeFileSync, existsSync, statSync } from "fs";
+import { createHash } from "crypto";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface FileCache {
+  files: Record<string, { hash: string; mtime: number }>;
+  last_full_extract: string;
+}
+
+export interface ChangedFiles {
+  changed: string[];
+  unchanged: string[];
+  added: string[];
+  removed: string[];
+}
+
+// ---------------------------------------------------------------------------
+// Cache file path
+// ---------------------------------------------------------------------------
+
+const CACHE_FILENAME = ".sigil-cache.json";
+
+function cachePath(projectPath: string): string {
+  return resolve(projectPath, CACHE_FILENAME);
+}
+
+// ---------------------------------------------------------------------------
+// Read / Write
+// ---------------------------------------------------------------------------
+
+export function readCache(projectPath: string): FileCache | null {
+  const cp = cachePath(projectPath);
+  if (!existsSync(cp)) return null;
+  try {
+    return JSON.parse(readFileSync(cp, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+
+export function writeCache(projectPath: string, cache: FileCache): void {
+  writeFileSync(cachePath(projectPath), JSON.stringify(cache, null, 2), "utf-8");
+}
+
+// ---------------------------------------------------------------------------
+// Build cache from current file state
+// ---------------------------------------------------------------------------
+
+export function buildCacheFromFiles(
+  projectPath: string,
+  files: string[],
+): FileCache {
+  const fileMap: Record<string, { hash: string; mtime: number }> = {};
+  const absProject = resolve(projectPath);
+
+  for (const relFile of files) {
+    const absFile = resolve(absProject, relFile);
+    try {
+      const stat = statSync(absFile);
+      const content = readFileSync(absFile, "utf-8");
+      const hash = createHash("sha256").update(content).digest("hex").slice(0, 12);
+      fileMap[relFile] = { hash, mtime: stat.mtimeMs };
+    } catch {
+      // Skip unreadable files
+    }
+  }
+
+  return {
+    files: fileMap,
+    last_full_extract: new Date().toISOString(),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Determine changed files
+// ---------------------------------------------------------------------------
+
+export function getChangedFiles(
+  projectPath: string,
+  currentFiles: string[],
+  cache: FileCache,
+): ChangedFiles {
+  const absProject = resolve(projectPath);
+  const changed: string[] = [];
+  const unchanged: string[] = [];
+  const added: string[] = [];
+  const currentSet = new Set(currentFiles);
+
+  for (const relFile of currentFiles) {
+    const cached = cache.files[relFile];
+    if (!cached) {
+      added.push(relFile);
+      continue;
+    }
+
+    try {
+      const absFile = resolve(absProject, relFile);
+      const stat = statSync(absFile);
+
+      // Quick check: mtime unchanged = file unchanged
+      if (stat.mtimeMs === cached.mtime) {
+        unchanged.push(relFile);
+        continue;
+      }
+
+      // mtime changed — verify with hash
+      const content = readFileSync(absFile, "utf-8");
+      const hash = createHash("sha256").update(content).digest("hex").slice(0, 12);
+      if (hash === cached.hash) {
+        unchanged.push(relFile);
+      } else {
+        changed.push(relFile);
+      }
+    } catch {
+      changed.push(relFile);
+    }
+  }
+
+  const removed = Object.keys(cache.files).filter((f) => !currentSet.has(f));
+
+  return { changed, unchanged, added, removed };
+}