@shapeshift-labs/frontier-lang-compiler 0.2.149 → 0.2.151

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

@@ -0,0 +1,85 @@
+import { hashSemanticValue } from '@shapeshift-labs/frontier-lang-kernel';
+import { compactRecord } from './js-ts-safe-merge-context.js';
+
+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 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];
+  return byPath ?? (input.sourceLedgers?.base || input.sourceLedgers?.worker || input.sourceLedgers?.head ? input.sourceLedgers : undefined);
+}
+
+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 safeId(value) { return String(value ?? 'unknown').replace(/[^a-zA-Z0-9]+/g, '_').replace(/^_+|_+$/g, '') || 'file'; }
+function uniqueStrings(values) { return [...new Set(values.filter((value) => typeof value === 'string' && value.length > 0))]; }
+
+export { blockedFile, hashText, policyForFile, safeId, sourceLedgersForFile, syntheticFile, uniqueStrings };

package/dist/js-ts-safe-project-merge-css-module-conflicts.js

@@ -0,0 +1,60 @@
+import { compactRecord } from './js-ts-safe-merge-context.js';
+
+function cssModuleUseSiteBlockerConflicts(blockers = []) {
+  return blockers.map(cssModuleUseSiteBlockerConflict);
+}
+
+function cssModuleUseSiteBlockerConflict(blocker) {
+  const reasonCode = blocker.reasonCode ?? 'css-module-use-site-proof-blocked';
+  return {
+    code: 'project-css-module-use-site-proof-blocked',
+    gateId: 'project-css-module-use-site-graph',
+    message: `Output project graph has unproved CSS Module use-site evidence: ${reasonCode}.`,
+    sourcePath: blocker.sourcePath,
+    details: compactRecord({
+      reasonCode,
+      conflictKey: cssModuleUseSiteBlockerConflictKey(blocker),
+      sourcePath: blocker.sourcePath,
+      sourceSpan: blocker.sourceSpan,
+      moduleSpecifier: blocker.moduleSpecifier,
+      localName: blocker.localName,
+      cssModuleImportBindingId: blocker.cssModuleImportBindingId,
+      cssModuleSourcePath: blocker.cssModuleSourcePath,
+      expressionText: blocker.expressionText,
+      writeOperation: blocker.writeOperation,
+      jsxPropRecordId: blocker.jsxPropRecordId,
+      failClosed: blocker.failClosed === true,
+      semanticEquivalenceClaim: blocker.semanticEquivalenceClaim === true
+    })
+  };
+}
+
+function cssModuleUseSiteBlockerConflictKey(blocker) {
+  return [
+    'css-module-use-site',
+    blocker.cssModuleSourcePath ?? blocker.moduleSpecifier ?? 'unknown-module',
+    blocker.sourcePath ?? 'unknown-source',
+    blocker.localName ?? 'unknown-local',
+    blocker.reasonCode ?? 'unknown-reason',
+    spanKey(blocker.sourceSpan),
+    blocker.expressionText
+  ].map((part) => String(part ?? '')).join('#');
+}
+
+function isResolvedCssModuleImportEdge(edge) {
+  return isCssModulePath(edge?.resolvedModulePath ?? edge?.moduleSpecifier)
+    && Boolean(edge?.targetDocumentId)
+    && typeof edge?.resolutionKind === 'string'
+    && edge.resolutionKind.endsWith('-source');
+}
+
+function isCssModulePath(path) {
+  return /\.module\.css(?:[?#].*)?$/i.test(String(path ?? ''));
+}
+
+function spanKey(span) {
+  if (!span) return '';
+  return [span.path, span.start, span.end].map((part) => String(part ?? '')).join(':');
+}
+
+export { cssModuleUseSiteBlockerConflicts, isResolvedCssModuleImportEdge };

package/dist/js-ts-safe-project-merge-declaration-emit-parity.js

@@ -0,0 +1,186 @@
+import { hashSemanticValue } from '@shapeshift-labs/frontier-lang-kernel';
+import { compactRecord, uniqueStrings } from './js-ts-safe-merge-context.js';
+import { createJsTsProjectMergeDeclarationGate } from './js-ts-safe-project-merge-declarations.js';
+
+const DeclarationEmitParityKind = 'typescript-checker-public-api-declaration-emit-parity';
+const DeclarationEmitParityProofLevel = 'typescript-checker-public-api-declaration-output-boundary';
+
+function createJsTsProjectMergeDeclarationEmitParityProof(input = {}, files = [], outputFiles = [], id = 'js_ts_project_safe_merge') {
+  const suppliedProof = input.declarationEmitParityProof ?? input.outputDeclarationEmitParityProof;
+  if (suppliedProof) return normalizeDeclarationEmitParityProof(suppliedProof, id);
+  if (!shouldCreateDeclarationEmitParityProof(input)) return undefined;
+  const stageFiles = declarationParityStageFiles(files, outputFiles, input);
+  const gateInput = declarationParityGateInput(input);
+  const gates = Object.fromEntries(Object.entries(stageFiles).map(([stage, stageOutputFiles]) => [
+    stage,
+    createJsTsProjectMergeDeclarationGate(gateInput, stageOutputFiles, `${id}_${stage}`)
+  ]));
+  return declarationEmitParityProof(input, id, gates);
+}
+
+function shouldCreateDeclarationEmitParityProof(input) {
+  return input.includeDeclarationOutput === true
+    || input.requireDeclarationOutput === true
+    || input.requirePublicApiDeclarationEmitParity === true;
+}
+
+function declarationParityStageFiles(files, outputFiles, input) {
+  return {
+    worker: files.map((file) => stageFile(file, workerStageSourceText(file), input)).filter(Boolean),
+    head: files.map((file) => stageFile(file, headStageSourceText(file), input)).filter(Boolean),
+    output: outputFiles
+  };
+}
+
+function declarationParityGateInput(input) {
+  return {
+    ...input,
+    includeDeclarationOutput: true,
+    requireDeclarationOutput: true,
+    outputDeclarations: undefined,
+    outputDeclarationFiles: undefined
+  };
+}
+
+function declarationEmitParityProof(input, id, gates) {
+  const boundaries = Object.fromEntries(Object.entries(gates).map(([stage, gate]) => [stage, declarationBoundary(gate)]));
+  const reasonCodes = declarationEmitParityReasonCodes(gates, boundaries);
+  const status = reasonCodes.length ? 'failed' : 'passed';
+  const outputFiles = boundaries.output?.files ?? [];
+  const core = {
+    kind: DeclarationEmitParityKind,
+    version: 1,
+    schema: 'frontier.lang.typescriptDeclarationEmitParityProof.v1',
+    id: `${id}_declaration_emit_parity`,
+    status,
+    proofLevel: DeclarationEmitParityProofLevel,
+    workerDeclarationBoundaryHash: boundaries.worker?.hash,
+    headDeclarationBoundaryHash: boundaries.head?.hash,
+    outputDeclarationBoundaryHash: boundaries.output?.hash,
+    declarationFileCount: outputFiles.length,
+    declarationFiles: outputFiles,
+    compilerOptionsHash: compilerOptionsHash(input),
+    diagnosticsHash: diagnosticsHash(gates),
+    missingSignals: reasonCodes,
+    reasonCodes,
+    autoMergeClaim: false,
+    semanticEquivalenceClaim: false
+  };
+  return { ...compactRecord(core), hash: hashSemanticValue(core) };
+}
+
+function declarationEmitParityReasonCodes(gates, boundaries) {
+  const reasonCodes = [];
+  for (const [stage, gate] of Object.entries(gates)) {
+    if (!gate) reasonCodes.push(`typescript-public-api-declaration-emit-${stage}-missing`);
+    if (gate?.status !== 'passed') reasonCodes.push(stage === 'output'
+      ? 'typescript-public-api-declaration-emit-output-missing'
+      : 'typescript-public-api-declaration-emit-proof-missing');
+    if ((gate?.diagnostics ?? []).some((diagnostic) => diagnostic.severity === 'error')) {
+      reasonCodes.push('typescript-public-api-declaration-emit-diagnostics-blocked');
+    }
+  }
+  if (!boundaries.worker?.hash || !boundaries.head?.hash || !boundaries.output?.hash) {
+    reasonCodes.push('typescript-compiler-declaration-output-public-boundary-hash-missing');
+  } else if (boundaries.worker.hash !== boundaries.head.hash || boundaries.worker.hash !== boundaries.output.hash) {
+    reasonCodes.push('typescript-public-api-declaration-emit-parity-mismatch');
+  }
+  return uniqueStrings(reasonCodes);
+}
+
+function declarationBoundary(gate) {
+  if (!gate || gate.status !== 'passed') return undefined;
+  const files = [...(gate.declarationFiles ?? [])]
+    .map((file) => compactRecord({
+      sourcePath: file.sourcePath,
+      sourceHash: file.sourceHash,
+      bytes: file.bytes,
+      source: file.source
+    }))
+    .sort((a, b) => String(a.sourcePath).localeCompare(String(b.sourcePath)));
+  return {
+    files,
+    hash: hashSemanticValue({ kind: 'frontier.lang.typescriptDeclarationBoundary', files })
+  };
+}
+
+function missingDeclarationEmitParityEvidence(proof, options = {}) {
+  if (options.requireDeclarationEmitParity !== true) return undefined;
+  if (!proof) {
+    return {
+      reasonCode: 'typescript-public-api-declaration-emit-proof-missing',
+      requiredEvidence: DeclarationEmitParityKind,
+      proofLevel: DeclarationEmitParityProofLevel,
+      missingSignals: ['typescript-public-api-declaration-emit-proof-missing']
+    };
+  }
+  if (proof.status === 'passed') return undefined;
+  const missingSignals = uniqueStrings(proof.reasonCodes ?? proof.missingSignals ?? ['typescript-public-api-declaration-emit-parity-mismatch']);
+  return compactRecord({
+    reasonCode: missingSignals[0],
+    requiredEvidence: DeclarationEmitParityKind,
+    proofLevel: DeclarationEmitParityProofLevel,
+    status: proof.status,
+    missingSignals,
+    workerDeclarationBoundaryHash: proof.workerDeclarationBoundaryHash,
+    headDeclarationBoundaryHash: proof.headDeclarationBoundaryHash,
+    outputDeclarationBoundaryHash: proof.outputDeclarationBoundaryHash,
+    declarationFileCount: proof.declarationFileCount,
+    compilerOptionsHash: proof.compilerOptionsHash,
+    diagnosticsHash: proof.diagnosticsHash,
+    autoMergeClaim: false,
+    semanticEquivalenceClaim: false
+  });
+}
+
+function normalizeDeclarationEmitParityProof(proof, id) {
+  const core = compactRecord({
+    ...proof,
+    kind: proof.kind ?? DeclarationEmitParityKind,
+    version: proof.version ?? 1,
+    id: proof.id ?? `${id}_declaration_emit_parity`,
+    proofLevel: proof.proofLevel ?? DeclarationEmitParityProofLevel,
+    status: proof.status ?? 'failed',
+    reasonCodes: uniqueStrings(proof.reasonCodes ?? proof.missingSignals ?? []),
+    missingSignals: uniqueStrings(proof.missingSignals ?? proof.reasonCodes ?? []),
+    autoMergeClaim: false,
+    semanticEquivalenceClaim: false
+  });
+  return { ...core, hash: proof.hash ?? hashSemanticValue(core) };
+}
+
+function workerStageSourceText(file) {
+  if (file.workerDeleted) return undefined;
+  return file.workerSourceText ?? file.baseSourceText;
+}
+
+function headStageSourceText(file) {
+  if (file.headDeleted) return undefined;
+  return file.headSourceText ?? file.baseSourceText;
+}
+
+function stageFile(file, sourceText, input) {
+  if (typeof sourceText !== 'string' || !file.sourcePath) return undefined;
+  return compactRecord({ sourcePath: file.sourcePath, language: file.language ?? input.language, sourceText });
+}
+
+function compilerOptionsHash(input) {
+  return hashSemanticValue({
+    compilerOptions: input.compilerOptions,
+    typescriptCompilerOptions: input.typescriptCompilerOptions,
+    declarationCompilerOptions: input.declarationCompilerOptions,
+    typescriptDeclarationCompilerOptions: input.typescriptDeclarationCompilerOptions,
+    tsconfig: input.tsconfig,
+    moduleResolution: input.moduleResolution,
+    projectReferences: input.projectReferences ?? input.typescriptProjectReferences ?? input.tsconfigProjectReferences
+  });
+}
+
+function diagnosticsHash(gates) {
+  return hashSemanticValue(Object.fromEntries(Object.entries(gates).map(([stage, gate]) => [stage, gate?.diagnostics ?? []])));
+}
+
+export {
+  createJsTsProjectMergeDeclarationEmitParityProof,
+  missingDeclarationEmitParityEvidence
+};

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

@@ -0,0 +1,227 @@
+import { hashSemanticValue } from '@shapeshift-labs/frontier-lang-kernel';
+import { compactRecord, uniqueStrings } from './js-ts-safe-merge-context.js';
+import {
+  createJsTsVirtualTypeScriptProgram,
+  normalizePath,
+  normalizeSuppliedDiagnostics,
+  normalizeTypeScriptDiagnostic,
+  sourceMapMatch
+} from './js-ts-safe-project-merge-ts-program.js';
+
+function createJsTsProjectMergeDeclarationGate(input = {}, outputFiles = [], id = 'js_ts_project_safe_merge') {
+  const declarationOutput = input.outputDeclarations || input.outputDeclarationFiles
+    ? normalizeSuppliedDeclarationOutput(input.outputDeclarations ?? input.outputDeclarationFiles)
+    : collectTypeScriptDeclarationOutput(input, outputFiles);
+  if (!declarationOutput && shouldSkipDeclarationGate(input)) return undefined;
+  if (!declarationOutput) return unavailableGate(input, id);
+  const diagnostics = declarationOutput.diagnostics ?? [];
+  const conflicts = diagnostics
+    .filter((diagnostic) => diagnostic.severity === 'error')
+    .map((diagnostic) => declarationConflict(input, diagnostic));
+  const requireFiles = input.requireDeclarationOutput === true;
+  if (requireFiles && declarationOutput.declarationFiles.length === 0) conflicts.push(missingDeclarationsConflict(input));
+  const status = conflicts.length ? 'blocked' : 'passed';
+  const core = {
+    kind: 'frontier.lang.jsTsProjectMergeDeclarationGate',
+    version: 1,
+    schema: 'frontier.lang.jsTsProjectMergeDeclarationGate.v1',
+    id: `${id}_declaration_output`,
+    status,
+    sourcePaths: outputFiles.map((file) => file.sourcePath).filter(Boolean),
+    declarationFiles: declarationOutput.declarationFiles,
+    diagnostics,
+    conflicts,
+    admission: {
+      status: status === 'passed' ? 'auto-merge-candidate' : 'blocked',
+      action: status === 'passed' ? 'accept-declarations' : 'human-review',
+      reviewRequired: status !== 'passed',
+      autoApplyCandidate: status === 'passed',
+      autoMergeClaim: false,
+      semanticEquivalenceClaim: false,
+      reasonCodes: uniqueStrings(conflicts.map((conflict) => conflict.code))
+    },
+    summary: declarationSummary(declarationOutput.declarationFiles, diagnostics, conflicts),
+    evidence: [declarationEvidence(id, status, declarationOutput, diagnostics, conflicts, input)]
+  };
+  return { ...core, hash: hashSemanticValue(core) };
+}
+
+function shouldSkipDeclarationGate(input) {
+  return input.includeDeclarationOutput !== true && input.requireDeclarationOutput !== true;
+}
+
+function collectTypeScriptDeclarationOutput(input, outputFiles) {
+  const emitted = new Map();
+  const created = createJsTsVirtualTypeScriptProgram(input, outputFiles, {
+    compilerOptions: {
+      noEmit: false,
+      declaration: true,
+      emitDeclarationOnly: true,
+      outDir: input.declarationOutDir ?? '__frontier_declarations__',
+      ...(input.declarationCompilerOptions ?? input.typescriptDeclarationCompilerOptions ?? {})
+    },
+    writeFile(fileName, text) {
+      emitted.set(normalizePath(fileName), String(text));
+    }
+  });
+  if (!created) return undefined;
+  const { ts, program, sourceMap } = created;
+  const projectRoot = normalizePath(input.projectRoot ?? '');
+  if (!program) return { declarationFiles: [], diagnostics: [] };
+  const preEmitDiagnostics = ts.getPreEmitDiagnostics
+    ? ts.getPreEmitDiagnostics(program)
+    : fallbackPreEmitDiagnostics(program);
+  const emitResult = program.emit(undefined, undefined, undefined, true);
+  const diagnostics = uniqueDiagnostics([...preEmitDiagnostics, ...(emitResult.diagnostics ?? [])]
+    .map((diagnostic) => normalizeTypeScriptDiagnostic(ts, diagnostic))
+    .filter((diagnostic) => diagnostic.sourcePath ? Boolean(sourceMapMatch(sourceMap, diagnostic.sourcePath, projectRoot)) : false));
+  return {
+    declarationFiles: [...emitted.entries()].map(([sourcePath, sourceText]) => declarationFile(sourcePath, sourceText, 'typescript-compiler-api')),
+    diagnostics
+  };
+}
+
+function fallbackPreEmitDiagnostics(program) {
+  const diagnostics = [];
+  for (const sourceFile of program.getSourceFiles()) {
+    diagnostics.push(...(program.getSyntacticDiagnostics?.(sourceFile) ?? []));
+    diagnostics.push(...(program.getSemanticDiagnostics?.(sourceFile) ?? []));
+  }
+  return diagnostics;
+}
+
+function uniqueDiagnostics(diagnostics) {
+  const seen = new Set();
+  return diagnostics.filter((diagnostic) => {
+    const key = `${diagnostic.code}:${diagnostic.sourcePath ?? ''}:${diagnostic.start ?? ''}:${diagnostic.message}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+function normalizeSuppliedDeclarationOutput(value) {
+  const entries = value instanceof Map
+    ? [...value.entries()].map(([sourcePath, sourceText]) => ({ sourcePath, sourceText }))
+    : Array.isArray(value) ? value
+      : typeof value === 'object' && value ? Object.entries(value).map(([sourcePath, sourceText]) => ({ sourcePath, sourceText }))
+        : [];
+  return {
+    declarationFiles: entries.map((entry) => declarationFile(
+      entry.sourcePath ?? entry.path,
+      entry.sourceText ?? entry.text ?? '',
+      entry.source ?? 'supplied'
+    )),
+    diagnostics: normalizeSuppliedDiagnostics(value?.diagnostics ?? [])
+  };
+}
+
+function declarationFile(sourcePath, sourceText, source) {
+  const text = String(sourceText ?? '');
+  return compactRecord({
+    sourcePath: normalizePath(sourcePath),
+    sourceText: text,
+    sourceHash: hashSemanticValue(text),
+    source,
+    bytes: byteLength(text)
+  });
+}
+
+function unavailableGate(input, id) {
+  const conflict = input.requireDeclarationOutput === true ? missingCompilerConflict(input) : undefined;
+  const conflicts = [conflict].filter(Boolean);
+  const status = conflict ? 'blocked' : 'skipped';
+  const core = {
+    kind: 'frontier.lang.jsTsProjectMergeDeclarationGate',
+    version: 1,
+    schema: 'frontier.lang.jsTsProjectMergeDeclarationGate.v1',
+    id: `${id}_declaration_output`,
+    status,
+    sourcePaths: [],
+    declarationFiles: [],
+    diagnostics: [],
+    conflicts,
+    admission: {
+      status,
+      action: conflict ? 'human-review' : 'skip-declarations',
+      reviewRequired: Boolean(conflict),
+      autoApplyCandidate: !conflict,
+      autoMergeClaim: false,
+      semanticEquivalenceClaim: false,
+      reasonCodes: uniqueStrings(conflicts.map((entry) => entry.code))
+    },
+    summary: declarationSummary([], [], conflicts),
+    evidence: [{
+      id: `${id}_declaration_output_evidence`,
+      kind: 'js-ts-project-declaration-output',
+      status: conflict ? 'failed' : 'skipped',
+      summary: conflict ? conflict.message : 'Declaration output was requested but no TypeScript compiler API or supplied declarations were provided.',
+      metadata: { declarationFiles: 0, conflicts: conflicts.length, declarationSource: 'missing' }
+    }]
+  };
+  return { ...core, hash: hashSemanticValue(core) };
+}
+
+function missingCompilerConflict(input) {
+  return {
+    code: 'project-declaration-output-unavailable',
+    gateId: 'project-declaration-output',
+    message: 'Project declaration output is required but no TypeScript compiler API or supplied declarations were provided.',
+    details: { required: input.requireDeclarationOutput === true }
+  };
+}
+
+function missingDeclarationsConflict(input) {
+  return {
+    code: 'project-declaration-output-empty',
+    gateId: 'project-declaration-output',
+    message: 'Project declaration output is required but no declaration files were emitted.',
+    details: { projectRoot: input.projectRoot }
+  };
+}
+
+function declarationConflict(input, diagnostic) {
+  return compactRecord({
+    code: 'project-declaration-diagnostic',
+    gateId: 'project-declaration-output',
+    message: `Project declaration diagnostic ${diagnostic.code}: ${diagnostic.message}`,
+    sourcePath: diagnostic.sourcePath,
+    details: { diagnostic, projectRoot: input.projectRoot }
+  });
+}
+
+function declarationSummary(declarationFiles, diagnostics, conflicts) {
+  return {
+    declarationFiles: declarationFiles.length,
+    declarationBytes: declarationFiles.reduce((total, file) => total + Number(file.bytes ?? 0), 0),
+    diagnostics: diagnostics.length,
+    conflicts: conflicts.length,
+    errors: diagnostics.filter((diagnostic) => diagnostic.severity === 'error').length,
+    warnings: diagnostics.filter((diagnostic) => diagnostic.severity === 'warning').length
+  };
+}
+
+function declarationEvidence(id, status, declarationOutput, diagnostics, conflicts, input) {
+  return {
+    id: `${id}_declaration_output_evidence`,
+    kind: 'js-ts-project-declaration-output',
+    status: status === 'passed' ? 'passed' : 'failed',
+    summary: status === 'passed'
+      ? `Emitted ${declarationOutput.declarationFiles.length} declaration file(s) for JS/TS project output.`
+      : `Blocked JS/TS project merge on ${conflicts.length} declaration output conflict(s).`,
+    metadata: {
+      declarationFiles: declarationOutput.declarationFiles.length,
+      diagnostics: diagnostics.length,
+      conflicts: conflicts.length,
+      declarationSource: input.outputDeclarations || input.outputDeclarationFiles ? 'supplied' : 'typescript-compiler-api',
+      autoMergeClaim: false,
+      semanticEquivalenceClaim: false
+    }
+  };
+}
+
+function byteLength(text) {
+  return typeof TextEncoder === 'function' ? new TextEncoder().encode(text).length : String(text).length;
+}
+
+export { createJsTsProjectMergeDeclarationGate };

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

@@ -0,0 +1,42 @@
+import { compactRecord } from './js-ts-safe-merge-context.js';
+import { describeJsTsProjectCompilerInputs, sourceMapMatch } from './js-ts-safe-project-merge-ts-program.js';
+
+const projectReferenceDiagnosticCodes = new Set([6053, 6305, 6306, 6310, 6311]);
+
+export function optionDiagnosticSource(diagnostic, metadata = {}) {
+  return metadata.projectReferenceCount && projectReferenceDiagnosticCodes.has(diagnostic.code)
+    ? 'typescript-project-references'
+    : 'typescript-compiler-options';
+}
+
+export function keepDiagnostic(diagnostic, sourceMap, projectRoot) {
+  if (!diagnostic.sourcePath) return true;
+  if (diagnostic.source === 'typescript-compiler-options' || diagnostic.source === 'typescript-project-references') return true;
+  return Boolean(sourceMapMatch(sourceMap, diagnostic.sourcePath, projectRoot));
+}
+
+export function uniqueDiagnostics(diagnostics) {
+  const seen = new Set();
+  return diagnostics.filter((diagnostic) => {
+    const key = `${diagnostic.source ?? ''}:${diagnostic.code}:${diagnostic.sourcePath ?? ''}:${diagnostic.start ?? ''}:${diagnostic.message}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+export function diagnosticsMetadata(compilerMetadata, rootNames, sourceMap, diagnosticSource) {
+  return compactRecord({
+    ...compilerMetadata,
+    diagnosticSource,
+    rootNames,
+    sourceFiles: sourceMap.size
+  });
+}
+
+export function diagnosticsGateMetadata(input, diagnosticsResult) {
+  return compactRecord({
+    ...(diagnosticsResult?.metadata ?? describeJsTsProjectCompilerInputs(input)),
+    diagnosticSource: diagnosticsResult?.metadata?.diagnosticSource ?? 'missing'
+  });
+}

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

@@ -0,0 +1,73 @@
+import { compactRecord } from './js-ts-safe-merge-context.js';
+import {
+  diagnosticsMetadata,
+  keepDiagnostic,
+  optionDiagnosticSource,
+  uniqueDiagnostics
+} from './js-ts-safe-project-merge-diagnostics-metadata.js';
+import {
+  createJsTsVirtualTypeScriptProgram,
+  normalizePath,
+  normalizeTypeScriptDiagnostic,
+  sourceMapMatch
+} from './js-ts-safe-project-merge-ts-program.js';
+
+export function collectTypeScriptDiagnostics(input, outputFiles) {
+  const created = createJsTsVirtualTypeScriptProgram(input, outputFiles);
+  if (!created) return undefined;
+  const { ts, sourceMap, program, compilerOptionDiagnostics = [], compilerMetadata = {}, rootNames = [] } = created;
+  const projectRoot = normalizePath(input.projectRoot ?? '');
+  const options = input.diagnosticOptions ?? input.typescriptDiagnosticOptions ?? {};
+  const diagnostics = [...compilerOptionDiagnostics];
+  if (!program) {
+    return {
+      diagnostics: uniqueDiagnostics(diagnostics),
+      metadata: diagnosticsMetadata(compilerMetadata, rootNames, sourceMap, 'typescript-compiler-api')
+    };
+  }
+  if (options.options !== false && program.getOptionsDiagnostics) {
+    diagnostics.push(...program.getOptionsDiagnostics().map((diagnostic) => (
+      normalizeTypeScriptDiagnostic(ts, diagnostic, optionDiagnosticSource(diagnostic, compilerMetadata))
+    )));
+  }
+  for (const sourceFile of program.getSourceFiles()) {
+    if (!sourceMapMatch(sourceMap, sourceFile.fileName, projectRoot)) continue;
+    if (options.syntactic !== false && program.getSyntacticDiagnostics) {
+      diagnostics.push(...program.getSyntacticDiagnostics(sourceFile).map((diagnostic) => ({
+        diagnostic,
+        phase: 'syntax'
+      })));
+    }
+    if (options.semantic !== false && program.getSemanticDiagnostics) {
+      diagnostics.push(...program.getSemanticDiagnostics(sourceFile).map((diagnostic) => ({
+        diagnostic,
+        phase: 'semantic'
+      })));
+    }
+  }
+  return {
+    diagnostics: uniqueDiagnostics(diagnostics.map((entry) => (
+      entry?.diagnostic
+        ? withDiagnosticPhase(normalizeTypeScriptDiagnostic(ts, entry.diagnostic), entry.phase)
+        : withDiagnosticPhase(entry, entry.phase)
+    )).filter((diagnostic) => keepDiagnostic(diagnostic, sourceMap, projectRoot))),
+    metadata: diagnosticsMetadata(compilerMetadata, rootNames, sourceMap, 'typescript-compiler-api')
+  };
+}
+
+function withDiagnosticPhase(diagnostic, phase) {
+  const normalizedPhase = normalizeDiagnosticPhase(phase);
+  return compactRecord({
+    ...diagnostic,
+    phase: normalizedPhase,
+    syntax: diagnostic.syntax === true || normalizedPhase === 'syntax' ? true : undefined
+  });
+}
+
+function normalizeDiagnosticPhase(value) {
+  if (typeof value !== 'string') return undefined;
+  const lowered = value.toLowerCase();
+  if (lowered.includes('syntax') || lowered.includes('syntactic') || lowered.includes('parse')) return 'syntax';
+  if (lowered.includes('semantic') || lowered.includes('type')) return 'semantic';
+  return value;
+}