@shapeshift-labs/frontier-lang-css 0.1.2 → 0.1.3

package/README.md

@@ -232,11 +232,11 @@ const merge = safeMergeCssSource({
 });
 ```
 
-`sourceMap.mappings` links emitted rule blocks back to Frontier Lang semantic node ids. `createCssSemanticMergeEvidence` records selectors, specificity, declarations, custom properties, cascade keys, source spans, stable hashes, and fail-closed proof gaps for cascade/render-sensitive CSS surfaces. `safeMergeCssSource` admits independent unscoped declaration edits by cascade key and blocks overlapping declaration changes or proof gaps.
+`sourceMap.mappings` links emitted rule blocks back to Frontier Lang semantic node ids. `createCssSemanticMergeEvidence` records selectors, specificity, declarations, custom properties, cascade keys, CSS Modules exports, ICSS edges, source spans, stable hashes, and fail-closed proof gaps for cascade/render-sensitive CSS surfaces. `safeMergeCssSource` admits independent unscoped declaration edits by cascade key, and for `.module.css` files it classifies exported local classes, `composes`, and ICSS import/export records as explicit merge contracts.
 
 ## Support Boundary
 
-- Ready evidence: style rules, selectors, specificity, declarations, custom properties, source spans, stable hashes.
-- Safe merge: independent unscoped declarations with non-overlapping cascade keys; output is a canonical CSS render and not a byte/trivia-preserving claim.
-- Review-only gaps: shorthands without longhand expansion, scoped cascade under `@media` / `@supports` / `@container` / `@layer`, `@keyframes`, `@font-face`, `@page`, browser layout and render equivalence.
+- Ready evidence: style rules, selectors, specificity, declarations, custom properties, CSS Modules local exports, generated class-name map coverage, JS/TS use-site graph hashes, composition graph hashes, ICSS graph hashes, source spans, stable hashes.
+- Safe merge: independent unscoped declarations with non-overlapping cascade keys; explicit CSS Modules export additions/deletions when generated class-name and JS/TS use-site graph proof is supplied; composition edits when composition graph proof is supplied; ICSS edits when ICSS graph proof is supplied. Output is a canonical CSS render and not a byte/trivia-preserving claim.
+- Review-only gaps: incomplete generated class-name maps, unproved CSS Modules use-site graphs, unproved composition or ICSS graphs, shorthands without longhand expansion, scoped cascade under `@media` / `@supports` / `@container` / `@layer`, `@keyframes`, `@font-face`, `@page`, browser layout and render equivalence.
 - Claims: `autoMergeClaim`, `semanticEquivalenceClaim`, `browserCascadeEquivalenceClaim`, and `browserRenderEquivalenceClaim` remain false.

package/dist/css-modules.js

@@ -41,6 +41,9 @@ function cssModuleProofGaps(exports, compositions, icssImports, icssExports, opt
   if (exports.length && !options.generatedClassNameMapHash && !options.generatedClassNameMap) {
     proofGaps.push(proofGap('css-module-generated-class-map-unproved', 'CSS Modules exported local classes need generated class-name map evidence from the bundler/runtime.'));
   }
+  if (exports.length && options.generatedClassNameMap && exports.some((entry) => !entry.generatedName)) {
+    proofGaps.push(proofGap('css-module-generated-class-map-incomplete', 'CSS Modules generated class-name map evidence must cover every exported local class.'));
+  }
   if (exports.length && !options.jsTsUseSiteGraphHash) {
     proofGaps.push(proofGap('css-module-js-ts-use-site-graph-unproved', 'CSS Modules exported classes need JS/TS/JSX import and member-use graph evidence.'));
   }

package/dist/index.d.ts

@@ -249,6 +249,8 @@ export interface CssSafeMergeResult {
   readonly headSheetHash?: string;
   readonly workerChangedDeclarations?: number;
   readonly headChangedDeclarations?: number;
+  readonly workerChangedCssModuleContracts?: number;
+  readonly headChangedCssModuleContracts?: number;
 }
 
 export interface CssSafeMergeInput {
@@ -257,6 +259,28 @@ export interface CssSafeMergeInput {
   readonly baseSourceText?: string;
   readonly workerSourceText?: string;
   readonly headSourceText?: string;
+  readonly cssModule?: boolean;
+  readonly cssModules?: boolean;
+  readonly generatedClassNameMap?: Readonly<Record<string, string>>;
+  readonly generatedClassNameMapHash?: string;
+  readonly jsTsUseSiteGraphHash?: string;
+  readonly cssModuleCompositionGraphHash?: string;
+  readonly icssGraphHash?: string;
+  readonly baseGeneratedClassNameMap?: Readonly<Record<string, string>>;
+  readonly workerGeneratedClassNameMap?: Readonly<Record<string, string>>;
+  readonly headGeneratedClassNameMap?: Readonly<Record<string, string>>;
+  readonly baseGeneratedClassNameMapHash?: string;
+  readonly workerGeneratedClassNameMapHash?: string;
+  readonly headGeneratedClassNameMapHash?: string;
+  readonly baseJsTsUseSiteGraphHash?: string;
+  readonly workerJsTsUseSiteGraphHash?: string;
+  readonly headJsTsUseSiteGraphHash?: string;
+  readonly baseCssModuleCompositionGraphHash?: string;
+  readonly workerCssModuleCompositionGraphHash?: string;
+  readonly headCssModuleCompositionGraphHash?: string;
+  readonly baseIcssGraphHash?: string;
+  readonly workerIcssGraphHash?: string;
+  readonly headIcssGraphHash?: string;
 }
 
 export declare function toCssAst(document: FrontierLangDocument, options?: CssProjectionOptions): CssAstStylesheet;

package/dist/semantic-merge-css-modules.js

@@ -0,0 +1,206 @@
+function sheetOptions(input, side, sourcePath) {
+  const prefix = side === 'base' ? 'base' : side === 'worker' ? 'worker' : 'head';
+  return {
+    sourcePath,
+    cssModule: input.cssModule,
+    cssModules: input.cssModules,
+    generatedClassNameMap: input[`${prefix}GeneratedClassNameMap`] ?? input.generatedClassNameMap,
+    generatedClassNameMapHash: input[`${prefix}GeneratedClassNameMapHash`] ?? input.generatedClassNameMapHash,
+    jsTsUseSiteGraphHash: input[`${prefix}JsTsUseSiteGraphHash`] ?? input.jsTsUseSiteGraphHash,
+    cssModuleCompositionGraphHash: input[`${prefix}CssModuleCompositionGraphHash`] ?? input.cssModuleCompositionGraphHash,
+    icssGraphHash: input[`${prefix}IcssGraphHash`] ?? input.icssGraphHash
+  };
+}
+
+function cssModuleContractChanges(sheets, hash) {
+  const indexes = {
+    base: cssModuleContractIndex(sheets.base, hash),
+    worker: cssModuleContractIndex(sheets.worker, hash),
+    head: cssModuleContractIndex(sheets.head, hash)
+  };
+  return {
+    worker: changedContracts(indexes.base, indexes.worker, 'worker', sheets.worker),
+    head: changedContracts(indexes.base, indexes.head, 'head', sheets.head)
+  };
+}
+
+function cssModuleContractIndex(sheet, hash) {
+  const contracts = new Map();
+  const cssModules = sheet.cssModules;
+  if (!cssModules) return { contracts, proofGaps: [], moduleHash: undefined };
+  for (const entry of cssModules.exports ?? []) {
+    const contractHash = hash?.({ kind: 'frontier.lang.css.module.export.contract.v1', name: entry.name, generatedName: entry.generatedName });
+    contracts.set(`export:${entry.name}`, {
+      key: `export:${entry.name}`,
+      contractKind: 'css-module-export',
+      name: entry.name,
+      hash: contractHash ?? entry.exportHash,
+      requiredProofGapCodes: ['css-module-generated-class-map-unproved', 'css-module-generated-class-map-incomplete', 'css-module-js-ts-use-site-graph-unproved']
+    });
+  }
+  for (const entry of cssModules.compositions ?? []) {
+    const key = ['composition', entry.localName, entry.sourceKind, entry.source ?? 'local'].join(':');
+    contracts.set(key, {
+      key,
+      contractKind: 'css-module-composition',
+      name: entry.localName,
+      hash: entry.compositionHash,
+      requiredProofGapCodes: ['css-module-composition-resolution-unproved']
+    });
+  }
+  for (const entry of cssModules.icssImports ?? []) {
+    const key = ['icss-import', entry.source, entry.importedName].join(':');
+    contracts.set(key, {
+      key,
+      contractKind: 'icss-import',
+      name: entry.localName,
+      hash: entry.importHash,
+      requiredProofGapCodes: ['css-module-icss-graph-unproved']
+    });
+  }
+  for (const entry of cssModules.icssExports ?? []) {
+    const key = `icss-export:${entry.name}`;
+    contracts.set(key, {
+      key,
+      contractKind: 'icss-export',
+      name: entry.name,
+      hash: entry.exportHash,
+      requiredProofGapCodes: ['css-module-icss-graph-unproved']
+    });
+  }
+  return { contracts, proofGaps: cssModules.proofGaps ?? [], moduleHash: cssModules.moduleHash };
+}
+
+function changedContracts(baseIndex, currentIndex, side, sheet) {
+  const keys = unique([...baseIndex.contracts.keys(), ...currentIndex.contracts.keys()]);
+  return keys.flatMap((key) => {
+    const before = baseIndex.contracts.get(key);
+    const after = currentIndex.contracts.get(key);
+    if ((before?.hash ?? '') === (after?.hash ?? '')) return [];
+    return [{
+      side,
+      key,
+      before,
+      after,
+      proofGaps: uniqueProofGaps([...(baseIndex.proofGaps ?? []), ...(currentIndex.proofGaps ?? [])]),
+      sheetHash: sheet.sheetHash,
+      kind: before && after ? 'update' : before ? 'delete' : 'add'
+    }];
+  });
+}
+
+function cssModuleContractConflicts(id, sourcePath, changes) {
+  return [
+    ...cssModuleContractProofConflicts(id, sourcePath, changes.worker),
+    ...cssModuleContractProofConflicts(id, sourcePath, changes.head),
+    ...cssModuleOverlapConflicts(id, sourcePath, changes.worker, changes.head)
+  ];
+}
+
+function cssModuleContractProofConflicts(id, sourcePath, changes) {
+  return changes.flatMap((change) => {
+    const contract = change.after ?? change.before;
+    const requiredCodes = contract?.requiredProofGapCodes ?? [];
+    return (change.proofGaps ?? [])
+      .filter((gap) => requiredCodes.includes(gap.code))
+      .map((gap) => conflict(id, sourcePath, 'css-module-proof-gap-blocked', gap.code, {
+        contractKey: change.key,
+        contractKind: contract.contractKind,
+        side: change.side,
+        changeKind: change.kind,
+        proofGap: gap
+      }));
+  });
+}
+
+function cssModuleOverlapConflicts(id, sourcePath, workerChanges, headChanges) {
+  const headByKey = new Map(headChanges.map((change) => [change.key, change]));
+  return workerChanges.flatMap((workerChange) => {
+    const headChange = headByKey.get(workerChange.key);
+    if (!headChange || sameContractChange(workerChange, headChange)) return [];
+    const contract = workerChange.after ?? workerChange.before ?? headChange.after ?? headChange.before;
+    return [conflict(id, sourcePath, 'css-module-contract-conflict', 'css-module-contract-conflict', {
+      contractKey: workerChange.key,
+      contractKind: contract?.contractKind,
+      worker: contractChangeDetails(workerChange),
+      head: contractChangeDetails(headChange)
+    })];
+  });
+}
+
+function unsupportedSourceShapeConflicts(id, sourcePath, sheets, declarationChanges, hash) {
+  const sourceShapeChanges = {
+    worker: unsupportedSourceShapeChanges(sheets.base, sheets.worker, declarationChanges.worker, 'worker', hash),
+    head: unsupportedSourceShapeChanges(sheets.base, sheets.head, declarationChanges.head, 'head', hash)
+  };
+  return [...sourceShapeChanges.worker, ...sourceShapeChanges.head].map((change) => conflict(id, sourcePath, 'css-source-shape-unsupported', change.reasonCode, change));
+}
+
+function unsupportedSourceShapeChanges(baseSheet, currentSheet, declarationChanges, side, hash) {
+  const baseShape = sourceShapeIndex(baseSheet, hash);
+  const currentShape = sourceShapeIndex(currentSheet, hash);
+  const keys = unique([...baseShape.keys(), ...currentShape.keys()]);
+  const changedDeclarationRuleKeys = new Set(declarationChanges.map((change) => (change.after ?? change.before)?.ruleKey));
+  return keys.flatMap((key) => {
+    const before = baseShape.get(key);
+    const after = currentShape.get(key);
+    if ((before?.hash ?? '') === (after?.hash ?? '')) return [];
+    if (before?.representedByDeclarations || after?.representedByDeclarations) return [];
+    if (changedDeclarationRuleKeys.has(before?.ruleKey) || changedDeclarationRuleKeys.has(after?.ruleKey)) return [];
+    return [{
+      side,
+      reasonCode: 'css-source-shape-unsupported',
+      shapeKey: key,
+      before: sourceShapeDetails(before),
+      after: sourceShapeDetails(after)
+    }];
+  });
+}
+
+function sourceShapeIndex(sheet, hash) {
+  const result = new Map();
+  for (const record of sheet.records ?? []) {
+    if (record.kind === 'rule') {
+      const ruleKey = ruleIdentityKey(record);
+      const declarations = record.declarations ?? [];
+      const exportName = sheet.cssModules?.exports?.find((entry) => (entry.ruleHashes ?? []).includes(record.ruleHash))?.name;
+      result.set(`rule:${ruleKey}`, {
+        kind: 'rule',
+        ruleKey,
+        selectors: record.selectors,
+        representedByDeclarations: declarations.length > 0,
+        contractKey: exportName ? `export:${exportName}` : undefined,
+        hash: hash?.({ kind: 'frontier.lang.css.sourceShape.rule.v1', ruleKey, declarations: declarations.length, exportName, ruleHash: record.ruleHash })
+      });
+    }
+    if (record.kind === 'at-rule') {
+      const shapeKey = `at-rule:${[...(record.scopes ?? []), record.atRuleName, record.conditionText].join('::')}`;
+      result.set(shapeKey, {
+        kind: 'at-rule',
+        atRuleName: record.atRuleName,
+        conditionText: record.conditionText,
+        representedByDeclarations: false,
+        hash: record.atRuleHash
+      });
+    }
+  }
+  return result;
+}
+
+function conflict(id, sourcePath, code, reasonCode, details = {}) {
+  const conflictTarget = details.cascadeKey ?? details.contractKey ?? details.shapeKey ?? sourcePath ?? 'source';
+  return { code, gateId: 'css-semantic-merge', sourcePath, details: { reasonCode, conflictKey: `css#${id}#${reasonCode}#${conflictTarget}`, ...details } };
+}
+
+function sameContractChange(left, right) { return (left.after?.hash ?? '') === (right.after?.hash ?? '') && left.kind === right.kind; }
+function contractChangeDetails(change) { return { kind: change.kind, contractKind: (change.after ?? change.before)?.contractKind, name: (change.after ?? change.before)?.name, hash: change.after?.hash }; }
+function sourceShapeDetails(shape) { return shape ? { kind: shape.kind, selectors: shape.selectors, atRuleName: shape.atRuleName, conditionText: shape.conditionText, representedByDeclarations: shape.representedByDeclarations } : undefined; }
+function ruleIdentityKey(record) { return [...(record.scopes ?? []), record.selectors.join(',')].join('::'); }
+function unique(values) { return [...new Set(values.filter(Boolean))]; }
+function uniqueProofGaps(values) {
+  const byCode = new Map();
+  for (const value of values) if (value?.code && !byCode.has(value.code)) byCode.set(value.code, value);
+  return [...byCode.values()];
+}
+
+export { cssModuleContractChanges, cssModuleContractConflicts, sheetOptions, unsupportedSourceShapeConflicts };

package/dist/semantic-merge.js

@@ -1,3 +1,5 @@
+import { cssModuleContractChanges, cssModuleContractConflicts, sheetOptions, unsupportedSourceShapeConflicts } from './semantic-merge-css-modules.js';
+
 function safeMergeCssSource(input = {}, context = {}) {
   const parseSheet = context.parseCssSemanticSheet;
   const hash = context.hashSemanticValue;
@@ -11,21 +13,24 @@ function safeMergeCssSource(input = {}, context = {}) {
   if (worker === base) return merged(id, sourcePath, head, 'worker-unchanged', hash);
   if (head === base) return merged(id, sourcePath, worker, 'head-unchanged', hash);
   const sheets = {
-    base: parseSheet(base, { sourcePath }),
-    worker: parseSheet(worker, { sourcePath }),
-    head: parseSheet(head, { sourcePath })
+    base: parseSheet(base, sheetOptions(input, 'base', sourcePath)),
+    worker: parseSheet(worker, sheetOptions(input, 'worker', sourcePath)),
+    head: parseSheet(head, sheetOptions(input, 'head', sourcePath))
   };
   const indexes = Object.fromEntries(Object.entries(sheets).map(([name, sheet]) => [name, declarationIndex(sheet)]));
   const changed = {
     worker: changedDeclarations(indexes.base, indexes.worker, 'worker'),
     head: changedDeclarations(indexes.base, indexes.head, 'head')
   };
+  const moduleChanges = cssModuleContractChanges(sheets, hash);
   const proofConflicts = proofGapConflicts(id, sourcePath, changed, indexes);
   const overlapConflicts = [
     ...overlapDeclarationConflicts(id, sourcePath, changed.worker, changed.head),
     ...shorthandOverlapConflicts(id, sourcePath, changed.worker, changed.head)
   ];
-  const conflicts = [...proofConflicts, ...overlapConflicts];
+  const moduleConflicts = cssModuleContractConflicts(id, sourcePath, moduleChanges);
+  const sourceShapeConflicts = unsupportedSourceShapeConflicts(id, sourcePath, sheets, changed, hash);
+  const conflicts = [...proofConflicts, ...overlapConflicts, ...moduleConflicts, ...sourceShapeConflicts];
   if (conflicts.length) return blocked(id, sourcePath, 'css-semantic-merge-conflict', conflicts);
   const mergedIndex = applyDeclarationChanges(applyDeclarationChanges(indexes.base, changed.head), changed.worker);
   return merged(id, sourcePath, renderDeclarationIndex(mergedIndex), 'semantic-declaration-merge', hash, {
@@ -33,7 +38,9 @@ function safeMergeCssSource(input = {}, context = {}) {
     workerSheetHash: sheets.worker.sheetHash,
     headSheetHash: sheets.head.sheetHash,
     workerChangedDeclarations: changed.worker.length,
-    headChangedDeclarations: changed.head.length
+    headChangedDeclarations: changed.head.length,
+    workerChangedCssModuleContracts: moduleChanges.worker.length,
+    headChangedCssModuleContracts: moduleChanges.head.length
   });
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shapeshift-labs/frontier-lang-css",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "CSS semantic merge evidence and projection adapter for Frontier Lang semantic source documents.",
   "type": "module",
   "main": "./dist/index.js",