common.test.ts

import { findFieldLine, generateFromSchema, readDoc } from '../utils';
import fs from 'node:fs';
import path from 'node:path';
import { beforeAll, describe, expect, it } from 'vitest';

describe('documentation plugin: common features', () => {
  describe('header, breadcrumbs, and badges', () => {
    let tmpDir: string;
    beforeAll(async () => {
      tmpDir = await generateFromSchema(`
                enum Role { ADMIN MEMBER }
                type Timestamps {
                    createdAt DateTime @default(now())
                }
                model User {
                    id   String @id @default(cuid())
                    role Role
                    posts Post[]
                }
                model Post {
                    id       String @id @default(cuid())
                    author   User   @relation(fields: [authorId], references: [id])
                    authorId String
                }
                procedure getUser(id: String): User
                mutation procedure signUp(name: String): User
            `);
    });

    it('all pages include auto-generated header with do-not-edit warning', () => {
      const headerPattern = /DO NOT MODIFY THIS FILE/u;
      expect(readDoc(tmpDir, 'index.md')).toMatch(headerPattern);
      expect(readDoc(tmpDir, 'models', 'User.md')).toMatch(headerPattern);
      expect(readDoc(tmpDir, 'enums', 'Role.md')).toMatch(headerPattern);
      expect(readDoc(tmpDir, 'types', 'Timestamps.md')).toMatch(headerPattern);
      expect(readDoc(tmpDir, 'procedures', 'getUser.md')).toMatch(
        headerPattern,
      );
      expect(readDoc(tmpDir, 'relationships.md')).toMatch(headerPattern);
    });

    it('header uses comment-block banner style without [!CAUTION]', () => {
      const indexContent = readDoc(tmpDir, 'index.md');
      expect(indexContent).toContain('// DO NOT MODIFY THIS FILE');
      expect(indexContent).toContain('// This file is automatically generated');
      expect(indexContent).not.toContain('[!CAUTION]');

      const userDocument = readDoc(tmpDir, 'models', 'User.md');
      expect(userDocument).toContain('// DO NOT MODIFY THIS FILE');
      expect(userDocument).not.toContain('[!CAUTION]');
    });

    it('omits the generated banner when includeGeneratedHeader is false', async () => {
      const noBanner = await generateFromSchema(
        `
                model User {
                    id String @id @default(cuid())
                    posts Post[]
                }
                model Post {
                    id       String @id @default(cuid())
                    author   User   @relation(fields: [authorId], references: [id])
                    authorId String
                }
            `,
        { includeGeneratedHeader: false },
      );

      const headerPattern = /DO NOT MODIFY THIS FILE/u;
      expect(readDoc(noBanner, 'index.md')).not.toMatch(headerPattern);
      expect(readDoc(noBanner, 'models', 'User.md')).not.toMatch(headerPattern);
      expect(readDoc(noBanner, 'relationships.md')).not.toMatch(headerPattern);
      expect(readDoc(noBanner, 'index.md')).toMatch(
        /^# Schema Documentation\n/u,
      );
    });

    it('entity pages show breadcrumb navigation and type badges', () => {
      const userDocument = readDoc(tmpDir, 'models', 'User.md');
      expect(userDocument).toContain('[Index](../index.md)');
      expect(userDocument).toContain('[Models](../index.md#models)');
      expect(userDocument).toContain('<kbd>Model</kbd>');

      const roleDocument = readDoc(tmpDir, 'enums', 'Role.md');
      expect(roleDocument).toContain('[Enums](../index.md#enums)');
      expect(roleDocument).toContain('<kbd>Enum</kbd>');

      const tsDocument = readDoc(tmpDir, 'types', 'Timestamps.md');
      expect(tsDocument).toContain('[Types](../index.md#types)');
      expect(tsDocument).toContain('<kbd>Type</kbd>');

      const queryDocument = readDoc(tmpDir, 'procedures', 'getUser.md');
      expect(queryDocument).toContain('[Procedures](../index.md#procedures)');
      expect(queryDocument).toContain('<kbd>Query</kbd>');

      const mutDocument = readDoc(tmpDir, 'procedures', 'signUp.md');
      expect(mutDocument).toContain('<kbd>Mutation</kbd>');
    });
  });

  it('header includes schema file path and generation date', async () => {
    const tmpDir = await generateFromSchema(
      `
            model User {
                id String @id @default(cuid())
            }
        `,
      {},
      '/app/zenstack/schema.zmodel',
    );

    const indexContent = readDoc(tmpDir, 'index.md');
    expect(indexContent).toContain('schema.zmodel');
    expect(indexContent).toMatch(/Generated.*\d{4}-\d{2}-\d{2}/u);

    const userDocument = readDoc(tmpDir, 'models', 'User.md');
    expect(userDocument).toContain('schema.zmodel');
    expect(userDocument).toMatch(/Generated.*\d{4}-\d{2}-\d{2}/u);
  });

  it('produces correct directory structure for models and enums', async () => {
    const tmpDir = await generateFromSchema(`
            model User {
                id   String @id @default(cuid())
                role Role
            }
            model Post {
                id String @id @default(cuid())
            }
            enum Role {
                ADMIN
                USER
            }
        `);

    expect(fs.existsSync(path.join(tmpDir, 'index.md'))).toBe(true);
    expect(fs.existsSync(path.join(tmpDir, 'models', 'User.md'))).toBe(true);
    expect(fs.existsSync(path.join(tmpDir, 'models', 'Post.md'))).toBe(true);
    expect(fs.existsSync(path.join(tmpDir, 'enums', 'Role.md'))).toBe(true);
  });

  it('omits sections when include* flags are false', async () => {
    const tmpDir = await generateFromSchema(
      `
            model User {
                id    String @id @default(cuid())
                email String @email
                posts Post[]
                @@allow('read', true)
                @@index([email])
            }
            model Post {
                id       String @id @default(cuid())
                author   User   @relation(fields: [authorId], references: [id])
                authorId String
            }
        `,
      {
        includeIndexes: false,
        includePolicies: false,
        includeRelationships: false,
        includeValidation: false,
      },
    );

    const userDocument = readDoc(tmpDir, 'models', 'User.md');
    expect(userDocument).not.toContain('## \u{1F517} Relationships');
    expect(userDocument).not.toContain('## \u{1F510} Access Policies');
    expect(userDocument).not.toContain('## \u2705 Validation Rules');
    expect(userDocument).not.toContain('## \u{1F4C7} Indexes');
    expect(fs.existsSync(path.join(tmpDir, 'relationships.md'))).toBe(false);
  });

  it('@@ignore models are excluded by default and included with includeInternalModels=true', async () => {
    const baseSchema = `
            model User {
                id String @id @default(cuid())
            }
            model Internal {
                id String @id @default(cuid())
                @@ignore
            }
        `;

    const excluded = await generateFromSchema(baseSchema);
    const excludedIndex = readDoc(excluded, 'index.md');
    expect(excludedIndex).toContain('[User]');
    expect(excludedIndex).not.toContain('[Internal]');
    expect(fs.existsSync(path.join(excluded, 'models', 'Internal.md'))).toBe(
      false,
    );

    const included = await generateFromSchema(baseSchema, {
      includeInternalModels: true,
    });
    const includedIndex = readDoc(included, 'index.md');
    expect(includedIndex).toContain('[Internal]');
    expect(fs.existsSync(path.join(included, 'models', 'Internal.md'))).toBe(
      true,
    );
  });

  it('links field types to model and enum pages', async () => {
    const tmpDir = await generateFromSchema(`
            model User {
                id    String @id @default(cuid())
                role  Role
                posts Post[]
            }
            model Post {
                id       String @id @default(cuid())
                author   User   @relation(fields: [authorId], references: [id])
                authorId String
            }
            enum Role {
                ADMIN
                USER
            }
        `);

    const userDocument = readDoc(tmpDir, 'models', 'User.md');
    expect(findFieldLine(userDocument, 'role')).toContain(
      '[Role](../enums/Role.md)',
    );
    expect(findFieldLine(userDocument, 'posts')).toContain('[Post](./Post.md)');
    expect(findFieldLine(userDocument, 'id')).not.toContain('[String]');

    const postDocument = readDoc(tmpDir, 'models', 'Post.md');
    expect(findFieldLine(postDocument, 'author')).toContain(
      '[User](./User.md)',
    );
  });

  it('deprecated entities render with strikethrough and badge', async () => {
    const tmpDir = await generateFromSchema(`
            model User {
                id String @id @default(cuid())
                @@meta('doc:deprecated', 'Use Account instead')
            }
            model Account {
                id String @id @default(cuid())
            }
            view OldReport {
                id    String
                total Int
                @@meta('doc:deprecated', 'Use ReportV2 instead')
            }
        `);

    const userDocument = readDoc(tmpDir, 'models', 'User.md');
    expect(userDocument).toContain(
      '# 🗃️ ~~User~~ <kbd>Model</kbd> <kbd>Deprecated</kbd>',
    );

    const indexContent = readDoc(tmpDir, 'index.md');
    expect(indexContent).toContain('~~[User]');
    expect(indexContent).toContain('Use Account instead');
    expect(indexContent).not.toMatch(/~~\[Account\]/u);

    const viewDocument = readDoc(tmpDir, 'views', 'OldReport.md');
    expect(viewDocument).toContain(
      '# ~~OldReport~~ <kbd>View</kbd> <kbd>Deprecated</kbd>',
    );
  });

  it('references section links to correct ZenStack documentation URLs', async () => {
    const tmpDir = await generateFromSchema(`
            enum Role { ADMIN USER }
            type Timestamps {
                createdAt DateTime @default(now())
            }
            view UserSummary {
                id Int
            }
            model User with Timestamps {
                id   String @id @default(cuid())
                role Role
            }
        `);

    expect(readDoc(tmpDir, 'models', 'User.md')).toContain(
      'https://zenstack.dev/docs/reference/zmodel/model',
    );
    expect(readDoc(tmpDir, 'enums', 'Role.md')).toContain(
      'https://zenstack.dev/docs/reference/zmodel/enum',
    );
    expect(readDoc(tmpDir, 'types', 'Timestamps.md')).toContain(
      'https://zenstack.dev/docs/reference/zmodel/type',
    );
    expect(readDoc(tmpDir, 'views', 'UserSummary.md')).toContain(
      'https://zenstack.dev/docs/reference/zmodel/view',
    );
  });
});