arkgate 4.8.19 → 4.8.20

package/bin/lib/start-install-recovery.mjs

@@ -0,0 +1,156 @@
+/**
+ * Classified next steps when start / start --apply package install fails.
+ *
+ * Callers render `formatStartPackageInstallFailure`. Classification, Age window,
+ * pin-aware npx, and AgeExclude-must-be-in-config stay behind this module.
+ */
+import { spawnSync } from 'node:child_process';
+import { arkPackageRecoveryCommand } from './package-manager.mjs';
+
+const AGE_MARK = /ERR_PNPM_NO_MATURE_MATCHING_VERSION|minimumReleaseAge/i;
+const AGE_EXCLUDE_LINE =
+  'To add it locally later: put arkgate on minimumReleaseAgeExclude in pnpm config or pnpm-workspace.yaml (a CLI flag is not enough), or wait until the release is old enough.';
+const BIN_NOTE =
+  '`arkgate-check` is a command in the arkgate package — not its own npm package.';
+
+/**
+ * @param {unknown} hostOutput
+ * @returns {string[]}
+ */
+function hostOutputTail(hostOutput) {
+  if (!hostOutput || !String(hostOutput).trim()) return [];
+  return String(hostOutput)
+    .split('\n')
+    .map((line) => line.trimEnd())
+    .filter((line) => line.trim())
+    .slice(-6);
+}
+
+/**
+ * Exact npm version for `npx --package=arkgate@<pin>` when Age blocked add.
+ * @param {string|undefined} packageVersion
+ * @param {string|undefined} installCommand
+ * @returns {string|null}
+ */
+export function resolveStartInstallPackagePin(packageVersion, installCommand) {
+  const fromArg = String(packageVersion ?? '')
+    .trim()
+    .replace(/^arkgate@/i, '')
+    .replace(/^\^/, '')
+    .replace(/^v/i, '');
+  if (/^\d+\.\d+\.\d+/.test(fromArg)) return fromArg.match(/^\d+\.\d+\.\d+/)?.[0] ?? null;
+  const fromCmd = String(installCommand ?? '').match(/arkgate@\^?v?(\d+\.\d+\.\d+)/i);
+  return fromCmd?.[1] ?? null;
+}
+
+/**
+ * @typedef {{ kind: 'pnpm-age', ageWindow: string, headline: string }} PnpmAgeInstallFailure
+ * @typedef {{ kind: 'generic', hostTail: string[] }} GenericInstallFailure
+ * @typedef {PnpmAgeInstallFailure | GenericInstallFailure} ClassifiedStartInstallFailure
+ */
+
+/**
+ * Classify captured package-manager stdout+stderr. Age is one class.
+ * @param {unknown} hostOutput
+ * @returns {ClassifiedStartInstallFailure}
+ */
+export function classifyStartInstallFailure(hostOutput) {
+  const text = String(hostOutput ?? '');
+  if (AGE_MARK.test(text)) {
+    const days = text.match(/(\d+)\s*days?/i)?.[1];
+    const ageWindow = days ? `${days} days` : 'a cooling-off window';
+    const headline = days
+      ? `This repo waits before trusting new npm packages (pnpm Age — ${days} days).`
+      : 'This repo waits before trusting new npm packages (pnpm Age).';
+    return { kind: 'pnpm-age', ageWindow, headline };
+  }
+  return { kind: 'generic', hostTail: hostOutputTail(text) };
+}
+
+/**
+ * Plain Age headline, or null. Kept for the #268 one-liner tests.
+ * @param {unknown} hostOutput
+ * @returns {string|null}
+ */
+export function explainPnpmMaturityBlock(hostOutput) {
+  const classified = classifyStartInstallFailure(hostOutput);
+  return classified.kind === 'pnpm-age' ? classified.headline : null;
+}
+
+/**
+ * @typedef {{
+ *   kind: 'pnpm-age' | 'generic',
+ *   ageWindow?: string,
+ *   primaryCommand: string,
+ *   replayInstallCommand: string | null,
+ *   lines: string[],
+ * }} StartInstallRecovery
+ */
+
+/**
+ * Typed next-step for a failed start package install.
+ * Age never replays the doomed add; generic still names the exact command.
+ * @param {{
+ *   exitStatus: number,
+ *   installCommand: string,
+ *   hostOutput?: string,
+ *   packageVersion?: string,
+ * }} input
+ * @returns {StartInstallRecovery}
+ */
+export function startInstallRecovery(input) {
+  const exitStatus = input?.exitStatus ?? 1;
+  const installCommand = input?.installCommand ?? '';
+  const classified = classifyStartInstallFailure(input?.hostOutput);
+  const pin = resolveStartInstallPackagePin(input?.packageVersion, installCommand);
+  const honesty = `Package install failed (exit ${exitStatus}). Setup files are written; the local command is not installed yet.`;
+  if (classified.kind === 'pnpm-age') {
+    const doctor = arkPackageRecoveryCommand(
+      'arkgate-check',
+      '--doctor',
+      pin ? `arkgate@${pin}` : undefined
+    );
+    return {
+      kind: 'pnpm-age',
+      ageWindow: classified.ageWindow,
+      primaryCommand: doctor,
+      replayInstallCommand: null,
+      lines: [classified.headline, honesty, `  ${doctor}`, BIN_NOTE, AGE_EXCLUDE_LINE],
+    };
+  }
+  const doctor = arkPackageRecoveryCommand('arkgate-check', '--doctor');
+  return {
+    kind: 'generic',
+    primaryCommand: installCommand,
+    replayInstallCommand: installCommand,
+    lines: [...classified.hostTail, honesty, `  ${installCommand}`, `  ${doctor}`, BIN_NOTE],
+  };
+}
+
+/**
+ * Red next-step when post-apply package install fails.
+ * Host files may already be written; local bins may be missing.
+ * @param {{
+ *   exitStatus: number,
+ *   installCommand: string,
+ *   hostOutput?: string,
+ *   packageVersion?: string,
+ * }} input
+ */
+export function formatStartPackageInstallFailure(input) {
+  return startInstallRecovery(input).lines.join('\n');
+}
+
+/** Pipe the package manager so recovery can hide maturity internals. */
+export function runStartPackageInstall(command, commandArgs, cwd) {
+  const result = spawnSync(command, commandArgs, {
+    cwd,
+    stdio: ['ignore', 'pipe', 'pipe'],
+    encoding: 'utf8',
+  });
+  return {
+    status: result.status ?? 1,
+    stdout: result.stdout ?? '',
+    stderr: result.stderr ?? '',
+  };
+}

package/bin/lib/start-preview.mjs

@@ -5,7 +5,6 @@ import os from 'node:os';
 import path from 'node:path';
 import {
   arkCommand,
-  arkPackageRecoveryCommand,
   buildArchitectureRecommendation,
   START_APPLY_REFUSE_FOOTER,
 } from '../ark-shared.mjs';
@@ -218,59 +217,6 @@ function commands(root, args, helpers) {
   return result;
 }
 
-/**
- * Plain one-liner for pnpm minimumReleaseAge / ERR_PNPM_NO_MATURE_MATCHING_VERSION.
- * Host dumps stay out of the recovery — stranger needs one next step.
- */
-export function explainPnpmMaturityBlock(hostOutput) {
-  const text = String(hostOutput ?? '');
-  if (!/ERR_PNPM_NO_MATURE_MATCHING_VERSION|minimumReleaseAge/i.test(text)) return null;
-  const days = text.match(/(\d+)\s*days?/i)?.[1];
-  const window = days ? `${days} days` : 'a cooling-off window';
-  return `This repo blocks packages younger than ${window} — pin an older release or exclude arkgate temporarily.`;
-}
-
-/** Pipe the package manager so recovery can hide maturity internals. */
-export function runStartPackageInstall(command, commandArgs, cwd) {
-  const result = spawnSync(command, commandArgs, {
-    cwd,
-    stdio: ['ignore', 'pipe', 'pipe'],
-    encoding: 'utf8',
-  });
-  return {
-    status: result.status ?? 1,
-    stdout: result.stdout ?? '',
-    stderr: result.stderr ?? '',
-  };
-}
-
-/**
- * Red next-step when post-apply package install fails.
- * Host files may already be written; local bins may be missing.
- */
-export function formatStartPackageInstallFailure({ exitStatus, installCommand, hostOutput }) {
-  const doctor = arkPackageRecoveryCommand('arkgate-check', '--doctor');
-  const maturity = explainPnpmMaturityBlock(hostOutput);
-  const lines = [];
-  if (maturity) {
-    lines.push(maturity);
-  } else if (hostOutput && String(hostOutput).trim()) {
-    const tail = String(hostOutput)
-      .split('\n')
-      .map((line) => line.trimEnd())
-      .filter((line) => line.trim())
-      .slice(-6);
-    if (tail.length) lines.push(...tail);
-  }
-  lines.push(
-    `Package install failed (exit ${exitStatus}). Setup files are written; the local command is not installed yet.`,
-    `  ${installCommand}`,
-    `  ${doctor}`,
-    '`arkgate-check` is a command in the arkgate package — not its own npm package.'
-  );
-  return lines.join('\n');
-}
-
 /**
  * @param {object} preview
  * @param {{ applying?: boolean }} [options] when applying=true, do not claim “no files were changed”

package/dist/{configTypes-VD0qcubY.d.ts → configTypes-VVknqcTJ.d.ts}

@@ -60,6 +60,8 @@ type ArkConfigRule = {
     sharedRoots?: string[];
     /** Directed slice→slice edges the repo declares on purpose. */
     allowedCrossSlice?: ArkConfigCrossSliceEdge[];
+    /** When `"deny"`, a declared shared root may not import a slice. */
+    sharedImportsSlice?: 'deny';
 };
 type ArkConfigCrossSliceEdge = {
     from: string;

package/dist/{diagnosticCatalog-D2v0ASN2.d.ts → diagnosticCatalog-BPYWNyJR.d.ts}

@@ -1,5 +1,5 @@
-import { e as CreateArchitectureProfileOptions, b as ArchitectureProfile, d as ArkCheckConfig, C as CreateArchitectureProfileFromArkConfigOptions, f as CreateElevenLayerArkConfigOptions, i as Policy, j as IntentCreator, I as IntentName } from './types-D5GT5ZT8.js';
-import { A as ArkConfig, c as ArkConfigLoadResult } from './configTypes-VD0qcubY.js';
+import { e as CreateArchitectureProfileOptions, b as ArchitectureProfile, d as ArkCheckConfig, C as CreateArchitectureProfileFromArkConfigOptions, f as CreateElevenLayerArkConfigOptions, i as Policy, j as IntentCreator, I as IntentName } from './types-p_fCp6P-.js';
+import { A as ArkConfig, c as ArkConfigLoadResult } from './configTypes-VVknqcTJ.js';
 
 /** Versioned public result contract types + JSON Schema (adapter envelope). */
 /**
@@ -392,7 +392,7 @@ declare function createAdapterResult(input: {
 }): CurrentAdapterResult;
 
 /** ArkGate library version — single source of truth. */
-declare const version = "4.8.19";
+declare const version = "4.8.20";
 
 /**
  * AI Code Gate (basic).
@@ -1738,6 +1738,12 @@ type InvariantCoverageEvidence = {
     description: string;
     /** Test file that supplied the `test-title` evidence, when there was one. */
     testEvidenceFile?: string;
+    /**
+     * Non-test file that declares `coverage.symbol`. Absent when the name only
+     * appears in an import or a call. ArkGate never runs tests; this path is the
+     * declaration text, not a passing suite.
+     */
+    symbolEvidenceFile?: string;
     /**
      * The only covering test found sits outside `coverage.coverageRoots` — the
      * places the project declares its runner executes. ArkGate never runs tests,