@dailephd/my-dev-kit-lab 0.2.0

package/dist/src/securityValidation/validate/runSecurityValidation.js

@@ -0,0 +1,169 @@
+import path from "node:path";
+import fs from "node:fs";
+import { runDependencyChecks } from "../dependencies/runDependencyChecks.js";
+import { runPackageChecks } from "../packageChecks/runPackageChecks.js";
+import { runCodeqlCheck } from "../staticScans/codeql.js";
+import { runSemgrepCheck } from "../staticScans/semgrep.js";
+import { runAllFuzzTargets } from "../fuzz/fuzzHarness.js";
+import { ALL_FUZZ_TARGETS } from "../fuzz/fuzzTargets.js";
+import { runSecurityCommand, resolveNpmCommand } from "../commandRunner.js";
+import { calculateVerdict } from "./verdict.js";
+import { resolveValidationTarget, targetDescription as describeTarget } from "./resolveTarget.js";
+import { DEFAULT_SECURITY_CONFIG } from "../config.js";
+export async function runSecurityValidation(options) {
+    const toolRoot = options.cwd;
+    const config = {
+        ...DEFAULT_SECURITY_CONFIG,
+        reportDir: path.join(toolRoot, DEFAULT_SECURITY_CONFIG.reportDir),
+        rawOutputDir: path.join(toolRoot, DEFAULT_SECURITY_CONFIG.rawOutputDir),
+        ...options.config,
+    };
+    // Resolve and validate the target project
+    const target = resolveValidationTarget(options.targetPath, toolRoot);
+    const startedAt = new Date().toISOString();
+    const allChecks = [];
+    const allFindings = [];
+    function collect(check) {
+        allChecks.push(check);
+        allFindings.push(...check.findings);
+    }
+    function collectMany(checks) {
+        for (const c of checks)
+            collect(c);
+    }
+    // --- Dependency checks (runs in target root) ---
+    // If target has no package.json/lockfile, runDependencyChecks will surface that
+    // as a structured finding rather than crashing.
+    try {
+        const depOutput = await runDependencyChecks({ cwd: target.targetRoot, config });
+        collectMany(depOutput.checks);
+    }
+    catch (err) {
+        collect(errorCheck("dependency-checks", "Dependency checks", "dependency-audit", err));
+    }
+    // --- Package content checks (runs in target root) ---
+    // Not all projects are publishable npm packages; runPackageChecks handles
+    // missing package.json gracefully.
+    try {
+        const pkgOutput = await runPackageChecks({ cwd: target.targetRoot, config });
+        collectMany(pkgOutput.checks);
+    }
+    catch (err) {
+        collect(errorCheck("package-content", "Package content checks", "package-content", err));
+    }
+    // --- Static scans (scan target root; config from tool root) ---
+    try {
+        collect(await runCodeqlCheck({ cwd: toolRoot, targetRoot: target.targetRoot, timeoutMs: config.commandTimeoutMs }));
+    }
+    catch (err) {
+        collect(errorCheck("codeql-scan", "CodeQL static analysis", "static-scan", err));
+    }
+    try {
+        collect(await runSemgrepCheck({
+            targetRoot: target.targetRoot,
+            toolRoot,
+            timeoutMs: config.commandTimeoutMs,
+        }));
+    }
+    catch (err) {
+        collect(errorCheck("semgrep-scan", "Semgrep static analysis", "static-scan", err));
+    }
+    // --- CLI adversarial tests (always tool-internal; tests my-dev-kit-lab harness) ---
+    // These run in the tool root because they use fake-adversarial-cli.js fixtures.
+    // Labeled clearly so the report shows they are not target-specific checks.
+    {
+        const startedAt2 = new Date().toISOString();
+        const npm = resolveNpmCommand();
+        const cmd = await runSecurityCommand({
+            command: npm,
+            args: ["run", "test:security", "--", "--reporter=json"],
+            cwd: toolRoot,
+            timeoutMs: Math.min(config.commandTimeoutMs * 3, 180_000),
+        });
+        const finishedAt2 = new Date().toISOString();
+        const passed = cmd.exitCode === 0;
+        collect({
+            id: "cli-adversarial-suite",
+            name: "CLI adversarial test suite (tool self-tests, not target-specific)",
+            category: "cli-adversarial",
+            status: passed ? "passed" : "failed",
+            severity: "major",
+            startedAt: startedAt2,
+            finishedAt: finishedAt2,
+            durationMs: cmd.durationMs,
+            findings: passed
+                ? []
+                : [
+                    {
+                        id: "cli-adversarial-suite-failed",
+                        title: "CLI adversarial test suite had failures",
+                        severity: "major",
+                        category: "cli-adversarial",
+                        description: `test:security exited with code ${String(cmd.exitCode)}. Run 'npm run test:security' for details.`,
+                        recommendation: "Fix failing adversarial tests before release.",
+                        releaseImpact: "Should fix before release",
+                    },
+                ],
+            command: `${npm} run test:security`,
+        });
+    }
+    // --- Fuzz smoke (always tool-internal; tests library parser/helper code) ---
+    try {
+        collect(await runAllFuzzTargets(ALL_FUZZ_TARGETS, {
+            seed: options.fuzzSeed ?? 0xdeadbeef,
+            iterations: options.fuzzIterations ?? 50,
+        }));
+    }
+    catch (err) {
+        collect(errorCheck("fuzz-smoke", "Fuzz smoke", "fuzz-smoke", err));
+    }
+    const finishedAt = new Date().toISOString();
+    // --- Tool root metadata ---
+    let toolPackageName = "my-dev-kit-lab";
+    let toolPackageVersion = "unknown";
+    try {
+        const pkgRaw = fs.readFileSync(path.join(toolRoot, "package.json"), "utf8");
+        const pkg = JSON.parse(pkgRaw);
+        if (pkg.name)
+            toolPackageName = pkg.name;
+        if (pkg.version)
+            toolPackageVersion = pkg.version;
+    }
+    catch {
+        // Use defaults.
+    }
+    const { verdict, recommendedNextStep } = calculateVerdict(allChecks, allFindings);
+    return {
+        toolRoot,
+        toolPackageName,
+        toolPackageVersion,
+        targetRoot: target.targetRoot,
+        targetDescription: describeTarget(target),
+        packageName: target.packageName ?? (target.isSelf ? toolPackageName : path.basename(target.targetRoot)),
+        packageVersion: target.packageVersion ?? (target.isSelf ? toolPackageVersion : "unknown"),
+        auditedBranch: target.branch ?? "unknown",
+        auditedCommit: target.commit ?? "unknown",
+        isSelf: target.isSelf,
+        startedAt,
+        finishedAt,
+        checks: allChecks,
+        findings: allFindings,
+        verdict,
+        recommendedNextStep,
+    };
+}
+function errorCheck(id, name, category, err) {
+    const now = new Date().toISOString();
+    return {
+        id,
+        name: `${name} (orchestrator error)`,
+        category,
+        status: "failed",
+        severity: "major",
+        startedAt: now,
+        finishedAt: now,
+        durationMs: 0,
+        findings: [],
+        skippedReason: err instanceof Error ? err.message : String(err),
+    };
+}

package/dist/src/securityValidation/validate/verdict.js

@@ -0,0 +1,73 @@
+// ---------------------------------------------------------------------------
+// Verdict calculation
+//
+// Rules (evaluated in order, first match wins):
+//   1. Any blocker finding                          → not-ready-security-blocker-remains
+//   2. Any mandatory check "failed"                 → not-ready-security-blocker-remains
+//   3. Too many mandatory checks skipped (>= 4)    → inconclusive-audit-environment-incomplete
+//   4. Any major finding                            → not-ready-security-blocker-remains
+//   5. Any optional check skipped                  → ready-except-optional-manual-checks
+//   6. Otherwise                                    → ready-for-release-preparation
+// ---------------------------------------------------------------------------
+// Checks that must not be skipped for a clean verdict.
+const MANDATORY_CHECK_IDS = new Set([
+    "npm-audit-full",
+    "npm-audit-runtime",
+    "npm-pack-dry-run",
+    "source-files-not-modified",
+    "writes-limited-to-output",
+]);
+export function calculateVerdict(checks, findings) {
+    const blockerFindings = findings.filter((f) => f.severity === "blocker");
+    const majorFindings = findings.filter((f) => f.severity === "major");
+    const failedMandatory = checks.filter((c) => MANDATORY_CHECK_IDS.has(c.id) && c.status === "failed");
+    const skippedMandatory = checks.filter((c) => MANDATORY_CHECK_IDS.has(c.id) && c.status === "skipped");
+    const skippedOptional = checks.filter((c) => !MANDATORY_CHECK_IDS.has(c.id) && c.status === "skipped");
+    if (blockerFindings.length > 0) {
+        return {
+            verdict: "not-ready-security-blocker-remains",
+            recommendedNextStep: `Fix ${blockerFindings.length} blocker finding(s) before release: ${blockerFindings.map((f) => f.title).join("; ")}`,
+        };
+    }
+    if (failedMandatory.length > 0) {
+        return {
+            verdict: "not-ready-security-blocker-remains",
+            recommendedNextStep: `Mandatory check(s) failed: ${failedMandatory.map((c) => c.name).join(", ")}. Investigate and re-run security:validate.`,
+        };
+    }
+    if (skippedMandatory.length >= 4) {
+        return {
+            verdict: "inconclusive-audit-environment-incomplete",
+            recommendedNextStep: `Too many mandatory checks were skipped (${skippedMandatory.length}). Ensure npm, npm audit, and package tools are available.`,
+        };
+    }
+    if (majorFindings.length > 0) {
+        return {
+            verdict: "not-ready-security-blocker-remains",
+            recommendedNextStep: `Fix or review ${majorFindings.length} major finding(s) before release: ${majorFindings.map((f) => f.title).join("; ")}`,
+        };
+    }
+    if (skippedOptional.length > 0) {
+        const names = skippedOptional.map((c) => c.name).join(", ");
+        return {
+            verdict: "ready-except-optional-manual-checks",
+            recommendedNextStep: `Optional check(s) were skipped due to unavailable tools: ${names}. Run manually if possible before publishing.`,
+        };
+    }
+    return {
+        verdict: "ready-for-release-preparation",
+        recommendedNextStep: "All mandatory checks passed. Proceed with version bump, changelog, and npm publish checklist.",
+    };
+}
+export function verdictToHumanLabel(verdict) {
+    switch (verdict) {
+        case "ready-for-release-preparation":
+            return "ready for release preparation";
+        case "not-ready-security-blocker-remains":
+            return "not ready: security blocker remains";
+        case "ready-except-optional-manual-checks":
+            return "ready except optional manual checks";
+        case "inconclusive-audit-environment-incomplete":
+            return "inconclusive: audit environment incomplete";
+    }
+}

package/dist/src/visualizationDemos/buildMyDevKitVisualizationCommands.js

@@ -0,0 +1,59 @@
+import path from "node:path";
+export function buildMyDevKitVisualizationCommands(options) {
+    const projectPath = path.resolve(options.projectPath);
+    const outDir = path.resolve(options.outDir);
+    const indexDir = path.join(outDir, "artifacts", "index");
+    const artifactsDir = path.join(outDir, "artifacts");
+    const query = options.query ?? "create task";
+    const nodeId = options.nodeId ?? "todo-ts:createTask";
+    return [
+        {
+            id: "index-project",
+            name: "Index project",
+            command: options.kitCommand,
+            args: ["index", "--src", projectPath, "--out", indexDir, "--call-graph", "--json"],
+            cwd: projectPath,
+            expectedArtifacts: [path.join(indexDir, "manifest.json")]
+        },
+        {
+            id: "search-task-symbols",
+            name: "Search task symbols",
+            command: options.kitCommand,
+            args: ["search", "--index", indexDir, "--query", query, "--limit", "10"],
+            cwd: projectPath,
+            expectedArtifacts: []
+        },
+        {
+            id: "view-call-graph",
+            name: "View call graph",
+            command: options.kitCommand,
+            args: ["view", "--index", indexDir, "--graph", "code", "--out", path.join(artifactsDir, "call-graph.svg")],
+            cwd: projectPath,
+            expectedArtifacts: [path.join(artifactsDir, "call-graph.svg")]
+        },
+        {
+            id: "view-data-model",
+            name: "View data model",
+            command: options.kitCommand,
+            args: ["view", "--index", indexDir, "--graph", "data-model", "--out", path.join(artifactsDir, "data-model.svg")],
+            cwd: projectPath,
+            expectedArtifacts: [path.join(artifactsDir, "data-model.svg")]
+        },
+        {
+            id: "view-model-view-lineage",
+            name: "View model-view-lineage",
+            command: options.kitCommand,
+            args: ["view", "--index", indexDir, "--graph", "model-view-lineage", "--out", path.join(artifactsDir, "model-view-lineage.svg")],
+            cwd: projectPath,
+            expectedArtifacts: [path.join(artifactsDir, "model-view-lineage.svg")]
+        },
+        {
+            id: "source-known-symbol",
+            name: "Source known symbol",
+            command: options.kitCommand,
+            args: ["source", "--index", indexDir, "--node", nodeId],
+            cwd: projectPath,
+            expectedArtifacts: []
+        }
+    ];
+}

package/dist/src/visualizationDemos/index.js

@@ -0,0 +1,4 @@
+export * from "./types.js";
+export * from "./buildMyDevKitVisualizationCommands.js";
+export * from "./runVisualizationDemos.js";
+export * from "./writeVisualizationDemoArtifacts.js";

package/dist/src/visualizationDemos/runVisualizationDemos.js

@@ -0,0 +1,82 @@
+import { existsSync } from "node:fs";
+import { mkdir } from "node:fs/promises";
+import path from "node:path";
+import { parseCommandString, serializeCommand } from "../core/commandLine.js";
+import { runMeasuredCommand } from "../core/runMeasuredCommand.js";
+import { buildMyDevKitVisualizationCommands } from "./buildMyDevKitVisualizationCommands.js";
+import { writeVisualizationDemoArtifacts } from "./writeVisualizationDemoArtifacts.js";
+export async function runVisualizationDemos(options) {
+    const outDir = path.resolve(options.outDir);
+    const projectPath = path.resolve(options.projectPath);
+    const kitCommand = normalizeKitCommand(options.kitCommand);
+    const commands = options.commands ??
+        buildMyDevKitVisualizationCommands({
+            projectPath,
+            kitCommand,
+            outDir,
+            query: options.query,
+            nodeId: options.nodeId
+        });
+    await mkdir(path.join(outDir, "commands"), { recursive: true });
+    await mkdir(path.join(outDir, "artifacts"), { recursive: true });
+    const runs = [];
+    const warnings = [];
+    for (const command of commands) {
+        const commandOutDir = path.join(outDir, "commands", command.id);
+        const measured = await runMeasuredCommand({
+            commandId: command.id,
+            commandString: command.command,
+            cwd: command.cwd,
+            outDir: commandOutDir,
+            extraArgs: command.args,
+            timeoutMs: options.timeoutMs
+        });
+        const expectedArtifacts = command.expectedArtifacts.map((artifactPath) => ({ path: artifactPath, exists: existsSync(artifactPath) }));
+        const producedArtifactPaths = expectedArtifacts.filter((artifact) => artifact.exists).map((artifact) => artifact.path);
+        const runWarnings = [
+            ...expectedArtifacts.filter((artifact) => !artifact.exists).map((artifact) => `Expected artifact was not produced: ${artifact.path}`)
+        ];
+        const errors = measured.ok ? [] : [(measured.error ?? measured.stderr) || `Command exited with code ${measured.exitCode}`];
+        if (runWarnings.length > 0)
+            warnings.push(...runWarnings.map((warning) => `${command.id}: ${warning}`));
+        if (!measured.ok)
+            warnings.push(`${command.id}: command failed or is unsupported.`);
+        runs.push({
+            id: command.id,
+            name: command.name,
+            commandString: command.command,
+            args: command.args,
+            cwd: command.cwd,
+            exitCode: measured.exitCode,
+            durationMs: measured.durationMs,
+            stdoutPath: measured.stdoutPath,
+            stderrPath: measured.stderrPath,
+            producedArtifactPaths,
+            expectedArtifacts,
+            warnings: runWarnings,
+            errors,
+            ok: measured.ok,
+            measured
+        });
+        if (!measured.ok && options.requireAll) {
+            break;
+        }
+    }
+    return writeVisualizationDemoArtifacts({
+        outDir,
+        projectPath,
+        kitCommand,
+        runs,
+        warnings
+    });
+}
+function normalizeKitCommand(command) {
+    const parsed = parseCommandString(command);
+    if ((parsed.executable === "node" || parsed.executable === "node.exe") && parsed.args[0] && !path.isAbsolute(parsed.args[0])) {
+        const scriptPath = path.resolve(process.cwd(), parsed.args[0]);
+        if (existsSync(scriptPath)) {
+            return serializeCommand([parsed.executable, scriptPath, ...parsed.args.slice(1)]);
+        }
+    }
+    return command;
+}

package/dist/src/visualizationDemos/types.js

@@ -0,0 +1 @@
+export {};

package/dist/src/visualizationDemos/writeVisualizationDemoArtifacts.js

@@ -0,0 +1,25 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { resolveWithinRoot } from "../core/pathSafety.js";
+export async function writeVisualizationDemoArtifacts(options) {
+    const outDir = path.resolve(options.outDir);
+    await mkdir(outDir, { recursive: true });
+    const artifactPaths = {
+        summaryPath: resolveWithinRoot(outDir, "visualization-demo-summary.json"),
+        runsPath: resolveWithinRoot(outDir, "visualization-demo-runs.json"),
+        commandsDir: resolveWithinRoot(outDir, "commands"),
+        artifactsDir: resolveWithinRoot(outDir, "artifacts")
+    };
+    const summary = {
+        generatedAt: options.generatedAt ?? new Date().toISOString(),
+        projectPath: path.resolve(options.projectPath),
+        kitCommand: options.kitCommand,
+        totalRuns: options.runs.length,
+        completedRuns: options.runs.filter((run) => run.ok).length,
+        failedRuns: options.runs.filter((run) => !run.ok).length,
+        warnings: options.warnings
+    };
+    await writeFile(artifactPaths.summaryPath, `${JSON.stringify(summary, null, 2)}\n`, "utf8");
+    await writeFile(artifactPaths.runsPath, `${JSON.stringify({ generatedAt: summary.generatedAt, runs: options.runs }, null, 2)}\n`, "utf8");
+    return { summary, runs: options.runs, artifactPaths, warnings: options.warnings };
+}