fix(ms-ai-architect): RX-OPS2 skrive-sikkerhet i driverne — scoped restore + atomiske skriv [skip-docs]
- backup.mjs restore(relPaths): SCOPED per-fil-rollback erstatter hel-tre rmSync(srcDir)+cpSync. Ruller kun tilbake kjøringens egne skriv; parallelle økters skriv til søsken-filer overlever; intet destruktivt rm→cp-vindu. Nyskapte filer slettes; prior bytes gjenopprettes atomisk. - migrate-corpus.mjs: returnert restore() er nå en null-arg closure bundet til kjøringens skrive- liste (public API uendret) → scoped. detectStaleRollback aborterer ved forrige krasj-sentinel; cleanupOldBackups pruner backups forbi retention etter vellykket batch. - 5 drivere (backfill-status/-category, dedup-plain-header, relabel-dato/-dialect): writeFileSync → atomicWriteSync (crash-safe tmp+rename) + recovery-kontrakt i header. - backfill-category.mjs: refaktorert importerbar (isMain-guard + run()/planCategoryBackfill/ categoryForFile/FOLDER_CATEGORY-eksporter, parameterisert root) → testbar uten scan-side-effekt. - Tester (+16): 6 scoped-restore (parallel-preservering, ny-fil-sletting, throws-guard) erstatter 2 hel-tre; test-backfill-category (frosset taxonomi + hermetisk plan); test-driver-atomic-writes (5 drivere); migrate stale-abort + cleanup-wiring. Suite 859→875 exit 0. validate-plugin 250/0.
This commit is contained in:
parent
b68514487c
commit
b3011da017
11 changed files with 406 additions and 100 deletions
|
|
@ -8,19 +8,26 @@
|
|||
// change by more than that single line, the run aborts and writes nothing. Idempotent:
|
||||
// files that already carry **Category:**/**Kategori:** are skipped, so a re-run is a no-op.
|
||||
//
|
||||
// The planning is factored into pure/importable pieces (categoryForFile + planCategoryBackfill)
|
||||
// behind an isMain guard, so the frozen taxonomy and the plan can be tested without executing
|
||||
// the corpus scan as an import side effect.
|
||||
//
|
||||
// Recovery contract: writes are crash-safe (atomicWriteSync tmp+rename — a reader sees the old
|
||||
// file or the new one, never a partial); an interrupted run is recovered by re-running (idempotent).
|
||||
//
|
||||
// Usage: node scripts/kb-update/backfill-category.mjs [--dry]
|
||||
import { readFileSync, writeFileSync } from 'node:fs';
|
||||
import { readFileSync, realpathSync } from 'node:fs';
|
||||
import { execSync } from 'node:child_process';
|
||||
import { join, dirname } from 'node:path';
|
||||
import { fileURLToPath } from 'node:url';
|
||||
import { insertMetaField } from './lib/transform.mjs';
|
||||
import { atomicWriteSync } from './lib/atomic-write.mjs';
|
||||
|
||||
const __dirname = dirname(fileURLToPath(import.meta.url));
|
||||
const PLUGIN_ROOT = join(__dirname, '..', '..');
|
||||
const dry = process.argv.includes('--dry');
|
||||
|
||||
// Immediate-parent-directory basename → Category. Operator-approved 2026-07-06.
|
||||
const FOLDER_CATEGORY = {
|
||||
// Immediate-parent-directory basename → Category. Operator-approved 2026-07-06 (frozen).
|
||||
export const FOLDER_CATEGORY = {
|
||||
architecture: 'Solution Architecture & Advisory',
|
||||
platforms: 'Microsoft AI Platforms',
|
||||
development: 'Microsoft AI Platforms',
|
||||
|
|
@ -30,53 +37,88 @@ const FOLDER_CATEGORY = {
|
|||
|
||||
const RE_CAT = /^\s*\*\*(Category|Kategori):\*\*/im;
|
||||
|
||||
const files = execSync("find skills/*/references -name '*.md'", { cwd: PLUGIN_ROOT, encoding: 'utf8' })
|
||||
.trim()
|
||||
.split('\n');
|
||||
|
||||
const targets = files.filter((rel) => !RE_CAT.test(readFileSync(join(PLUGIN_ROOT, rel), 'utf8')));
|
||||
|
||||
const planned = [];
|
||||
const unmatched = [];
|
||||
for (const rel of targets) {
|
||||
const folder = rel.split('/').slice(-2, -1)[0];
|
||||
const cat = FOLDER_CATEGORY[folder];
|
||||
if (!cat) {
|
||||
unmatched.push(`${rel} (folder=${folder})`);
|
||||
continue;
|
||||
}
|
||||
const old = readFileSync(join(PLUGIN_ROOT, rel), 'utf8');
|
||||
const out = insertMetaField(old, 'Category', cat);
|
||||
// Hard invariant: exactly one line inserted (the Category line), body byte-identical.
|
||||
const o = old.split('\n');
|
||||
const n = out.split('\n');
|
||||
if (n.length !== o.length + 1) throw new Error(`ABORT ${rel}: not exactly one line inserted`);
|
||||
let d = 0;
|
||||
while (d < o.length && o[d] === n[d]) d++;
|
||||
if (n[d] !== `**Category:** ${cat}`) {
|
||||
throw new Error(`ABORT ${rel}: inserted line mismatch → ${JSON.stringify(n[d])}`);
|
||||
}
|
||||
if (o.slice(d).join('\n') !== n.slice(d + 1).join('\n')) {
|
||||
throw new Error(`ABORT ${rel}: body not byte-identical below the insertion`);
|
||||
}
|
||||
planned.push({ rel, cat, out });
|
||||
/**
|
||||
* The Category for a reference file, keyed on its immediate-parent folder. Pure.
|
||||
* @param {string} rel — plugin-relative path
|
||||
* @returns {string|null} the approved Category, or null when the folder is outside the rule
|
||||
*/
|
||||
export function categoryForFile(rel) {
|
||||
const folder = String(rel ?? '').split('/').slice(-2, -1)[0];
|
||||
return FOLDER_CATEGORY[folder] ?? null;
|
||||
}
|
||||
|
||||
if (unmatched.length) {
|
||||
console.error(`ABORT — ${unmatched.length} target(s) outside the approved folder rule:`);
|
||||
unmatched.forEach((u) => console.error(' ' + u));
|
||||
process.exit(1);
|
||||
/**
|
||||
* Plan the Category backfill under `root` (reads files; performs NO writes). Discovers every
|
||||
* reference file, keeps only those missing a Category, and for each in an approved folder builds
|
||||
* the insert-only mutation behind the one-line/byte-identical invariant. Files outside the
|
||||
* approved folder rule are collected as `unmatched` (never planned for a write).
|
||||
* @param {string} root — corpus root (contains skills/…)
|
||||
* @returns {{files: string[], targets: string[], planned: {rel:string,cat:string,out:string}[], unmatched: string[]}}
|
||||
*/
|
||||
export function planCategoryBackfill(root) {
|
||||
const files = execSync("find skills/*/references -name '*.md'", { cwd: root, encoding: 'utf8' })
|
||||
.trim()
|
||||
.split('\n')
|
||||
.filter(Boolean);
|
||||
|
||||
const targets = files.filter((rel) => !RE_CAT.test(readFileSync(join(root, rel), 'utf8')));
|
||||
|
||||
const planned = [];
|
||||
const unmatched = [];
|
||||
for (const rel of targets) {
|
||||
const cat = categoryForFile(rel);
|
||||
if (!cat) {
|
||||
const folder = String(rel).split('/').slice(-2, -1)[0];
|
||||
unmatched.push(`${rel} (folder=${folder})`);
|
||||
continue;
|
||||
}
|
||||
const old = readFileSync(join(root, rel), 'utf8');
|
||||
const out = insertMetaField(old, 'Category', cat);
|
||||
// Hard invariant: exactly one line inserted (the Category line), body byte-identical.
|
||||
const o = old.split('\n');
|
||||
const n = out.split('\n');
|
||||
if (n.length !== o.length + 1) throw new Error(`ABORT ${rel}: not exactly one line inserted`);
|
||||
let d = 0;
|
||||
while (d < o.length && o[d] === n[d]) d++;
|
||||
if (n[d] !== `**Category:** ${cat}`) {
|
||||
throw new Error(`ABORT ${rel}: inserted line mismatch → ${JSON.stringify(n[d])}`);
|
||||
}
|
||||
if (o.slice(d).join('\n') !== n.slice(d + 1).join('\n')) {
|
||||
throw new Error(`ABORT ${rel}: body not byte-identical below the insertion`);
|
||||
}
|
||||
planned.push({ rel, cat, out });
|
||||
}
|
||||
return { files, targets, planned, unmatched };
|
||||
}
|
||||
|
||||
const byCat = {};
|
||||
for (const p of planned) byCat[p.cat] = (byCat[p.cat] || 0) + 1;
|
||||
console.log(`Reference files: ${files.length} | without a category: ${targets.length} | planned: ${planned.length}`);
|
||||
console.log('By category:');
|
||||
for (const [c, n] of Object.entries(byCat).sort()) console.log(` ${n} ${c}`);
|
||||
function run({ root = PLUGIN_ROOT, dry }) {
|
||||
const { files, targets, planned, unmatched } = planCategoryBackfill(root);
|
||||
|
||||
if (dry) {
|
||||
console.log('\n(dry run — no writes)');
|
||||
process.exit(0);
|
||||
if (unmatched.length) {
|
||||
console.error(`ABORT — ${unmatched.length} target(s) outside the approved folder rule:`);
|
||||
unmatched.forEach((u) => console.error(' ' + u));
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
const byCat = {};
|
||||
for (const p of planned) byCat[p.cat] = (byCat[p.cat] || 0) + 1;
|
||||
console.log(`Reference files: ${files.length} | without a category: ${targets.length} | planned: ${planned.length}`);
|
||||
console.log('By category:');
|
||||
for (const [c, n] of Object.entries(byCat).sort()) console.log(` ${n} ${c}`);
|
||||
|
||||
if (dry) {
|
||||
console.log('\n(dry run — no writes)');
|
||||
return;
|
||||
}
|
||||
for (const p of planned) atomicWriteSync(join(root, p.rel), p.out);
|
||||
console.log(`\nWrote ${planned.length} files.`);
|
||||
}
|
||||
for (const p of planned) writeFileSync(join(PLUGIN_ROOT, p.rel), p.out);
|
||||
console.log(`\nWrote ${planned.length} files.`);
|
||||
|
||||
const isMain = (() => {
|
||||
try {
|
||||
return realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url));
|
||||
} catch {
|
||||
return false;
|
||||
}
|
||||
})();
|
||||
if (isMain) run({ dry: process.argv.includes('--dry') });
|
||||
|
|
|
|||
|
|
@ -22,11 +22,15 @@
|
|||
// **Status:** in its header window is skipped, so a re-run — including the 14 R21 files already
|
||||
// applied — is a no-op. Aborts and writes nothing on any drift or invariant breach.
|
||||
//
|
||||
// Recovery contract: writes are crash-safe (atomicWriteSync tmp+rename — a reader sees the old
|
||||
// file or the new one, never a partial); an interrupted run is recovered by re-running (idempotent).
|
||||
//
|
||||
// Usage: node scripts/kb-update/backfill-status.mjs [--dry]
|
||||
import { readFileSync, writeFileSync, existsSync, realpathSync } from 'node:fs';
|
||||
import { readFileSync, existsSync, realpathSync } from 'node:fs';
|
||||
import { join, dirname, basename } from 'node:path';
|
||||
import { fileURLToPath } from 'node:url';
|
||||
import { insertMetaField } from './lib/transform.mjs';
|
||||
import { atomicWriteSync } from './lib/atomic-write.mjs';
|
||||
|
||||
const __dirname = dirname(fileURLToPath(import.meta.url));
|
||||
const PLUGIN_ROOT = join(__dirname, '..', '..');
|
||||
|
|
@ -143,7 +147,7 @@ function run({ dry }) {
|
|||
for (const p of planned) console.log(` + ${p.rel} → **Status:** ${p.status}`);
|
||||
return;
|
||||
}
|
||||
for (const p of planned) writeFileSync(join(PLUGIN_ROOT, p.rel), p.out);
|
||||
for (const p of planned) atomicWriteSync(join(PLUGIN_ROOT, p.rel), p.out);
|
||||
console.log(`\nWrote ${planned.length} files.`);
|
||||
}
|
||||
|
||||
|
|
|
|||
|
|
@ -21,11 +21,15 @@
|
|||
//
|
||||
// Closes the last 4 of the corpus's Missing-Status and all 4 Missing-English-Last-updated.
|
||||
//
|
||||
// Recovery contract: writes are crash-safe (atomicWriteSync tmp+rename — a reader sees the old
|
||||
// file or the new one, never a partial); an interrupted run is recovered by re-running (idempotent).
|
||||
//
|
||||
// Usage: node scripts/kb-update/dedup-plain-header.mjs [--dry]
|
||||
import { readFileSync, writeFileSync, existsSync, realpathSync } from 'node:fs';
|
||||
import { readFileSync, existsSync, realpathSync } from 'node:fs';
|
||||
import { join, dirname } from 'node:path';
|
||||
import { fileURLToPath } from 'node:url';
|
||||
import { boldifyPlainField, dropRedundantPlainField } from './lib/transform.mjs';
|
||||
import { atomicWriteSync } from './lib/atomic-write.mjs';
|
||||
|
||||
const __dirname = dirname(fileURLToPath(import.meta.url));
|
||||
const PLUGIN_ROOT = join(__dirname, '..', '..');
|
||||
|
|
@ -125,7 +129,7 @@ function run({ dry }) {
|
|||
for (const p of planned) console.log(` ~ ${p.rel}`);
|
||||
return;
|
||||
}
|
||||
for (const p of planned) writeFileSync(join(PLUGIN_ROOT, p.rel), p.out);
|
||||
for (const p of planned) atomicWriteSync(join(PLUGIN_ROOT, p.rel), p.out);
|
||||
console.log(`\nWrote ${planned.length} files.`);
|
||||
}
|
||||
|
||||
|
|
|
|||
|
|
@ -1,9 +1,12 @@
|
|||
// backup.mjs — Backup + sentinel-guarded rollback for skills/-tree.
|
||||
// backup.mjs — Backup + sentinel-guarded, SCOPED rollback for skills/-tree.
|
||||
// Zero dependencies. Uses fs.cpSync (recursive + preserveTimestamps) without
|
||||
// dereference (Node 22.17.x regression) and without filter (Windows symlink-
|
||||
// type bug). Rollback writes a .rollback-in-progress sentinel at backupRoot
|
||||
// BEFORE destructive operations and removes it on success — a crash mid-
|
||||
// restore leaves the sentinel behind so detectStaleRollback() can flag it.
|
||||
// type bug). restore(relPaths) rolls back ONLY the relative paths the calling
|
||||
// run wrote — never the whole tree — so a parallel session's writes to sibling
|
||||
// files survive and there is no destructive rm→cp window. It writes a
|
||||
// .rollback-in-progress sentinel at backupRoot BEFORE the first per-file restore
|
||||
// and removes it on success — a crash mid-restore leaves the sentinel behind so
|
||||
// detectStaleRollback() can flag it.
|
||||
|
||||
import {
|
||||
cpSync,
|
||||
|
|
@ -15,8 +18,8 @@ import {
|
|||
unlinkSync,
|
||||
mkdirSync,
|
||||
} from 'node:fs';
|
||||
import { join, basename } from 'node:path';
|
||||
import { atomicWriteJson } from './atomic-write.mjs';
|
||||
import { join, basename, dirname } from 'node:path';
|
||||
import { atomicWriteJson, atomicWriteSync } from './atomic-write.mjs';
|
||||
|
||||
const META_FILENAME = '.backup-meta.json';
|
||||
const SENTINEL_FILENAME = '.rollback-in-progress';
|
||||
|
|
@ -84,39 +87,41 @@ export function backupDir(srcDir, backupRoot, opts = {}) {
|
|||
schema_version: 1,
|
||||
});
|
||||
|
||||
const restore = () => {
|
||||
// Scoped rollback: restore ONLY the relative paths (relative to srcDir) that the calling run
|
||||
// wrote this session. A file present in the backup is restored to its prior bytes atomically; a
|
||||
// file ABSENT from the backup was created this run, so rolling back means deleting it. Sibling
|
||||
// files a parallel session touched after this backup are never read or written, and there is no
|
||||
// window where srcDir is deleted. The sentinel is written before the first mutation and cleared
|
||||
// only on the success path — a throw mid-restore leaves it for detectStaleRollback().
|
||||
const restore = (relPaths) => {
|
||||
if (!Array.isArray(relPaths)) {
|
||||
throw new Error(
|
||||
"backupDir.restore: relPaths must be an array — restore is scoped to the run's own writes",
|
||||
);
|
||||
}
|
||||
const sentinelPath = join(backupRoot, SENTINEL_FILENAME);
|
||||
atomicWriteJson(sentinelPath, {
|
||||
backup_path: backupPath,
|
||||
src_dir: srcDir,
|
||||
rel_paths: relPaths,
|
||||
started_at: new Date().toISOString(),
|
||||
schema_version: 1,
|
||||
schema_version: 2,
|
||||
});
|
||||
try {
|
||||
rmSync(srcDir, {
|
||||
recursive: true,
|
||||
force: true,
|
||||
maxRetries: 3,
|
||||
retryDelay: 200,
|
||||
});
|
||||
cpSync(backupPath, srcDir, {
|
||||
recursive: true,
|
||||
force: true,
|
||||
preserveTimestamps: true,
|
||||
});
|
||||
// Remove the meta file we copied back into srcDir so srcDir is clean.
|
||||
const restoredMeta = join(srcDir, META_FILENAME);
|
||||
if (existsSync(restoredMeta)) {
|
||||
for (const rel of relPaths) {
|
||||
const from = join(backupPath, rel);
|
||||
const to = join(srcDir, rel);
|
||||
if (existsSync(from)) {
|
||||
mkdirSync(dirname(to), { recursive: true });
|
||||
atomicWriteSync(to, readFileSync(from)); // prior bytes, crash-safe (Buffer → byte-exact)
|
||||
} else if (existsSync(to)) {
|
||||
try {
|
||||
unlinkSync(restoredMeta);
|
||||
unlinkSync(to); // created this run — must not exist in the rolled-back state
|
||||
} catch {
|
||||
// best-effort
|
||||
}
|
||||
}
|
||||
} finally {
|
||||
// Sentinel removed only on success path — leave it on throw so the
|
||||
// post-mortem detector can see the orphan.
|
||||
}
|
||||
// Success — clear the sentinel. On a throw above it is left behind for detectStaleRollback().
|
||||
try {
|
||||
unlinkSync(sentinelPath);
|
||||
} catch {
|
||||
|
|
|
|||
|
|
@ -18,7 +18,10 @@
|
|||
// - advisor allowlist: only the 4 non-advisor skills are walked; a target path that
|
||||
// matches /ms-ai-advisor/ is a hard throw (belt-and-suspenders on the pure fn).
|
||||
// - atomic: atomicWriteSync only, never the raw fs writer.
|
||||
// - backup: backupDir(root, backupRoot) before the first write; restore() retained.
|
||||
// - backup: backupDir(root, backupRoot) before the first write. Recovery contract — restore()
|
||||
// is SCOPED: it rolls back ONLY the files this run wrote, so a parallel session's writes to
|
||||
// sibling files survive; a stale rollback sentinel aborts the run; old backups are pruned
|
||||
// past retention after a successful batch.
|
||||
// - per-field idempotent: delegated to insertHeaderFields (skips set Type/Source) and
|
||||
// insertToc (skips a file that already hasToc / is small).
|
||||
// - post-write assertion: re-read each written file, assert parseTypeHeader (and, when a
|
||||
|
|
@ -41,7 +44,7 @@ import {
|
|||
} from './lib/transform.mjs';
|
||||
import { parseTypeHeader, parseSourceHeader } from './lib/kb-headers.mjs';
|
||||
import { atomicWriteSync } from './lib/atomic-write.mjs';
|
||||
import { backupDir } from './lib/backup.mjs';
|
||||
import { backupDir, detectStaleRollback, cleanupOldBackups } from './lib/backup.mjs';
|
||||
|
||||
// The 4 non-advisor skills, enumerated explicitly (NO shell brace-expansion). Advisor
|
||||
// (ms-ai-advisor) is deliberately absent — it is classified in the manifest but never
|
||||
|
|
@ -170,16 +173,30 @@ export function migrateCorpus({ root, backupRoot, manifest, write = false }) {
|
|||
return { root, write, backupPath: null, restore: null, results, counts };
|
||||
}
|
||||
|
||||
// ONE backup before the first write — restore() undoes the whole batch.
|
||||
const { backupPath, restore } = backupDir(skillsDir, backupRoot);
|
||||
// A stale rollback sentinel means a prior run crashed mid-restore and the tree may be
|
||||
// inconsistent — refuse to write over it; the operator must recover and clear it first.
|
||||
if (detectStaleRollback(backupRoot)) {
|
||||
throw new Error(
|
||||
`migrateCorpus: a stale rollback sentinel is present under ${backupRoot} — a prior run ` +
|
||||
`crashed mid-restore. Recover the corpus and clear .rollback-in-progress before rerunning.`,
|
||||
);
|
||||
}
|
||||
|
||||
// ONE backup before the first write. restore() rolls back ONLY the files THIS run wrote
|
||||
// (scoped) — a parallel session's writes to sibling files are never touched.
|
||||
const { backupPath, retentionDays, restore: restoreFiles } = backupDir(skillsDir, backupRoot);
|
||||
const writtenRel = [];
|
||||
const restore = () => restoreFiles(writtenRel);
|
||||
|
||||
for (const r of changed) {
|
||||
const rel = relative(skillsDir, r.full).split(sep).join('/');
|
||||
atomicWriteSync(r.full, r.content);
|
||||
writtenRel.push(rel);
|
||||
const written = readFileSync(r.full, 'utf8');
|
||||
const typeOk = !r.expectType || parseTypeHeader(written) !== null;
|
||||
const sourceOk = !r.expectSource || parseSourceHeader(written) !== null;
|
||||
if (!typeOk || !sourceOk) {
|
||||
restore(); // roll the whole batch back — never leave a partial corpus
|
||||
restore(); // roll back only this run's own writes — never leave a partial corpus
|
||||
throw new Error(
|
||||
`migrateCorpus: post-write header truncated for ${r.relpath} ` +
|
||||
`(inserted field fell past the ${500}-byte scan window; corpus restored from backup)`,
|
||||
|
|
@ -189,6 +206,9 @@ export function migrateCorpus({ root, backupRoot, manifest, write = false }) {
|
|||
counts.written += 1;
|
||||
}
|
||||
|
||||
// Successful batch — prune backups past retention (best-effort hygiene).
|
||||
cleanupOldBackups(backupRoot, retentionDays);
|
||||
|
||||
return { root, write, backupPath, restore, results, counts };
|
||||
}
|
||||
|
||||
|
|
|
|||
|
|
@ -19,11 +19,15 @@
|
|||
// creation-vs-modified date pair) → carved out to a later dedup unit, and the collision-guard aborts on
|
||||
// them regardless. 8 further occurrences are body/list/placeholder and are never in scope.
|
||||
//
|
||||
// Recovery contract: writes are crash-safe (atomicWriteSync tmp+rename — a reader sees the old
|
||||
// file or the new one, never a partial); an interrupted run is recovered by re-running (idempotent).
|
||||
//
|
||||
// Usage: node scripts/kb-update/relabel-dato.mjs [--dry]
|
||||
import { readFileSync, writeFileSync, existsSync, realpathSync } from 'node:fs';
|
||||
import { readFileSync, existsSync, realpathSync } from 'node:fs';
|
||||
import { join, dirname } from 'node:path';
|
||||
import { fileURLToPath } from 'node:url';
|
||||
import { relabelHeaderDialect } from './relabel-dialect.mjs';
|
||||
import { atomicWriteSync } from './lib/atomic-write.mjs';
|
||||
|
||||
const __dirname = dirname(fileURLToPath(import.meta.url));
|
||||
const PLUGIN_ROOT = join(__dirname, '..', '..');
|
||||
|
|
@ -125,7 +129,7 @@ function run({ dry }) {
|
|||
}
|
||||
return;
|
||||
}
|
||||
for (const p of planned) writeFileSync(join(PLUGIN_ROOT, p.rel), p.out);
|
||||
for (const p of planned) atomicWriteSync(join(PLUGIN_ROOT, p.rel), p.out);
|
||||
console.log(`\nWrote ${planned.length} files.`);
|
||||
}
|
||||
|
||||
|
|
|
|||
|
|
@ -18,10 +18,14 @@
|
|||
// label token swapped, everything else byte-identical). Idempotent: a file with no norsk header
|
||||
// label is skipped, so a re-run is a no-op. Aborts and writes nothing on any drift or invariant breach.
|
||||
//
|
||||
// Recovery contract: writes are crash-safe (atomicWriteSync tmp+rename — a reader sees the old
|
||||
// file or the new one, never a partial); an interrupted run is recovered by re-running (idempotent).
|
||||
//
|
||||
// Usage: node scripts/kb-update/relabel-dialect.mjs [--dry]
|
||||
import { readFileSync, writeFileSync, existsSync, realpathSync } from 'node:fs';
|
||||
import { readFileSync, existsSync, realpathSync } from 'node:fs';
|
||||
import { join, dirname } from 'node:path';
|
||||
import { fileURLToPath } from 'node:url';
|
||||
import { atomicWriteSync } from './lib/atomic-write.mjs';
|
||||
|
||||
const __dirname = dirname(fileURLToPath(import.meta.url));
|
||||
const PLUGIN_ROOT = join(__dirname, '..', '..');
|
||||
|
|
@ -180,7 +184,7 @@ function run({ dry }) {
|
|||
}
|
||||
return;
|
||||
}
|
||||
for (const p of planned) writeFileSync(join(PLUGIN_ROOT, p.rel), p.out);
|
||||
for (const p of planned) atomicWriteSync(join(PLUGIN_ROOT, p.rel), p.out);
|
||||
console.log(`\nWrote ${planned.length} files.`);
|
||||
}
|
||||
|
||||
|
|
|
|||
93
tests/kb-update/test-backfill-category.test.mjs
Normal file
93
tests/kb-update/test-backfill-category.test.mjs
Normal file
|
|
@ -0,0 +1,93 @@
|
|||
// tests/kb-update/test-backfill-category.test.mjs
|
||||
// TDD for the Category-backfill driver (R20). RX-OPS2 makes it importable (isMain
|
||||
// guard + extracted run()/planCategoryBackfill) so its deterministic contract can be
|
||||
// pinned without executing the corpus scan as an import side effect, and routes its
|
||||
// writes through the crash-safe atomic writer. The pure, frozen contract:
|
||||
// - FOLDER_CATEGORY: the 5 operator-approved folder→category entries (2026-07-06).
|
||||
// - categoryForFile: immediate-parent-folder lookup; unknown folder → null.
|
||||
// - planCategoryBackfill: reads a corpus root, plans insert-only Category lines behind
|
||||
// the same one-line/byte-identical invariant as the sibling drivers; files that
|
||||
// already carry Category are idempotently skipped; unknown folders are unmatched
|
||||
// (never written).
|
||||
|
||||
import { test } from 'node:test';
|
||||
import assert from 'node:assert/strict';
|
||||
import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
|
||||
import { tmpdir } from 'node:os';
|
||||
import { join, dirname } from 'node:path';
|
||||
import {
|
||||
FOLDER_CATEGORY,
|
||||
categoryForFile,
|
||||
planCategoryBackfill,
|
||||
} from '../../scripts/kb-update/backfill-category.mjs';
|
||||
|
||||
function withTmp(fn) {
|
||||
const dir = mkdtempSync(join(tmpdir(), 'bcat-test-'));
|
||||
try {
|
||||
return fn(dir);
|
||||
} finally {
|
||||
rmSync(dir, { recursive: true, force: true });
|
||||
}
|
||||
}
|
||||
|
||||
function writeFile(root, rel, content) {
|
||||
const path = join(root, rel);
|
||||
mkdirSync(dirname(path), { recursive: true });
|
||||
writeFileSync(path, content, 'utf8');
|
||||
}
|
||||
|
||||
test('FOLDER_CATEGORY — frozen operator-approved taxonomy (5 folders, 2026-07-06)', () => {
|
||||
assert.deepEqual(FOLDER_CATEGORY, {
|
||||
architecture: 'Solution Architecture & Advisory',
|
||||
platforms: 'Microsoft AI Platforms',
|
||||
development: 'Microsoft AI Platforms',
|
||||
'responsible-ai': 'Responsible AI & Governance',
|
||||
'mlops-genaiops': 'MLOps & GenAIOps',
|
||||
});
|
||||
});
|
||||
|
||||
test('categoryForFile — maps immediate-parent folder; unknown folder → null', () => {
|
||||
assert.equal(categoryForFile('skills/x/references/architecture/foo.md'), 'Solution Architecture & Advisory');
|
||||
assert.equal(categoryForFile('skills/x/references/mlops-genaiops/bar.md'), 'MLOps & GenAIOps');
|
||||
assert.equal(categoryForFile('skills/x/references/responsible-ai/baz.md'), 'Responsible AI & Governance');
|
||||
assert.equal(categoryForFile('skills/x/references/unknown-folder/qux.md'), null);
|
||||
});
|
||||
|
||||
test('planCategoryBackfill — plans a Category-less file in a known folder (one line, right value)', () => {
|
||||
withTmp((root) => {
|
||||
writeFile(
|
||||
root,
|
||||
'skills/ms-ai-engineering/references/mlops-genaiops/x.md',
|
||||
'# X\n\n**Status:** Reference\n\n---\n\nBody.\n',
|
||||
);
|
||||
const { planned, unmatched } = planCategoryBackfill(root);
|
||||
assert.equal(unmatched.length, 0);
|
||||
assert.equal(planned.length, 1);
|
||||
assert.equal(planned[0].cat, 'MLOps & GenAIOps');
|
||||
// Insert-only invariant: exactly one extra line, the Category line.
|
||||
assert.match(planned[0].out, /^\*\*Category:\*\* MLOps & GenAIOps$/m);
|
||||
});
|
||||
});
|
||||
|
||||
test('planCategoryBackfill — file already carrying Category is skipped (idempotent)', () => {
|
||||
withTmp((root) => {
|
||||
writeFile(
|
||||
root,
|
||||
'skills/ms-ai-engineering/references/mlops-genaiops/x.md',
|
||||
'# X\n\n**Category:** MLOps & GenAIOps\n**Status:** Reference\n\n---\n\nBody.\n',
|
||||
);
|
||||
const { planned, unmatched } = planCategoryBackfill(root);
|
||||
assert.equal(planned.length, 0);
|
||||
assert.equal(unmatched.length, 0);
|
||||
});
|
||||
});
|
||||
|
||||
test('planCategoryBackfill — file in an unknown folder is unmatched, never planned for a write', () => {
|
||||
withTmp((root) => {
|
||||
writeFile(root, 'skills/ms-ai-x/references/mystery/x.md', '# X\n\n**Status:** Reference\n\n---\n\nBody.\n');
|
||||
const { planned, unmatched } = planCategoryBackfill(root);
|
||||
assert.equal(planned.length, 0);
|
||||
assert.equal(unmatched.length, 1);
|
||||
assert.match(unmatched[0], /mystery/);
|
||||
});
|
||||
});
|
||||
|
|
@ -141,35 +141,95 @@ test('backupDir — writes .backup-meta.json sentinel inside backup', () => {
|
|||
});
|
||||
});
|
||||
|
||||
test('restore — round-trips content after src is mutated', () => {
|
||||
// --- restore(relPaths): SCOPED per-file rollback (RX-OPS2) ---
|
||||
// The old restore() rm+cp'd the WHOLE srcDir, which deletes a parallel session's
|
||||
// writes made after the backup and opens a destructive rm→cp window. restore() now
|
||||
// takes the explicit list of relative paths THIS run wrote and rolls back only those.
|
||||
|
||||
test('restore(relPaths) — scoped: rolls back only listed files, preserves parallel writes', () => {
|
||||
withTmp((tmp) => {
|
||||
const src = join(tmp, 'skills');
|
||||
const root = join(tmp, '.kb-backup');
|
||||
makeSrc(src, { 'a.md': 'original', 'sub/b.md': 'original-b' });
|
||||
const original = readAll(src);
|
||||
makeSrc(src, { 'a.md': 'orig-a', 'b.md': 'orig-b' });
|
||||
|
||||
const handle = backupDir(src, root);
|
||||
|
||||
// Mutate src.
|
||||
writeFileSync(join(src, 'a.md'), 'mutated', 'utf8');
|
||||
writeFileSync(join(src, 'new.md'), 'extra', 'utf8');
|
||||
rmSync(join(src, 'sub'), { recursive: true, force: true });
|
||||
// This run mutates a.md; a PARALLEL session writes b.md AFTER the backup.
|
||||
writeFileSync(join(src, 'a.md'), 'mutated-a', 'utf8');
|
||||
writeFileSync(join(src, 'b.md'), 'parallel-b', 'utf8');
|
||||
|
||||
handle.restore();
|
||||
handle.restore(['a.md']); // roll back ONLY this run's own write
|
||||
|
||||
const restored = readAll(src);
|
||||
assert.deepEqual(restored, original);
|
||||
assert.equal(readFileSync(join(src, 'a.md'), 'utf8'), 'orig-a', 'listed file rolled back');
|
||||
assert.equal(readFileSync(join(src, 'b.md'), 'utf8'), 'parallel-b', "parallel session's write preserved");
|
||||
});
|
||||
});
|
||||
|
||||
test('restore — sentinel is removed after successful restore', () => {
|
||||
test('restore(relPaths) — scoped: deletes a file newly created this run', () => {
|
||||
withTmp((tmp) => {
|
||||
const src = join(tmp, 'skills');
|
||||
const root = join(tmp, '.kb-backup');
|
||||
makeSrc(src, { 'foo.md': 'A' });
|
||||
makeSrc(src, { 'a.md': 'orig-a' });
|
||||
|
||||
const handle = backupDir(src, root);
|
||||
handle.restore();
|
||||
assert.equal(detectStaleRollback(root), false);
|
||||
writeFileSync(join(src, 'new.md'), 'created', 'utf8'); // absent at backup time
|
||||
|
||||
handle.restore(['new.md']);
|
||||
|
||||
assert.equal(existsSync(join(src, 'new.md')), false, 'file created this run removed on rollback');
|
||||
assert.equal(readFileSync(join(src, 'a.md'), 'utf8'), 'orig-a', 'sibling untouched');
|
||||
});
|
||||
});
|
||||
|
||||
test('restore(relPaths) — scoped: restores a nested file to its pre-write bytes', () => {
|
||||
withTmp((tmp) => {
|
||||
const src = join(tmp, 'skills');
|
||||
const root = join(tmp, '.kb-backup');
|
||||
makeSrc(src, { 'sub/deep/c.md': 'orig-c', 'sub/other.md': 'orig-other' });
|
||||
|
||||
const handle = backupDir(src, root);
|
||||
writeFileSync(join(src, 'sub/deep/c.md'), 'mutated-c', 'utf8');
|
||||
writeFileSync(join(src, 'sub/other.md'), 'parallel-other', 'utf8');
|
||||
|
||||
handle.restore(['sub/deep/c.md']);
|
||||
assert.equal(readFileSync(join(src, 'sub/deep/c.md'), 'utf8'), 'orig-c', 'nested file rolled back');
|
||||
assert.equal(readFileSync(join(src, 'sub/other.md'), 'utf8'), 'parallel-other', 'unlisted nested sibling preserved');
|
||||
});
|
||||
});
|
||||
|
||||
test('restore(relPaths) — leaves no atomic-write temp file behind', () => {
|
||||
withTmp((tmp) => {
|
||||
const src = join(tmp, 'skills');
|
||||
const root = join(tmp, '.kb-backup');
|
||||
makeSrc(src, { 'a.md': 'orig-a' });
|
||||
const handle = backupDir(src, root);
|
||||
writeFileSync(join(src, 'a.md'), 'mutated-a', 'utf8');
|
||||
handle.restore(['a.md']);
|
||||
const names = Object.keys(readAll(src));
|
||||
assert.equal(names.some((n) => /\.tmp\./.test(n)), false, 'no restore temp file survived');
|
||||
});
|
||||
});
|
||||
|
||||
test('restore — throws when relPaths is not an array (rollback must be scoped)', () => {
|
||||
withTmp((tmp) => {
|
||||
const src = join(tmp, 'skills');
|
||||
const root = join(tmp, '.kb-backup');
|
||||
makeSrc(src, { 'a.md': 'A' });
|
||||
const handle = backupDir(src, root);
|
||||
assert.throws(() => handle.restore(), /relPaths|scoped/i);
|
||||
assert.throws(() => handle.restore('a.md'), /relPaths|scoped/i);
|
||||
});
|
||||
});
|
||||
|
||||
test('restore — sentinel is written then removed after a successful scoped restore', () => {
|
||||
withTmp((tmp) => {
|
||||
const src = join(tmp, 'skills');
|
||||
const root = join(tmp, '.kb-backup');
|
||||
makeSrc(src, { 'a.md': 'orig-a' });
|
||||
const handle = backupDir(src, root);
|
||||
writeFileSync(join(src, 'a.md'), 'mut', 'utf8');
|
||||
handle.restore(['a.md']);
|
||||
assert.equal(detectStaleRollback(root), false, 'sentinel cleared on success');
|
||||
});
|
||||
});
|
||||
|
||||
|
|
|
|||
29
tests/kb-update/test-driver-atomic-writes.test.mjs
Normal file
29
tests/kb-update/test-driver-atomic-writes.test.mjs
Normal file
|
|
@ -0,0 +1,29 @@
|
|||
// tests/kb-update/test-driver-atomic-writes.test.mjs
|
||||
// RX-OPS2 acceptance: every corpus-writing driver routes its writes through the
|
||||
// crash-safe atomicWriteSync (tmp+rename), never a bare writeFileSync that can leave a
|
||||
// half-written reference file. Mirrors the existing migrate-corpus source guard
|
||||
// (test-migrate-apply.test.mjs) for the five standalone drivers.
|
||||
|
||||
import { test } from 'node:test';
|
||||
import assert from 'node:assert/strict';
|
||||
import { readFileSync } from 'node:fs';
|
||||
import { join, dirname } from 'node:path';
|
||||
import { fileURLToPath } from 'node:url';
|
||||
|
||||
const KB = join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'scripts', 'kb-update');
|
||||
|
||||
const DRIVERS = [
|
||||
'backfill-status.mjs',
|
||||
'backfill-category.mjs',
|
||||
'dedup-plain-header.mjs',
|
||||
'relabel-dato.mjs',
|
||||
'relabel-dialect.mjs',
|
||||
];
|
||||
|
||||
for (const driver of DRIVERS) {
|
||||
test(`${driver} — writes corpus files via atomicWriteSync, never bare writeFileSync`, () => {
|
||||
const src = readFileSync(join(KB, driver), 'utf8');
|
||||
assert.match(src, /atomicWriteSync/, `${driver} must import/use the atomic writer`);
|
||||
assert.doesNotMatch(src, /\bwriteFileSync\b/, `${driver} must not call writeFileSync directly`);
|
||||
});
|
||||
}
|
||||
|
|
@ -279,3 +279,44 @@ test('migrateCorpus — post-write parse assertion catches a deep-preamble (>500
|
|||
assert.deepEqual(readAll(root), original);
|
||||
});
|
||||
});
|
||||
|
||||
// --- RX-OPS2: backup hygiene wired into the applier ---
|
||||
|
||||
test('migrateCorpus — aborts when a stale rollback sentinel is present (prior crash)', () => {
|
||||
withTmp((tmp) => {
|
||||
const root = join(tmp, 'skills');
|
||||
const backupRoot = join(tmp, '.kb-backup');
|
||||
makeCorpus(root, { 'ms-ai-engineering/references/a.md': REF_SMALL });
|
||||
mkdirSync(backupRoot, { recursive: true });
|
||||
// A previous run crashed mid-restore and left its sentinel behind.
|
||||
writeFileSync(join(backupRoot, '.rollback-in-progress'), JSON.stringify({ started_at: '2026-07-01T00:00:00Z' }), 'utf8');
|
||||
const manifest = { [key('ms-ai-engineering/references/a.md')]: { type: 'reference', source: 'https://learn.microsoft.com/x' } };
|
||||
assert.throws(
|
||||
() => migrateCorpus({ root, backupRoot, manifest, write: true }),
|
||||
/stale|rollback|recover/i,
|
||||
);
|
||||
// Aborted before any write — corpus untouched.
|
||||
assert.equal(readFileSync(join(root, 'ms-ai-engineering/references/a.md'), 'utf8'), REF_SMALL);
|
||||
});
|
||||
});
|
||||
|
||||
test('migrateCorpus — prunes backups older than retention after a successful write', () => {
|
||||
withTmp((tmp) => {
|
||||
const root = join(tmp, 'skills');
|
||||
const backupRoot = join(tmp, '.kb-backup');
|
||||
makeCorpus(root, { 'ms-ai-engineering/references/a.md': REF_SMALL });
|
||||
// Seed an old backup dir (>7 days) that cleanup must remove after a good run.
|
||||
const oldDir = join(backupRoot, '2026-01-01T00-00-00');
|
||||
mkdirSync(oldDir, { recursive: true });
|
||||
writeFileSync(
|
||||
join(oldDir, '.backup-meta.json'),
|
||||
JSON.stringify({ created_at: '2026-01-01T00:00:00.000Z', schema_version: 1 }),
|
||||
'utf8',
|
||||
);
|
||||
const manifest = { [key('ms-ai-engineering/references/a.md')]: { type: 'reference', source: 'https://learn.microsoft.com/x' } };
|
||||
const report = migrateCorpus({ root, backupRoot, manifest, write: true });
|
||||
assert.equal(report.counts.written, 1);
|
||||
assert.equal(existsSync(oldDir), false, 'stale-age backup pruned after successful write');
|
||||
assert.ok(existsSync(report.backupPath), "this run's fresh backup retained");
|
||||
});
|
||||
});
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue