@shapeshift-labs/frontier-lang-css 0.1.5 → 0.1.7

package/dist/index.d.ts

@@ -36,6 +36,20 @@ export interface CssSourceSpan {
   readonly endColumn: number;
 }
 
+export interface CssParserDiagnostic {
+  readonly reason?: string;
+  readonly line?: number;
+  readonly column?: number;
+  readonly input?: string;
+  readonly [key: string]: unknown;
+}
+
+export interface CssParserEvidence {
+  readonly name: 'postcss' | string;
+  readonly sourceCodeLocationInfo: boolean;
+  readonly parseErrors: readonly CssParserDiagnostic[];
+}
+
 export interface CssSourceRef {
   readonly semanticNodeId: string;
   readonly semanticNodeKind?: string;
@@ -109,6 +123,8 @@ export interface CssSemanticDeclaration {
   readonly value: string;
   readonly important: boolean;
   readonly valueHash: string;
+  readonly sourceSpan?: CssSourceSpan;
+  readonly rawTextHash?: string;
   readonly ordinal: number;
   readonly cascadeKey: string;
   readonly declarationHash: string;
@@ -129,6 +145,8 @@ export interface CssSemanticRecord {
   readonly scopedCascadeGraphHash?: string;
   readonly sourceSpan: CssSourceSpan;
   readonly sourceHash: string;
+  readonly parser?: 'postcss' | string;
+  readonly rawTextHash?: string;
   readonly ruleHash?: string;
   readonly atRuleHash?: string;
   readonly proofGaps?: readonly CssSemanticProofGap[];
@@ -200,6 +218,7 @@ export interface CssSemanticSheet {
   readonly sheetHash: string;
   readonly summary: Readonly<Record<string, number>>;
   readonly proofGaps: readonly CssSemanticProofGap[];
+  readonly parser: CssParserEvidence;
 }
 
 export interface CssSemanticMergeEvidence {
@@ -254,40 +273,35 @@ export interface CssSafeMergeResult {
   readonly headChangedDeclarations?: number;
   readonly workerChangedCssModuleContracts?: number;
   readonly headChangedCssModuleContracts?: number;
+  readonly parserEvidence?: CssSafeMergeParserEvidence;
+}
+
+export interface CssSafeMergeParserEvidence {
+  readonly kind: 'frontier.lang.cssSafeMergeParserEvidence';
+  readonly version: 1;
+  readonly parserNames: readonly string[];
+  readonly sourceCodeLocationInfo: boolean; readonly parserBackedSourceSpans: boolean; readonly parserBackedDeclarationSpans: boolean; readonly parserBackedTriviaHashes: boolean;
+  readonly scopedCascadeGraphHashPresent: boolean; readonly parseErrors: number;
+  readonly sides: Readonly<Record<string, CssSafeMergeParserSideEvidence>>;
+}
+
+export interface CssSafeMergeParserSideEvidence {
+  readonly parserName: string;
+  readonly sourceCodeLocationInfo: boolean; readonly parserBackedSourceSpans: boolean; readonly parserBackedDeclarationSpans: boolean; readonly parserBackedTriviaHashes: boolean;
+  readonly scopedCascadeGraphHashPresent: boolean; readonly parseErrors: number; readonly recordCount: number; readonly declarationCount: number;
 }
 
 export interface CssSafeMergeInput {
-  readonly id?: string;
-  readonly sourcePath?: string;
-  readonly baseSourceText?: string;
-  readonly workerSourceText?: string;
-  readonly headSourceText?: string;
-  readonly cssModule?: boolean;
-  readonly cssModules?: boolean;
+  readonly id?: string; readonly sourcePath?: string; 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 scopedCascadeGraphHash?: 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;
-  readonly baseScopedCascadeGraphHash?: string;
-  readonly workerScopedCascadeGraphHash?: string;
-  readonly headScopedCascadeGraphHash?: string;
+  readonly generatedClassNameMapHash?: string; readonly jsTsUseSiteGraphHash?: string; readonly cssModuleCompositionGraphHash?: string; readonly icssGraphHash?: string; readonly scopedCascadeGraphHash?: 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;
+  readonly baseScopedCascadeGraphHash?: string; readonly workerScopedCascadeGraphHash?: string; readonly headScopedCascadeGraphHash?: string;
 }
 
 export declare function toCssAst(document: FrontierLangDocument, options?: CssProjectionOptions): CssAstStylesheet;

package/dist/index.js

@@ -1,5 +1,6 @@
 import { hashSemanticValue } from '@shapeshift-labs/frontier-lang-kernel';
 import { createCssModuleEvidence } from './css-modules.js';
+import { parsePostcssSemanticRecords } from './postcss-parser-evidence.js';
 import { safeMergeCssSource as safeMergeCssSourceImpl } from './semantic-merge.js';
 
 const ShorthandProperties = new Set(['all', 'animation', 'background', 'border', 'border-block', 'border-color', 'border-image', 'border-inline', 'border-radius', 'border-style', 'border-width', 'columns', 'flex', 'font', 'gap', 'grid', 'grid-area', 'grid-column', 'grid-row', 'inset', 'list-style', 'margin', 'offset', 'outline', 'overflow', 'padding', 'place-content', 'place-items', 'place-self', 'text-decoration', 'transition']);
@@ -57,11 +58,12 @@ export function emitCssWithSourceMap(document, options = {}) {
 }
 
 export function parseCssSemanticSheet(sourceText, options = {}) {
-  const lineStarts = computeLineStarts(sourceText);
   const sourceHash = options.sourceHash ?? hashSemanticValue({ kind: 'frontier.lang.css.source.v1', sourceText });
-  const records = parseCssBlocks(sourceText, 0, sourceText.length, [], lineStarts, sourceHash, options);
+  const parsed = parsePostcssSemanticRecords(sourceText, sourceHash, options);
+  const records = parsed.records;
   const cssModules = createCssModuleEvidence(records, options, sourceHash);
   const proofGaps = [
+    ...parsed.proofGaps,
     ...records.flatMap((record) => record.proofGaps ?? []),
     ...(cssModules?.proofGaps ?? [])
   ];
@@ -81,9 +83,11 @@ export function parseCssSemanticSheet(sourceText, options = {}) {
       cssModuleCompositions: cssModules?.compositions.length ?? 0,
       icssImports: cssModules?.icssImports.length ?? 0,
       icssExports: cssModules?.icssExports.length ?? 0,
-      proofGaps: proofGaps.length
+      proofGaps: proofGaps.length,
+      parseErrors: parsed.parser.parseErrors.length
     },
-    proofGaps
+    proofGaps,
+    parser: parsed.parser
   };
 }
 

package/dist/postcss-parser-evidence.js

@@ -0,0 +1,151 @@
+import { hashSemanticValue } from '@shapeshift-labs/frontier-lang-kernel';
+import postcss from 'postcss';
+
+const ShorthandProperties = new Set(['all', 'animation', 'background', 'border', 'border-block', 'border-color', 'border-image', 'border-inline', 'border-radius', 'border-style', 'border-width', 'columns', 'flex', 'font', 'gap', 'grid', 'grid-area', 'grid-column', 'grid-row', 'inset', 'list-style', 'margin', 'offset', 'outline', 'overflow', 'padding', 'place-content', 'place-items', 'place-self', 'text-decoration', 'transition']);
+const RuntimeAtRules = new Set(['keyframes', 'font-face', 'page', 'property']);
+const ScopeAtRules = new Set(['media', 'supports', 'container', 'layer', 'scope']);
+
+function parsePostcssSemanticRecords(sourceText, sourceHash, options) {
+  try {
+    const root = postcss.parse(sourceText, { from: options.sourcePath });
+    const records = postcssContainerRecords(root.nodes ?? [], [], sourceHash, options);
+    return { records, proofGaps: [], parser: { name: 'postcss', sourceCodeLocationInfo: true, parseErrors: [] } };
+  } catch (error) {
+    const reason = error?.reason ?? error?.message ?? 'CSS parser failed';
+    return {
+      records: [],
+      proofGaps: [proofGap('css-parser-error', `CSS parser rejected source: ${reason}`)],
+      parser: {
+        name: 'postcss',
+        sourceCodeLocationInfo: true,
+        parseErrors: [compactRecord({ reason, line: error?.line, column: error?.column, input: error?.input?.file })]
+      }
+    };
+  }
+}
+
+function postcssContainerRecords(nodes, scopes, sourceHash, options) {
+  const records = [];
+  for (const node of nodes) {
+    if (node.type === 'rule') records.push(postcssRuleRecord(node, scopes, sourceHash, options));
+    else if (node.type === 'atrule') {
+      records.push(postcssAtRuleRecord(node, scopes, sourceHash, options));
+      if (ScopeAtRules.has(String(node.name).toLowerCase()) && node.nodes?.length) {
+        records.push(...postcssContainerRecords(node.nodes, [...scopes, postcssAtRuleScopeKey(node)], sourceHash, options));
+      }
+    }
+  }
+  return records.sort((left, right) => left.sourceSpan.startOffset - right.sourceSpan.startOffset);
+}
+
+function postcssRuleRecord(node, scopes, sourceHash, options) {
+  const selectors = String(node.selector ?? '').split(',').map((selector) => selector.trim()).filter(Boolean);
+  const declarations = (node.nodes ?? []).filter((child) => child.type === 'decl').map(postcssDeclaration);
+  const nestedChildren = (node.nodes ?? []).filter((child) => child.type !== 'decl' && child.type !== 'comment');
+  const proofGaps = [
+    ...declarations.filter((declaration) => ShorthandProperties.has(declaration.property)).map((declaration) => proofGap('css-shorthand-expansion-unproved', `CSS shorthand ${declaration.property} needs longhand expansion evidence.`)),
+    ...scopes.length && !options.scopedCascadeGraphHash ? [proofGap('css-scoped-cascade-equivalence-unproved', 'Scoped cascade equivalence requires browser/style evidence.')] : [],
+    ...nestedChildren.length ? [proofGap('css-nesting-semantic-unproved', 'CSS nested rule semantics require nesting expansion evidence.')] : []
+  ];
+  return compactRecord({
+    kind: 'rule',
+    selectors,
+    selectorHash: hashSemanticValue({ kind: 'frontier.lang.css.selectors.v2.postcss', selectors }),
+    specificity: selectors.map(selectorSpecificity),
+    scopes,
+    declarations: declarations.map((declaration, ordinal) => ({
+      ...declaration,
+      ordinal,
+      cascadeKey: [...scopes, selectors.join(','), declaration.property].join('::'),
+      declarationHash: hashSemanticValue({ kind: 'frontier.lang.css.declaration.v2.postcss', scopes, selectors, property: declaration.property, rawProperty: declaration.rawProperty, value: declaration.value, important: declaration.important })
+    })),
+    customProperties: declarations.filter((declaration) => declaration.property.startsWith('--')).map((declaration) => declaration.property),
+    scopedCascadeGraphHash: scopes.length ? options.scopedCascadeGraphHash : undefined,
+    sourceSpan: sourceSpanFromPostcss(node.source, options.sourcePath),
+    sourceHash,
+    rawTextHash: hashSemanticValue({ kind: 'frontier.lang.css.rawRuleText.v1', text: node.toString() }),
+    ruleHash: hashSemanticValue({ kind: 'frontier.lang.css.rule.v2.postcss', selectors, scopes, declarations, nestedChildren: nestedChildren.map((child) => child.type) }),
+    parser: 'postcss',
+    proofGaps: proofGaps.length ? proofGaps : undefined
+  });
+}
+
+function postcssDeclaration(node) {
+  const property = String(node.prop ?? '').toLowerCase();
+  const value = String(node.value ?? '').trim();
+  return {
+    property,
+    rawProperty: node.raws?.prop?.raw ?? node.prop,
+    value,
+    important: node.important === true,
+    valueHash: hashSemanticValue({ kind: 'frontier.lang.css.value.v2.postcss', value }),
+    sourceSpan: sourceSpanFromPostcss(node.source, node.source?.input?.file),
+    rawTextHash: hashSemanticValue({ kind: 'frontier.lang.css.rawDeclarationText.v1', text: node.toString() })
+  };
+}
+
+function postcssAtRuleRecord(node, scopes, sourceHash, options) {
+  const atRuleName = String(node.name ?? 'unknown').toLowerCase();
+  const conditionText = String(node.params ?? '').trim();
+  const rawText = rawPostcssText(node);
+  const proofGaps = [];
+  if (RuntimeAtRules.has(atRuleName)) proofGaps.push(proofGap(`css-${atRuleName}-runtime-equivalence-unproved`, `CSS @${atRuleName} semantics require browser evidence.`));
+  if (ScopeAtRules.has(atRuleName) && !options.scopedCascadeGraphHash) proofGaps.push(proofGap(`css-${atRuleName}-cascade-scope-unproved`, `CSS @${atRuleName} scoped cascade requires condition evaluation evidence.`));
+  if (!node.nodes?.length && atRuleName === 'layer') proofGaps.push(proofGap('css-layer-order-statement-unsupported', 'CSS @layer statement order requires cascade order evidence.'));
+  else if (!node.nodes?.length) proofGaps.push(proofGap(`css-${atRuleName}-statement-equivalence-unproved`, `CSS @${atRuleName} statement semantics require host evidence.`));
+  const kind = node.nodes?.length ? 'at-rule' : 'at-rule-statement';
+  return compactRecord({
+    kind,
+    atRuleName,
+    conditionText,
+    statementText: kind === 'at-rule-statement' ? rawText : undefined,
+    scopeKey: postcssAtRuleScopeKey(node),
+    scopes,
+    scopedCascadeGraphHash: ScopeAtRules.has(atRuleName) ? options.scopedCascadeGraphHash : undefined,
+    sourceSpan: sourceSpanFromPostcss(node.source, options.sourcePath),
+    sourceHash,
+    rawTextHash: hashSemanticValue({ kind: 'frontier.lang.css.rawAtRuleText.v1', text: rawText }),
+    atRuleHash: hashSemanticValue({ kind: 'frontier.lang.css.atRule.v2.postcss', atRuleName, conditionText, scopes, statementText: kind === 'at-rule-statement' ? rawText : undefined }),
+    parser: 'postcss',
+    proofGaps: proofGaps.length ? proofGaps : undefined
+  });
+}
+
+function postcssAtRuleScopeKey(node) {
+  return `@${String(node.name ?? 'unknown').toLowerCase()} ${String(node.params ?? '').trim()}`.trim();
+}
+
+function sourceSpanFromPostcss(source, fallbackPath) {
+  const start = source?.start;
+  const end = source?.end;
+  if (!start || !end) return undefined;
+  return compactRecord({
+    path: fallbackPath,
+    startOffset: start.offset,
+    endOffset: end.offset,
+    startLine: start.line,
+    startColumn: start.column,
+    endLine: end.line,
+    endColumn: end.column
+  });
+}
+
+function rawPostcssText(node) {
+  const css = node.source?.input?.css;
+  const start = node.source?.start?.offset;
+  const end = node.source?.end?.offset;
+  return typeof css === 'string' && Number.isFinite(start) && Number.isFinite(end) ? css.slice(start, end) : node.toString();
+}
+
+function selectorSpecificity(selector) {
+  const withoutStrings = selector.replace(/"[^"]*"|'[^']*'/g, '');
+  const ids = (withoutStrings.match(/#[\w-]+/g) ?? []).length;
+  const classes = (withoutStrings.match(/\.[\w-]+|\[[^\]]+\]|:(?!:)[\w-]+(?:\([^)]*\))?/g) ?? []).length;
+  const elements = (withoutStrings.replace(/#[\w-]+|\.[\w-]+|\[[^\]]+\]|:{1,2}[\w-]+(?:\([^)]*\))?/g, ' ').match(/\b[A-Za-z][\w-]*\b/g) ?? []).length;
+  return [ids, classes, elements];
+}
+
+function proofGap(code, summary) { return { code, status: 'not-claimed', summary, failClosed: true, semanticEquivalenceClaim: false }; }
+function compactRecord(record) { return Object.fromEntries(Object.entries(record).filter(([, value]) => value !== undefined)); }
+
+export { parsePostcssSemanticRecords };

package/dist/semantic-merge.js

@@ -22,14 +22,16 @@ function safeMergeCssSource(input = {}, context = {}) {
   };
   const moduleChanges = cssModuleContractChanges(sheets, hash);
   const proofConflicts = proofGapConflicts(id, sourcePath, changed, indexes);
+  const parserConflicts = parserErrorConflicts(id, sourcePath, sheets);
   const overlapConflicts = [
     ...overlapDeclarationConflicts(id, sourcePath, changed.worker, changed.head),
     ...shorthandOverlapConflicts(id, sourcePath, changed.worker, changed.head)
   ];
   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 conflicts = [...parserConflicts, ...proofConflicts, ...overlapConflicts, ...moduleConflicts, ...sourceShapeConflicts];
+  const parserEvidence = mergeParserEvidence(sheets);
+  if (conflicts.length) return blocked(id, sourcePath, 'css-semantic-merge-conflict', conflicts, { parserEvidence });
   const mergedIndex = applyDeclarationChanges(applyDeclarationChanges(indexes.base, changed.head), changed.worker);
   return merged(id, sourcePath, renderDeclarationIndex(mergedIndex), 'semantic-declaration-merge', hash, {
     baseSheetHash: sheets.base.sheetHash,
@@ -38,7 +40,8 @@ function safeMergeCssSource(input = {}, context = {}) {
     workerChangedDeclarations: changed.worker.length,
     headChangedDeclarations: changed.head.length,
     workerChangedCssModuleContracts: moduleChanges.worker.length,
-    headChangedCssModuleContracts: moduleChanges.head.length
+    headChangedCssModuleContracts: moduleChanges.head.length,
+    parserEvidence
   });
 }
 
@@ -100,6 +103,44 @@ function proofGapConflicts(id, sourcePath, changed, indexes) {
   });
 }
 
+function parserErrorConflicts(id, sourcePath, sheets) {
+  return Object.entries(sheets).flatMap(([side, sheet]) => (sheet.proofGaps ?? [])
+    .filter((gap) => gap.code === 'css-parser-error')
+    .map((gap) => conflict(id, sourcePath, 'css-parser-error-blocked', gap.code, { side, proofGap: gap })));
+}
+
+function mergeParserEvidence(sheets) {
+  const entries = Object.entries(sheets).map(([side, sheet]) => [side, sheetParserEvidence(sheet)]);
+  return {
+    kind: 'frontier.lang.cssSafeMergeParserEvidence',
+    version: 1,
+    parserNames: unique(entries.map(([, evidence]) => evidence.parserName)),
+    sourceCodeLocationInfo: entries.every(([, evidence]) => evidence.sourceCodeLocationInfo === true),
+    parserBackedSourceSpans: entries.every(([, evidence]) => evidence.parserBackedSourceSpans === true),
+    parserBackedDeclarationSpans: entries.every(([, evidence]) => evidence.parserBackedDeclarationSpans === true),
+    parserBackedTriviaHashes: entries.every(([, evidence]) => evidence.parserBackedTriviaHashes === true),
+    scopedCascadeGraphHashPresent: entries.every(([, evidence]) => evidence.scopedCascadeGraphHashPresent === true),
+    parseErrors: entries.reduce((sum, [, evidence]) => sum + evidence.parseErrors, 0),
+    sides: Object.fromEntries(entries)
+  };
+}
+
+function sheetParserEvidence(sheet) {
+  const records = sheet.records ?? [];
+  const declarations = records.flatMap((record) => record.declarations ?? []);
+  return {
+    parserName: sheet.parser?.name ?? 'unknown',
+    sourceCodeLocationInfo: sheet.parser?.sourceCodeLocationInfo === true,
+    parserBackedSourceSpans: records.some((record) => record.parser === 'postcss' && record.sourceSpan?.startOffset !== undefined),
+    parserBackedDeclarationSpans: declarations.some((declaration) => declaration.sourceSpan?.startOffset !== undefined),
+    parserBackedTriviaHashes: records.some((record) => record.parser === 'postcss' && typeof record.rawTextHash === 'string'),
+    scopedCascadeGraphHashPresent: records.every((record) => !(record.scopes?.length) || Boolean(record.scopedCascadeGraphHash)),
+    parseErrors: sheet.parser?.parseErrors?.length ?? 0,
+    recordCount: records.length,
+    declarationCount: declarations.length
+  };
+}
+
 function overlapDeclarationConflicts(id, sourcePath, workerChanges, headChanges) {
   const headByKey = new Map(headChanges.map((change) => [change.key, change]));
   return workerChanges.flatMap((workerChange) => {
@@ -210,10 +251,11 @@ function merged(id, sourcePath, sourceText, operation, hash, extra = {}) {
   });
 }
 
-function blocked(id, sourcePath, reasonCode, conflicts = []) {
+function blocked(id, sourcePath, reasonCode, conflicts = [], extra = {}) {
   return result(id, sourcePath, 'blocked', {
     operation: 'blocked',
-    conflicts: conflicts.length ? conflicts : [conflict(id, sourcePath, reasonCode, reasonCode)]
+    conflicts: conflicts.length ? conflicts : [conflict(id, sourcePath, reasonCode, reasonCode)],
+    ...extra
   });
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shapeshift-labs/frontier-lang-css",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "CSS semantic merge evidence and projection adapter for Frontier Lang semantic source documents.",
   "type": "module",
   "main": "./dist/index.js",
@@ -53,7 +53,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@shapeshift-labs/frontier-lang-kernel": "0.3.12"
+    "@shapeshift-labs/frontier-lang-kernel": "0.3.12",
+    "postcss": "^8.5.15"
   },
   "devDependencies": {
     "typescript": "^5.9.3"