@astryxdesign/cli 0.2.0 → 0.3.0

package/authoring/config/parse.test.mjs

@@ -0,0 +1,91 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Colocated tests for `parseConfig` — the load-boundary validator for
+ * `astryx.config.*`. Zod is sealed inside the parser, so these exercise the
+ * public contract only: a validated value comes back on success, a readable
+ * `<label> is invalid: …` error is thrown on failure. The accept/reject set
+ * matches the old `AstryxConfigSchema` cases verbatim.
+ */
+
+import {describe, it, expect} from 'vitest';
+import {parseConfig} from './parse.mjs';
+
+/** Run parseConfig and return the thrown message (asserting it throws). */
+function reason(value, label = 'config') {
+  try {
+    parseConfig(value, label);
+  } catch (err) {
+    return err instanceof Error ? err.message : String(err);
+  }
+  throw new Error('expected parseConfig to throw');
+}
+
+describe('parseConfig (load boundary)', () => {
+  it('accepts an empty config (every field optional)', () => {
+    expect(parseConfig({})).toEqual({});
+  });
+
+  it('accepts a fully-populated valid config', () => {
+    const cfg = {
+      integrations: ['@astryxdesign/core'],
+      issuesUrl: 'https://github.com/org/repo/issues',
+      hooks: {postCodemod: [{name: 'build', buildCommand: () => {}}]},
+      experimental: {xle: {components: {Foo: {from: 'pkg', default: true}}}},
+    };
+    expect(() => parseConfig(cfg)).not.toThrow();
+  });
+
+  it('accepts hooks.postCodemod with a buildCommand function', () => {
+    expect(() =>
+      parseConfig({
+        hooks: {postCodemod: [{name: 'format', buildCommand: () => null}]},
+      }),
+    ).not.toThrow();
+  });
+
+  it('rejects non-objects with a readable message', () => {
+    expect(reason(null)).toContain('expected object');
+    expect(reason(42)).toContain('expected object');
+    expect(reason([])).toContain('expected object');
+  });
+
+  it('rejects unknown top-level keys (strict)', () => {
+    const msg = reason({packages: ['./libs']});
+    expect(msg).toContain('Unrecognized key');
+    expect(msg).toContain('packages');
+  });
+
+  it('rejects a non-array integrations field', () => {
+    expect(reason({integrations: '@acme/widgets'})).toContain('expected array');
+    expect(reason({integrations: [1]})).toContain('integrations.0');
+  });
+
+  it('rejects a non-URL issuesUrl', () => {
+    expect(reason({issuesUrl: 'not-a-url'})).toContain('issuesUrl');
+  });
+
+  it('rejects a postCodemod hook without buildCommand', () => {
+    expect(() =>
+      parseConfig({hooks: {postCodemod: [{name: 'empty'}]}}),
+    ).toThrow();
+  });
+
+  it('rejects a non-function postCodemod.buildCommand', () => {
+    expect(reason({hooks: {postCodemod: [{buildCommand: 'notAFn'}]}})).toContain(
+      'buildCommand',
+    );
+  });
+
+  it('rejects unknown nested keys inside experimental.xle.components', () => {
+    expect(
+      reason({experimental: {xle: {components: {Foo: {from: 'pkg', bad: 1}}}}}),
+    ).toContain('Unrecognized key');
+  });
+
+  it('rejects an xle component missing `from`', () => {
+    expect(() =>
+      parseConfig({experimental: {xle: {components: {Foo: {}}}}}),
+    ).toThrow();
+  });
+});

package/authoring/config/type.ts

@@ -0,0 +1,77 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * Public type surface for an Astryx config file (`astryx.config.{ts,mjs,js}`).
+ *
+ * Authors write a plain object against {@link AstryxConfig} — in TS via
+ * `satisfies AstryxConfig`, in JS via `/** @type {import('@astryxdesign/cli/authoring').AstryxConfig} *\/`.
+ * The CLI turns the loaded value into this type via `parseConfig` at the load
+ * boundary; there is no factory to call.
+ */
+
+/**
+ * A command to run as part of a post-codemod hook. Returned by a hook's
+ * `buildCommand` and executed after codemods write files.
+ */
+export interface PostCodemodCommand {
+  command: string;
+  args?: string[];
+  options?: {
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    timeout?: number;
+  };
+}
+
+/**
+ * A post-codemod hook. `buildCommand` receives the package directory and the
+ * list of files changed by codemods, and returns the command to run (or a
+ * nullish value to skip).
+ */
+export type PostCodemodHook = {
+  name?: string;
+  buildCommand: (ctx: {
+    packageDir: string;
+    files: string[];
+  }) =>
+    | PostCodemodCommand
+    | null
+    | undefined
+    | Promise<PostCodemodCommand | null | undefined>;
+};
+
+/** A component XLE layout expressions can reference by name via `{hint}`. */
+export interface XleComponent {
+  /** Import specifier the component is imported from, e.g. '@/components/KpiCard'. */
+  from: string;
+  /** Optional human description shown in tooling. */
+  description?: string;
+  /** Import as the module's default export instead of a named export. Defaults to false. */
+  default?: boolean;
+}
+
+/** User config exported from astryx.config.{ts,mjs,js}. */
+export interface AstryxConfig {
+  /** Integration package names to load. */
+  integrations?: string[];
+  /** Where to file issues/feedback for this project. */
+  issuesUrl?: string;
+  /** Lifecycle hooks. */
+  hooks?: {
+    postCodemod?: PostCodemodHook[];
+  };
+  /**
+   * EXPERIMENTAL — shape may change and is not part of the stable config
+   * contract. Provisional home for features still being proven out.
+   */
+  experimental?: {
+    /** Experimental XLE (layout expression) configuration. */
+    xle?: {
+      /**
+       * Register app-local components so XLE layout expressions can
+       * reference them by name via {hint}. Keyed by component name.
+       */
+      components?: Record<string, XleComponent>;
+    };
+  };
+}

package/authoring/doctypes/_schema.mjs

@@ -0,0 +1,135 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Sealed doc load-boundary schemas (doctypes-internal).
+ *
+ * These zod schemas are the implementation detail behind the doctypes parsers.
+ * They are NOT part of the public authoring surface: nothing outside
+ * `authoring/doctypes/**` imports them, and they never appear in a public type.
+ * They accept BOTH the stamped formats (`type: 'component' | 'function' |
+ * 'generic'`) and the legacy loose `export const docs = {...}` shape, so the
+ * ~600+ existing docs keep validating unchanged.
+ */
+
+import {z} from 'zod';
+
+const PropSchema = z
+  .object({
+    name: z.string().min(1, 'prop name is required'),
+    type: z.string().min(1, 'prop type is required'),
+    description: z.string(),
+    default: z.string().optional(),
+    required: z.boolean().optional(),
+  })
+  .passthrough();
+
+const ParamSchema = z
+  .object({
+    name: z.string().min(1, 'param name is required'),
+    type: z.string().min(1, 'param type is required'),
+    description: z.string(),
+    default: z.string().optional(),
+    required: z.boolean().optional(),
+  })
+  .passthrough();
+
+const ReturnSchema = z
+  .object({
+    name: z.string().min(1, 'return name is required'),
+    type: z.string().min(1, 'return type is required'),
+    description: z.string(),
+  })
+  .passthrough();
+
+const BaseDocFields = {
+  name: z.string().min(1, 'name is required'),
+  displayName: z.string().optional(),
+  description: z.string().optional(),
+  usage: z.unknown().optional(),
+  group: z.string().optional(),
+  category: z.string().optional(),
+  keywords: z.array(z.string()).optional(),
+  parent: z.string().optional(),
+  relatedDocs: z.array(z.string()).optional(),
+  hidden: z.boolean().optional(),
+  isHiddenFromOverview: z.boolean().optional(),
+};
+
+/** New-format stamped component doc (`type: 'component'`). */
+export const ComponentDocKindSchema = z
+  .object({
+    ...BaseDocFields,
+    type: z.literal('component'),
+    props: z.array(PropSchema),
+    theming: z.unknown().optional(),
+    playground: z.unknown().optional(),
+    examples: z.array(z.unknown()).optional(),
+  })
+  .passthrough();
+
+/** New-format stamped function/hook doc (`type: 'function'`). */
+export const FunctionDocKindSchema = z
+  .object({
+    ...BaseDocFields,
+    type: z.literal('function'),
+    params: z.array(ParamSchema),
+    returns: z.array(ReturnSchema),
+  })
+  .passthrough();
+
+/** New-format stamped generic reference/topic doc (`type: 'generic'`). */
+export const GenericDocKindSchema = z
+  .object({
+    ...BaseDocFields,
+    type: z.literal('generic'),
+  })
+  .passthrough();
+
+// ── Legacy loose format (unchanged, kept for back-compat) ─────────────
+const LegacyBaseDocSchema = z.object({
+  name: z.string().min(1, 'name is required'),
+  displayName: z.string().optional(),
+  description: z.string().optional(),
+  group: z.string().optional(),
+  category: z.string().optional(),
+  keywords: z.array(z.string()).optional(),
+  isHiddenFromOverview: z.boolean().optional(),
+  hidden: z.boolean().optional(),
+  hiddenComponents: z.array(z.string()).optional(),
+  usage: z.unknown().optional(),
+  playground: z.unknown().optional(),
+  theming: z.unknown().optional(),
+  examples: z.array(z.unknown()).optional(),
+  showcase: z.unknown().optional(),
+  parent: z.string().optional(),
+  relatedDocs: z.array(z.string()).optional(),
+  relatedComponents: z.array(z.string()).optional(),
+  relatedHooks: z.array(z.string()).optional(),
+});
+
+const LegacySingleComponentDocSchema = LegacyBaseDocSchema.extend({
+  props: z.array(PropSchema),
+}).passthrough();
+
+const LegacyMultiComponentDocSchema = LegacyBaseDocSchema.extend({
+  components: z.array(z.unknown()),
+}).passthrough();
+
+const LegacyHookDocSchema = LegacyBaseDocSchema.extend({
+  params: z.array(ParamSchema),
+  returns: z.array(ReturnSchema),
+}).passthrough();
+
+const LegacySubComponentDocSchema = LegacyBaseDocSchema.extend({
+  subComponentOf: z.string().min(1, 'subComponentOf is required'),
+  description: z.string(),
+  props: z.array(PropSchema),
+}).passthrough();
+
+/** The permissive legacy union (sub-component first, then hook, multi, single). */
+export const LegacyDocSchema = z.union([
+  LegacySubComponentDocSchema,
+  LegacyHookDocSchema,
+  LegacyMultiComponentDocSchema,
+  LegacySingleComponentDocSchema,
+]);