@astryxdesign/cli 0.2.0 → 0.3.0

package/authoring/doctypes/parse.test.mjs

@@ -0,0 +1,348 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Colocated tests for the doc load boundary. `parseDoc` dispatches on the
+ * stamped `type` to the per-kind parsers and falls back to legacy shape-sniffing
+ * for unstamped docs — its acceptance set matches the old permissive
+ * `ComponentDocSchema` exactly, so every existing `.doc.*` keeps loading. Zod is
+ * sealed inside the parsers; authors write a plain object and stamp `type`
+ * directly (no factory). The end-to-end `loadComponentDoc` cases lock that both
+ * the stamped default export and the legacy `export const docs = {}` load.
+ */
+
+import {afterEach, beforeEach, describe, expect, it} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {parseDoc} from './parse.mjs';
+import {parseComponent} from './component/parse.mjs';
+import {parseHook} from './hook/parse.mjs';
+import {parseReference} from './reference/parse.mjs';
+import {loadComponentDoc} from '../../foundation/discovery/component-loader.mjs';
+
+const goodComponent = {
+  type: 'component',
+  name: 'Widget',
+  displayName: 'Widget',
+  description: 'A small widget.',
+  props: [
+    {name: 'label', type: 'string', description: 'Visible label.', required: true},
+    {name: 'size', type: "'sm' | 'md'", description: 'Control size.', default: "'md'"},
+  ],
+};
+
+const goodFunction = {
+  type: 'function',
+  name: 'useThing',
+  displayName: 'useThing',
+  description: 'A thing hook.',
+  params: [{name: 'input', type: 'string', description: 'The input.', required: true}],
+  returns: [{name: 'value', type: 'string', description: 'The result.'}],
+};
+
+const goodGeneric = {
+  type: 'generic',
+  name: 'Theming',
+  displayName: 'Theming',
+  description: 'How theming works.',
+};
+
+/** Run parseDoc and return the thrown message (asserting it throws). */
+function reason(value, label = 'doc') {
+  try {
+    parseDoc(value, label);
+  } catch (err) {
+    return err instanceof Error ? err.message : String(err);
+  }
+  throw new Error('expected parseDoc to throw');
+}
+
+describe('per-kind parsers (stamped format)', () => {
+  it('parseComponent accepts a valid component doc', () => {
+    expect(() => parseComponent(goodComponent)).not.toThrow();
+  });
+
+  it('parseComponent rejects a missing name with a readable message', () => {
+    expect(() =>
+      parseComponent({type: 'component', name: '', props: []}),
+    ).toThrow(/name is required/);
+  });
+
+  it('parseComponent rejects a prop missing its type', () => {
+    expect(() =>
+      parseComponent({
+        type: 'component',
+        name: 'Widget',
+        props: [{name: 'label', description: 'no type'}],
+      }),
+    ).toThrow(/type/);
+  });
+
+  it('parseComponent surfaces the custom message for an empty prop type', () => {
+    expect(() =>
+      parseComponent({
+        type: 'component',
+        name: 'Widget',
+        props: [{name: 'label', type: '', description: 'empty type'}],
+      }),
+    ).toThrow(/prop type is required/);
+  });
+
+  it('parseHook accepts a valid function doc', () => {
+    expect(() => parseHook(goodFunction)).not.toThrow();
+  });
+
+  it('parseHook rejects a function doc missing returns', () => {
+    expect(() =>
+      parseHook({type: 'function', name: 'useThing', params: []}),
+    ).toThrow();
+  });
+
+  it('parseReference accepts a valid generic doc', () => {
+    expect(() => parseReference(goodGeneric)).not.toThrow();
+  });
+
+  it('keeps nested rich blobs loose (usage/theming/playground passthrough)', () => {
+    expect(() =>
+      parseComponent({
+        ...goodComponent,
+        usage: {description: 'Use it.', anatomy: [{name: 'root'}]},
+        theming: {targets: [{className: 'astryx-widget'}]},
+        playground: {defaults: {label: 'Hi'}},
+        examples: [{title: 'Basic', code: '<Widget />'}],
+      }),
+    ).not.toThrow();
+  });
+
+  it('accepts parent + relatedDocs on the shared base', () => {
+    const parsed = parseComponent({
+      ...goodComponent,
+      parent: 'WidgetGroup',
+      relatedDocs: ['Gauge', 'useThing'],
+      group: 'Widgets',
+    });
+    expect(parsed.parent).toBe('WidgetGroup');
+    expect(parsed.relatedDocs).toEqual(['Gauge', 'useThing']);
+  });
+});
+
+describe('parseDoc (load boundary, both formats)', () => {
+  it('accepts a stamped component doc', () => {
+    expect(() => parseDoc(goodComponent)).not.toThrow();
+  });
+
+  it('accepts a stamped function doc', () => {
+    expect(() => parseDoc(goodFunction)).not.toThrow();
+  });
+
+  it('accepts a stamped generic doc', () => {
+    expect(() => parseDoc(goodGeneric)).not.toThrow();
+  });
+
+  it('accepts the OLD loose single-component shape (no type)', () => {
+    const {type, ...loose} = goodComponent;
+    expect(() => parseDoc(loose)).not.toThrow();
+  });
+
+  it('accepts the OLD loose multi-component shape (components[])', () => {
+    const multi = {
+      name: 'Table',
+      displayName: 'Table',
+      components: [
+        {name: 'TableRow', displayName: 'Table Row', description: 'A row.'},
+      ],
+    };
+    expect(() => parseDoc(multi)).not.toThrow();
+  });
+
+  it('accepts the OLD loose sub-component shape (subComponentOf)', () => {
+    const sub = {
+      name: 'GaugeItem',
+      subComponentOf: 'Gauge',
+      displayName: 'Gauge Item',
+      description: 'A gauge item.',
+      props: [{name: 'item', type: 'Item', description: 'The item.'}],
+    };
+    expect(() => parseDoc(sub)).not.toThrow();
+  });
+
+  it('accepts the OLD loose standalone-hook shape (params + returns, no type)', () => {
+    const hook = {
+      name: 'useThing',
+      displayName: 'useThing',
+      params: [{name: 'q', type: 'string', description: 'query'}],
+      returns: [{name: 'value', type: 'boolean', description: 'match'}],
+    };
+    expect(() => parseDoc(hook)).not.toThrow();
+  });
+
+  it('accepts BOTH parent and legacy subComponentOf', () => {
+    const withParent = {name: 'A', parent: 'B', props: []};
+    const withSubComponentOf = {
+      name: 'A',
+      subComponentOf: 'B',
+      description: 'sub',
+      props: [],
+    };
+    expect(() => parseDoc(withParent)).not.toThrow();
+    expect(() => parseDoc(withSubComponentOf)).not.toThrow();
+  });
+
+  it('accepts BOTH relatedDocs and legacy relatedComponents/relatedHooks', () => {
+    const legacy = {
+      name: 'useThing',
+      displayName: 'useThing',
+      params: [],
+      returns: [],
+      relatedComponents: ['Gauge'],
+      relatedHooks: ['useOther'],
+    };
+    const modern = {...goodComponent, relatedDocs: ['Gauge', 'useThing']};
+    expect(() => parseDoc(legacy)).not.toThrow();
+    expect(() => parseDoc(modern)).not.toThrow();
+  });
+
+  it('passes through loose extras (usage, playground, theming, importPath, showcase)', () => {
+    const {type, ...base} = goodComponent;
+    const parsed = parseDoc({
+      ...base,
+      usage: {description: 'Use it wisely.'},
+      playground: {defaults: {label: 'Hi'}},
+      theming: {targets: [{className: 'astryx-widget'}]},
+      keywords: ['widget', 'thing'],
+      category: 'Content',
+      isHiddenFromOverview: true,
+      importPath: '@astryxdesign/core/Widget',
+      showcase: 'WidgetHero',
+    });
+    expect(parsed.importPath).toBe('@astryxdesign/core/Widget');
+    expect(parsed.showcase).toBe('WidgetHero');
+  });
+
+  it('rejects a doc with no name', () => {
+    expect(() => parseDoc({props: []})).toThrow();
+  });
+
+  it('rejects an empty name with a readable message', () => {
+    expect(reason({name: '', props: []})).toMatch(/name is required/);
+  });
+});
+
+describe('loadComponentDoc (end-to-end load boundary)', () => {
+  let tmpDir;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(process.cwd(), '.astryx-doc-test-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, {recursive: true, force: true});
+  });
+
+  it('loads a stamped component .doc.mjs default export', async () => {
+    const file = path.join(tmpDir, 'Widget.doc.mjs');
+    fs.writeFileSync(
+      file,
+      [
+        'export default {',
+        "  type: 'component',",
+        "  name: 'Widget',",
+        "  displayName: 'Widget',",
+        "  description: 'A small widget.',",
+        '  props: [',
+        "    {name: 'label', type: 'string', description: 'Visible label.', required: true},",
+        '  ],',
+        '};',
+      ].join('\n'),
+    );
+    const docs = await loadComponentDoc(file);
+    expect(docs.type).toBe('component');
+    expect(docs.name).toBe('Widget');
+    expect(docs.props).toHaveLength(1);
+  });
+
+  it('loads a stamped function .doc.mjs default export', async () => {
+    const file = path.join(tmpDir, 'useThing.doc.mjs');
+    fs.writeFileSync(
+      file,
+      [
+        'export default {',
+        "  type: 'function',",
+        "  name: 'useThing',",
+        "  displayName: 'useThing',",
+        "  params: [{name: 'input', type: 'string', description: 'The input.'}],",
+        "  returns: [{name: 'value', type: 'string', description: 'The result.'}],",
+        '};',
+      ].join('\n'),
+    );
+    const docs = await loadComponentDoc(file);
+    expect(docs.type).toBe('function');
+    expect(docs.params).toHaveLength(1);
+    expect(docs.returns).toHaveLength(1);
+  });
+
+  it('loads a stamped generic .doc.mjs default export', async () => {
+    const file = path.join(tmpDir, 'Theming.doc.mjs');
+    fs.writeFileSync(
+      file,
+      [
+        'export default {',
+        "  type: 'generic',",
+        "  name: 'Theming',",
+        "  displayName: 'Theming',",
+        "  description: 'How theming works.',",
+        '};',
+      ].join('\n'),
+    );
+    const docs = await loadComponentDoc(file);
+    expect(docs.type).toBe('generic');
+    expect(docs.name).toBe('Theming');
+  });
+
+  it('REGRESSION: loads the OLD loose `export const docs = {}` format', async () => {
+    const file = path.join(tmpDir, 'Legacy.doc.mjs');
+    fs.writeFileSync(
+      file,
+      [
+        'export const docs = {',
+        "  name: 'Legacy',",
+        "  displayName: 'Legacy',",
+        "  description: 'A loose named-export doc.',",
+        "  relatedComponents: ['Gauge'],",
+        "  relatedHooks: ['useThing'],",
+        "  importPath: '@astryxdesign/core/Legacy',",
+        "  props: [{name: 'value', type: 'string', description: 'A value.'}],",
+        '};',
+      ].join('\n'),
+    );
+    const docs = await loadComponentDoc(file);
+    expect(docs.name).toBe('Legacy');
+    expect(docs.props[0].name).toBe('value');
+    expect(docs.relatedComponents).toEqual(['Gauge']);
+    expect(docs.importPath).toBe('@astryxdesign/core/Legacy');
+  });
+
+  it('REGRESSION: loads the OLD loose standalone-hook `docs` format', async () => {
+    const file = path.join(tmpDir, 'useLegacy.doc.mjs');
+    fs.writeFileSync(
+      file,
+      [
+        'export const docs = {',
+        "  name: 'useLegacy',",
+        "  displayName: 'useLegacy',",
+        "  params: [{name: 'q', type: 'string', description: 'query'}],",
+        "  returns: [{name: 'value', type: 'boolean', description: 'match'}],",
+        "  relatedHooks: ['useThing'],",
+        '};',
+      ].join('\n'),
+    );
+    const docs = await loadComponentDoc(file);
+    expect(docs.name).toBe('useLegacy');
+    expect(docs.returns[0].name).toBe('value');
+  });
+
+  it('throws a readable error for an invalid doc', async () => {
+    const file = path.join(tmpDir, 'Bad.doc.mjs');
+    fs.writeFileSync(file, 'export default {group: "Buttons"};\n');
+    await expect(loadComponentDoc(file)).rejects.toThrow(/is invalid|name/);
+  });
+});

package/authoring/doctypes/reference/parse.d.mts

@@ -0,0 +1,4 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import type {ReferenceDoc} from '../types';
+export function parseReference(input: unknown, label?: string): ReferenceDoc;

package/authoring/doctypes/reference/parse.mjs

@@ -0,0 +1,30 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Reference/topic doc parser (stamped `type: 'generic'`). The rich type
+ * is {@link ReferenceDoc}; the stamped discriminant value stays `'generic'`.
+ * Zod is sealed in `../_schema.mjs`; consumers call `parseReference` or `parseDoc`.
+ */
+
+import {GenericDocKindSchema} from '../_schema.mjs';
+import {formatZodError} from '../../_shared/errors.mjs';
+
+/** @typedef {import('../types').ReferenceDoc} ReferenceDoc */
+
+/**
+ * Validate an unknown value as a stamped reference/topic doc, or throw.
+ *
+ * @param {unknown} input
+ * @param {string} [label]
+ * @returns {ReferenceDoc}
+ */
+export function parseReference(input, label = 'reference doc') {
+  const result = GenericDocKindSchema.safeParse(input);
+  if (!result.success) {
+    throw new Error(formatZodError(label, result.error));
+  }
+  // The schema is permissive (it also accepts legacy generic docs), so it is
+  // deliberately looser than the rich public type; cast through unknown at this
+  // validated boundary.
+  return /** @type {ReferenceDoc} */ (/** @type {unknown} */ (result.data));
+}

package/authoring/doctypes/reference/type.ts

@@ -0,0 +1,154 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Reference/topic doc types.
+ */
+
+/**
+ * A content block within a reference doc section.
+ * Ordered array of these makes up a section's content.
+ * New block types can be added without breaking existing docs.
+ *
+ * @example
+ * ```
+ * { type: 'prose', text: 'Spacing tokens control gap and padding...' }
+ * { type: 'heading', level: 3, text: 'Examples' }
+ * { type: 'code', lang: 'tsx', code: 'padding: spacingVars[...]' }
+ * { type: 'table', headers: ['Token', 'Value'], rows: [['--spacing-4', '16px']] }
+ * { type: 'list', style: 'do', items: ['Use semantic tokens'] }
+ * { type: 'token-ref', topic: 'tokens', section: 'Color Tokens' }
+ * ```
+ */
+export type ReferenceContentBlock =
+  | {type: 'prose'; text: string}
+  | {type: 'heading'; level: 3 | 4 | 5 | 6; text: string}
+  | {type: 'code'; lang: string; code: string; label?: string}
+  | {type: 'table'; headers: string[]; rows: string[][]}
+  | {
+      type: 'list';
+      style: 'ordered' | 'unordered' | 'do' | 'dont';
+      items: string[];
+    }
+  | {
+      /** Reference to a token table in another doc topic.
+       *  The CLI resolves this at read time and inlines the referenced
+       *  section's table. The docsite can render it with live theme values
+       *  and type-specific previews instead of static strings. */
+      type: 'token-ref';
+      /** Doc topic name containing the tokens. e.g. `'tokens'` */
+      topic: string;
+      /** Section title to pull from that topic. e.g. `'Color Tokens'` */
+      section: string;
+    };
+
+/**
+ * A reference documentation file (.doc.mjs).
+ *
+ * Reference docs cover topics like design tokens, principles, theming,
+ * patterns, accessibility, and migration guides. Unlike ComponentDoc,
+ * they aren't tied to a specific component — just drop a .doc.mjs file
+ * in the docs/ directory and it shows up in `astryx docs`.
+ *
+ * Every reference .doc.mjs must export a single `docs` constant:
+ *
+ *   /** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} *\/
+ *   export const docs = { ... };
+ */
+export interface ReferenceDoc {
+  /** Doc-kind discriminant for the stamped default-export format
+   *  (`export default { type: 'generic', ... }`). Optional: legacy
+   *  `export const docs = {...}` docs omit it. The value stays `'generic'`
+   *  (the reference/topic discriminant). */
+  type?: 'generic';
+  /** URL-safe identifier, used as the CLI topic name. e.g. 'tokens', 'principles' */
+  name: string;
+  /** Human-readable title. e.g. 'All Tokens' */
+  title: string;
+  /** One-line summary shown in topic listings. */
+  description: string;
+  /** Navigation category: 'guide' or 'foundations'. */
+  category?: string;
+  /** Ordered sections that make up the doc. */
+  sections: ReferenceSection[];
+  /** Token category for foundational docs that map to a token section.
+   *  When set, the docsite can link from the tokens overview page
+   *  to this doc for detailed guidance on that category.
+   *  e.g. `'color'` links tokens → color foundational doc. */
+  tokenCategory?: string;
+}
+
+/**
+ * A section within a reference doc. Sections are the primary
+ * organizational unit — each becomes an h2 in full output,
+ * and can be individually retrieved via `astryx docs <topic> <section>`.
+ */
+export interface ReferenceSection {
+  /** Section title, e.g. "Spacing Tokens", "Light/Dark Mode" */
+  title: string;
+  /** Navigation category ('guide' | 'foundations'). Mirrors the parent doc's
+   *  category so sections can be grouped independently in the docsite nav. */
+  category?: string;
+  /** Ordered content blocks. Mix prose, code, tables, and lists freely. */
+  content: ReferenceContentBlock[];
+  /** Preview type for token tables in this section. When set, the docsite
+   *  renders a visual preview column using the token's computed CSS value
+   *  from the current theme. Omit for non-token sections. */
+  previewType?: ReferenceTokenPreviewType;
+}
+
+/**
+ * Preview type hint for token tables. Tells the docsite how to render
+ * a visual preview column for each token row.
+ *
+ * - `'swatch'` — Color circle/square showing the token value
+ * - `'shadow-box'` — Box with the shadow applied
+ * - `'radius-box'` — Box with the border-radius applied
+ * - `'spacing-bar'` — Horizontal bar at the token's width
+ * - `'size-bar'` — Horizontal bar at the token's height
+ * - `'border-line'` — Line at the token's border-width
+ * - `'duration-bar'` — Animated bar showing the timing
+ * - `'easing-curve'` — Bezier curve visualization
+ * - `'font-sample'` — Text sample in the font family/size/weight
+ */
+export type ReferenceTokenPreviewType =
+  | 'swatch'
+  | 'shadow-box'
+  | 'radius-box'
+  | 'spacing-bar'
+  | 'size-bar'
+  | 'border-line'
+  | 'duration-bar'
+  | 'easing-curve'
+  | 'font-sample';
+
+/**
+ * Translation/compression overlay for reference documentation.
+ *
+ * Swaps prose text and list items. Code blocks and table data
+ * are NOT translated — they stay as-is from the base doc.
+ *
+ * Used by `docsZh` (Chinese) and `docsDense` (compressed format).
+ */
+export interface ReferenceTranslationDoc {
+  /** Translated/compressed description. */
+  description: string;
+  /** Section overrides, keyed to base sections by `section`. Order does not
+   *  matter, and an overlay may cover any subset — sections it does not name
+   *  keep their base content. (These used to be matched by array index, which
+   *  meant a reordered or partial overlay grafted every title onto the wrong
+   *  body: `docs tokens --dense` printed the colour table under a "Spacing"
+   *  heading. See #2182.) */
+  sections: {
+    /** Title of the BASE section this entry overrides, verbatim and in English
+     *  (e.g. 'Spacing Tokens'). Must match a section in the base doc. */
+    section: string;
+    /** Translated/compressed section title, shown in place of the base title. */
+    title: string;
+    /** Content block overrides, by index within the anchored base section.
+     *  Only prose and list blocks need entries. Use null for blocks that don't
+     *  change (code, table). */
+    content: (
+      {type: 'prose'; text: string} | {type: 'list'; items: string[]} | null
+    )[];
+  }[];
+}

package/authoring/doctypes/template/parse.d.mts

@@ -0,0 +1,4 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import type {TemplateDoc} from '../types';
+export function parseTemplate(input: unknown, label?: string): TemplateDoc;

package/authoring/doctypes/template/parse.mjs

@@ -0,0 +1,54 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Template doc parser (stamped `type: 'page' | 'block'`). Zod is sealed
+ * here; template discovery calls `parseTemplate` at the load boundary.
+ *
+ * The schema is the minimal INTEGRATION-template envelope (integration templates
+ * carry only name/description/category/componentsUsed/preview plus the
+ * page|block discriminant). First-party core templates use the richer
+ * {@link TemplateDoc} and are loaded separately; `parseTemplate` returns that
+ * public type.
+ */
+
+import {z} from 'zod';
+import {formatZodError} from '../../_shared/errors.mjs';
+
+/** @typedef {import('../types').TemplateDoc} TemplateDoc */
+
+const previewSchema = z
+  .object({
+    image: z.string().optional(),
+    aspectRatio: z.string().optional(),
+  })
+  .strict();
+
+const baseTemplateFields = {
+  name: z.string().min(1, 'name is required'),
+  description: z.string().min(1, 'description is required'),
+  category: z.string().optional(),
+  componentsUsed: z.array(z.string()).optional(),
+  preview: previewSchema.optional(),
+};
+
+const templateEnvelopeSchema = z.discriminatedUnion('type', [
+  z.object({...baseTemplateFields, type: z.literal('page')}).strict(),
+  z.object({...baseTemplateFields, type: z.literal('block')}).strict(),
+]);
+
+/**
+ * Validate an unknown value as a stamped template doc, or throw. The zod schema
+ * validates the minimal integration-template envelope; the returned value is
+ * typed as the public {@link TemplateDoc}.
+ *
+ * @param {unknown} input
+ * @param {string} [label]
+ * @returns {TemplateDoc}
+ */
+export function parseTemplate(input, label = 'template') {
+  const result = templateEnvelopeSchema.safeParse(input);
+  if (!result.success) {
+    throw new Error(formatZodError(label, result.error));
+  }
+  return /** @type {TemplateDoc} */ (result.data);
+}

package/authoring/doctypes/template/parse.test.mjs

@@ -0,0 +1,87 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Colocated tests for `parseTemplate` — the load-boundary validator run
+ * against a `.template.*` module's default export during template discovery.
+ * Zod is sealed inside the parser; authors write a plain object stamped with a
+ * `type` of `'page'` or `'block'`. Accept/reject set matches the old
+ * `TemplateEnvelopeSchema`.
+ */
+
+import {describe, it, expect} from 'vitest';
+import {parseTemplate} from './parse.mjs';
+
+/** Run parseTemplate and return the thrown message (asserting it throws). */
+function reason(value, label = 'template') {
+  try {
+    parseTemplate(value, label);
+  } catch (err) {
+    return err instanceof Error ? err.message : String(err);
+  }
+  throw new Error('expected parseTemplate to throw');
+}
+
+describe('parseTemplate (load boundary)', () => {
+  it('accepts a stamped page template', () => {
+    const parsed = parseTemplate({
+      type: 'page',
+      name: 'Landing',
+      description: 'A landing page.',
+    });
+    expect(parsed.type).toBe('page');
+  });
+
+  it('accepts a block template with optional fields', () => {
+    const parsed = parseTemplate({
+      type: 'block',
+      name: 'Hero',
+      description: 'A hero block.',
+      category: 'Marketing',
+      componentsUsed: ['Button', 'Card'],
+      preview: {image: './preview.png', aspectRatio: '16 / 9'},
+    });
+    expect(parsed.name).toBe('Hero');
+    expect(parsed.preview).toEqual({image: './preview.png', aspectRatio: '16 / 9'});
+  });
+
+  it('rejects a missing name', () => {
+    expect(reason({type: 'page', description: 'x'})).toContain('name');
+  });
+
+  it('rejects a missing description', () => {
+    expect(reason({type: 'page', name: 'x'})).toContain('description');
+  });
+
+  it('rejects an empty-string name', () => {
+    expect(reason({type: 'page', name: '', description: 'x'})).toContain('name');
+  });
+
+  it('rejects a missing/invalid type', () => {
+    expect(() => parseTemplate({name: 'x', description: 'y'})).toThrow();
+    expect(() =>
+      parseTemplate({type: 'bogus', name: 'x', description: 'y'}),
+    ).toThrow();
+  });
+
+  it('rejects unknown keys (strict)', () => {
+    expect(() =>
+      parseTemplate({
+        type: 'page',
+        name: 'x',
+        description: 'y',
+        source: './x.tsx',
+      }),
+    ).toThrow();
+  });
+
+  it('rejects inline sourceFile (not supported in v1)', () => {
+    expect(() =>
+      parseTemplate({
+        type: 'page',
+        name: 'x',
+        description: 'y',
+        sourceFile: './x.tsx',
+      }),
+    ).toThrow();
+  });
+});