logicstamp-context 0.1.0

package/dist/core/contractBuilder.js

@@ -0,0 +1,120 @@
+/**
+ * @uif Contract 0.3
+ *
+ * Description: contractBuilder - Presentational component
+ *
+ * Version (Component Composition):
+ *   variables: []
+ *   hooks: []
+ *   components: []
+ *   functions: ["buildContract","mergeContractUpdate"]
+ *   imports: ["../types/UIFContract.js","../utils/fsx.js","../utils/hash.js","./astParser.js","./signature.js"]
+ *
+ * Logic Signature:
+ *   props: {}
+ *   emits: {}
+ *   state: {}
+ *
+ * Predictions:
+ *   (none)
+ *
+ * Hashes (informational only - authoritative values in .uif.json):
+ *   semantic: uif:9e7343c07744633f5dfe4cd9 (informational)
+ *   file: uif:6885bc3a8a6e6f3a4c0056fb
+ */
+import { buildLogicSignature, generateBehavioralPredictions, inferDescription, } from './signature.js';
+import { semanticHashFromAst, fileHash } from '../utils/hash.js';
+import { normalizeEntryId } from '../utils/fsx.js';
+import { resolve, relative } from 'node:path';
+import { platform } from 'node:os';
+/**
+ * Extract export metadata from AST
+ */
+function extractExportsMetadata(ast) {
+    // Check if we have any exports at all
+    if (!ast.functions || ast.functions.length === 0) {
+        return undefined;
+    }
+    // Check for default export in the component name
+    const hasDefaultExport = ast.functions.some(fn => fn.toLowerCase() === 'default');
+    // If we have only one function and it matches the file name, assume default export
+    const isLikelyDefault = ast.functions.length === 1 && !hasDefaultExport;
+    if (hasDefaultExport || isLikelyDefault) {
+        return 'default';
+    }
+    // If multiple exports or clear named exports
+    if (ast.functions.length > 1) {
+        return { named: ast.functions };
+    }
+    // Single named export
+    return { named: ast.functions };
+}
+/**
+ * Build a complete UIFContract from extracted AST data
+ */
+export function buildContract(entryId, ast, params) {
+    // Build logic signature with preset validation
+    const { signature, prediction: presetPredictions, violations } = buildLogicSignature(ast, params.preset);
+    // Generate additional behavioral predictions (only if enabled)
+    const behavioralPredictions = params.enablePredictions
+        ? generateBehavioralPredictions(ast)
+        : [];
+    // Combine all predictions
+    const allPredictions = [...presetPredictions, ...behavioralPredictions];
+    // Compute path fields
+    const entryPathAbs = resolve(entryId);
+    const cwd = process.cwd();
+    const entryPathRel = relative(cwd, entryId).replace(/\\/g, '/'); // Always use POSIX separators
+    const os = platform() === 'win32' ? 'win32' : 'posix';
+    // Extract exports
+    const exports = extractExportsMetadata(ast);
+    // Build the contract (usedIn omitted - computed at manifest time, not persisted)
+    const contract = {
+        type: 'UIFContract',
+        schemaVersion: '0.3',
+        kind: ast.kind,
+        entryId: normalizeEntryId(entryId),
+        entryPathAbs,
+        entryPathRel,
+        os,
+        description: params.description || inferDescription(entryId, ast),
+        version: {
+            variables: ast.variables,
+            hooks: ast.hooks,
+            components: ast.components,
+            functions: ast.functions,
+            imports: ast.imports,
+        },
+        logicSignature: signature,
+        exports,
+        prediction: allPredictions.length > 0 ? allPredictions : undefined,
+        metrics: undefined,
+        links: undefined,
+        nextjs: ast.nextjs,
+        semanticHash: semanticHashFromAst(ast, signature),
+        fileHash: fileHash(params.sourceText),
+    };
+    return { contract, violations };
+}
+/**
+ * Merge contract updates while preserving manual fields
+ */
+export function mergeContractUpdate(existing, updated) {
+    return {
+        ...updated,
+        // kind should always use the updated value (auto-detected)
+        kind: updated.kind,
+        // Preserve manually set fields that shouldn't be auto-updated
+        description: existing.description || updated.description,
+        metrics: existing.metrics || updated.metrics,
+        links: existing.links || updated.links,
+        // nextjs metadata should be auto-updated with shallow merge for future extensibility
+        nextjs: updated.nextjs ? {
+            ...(existing.nextjs ?? {}),
+            ...updated.nextjs
+        } : existing.nextjs,
+        // usedIn is never persisted (computed at manifest time)
+        usedIn: undefined,
+    };
+}
+//# sourceMappingURL=contractBuilder.js.map

package/dist/core/contractBuilder.js.map

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

package/dist/core/manifest.d.ts

@@ -0,0 +1,75 @@
+/**
+ * @uif Contract 0.3
+ *
+ * Description: manifest - Presentational component
+ *
+ * Version (Component Composition):
+ *   variables: []
+ *   hooks: []
+ *   components: []
+ *   functions: ["buildDependencyGraph","buildHashIndices","findComponentByName","generateStats","writeManifest"]
+ *   imports: ["../types/UIFContract.js","../utils/hash.js","node:fs/promises","node:path"]
+ *
+ * Logic Signature:
+ *   props: {}
+ *   events: {}
+ *   state: {}
+ *
+ * Predictions:
+ *   (none)
+ *
+ * Hashes (informational only - authoritative values in .uif.json):
+ *   semantic: uif:1ddfb5c70a09a2614d47690e (informational)
+ *   file: uif:179d1c0bb533920680e6417f
+ */
+import type { UIFContract } from '../types/UIFContract.js';
+export interface ComponentNode {
+    entryId: string;
+    description: string;
+    dependencies: string[];
+    usedBy: string[];
+    imports: string[];
+    routes: string[];
+    semanticHash: string;
+    structureHash?: string;
+    signatureHash?: string;
+}
+export interface ProjectManifest {
+    version: '0.3';
+    generatedAt: string;
+    totalComponents: number;
+    components: Record<string, ComponentNode>;
+    graph: {
+        roots: string[];
+        leaves: string[];
+    };
+    hashIndex?: {
+        structureHash: Record<string, string[]>;
+        signatureHash: Record<string, string[]>;
+    };
+}
+/**
+ * Build dependency graph from contracts
+ */
+export declare function buildDependencyGraph(contracts: UIFContract[], options?: {
+    includeHashIndices?: boolean;
+}): ProjectManifest;
+/**
+ * Write manifest to file
+ */
+export declare function writeManifest(manifest: ProjectManifest, outPath: string): Promise<void>;
+/**
+ * Generate component usage statistics
+ */
+export declare function generateStats(manifest: ProjectManifest): {
+    mostUsed: Array<{
+        id: string;
+        usageCount: number;
+    }>;
+    mostComplex: Array<{
+        id: string;
+        dependencyCount: number;
+    }>;
+    isolated: string[];
+};
+//# sourceMappingURL=manifest.d.ts.map

package/dist/core/manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../src/core/manifest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAQH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAG3D,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,KAAK,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IAC1C,KAAK,EAAE;QACL,KAAK,EAAE,MAAM,EAAE,CAAC;QAChB,MAAM,EAAE,MAAM,EAAE,CAAC;KAClB,CAAC;IACF,SAAS,CAAC,EAAE;QACV,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;QACxC,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;KACzC,CAAC;CACH;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,WAAW,EAAE,EACxB,OAAO,CAAC,EAAE;IAAE,kBAAkB,CAAC,EAAE,OAAO,CAAA;CAAE,GACzC,eAAe,CAyEjB;AA4DD;;GAEG;AACH,wBAAsB,aAAa,CAAC,QAAQ,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAI7F;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,eAAe,GAAG;IACxD,QAAQ,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACpD,WAAW,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,eAAe,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC5D,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB,CAoBA"}

package/dist/core/manifest.js

@@ -0,0 +1,173 @@
+/**
+ * @uif Contract 0.3
+ *
+ * Description: manifest - Presentational component
+ *
+ * Version (Component Composition):
+ *   variables: []
+ *   hooks: []
+ *   components: []
+ *   functions: ["buildDependencyGraph","buildHashIndices","findComponentByName","generateStats","writeManifest"]
+ *   imports: ["../types/UIFContract.js","../utils/hash.js","node:fs/promises","node:path"]
+ *
+ * Logic Signature:
+ *   props: {}
+ *   events: {}
+ *   state: {}
+ *
+ * Predictions:
+ *   (none)
+ *
+ * Hashes (informational only - authoritative values in .uif.json):
+ *   semantic: uif:1ddfb5c70a09a2614d47690e (informational)
+ *   file: uif:179d1c0bb533920680e6417f
+ */
+/**
+ * Manifest builder - Creates dependency graph for the entire project
+ */
+import { writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { structureHash, signatureHash } from '../utils/hash.js';
+/**
+ * Build dependency graph from contracts
+ */
+export function buildDependencyGraph(contracts, options) {
+    const components = {};
+    // First pass: create nodes
+    for (const contract of contracts) {
+        // Compute structure and signature hashes from contract data
+        // These are computed on-demand rather than stored in contracts
+        // Note: structureHash() and signatureHash() already return hashes with uif: prefix
+        const structHash = structureHash(contract.version);
+        const sigHash = signatureHash(contract.logicSignature);
+        components[contract.entryId] = {
+            entryId: contract.entryId,
+            description: contract.description,
+            dependencies: contract.version.components,
+            usedBy: [],
+            imports: contract.version.imports || [],
+            routes: contract.usedIn || [],
+            semanticHash: contract.semanticHash,
+            structureHash: structHash,
+            signatureHash: sigHash,
+        };
+    }
+    // Second pass: build reverse relationships (usedBy)
+    for (const contract of contracts) {
+        const componentId = contract.entryId;
+        // For each component this one uses
+        for (const dependency of contract.version.components) {
+            // Find the matching component in our graph
+            const depNode = findComponentByName(components, dependency);
+            if (depNode) {
+                // Add this component to the dependency's usedBy list
+                if (!depNode.usedBy.includes(componentId)) {
+                    depNode.usedBy.push(componentId);
+                }
+            }
+        }
+    }
+    // Identify roots and leaves
+    const roots = [];
+    const leaves = [];
+    for (const [id, node] of Object.entries(components)) {
+        if (node.usedBy.length === 0) {
+            roots.push(id);
+        }
+        if (node.dependencies.length === 0) {
+            leaves.push(id);
+        }
+    }
+    // Build hash indices if requested
+    let hashIndex;
+    if (options?.includeHashIndices) {
+        hashIndex = buildHashIndices(components);
+    }
+    return {
+        version: '0.3',
+        generatedAt: new Date().toISOString(),
+        totalComponents: contracts.length,
+        components,
+        graph: {
+            roots: roots.sort(),
+            leaves: leaves.sort(),
+        },
+        hashIndex,
+    };
+}
+/**
+ * Build hash indices for similarity detection
+ */
+function buildHashIndices(components) {
+    const structureIndex = {};
+    const signatureIndex = {};
+    for (const [entryId, node] of Object.entries(components)) {
+        // Index by structure hash
+        if (node.structureHash) {
+            if (!structureIndex[node.structureHash]) {
+                structureIndex[node.structureHash] = [];
+            }
+            structureIndex[node.structureHash].push(entryId);
+        }
+        // Index by signature hash
+        if (node.signatureHash) {
+            if (!signatureIndex[node.signatureHash]) {
+                signatureIndex[node.signatureHash] = [];
+            }
+            signatureIndex[node.signatureHash].push(entryId);
+        }
+    }
+    return {
+        structureHash: structureIndex,
+        signatureHash: signatureIndex,
+    };
+}
+/**
+ * Find component by name (handles partial matches)
+ */
+function findComponentByName(components, name) {
+    // First try exact match
+    const exactMatch = Object.values(components).find((c) => c.entryId.endsWith(`/${name}.tsx`));
+    if (exactMatch)
+        return exactMatch;
+    // Try with .ts extension
+    const tsMatch = Object.values(components).find((c) => c.entryId.endsWith(`/${name}.ts`));
+    if (tsMatch)
+        return tsMatch;
+    // Try partial match on component name
+    const partialMatch = Object.values(components).find((c) => {
+        const componentName = c.entryId.split('/').pop()?.replace(/\.(tsx?|jsx?)$/, '');
+        return componentName === name;
+    });
+    return partialMatch || null;
+}
+/**
+ * Write manifest to file
+ */
+export async function writeManifest(manifest, outPath) {
+    const manifestPath = join(outPath, 'logicstamp.manifest.json');
+    const json = JSON.stringify(manifest, null, 2);
+    await writeFile(manifestPath, json, 'utf8');
+}
+/**
+ * Generate component usage statistics
+ */
+export function generateStats(manifest) {
+    const usageStats = Object.entries(manifest.components).map(([id, node]) => ({
+        id,
+        usageCount: node.usedBy.length,
+    }));
+    const complexityStats = Object.entries(manifest.components).map(([id, node]) => ({
+        id,
+        dependencyCount: node.dependencies.length,
+    }));
+    const isolated = Object.entries(manifest.components)
+        .filter(([_, node]) => node.usedBy.length === 0 && node.dependencies.length === 0)
+        .map(([id]) => id);
+    return {
+        mostUsed: usageStats.sort((a, b) => b.usageCount - a.usageCount).slice(0, 10),
+        mostComplex: complexityStats.sort((a, b) => b.dependencyCount - a.dependencyCount).slice(0, 10),
+        isolated,
+    };
+}
+//# sourceMappingURL=manifest.js.map

package/dist/core/manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.js","sourceRoot":"","sources":["../../src/core/manifest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH;;GAEG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AA6BhE;;GAEG;AACH,MAAM,UAAU,oBAAoB,CAClC,SAAwB,EACxB,OAA0C;IAE1C,MAAM,UAAU,GAAkC,EAAE,CAAC;IAErD,2BAA2B;IAC3B,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;QACjC,4DAA4D;QAC5D,+DAA+D;QAC/D,mFAAmF;QACnF,MAAM,UAAU,GAAG,aAAa,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;QACnD,MAAM,OAAO,GAAG,aAAa,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAC;QAEvD,UAAU,CAAC,QAAQ,CAAC,OAAO,CAAC,GAAG;YAC7B,OAAO,EAAE,QAAQ,CAAC,OAAO;YACzB,WAAW,EAAE,QAAQ,CAAC,WAAW;YACjC,YAAY,EAAE,QAAQ,CAAC,OAAO,CAAC,UAAU;YACzC,MAAM,EAAE,EAAE;YACV,OAAO,EAAE,QAAQ,CAAC,OAAO,CAAC,OAAO,IAAI,EAAE;YACvC,MAAM,EAAE,QAAQ,CAAC,MAAM,IAAI,EAAE;YAC7B,YAAY,EAAE,QAAQ,CAAC,YAAY;YACnC,aAAa,EAAE,UAAU;YACzB,aAAa,EAAE,OAAO;SACvB,CAAC;IACJ,CAAC;IAED,oDAAoD;IACpD,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;QACjC,MAAM,WAAW,GAAG,QAAQ,CAAC,OAAO,CAAC;QAErC,mCAAmC;QACnC,KAAK,MAAM,UAAU,IAAI,QAAQ,CAAC,OAAO,CAAC,UAAU,EAAE,CAAC;YACrD,2CAA2C;YAC3C,MAAM,OAAO,GAAG,mBAAmB,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC;YAE5D,IAAI,OAAO,EAAE,CAAC;gBACZ,qDAAqD;gBACrD,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC;oBAC1C,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;gBACnC,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;IAED,4BAA4B;IAC5B,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,MAAM,MAAM,GAAa,EAAE,CAAC;IAE5B,KAAK,MAAM,CAAC,EAAE,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,CAAC;QACpD,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC7B,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACjB,CAAC;QACD,IAAI,IAAI,CAAC,YAAY,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACnC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAClB,CAAC;IACH,CAAC;IAED,kCAAkC;IAClC,IAAI,SAA2G,CAAC;IAEhH,IAAI,OAAO,EAAE,kBAAkB,EAAE,CAAC;QAChC,SAAS,GAAG,gBAAgB,CAAC,UAAU,CAAC,CAAC;IAC3C,CAAC;IAED,OAAO;QACL,OAAO,EAAE,KAAK;QACd,WAAW,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACrC,eAAe,EAAE,SAAS,CAAC,MAAM;QACjC,UAAU;QACV,KAAK,EAAE;YACL,KAAK,EAAE,KAAK,CAAC,IAAI,EAAE;YACnB,MAAM,EAAE,MAAM,CAAC,IAAI,EAAE;SACtB;QACD,SAAS;KACV,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,SAAS,gBAAgB,CAAC,UAAyC;IAIjE,MAAM,cAAc,GAA6B,EAAE,CAAC;IACpD,MAAM,cAAc,GAA6B,EAAE,CAAC;IAEpD,KAAK,MAAM,CAAC,OAAO,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,CAAC;QACzD,0BAA0B;QAC1B,IAAI,IAAI,CAAC,aAAa,EAAE,CAAC;YACvB,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,aAAa,CAAC,EAAE,CAAC;gBACxC,cAAc,CAAC,IAAI,CAAC,aAAa,CAAC,GAAG,EAAE,CAAC;YAC1C,CAAC;YACD,cAAc,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACnD,CAAC;QAED,0BAA0B;QAC1B,IAAI,IAAI,CAAC,aAAa,EAAE,CAAC;YACvB,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,aAAa,CAAC,EAAE,CAAC;gBACxC,cAAc,CAAC,IAAI,CAAC,aAAa,CAAC,GAAG,EAAE,CAAC;YAC1C,CAAC;YACD,cAAc,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACnD,CAAC;IACH,CAAC;IAED,OAAO;QACL,aAAa,EAAE,cAAc;QAC7B,aAAa,EAAE,cAAc;KAC9B,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,SAAS,mBAAmB,CAC1B,UAAyC,EACzC,IAAY;IAEZ,wBAAwB;IACxB,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,IAAI,MAAM,CAAC,CAAC,CAAC;IAC7F,IAAI,UAAU;QAAE,OAAO,UAAU,CAAC;IAElC,yBAAyB;IACzB,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,IAAI,KAAK,CAAC,CAAC,CAAC;IACzF,IAAI,OAAO;QAAE,OAAO,OAAO,CAAC;IAE5B,sCAAsC;IACtC,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE;QACxD,MAAM,aAAa,GAAG,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,OAAO,CAAC,gBAAgB,EAAE,EAAE,CAAC,CAAC;QAChF,OAAO,aAAa,KAAK,IAAI,CAAC;IAChC,CAAC,CAAC,CAAC;IAEH,OAAO,YAAY,IAAI,IAAI,CAAC;AAC9B,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,QAAyB,EAAE,OAAe;IAC5E,MAAM,YAAY,GAAG,IAAI,CAAC,OAAO,EAAE,0BAA0B,CAAC,CAAC;IAC/D,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;IAC/C,MAAM,SAAS,CAAC,YAAY,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;AAC9C,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,aAAa,CAAC,QAAyB;IAKrD,MAAM,UAAU,GAAG,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC;QAC1E,EAAE;QACF,UAAU,EAAE,IAAI,CAAC,MAAM,CAAC,MAAM;KAC/B,CAAC,CAAC,CAAC;IAEJ,MAAM,eAAe,GAAG,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC;QAC/E,EAAE;QACF,eAAe,EAAE,IAAI,CAAC,YAAY,CAAC,MAAM;KAC1C,CAAC,CAAC,CAAC;IAEJ,MAAM,QAAQ,GAAG,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC;SACjD,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC,IAAI,IAAI,CAAC,YAAY,CAAC,MAAM,KAAK,CAAC,CAAC;SACjF,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC;IAErB,OAAO;QACL,QAAQ,EAAE,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,UAAU,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC;QAC7E,WAAW,EAAE,eAAe,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,eAAe,GAAG,CAAC,CAAC,eAAe,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC;QAC/F,QAAQ;KACT,CAAC;AACJ,CAAC"}

package/dist/core/pack.d.ts

@@ -0,0 +1,190 @@
+/**
+ * @uif Contract 0.3
+ *
+ * Description: pack - Presentational component
+ *
+ * Version (Component Composition):
+ *   variables: []
+ *   hooks: []
+ *   components: []
+ *   functions: ["buildEdges","collectDependencies","computeBundleHash","extractCodeHeader","findComponentByName","formatBundle","loadContract","loadManifest","pack","readSourceCode","resolveDependency","resolveKey","stableSort","validateHashLock"]
+ *   imports: ["../types/UIFContract.js","../utils/fsx.js","../utils/hash.js","./manifest.js","node:fs/promises","node:path"]
+ *
+ * Logic Signature:
+ *   props: {}
+ *   events: {}
+ *   state: {}
+ *
+ * Predictions:
+ *   Includes form validation logic, Fetches or mutates external data
+ *
+ * Hashes (informational only - authoritative values in .uif.json):
+ *   semantic: uif:70da3ed90cc7516abcbbf13b (informational)
+ *   file: uif:a70a7b698f5520bf49d74a91
+ */
+import type { UIFContract } from '../types/UIFContract.js';
+import type { ProjectManifest, ComponentNode } from './manifest.js';
+/**
+ * Code inclusion mode for bundles
+ */
+export type CodeInclusionMode = 'none' | 'header' | 'full';
+/**
+ * Output format for bundles
+ */
+export type BundleFormat = 'json' | 'pretty' | 'ndjson';
+/**
+ * Options for packing a component
+ */
+export interface PackOptions {
+    depth: number;
+    includeCode: CodeInclusionMode;
+    format: BundleFormat;
+    hashLock: boolean;
+    strict: boolean;
+    allowMissing: boolean;
+    maxNodes: number;
+    contractsMap?: Map<string, UIFContract>;
+}
+/**
+ * A node in the bundle graph
+ */
+export interface BundleNode {
+    entryId: string;
+    contract: UIFContract;
+    codeHeader?: string | null;
+    code?: string | null;
+}
+/**
+ * Missing dependency information
+ */
+export interface MissingDependency {
+    name: string;
+    reason: string;
+    referencedBy?: string;
+}
+/**
+ * Complete bundle structure
+ */
+export interface LogicStampBundle {
+    type: 'LogicStampBundle';
+    schemaVersion: '0.1';
+    entryId: string;
+    depth: number;
+    createdAt: string;
+    bundleHash: string;
+    graph: {
+        nodes: BundleNode[];
+        edges: [string, string][];
+    };
+    meta: {
+        missing: MissingDependency[];
+        source: string;
+    };
+}
+/**
+ * Folder information in the index
+ */
+export interface FolderInfo {
+    path: string;
+    contextFile: string;
+    bundles: number;
+    components: string[];
+    isRoot: boolean;
+    rootLabel?: string;
+    tokenEstimate: number;
+}
+/**
+ * Main index structure - serves as a directory to all context files
+ */
+export interface LogicStampIndex {
+    type: 'LogicStampIndex';
+    schemaVersion: '0.1';
+    projectRoot: string;
+    projectRootResolved?: string;
+    createdAt: string;
+    summary: {
+        totalComponents: number;
+        totalBundles: number;
+        totalFolders: number;
+        totalTokenEstimate: number;
+    };
+    folders: FolderInfo[];
+    meta: {
+        source: string;
+    };
+}
+/**
+ * Load manifest from file
+ */
+export declare function loadManifest(basePath: string): Promise<ProjectManifest>;
+/**
+ * Load a sidecar contract file
+ * Sidecar path is computed from the manifest key (project-relative): resolved from projectRoot + key + '.uif.json'
+ */
+export declare function loadContract(entryId: string, projectRoot: string): Promise<UIFContract | null>;
+/**
+ * Normalize a file path for cross-platform consistency
+ * Re-exports the canonical normalizeEntryId from utils/fsx
+ * This ensures all path normalization uses the same function
+ */
+export { normalizeEntryId } from '../utils/fsx.js';
+/**
+ * Resolve input (path or name) to a manifest key
+ * This is the canonical resolution used by both pack and similar commands
+ */
+export declare function resolveKey(manifest: ProjectManifest, input: string): string | null;
+/**
+ * Find a component node by name or path
+ * Returns the component node and the manifest key it was found under
+ */
+export declare function findComponentByName(manifest: ProjectManifest, nameOrPath: string): ComponentNode | null;
+/**
+ * Resolve a dependency name to a manifest key
+ * Uses the canonical resolveKey() function for consistent resolution
+ * Prioritizes relative paths to avoid cross-directory conflicts
+ */
+export declare function resolveDependency(manifest: ProjectManifest, depName: string, parentId: string): string | null;
+/**
+ * Perform BFS traversal to collect dependencies
+ */
+export declare function collectDependencies(entryId: string, manifest: ProjectManifest, depth: number, maxNodes: number): {
+    visited: Set<string>;
+    missing: MissingDependency[];
+};
+/**
+ * Extract code header (JSDoc @uif block) from source file
+ */
+export declare function extractCodeHeader(entryId: string, projectRoot: string): Promise<string | null>;
+/**
+ * Read full source code
+ */
+export declare function readSourceCode(entryId: string, projectRoot: string): Promise<string | null>;
+/**
+ * Build edges from nodes based on dependencies
+ */
+export declare function buildEdges(nodes: BundleNode[], manifest: ProjectManifest): [string, string][];
+/**
+ * Sort nodes deterministically for stable bundle hashes
+ */
+export declare function stableSort(nodes: BundleNode[]): BundleNode[];
+/**
+ * Compute bundle hash from nodes using stable hashing
+ */
+export declare function computeBundleHash(nodes: BundleNode[], depth: number): string;
+/**
+ * Validate hash-lock: ensure contract hashes match current state
+ *
+ * Recomputes file hash from source and compares to contract.fileHash from sidecar
+ * (authoritative, not from header). fileHash() automatically strips @uif header block
+ * before hashing, so header updates won't cause hash churn.
+ */
+export declare function validateHashLock(contract: UIFContract, entryId: string, projectRoot: string): Promise<boolean>;
+/**
+ * Main pack function - generates a bundle for a component
+ */
+export declare function pack(entryId: string, manifest: ProjectManifest, options: PackOptions, projectRoot: string): Promise<LogicStampBundle>;
+/**
+ * Format bundle for output
+ */
+export declare function formatBundle(bundle: LogicStampBundle, format: BundleFormat): string;
+//# sourceMappingURL=pack.d.ts.map

package/dist/core/pack.d.ts.map

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