mapterrain 0.1.0

package/LICENSE

@@ -0,0 +1,191 @@
+
+                                 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 the 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 the 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 any 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
+
+   Copyright 2024-2026 PMcL
+
+   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,467 @@
+# Terrain
+
+**Map your test terrain.** Understand your test system in 30 seconds.
+
+```bash
+# Homebrew
+brew install pmclSF/terrain/mapterrain
+
+# npm
+npm install -g mapterrain
+
+cd your-repo
+terrain analyze
+```
+
+That's it. No config, no setup, no test execution required.
+
+> **New here?** Read the [Quickstart Guide](docs/quickstart.md) to understand your first report in 5 minutes.
+
+---
+
+Terrain is a test system intelligence platform. It reads your repository — test code, source structure, coverage data, runtime artifacts, ownership files, and local policy — and builds a structural model of how your tests relate to your code. From that model it surfaces risk, quality gaps, redundancy, fragile dependencies, and migration readiness, all without running a single test.
+
+The core idea: every codebase has a *test terrain* — the shape of its testing infrastructure, the density of coverage across areas, the hidden fault lines where a fixture change cascades into thousands of tests. Terrain makes that shape visible and navigable so you can make informed decisions about what to test, what to fix, and where to invest.
+
+## What "Test Terrain" Means
+
+Most teams know what tests they have. Few teams understand the *terrain* underneath:
+
+- Which source files have no structural test coverage?
+- Which shared fixtures fan out to thousands of tests, making any change to them a blast-radius problem?
+- Which test clusters are near-duplicates burning CI time?
+- Which areas have tests but weak assertions that wouldn't catch a real regression?
+- When you change `auth/session.ts`, which 41 of your 18,000 tests actually matter?
+
+Test terrain is the structural topology of your test system — the dependency graph, the coverage landscape, the duplication clusters, the fanout hotspots, the skip debt. Terrain maps it.
+
+## Problems Terrain Solves
+
+**"We don't know the state of our test system."** Teams inherit test suites they didn't write. Terrain gives a baseline in seconds: framework mix, coverage confidence, duplication, risk posture.
+
+**"CI takes too long and we don't know what to cut."** Terrain identifies redundant tests, high-fanout fixtures, and confidence-based test selection — showing where CI time is wasted and what can be safely reduced.
+
+**"We changed auth code — what tests should we worry about?"** Terrain traces your change through the import graph and structural dependencies, returning the impacted tests ranked by confidence, with reason chains explaining each selection.
+
+**"A tool flagged something but won't explain why."** Every Terrain finding carries an evidence chain. `terrain explain` shows exactly what signals, dependency paths, and scoring rules produced each decision.
+
+**"We're migrating frameworks and need to know what's blocking us."** Migration readiness, blockers by type, and preview-scoped difficulty assessment — all derived from static analysis.
+
+## The Four Canonical Workflows
+
+Terrain is organized around four questions. Everything else is a supporting view.
+
+```
+terrain analyze     "What is the state of our test system?"
+terrain insights    "What should we fix in our test system?"
+terrain impact      "What validations matter for this change?"
+terrain explain     "Why did Terrain make this decision?"
+```
+
+### 1. Analyze — understand the test system
+
+```bash
+terrain analyze
+```
+
+```
+Terrain — Test Suite Analysis
+============================================================
+
+  conftest.py fixture fans out to 3,100 tests — any change retriggers the frame/ suite.
+
+Key Findings
+------------------------------------------------------------
+  1. [HIGH] 23 source files (18%) have low structural coverage
+  2. [HIGH] 8 duplicate test clusters with 0.91+ similarity
+  3. [MEDIUM] 34 xfail markers older than 180 days
+
+Repository Profile
+------------------------------------------------------------
+  Test volume:          very large
+  CI pressure:          high
+  Coverage confidence:  medium
+  Redundancy level:     medium
+  Fanout burden:        high
+
+Validation Inventory
+------------------------------------------------------------
+  Test files:     1,047
+  Test cases:     52,341
+  Frameworks:
+    pytest                1,047 files [unit]
+
+Risk Posture
+------------------------------------------------------------
+  health:              MODERATE
+  coverage_depth:      ELEVATED
+  coverage_diversity:  STRONG
+  structural_risk:     STRONG
+  operational_risk:    STRONG
+
+Next steps:
+  terrain insights            prioritized actions and recommendations
+  terrain impact              what tests matter for this change?
+```
+
+### 2. Insights — find what to improve
+
+```bash
+terrain insights
+```
+
+```
+Terrain — Test System Health Report
+============================================================
+
+Health Grade: C
+
+Reliability Problems (2)
+  [HIGH] 12 flaky tests with >10% failure rate
+  [MEDIUM] 34 skipped tests consuming CI resources
+
+Coverage Debt (2)
+  [HIGH] 23 source files (18%) have low structural coverage
+  [MEDIUM] conftest.py fixture fans out to 3,100 tests
+
+Recommended Actions
+  1. [reliability] Quarantine 12 flaky tests
+     why: Flaky tests block unrelated PRs and erode CI trust.
+  2. [coverage] Add tests for 23 uncovered source files
+     why: Changes in uncovered files cannot trigger test selection.
+  3. [optimization] Consolidate 8 duplicate test clusters
+     why: 0.91+ similarity — redundant CI cost with no coverage benefit.
+```
+
+### 3. Impact — understand what a change affects
+
+```bash
+terrain impact --base main
+```
+
+```
+Terrain Impact Analysis
+============================================================
+
+Summary: 3 file(s) changed, 41 test(s) relevant. Posture: needs_attention.
+
+Impacted tests:          127 of 52,341 total
+Coverage confidence:     High
+
+Recommended Tests (41)
+------------------------------------------------------------
+  tests/groupby/test_groupby.py [exact]
+    Covers: groupby.py:GroupBy.aggregate
+  tests/groupby/test_apply.py [exact]
+    Covers: groupby.py:GroupBy.apply
+  tests/resample/test_base.py [inferred]
+    Reached via shared fixture path
+  ...and 38 more
+
+Protection Gaps
+------------------------------------------------------------
+  [medium] pandas/core/groupby/ops.py — no covering tests found
+
+Next steps:
+  terrain impact --show tests      full test list
+  terrain impact --show gaps       all protection gaps
+```
+
+### 4. Explain — understand why
+
+```bash
+terrain explain tests/io/json/test_pandas.py
+```
+
+```
+Test File: tests/io/json/test_pandas.py
+Framework: pytest
+Tests: 84    Assertions: 312
+
+Signals (3):
+  [high]   networkDependency: 12 tests use @pytest.mark.network — flaky in CI
+  [medium] weakAssertion: 8 bare assert statements without descriptive messages
+  [low]    xfailAccumulation: 3 xfail markers older than 180 days
+
+Next steps:
+  terrain explain selection       explain overall test selection strategy
+  terrain impact --show tests     see all impacted tests
+```
+
+See [Canonical User Journeys](docs/product/canonical-user-journeys.md) for the full workflow specification and [example outputs](docs/examples/) for detailed report samples.
+
+## Product Philosophy
+
+**Inference first.** Terrain reads code. It parses imports, detects frameworks, resolves coverage relationships, and builds dependency graphs from what already exists in the repository. No annotations, no test tagging, no SDK integration required.
+
+**Zero-config by default.** `terrain analyze` works on any repository with test files. Coverage data, runtime artifacts, ownership files, and policy rules are optional inputs that enrich the model — but the core analysis requires nothing beyond the code itself.
+
+**Explainability over magic.** Every finding carries evidence: which signal type, what confidence level, what dependency path, what scoring rule. `terrain explain` exposes the full reasoning chain behind any decision. Teams should never wonder *why* Terrain said something.
+
+**Conservative under uncertainty.** When Terrain encounters ambiguity — a dependency path with low confidence, a file that might or might not be a test — it flags the uncertainty rather than guessing. Impact analysis uses fallback policies with explicit confidence penalties rather than silently expanding scope.
+
+**System health, not individual productivity.** Terrain measures the test system. It never attributes quality to individual developers. Ownership information is used for routing and triage, not scoring.
+
+## Who Uses Terrain
+
+Terrain is framework-agnostic and language-aware. The same analysis model applies across:
+
+- **Frontend teams** — React/Vue component tests, Playwright/Cypress E2E suites, Vitest/Jest unit tests
+- **Backend teams** — Go test suites, pytest collections, JUnit hierarchies, integration test infrastructure
+- **Mobile teams** — cross-platform test suites with standard test frameworks
+- **QA / SDET** — test portfolio management, coverage gap analysis, migration planning across frameworks
+- **SRE / Platform** — CI optimization, test selection for pipelines, policy enforcement
+- **AI / ML evaluation** — evaluation suite structure, benchmark test management, coverage across model behaviors
+
+The structural model is the same. The signals and recommendations adapt to the framework and test patterns detected.
+
+## How CI Optimization Emerges
+
+Terrain does not start with CI optimization. It starts with understanding.
+
+When you run `terrain analyze`, Terrain builds a structural model: which tests exist, which source files they cover, how they depend on shared fixtures, where duplication lives. From that model, CI optimization *emerges*:
+
+- **Test selection** — `terrain impact` traces a diff through the dependency graph and returns only the tests that structurally matter, ranked by confidence. This is not a heuristic skip list — it is a graph traversal with evidence.
+- **Redundancy reduction** — `terrain insights` surfaces duplicate test clusters. Removing or consolidating them directly reduces CI time without reducing coverage.
+- **Fanout control** — High-fanout fixtures that trigger thousands of tests on any change are identified and prioritized for splitting.
+- **Confidence-based runs** — Impact analysis assigns confidence scores. CI pipelines can run high-confidence tests immediately and defer low-confidence tests to nightly runs.
+
+The result is faster CI that comes from *understanding the test system*, not from skipping tests and hoping for the best.
+
+## Installation
+
+### Homebrew (macOS and Linux)
+
+```bash
+brew install pmclSF/terrain/mapterrain
+```
+
+After the first install, you can also tap once and use the short formula name:
+
+```bash
+brew tap pmclSF/terrain
+brew install mapterrain
+```
+
+### npm
+
+```bash
+npm install -g mapterrain
+```
+
+### Go install
+
+```bash
+go install github.com/pmclSF/terrain/cmd/terrain@latest
+```
+
+Requires Go 1.23 or later.
+
+### Pre-built binaries
+
+Download the appropriate binary for your platform from [GitHub Releases](https://github.com/pmclSF/terrain/releases), then:
+
+```bash
+chmod +x terrain
+sudo mv terrain /usr/local/bin/
+```
+
+Binaries are available for macOS, Linux, and Windows (amd64 and arm64).
+
+### Build from source
+
+```bash
+git clone https://github.com/pmclSF/terrain.git
+cd terrain
+go build -o terrain ./cmd/terrain
+```
+
+### Verify installation
+
+```bash
+terrain --version
+```
+
+## Quick Start
+
+```bash
+# Detect coverage/runtime data paths (recommended first step)
+terrain init
+
+# Analyze the current repository
+terrain analyze
+
+# JSON output for any command
+terrain analyze --json
+
+# See what a change affects
+terrain impact --base main
+
+# Get prioritized recommendations
+terrain insights
+```
+
+## Commands
+
+### Primary commands
+
+| Command | Question |
+|---------|----------|
+| `terrain analyze` | What is the state of our test system? |
+| `terrain insights` | What should we fix in our test system? |
+| `terrain impact` | What validations matter for this change? |
+| `terrain explain <target>` | Why did Terrain make this decision? |
+
+### Supporting commands
+
+| Command | Purpose |
+|---------|---------|
+| `terrain init` | Detect data files and print recommended analyze command |
+| `terrain summary` | Executive summary with risk, trends, benchmark readiness |
+| `terrain focus` | Prioritized next actions |
+| `terrain posture` | Detailed posture breakdown with measurement evidence |
+| `terrain portfolio` | Portfolio intelligence: cost, breadth, leverage, redundancy |
+| `terrain metrics` | Aggregate metrics scorecard |
+| `terrain compare` | Compare two snapshots for trend tracking |
+| `terrain select-tests` | Recommend protective test set for a change |
+| `terrain pr` | PR/change-scoped analysis |
+| `terrain show <type> <id>` | Drill into test, unit, owner, or finding |
+| `terrain migration <sub>` | Migration readiness, blockers, or preview |
+| `terrain policy check` | Evaluate local policy rules |
+| `terrain export benchmark` | Privacy-safe JSON export for benchmarking |
+| `terrain serve` | Local HTTP server with HTML report and JSON API |
+
+### AI / eval
+
+| Command | Purpose |
+|---------|---------|
+| `terrain ai list` | List detected scenarios, prompts, datasets, eval files |
+| `terrain ai doctor` | Validate AI/eval setup and surface configuration issues |
+| `terrain ai run` | Execute eval scenarios and collect results |
+| `terrain ai replay` | Replay and verify a previous eval run artifact |
+| `terrain ai record` | Record eval results as a baseline snapshot |
+| `terrain ai baseline` | Manage eval baselines (show, compare) |
+
+### Conversion / migration
+
+| Command | Purpose |
+|---------|---------|
+| `terrain convert <source>` | Go-native test conversion (25 directions) |
+| `terrain convert-config <source>` | Convert framework config files |
+| `terrain migrate <dir>` | Project-wide migration with state tracking |
+| `terrain estimate <dir>` | Estimate migration complexity |
+| `terrain status` | Show migration progress |
+| `terrain checklist` | Generate migration checklist |
+| `terrain doctor [path]` | Run migration diagnostics |
+| `terrain reset` | Clear migration state |
+| `terrain list-conversions` | List supported conversion directions |
+| `terrain shorthands` | List shorthand aliases (e.g., `cy2pw`, `jest2vt`) |
+| `terrain detect <file-or-dir>` | Detect dominant framework |
+
+### Advanced / debug
+
+| Command | Purpose |
+|---------|---------|
+| `terrain debug graph` | Dependency graph statistics |
+| `terrain debug coverage` | Structural coverage analysis |
+| `terrain debug fanout` | High-fanout node analysis |
+| `terrain debug duplicates` | Duplicate test cluster analysis |
+| `terrain debug depgraph` | Full dependency graph analysis (all engines) |
+
+Repository-scoped commands support `--root PATH`, and machine-readable commands support `--json`. Most analysis commands support `--verbose` for additional detail. Run `terrain <command> --help` for full flag documentation.
+
+## Architecture Overview
+
+Terrain is built around a signal-first architecture:
+
+```
+Repository scan  →  Signal detection  →  Risk modeling  →  Reporting
+     │                    │                    │               │
+  test files         framework-specific    explainable     human-readable
+  source files       pattern detectors     risk scoring    + JSON output
+  coverage data      quality signals       with evidence
+  runtime artifacts  health signals        chains
+  ownership files    migration signals
+  policy rules       governance signals
+```
+
+- **Signals** are the core abstraction — every finding is a structured signal with type, severity, confidence, evidence, and location
+- **Snapshots** (`TestSuiteSnapshot`) are the canonical serialized artifact — the complete structural model of a test system at a point in time
+- **Risk surfaces** are derived from signals with explainable scoring across dimensions (quality, reliability, speed, governance)
+- **Dependency graphs** model import relationships, fixture fanout, and structural coverage
+- **Reports** synthesize signals, risk, trends, and benchmark readiness into actionable output
+
+```
+cmd/terrain/     CLI (30+ commands)
+internal/        47 Go packages covering analysis, signals, risk,
+                 impact, depgraph, measurement, reporting, and more
+```
+
+See [DESIGN.md](DESIGN.md) for the full architecture overview and package map, [docs/architecture/](docs/architecture/) for detailed design documents, and [docs/json-schema.md](docs/json-schema.md) for JSON output structure.
+
+## Snapshot Workflow
+
+Terrain supports local snapshot history for trend tracking:
+
+```bash
+# Save a snapshot
+terrain analyze --write-snapshot
+
+# Later, save another snapshot
+terrain analyze --write-snapshot
+
+# Compare the two most recent snapshots
+terrain compare
+
+# Executive summary automatically includes trend highlights
+terrain summary
+```
+
+Snapshots are stored in `.terrain/snapshots/` as timestamped JSON files.
+
+## Policy
+
+Define local policy rules in `.terrain/policy.yaml`:
+
+```yaml
+rules:
+  disallow_skipped_tests: true
+  max_weak_assertions: 10
+  max_mock_heavy_tests: 5
+```
+
+Then check compliance:
+
+```bash
+terrain policy check        # human-readable output
+terrain policy check --json # JSON output for CI
+```
+
+Exit code 0 = pass, 2 = violations found, 1 = error.
+
+## Documentation
+
+- [Quickstart Guide](docs/quickstart.md) — understand your first report in 5 minutes
+- [CLI Specification](docs/cli-spec.md) — full command and flag reference
+- [Example Reports](docs/examples/) — analyze, impact, insights, explain output samples
+- [Canonical User Journeys](docs/product/canonical-user-journeys.md) — primary workflows and expected outcomes
+- [Signal Model](docs/signal-model.md) — the core signal abstraction
+- [Architecture](docs/architecture/) — design documents and technical specifications
+- [Contributing](CONTRIBUTING.md) — how to build, test, and extend Terrain
+
+## Development
+
+```bash
+# Build
+go build -o terrain ./cmd/terrain
+
+# Test
+go test ./cmd/... ./internal/...
+
+# Full release verification
+make release-verify
+```
+
+## License
+
+Apache License 2.0 — see [LICENSE](LICENSE) for details.

package/SECURITY.md

@@ -0,0 +1,29 @@
+# Security Policy
+
+## Supported Versions
+
+Security updates are provided for the latest published major version of Terrain, covering both the Go CLI (`terrain`) and the JavaScript converter package.
+
+## Reporting a Vulnerability
+
+If you believe you found a security issue, report it privately:
+
+- Open a private GitHub security advisory if available for this repository.
+- If private advisories are unavailable, open a regular issue without exploit details and request a secure contact channel.
+
+Please include:
+
+- A clear description of the issue and impact
+- Reproduction steps or proof-of-concept input
+- Affected version(s)
+- Any suggested mitigation
+
+## Response Expectations
+
+- We aim to acknowledge reports within 3 business days.
+- We aim to provide an initial triage within 7 business days.
+- Confirmed vulnerabilities will be patched and released as quickly as possible.
+
+## Disclosure
+
+Please avoid public disclosure until a fix is available and maintainers confirm coordinated disclosure timing.

package/bin/postinstall.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+
+import { ensureTerrainBinary } from './terrain-installer.js';
+
+try {
+  await ensureTerrainBinary({ quiet: false });
+} catch (error) {
+  process.stderr.write(
+    `[mapterrain] Warning: ${error.message}\n` +
+      '[mapterrain] The `terrain` command will try again on first run.\n'
+  );
+}

package/bin/terrain-cli.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+
+import { runTerrainCli } from './terrain-installer.js';
+
+try {
+  await runTerrainCli();
+} catch (error) {
+  process.stderr.write(`${error.message}\n`);
+  process.exit(1);
+}

package/bin/terrain-installer.js

@@ -0,0 +1,310 @@
+#!/usr/bin/env node
+
+import { execFileSync, spawn } from 'child_process';
+import { createWriteStream, existsSync } from 'fs';
+import fs from 'fs/promises';
+import https from 'https';
+import os from 'os';
+import path from 'path';
+import { pipeline } from 'stream/promises';
+import { fileURLToPath } from 'url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const packageRoot = path.resolve(__dirname, '..');
+const packageJson = JSON.parse(
+  await fs.readFile(path.join(packageRoot, 'package.json'), 'utf8')
+);
+
+const GITHUB_OWNER = 'pmclSF';
+const GITHUB_REPO = 'terrain';
+
+function currentTarget() {
+  const goosMap = {
+    darwin: 'darwin',
+    linux: 'linux',
+    win32: 'windows',
+  };
+  const goarchMap = {
+    x64: 'amd64',
+    arm64: 'arm64',
+  };
+
+  const goos = goosMap[process.platform];
+  const goarch = goarchMap[process.arch];
+  if (!goos || !goarch) {
+    throw new Error(
+      `Unsupported platform ${process.platform}/${process.arch}. ` +
+        'Install Terrain manually from GitHub Releases or via Homebrew.'
+    );
+  }
+
+  return {
+    goos,
+    goarch,
+    archiveExt: goos === 'windows' ? 'zip' : 'tar.gz',
+    binaryName: goos === 'windows' ? 'terrain.exe' : 'terrain',
+  };
+}
+
+function isDevelopmentCheckout(rootDir = packageRoot) {
+  return existsSync(path.join(rootDir, 'cmd', 'terrain'));
+}
+
+function installedBinaryPath(rootDir = packageRoot) {
+  const target = currentTarget();
+  return path.join(
+    rootDir,
+    'vendor',
+    'terrain',
+    `${target.goos}-${target.goarch}`,
+    target.binaryName
+  );
+}
+
+function localBuiltBinaryPath(rootDir = packageRoot) {
+  const target = currentTarget();
+  return path.join(rootDir, target.binaryName);
+}
+
+function archiveFileName(version) {
+  const target = currentTarget();
+  return `terrain_${version}_${target.goos}_${target.goarch}.${target.archiveExt}`;
+}
+
+function archiveDownloadUrl(version) {
+  const baseUrl =
+    process.env.TERRAIN_INSTALLER_BASE_URL ||
+    `https://github.com/${GITHUB_OWNER}/${GITHUB_REPO}/releases/download`;
+  return `${baseUrl}/v${version}/${archiveFileName(version)}`;
+}
+
+async function ensureDirectory(dir) {
+  await fs.mkdir(dir, { recursive: true });
+}
+
+async function copyBinary(sourcePath, destinationPath) {
+  await ensureDirectory(path.dirname(destinationPath));
+  await fs.copyFile(sourcePath, destinationPath);
+  if (process.platform !== 'win32') {
+    await fs.chmod(destinationPath, 0o755);
+  }
+}
+
+function log(message, quiet = false) {
+  if (!quiet) {
+    process.stderr.write(`${message}\n`);
+  }
+}
+
+async function downloadFile(url, destinationPath) {
+  await new Promise((resolve, reject) => {
+    const request = https.get(
+      url,
+      {
+        headers: {
+          'User-Agent': `${packageJson.name}/${packageJson.version}`,
+        },
+      },
+      async (response) => {
+        if (
+          response.statusCode &&
+          response.statusCode >= 300 &&
+          response.statusCode < 400 &&
+          response.headers.location
+        ) {
+          response.resume();
+          try {
+            await downloadFile(response.headers.location, destinationPath);
+            resolve();
+          } catch (error) {
+            reject(error);
+          }
+          return;
+        }
+
+        if (response.statusCode !== 200) {
+          response.resume();
+          reject(
+            new Error(
+              `download failed with HTTP ${response.statusCode} for ${url}`
+            )
+          );
+          return;
+        }
+
+        try {
+          await pipeline(response, createWriteStream(destinationPath));
+          resolve();
+        } catch (error) {
+          reject(error);
+        }
+      }
+    );
+
+    request.on('error', reject);
+  });
+}
+
+function extractArchive(archivePath, extractDir) {
+  if (archivePath.endsWith('.tar.gz')) {
+    execFileSync('tar', ['-xzf', archivePath, '-C', extractDir], {
+      stdio: 'pipe',
+    });
+    return;
+  }
+
+  try {
+    execFileSync('tar', ['-xf', archivePath, '-C', extractDir], {
+      stdio: 'pipe',
+    });
+  } catch (error) {
+    if (process.platform !== 'win32') {
+      throw error;
+    }
+    execFileSync(
+      'powershell.exe',
+      [
+        '-NoLogo',
+        '-NoProfile',
+        '-Command',
+        `Expand-Archive -LiteralPath '${archivePath}' -DestinationPath '${extractDir}' -Force`,
+      ],
+      { stdio: 'pipe' }
+    );
+  }
+}
+
+async function findBinary(dir, binaryName) {
+  const entries = await fs.readdir(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isFile() && entry.name === binaryName) {
+      return fullPath;
+    }
+    if (entry.isDirectory()) {
+      const nested = await findBinary(fullPath, binaryName);
+      if (nested) {
+        return nested;
+      }
+    }
+  }
+  return null;
+}
+
+export async function ensureTerrainBinary({
+  rootDir = packageRoot,
+  quiet = false,
+  version = packageJson.version,
+  env = process.env,
+} = {}) {
+  const binaryPath = installedBinaryPath(rootDir);
+  if (existsSync(binaryPath)) {
+    return binaryPath;
+  }
+
+  const localOverride = env.TERRAIN_INSTALLER_LOCAL_BINARY;
+  if (localOverride && existsSync(localOverride)) {
+    log(`Using local Terrain binary override: ${localOverride}`, quiet);
+    await copyBinary(localOverride, binaryPath);
+    return binaryPath;
+  }
+
+  if (isDevelopmentCheckout(rootDir)) {
+    const localBinary = localBuiltBinaryPath(rootDir);
+    if (existsSync(localBinary)) {
+      return localBinary;
+    }
+    return null;
+  }
+
+  if (env.TERRAIN_INSTALLER_SKIP_DOWNLOAD === '1') {
+    throw new Error(
+      'Terrain binary download skipped because TERRAIN_INSTALLER_SKIP_DOWNLOAD=1.'
+    );
+  }
+
+  const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), 'terrain-install-'));
+  const archivePath = path.join(tempDir, archiveFileName(version));
+  const extractDir = path.join(tempDir, 'extract');
+
+  try {
+    log(
+      `Downloading Terrain ${version} for ${process.platform}/${process.arch}...`,
+      quiet
+    );
+    await downloadFile(archiveDownloadUrl(version), archivePath);
+    await ensureDirectory(extractDir);
+    extractArchive(archivePath, extractDir);
+
+    const extractedBinary = await findBinary(
+      extractDir,
+      currentTarget().binaryName
+    );
+    if (!extractedBinary) {
+      throw new Error(
+        `downloaded archive ${path.basename(archivePath)} did not contain ${currentTarget().binaryName}`
+      );
+    }
+
+    await copyBinary(extractedBinary, binaryPath);
+    log(`Installed Terrain binary to ${binaryPath}`, quiet);
+    return binaryPath;
+  } finally {
+    await fs.rm(tempDir, { recursive: true, force: true });
+  }
+}
+
+export async function runTerrainCli(argv = process.argv.slice(2)) {
+  const rootDir = packageRoot;
+
+  if (isDevelopmentCheckout(rootDir)) {
+    const localBinary = localBuiltBinaryPath(rootDir);
+    if (existsSync(localBinary)) {
+      await runBinary(localBinary, argv);
+      return;
+    }
+
+    await runBinary('go', ['run', './cmd/terrain', ...argv], rootDir);
+    return;
+  }
+
+  let binaryPath;
+  try {
+    binaryPath = await ensureTerrainBinary({ rootDir });
+  } catch (error) {
+    throw new Error(
+      `${error.message}\n\n` +
+        'Fallback install options:\n' +
+        '  brew install pmclSF/terrain/mapterrain\n' +
+        '  go install github.com/pmclSF/terrain/cmd/terrain@latest'
+    );
+  }
+
+  if (!binaryPath) {
+    throw new Error(
+      'No Terrain binary is available in this checkout yet. ' +
+        'Build it with `go build -o terrain ./cmd/terrain` or run the Go CLI directly.'
+    );
+  }
+
+  await runBinary(binaryPath, argv);
+}
+
+async function runBinary(command, args, cwd = undefined) {
+  await new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      cwd,
+      stdio: 'inherit',
+    });
+
+    child.on('error', reject);
+    child.on('exit', (code, signal) => {
+      if (signal) {
+        process.kill(process.pid, signal);
+        return;
+      }
+      process.exitCode = code ?? 1;
+      resolve();
+    });
+  });
+}

package/package.json

@@ -0,0 +1,84 @@
+{
+  "name": "mapterrain",
+  "version": "0.1.0",
+  "description": "Terrain test intelligence CLI.",
+  "type": "module",
+  "bin": {
+    "mapterrain": "bin/terrain-cli.js",
+    "terrain": "bin/terrain-cli.js"
+  },
+  "files": [
+    "bin",
+    "README.md",
+    "SECURITY.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pmclSF/terrain.git"
+  },
+  "homepage": "https://github.com/pmclSF/terrain#readme",
+  "bugs": {
+    "url": "https://github.com/pmclSF/terrain/issues"
+  },
+  "scripts": {
+    "postinstall": "node bin/postinstall.js",
+    "test": "node scripts/verify-pack.js",
+    "lint": "eslint \"bin/*.js\" \"scripts/*.js\"",
+    "format": "prettier --write \"bin/*.js\" \"scripts/*.js\"",
+    "format:check": "prettier --check \"bin/*.js\" \"scripts/*.js\"",
+    "start": "node bin/terrain-cli.js",
+    "convert": "node bin/terrain-cli.js convert",
+    "lint-staged": "lint-staged",
+    "release:verify": "npm run format:check && npm run lint && npm test",
+    "prepublishOnly": "npm run format:check && npm run lint && npm test"
+  },
+  "keywords": [
+    "terrain",
+    "test-intelligence",
+    "test-analysis",
+    "risk-analysis",
+    "playwright",
+    "cypress",
+    "selenium",
+    "jest",
+    "vitest",
+    "mocha",
+    "jasmine",
+    "junit",
+    "testng",
+    "pytest",
+    "unittest",
+    "nose2",
+    "webdriverio",
+    "puppeteer",
+    "testcafe",
+    "testing",
+    "automation",
+    "migration",
+    "e2e-testing",
+    "test-migration",
+    "test-converter"
+  ],
+  "author": "pmclSF",
+  "license": "Apache-2.0",
+  "dependencies": {},
+  "devDependencies": {
+    "@commitlint/cli": "^19.6.1",
+    "@commitlint/config-conventional": "^19.6.0",
+    "eslint": "^8.57.1",
+    "eslint-config-prettier": "^10.1.8",
+    "lint-staged": "^16.2.7",
+    "prettier": "^3.0.0"
+  },
+  "lint-staged": {
+    "{bin,scripts}/*.js": [
+      "prettier --write",
+      "eslint --fix --max-warnings=0"
+    ]
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "sideEffects": false
+}