@shapeshift-labs/frontier-lang-compiler 0.2.54 → 0.2.55

package/README.md

@@ -19,6 +19,19 @@ const result = compileFrontierSource(source, { target: 'typescript' });
 if (result.ok) console.log(result.output);
 ```
 
+Run a small end-to-end demo after installing or building the package:
+
+```sh
+npm run build
+node examples/native-js-to-rust-demo.mjs
+```
+
+The demo prints JavaScript source, the Frontier universal AST/semantic-index summary,
+Rust declaration stubs, a host-adapter Rust projection, and a direct Frontier-source
+to Rust projection. Native JavaScript projection remains loss-aware: without a
+target adapter the compiler emits review-required stubs rather than claiming a
+lossless JS-to-Rust transpilation.
+
 Emit code with declaration-level source-map sidecars for semantic review and merge admission:
 
 ```js

package/dist/internal/index-impl/createSemanticImportSidecar.js

@@ -18,9 +18,13 @@ export function createSemanticImportSidecar(importResult, options = {}) {
   const proofSpec = summarizeSemanticImportSidecarProofSpec(importEntries);
   const paradigmSemantics = summarizeSemanticImportSidecarParadigmSemantics(importEntries);
   const dependencies = summarizeSemanticImportDependencies(imports);
+  const entryReadiness = importEntries.reduce(
+    (current, entry) => maxSemanticMergeReadiness(current, entry.readiness),
+    lossSummary.semanticMergeReadiness
+  );
   const readiness = mergeCandidates.reduce(
     (current, candidate) => maxSemanticMergeReadiness(current, candidate.readiness),
-    lossSummary.semanticMergeReadiness
+    entryReadiness
   );
   const patchHints = ownershipRegions.map((region) => semanticPatchHintForRegion(region, readiness, options));
   const quality = createSemanticImportSidecarQuality({

package/dist/internal/index-impl/treeSitterDeclaration.js

@@ -1,24 +1,32 @@
-import{declarationRecord}from'./declarationRecord.js';import{nativeNodeId}from'./nativeNodeId.js';import{shortNodeText}from'./shortNodeText.js';import{treeSitterFieldText}from'./treeSitterFieldText.js';
+import{declarationRecord}from'./declarationRecord.js';import{shortNodeText}from'./shortNodeText.js';import{treeSitterChildText,treeSitterFieldText}from'./treeSitterNodeAccess.js';
 export function treeSitterDeclaration(node, kind, nativeNodeId, input) {
   if (/import|include|use/.test(kind)) {
-    const name = treeSitterFieldText(node, 'path') ?? treeSitterFieldText(node, 'source') ?? shortNodeText(node);
+    const name = treeSitterNamedText(node, ['string', 'string_fragment', 'identifier']) ?? shortNodeText(node);
     if (name) return declarationRecord(input, nativeNodeId, name, 'module', 'import');
   }
   if (/function|method|fn_item|function_declaration/.test(kind)) {
-    const name = treeSitterFieldText(node, 'name');
+    const name = treeSitterNamedText(node, ['identifier', 'property_identifier']);
     if (name) return declarationRecord(input, nativeNodeId, name, 'function', 'definition');
   }
   if (/class/.test(kind)) {
-    const name = treeSitterFieldText(node, 'name');
+    const name = treeSitterNamedText(node, ['type_identifier', 'identifier']);
     if (name) return declarationRecord(input, nativeNodeId, name, 'class', 'definition');
   }
   if (/interface/.test(kind)) {
-    const name = treeSitterFieldText(node, 'name');
+    const name = treeSitterNamedText(node, ['type_identifier', 'identifier']);
     if (name) return declarationRecord(input, nativeNodeId, name, 'interface', 'definition');
   }
   if (/struct|enum|type/.test(kind)) {
-    const name = treeSitterFieldText(node, 'name');
+    const name = treeSitterNamedText(node, ['type_identifier', 'identifier']);
     if (name) return declarationRecord(input, nativeNodeId, name, 'type', 'definition');
   }
+  if (/variable_declarator|property_declaration|field_declaration/.test(kind)) {
+    const name = treeSitterNamedText(node, ['identifier', 'property_identifier', 'field_identifier']);
+    if (name) return declarationRecord(input, nativeNodeId, name, 'variable', 'definition');
+  }
   return undefined;
 }
+
+function treeSitterNamedText(node, childKinds) {
+  return treeSitterFieldText(node, 'name') ?? treeSitterFieldText(node, 'declarator') ?? treeSitterChildText(node, childKinds);
+}

package/dist/internal/index-impl/treeSitterFieldText.js

@@ -1,5 +1 @@
-import{shortNodeText}from'./shortNodeText.js';
-export function treeSitterFieldText(node, field) {
-  if (typeof node.childForFieldName !== 'function') return undefined;
-  return shortNodeText(node.childForFieldName(field));
-}
+export{treeSitterFieldText}from'./treeSitterNodeAccess.js';

package/dist/internal/index-impl/treeSitterNodeAccess.js

@@ -0,0 +1,75 @@
+import{shortNodeText}from'./shortNodeText.js';
+export function treeSitterNodeKind(node) {
+  return String(node?.type ?? node?.kind ?? 'node');
+}
+
+export function treeSitterChildren(node) {
+  const children = treeSitterArrayChildren(node, 'children');
+  if (children.length) return children;
+  const childCountChildren = treeSitterIndexedChildren(node, 'childCount', 'child');
+  if (childCountChildren.length) return childCountChildren;
+  const namedChildren = treeSitterArrayChildren(node, 'namedChildren');
+  if (namedChildren.length) return namedChildren;
+  return treeSitterIndexedChildren(node, 'namedChildCount', 'namedChild');
+}
+
+export function treeSitterChildText(node, kinds) {
+  const wanted = new Set(kinds);
+  const stack = [...treeSitterChildren(node)];
+  while (stack.length) {
+    const child = stack.shift();
+    if (!child || typeof child !== 'object') continue;
+    if (wanted.has(treeSitterNodeKind(child))) {
+      const text = shortNodeText(child);
+      if (text) return text;
+    }
+    stack.unshift(...treeSitterChildren(child));
+  }
+  return undefined;
+}
+
+export function treeSitterFieldText(node, field) {
+  const exact = treeSitterFieldNode(node, field);
+  if (exact) return shortNodeText(exact);
+  return treeSitterNamedFieldText(node, field);
+}
+
+function treeSitterFieldNode(node, field) {
+  if (typeof node?.childForFieldName === 'function') return node.childForFieldName(field);
+  if (typeof node?.child_by_field_name === 'function') return node.child_by_field_name(field);
+  return undefined;
+}
+
+function treeSitterNamedFieldText(node, field) {
+  for (const child of treeSitterChildren(node)) {
+    if (treeSitterFieldName(child) === field) {
+      const text = shortNodeText(child);
+      if (text) return text;
+    }
+  }
+  return undefined;
+}
+
+function treeSitterFieldName(node) {
+  if (typeof node?.fieldName === 'string') return node.fieldName;
+  if (typeof node?.field_name === 'string') return node.field_name;
+  if (typeof node?.fieldName === 'function') return node.fieldName();
+  if (typeof node?.field_name === 'function') return node.field_name();
+  return undefined;
+}
+
+function treeSitterArrayChildren(node, field) {
+  const value = node?.[field];
+  return Array.isArray(value) ? value.filter((child) => child && typeof child === 'object') : [];
+}
+
+function treeSitterIndexedChildren(node, countField, childMethod) {
+  const count = Number(node?.[countField]);
+  if (!Number.isFinite(count) || count <= 0 || typeof node?.[childMethod] !== 'function') return [];
+  const children = [];
+  for (let index = 0; index < count; index += 1) {
+    const child = node[childMethod](index);
+    if (child && typeof child === 'object') children.push(child);
+  }
+  return children;
+}

package/dist/internal/index-impl/visitTreeSitterNode.js

@@ -1,5 +1,5 @@
 import{idFragment}from'../../native-import-utils.js';
-import{nativeNodeId}from'./nativeNodeId.js';import{numberOrUndefined}from'./numberOrUndefined.js';import{shortNodeText}from'./shortNodeText.js';import{spanFromTreeSitterNode}from'./spanFromTreeSitterNode.js';import{treeSitterDeclaration}from'./treeSitterDeclaration.js';
+import{nativeNodeId}from'./nativeNodeId.js';import{numberOrUndefined}from'./numberOrUndefined.js';import{shortNodeText}from'./shortNodeText.js';import{spanFromTreeSitterNode}from'./spanFromTreeSitterNode.js';import{treeSitterDeclaration}from'./treeSitterDeclaration.js';import{treeSitterChildren,treeSitterNodeKind}from'./treeSitterNodeAccess.js';
 export function visitTreeSitterNode(node, context, propertyPath, depth = 0) {
   if (!node || typeof node !== 'object' || context.truncated) return undefined;
   if (context.objectIds.has(node)) return context.objectIds.get(node);
@@ -8,7 +8,7 @@ export function visitTreeSitterNode(node, context, propertyPath, depth = 0) {
     return undefined;
   }
   context.counter += 1;
-  const kind = String(node.type ?? node.kind ?? 'node');
+  const kind = treeSitterNodeKind(node);
   const span = spanFromTreeSitterNode(node, context.input);
   const id = nativeNodeId(context, kind, { start: { line: span?.startLine, column: span?.startColumn } }, propertyPath);
   context.objectIds.set(node, id);
@@ -82,32 +82,6 @@ export function visitTreeSitterNode(node, context, propertyPath, depth = 0) {
   return id;
 }
 
-function treeSitterChildren(node) {
-  const children = treeSitterArrayChildren(node, 'children');
-  if (children.length) return children;
-  const childCountChildren = treeSitterIndexedChildren(node, 'childCount', 'child');
-  if (childCountChildren.length) return childCountChildren;
-  const namedChildren = treeSitterArrayChildren(node, 'namedChildren');
-  if (namedChildren.length) return namedChildren;
-  return treeSitterIndexedChildren(node, 'namedChildCount', 'namedChild');
-}
-
-function treeSitterArrayChildren(node, field) {
-  const value = node[field];
-  return Array.isArray(value) ? value.filter((child) => child && typeof child === 'object') : [];
-}
-
-function treeSitterIndexedChildren(node, countField, childMethod) {
-  const count = Number(node[countField]);
-  if (!Number.isFinite(count) || count <= 0 || typeof node[childMethod] !== 'function') return [];
-  const children = [];
-  for (let index = 0; index < count; index += 1) {
-    const child = node[childMethod](index);
-    if (child && typeof child === 'object') children.push(child);
-  }
-  return children;
-}
-
 function treeSitterBoolean(node, ...fields) {
   for (const field of fields) {
     const value = node[field];

package/dist/semantic-import-sidecar-entry.js

@@ -18,6 +18,7 @@ function semanticImportSidecarEntry(imported, index, options) {
   const proofSpec = summarizeProofSpecLayer(imported?.universalAst?.proof ?? imported?.proof);
   const paradigmSemantics = summarizeParadigmSemanticsLayer(imported?.universalAst?.paradigmSemantics ?? imported?.paradigmSemantics);
   const dependencies = summarizeSemanticImportDependencyRelations(semanticIndex?.relations ?? []);
+  const readiness = semanticImportEntryReadiness(imported);
   const mappingsBySymbolId = new Map();
   for (const mapping of sourceMapMappings) {
     if (mapping.semanticSymbolId && !mappingsBySymbolId.has(mapping.semanticSymbolId)) {
@@ -44,7 +45,7 @@ function semanticImportSidecarEntry(imported, index, options) {
       ownershipRegionId: region.id,
       ownershipKey: region.key,
       ownershipRegionKind: region.regionKind,
-      readiness: imported?.metadata?.semanticMergeReadiness ?? imported?.mergeCandidates?.[0]?.readiness ?? 'needs-review'
+      readiness
     });
   }
   const ownershipRegions = uniqueRecordsById(regions);
@@ -71,7 +72,7 @@ function semanticImportSidecarEntry(imported, index, options) {
     paradigmSemantics,
     dependencyRelationCount: dependencies.total,
     dependencyPredicates: dependencies.predicates,
-    readiness: imported?.metadata?.semanticMergeReadiness ?? imported?.mergeCandidates?.[0]?.readiness ?? 'needs-review',
+    readiness,
     emptySemanticIndex: symbols.length === 0,
     regionTaxonomy,
     symbols,
@@ -79,4 +80,14 @@ function semanticImportSidecarEntry(imported, index, options) {
   };
 }
 
+function semanticImportEntryReadiness(imported) {
+  const readiness = imported?.metadata?.semanticMergeReadiness
+    ?? imported?.metadata?.nativeImportLossSummary?.semanticMergeReadiness
+    ?? imported?.readiness?.semanticMergeReadiness
+    ?? imported?.readiness?.readiness
+    ?? (typeof imported?.readiness === 'string' ? imported.readiness : undefined)
+    ?? imported?.mergeCandidates?.[0]?.readiness;
+  return readiness ?? 'needs-review';
+}
+
 export { semanticImportSidecarEntry };

package/examples/native-js-to-rust-demo.mjs

@@ -0,0 +1,148 @@
+import {
+  compileFrontierSource,
+  compileNativeSource,
+  importNativeSource,
+  writeUniversalAstJson
+} from '../dist/index.js';
+
+const javascriptSource = `import { nanoid } from "nanoid";
+
+export function addTodo(title) {
+  return { id: nanoid(), title };
+}
+
+export class TodoStore {
+  save(title) {
+    return addTodo(title);
+  }
+}
+`;
+
+const imported = importNativeSource({
+  language: 'javascript',
+  sourcePath: 'src/todo.js',
+  sourceText: javascriptSource
+});
+
+const graphSummary = {
+  universalAst: imported.universalAst.kind,
+  semanticIndexId: imported.semanticIndex.id,
+  symbols: imported.semanticIndex.symbols.map((symbol) => ({
+    name: symbol.name,
+    kind: symbol.kind,
+    region: symbol.metadata?.ownershipRegionKind
+  })),
+  sourceMapMappings: imported.sourceMaps[0]?.mappings.length ?? 0,
+  mergeReadiness: imported.metadata.nativeImportLossSummary.semanticMergeReadiness,
+  losses: imported.losses.map((loss) => loss.kind)
+};
+
+console.log('--- JavaScript source ---');
+console.log(javascriptSource.trim());
+console.log('\n--- Frontier graph summary ---');
+console.log(JSON.stringify(graphSummary, null, 2));
+console.log('\n--- Universal AST envelope excerpt ---');
+console.log(JSON.stringify(universalAstExcerpt(imported), null, 2));
+
+const stubProjection = compileNativeSource(imported, {
+  target: 'rust',
+  targetPath: 'src/todo.rs'
+});
+
+console.log('\n--- Rust declaration stubs without a target adapter ---');
+console.log(`ok=${stubProjection.ok} readiness=${stubProjection.readiness.readiness} mode=${stubProjection.outputMode}`);
+console.log(stubProjection.output.trim());
+
+const adapterProjection = compileNativeSource(imported, {
+  target: 'rust',
+  targetPath: 'src/todo.rs',
+  targetAdapters: [createDemoJsToRustAdapter()]
+});
+
+console.log('\n--- Rust output with a host-owned target adapter ---');
+console.log(`ok=${adapterProjection.ok} readiness=${adapterProjection.readiness.readiness} mode=${adapterProjection.outputMode}`);
+console.log(adapterProjection.output.trim());
+
+const frontierSource = `module TodoApp @id("mod_todo")
+
+type TodoInput @id("type_todo_input") {
+  title: Text
+}
+
+entity Todo @id("ent_todo") {
+  title @id("field_title"): Text
+}
+
+action addTodo @id("action_add") {
+  input TodoInput
+  writes field_title
+  returns Patch
+}
+`;
+
+const canonicalRust = compileFrontierSource(frontierSource, { target: 'rust' });
+
+console.log('\n--- Frontier source projected directly to Rust ---');
+console.log(`ok=${canonicalRust.ok} target=${canonicalRust.target}`);
+console.log(canonicalRust.output.trim());
+
+function universalAstExcerpt(importResult) {
+  const parsed = JSON.parse(writeUniversalAstJson(importResult.universalAst));
+  return {
+    kind: parsed.kind,
+    id: parsed.id,
+    documentCount: parsed.documents?.length ?? 0,
+    symbolCount: parsed.semanticIndex?.symbols?.length ?? 0,
+    sourceMapCount: parsed.sourceMaps?.length ?? 0
+  };
+}
+
+function createDemoJsToRustAdapter() {
+  return {
+    id: 'demo-js-to-rust-target-adapter',
+    sourceLanguage: 'javascript',
+    target: 'rust',
+    version: '0.0.0-demo',
+    capabilities: ['declaration-stubs'],
+    coverage: {
+      readiness: 'ready',
+      handledLossKinds: ['opaqueNative', 'declarationOnlyCoverage', 'partialSemanticIndex', 'sourceMapApproximation', 'sourcePreservation'],
+      notes: ['Demo adapter turns Frontier semantic symbols into deterministic Rust scaffolding.']
+    },
+    project(input) {
+      const symbols = input.importResult.semanticIndex?.symbols ?? [];
+      return {
+        output: renderRustScaffold(symbols),
+        readiness: 'ready',
+        evidence: [{
+          id: 'evidence_demo_js_to_rust_adapter',
+          kind: 'projection',
+          status: 'passed',
+          summary: 'Demo adapter projected JavaScript semantic symbols to Rust scaffolding.'
+        }]
+      };
+    }
+  };
+}
+
+function renderRustScaffold(symbols) {
+  const lines = ['// Generated from Frontier semantic graph evidence.'];
+  for (const symbol of symbols) {
+    if (symbol.kind === 'class') {
+      lines.push(`pub struct ${symbol.name};`, '');
+    } else if (symbol.kind === 'function' || symbol.kind === 'method') {
+      lines.push(`pub fn ${rustName(symbol.name)}() {`);
+      lines.push('    todo!("port body from native source evidence");');
+      lines.push('}', '');
+    }
+  }
+  return `${lines.join('\n').trim()}\n`;
+}
+
+function rustName(name) {
+  return String(name)
+    .replace(/\./g, '_')
+    .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
+    .replace(/[^A-Za-z0-9_]/g, '_')
+    .toLowerCase();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shapeshift-labs/frontier-lang-compiler",
-  "version": "0.2.54",
+  "version": "0.2.55",
   "description": "Compiler facade for Frontier Lang source documents and language projection adapters.",
   "type": "module",
   "main": "./dist/index.js",