pbakaus_impeccable/skill/scripts/doctor.mjs

#!/usr/bin/env node
/**
 * Deep staleness pass over Impeccable's own project artifacts.
 *
 *   node doctor.mjs                 # human-readable report
 *   node doctor.mjs --json          # machine-readable, for the skill command
 *   node doctor.mjs --fix           # apply the mechanical migrations only
 *   node doctor.mjs --target <path> # pick a monorepo workspace
 *
 * The boot check in context.mjs reports what a session can afford to measure.
 * This runs everything: git drift, per-workspace sweep, ignore-list validation
 * against the live rule registry, hook script resolution.
 *
 * `--fix` is deliberately narrow. It performs only the migrations marked
 * severity 'auto', the ones with no judgment in them: stamp the product record,
 * move a sidecar out of a retired location. Anything that needs an answer from
 * the user (a platform value, whether an inherited record still describes an
 * app, whether a document has drifted from the code) is reported and left
 * alone. Exit code is 0 unless the run itself failed; findings are not errors.
 */

import fs from 'node:fs';
import path from 'node:path';
import { fileURLToPath } from 'node:url';

import { loadContext, extractPlatform, resolveTargetSelection } from './context.mjs';
import { parseTargetOptions } from './lib/target-args.mjs';
import { IMPECCABLE_COMMAND, IMPECCABLE_PROVIDER_ID } from './lib/provider.mjs';
import { parseDesignMd } from './lib/design-parser.mjs';
import {
  PRODUCT_SCHEMA_VERSION,
  readProductSchemaVersion,
  stampProductSchema,
} from './lib/artifact-schema.mjs';
import {
  checkConfig,
  checkDesignSidecar,
  checkNativePlatformEvidence,
  checkProduct,
  checkProjectRoots,
  checkSurfaceBriefs,
  designSidecarCandidatesFor,
} from './lib/staleness.mjs';
import {
  checkDesignCoverage,
  checkDesignDrift,
  checkDetectorIgnores,
  checkHookInstallation,
  checkLegacyLiveState,
  checkWorkspaces,
  loadKnownRuleIds,
} from './lib/staleness-deep.mjs';

const SCRIPTS_DIR = path.dirname(fileURLToPath(import.meta.url));

function safeRead(filePath) {
  try {
    return fs.readFileSync(filePath, 'utf-8');
  } catch {
    return null;
  }
}

function parseArgs(argv) {
  const passthrough = [];
  const flags = { json: false, fix: false, help: false };
  for (const arg of argv) {
    if (arg === '--json') flags.json = true;
    else if (arg === '--fix') flags.fix = true;
    else if (arg === '--help' || arg === '-h') flags.help = true;
    else passthrough.push(arg);
  }
  return { flags, targetOptions: parseTargetOptions(passthrough, { strict: true }) };
}

function usage() {
  return [
    `Usage: node doctor.mjs [--json] [--fix] [--target <path>]`,
    '',
    "Report drift between this project's Impeccable artifacts and what the",
    'installed version reads: PRODUCT.md, DESIGN.md and its sidecar,',
    '.impeccable/config.json, surface briefs, and the design hook.',
    '',
    '  --json           Emit findings as JSON.',
    '  --fix            Apply the mechanical migrations (severity "auto") only.',
    '  --target <path>  Select a workspace in a monorepo.',
  ].join('\n');
}

async function collect(cwd, targetOptions) {
  const ctx = loadContext(cwd, targetOptions);
  const projectRoot = ctx.projectRoot || cwd;
  const absProductPath = ctx.productPath ? path.resolve(cwd, ctx.productPath) : null;
  const absDesignPath = ctx.designPath ? path.resolve(cwd, ctx.designPath) : null;
  const sidecarCandidates = designSidecarCandidatesFor(projectRoot, ctx.contextDir);
  const knownRuleIds = await loadKnownRuleIds(SCRIPTS_DIR);

  const selection = resolveTargetSelection(cwd, targetOptions);
  const workspaceCandidates = selection?.targetCandidates || [];

  const workspaceResult = checkWorkspaces({
    repoRoot: ctx.repoRoot,
    candidates: workspaceCandidates,
    checkNativePlatformEvidence,
    extractPlatform,
    readFile: safeRead,
  });

  const findings = [
    ...checkProduct(ctx.product, ctx.productPath || 'PRODUCT.md'),
    ...(ctx.product
      ? checkNativePlatformEvidence({
          projectRoot,
          platform: ctx.platform,
          product: ctx.product,
          productPath: ctx.productPath,
        })
      : []),
    ...checkDesignSidecar({ designPath: absDesignPath, sidecarCandidates, projectRoot }),
    ...checkDesignDrift({ designPath: absDesignPath, projectRoot }),
    ...checkDesignCoverage({ design: ctx.design, designPath: ctx.designPath, parseDesignMd }),
    ...checkConfig({ projectRoot, repoRoot: ctx.repoRoot }),
    ...checkDetectorIgnores({ projectRoot, knownRuleIds }),
    ...checkSurfaceBriefs({ candidates: ctx.surfaceBriefCandidates, projectRoot }),
    ...checkHookInstallation({
      projectRoot,
      repoRoot: ctx.repoRoot,
      providerId: IMPECCABLE_PROVIDER_ID,
    }),
    ...checkLegacyLiveState({ projectRoot }),
    ...checkProjectRoots({
      patterns: readProjectRootPatterns(ctx.repoRoot),
      candidates: workspaceCandidates,
    }),
    ...workspaceResult.findings,
  ];

  return {
    ctx,
    projectRoot,
    absProductPath,
    sidecarCandidates,
    findings,
    workspaces: workspaceResult.workspaces,
    ruleRegistryAvailable: knownRuleIds !== null,
  };
}

// Read straight from disk rather than importing context.mjs's private reader.
// Only the positive/negative pattern strings matter here.
function readProjectRootPatterns(repoRoot) {
  if (!repoRoot) return [];
  const patterns = [];
  for (const name of ['config.json', 'config.local.json']) {
    try {
      const raw = JSON.parse(fs.readFileSync(path.join(repoRoot, '.impeccable', name), 'utf-8'));
      if (Array.isArray(raw?.projectRoots)) {
        for (const entry of raw.projectRoots) {
          if (typeof entry === 'string' && entry.trim()) patterns.push(entry.trim());
        }
      }
    } catch { /* missing or malformed: nothing to check */ }
  }
  return patterns;
}

/**
 * Apply the migrations that carry no decision. Returns what was done and what
 * was deliberately left for the user.
 */
function applyFixes(report) {
  const applied = [];
  const skipped = [];

  for (const entry of report.findings) {
    if (entry.severity !== 'auto') {
      skipped.push({ id: entry.id, reason: 'needs a decision from the user' });
      continue;
    }
    if (entry.id === 'design-sidecar-legacy-path') {
      const canonical = report.sidecarCandidates[0];
      const present = report.sidecarCandidates.find((candidate) => fs.existsSync(candidate));
      if (!canonical || !present || path.resolve(canonical) === path.resolve(present)) continue;
      if (fs.existsSync(canonical)) {
        skipped.push({ id: entry.id, reason: `${rel(canonical, report.projectRoot)} already exists; not overwriting` });
        continue;
      }
      fs.mkdirSync(path.dirname(canonical), { recursive: true });
      fs.renameSync(present, canonical);
      applied.push(`Moved ${rel(present, report.projectRoot)} to ${rel(canonical, report.projectRoot)}.`);
      continue;
    }
    if (entry.id === 'legacy-live-state') {
      // Reported, never deleted here: a running live session still reads these,
      // and losing session state to a doctor run is a worse outcome than a
      // stale file. The report says what to remove and when.
      skipped.push({ id: entry.id, reason: 'delete by hand once no live session is running' });
      continue;
    }
    skipped.push({ id: entry.id, reason: 'no automatic migration implemented' });
  }

  // Stamping the product record is additive and safe, and it is what stops a
  // later version proposing an interview the user has already sat through.
  const productPath = report.absProductPath;
  if (productPath && report.ctx.product && readProductSchemaVersion(report.ctx.product) === null
    && !report.findings.some((entry) => entry.id === 'product-schema-legacy')) {
    fs.writeFileSync(productPath, stampProductSchema(report.ctx.product), 'utf-8');
    applied.push(`Stamped ${rel(productPath, report.projectRoot)} as product-schema ${PRODUCT_SCHEMA_VERSION}.`);
  }

  return { applied, skipped };
}

function rel(filePath, root) {
  const value = path.relative(root, filePath);
  return value && !value.startsWith('..') ? value.split(path.sep).join('/') : filePath;
}

const SEVERITY_LABEL = {
  auto: 'automatic',
  mention: 'worth saying',
  route: 'needs a command',
};

function renderText(report, fixes) {
  const lines = [];
  const { findings } = report;

  lines.push(`Impeccable doctor: ${rel(report.projectRoot, process.cwd()) || '.'}`);
  if (report.ctx.isMonorepo) {
    lines.push(`Monorepo, repo root ${rel(report.ctx.repoRoot, process.cwd()) || '.'}.`);
  }
  lines.push('');

  if (!findings.length) {
    lines.push('No drift found. Every artifact matches what this version reads.');
  } else {
    const order = ['route', 'mention', 'auto'];
    for (const severity of order) {
      const group = findings.filter((entry) => entry.severity === severity);
      if (!group.length) continue;
      lines.push(`${SEVERITY_LABEL[severity]} (${group.length}):`);
      for (const entry of group) {
        lines.push(`  ${entry.id}${entry.path ? `  [${entry.path}]` : ''}`);
        lines.push(`    ${entry.summary}`);
        lines.push(`    → ${entry.fix}`);
      }
      lines.push('');
    }
  }

  if (report.workspaces.length) {
    lines.push('Workspaces:');
    for (const workspace of report.workspaces) {
      lines.push(`  ${workspace.path}  product: ${workspace.productStatus}`
        + `  design: ${workspace.designStatus}`
        + `${workspace.platform ? `  platform: ${workspace.platform}` : ''}`);
    }
    lines.push('');
  }

  if (!report.ruleRegistryAvailable) {
    lines.push('Note: the bundled detector could not be resolved, so ignored rule ids were not validated.');
    lines.push('');
  }

  if (fixes) {
    lines.push(fixes.applied.length ? 'Applied:' : 'Applied nothing.');
    for (const entry of fixes.applied) lines.push(`  ${entry}`);
    const held = fixes.skipped.filter((entry) => entry.reason !== 'needs a decision from the user');
    if (held.length) {
      lines.push('Left alone:');
      for (const entry of held) lines.push(`  ${entry.id}: ${entry.reason}`);
    }
  } else if (findings.some((entry) => entry.severity === 'auto')) {
    lines.push(`Run \`node doctor.mjs --fix\` to apply the automatic migrations, `
      + `or \`${IMPECCABLE_COMMAND} doctor\` to work through all of them.`);
  }

  return lines.join('\n');
}

async function cli() {
  let parsed;
  try {
    parsed = parseArgs(process.argv.slice(2));
  } catch (err) {
    process.stderr.write(`${err.message}\n`);
    process.exit(1);
  }
  if (parsed.flags.help) {
    process.stdout.write(`${usage()}\n`);
    return;
  }

  const report = await collect(process.cwd(), parsed.targetOptions);
  const fixes = parsed.flags.fix ? applyFixes(report) : null;

  if (parsed.flags.json) {
    process.stdout.write(`${JSON.stringify({
      projectRoot: report.projectRoot,
      repoRoot: report.ctx.repoRoot,
      isMonorepo: report.ctx.isMonorepo,
      productPath: report.ctx.productPath,
      designPath: report.ctx.designPath,
      platform: report.ctx.platform,
      ruleRegistryAvailable: report.ruleRegistryAvailable,
      findings: report.findings,
      workspaces: report.workspaces,
      ...(fixes ? { fixes } : {}),
    }, null, 2)}\n`);
    return;
  }

  process.stdout.write(`${renderText(report, fixes)}\n`);
}

function invokedAsScript() {
  const arg = process.argv[1];
  if (!arg) return false;
  try {
    return fs.realpathSync(arg) === fs.realpathSync(fileURLToPath(import.meta.url));
  } catch {
    return false;
  }
}

if (invokedAsScript()) {
  cli().catch((err) => {
    process.stderr.write(`impeccable doctor failed: ${err?.message || err}\n`);
    process.exit(1);
  });
}

export { collect, applyFixes, renderText };