@testspectra/cli 1.1.7 → 1.1.8-rc.2

package/dist/linter/schemas/spec.schema.js

@@ -0,0 +1,150 @@
+import { z } from 'zod';
+export const PRIORITY_VALUES = ['Critical', 'High', 'Medium', 'Low'];
+export const CASE_TYPE_VALUES = ['Positive', 'Negative', 'Edge'];
+export const STATUS_VALUES = ['draft', 'ready-for-automation', 'automated', 'deprecated'];
+export const COVERAGE_STATUS_VALUES = ['automated', 'manual', 'unsupported'];
+export const PriorityEnum = z.enum(PRIORITY_VALUES, {
+    errorMap: (issue) => {
+        if (issue.code === 'invalid_type' && issue.received === 'undefined') {
+            return { message: "Missing required frontmatter attribute 'priority'" };
+        }
+        return {
+            message: `Invalid priority value. Expected one of: ${PRIORITY_VALUES.join(', ')}`,
+        };
+    },
+});
+export const CaseTypeEnum = z.enum(CASE_TYPE_VALUES, {
+    errorMap: (issue) => {
+        if (issue.code === 'invalid_type' && issue.received === 'undefined') {
+            return { message: "Missing required frontmatter attribute 'caseType'" };
+        }
+        return {
+            message: `Invalid caseType value. Expected one of: ${CASE_TYPE_VALUES.join(', ')}`,
+        };
+    },
+});
+export const StatusEnum = z.enum(STATUS_VALUES, {
+    errorMap: (issue) => {
+        if (issue.code === 'invalid_type' && issue.received === 'undefined') {
+            return { message: "Missing required frontmatter attribute 'status'" };
+        }
+        return {
+            message: `Invalid status value. Expected one of: ${STATUS_VALUES.join(', ')}`,
+        };
+    },
+});
+export const CoverageSchema = z.object({
+    web: z.enum(COVERAGE_STATUS_VALUES).optional(),
+    mobile: z.enum(COVERAGE_STATUS_VALUES).optional(),
+});
+export const SpecFrontmatterSchema = z.object({
+    id: z
+        .string({
+        required_error: "Missing required frontmatter attribute 'id'",
+        invalid_type_error: "Frontmatter attribute 'id' must be a string",
+    })
+        .min(1, "Attribute 'id' cannot be empty"),
+    title: z
+        .string({
+        required_error: "Missing required frontmatter attribute 'title'",
+        invalid_type_error: "Frontmatter attribute 'title' must be a string",
+    })
+        .min(1, "Attribute 'title' cannot be empty"),
+    priority: PriorityEnum,
+    caseType: CaseTypeEnum,
+    status: StatusEnum,
+    coverage: CoverageSchema.optional(),
+    tags: z.array(z.string()).optional(),
+});
+export const REQUIRED_SPEC_SECTIONS = [
+    {
+        name: 'Title',
+        level: 1,
+        required: true,
+        headerPattern: /^#\s+(.+)$/,
+        description: 'Top-level H1 test case heading (# <Title>)',
+    },
+    {
+        name: 'Test Steps',
+        level: 2,
+        required: true,
+        headerPattern: /^##\s+Test Steps/i,
+        description: 'Ordered test case steps and @step:<name> directives (## Test Steps)',
+    },
+];
+export const STANDARD_SPEC_SECTIONS = [
+    ...REQUIRED_SPEC_SECTIONS,
+    {
+        name: 'Description',
+        level: 2,
+        required: false,
+        headerPattern: /^##\s+Description/i,
+        description: 'Detailed scenario narrative and business context (## Description)',
+    },
+    {
+        name: 'Prerequisites',
+        level: 2,
+        required: false,
+        headerPattern: /^##\s+Prerequisites/i,
+        description: 'Precondition steps or initial test data requirements (## Prerequisites)',
+    },
+];
+/**
+ * Extracts markdown headers from document body.
+ */
+export function extractMarkdownHeaders(body, startLine) {
+    const headers = [];
+    const lines = body.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const match = line.match(/^(#{1,6})\s+(.+)$/);
+        if (match) {
+            headers.push({
+                level: match[1].length,
+                text: match[2].trim(),
+                line: startLine + i,
+                raw: line,
+            });
+        }
+    }
+    return headers;
+}
+/**
+ * Validates markdown body sections against spec rules.
+ */
+export function validateSpecSections(body, filePath, bodyStartLine) {
+    const diagnostics = [];
+    const headers = extractMarkdownHeaders(body, bodyStartLine);
+    // 1. Verify required H1 Title header exists
+    const h1Headers = headers.filter((h) => h.level === 1);
+    if (h1Headers.length === 0) {
+        diagnostics.push({
+            code: 'testspectra/missing-frontmatter',
+            severity: 'error',
+            message: 'Missing required markdown heading: expected top-level test title "# <Title>"',
+            filePath,
+            line: bodyStartLine,
+        });
+    }
+    else if (h1Headers.length > 1) {
+        diagnostics.push({
+            code: 'testspectra/missing-frontmatter',
+            severity: 'warning',
+            message: `Multiple top-level H1 headings found in spec.md (${h1Headers.length}). Expected exactly one test title heading.`,
+            filePath,
+            line: h1Headers[1].line,
+        });
+    }
+    // 2. Verify required "## Test Steps" header exists
+    const testStepsHeader = headers.find((h) => h.level === 2 && /^Test Steps$/i.test(h.text));
+    if (!testStepsHeader) {
+        diagnostics.push({
+            code: 'testspectra/missing-frontmatter',
+            severity: 'error',
+            message: 'Missing required markdown section: expected "## Test Steps"',
+            filePath,
+            line: bodyStartLine,
+        });
+    }
+    return diagnostics;
+}

package/dist/linter/schemas/suite.schema.d.ts

@@ -0,0 +1,59 @@
+import { z } from 'zod';
+import type { LintDiagnostic } from '../types.js';
+import { type SectionDefinition } from './spec.schema.js';
+export declare const SUITE_STATUS_VALUES: readonly ["active", "draft", "deprecated"];
+export declare const SuiteStatusEnum: z.ZodEnum<["active", "draft", "deprecated"]>;
+export declare const SuiteFrontmatterSchema: z.ZodEffects<z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodOptional<z.ZodString>;
+    title: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    executionOrder: z.ZodOptional<z.ZodNumber>;
+    parallel: z.ZodOptional<z.ZodBoolean>;
+    status: z.ZodOptional<z.ZodEnum<["active", "draft", "deprecated"]>>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    name?: string | undefined;
+    status?: "active" | "draft" | "deprecated" | undefined;
+    title?: string | undefined;
+    tags?: string[] | undefined;
+    description?: string | undefined;
+    executionOrder?: number | undefined;
+    parallel?: boolean | undefined;
+}, {
+    id: string;
+    name?: string | undefined;
+    status?: "active" | "draft" | "deprecated" | undefined;
+    title?: string | undefined;
+    tags?: string[] | undefined;
+    description?: string | undefined;
+    executionOrder?: number | undefined;
+    parallel?: boolean | undefined;
+}>, {
+    id: string;
+    name?: string | undefined;
+    status?: "active" | "draft" | "deprecated" | undefined;
+    title?: string | undefined;
+    tags?: string[] | undefined;
+    description?: string | undefined;
+    executionOrder?: number | undefined;
+    parallel?: boolean | undefined;
+}, {
+    id: string;
+    name?: string | undefined;
+    status?: "active" | "draft" | "deprecated" | undefined;
+    title?: string | undefined;
+    tags?: string[] | undefined;
+    description?: string | undefined;
+    executionOrder?: number | undefined;
+    parallel?: boolean | undefined;
+}>;
+export type SuiteStatus = (typeof SUITE_STATUS_VALUES)[number];
+export type SuiteFrontmatter = z.infer<typeof SuiteFrontmatterSchema>;
+export declare const REQUIRED_SUITE_SECTIONS: SectionDefinition[];
+export declare const STANDARD_SUITE_SECTIONS: SectionDefinition[];
+/**
+ * Validates markdown body sections against suite rules.
+ */
+export declare function validateSuiteSections(body: string, filePath: string, bodyStartLine: number): LintDiagnostic[];

package/dist/linter/schemas/suite.schema.js

@@ -0,0 +1,83 @@
+import { z } from 'zod';
+import { extractMarkdownHeaders } from './spec.schema.js';
+export const SUITE_STATUS_VALUES = ['active', 'draft', 'deprecated'];
+export const SuiteStatusEnum = z.enum(SUITE_STATUS_VALUES, {
+    errorMap: (issue) => {
+        if (issue.code === 'invalid_type' && issue.received === 'undefined') {
+            return { message: "Missing required frontmatter attribute 'status'" };
+        }
+        return {
+            message: `Invalid status value. Expected one of: ${SUITE_STATUS_VALUES.join(', ')}`,
+        };
+    },
+});
+export const SuiteFrontmatterSchema = z
+    .object({
+    id: z
+        .string({
+        required_error: "Missing required frontmatter attribute 'id'",
+        invalid_type_error: "Frontmatter attribute 'id' must be a string",
+    })
+        .min(1, "Attribute 'id' cannot be empty"),
+    name: z.string().optional(),
+    title: z.string().optional(),
+    description: z.string().optional(),
+    executionOrder: z.number().optional(),
+    parallel: z.boolean().optional(),
+    status: SuiteStatusEnum.optional(),
+    tags: z.array(z.string()).optional(),
+})
+    .refine((data) => Boolean(data.name || data.title), {
+    message: "Missing required frontmatter attribute 'name' or 'title'",
+    path: ['title'],
+});
+// ─────────────────────────────────────────────────────────────────────────────
+// Suite Markdown Section Rules
+// ─────────────────────────────────────────────────────────────────────────────
+export const REQUIRED_SUITE_SECTIONS = [
+    {
+        name: 'Suite Title',
+        level: 1,
+        required: true,
+        headerPattern: /^#\s+(Suite:\s*)?.+$/i,
+        description: 'Top-level H1 suite heading (# Suite: <Name> or # <Name>)',
+    },
+];
+export const STANDARD_SUITE_SECTIONS = [
+    ...REQUIRED_SUITE_SECTIONS,
+    {
+        name: 'Description',
+        level: 2,
+        required: false,
+        headerPattern: /^##\s+Description/i,
+        description: 'Detailed description of suite scope and test coverage (## Description)',
+    },
+];
+/**
+ * Validates markdown body sections against suite rules.
+ */
+export function validateSuiteSections(body, filePath, bodyStartLine) {
+    const diagnostics = [];
+    const headers = extractMarkdownHeaders(body, bodyStartLine);
+    // 1. Verify required H1 Suite Title header exists
+    const h1Headers = headers.filter((h) => h.level === 1);
+    if (h1Headers.length === 0) {
+        diagnostics.push({
+            code: 'testspectra/missing-frontmatter',
+            severity: 'error',
+            message: 'Missing required markdown heading: expected top-level suite title "# Suite: <Name>"',
+            filePath,
+            line: bodyStartLine,
+        });
+    }
+    else if (h1Headers.length > 1) {
+        diagnostics.push({
+            code: 'testspectra/missing-frontmatter',
+            severity: 'warning',
+            message: `Multiple top-level H1 headings found in suite.md (${h1Headers.length}). Expected exactly one suite title heading.`,
+            filePath,
+            line: h1Headers[1].line,
+        });
+    }
+    return diagnostics;
+}

package/dist/linter/spec-linter.d.ts

@@ -0,0 +1,23 @@
+import type { LintDiagnostic, SpecLintResult } from './types.js';
+export declare class SpecLinter {
+    /**
+     * Validates a single spec.md file.
+     */
+    static validateSpecFile(filePath: string, contentOverride?: string, companionCodeOverrides?: Map<string, string> | Record<string, string>): {
+        diagnostics: LintDiagnostic[];
+        id?: string;
+        idLine?: number;
+    };
+    /**
+     * Validates a single suite.md file.
+     */
+    static validateSuiteFile(filePath: string, contentOverride?: string): {
+        diagnostics: LintDiagnostic[];
+        id?: string;
+        idLine?: number;
+    };
+    /**
+     * Validates all spec.md and suite.md files in a workspace or specific target path.
+     */
+    static validateWorkspace(workspaceDir: string, targetPath?: string): SpecLintResult;
+}