@anhcodo13/lattice 0.3.0 → 0.4.0

package/README.md

@@ -1,23 +1,23 @@
 # NKLattice
 
-NKLattice is an independent, local CLI for project governance and architecture analysis across Next.js, Vite + React, and React applications. Version 0.3.0 assesses exact app coverage, dependency policy and source architecture in standalone repositories or npm/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 đánh giá danh sách app, dependency và kiến trúc mã nguồn theo policy chung cho các ứ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/).
 
-## Run the 0.3.0 source release
+## Install and run 0.4.0
 
-Requires Node.js 24 or newer. The npm package is `@anhcodo13/lattice` and the executable is `lattice`. Version 0.3.0 is awaiting npm account approval; the published 0.2.0 release supports dependency governance only. From this checkout, run:
+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
-pnpm install --frozen-lockfile
-pnpm build
-npm exec --package . -- lattice governance assess examples/governance \
-  --policy governance/policy.json --expect-apps 3
+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
 ```
 
-After npm approval and publication, install with `npm install --global @anhcodo13/lattice@0.3.0` and run `lattice governance assess path/to/app --expect-apps 1`. Check `npm view @anhcodo13/lattice version` before installing. Each app needs a committed `.nklattice-apps.json` for the assessment.
+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 0.2.0 CLI
+## Verify the source and try the published CLI
 
 The source checkout uses pnpm 10.30.3:
 
@@ -25,9 +25,9 @@ The source checkout uses pnpm 10.30.3:
 corepack enable
 pnpm install --frozen-lockfile
 pnpm verify
-pnpm dlx @anhcodo13/lattice@0.2.0 doctor examples/governance/apps/vite
-pnpm dlx @anhcodo13/lattice@0.2.0 analyze examples/governance/apps/vite
-pnpm dlx @anhcodo13/lattice@0.2.0 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
 ```
@@ -36,25 +36,19 @@ pnpm dlx @anhcodo13/lattice@0.2.0 governance check examples/governance \
 
 The analysis writes `report.html` and `analysis.json` into the app's `.nklattice-report/` directory. The HTML opens offline.
 
-## Assess project governance from source
-
-Commit `.nklattice-apps.json` in each consumer scan root with exact app paths/profiles. The centrally reviewed policy sets dependency floors and architecture gates; app-local `.nklattice.json` cannot weaken an assessment. Build this checkout and run:
+## Assess project governance
 
-```sh
-pnpm install --frozen-lockfile
-pnpm build
-npm exec --package . -- lattice governance assess examples/governance --policy governance/policy.json --expect-apps 3
-```
+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 inventory, dependencies and architecture 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 the inventory schema, scope and limits.
+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
-pnpm dlx @anhcodo13/lattice@0.2.0 init path/to/app
-pnpm dlx @anhcodo13/lattice@0.2.0 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/).
@@ -63,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:
 
@@ -71,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`, an exact inventory and an `expected-apps` count. It builds CLI and policy from that commit, assesses three domains and uploads evidence. 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.
+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
-pnpm dlx @anhcodo13/lattice@0.2.0 governance check ./my-app --policy ./governance/policy.json
-pnpm dlx @anhcodo13/lattice@0.2.0 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
 ```