import { promises as fs } from 'fs';
import path from 'path';
import { z } from 'zod';
import {
CODEBASE_CONTEXT_DIRNAME,
INDEX_FORMAT_VERSION,
INDEX_META_FILENAME,
INDEX_META_VERSION,
INTELLIGENCE_FILENAME,
KEYWORD_INDEX_FILENAME,
RELATIONSHIPS_FILENAME,
VECTOR_DB_DIRNAME
} from '../constants/codebase-context.js';
import { IndexCorruptedError } from '../errors/index.js';
const ArtifactHeaderSchema = z.object({
buildId: z.string().min(1),
formatVersion: z.number().int().nonnegative()
});
const KeywordIndexFileSchema = z.object({
header: ArtifactHeaderSchema,
chunks: z.array(z.unknown())
});
const VectorDbBuildSchema = z.object({
buildId: z.string().min(1),
formatVersion: z.number().int().nonnegative()
});
const IntelligenceFileSchema = z
.object({
header: ArtifactHeaderSchema
})
.passthrough();
const RelationshipsFileSchema = z
.object({
header: ArtifactHeaderSchema
})
.passthrough();
export const IndexMetaSchema = z.object({
metaVersion: z.number().int().positive(),
formatVersion: z.number().int().nonnegative(),
buildId: z.string().min(1),
generatedAt: z.string().datetime(),
toolVersion: z.string().min(1),
artifacts: z
.object({
keywordIndex: z.object({
path: z.string().min(1)
}),
vectorDb: z.object({
path: z.string().min(1),
provider: z.string().min(1)
}),
intelligence: z
.object({
path: z.string().min(1)
})
.optional()
})
.passthrough()
});
export type IndexMeta = z.infer<typeof IndexMetaSchema>;
async function pathExists(targetPath: string): Promise<boolean> {
try {
await fs.access(targetPath);
return true;
} catch {
return false;
}
}
async function requireFile(targetPath: string, label: string): Promise<void> {
if (!(await pathExists(targetPath))) {
throw new IndexCorruptedError(`${label} missing: ${targetPath}`);
}
}
async function requireDirectory(targetPath: string, label: string): Promise<void> {
try {
const stat = await fs.stat(targetPath);
if (!stat.isDirectory()) {
throw new IndexCorruptedError(`${label} is not a directory: ${targetPath}`);
}
} catch (error) {
if (error instanceof IndexCorruptedError) throw error;
throw new IndexCorruptedError(`${label} missing: ${targetPath}`);
}
}
function asIndexCorrupted(message: string, error: unknown): IndexCorruptedError {
const suffix = error instanceof Error ? error.message : String(error);
return new IndexCorruptedError(`${message}: ${suffix}`);
}
export async function readIndexMeta(rootDir: string): Promise<IndexMeta> {
const metaPath = path.join(rootDir, CODEBASE_CONTEXT_DIRNAME, INDEX_META_FILENAME);
let parsed: unknown;
try {
const raw = await fs.readFile(metaPath, 'utf-8');
parsed = JSON.parse(raw);
} catch (error) {
throw asIndexCorrupted('Index meta missing or unreadable (rebuild required)', error);
}
const result = IndexMetaSchema.safeParse(parsed);
if (!result.success) {
throw new IndexCorruptedError(
`Index meta schema mismatch (rebuild required): ${result.error.message}`
);
}
const meta = result.data;
if (meta.metaVersion !== INDEX_META_VERSION) {
throw new IndexCorruptedError(
`Index meta version mismatch (rebuild required): expected metaVersion=${INDEX_META_VERSION}, found metaVersion=${meta.metaVersion}`
);
}
if (meta.formatVersion !== INDEX_FORMAT_VERSION) {
throw new IndexCorruptedError(
`Index format version mismatch (rebuild required): expected formatVersion=${INDEX_FORMAT_VERSION}, found formatVersion=${meta.formatVersion}`
);
}
return meta;
}
export async function validateIndexArtifacts(rootDir: string, meta: IndexMeta): Promise<void> {
const contextDir = path.join(rootDir, CODEBASE_CONTEXT_DIRNAME);
const keywordPath = path.join(contextDir, KEYWORD_INDEX_FILENAME);
const vectorDir = path.join(contextDir, VECTOR_DB_DIRNAME);
const vectorBuildPath = path.join(vectorDir, 'index-build.json');
await requireFile(keywordPath, 'Keyword index');
await requireDirectory(vectorDir, 'Vector DB directory');
await requireFile(vectorBuildPath, 'Vector DB build marker');
// Keyword index header (required)
try {
const raw = await fs.readFile(keywordPath, 'utf-8');
const json = JSON.parse(raw);
const parsed = KeywordIndexFileSchema.safeParse(json);
if (!parsed.success) {
throw new IndexCorruptedError(
`Keyword index schema mismatch (rebuild required): ${parsed.error.message}`
);
}
const { buildId, formatVersion } = parsed.data.header;
if (formatVersion !== meta.formatVersion) {
throw new IndexCorruptedError(
`Keyword index formatVersion mismatch (rebuild required): meta=${meta.formatVersion}, index.json=${formatVersion}`
);
}
if (buildId !== meta.buildId) {
throw new IndexCorruptedError(
`Keyword index buildId mismatch (rebuild required): meta=${meta.buildId}, index.json=${buildId}`
);
}
} catch (error) {
if (error instanceof IndexCorruptedError) throw error;
throw asIndexCorrupted('Keyword index corrupted (rebuild required)', error);
}
// Vector DB build marker (required)
try {
const raw = await fs.readFile(vectorBuildPath, 'utf-8');
const json = JSON.parse(raw);
const parsed = VectorDbBuildSchema.safeParse(json);
if (!parsed.success) {
throw new IndexCorruptedError(
`Vector DB build marker schema mismatch (rebuild required): ${parsed.error.message}`
);
}
const { buildId, formatVersion } = parsed.data;
if (formatVersion !== meta.formatVersion) {
throw new IndexCorruptedError(
`Vector DB formatVersion mismatch (rebuild required): meta=${meta.formatVersion}, index-build.json=${formatVersion}`
);
}
if (buildId !== meta.buildId) {
throw new IndexCorruptedError(
`Vector DB buildId mismatch (rebuild required): meta=${meta.buildId}, index-build.json=${buildId}`
);
}
} catch (error) {
if (error instanceof IndexCorruptedError) throw error;
throw asIndexCorrupted('Vector DB build marker corrupted (rebuild required)', error);
}
// Optional intelligence artifact: validate if present, but do not require.
const intelligencePath = path.join(contextDir, INTELLIGENCE_FILENAME);
if (await pathExists(intelligencePath)) {
try {
const raw = await fs.readFile(intelligencePath, 'utf-8');
const json = JSON.parse(raw);
const parsed = IntelligenceFileSchema.safeParse(json);
if (!parsed.success) {
throw new IndexCorruptedError(
`Intelligence schema mismatch (rebuild required): ${parsed.error.message}`
);
}
const { buildId, formatVersion } = parsed.data.header;
if (formatVersion !== meta.formatVersion) {
throw new IndexCorruptedError(
`Intelligence formatVersion mismatch (rebuild required): meta=${meta.formatVersion}, intelligence.json=${formatVersion}`
);
}
if (buildId !== meta.buildId) {
throw new IndexCorruptedError(
`Intelligence buildId mismatch (rebuild required): meta=${meta.buildId}, intelligence.json=${buildId}`
);
}
} catch (error) {
if (error instanceof IndexCorruptedError) throw error;
throw asIndexCorrupted('Intelligence corrupted (rebuild required)', error);
}
}
// Optional relationships sidecar: validate if present, but do not require.
const relationshipsPath = path.join(contextDir, RELATIONSHIPS_FILENAME);
if (await pathExists(relationshipsPath)) {
try {
const raw = await fs.readFile(relationshipsPath, 'utf-8');
const json = JSON.parse(raw);
const parsed = RelationshipsFileSchema.safeParse(json);
if (!parsed.success) {
throw new IndexCorruptedError(
`Relationships schema mismatch (rebuild required): ${parsed.error.message}`
);
}
const { buildId, formatVersion } = parsed.data.header;
if (formatVersion !== meta.formatVersion) {
throw new IndexCorruptedError(
`Relationships formatVersion mismatch (rebuild required): meta=${meta.formatVersion}, relationships.json=${formatVersion}`
);
}
if (buildId !== meta.buildId) {
throw new IndexCorruptedError(
`Relationships buildId mismatch (rebuild required): meta=${meta.buildId}, relationships.json=${buildId}`
);
}
} catch (error) {
if (error instanceof IndexCorruptedError) throw error;
throw asIndexCorrupted('Relationships sidecar corrupted (rebuild required)', error);
}
}
}
