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

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);
+}
+```
+
+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 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,47 @@
 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 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;
+}
+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 recognizedKinds: readonly string[];
+    readonly unknownKinds: readonly string[];
+    readonly failClosed: boolean;
+    readonly unsupportedSyntax: boolean;
+  };
+  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,170 @@
+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 blocks = readCandidateDeclarationBlocks(source).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'
+  }));
+  return {
+    kind: 'frontier.lang.sourceSyntaxReport',
+    version: 1,
+    documentId,
+    documentName,
+    blocks,
+    recognizedBlocks,
+    unknownBlocks,
+    summary: {
+      blockCount: blocks.length,
+      recognizedBlockCount: recognizedBlocks.length,
+      unknownBlockCount: unknownBlocks.length,
+      recognizedKinds: unique(recognizedBlocks.map((block) => block.kind)),
+      unknownKinds: unique(unknownBlocks.map((block) => block.kind)),
+      failClosed: unknownBlocks.length > 0,
+      unsupportedSyntax: unknownBlocks.length > 0
+    },
+    metadata: {
+      sourceBytes: source.length,
+      autoMergeClaim: false,
+      semanticEquivalenceClaim: false
+    }
+  };
+}
+
+function readCandidateDeclarationBlocks(source) {
+  const moduleRanges = readModuleRanges(source);
+  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;
+    const close = findMatchingBrace(source, open);
+    const depth = braceDepthBefore(source, 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: close + 1,
+      bodyStartOffset: open + 1,
+      bodyEndOffset: close,
+      location: sourcePosition(source, start),
+      moduleId: moduleRange?.id,
+      moduleName: moduleRange?.name
+    });
+  }
+  return blocks;
+}
+
+function readModuleRanges(source) {
+  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;
+    const close = findMatchingBrace(source, open);
+    ranges.push({
+      start,
+      open,
+      close,
+      depth: braceDepthBefore(source, start),
+      name: nameFrom(match[2].trim()),
+      id: idFrom(match[2].trim())
+    });
+  }
+  return ranges;
+}
+
+function findMatchingBrace(source, open) {
+  let depth = 1;
+  for (let index = open + 1; index < source.length; index++) {
+    if (source[index] === '{') depth++;
+    if (source[index] === '}') depth--;
+    if (depth === 0) return index;
+  }
+  return source.length - 1;
+}
+
+function braceDepthBefore(source, offset) {
+  let depth = 0;
+  for (let index = 0; index < offset; index++) {
+    if (source[index] === '{') depth++;
+    if (source[index] === '}') depth = Math.max(0, depth - 1);
+  }
+  return depth;
+}
+
+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.34",
   "description": "Parser for the first Frontier Lang .frontier syntax slice.",
   "type": "module",
   "main": "./dist/index.js",