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

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

@@ -0,0 +1,244 @@
+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;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        name: string;
+        action: string;
+        part: string;
+    }, {
+        id: string;
+        name: string;
+        action: string;
+        part: string;
+    }>, "many">>;
+    interfaces: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        short: z.ZodString;
+        change: z.ZodString;
+        part: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        part: string;
+        short: string;
+        change: string;
+    }, {
+        id: string;
+        part: string;
+        short: string;
+        change: string;
+    }>, "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;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        part: string;
+        route: string;
+        apis: string[];
+    }, {
+        id: string;
+        part: string;
+        route: string;
+        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;
+    }>>;
+}, "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;
+    }[];
+    interfaces: {
+        id: string;
+        part: string;
+        short: string;
+        change: string;
+    }[];
+    pages: {
+        id: string;
+        part: string;
+        route: string;
+        apis: string[];
+    }[];
+    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;
+}, {
+    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;
+    }[] | undefined;
+    interfaces?: {
+        id: string;
+        part: string;
+        short: string;
+        change: string;
+    }[] | undefined;
+    pages?: {
+        id: string;
+        part: string;
+        route: string;
+        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;
+}>;
+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,90 @@
+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),
+});
+const interfaceRefSchema = z.object({
+    id: z.string().min(1),
+    short: z.string().min(1),
+    change: z.string().min(1),
+    part: z.string().min(1),
+});
+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),
+});
+const capabilityRefSchema = z.object({
+    id: z.string().min(1),
+    part: z.string().min(1),
+});
+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(),
+});
+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, } 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');
+}

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

@@ -0,0 +1,92 @@
+export type ApprovalGenerationMode = 'segmented' | 'monolithic';
+export type ApprovalPartStatus = 'draft' | 'ok' | 'retry';
+export interface ApprovalOptionalChapters {
+    readonly s5: boolean;
+    readonly s7: boolean;
+    readonly s8: boolean;
+}
+export interface ApprovalBatching {
+    readonly tables_per_call: number;
+    readonly interfaces_per_call: number;
+    readonly pages_per_call: number;
+    readonly capabilities_per_call: number;
+}
+export interface ApprovalTableRef {
+    readonly id: string;
+    readonly name: string;
+    readonly action: string;
+    readonly part: string;
+}
+export interface ApprovalInterfaceRef {
+    readonly id: string;
+    readonly short: string;
+    readonly change: string;
+    readonly part: string;
+}
+export interface ApprovalPageRef {
+    readonly id: string;
+    readonly route: string;
+    readonly apis: readonly string[];
+    readonly part: string;
+}
+export interface ApprovalCapabilityRef {
+    readonly id: string;
+    readonly part: string;
+}
+export interface ApprovalConventionsResolved {
+    readonly architecture?: readonly string[];
+    readonly database?: readonly string[];
+    readonly api?: readonly string[];
+    readonly frontend?: readonly string[];
+}
+export interface ApprovalIndex {
+    readonly schema: 'specflow.approval.index/v1';
+    readonly change: string;
+    readonly generated_at: string;
+    readonly mode: ApprovalGenerationMode;
+    readonly ui_in_scope: boolean;
+    readonly db_in_scope: boolean;
+    readonly api_in_scope: boolean;
+    readonly optional: ApprovalOptionalChapters;
+    readonly parts_order: readonly string[];
+    readonly design_points: readonly string[];
+    readonly decisions: readonly string[];
+    readonly tables: readonly ApprovalTableRef[];
+    readonly interfaces: readonly ApprovalInterfaceRef[];
+    readonly pages: readonly ApprovalPageRef[];
+    readonly capabilities: readonly ApprovalCapabilityRef[];
+    readonly batching: ApprovalBatching;
+    readonly conventions: ApprovalConventionsResolved;
+    readonly meta?: {
+        readonly language?: string;
+        readonly tech_stack?: string;
+        readonly project_mode?: string;
+    };
+}
+export interface ApprovalManifestPart {
+    readonly id: string;
+    readonly path: string;
+    readonly status: ApprovalPartStatus;
+    readonly sha256?: string;
+    readonly updated_at?: string;
+}
+export interface ApprovalManifest {
+    readonly schema: 'specflow.approval.manifest/v1';
+    readonly change: string;
+    readonly parts: readonly ApprovalManifestPart[];
+    readonly assembled_at?: string;
+    readonly approval_sha256?: string;
+}
+export type ApprovalDiagnosticSeverity = 'error' | 'warning';
+export interface ApprovalDiagnostic {
+    readonly code: string;
+    readonly severity: ApprovalDiagnosticSeverity;
+    readonly message: string;
+    readonly part?: string;
+}
+export interface ApprovalAssembleResult {
+    readonly markdown?: string;
+    readonly outputPath?: string;
+    readonly diagnostics: readonly ApprovalDiagnostic[];
+    readonly ok: boolean;
+}

package/dist/core/approval/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gordon.gan/specflow",
-  "version": "1.4.4-beta",
+  "version": "1.4.6-beta",
   "type": "module",
   "description": "SpecFlow — unified spec-driven development: OpenSpec planning + Superpowers execution in one CLI and cross-IDE workflow",
   "keywords": [