@shapeshift-labs/frontier-lang-compiler 0.2.107 → 0.2.109

package/README.md

@@ -187,6 +187,27 @@ artifacts keep `autoMergeClaim: false` and `semanticEquivalenceClaim: false`,
 but give coordinators machine-readable proof that the projected source matches
 the merge output and that applying the same projection again is a no-op.
 
+Project-level JS/TS safe merges compose the same file-level gates across a
+base/worker/head file set. They preserve head-only files, admit worker-only
+file additions when file additions are enabled, block conflicting same-path
+additions, and attach per-file semantic artifacts for files merged through the
+JS/TS source merger:
+
+```js
+import { safeMergeJsTsProject } from '@shapeshift-labs/frontier-lang-compiler';
+
+const project = safeMergeJsTsProject({
+  language: 'typescript',
+  baseFiles: { 'src/index.ts': 'export const stable = 1;\n' },
+  workerFiles: { 'src/index.ts': 'export const stable = 1;\nexport const workerOnly = 1;\n' },
+  headFiles: { 'src/index.ts': 'export const stable = 1;\n' }
+});
+
+console.log(project.status); // "merged"
+console.log(project.outputFiles[0].sourcePath); // "src/index.ts"
+console.log(project.files[0].semanticArtifacts.status); // "verified"
+```
+
 High-risk native features also have explicit evidence policies. These policies are advisory in this package: they tell a swarm or admission queue what evidence is missing without silently changing the existing readiness classification.
 
 ```js

package/dist/declarations/js-ts-safe-project-merge.d.ts

@@ -0,0 +1,128 @@
+import type { FrontierSourceLanguage } from '@shapeshift-labs/frontier-lang-kernel';
+import type {
+  JsTsSafeMergeAdmission,
+  JsTsSafeMergeConflict,
+  JsTsSafeMergeResult,
+  JsTsSafeMergeSemanticArtifacts,
+  JsTsSafeMergeSummary
+} from './js-ts-safe-merge.js';
+import type { JsTsSafeMemberMergePolicy, JsTsSafeMemberMergePolicyRegion } from './js-ts-safe-member-merge.js';
+
+export type JsTsProjectSafeMergeStatus = 'merged' | 'blocked';
+export type JsTsProjectSafeMergeFileStatus = 'merged' | 'blocked';
+export type JsTsProjectSafeMergeFileOperation =
+  | 'merged-source'
+  | 'merged-source-and-members'
+  | 'worker-added'
+  | 'head-only'
+  | 'both-added-identical'
+  | 'worker-deleted'
+  | 'head-deleted-worker-unchanged'
+  | 'blocked-merge'
+  | 'blocked-file-presence'
+  | string;
+
+export interface JsTsProjectSafeMergeFileInput {
+  readonly sourcePath?: string;
+  readonly path?: string;
+  readonly language?: FrontierSourceLanguage | string;
+  readonly baseSourceText?: string;
+  readonly baseText?: string;
+  readonly workerSourceText?: string;
+  readonly workerText?: string;
+  readonly headSourceText?: string;
+  readonly headText?: string;
+  readonly workerDeleted?: boolean;
+  readonly headDeleted?: boolean;
+  readonly policy?: JsTsSafeMemberMergePolicy | readonly JsTsSafeMemberMergePolicyRegion[];
+  readonly mergePolicy?: JsTsSafeMemberMergePolicy | readonly JsTsSafeMemberMergePolicyRegion[];
+}
+
+export type JsTsProjectSafeMergeFileMap =
+  | Readonly<Record<string, string>>
+  | ReadonlyMap<string, string>
+  | readonly { readonly sourcePath?: string; readonly path?: string; readonly sourceText?: string; readonly text?: string }[];
+
+export interface JsTsProjectSafeMergeInput {
+  readonly id?: string;
+  readonly language?: FrontierSourceLanguage | string;
+  readonly projectRoot?: string;
+  readonly files?: readonly JsTsProjectSafeMergeFileInput[];
+  readonly baseFiles?: JsTsProjectSafeMergeFileMap;
+  readonly workerFiles?: JsTsProjectSafeMergeFileMap;
+  readonly headFiles?: JsTsProjectSafeMergeFileMap;
+  readonly allowFileAdditions?: boolean;
+  readonly allowFileDeletes?: boolean;
+  readonly workerChangeSetId?: string;
+  readonly headChangeSetId?: string;
+  readonly policy?: JsTsSafeMemberMergePolicy | readonly JsTsSafeMemberMergePolicyRegion[];
+  readonly mergePolicy?: JsTsSafeMemberMergePolicy | readonly JsTsSafeMemberMergePolicyRegion[];
+  readonly policyByPath?: Readonly<Record<string, JsTsSafeMemberMergePolicy | readonly JsTsSafeMemberMergePolicyRegion[]>>;
+  readonly mergePolicyByPath?: Readonly<Record<string, JsTsSafeMemberMergePolicy | readonly JsTsSafeMemberMergePolicyRegion[]>>;
+  readonly requireSourceLedgerSpans?: boolean;
+  readonly sourceLedgers?: Record<string, unknown>;
+  readonly sourceLedgersByPath?: Record<string, Record<string, unknown>>;
+}
+
+export interface JsTsProjectSafeMergeOutputFile {
+  readonly sourcePath: string;
+  readonly language?: FrontierSourceLanguage | string;
+  readonly sourceText: string;
+  readonly sourceHash?: string;
+  readonly operation: JsTsProjectSafeMergeFileOperation;
+}
+
+export interface JsTsProjectSafeMergeFileResult {
+  readonly kind: 'frontier.lang.jsTsProjectSafeMergeFile';
+  readonly version: 1;
+  readonly sourcePath?: string;
+  readonly language?: FrontierSourceLanguage | string;
+  readonly status: JsTsProjectSafeMergeFileStatus;
+  readonly operation: JsTsProjectSafeMergeFileOperation;
+  readonly outputSourceText?: string;
+  readonly outputHash?: string;
+  readonly baseHash?: string;
+  readonly workerHash?: string;
+  readonly headHash?: string;
+  readonly result?: JsTsSafeMergeResult;
+  readonly semanticArtifacts?: JsTsSafeMergeSemanticArtifacts;
+  readonly conflicts: readonly JsTsSafeMergeConflict[];
+  readonly admission: JsTsSafeMergeAdmission;
+  readonly summary?: JsTsSafeMergeSummary | Record<string, unknown>;
+  readonly conflictKeys: readonly string[];
+}
+
+export interface JsTsProjectSafeMergeAdmission {
+  readonly status: 'auto-merge-candidate' | 'blocked' | string;
+  readonly action: 'apply-project' | 'human-review' | string;
+  readonly reviewRequired: boolean;
+  readonly autoApplyCandidate: boolean;
+  readonly autoMergeClaim: false;
+  readonly semanticEquivalenceClaim: false;
+  readonly reasonCodes: readonly string[];
+  readonly conflictKeys: readonly string[];
+}
+
+export interface JsTsProjectSafeMergeResult {
+  readonly kind: 'frontier.lang.jsTsProjectSafeMerge';
+  readonly version: 1;
+  readonly schema: 'frontier.lang.jsTsProjectSafeMerge.v1';
+  readonly id: string;
+  readonly hash: string;
+  readonly status: JsTsProjectSafeMergeStatus;
+  readonly files: readonly JsTsProjectSafeMergeFileResult[];
+  readonly outputFiles: readonly JsTsProjectSafeMergeOutputFile[];
+  readonly conflicts: readonly JsTsSafeMergeConflict[];
+  readonly admission: JsTsProjectSafeMergeAdmission;
+  readonly summary: {
+    readonly files: number;
+    readonly mergedFiles: number;
+    readonly blockedFiles: number;
+    readonly outputFiles: number;
+    readonly semanticArtifactFiles: number;
+    readonly operations: Readonly<Record<string, number>>;
+  };
+  readonly metadata?: Record<string, unknown>;
+}
+
+export declare function safeMergeJsTsProject(input?: JsTsProjectSafeMergeInput): JsTsProjectSafeMergeResult;

package/dist/declarations/js-ts-semantic-merge.d.ts

@@ -1,4 +1,5 @@
 export * from './js-ts-safe-merge.js';
+export * from './js-ts-safe-project-merge.js';
 export * from './js-ts-safe-member-merge.js';
 export * from './js-ts-semantic-merge-contracts.js';
 export * from './js-ts-semantic-conflict-sidecars.js';

package/dist/declarations/native-project.d.ts

@@ -78,8 +78,6 @@ export interface ImportNativeProjectOptions {
 }
 
 export type NativeProjectSymbolGraphRemainingField =
-  | 'moduleEdges[].resolvedModulePath'
-  | 'moduleEdges[].targetDocumentId'
   | 'moduleEdges[].resolvedTargetSymbolId'
   | 'moduleEdges[].resolutionKind'
   | 'moduleEdges[].packageName'
@@ -112,6 +110,9 @@ export interface NativeProjectSymbolGraphModuleEdgeRecord {
   readonly sourcePath?: string;
   readonly sourceHash?: string;
   readonly moduleSpecifier?: string;
+  readonly resolvedModulePath?: string;
+  readonly targetDocumentId?: string;
+  readonly resolutionKind?: 'relative-source' | 'relative-missing' | string;
   readonly importKind?: string;
   readonly exportKind?: string;
   readonly importedName?: string;

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

@@ -1,5 +1,6 @@
 import{idFragment,uniqueByEvidenceId,uniqueByLossId,uniqueStrings}from'../../native-import-utils.js';import{createDocument,createPatch,createUniversalAstEnvelope}from'@shapeshift-labs/frontier-lang-kernel';
 import{createNativeImportResultContract}from'./createNativeImportResultContract.js';import{createProjectImportAdmissionRecord}from'./createProjectImportAdmissionRecord.js';import{mergeSemanticIndexes}from'./mergeSemanticIndexes.js';import{summarizeNativeImportLosses}from'./summarizeNativeImportLosses.js';import{summarizeProjectSourcePreservation}from'./summarizeProjectSourcePreservation.js';
+import{resolveRelativeProjectModule}from'./projectSymbolGraphModuleResolution.js';
 export function createNativeProjectImportResult(input, imports) {
   const idPart = idFragment(input.id ?? input.projectRoot ?? 'native_project');
   const nodes = {};
@@ -140,8 +141,6 @@ export function createNativeProjectImportResult(input, imports) {
 }
 
 const PROJECT_SYMBOL_GRAPH_REMAINING_FIELDS = Object.freeze([
-  'moduleEdges[].resolvedModulePath',
-  'moduleEdges[].targetDocumentId',
   'moduleEdges[].resolvedTargetSymbolId',
   'moduleEdges[].resolutionKind',
   'moduleEdges[].packageName',
@@ -158,16 +157,17 @@ function createProjectSymbolGraphSummary(semanticIndex, imports, input) {
   const documents = semanticIndex?.documents ?? [];
   const symbolsById = new Map((semanticIndex?.symbols ?? []).map((symbol) => [symbol.id, symbol]));
   const documentsById = new Map(documents.map((document) => [document.id, document]));
+  const documentsByPath = new Map(documents.filter((document) => document.path).map((document) => [document.path, document]));
   const facts = semanticIndex?.facts ?? [];
   const moduleEdgeFacts = facts.filter((fact) => fact.predicate === 'moduleEdge');
   const moduleEdgeByRelation = new Map(moduleEdgeFacts.map((fact) => [fact.subjectId, fact]));
   const relations = semanticIndex?.relations ?? [];
   const importEdges = relations
     .filter((relation) => relation.predicate === 'imports')
-    .map((relation) => moduleEdgeRecord(relation, moduleEdgeByRelation, symbolsById, documentsById));
+    .map((relation) => moduleEdgeRecord(relation, moduleEdgeByRelation, symbolsById, documentsById, documentsByPath));
   const exportEdges = relations
     .filter((relation) => relation.predicate === 'exports')
-    .map((relation) => moduleEdgeRecord(relation, moduleEdgeByRelation, symbolsById, documentsById));
+    .map((relation) => moduleEdgeRecord(relation, moduleEdgeByRelation, symbolsById, documentsById, documentsByPath));
   const reExportIdentities = uniqueRecords([
     ...facts
       .filter((fact) => fact.predicate === 'reExportIdentity' && fact.value)
@@ -213,7 +213,7 @@ function createProjectSymbolGraphSummary(semanticIndex, imports, input) {
   };
 }
 
-function moduleEdgeRecord(relation, moduleEdgeByRelation, symbolsById, documentsById) {
+function moduleEdgeRecord(relation, moduleEdgeByRelation, symbolsById, documentsById, documentsByPath) {
   const fact = moduleEdgeByRelation.get(relation.id);
   const value = objectValue(fact?.value);
   const metadata = objectValue(relation.metadata);
@@ -228,6 +228,7 @@ function moduleEdgeRecord(relation, moduleEdgeByRelation, symbolsById, documents
     symbolMetadata.moduleSpecifier,
     symbol?.kind === 'module' ? symbol.name : undefined
   );
+  const resolution = resolveRelativeProjectModule(document?.path, moduleSpecifier, documentsByPath);
   return compactRecord({
     id: relation.id,
     sourceDocumentId: relation.sourceId,
@@ -237,6 +238,9 @@ function moduleEdgeRecord(relation, moduleEdgeByRelation, symbolsById, documents
     sourcePath: document?.path,
     sourceHash: document?.sourceHash,
     moduleSpecifier,
+    resolvedModulePath: resolution?.path,
+    targetDocumentId: resolution?.documentId,
+    resolutionKind: resolution?.kind,
     importKind: firstString(moduleEdge.importKind, value.importKind),
     exportKind: firstString(moduleEdge.exportKind, value.exportKind),
     importedName: firstString(moduleEdge.importedName, value.importedName),

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

@@ -0,0 +1,33 @@
+export function resolveRelativeProjectModule(sourcePath, moduleSpecifier, documentsByPath) {
+  if (!sourcePath || !moduleSpecifier || !moduleSpecifier.startsWith('.')) return undefined;
+  const base = sourcePath.includes('/') ? sourcePath.slice(0, sourcePath.lastIndexOf('/')) : '';
+  const unresolvedPath = normalizeProjectPath(`${base}/${moduleSpecifier}`);
+  const target = moduleTargetDocument(unresolvedPath, documentsByPath);
+  return {
+    path: target?.path ?? unresolvedPath,
+    documentId: target?.id,
+    kind: target ? 'relative-source' : 'relative-missing'
+  };
+}
+
+function moduleTargetDocument(path, documentsByPath) {
+  for (const candidate of modulePathCandidates(path)) {
+    const document = documentsByPath.get(candidate);
+    if (document) return document;
+  }
+  return undefined;
+}
+
+function modulePathCandidates(path) {
+  return [path, `${path}.js`, `${path}.ts`, `${path}.tsx`, `${path}.jsx`, `${path}/index.js`, `${path}/index.ts`];
+}
+
+function normalizeProjectPath(path) {
+  const parts = [];
+  for (const part of String(path).split('/')) {
+    if (!part || part === '.') continue;
+    if (part === '..') parts.pop();
+    else parts.push(part);
+  }
+  return parts.join('/');
+}

package/dist/js-ts-safe-project-merge.js

@@ -0,0 +1,288 @@
+import { hashSemanticValue } from '@shapeshift-labs/frontier-lang-kernel';
+import { safeMergeJsTsSource } from './js-ts-safe-merge-composed.js';
+import { compactRecord } from './js-ts-safe-merge-context.js';
+
+function safeMergeJsTsProject(input = {}) {
+  const id = String(input.id ?? 'js_ts_project_safe_merge');
+  const files = normalizeProjectFiles(input);
+  const fileResults = files.map((file) => mergeProjectFile(file, input, id));
+  const blockedFiles = fileResults.filter((file) => file.status === 'blocked');
+  const status = blockedFiles.length ? 'blocked' : 'merged';
+  const outputFiles = fileResults
+    .filter((file) => typeof file.outputSourceText === 'string')
+    .map((file) => compactRecord({
+      sourcePath: file.sourcePath,
+      language: file.language,
+      sourceText: file.outputSourceText,
+      sourceHash: file.outputHash,
+      operation: file.operation
+    }));
+  const reasonCodes = uniqueStrings(blockedFiles.flatMap((file) => file.admission.reasonCodes));
+  const core = {
+    kind: 'frontier.lang.jsTsProjectSafeMerge',
+    version: 1,
+    schema: 'frontier.lang.jsTsProjectSafeMerge.v1',
+    id,
+    status,
+    files: fileResults,
+    outputFiles,
+    conflicts: fileResults.flatMap((file) => file.conflicts),
+    admission: {
+      status: status === 'merged' ? 'auto-merge-candidate' : 'blocked',
+      action: status === 'merged' ? 'apply-project' : 'human-review',
+      reviewRequired: status !== 'merged',
+      autoApplyCandidate: status === 'merged',
+      autoMergeClaim: false,
+      semanticEquivalenceClaim: false,
+      reasonCodes,
+      conflictKeys: uniqueStrings(fileResults.flatMap((file) => file.conflictKeys))
+    },
+    summary: projectSummary(fileResults),
+    metadata: compactRecord({
+      workerChangeSetId: input.workerChangeSetId,
+      headChangeSetId: input.headChangeSetId,
+      projectRoot: input.projectRoot,
+      filesInput: Array.isArray(input.files) ? 'records' : 'maps',
+      autoMergeClaim: false,
+      semanticEquivalenceClaim: false
+    })
+  };
+  return { ...core, hash: hashSemanticValue(core) };
+}
+
+function mergeProjectFile(file, input, projectId) {
+  const base = file.baseSourceText;
+  const worker = file.workerDeleted ? undefined : file.workerSourceText ?? base;
+  const head = file.headDeleted ? undefined : file.headSourceText ?? base;
+  const context = { sourcePath: file.sourcePath, language: file.language ?? input.language ?? 'typescript' };
+  if (!file.sourcePath) return blockedFile(file, context, 'missing-source-path');
+  if (base === undefined && worker === undefined && head !== undefined) {
+    return syntheticFile(file, context, head, 'head-only');
+  }
+  if (base === undefined && worker !== undefined && head === undefined) {
+    return input.allowFileAdditions === false
+      ? blockedFile(file, context, 'worker-file-addition-disabled')
+      : syntheticFile(file, context, worker, 'worker-added');
+  }
+  if (base === undefined && worker !== undefined && head !== undefined) {
+    return worker === head
+      ? syntheticFile(file, context, worker, 'both-added-identical')
+      : blockedFile(file, context, 'file-add-conflict');
+  }
+  if (base !== undefined && worker === undefined) {
+    return input.allowFileDeletes
+      ? syntheticFile(file, context, undefined, 'worker-deleted')
+      : blockedFile(file, context, 'worker-file-delete-blocked');
+  }
+  if (base !== undefined && head === undefined) {
+    return worker === base
+      ? syntheticFile(file, context, undefined, 'head-deleted-worker-unchanged')
+      : blockedFile(file, context, 'head-file-delete-conflict');
+  }
+  const result = safeMergeJsTsSource({
+    ...input,
+    ...context,
+    id: `${projectId}_${safeId(file.sourcePath)}`,
+    baseSourceText: base,
+    workerSourceText: worker,
+    headSourceText: head,
+    sourceLedgers: sourceLedgersForFile(input, file.sourcePath),
+    policy: file.policy ?? file.mergePolicy ?? policyForFile(input, file.sourcePath)
+  });
+  if (result.status !== 'merged') return mergeBlockedFile(file, context, result);
+  return compactRecord({
+    kind: 'frontier.lang.jsTsProjectSafeMergeFile',
+    version: 1,
+    sourcePath: file.sourcePath,
+    language: context.language,
+    status: 'merged',
+    operation: result.summary.memberAdditions ? 'merged-source-and-members' : 'merged-source',
+    outputSourceText: result.mergedSourceText,
+    outputHash: hashText(result.mergedSourceText),
+    baseHash: hashText(base),
+    workerHash: hashText(worker),
+    headHash: hashText(head),
+    result,
+    semanticArtifacts: result.semanticArtifacts,
+    conflicts: [],
+    admission: result.admission,
+    summary: result.summary,
+    conflictKeys: [`source#${file.sourcePath}`]
+  });
+}
+
+function mergeBlockedFile(file, context, result) {
+  return compactRecord({
+    kind: 'frontier.lang.jsTsProjectSafeMergeFile',
+    version: 1,
+    sourcePath: file.sourcePath,
+    language: context.language,
+    status: 'blocked',
+    operation: 'blocked-merge',
+    result,
+    conflicts: result.conflicts ?? [],
+    admission: result.admission,
+    summary: result.summary,
+    conflictKeys: [`source#${file.sourcePath}`]
+  });
+}
+
+function syntheticFile(file, context, sourceText, operation) {
+  return compactRecord({
+    kind: 'frontier.lang.jsTsProjectSafeMergeFile',
+    version: 1,
+    sourcePath: file.sourcePath,
+    language: context.language,
+    status: 'merged',
+    operation,
+    outputSourceText: sourceText,
+    outputHash: hashText(sourceText),
+    baseHash: hashText(file.baseSourceText),
+    workerHash: hashText(file.workerSourceText),
+    headHash: hashText(file.headSourceText),
+    conflicts: [],
+    admission: admittedSyntheticAdmission(operation),
+    summary: { conflicts: 0, synthetic: true },
+    conflictKeys: [`source#${file.sourcePath}`]
+  });
+}
+
+function blockedFile(file, context, reasonCode) {
+  const conflict = {
+    code: reasonCode,
+    gateId: 'project-file-presence',
+    message: `Project file cannot be safely merged: ${reasonCode}.`,
+    sourcePath: file.sourcePath,
+    details: { sourcePath: file.sourcePath }
+  };
+  return compactRecord({
+    kind: 'frontier.lang.jsTsProjectSafeMergeFile',
+    version: 1,
+    sourcePath: file.sourcePath,
+    language: context.language,
+    status: 'blocked',
+    operation: 'blocked-file-presence',
+    conflicts: [conflict],
+    admission: blockedAdmission(reasonCode),
+    summary: { conflicts: 1, synthetic: true },
+    conflictKeys: [`source#${file.sourcePath ?? 'unknown'}`]
+  });
+}
+
+function normalizeProjectFiles(input) {
+  if (Array.isArray(input.files)) return input.files.map(normalizeFileRecord).sort(bySourcePath);
+  const base = normalizeFileMap(input.baseFiles);
+  const worker = normalizeFileMap(input.workerFiles);
+  const head = normalizeFileMap(input.headFiles);
+  const paths = [...new Set([...base.keys(), ...worker.keys(), ...head.keys()])].sort();
+  return paths.map((sourcePath) => normalizeFileRecord({
+    sourcePath,
+    baseSourceText: base.get(sourcePath),
+    workerSourceText: worker.get(sourcePath),
+    headSourceText: head.get(sourcePath)
+  }));
+}
+
+function normalizeFileRecord(record = {}) {
+  return {
+    sourcePath: record.sourcePath ?? record.path,
+    language: record.language,
+    baseSourceText: stringOrUndefined(record.baseSourceText ?? record.baseText),
+    workerSourceText: stringOrUndefined(record.workerSourceText ?? record.workerText),
+    headSourceText: stringOrUndefined(record.headSourceText ?? record.headText),
+    workerDeleted: record.workerDeleted === true,
+    headDeleted: record.headDeleted === true,
+    policy: record.policy,
+    mergePolicy: record.mergePolicy
+  };
+}
+
+function normalizeFileMap(value) {
+  const map = new Map();
+  if (!value) return map;
+  if (value instanceof Map) {
+    for (const [sourcePath, sourceText] of value) map.set(String(sourcePath), String(sourceText));
+    return map;
+  }
+  if (Array.isArray(value)) {
+    for (const entry of value) {
+      if (!entry?.sourcePath && !entry?.path) continue;
+      map.set(String(entry.sourcePath ?? entry.path), String(entry.sourceText ?? entry.text ?? ''));
+    }
+    return map;
+  }
+  for (const [sourcePath, sourceText] of Object.entries(value)) map.set(sourcePath, String(sourceText));
+  return map;
+}
+
+function policyForFile(input, sourcePath) {
+  if (input.policyByPath?.[sourcePath]) return input.policyByPath[sourcePath];
+  if (input.mergePolicyByPath?.[sourcePath]) return input.mergePolicyByPath[sourcePath];
+  return input.policy ?? input.mergePolicy;
+}
+
+function sourceLedgersForFile(input, sourcePath) {
+  const byPath = input.sourceLedgersByPath?.[sourcePath] ?? input.sourceLedgers?.[sourcePath];
+  if (byPath) return byPath;
+  if (input.sourceLedgers?.base || input.sourceLedgers?.worker || input.sourceLedgers?.head) return input.sourceLedgers;
+  return undefined;
+}
+
+function projectSummary(files) {
+  const byOperation = {};
+  for (const file of files) byOperation[file.operation] = (byOperation[file.operation] ?? 0) + 1;
+  return {
+    files: files.length,
+    mergedFiles: files.filter((file) => file.status === 'merged').length,
+    blockedFiles: files.filter((file) => file.status === 'blocked').length,
+    outputFiles: files.filter((file) => typeof file.outputSourceText === 'string').length,
+    semanticArtifactFiles: files.filter((file) => file.semanticArtifacts).length,
+    operations: byOperation
+  };
+}
+
+function admittedSyntheticAdmission(operation) {
+  return {
+    status: 'auto-merge-candidate',
+    action: operation === 'head-only' ? 'preserve-head' : 'apply',
+    reviewRequired: false,
+    autoApplyCandidate: true,
+    autoMergeClaim: false,
+    semanticEquivalenceClaim: false,
+    reasonCodes: []
+  };
+}
+
+function blockedAdmission(reasonCode) {
+  return {
+    status: 'blocked',
+    action: 'human-review',
+    reviewRequired: true,
+    autoApplyCandidate: false,
+    autoMergeClaim: false,
+    semanticEquivalenceClaim: false,
+    reasonCodes: [reasonCode]
+  };
+}
+
+function hashText(text) {
+  return typeof text === 'string' ? hashSemanticValue(text) : undefined;
+}
+
+function stringOrUndefined(value) {
+  return typeof value === 'string' ? value : undefined;
+}
+
+function safeId(value) {
+  return String(value ?? 'unknown').replace(/[^a-zA-Z0-9]+/g, '_').replace(/^_+|_+$/g, '') || 'file';
+}
+
+function bySourcePath(left, right) {
+  return String(left.sourcePath ?? '').localeCompare(String(right.sourcePath ?? ''));
+}
+
+function uniqueStrings(values) {
+  return [...new Set(values.filter((value) => typeof value === 'string' && value.length > 0))];
+}
+
+export { safeMergeJsTsProject };

package/dist/js-ts-semantic-merge.js

@@ -7,6 +7,9 @@ export {
 export {
   safeMergeJsTsSource
 } from './js-ts-safe-merge-composed.js';
+export {
+  safeMergeJsTsProject
+} from './js-ts-safe-project-merge.js';
 export {
   mergeJsTsSafeMemberAdditions,
   safeMergeJsTsMembers

package/package.json

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