@anhcodo13/lattice 0.2.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. package/README.md +33 -16
  2. package/dist/cli.js +923 -150
  3. package/dist/index.d.ts +117 -1
  4. package/dist/index.js +965 -63
  5. package/governance/policy.json +14 -1
  6. package/package.json +2 -2
package/README.md CHANGED
@@ -1,20 +1,23 @@
1
1
  # NKLattice
2
2
 
3
- 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.
3
+ 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.
4
4
 
5
- **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/).
5
+ **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/).
6
6
 
7
- ## Install the CLI
7
+ ## Run the 0.3.0 source release
8
8
 
9
- Requires Node.js 24 or newer. The npm package is `@anhcodo13/lattice`; the executable is `lattice`.
9
+ 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:
10
10
 
11
11
  ```sh
12
- npm install --global @anhcodo13/lattice@0.2.0
13
- lattice --version
14
- lattice governance check path/to/app --expect-apps 1
12
+ pnpm install --frozen-lockfile
13
+ pnpm build
14
+ npm exec --package . -- lattice governance assess examples/governance \
15
+ --policy governance/policy.json --expect-apps 3
15
16
  ```
16
17
 
17
- ## Build and try the source
18
+ 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.
19
+
20
+ ## Verify the source and try the published 0.2.0 CLI
18
21
 
19
22
  The source checkout uses pnpm 10.30.3:
20
23
 
@@ -22,22 +25,36 @@ The source checkout uses pnpm 10.30.3:
22
25
  corepack enable
23
26
  pnpm install --frozen-lockfile
24
27
  pnpm verify
25
- node dist/cli.js doctor examples/governance/apps/vite
26
- node dist/cli.js analyze examples/governance/apps/vite
27
- node dist/cli.js governance check examples/governance \
28
+ pnpm dlx @anhcodo13/lattice@0.2.0 doctor examples/governance/apps/vite
29
+ pnpm dlx @anhcodo13/lattice@0.2.0 analyze examples/governance/apps/vite
30
+ pnpm dlx @anhcodo13/lattice@0.2.0 governance check examples/governance \
28
31
  --workspace-root examples/governance \
29
32
  --policy governance/policy.json --expect-apps 3
30
33
  ```
31
34
 
35
+ `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`.
36
+
32
37
  The analysis writes `report.html` and `analysis.json` into the app's `.nklattice-report/` directory. The HTML opens offline.
33
38
 
39
+ ## Assess project governance from source
40
+
41
+ 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:
42
+
43
+ ```sh
44
+ pnpm install --frozen-lockfile
45
+ pnpm build
46
+ npm exec --package . -- lattice governance assess examples/governance --policy governance/policy.json --expect-apps 3
47
+ ```
48
+
49
+ 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.
50
+
34
51
  ## Architecture analysis
35
52
 
36
53
  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`.
37
54
 
38
55
  ```sh
39
- node dist/cli.js init path/to/app
40
- node dist/cli.js analyze path/to/app --output path/to/report
56
+ pnpm dlx @anhcodo13/lattice@0.2.0 init path/to/app
57
+ pnpm dlx @anhcodo13/lattice@0.2.0 analyze path/to/app --output path/to/report
41
58
  ```
42
59
 
43
60
  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/).
@@ -54,11 +71,11 @@ Profiles are `next`, `vite-react`, and `react`. NKLattice can infer them from di
54
71
  { "nklattice": { "profile": "next" } }
55
72
  ```
56
73
 
57
- 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.
74
+ 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.
58
75
 
59
76
  ```sh
60
- node dist/cli.js governance check ./my-app --policy ./governance/policy.json
61
- node dist/cli.js governance check ./monorepo/apps \
77
+ pnpm dlx @anhcodo13/lattice@0.2.0 governance check ./my-app --policy ./governance/policy.json
78
+ pnpm dlx @anhcodo13/lattice@0.2.0 governance check ./monorepo/apps \
62
79
  --workspace-root ./monorepo --policy ./governance/policy.json --expect-apps 3 --json
63
80
  ```
64
81