@dailephd/my-dev-kit-lab 0.6.0 → 0.6.2

package/dist/src/evaluation/affectedNeighborhoodMetrics.js

@@ -0,0 +1,51 @@
+const FIELD_LABELS = {
+    changedFileCount: "the changed indexed file count",
+    changedSymbolCount: "the changed baseline symbol count",
+    affectedNodeCount: "the affected graph node count",
+    affectedEdgeCount: "the affected graph edge count",
+    taskOverlapCount: "the task-overlap node count",
+    taskOverlapPercent: "the task-overlap percent"
+};
+/**
+ * Converts a persisted (or in-memory) affected-neighborhood assessment into the six frozen v0.6.1
+ * metrics, once. A finite value (including zero) is available; a missing assessment or a null
+ * field is unavailable with a bounded reason, never zero. Pure; this is the ONLY owner of this
+ * conversion, reused unchanged by every caller.
+ */
+export function toAffectedNeighborhoodMetricValues(assessment, noAssessmentReason) {
+    const one = (field) => {
+        const unit = field === "taskOverlapPercent" ? "percent" : "count";
+        if (!assessment) {
+            return { availability: "unavailable", value: null, unit, reason: noAssessmentReason };
+        }
+        const value = assessment[field];
+        if (typeof value === "number") {
+            return { availability: "available", value, unit, reason: null };
+        }
+        const context = `assessment ${assessment.status}; seed mapping ${assessment.seedMappingStatus}; ` +
+            `graph ${assessment.graphEvidenceStatus}; neighborhood ${assessment.neighborhoodStatus}; task mapping ${assessment.taskMapping.status}` +
+            (field === "taskOverlapPercent" ? `; resolvable task nodes ${assessment.taskMapping.resolvableTaskNodeCount}` : "");
+        return {
+            availability: "unavailable",
+            value: null,
+            unit,
+            reason: `Affected-neighborhood evidence did not establish ${FIELD_LABELS[field]} (${context}).`
+        };
+    };
+    return {
+        changedFileCount: one("changedFileCount"),
+        changedSymbolCount: one("changedSymbolCount"),
+        affectedNodeCount: one("affectedNodeCount"),
+        affectedEdgeCount: one("affectedEdgeCount"),
+        taskOverlapCount: one("taskOverlapCount"),
+        taskOverlapPercent: one("taskOverlapPercent")
+    };
+}
+export const AFFECTED_NEIGHBORHOOD_METRIC_FIELDS = [
+    "changedFileCount",
+    "changedSymbolCount",
+    "affectedNodeCount",
+    "affectedEdgeCount",
+    "taskOverlapCount",
+    "taskOverlapPercent"
+];

package/dist/src/evaluation/indexSnapshot.js

@@ -228,7 +228,7 @@ async function enumerateIndexArtifacts(indexDir) {
     artifacts.sort((left, right) => compareCodeUnits(left.path, right.path));
     return { artifacts, truncated };
 }
-async function readJson(filePath) {
+export async function readJson(filePath) {
     let text;
     try {
         text = await readFile(filePath, "utf8");

package/dist/src/experiments/defaultRegistry.js

@@ -1,9 +1,11 @@
 import { ExperimentPluginRegistry } from "./registry.js";
 import { contextStrategyComparisonPlugin } from "./plugins/contextStrategyComparison/index.js";
+import { incrementalChangeStalenessPlugin } from "./plugins/incrementalChangeStaleness/index.js";
 import { warmIndexReusePlugin } from "./plugins/warmIndexReuse/index.js";
 export function createDefaultExperimentPluginRegistry() {
     const registry = new ExperimentPluginRegistry();
     registry.register(contextStrategyComparisonPlugin);
     registry.register(warmIndexReusePlugin);
+    registry.register(incrementalChangeStalenessPlugin);
     return registry;
 }

package/dist/src/experiments/plugins/incrementalChangeStaleness/comparison.js

@@ -0,0 +1,101 @@
+// v0.6.2 Batch 4 -- pure, deterministic comparison/classification owner.
+//
+// This module owns exactly:
+//  - CorrectnessRelationV1;
+//  - RequiredFileEvidenceStatusV1 / RequiredFileEvidenceV1;
+//  - RequiredFileEvidenceRelationV1;
+//  - StaleRiskClassificationV1;
+//  - the pure functions that compute them.
+//
+// Every function here is a pure, side-effect-free transform over already
+// collected evidence. No retrieval, no filesystem access, no my-dev-kit
+// invocation, and no numeric risk score: see the frozen batch prompt
+// sections 22-35 for the exact rules this file implements.
+/** Section 23: exact correctness comparison rules. */
+export function compareCorrectness(stale, fullRefresh) {
+    if (!stale.available || !fullRefresh.available) {
+        return "unknown";
+    }
+    if (stale.score < fullRefresh.score)
+        return "stale-worse";
+    if (stale.score > fullRefresh.score)
+        return "stale-better";
+    return "same";
+}
+/** Repository-standard forward-slash path normalization, matching existing lifecycle policy. */
+export function normalizeRequiredFilePath(value) {
+    return value.replace(/\\/g, "/").replace(/^(\.\/)+/, "");
+}
+function sortedUnique(values) {
+    return [...new Set(values.map(normalizeRequiredFilePath))].sort((left, right) => (left < right ? -1 : left > right ? 1 : 0));
+}
+/**
+ * Section 27: builds one treatment's required-file evidence.
+ *
+ * - `observedFilesComplete: false` means the treatment's actual-files-read set could not be
+ *   established completely (retrieval failed/partial or the contract could not prove completeness);
+ *   the result is always `unknown` in that case, regardless of `observedFiles` contents.
+ * - Otherwise: every normalized required file present in `observedFiles` is `present`; any
+ *   absence is `missing`.
+ */
+export function buildRequiredFileEvidence(args) {
+    const requiredFiles = sortedUnique(args.requiredFiles);
+    const observedFiles = sortedUnique(args.observedFiles);
+    if (!args.observedFilesComplete) {
+        return {
+            status: "unknown",
+            requiredFiles,
+            observedFiles,
+            missingFiles: [],
+            reason: args.unknownReason ?? "Retrieval evidence did not establish a complete actual-files-read set."
+        };
+    }
+    const observedSet = new Set(observedFiles);
+    const missingFiles = requiredFiles.filter((file) => !observedSet.has(file));
+    return {
+        status: missingFiles.length === 0 ? "present" : "missing",
+        requiredFiles,
+        observedFiles,
+        missingFiles,
+        reason: null
+    };
+}
+/** Section 30: exact required-file comparison rules. */
+export function compareRequiredFileEvidence(stale, fullRefresh) {
+    if (stale.status === "unknown" || fullRefresh.status === "unknown") {
+        return "unknown";
+    }
+    if (stale.status === "missing" && fullRefresh.status === "present")
+        return "stale-worse";
+    if (stale.status === "present" && fullRefresh.status === "missing")
+        return "stale-better";
+    return "same";
+}
+/**
+ * Sections 31-35: the frozen precedence algorithm. Correctness and required-file evidence are the
+ * only two inputs; affected-neighborhood evidence and reindexRecommendation are never inputs here.
+ */
+export function classifyStaleRisk(correctnessRelation, requiredFileEvidenceRelation) {
+    const reasonCodes = [];
+    // RULE 1 -- observed regression wins even if the other dimension is unknown.
+    if (correctnessRelation === "stale-worse" || requiredFileEvidenceRelation === "stale-worse") {
+        if (correctnessRelation === "stale-worse")
+            reasonCodes.push("stale-correctness-lower");
+        if (requiredFileEvidenceRelation === "stale-worse")
+            reasonCodes.push("stale-missing-required-file");
+        return { staleRiskClassification: "observed-stale-regression", reasonCodes: dedupe(reasonCodes) };
+    }
+    // RULE 2 -- inconclusive.
+    if (correctnessRelation === "unknown" || requiredFileEvidenceRelation === "unknown") {
+        if (correctnessRelation === "unknown")
+            reasonCodes.push("correctness-unavailable");
+        if (requiredFileEvidenceRelation === "unknown")
+            reasonCodes.push("required-file-evidence-unavailable");
+        return { staleRiskClassification: "inconclusive", reasonCodes: dedupe(reasonCodes) };
+    }
+    // RULE 3 -- no observed regression.
+    return { staleRiskClassification: "no-observed-stale-regression", reasonCodes: ["no-stale-specific-difference-observed"] };
+}
+function dedupe(values) {
+    return [...new Set(values)];
+}

package/dist/src/experiments/plugins/incrementalChangeStaleness/config.js

@@ -0,0 +1,66 @@
+import { invalidExperimentConfig, isPlainObject, mergeConfig, validExperimentConfig } from "../../config.js";
+import { FROZEN_INCREMENTAL_CHANGE_STALENESS_SCENARIO_IDS } from "./scenarioTypes.js";
+/**
+ * The frozen v0.6.2 compatibility baseline for the upstream tool. Every index
+ * of one matched scenario must come from this one configured command.
+ */
+export const INCREMENTAL_CHANGE_STALENESS_DEFAULT_KIT_COMMAND = "npx @dailephd/my-dev-kit@1.12.4";
+export const defaultIncrementalChangeStalenessConfig = {
+    outDir: "lab-output/incremental-change-staleness",
+    kitCommand: INCREMENTAL_CHANGE_STALENESS_DEFAULT_KIT_COMMAND
+};
+const SUPPORTED_FIELDS = ["outDir", "kitCommand", "caseIds"];
+export const incrementalChangeStalenessConfigDefinition = {
+    fields: [
+        { name: "outDir", type: "string", required: true, description: "Experiment output root." },
+        { name: "kitCommand", type: "string", description: "my-dev-kit command used for every treatment index build." },
+        {
+            name: "caseIds",
+            type: "array",
+            description: `Frozen scenario ids to include (${FROZEN_INCREMENTAL_CHANGE_STALENESS_SCENARIO_IDS.join(", ")}); defaults to all. Both stale-index and full-refresh always run for each selected scenario.`
+        }
+    ]
+};
+/**
+ * Closed validation: unknown fields (including any attempt to supply variant
+ * filters, catalog paths, or mutation text) are rejected. Scenario ids must be
+ * frozen production ids, non-empty, and free of duplicates, so invalid
+ * selections fail before any target or index work.
+ */
+export function validateIncrementalChangeStalenessConfig(config) {
+    if (config !== undefined && !isPlainObject(config)) {
+        return invalidExperimentConfig(["incremental-change-staleness config must be an object."]);
+    }
+    const errors = [];
+    const unsupported = Object.keys(config ?? {}).filter((key) => !SUPPORTED_FIELDS.includes(key));
+    if (unsupported.length > 0) {
+        errors.push(`Unsupported incremental-change-staleness config field(s): ${unsupported.sort().join(", ")}.`);
+    }
+    const normalized = mergeConfig(defaultIncrementalChangeStalenessConfig, config);
+    for (const field of ["outDir", "kitCommand"]) {
+        const value = normalized[field];
+        if (typeof value !== "string" || !value.trim()) {
+            errors.push(`${field} must be a non-empty string.`);
+        }
+    }
+    const caseIds = normalized.caseIds;
+    if (caseIds !== undefined) {
+        if (!Array.isArray(caseIds) || caseIds.length === 0 || !caseIds.every((item) => typeof item === "string" && item.trim())) {
+            errors.push("caseIds must be a non-empty array of non-empty scenario id strings when provided.");
+        }
+        else {
+            const duplicates = caseIds.filter((id, index) => caseIds.indexOf(id) !== index);
+            if (duplicates.length > 0) {
+                errors.push(`caseIds contains duplicate scenario id(s): ${[...new Set(duplicates)].join(", ")}.`);
+            }
+            const unknown = caseIds.filter((id) => !FROZEN_INCREMENTAL_CHANGE_STALENESS_SCENARIO_IDS.includes(id));
+            if (unknown.length > 0) {
+                errors.push(`caseIds contains unknown scenario id(s): ${unknown.join(", ")}. Expected one of ${FROZEN_INCREMENTAL_CHANGE_STALENESS_SCENARIO_IDS.join(", ")}.`);
+            }
+        }
+    }
+    if (errors.length > 0) {
+        return invalidExperimentConfig(errors);
+    }
+    return validExperimentConfig(normalized);
+}

package/dist/src/experiments/plugins/incrementalChangeStaleness/disposableTarget.js

@@ -0,0 +1,107 @@
+import { existsSync } from "node:fs";
+import { cp, realpath, rm } from "node:fs/promises";
+import path from "node:path";
+import { resolveWithinRoot } from "../../../core/pathSafety.js";
+/**
+ * The two primary v0.6.2 treatment identities, already frozen by the planned
+ * plugin design. Batch 2 uses them only to name independent disposable
+ * target copies; it never builds a treatment index or runs retrieval.
+ */
+export const INCREMENTAL_CHANGE_STALENESS_TREATMENT_IDS = ["stale-index", "full-refresh"];
+/**
+ * Default project-relative, gitignored runtime location for disposable
+ * treatment targets. Callers may pass a different `runRoot`, but it must
+ * still resolve inside `repoRoot` (see `createDisposableTreatmentTarget`).
+ */
+export const DEFAULT_INCREMENTAL_CHANGE_STALENESS_RUNTIME_ROOT_RELATIVE = ".my-dev-kit-context/runtime/incremental-change-staleness";
+function assertSafeRuntimeBoundary(repoRoot, runRoot) {
+    // runRoot itself must live inside the repository; this also rejects a
+    // caller-supplied runRoot that points outside the my-dev-kit-lab worktree.
+    return resolveWithinRoot(repoRoot, path.resolve(runRoot));
+}
+function assertDisposableRootDoesNotOverlapCanonical(targetRoot, canonicalProjectRoot) {
+    const relativeFromCanonical = path.relative(canonicalProjectRoot, targetRoot);
+    const targetIsInsideCanonical = relativeFromCanonical !== "" && !relativeFromCanonical.startsWith("..") && !path.isAbsolute(relativeFromCanonical);
+    const relativeFromTarget = path.relative(targetRoot, canonicalProjectRoot);
+    const canonicalIsInsideTarget = relativeFromTarget !== "" && !relativeFromTarget.startsWith("..") && !path.isAbsolute(relativeFromTarget);
+    if (targetRoot === canonicalProjectRoot || targetIsInsideCanonical || canonicalIsInsideTarget) {
+        throw new Error(`Disposable treatment target root ${targetRoot} unsafely overlaps the canonical benchmark project root ${canonicalProjectRoot}.`);
+    }
+}
+/**
+ * Creates one independent disposable copy of a canonical benchmark project
+ * for one scenario/treatment pair. Always copies the whole benchmark
+ * project (not just the changed file), since later index/retrieval
+ * execution requires a coherent project. Never overwrites an existing
+ * destination and never allows the destination to overlap the canonical
+ * project tree.
+ */
+export async function createDisposableTreatmentTarget(options) {
+    const { repoRoot, scenarioId, treatmentId, benchmarkProjectId, canonicalProjectRootRelative } = options;
+    if (!INCREMENTAL_CHANGE_STALENESS_TREATMENT_IDS.includes(treatmentId)) {
+        throw new Error(`Unknown treatment id: ${treatmentId}. Expected one of ${INCREMENTAL_CHANGE_STALENESS_TREATMENT_IDS.join(", ")}.`);
+    }
+    if (typeof scenarioId !== "string" || scenarioId.length === 0) {
+        throw new Error("scenarioId must be a nonempty string.");
+    }
+    const resolvedRepoRoot = path.resolve(repoRoot);
+    const resolvedRunRoot = assertSafeRuntimeBoundary(resolvedRepoRoot, options.runRoot);
+    const canonicalProjectRoot = resolveWithinRoot(resolvedRepoRoot, canonicalProjectRootRelative);
+    const targetRoot = resolveWithinRoot(resolvedRunRoot, path.join(scenarioId, treatmentId));
+    assertDisposableRootDoesNotOverlapCanonical(targetRoot, canonicalProjectRoot);
+    if (!existsSync(canonicalProjectRoot)) {
+        throw new Error(`Canonical benchmark project root does not exist: ${canonicalProjectRoot}.`);
+    }
+    if (existsSync(targetRoot)) {
+        throw new Error(`Disposable treatment target already exists; refusing to overwrite: ${targetRoot}.`);
+    }
+    await cp(canonicalProjectRoot, targetRoot, { recursive: true, errorOnExist: true, force: false });
+    return {
+        scenarioId,
+        treatmentId,
+        benchmarkProjectId,
+        canonicalProjectRoot,
+        targetRoot
+    };
+}
+/**
+ * Removes one disposable treatment target directory. Only ever deletes a
+ * path that resolves inside the caller-owned `runRoot`; refuses to touch
+ * anything else, including a canonical benchmark project. Idempotent: a
+ * missing target is a successful no-op.
+ */
+export async function removeDisposableTreatmentTarget(target, repoRoot, runRoot) {
+    const resolvedRepoRoot = path.resolve(repoRoot);
+    const resolvedRunRoot = assertSafeRuntimeBoundary(resolvedRepoRoot, runRoot);
+    // Re-derive containment from the caller-owned root rather than trusting the descriptor blindly.
+    const containedTargetRoot = resolveWithinRoot(resolvedRunRoot, path.resolve(target.targetRoot));
+    await rm(containedTargetRoot, { recursive: true, force: true });
+}
+/**
+ * Removes the entire caller-owned runtime root (both treatment copies for
+ * every scenario created under it). Refuses to operate unless `runRoot`
+ * resolves inside `repoRoot`, and never touches anything outside it.
+ */
+export async function removeIncrementalChangeStalenessRuntimeRoot(repoRoot, runRoot) {
+    const resolvedRepoRoot = path.resolve(repoRoot);
+    const resolvedRunRoot = assertSafeRuntimeBoundary(resolvedRepoRoot, runRoot);
+    await rm(resolvedRunRoot, { recursive: true, force: true });
+}
+/**
+ * Resolves a target-relative path inside a disposable treatment target,
+ * rejecting both textual path traversal and symlink escape: the resolved
+ * real path (once the file exists) must still be contained by the real
+ * path of the treatment root.
+ */
+export async function resolveWithinDisposableTarget(target, relativePath) {
+    const resolved = resolveWithinRoot(target.targetRoot, relativePath);
+    if (!existsSync(resolved)) {
+        return resolved;
+    }
+    const [realResolved, realRoot] = await Promise.all([realpath(resolved), realpath(target.targetRoot)]);
+    const relativeFromRoot = path.relative(realRoot, realResolved);
+    if (relativeFromRoot === ".." || relativeFromRoot.startsWith(`..${path.sep}`) || path.isAbsolute(relativeFromRoot)) {
+        throw new Error(`Resolved path escapes the disposable treatment root via a symbolic link: ${relativePath}`);
+    }
+    return resolved;
+}