@ecoma-io/archkeep 0.13.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,262 @@
+# Archkeep
+
+**Architecture governance for polyglot repositories** — a deterministic
+authority that keeps the architecture your team declared aligned with the code
+your team keeps changing. Dependency graphs and module boundaries for Go, Rust,
+Python, TypeScript, JavaScript and Vue, with Nx and Moon as first-class
+integrations. Coding agents read the same verdicts, machine-readably, through
+the `arch-*` skills. The system boundary — what Archkeep is and what it is not —
+is owned by [architecture-authority.md](https://github.com/ecoma-io/archkeep/blob/main/docs/doctrine/architecture-authority.md).
+
+## Why it exists
+
+ESLint reads JavaScript, TypeScript and Vue. In a polyglot repository, the
+languages it cannot parse carry their `layer:` and `scope:` tags with **no
+enforcer behind them**: a Go import that crosses a boundary passes lint, because
+ESLint answers "File ignored because no matching configuration was supplied"
+for `.go`. The dependency graph is silent the same way — `nx affected` only
+knows a dependency exists when it is an edge in the project graph, and Nx infers
+no edge for a Go import, a Cargo path dependency, or a `pyproject.toml` path
+dependency. An under-selecting `affected` and an absent boundary rule look
+exactly like a clean workspace, which is why the silence goes unnoticed (the
+measurement: [why.md](https://github.com/ecoma-io/archkeep/blob/main/docs/doctrine/why.md)).
+
+Archkeep closes both gaps with one analysis, served three ways — a CLI
+(`archkeep check`), a language server (`archkeep-lsp`), and an Nx plugin
+(`@ecoma-io/archkeep/nx`) — with the same verdict in each.
+
+## It works in under a minute
+
+```shell
+npm install -D @ecoma-io/archkeep
+```
+
+`archkeep.json` at the repository root declares the projects and their tags —
+the `coverage.exempt` row names the boundary law itself, which no project owns:
+
+```json
+{
+  "projects": {
+    "declared": [
+      { "name": "billing-core", "root": "libs/billing/core", "tags": ["scope:billing"] },
+      { "name": "shared-ui", "root": "libs/shared/ui", "tags": ["scope:shared"] }
+    ]
+  },
+  "coverage": {
+    "exempt": [
+      {
+        "path": "module-boundaries.config.mjs",
+        "reason": "The boundary law, not owned by a project"
+      }
+    ]
+  }
+}
+```
+
+`module-boundaries.config.mjs` at the same root holds the constraint table —
+the same shape `@nx/enforce-module-boundaries` takes, so one table feeds both
+enforcers:
+
+```js
+export const depConstraints = [
+  {
+    sourceTag: "scope:billing",
+    onlyDependOnLibsWithTags: ["scope:billing", "scope:shared"],
+    description: "Billing services must not reach outside their scope",
+    remediation: "Move the shared logic into a scope:shared library",
+  },
+];
+
+export const moduleBoundaryOptions = {
+  allow: [],
+  buildTargets: ["build"],
+  enforceBuildableLibDependency: false,
+  allowCircularSelfDependency: false,
+  checkDynamicDependenciesExceptions: [],
+  ignoredCircularDependencies: [],
+  banTransitiveDependencies: false,
+  checkNestedExternalImports: false,
+};
+```
+
+The import resolver reads the workspace's `tsconfig.base.json` for path
+mappings, so `@shared/button` maps to the UI source:
+
+```json
+{
+  "compilerOptions": {
+    "paths": { "@shared/button": ["libs/shared/ui/src/button.ts"] }
+  }
+}
+```
+
+A `billing-core` file importing `@shared/button` is legal (the constraint
+row allows it) — and had a `billing-core` file imported into a project tagged
+outside `scope:billing` or `scope:shared`, the same constraint would be an
+`onlyTagsConstraintViolation`, exit 1. Now check the tree:
+
+```shell
+archkeep check
+```
+
+```text
+policy  module-boundaries.config.mjs — fingerprint 3f9c…
+
+✔ no boundary violations (1 import in 2 files across 2 projects; 1 file exempted from coverage by archkeep.json's coverage.exempt)
+```
+
+A clean run states what it inspected — the import, file and project counts are
+the load-bearing half, so "no violations" is a claim about coverage as much as
+about correctness. The exempt suffix names the boundary law itself, which is
+not owned by any project.
+
+The import resolver uses the workspace's own `typescript` (a peer dependency,
+resolved from your tree, never bundled). A TypeScript-free Go/Rust/Python
+workspace pays nothing: resolution keys off the manifests that exist.
+
+## Who it is for
+
+**Human teams** run `archkeep check` in CI and gate on its exit code. The verdict
+is deterministic and evidence-based: same tree, same config, same answer — no
+machine-specific toolchain result, no model in the loop, and every verdict names
+what it inspected beside what it found
+([exit-codes.md](https://github.com/ecoma-io/archkeep/blob/main/docs/reference/exit-codes.md)).
+
+**Coding agents** read the same authority through the five `arch-*` skills —
+`arch-context` before an edit, `arch-change` during, `arch-check` after,
+`arch-review` on a change or PR, and `arch-migrate` to bring a repository that
+declares no architecture under one. The agent is a consumer of the verdict, never
+its authority: the commands it runs are read-only, and the constraint table is
+a file it cannot edit ([overview.md](https://github.com/ecoma-io/archkeep/blob/main/docs/skills/overview.md)).
+
+## What it does
+
+- **Deterministic graph** — a project graph from any provider: Nx, Moon, or the
+  native discovery that needs neither
+  ([graph.md](https://github.com/ecoma-io/archkeep/blob/main/docs/concepts/graph.md)).
+- **Boundary check** — every import judged against the constraint table, with
+  `file:line:column` evidence for each violation
+  ([violations.md](https://github.com/ecoma-io/archkeep/blob/main/docs/reference/violations.md)).
+- **Drift and intent** — a tracked `architecture-intent.json` declares what the
+  architecture must be; `drift` and `check` compare the observed graph against
+  it, and an unverifiable intent is a no-verdict, never a pass
+  ([drift.md](https://github.com/ecoma-io/archkeep/blob/main/docs/concepts/drift.md)).
+- **Evolution** — `graph` snapshots the architecture, `diff` compares two
+  snapshots, `history` describes the evolution across a directory of them
+  ([diff.md](https://github.com/ecoma-io/archkeep/blob/main/docs/usage/diff.md)).
+- **Waivers, profiles, fitness, ADR** — term-bound waivers, named law profiles
+  selected at check time, declared quality gates judged per run, and recorded
+  architecture decisions a constraint row can lean on
+  ([waivers.md](https://github.com/ecoma-io/archkeep/blob/main/docs/concepts/waivers.md) ·
+  [profiles.md](https://github.com/ecoma-io/archkeep/blob/main/docs/concepts/profiles.md) ·
+  [fitness-functions.md](https://github.com/ecoma-io/archkeep/blob/main/docs/concepts/fitness-functions.md) ·
+  [adr.md](https://github.com/ecoma-io/archkeep/blob/main/docs/concepts/adr.md)).
+- **Custom rules** — the policy's `customRules` list declares your own rules
+  as committed WebAssembly artifacts, written in any language whose toolchain
+  emits core wasm. Four typed SDKs ship from this repository on the same
+  version chain as the engine — `archkeep-rule-sdk` on crates.io (Rust),
+  `@ecoma-io/archkeep-rule-sdk` on npm (AssemblyScript), `archkeep-rule-sdk` on
+  PyPI (Python, via a RustPython carrier), and a Go module built with TinyGo —
+  and each one's README carries its build story and its measured limits. The
+  contract, not the SDK, is the interface: any toolchain emitting a core-wasm
+  module with no imports is equally valid. Each rule receives the run's
+  observed facts and answers in the same four-verdict vocabulary as everything
+  else: a finding exits 1 under `custom/<rule>/<finding>`, a rule that could
+  not judge exits 3, and an artifact that will not load (missing, hash
+  mismatch, undeclared imports) refuses the run — never a silent skip
+  ([custom-rules.md](https://github.com/ecoma-io/archkeep/blob/main/docs/concepts/custom-rules.md),
+  [writing one](https://github.com/ecoma-io/archkeep/blob/main/docs/usage/custom-rules.md)).
+- **Shipped policy packs** — Clean Architecture, hexagonal, layered modular
+  monolith and DDD bounded contexts, as ready-made profile registries under
+  this package's `presets/` directory. Copy one into your workspace, or point
+  the `profiles` option straight at it; either way it is enforced by the same
+  path a registry you wrote yourself is
+  ([presets.md](https://github.com/ecoma-io/archkeep/blob/main/docs/usage/presets.md)).
+- **Machine-readable JSON** — `--format json` wraps any verdict in a versioned
+  envelope (`schemaVersion`, `status`, `exitCode`, `coverage`); every field
+  name is a public contract
+  ([json-output.md](https://github.com/ecoma-io/archkeep/blob/main/docs/reference/json-output.md)).
+- **Language server** — `archkeep-lsp` publishes one diagnostic per violation in
+  any LSP client; an empty diagnostic list means "no violation", nothing else
+  ([vscode.md](https://github.com/ecoma-io/archkeep/blob/main/docs/integrations/vscode.md)).
+
+## Support
+
+- **Languages** — Go, Rust, Python, TypeScript and JavaScript, and Vue. Analysis
+  from source, never a build: nothing shells out to `go`, `cargo`, `uv` or `tsc`
+  ([languages.md](https://github.com/ecoma-io/archkeep/blob/main/docs/reference/languages.md)).
+- **Workspaces** — any repository: Nx registers the plugin in `nx.json` and
+  reuses Nx's project graph; Moon workspaces are recognised automatically; any
+  other tree uses `archkeep.json` and the native provider
+  ([nx.md](https://github.com/ecoma-io/archkeep/blob/main/docs/integrations/nx.md) ·
+  [moon.md](https://github.com/ecoma-io/archkeep/blob/main/docs/integrations/moon.md)).
+- **Agents** — Claude Code, Codex and opencode run the `arch-*` skills, which
+  are host-independent ([supported-hosts.md](https://github.com/ecoma-io/archkeep/blob/main/docs/skills/supported-hosts.md)).
+
+## Install and quick start
+
+`npm install -D @ecoma-io/archkeep` (or pnpm / yarn / bun), create
+`archkeep.json` and `module-boundaries.config.mjs` as above, then `archkeep check`.
+
+In CI, both findings (1) and "no verdict" (3) must fail the build — the
+distinction is the point. `archkeep check || true` is wrong: it turns "could
+not look" into "looked and found nothing". Distinguish explicitly:
+
+```shell
+archkeep check
+case $? in
+  0) echo "clean" ;;
+  1) echo "boundary violations"; exit 1 ;;
+  3) echo "the checker could not reach a verdict"; exit 1 ;;
+  *) echo "usage error"; exit 1 ;;
+esac
+```
+
+Exit codes: 0 clean — and every selected file was analyzed; 1 findings;
+2 usage error; 3 no verdict
+([exit-codes.md](https://github.com/ecoma-io/archkeep/blob/main/docs/reference/exit-codes.md) ·
+[ci.md](https://github.com/ecoma-io/archkeep/blob/main/docs/usage/ci.md)).
+
+Ten minutes end to end, most of it spent deciding what your tags mean:
+[**Getting started →**](https://github.com/ecoma-io/archkeep/blob/main/docs/getting-started/installation.md). `graph`, `diff`,
+`history`, `drift`, `impact`, `explain`, `context` and the rest of the
+seventeen-command surface are in the [CLI reference](https://github.com/ecoma-io/archkeep/blob/main/docs/reference/cli.md).
+
+## Documentation map
+
+| Topic           | Read                                                                                                                                                                                                                                                                                                                                                                              |
+| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Getting started | [Installation](https://github.com/ecoma-io/archkeep/blob/main/docs/getting-started/installation.md) → [first project](https://github.com/ecoma-io/archkeep/blob/main/docs/getting-started/first-project.md) → [first policy](https://github.com/ecoma-io/archkeep/blob/main/docs/getting-started/first-policy.md)                                                                 |
+| Concepts        | [The engine](https://github.com/ecoma-io/archkeep/blob/main/docs/concepts/architecture.md) · [boundaries](https://github.com/ecoma-io/archkeep/blob/main/docs/concepts/boundaries.md) · [drift](https://github.com/ecoma-io/archkeep/blob/main/docs/concepts/drift.md) · [intent](https://github.com/ecoma-io/archkeep/blob/main/docs/reference/architecture-intent.md)           |
+| Reference       | [CLI and flags](https://github.com/ecoma-io/archkeep/blob/main/docs/reference/cli.md) · [configuration](https://github.com/ecoma-io/archkeep/blob/main/docs/reference/configuration.md) · [exit codes](https://github.com/ecoma-io/archkeep/blob/main/docs/reference/exit-codes.md) · [JSON output](https://github.com/ecoma-io/archkeep/blob/main/docs/reference/json-output.md) |
+| Using it        | [Checking](https://github.com/ecoma-io/archkeep/blob/main/docs/usage/checking.md) · [CI](https://github.com/ecoma-io/archkeep/blob/main/docs/usage/ci.md) · [troubleshooting](https://github.com/ecoma-io/archkeep/blob/main/docs/usage/troubleshooting.md)                                                                                                                       |
+| Agents          | [The `arch-*` protocol](https://github.com/ecoma-io/archkeep/blob/main/docs/skills/overview.md)                                                                                                                                                                                                                                                                                   |
+| Building on it  | [Architecture](https://github.com/ecoma-io/archkeep/blob/main/docs/development/architecture.md) · [contributing](https://github.com/ecoma-io/archkeep/blob/main/CONTRIBUTING.md)                                                                                                                                                                                                  |
+
+## Status and deliberate limits
+
+CI proves both halves run on this repository's own source — the same `check`
+command runs against this tree's tag vocabulary, which shares nothing with the
+workspace the tool was written against.
+
+Three refusals, by design (full list:
+[architecture-authority.md](https://github.com/ecoma-io/archkeep/blob/main/docs/doctrine/architecture-authority.md)):
+
+- **It never infers targets.** Projects and targets stay hand-written in each
+  `project.json`; this tool adds the missing dependency edges only, so what a
+  target does has one source of truth. (The one derivation the Moon provider
+  performs — inferring the workspace layout's `libsDir`/`appsDir` prefixes from
+  project root paths — is about where source lives, never what a target runs.)
+- **It never shells out.** Resolvers read only tracked manifest and source
+  files, so the graph computes on a lint-only CI runner with no Go, Cargo or uv
+  installed.
+- **There is no language off-switch.** Every report of a disabled language
+  would be byte-for-byte identical to that language having no violations, and
+  each analyzer already costs nothing in a workspace without that language.
+
+## License
+
+[Apache License 2.0](https://github.com/ecoma-io/archkeep/blob/main/LICENSE) — © Mai Ngọc Hóa (John Martin) and the
+Archkeep contributors. This README ships inside the tarball; the
+repository-level landing page with the full capability index is
+[`README.md`](https://github.com/ecoma-io/archkeep).