@gordon.gan/specflow 1.1.1 → 1.2.0-beta.1

package/dist/core/project-config.js

@@ -0,0 +1,104 @@
+import { z } from 'zod';
+import { DEFAULT_ARTIFACT_LANGUAGE, isArtifactLanguage, } from './artifact-language.js';
+const KEBAB_CASE_ID = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+const ReferenceObjectSchema = z
+    .object({
+    id: z.string().regex(KEBAB_CASE_ID),
+    remote: z.string().url().optional(),
+})
+    .strict();
+function referenceDiagnostic(message, target) {
+    return {
+        severity: 'warning',
+        code: 'invalid_reference',
+        message,
+        target,
+        fix: 'Fix or remove the invalid reference entry in specflow/config.yaml.',
+    };
+}
+export function parseProjectConfig(raw) {
+    const diagnostics = [];
+    const record = typeof raw === 'object' && raw !== null ? raw : {};
+    const schema = typeof record.schema === 'string' ? record.schema : 'specflow';
+    const context = typeof record.context === 'string' ? record.context : undefined;
+    let artifactLanguage = DEFAULT_ARTIFACT_LANGUAGE;
+    if (record.artifacts !== undefined) {
+        const artifacts = typeof record.artifacts === 'object' &&
+            record.artifacts !== null &&
+            !Array.isArray(record.artifacts)
+            ? record.artifacts
+            : undefined;
+        const configuredLanguage = artifacts?.language;
+        if (!artifacts ||
+            (configuredLanguage !== undefined &&
+                !isArtifactLanguage(configuredLanguage))) {
+            diagnostics.push({
+                severity: 'error',
+                code: 'invalid_artifact_language',
+                message: "Project artifact language must be one of: 'en', 'zh-CN'.",
+                target: 'config.artifacts.language',
+                fix: "Set artifacts.language to 'en' or 'zh-CN'.",
+            });
+        }
+        else if (isArtifactLanguage(configuredLanguage)) {
+            artifactLanguage = configuredLanguage;
+        }
+    }
+    let store;
+    if (record.store !== undefined) {
+        if (typeof record.store === 'string' && KEBAB_CASE_ID.test(record.store)) {
+            store = record.store;
+        }
+        else {
+            diagnostics.push({
+                severity: 'error',
+                code: 'invalid_store_pointer',
+                message: 'Project store pointer must be a kebab-case store ID.',
+                target: 'config.store',
+                fix: 'Set store to a valid kebab-case ID such as platform-contracts.',
+            });
+        }
+    }
+    const references = [];
+    const seen = new Set();
+    if (Array.isArray(record.references)) {
+        for (const [index, entry] of record.references.entries()) {
+            if (typeof entry === 'string') {
+                if (!KEBAB_CASE_ID.test(entry)) {
+                    diagnostics.push(referenceDiagnostic(`Invalid reference ID '${entry}'.`, `config.references[${index}]`));
+                    continue;
+                }
+                if (seen.has(entry)) {
+                    continue;
+                }
+                seen.add(entry);
+                references.push({ id: entry });
+                continue;
+            }
+            const parsed = ReferenceObjectSchema.safeParse(entry);
+            if (!parsed.success) {
+                diagnostics.push(referenceDiagnostic(parsed.error.message, `config.references[${index}]`));
+                continue;
+            }
+            if (seen.has(parsed.data.id)) {
+                continue;
+            }
+            seen.add(parsed.data.id);
+            references.push({
+                id: parsed.data.id,
+                ...(parsed.data.remote ? { remote: parsed.data.remote } : {}),
+            });
+        }
+    }
+    return {
+        schema,
+        context,
+        artifactLanguage,
+        store,
+        references,
+        diagnostics,
+    };
+}
+export function loadProjectConfigFromObject(raw) {
+    return parseProjectConfig(raw);
+}

package/dist/core/reference-index.d.ts

@@ -0,0 +1,8 @@
+import type { ReferencedStoresSection } from './artifact-graph/instruction-loader.js';
+import type { NormalizedReference } from './project-config.js';
+import type { StoreRegistry } from './store/foundation.js';
+export declare function buildReferencedStoreIndex(input: {
+    references: readonly NormalizedReference[];
+    registry: StoreRegistry;
+    rootStoreId?: string;
+}): Promise<ReferencedStoresSection>;

package/dist/core/reference-index.js

@@ -0,0 +1,80 @@
+import { promises as fs } from 'node:fs';
+import * as path from 'node:path';
+import { sortDiagnostics } from './diagnostics.js';
+import { buildReferenceIndex, normalizeReferences, sanitizeReferenceField } from './references.js';
+import { inspectStoreEntry } from './store/health.js';
+function extractPurpose(content) {
+    const match = content.match(/^## Purpose\s*\n+([^\n#]+)/m);
+    return match?.[1]?.trim() ?? 'No purpose summary available.';
+}
+async function listBaselineSpecs(specsDir) {
+    try {
+        const entries = await fs.readdir(specsDir, { withFileTypes: true });
+        const specs = [];
+        for (const entry of entries) {
+            if (!entry.isDirectory()) {
+                continue;
+            }
+            const specPath = path.join(specsDir, entry.name, 'spec.md');
+            try {
+                const content = await fs.readFile(specPath, 'utf-8');
+                specs.push({ specId: entry.name, purpose: extractPurpose(content) });
+            }
+            catch {
+                // skip unreadable specs
+            }
+        }
+        return specs.sort((a, b) => a.specId.localeCompare(b.specId));
+    }
+    catch {
+        return [];
+    }
+}
+export async function buildReferencedStoreIndex(input) {
+    const normalized = normalizeReferences(input.references, input.rootStoreId);
+    const indexEntries = [];
+    const diagnostics = [];
+    for (const ref of normalized) {
+        const entry = input.registry.stores[ref.id];
+        if (!entry) {
+            diagnostics.push({
+                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`,
+            });
+            continue;
+        }
+        const storeDiagnostics = await inspectStoreEntry(ref.id, entry);
+        const blocking = storeDiagnostics.some((d) => d.severity === 'error');
+        if (blocking) {
+            diagnostics.push(...storeDiagnostics.filter((d) => d.severity === 'error'));
+            continue;
+        }
+        const specs = await listBaselineSpecs(path.join(entry.backend.local_path, 'specflow', 'specs'));
+        if (specs.length === 0) {
+            diagnostics.push({
+                severity: 'info',
+                code: 'reference_no_specs',
+                message: `Referenced store '${ref.id}' has no baseline specs to index.`,
+                target: `references.${ref.id}`,
+            });
+            continue;
+        }
+        for (const spec of specs) {
+            indexEntries.push({
+                storeId: ref.id,
+                specId: spec.specId,
+                purpose: sanitizeReferenceField(spec.purpose),
+                fetchCommand: `specflow show ${sanitizeReferenceField(spec.specId)} --type spec --store ${ref.id}`,
+            });
+        }
+    }
+    const index = buildReferenceIndex(indexEntries);
+    return {
+        rendered: index.rendered,
+        truncated: index.truncated,
+        diagnostics: sortDiagnostics([...diagnostics, ...index.diagnostics]),
+    };
+}

package/dist/core/references.d.ts

@@ -0,0 +1,17 @@
+import type { Diagnostic } from './diagnostics.js';
+import type { NormalizedReference } from './project-config.js';
+export declare const REFERENCE_INDEX_BUDGET_BYTES: number;
+export interface ReferenceEntry {
+    readonly storeId: string;
+    readonly specId: string;
+    readonly purpose: string;
+    readonly fetchCommand: string;
+}
+export interface ReferenceIndexResult {
+    readonly rendered: string;
+    readonly truncated: boolean;
+    readonly diagnostics: readonly Diagnostic[];
+}
+export declare function normalizeReferences(references: readonly NormalizedReference[], rootStoreId?: string): NormalizedReference[];
+export declare function sanitizeReferenceField(value: string, maxLength?: number): string;
+export declare function buildReferenceIndex(entries: readonly ReferenceEntry[]): ReferenceIndexResult;

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';