@anhcodo13/lattice 0.0.0-stage → 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,34 @@
+type ProfileName = "next" | "vite-react" | "react";
+interface VersionPolicy {
+    schemaVersion: 1;
+    policyVersion: string;
+    profiles: Record<string, Record<string, string>>;
+    source: string;
+    sha256: string;
+}
+interface GovernanceFinding {
+    app: string;
+    packageName: string;
+    expected: string;
+    declared?: string;
+    locked?: string;
+    reason: string;
+}
+interface GovernanceResult {
+    appsChecked: number;
+    findings: GovernanceFinding[];
+    policyVersion: string;
+    policySource: string;
+    policySha256: string;
+}
+interface CheckOptions {
+    scanRoot: string;
+    workspaceRoot?: string;
+    policy: VersionPolicy;
+}
+
+declare function loadPolicy(source: string): Promise<VersionPolicy>;
+
+declare function checkGovernance(options: CheckOptions): Promise<GovernanceResult>;
+
+export { type CheckOptions, type GovernanceFinding, type GovernanceResult, type ProfileName, type VersionPolicy, checkGovernance, loadPolicy };

package/dist/index.js

@@ -0,0 +1,290 @@
+// src/governance/policy.ts
+import { createHash } from "crypto";
+import { readFile } from "fs/promises";
+import { resolve } from "path";
+var exactVersion = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+function record(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function parsePolicy(raw, source) {
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } 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 (typeof parsed.policyVersion !== "string" || !exactVersion.test(parsed.policyVersion)) {
+    throw new Error("Policy policyVersion must be an exact version");
+  }
+  if (!record(parsed.profiles) || Object.keys(parsed.profiles).length === 0) {
+    throw new Error("Policy profiles must be a nonempty object");
+  }
+  const profiles2 = {};
+  for (const [name, rules] of Object.entries(parsed.profiles)) {
+    if (!record(rules) || Object.keys(rules).length === 0) {
+      throw new Error(`Policy profile ${name} must list packages`);
+    }
+    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}`);
+      }
+      versions[packageName] = version;
+    }
+    profiles2[name] = versions;
+  }
+  return {
+    schemaVersion: 1,
+    policyVersion: parsed.policyVersion,
+    profiles: profiles2,
+    source,
+    sha256: createHash("sha256").update(raw).digest("hex")
+  };
+}
+async function loadPolicy(source) {
+  if (/^https?:\/\//i.test(source)) {
+    if (!source.startsWith("https://")) {
+      throw new Error("Remote policy requires HTTPS");
+    }
+    const response = await fetch(source);
+    if (response.url && !response.url.startsWith("https://")) {
+      throw new Error("Remote policy redirects must remain on HTTPS");
+    }
+    if (!response.ok) {
+      throw new Error(`Policy fetch failed with HTTP ${response.status}`);
+    }
+    return parsePolicy(await response.text(), source);
+  }
+  return parsePolicy(await readFile(resolve(source), "utf8"), source);
+}
+
+// src/governance/check.ts
+import { resolve as resolve3, relative as relative3, sep as sep2 } from "path";
+
+// src/governance/discover.ts
+import { readFile as readFile2 } from "fs/promises";
+import { join, relative } from "path";
+import fastGlob from "fast-glob";
+var profiles = /* @__PURE__ */ new Set(["next", "vite-react", "react"]);
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function dependencyMap(manifest) {
+  const result = {};
+  for (const section2 of ["dependencies", "devDependencies", "optionalDependencies"]) {
+    const entries = manifest[section2];
+    if (entries === void 0) continue;
+    if (!isRecord(entries)) throw new Error(`Invalid ${section2} in package.json`);
+    for (const [name, version] of Object.entries(entries)) {
+      if (typeof version !== "string") throw new Error(`Invalid version for ${name}`);
+      if (result[name] !== void 0 && result[name] !== version) {
+        throw new Error(`Conflicting declarations for ${name}`);
+      }
+      result[name] = version;
+    }
+  }
+  return result;
+}
+function profileFor(manifest, dependencies) {
+  const config = manifest.nklattice;
+  if (config !== void 0) {
+    if (!isRecord(config) || typeof config.profile !== "string" || !profiles.has(config.profile)) {
+      throw new Error("Invalid nklattice.profile in package.json");
+    }
+    return config.profile;
+  }
+  if (dependencies.next !== void 0) return "next";
+  if (dependencies.vite !== void 0 && dependencies.react !== void 0) return "vite-react";
+  if (dependencies.react !== void 0) return "react";
+  return void 0;
+}
+async function discoverApps(scanRoot, workspaceRoot) {
+  const manifests = await fastGlob(["package.json", "**/package.json"], {
+    cwd: scanRoot,
+    onlyFiles: true,
+    unique: true,
+    followSymbolicLinks: false,
+    ignore: ["**/node_modules/**", "**/.git/**", "**/dist/**", "**/.next/**", "**/coverage/**"]
+  });
+  const apps = [];
+  for (const path of manifests.sort()) {
+    const directory = join(scanRoot, path, "..");
+    let parsed;
+    try {
+      parsed = JSON.parse(await readFile2(join(scanRoot, path), "utf8"));
+    } catch {
+      throw new Error(`Invalid package.json: ${path}`);
+    }
+    if (!isRecord(parsed)) throw new Error(`Invalid package.json: ${path}`);
+    const dependencies = dependencyMap(parsed);
+    const profile = profileFor(parsed, dependencies);
+    if (!profile) continue;
+    apps.push({
+      directory,
+      relativePath: relative(workspaceRoot, directory).replaceAll("\\", "/") || ".",
+      profile,
+      dependencies
+    });
+  }
+  return apps;
+}
+
+// src/governance/lockfiles.ts
+import { access, readFile as readFile3 } from "fs/promises";
+import { dirname, join as join2, relative as relative2, resolve as resolve2, sep } from "path";
+import YAML from "yaml";
+function record2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+async function exists(path) {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function within(parent, child) {
+  const rel = relative2(parent, child);
+  return rel === "" || rel !== ".." && !rel.startsWith(`..${sep}`);
+}
+async function findLockfile(appDirectory, workspaceRoot) {
+  let directory = resolve2(appDirectory);
+  const boundary = resolve2(workspaceRoot);
+  if (!within(boundary, directory)) throw new Error("Application is outside workspace root");
+  while (within(boundary, directory)) {
+    const npm = join2(directory, "package-lock.json");
+    const pnpm = join2(directory, "pnpm-lock.yaml");
+    const [hasNpm, hasPnpm] = await Promise.all([exists(npm), exists(pnpm)]);
+    if (hasNpm && hasPnpm) throw new Error(`Ambiguous lockfiles in ${directory}`);
+    if (hasNpm) return { path: npm, kind: "npm", root: directory };
+    if (hasPnpm) return { path: pnpm, kind: "pnpm", root: directory };
+    if (directory === boundary) break;
+    directory = dirname(directory);
+  }
+  throw new Error(`No lockfile found for ${appDirectory}`);
+}
+function section(importer, name) {
+  for (const key of ["dependencies", "devDependencies", "optionalDependencies"]) {
+    const entries = importer[key];
+    if (record2(entries) && Object.hasOwn(entries, name)) return entries[name];
+  }
+  return void 0;
+}
+function readNpm(raw, root, app, name) {
+  let lock;
+  try {
+    lock = JSON.parse(raw);
+  } catch {
+    throw new Error("Malformed npm lockfile JSON");
+  }
+  if (!record2(lock) || lock.lockfileVersion !== 3 || !record2(lock.packages)) {
+    throw new Error("Unsupported or malformed npm lockfile");
+  }
+  const importerKey = relative2(root, app.directory).replaceAll("\\", "/");
+  const importer = lock.packages[importerKey];
+  if (!record2(importer)) throw new Error(`Missing npm lockfile importer ${importerKey || "."}`);
+  const specifier = section(importer, name);
+  if (specifier !== void 0 && typeof specifier !== "string") {
+    throw new Error(`Malformed npm lockfile specifier for ${name}`);
+  }
+  let resolved;
+  const segments = importerKey ? importerKey.split("/") : [];
+  while (true) {
+    const prefix = segments.length ? `${segments.join("/")}/` : "";
+    resolved = lock.packages[`${prefix}node_modules/${name}`];
+    if (resolved !== void 0 || segments.length === 0) break;
+    segments.pop();
+  }
+  if (specifier !== void 0 && !record2(resolved)) {
+    throw new Error(`Missing npm lockfile package resolution for ${name}`);
+  }
+  if (record2(resolved) && typeof resolved.version !== "string") {
+    throw new Error(`Malformed npm lockfile package version for ${name}`);
+  }
+  return { specifier, version: record2(resolved) ? resolved.version : void 0 };
+}
+function readPnpm(raw, root, app, name) {
+  let lock;
+  try {
+    lock = YAML.parse(raw);
+  } catch {
+    throw new Error("Malformed pnpm lockfile YAML");
+  }
+  if (!record2(lock) || String(lock.lockfileVersion) !== "9.0" || !record2(lock.importers) || !record2(lock.packages) || !record2(lock.snapshots)) {
+    throw new Error("Unsupported or malformed pnpm lockfile");
+  }
+  const importerKey = relative2(root, app.directory).replaceAll("\\", "/") || ".";
+  const importer = lock.importers[importerKey];
+  if (!record2(importer)) throw new Error(`Missing pnpm lockfile importer ${importerKey}`);
+  const entry = section(importer, name);
+  if (entry === void 0) return {};
+  if (!record2(entry) || typeof entry.specifier !== "string" || typeof entry.version !== "string") {
+    throw new Error(`Malformed pnpm lockfile dependency for ${name}`);
+  }
+  const version = entry.version.match(/^(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)/)?.[1];
+  if (!version) throw new Error(`Unsupported pnpm resolution for ${name}`);
+  const packageKeys = [`${name}@${version}`, `/${name}@${version}`];
+  if (!packageKeys.some((key) => record2(lock.packages) && Object.hasOwn(lock.packages, key))) {
+    throw new Error(`Missing pnpm package entry for ${name}@${version}`);
+  }
+  const snapshotKeys = [`${name}@${entry.version}`, `/${name}@${entry.version}`, ...packageKeys];
+  if (!snapshotKeys.some((key) => Object.hasOwn(lock.snapshots, key))) {
+    throw new Error(`Missing pnpm snapshot for ${name}@${entry.version}`);
+  }
+  return { specifier: entry.specifier, version };
+}
+async function readResolution(app, workspaceRoot, name) {
+  const lockfile = await findLockfile(app.directory, workspaceRoot);
+  const raw = await readFile3(lockfile.path, "utf8");
+  return lockfile.kind === "npm" ? readNpm(raw, lockfile.root, app, name) : readPnpm(raw, lockfile.root, app, name);
+}
+
+// src/governance/check.ts
+async function checkGovernance(options) {
+  const scanRoot = resolve3(options.scanRoot);
+  const workspaceRoot = resolve3(options.workspaceRoot ?? scanRoot);
+  const path = relative3(workspaceRoot, scanRoot);
+  if (path === ".." || path.startsWith(`..${sep2}`)) {
+    throw new Error("Scan root must be inside workspace root");
+  }
+  const apps = await discoverApps(scanRoot, workspaceRoot);
+  if (apps.length === 0) throw new Error("No managed applications found");
+  const findings = [];
+  for (const app of apps) {
+    const requirements = options.policy.profiles[app.profile];
+    if (!requirements) throw new Error(`Policy does not define profile ${app.profile}`);
+    for (const [packageName, expected] of Object.entries(requirements)) {
+      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");
+      if (resolution.specifier !== declared) reasons.push("lockfile specifier differs");
+      if (resolution.version !== expected) reasons.push("lockfile resolution differs");
+      if (reasons.length) {
+        findings.push({
+          app: app.relativePath,
+          packageName,
+          expected,
+          declared,
+          locked: resolution.version,
+          reason: reasons.join("; ")
+        });
+      }
+    }
+  }
+  return {
+    appsChecked: apps.length,
+    findings,
+    policyVersion: options.policy.policyVersion,
+    policySource: options.policy.source,
+    policySha256: options.policy.sha256
+  };
+}
+export {
+  checkGovernance,
+  loadPolicy
+};

package/governance/policy.json

@@ -0,0 +1,23 @@
+{
+  "schemaVersion": 1,
+  "policyVersion": "1.0.0",
+  "profiles": {
+    "next": {
+      "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"
+    },
+    "react": {
+      "react": "19.2.0",
+      "react-dom": "19.2.0",
+      "typescript": "5.9.3"
+    }
+  }
+}

package/package.json

@@ -1,6 +1,36 @@
 {
   "name": "@anhcodo13/lattice",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "private": false,
+  "packageManager": "pnpm@10.30.3",
+  "type": "module",
+  "description": "Independent architecture analysis and dependency governance for React teams",
+  "author": "KhucHieuNghi",
+  "license": "MIT",
+  "repository": { "type": "git", "url": "git+https://github.com/KhucHieuNghi/nklattice.git" },
+  "homepage": "https://khuchieunghi.github.io/nklattice/",
+  "bugs": { "url": "https://github.com/KhucHieuNghi/nklattice/issues" },
+  "publishConfig": { "access": "public" },
+  "bin": { "lattice": "dist/cli.js" },
+  "exports": { ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" } },
+  "files": ["dist", "governance/policy.json", "LICENSE"],
+  "engines": { "node": ">=24" },
+  "scripts": {
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "build": "tsup",
+    "verify": "pnpm typecheck && pnpm test && pnpm build && node scripts/smoke-built-cli.mjs",
+    "verify:package": "node scripts/smoke-tarball.mjs"
+  },
+  "dependencies": {
+    "commander": "^14.0.0",
+    "fast-glob": "^3.3.3",
+    "typescript": "5.9.3",
+    "yaml": "^2.9.1"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "tsup": "^8.5.0",
+    "vitest": "^3.2.0"
+  }
+}