@shapeshift-labs/frontier-lang-parser 0.3.33 → 0.3.35

package/README.md

@@ -220,6 +220,22 @@ npm install @shapeshift-labs/frontier-lang-parser
 
 The parser projects text into `@shapeshift-labs/frontier-lang-kernel` documents. The syntax is intentionally small and experimental.
 
+## Source syntax reports
+
+Use `inspectFrontierSourceSyntax` when a `.frontier` file is being treated as authored source, not only as convenient input to `parseFrontierSource`. It returns a `frontier.lang.sourceSyntaxReport` with every module-level or top-level declaration block the parser can see, whether that block kind is recognized, and any unsupported block kinds that would make a translation or merge proof fail closed.
+
+```js
+import { inspectFrontierSourceSyntax } from '@shapeshift-labs/frontier-lang-parser';
+
+const report = inspectFrontierSourceSyntax(source);
+
+if (report.summary.failClosed) {
+  console.error(report.summary.unknownKinds, report.diagnostics);
+}
+```
+
+Nested child syntax such as `render` blocks inside a `view` is not reported as an unknown top-level block; the parent parser owns those child rows. The report ignores braces inside quoted strings and comments when finding authored declaration boundaries, reports UTF-8 `sourceBytes`, and fails closed for malformed or unterminated blocks through `diagnostics`. The report is evidence about parser coverage only. It keeps `autoMergeClaim` and `semanticEquivalenceClaim` false.
+
 ## Authored view render graph syntax
 
 `.frontier` view blocks can describe UI render graphs directly. Nested `render`

package/dist/index.d.ts

@@ -1,4 +1,57 @@
 import type { FrontierLangDocument } from '@shapeshift-labs/frontier-lang-kernel';
 export interface ParseFrontierOptions { readonly id?: string; readonly name?: string; }
+export declare const FrontierSourceBlockKinds: readonly string[];
+export interface FrontierSourceSyntaxDiagnostic {
+  readonly reason: 'unterminated-block' | 'unmatched-close-brace';
+  readonly message: string;
+  readonly location: { readonly line: number; readonly column: number; readonly offset: number };
+}
+export interface FrontierSourceBlockSyntaxRecord {
+  readonly kind: string;
+  readonly name: string;
+  readonly id?: string;
+  readonly header: string;
+  readonly startOffset: number;
+  readonly endOffset: number;
+  readonly bodyStartOffset: number;
+  readonly bodyEndOffset: number;
+  readonly location: { readonly line: number; readonly column: number; readonly offset: number };
+  readonly moduleId?: string;
+  readonly moduleName?: string;
+  readonly recognized: boolean;
+  readonly malformed?: boolean;
+  readonly diagnostics?: readonly FrontierSourceSyntaxDiagnostic[];
+}
+export interface FrontierUnknownSourceBlockSyntaxRecord extends FrontierSourceBlockSyntaxRecord {
+  readonly recognized: false;
+  readonly reason: 'unsupported-top-level-block';
+}
+export interface FrontierSourceSyntaxReport {
+  readonly kind: 'frontier.lang.sourceSyntaxReport';
+  readonly version: 1;
+  readonly documentId: string;
+  readonly documentName: string;
+  readonly blocks: readonly FrontierSourceBlockSyntaxRecord[];
+  readonly recognizedBlocks: readonly FrontierSourceBlockSyntaxRecord[];
+  readonly unknownBlocks: readonly FrontierUnknownSourceBlockSyntaxRecord[];
+  readonly summary: {
+    readonly blockCount: number;
+    readonly recognizedBlockCount: number;
+    readonly unknownBlockCount: number;
+    readonly malformedBlockCount: number;
+    readonly diagnosticCount: number;
+    readonly recognizedKinds: readonly string[];
+    readonly unknownKinds: readonly string[];
+    readonly failClosed: boolean;
+    readonly unsupportedSyntax: boolean;
+  };
+  readonly diagnostics: readonly FrontierSourceSyntaxDiagnostic[];
+  readonly metadata: {
+    readonly sourceBytes: number;
+    readonly autoMergeClaim: false;
+    readonly semanticEquivalenceClaim: false;
+  };
+}
+export declare function inspectFrontierSourceSyntax(source: string, options?: ParseFrontierOptions): FrontierSourceSyntaxReport;
 export declare function parseFrontierSource(source: string, options?: ParseFrontierOptions): FrontierLangDocument;
 export declare function parseFrontierFile(name: string, source: string): FrontierLangDocument;

package/dist/index.js

@@ -16,6 +16,8 @@ import { parseRuntimeCapabilityBlock } from './runtime-capability.js';
 import { parseNativeSourceBlock } from './source-evidence.js';
 import { parseTargetProjectionMetadata } from './target-projection.js';
 import { parseViewBlock } from './view.js';
+import { FrontierSourceBlockKinds } from './source-syntax-report.js';
+export { FrontierSourceBlockKinds, inspectFrontierSourceSyntax } from './source-syntax-report.js';
 
 export function parseFrontierSource(source, options = {}) {
   const nodes = [];
@@ -76,7 +78,7 @@ function readName(source) { return /module\s+([A-Za-z_$][\w$]*)/.exec(source)?.[
 function readId(source) { return /module\s+[A-Za-z_$][\w$]*\s+@id\(\s*["']([^"']+)["']\s*\)/.exec(source)?.[1]; }
 function readBlocks(source) {
   const blocks = [];
-  const header = /\b(entity|state|action|view|migration|capability|effect|type|extern|lattice|nativeSource|target|proof|paradigm|paradigmSemantics|operations|semanticOperations|conversion|universalConversionPlan|constraintSpace|possibilitySpace|decisionGraph|admissionGraph|dialectRegistry|universalDialectRegistry|interlingua|universalInterlingua|resourceGraph|semanticResourceGraph|packageManifest|packageGraph|packageSurface|canvasSurface|canvasGraph|applicationSurface|appHost|plugin|pluginSurface|pluginContract|runtimeCapabilities|runtimeCapabilityMatrix|runtimeHosts)\s+([^{}]+)\{/g;
+  const header = new RegExp('\\b(' + FrontierSourceBlockKinds.join('|') + ')\\s+([^{}]+)\\{', 'g');
   let match;
   while ((match = header.exec(source))) {
     let depth = 1; let index = header.lastIndex;

package/dist/source-syntax-report.js

@@ -0,0 +1,284 @@
+export const FrontierSourceBlockKinds = Object.freeze([
+  'entity',
+  'state',
+  'action',
+  'view',
+  'migration',
+  'capability',
+  'effect',
+  'type',
+  'extern',
+  'lattice',
+  'nativeSource',
+  'target',
+  'proof',
+  'paradigm',
+  'paradigmSemantics',
+  'operations',
+  'semanticOperations',
+  'conversion',
+  'universalConversionPlan',
+  'constraintSpace',
+  'possibilitySpace',
+  'decisionGraph',
+  'admissionGraph',
+  'dialectRegistry',
+  'universalDialectRegistry',
+  'interlingua',
+  'universalInterlingua',
+  'resourceGraph',
+  'semanticResourceGraph',
+  'packageManifest',
+  'packageGraph',
+  'packageSurface',
+  'canvasSurface',
+  'canvasGraph',
+  'applicationSurface',
+  'appHost',
+  'plugin',
+  'pluginSurface',
+  'pluginContract',
+  'runtimeCapabilities',
+  'runtimeCapabilityMatrix',
+  'runtimeHosts'
+]);
+
+const FrontierSourceBlockKindSet = new Set(FrontierSourceBlockKinds);
+
+export function inspectFrontierSourceSyntax(source, options = {}) {
+  const documentId = options.id ?? readId(source) ?? 'mod_frontier';
+  const documentName = options.name ?? readName(source) ?? 'FrontierModule';
+  const structure = scanFrontierStructure(source);
+  const blocks = readCandidateDeclarationBlocks(source, structure).map((block) => ({
+    ...block,
+    recognized: FrontierSourceBlockKindSet.has(block.kind)
+  }));
+  const recognizedBlocks = blocks.filter((block) => block.recognized);
+  const unknownBlocks = blocks.filter((block) => !block.recognized).map((block) => ({
+    ...block,
+    reason: 'unsupported-top-level-block'
+  }));
+  const malformedBlockOpenOffsets = new Set(blocks.filter((block) => block.malformed).map((block) => block.bodyStartOffset - 1));
+  const diagnostics = [
+    ...blocks.flatMap((block) => block.diagnostics ?? []),
+    ...structure.unmatchedOpenBraces.filter((offset) => !malformedBlockOpenOffsets.has(offset)).map((offset) => ({
+      reason: 'unterminated-block',
+      message: 'Found an opening brace without a matching closing brace.',
+      location: sourcePosition(source, offset)
+    })),
+    ...structure.unmatchedCloseBraces.map((offset) => ({
+      reason: 'unmatched-close-brace',
+      message: 'Found a closing brace without a matching opening brace.',
+      location: sourcePosition(source, offset)
+    }))
+  ];
+  const malformedBlocks = blocks.filter((block) => block.malformed);
+  const failClosed = unknownBlocks.length > 0 || diagnostics.length > 0;
+  return {
+    kind: 'frontier.lang.sourceSyntaxReport',
+    version: 1,
+    documentId,
+    documentName,
+    blocks,
+    recognizedBlocks,
+    unknownBlocks,
+    summary: {
+      blockCount: blocks.length,
+      recognizedBlockCount: recognizedBlocks.length,
+      unknownBlockCount: unknownBlocks.length,
+      malformedBlockCount: malformedBlocks.length,
+      diagnosticCount: diagnostics.length,
+      recognizedKinds: unique(recognizedBlocks.map((block) => block.kind)),
+      unknownKinds: unique(unknownBlocks.map((block) => block.kind)),
+      failClosed,
+      unsupportedSyntax: unknownBlocks.length > 0
+    },
+    diagnostics,
+    metadata: {
+      sourceBytes: utf8ByteLength(source),
+      autoMergeClaim: false,
+      semanticEquivalenceClaim: false
+    }
+  };
+}
+
+function readCandidateDeclarationBlocks(source, structure) {
+  const moduleRanges = readModuleRanges(source, structure);
+  const blocks = [];
+  const header = /(^|\n)\s*([A-Za-z_$][\w$]*)\s+([^{}\n]+)\{/g;
+  let match;
+  while ((match = header.exec(source))) {
+    const fullStart = match.index + match[1].length;
+    const leading = /^\s*/.exec(source.slice(fullStart))?.[0].length ?? 0;
+    const start = fullStart + leading;
+    const kind = match[2];
+    if (kind === 'module') continue;
+    const open = header.lastIndex - 1;
+    if (!structure.codeOffsets[start] || !structure.codeOffsets[open]) continue;
+    const close = findMatchingBrace(structure, open);
+    const malformed = close < 0;
+    const end = malformed ? source.length : close + 1;
+    const bodyEnd = malformed ? source.length : close;
+    const depth = braceDepthBefore(structure, start);
+    const moduleRange = moduleRanges.find((range) => start > range.open && start < range.close);
+    const declarationDepth = moduleRange ? moduleRange.depth + 1 : 0;
+    if (depth !== declarationDepth) continue;
+    const headerText = match[3].trim();
+    blocks.push({
+      kind,
+      name: nameFrom(headerText),
+      id: idFrom(headerText),
+      header: headerText,
+      startOffset: start,
+      endOffset: end,
+      bodyStartOffset: open + 1,
+      bodyEndOffset: bodyEnd,
+      location: sourcePosition(source, start),
+      moduleId: moduleRange?.id,
+      moduleName: moduleRange?.name,
+      malformed,
+      diagnostics: malformed ? [{
+        reason: 'unterminated-block',
+        message: `Block "${kind}" has no matching closing brace.`,
+        location: sourcePosition(source, open)
+      }] : []
+    });
+  }
+  return blocks;
+}
+
+function readModuleRanges(source, structure) {
+  const ranges = [];
+  const header = /(^|\n)\s*module\s+([^{}\n]+)\{/g;
+  let match;
+  while ((match = header.exec(source))) {
+    const fullStart = match.index + match[1].length;
+    const leading = /^\s*/.exec(source.slice(fullStart))?.[0].length ?? 0;
+    const start = fullStart + leading;
+    const open = header.lastIndex - 1;
+    if (!structure.codeOffsets[start] || !structure.codeOffsets[open]) continue;
+    const close = findMatchingBrace(structure, open);
+    const malformed = close < 0;
+    ranges.push({
+      start,
+      open,
+      close: malformed ? source.length : close,
+      depth: braceDepthBefore(structure, start),
+      name: nameFrom(match[2].trim()),
+      id: idFrom(match[2].trim()),
+      malformed
+    });
+  }
+  return ranges;
+}
+
+function findMatchingBrace(structure, open) {
+  return structure.bracePairs.get(open) ?? -1;
+}
+
+function braceDepthBefore(structure, offset) {
+  return structure.depthBefore[Math.min(Math.max(offset, 0), structure.depthBefore.length - 1)] ?? 0;
+}
+
+function scanFrontierStructure(source) {
+  const depthBefore = new Int32Array(source.length + 1);
+  const codeOffsets = new Uint8Array(source.length);
+  const stack = [];
+  const bracePairs = new Map();
+  const unmatchedCloseBraces = [];
+  let depth = 0;
+  let state = 'code';
+  let quote = '';
+  for (let index = 0; index < source.length; index++) {
+    depthBefore[index] = depth;
+    const char = source[index];
+    const next = source[index + 1];
+    if (state === 'line-comment') {
+      if (char === '\n') state = 'code';
+      continue;
+    }
+    if (state === 'block-comment') {
+      if (char === '*' && next === '/') {
+        depthBefore[index + 1] = depth;
+        index++;
+        state = 'code';
+      }
+      continue;
+    }
+    if (state === 'string') {
+      if (char === '\\') {
+        depthBefore[index + 1] = depth;
+        index++;
+        continue;
+      }
+      if (char === quote) {
+        state = 'code';
+        quote = '';
+      }
+      continue;
+    }
+    codeOffsets[index] = 1;
+    if (char === '/' && next === '/') {
+      codeOffsets[index + 1] = 0;
+      depthBefore[index + 1] = depth;
+      index++;
+      state = 'line-comment';
+      continue;
+    }
+    if (char === '/' && next === '*') {
+      codeOffsets[index + 1] = 0;
+      depthBefore[index + 1] = depth;
+      index++;
+      state = 'block-comment';
+      continue;
+    }
+    if (char === '#' && isLineLeadingWhitespace(source, index)) {
+      state = 'line-comment';
+      continue;
+    }
+    if (char === '"' || char === "'" || char === '`') {
+      state = 'string';
+      quote = char;
+      continue;
+    }
+    if (char === '{') {
+      stack.push(index);
+      depth++;
+      continue;
+    }
+    if (char === '}') {
+      const open = stack.pop();
+      if (open === undefined) {
+        unmatchedCloseBraces.push(index);
+        continue;
+      }
+      depth = Math.max(0, depth - 1);
+      bracePairs.set(open, index);
+    }
+  }
+  depthBefore[source.length] = depth;
+  return { bracePairs, codeOffsets, depthBefore, unmatchedCloseBraces, unmatchedOpenBraces: stack };
+}
+
+function isLineLeadingWhitespace(source, offset) {
+  for (let index = offset - 1; index >= 0 && source[index] !== '\n'; index--) {
+    if (!/\s/.test(source[index])) return false;
+  }
+  return true;
+}
+
+function utf8ByteLength(source) {
+  if (typeof TextEncoder !== 'undefined') return new TextEncoder().encode(source).length;
+  return unescape(encodeURIComponent(source)).length;
+}
+
+function sourcePosition(source, offset) {
+  const lines = source.slice(0, offset).split('\n');
+  return { line: lines.length, column: lines[lines.length - 1].length + 1, offset };
+}
+
+function readName(source) { return /module\s+([A-Za-z_$][\w$]*)/.exec(source)?.[1]; }
+function readId(source) { return /module\s+[A-Za-z_$][\w$]*\s+@id\(\s*["']([^"']+)["']\s*\)/.exec(source)?.[1]; }
+function idFrom(header) { return /@id\(\s*["']([^"']+)["']\s*\)/.exec(header)?.[1]; }
+function nameFrom(header) { return /^([A-Za-z_$][\w$]*)/.exec(header)?.[1] ?? 'Unnamed'; }
+function unique(values) { return [...new Set(values.filter(Boolean))]; }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shapeshift-labs/frontier-lang-parser",
-  "version": "0.3.33",
+  "version": "0.3.35",
   "description": "Parser for the first Frontier Lang .frontier syntax slice.",
   "type": "module",
   "main": "./dist/index.js",