@prisma-next/psl-parser 0.14.0 → 0.15.0-dev.1

package/src/attribute-spec/combinators/str.ts

@@ -0,0 +1,19 @@
+import type { PslDiagnostic } from '@prisma-next/framework-components/psl-ast';
+import { notOk, ok, type Result } from '@prisma-next/utils/result';
+import { StringLiteralExprAst } from '../../syntax/ast/expressions';
+import type { ArgType } from '../types';
+import { leafDiagnostic } from './diagnostic';
+
+export function str(): ArgType<string> {
+  return {
+    kind: 'str',
+    label: 'string',
+    parse: (arg, ctx): Result<string, readonly PslDiagnostic[]> => {
+      if (arg instanceof StringLiteralExprAst) {
+        const value = arg.value();
+        if (value !== undefined) return ok(value);
+      }
+      return notOk([leafDiagnostic(ctx, arg, 'Expected a string literal')]);
+    },
+  };
+}

package/src/attribute-spec/field-attribute.ts

@@ -0,0 +1,27 @@
+import type { PslDiagnostic } from '@prisma-next/framework-components/psl-ast';
+import type { AttributeOut, AttributeSpec, InterpretCtx, Param, PositionalParam } from './types';
+
+interface FieldAttributeConfig<
+  Pos extends readonly PositionalParam[],
+  Named extends Record<string, Param<unknown>>,
+> {
+  readonly positional?: Pos;
+  readonly named?: Named;
+  readonly refine?: (
+    parsed: AttributeOut<Pos, Named>,
+    ctx: InterpretCtx,
+  ) => readonly PslDiagnostic[];
+}
+
+export function fieldAttribute<
+  const Pos extends readonly PositionalParam[] = readonly [],
+  const Named extends Record<string, Param<unknown>> = Record<never, never>,
+>(name: string, config: FieldAttributeConfig<Pos, Named>): AttributeSpec<AttributeOut<Pos, Named>> {
+  return {
+    level: 'field',
+    name,
+    positional: config.positional ?? [],
+    named: config.named ?? {},
+    ...(config.refine !== undefined ? { refine: config.refine } : {}),
+  };
+}

package/src/attribute-spec/interpret.ts

@@ -0,0 +1,177 @@
+import type { PslDiagnostic, PslSpan } from '@prisma-next/framework-components/psl-ast';
+import { blindCast } from '@prisma-next/utils/casts';
+import { notOk, ok, type Result } from '@prisma-next/utils/result';
+import { nodePslSpan } from '../resolve';
+import type { FieldAttributeAst, ModelAttributeAst } from '../syntax/ast/attributes';
+import type { AttributeArgAst } from '../syntax/ast/expressions';
+import { ATTRIBUTE_DIAGNOSTIC_CODE } from './combinators/diagnostic';
+import type {
+  ArgType,
+  AttributeSpec,
+  InterpretCtx,
+  OptionalArgType,
+  Param,
+  PositionalParam,
+} from './types';
+
+// The positional/named argument-binding for an attribute or a function call. `name` labels the
+// callee in binding diagnostics (`Attribute "<name>" …`); `span` anchors the arity diagnostics
+// (too-many / missing) that have no per-argument node to point at.
+export interface ArgBindingSpec {
+  readonly name: string;
+  readonly positional: readonly PositionalParam<unknown>[];
+  readonly named: Readonly<Record<string, Param<unknown>>>;
+}
+
+export function interpretArgs(
+  args: Iterable<AttributeArgAst>,
+  spec: ArgBindingSpec,
+  ctx: InterpretCtx,
+  span: PslSpan,
+): Result<Record<string, unknown>, readonly PslDiagnostic[]> {
+  const diagnostics: PslDiagnostic[] = [];
+
+  const output: Record<string, unknown> = {};
+  const seen = new Set<string>();
+  let positionalSlot = 0;
+  let reportedExcess = false;
+
+  for (const arg of args) {
+    const name = arg.name()?.name();
+
+    let key: string;
+    let param: Param<unknown>;
+    if (name === undefined) {
+      const posParam = spec.positional[positionalSlot];
+      if (posParam === undefined) {
+        if (!reportedExcess) {
+          diagnostics.push(
+            diagnostic(
+              `Attribute "${spec.name}" received too many positional arguments`,
+              ctx,
+              span,
+            ),
+          );
+          reportedExcess = true;
+        }
+        continue;
+      }
+      positionalSlot += 1;
+      key = posParam.key;
+      param = posParam.type;
+    } else {
+      const namedParam = Object.hasOwn(spec.named, name) ? spec.named[name] : undefined;
+      if (namedParam === undefined) {
+        diagnostics.push(
+          diagnostic(
+            `Attribute "${spec.name}" received unknown argument "${name}"`,
+            ctx,
+            nodePslSpan(arg.syntax, ctx.sourceFile),
+          ),
+        );
+        continue;
+      }
+      key = name;
+      param = namedParam;
+    }
+
+    if (seen.has(key)) {
+      diagnostics.push(
+        diagnostic(
+          `Attribute "${spec.name}" received duplicate argument "${key}"`,
+          ctx,
+          nodePslSpan(arg.syntax, ctx.sourceFile),
+        ),
+      );
+      continue;
+    }
+    seen.add(key);
+    const result = parseArgValue(arg, param, ctx, diagnostics);
+    if (result.ok) output[key] = result.value;
+  }
+
+  const finalized = new Set<string>();
+  const finalizeAbsentKey = (
+    key: string,
+    positionalParam: Param<unknown> | undefined,
+    namedParam: Param<unknown> | undefined,
+  ): void => {
+    if (finalized.has(key) || seen.has(key)) return;
+    finalized.add(key);
+    const effective = namedParam ?? positionalParam;
+    if (effective === undefined) return;
+    if (isOptionalArgType(effective)) {
+      if (effective.hasDefault) output[key] = effective.defaultValue;
+      return;
+    }
+    diagnostics.push(
+      diagnostic(`Attribute "${spec.name}" is missing required argument "${key}"`, ctx, span),
+    );
+  };
+
+  for (const param of spec.positional) {
+    const namedParam = Object.hasOwn(spec.named, param.key) ? spec.named[param.key] : undefined;
+    finalizeAbsentKey(param.key, param.type, namedParam);
+  }
+  for (const key of Object.keys(spec.named)) {
+    finalizeAbsentKey(key, undefined, spec.named[key]);
+  }
+
+  if (diagnostics.length > 0) {
+    return notOk<readonly PslDiagnostic[]>(diagnostics);
+  }
+  return ok(output);
+}
+
+export function interpretAttribute<Out>(
+  attrNode: FieldAttributeAst | ModelAttributeAst,
+  spec: AttributeSpec<Out>,
+  ctx: InterpretCtx,
+): Result<Out, readonly PslDiagnostic[]> {
+  const attributeSpan = nodePslSpan(attrNode.syntax, ctx.sourceFile);
+  const bound = interpretArgs(attrNode.argList()?.args() ?? [], spec, ctx, attributeSpan);
+  if (!bound.ok) return notOk<readonly PslDiagnostic[]>(bound.failure);
+
+  const value = blindCast<
+    Out,
+    'The engine builds the output object structurally from the spec; TypeScript cannot relate the dynamically-keyed record to the spec-inferred output type.'
+  >(bound.value);
+  if (spec.refine !== undefined) {
+    const refineDiagnostics = spec.refine(value, ctx);
+    if (refineDiagnostics.length > 0) {
+      return notOk<readonly PslDiagnostic[]>(refineDiagnostics);
+    }
+  }
+  return ok(value);
+}
+
+function parseArgValue(
+  arg: AttributeArgAst,
+  argType: ArgType<unknown>,
+  ctx: InterpretCtx,
+  diagnostics: PslDiagnostic[],
+): Result<unknown, readonly PslDiagnostic[]> {
+  const value = arg.value();
+  if (value === undefined) {
+    const missing = diagnostic(
+      'Attribute argument is missing a value',
+      ctx,
+      nodePslSpan(arg.syntax, ctx.sourceFile),
+    );
+    diagnostics.push(missing);
+    return notOk<readonly PslDiagnostic[]>([missing]);
+  }
+  const result = argType.parse(value, ctx);
+  if (!result.ok) {
+    for (const failure of result.failure) diagnostics.push(failure);
+  }
+  return result;
+}
+
+function isOptionalArgType(param: Param<unknown>): param is OptionalArgType<unknown> {
+  return 'optional' in param && param.optional === true;
+}
+
+function diagnostic(message: string, ctx: InterpretCtx, span: PslSpan): PslDiagnostic {
+  return { code: ATTRIBUTE_DIAGNOSTIC_CODE, message, sourceId: ctx.sourceId, span };
+}

package/src/attribute-spec/model-attribute.ts

@@ -0,0 +1,27 @@
+import type { PslDiagnostic } from '@prisma-next/framework-components/psl-ast';
+import type { AttributeOut, AttributeSpec, InterpretCtx, Param, PositionalParam } from './types';
+
+interface ModelAttributeConfig<
+  Pos extends readonly PositionalParam[],
+  Named extends Record<string, Param<unknown>>,
+> {
+  readonly positional?: Pos;
+  readonly named?: Named;
+  readonly refine?: (
+    parsed: AttributeOut<Pos, Named>,
+    ctx: InterpretCtx,
+  ) => readonly PslDiagnostic[];
+}
+
+export function modelAttribute<
+  const Pos extends readonly PositionalParam[] = readonly [],
+  const Named extends Record<string, Param<unknown>> = Record<never, never>,
+>(name: string, config: ModelAttributeConfig<Pos, Named>): AttributeSpec<AttributeOut<Pos, Named>> {
+  return {
+    level: 'model',
+    name,
+    positional: config.positional ?? [],
+    named: config.named ?? {},
+    ...(config.refine !== undefined ? { refine: config.refine } : {}),
+  };
+}

package/src/attribute-spec/optional.ts

@@ -0,0 +1,8 @@
+import type { ArgType, OptionalArgType } from './types';
+
+export function optional<T>(type: ArgType<T>, ...rest: [defaultValue: T] | []): OptionalArgType<T> {
+  if (rest.length === 0) {
+    return { ...type, optional: true, hasDefault: false };
+  }
+  return { ...type, optional: true, hasDefault: true, defaultValue: rest[0] };
+}

package/src/attribute-spec/types.ts

@@ -0,0 +1,72 @@
+import type { PslDiagnostic } from '@prisma-next/framework-components/psl-ast';
+import type { Result } from '@prisma-next/utils/result';
+import type { Simplify, UnionToIntersection } from '@prisma-next/utils/types';
+import type { SourceFile } from '../source-file';
+import type { FieldSymbol, ModelSymbol } from '../symbol-table';
+import type { ExpressionAst } from '../syntax/ast/expressions';
+
+export type AttributeLevel = 'field' | 'model' | 'block';
+
+export interface ArgType<T> {
+  readonly kind: string;
+  readonly label: string;
+  // phantom carrier for `T`; never read at runtime.
+  readonly _out?: T;
+  parse(arg: ExpressionAst, ctx: InterpretCtx): Result<T, readonly PslDiagnostic[]>;
+}
+
+export interface InterpretCtx {
+  readonly level: AttributeLevel;
+  readonly sourceId: string;
+  readonly sourceFile: SourceFile;
+  readonly selfModel: ModelSymbol;
+  resolveReferencedModel(): ModelSymbol | undefined;
+  readonly field?: FieldSymbol;
+}
+
+export interface OptionalArgType<T> extends ArgType<T> {
+  // the engine detects optionality by checking for this marker (`'optional' in param`).
+  readonly optional: true;
+  readonly hasDefault: boolean;
+  readonly defaultValue?: T;
+}
+
+export type Param<T> = ArgType<T>;
+
+export interface PositionalParam<T = unknown> {
+  readonly key: string;
+  readonly type: Param<T>;
+}
+
+export interface AttributeSpec<Out> {
+  readonly level: AttributeLevel;
+  readonly name: string;
+  readonly positional: readonly PositionalParam[];
+  readonly named: Readonly<Record<string, Param<unknown>>>;
+  readonly refine?: (parsed: Out, ctx: InterpretCtx) => readonly PslDiagnostic[];
+}
+
+export type OutOf<P> = P extends ArgType<infer T> ? T : never;
+
+export type NamedOut<N extends Record<string, Param<unknown>>> = Simplify<
+  { [K in keyof N as N[K] extends OptionalArgType<unknown> ? never : K]: OutOf<N[K]> } & {
+    [K in keyof N as N[K] extends OptionalArgType<unknown> ? K : never]?: OutOf<N[K]>;
+  }
+>;
+
+type PosEntryObject<E extends PositionalParam> =
+  E['type'] extends OptionalArgType<unknown>
+    ? { [K in E['key']]?: OutOf<E['type']> }
+    : { [K in E['key']]: OutOf<E['type']> };
+
+export type PosOut<Pos extends readonly PositionalParam[]> = Simplify<
+  UnionToIntersection<{ [I in keyof Pos]: PosEntryObject<Pos[I]> }[number]>
+>;
+
+export type AttributeOut<
+  Pos extends readonly PositionalParam[],
+  Named extends Record<string, Param<unknown>>,
+> = Simplify<PosOut<Pos> & NamedOut<Named>>;
+
+// `S` is unconstrained on purpose: `refine` makes `Out` contravariant, so a bound like `S extends AttributeSpec<unknown>` would reject every spec that uses `refine`.
+export type InferAttr<S> = S extends AttributeSpec<infer Out> ? Out : never;

package/src/block-reconstruction.ts

@@ -0,0 +1,140 @@
+import type { AuthoringPslBlockDescriptor } from '@prisma-next/framework-components/authoring';
+import type {
+  PslBlockParam,
+  PslExtensionBlock,
+  PslExtensionBlockAttribute,
+  PslExtensionBlockParamValue,
+  PslSpan,
+} from '@prisma-next/framework-components/psl-ast';
+import type { ParseDiagnostic } from './parse';
+import { nodePslSpan } from './resolve';
+import type { SourceFile } from './source-file';
+import type { GenericBlockDeclarationAst, KeyValuePairAst } from './syntax/ast/declarations';
+import { ArrayLiteralAst, type ExpressionAst } from './syntax/ast/expressions';
+import { printSyntax } from './syntax/ast-helpers';
+
+/**
+ * Descriptor-free and unknown parameters become `value` stubs so validation can
+ * report them via key-set comparison. Duplicate member names are first-wins.
+ */
+export function reconstructExtensionBlock(
+  node: GenericBlockDeclarationAst,
+  descriptor: AuthoringPslBlockDescriptor | undefined,
+  sourceFile: SourceFile,
+  diagnostics: ParseDiagnostic[],
+): PslExtensionBlock {
+  const keyword = node.keyword()?.text ?? '';
+  const blockName = node.name()?.name() ?? '';
+
+  const blockAttributes: PslExtensionBlockAttribute[] = [];
+  for (const attribute of node.attributes()) {
+    const name = attribute.name()?.path().join('.') ?? '';
+    const args = Array.from(attribute.argList()?.args() ?? [], (arg) => {
+      const value = arg.value();
+      return {
+        kind: 'positional' as const,
+        value: value === undefined ? '' : printSyntax(value.syntax).trim(),
+        span: nodePslSpan(arg.syntax, sourceFile),
+      };
+    });
+    blockAttributes.push({
+      name,
+      args,
+      span: nodePslSpan(attribute.syntax, sourceFile),
+    });
+  }
+
+  const parameters: Record<string, PslExtensionBlockParamValue> = {};
+  for (const entry of node.entries()) {
+    const key = entry.key()?.name();
+    if (key === undefined) continue;
+    const span = nodePslSpan(entry.syntax, sourceFile);
+    if (Object.hasOwn(parameters, key)) {
+      diagnostics.push({
+        code: 'PSL_EXTENSION_DUPLICATE_PARAMETER',
+        message: `Duplicate parameter "${key}" in "${keyword}" block "${blockName}"; first occurrence wins`,
+        range: {
+          start: sourceFile.positionAt(entry.syntax.offset),
+          end: sourceFile.positionAt(entry.syntax.offset + entry.syntax.green.textLength),
+        },
+      });
+      continue;
+    }
+    parameters[key] = reconstructParamValue(
+      entry,
+      descriptor?.parameters[key],
+      span,
+      sourceFile,
+      diagnostics,
+    );
+  }
+
+  return {
+    kind: descriptor?.discriminator ?? keyword,
+    keyword,
+    name: blockName,
+    parameters,
+    blockAttributes,
+    span: nodePslSpan(node.syntax, sourceFile),
+  };
+}
+
+function reconstructParamValue(
+  entry: KeyValuePairAst,
+  param: PslBlockParam | undefined,
+  span: PslSpan,
+  sourceFile: SourceFile,
+  diagnostics: ParseDiagnostic[],
+): PslExtensionBlockParamValue {
+  const value = entry.value();
+  if (value === undefined) {
+    return { kind: 'bare', span };
+  }
+  return reconstructFromExpression(value, param, span, sourceFile, diagnostics);
+}
+
+function reconstructFromExpression(
+  value: ExpressionAst,
+  param: PslBlockParam | undefined,
+  span: PslSpan,
+  sourceFile: SourceFile,
+  diagnostics?: ParseDiagnostic[],
+): PslExtensionBlockParamValue {
+  const raw = printSyntax(value.syntax).trim();
+  if (param?.kind === 'list') {
+    const array = ArrayLiteralAst.cast(value.syntax);
+    if (!array) {
+      diagnostics?.push({
+        code: 'PSL_EXTENSION_INVALID_VALUE',
+        message: `List parameter expects an array literal, got ${raw}`,
+        range: {
+          start: sourceFile.positionAt(value.syntax.offset),
+          end: sourceFile.positionAt(value.syntax.offset + value.syntax.green.textLength),
+        },
+      });
+      return { kind: 'value', raw, span };
+    }
+
+    const items: PslExtensionBlockParamValue[] = [];
+    for (const element of array.elements()) {
+      items.push(
+        reconstructFromExpression(
+          element,
+          param.of,
+          nodePslSpan(element.syntax, sourceFile),
+          sourceFile,
+          diagnostics,
+        ),
+      );
+    }
+    return { kind: 'list', items, span };
+  }
+  switch (param?.kind) {
+    case 'ref':
+      return { kind: 'ref', identifier: raw, span };
+    case 'option':
+      return { kind: 'option', token: raw, span };
+    default:
+      return { kind: 'value', raw, span };
+  }
+}

package/src/exports/format.ts

@@ -0,0 +1,3 @@
+export { PslFormatError } from '../format/error';
+export { format } from '../format/format';
+export type { FormatOptions } from '../format/options';

package/src/exports/index.ts

@@ -1,6 +1,4 @@
 export type {
-  ParsePslDocumentInput,
-  ParsePslDocumentResult,
   PslAttribute,
   PslAttributeArgument,
   PslAttributeNamedArgument,
@@ -38,4 +36,64 @@ export {
   namespacePslExtensionBlocks,
 } from '@prisma-next/framework-components/psl-ast';
 export { getPositionalArgument, parseQuotedStringLiteral } from '../attribute-helpers';
-export { parsePslDocument } from '../parser';
+export { bool } from '../attribute-spec/combinators/bool';
+export { leafDiagnostic } from '../attribute-spec/combinators/diagnostic';
+export { entityRef } from '../attribute-spec/combinators/entity-ref';
+export type { FieldRefArgType, FieldRefScope } from '../attribute-spec/combinators/field-ref';
+export { fieldRef } from '../attribute-spec/combinators/field-ref';
+export type { FuncCallSig, TypedFuncCall } from '../attribute-spec/combinators/func-call';
+export { funcCall } from '../attribute-spec/combinators/func-call';
+export { identifier } from '../attribute-spec/combinators/identifier';
+export { int } from '../attribute-spec/combinators/int';
+export type { ListOptions } from '../attribute-spec/combinators/list';
+export { list } from '../attribute-spec/combinators/list';
+export { num } from '../attribute-spec/combinators/num';
+export { oneOf } from '../attribute-spec/combinators/one-of';
+export { record } from '../attribute-spec/combinators/record';
+export { str } from '../attribute-spec/combinators/str';
+export { fieldAttribute } from '../attribute-spec/field-attribute';
+export type { ArgBindingSpec } from '../attribute-spec/interpret';
+export { interpretArgs, interpretAttribute } from '../attribute-spec/interpret';
+export { modelAttribute } from '../attribute-spec/model-attribute';
+export { optional } from '../attribute-spec/optional';
+export type {
+  ArgType,
+  AttributeLevel,
+  AttributeOut,
+  AttributeSpec,
+  InferAttr,
+  InterpretCtx,
+  NamedOut,
+  OptionalArgType,
+  OutOf,
+  Param,
+  PositionalParam,
+  PosOut,
+} from '../attribute-spec/types';
+export { findBlockDescriptor, validateExtensionBlockFromSymbol } from '../extension-block';
+export {
+  keywordPslSpan,
+  nodePslSpan,
+  rangeToPslSpan,
+  readResolvedAttribute,
+  readResolvedAttributes,
+  readResolvedConstructorCall,
+} from '../resolve';
+export type {
+  BlockSymbol,
+  BuildSymbolTableOptions,
+  CompositeTypeSymbol,
+  FieldSymbol,
+  ModelSymbol,
+  NamespaceSymbol,
+  ResolvedAttribute,
+  ResolvedAttributeArg,
+  ResolvedNamedTypeBinding,
+  ResolvedTypeConstructorCall,
+  ScalarSymbol,
+  SymbolTable,
+  SymbolTableResult,
+  TopLevelScope,
+  TypeAliasSymbol,
+} from '../symbol-table';
+export { buildSymbolTable } from '../symbol-table';

package/src/exports/interpret.ts

@@ -0,0 +1,2 @@
+export type { PslInterpretCapable, PslInterpretInput } from '../interpret';
+export { hasPslInterpreter, withSeedDiagnostics } from '../interpret';

package/src/exports/syntax.ts

@@ -7,7 +7,13 @@ export {
   FieldAttributeAst,
   ModelAttributeAst,
 } from '../syntax/ast/attributes';
-export type { NamespaceMemberAst } from '../syntax/ast/declarations';
+export type {
+  AttributeAst,
+  BlockMemberAst,
+  DeclarationAst,
+  GenericBlockMemberAst,
+  NamespaceMemberAst,
+} from '../syntax/ast/declarations';
 export {
   CompositeTypeDeclarationAst,
   DocumentAst,
@@ -35,12 +41,26 @@ export {
 export { IdentifierAst } from '../syntax/ast/identifier';
 export { QualifiedNameAst } from '../syntax/ast/qualified-name';
 export { TypeAnnotationAst } from '../syntax/ast/type-annotation';
-export type { AstNode } from '../syntax/ast-helpers';
-export { filterChildren, findChildToken, findFirstChild, printSyntax } from '../syntax/ast-helpers';
+export type { AstNode, BracedBlock } from '../syntax/ast-helpers';
+export {
+  any,
+  filterChildren,
+  findChildToken,
+  findFirstChild,
+  printSyntax,
+} from '../syntax/ast-helpers';
 export type { GreenElement, GreenNode, GreenToken } from '../syntax/green';
 export { greenNode, greenToken } from '../syntax/green';
 export { GreenNodeBuilder } from '../syntax/green-builder';
+// Navigation helpers
+export type { Direction } from '../syntax/navigation';
+export {
+  isTrivia,
+  isTriviaKind,
+  nonTriviaSibling,
+  skipTriviaToken,
+} from '../syntax/navigation';
 // Red layer
-export type { SyntaxElement, SyntaxToken } from '../syntax/red';
-export { createSyntaxTree, SyntaxNode } from '../syntax/red';
+export type { SyntaxElement } from '../syntax/red';
+export { createSyntaxTree, SyntaxNode, SyntaxToken, TokenAtOffset } from '../syntax/red';
 export type { SyntaxKind } from '../syntax/syntax-kind';