@prisma-next/framework-components 0.12.0 → 0.13.0-dev.10

package/src/control/psl-extension-block-validator.ts

@@ -0,0 +1,324 @@
+/**
+ * Generic validator for extension-contributed top-level PSL blocks.
+ *
+ * One function — {@link validateExtensionBlock} — takes a parsed
+ * {@link PslExtensionBlock}, its {@link AuthoringPslBlockDescriptor}, a
+ * {@link CodecLookup} (for `value` parameters), and the set of
+ * {@link PslNamespace} objects from the document (for `ref` resolution), and
+ * returns the full list of {@link PslDiagnostic} objects for the block.
+ *
+ * Detection logic per failure mode:
+ *
+ * 1. **Unknown parameter** — keys present in `node.parameters` that are absent
+ *    from `descriptor.parameters` (key-set difference). The parser stores
+ *    unknown parameters as `kind:'value'` stubs; the validator discovers them
+ *    by comparing the key sets, not by inspecting the captured kind.
+ *
+ * 2. **Missing required parameter** — `descriptor.parameters` entries with
+ *    `required: true` whose key is absent from `node.parameters`.
+ *
+ * 3. **`option` value outside its set** — the captured `token` is not in
+ *    `descriptor.values`.
+ *
+ * 4. **`value` rejected by its codec** — the raw string is first parsed as
+ *    JSON (`JSON.parse(raw)`). If `JSON.parse` throws, the literal is not valid
+ *    JSON and a `PSL_EXTENSION_INVALID_VALUE` diagnostic is emitted. If parsing
+ *    succeeds but `codec.decodeJson(jsonValue)` throws, the JSON value is not
+ *    acceptable to the codec and a `PSL_EXTENSION_INVALID_VALUE` diagnostic is
+ *    emitted. If `codecLookup.get(codecId)` returns `undefined` (unknown codec
+ *    id), a `PSL_EXTENSION_INVALID_VALUE` diagnostic is also emitted.
+ *
+ * 5. **`ref` that does not resolve within its scope** — the captured
+ *    `identifier` is looked up in the PSL document's `PslNamespace` objects
+ *    according to `param.scope`:
+ *    - `same-namespace`: the referent must be in the same namespace as the
+ *      block (the namespace containing the block).
+ *    - `same-space`: the referent may be in any namespace in the document.
+ *    - `cross-space`: pass-through — enforcement is scoped to first-consumer
+ *      need (RLS roles). This case is documented and clearly flagged; the
+ *      caller is responsible for wiring cross-space resolution when needed.
+ *
+ * 6. **`list`** — each element is validated against `param.of` recursively.
+ *
+ * ### `char`/`varchar` length
+ * Not enforced. RLS `using`/`check` strings are unbounded text and the codec
+ * already rejects structurally invalid literals; length constraints are a
+ * database-side concern, not a PSL authoring constraint.
+ *
+ * ### `cross-space` scope
+ * Implemented as a documented pass-through. The spec permits scoping
+ * cross-space enforcement to first-consumer need (RLS roles). When RLS roles
+ * arrive, wire `cross-space` resolution through the cross-contract-space
+ * coordinate model `(spaceId, namespaceId, entityKind, entityName)`.
+ */
+
+import type { JsonValue } from '@prisma-next/contract/types';
+import { blindCast } from '@prisma-next/utils/casts';
+import type { CodecLookup } from '../shared/codec-types';
+import type { AuthoringPslBlockDescriptor } from '../shared/framework-authoring';
+import type {
+  PslBlockParam,
+  PslBlockParamRef,
+  PslExtensionBlock,
+  PslExtensionBlockParamValue,
+  PslSpan,
+} from '../shared/psl-extension-block';
+import type { PslDiagnostic, PslNamespace } from './psl-ast';
+
+/**
+ * Context for ref resolution during extension-block validation.
+ *
+ * - `ownerNamespace` is the `PslNamespace` that contains the block being
+ *   validated. Used for `same-namespace` scope checks.
+ * - `allNamespaces` is every namespace in the document. Used for `same-space`
+ *   scope checks.
+ */
+export interface ExtensionBlockRefResolutionContext {
+  readonly ownerNamespace: PslNamespace;
+  readonly allNamespaces: readonly PslNamespace[];
+}
+
+/**
+ * Validate a single parsed extension block against its descriptor.
+ *
+ * Returns an array of {@link PslDiagnostic} objects (possibly empty). The
+ * caller is responsible for threading `sourceId` into each returned diagnostic
+ * — the returned objects already have `sourceId` set from the `sourceId`
+ * parameter.
+ *
+ * @param node - The parsed block node produced by the generic framework parser.
+ * @param descriptor - The descriptor that claims this block's keyword.
+ * @param sourceId - The PSL source file identifier (threaded into diagnostics).
+ * @param codecLookup - Used to validate `value`-kind parameter literals via
+ *   `codecLookup.get(codecId)?.decodeJson(JSON.parse(raw))`.
+ * @param refCtx - Namespace context for `ref`-kind scope resolution. Required
+ *   when any descriptor parameter is `kind: 'ref'`; may be omitted if none are.
+ */
+export function validateExtensionBlock(
+  node: PslExtensionBlock,
+  descriptor: AuthoringPslBlockDescriptor,
+  sourceId: string,
+  codecLookup: CodecLookup,
+  refCtx?: ExtensionBlockRefResolutionContext,
+): readonly PslDiagnostic[] {
+  const diagnostics: PslDiagnostic[] = [];
+
+  const descriptorKeys = new Set(Object.keys(descriptor.parameters));
+  const nodeKeys = new Set(Object.keys(node.parameters));
+
+  // 1. Unknown parameters — keys in the node not in the descriptor.
+  for (const key of nodeKeys) {
+    if (!descriptorKeys.has(key)) {
+      const captured = node.parameters[key];
+      diagnostics.push({
+        code: 'PSL_EXTENSION_UNKNOWN_PARAMETER',
+        message: `Unknown parameter "${key}" in "${descriptor.keyword}" block "${node.name}". The descriptor does not declare this parameter.`,
+        sourceId,
+        span: captured?.span ?? node.span,
+      });
+    }
+  }
+
+  // 2. Missing required parameters — required descriptor keys absent from the node.
+  for (const [key, param] of Object.entries(descriptor.parameters)) {
+    if (param.required === true && !nodeKeys.has(key)) {
+      diagnostics.push({
+        code: 'PSL_EXTENSION_MISSING_REQUIRED_PARAMETER',
+        message: `Required parameter "${key}" is missing from "${descriptor.keyword}" block "${node.name}".`,
+        sourceId,
+        span: node.span,
+      });
+    }
+  }
+
+  // 3–5. Per-parameter validation for parameters that are present.
+  for (const [key, param] of Object.entries(descriptor.parameters)) {
+    const captured = node.parameters[key];
+    if (captured === undefined) {
+      continue;
+    }
+    validateParam(
+      node,
+      descriptor,
+      key,
+      param,
+      captured,
+      sourceId,
+      codecLookup,
+      refCtx,
+      diagnostics,
+    );
+  }
+
+  return diagnostics;
+}
+
+function validateParam(
+  node: PslExtensionBlock,
+  descriptor: AuthoringPslBlockDescriptor,
+  key: string,
+  param: PslBlockParam,
+  captured: PslExtensionBlockParamValue,
+  sourceId: string,
+  codecLookup: CodecLookup,
+  refCtx: ExtensionBlockRefResolutionContext | undefined,
+  diagnostics: PslDiagnostic[],
+): void {
+  switch (param.kind) {
+    case 'option': {
+      if (captured.kind !== 'option') {
+        return;
+      }
+      if (!param.values.includes(captured.token)) {
+        diagnostics.push({
+          code: 'PSL_EXTENSION_OPTION_OUT_OF_SET',
+          message: `Parameter "${key}" in "${descriptor.keyword}" block "${node.name}" has value "${captured.token}" which is not one of the allowed values: ${param.values.map((v) => `"${v}"`).join(', ')}.`,
+          sourceId,
+          span: captured.span,
+        });
+      }
+      return;
+    }
+
+    case 'value': {
+      if (captured.kind !== 'value') {
+        return;
+      }
+      const codec = codecLookup.get(param.codecId);
+      if (codec === undefined) {
+        diagnostics.push({
+          code: 'PSL_EXTENSION_INVALID_VALUE',
+          message: `Parameter "${key}" in "${descriptor.keyword}" block "${node.name}" references unknown codec "${param.codecId}".`,
+          sourceId,
+          span: captured.span,
+        });
+        return;
+      }
+      let jsonValue: unknown;
+      try {
+        jsonValue = JSON.parse(captured.raw);
+      } catch {
+        diagnostics.push({
+          code: 'PSL_EXTENSION_INVALID_VALUE',
+          message: `Parameter "${key}" in "${descriptor.keyword}" block "${node.name}" is not a valid JSON literal (expected a JSON string, number, boolean, or null): ${captured.raw}`,
+          sourceId,
+          span: captured.span,
+        });
+        return;
+      }
+      try {
+        codec.decodeJson(
+          blindCast<JsonValue, 'JSON.parse returns a JsonValue-compatible value'>(jsonValue),
+        );
+      } catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        diagnostics.push({
+          code: 'PSL_EXTENSION_INVALID_VALUE',
+          message: `Parameter "${key}" in "${descriptor.keyword}" block "${node.name}" was rejected by codec "${param.codecId}": ${reason}`,
+          sourceId,
+          span: captured.span,
+        });
+      }
+      return;
+    }
+
+    case 'ref': {
+      if (captured.kind !== 'ref') {
+        return;
+      }
+      validateRef(
+        node,
+        descriptor,
+        key,
+        param,
+        captured.identifier,
+        captured.span,
+        sourceId,
+        refCtx,
+        diagnostics,
+      );
+      return;
+    }
+
+    case 'list': {
+      if (captured.kind !== 'list') {
+        return;
+      }
+      for (const item of captured.items) {
+        validateParam(
+          node,
+          descriptor,
+          key,
+          param.of,
+          item,
+          sourceId,
+          codecLookup,
+          refCtx,
+          diagnostics,
+        );
+      }
+      return;
+    }
+  }
+}
+
+function validateRef(
+  node: PslExtensionBlock,
+  descriptor: AuthoringPslBlockDescriptor,
+  key: string,
+  param: PslBlockParamRef,
+  identifier: string,
+  span: PslSpan,
+  sourceId: string,
+  refCtx: ExtensionBlockRefResolutionContext | undefined,
+  diagnostics: PslDiagnostic[],
+): void {
+  if (param.scope === 'cross-space') {
+    // cross-space enforcement is a documented pass-through. The spec permits
+    // scoping cross-space resolution to first-consumer need (RLS roles). When
+    // that consumer arrives, wire resolution here through the
+    // cross-contract-space coordinate model
+    // (spaceId, namespaceId, entityKind, entityName).
+    // For now, cross-space refs pass validation unconditionally.
+    return;
+  }
+
+  if (refCtx === undefined) {
+    // If no resolution context was provided, skip ref resolution. This matches
+    // the closed-grammar invariant: callers that register ref parameters must
+    // provide resolution context; callers without namespaces (e.g. unit tests
+    // that only exercise other validation modes) can omit it.
+    return;
+  }
+
+  const namespacesToSearch: readonly PslNamespace[] =
+    param.scope === 'same-namespace' ? [refCtx.ownerNamespace] : refCtx.allNamespaces;
+
+  if (!resolveEntityInNamespaces(identifier, param.refKind, namespacesToSearch)) {
+    const scopeLabel =
+      param.scope === 'same-namespace' ? 'the same namespace' : 'any namespace in the schema';
+    diagnostics.push({
+      code: 'PSL_EXTENSION_UNRESOLVED_REF',
+      message: `Parameter "${key}" in "${descriptor.keyword}" block "${node.name}" refers to "${identifier}" (expected ${param.refKind}), but no entity with that name and kind was found in ${scopeLabel}.`,
+      sourceId,
+      span,
+    });
+  }
+}
+
+/**
+ * True if an entity named `name` of kind `refKind` exists in any of the given
+ * namespaces. Built-in and extension kinds resolve the same way, through
+ * `entries[refKind]`.
+ */
+function resolveEntityInNamespaces(
+  name: string,
+  refKind: string,
+  namespaces: readonly PslNamespace[],
+): boolean {
+  for (const ns of namespaces) {
+    const kindMap = ns.entries[refKind];
+    if (kindMap !== undefined && Object.hasOwn(kindMap, name)) return true;
+  }
+  return false;
+}

package/src/control/verifier-disposition.ts

@@ -0,0 +1,62 @@
+import type { ControlPolicy } from '@prisma-next/contract/types';
+import type { SchemaVerificationNode } from './control-result-types';
+
+export type VerificationStatus = SchemaVerificationNode['status'];
+
+export type VerifierOutcome = VerificationStatus | 'suppress';
+
+/**
+ * Target-neutral classification of a verifier finding, abstracted away from any
+ * one storage model's vocabulary. Each family classifies its own concrete issue
+ * kinds into these categories; the framework only grades the category against a
+ * control policy.
+ *
+ * - `declaredMissing` — a declared object/element is absent from the database.
+ * - `declaredIncompatible` — a declared object/element exists but its shape diverges.
+ * - `valueDrift` — the value set of an existing type drifted (e.g. enum values).
+ * - `extraNestedElement` — an undeclared element nested inside a declared object
+ *   (a SQL column, a document field).
+ * - `extraAuxiliary` — an undeclared auxiliary attached to a declared object
+ *   (a SQL constraint/index, a Mongo index/validator).
+ * - `extraTopLevelObject` — an undeclared top-level object (a SQL table, a
+ *   Mongo collection).
+ */
+export type VerifierIssueCategory =
+  | 'declaredMissing'
+  | 'declaredIncompatible'
+  | 'valueDrift'
+  | 'extraNestedElement'
+  | 'extraAuxiliary'
+  | 'extraTopLevelObject';
+
+/**
+ * Grades a target-neutral issue category against a control policy.
+ *
+ * - `observed` warns on everything.
+ * - `tolerated` suppresses only an extra nested element (everything else fails).
+ * - `external` suppresses every extra category and value drift (existence and
+ *   declared-shape divergences still fail).
+ * - `managed` (and any other) fails.
+ */
+export function dispositionForCategory(
+  controlPolicy: ControlPolicy,
+  category: VerifierIssueCategory,
+): VerifierOutcome {
+  if (controlPolicy === 'observed') {
+    return 'warn';
+  }
+  if (controlPolicy === 'tolerated' && category === 'extraNestedElement') {
+    return 'suppress';
+  }
+  if (controlPolicy === 'external') {
+    if (
+      category === 'extraNestedElement' ||
+      category === 'extraAuxiliary' ||
+      category === 'extraTopLevelObject' ||
+      category === 'valueDrift'
+    ) {
+      return 'suppress';
+    }
+  }
+  return 'fail';
+}

package/src/exports/authoring.ts

@@ -11,6 +11,8 @@ export type {
   AuthoringFieldNamespace,
   AuthoringFieldPresetDescriptor,
   AuthoringFieldPresetOutput,
+  AuthoringPslBlockDescriptor,
+  AuthoringPslBlockDescriptorNamespace,
   AuthoringStorageTypeTemplate,
   AuthoringTemplateValue,
   AuthoringTypeConstructorDescriptor,
@@ -25,8 +27,22 @@ export {
   isAuthoringArgRef,
   isAuthoringEntityTypeDescriptor,
   isAuthoringFieldPresetDescriptor,
+  isAuthoringPslBlockDescriptor,
   isAuthoringTypeConstructorDescriptor,
   mergeAuthoringNamespaces,
   resolveAuthoringTemplateValue,
   validateAuthoringHelperArguments,
 } from '../shared/framework-authoring';
+export type {
+  PslBlockParam,
+  PslBlockParamList,
+  PslBlockParamOption,
+  PslBlockParamRef,
+  PslBlockParamValue,
+  PslExtensionBlock,
+  PslExtensionBlockParamList,
+  PslExtensionBlockParamOption,
+  PslExtensionBlockParamRef,
+  PslExtensionBlockParamScalarValue,
+  PslExtensionBlockParamValue,
+} from '../shared/psl-extension-block';

package/src/exports/control.ts

@@ -95,6 +95,7 @@ export {
   assembleControlMutationDefaults,
   assembleScalarTypeDescriptors,
   assertUniqueCodecOwner,
+  buildExtensionLoadOrder,
   createControlStack,
   extractCodecLookup,
   extractCodecTypeImports,
@@ -106,6 +107,12 @@ export type {
   SchemaVerifyOptions,
   SchemaVerifyResult,
 } from '../control/schema-verifier';
+export type {
+  VerificationStatus,
+  VerifierIssueCategory,
+  VerifierOutcome,
+} from '../control/verifier-disposition';
+export { dispositionForCategory } from '../control/verifier-disposition';
 export type {
   ControlMutationDefaultEntry,
   ControlMutationDefaultRegistry,

package/src/exports/psl-ast.ts

@@ -1 +1,3 @@
 export * from '../control/psl-ast';
+export type { ExtensionBlockRefResolutionContext } from '../control/psl-extension-block-validator';
+export { validateExtensionBlock } from '../control/psl-extension-block-validator';

package/src/ir/namespace.ts

@@ -41,28 +41,30 @@ export const UNBOUND_NAMESPACE_ID = '__unbound__' as const;
  *
  * The framework promises only the coordinate (`id`) — the named storage
  * entities a namespace contains are family-typed (SQL contributes
- * `tables`, Mongo contributes `collections`, future families pick their
- * own native idiom). Generic consumers walking "all named entries" go
- * through a family-typed namespace, not the framework `Namespace`.
+ * `table` / `type`, Mongo contributes `collection`, future families pick
+ * their own native idiom under `entries`). Generic consumers walking "all
+ * named entries" go through a family-typed namespace, not the framework
+ * `Namespace`.
  *
  * Every namespace concretion (e.g. family-built SQL namespaces,
  * `MongoUnboundNamespace`, target-promoted namespaces like
- * `PostgresSchema`) carries exactly: `id` (enumerable string), `kind`
- * (non-enumerable string discriminator set via `Object.defineProperty`),
- * and one or more entity-kind slot maps — each an own-enumerable property
- * whose key is the entity kind (`tables`, `types`, `collections`,
- * target-pack-contributed slot names) and whose value is a
- * `Record<entityName, EntityIRClass>`. No other own-enumerable data lives
- * on a namespace; non-entity computed data lives on the surrounding storage
- * or contract IR. The framework's `elementCoordinates(storage)` walk relies
- * on this invariant to enumerate entities structurally without
- * family-specific knowledge.
+ * `PostgresSchema`) carries exactly: `id` (enumerable string),
+ * `entries` (frozen object holding entity-kind slot maps), and `kind`
+ * (non-enumerable string discriminator set via `Object.defineProperty`).
+ * Each slot map under `entries` uses a singular essence key (`table`,
+ * `type`, `collection`, …) mapping entity names to IR classes. No other
+ * own-enumerable data lives on a namespace; non-entity computed data lives
+ * on the surrounding storage or contract IR. The framework's
+ * `elementCoordinates(storage)` walk relies on this invariant to enumerate
+ * entities structurally without family-specific knowledge.
  */
 export interface Namespace extends IRNode, StorageNamespace {
   readonly kind: string;
+  readonly entries: Readonly<Record<string, Readonly<Record<string, unknown>>>>;
 }
 
 export abstract class NamespaceBase extends IRNodeBase implements Namespace {
   abstract readonly id: string;
+  abstract readonly entries: Readonly<Record<string, Readonly<Record<string, unknown>>>>;
   abstract override readonly kind: string;
 }

package/src/ir/storage.ts

@@ -30,18 +30,19 @@ export interface EntityCoordinate {
  * value, yielded as {@link EntityCoordinate} tuples with
  * `plane: 'storage'` (the parameter type binds the plane).
  *
- * Iterates each namespace's own-enumerable properties structurally.
- * Skips `id` (known scalar); `kind` is non-enumerable on namespace
- * concretions and does not appear in `Object.entries`. For every other
- * property whose value is a non-null object, yields one coordinate per
- * entry key in that map. No family-specific slot vocabulary is required.
+ * Iterates each namespace's `entries` slot maps structurally. Skips
+ * non-object `entries`; `id` and `kind` are not walked (`kind` is
+ * non-enumerable on concretions). For every entity-kind key under
+ * `entries` whose value is a non-null object, yields one coordinate per
+ * entity name in that map. No family-specific slot vocabulary is required.
  */
 export function* elementCoordinates(
   storage: Pick<StorageBase, 'namespaces'>,
 ): Generator<EntityCoordinate> {
   for (const [namespaceId, ns] of Object.entries(storage.namespaces)) {
-    for (const [entityKind, slot] of Object.entries(ns)) {
-      if (entityKind === 'id') continue;
+    const entries = ns.entries;
+    if (entries === null || typeof entries !== 'object') continue;
+    for (const [entityKind, slot] of Object.entries(entries)) {
       if (slot === null || typeof slot !== 'object') continue;
       for (const entityName of Object.keys(slot)) {
         yield { plane: 'storage', namespaceId, entityKind, entityName };