arkgate 4.0.0 → 4.1.0

package/bin/lib/project-root.mjs

@@ -0,0 +1,268 @@
+/**
+ * Effective project root for ark-check / doctor.
+ *
+ * Monorepo honesty (NEW-MONOREPO-CWD-WALKUP): when cwd (or --root) has no
+ * ark.config.json, walk parent directories until one is found. Never invent a
+ * silent 11-layer / empty ADAPT world while a parent monorepo contract exists.
+ *
+ * Security (S0 walk-up review):
+ * - Split **config discovery root** from **write root**.
+ * - Walk-up is for read/doctor/check by default.
+ * - Mutating commands stay on explicit --root/cwd unless --follow-config-root.
+ * - Walk is bounded by git root, workspaces package root, and max depth.
+ * - Config write paths must stay under the write root (no --config ../outside).
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+/** Safety cap so a pathological tree cannot walk forever. */
+export const MAX_CONFIG_WALK_DEPTH = 32;
+
+/**
+ * True when dir looks like a package-manager workspaces / monorepo root.
+ * Used as an upper bound for walk-up (config at this root is accepted; parents are not).
+ * @param {string} dir
+ */
+export function isWorkspacesPackageRoot(dir) {
+  const pkgPath = path.join(dir, 'package.json');
+  try {
+    if (!fs.statSync(pkgPath, { throwIfNoEntry: false })?.isFile()) {
+      // still check workspace marker files below
+    } else {
+      const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+      if (
+        pkg &&
+        (Array.isArray(pkg.workspaces) ||
+          (pkg.workspaces && typeof pkg.workspaces === 'object'))
+      ) {
+        return true;
+      }
+    }
+  } catch {
+    // ignore
+  }
+  for (const marker of ['pnpm-workspace.yaml', 'lerna.json', 'rush.json', 'nx.json']) {
+    try {
+      if (fs.statSync(path.join(dir, marker), { throwIfNoEntry: false })?.isFile()) return true;
+    } catch {
+      // ignore
+    }
+  }
+  return false;
+}
+
+/**
+ * True when dir is a git worktree root (.git file or directory).
+ * @param {string} dir
+ */
+export function isGitRoot(dir) {
+  try {
+    const git = path.join(dir, '.git');
+    const st = fs.statSync(git, { throwIfNoEntry: false });
+    return Boolean(st && (st.isDirectory() || st.isFile()));
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Resolve config path and require it is under projectRoot (or equal).
+ * Used by mutative paths (migrate-contract --write, init --force, etc.).
+ *
+ * @param {string} projectRoot
+ * @param {string} configPathOrName absolute path or relative name
+ * @returns {{ ok: true, configPath: string } | { ok: false, error: string, configPath: string }}
+ */
+export function resolveConfigPathWithinRoot(projectRoot, configPathOrName) {
+  const root = path.resolve(projectRoot || process.cwd());
+  const raw = configPathOrName || 'ark.config.json';
+  const configPath = path.isAbsolute(raw) ? path.resolve(raw) : path.resolve(root, raw);
+  const rel = path.relative(root, configPath);
+  if (rel.startsWith('..') || path.isAbsolute(rel)) {
+    return {
+      ok: false,
+      configPath,
+      error: `Refusing config path outside project root: ${configPath} (root ${root}). Pass a path under --root, or only use --follow-config-root when intentional monorepo writes are required.`,
+    };
+  }
+  return { ok: true, configPath };
+}
+
+/**
+ * Walk parents from startDir looking for configName (default ark.config.json).
+ * Bounds: filesystem root, max depth, git root, workspaces package root.
+ * Config found at a bound root is accepted; walking above a bound is refused.
+ *
+ * @param {string} startDir
+ * @param {string} [configName='ark.config.json']
+ * @param {{ maxDepth?: number, boundAtGitRoot?: boolean, boundAtWorkspacesRoot?: boolean }} [opts]
+ * @returns {{ root: string, configPath: string, walkedUp: boolean } | null}
+ */
+export function findNearestArkConfig(startDir, configName = 'ark.config.json', opts = {}) {
+  const maxDepth = Number.isFinite(opts.maxDepth) ? opts.maxDepth : MAX_CONFIG_WALK_DEPTH;
+  const boundAtGit = opts.boundAtGitRoot !== false;
+  const boundAtWorkspaces = opts.boundAtWorkspacesRoot !== false;
+
+  if (typeof configName === 'string' && path.isAbsolute(configName)) {
+    if (fs.existsSync(configName)) {
+      const root = path.dirname(configName);
+      const start = path.resolve(startDir || process.cwd());
+      return { root, configPath: configName, walkedUp: path.resolve(root) !== start };
+    }
+    return null;
+  }
+
+  let dir = path.resolve(startDir || process.cwd());
+  const start = dir;
+  const name = configName || 'ark.config.json';
+  let depth = 0;
+  for (;;) {
+    const candidate = path.join(dir, name);
+    try {
+      if (fs.statSync(candidate, { throwIfNoEntry: false })?.isFile()) {
+        return {
+          root: dir,
+          configPath: candidate,
+          walkedUp: dir !== start,
+        };
+      }
+    } catch {
+      // unreadable — keep walking
+    }
+
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    depth += 1;
+    if (depth > maxDepth) return null;
+
+    // Do not walk above git / workspaces roots (config at this dir already checked).
+    if (boundAtGit && isGitRoot(dir)) return null;
+    if (boundAtWorkspaces && isWorkspacesPackageRoot(dir)) return null;
+
+    dir = parent;
+  }
+}
+
+/**
+ * Resolve config discovery vs write roots for CLI invocation.
+ *
+ * - If config exists at startRoot → use startRoot for both.
+ * - Else walk parents for config (bounded) → configRoot may differ from writeRoot.
+ * - writeMode without followConfigRoot: keep writeRoot/start as `root` (do not rewrite parent).
+ * - writeMode + followConfigRoot (or read mode): adopt walked config root as `root`.
+ *
+ * @param {string} startRoot
+ * @param {{
+ *   configName?: string,
+ *   writeMode?: boolean,
+ *   followConfigRoot?: boolean,
+ *   maxDepth?: number,
+ * }} [opts]
+ * @returns {{
+ *   root: string,
+ *   writeRoot: string,
+ *   config: string,
+ *   configPath: string,
+ *   configRoot: string,
+ *   walkedUp: boolean,
+ *   configFound: boolean,
+ *   writeRootFollowedConfig: boolean,
+ * }}
+ */
+export function resolveEffectiveProjectRoot(startRoot, opts = {}) {
+  const configName = opts.configName || 'ark.config.json';
+  const start = path.resolve(startRoot || process.cwd());
+  const writeMode = opts.writeMode === true;
+  const followConfigRoot = opts.followConfigRoot === true;
+  // Writes adopt walked config root only with explicit opt-in.
+  const adoptWalkedRoot = !writeMode || followConfigRoot;
+
+  if (typeof configName === 'string' && path.isAbsolute(configName)) {
+    const found = findNearestArkConfig(start, configName, opts);
+    if (found) {
+      const root = adoptWalkedRoot ? found.root : start;
+      return {
+        root,
+        writeRoot: start,
+        config: configName,
+        configPath: found.configPath,
+        configRoot: found.root,
+        walkedUp: found.walkedUp,
+        configFound: true,
+        writeRootFollowedConfig: adoptWalkedRoot && found.walkedUp,
+      };
+    }
+    return {
+      root: start,
+      writeRoot: start,
+      config: configName,
+      configPath: configName,
+      configRoot: start,
+      walkedUp: false,
+      configFound: false,
+      writeRootFollowedConfig: false,
+    };
+  }
+
+  const localPath = path.join(start, configName);
+  try {
+    if (fs.statSync(localPath, { throwIfNoEntry: false })?.isFile()) {
+      return {
+        root: start,
+        writeRoot: start,
+        config: configName,
+        configPath: localPath,
+        configRoot: start,
+        walkedUp: false,
+        configFound: true,
+        writeRootFollowedConfig: false,
+      };
+    }
+  } catch {
+    // fall through to walk-up
+  }
+
+  const found = findNearestArkConfig(start, configName, opts);
+  if (found) {
+    const root = adoptWalkedRoot ? found.root : start;
+    return {
+      root,
+      writeRoot: start,
+      config: configName,
+      configPath: found.configPath,
+      configRoot: found.root,
+      walkedUp: true,
+      configFound: true,
+      writeRootFollowedConfig: adoptWalkedRoot && found.walkedUp,
+    };
+  }
+
+  return {
+    root: start,
+    writeRoot: start,
+    config: configName,
+    configPath: localPath,
+    configRoot: start,
+    walkedUp: false,
+    configFound: false,
+    writeRootFollowedConfig: false,
+  };
+}
+
+/**
+ * Commands that mutate project files under --root.
+ * Walk-up must not rewrite a parent monorepo unless --follow-config-root.
+ * @param {Record<string, unknown>} args
+ */
+export function isMutatingCliCommand(args = {}) {
+  if (args.installAgentGates) return true;
+  if (args.init) return true;
+  if (args.applyPolicyPack) return true;
+  if (args.migrateContract && args.write) return true;
+  if (args.adoptContract && args.write) return true;
+  if (args.updateBaseline) return true;
+  if (args.ratchetCores) return true;
+  if (args.migrateCommands) return true;
+  if (args.suggestInclude && args.write) return true;
+  return false;
+}

package/bin/lib/remediation.mjs

@@ -109,14 +109,7 @@ export function classifyRemediation(violation) {
                 rationale: 'Whole source file is type-only surface (no runtime statements) with a type-only cross-layer edge: relocate the file to the owning layer (or extract the type there). Behavior-preserving; gate verifies.',
             };
         }
-        if (violation?.typeOnly) {
-            return {
-                class: 'mechanical-safe',
-                confidence: 0.9,
-                remediationKind: 'type-only-import-move',
-                rationale: 'Type-only import (erased at runtime): move the type to the layer that owns it and re-export for back-compat. Behavior-preserving, and the gate verifies it.',
-            };
-        }
+        // Pure type-only *module* first (target has no value exports) — convert to import type.
         if (violation?.targetTypeOnlyExports) {
             return {
                 class: 'mechanical-safe',
@@ -125,9 +118,9 @@ export function classifyRemediation(violation) {
                 rationale: 'Static import targets a pure type-only module: convert to `import type` (erased at runtime) and place the type in a shared/owning layer. No runtime coupling; gate verifies.',
             };
         }
-        // R6: value-syntax named import/export of type-only exports from a mixed module.
-        // Only set when scan proves no dual-space value export and no top-level side effects.
-        if (violation?.namedBindingsTypeOnly) {
+        // R6: value-syntax named import of type-only exports from a *mixed* module.
+        // When the edge is already `import type`, prefer relocate (type-only-import-move) below.
+        if (violation?.namedBindingsTypeOnly && !violation?.typeOnly) {
             return {
                 class: 'mechanical-safe',
                 confidence: 0.86,
@@ -135,6 +128,14 @@ export function classifyRemediation(violation) {
                 rationale: 'Named bindings are type-only exports of the target module (even if the file also exports values): convert to `import type` / `export type` (erased at runtime). Gate verifies.',
             };
         }
+        if (violation?.typeOnly) {
+            return {
+                class: 'mechanical-safe',
+                confidence: 0.9,
+                remediationKind: 'type-only-import-move',
+                rationale: 'Type-only import (erased at runtime): move the type to the layer that owns it and re-export for back-compat. Behavior-preserving, and the gate verifies it.',
+            };
+        }
         // W6: port-proof inject is a *suggested* shape when proof holds, but always judgment
         // for auto-apply — adding a required parameter breaks external call sites.
         if (violation?.portProofEligible &&

package/bin/lib/rules-inventory.mjs

@@ -15,11 +15,24 @@ export function buildRulesInventory(input) {
     const candidates = [];
     let seq = 0;
     for (const [file, content] of Object.entries(input.fileContents).sort(([a], [b]) => a.localeCompare(b))) {
-        const isController = /controller|route|handler|resolver/i.test(file) ||
-            /@(Controller|Get|Post|Put|Delete|Patch)\b/.test(content);
+        const posix = file.replace(/\\/g, '/');
+        // P2-N — clear UI bags only (components/theme/styles). Do NOT blanket-skip all
+        // app/pages (server actions / route handlers live there and stay inventoriable).
+        const isUiChrome = /(?:^|\/)(?:components|ui|layouts|styles|hooks|theme|tokens|i18n|locales?)(?:\/|$)/i.test(posix) ||
+            /(?:^|\/)(?:src\/)?(?:app|pages)\/.+\.(?:tsx|jsx)$/i.test(posix) &&
+                /(?:page|layout|loading|error|template|default)\.(?:tsx|jsx)$/i.test(posix);
+        const isApiRoute = /(?:^|\/)(?:app|pages)(?:\/[^/]+)*\/api(?:\/|$)/i.test(posix);
+        const isServerAction = /(?:^|\/)actions?(?:\/|\.|$)/i.test(posix) || /['"]use server['"]/.test(content);
+        const isController = /controller|handler|resolver/i.test(file) ||
+            isApiRoute ||
+            isServerAction ||
+            (/route\.(?:ts|js|tsx|jsx)$/i.test(posix) && !isUiChrome) ||
+            /@(Controller|Get|Post|Put|Delete|Patch)\b/.test(content) ||
+            /\bexport\s+(?:async\s+)?function\s+(?:GET|POST|PUT|DELETE|PATCH)\b/.test(content) ||
+            /\bexport\s+const\s+(?:GET|POST|PUT|DELETE|PATCH)\s*=/.test(content);
         const isDomain = /domain|entity|aggregate|model/i.test(file);
-        // validation-in-controller
-        if (isController) {
+        // validation-in-controller (API/Nest/server-action handlers — not pure UI chrome)
+        if (isController && !isUiChrome) {
             const valRe = /\b(if\s*\([^)]{0,80}(amount|total|price|qty|quantity|balance)[^)]{0,40}\)|throw new (Error|BadRequest|ValidationError)|z\.object\(|yup\.|class-validator|@Is[A-Z])/g;
             let m;
             while ((m = valRe.exec(content)) !== null) {
@@ -40,11 +53,32 @@ export function buildRulesInventory(input) {
                 });
             }
         }
-        // magic business constants (heuristic)
+        // magic business constants (heuristic) — quiet UI labels via anchored prefixes/tokens
         const magicRe = /\b(const|let)\s+([A-Z][A-Z0-9_]{2,})\s*=\s*(\d{2,}|['"][^'"]{8,}['"])/g;
         let magic;
+        // Wave-2 (P2N residual): infra / I/O / storage noise without swallowing domain seeds
+        // like MAX_CART_SIZE, ORDER_STATUS_OPEN, MAX_PROPERTY_LIMIT, MAX_MEDIA_PER_PROPERTY,
+        // DEFAULT_ORDER_LIMIT (narrow DEFAULT_/REQUEST_/STORAGE_ — do not drop all DEFAULT_*).
+        const isInfraMagicName = (name) => /^(?:TEST|SPEC|TIMEOUT|PORT|VERSION|MAX_RETRY|MIN_RETRY|TTL|CACHE|HEADER|COOKIE|MIME|CONTENT_TYPE|HTTP_STATUS|NODE_ENV|LOG_LEVEL|FEATURE_FLAG|ID_PREFIX|Z_INDEX)(?:_|$)/i.test(name) ||
+            /^(?:ROUTE|PATH|LABEL|TITLE|HEADING|CLASS|STYLE|COLOR|THEME|BREAKPOINT|QUERY|PARAM|ICON|ARIA|MSG|COPY|I18N|LOCALE|PAGE|NAV|MENU|TAB|BTN|BUTTON|PLACEHOLDER|TOOLTIP|SHADOW|RADIUS|GAP|PADDING|MARGIN|FONT|WIDTH|HEIGHT|OPACITY|DURATION|EASE|ANIM)_/i.test(name) ||
+            /_(?:ROUTE|PATH|LABEL|TITLE|COLOR|THEME|CLASS|STYLE|ICON|ARIA|MSG|COPY|TIMEOUT|PORT|VERSION|RETRY|DELAY|INTERVAL|TTL|CACHE)$/i.test(name) ||
+            // ms/timeout/bytes/storage/bucket/url infra suffixes (predial residual)
+            /_(?:TIMEOUT(?:_MS)?|MS|BYTES|BUCKET|STORAGE_KEY|WINDOW_MS)$/i.test(name) ||
+            // Narrow DEFAULT_/REQUEST_/STORAGE_ — only known infra tokens, not all DEFAULT_* seeds
+            /^(?:DEFAULT_(?:BASE_URL|TIMEOUT(?:_MS)?|RETRY|PORT|HOST|HEADERS?|CACHE|TTL|MS|LOCALE|LANG|TIMEZONE|TZ)|REQUEST_(?:TIMEOUT(?:_MS)?|HEADERS?|RETRY|ID_PREFIX)|STORAGE_(?:KEY|PREFIX|BUCKET)|DAY_MS$|APP_DOMAIN$|BASE_URL$)$/i.test(name) ||
+            // Known I/O bag prefixes that are never domain seeds in field clones
+            /^(?:FAVORITES_STORAGE|LISTINGS_CACHE|DOCS_PATH|METRICS_INTERVAL)/i.test(name);
         while ((magic = magicRe.exec(content)) !== null) {
-            if (/TEST|SPEC|TIMEOUT|PORT|VERSION|MAX_RETRY/i.test(magic[2]))
+            const name = magic[2];
+            if (isInfraMagicName(name))
+                continue;
+            // P2-N: skip remaining ALL_CAPS noise only on clear UI chrome (not all of app/).
+            if (isUiChrome && !isDomain)
+                continue;
+            // Wave-2: integrations / repos / clients are usually I/O constants, not Domain seeds.
+            // Keep Domain/controller paths so spaghetti magic limits still surface.
+            const isIoSurface = /(?:^|\/)(?:integrations?|repos?|clients?|infra(?:structure)?|adapters?)(?:\/|$)/i.test(posix) && !isDomain;
+            if (isIoSurface)
                 continue;
             seq += 1;
             candidates.push({
@@ -52,9 +86,9 @@ export function buildRulesInventory(input) {
                 kind: 'magic-business-constant',
                 file,
                 line: lineOf(content, magic.index),
-                message: `Magic business constant ${magic[2]} may belong in a Domain policy or invariant catalog.`,
+                message: `Magic business constant ${name} may belong in a Domain policy or invariant catalog.`,
                 confidence: 'heuristic',
-                suggestedArkRule: { layer: 'DomainModel', invariantId: `INV-${magic[2]}` },
+                suggestedArkRule: { layer: 'DomainModel', invariantId: `INV-${name}` },
                 neverMechanicalSafe: true,
             });
         }
@@ -87,27 +121,35 @@ export function buildRulesInventory(input) {
         }
         // mutation without guard in domain
         if (isDomain) {
-            const mutRe = /this\.\w+\s*=/g;
-            let mut;
-            while ((mut = mutRe.exec(content)) !== null) {
-                const window = content.slice(Math.max(0, mut.index - 200), mut.index + 200);
-                if (!/\b(ensureInvariants|assertInvariants|validate|publish|emit)\b/.test(window)) {
-                    seq += 1;
-                    candidates.push({
-                        id: `inv-mut-${seq}`,
-                        kind: 'mutation-without-guard',
-                        file,
-                        line: lineOf(content, mut.index),
-                        message: 'Domain field mutation without nearby guard/publish call.',
-                        confidence: 'heuristic',
-                        suggestedArkRule: {
-                            layer: 'DomainModel',
-                            structureId: 'events-on-mutation',
-                            sensor: 'domain-event-on-mutation',
-                        },
-                        neverMechanicalSafe: true,
-                    });
-                    break; // one per file is enough for inventory ranking
+            // Wave-2: *Error / *access.error bags are not aggregate mutators (propia residual).
+            // Narrow: path-based error modules only — do not skip whole domain files that
+            // merely export an Error class alongside aggregates.
+            const isErrorBag = /\.error\.(?:ts|js|tsx|jsx)$/i.test(posix) ||
+                /(?:^|\/)[^/]*(?:-access)?\.error\./i.test(posix) ||
+                /(?:^|\/)errors?(?:\/|$)/i.test(posix);
+            if (!isErrorBag) {
+                const mutRe = /this\.\w+\s*=/g;
+                let mut;
+                while ((mut = mutRe.exec(content)) !== null) {
+                    const window = content.slice(Math.max(0, mut.index - 200), mut.index + 200);
+                    if (!/\b(ensureInvariants|assertInvariants|validate|publish|emit)\b/.test(window)) {
+                        seq += 1;
+                        candidates.push({
+                            id: `inv-mut-${seq}`,
+                            kind: 'mutation-without-guard',
+                            file,
+                            line: lineOf(content, mut.index),
+                            message: 'Domain field mutation without nearby guard/publish call.',
+                            confidence: 'heuristic',
+                            suggestedArkRule: {
+                                layer: 'DomainModel',
+                                structureId: 'events-on-mutation',
+                                sensor: 'domain-event-on-mutation',
+                            },
+                            neverMechanicalSafe: true,
+                        });
+                        break; // one per file is enough for inventory ranking
+                    }
                 }
             }
         }