@shapeshift-labs/frontier-lang-compiler 0.2.108 → 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/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.108",
+  "version": "0.2.109",
   "description": "Compiler facade for Frontier Lang source documents and language projection adapters.",
   "type": "module",
   "main": "./dist/index.js",