@anhcodo13/lattice 0.1.0 → 0.2.0

package/README.md

@@ -9,7 +9,7 @@ NKLattice is an independent, local CLI for architecture analysis and dependency
 Requires Node.js 24 or newer. The npm package is `@anhcodo13/lattice`; the executable is `lattice`.
 
 ```sh
-npm install --global @anhcodo13/lattice@0.1.0
+npm install --global @anhcodo13/lattice@0.2.0
 lattice --version
 lattice governance check path/to/app --expect-apps 1
 ```
@@ -44,7 +44,9 @@ The score is an explainable review aid, not a claim about runtime speed or corre
 
 ## Dependency governance
 
-The versioned [central policy](governance/policy.json) requires exact versions. For each supported app, the CLI checks direct `package.json` declarations **and** matching npm/pnpm lockfile resolution. It returns exit `7` on drift and exit `3` for invalid input. The result lists the approved, declared, and locked versions.
+The versioned [central policy](governance/policy.json) sets minimum versions (`>=X.Y.Z`). For each supported app, the CLI checks that its direct `package.json` range cannot install below the minimum, that the npm/pnpm lockfile specifier matches the declaration, and that the resolved version satisfies both. Exact declarations are allowed when they meet the minimum. It returns exit `7` on drift and exit `3` for invalid input. Findings list the required range, declared range, lockfile specifier, locked version, and reason. A minimum has no upper bound: review framework compatibility and security separately before adopting newer major releases.
+
+CLI 0.2.0 requires policy schema 2. Existing schema 1 files use exact-version rules and need migration; consumers pinned to an older core SHA or npm package keep their existing behavior until explicitly upgraded.
 
 Profiles are `next`, `vite-react`, and `react`. NKLattice can infer them from direct dependencies or read an explicit app profile:
 

package/dist/cli.js

@@ -663,6 +663,7 @@ async function analyzeProject(projectRoot, options = {}) {
 
 // src/governance/check.ts
 import { resolve as resolve5, relative as relative4, sep as sep3 } from "path";
+import { satisfies, subset, valid, validRange } from "semver";
 
 // src/governance/discover.ts
 import { readFile as readFile5 } from "fs/promises";
@@ -861,15 +862,26 @@ async function checkGovernance(options) {
       const declared = app.dependencies[packageName];
       const resolution = declared === void 0 ? { specifier: void 0, version: void 0 } : await readResolution(app, workspaceRoot, packageName);
       const reasons = [];
-      if (declared !== expected) reasons.push("manifest version differs");
+      const declaredRange = declared === void 0 ? null : validRange(declared);
+      if (declared === void 0) reasons.push("required manifest declaration missing");
+      else if (declaredRange === null) reasons.push("unsupported manifest range");
+      else if (!subset(declaredRange, expected)) reasons.push("manifest range allows versions below minimum");
       if (resolution.specifier !== declared) reasons.push("lockfile specifier differs");
-      if (resolution.version !== expected) reasons.push("lockfile resolution differs");
+      if (resolution.version === void 0) reasons.push("lockfile resolution missing");
+      else if (!valid(resolution.version)) reasons.push("invalid lockfile resolution");
+      else {
+        if (!satisfies(resolution.version, expected)) reasons.push("lockfile resolution does not satisfy minimum");
+        if (declaredRange !== null && !satisfies(resolution.version, declaredRange)) {
+          reasons.push("lockfile resolution outside manifest range");
+        }
+      }
       if (reasons.length) {
         findings.push({
           app: app.relativePath,
           packageName,
           expected,
           declared,
+          lockfileSpecifier: resolution.specifier,
           locked: resolution.version,
           reason: reasons.join("; ")
         });
@@ -889,7 +901,9 @@ async function checkGovernance(options) {
 import { createHash } from "crypto";
 import { readFile as readFile7 } from "fs/promises";
 import { resolve as resolve6 } from "path";
+import { valid as valid2 } from "semver";
 var exactVersion = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+var minimumVersion = /^>=(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
 function record3(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -900,10 +914,10 @@ function parsePolicy(raw, source) {
   } catch {
     throw new Error(`Policy at ${source} is not valid JSON`);
   }
-  if (!record3(parsed) || parsed.schemaVersion !== 1) {
-    throw new Error("Policy schemaVersion must be 1");
+  if (!record3(parsed) || parsed.schemaVersion !== 2) {
+    throw new Error("Policy schemaVersion must be 2");
   }
-  if (typeof parsed.policyVersion !== "string" || !exactVersion.test(parsed.policyVersion)) {
+  if (typeof parsed.policyVersion !== "string" || !exactVersion.test(parsed.policyVersion) || valid2(parsed.policyVersion) === null) {
     throw new Error("Policy policyVersion must be an exact version");
   }
   if (!record3(parsed.profiles) || Object.keys(parsed.profiles).length === 0) {
@@ -916,15 +930,15 @@ function parsePolicy(raw, source) {
     }
     const versions = {};
     for (const [packageName, version] of Object.entries(rules)) {
-      if (typeof version !== "string" || !exactVersion.test(version)) {
-        throw new Error(`Policy exact version required for ${packageName} in ${name}`);
+      if (typeof version !== "string" || !minimumVersion.test(version) || valid2(version.slice(2)) === null) {
+        throw new Error(`Policy minimum version (>=X.Y.Z) required for ${packageName} in ${name}`);
       }
       versions[packageName] = version;
     }
     profiles2[name] = versions;
   }
   return {
-    schemaVersion: 1,
+    schemaVersion: 2,
     policyVersion: parsed.policyVersion,
     profiles: profiles2,
     source,
@@ -967,7 +981,7 @@ async function runCli(arguments_, output = defaultOutput) {
   }
   let exitCode = 0;
   const program = new Command();
-  program.name("lattice").description("Architecture analysis and dependency governance for React teams").version("0.1.0");
+  program.name("lattice").description("Architecture analysis and dependency governance for React teams").version("0.2.0");
   program.configureOutput({ writeOut: output.out, writeErr: output.err });
   program.exitOverride();
   program.command("analyze [path]").description("Analyze local architecture and write offline reports").option("--output <directory>", "Output directory").action(async (path, flags) => {
@@ -1018,7 +1032,7 @@ async function runCli(arguments_, output = defaultOutput) {
       output.out(`${result.appsChecked} application${result.appsChecked === 1 ? "" : "s"} checked; ${result.findings.length} dependency mismatch${result.findings.length === 1 ? "" : "es"}.
 `);
       for (const finding of result.findings) {
-        output.out(`${finding.app}: ${finding.packageName} expected ${finding.expected}; declared ${finding.declared ?? "missing"}; locked ${finding.locked ?? "missing"} (${finding.reason}).
+        output.out(`${finding.app}: ${finding.packageName} required ${finding.expected}; declared ${finding.declared ?? "missing"}; lockfile specifier ${finding.lockfileSpecifier ?? "missing"}; locked ${finding.locked ?? "missing"} (${finding.reason}).
 `);
       }
     }

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 type ProfileName = "next" | "vite-react" | "react";
 interface VersionPolicy {
-    schemaVersion: 1;
+    schemaVersion: 2;
     policyVersion: string;
     profiles: Record<string, Record<string, string>>;
     source: string;
@@ -11,6 +11,7 @@ interface GovernanceFinding {
     packageName: string;
     expected: string;
     declared?: string;
+    lockfileSpecifier?: string;
     locked?: string;
     reason: string;
 }

package/dist/index.js

@@ -2,7 +2,9 @@
 import { createHash } from "crypto";
 import { readFile } from "fs/promises";
 import { resolve } from "path";
+import { valid } from "semver";
 var exactVersion = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+var minimumVersion = /^>=(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
 function record(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -13,10 +15,10 @@ function parsePolicy(raw, source) {
   } catch {
     throw new Error(`Policy at ${source} is not valid JSON`);
   }
-  if (!record(parsed) || parsed.schemaVersion !== 1) {
-    throw new Error("Policy schemaVersion must be 1");
+  if (!record(parsed) || parsed.schemaVersion !== 2) {
+    throw new Error("Policy schemaVersion must be 2");
   }
-  if (typeof parsed.policyVersion !== "string" || !exactVersion.test(parsed.policyVersion)) {
+  if (typeof parsed.policyVersion !== "string" || !exactVersion.test(parsed.policyVersion) || valid(parsed.policyVersion) === null) {
     throw new Error("Policy policyVersion must be an exact version");
   }
   if (!record(parsed.profiles) || Object.keys(parsed.profiles).length === 0) {
@@ -29,15 +31,15 @@ function parsePolicy(raw, source) {
     }
     const versions = {};
     for (const [packageName, version] of Object.entries(rules)) {
-      if (typeof version !== "string" || !exactVersion.test(version)) {
-        throw new Error(`Policy exact version required for ${packageName} in ${name}`);
+      if (typeof version !== "string" || !minimumVersion.test(version) || valid(version.slice(2)) === null) {
+        throw new Error(`Policy minimum version (>=X.Y.Z) required for ${packageName} in ${name}`);
       }
       versions[packageName] = version;
     }
     profiles2[name] = versions;
   }
   return {
-    schemaVersion: 1,
+    schemaVersion: 2,
     policyVersion: parsed.policyVersion,
     profiles: profiles2,
     source,
@@ -63,6 +65,7 @@ async function loadPolicy(source) {
 
 // src/governance/check.ts
 import { resolve as resolve3, relative as relative3, sep as sep2 } from "path";
+import { satisfies, subset, valid as valid2, validRange } from "semver";
 
 // src/governance/discover.ts
 import { readFile as readFile2 } from "fs/promises";
@@ -261,15 +264,26 @@ async function checkGovernance(options) {
       const declared = app.dependencies[packageName];
       const resolution = declared === void 0 ? { specifier: void 0, version: void 0 } : await readResolution(app, workspaceRoot, packageName);
       const reasons = [];
-      if (declared !== expected) reasons.push("manifest version differs");
+      const declaredRange = declared === void 0 ? null : validRange(declared);
+      if (declared === void 0) reasons.push("required manifest declaration missing");
+      else if (declaredRange === null) reasons.push("unsupported manifest range");
+      else if (!subset(declaredRange, expected)) reasons.push("manifest range allows versions below minimum");
       if (resolution.specifier !== declared) reasons.push("lockfile specifier differs");
-      if (resolution.version !== expected) reasons.push("lockfile resolution differs");
+      if (resolution.version === void 0) reasons.push("lockfile resolution missing");
+      else if (!valid2(resolution.version)) reasons.push("invalid lockfile resolution");
+      else {
+        if (!satisfies(resolution.version, expected)) reasons.push("lockfile resolution does not satisfy minimum");
+        if (declaredRange !== null && !satisfies(resolution.version, declaredRange)) {
+          reasons.push("lockfile resolution outside manifest range");
+        }
+      }
       if (reasons.length) {
         findings.push({
           app: app.relativePath,
           packageName,
           expected,
           declared,
+          lockfileSpecifier: resolution.specifier,
           locked: resolution.version,
           reason: reasons.join("; ")
         });

package/governance/policy.json

@@ -1,23 +1,23 @@
 {
-  "schemaVersion": 1,
-  "policyVersion": "1.0.0",
+  "schemaVersion": 2,
+  "policyVersion": "2.0.0",
   "profiles": {
     "next": {
-      "next": "15.5.6",
-      "react": "19.2.0",
-      "react-dom": "19.2.0",
-      "typescript": "5.9.3"
+      "next": ">=15.5.6",
+      "react": ">=19.2.0",
+      "react-dom": ">=19.2.0",
+      "typescript": ">=5.9.3"
     },
     "vite-react": {
-      "vite": "6.4.3",
-      "react": "19.2.0",
-      "react-dom": "19.2.0",
-      "typescript": "5.9.3"
+      "vite": ">=6.4.3",
+      "react": ">=19.2.0",
+      "react-dom": ">=19.2.0",
+      "typescript": ">=5.9.3"
     },
     "react": {
-      "react": "19.2.0",
-      "react-dom": "19.2.0",
-      "typescript": "5.9.3"
+      "react": ">=19.2.0",
+      "react-dom": ">=19.2.0",
+      "typescript": ">=5.9.3"
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anhcodo13/lattice",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "private": false,
   "packageManager": "pnpm@10.30.3",
   "type": "module",
@@ -25,11 +25,13 @@
   "dependencies": {
     "commander": "^14.0.0",
     "fast-glob": "^3.3.3",
+    "semver": "7.8.5",
     "typescript": "5.9.3",
     "yaml": "^2.9.1"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",
+    "@types/semver": "^7.8.0",
     "tsup": "^8.5.0",
     "vitest": "^3.2.0"
   }