@gordon.gan/specflow 1.1.0 → 1.2.0-beta

package/dist/core/artifact-graph/types.d.ts

@@ -77,8 +77,8 @@ export declare const SchemaYamlSchema: z.ZodObject<{
         tracks?: string | null | undefined;
     }>>;
 }, "strip", z.ZodTypeAny, {
-    name: string;
     version: number;
+    name: string;
     artifacts: {
         id: string;
         generates: string;
@@ -93,8 +93,8 @@ export declare const SchemaYamlSchema: z.ZodObject<{
     } | undefined;
     description?: string | undefined;
 }, {
-    name: string;
     version: number;
+    name: string;
     artifacts: {
         id: string;
         generates: string;

package/dist/core/context-assembly.d.ts

@@ -0,0 +1,9 @@
+import type { Diagnostic } from './diagnostics.js';
+import type { ResolvedPlanningRoot } from './root-selection.js';
+import type { StoreRegistry } from './store/foundation.js';
+import { type WorkingSet } from './working-set.js';
+export interface AssembledContext {
+    readonly workingSet: WorkingSet;
+    readonly diagnostics: readonly Diagnostic[];
+}
+export declare function assembleContextFromRoot(resolved: ResolvedPlanningRoot, registry: StoreRegistry): Promise<AssembledContext>;

package/dist/core/context-assembly.js

@@ -0,0 +1,68 @@
+import { readFileSync } from 'node:fs';
+import yaml from 'js-yaml';
+import { sortDiagnostics } from './diagnostics.js';
+import { parseProjectConfig } from './project-config.js';
+import { normalizeReferences } from './references.js';
+import { inspectStoreEntry } from './store/health.js';
+import { assembleWorkingSet } from './working-set.js';
+export async function assembleContextFromRoot(resolved, registry) {
+    const configPath = `${resolved.root}/specflow/config.yaml`;
+    let parsedConfig;
+    try {
+        parsedConfig = parseProjectConfig(yaml.load(readFileSync(configPath, 'utf-8')));
+    }
+    catch {
+        parsedConfig = parseProjectConfig({});
+    }
+    const rootStoreId = resolved.storeId ?? resolved.root.split('/').pop() ?? 'root';
+    const references = normalizeReferences(parsedConfig.references, rootStoreId);
+    const diagnostics = [...resolved.diagnostics, ...parsedConfig.diagnostics];
+    const referenceMembers = await Promise.all(references.map(async (ref) => {
+        const entry = registry.stores[ref.id];
+        if (!entry) {
+            return {
+                storeId: ref.id,
+                healthy: false,
+                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`,
+                    },
+                ],
+            };
+        }
+        const storeDiagnostics = await inspectStoreEntry(ref.id, entry);
+        const unhealthy = storeDiagnostics.some((d) => d.severity === 'error');
+        if (unhealthy) {
+            return {
+                storeId: ref.id,
+                healthy: false,
+                diagnostics: [...storeDiagnostics],
+            };
+        }
+        return {
+            storeId: ref.id,
+            healthy: true,
+            path: entry.backend.local_path,
+            diagnostics: storeDiagnostics.filter((d) => d.severity !== 'error'),
+        };
+    }));
+    diagnostics.push(...referenceMembers.flatMap((member) => member.diagnostics));
+    const rootDiagnostics = resolved.storeId && registry.stores[resolved.storeId]
+        ? await inspectStoreEntry(resolved.storeId, registry.stores[resolved.storeId])
+        : [];
+    const rootHealthy = !rootDiagnostics.some((d) => d.severity === 'error');
+    diagnostics.push(...rootDiagnostics);
+    const workingSet = assembleWorkingSet({
+        root: {
+            storeId: rootStoreId,
+            path: resolved.root,
+            healthy: rootHealthy,
+        },
+        references: referenceMembers,
+    });
+    return { workingSet, diagnostics: sortDiagnostics(diagnostics) };
+}

package/dist/core/diagnostics.d.ts

@@ -0,0 +1,11 @@
+export type DiagnosticSeverity = 'error' | 'warning' | 'info';
+export interface Diagnostic {
+    readonly severity: DiagnosticSeverity;
+    readonly code: string;
+    readonly message: string;
+    readonly target?: string;
+    readonly fix?: string;
+}
+export declare function compareDiagnostics(a: Diagnostic, b: Diagnostic): number;
+export declare function sortDiagnostics(diagnostics: readonly Diagnostic[]): Diagnostic[];
+export declare function hasErrorDiagnostic(diagnostics: readonly Diagnostic[]): boolean;

package/dist/core/diagnostics.js

@@ -0,0 +1,18 @@
+const SEVERITY_RANK = {
+    error: 0,
+    warning: 1,
+    info: 2,
+};
+export function compareDiagnostics(a, b) {
+    const bySeverity = SEVERITY_RANK[a.severity] - SEVERITY_RANK[b.severity];
+    if (bySeverity !== 0) {
+        return bySeverity;
+    }
+    return a.code.localeCompare(b.code);
+}
+export function sortDiagnostics(diagnostics) {
+    return [...diagnostics].sort(compareDiagnostics);
+}
+export function hasErrorDiagnostic(diagnostics) {
+    return diagnostics.some((d) => d.severity === 'error');
+}

package/dist/core/file-state.d.ts

@@ -0,0 +1,23 @@
+import * as nodeFs from 'node:fs';
+export type FileLockErrorKind = 'create-failed' | 'timeout';
+export interface FileLockErrorInfo {
+    lockPath: string;
+    cause?: unknown;
+}
+export interface FileLockOptions {
+    lockPath: string;
+    errorFor: (kind: FileLockErrorKind, info: FileLockErrorInfo) => Error;
+}
+export interface LockErrorData {
+    createSubject: string;
+    busyMessage: string;
+    code: string;
+    target: string;
+}
+export declare function makeLockErrorFactory(data: LockErrorData): (kind: FileLockErrorKind, info: FileLockErrorInfo) => Error;
+export declare function isNodeErrorCode(error: unknown, code: string): boolean;
+export declare function pathIsFile(filePath: string): Promise<boolean>;
+export declare function pathIsDirectory(dirPath: string): Promise<boolean>;
+export declare function writeFileAtomically(filePath: string, content: string): Promise<void>;
+export declare function acquireFileLock(options: FileLockOptions): Promise<nodeFs.promises.FileHandle>;
+export declare function releaseFileLock(lock: nodeFs.promises.FileHandle, lockPath: string): Promise<void>;

package/dist/core/file-state.js

@@ -0,0 +1,101 @@
+import * as nodeFs from 'node:fs';
+import * as path from 'node:path';
+import { ensureDir } from '../utils/file-system.js';
+const fs = nodeFs.promises;
+export function makeLockErrorFactory(data) {
+    return (kind, info) => {
+        const diagnostic = {
+            severity: 'error',
+            code: data.code,
+            message: kind === 'timeout' ? data.busyMessage : `Cannot create ${data.createSubject}.`,
+            target: data.target,
+            fix: kind === 'timeout'
+                ? `Retry shortly; if this persists, delete the stale lock file ${info.lockPath}.`
+                : `Check permissions on ${path.dirname(info.lockPath)}.`,
+        };
+        const error = new Error(diagnostic.message);
+        error.diagnostics = [diagnostic];
+        if (kind === 'create-failed' && info.cause) {
+            error.cause = info.cause;
+        }
+        return error;
+    };
+}
+const STALE_LOCK_THRESHOLD_MS = 30_000;
+const LOCK_DEADLINE_MS = 5_000;
+const LOCK_POLL_MS = 25;
+export function isNodeErrorCode(error, code) {
+    return (typeof error === 'object' &&
+        error !== null &&
+        'code' in error &&
+        error.code === code);
+}
+export async function pathIsFile(filePath) {
+    try {
+        return (await fs.stat(filePath)).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+export async function pathIsDirectory(dirPath) {
+    try {
+        return (await fs.stat(dirPath)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+async function sleep(milliseconds) {
+    await new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
+export async function writeFileAtomically(filePath, content) {
+    const dirPath = path.dirname(filePath);
+    await ensureDir(dirPath);
+    const tempPath = path.join(dirPath, `.${path.basename(filePath)}.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2)}.tmp`);
+    try {
+        await fs.writeFile(tempPath, content, 'utf-8');
+        await fs.rename(tempPath, filePath);
+    }
+    catch (error) {
+        await fs.rm(tempPath, { force: true }).catch(() => undefined);
+        throw error;
+    }
+}
+export async function acquireFileLock(options) {
+    const { lockPath, errorFor } = options;
+    const lockDir = path.dirname(lockPath);
+    await ensureDir(lockDir);
+    const deadline = Date.now() + LOCK_DEADLINE_MS;
+    while (true) {
+        try {
+            return await fs.open(lockPath, 'wx');
+        }
+        catch (error) {
+            if (!isNodeErrorCode(error, 'EEXIST')) {
+                throw errorFor('create-failed', { lockPath, cause: error });
+            }
+            let staleStolen = false;
+            try {
+                const lockStat = await fs.stat(lockPath);
+                if (Date.now() - lockStat.mtimeMs > STALE_LOCK_THRESHOLD_MS) {
+                    await fs.rm(lockPath, { force: true });
+                    staleStolen = true;
+                }
+            }
+            catch {
+                // Holder released between open and stat — retry within deadline.
+            }
+            if (!staleStolen) {
+                if (Date.now() >= deadline) {
+                    throw errorFor('timeout', { lockPath });
+                }
+                await sleep(LOCK_POLL_MS);
+            }
+        }
+    }
+}
+export async function releaseFileLock(lock, lockPath) {
+    await lock.close().catch(() => undefined);
+    await fs.rm(lockPath, { force: true }).catch(() => undefined);
+}

package/dist/core/global-config.d.ts

@@ -0,0 +1,26 @@
+export declare const GLOBAL_CONFIG_DIR_NAME = "specflow";
+export declare const GLOBAL_CONFIG_FILE_NAME = "config.json";
+export declare const GLOBAL_DATA_DIR_NAME = "specflow";
+export interface GlobalConfig {
+    defaultStore?: string;
+}
+export interface GlobalConfigDirOptions {
+    env?: NodeJS.ProcessEnv;
+    platform?: NodeJS.Platform;
+    homedir?: string;
+}
+export interface GlobalDataDirOptions {
+    env?: NodeJS.ProcessEnv;
+    platform?: NodeJS.Platform;
+    homedir?: string;
+}
+export interface GlobalConfigLoadOptions {
+    configPath?: string;
+}
+export declare function getGlobalConfigDir(options?: GlobalConfigDirOptions): string;
+export declare function getGlobalDataDir(options?: GlobalDataDirOptions): string;
+export declare function getGlobalConfigPath(options?: GlobalConfigDirOptions): string;
+export declare function getGlobalConfig(options?: GlobalConfigLoadOptions & GlobalConfigDirOptions): GlobalConfig;
+export declare function saveGlobalConfig(config: GlobalConfig, options?: GlobalConfigDirOptions): void;
+export declare function getStoreRegistryPath(dataDir?: string, options?: GlobalDataDirOptions): string;
+export declare function getWorksetsStatePath(dataDir?: string, options?: GlobalDataDirOptions): string;

package/dist/core/global-config.js

@@ -0,0 +1,77 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+export const GLOBAL_CONFIG_DIR_NAME = 'specflow';
+export const GLOBAL_CONFIG_FILE_NAME = 'config.json';
+export const GLOBAL_DATA_DIR_NAME = 'specflow';
+const DEFAULT_CONFIG = {};
+function joinGlobalDataPath(platform, ...segments) {
+    return platform === 'win32' ? path.win32.join(...segments) : path.posix.join(...segments);
+}
+export function getGlobalConfigDir(options = {}) {
+    const env = options.env ?? process.env;
+    const platform = options.platform ?? os.platform();
+    const homedir = options.homedir ?? os.homedir();
+    const xdgConfigHome = env.XDG_CONFIG_HOME;
+    if (xdgConfigHome) {
+        return joinGlobalDataPath(platform, xdgConfigHome, GLOBAL_CONFIG_DIR_NAME);
+    }
+    if (platform === 'win32') {
+        const appData = env.APPDATA;
+        if (appData) {
+            return joinGlobalDataPath(platform, appData, GLOBAL_CONFIG_DIR_NAME);
+        }
+        return joinGlobalDataPath(platform, homedir, 'AppData', 'Roaming', GLOBAL_CONFIG_DIR_NAME);
+    }
+    return joinGlobalDataPath(platform, homedir, '.config', GLOBAL_CONFIG_DIR_NAME);
+}
+export function getGlobalDataDir(options = {}) {
+    const env = options.env ?? process.env;
+    const platform = options.platform ?? os.platform();
+    const homedir = options.homedir ?? os.homedir();
+    const xdgDataHome = env.XDG_DATA_HOME;
+    if (xdgDataHome) {
+        return joinGlobalDataPath(platform, xdgDataHome, GLOBAL_DATA_DIR_NAME);
+    }
+    if (platform === 'win32') {
+        const localAppData = env.LOCALAPPDATA;
+        if (localAppData) {
+            return joinGlobalDataPath(platform, localAppData, GLOBAL_DATA_DIR_NAME);
+        }
+        return joinGlobalDataPath(platform, homedir, 'AppData', 'Local', GLOBAL_DATA_DIR_NAME);
+    }
+    return joinGlobalDataPath(platform, homedir, '.local', 'share', GLOBAL_DATA_DIR_NAME);
+}
+export function getGlobalConfigPath(options = {}) {
+    return path.join(getGlobalConfigDir(options), GLOBAL_CONFIG_FILE_NAME);
+}
+export function getGlobalConfig(options = {}) {
+    const configPath = options.configPath ?? getGlobalConfigPath(options);
+    try {
+        if (!fs.existsSync(configPath)) {
+            return { ...DEFAULT_CONFIG };
+        }
+        const content = fs.readFileSync(configPath, 'utf-8');
+        const parsed = JSON.parse(content);
+        return { ...DEFAULT_CONFIG, ...parsed };
+    }
+    catch {
+        return { ...DEFAULT_CONFIG };
+    }
+}
+export function saveGlobalConfig(config, options = {}) {
+    const configDir = getGlobalConfigDir(options);
+    const configPath = path.join(configDir, GLOBAL_CONFIG_FILE_NAME);
+    if (!fs.existsSync(configDir)) {
+        fs.mkdirSync(configDir, { recursive: true });
+    }
+    fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n', 'utf-8');
+}
+export function getStoreRegistryPath(dataDir, options = {}) {
+    const base = dataDir ?? getGlobalDataDir(options);
+    return path.join(base, 'stores', 'registry.yaml');
+}
+export function getWorksetsStatePath(dataDir, options = {}) {
+    const base = dataDir ?? getGlobalDataDir(options);
+    return path.join(base, 'worksets', 'worksets.yaml');
+}

package/dist/core/opener-launch.d.ts

@@ -0,0 +1,3 @@
+import type { OpenerDefinition } from './openers.js';
+export declare function isOpenerAvailable(opener: OpenerDefinition): boolean;
+export declare function launchOpener(opener: OpenerDefinition, workspacePath: string, primaryPath: string): void;

package/dist/core/opener-launch.js

@@ -0,0 +1,20 @@
+import { spawnSync } from 'node:child_process';
+export function isOpenerAvailable(opener) {
+    const result = spawnSync(process.platform === 'win32' ? 'where' : 'which', [opener.command], {
+        stdio: 'ignore',
+    });
+    return result.status === 0;
+}
+export function launchOpener(opener, workspacePath, primaryPath) {
+    const child = spawnSync(opener.command, [workspacePath], {
+        cwd: primaryPath,
+        shell: false,
+        stdio: 'inherit',
+    });
+    if (child.error) {
+        throw child.error;
+    }
+    if (child.status !== 0 && child.status !== null) {
+        throw new Error(`${opener.command} exited with status ${child.status}.`);
+    }
+}

package/dist/core/openers.d.ts

@@ -0,0 +1,23 @@
+export type OpenerStyle = 'workspace-file';
+export interface OpenerDefinition {
+    readonly id: string;
+    readonly label: string;
+    readonly style: OpenerStyle;
+    readonly command: string;
+}
+export declare const BUILTIN_OPENERS: readonly OpenerDefinition[];
+export declare function findOpener(table: readonly OpenerDefinition[], id: string): OpenerDefinition | null;
+export interface WorksetMemberInput {
+    readonly name: string;
+    readonly path: string;
+}
+export interface LaunchCommand {
+    readonly executable: string;
+    readonly args: string[];
+    readonly cwd: string;
+}
+export declare function buildLaunchCommand(opener: OpenerDefinition, input: {
+    members: WorksetMemberInput[];
+    codeWorkspacePath: string;
+}): LaunchCommand;
+export declare function isCliAgentOpener(id: string): boolean;

package/dist/core/openers.js

@@ -0,0 +1,20 @@
+export const BUILTIN_OPENERS = [
+    { id: 'cursor', label: 'Cursor', style: 'workspace-file', command: 'cursor' },
+    { id: 'code', label: 'VS Code', style: 'workspace-file', command: 'code' },
+];
+export function findOpener(table, id) {
+    return table.find((opener) => opener.id === id) ?? null;
+}
+export function buildLaunchCommand(opener, input) {
+    if (input.members.length === 0) {
+        throw new Error('buildLaunchCommand requires at least one member.');
+    }
+    return {
+        executable: opener.command,
+        args: [input.codeWorkspacePath],
+        cwd: input.members[0].path,
+    };
+}
+export function isCliAgentOpener(id) {
+    return id === 'claude' || id === 'codex';
+}

package/dist/core/project-config.d.ts

@@ -0,0 +1,14 @@
+import type { Diagnostic } from './diagnostics.js';
+export interface NormalizedReference {
+    readonly id: string;
+    readonly remote?: string;
+}
+export interface ParsedProjectConfig {
+    readonly schema: string;
+    readonly context?: string;
+    readonly store?: string;
+    readonly references: readonly NormalizedReference[];
+    readonly diagnostics: readonly Diagnostic[];
+}
+export declare function parseProjectConfig(raw: unknown): ParsedProjectConfig;
+export declare function loadProjectConfigFromObject(raw: unknown): ParsedProjectConfig;

package/dist/core/project-config.js

@@ -0,0 +1,73 @@
+import { z } from 'zod';
+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 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, 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;