@gordon.gan/specflow 1.1.1 → 1.2.0-beta

package/dist/core/references.js

@@ -0,0 +1,51 @@
+export const REFERENCE_INDEX_BUDGET_BYTES = 50 * 1024;
+export function normalizeReferences(references, rootStoreId) {
+    const seen = new Set();
+    const output = [];
+    for (const ref of references) {
+        if (rootStoreId && ref.id === rootStoreId) {
+            continue;
+        }
+        if (seen.has(ref.id)) {
+            continue;
+        }
+        seen.add(ref.id);
+        output.push(ref);
+    }
+    return output;
+}
+export function sanitizeReferenceField(value, maxLength = 200) {
+    return value
+        .replace(/[\u0000-\u001F\u007F]/g, ' ')
+        .replace(/\s+/g, ' ')
+        .trim()
+        .slice(0, maxLength);
+}
+export function buildReferenceIndex(entries) {
+    const lines = [];
+    const diagnostics = [];
+    let truncated = false;
+    for (const entry of entries) {
+        const line = `- ${sanitizeReferenceField(entry.storeId)}/${sanitizeReferenceField(entry.specId)}: ${sanitizeReferenceField(entry.purpose)} | ${entry.fetchCommand}`;
+        const candidate = [...lines, line].join('\n');
+        if (Buffer.byteLength(candidate, 'utf8') > REFERENCE_INDEX_BUDGET_BYTES) {
+            truncated = true;
+            break;
+        }
+        lines.push(line);
+    }
+    if (truncated) {
+        diagnostics.push({
+            severity: 'warning',
+            code: 'reference_index_truncated',
+            message: 'Referenced specification index exceeded the 50 KiB budget.',
+            target: 'references.index',
+            fix: 'Use specflow show or specflow context to fetch remaining referenced specs.',
+        });
+    }
+    return {
+        rendered: lines.join('\n'),
+        truncated,
+        diagnostics,
+    };
+}

package/dist/core/relationship-health.d.ts

@@ -0,0 +1,22 @@
+import type { Diagnostic } from './diagnostics.js';
+import type { NormalizedReference } from './project-config.js';
+import type { ParsedProjectConfig } from './project-config.js';
+import type { StoreRegistry } from './store/foundation.js';
+import type { ResolvedPlanningRoot } from './root-selection.js';
+export interface RelationshipHealthResult {
+    readonly rootHealth: readonly Diagnostic[];
+    readonly selectedStoreHealth: readonly Diagnostic[];
+    readonly referenceHealth: Array<{
+        storeId: string;
+        diagnostics: Diagnostic[];
+    }>;
+    readonly registryHealth: readonly Diagnostic[];
+    readonly pointerHealth: readonly Diagnostic[];
+    readonly mutationsPerformed: false;
+}
+export declare function inspectRelationships(input: {
+    resolved: ResolvedPlanningRoot;
+    references: readonly NormalizedReference[];
+    registry: StoreRegistry;
+    projectConfig?: ParsedProjectConfig;
+}): Promise<RelationshipHealthResult>;

package/dist/core/relationship-health.js

@@ -0,0 +1,68 @@
+import { sortDiagnostics } from './diagnostics.js';
+import { inspectStoreEntry } from './store/health.js';
+import { hasPlanningContent } from './root-selection.js';
+export async function inspectRelationships(input) {
+    const pointerHealth = [];
+    if (input.projectConfig?.store && input.resolved.source === 'nearest') {
+        pointerHealth.push({
+            severity: 'info',
+            code: 'store_pointer_ignored',
+            message: `Project store pointer '${input.projectConfig.store}' is ignored because local planning content exists.`,
+            target: 'config.store',
+        });
+    }
+    const rootHealth = [...input.resolved.diagnostics];
+    if (!(await hasPlanningContent(input.resolved.root)) && !input.resolved.storeId) {
+        rootHealth.push({
+            severity: 'warning',
+            code: 'root_empty_planning',
+            message: 'Resolved planning root has no baseline specs or active changes.',
+            target: 'planning.root',
+        });
+    }
+    const selectedStoreHealth = [];
+    if (input.resolved.storeId) {
+        const entry = input.registry.stores[input.resolved.storeId];
+        if (!entry) {
+            selectedStoreHealth.push({
+                severity: 'error',
+                code: 'store_not_registered',
+                message: `Selected store '${input.resolved.storeId}' is not registered.`,
+                target: `stores.${input.resolved.storeId}`,
+                fix: `Run specflow store register --id ${input.resolved.storeId} <path> --yes`,
+            });
+        }
+        else {
+            selectedStoreHealth.push(...(await inspectStoreEntry(input.resolved.storeId, entry)));
+        }
+    }
+    const referenceHealth = await Promise.all(input.references.map(async (ref) => {
+        const entry = input.registry.stores[ref.id];
+        if (!entry) {
+            return {
+                storeId: ref.id,
+                diagnostics: [
+                    {
+                        severity: 'warning',
+                        code: 'reference_unregistered',
+                        message: `Referenced store '${ref.id}' is not registered.`,
+                        target: `references.${ref.id}`,
+                        fix: `Run specflow store register --id ${ref.id} <path> --yes`,
+                    },
+                ],
+            };
+        }
+        return {
+            storeId: ref.id,
+            diagnostics: [...(await inspectStoreEntry(ref.id, entry))],
+        };
+    }));
+    return {
+        rootHealth: sortDiagnostics(rootHealth),
+        selectedStoreHealth: sortDiagnostics(selectedStoreHealth),
+        referenceHealth,
+        registryHealth: [],
+        pointerHealth: sortDiagnostics(pointerHealth),
+        mutationsPerformed: false,
+    };
+}

package/dist/core/root-selection.d.ts

@@ -0,0 +1,26 @@
+import type { Diagnostic } from './diagnostics.js';
+import type { GlobalConfig } from './global-config.js';
+import { type ParsedProjectConfig } from './project-config.js';
+import type { StoreRegistry } from './store/foundation.js';
+export type RootSource = 'store' | 'declared' | 'global_default' | 'nearest' | 'implicit';
+export interface ResolvedPlanningRoot {
+    readonly root: string;
+    readonly specsDir: string;
+    readonly changesDir: string;
+    readonly archiveDir: string;
+    readonly source: RootSource;
+    readonly storeId?: string;
+    readonly diagnostics: readonly Diagnostic[];
+}
+export interface ResolvePlanningRootOptions {
+    readonly startPath?: string;
+    readonly store?: string;
+    readonly allowImplicitRoot?: boolean;
+    readonly registry?: StoreRegistry;
+    readonly globalConfig?: GlobalConfig;
+    readonly readConfig?: (projectRoot: string) => ParsedProjectConfig;
+}
+export declare function hasBaselineSpec(root: string): Promise<boolean>;
+export declare function hasNonArchiveChange(root: string): Promise<boolean>;
+export declare function hasPlanningContent(root: string): Promise<boolean>;
+export declare function resolvePlanningRoot(options?: ResolvePlanningRootOptions): Promise<ResolvedPlanningRoot>;

package/dist/core/root-selection.js

@@ -0,0 +1,197 @@
+import { readFileSync } from 'node:fs';
+import yaml from 'js-yaml';
+import { promises as fs } from 'node:fs';
+import * as path from 'node:path';
+import { parseProjectConfig } from './project-config.js';
+import { findProjectRoot } from '../utils/project-root.js';
+const ARCHIVE_DIR_NAME = 'archive';
+async function directoryHasEntries(dirPath) {
+    try {
+        const entries = await fs.readdir(dirPath);
+        return entries.length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+export async function hasBaselineSpec(root) {
+    const specsDir = path.join(root, 'specflow', 'specs');
+    if (!(await directoryHasEntries(specsDir))) {
+        return false;
+    }
+    const entries = await fs.readdir(specsDir, { withFileTypes: true });
+    for (const entry of entries) {
+        if (entry.isDirectory()) {
+            const specPath = path.join(specsDir, entry.name, 'spec.md');
+            try {
+                await fs.stat(specPath);
+                return true;
+            }
+            catch {
+                // continue
+            }
+        }
+    }
+    return false;
+}
+export async function hasNonArchiveChange(root) {
+    const changesDir = path.join(root, 'specflow', 'changes');
+    if (!(await directoryHasEntries(changesDir))) {
+        return false;
+    }
+    const entries = await fs.readdir(changesDir, { withFileTypes: true });
+    for (const entry of entries) {
+        if (!entry.isDirectory() || entry.name === ARCHIVE_DIR_NAME) {
+            continue;
+        }
+        return true;
+    }
+    return false;
+}
+export async function hasPlanningContent(root) {
+    return (await hasBaselineSpec(root)) || (await hasNonArchiveChange(root));
+}
+function resolveFromStoreId(storeId, registry, source) {
+    const entry = registry.stores[storeId];
+    if (!entry) {
+        return null;
+    }
+    const root = entry.backend.local_path;
+    return {
+        root,
+        specsDir: path.join(root, 'specflow', 'specs'),
+        changesDir: path.join(root, 'specflow', 'changes'),
+        archiveDir: path.join(root, 'specflow', 'changes', ARCHIVE_DIR_NAME),
+        source,
+        storeId,
+        diagnostics: [],
+    };
+}
+function buildImplicitFailure(startPath) {
+    return {
+        root: startPath,
+        specsDir: path.join(startPath, 'specflow', 'specs'),
+        changesDir: path.join(startPath, 'specflow', 'changes'),
+        archiveDir: path.join(startPath, 'specflow', 'changes', ARCHIVE_DIR_NAME),
+        source: 'implicit',
+        diagnostics: [
+            {
+                severity: 'error',
+                code: 'planning_root_not_found',
+                message: 'No planning root could be resolved.',
+                target: 'planning.root',
+                fix: 'Run specflow init or register a planning store.',
+            },
+        ],
+    };
+}
+export async function resolvePlanningRoot(options = {}) {
+    const startPath = path.resolve(options.startPath ?? process.cwd());
+    const registry = options.registry ?? { version: 1, stores: {} };
+    const globalConfig = options.globalConfig ?? {};
+    const readConfig = options.readConfig ??
+        ((projectRoot) => {
+            const configPath = path.join(projectRoot, 'specflow', 'config.yaml');
+            try {
+                const content = readFileSync(configPath, 'utf-8');
+                return parseProjectConfig(yaml.load(content));
+            }
+            catch {
+                return parseProjectConfig({});
+            }
+        });
+    if (options.store) {
+        const explicit = resolveFromStoreId(options.store, registry, 'store');
+        if (explicit) {
+            return explicit;
+        }
+        return {
+            ...buildImplicitFailure(startPath),
+            source: 'store',
+            storeId: options.store,
+            diagnostics: [
+                {
+                    severity: 'error',
+                    code: 'store_not_registered',
+                    message: `Store '${options.store}' is not registered.`,
+                    target: `stores.${options.store}`,
+                    fix: 'Run specflow store register to add the checkout.',
+                },
+            ],
+        };
+    }
+    const nearest = findProjectRoot(startPath);
+    if (nearest) {
+        const config = readConfig(nearest);
+        if (await hasPlanningContent(nearest)) {
+            return {
+                root: nearest,
+                specsDir: path.join(nearest, 'specflow', 'specs'),
+                changesDir: path.join(nearest, 'specflow', 'changes'),
+                archiveDir: path.join(nearest, 'specflow', 'changes', ARCHIVE_DIR_NAME),
+                source: 'nearest',
+                diagnostics: config.store
+                    ? [
+                        {
+                            severity: 'info',
+                            code: 'store_pointer_ignored',
+                            message: `Ignoring store pointer '${config.store}' because local planning content exists.`,
+                            target: 'config.store',
+                        },
+                    ]
+                    : [],
+            };
+        }
+        if (config.store) {
+            const declared = resolveFromStoreId(config.store, registry, 'declared');
+            if (declared) {
+                return declared;
+            }
+            return {
+                ...buildImplicitFailure(nearest),
+                source: 'declared',
+                storeId: config.store,
+                diagnostics: [
+                    {
+                        severity: 'error',
+                        code: 'store_not_registered',
+                        message: `Declared store '${config.store}' is not registered.`,
+                        target: 'config.store',
+                        fix: `Run specflow store register for '${config.store}'.`,
+                    },
+                ],
+            };
+        }
+    }
+    if (globalConfig.defaultStore) {
+        const fallback = resolveFromStoreId(globalConfig.defaultStore, registry, 'global_default');
+        if (fallback) {
+            return fallback;
+        }
+        return {
+            ...buildImplicitFailure(startPath),
+            source: 'global_default',
+            storeId: globalConfig.defaultStore,
+            diagnostics: [
+                {
+                    severity: 'error',
+                    code: 'default_store_missing',
+                    message: `Global default store '${globalConfig.defaultStore}' is not registered.`,
+                    target: 'global.defaultStore',
+                    fix: 'Register the default store or clear defaultStore from global config.',
+                },
+            ],
+        };
+    }
+    if (nearest && options.allowImplicitRoot !== false) {
+        return {
+            root: nearest,
+            specsDir: path.join(nearest, 'specflow', 'specs'),
+            changesDir: path.join(nearest, 'specflow', 'changes'),
+            archiveDir: path.join(nearest, 'specflow', 'changes', ARCHIVE_DIR_NAME),
+            source: 'nearest',
+            diagnostics: [],
+        };
+    }
+    return buildImplicitFailure(startPath);
+}

package/dist/core/store/errors.d.ts

@@ -0,0 +1,2 @@
+export { StoreError } from './foundation.js';
+export type { StoreIdentity, StoreRegistry, RegistryEntry, } from './foundation.js';

package/dist/core/store/errors.js

@@ -0,0 +1 @@
+export { StoreError } from './foundation.js';

package/dist/core/store/foundation.d.ts

@@ -0,0 +1,141 @@
+import { z } from 'zod';
+import type { Diagnostic } from '../diagnostics.js';
+export declare const KEBAB_CASE_STORE_ID: RegExp;
+export declare const StoreIdentitySchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    id: z.ZodString;
+    remote: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    version: 1;
+    id: string;
+    remote?: string | undefined;
+}, {
+    version: 1;
+    id: string;
+    remote?: string | undefined;
+}>;
+export type StoreIdentity = z.infer<typeof StoreIdentitySchema>;
+export declare const StoreProvenanceSchema: z.ZodEnum<["managed", "external"]>;
+export declare const StoreBackendSchema: z.ZodObject<{
+    type: z.ZodLiteral<"git">;
+    local_path: z.ZodString;
+    remote: z.ZodOptional<z.ZodString>;
+    branch: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    type: "git";
+    local_path: string;
+    remote?: string | undefined;
+    branch?: string | undefined;
+}, {
+    type: "git";
+    local_path: string;
+    remote?: string | undefined;
+    branch?: string | undefined;
+}>;
+export declare const RegistryEntrySchema: z.ZodObject<{
+    provenance: z.ZodEnum<["managed", "external"]>;
+    backend: z.ZodObject<{
+        type: z.ZodLiteral<"git">;
+        local_path: z.ZodString;
+        remote: z.ZodOptional<z.ZodString>;
+        branch: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        type: "git";
+        local_path: string;
+        remote?: string | undefined;
+        branch?: string | undefined;
+    }, {
+        type: "git";
+        local_path: string;
+        remote?: string | undefined;
+        branch?: string | undefined;
+    }>;
+}, "strict", z.ZodTypeAny, {
+    provenance: "managed" | "external";
+    backend: {
+        type: "git";
+        local_path: string;
+        remote?: string | undefined;
+        branch?: string | undefined;
+    };
+}, {
+    provenance: "managed" | "external";
+    backend: {
+        type: "git";
+        local_path: string;
+        remote?: string | undefined;
+        branch?: string | undefined;
+    };
+}>;
+export declare const StoreRegistrySchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    stores: z.ZodRecord<z.ZodString, z.ZodObject<{
+        provenance: z.ZodEnum<["managed", "external"]>;
+        backend: z.ZodObject<{
+            type: z.ZodLiteral<"git">;
+            local_path: z.ZodString;
+            remote: z.ZodOptional<z.ZodString>;
+            branch: z.ZodOptional<z.ZodString>;
+        }, "strict", z.ZodTypeAny, {
+            type: "git";
+            local_path: string;
+            remote?: string | undefined;
+            branch?: string | undefined;
+        }, {
+            type: "git";
+            local_path: string;
+            remote?: string | undefined;
+            branch?: string | undefined;
+        }>;
+    }, "strict", z.ZodTypeAny, {
+        provenance: "managed" | "external";
+        backend: {
+            type: "git";
+            local_path: string;
+            remote?: string | undefined;
+            branch?: string | undefined;
+        };
+    }, {
+        provenance: "managed" | "external";
+        backend: {
+            type: "git";
+            local_path: string;
+            remote?: string | undefined;
+            branch?: string | undefined;
+        };
+    }>>;
+}, "strict", z.ZodTypeAny, {
+    stores: Record<string, {
+        provenance: "managed" | "external";
+        backend: {
+            type: "git";
+            local_path: string;
+            remote?: string | undefined;
+            branch?: string | undefined;
+        };
+    }>;
+    version: 1;
+}, {
+    stores: Record<string, {
+        provenance: "managed" | "external";
+        backend: {
+            type: "git";
+            local_path: string;
+            remote?: string | undefined;
+            branch?: string | undefined;
+        };
+    }>;
+    version: 1;
+}>;
+export type StoreRegistry = z.infer<typeof StoreRegistrySchema>;
+export type RegistryEntry = z.infer<typeof RegistryEntrySchema>;
+export declare class StoreError extends Error {
+    readonly diagnostics: readonly Diagnostic[];
+    constructor(message: string, diagnostics: Diagnostic | readonly Diagnostic[]);
+}
+export declare function validateStoreId(id: string): void;
+export declare function canonicalizePath(targetPath: string): string;
+export declare function pathsReferToSameCheckout(leftPath: string, rightPath: string, platform?: NodeJS.Platform): boolean;
+export declare const STORE_IDENTITY_RELATIVE_PATH: string;
+export declare function getStoreIdentityPath(root: string): string;
+export declare function emptyRegistry(): StoreRegistry;

package/dist/core/store/foundation.js

@@ -0,0 +1,79 @@
+import { z } from 'zod';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+export const KEBAB_CASE_STORE_ID = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+export const StoreIdentitySchema = z
+    .object({
+    version: z.literal(1),
+    id: z.string().regex(KEBAB_CASE_STORE_ID),
+    remote: z.string().url().optional(),
+})
+    .strict();
+export const StoreProvenanceSchema = z.enum(['managed', 'external']);
+export const StoreBackendSchema = z
+    .object({
+    type: z.literal('git'),
+    local_path: z.string().min(1),
+    remote: z.string().optional(),
+    branch: z.string().optional(),
+})
+    .strict();
+export const RegistryEntrySchema = z
+    .object({
+    provenance: StoreProvenanceSchema,
+    backend: StoreBackendSchema,
+})
+    .strict();
+export const StoreRegistrySchema = z
+    .object({
+    version: z.literal(1),
+    stores: z.record(RegistryEntrySchema),
+})
+    .strict();
+export class StoreError extends Error {
+    diagnostics;
+    constructor(message, diagnostics) {
+        super(message);
+        this.name = 'StoreError';
+        this.diagnostics = Array.isArray(diagnostics) ? diagnostics : [diagnostics];
+    }
+}
+export function validateStoreId(id) {
+    if (!KEBAB_CASE_STORE_ID.test(id)) {
+        throw new StoreError(`Invalid store ID '${id}'.`, {
+            severity: 'error',
+            code: 'invalid_store_id',
+            message: `Store ID '${id}' must be kebab-case.`,
+            target: 'store.id',
+            fix: 'Use lowercase letters, numbers, and single hyphens only.',
+        });
+    }
+}
+export function canonicalizePath(targetPath) {
+    return fs.realpathSync.native ? fs.realpathSync.native(targetPath) : fs.realpathSync(targetPath);
+}
+export function pathsReferToSameCheckout(leftPath, rightPath, platform = process.platform) {
+    const left = canonicalizePath(leftPath);
+    const right = canonicalizePath(rightPath);
+    if (platform === 'win32') {
+        return left.toLowerCase() === right.toLowerCase();
+    }
+    if (left === right) {
+        return true;
+    }
+    try {
+        const leftStat = fs.statSync(left);
+        const rightStat = fs.statSync(right);
+        return leftStat.dev === rightStat.dev && leftStat.ino === rightStat.ino;
+    }
+    catch {
+        return false;
+    }
+}
+export const STORE_IDENTITY_RELATIVE_PATH = path.join('.specflow-store', 'store.yaml');
+export function getStoreIdentityPath(root) {
+    return path.join(root, STORE_IDENTITY_RELATIVE_PATH);
+}
+export function emptyRegistry() {
+    return { version: 1, stores: {} };
+}

package/dist/core/store/health.d.ts

@@ -0,0 +1,13 @@
+import type { Diagnostic } from '../diagnostics.js';
+import { type RegistryEntry, type StoreRegistry } from './foundation.js';
+export declare function inspectStoreEntry(storeId: string, entry: RegistryEntry): Promise<readonly Diagnostic[]>;
+export declare function inspectAllStoresHealth(registry: StoreRegistry): Promise<Array<{
+    id: string;
+    root: string;
+    provenance: string;
+    diagnostics: Diagnostic[];
+}>>;
+export declare function flattenStoreDoctorDiagnostics(stores: Array<{
+    id: string;
+    diagnostics: Diagnostic[];
+}>): Diagnostic[];