@hifullmoon/aicommit 1.4.0

package/src/metrics.js

@@ -0,0 +1,375 @@
+import { appendFile, chmod, mkdir, readFile, rename, unlink, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+
+import chalk from 'chalk';
+
+export const DEFAULT_METRICS = Object.freeze({
+  enabled: true,
+  path: '',
+  maxEntries: 500,
+});
+
+let activeSettings = null;
+const METRIC_RESULTS = new Set([
+  'committed',
+  'dry_run',
+  'cancelled',
+  'config',
+  'git_state',
+  'network',
+  'provider',
+  'response_format',
+  'sensitive_data',
+  'concurrent_modification',
+  'internal',
+  'unknown',
+]);
+
+export function metricsPath(settings = DEFAULT_METRICS, home = homedir()) {
+  return settings.path || join(home, '.aicommit', 'metrics.jsonl');
+}
+
+export function configureMetrics(settings) {
+  activeSettings = { ...DEFAULT_METRICS, ...settings };
+}
+
+function safeUsage(usage) {
+  if (!usage) return null;
+  const safe = {};
+  for (const key of ['inputTokens', 'outputTokens', 'totalTokens']) {
+    if (typeof usage[key] === 'number' && Number.isFinite(usage[key]) && usage[key] >= 0) {
+      safe[key] = usage[key];
+    }
+  }
+  return Object.keys(safe).length ? safe : null;
+}
+
+export function minimizeMetric(input = {}) {
+  const result = METRIC_RESULTS.has(input.result) ? input.result : 'unknown';
+  return {
+    durationMs:
+      typeof input.durationMs === 'number' && Number.isFinite(input.durationMs)
+        ? Math.max(0, Math.round(input.durationMs))
+        : null,
+    usage: safeUsage(input.usage),
+    result,
+    edited: Boolean(input.edited),
+    rewrites:
+      Number.isInteger(input.rewrites) && input.rewrites >= 0 ? Math.min(input.rewrites, 1000) : 0,
+  };
+}
+
+async function trimMetrics(path, maxEntries) {
+  const text = await readFile(path, 'utf8');
+  const lines = text.split('\n').filter(Boolean);
+  if (lines.length <= maxEntries) return;
+
+  const tempPath = `${path}.${process.pid}.${Date.now()}.tmp`;
+  try {
+    await writeFile(tempPath, lines.slice(-maxEntries).join('\n') + '\n', {
+      encoding: 'utf8',
+      mode: 0o600,
+    });
+    await rename(tempPath, path);
+    await chmod(path, 0o600).catch(() => {});
+  } catch (err) {
+    await unlink(tempPath).catch(() => {});
+    throw err;
+  }
+}
+
+export async function recordMetric(input, settings = activeSettings) {
+  if (!settings?.enabled) return false;
+  const path = metricsPath(settings);
+  await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+  await appendFile(path, JSON.stringify(minimizeMetric(input)) + '\n', {
+    encoding: 'utf8',
+    mode: 0o600,
+  });
+  await chmod(path, 0o600).catch(() => {});
+  await trimMetrics(path, settings.maxEntries || DEFAULT_METRICS.maxEntries);
+  return true;
+}
+
+async function readUserMetricsConfig(path) {
+  try {
+    const parsed = JSON.parse(await readFile(path, 'utf8'));
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+      throw new Error('expected a JSON object');
+    }
+    return parsed;
+  } catch (err) {
+    if (err.code === 'ENOENT') return {};
+    throw new Error(`Failed to read user config ${path}: ${err.message}`);
+  }
+}
+
+async function writeUserConfig(path, config) {
+  const tempPath = `${path}.${process.pid}.${Date.now()}.tmp`;
+  try {
+    await writeFile(tempPath, JSON.stringify(config, null, 2) + '\n', {
+      encoding: 'utf8',
+      mode: 0o600,
+    });
+    await rename(tempPath, path);
+    await chmod(path, 0o600).catch(() => {});
+  } catch (err) {
+    await unlink(tempPath).catch(() => {});
+    throw err;
+  }
+}
+
+async function metricCount(path) {
+  try {
+    return (await readFile(path, 'utf8')).split('\n').filter(Boolean).length;
+  } catch (err) {
+    if (err.code === 'ENOENT') return 0;
+    throw err;
+  }
+}
+
+export async function readMetricRecords(path) {
+  let textValue;
+  try {
+    textValue = await readFile(path, 'utf8');
+  } catch (err) {
+    if (err.code === 'ENOENT') return { records: [], invalid: 0 };
+    throw err;
+  }
+  const records = [];
+  let invalid = 0;
+  for (const line of textValue.split('\n')) {
+    if (!line.trim()) continue;
+    try {
+      const parsed = JSON.parse(line);
+      if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        invalid++;
+        continue;
+      }
+      records.push(minimizeMetric(parsed));
+    } catch {
+      invalid++;
+    }
+  }
+  return { records, invalid };
+}
+
+function average(values) {
+  return values.length ? values.reduce((sum, value) => sum + value, 0) / values.length : null;
+}
+
+function percentile(values, ratio) {
+  if (!values.length) return null;
+  const sorted = [...values].sort((a, b) => a - b);
+  return sorted[Math.ceil((sorted.length - 1) * ratio)];
+}
+
+function percent(part, whole) {
+  return whole ? (part / whole) * 100 : null;
+}
+
+function relativeChange(previous, recent) {
+  if (previous === null || recent === null || previous === 0) return null;
+  return ((recent - previous) / previous) * 100;
+}
+
+function tokenTotal(record) {
+  const usage = record.usage;
+  if (!usage) return null;
+  if (typeof usage.totalTokens === 'number') return usage.totalTokens;
+  if (typeof usage.inputTokens === 'number' && typeof usage.outputTokens === 'number') {
+    return usage.inputTokens + usage.outputTokens;
+  }
+  return null;
+}
+
+function halves(records) {
+  if (records.length < 2) return [[], records];
+  const split = Math.floor(records.length / 2);
+  return [records.slice(0, split), records.slice(split)];
+}
+
+function windowQuality(records) {
+  const changed = records.filter((record) => record.edited || record.rewrites > 0).length;
+  return { runs: records.length, changed, rate: percent(changed, records.length) };
+}
+
+export function summarizeMetrics(inputRecords) {
+  const records = (inputRecords || []).map((record) => minimizeMetric(record));
+  const successful = records.filter((record) => ['committed', 'dry_run'].includes(record.result));
+  const failed = records.filter(
+    (record) => !['committed', 'dry_run', 'cancelled'].includes(record.result),
+  );
+  const edited = records.filter((record) => record.edited);
+  const rewritten = records.filter((record) => record.rewrites > 0);
+  const acceptedFirstPass = successful.filter((record) => !record.edited && record.rewrites === 0);
+  const durations = records
+    .map((record) => record.durationMs)
+    .filter((value) => typeof value === 'number');
+  const tokens = records.map(tokenTotal).filter((value) => typeof value === 'number');
+  const [previousRecords, recentRecords] = halves(records);
+  const previousDurations = previousRecords
+    .map((record) => record.durationMs)
+    .filter((value) => typeof value === 'number');
+  const recentDurations = recentRecords
+    .map((record) => record.durationMs)
+    .filter((value) => typeof value === 'number');
+  const previousTokens = previousRecords
+    .map(tokenTotal)
+    .filter((value) => typeof value === 'number');
+  const recentTokens = recentRecords.map(tokenTotal).filter((value) => typeof value === 'number');
+  const [previousSuccess, recentSuccess] = halves(successful);
+  const previousQuality = windowQuality(previousSuccess);
+  const recentQuality = windowQuality(recentSuccess);
+  const qualityImprovement =
+    previousQuality.rate === null || recentQuality.rate === null || previousQuality.rate === 0
+      ? null
+      : ((previousQuality.rate - recentQuality.rate) / previousQuality.rate) * 100;
+
+  return {
+    runs: records.length,
+    outcomes: {
+      committed: records.filter((record) => record.result === 'committed').length,
+      dryRuns: records.filter((record) => record.result === 'dry_run').length,
+      acceptedFirstPass: acceptedFirstPass.length,
+      edited: edited.length,
+      rewritten: rewritten.length,
+      rewriteCount: records.reduce((sum, record) => sum + record.rewrites, 0),
+      failed: failed.length,
+      cancelled: records.filter((record) => record.result === 'cancelled').length,
+    },
+    rates: {
+      firstPassAcceptance: percent(acceptedFirstPass.length, successful.length),
+      editOrRewrite: percent(
+        successful.filter((record) => record.edited || record.rewrites > 0).length,
+        successful.length,
+      ),
+      failure: percent(failed.length, records.length),
+    },
+    latency: {
+      count: durations.length,
+      averageMs: average(durations),
+      p50Ms: percentile(durations, 0.5),
+      p95Ms: percentile(durations, 0.95),
+      previousAverageMs: average(previousDurations),
+      recentAverageMs: average(recentDurations),
+      relativeChangePercent: relativeChange(average(previousDurations), average(recentDurations)),
+    },
+    tokens: {
+      count: tokens.length,
+      total: tokens.reduce((sum, value) => sum + value, 0),
+      average: average(tokens),
+      previousAverage: average(previousTokens),
+      recentAverage: average(recentTokens),
+      relativeChangePercent: relativeChange(average(previousTokens), average(recentTokens)),
+    },
+    qualityTrend: {
+      baselineReady: previousSuccess.length >= 5 && recentSuccess.length >= 5,
+      previous: previousQuality,
+      recent: recentQuality,
+      relativeImprovementPercent: qualityImprovement,
+      targetMet: qualityImprovement !== null && qualityImprovement >= 20,
+    },
+  };
+}
+
+function renderPercent(value) {
+  return value === null ? 'n/a' : `${value.toFixed(1)}%`;
+}
+
+function renderDuration(value) {
+  if (value === null) return 'n/a';
+  return value < 1000 ? `${Math.round(value)}ms` : `${(value / 1000).toFixed(1)}s`;
+}
+
+function renderNumber(value) {
+  return value === null ? 'n/a' : Math.round(value).toLocaleString('en-US');
+}
+
+export async function runStatsCommand(action = 'show', options = {}) {
+  if (['clear', 'enable', 'disable'].includes(action)) {
+    return updateMetrics(action, options);
+  }
+  const home = options.home || homedir();
+  const userConfigPath = options.userConfigPath || join(home, '.aicommit.config.json');
+  const existing = await readUserMetricsConfig(userConfigPath);
+  const settings = { ...DEFAULT_METRICS, ...existing.metrics };
+  const path = metricsPath(settings, home);
+  const { records, invalid } = await readMetricRecords(path);
+  const stats = summarizeMetrics(records);
+
+  console.log('');
+  console.log('  ' + chalk.cyan.bold('Local quality stats'));
+  console.log(`  Status:      ${settings.enabled ? 'enabled' : 'disabled'}`);
+  console.log(
+    `  Runs:        ${stats.runs}${invalid ? ` (${invalid} invalid line(s) ignored)` : ''}`,
+  );
+  console.log(
+    `  First pass:  ${stats.outcomes.acceptedFirstPass} (${renderPercent(stats.rates.firstPassAcceptance)})`,
+  );
+  console.log(`  Edited:      ${stats.outcomes.edited}`);
+  console.log(
+    `  Rewritten:   ${stats.outcomes.rewritten} run(s), ${stats.outcomes.rewriteCount} rewrite(s)`,
+  );
+  console.log(`  Failed:      ${stats.outcomes.failed} (${renderPercent(stats.rates.failure)})`);
+  console.log(
+    `  Latency:     P50 ${renderDuration(stats.latency.p50Ms)}, P95 ${renderDuration(stats.latency.p95Ms)}, ` +
+      `recent ${renderPercent(stats.latency.relativeChangePercent)}`,
+  );
+  console.log(
+    `  Tokens:      total ${renderNumber(stats.tokens.total)}, average ${renderNumber(stats.tokens.average)}, ` +
+      `recent ${renderPercent(stats.tokens.relativeChangePercent)}`,
+  );
+  if (stats.qualityTrend.baselineReady) {
+    console.log(
+      `  Edit/rewrite: previous ${renderPercent(stats.qualityTrend.previous.rate)} → ` +
+        `recent ${renderPercent(stats.qualityTrend.recent.rate)}; relative improvement ` +
+        `${renderPercent(stats.qualityTrend.relativeImprovementPercent)} ` +
+        `(20% target ${stats.qualityTrend.targetMet ? 'met' : 'not yet met'})`,
+    );
+  } else {
+    console.log(
+      '  Edit/rewrite: collect at least 10 successful runs to establish two baseline windows',
+    );
+  }
+  console.log(`  Path:        ${path}`);
+  console.log(
+    '  Privacy:     local only; no messages, diffs, reasoning, file names, providers, or models',
+  );
+  console.log('');
+  return { action, path, enabled: settings.enabled, invalid, stats };
+}
+
+async function updateMetrics(action, options = {}) {
+  const home = options.home || homedir();
+  const userConfigPath = options.userConfigPath || join(home, '.aicommit.config.json');
+  const existing = await readUserMetricsConfig(userConfigPath);
+  const settings = { ...DEFAULT_METRICS, ...existing.metrics };
+  const path = metricsPath(settings, home);
+
+  if (action === 'clear') {
+    const count = await metricCount(path);
+    await unlink(path).catch((err) => {
+      if (err.code !== 'ENOENT') throw err;
+    });
+    console.log(
+      `  ${chalk.green('✓')} Cleared ${count} local metric record(s): ${path} ` +
+        chalk.dim('(cannot be recovered)'),
+    );
+    return { action, count, path, enabled: settings.enabled };
+  }
+
+  if (action === 'enable' || action === 'disable') {
+    const enabled = action === 'enable';
+    const updated = {
+      ...existing,
+      metrics: { ...existing.metrics, enabled },
+    };
+    await writeUserConfig(userConfigPath, updated);
+    console.log(`  ${chalk.green('✓')} Local metrics ${enabled ? 'enabled' : 'disabled'}.`);
+    return { action, count: await metricCount(path), path, enabled };
+  }
+
+  throw new Error(`Unsupported stats action: ${action}`);
+}

package/src/output.js

@@ -0,0 +1,87 @@
+import { classifyError, EXIT_CODES } from './errors.js';
+
+export const OUTPUT_SCHEMA_VERSION = '1.0';
+
+function normalizedUsage(usage) {
+  if (!usage) return null;
+  const value = {};
+  for (const key of ['inputTokens', 'outputTokens', 'totalTokens']) {
+    if (typeof usage[key] === 'number' && Number.isFinite(usage[key])) value[key] = usage[key];
+  }
+  return Object.keys(value).length ? value : null;
+}
+
+function normalizedPlan(plan) {
+  if (!Array.isArray(plan)) return null;
+  return plan.map((item) => ({
+    message: String(item?.message || ''),
+    files: Array.isArray(item?.files) ? item.files.map(String) : [],
+    ...(Array.isArray(item?.hunks)
+      ? {
+          hunks: item.hunks.map((assignment) => ({
+            path: String(assignment?.path || ''),
+            ids: Array.isArray(assignment?.ids) ? assignment.ids.map(String) : [],
+          })),
+        }
+      : {}),
+  }));
+}
+
+export function successOutput(result = {}) {
+  const output = {
+    schemaVersion: OUTPUT_SCHEMA_VERSION,
+    ok: true,
+    message: typeof result.message === 'string' ? result.message : null,
+    plan: normalizedPlan(result.plan),
+    provider: result.provider || null,
+    model: result.model || null,
+    latencyMs:
+      typeof result.latencyMs === 'number' && Number.isFinite(result.latencyMs)
+        ? result.latencyMs
+        : null,
+    usage: normalizedUsage(result.usage),
+    warnings: Array.isArray(result.warnings) ? result.warnings.map(String) : [],
+    exitReason: result.exitReason || 'success',
+    committed: Boolean(result.committed),
+    error: null,
+  };
+  if (result.data && typeof result.data === 'object' && !Array.isArray(result.data)) {
+    output.data = result.data;
+  }
+  return output;
+}
+
+export function errorOutput(err) {
+  const classified = classifyError(err);
+  const output = {
+    schemaVersion: OUTPUT_SCHEMA_VERSION,
+    ok: false,
+    message: null,
+    plan: null,
+    provider: null,
+    model: null,
+    latencyMs: null,
+    usage: null,
+    warnings: [],
+    exitReason: classified.category,
+    committed: false,
+    error: {
+      category: classified.category,
+      message: classified.message,
+    },
+  };
+  if (classified.data && typeof classified.data === 'object' && !Array.isArray(classified.data)) {
+    output.data = classified.data;
+  }
+  return output;
+}
+
+export function exitCodeFor(err) {
+  return classifyError(err).exitCode ?? EXIT_CODES.internal;
+}
+
+export function isJsonOutputRequested(args = process.argv.slice(2)) {
+  return args.some(
+    (arg, index) => arg === '--output=json' || (arg === '--output' && args[index + 1] === 'json'),
+  );
+}

package/src/policy-command.js

@@ -0,0 +1,172 @@
+import { createHash } from 'node:crypto';
+import { lstat, readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+
+import { loadConfig } from './config.js';
+import {
+  applyCommitlintPolicy,
+  DEFAULT_REPOSITORY_CONTEXT,
+  detectCommitlintConstraints,
+} from './context.js';
+import { ERROR_CATEGORIES, fail } from './errors.js';
+import { readGit } from './git.js';
+import { normalizeCommitPolicy, validateCommitCandidate } from './policy.js';
+import { renderTeamPolicyTemplate } from './team-policy.js';
+
+const MAX_MESSAGE_FILE_BYTES = 1024 * 1024;
+const MAX_RANGE_OUTPUT_BYTES = 8 * 1024 * 1024;
+const MAX_RANGE_COMMITS = 1000;
+
+function normalizedPolicyDocument(policy) {
+  return {
+    version: policy.version,
+    types: [...policy.types],
+    scope: { mode: policy.scope.mode, values: [...policy.scope.values] },
+    subject: { maxLength: policy.subject.maxLength },
+    body: { mode: policy.body.mode, maxLines: policy.body.maxLines },
+    breakingChange: policy.breakingChange,
+    language: policy.language,
+    effectiveLanguage: policy.effectiveLanguage,
+  };
+}
+
+function policyFingerprint(policy) {
+  return createHash('sha256')
+    .update(JSON.stringify(normalizedPolicyDocument(policy)))
+    .digest('hex');
+}
+
+async function messageFromFile(path) {
+  const absolutePath = resolve(path);
+  let info;
+  try {
+    info = await lstat(absolutePath);
+  } catch (err) {
+    throw fail(ERROR_CATEGORIES.CONFIG, `Cannot read policy message file: ${path}`, { cause: err });
+  }
+  if (!info.isFile() || info.isSymbolicLink()) {
+    throw fail(ERROR_CATEGORIES.CONFIG, `Policy message file must be a regular file: ${path}`);
+  }
+  if (info.size > MAX_MESSAGE_FILE_BYTES) {
+    throw fail(ERROR_CATEGORIES.CONFIG, `Policy message file exceeds 1 MiB: ${path}`);
+  }
+  try {
+    return [{ id: 'message-file', message: await readFile(absolutePath, 'utf8') }];
+  } catch (err) {
+    throw fail(ERROR_CATEGORIES.CONFIG, `Cannot read policy message file: ${path}`, { cause: err });
+  }
+}
+
+function messagesFromRange(projectRoot, range) {
+  if (
+    typeof range !== 'string' ||
+    !range ||
+    range.length > 512 ||
+    range.startsWith('-') ||
+    /[\0\r\n]/.test(range)
+  ) {
+    throw fail(ERROR_CATEGORIES.CONFIG, 'Policy Git range is invalid.');
+  }
+  const output = readGit(
+    ['log', '-z', '--format=%H%x00%B', range, '--'],
+    projectRoot,
+    MAX_RANGE_OUTPUT_BYTES,
+  );
+  const fields = output.split('\0');
+  if (fields.at(-1) === '') fields.pop();
+  if (fields.length % 2 !== 0) {
+    throw fail(ERROR_CATEGORIES.GIT_STATE, 'Git returned a malformed commit-message stream.');
+  }
+  const messages = [];
+  for (let index = 0; index < fields.length; index += 2) {
+    messages.push({ id: fields[index], message: fields[index + 1] });
+  }
+  if (!messages.length) {
+    throw fail(ERROR_CATEGORIES.GIT_STATE, `Git range contains no commits: ${range}`);
+  }
+  if (messages.length > MAX_RANGE_COMMITS) {
+    throw fail(
+      ERROR_CATEGORIES.CONFIG,
+      `Policy check is limited to ${MAX_RANGE_COMMITS} commits per run.`,
+    );
+  }
+  return messages;
+}
+
+function resultFor(entry, policy) {
+  // Team checks treat the resolved repository language as an explicit rule,
+  // even when the document says "inherit" inside commitPolicy.
+  const validation = validateCommitCandidate(entry.message, {
+    policy: { ...policy, language: policy.effectiveLanguage },
+  });
+  return {
+    id: entry.id,
+    valid: validation.valid,
+    issues: validation.issues.map(({ code, message, severity }) => ({ code, message, severity })),
+  };
+}
+
+function printResults(data) {
+  console.log(`Policy: commitPolicy v${data.policy.version} (${data.policyFingerprint})`);
+  for (const result of data.results) {
+    console.log(`${result.valid ? '✓' : '✗'} ${result.id}`);
+    for (const issue of result.issues) {
+      console.log(`  ${issue.severity}: ${issue.code}: ${issue.message}`);
+    }
+  }
+  console.log(
+    data.valid
+      ? `Policy valid for ${data.results.length} commit message(s).`
+      : `Policy violations found in ${data.invalidCount} commit message(s).`,
+  );
+}
+
+export async function runPolicyCommand(
+  action,
+  { messageFile = null, range = null, machineOutput = false } = {},
+) {
+  if (action === 'template') {
+    process.stdout.write(renderTeamPolicyTemplate());
+    return { exitReason: 'policy_template' };
+  }
+
+  const loaded = await loadConfig(null, { resolveCredentials: false });
+  const constraints = detectCommitlintConstraints(
+    loaded.projectRoot,
+    DEFAULT_REPOSITORY_CONTEXT.commitlint,
+  );
+  const effective = applyCommitlintPolicy(
+    loaded.config.commitPolicy,
+    constraints,
+    loaded.config.language,
+  );
+  const policy = normalizeCommitPolicy(effective, loaded.config.language);
+  const entries = messageFile
+    ? await messageFromFile(messageFile)
+    : messagesFromRange(loaded.projectRoot, range || 'HEAD');
+  const results = entries.map((entry) => resultFor(entry, policy));
+  const invalidCount = results.filter((result) => !result.valid).length;
+  const machineResults = results.map((result) => ({
+    id: result.id,
+    valid: result.valid,
+    issues: result.issues.map(({ code, severity }) => ({ code, severity })),
+  }));
+  const data = {
+    valid: invalidCount === 0,
+    invalidCount,
+    policy: normalizedPolicyDocument(policy),
+    policyFingerprint: policyFingerprint(policy),
+    source: messageFile ? 'file' : 'git-range',
+    range: messageFile ? null : range || 'HEAD',
+    commitlintSource: constraints?.path || null,
+    results: machineResults,
+  };
+  if (!machineOutput) printResults({ ...data, results });
+  if (invalidCount) {
+    throw fail(ERROR_CATEGORIES.CONFIG, `Team policy rejected ${invalidCount} commit message(s).`, {
+      reported: !machineOutput,
+      data,
+    });
+  }
+  return { exitReason: 'policy_valid', data };
+}