@anhcodo13/lattice 0.2.0 → 0.4.0

package/README.md

@@ -1,20 +1,23 @@
 # NKLattice
 
-NKLattice is an independent, local CLI for architecture analysis and dependency governance across Next.js, Vite + React, and React applications. It supports standalone repositories and npm or pnpm workspaces.
+NKLattice is an independent, local CLI for project governance and architecture analysis across Next.js, Vite + React, and React applications. Version 0.4.0 assesses exact app coverage, dependency policy, architecture, known dependency advisories, code quality, code security and browser/mobile-emulation compatibility in standalone repositories and npm/pnpm workspaces. Its compatibility gate records tested browser versions and mobile user-agent OS versions, then compares them with the central test-environment floors; physical-device support remains outside this scan.
 
-**Tiếng Việt:** NKLattice phân tích kiến trúc mã nguồn và kiểm tra phiên bản thư viện theo một policy chung cho nhiều ứng dụng Next.js, Vite và React. Xem [tài liệu tiếng Việt](https://khuchieunghi.github.io/nklattice/vi/docs/introduction/).
+**Tiếng Việt:** NKLattice đánh giá danh sách app, dependency, kiến trúc, chất lượng và bảo mật mã cùng tính tương thích trình duyệt theo policy chung cho Next.js, Vite và React. Xem [tài liệu tiếng Việt](https://khuchieunghi.github.io/nklattice/vi/docs/introduction/).
 
-## Install the CLI
+## Install and run 0.4.0
 
-Requires Node.js 24 or newer. The npm package is `@anhcodo13/lattice`; the executable is `lattice`.
+Requires Node.js 24 or newer. The npm package is `@anhcodo13/lattice` and the executable is `lattice`. Install the exact version, commit the package manifest and lockfile, and create the `.nklattice-apps.json` inventory described in the [governance guide](https://khuchieunghi.github.io/nklattice/docs/governance/). The full assessment also needs the listed scanner and test tools in the consuming repository.
 
 ```sh
-npm install --global @anhcodo13/lattice@0.2.0
-lattice --version
-lattice governance check path/to/app --expect-apps 1
+npm install --save-dev --save-exact @anhcodo13/lattice@0.4.0
+npx lattice --version
+npx lattice governance run . --policy path/to/reviewed-policy.json \
+  --expect-apps 1 --evidence /tmp/lattice-governance-evidence.json
 ```
 
-## Build and try the source
+The command writes `.nklattice-governance/assessment.json` and an offline HTML report. Use `npm view @anhcodo13/lattice version` to verify what the public registry currently serves before installing.
+
+## Verify the source and try the published CLI
 
 The source checkout uses pnpm 10.30.3:
 
@@ -22,22 +25,30 @@ The source checkout uses pnpm 10.30.3:
 corepack enable
 pnpm install --frozen-lockfile
 pnpm verify
-node dist/cli.js doctor examples/governance/apps/vite
-node dist/cli.js analyze examples/governance/apps/vite
-node dist/cli.js governance check examples/governance \
+pnpm dlx @anhcodo13/lattice@0.4.0 doctor examples/governance/apps/vite
+pnpm dlx @anhcodo13/lattice@0.4.0 analyze examples/governance/apps/vite
+pnpm dlx @anhcodo13/lattice@0.4.0 governance check examples/governance \
   --workspace-root examples/governance \
   --policy governance/policy.json --expect-apps 3
 ```
 
+`pnpm verify` checks the source checkout. The `pnpm dlx` commands invoke the exact published npm package against the included examples. In an app with the package pinned as a dev dependency, use `npx lattice`.
+
 The analysis writes `report.html` and `analysis.json` into the app's `.nklattice-report/` directory. The HTML opens offline.
 
+## Assess project governance
+
+Commit `.nklattice-apps.json` in each consumer scan root with exact app paths/profiles. The centrally reviewed policy sets dependency, architecture, quality, security and compatibility gates; app-local `.nklattice.json` cannot weaken an assessment. Run the combined collector and assessment shown above. The separate `collect` and `assess` commands remain useful for local inspection; the CI gate uses `run` so no editable evidence file is read between collection and verdict.
+
+The command evaluates seven domains per app and writes `.nklattice-governance/assessment.json` plus offline `report.html`. Exit 0 means pass, 7 measured policy failure and 3 incomplete evidence or command error. See the [project governance guide](https://khuchieunghi.github.io/nklattice/docs/governance/) for scanner setup, inventory schema, scope and limits.
+
 ## Architecture analysis
 
 NKLattice scans supported JS/TS and JSX/TSX files, resolves local imports, builds a module graph, and reports cycles, dependency concentration, long chains, duplicate imports, unused internal exports, component size, JSX depth, and approximate complexity. Define boundary policies and adjust thresholds or score weights in `.nklattice.json`.
 
 ```sh
-node dist/cli.js init path/to/app
-node dist/cli.js analyze path/to/app --output path/to/report
+pnpm dlx @anhcodo13/lattice@0.4.0 init path/to/app
+pnpm dlx @anhcodo13/lattice@0.4.0 analyze path/to/app --output path/to/report
 ```
 
 The score is an explainable review aid, not a claim about runtime speed or correctness. See [findings](https://khuchieunghi.github.io/nklattice/docs/findings/) and [scoring](https://khuchieunghi.github.io/nklattice/docs/scoring/).
@@ -46,7 +57,7 @@ The score is an explainable review aid, not a claim about runtime speed or corre
 
 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.
+CLI 0.4.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:
 
@@ -54,11 +65,11 @@ Profiles are `next`, `vite-react`, and `react`. NKLattice can infer them from di
 { "nklattice": { "profile": "next" } }
 ```
 
-The [reusable governance workflow](.github/workflows/governance-check.yml) requires a reviewed 40-character `core-ref` and an `expected-apps` count. It checks out the CLI and policy from that commit, then fails if the number of managed apps differs. The [consumer workflow template](examples/consumer-workflow.yml) pins both the workflow `uses` ref and `core-ref` to the same SHA, with deployment depending on the governance job. Replace its placeholders and set `expected-apps` for each consuming repository. For a pnpm monorepo, pass its root as `--workspace-root` when running the CLI directly.
+The [reusable governance workflow](.github/workflows/governance-check.yml) requires a reviewed 40-character `core-ref`, an exact inventory and an `expected-apps` count. It builds CLI and policy from that commit, installs the scanner toolchain, collects evidence and gates seven domains. The [consumer workflow template](examples/consumer-workflow.yml) pins both the workflow `uses` ref and `core-ref` to the same SHA, with deployment depending on governance. The consumer must keep the two refs equal. For a pnpm monorepo subtree, pass its root as `--workspace-root` when running the CLI directly.
 
 ```sh
-node dist/cli.js governance check ./my-app --policy ./governance/policy.json
-node dist/cli.js governance check ./monorepo/apps \
+pnpm dlx @anhcodo13/lattice@0.4.0 governance check ./my-app --policy ./governance/policy.json
+pnpm dlx @anhcodo13/lattice@0.4.0 governance check ./monorepo/apps \
   --workspace-root ./monorepo --policy ./governance/policy.json --expect-apps 3 --json
 ```