Architecture analysis policy

For exploratory lattice analyze, architecture settings live in .nklattice.json at the analyzed root. With Node.js 24+ and pnpm 10.30.3, run pnpm dlx @anhcodo13/lattice@0.5.0 init path/to/project to create a minimal file, or omit it to use defaults. In version 0.5.0, governance assess instead uses the central governance/policy.json architecture settings; app-local settings cannot weaken its gate. Architecture weights and dependency floors remain separate fields of that policy.

For a Vite alias defined as @ → ./src, add "aliases": { "@/": "src/" } inside central assessment.architecture.analysis or provide an equivalent tsconfig.paths entry. The assessment verifies a static Vite alias target against that mapping and treats an unverifiable target as incomplete. The mapping target must stay inside the app root. Literal dynamic import() and require() calls join the local graph; computed import paths cannot be assessed and produce incomplete evidence.

Built-in thresholds

A finding is emitted when the observed value is greater than its limit.

Setting	Default	What it measures
maxFanIn	8	Runtime local import edges entering one module.
maxFanOut	10	Runtime local import edges leaving one module.
maxChainDepth	6	Local runtime import hops in a dependency chain.
maxComponentLines	200	Lines in a file with a recognized JSX component.
maxJsxDepth	6	Maximum JSX nesting depth in a file.
maxComplexity	15	Approximate count of branches and logical conditions.

Thresholds can be overridden individually with non-negative integers. The component detector recognizes top-level, capitalized functions or variables containing JSX; it is a heuristic, not a full React component inventory. See Findings for each built-in rule.

A concrete configuration

This example tightens two limits, changes the score emphasis, and forbids UI modules from importing server internals:

{
  "analysis": {
    "thresholds": {
      "maxFanOut": 8,
      "maxJsxDepth": 5
    },
    "weights": {
      "architecture": 50,
      "imports": 20,
      "components": 20,
      "complexity": 10
    }
  },
  "policies": [
    {
      "id": "ui-server-boundary",
      "description": "UI modules cannot import server internals",
      "from": ["src/ui/**"],
      "disallow": ["src/server/**"],
      "severity": "error",
      "recommendation": "Call a public API instead of importing server internals."
    }
  ]
}

Run pnpm dlx @anhcodo13/lattice@0.5.0 analyze path/to/project to apply it. Paths in boundary globs are relative to that analyzed root. In the example, a resolved local import from src/ui/view.ts to src/server/secret.ts creates a finding at the import line. Imports to packages outside the scanned source set do not form local graph edges.

Boundary rule semantics

Each enabled policy needs a unique lowercase-hyphen ID, a nonempty description, one or more from globs, a severity (info, warning, or error), and exactly one of:

• disallow: report a matching target import.
• allow: report every local runtime target import that matches none of the listed target globs. Include all legitimate destinations when using an allowlist.

recommendation supplies the next step shown in the finding. Set "enabled": false to disable a policy without deleting its definition. Boundary rules inspect resolved local runtime import edges; declaration-level import type and export type do not create runtime boundary findings.

You can add these boundary policies through JSON. The built-in detectors themselves are fixed in code in this release; a JSON entry cannot define a new arbitrary AST rule.

Weights affect the score, not detection

The default weights are architecture 40, imports 25, components 20, and complexity 15. If you override them, provide all four non-negative numeric values totaling exactly 100. A larger architecture weight makes architecture findings cost more points; it does not discover more cycles. See Scoring for the calculation.

Invalid JSON, unknown threshold keys, negative limits, duplicate policy IDs, or invalid weights stop analysis with exit code 3. NKLattice does not silently ignore invalid configuration. Review a policy change alongside the affected findings before making it a team-wide standard.