110 lines
3.2 KiB
TypeScript
110 lines
3.2 KiB
TypeScript
/**
|
|
* Agent Forum v4 - Translator Agent
|
|
*
|
|
* Role: Maintain code-to-documentation parity.
|
|
* Inputs: SCIP diffs, existing docs
|
|
* Outputs: API references, guides (updates to docs in the repo)
|
|
*/
|
|
|
|
import { parseArgs } from "https://deno.land/std@0.224.0/cli/parse_args.ts";
|
|
import { join } from "https://deno.land/std@0.224.0/path/mod.ts";
|
|
import { existsSync } from "https://deno.land/std@0.224.0/fs/exists.ts";
|
|
import { writeNote } from "../core/git_storage.ts";
|
|
import { getDiff } from "../core/git_inspector.ts";
|
|
import type { TranslatorUpdates } from "../core/types.ts";
|
|
|
|
import * as scip from "npm:@sourcegraph/scip-typescript@0.3.3/dist/src/scip.js";
|
|
|
|
const CWD = Deno.cwd();
|
|
|
|
export async function updateDocumentation() {
|
|
console.log(
|
|
"-> Translator Agent: Analyzing code diffs for documentation drift...",
|
|
);
|
|
|
|
// 1. In a real scenario, read SCIP diffs or Merkle diffs to see changed interfaces
|
|
const diffs = await getDiff("HEAD~1", "HEAD");
|
|
const changedFiles = diffs.map((d) => d.filepath);
|
|
|
|
console.log(` Detected changes in ${changedFiles.length} files.`);
|
|
|
|
const proposedUpdates: { file: string; section: string; content: string }[] =
|
|
[];
|
|
|
|
let scipIndex: any = null;
|
|
const scipPath = join(CWD, "index.scip");
|
|
if (!existsSync(scipPath)) {
|
|
console.warn(" ⚠️ index.scip not found. Failing gracefully.");
|
|
} else {
|
|
try {
|
|
const buffer = Deno.readFileSync(scipPath);
|
|
scipIndex = scip.scip.Index.deserializeBinary(buffer);
|
|
console.log(
|
|
` Successfully loaded SCIP index with ${scipIndex.documents.length} documents.`,
|
|
);
|
|
} catch (e) {
|
|
console.warn(" ⚠️ Failed to deserialize index.scip:", e);
|
|
}
|
|
}
|
|
|
|
if (scipIndex) {
|
|
for (const file of changedFiles) {
|
|
const doc = scipIndex.documents.find((d: any) =>
|
|
d.relative_path === file
|
|
);
|
|
if (doc) {
|
|
if (doc.occurrences && doc.occurrences.length > 0) {
|
|
proposedUpdates.push({
|
|
file: `docs/drift/${file}.md`,
|
|
section:
|
|
`Document structural changes detected in SCIP index for ${file}`,
|
|
content: scipPath,
|
|
});
|
|
}
|
|
}
|
|
}
|
|
}
|
|
|
|
// 2. Generate Doc Updates
|
|
const docUpdates = {
|
|
agent: "Translator",
|
|
timestamp: Date.now(),
|
|
proposedDocAdditions: proposedUpdates.length > 0 ? proposedUpdates : [
|
|
{
|
|
file: "none",
|
|
section:
|
|
"No structural AST drift detected requiring documentation updates.",
|
|
content: "none",
|
|
},
|
|
],
|
|
};
|
|
|
|
console.log("-> Translator Agent: Documentation updates proposed.");
|
|
|
|
// Write the proposed doc updates to Git Notes (or in a real scenario, write directly to doc files)
|
|
try {
|
|
await writeNote<TranslatorUpdates>("translator_updates", docUpdates);
|
|
console.log(
|
|
"-> Doc proposals written to Git Notes (refs/notes/translator_updates).",
|
|
);
|
|
} catch (e) {
|
|
throw new Error("Failed to write translator updates to Git Notes: " + e);
|
|
}
|
|
}
|
|
|
|
export async function main(args: string[] = Deno.args) {
|
|
const parsed = parseArgs(args, {
|
|
boolean: ["run"],
|
|
});
|
|
|
|
if (parsed["run"]) {
|
|
await updateDocumentation();
|
|
} else {
|
|
console.log("Translator Agent installed. Run with --run flag.");
|
|
}
|
|
}
|
|
|
|
if (import.meta.main) {
|
|
await main(Deno.args);
|
|
}
|