@prisma-next/psl-parser 0.14.0-dev.7 → 0.14.0-dev.71

package/src/attribute-spec/interpret.ts

@@ -0,0 +1,154 @@
+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 } from './types';
+
+export function interpretAttribute<Out>(
+  attrNode: FieldAttributeAst | ModelAttributeAst,
+  spec: AttributeSpec<Out>,
+  ctx: InterpretCtx,
+): Result<Out, readonly PslDiagnostic[]> {
+  const diagnostics: PslDiagnostic[] = [];
+  const attributeSpan = nodePslSpan(attrNode.syntax, ctx.sourceFile);
+
+  const output: Record<string, unknown> = {};
+  const seen = new Set<string>();
+  let positionalSlot = 0;
+  let reportedExcess = false;
+
+  for (const arg of attrNode.argList()?.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,
+              attributeSpan,
+            ),
+          );
+          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,
+        attributeSpan,
+      ),
+    );
+  };
+
+  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);
+  }
+
+  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.'
+  >(output);
+  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

@@ -71,6 +71,7 @@ export function reconstructExtensionBlock(
 
   return {
     kind: descriptor?.discriminator ?? keyword,
+    keyword,
     name: blockName,
     parameters,
     blockAttributes,

package/src/exports/index.ts

@@ -36,6 +36,36 @@ export {
   namespacePslExtensionBlocks,
 } from '@prisma-next/framework-components/psl-ast';
 export { getPositionalArgument, parseQuotedStringLiteral } from '../attribute-helpers';
+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 { 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 { 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 { 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,

package/src/exports/interpret.ts

@@ -0,0 +1,2 @@
+export type { PslInterpretCapable, PslInterpretInput } from '../interpret';
+export { hasPslInterpreter } 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';

package/src/interpret.ts

@@ -0,0 +1,40 @@
+import type {
+  ContractSourceContext,
+  ContractSourceDiagnostic,
+  ContractSourceProvider,
+  PslContractSourceProvider,
+} from '@prisma-next/config/config-types';
+import type { SourceFile } from './source-file';
+import type { SymbolTable } from './symbol-table';
+import type { DocumentAst } from './syntax/ast/declarations';
+
+/**
+ * Lets editor tooling that already parses incrementally (e.g. the language
+ * server) hand cached artifacts to the interpreter instead of forcing a
+ * disk re-parse.
+ */
+export interface PslInterpretInput {
+  readonly document: DocumentAst;
+  readonly sourceFile: SourceFile;
+  readonly symbolTable: SymbolTable;
+  readonly sourceId: string;
+}
+
+/**
+ * Declared here — the authoring layer that owns `DocumentAst` / `SourceFile` /
+ * `SymbolTable` — because `@prisma-next/config` (core) cannot name authoring
+ * types.
+ */
+export interface PslInterpretCapable extends PslContractSourceProvider {
+  interpret(
+    input: PslInterpretInput,
+    context: ContractSourceContext,
+  ): readonly ContractSourceDiagnostic[];
+}
+
+/** The single seam that narrows a contract source to the interpret capability. */
+export function hasPslInterpreter(source: ContractSourceProvider): source is PslInterpretCapable {
+  return (
+    source.sourceFormat === 'psl' && 'interpret' in source && typeof source.interpret === 'function'
+  );
+}

package/src/parse.ts

@@ -399,14 +399,24 @@ function parseParenArgs(cursor: Cursor): void {
   }
 }
 
-export function parseAttributeArg(cursor: Cursor): GreenNode {
+export function parseAttributeArg(cursor: Cursor): void {
+  const kind = cursor.peekKind();
+  if (
+    kind !== 'Ident' &&
+    kind !== 'StringLiteral' &&
+    kind !== 'NumberLiteral' &&
+    kind !== 'LBracket' &&
+    kind !== 'LBrace'
+  ) {
+    return;
+  }
   cursor.startNode('AttributeArg');
   if (cursor.peekKind() === 'Ident' && cursor.peekKind(1) === 'Colon') {
     parseIdentifier(cursor);
     cursor.bump();
   }
   parseArgValue(cursor);
-  return cursor.finishNode();
+  cursor.finishNode();
 }
 
 function parseArgValue(cursor: Cursor): void {
@@ -435,8 +445,16 @@ export function parseAttribute(cursor: Cursor): GreenNode {
   return cursor.finishNode();
 }
 
-/** A type annotation: `QualifiedName (argList)? ([])? (?)?`, e.g. `pgvector.Vector(1536)[]?`. */
-export function parseTypeAnnotation(cursor: Cursor): GreenNode {
+/**
+ * A type annotation: `QualifiedName (argList)? ([])? (?)?`, e.g.
+ * `pgvector.Vector(1536)[]?`. When the field has no type, no node is emitted —
+ * a missing type is the absence of a `TypeAnnotation`, not a zero-width one.
+ */
+export function parseTypeAnnotation(cursor: Cursor): void {
+  const kind = cursor.peekKind();
+  if (kind !== 'Ident' && kind !== 'LBracket' && kind !== 'Question') {
+    return;
+  }
   cursor.startNode('TypeAnnotation');
   if (cursor.peekKind() === 'Ident') {
     parseQualifiedName(cursor);
@@ -453,7 +471,7 @@ export function parseTypeAnnotation(cursor: Cursor): GreenNode {
   if (cursor.peekKind() === 'Question') {
     cursor.bump();
   }
-  return cursor.finishNode();
+  cursor.finishNode();
 }
 
 type MemberParser = (cursor: Cursor) => void;

package/src/resolve.ts

@@ -15,6 +15,7 @@ export interface ResolvedAttributeArg {
   readonly kind: 'positional' | 'named';
   readonly name?: string;
   readonly value: string;
+  readonly expression?: ExpressionAst;
   readonly span: PslSpan;
 }
 
@@ -69,10 +70,12 @@ function readResolvedArgList(
   const args: ResolvedAttributeArg[] = [];
   for (const arg of argList.args()) {
     const name = arg.name()?.name();
+    const expression = arg.value();
     args.push({
       kind: name !== undefined ? 'named' : 'positional',
       ...(name !== undefined ? { name } : {}),
-      value: renderExpression(arg.value()),
+      value: renderExpression(expression),
+      ...(expression !== undefined ? { expression } : {}),
       span: nodePslSpan(arg.syntax, sourceFile),
     });
   }

package/src/source-file.ts

@@ -1,3 +1,4 @@
+const CARRIAGE_RETURN = 13;
 const LINE_FEED = 10;
 
 export interface Position {
@@ -41,6 +42,30 @@ export class SourceFile {
     return this.#lineStarts;
   }
 
+  lineStartOffset(line: number): number {
+    if (line <= 0) {
+      return 0;
+    }
+    return this.#lineStarts[line] ?? this.#text.length;
+  }
+
+  lineEndOffset(line: number): number {
+    if (line < 0) {
+      return 0;
+    }
+
+    const nextLineStart = this.#lineStarts[line + 1];
+    if (nextLineStart === undefined) {
+      return this.#text.length;
+    }
+
+    const lineFeedOffset = nextLineStart - 1;
+    const carriageReturnOffset = lineFeedOffset - 1;
+    return this.#text.charCodeAt(carriageReturnOffset) === CARRIAGE_RETURN
+      ? carriageReturnOffset
+      : lineFeedOffset;
+  }
+
   positionAt(offset: number): Position {
     const clamped = clamp(offset, 0, this.#text.length);
     const line = this.#lineIndexAt(clamped);

package/src/syntax/ast/attributes.ts

@@ -1,7 +1,6 @@
-import type { Token } from '../../tokenizer';
 import type { AstNode } from '../ast-helpers';
 import { filterChildren, findChildToken, findFirstChild } from '../ast-helpers';
-import type { SyntaxNode } from '../red';
+import type { SyntaxNode, SyntaxToken } from '../red';
 import { AttributeArgAst } from './expressions';
 import { QualifiedNameAst } from './qualified-name';
 
@@ -12,11 +11,11 @@ export class AttributeArgListAst implements AstNode {
     this.syntax = syntax;
   }
 
-  lparen(): Token | undefined {
+  lparen(): SyntaxToken | undefined {
     return findChildToken(this.syntax, 'LParen');
   }
 
-  rparen(): Token | undefined {
+  rparen(): SyntaxToken | undefined {
     return findChildToken(this.syntax, 'RParen');
   }
 
@@ -36,7 +35,7 @@ export class FieldAttributeAst implements AstNode {
     this.syntax = syntax;
   }
 
-  at(): Token | undefined {
+  at(): SyntaxToken | undefined {
     return findChildToken(this.syntax, 'At');
   }
 
@@ -60,7 +59,7 @@ export class ModelAttributeAst implements AstNode {
     this.syntax = syntax;
   }
 
-  doubleAt(): Token | undefined {
+  doubleAt(): SyntaxToken | undefined {
     return findChildToken(this.syntax, 'DoubleAt');
   }