Function scanRepo

extensions/java-modernization-studio/scan.mjs:474–571

(repoPath, opts = {})

 * @param {{ includeGit?: boolean }} [opts]
 */
export async function scanRepo(repoPath, opts = {}) {
    const includeGit = opts.includeGit !== false;
    if (!repoPath || !(await isDirectory(repoPath))) {
        return { ok: false, repoPath: repoPath || null, error: "repo path not available" };
    }

    // Modernization docs. Prefer the namespaced .appmod/ copies; the root-level
    // files (plan.md / progress.md / summary.md) use very common filenames, so we
    // trust them as workflow state only when the provenance gate below passes.
    const [apPlan, apProgress, apSummary, rootPlan, rootProgress, rootSummary] = await Promise.all([
        readText(join(repoPath, ".appmod", "plan.md")),
        readText(join(repoPath, ".appmod", "progress.md")),
        readText(join(repoPath, ".appmod", "summary.md")),
        readText(join(repoPath, "plan.md")),
        readText(join(repoPath, "progress.md")),
        readText(join(repoPath, "summary.md")),
    ]);

    // Structured assessment report (written by the assessment step). Optional,
    // and the strongest provenance signal that this repo is running the workflow.
    let report = null;
    const reportRaw = await readText(join(repoPath, ".appmod", "assessment.json"));
    if (reportRaw) {
        try {
            report = normalizeReport(JSON.parse(reportRaw));
        } catch {
            report = null;
        }
    }

    // Provenance gate. A .appmod/ artifact (assessment.json or a namespaced doc)
    // means the modernization workflow is active in this repo, so the root docs
    // are ours. Otherwise a root doc is trusted only if it carries the explicit
    // <!-- appmod-cockpit --> marker. This stops an unrelated summary.md from
    // flipping a foreign repo to "completed", or a stray plan.md from injecting
    // fake steps into the progress/ordering/autopilot machinery.
    const hasAppmodArtifact =
        reportRaw != null || apPlan != null || apProgress != null || apSummary != null;
    const trusted = (root) => hasAppmodArtifact || hasMarker(root);
    const planMd = apPlan || (trusted(rootPlan) ? rootPlan : null);
    const progressMd = apProgress || (trusted(rootProgress) ? rootProgress : null);
    const summaryMd = apSummary || (trusted(rootSummary) ? rootSummary : null);

    const assessment = await buildAssessment(repoPath);
    const skills = await discoverSkills(repoPath);

    const planSteps = parseSteps(planMd);
    const progressSteps = parseSteps(progressMd);
    // Tag each step with its canonical phase rank for ordering guidance.
    for (const arr of [planSteps, progressSteps]) {
        for (const st of arr) st.rank = phaseRankFromName(st.section);
    }
    // Progress is the source of truth for status; fall back to plan steps.
    const steps = progressSteps.length ? progressSteps : planSteps;
    const percent = percentDone(steps);
    const ordering = computeOrdering(steps);
    // Prefer an explicit "Validation"/"gates" section for gate status; fall back
    // to scanning all steps when no such section exists.