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

package/dist/src/report/experiments/renderIncrementalChangeStalenessTextV2.js

@@ -0,0 +1,96 @@
+// v0.6.3 -- V2 text section for the incremental-change-staleness plugin report. Renders only persisted
+// V2 report-model fields (via the shared row builders); no recomputation. Lists are bounded.
+import { COMPARISON_PRESENTATION_ORDER, EVIDENCE_FAMILY_NOTE, SCENARIO_SUMMARY_ROWS, TREATMENT_PRESENTATION_ORDER, affectedNeighborhoodSummary, comparisonBlock, treatmentBlock } from "./incrementalChangeStalenessReportRowsV2.js";
+function renderScenario(lines, scenario, h) {
+    h.pushSection(lines, `Scenario: ${scenario.scenarioId}`);
+    lines.push(h.fieldLine("Category", scenario.category));
+    lines.push(h.fieldLine("Status", scenario.status));
+    lines.push(h.fieldLine("Failure Reason", scenario.failureReason));
+    lines.push(h.fieldLine("Benchmark Project", scenario.benchmarkProjectId));
+    lines.push(h.fieldLine("Base Case", scenario.baseCaseId));
+    lines.push(h.fieldLine("Answer Policy", scenario.answerPolicy));
+    lines.push(h.fieldLine("Query", scenario.query));
+    h.pushBoundedStringList(lines, "Expected Files", scenario.expectedFiles);
+    h.pushBoundedStringList(lines, "Expected Symbols", scenario.expectedSymbols);
+    h.pushSection(lines, "Lifecycle");
+    const lifecycle = scenario.lifecycle;
+    if (!lifecycle) {
+        lines.push("Not available.");
+    }
+    else {
+        lines.push(h.fieldLine("my-dev-kit Version", lifecycle.myDevKitVersion));
+        lines.push(h.fieldLine("Index Invocations (total)", lifecycle.totalIndexInvocationCount));
+        lines.push(h.fieldLine("Freshness Assessments (total)", lifecycle.totalFreshnessAssessmentCount));
+        for (const [treatmentId, result] of Object.entries(lifecycle.preMutationEquivalence)) {
+            lines.push(h.fieldLine(`Pre-Mutation Equivalence (${treatmentId} vs stale-index reference)`, result));
+        }
+        for (const [treatmentId, result] of Object.entries(lifecycle.postMutationEquivalence)) {
+            lines.push(h.fieldLine(`Post-Mutation Equivalence (${treatmentId} vs stale-index reference)`, result));
+        }
+        h.pushBoundedStringList(lines, "Controlled File Paths", lifecycle.controlledFilePaths);
+        h.pushBoundedStringList(lines, "Source Roots", lifecycle.sourceRoots);
+    }
+    h.pushSection(lines, "Affected-Neighborhood Evidence (changed baseline neighborhood relative to the task)");
+    const affected = affectedNeighborhoodSummary(scenario);
+    if (affected.state === "none") {
+        lines.push("Not available.");
+    }
+    else if (affected.state === "inconsistent") {
+        lines.push("inconsistent persisted evidence");
+    }
+    else {
+        for (const [label, value] of affected.rows)
+            lines.push(h.fieldLine(label, value));
+        lines.push(h.fieldLine("Reindex Recommendation Explanation", affected.explanation));
+    }
+    lines.push(EVIDENCE_FAMILY_NOTE);
+    if (scenario.treatments.length === 0) {
+        h.pushSection(lines, "Treatments");
+        lines.push("Not produced: the scenario failed before any treatment evidence existed.");
+    }
+    else {
+        for (const entry of TREATMENT_PRESENTATION_ORDER) {
+            const block = treatmentBlock(scenario, entry.id, entry.label);
+            h.pushSection(lines, `${block.label} Treatment (${entry.id})`);
+            if (!block.available) {
+                lines.push("Not available.");
+                continue;
+            }
+            for (const [label, value] of block.rows)
+                lines.push(h.fieldLine(label, value));
+            lines.push("Refresh Execution (upstream evidence of what my-dev-kit actually did):");
+            for (const [label, value] of block.refreshRows)
+                lines.push(h.fieldLine(label, value));
+            if (block.fallbackStatement)
+                lines.push(block.fallbackStatement);
+            if (block.forcedNeighborSample)
+                h.pushBoundedStringList(lines, "Forced-Neighbor Sample", block.forcedNeighborSample);
+            h.pushBoundedStringList(lines, "Files Read", block.filesRead);
+            h.pushBoundedStringList(lines, "Required Files", block.requiredFiles);
+            h.pushBoundedStringList(lines, "Observed Files", block.observedFiles);
+            h.pushBoundedStringList(lines, "Missing Files", block.missingFiles);
+        }
+    }
+    h.pushSection(lines, "Reference Comparisons (against the full-refresh reference)");
+    for (const entry of COMPARISON_PRESENTATION_ORDER) {
+        const block = comparisonBlock(scenario, entry);
+        lines.push(block.label);
+        if (!block.available) {
+            lines.push("Not available.");
+            continue;
+        }
+        for (const [label, value] of block.rows)
+            lines.push(h.fieldLine(label, value));
+        h.pushDashList(lines, block.reasonCodes);
+        lines.push(block.explanation);
+    }
+}
+export function renderIncrementalChangeStalenessSectionV2(lines, section, h) {
+    h.pushSection(lines, "Summary");
+    for (const [label, value] of SCENARIO_SUMMARY_ROWS(section.summary))
+        lines.push(h.fieldLine(label, value));
+    for (const scenario of section.scenarios)
+        renderScenario(lines, scenario, h);
+    h.pushSection(lines, "Limitations");
+    h.pushDashList(lines, section.limitations);
+}

package/dist/src/report/experiments/renderPluginExperimentReportText.js

@@ -1,4 +1,6 @@
 import { STALE_RISK_CLASSIFICATION_EXPLANATIONS } from "./buildIncrementalChangeStalenessReport.js";
+import { isV2ReportSection } from "./buildIncrementalChangeStalenessReportV2.js";
+import { renderIncrementalChangeStalenessSectionV2 } from "./renderIncrementalChangeStalenessTextV2.js";
 import { REINDEX_RECOMMENDATION_EXPLANATIONS } from "./buildWarmIndexReuseReport.js";
 function sanitizeScalar(value) {
     const text = String(value);
@@ -612,6 +614,10 @@ function renderIncrementalChangeStalenessSection(lines, section) {
         lines.push("Not applicable to this plugin.");
         return;
     }
+    if (isV2ReportSection(section)) {
+        renderIncrementalChangeStalenessSectionV2(lines, section, { pushSection, fieldLine, pushDashList, pushBoundedStringList });
+        return;
+    }
     pushSection(lines, "Summary");
     lines.push(fieldLine("Scenarios", section.scenarioCount));
     lines.push(fieldLine("Ready", section.readyScenarioCount));

package/dist/src/securityValidation/staticScans/codeql.js

@@ -1,18 +1,18 @@
 import { runSecurityCommand } from "../commandRunner.js";
 import { resolveCommand } from "../../core/resolveCommand.js";
 import { skippedCheck } from "../cliAdversarial/runAdversarialCheck.js";
-// CodeQL is primarily a GitHub Actions / code-scanning integration.
-// Local CodeQL CLI is optional — if unavailable the check is skipped.
-// Absence is not a release blocker; it surfaces as "ready except optional checks".
+// This local check only verifies CodeQL CLI availability and integration.
+// Full CodeQL analysis is owned by .github/workflows/codeql.yml.
+// Release readiness requires successful GitHub analysis for the exact candidate SHA.
 export async function runCodeqlCheck(options) {
     const { cwd, timeoutMs } = options;
     const resolved = resolveCommand("codeql", { cwd, env: process.env });
     if (resolved.resolutionKind === "unavailable") {
         return skippedCheck({
             id: "codeql-scan",
-            name: "CodeQL static analysis",
+            name: "CodeQL CLI availability preflight",
             category: "static-scan",
-            reason: "CodeQL CLI not found in PATH. Full analysis runs via GitHub Actions code-scanning workflow. Install the CodeQL CLI locally for local analysis.",
+            reason: "Local CodeQL CLI is unavailable, so the local availability preflight is skipped. Full release-readiness coverage requires a successful GitHub CodeQL advanced-setup analysis for the exact candidate SHA.",
         });
     }
     const startedAt = new Date().toISOString();
@@ -29,7 +29,7 @@ export async function runCodeqlCheck(options) {
     if (versionCmd.exitCode !== 0 || versionCmd.exitCode === null) {
         return {
             id: "codeql-scan",
-            name: "CodeQL static analysis",
+            name: "CodeQL CLI availability preflight",
             category: "static-scan",
             status: "failed",
             severity: "major",
@@ -50,10 +50,10 @@ export async function runCodeqlCheck(options) {
             command: "codeql version --format terse",
         };
     }
-    // CLI is present and functional. Full analysis runs in GitHub Actions.
+    // The CLI is present and functional; this is not repository-wide analysis.
     return {
         id: "codeql-scan",
-        name: "CodeQL static analysis",
+        name: "CodeQL CLI availability preflight",
         category: "static-scan",
         status: "passed",
         severity: "informational",

package/docs/METRICS.md

@@ -629,3 +629,35 @@ The `incremental-change-staleness` plugin reuses the six existing v0.6.1 affecte
 `staleRiskClassification` is not a numeric risk score, not a winner, not a ranking, and not an automatic reindex decision. `no-observed-stale-regression` means only that this matched scenario did not observe a stale-specific regression under these two frozen evidence dimensions; it does not establish that stale indexes are generally safe. `reindexRecommendation` (the released v0.6.1 categorical evidence) remains separate observational evidence about the affected-neighborhood analysis; it does not select or trigger either treatment and is not an input to the stale-risk classification above.
 
 **Report presentation.** `report.incrementalChangeStaleness` holds `scenarioCount`, `readyScenarioCount`, `failedScenarioCount`, `observedStaleRegressionCount`, `noObservedStaleRegressionCount`, `inconclusiveCount`, per-scenario evidence (lifecycle, both treatments in order, and the comparison), and fixed limitations text. There is no overall score, grade, winner, best-treatment, or safe-to-skip-reindex field anywhere in the report or the persisted execution artifact.
+
+### Partial-refresh treatment evidence (v0.6.3, current release)
+
+The `incremental-change-staleness` plugin now compares four treatments (`stale-index`, `changed-files-refresh`, `affected-neighborhood-refresh`, `full-refresh`). It defines no new formula. Two evidence families must not be merged:
+
+- **Lab task-relationship affected-neighborhood evidence** (released v0.6.1, unchanged): the six numeric metrics `changedFileCount`, `changedSymbolCount`, `affectedNodeCount`, `affectedEdgeCount`, `taskOverlapCount`, `taskOverlapPercent`, plus the categorical `relationship` and `reindexRecommendation`. They describe the baseline graph neighborhood of the controlled change relative to the task. `changedSymbolCount` still means baseline symbol identities belonging to confirmed changed indexed files, not proof that any symbol body changed, and `reindexRecommendation` stays observational: it selects and executes no treatment.
+- **Upstream refresh execution evidence** (new): what my-dev-kit actually did during a partial refresh invocation. It does not depend on the task and is not a task-relevance measure.
+
+**Numeric upstream-refresh metrics** (unit `count`; emitted as `ExperimentMetric` entries on the outcome of an incremental treatment, `changed-files-refresh` or `affected-neighborhood-refresh`, and never on `stale-index` or `full-refresh`):
+
+| Metric ID | Meaning |
+|---|---|
+| `upstream-refresh-fresh-extraction-file-count` | Files upstream freshly re-extracted during the refresh invocation. |
+| `upstream-refresh-reused-file-count` | Files upstream reused from the previous index. |
+| `upstream-refresh-forced-neighbor-reanalysis-file-count` | Neighboring files upstream forced to re-analyze during the refresh. |
+| `upstream-refresh-seed-file-count` | Seed files upstream selected for the affected-neighborhood refresh. |
+| `upstream-refresh-seed-symbol-count` | Seed symbols upstream selected. |
+| `upstream-refresh-affected-node-count` | Graph nodes upstream treated as affected. |
+| `upstream-refresh-affected-edge-count` | Graph edges upstream treated as affected. |
+
+Availability: the first three are always present for a validated incremental treatment. The seed, node, and edge counts appear only when upstream supplied a non-null value; a `null` upstream value is unavailable evidence and the metric is omitted, never emitted as zero. These counts describe upstream execution only: they do not prove a treatment is better, faster, safer, or more accurate, and they are distinct from the Lab `affectedNodeCount`/`affectedEdgeCount` above (different metric IDs).
+
+**Categorical refresh evidence** (not numeric metrics, never converted to numbers): `requestedScope` (`changed-files` or `affected-neighborhood`), `appliedScope` (the scope upstream actually applied: `changed-files`, `affected-neighborhood`, `full`, or `none`), `selectionStatus` (`applied`, `fallback-full`, or `not-needed`), `fallbackReason` (an upstream reason or `null`), `forcedNeighborSample` (a bounded sample of path strings, capped by upstream, so its length can be less than the forced-neighbor count), and the Lab `refreshRealization` (`NO_REFRESH`, `APPLIED_PARTIAL`, `FALLBACK_FULL`, `FULL_REFRESH`). Only `changed-files-refresh` and `affected-neighborhood-refresh` can be `APPLIED_PARTIAL` or `FALLBACK_FULL`.
+
+**Reference comparisons** (exactly three per ready scenario, each against `full-refresh`):
+
+- `stale-index` vs `full-refresh` uses the v0.6.2 stale-risk vocabulary and precedence unchanged (`observed-stale-regression`, `no-observed-stale-regression`, `inconclusive`).
+- `changed-files-refresh` vs `full-refresh` and `affected-neighborhood-refresh` vs `full-refresh` use neutral candidate relations (`candidate-worse`, `same`, `candidate-better`, `unknown`) for deterministic fake-agent correctness and for the required-file status, with the frozen precedence: (1) `not-comparable-as-partial-refresh` if the candidate fell back to a full rebuild (`FALLBACK_FULL`); (2) `observed-regression-relative-to-full` if correctness or required-file presence is `candidate-worse`; (3) `inconclusive` if either relation is `unknown`; (4) otherwise `no-observed-regression-relative-to-full`.
+
+`no-observed-regression-relative-to-full` means only that the executed scenario showed no regression under those two evidence dimensions. It does not establish equivalence or safety and does not show that full refresh is unnecessary. `not-comparable-as-partial-refresh` says the run gives no evidence about the requested partial behavior. There is no winner, ranking, composite score, safety score, safe-to-skip-refresh flag, or stale-risk percentage. Ordinary per-treatment correctness `score` remains the existing deterministic fake-agent evidence.
+
+**Report presentation.** `report.incrementalChangeStaleness` (schema `my-dev-kit-lab-incremental-change-staleness-report-v2`) holds the summary counts (including per-treatment applied-partial, fallback, and classification counts), per-scenario lifecycle, four treatments and three comparisons identified by explicit treatment IDs, and fixed limitations text. Unavailable evidence is written as `unavailable` or `not applicable`, never zero. Historical V1 reports keep their original two-treatment presentation.

package/examples/tutorial-browser/prepare.mjs

@@ -1,14 +1,14 @@
-import fs from "node:fs";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-
-const sourceRoot = path.dirname(fileURLToPath(import.meta.url));
-const targetRoot = process.argv[2];
-if (!targetRoot) {
-  console.error("prepare requires a target root argument");
-  process.exit(2);
-}
-fs.mkdirSync(path.join(targetRoot, "app"), { recursive: true });
-fs.mkdirSync(path.join(targetRoot, "out"), { recursive: true });
-for (const file of ["index.html", "server.mjs"]) fs.copyFileSync(path.join(sourceRoot, file), path.join(targetRoot, "app", file));
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const sourceRoot = path.dirname(fileURLToPath(import.meta.url));
+const targetRoot = process.argv[2];
+if (!targetRoot) {
+  console.error("prepare requires a target root argument");
+  process.exit(2);
+}
+fs.mkdirSync(path.join(targetRoot, "app"), { recursive: true });
+fs.mkdirSync(path.join(targetRoot, "out"), { recursive: true });
+for (const file of ["index.html", "server.mjs"]) fs.copyFileSync(path.join(sourceRoot, file), path.join(targetRoot, "app", file));
 fs.writeFileSync(path.join(targetRoot, "out", "report.json"), JSON.stringify({ prepared: true, counts: { widgets: 3 } }, null, 2), "utf8");

package/examples/tutorial-browser/server.mjs

@@ -1,14 +1,14 @@
-import http from "node:http";
-import fs from "node:fs";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-
-const root = path.dirname(fileURLToPath(import.meta.url));
-const port = Number(process.env.TUTORIAL_FIXTURE_PORT || 0);
-const server = http.createServer((req, res) => {
-  const url = new URL(req.url ?? "/", "http://127.0.0.1");
-  if (url.pathname === "/api/status") { res.writeHead(200, { "content-type": "application/json" }); res.end(JSON.stringify({ ok: true, widgets: 3 })); return; }
-  const filePath = url.pathname === "/" ? path.join(root, "index.html") : path.join(root, url.pathname);
-  fs.readFile(filePath, (error, contents) => { if (error) { res.writeHead(404); res.end("not found"); return; } res.writeHead(200, { "content-type": filePath.endsWith(".html") ? "text/html" : "application/octet-stream" }); res.end(contents); });
-});
+import http from "node:http";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = path.dirname(fileURLToPath(import.meta.url));
+const port = Number(process.env.TUTORIAL_FIXTURE_PORT || 0);
+const server = http.createServer((req, res) => {
+  const url = new URL(req.url ?? "/", "http://127.0.0.1");
+  if (url.pathname === "/api/status") { res.writeHead(200, { "content-type": "application/json" }); res.end(JSON.stringify({ ok: true, widgets: 3 })); return; }
+  const filePath = url.pathname === "/" ? path.join(root, "index.html") : path.join(root, url.pathname);
+  fs.readFile(filePath, (error, contents) => { if (error) { res.writeHead(404); res.end("not found"); return; } res.writeHead(200, { "content-type": filePath.endsWith(".html") ? "text/html" : "application/octet-stream" }); res.end(contents); });
+});
 server.listen(port, "127.0.0.1", () => console.log("tutorial fixture listening on " + server.address().port));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dailephd/my-dev-kit-lab",
-  "version": "0.6.2",
+  "version": "0.6.3",
   "type": "module",
   "description": "Evidence, benchmark, and evaluation companion for my-dev-kit.",
   "bin": {