@formspec/constraints 0.1.0-alpha.7

package/README.md

@@ -0,0 +1,265 @@
+# @formspec/constraints
+
+Define and enforce constraints on which FormSpec DSL features are allowed in your project.
+
+## Overview
+
+The constraints package lets you restrict which parts of the FormSpec DSL can be used. This is useful for:
+
+- **Standardization**: Enforce consistent form patterns across a team
+- **Compatibility**: Restrict to features your renderer supports
+- **Simplicity**: Keep forms simple by disallowing complex nesting or conditionals
+- **Linting**: Catch constraint violations at development time via ESLint
+
+## Installation
+
+```bash
+npm install @formspec/constraints
+# or
+pnpm add @formspec/constraints
+```
+
+## Configuration
+
+Create a `.formspec.yml` file in your project root:
+
+```yaml
+constraints:
+  fieldTypes:
+    text: off          # Allow text fields
+    number: off        # Allow number fields
+    boolean: off       # Allow boolean fields
+    staticEnum: off    # Allow static enums
+    dynamicEnum: warn  # Warn on dynamic enums
+    dynamicSchema: error  # Disallow dynamic schemas
+    array: off         # Allow arrays
+    object: off        # Allow objects
+
+  layout:
+    group: off         # Allow groups
+    conditionals: off  # Allow when() conditionals
+    maxNestingDepth: 3 # Max nesting depth (0 = flat only)
+
+  fieldOptions:
+    label: off
+    placeholder: off
+    required: off
+    minValue: off
+    maxValue: off
+    minItems: off
+    maxItems: off
+```
+
+### Severity Levels
+
+Each constraint can be set to:
+
+| Severity | Behavior |
+|----------|----------|
+| `"off"` | Feature is allowed (default) |
+| `"warn"` | Emit warning but allow |
+| `"error"` | Disallow - fail validation |
+
+## Constraint Categories
+
+### Field Types (`fieldTypes`)
+
+Control which DSL field builders are allowed:
+
+| Constraint | DSL Function |
+|------------|--------------|
+| `text` | `field.text()` |
+| `number` | `field.number()` |
+| `boolean` | `field.boolean()` |
+| `staticEnum` | `field.enum()` |
+| `dynamicEnum` | `field.dynamicEnum()` |
+| `dynamicSchema` | `field.dynamicSchema()` |
+| `array` | `field.array()`, `field.arrayWithConfig()` |
+| `object` | `field.object()`, `field.objectWithConfig()` |
+
+### Layout (`layout`)
+
+Control structure and nesting:
+
+| Constraint | Description |
+|------------|-------------|
+| `group` | `group()` visual grouping |
+| `conditionals` | `when()` conditional visibility |
+| `maxNestingDepth` | Maximum depth for nested objects/arrays |
+
+### Field Options (`fieldOptions`)
+
+Control which field configuration options are allowed:
+
+| Constraint | Description |
+|------------|-------------|
+| `label` | Field label text |
+| `placeholder` | Input placeholder |
+| `required` | Required field validation |
+| `minValue`, `maxValue` | Number field constraints |
+| `minItems`, `maxItems` | Array length constraints |
+
+### UI Schema (`uiSchema`)
+
+Control JSON Forms-specific features:
+
+```yaml
+constraints:
+  uiSchema:
+    layouts:
+      VerticalLayout: off
+      HorizontalLayout: off
+      Group: off
+      Categorization: error  # Disallow tabbed interfaces
+      Category: error
+    rules:
+      enabled: off
+      effects:
+        SHOW: off
+        HIDE: off
+        ENABLE: warn
+        DISABLE: warn
+```
+
+## Programmatic Usage
+
+### Loading Configuration
+
+```typescript
+import { loadConfig, mergeWithDefaults } from "@formspec/constraints";
+
+// Load from .formspec.yml (searches up directory tree)
+const config = await loadConfig();
+
+// Or load from specific path
+const config = await loadConfig("/path/to/.formspec.yml");
+
+// Merge with defaults to get fully resolved config
+const resolved = mergeWithDefaults(config.constraints);
+```
+
+### Validating Forms
+
+```typescript
+import { validateFormSpec } from "@formspec/constraints";
+import { formspec, field, when, is } from "@formspec/dsl";
+
+const form = formspec(
+  field.text("name"),
+  field.dynamicEnum("country", "fetch_countries"),
+  when(is("country", "US"),
+    field.text("state"),
+  ),
+);
+
+const result = validateFormSpec(form, resolved);
+
+if (!result.valid) {
+  for (const issue of result.issues) {
+    console.log(`${issue.severity}: ${issue.message}`);
+  }
+}
+```
+
+### Validation Result
+
+```typescript
+interface ValidationResult {
+  valid: boolean;  // true if no errors (warnings OK)
+  issues: ValidationIssue[];
+}
+
+interface ValidationIssue {
+  code: string;           // e.g., "FIELD_TYPE_NOT_ALLOWED"
+  message: string;        // Human-readable description
+  severity: "error" | "warning";
+  category: "fieldTypes" | "layout" | "uiSchema" | "fieldOptions" | "controlOptions";
+  path?: string;          // JSON pointer to issue location
+  fieldName?: string;     // Affected field name
+  fieldType?: string;     // Affected field type
+}
+```
+
+## ESLint Integration
+
+Use `@formspec/eslint-plugin` to catch constraint violations at development time:
+
+```javascript
+// eslint.config.js
+import formspec from "@formspec/eslint-plugin";
+
+export default [
+  {
+    plugins: { formspec },
+    rules: {
+      // Enforce allowed field types from .formspec.yml
+      "formspec/constraints-allowed-field-types": "error",
+      // Enforce allowed layouts from .formspec.yml
+      "formspec/constraints-allowed-layouts": "error",
+    },
+  },
+];
+```
+
+The ESLint rules automatically load constraints from your `.formspec.yml` file.
+
+## Example Configurations
+
+### Simple Forms Only
+
+Restrict to flat forms with basic field types:
+
+```yaml
+constraints:
+  fieldTypes:
+    array: error
+    object: error
+    dynamicEnum: error
+    dynamicSchema: error
+  layout:
+    conditionals: error
+    maxNestingDepth: 0
+```
+
+### JSON Forms Compatible
+
+Restrict to features supported by standard JSON Forms renderers:
+
+```yaml
+constraints:
+  fieldTypes:
+    dynamicSchema: error  # Not supported by JSON Forms
+  uiSchema:
+    layouts:
+      Categorization: warn  # May not be supported by all renderers
+```
+
+### Warn on Advanced Features
+
+Allow all features but warn on complex ones:
+
+```yaml
+constraints:
+  fieldTypes:
+    dynamicEnum: warn
+    dynamicSchema: warn
+    array: warn
+    object: warn
+  layout:
+    conditionals: warn
+    maxNestingDepth: 2
+```
+
+## JSON Schema
+
+A JSON Schema for `.formspec.yml` is available for editor autocompletion:
+
+```yaml
+# .formspec.yml
+# yaml-language-server: $schema=node_modules/@formspec/constraints/formspec.schema.json
+
+constraints:
+  fieldTypes:
+    text: off
+    # ... autocomplete available
+```

package/dist/__tests__/loader.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=loader.test.d.ts.map

package/dist/__tests__/loader.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/loader.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/loader.test.js

@@ -0,0 +1,133 @@
+import { describe, it, expect } from "vitest";
+import { loadConfigFromString, defineConstraints } from "../index.js";
+describe("loadConfigFromString", () => {
+    it("parses YAML with constraints section", () => {
+        const yaml = `
+constraints:
+  fieldTypes:
+    dynamicEnum: error
+    dynamicSchema: error
+  layout:
+    group: error
+    conditionals: warn
+`;
+        const config = loadConfigFromString(yaml);
+        expect(config.fieldTypes.dynamicEnum).toBe("error");
+        expect(config.fieldTypes.dynamicSchema).toBe("error");
+        expect(config.layout.group).toBe("error");
+        expect(config.layout.conditionals).toBe("warn");
+    });
+    it("applies defaults for missing values", () => {
+        const yaml = `
+constraints:
+  fieldTypes:
+    dynamicEnum: error
+`;
+        const config = loadConfigFromString(yaml);
+        expect(config.fieldTypes.dynamicEnum).toBe("error");
+        expect(config.fieldTypes.text).toBe("off");
+        expect(config.fieldTypes.number).toBe("off");
+        expect(config.layout.group).toBe("off");
+    });
+    it("handles empty YAML", () => {
+        const config = loadConfigFromString("");
+        // Should return all defaults
+        expect(config.fieldTypes.text).toBe("off");
+        expect(config.layout.group).toBe("off");
+    });
+    it("handles YAML with only comments", () => {
+        const yaml = `
+# This is a comment
+# Another comment
+`;
+        const config = loadConfigFromString(yaml);
+        expect(config.fieldTypes.text).toBe("off");
+    });
+    it("parses nested uiSchema constraints", () => {
+        const yaml = `
+constraints:
+  uiSchema:
+    layouts:
+      VerticalLayout: off
+      HorizontalLayout: error
+      Group: error
+    rules:
+      enabled: error
+`;
+        const config = loadConfigFromString(yaml);
+        expect(config.uiSchema.layouts.VerticalLayout).toBe("off");
+        expect(config.uiSchema.layouts.HorizontalLayout).toBe("error");
+        expect(config.uiSchema.layouts.Group).toBe("error");
+        expect(config.uiSchema.rules.enabled).toBe("error");
+    });
+    it("parses fieldOptions constraints", () => {
+        const yaml = `
+constraints:
+  fieldOptions:
+    minItems: error
+    maxItems: error
+    placeholder: warn
+`;
+        const config = loadConfigFromString(yaml);
+        expect(config.fieldOptions.minItems).toBe("error");
+        expect(config.fieldOptions.maxItems).toBe("error");
+        expect(config.fieldOptions.placeholder).toBe("warn");
+        expect(config.fieldOptions.label).toBe("off");
+    });
+    it("parses maxNestingDepth as number", () => {
+        const yaml = `
+constraints:
+  layout:
+    maxNestingDepth: 2
+`;
+        const config = loadConfigFromString(yaml);
+        expect(config.layout.maxNestingDepth).toBe(2);
+    });
+    it("throws on invalid YAML structure", () => {
+        const yaml = `
+- this
+- is
+- an array
+`;
+        expect(() => loadConfigFromString(yaml)).toThrow();
+    });
+});
+describe("defineConstraints", () => {
+    it("creates config from object literal", () => {
+        const config = defineConstraints({
+            fieldTypes: {
+                dynamicEnum: "error",
+                array: "warn",
+            },
+            layout: {
+                group: "error",
+                maxNestingDepth: 1,
+            },
+        });
+        expect(config.fieldTypes.dynamicEnum).toBe("error");
+        expect(config.fieldTypes.array).toBe("warn");
+        expect(config.fieldTypes.text).toBe("off"); // default
+        expect(config.layout.group).toBe("error");
+        expect(config.layout.maxNestingDepth).toBe(1);
+    });
+    it("handles empty config", () => {
+        const config = defineConstraints({});
+        // All defaults
+        expect(config.fieldTypes.text).toBe("off");
+        expect(config.layout.group).toBe("off");
+        expect(config.uiSchema.layouts.VerticalLayout).toBe("off");
+    });
+    it("handles partial nested config", () => {
+        const config = defineConstraints({
+            uiSchema: {
+                rules: {
+                    enabled: "error",
+                },
+            },
+        });
+        expect(config.uiSchema.rules.enabled).toBe("error");
+        expect(config.uiSchema.rules.effects.SHOW).toBe("off"); // default
+        expect(config.uiSchema.layouts.VerticalLayout).toBe("off"); // default
+    });
+});
+//# sourceMappingURL=loader.test.js.map

package/dist/__tests__/loader.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.test.js","sourceRoot":"","sources":["../../src/__tests__/loader.test.ts"],"names":[],"mappings":"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"}

package/dist/__tests__/validators.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=validators.test.d.ts.map

package/dist/__tests__/validators.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validators.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/validators.test.ts"],"names":[],"mappings":""}