Mensor

Mensor is a deterministic contract checker for agent-edited, server-rendered HTML applications.

The runnable examples/dogfood-tasks application keeps compiler checks tied to real GET/POST behavior instead of fixtures alone.

The project turns architectural knowledge that normally lives in a maintainer's head into machine-readable project contracts. It links static HTML forms, action input contracts, optional source-bound route facts, source-file roles, import boundaries, and feature ownership, then reports violations in stable JSON that a person, CI job, or coding agent can act on.

Status

Version 0.2.1 is the current public preview. It adds package-specific npm guides while preserving the Check Output v2 and revision-1 contracts.

Registry Installation

The supported CLI installation path is:

pnpm add --save-dev @0disoft/mensor-cli@0.2.1
pnpm exec mensor check . --json

See the release runbook, the 0.2.1 migration note, and the prior 0.2.0 release audit for the publication process and compatibility boundary.

Contract Path Bases

Mensor uses two path bases. Project-level discovery paths do not become sourceRoot-relative merely because discovered source lives below that root.

Contract field	Path base
sourceRoot	project root
featureContracts[]	project root; include the sourceRoot prefix when applicable
routeIndex	project root
fileRoles[].withinFeature	directory containing the feature contract
action form.template	directory containing the feature contract
action handler.file	directory containing the feature contract

For example, a feature contract stored at src/features/guestbook/feature.mensor.jsonc is listed by that complete path in featureContracts, while its handler may be declared as server/create-entry.ts inside the feature contract.

Source Checkout

The current preview runs from a source checkout with Node.js 22 or newer and pnpm 11:

pnpm install --frozen-lockfile
pnpm build
pnpm mensor check fixtures/valid/tiny-tasks --json
pnpm mensor check fixtures/valid/tiny-tasks --json --report-version 2

Both check commands exit 0. The first preserves DiagnosticReport v1; the second adds compiler-derived inspection states through Check Output v2. To inspect a deterministic contract failure, run:

pnpm mensor check fixtures/invalid/form-field-missing --json

That command exits 1 and reports form.field_missing. The complete project and feature contract authoring example lives in packages/contract/spec/README.md. This is the contributor path for exercising the current source tree; registry installation is the supported consumer path.

First Proof

The current proof:

1. loads JSONC project and feature contracts without executing project code;
2. extracts static HTML forms and TypeScript/JavaScript source facts;
3. detects form, route, handler, import-boundary, placement, and ownership violations;
4. emits byte-stable diagnostics through mensor check --json; and
5. rejects checker-clean repairs that weaken a protected contract or delete feature semantics.

Product Boundary

Mensor is not a web framework, router, template engine, ORM, deployment platform, or LLM wrapper. It does not replace htmx, Turbo, Unpoly, LiveView, Livewire, or a server framework. It checks contracts around applications built with those kinds of tools.

The MVP supports TypeScript or JavaScript projects with static .html files. An optional canonical RouteIndex lets an external producer supply static route facts without granting the compiler code-execution authority. When routeIndex is omitted, Mensor does not inspect application route declarations and does not run the route.missing rule. A passing check means only that every configured static contract check passed; it never proves runtime application semantics. Dynamic template languages, runtime manifests, production HTTP handling, autofix, arbitrary plugins, cloud processing, and telemetry are deferred.

Repository Shape

• packages/contract: serializable contracts, diagnostics, and validation
• packages/compiler: discovery, source facts, semantic linking, and rules
• packages/cli: command parsing, output, and exit codes
• internal/fixture-kit: deterministic fixture and repair-test support
• fixtures: valid and intentionally broken example projects

See the product specification, system boundary, and workspace boundaries before adding or changing implementation boundaries.

Contributing And Security

Contributions are accepted under the Apache License 2.0 and require a DCO 1.1 sign-off. See CONTRIBUTING.md and DCO.txt. Report suspected vulnerabilities through the private process in SECURITY.md.

License

Mensor is licensed under the Apache License, Version 2.0. See LICENSE.