@gordon.gan/specflow 1.4.4-beta → 1.5.0-beta

package/dist/core/approval/index-schema.d.ts

@@ -0,0 +1,473 @@
+import { z } from 'zod';
+import type { ApprovalIndex } from './types.js';
+export declare const approvalIndexSchema: z.ZodObject<{
+    schema: z.ZodLiteral<"specflow.approval.index/v1">;
+    change: z.ZodString;
+    generated_at: z.ZodEffects<z.ZodString, string, unknown>;
+    mode: z.ZodDefault<z.ZodEnum<["segmented", "monolithic"]>>;
+    ui_in_scope: z.ZodDefault<z.ZodBoolean>;
+    db_in_scope: z.ZodDefault<z.ZodBoolean>;
+    api_in_scope: z.ZodDefault<z.ZodBoolean>;
+    optional: z.ZodDefault<z.ZodObject<{
+        s5: z.ZodDefault<z.ZodBoolean>;
+        s7: z.ZodDefault<z.ZodBoolean>;
+        s8: z.ZodDefault<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        s5: boolean;
+        s7: boolean;
+        s8: boolean;
+    }, {
+        s5?: boolean | undefined;
+        s7?: boolean | undefined;
+        s8?: boolean | undefined;
+    }>>;
+    parts_order: z.ZodArray<z.ZodString, "many">;
+    design_points: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    decisions: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    tables: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        action: z.ZodString;
+        part: z.ZodString;
+        repo: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        name: string;
+        action: string;
+        part: string;
+        repo?: string | undefined;
+    }, {
+        id: string;
+        name: string;
+        action: string;
+        part: string;
+        repo?: string | undefined;
+    }>, "many">>;
+    interfaces: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        short: z.ZodString;
+        change: z.ZodString;
+        part: z.ZodString;
+        repo: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        part: string;
+        short: string;
+        change: string;
+        repo?: string | undefined;
+    }, {
+        id: string;
+        part: string;
+        short: string;
+        change: string;
+        repo?: string | undefined;
+    }>, "many">>;
+    pages: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        route: z.ZodString;
+        apis: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        part: z.ZodString;
+        repo: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        part: string;
+        route: string;
+        apis: string[];
+        repo?: string | undefined;
+    }, {
+        id: string;
+        part: string;
+        route: string;
+        repo?: string | undefined;
+        apis?: string[] | undefined;
+    }>, "many">>;
+    capabilities: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        part: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        part: string;
+    }, {
+        id: string;
+        part: string;
+    }>, "many">>;
+    batching: z.ZodDefault<z.ZodObject<{
+        tables_per_call: z.ZodDefault<z.ZodNumber>;
+        interfaces_per_call: z.ZodDefault<z.ZodNumber>;
+        pages_per_call: z.ZodDefault<z.ZodNumber>;
+        capabilities_per_call: z.ZodDefault<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        tables_per_call: number;
+        interfaces_per_call: number;
+        pages_per_call: number;
+        capabilities_per_call: number;
+    }, {
+        tables_per_call?: number | undefined;
+        interfaces_per_call?: number | undefined;
+        pages_per_call?: number | undefined;
+        capabilities_per_call?: number | undefined;
+    }>>;
+    conventions: z.ZodDefault<z.ZodObject<{
+        architecture: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        database: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        api: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        frontend: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        architecture?: string[] | undefined;
+        api?: string[] | undefined;
+        database?: string[] | undefined;
+        frontend?: string[] | undefined;
+    }, {
+        architecture?: string[] | undefined;
+        api?: string[] | undefined;
+        database?: string[] | undefined;
+        frontend?: string[] | undefined;
+    }>>;
+    meta: z.ZodOptional<z.ZodObject<{
+        language: z.ZodOptional<z.ZodString>;
+        tech_stack: z.ZodOptional<z.ZodString>;
+        project_mode: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        language?: string | undefined;
+        tech_stack?: string | undefined;
+        project_mode?: string | undefined;
+    }, {
+        language?: string | undefined;
+        tech_stack?: string | undefined;
+        project_mode?: string | undefined;
+    }>>;
+    multi_repo: z.ZodOptional<z.ZodEffects<z.ZodObject<{
+        enabled: z.ZodBoolean;
+        document_mode: z.ZodOptional<z.ZodEnum<["unified", "per_repo"]>>;
+        primary_repo: z.ZodOptional<z.ZodString>;
+        repos: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            label: z.ZodString;
+            role: z.ZodOptional<z.ZodEnum<["platform", "web", "worker", "hub", "other"]>>;
+            change: z.ZodString;
+            root_hint: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            id: string;
+            change: string;
+            label: string;
+            role?: "platform" | "web" | "worker" | "hub" | "other" | undefined;
+            root_hint?: string | undefined;
+        }, {
+            id: string;
+            change: string;
+            label: string;
+            role?: "platform" | "web" | "worker" | "hub" | "other" | undefined;
+            root_hint?: string | undefined;
+        }>, "many">;
+        outputs: z.ZodOptional<z.ZodObject<{
+            unified: z.ZodOptional<z.ZodObject<{
+                repo: z.ZodString;
+                change: z.ZodString;
+                path: z.ZodString;
+            }, "strip", z.ZodTypeAny, {
+                path: string;
+                repo: string;
+                change: string;
+            }, {
+                path: string;
+                repo: string;
+                change: string;
+            }>>;
+            per_repo: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                repo: z.ZodString;
+                change: z.ZodString;
+                path: z.ZodString;
+            }, "strip", z.ZodTypeAny, {
+                path: string;
+                repo: string;
+                change: string;
+            }, {
+                path: string;
+                repo: string;
+                change: string;
+            }>, "many">>;
+        }, "strip", z.ZodTypeAny, {
+            unified?: {
+                path: string;
+                repo: string;
+                change: string;
+            } | undefined;
+            per_repo?: {
+                path: string;
+                repo: string;
+                change: string;
+            }[] | undefined;
+        }, {
+            unified?: {
+                path: string;
+                repo: string;
+                change: string;
+            } | undefined;
+            per_repo?: {
+                path: string;
+                repo: string;
+                change: string;
+            }[] | undefined;
+        }>>;
+    }, "strip", z.ZodTypeAny, {
+        enabled: boolean;
+        repos: {
+            id: string;
+            change: string;
+            label: string;
+            role?: "platform" | "web" | "worker" | "hub" | "other" | undefined;
+            root_hint?: string | undefined;
+        }[];
+        document_mode?: "unified" | "per_repo" | undefined;
+        primary_repo?: string | undefined;
+        outputs?: {
+            unified?: {
+                path: string;
+                repo: string;
+                change: string;
+            } | undefined;
+            per_repo?: {
+                path: string;
+                repo: string;
+                change: string;
+            }[] | undefined;
+        } | undefined;
+    }, {
+        enabled: boolean;
+        repos: {
+            id: string;
+            change: string;
+            label: string;
+            role?: "platform" | "web" | "worker" | "hub" | "other" | undefined;
+            root_hint?: string | undefined;
+        }[];
+        document_mode?: "unified" | "per_repo" | undefined;
+        primary_repo?: string | undefined;
+        outputs?: {
+            unified?: {
+                path: string;
+                repo: string;
+                change: string;
+            } | undefined;
+            per_repo?: {
+                path: string;
+                repo: string;
+                change: string;
+            }[] | undefined;
+        } | undefined;
+    }>, {
+        enabled: boolean;
+        repos: {
+            id: string;
+            change: string;
+            label: string;
+            role?: "platform" | "web" | "worker" | "hub" | "other" | undefined;
+            root_hint?: string | undefined;
+        }[];
+        document_mode?: "unified" | "per_repo" | undefined;
+        primary_repo?: string | undefined;
+        outputs?: {
+            unified?: {
+                path: string;
+                repo: string;
+                change: string;
+            } | undefined;
+            per_repo?: {
+                path: string;
+                repo: string;
+                change: string;
+            }[] | undefined;
+        } | undefined;
+    }, {
+        enabled: boolean;
+        repos: {
+            id: string;
+            change: string;
+            label: string;
+            role?: "platform" | "web" | "worker" | "hub" | "other" | undefined;
+            root_hint?: string | undefined;
+        }[];
+        document_mode?: "unified" | "per_repo" | undefined;
+        primary_repo?: string | undefined;
+        outputs?: {
+            unified?: {
+                path: string;
+                repo: string;
+                change: string;
+            } | undefined;
+            per_repo?: {
+                path: string;
+                repo: string;
+                change: string;
+            }[] | undefined;
+        } | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    schema: "specflow.approval.index/v1";
+    conventions: {
+        architecture?: string[] | undefined;
+        api?: string[] | undefined;
+        database?: string[] | undefined;
+        frontend?: string[] | undefined;
+    };
+    change: string;
+    generated_at: string;
+    mode: "segmented" | "monolithic";
+    ui_in_scope: boolean;
+    db_in_scope: boolean;
+    api_in_scope: boolean;
+    optional: {
+        s5: boolean;
+        s7: boolean;
+        s8: boolean;
+    };
+    parts_order: string[];
+    design_points: string[];
+    decisions: string[];
+    tables: {
+        id: string;
+        name: string;
+        action: string;
+        part: string;
+        repo?: string | undefined;
+    }[];
+    interfaces: {
+        id: string;
+        part: string;
+        short: string;
+        change: string;
+        repo?: string | undefined;
+    }[];
+    pages: {
+        id: string;
+        part: string;
+        route: string;
+        apis: string[];
+        repo?: string | undefined;
+    }[];
+    capabilities: {
+        id: string;
+        part: string;
+    }[];
+    batching: {
+        tables_per_call: number;
+        interfaces_per_call: number;
+        pages_per_call: number;
+        capabilities_per_call: number;
+    };
+    meta?: {
+        language?: string | undefined;
+        tech_stack?: string | undefined;
+        project_mode?: string | undefined;
+    } | undefined;
+    multi_repo?: {
+        enabled: boolean;
+        repos: {
+            id: string;
+            change: string;
+            label: string;
+            role?: "platform" | "web" | "worker" | "hub" | "other" | undefined;
+            root_hint?: string | undefined;
+        }[];
+        document_mode?: "unified" | "per_repo" | undefined;
+        primary_repo?: string | undefined;
+        outputs?: {
+            unified?: {
+                path: string;
+                repo: string;
+                change: string;
+            } | undefined;
+            per_repo?: {
+                path: string;
+                repo: string;
+                change: string;
+            }[] | undefined;
+        } | undefined;
+    } | undefined;
+}, {
+    schema: "specflow.approval.index/v1";
+    change: string;
+    parts_order: string[];
+    conventions?: {
+        architecture?: string[] | undefined;
+        api?: string[] | undefined;
+        database?: string[] | undefined;
+        frontend?: string[] | undefined;
+    } | undefined;
+    generated_at?: unknown;
+    mode?: "segmented" | "monolithic" | undefined;
+    ui_in_scope?: boolean | undefined;
+    db_in_scope?: boolean | undefined;
+    api_in_scope?: boolean | undefined;
+    optional?: {
+        s5?: boolean | undefined;
+        s7?: boolean | undefined;
+        s8?: boolean | undefined;
+    } | undefined;
+    design_points?: string[] | undefined;
+    decisions?: string[] | undefined;
+    tables?: {
+        id: string;
+        name: string;
+        action: string;
+        part: string;
+        repo?: string | undefined;
+    }[] | undefined;
+    interfaces?: {
+        id: string;
+        part: string;
+        short: string;
+        change: string;
+        repo?: string | undefined;
+    }[] | undefined;
+    pages?: {
+        id: string;
+        part: string;
+        route: string;
+        repo?: string | undefined;
+        apis?: string[] | undefined;
+    }[] | undefined;
+    capabilities?: {
+        id: string;
+        part: string;
+    }[] | undefined;
+    batching?: {
+        tables_per_call?: number | undefined;
+        interfaces_per_call?: number | undefined;
+        pages_per_call?: number | undefined;
+        capabilities_per_call?: number | undefined;
+    } | undefined;
+    meta?: {
+        language?: string | undefined;
+        tech_stack?: string | undefined;
+        project_mode?: string | undefined;
+    } | undefined;
+    multi_repo?: {
+        enabled: boolean;
+        repos: {
+            id: string;
+            change: string;
+            label: string;
+            role?: "platform" | "web" | "worker" | "hub" | "other" | undefined;
+            root_hint?: string | undefined;
+        }[];
+        document_mode?: "unified" | "per_repo" | undefined;
+        primary_repo?: string | undefined;
+        outputs?: {
+            unified?: {
+                path: string;
+                repo: string;
+                change: string;
+            } | undefined;
+            per_repo?: {
+                path: string;
+                repo: string;
+                change: string;
+            }[] | undefined;
+        } | undefined;
+    } | undefined;
+}>;
+export declare function parseApprovalIndex(raw: unknown): ApprovalIndex;
+/** Returns true when segmented fast-path (monolithic) is allowed. */
+export declare function isLightweightApproval(index: ApprovalIndex): boolean;
+export declare function shouldForceSegmented(index: ApprovalIndex): boolean;

package/dist/core/approval/index-schema.js

@@ -0,0 +1,146 @@
+import { z } from 'zod';
+const tableRefSchema = z.object({
+    id: z.string().min(1),
+    name: z.string().min(1),
+    action: z.string().min(1),
+    part: z.string().min(1),
+    repo: z.string().min(1).optional(),
+});
+const interfaceRefSchema = z.object({
+    id: z.string().min(1),
+    short: z.string().min(1),
+    change: z.string().min(1),
+    part: z.string().min(1),
+    repo: z.string().min(1).optional(),
+});
+const pageRefSchema = z.object({
+    id: z.string().min(1),
+    route: z.string().min(1),
+    apis: z.array(z.string()).default([]),
+    part: z.string().min(1),
+    repo: z.string().min(1).optional(),
+});
+const capabilityRefSchema = z.object({
+    id: z.string().min(1),
+    part: z.string().min(1),
+});
+const outputRefSchema = z.object({
+    repo: z.string().min(1),
+    change: z.string().min(1),
+    path: z.string().min(1),
+});
+const multiRepoSchema = z
+    .object({
+    enabled: z.boolean(),
+    document_mode: z.enum(['unified', 'per_repo']).optional(),
+    primary_repo: z.string().min(1).optional(),
+    repos: z
+        .array(z.object({
+        id: z.string().min(1),
+        label: z.string().min(1),
+        role: z.enum(['platform', 'web', 'worker', 'hub', 'other']).optional(),
+        change: z.string().min(1),
+        root_hint: z.string().min(1).optional(),
+    }))
+        .min(1),
+    outputs: z
+        .object({
+        unified: outputRefSchema.optional(),
+        per_repo: z.array(outputRefSchema).optional(),
+    })
+        .optional(),
+})
+    .superRefine((value, ctx) => {
+    if (!value.enabled) {
+        return;
+    }
+    if (value.repos.length < 2) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: 'multi_repo.repos must have at least 2 entries when enabled',
+            path: ['repos'],
+        });
+    }
+    if (value.document_mode === 'unified' && !value.primary_repo) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: 'multi_repo.primary_repo is required when document_mode is unified',
+            path: ['primary_repo'],
+        });
+    }
+    if (value.primary_repo && !value.repos.some((r) => r.id === value.primary_repo)) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: 'multi_repo.primary_repo must match a repos[].id',
+            path: ['primary_repo'],
+        });
+    }
+});
+export const approvalIndexSchema = z.object({
+    schema: z.literal('specflow.approval.index/v1'),
+    change: z.string().min(1),
+    generated_at: z.preprocess((val) => (val instanceof Date ? val.toISOString() : val), z.string().min(1)),
+    mode: z.enum(['segmented', 'monolithic']).default('segmented'),
+    ui_in_scope: z.boolean().default(false),
+    db_in_scope: z.boolean().default(false),
+    api_in_scope: z.boolean().default(false),
+    optional: z
+        .object({
+        s5: z.boolean().default(false),
+        s7: z.boolean().default(false),
+        s8: z.boolean().default(false),
+    })
+        .default({ s5: false, s7: false, s8: false }),
+    parts_order: z.array(z.string().min(1)).min(1),
+    design_points: z.array(z.string()).default([]),
+    decisions: z.array(z.string()).default([]),
+    tables: z.array(tableRefSchema).default([]),
+    interfaces: z.array(interfaceRefSchema).default([]),
+    pages: z.array(pageRefSchema).default([]),
+    capabilities: z.array(capabilityRefSchema).default([]),
+    batching: z
+        .object({
+        tables_per_call: z.number().int().positive().default(3),
+        interfaces_per_call: z.number().int().positive().default(3),
+        pages_per_call: z.number().int().positive().default(3),
+        capabilities_per_call: z.number().int().positive().default(1),
+    })
+        .default({
+        tables_per_call: 3,
+        interfaces_per_call: 3,
+        pages_per_call: 3,
+        capabilities_per_call: 1,
+    }),
+    conventions: z
+        .object({
+        architecture: z.array(z.string()).optional(),
+        database: z.array(z.string()).optional(),
+        api: z.array(z.string()).optional(),
+        frontend: z.array(z.string()).optional(),
+    })
+        .default({}),
+    meta: z
+        .object({
+        language: z.string().optional(),
+        tech_stack: z.string().optional(),
+        project_mode: z.string().optional(),
+    })
+        .optional(),
+    multi_repo: multiRepoSchema.optional(),
+});
+export function parseApprovalIndex(raw) {
+    return approvalIndexSchema.parse(raw);
+}
+/** Returns true when segmented fast-path (monolithic) is allowed. */
+export function isLightweightApproval(index) {
+    return (index.tables.length <= 2 &&
+        index.interfaces.length <= 3 &&
+        index.pages.length <= 2 &&
+        !index.optional.s5);
+}
+export function shouldForceSegmented(index) {
+    if (index.mode === 'monolithic') {
+        return false;
+    }
+    return !isLightweightApproval(index);
+}

package/dist/core/approval/index.d.ts

@@ -0,0 +1,4 @@
+export type { ApprovalAssembleResult, ApprovalDiagnostic, ApprovalIndex, ApprovalManifest, ApprovalGenerationMode, ApprovalMultiRepo, ApprovalDocumentMode, } from './types.js';
+export { parseApprovalIndex, isLightweightApproval, shouldForceSegmented, approvalIndexSchema, } from './index-schema.js';
+export { getChangeDirectory, getApprovalWorkspaceDir, getApprovalIndexPath, getApprovalManifestPath, getApprovalPartsDir, getApprovalPartPath, getApprovalOutputPath, getApprovalAnalysisPath, } from './paths.js';
+export { assembleApprovalDocument, readApprovalIndex, readApprovalManifest, } from './assemble.js';

package/dist/core/approval/index.js

@@ -0,0 +1,3 @@
+export { parseApprovalIndex, isLightweightApproval, shouldForceSegmented, approvalIndexSchema, } from './index-schema.js';
+export { getChangeDirectory, getApprovalWorkspaceDir, getApprovalIndexPath, getApprovalManifestPath, getApprovalPartsDir, getApprovalPartPath, getApprovalOutputPath, getApprovalAnalysisPath, } from './paths.js';
+export { assembleApprovalDocument, readApprovalIndex, readApprovalManifest, } from './assemble.js';

package/dist/core/approval/paths.d.ts

@@ -0,0 +1,8 @@
+export declare function getChangeDirectory(projectRoot: string, changeName: string): string;
+export declare function getApprovalWorkspaceDir(changeDir: string): string;
+export declare function getApprovalIndexPath(changeDir: string): string;
+export declare function getApprovalManifestPath(changeDir: string): string;
+export declare function getApprovalPartsDir(changeDir: string): string;
+export declare function getApprovalPartPath(changeDir: string, partId: string): string;
+export declare function getApprovalOutputPath(changeDir: string): string;
+export declare function getApprovalAnalysisPath(changeDir: string): string;

package/dist/core/approval/paths.js

@@ -0,0 +1,28 @@
+import { join } from 'node:path';
+import { validateChangeName } from '../../utils/change-utils.js';
+const CHANGES_REL = 'specflow/changes';
+export function getChangeDirectory(projectRoot, changeName) {
+    validateChangeName(changeName);
+    return join(projectRoot, CHANGES_REL, changeName);
+}
+export function getApprovalWorkspaceDir(changeDir) {
+    return join(changeDir, 'approval');
+}
+export function getApprovalIndexPath(changeDir) {
+    return join(getApprovalWorkspaceDir(changeDir), 'index.yaml');
+}
+export function getApprovalManifestPath(changeDir) {
+    return join(getApprovalWorkspaceDir(changeDir), 'manifest.json');
+}
+export function getApprovalPartsDir(changeDir) {
+    return join(getApprovalWorkspaceDir(changeDir), 'parts');
+}
+export function getApprovalPartPath(changeDir, partId) {
+    return join(getApprovalPartsDir(changeDir), `${partId}.md`);
+}
+export function getApprovalOutputPath(changeDir) {
+    return join(changeDir, 'approval.md');
+}
+export function getApprovalAnalysisPath(changeDir) {
+    return join(getApprovalWorkspaceDir(changeDir), 'analysis.json');
+}